JianFeeeee
c774904c0c
第二步：让 ZCode 上的 Bash/Write/Edit 授权走 AgentMail 的人工审批，
而不是只靠本地界面。
钩子契约从 CLI 产物里逆出来（不猜协议）：
- 输入走 stdin：{hook_event_name, tool_name, tool_input, session_id, permission_mode…}
- 输出走 stdout，schema **严格**：{"decision":"approve"} / {"decision":"block","reason"}
多一个键就会报 "Hook stdout failed HookJSONOutput schema validation"
- 空输出 / 不以 { 开头 = 不表态；exit 2 = 拒绝；其它非零 = 钩子失败
- 注入的环境变量含 ZCODE_PLUGIN_ROOT / ZCODE_PLUGIN_DATA / ZCODE_SESSION_ID
（MCP 配置里用 ZCODE_SESSION_ID 反而会抛「需要运行时会话上下文」）
档位判定与 pi 桥逐条对齐（plan 直接拒 / workspace 问人 / full 批准），
判定逻辑抽成纯函数 lib/hook-policy.mjs 以便穷举：
其中 full 档必须**返回批准而不是不表态** —— 钩子一旦触发说明 ZCode 本会去问人，
不表态等于让那个询问照常发生，full 档就退化成了 workspace 档。
钩子自己开 SSE 等决定，不依赖桥进程：网关的 SSE 是扇出的
（clients 按唯一 id 存，SendToAgent 推给该 Agent 的所有客户端），
一次性进程也能订阅到自己那条 permission_decision。这样交互模式下同样可用
（人自己开着 ZCode 干活时并没有桥在跑）。先建连再发请求是有意的：
反过来会有一个窗口，人在窗口内点的同意推送给当时还不存在的客户端。
fail closed 但区分模式：永久失败（409/4xx）一律拒绝；暂时失败在
AGENTMAIL_SESSION_ID 非空（邮件驱动、没有本地界面兜底）时拒绝，
交互模式则不表态让人就地决定。
「一直同意」落盘（lib/grants-file.mjs）：钩子是一个事件一个进程，
不落盘那个选项就是骗人的。判定仍交给共用的 permission-grants.js。
共用模块同源范围扩到 9 个（新增 permission-mode / relay-key /
permission-grants / sse-client）—— 档位语义与决策判定分叉会让「同意」
在 ZCode 上悄悄变成另一种意思。
验证：
- 单元 229/229（新增 hook-policy 14 项、grants-file 8 项，含反向对照）
- 共用模块四方同源检查通过
- 授权桥端到端 5/5，全部带反向对照：
同意→approve；拒绝→block 且原因必须来自人的拒绝（不能是超时兜底）；
plan 档拒绝且**不产生**任何权限邮件；无人可问(409)→fail closed；
非守卫工具→不表态
- `zcode plugins list` → agentmail@inline [enabled]，hooks: 1，
mcp: plugin:agentmail:agentmail
我自己写错的两处判据（都已修，值得记下）：
1. 待决权限列表里有历史积压（实测 6 条，含其它 Agent 的条目），
只按「第一条新的」取会拿到无关请求 —— 于是人点了同意而钩子在等自己那条，
最后超时。第一版还把这个超时误报成「拒绝路径通过」。
现在按「启动前快照差集 + session_id + agent_name」三重过滤。
2. 「无人可问」控制组最初传了个非 UUID 的 session id，走的是 400（参数错），
验不到 409 那条真实路径。改为真的造一条只有 Agent 没有人类的会话。
157 lines
8.0 KiB
Markdown
157 lines
8.0 KiB
Markdown
# zcode-mail-bridge —— AgentMail 的 ZCode 适配
|
||
|
||
让 [ZCode](https://zcode.z.ai)（z.ai 的 Electron 客户端）成为 AgentMail 里
|
||
一个能收发邮件、传附件、**把危险工具授权交给人**的 Agent。
|
||
|
||
ZCode 用**插件**扩展能力（`.zcode-plugin/plugin.json` 声明
|
||
`skills` / `commands` / `hooks` / `mcpServers`），所以适配它的正确形状是一个插件，
|
||
而不是又一个常驻桥进程。本目录就是那个插件。
|
||
|
||
## 组成
|
||
|
||
```
|
||
.zcode-plugin/plugin.json 插件清单（MCP 服务器 + hooks 目录）
|
||
mcp/server.mjs MCP 服务器入口（stdio，换行分隔 JSON-RPC）
|
||
hooks/permission.mjs PermissionRequest 钩子：把授权问给人、等决定、回结论
|
||
hooks/hooks.json 钩子注册（matcher + 进程型钩子 + 超时）
|
||
lib/mcp-rpc.mjs 协议层（纯函数，可穷举测试）
|
||
lib/tools.mjs 11 个 AgentMail 工具（与另三个桥同名同参）
|
||
lib/gateway.mjs 网关 HTTP 客户端
|
||
lib/hook-policy.mjs 档位判定（纯函数）
|
||
lib/grants-file.mjs 「一直同意」的跨进程持久化
|
||
lib/{addressing,inbox-format,bounded,discovery,attachment-ids,
|
||
permission-mode,relay-key,permission-grants,sse-client}.js
|
||
← 与 pi/dsh/opencode 三桥**逐字节同源**（见下）
|
||
test/ 单元测试（含继承的共用测试）
|
||
test/manual/permission-e2e.mjs 授权桥的端到端验证（真去点同意/拒绝）
|
||
```
|
||
|
||
## 两条能力线
|
||
|
||
### 1）MCP 工具面
|
||
|
||
模型通过 `mcp__agentmail__<工具名>` 调用：
|
||
|
||
`read_inbox` `read_mail` `read_thread` `send_mail` `forward_mail`
|
||
`upload_attachment` `download_attachment` `suggest_address` `list_contacts`
|
||
`session_participants` `connect_to_server`
|
||
|
||
工具名、参数名与渲染文本都与 pi / dsh / opencode 三桥一致，渲染直接复用共用的
|
||
`inbox-format` / `discovery` —— 同一封邮件在任何平台上看起来都该是同一个样子。
|
||
`test/tools.test.mjs` 里有一条断言直接拿 pi 桥的工具名做对照：少一个就会让某个平台
|
||
的行为与其它平台不同，而那种问题只在单一平台复现，排查代价最高。
|
||
|
||
### 2）授权桥（`PermissionRequest` 钩子）
|
||
|
||
ZCode 决定某个工具需要授权时触发钩子（事件 JSON 走 stdin），我们回一个结论走 stdout：
|
||
|
||
```jsonc
|
||
{"decision":"approve"} // 放行
|
||
{"decision":"block","reason":"…"} // 拒绝，且模型能看到原因
|
||
// 什么都不输出 // 不表态，退回 ZCode 自己的权限流程
|
||
```
|
||
|
||
档位语义与 pi 桥逐条对齐（同一条邮件派给不同 Agent，行为必须一致）：
|
||
|
||
| 档位 | 守卫工具（`Bash`/`Write`/`Edit`/`ApplyPatch`） | 其它工具 |
|
||
|---|---|---|
|
||
| `plan` | 直接拒绝，文案与 pi 桥同源 | 不表态（读与查本来就允许） |
|
||
| `workspace`（默认） | 发邮件问人，等决定 | 不表态 |
|
||
| `full` | 批准（该档语义就是免掉询问） | 不表态 |
|
||
|
||
**只有明确同意才放行**：看不懂的决策文本一律当拒绝（判定交给共用的
|
||
`permission-grants.js`）。「一直同意」落盘存到
|
||
`$AGENTMAIL_ZCODE_GRANTS_FILE`（或 `$AGENTMAIL_CONFIG_DIR` / `$ZCODE_PLUGIN_DATA` 下的
|
||
`permission-grants.json`）—— 钩子是**一个事件一个进程**，不落盘的话那个选项就是骗人的。
|
||
|
||
**失败一律 fail closed，但区分模式**：
|
||
|
||
- 永久失败（409 无人可问 / 其它 4xx）→ 拒绝并说明原因
|
||
- 暂时失败（5xx / 网络）＋ `AGENTMAIL_SESSION_ID` 非空（邮件驱动）→ 拒绝
|
||
（邮件驱动的会话没有本地界面兜底，退回本地决策等于守卫消失）
|
||
- 暂时失败 ＋ 交互模式 → 不表态，让人就地决定
|
||
|
||
钩子**自己开 SSE** 等决定，不找桥进程要 —— 网关的 SSE 是扇出的
|
||
（`clients` 按唯一 id 存，`SendToAgent` 推给该 Agent 的所有客户端），
|
||
所以一次性进程也能订阅到自己那条 `permission_decision`。
|
||
这样**交互模式下这个功能同样可用**（人自己开着 ZCode 干活时并没有桥在跑）。
|
||
|
||
## 配置
|
||
|
||
插件读与其它三桥**同名**的环境变量：
|
||
|
||
| 变量 | 说明 |
|
||
|---|---|
|
||
| `AGENTMAIL_GATEWAY_URL` | 网关地址，默认 `http://127.0.0.1:8180` |
|
||
| `AGENTMAIL_AGENT_NAME` | 本 Agent 在 AgentMail 里的名字（如 `zcode`） |
|
||
| `AGENTMAIL_AGENT_KEY` | 管理员签发的 Agent 密钥 |
|
||
| `AGENTMAIL_AGENT_SECRET` | 没有密钥时的兜底（`X-Agent-Secret`，服务端两条路都认） |
|
||
| `AGENTMAIL_SESSION_ID` | **仅邮件驱动时**由驱动进程注入：本会话的 AgentMail 会话 id，兼作「有无本地界面」的判据 |
|
||
| `AGENTMAIL_PERMISSION_MODE` | 档位（`plan`/`workspace`/`full`），由驱动按邮件的 `permission_mode` 注入 |
|
||
| `AGENTMAIL_PERMISSION_WAIT_MS` | 等人工决策的上限，默认 540000（9 分钟，须小于钩子的 `timeoutMs`） |
|
||
|
||
密钥怎么给：ZCode 的插件 `userConfig` **不支持** `sensitive` 值（官方文档明说
|
||
「sensitive 值当前无法在界面输入或持久化」），所以密钥走 **ZCode 进程的环境变量**
|
||
（systemd `EnvironmentFile`），由 MCP 服务器与钩子继承。
|
||
`userConfig` 只适合放非机密项。
|
||
|
||
### 安装（本地目录，无需 marketplace）
|
||
|
||
ZCode 的发现源之一是 `plugins.dirs`（配置里的「inline directories」）。
|
||
|
||
```jsonc
|
||
// ~/.zcode/cli/config.json
|
||
{ "plugins": { "enabled": true, "dirs": ["/opt/agentmail/plugins/zcode-mail-bridge/current"] } }
|
||
```
|
||
|
||
装完用 `node <zcode.cjs> plugins list` 自查，应当看到：
|
||
|
||
```
|
||
- agentmail@inline [enabled]
|
||
inline/inline: <插件目录>
|
||
skills: 0, commands: 0, hooks: 1, mcp: plugin:agentmail:agentmail
|
||
```
|
||
|
||
## 谁在维护"同源"
|
||
|
||
`deploy/check-shared-libs.sh` 会逐个字节比对上面那 9 个共用模块（及其测试）
|
||
与 opencode 基准。**该脚本曾有假绿**：本机 PATH 上的 `diff` 是鸿蒙 SDK 工具链里的
|
||
`diff`，不认 `-q` 且对内容不同的文件**仍返回 0**，于是检查器一直是永真输出。
|
||
现已改用 `cmp -s` 并在开头自检（判据本身必须先被证明能发现差异）。
|
||
|
||
改了共用模块的正规流程：改 `opencode-mail-bridge/lib/` 下的基准，
|
||
跑 `deploy/check-shared-libs.sh` 看它报错，再逐字拷到其余三处。
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
# 单元 + 继承的共用测试
|
||
node --test 'test/*.test.mjs'
|
||
|
||
# 共用模块四方同源（含判据自检）
|
||
bash ../../deploy/check-shared-libs.sh
|
||
|
||
# 授权桥端到端：真建会话 → 起钩子 → 以人类身份点同意/拒绝 → 验钩子结论
|
||
node test/manual/permission-e2e.mjs
|
||
```
|
||
|
||
`permission-e2e.mjs` 的判据设计：正向（同意→approve）之外还有四条反向对照
|
||
（拒绝→block 且原因必须来自人的拒绝、plan 档拒绝且**不产生**任何权限邮件、
|
||
无人可问→fail closed、非守卫工具→不表态）。它必须按「启动前快照差集 +
|
||
`session_id` + `agent_name`」三重过滤待决请求 —— 待决列表里有历史积压
|
||
（实测 6 条，含其它 Agent 的），只取「第一条新的」会拿到一条无关请求，
|
||
于是人点了同意而钩子在等自己那条，最后超时。
|
||
|
||
## 已知缺口
|
||
|
||
- **邮件驱动还没做**：目前是「模型侧工具面 + 授权桥」。让 ZCode 收到来信就自动开工，
|
||
需要一个驱动进程（订阅 SSE → 起 ZCode 会话 → 把最终回复当回信发出），
|
||
并把 `AGENTMAIL_SESSION_ID` / `AGENTMAIL_PERMISSION_MODE` 注入会话。
|
||
- **`mode_enforcement` 仍是 `advisory`**：授权桥已经能真的拦截（钩子返回 block 会拒绝工具），
|
||
但库里的档位声明还没提为 `native`。
|
||
- **生产路径**：当前 `plugins.dirs` 指向仓库工作副本，按项目纪律应改为
|
||
`/opt/agentmail/plugins/zcode-mail-bridge/current` 的快照 + 原子切换
|
||
（等 ZCode 重启不影响在跑的登录流程时再做）。
|
||
- **闭源**：ZCode 是闭源客户端（deb 里 `License: unknown`），本插件的协议层
|
||
（MCP 分帧、钩子 schema）是从其产物里实测逆出来的，版本升级可能破坏。
|