全栈开发 / AI 系统工程
Agent 权限与未知终态恢复工作台
用真实 MCP 协议网关和确定性故障状态机验证 Agent 写操作的可信身份、租户隔离、一次性审批、审计、幂等意图与未知终态恢复。
Reuse contract
复用合同
- 最近核验
- 2026/07/19
- 固定版本
83952b3bae58
输入
- 认证层提供的 principal、tenant、resource 与 scopes，不接受 tool arguments 自报身份
- 包含 expectedVersion、一次性 approvalId 和幂等键的有限写操作
- dispatch 前失败、commit 后响应丢失、权威状态分叉等固定故障场景
输出
- 策略允许或拒绝决定、最小化审计事件和经过 schema 校验的上游结果
- 权威记录版本、上游 mutation 次数与租户隔离断言
- succeeded、blocked、failed 或 unknown 终态及是否需要人工处理
可执行命令
mcp-gateway-test测试npm run lab:mcp:test- 平台
- macOS、Linux 或 Windows；离线 Node.js
- 权威输出
- TAP stdout；从网关返回、上游调用次数、租户记录和审计阶段共同判定
- 副作用
- 不修改状态
- Node.js >=22.12.0
- 仓库根目录已安装锁定依赖
mcp-gateway-demo采集npm run lab:mcp-gateway- 平台
- macOS、Linux 或 Windows；离线 Node.js
- 权威输出
- stdout 中的确定性 MCP 权限网关 JSON 示例
- 副作用
- 不修改状态
- Node.js >=22.12.0
- 仓库根目录已安装锁定依赖
agent-recovery-test测试npm run lab:agent-recovery:test- 平台
- macOS、Linux 或 Windows；离线 Node.js
- 权威输出
- TAP stdout；11 个故障场景及工件 replay/hash 断言
- 副作用
- 不修改状态
- Node.js >=22.12.0
- 仓库根目录
agent-recovery-capture采集npm run lab:agent-recovery:capture- 平台
- macOS 或 Linux；离线 Node.js
- 权威输出
- /tmp/younis-ai-lab-agent-recovery.json
- 副作用
- 会修改运行环境
- Node.js >=22.12.0
- POSIX /tmp 可写
可直接复用
- 为 CRM、工单或知识库 MCP server 增加业务侧身份、租户和参数授权
- 为不可逆或高价值工具调用增加一次性审批与并发版本保护
- 把超时后的盲重试改为幂等查询、权威对账和人工接管状态机
明确边界
- 身份注入、ApprovalStore、审计、记录和恢复状态均为内存实现，不是生产 IAM 或分布式事务。
- 确定性故障注入不证明真实网络能够判断请求是否越过 dispatch 或 commit 边界。
- 没有验证数据库持久化、跨进程并发、durable outbox、速率限制、撤销和长期运行。
固定结果工件
- MCP 网关状态变更示例
mcp-gateway-demo-result- 仓库路径
labs/mcp-policy-gateway/results/2026-07-13-demo.json- SHA-256
e608eb2cd3e341b9e5530671670bb951f5a19065d1c080eea9483b22a1cc0586- 生成/验证命令
mcp-gateway-demo
- 未知终态 11 场景结果
agent-recovery-result- 仓库路径
labs/agent-recovery/results/2026-07-13-results.json- SHA-256
2831d4c8cd6b051c20b06fdbf62cb4bc775c6cd7752ee24b4f35e7cc26c63bc5- 生成/验证命令
agent-recovery-capture
项目问题
MCP 能统一 Agent 连接工具的方式，却不会自动回答“谁能以什么参数改变哪个租户的哪条记录”。同样，工具调用超时也不意味着操作失败：请求可能没有送达，也可能已经提交但响应丢失。若系统把两种情况都直接重试，权限缺口和重复副作用会叠加。
本项目把这两个问题放进同一条写操作生命周期：调用前由权限网关决定是否允许 dispatch，调用后由恢复状态机根据幂等记录和权威状态决定成功、失败、unknown 或人工接管。
两个可独立复用的 lab
labs/mcp-policy-gateway/ 使用官方 MCP SDK 建立测试 Client、Gateway 和模拟记录存储 Server 三个角色。Gateway 对外暴露 records.read 与 records.update，上游只暴露 storage.read 与 storage.update。可信 authInfo 提供 principal、tenant、resource 与 scopes；arguments 中伪造身份或租户会在 schema 边界被拒绝。
写操作审批绑定 principal、tenant、tool、规范化参数和 policy version，并要求 expectedVersion。审批在上游调用前同步消费，不能作为 MCP tool 由 caller 自批；并发复用最多一个请求进入上游。审计只保存参数键和哈希。写前 allow 事件无法落盘时 fail closed；上游成功后终态审计失败则进入内存待投递队列，避免把真实成功误报为拒绝。
labs/agent-recovery/ 不重复实现 MCP，而是抽出副作用恢复状态机。相同幂等键只能对应相同 principal、tenant、tool、desiredStatus 和 expectedVersion。确定未 dispatch 的故障允许一次安全重试；commit 结果不明确时停止自动重放，读取权威记录。若状态已经达到目标则对账为成功，若之后发生分叉则保持 unknown 并要求人工处理。
运行与验收
npm run lab:mcp:test
npm run lab:agent-recovery:test
MCP 测试从 Gateway 返回、上游调用次数、两个租户的记录值与版本共同验收策略，不只检查一段模型可见文本。冻结 TAP 与 demo JSON 记录了网关结果。
恢复实验冻结 11 个场景，结果为 4 succeeded、4 blocked、2 failed 和 1 unknown；意外重复 mutation 为 0，unknown 后的不安全自动重试为 0。该结论只对应固定内存模拟器，但能够作为真实业务状态机的回归合同。
接入方式
接入真实系统时，先将业务身份映射到网关可信上下文，再为每个 tool 定义 resource、scope、tenant、参数 schema 和副作用等级。只读工具可以直接经过策略；写工具还需一次性审批、expectedVersion、稳定幂等键和可查询权威状态。
生产实现必须把审批、幂等记录、业务状态与 outbox 持久化，并明确 dispatch 与 commit 的可观察边界。上游若没有幂等查询或权威结果接口，恢复状态机无法凭超时错误推导真实终态，应直接进入人工队列。
尚未证明
当前两个 lab 都是本地 reproduced 证据。InMemoryTransport 中的认证身份由测试夹具固定，策略、审批、记录和审计没有跨进程持久化。项目没有完成 OAuth token 验证、真实数据库事务、网络分区、长期并发、跨服务撤销或真实用户任务，因此不能把当前结果写成生产可靠性或 exactly-once 保证。
Research links
关联文章
这些文章分别提供问题背景、设计依据、实验验证或运行证据。
- 发布 2026/06/28
本文把 Agent 收敛为固定工作流中的局部决策，并提出窄工具 schema、写操作审批、审计与失败恢复；本项目将这些原则具体化为 MCP 权限网关和未知终态恢复状态机。
- 发布 2026/07/13
本文将行动回路定义为任务身份、资源范围、窄工具 schema、审批、幂等执行、权威结果验证与恢复；本项目把这套控制面设计实现为 MCP 权限网关和未知终态状态机。
- 发布 2026/07/13
本文说明 MCP 只统一连接契约，身份、授权、审批、审计和恢复必须由外部控制面承担，为本项目划定系统边界。
- 发布 2026/07/13
本文逐项重放 MCP 网关的默认拒绝、租户注入、一次性审批、版本冲突和审计故障，并以模拟上游终态验收。
- 发布 2026/07/13
本文用 11 个故障场景验证安全重试、幂等意图绑定、权威对账和 unknown 后不自动重放。