工具三态守卫与审批回路
模块:工具安全(旧线
internal/guard,现internal/runengine/pii.go+ 沙箱)| 状态:三态闸 +run_approvals+ 挂起等人 整条不做(2026-10-22);危险面改由沙箱围栏硬挡;PII 已落地| 证据:doc/06-工具安全层.md、doc/41-任务看板与人工审批.md§3.1/§6 Loop A/§8、tmp/审批回路/决策记录.md
1. 场景与病灶
agent 有了手(bash、文件读写)之后,怎么防止它闯祸?最早的设计是三态闸:allow 放行、deny 把解释文本当结果挡回模型(不抛 error)、ask 暂停整张图等人裁决。旧线(doc/06)把它实现成命令规则引擎 + 文件路径三态 + PII 打码,ask 用 eino 的 StatefulInterrupt + gob checkpoint。
搬进 v6 时先看到的病灶是:run 只有 complete / error / stopped 三种终态,没有「暂停等人」的生命周期;interrupted 是崩溃后的读侧派生视图,语义是「执行者死了」,不是「挂起等人」。于是 doc/41 设计了一套队列式审批:拦截 → run_approvals 落行 → approval 帧 → 阻塞轮询 → 人裁决 → 继续;awaiting_approval 要算会话占用,否则能跳过审批直接投新消息。
但同一天实测改变了前提:bash 的越界由 sandbox-exec 围栏硬挡(越界读/写全部 Operation not permitted),MCP 也进了同款围栏(围栏根 = 租户目录)。没有需要「挂起问人」的场景了——越界是「禁止 + 模型自己改路」,不是「问人」。
2. 候选与代价
| 问题 | 候选 | 好处 | 代价 |
|---|---|---|---|
| 危险面怎么收 | A 提示词劝告 | 零机制 | 外部文本一来就失效(doc/26 那场 `curl |
| B 三态闸 + 审批队列(doc/41 Loop A 原设计) | 人保留最终裁决;等待态持久、多副本安全 | 多一个状态值 → 帧 terminal、前端渲染、runlog 语义、两个会话闸唯一索引全要改;模型要「重新热身」;awaiting_approval 必须算占用,否则审批成孤儿 |
|
| C 沙箱围栏硬挡 + 规则表只做 deny(定案方向) | 越界是确定性的「不能」,不产生噪音;模型拿到明确失败原因后改路 | 只能挡「围栏外」;围栏内仍是宽权限(项目根可读写、出站网络开);规则表挡的是「围栏内也不该做」的命令 | |
| D 逐工具守卫 | 不需要沙箱 | 逐工具的守卫 ≠ 沙箱:bash 能读任意路径,文件守卫只管文件工具;Codex 用系统调用层兜底,工具边界只是软约束 | |
| 审批用哪套持久化 | A eino gob checkpoint + StatefulInterrupt | 旧线已验证 | 进程内字节,多副本下裁决端点在别的副本够不着;v6 的 run 循环是 worker 直驱动,没有可重入执行图 |
| B PG 审批行 + 阻塞轮询 | 共享阵地;人与 worker 不必同进程 | 需要新表、新帧、新端点、会话闸改条件 | |
| PII 要不要一起做 | A 等审批回路 | 一次挂齐 | PII 的落点在「所有工具结果的唯一出口」与「模型输入的唯一转换口」,与审批无关,可独立先做(事实也正是 B/C 两线落地、A 取消) |
| B 独立落三处(定案) | 覆盖面完整 | 挂载点选错会漏(贴真工具内侧漏 MCP;只挂 prepareInput 折叠后 PII 复活) |
裁定:C(危险面靠沙箱 + deny 规则);B 的审批队列整条不做,设计留档备查;PII 独立落地。
3. 同族小裁定
| 小问题 | 裁定 | 代价 / 备注 |
|---|---|---|
| 硬拒返回 error 还是 string? | 返回解释性 string 当 tool_result,不抛 error | 抛 error 模型只看到「tool execution failed」,容易傻重试;带理由的拒绝能让它改道或收手 |
| 三态里的 ask 还需要吗? | 当前无场景;将来出现不可逆动作(如删项目)可从 Loop A 留档直接取 | run_approvals 表、挂起三拍、裁决 CAS、resume 第三分支都还在文档里,代码零落点 |
| 「能问的不拒,该拒的不问」? | 保留为原则 | 全 ask 会把审批弹窗变成噪音,人就会无脑点 y;全 deny 会逼 agent 绕道(自己 bash cat),反而丧失可观测性 |
| 审批挂起时 run 算什么状态? | 原设计:不新增存储状态,running + 存在 pending 审批行(读侧派生「等审批」) | 与 interrupted 的派生哲学一致;若真做,会话闸要改成 status IN ('running','awaiting_approval'),那是单独一拍 |
| 挂起时进程死了怎么办? | 原设计:journal 重放第三分支——无行回注 interruptedResultText;pending 重新挂起;approved 补执行;rejected 补拒绝文本 |
「结果未知」与「人白批了」是两种不同的语义,不能混 |
| 规则从哪来? | 旧线 10 条代表性规则(rm/mv、mkfs/dd、fork 炸弹、`curl | bash、反弹 shell、Unicode 空白、/proc/environ、jq system()`、sudo),规则即代码、可单测 |
| PII 打码挂在哪些点? | ① 工具统一出口 wrapToolErrors(含 MCP);② 模型输入唯一转换口 toSchemaMessages(首轮/折叠/救援全覆盖);③ 记忆抽取入库前 |
贴真工具内侧会漏 MCP;只挂 prepareInput 会在折叠后让 PII 复活 |
| 三处策略一样吗? | 工具输出:打码即焚(原文不进任何持久层);模型输入:mh/runlog 留原文、模型侧见掩码;记忆:密钥类拒收、证件类打码入库 | 用户消息原文要留在 runlog 给页面回放;密钥没有「用户想看原文」的需求 |
4. 证据
- 方案:
doc/06-工具安全层.md§1(三件套)、§3(实现)、§4(三态注解 + 两态实现的教训)、§8(未做系统调用层沙箱);doc/41§3.1(人审回路全设计)、§6 Loop A(七拍全部划掉)、§8 开放问题 1/6/7(两处拍板:bash 不问人、MCP 进围栏、Loop A 不做)。 - 台账:
tmp/审批回路/决策记录.md(2026-10-22 02:52 三拍:YAML 规则 / 队列审批 / 先审批后沙箱;后被同日实测推翻)。 - 代码(现状):
pii.go(piiRules、maskSpan、piiToolWrapper);没有任何run_approvals表或审批端点(grep -rn "run_approvals" internal/runengine/*.go无匹配);旧线internal/guard已不在本仓。 - 复核命令:
grep -rn "run_approvals\|awaiting_approval" yk-tako-eino/internal/runengine。
5. 现状
审批回路未落地,且按 2026-10-22 拍板不做;PII 脱敏已落地(doc/41 B 线)。危险面的实际防线是:bash 与租户 MCP 的沙箱围栏(macOS seatbelt;Linux 待补 bwrap,见 没有沙箱的系统怎么办)+ 旧线规则表的结论(未迁入 v6 代码)。若将来出现真需要人拍板的不可逆动作,doc/41 §3.1 与 §6 是可直接取用的设计。