packages/soap — SOAP

SOAP = Spatial Omnity Agentic Protocol — 空间智能体时代的 HTTP：开放规范 + 参考实现 + soap-mcp，让任意 AI Agent 用统一方式理解、查询与操作真实 3D 空间。

已实现

soap-view 亮点

• Canvas 2D 像素级清晰渲染：商场楼层布局 + 实体图标 + 虚实颜色编码
• Agent 实时可视化：绿色头像 + 思维气泡（💭 斯坦福小镇风格）
• 平滑移动动画：所有动作（OBSERVE / NAVIGATE / MANIPULATE）在 1s 内沿路径平滑移动，不跳变
• 动作特效：OBSERVE 扫描波纹、NAVIGATE 虚线路径 + 箭头、MANIPULATE 冲击波
• 自主巡游：一键启动 explorer Agent，自动规划 12 步探索商场（观察→逛店→聊天→喝咖啡→战斗）
• HTTP API：/api/scene、/api/roles、/api/events、/api/act（POST）— 外部 Agent 通过 HTTP 即可交互

快速开始

cd packages/soap

# 1. Python 环境
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"      # 校验与测试
pip install -e ".[mcp]"      # MCP Server（需 Python ≥3.10）

# 2. 构建前端
(cd web/viewer && npm ci && npm run build)

# 3. 启动可视化
export SOAP_SCENE_PATH=examples/mall-mixed-reality.json
soap-view
# 浏览器打开 http://127.0.0.1:8765/

# 4. 校验 & 测试
soap-validate examples/mall-mixed-reality.json
pytest tests/ -q

通过 HTTP 控制 Agent

# 观察中庭
curl -X POST http://127.0.0.1:8765/api/act \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"my_bot","verb":"OBSERVE","target_id":"atrium","params":{}}'

# 导航到店铺
curl -X POST http://127.0.0.1:8765/api/act \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"my_bot","verb":"NAVIGATE","target_id":"store_102","params":{"target_uri":"soap://mall_01/store_102"}}'

# 与 NPC 对话
curl -X POST http://127.0.0.1:8765/api/act \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"my_bot","verb":"MANIPULATE","target_id":"store_102_ai_clerk","params":{"action":"speak","message":"推荐一下？"}}'

文档

• SOAP 规范 v0.1
• 五层协议栈愿景
• 活商场思想实验
• 工作计划
• soap-mcp README
• 可视化灵感与合规

后续规划

• soap-scan — 照片 → 3DGS + SOAP 场景
• soap-sem — 3D 语义分割
• soap-edit — 自然语言空间编辑
• soap-render — 跨端 3DGS 渲染

许可

Apache-2.0