Strategic Agent Reasoning MCP

@putervision/agent-reasoning-mcp

面向自主 AI Agent 的战略性 BDI 推理、多属性期望效用理论与决策智能

@putervision/agent-reasoning-mcp 是一个形式化的 Model Context Protocol（MCP）服务，提供战略性信念－愿望－意图（BDI）推理、分层目标分解、多属性期望效用计算 ((E[U] = \sum w_i u_i))、指数信念衰减、定量风险评估，以及跨多模态记忆桥接的反应式重新规划。

🌐 官方文档：putervision.com • 交互式 Web 文档

---

⚡ 15 秒快速入门

# 1. Initialize reasoning database & seed default utility profiles
npx @putervision/agent-reasoning-mcp init

# 2. Run health diagnostics and Merkle audit checks
npx @putervision/agent-reasoning-mcp doctor

# 3. Inspect active goals, intentions, and belief states
npx @putervision/agent-reasoning-mcp inspect

---

🛠️ 15 个核心 MCP 工具

BDI 战略审议（10 个工具）

工具	操作	用途
set_goal	create、update、decompose、get、list、abandon	管理目标层级、任务 DAG 和成功标准
evaluate_situation	snapshot、quick	根据环境快照为候选操作评分并排序
replan	blocker、event、full	遇到障碍时自适应地重构子目标，并中止过时的意图
assess_risk	action、plan、compare	对候选操作进行定量威胁与风险计算
query_knowledge	search、patterns、similar_situations	搜索已学习的启发式规则、战术知识和过往决策模式
set_utility_weights	configure、get、list、activate	配置效用权重（进取、谨慎、贪婪、效率、探索）
get_decision_trace	latest、get、list、explain	提供可解释的思维链依据和延迟遥测数据
manage_beliefs	update、query、expire、reconcile	结构化信念状态，并采用指数置信度衰减 ($C = C_0 e^{-\lambda t}$)
manage_intentions	create、dispatch、get、list、cancel、resolve	为运行时执行引擎接入契约指令队列
manage_reasoning_db	stats、audit、snapshot、restore	推理数据库统计信息、SHA-256 Merkle 审计和快照回滚

系统 1 快速决策层（5 个工具）

灵感来自 TypeSafe 的 Jev 开创的类型化系统 1 模式（在不生成令牌的情况下，对紧凑状态中的类型化 Choice、Score 和 Noul 基元进行评估），通过内存中的 LRU 缓存和确定性启发式方法在本地实现（<2ms），无需调用外部 API。

工具	用途	延迟目标	L1 缓存（p50）	吞吐量
classify	对多模态 StatePacks 进行低延迟分类标注	<2ms	0.0075 ms	~90,000 ops/s
ask_noul	类型化概率假设与布尔验证（$p \in [0.0, 1.0]$）	<2ms	0.0049 ms	~127,000 ops/s
ask_choice	离散的 $1$ 选 $N$ 选择（$N \le 16$），带概率单纯形	<2ms	0.0138 ms	~64,000 ops/s
ask_score	有界数值标量评分与校准效用评级	<2ms	0.0057 ms	~129,000 ops/s
gate_intention	分发前的影响范围审计门，签发已签名的 HMAC 分发令牌	<1ms	0.0709 ms	~12,000 ops/s

完整的基准测试复现命令、延迟百分位数（p50/p95/p99）以及多层缓存架构详情，请参阅 docs/benchmarks.md。

---

🏛️ PuterVision 五元组多模态生态系统

agent-reasoning-mcp 协调闭环 PuterVision 超级循环：

• 🧠 agent-reasoning-mcp：决定要做什么（BDI 战略推理、效用理论、重新规划）
• ⚡ behavior-mcp：在浏览器运行时中以约 60Hz 执行如何行动
• 📊 state-memory-mcp：持久化工作流记忆、任务、阻碍项和决策
• 👁️ vision-memory-mcp：感知缓存、视觉定位和视频时间线
• 🌐 world-model-mcp：3D/2D 空间布局、实体持久性和碰撞模拟

---

📚 深入文档指南

• 📖 正式 API 参考：所有 15 个工具的完整参数表、类型定义和工具架构。
• 🚀 性能基准测试：全部 5 个系统 1 工具的实测吞吐量和微秒级延迟指标。
• 💡 核心架构与概念：BDI 模型、效用公式和信念衰减动态。
• 🖥️ CLI 使用指南：完整的 CLI 命令参考（init、doctor、inspect、run）。
• 💾 数据库架构：SQLite 表结构、索引和 Merkle 审计账本。
• ⚙️ 配置参考：.agent-reasoning-mcp.json 参数和环境变量。

---

🔗 客户端配置与环境

添加到 .cursor/mcp.json 或 .vscode/mcp.json：

{
  "mcpServers": {
    "agent-reasoning-mcp": {
      "command": "agent-reasoning-mcp",
      "args": ["run"],
      "env": {
        "PENTAD_HMAC_SECRET": "your-secure-shared-secret-here",
        "DISPATCH_TOKEN_TTL_MS": "30000"
      }
    }
  }
}

关键环境变量

• PENTAD_HMAC_SECRET：用于加密签署意图分发令牌的 256 位共享密钥。
• DISPATCH_TOKEN_TTL_MS：分发令牌的有效期（默认：30,000ms）。
• SKIP_MODEL_LOAD：设为 1（或 OFFLINE=1）以强制进行气隙隔离的 L1/L2 确定性评估。

---

🧪 测试与基准测试

# Run full unit and integration test suites
npm test

# Run System 1 fast decision layer benchmark suite (throughput & latency percentiles)
npm run benchmark

# Run air-gapped verification
OFFLINE=1 SKIP_MODEL_LOAD=1 npm test

---

📄 许可证

MIT © PuterVision