World Model MCP

@putervision/world-model-mcp

@putervision/world-model-mcp 是一款无需基础设施、具备确定性的模型上下文协议（MCP）服务，可为 AI Agent 持续维护 3D/2D 空间世界模型。它通过持久实体追踪、带置信度衰减的物体恒存性、具备 AABB 碰撞规避能力的移动模拟、预期视锥投影以及 Playwright 3D 游戏自动化，连接感知（@putervision/vision-memory-mcp）与推理/行动（@putervision/state-memory-mcp）。

🌐 官方文档与网站：putervision.com

---

⚡ 快速开始与安装

前置条件：Node.js >= 18.18.0

# 1. Install globally
npm install -g @putervision/world-model-mcp

# 2. Navigate to your project directory
cd your-project

# 3. Initialize world-model-mcp
# Creates .world-model-mcp/, updates .gitignore, registers project,
# and scaffolds IDE instructions and MCP configs for Cursor, Claude, VS Code, Windsurf, etc.
world-model-mcp init

# Done! Restart your IDE or Agent Manager to activate.

替代方案

# Run directly via binary (after global install)
world-model-mcp run

# Launch interactive 3D WebGL Scene Visualizer
world-model-mcp view

# Display database metrics and permanence confidence stats
world-model-mcp stats

---

🌟 主要亮点

• 🌐 确定性的 3D/2D 空间记忆与紧凑切片：空间索引过程中无需调用大模型；通过确定性的 SQLite WAL 查询、FTS5 搜索、3D 欧几里得邻近半径查找，以及相对于观察者的 1 KB 以下紧凑切片（$K \le 16$ 个最近实体），为系统 1 快速通路提供评估能力。
• ⚡ 15 个生产级整合 MCP 工具：提供完整的 CRUD、拓扑空间图（on、inside、contains、near）、射线-AABB 遮挡视锥剔除、航点导航和时间回溯。
• ⏳ 物体恒存性与衰减：即使实体不在视野内，也会保留在持久记忆中，并支持可配置的指数置信度衰减（$C = C_0 \cdot e^{-\lambda t}$）和状态生命周期（active → hidden → lost）。
• 🚀 碰撞与移动模拟：预测实体位移轨迹、检测 AABB 障碍物碰撞，并在执行操作前计算避障导航航点。
• 🎮 Playwright 游戏自动化：生成定时 WASD / 箭头键按住序列（KeyW for 450ms、ArrowLeft for 290ms）以及 3D↔2D 坐标屏幕投影。
• 🤝 多 Agent 空间黑板：通过 TTL、互斥锁和碰撞意图警报，实现并行子 Agent 间基于主题的协同。
• 🛡️ 空间规范驱动开发（Spatial SDD）：注册物理设计合同基准，进行实时验证（间隙、边界、包含关系），并生成加密 SHA-256 证据包。
• 🎨 交互式 3D WebGL 可视化器：基于浏览器的 Three.js 3D 视口，可渲染活动实体、方向轴、视锥和拓扑链接（world-model-mcp view）。
• 🔒 100% 本地且私密：所有空间实体、关系和历史记录均保存在工作区的 .world-model-mcp/ 中。

---

🛠️ MCP 工具套件

@putervision/world-model-mcp 提供 15 个适用于生产环境的整合型 MCP 工具，分布在 5 个核心工作流领域：

• 空间记忆与搜索：update_entity（实体 CRUD、3D 边界、属性、置信度）、query_entities（FTS5 搜索、邻近半径、状态/标签筛选、历史记录查询）、set_relation（拓扑图链接：on、inside、near、contains）、get_spatial_map（JSON、GeoJSON、glTF 2.0、OBJ、摘要，以及 format: "compact_slice"）。
• 模拟与视觉集成：simulate_movement（位移预测、AABB 碰撞检查、航点路线规划）、ingest_observation（视觉检测数据导入、欧几里得重新识别、视锥校准）、get_expected_view（观察者姿态、水平 FOV 视锥、射线-AABB 遮挡）。
• 目标与状态集成：link_to_goal（将实体/区域关联到 State Memory 任务，提取空间上下文切片）、record_outcome（记录执行结果、位置偏移、属性更改、销毁）。
• 空间 SDD 与证明：manage_spatial_spec（注册物理净空/包含契约，实时验证评分）、create_evidence_pack（将空间证明链接到任务节点的 SHA-256 加密证据包）。
• 多 Agent、回放与自动化：use_spatial_blackboard（主题公告板、互斥锁声明/释放、意图冲突）、manage_snapshot（检查点、快照差异、时间回溯撤销）、wait_for_spatial_state（异步轮询目标空间状态）、generate_game_inputs（Playwright WASD 按住时长、3D↔2D 屏幕射线投影）。

