feat(zcode): yolo + 自有工具面 + 我们自己的执行门禁（headless 真正能干活了）
按用户裁定「yolo_own_tools」实现：平台让开（--mode yolo），它自带的一切
「能动机器」的工具被 --disallowed-tools 拿掉，执行类动作改由我们自己的
run_command / write_file 承担，而门禁就在这两个工具里 —— 逐次向发件人请示。
## 为什么必须走这条路（实测，不是推断）
MCP 工具的 needsApproval 在产物里**硬编码为 true**（与 annotations 无关），
而 build/edit 档的判定最后一条是「需要审批 → ask」；headless 没有审批客户端
可问 ⇒ **每个 MCP 工具都被拒**（连 read_inbox 都调不动）。
我们本想让平台把询问转给钩子，但 PermissionRequest 在本版本（3.10.2 / CLI 0.16.5）
**不可靠**：有时压根不注册，触发时也无条件在 ~5ms 内失败、命令从未被 spawn
（用「钩子写 marker 文件」的副作用验证）。
于是选择只剩两个：「平台问、但问不到人 → 全拒」与「平台不问、我们自己问」。
后者才既可用又可审计。代价（平台不再提供第二道防线）写进了 README 的残余风险。
## 新增
- `lib/approval.mjs`：授权往返的唯一实现（钩子与工具共用，否则必然漂移）。
三条不可动摇的规矩：只有明确同意才放行（判据是共用库的前缀白名单，
不是「不等于拒绝」）；永久失败（409/4xx）当场拒绝并把服务端建议带给模型；
暂时失败看有没有本地界面 —— 判据用**调用方传的 sessionId**（单一事实来源，
不再另读环境变量）。自己开 SSE 等决定，先建连再发请求。
- `lib/action-tools.mjs`：`run_command` / `write_file`。输出上限、超时上限、
默认 cwd=工作区；拒绝时**抛错**（MCP 层转 isError）而不是返回「已处理」——
opencode 上「工具失败但报成功」导致模型连试 6 次后放弃整个任务的教训。
平台保护目录（网关数据库/插件代码/服务单元/密钥目录）**无论谁批准都不写**，
且判定在门禁之前（不消耗人的注意力）——防的是自我强化：邮件驱动的 Agent
可能被来信诱导去改自己的插件代码，改完下一轮就换了一套规则。
- `REVIEWED_DENYLIST`（32 项）：逐条按「不拿掉会怎样」分类。名单来自 CLI 产物里
模型可见工具名的**权威注册表**（aIn 那个 28 项数组）+ 另一份更宽的候选集并集，
**不采信模型自述**（基线里它用某个没点名的方式真的创建了文件）。
最容易被漏掉的是 `js` / `mcp__node_repl__js`：它挂在 MCP 上、
产物里自述「can run arbitrary JavaScript with full Node privileges, like Bash」。
- 提示词的能力说明（分档）：告诉模型自带工具被禁、动手要用哪两个工具、
会被请示；并明确「被拒是业务结果，不要重试、不要绕道」。
## 修掉三个真缺陷（都是实测撞出来的）
1. **幂等键按「会话+工具」取 → 同会话第二次调用被静默吞掉**。
网关对重复 relay_key 返回 **HTTP 200** `{status:"duplicate_relay"}` 并提前返回：
不建请求、不发邮件、**永远不会有人来决策**。于是工具干等 → 被 MCP 调用超时
砍掉 → 模型回报「30 秒内未获批准」。从状态码到措辞全看不出问题，归因还完全
错了（像是人没理它）。改为**按调用唯一**（保留会话/工具前缀便于反查），
并把 duplicate_relay 当成可读的拒绝（fail fast，不再干等）。
2. **授权窗口被 MCP 调用超时截断**。ZCode 对 MCP 工具调用有超时（默认量级 30 秒），
而门禁要等人。已在插件清单声明 `mcpServers.agentmail.timeoutMs=600000`
（实测生效：40 秒的命令没被砍，墙钟 50 秒通过），并让门禁**自己**把等待夹到
timeoutMs - 余量之下（`resolveWaitMs`）——被客户端杀掉时连理由都发不出去，
所以必须由我们自己先 settle。
3. **`--allowed-tools` 在 help 里写着但解析器不认**（`Unknown option`）。
留着会拼出一条永远跑不起来的命令行，现在 `buildRunArgs` 直接抛错并指出
替代方案。我在这里误判过一次：先看到「文件没创建」就以为白名单生效，
其实进程只是没退到 usage。判据缺了「进程真的执行了」这一环。
## 自报改成如实
detectModeEnforcement 以前拿「钩子已注册」当 native 的凭据 —— yolo 下钩子
根本不会触发，那等于替一个不存在的能力背书。现在先看**我们那条链**是否就绪
（yolo + 禁用清单里真的有 Bash/js），就绪才报 native，并在理由里点明谁在把关
（实测输出：「执行类动作只能经我们自己的门禁…平台自带危险工具已禁用 32 项」）。
## 验证
- 单测 376/376（新增 47 条）。重点在反向对照：一句「拒绝/deny/空串/平台自己的
shutdown 哨兵都不放行」之外，还验了「别人的决策不能拿来用（relay_key 配对）」、
「超时必须真的拒绝」、「同一会话两次调用必须用不同的幂等键」、
「重复请求要当场拒绝而不是干等」；执行工具的每条拒绝场景都配一个**文件系统断言**
（「抛错了」不等于「副作用没发生」），保护目录还验了 `..`/`./` 绕不过去。
- 真模型端到端（`/root/e2e-zcode-gate/run.py`，13/13）：
批 → 命令真执行（文件内容=标记）；拒 → 命令真没执行（文件不存在）
且回信把成因说成「人拒绝」而**不是**「超时」；同会话第三次调用仍能产生新请求
并在获批后执行。判据本身也修了两处（授权请求邮件里带标记会被误当成回信；
备注在通过项旁边显示会误导）。
- 部署：`deploy/redeploy-plugin.sh zcode` 快照切换 + 握手自检；
驱动单元改为跑快照（生产不跑仓库工作区），env 与清单超时的关系写进注释。
- 顺手清掉一个遗留驱动进程（跑的是仓库路径的旧代码、连着网关 SSE、会抢邮件）。
## 判据纪律（本轮又踩到、已写进代码注释）
「文件没被创建」不能区分「被拦住了」与「进程根本没跑」；
「未获批准」不能区分「人拒绝」与「窗口被截断」；
「工具报错」不能区分「命令失败」与「工具坏了」。
每一处都改成了验到**具体成因**。
This commit is contained in:
@ -33,7 +33,7 @@ test/manual/permission-e2e.mjs 授权桥端到端（真去点同意/拒绝）
|
||||
test/manual/driver-e2e.mjs 邮件驱动端到端（桩 CLI，真网关真邮件）
|
||||
```
|
||||
|
||||
## 三条能力线
|
||||
## 三条能力线（现行姿态：一条主路 + 一条桌面通路）
|
||||
|
||||
### 1）MCP 工具面
|
||||
|
||||
@ -48,7 +48,59 @@ test/manual/driver-e2e.mjs 邮件驱动端到端（桩 CLI，真网关真
|
||||
`test/tools.test.mjs` 里有一条断言直接拿 pi 桥的工具名做对照：少一个就会让某个平台
|
||||
的行为与其它平台不同，而那种问题只在单一平台复现，排查代价最高。
|
||||
|
||||
### 2）授权桥（`PermissionRequest` 钩子）
|
||||
### 2）执行门禁（headless 的主力路径）—— `lib/action-tools.mjs` + `lib/approval.mjs`
|
||||
|
||||
**这是本平台现在真正的安全边界。** 平台自带的 `Bash`/`Write`/`Edit`/`js` 等
|
||||
32 项「能动机器」的工具全部被 `--disallowed-tools` 拿掉（清单见
|
||||
`src/turn-mode.mjs` 的 `REVIEWED_DENYLIST`，逐条的取舍理由写在那里），
|
||||
模型唯一能动手的路径是我们自己的两个工具：
|
||||
|
||||
| 工具 | 作用 | 批准后 |
|
||||
|---|---|---|
|
||||
| `run_command` | 执行一条 shell 命令（`bash -c`，默认 cwd = 会话工作区） | 真执行；退出码 / stdout / stderr 原样交回模型；输出超 16000 字符截断并标明截了多少 |
|
||||
| `write_file` | 写文件（覆盖写，父目录自动建） | 真写；平台保护目录之外才行 |
|
||||
|
||||
两者的语义与档位对齐：
|
||||
|
||||
| 档位 | `--mode` | `run_command` / `write_file` |
|
||||
|---|---|---|
|
||||
| `plan` | `plan` | **直接拒绝**，且**根本不发授权请求**（注定拒绝的事不该打扰人） |
|
||||
| `workspace`（默认） | `yolo` | 每次调用**先向发件人请示**，拿到同意才执行 |
|
||||
| `full` | `yolo` | 直接执行（该档语义就是发件人已给全权） |
|
||||
|
||||
为什么 workspace 敢用 `yolo`：平台那条路在本环境下**不可用**——
|
||||
MCP 工具的 `needsApproval` 在产物里硬编码为 `true`，headless 没有审批客户端
|
||||
可问 ⇒ `build`/`edit` 档下**每个** MCP 工具都被拒（连 `read_inbox` 都调不动）。
|
||||
于是选择只有两个：「平台问、但问不到人 → 全拒」与「平台不问、我们自己问」。
|
||||
后者才是真的可用且仍然可审计。
|
||||
|
||||
**三道不可动摇的规矩**（`lib/approval.mjs` 的文件头有完整推导）：
|
||||
|
||||
1. **只有明确同意才放行** —— 判据是共用库的前缀白名单（`^同意|一直同意|allow|approve|always|yes`，
|
||||
四个桥共用同一份）。看不懂的文本、空串、`拒绝`、`deny`、平台自己的 `shutdown` 哨兵
|
||||
全部当拒绝。判据是「在放行白名单里」，不是「不等于拒绝」。
|
||||
2. **永久失败当场拒绝** —— 409（本线索内没有可决策的人）/ 其它 4xx 不会因重试而改变；
|
||||
服务端的 `error` 与 `suggestion` 原样带回给模型，让它能改道而不是盲试。
|
||||
3. **暂时失败看有没有本地界面** —— 判据是**调用方传的会话 id**（单一事实来源，
|
||||
不再另读 `AGENTMAIL_SESSION_ID`，两个来源不一致时谁也说不清）：
|
||||
邮件驱动（有会话、无界面）必须 fail closed；交互模式退回平台自己的流程。
|
||||
|
||||
**保护目录**（`PROTECTED_PREFIXES`）：`/opt/agentmail/data`（网关数据库）、
|
||||
`/opt/agentmail/plugins`（我们自己的代码）、`/etc/systemd`、`/etc/agentmail`（含密钥）、
|
||||
`/root/.agentmail-zcode`、`/root/.ssh` —— 这些**无论谁批准都不写**，而且判定在门禁
|
||||
**之前**（不消耗人的注意力）。理由不是不信任人，而是防自我强化：邮件驱动的 Agent
|
||||
可能被来信诱导去改网关数据库或自己的插件代码，改完下一轮就换了一套规则，
|
||||
而人看到的是一封看起来合理的申请。这类改动应当是人工部署动作。
|
||||
|
||||
拒绝时**抛错**（MCP 层转成 `isError: true`）而不是返回一句「已处理」：
|
||||
模型必须看见原因才有机会改道。opencode 上「工具失败但报成功」导致模型连试 6 次、
|
||||
最后放弃整个任务的教训。
|
||||
|
||||
### 2b）授权桥（`PermissionRequest` 钩子）—— 交互（桌面）模式用
|
||||
|
||||
**注意：headless 驱动这条路上这个钩子不参与**（`--mode yolo` 下平台不做任何权限判定，
|
||||
钩子根本不会触发）。它保留给「人自己开着 ZCode 干活」的场景，那时没有桥进程在跑，
|
||||
钩子就是唯一的授权通道。
|
||||
|
||||
ZCode 决定某个工具需要授权时触发钩子（事件 JSON 走 stdin），我们回一个结论走 stdout：
|
||||
|
||||
@ -101,9 +153,12 @@ node /opt/ZCode/resources/glm/zcode.cjs \
|
||||
```
|
||||
|
||||
**⚠ `--mode` 漏传的后果**：`--prompt` 的默认 mode 是 **`yolo`**，而 ZCode 的判定里
|
||||
`mode === "yolo"` 一律 allow（`Yolo mode bypasses permission prompts`）——
|
||||
授权钩子根本不会触发，整个授权系统**静默消失**（不报错，只是没有询问）。
|
||||
档位映射表见 `src/turn-mode.mjs`；`buildRunArgs` 收不到 mode 会直接抛错。
|
||||
`mode === "yolo"` 一律 allow（`Yolo mode bypasses permission prompts`）。
|
||||
现在 workspace 档**故意**用 `yolo`（见上文 2 节），所以「mode 是不是 yolo」
|
||||
已经不是安全性质 —— 真正的性质是「我们自己的门禁在不在管」，由
|
||||
`denylistForTier` 与 `ourGateIsActive` 两个函数表达，且都有测试钉住。
|
||||
`buildRunArgs` 收不到 mode 会直接抛错；`--allowed-tools` 会被它直接拒掉
|
||||
（本版本 CLI 的 help 里写着这个选项，但解析器报 `Unknown option`）。
|
||||
|
||||
回信策略（与另三桥同源，复用 `lib/relay-policy.js`）：
|
||||
|
||||
@ -139,6 +194,8 @@ node /opt/ZCode/resources/glm/zcode.cjs \
|
||||
| `AGENTMAIL_SESSION_ID` | **仅邮件驱动时**由驱动进程注入：本会话的 AgentMail 会话 id，兼作「有无本地界面」的判据 |
|
||||
| `AGENTMAIL_PERMISSION_MODE` | 档位（`plan`/`workspace`/`full`），由驱动按邮件的 `permission_mode` 注入 |
|
||||
| `AGENTMAIL_PERMISSION_WAIT_MS` | 等人工决策的上限，默认 540000（9 分钟，须小于钩子的 `timeoutMs`） |
|
||||
| `AGENTMAIL_ZCODE_MODE_MAP` | 覆盖档位→mode 映射（`workspace:yolo,full:yolo`），平台修好钩子后只改配置即可恢复 |
|
||||
| `AGENTMAIL_ZCODE_DISALLOWED_TOOLS` | **整表替换**禁用清单（空格/逗号分隔）。传空串 = 一张空清单，与「没设置」不同 |
|
||||
|
||||
密钥怎么给：ZCode 的插件 `userConfig` **不支持** `sensitive` 值（官方文档明说
|
||||
「sensitive 值当前无法在界面输入或持久化」），所以密钥走 **ZCode 进程的环境变量**
|
||||
@ -186,8 +243,21 @@ node test/manual/permission-e2e.mjs
|
||||
|
||||
# 邮件驱动端到端：桩 CLI 替掉 ZCode，真网关真邮件
|
||||
node test/manual/driver-e2e.mjs
|
||||
|
||||
# 门禁端到端（真模型、真网关、真邮件）：批了→真执行；拒了→真不执行
|
||||
python3 /root/e2e-zcode-gate/run.py
|
||||
```
|
||||
|
||||
新增的两组测试把安全性质钉住（共 34 条）：
|
||||
|
||||
- `test/approval.test.mjs`：全部授权往返。重点在反向对照 ——
|
||||
一句「拒绝/deny/空串/平台自己的 shutdown 哨兵都不放行」之外，
|
||||
还验了「别人的决策不能拿来用（relay_key 配对）」（同一个 Agent 并行发起
|
||||
两个动作时，B 的同意不能放行 A）与「超时必须真的拒绝而不是静默放行」。
|
||||
- `test/action-tools.test.mjs`：每条拒绝场景都配一个**文件系统断言** ——
|
||||
「抛错了」不等于「副作用没发生」，只看抛错发现不了「抛完错照样写文件」。
|
||||
保护目录还验了路径花招（`..`、`./`）绕不过去。
|
||||
|
||||
`driver-e2e.mjs` 用桩 CLI 把「除了模型之外」的每一环都真跑一遍：参数拼装
|
||||
（尤其是 `--mode`）、stream-json 解析、回信策略、跨进程去重、失败必回信。
|
||||
它需要 `gui-lab` 这个人类账号（去点界面/收信）与 zcode 的凭据。
|
||||
@ -199,20 +269,42 @@ node test/manual/driver-e2e.mjs
|
||||
（实测 6 条，含其它 Agent 的），只取「第一条新的」会拿到一条无关请求，
|
||||
于是人点了同意而钩子在等自己那条，最后超时。
|
||||
|
||||
## 已知缺口
|
||||
## 已知缺口与残余风险
|
||||
|
||||
- **真实一轮还没跑过**：ZCode 的模型访问要 OAuth 登录，登录完成前 headless 会直接
|
||||
报「Model config is missing」。桩 CLI 已经把除「模型干活」之外的每一环验过了，
|
||||
但「模型能不能真的用这些工具把活干完」要等登录后实测。
|
||||
- **驱动服务已写好但**未启用**：`deploy/zcode-mail-bridge.service`。
|
||||
未登录就启用的话，每封来信都会收到一封「处理失败」，所以留给人决定。
|
||||
启用：`install -m 0644 deploy/zcode-mail-bridge.service /etc/systemd/system/ && cp deploy/zcode.env.example /etc/agentmail/zcode.env && systemctl enable --now zcode-mail-bridge`。
|
||||
- **`mode_enforcement` 靠自检得出**：驱动启动时会读自己的 `hooks/hooks.json`，
|
||||
确认 `PermissionRequest` 已注册才报 `native`，否则报 `advisory` 并在日志里说明原因
|
||||
（不替一个不存在的能力背书）。
|
||||
- **生产路径**：当前 `plugins.dirs` 指向仓库工作副本，按项目纪律应改为
|
||||
`/opt/agentmail/plugins/zcode-mail-bridge/current` 的快照 + 原子切换
|
||||
（等 ZCode 重启不影响在跑的登录流程时再做）。
|
||||
### 残余风险（新姿态必须说清楚的代价）
|
||||
|
||||
- **`yolo` 意味着平台不再有任何权限判定**。安全完全来自两处：那张
|
||||
`REVIEWED_DENYLIST`（黑名单，漏一项就是开一个洞），以及我们自己的门禁。
|
||||
黑名单的完整性靠**穷举工具名**保证——名单来自 CLI 产物里模型可见工具名的
|
||||
权威注册表（`aIn` 那个 28 项数组）+ 另一份更宽的候选集取并集，测试里有一条
|
||||
「一切能动机器的自带工具都在清单里」把审阅结论钉住。但**不能证明完备**：
|
||||
换版本、装新插件（浏览器类、其它 MCP 服务器）都可能新增执行能力，
|
||||
而黑名单不会自动跟上。升级 ZCode 或安装新插件后应重做一次枚举。
|
||||
- **网络出向未被门禁覆盖**：`WebFetch` / `WebSearch` 保留着（它们读不到本机文件），
|
||||
但能把上下文里的内容编码进 URL 发出去。要收紧就把它们加进
|
||||
`AGENTMAIL_ZCODE_DISALLOWED_TOOLS`。
|
||||
- **文件系统读取范围未被限制**：`Read`/`Grep`/`Glob` 能读本机任何可读文件
|
||||
（包括密钥文件）。要收紧只能收紧整机权限（systemd `ProtectHome` / 专用用户）。
|
||||
- **保护目录是前缀匹配**：它挡住的是「按字面路径写入」，不是绕过符号链接等
|
||||
间接路径；真正的隔离需要 mount namespace 或文件权限。
|
||||
|
||||
### 缺口
|
||||
|
||||
- **旧钩子在本版本（3.10.2 / CLI 0.16.5）不可靠**：有时钩子压根不注册
|
||||
（插件扫描与会话创建有竞态），触发时也无条件在 ~5ms 内失败且命令从未被 spawn
|
||||
（用「钩子写 marker 文件」的副作用验证）。这是转向「我们自己的门禁」的直接原因；
|
||||
桌面模式下钩子仍然可用（已验：5/5）。
|
||||
- **`mode_enforcement` 靠自检得出**：驱动启动时先看我们那条门禁链是否就绪
|
||||
（`--mode yolo` + 禁用清单里真的有 `Bash`/`js`），就绪就报 `native` 并在日志里
|
||||
点明「谁在把关」；否则降级成 `advisory`。**不再拿「钩子已注册」当凭据** ——
|
||||
yolo 下钩子不会触发，那样等于替一个不存在的能力背书。
|
||||
- **闭源**：ZCode 是闭源客户端（deb 里 `License: unknown`），本插件的协议层
|
||||
（MCP 分帧、钩子 schema、headless 输出格式、`--mode` 判定规则）全是从其产物里
|
||||
实测逆出来的，版本升级可能破坏。
|
||||
（MCP 分帧、钩子 schema、headless 输出格式、`--mode`/`--disallowed-tools` 的语义）
|
||||
全是从其产物里实测逆出来的，版本升级可能破坏。
|
||||
- **
|
||||
`--allowed-tools` 在 help 里写着但不可用**：解析器报 `Unknown option`，
|
||||
退回 usage。所以「只放行只读自带工具 + 我们的工具」这种白名单姿态做不到，
|
||||
只能用黑名单。`buildRunArgs` 现在会为此直接抛错，而不是拼出一条跑不起来的命令。
|
||||
- **驱动与 MCP 服务器是两个进程**：模型自己发过信的记录、以及「一直同意」表，
|
||||
都靠落盘对齐（`lib/explicit-sends.mjs` / `lib/grants-file.mjs`）。
|
||||
两边解析出不同路径就会出现「刚点过一直同意又问你一遍」与「同一件事发两封信」。
|
||||
|
||||
Reference in New Issue
Block a user