👉 有关完整的参数规范、返回架构和示例载荷，请参阅 API 参考指南 和 数据库架构。

---

🚀 架构与空间记忆生命周期

                     Perception / Vision Detection
                                  │
                                  ▼
                 ┌─────────────────────────────────┐
                 │  Perception Ingestion & Re-ID   │ ──▶ ingest_observation(reconcile: true)
                 └────────────────┬────────────────┘
                                  │
                                  ▼
                 ┌─────────────────────────────────┐
                 │  Durable Entity & Permanence    │ ──▶ update_entity(...)
                 │  (3D Bounding Boxes, Decay)     │ ──▶ set_relation(relation: "on"|"inside")
                 └────────────────┬────────────────┘
                                  │
                                  ▼
                 ┌─────────────────────────────────┐
                 │  Simulation & Waypoint Routing  │ ──▶ simulate_movement(mode: "navigate")
                 │  (AABB Collision Avoidance)     │ ──▶ get_expected_view(fov: 90)
                 └────────────────┬────────────────┘
                                  │
                                  ▼
                 ┌─────────────────────────────────┐
                 │  Playwright & Action Execution  │ ──▶ generate_game_inputs(...)
                 │  (WASD Sequences, Screen Rays)  │ ──▶ record_outcome(action_type: "move")
                 └────────────────┬────────────────┘
                                  │
                                  ▼
                 ┌─────────────────────────────────┐
                 │  Spatial SDD & Cryptographic    │ ──▶ manage_spatial_spec(action: "verify")
                 │  Evidence Bundling to Tasks     │ ──▶ create_evidence_pack(...)
                 └────────────────┬────────────────┘
                                  │
                                  ▼
                 ┌─────────────────────────────────┐
                 │  Persistent SQLite Engine       │ ──▶ .world-model-mcp/world.db (WAL mode)
                 │  Append-Only History Ledger     │ ──▶ SHA-256 Cryptographic Audit Chain
                 └─────────────────────────────────┘

---

📚 文档目录

在 docs/ 目录中浏览专门指南和深入介绍：

指南	说明
🏗️ 架构与代码库提炼	高信号架构概览、模块清单、数据流和设计决策。
💡 功能与三元组概览	PuterVision Autonomous Triad 交互、3D WebGL 场景可视化工具和证据包。
📋 空间世界模型概念	物体恒存性（$C = C_0 \cdot e^{-\lambda t}$）、置信度衰减、视锥投影和空间 SDD。
⚙️ 配置与 IDE 设置	自动初始化详情、环境变量和编辑器配置（Cursor、VS Code、Claude、Windsurf）。
🛠️ CLI 命令参考	CLI 标志（init、run、view、stats、inspect、map、export、import、doctor、snapshot、spec、blackboard）。
🧰 工具与 API 参考	全部 15 个整合型 MCP 工具的完整参考、旧版工具映射和参数示例。
🗄️ 数据库架构	SQLite 表（entities、spatial_relations、entity_history、spatial_specs、blackboard_items、evidence_packs）。
🎮 交互式 3D 游戏竞技场演示	自主 3D 浏览器竞技场，附带 Three.js 桥接诊断（window.__WORLD_MODEL_BRIDGE）。
🧭 示例与教程	深入示例：空间导航、感知校准和多 Agent 公告板。

---

📖 Agent 操作手册：5 步标准工作流

当自主 AI Agent 进入包含 world-model-mcp 的代码库时：

1. Orient & Explore   ──▶ get_spatial_map(format: "summary") + get_expected_view(fov: 90)
2. Query & Locate     ──▶ query_entities(query: "chest", radius: 15) + query_entities(entity_id: "...")
3. Plan & Simulate    ──▶ simulate_movement(mode: "navigate") + manage_spatial_spec(action: "verify")
4. Execute & Ingest   ──▶ generate_game_inputs(...) + ingest_observation(reconcile: true)
5. Record & Evidence  ──▶ record_outcome(...) + create_evidence_pack(task_id: "...")

---

🧪 测试

# Run full unit, integration, and geometry stress test suite across 47 test files (206 tests)
npm test

# Run multi-Node matrix test suite across Node.js 18, 20, and 22
npm run test:matrix

# Run 3D geometry, projection, and Playwright game loop tests
npm run test:3d

---

⚖️ 许可与免责声明

由 PuterVision 开发和维护。根据 MIT License 发布。

• 本地存储保证：所有空间坐标、边界体积和实体历史记录均 100% 保留在您的工作区本地。绝不会传输任何遥测数据或项目数据。
• 商标与非关联声明：产品名称（Cursor、Claude Code、Gemini、Windsurf、VS Code、GitHub、SQLite、Three.js、Playwright）均为其各自所有者的财产，仅用于兼容性识别。