JianFeeeee
6a7356ebe7
## 缺陷：入口判断不解析软链 → 生产形态下 main() 从不执行
`mcp/server.mjs` 与 `src/index.mjs` 都这么判断是否被直接执行：
import.meta.url === `file://${process.argv[1]}`
而 ESM 的 `import.meta.url` 是**解析过软链的真实路径**，argv 是命令行里写的那个。
生产布局是软链（`/opt/agentmail/plugins/<name>/current` → 时间戳目录），
于是两者不等、`main()` 从不执行：**没有输出、没有报错、退出码 0**。
它是被部署脚本的后置验证抓到的：第一次从快照起 MCP 服务器时
「握手 0 个工具、stderr 一个字都没有」，而同一个文件从仓库路径跑完全正常
（仓库路径没有软链）。这类缺陷只在部署形态下出现，本地怎么试都对；
表现（静默成功）又与「功能没被调用」一模一样。
修法：新增 `lib/is-main.mjs`，**两侧都 realpath** 后比较（只归一 != 「同一文件」）。
单测含目录软链、文件软链、文件不存在（保守判否，避免被 import 时误跑一遍）。
## 部署脚本：引入 HOST 概念，四个插件一条部署路径
pi/opencode/dsh 的宿主是 systemd 单元，zcode 的宿主是 ZCode 应用本身 ——
没有我们的单元可重启。于是：
- `HOST=systemd`：重启单元 + 看网关库里有没有新心跳（原有判据）
- `HOST=zcode`：**从快照起一次 MCP 服务器并走完握手**，这与 ZCode 加载插件
走的是同一份入口代码；另查 `plugins list` 报告的路径是不是 current
后置验证带**判据自检**：握手函数对坏路径必须返回 0，否则判据本身失效就拒绝通过。
计数用 `grep -o | wc -l` 而不是 `grep -c` —— 每条响应只占一行，tools/list 的
11 个工具名全在同一行，用 -c 会得到 2，把好快照判失败（实测踩过）。
## 生产已切到快照
`/opt/agentmail/plugins/zcode-mail-bridge/current → 20260912-150547`，
`~/.zcode/cli/config.json` 的 `plugins.dirs` 已指向 current，
`zcode plugins list` 报的路径就是快照路径。仓库不再是生产代码。
验证：单测 325/325；快照握手 12 个 name 字段；官方 __zcode-plugin-host 从快照
启动正常；钩子从快照跑通 409 → block；坏路径能被握手判据发现（反向对照）。
zcode-mail-bridge —— AgentMail 的 ZCode 适配
让 ZCode（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 + 进程型钩子 + 超时）
src/index.mjs ★ 邮件驱动：收到来信 → 起一轮 ZCode → 回信
src/zcode-run.mjs 跑一轮（headless CLI + stream-json 解析）
src/prompt.mjs 由邮件构造提示词与回信文案
src/turn-mode.mjs 档位 → `--mode` 映射（授权系统在不在的关键）
lib/mcp-rpc.mjs 协议层（纯函数，可穷举测试）
lib/tools.mjs 11 个 AgentMail 工具（与另三个桥同名同参）
lib/gateway.mjs 网关 HTTP 客户端
lib/hook-policy.mjs 档位判定（纯函数）
lib/grants-file.mjs 「一直同意」的跨进程持久化
lib/explicit-sends.mjs 模型自己发过信的记录（工具与驱动跨进程对齐）
lib/{addressing,inbox-format,bounded,discovery,attachment-ids,
permission-mode,relay-key,permission-grants,sse-client,
catchup,relay-dedup,relay-policy,workspace}.js
← 与 pi/dsh/opencode 三桥**逐字节同源**（见下）
test/ 单元测试（含继承的共用测试）
test/manual/permission-e2e.mjs 授权桥端到端（真去点同意/拒绝）
test/manual/driver-e2e.mjs 邮件驱动端到端（桩 CLI，真网关真邮件）
三条能力线
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：
{"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 干活时并没有桥在跑）。
3）邮件驱动（src/index.mjs）
收到来信就自动开工，不需要人先打开 ZCode：
SSE 收到 new_mail → 去重 → 解析工作目录与档位 → 跑一轮 headless ZCode
→ 取最终文本 → 决定要不要回信 → 投递
一轮长这样（--mode 是必传的，见下）：
node /opt/ZCode/resources/glm/zcode.cjs \
--prompt "<邮件提示词>" --output-format stream-json \
--cwd <工作目录> --mode build [--resume sess_xxx] --max-turns N
⚠ --mode 漏传的后果：--prompt 的默认 mode 是 yolo，而 ZCode 的判定里
mode === "yolo" 一律 allow（Yolo mode bypasses permission prompts）——
授权钩子根本不会触发，整个授权系统静默消失（不报错，只是没有询问）。
档位映射表见 src/turn-mode.mjs；buildRunArgs 收不到 mode 会直接抛错。
回信策略（与另三桥同源，复用 lib/relay-policy.js）：
| 来信方 | 自动回信？ | 为什么 |
|---|---|---|
| 人 | 是（把本轮最终文本回过去） | 消息在提示词里就告诉他「回信不用你自己发」 |
| Agent | 否 | Agent 间必须自己 send_mail；否则两边会把对方的「已收到」当待办，无限客套 |
两种情况下都不回信也不行：
- 一轮跑不起来（CLI 报错 / 超时）→ 必回一封失败信，并写明 ZCode 自己的成因 （没登录 / 缺模型配置 / CLI 路径不对）。邮件驱动的会话没有本地界面， 什么都不发等于「信发出去了，然后再无音讯」。
- 模型这一轮自己发过信（工具跑在 ZCode 派生的 MCP 服务器进程里）→ 让位，
否则收件箱里会出现两封说同一件事的邮件（线上实测过 311 与 342 字节两封）。
跨进程对齐靠
lib/explicit-sends.mjs落盘。
串行：一轮一次。ZCode 的会话与工作目录是重资源，同目录并发跑两轮会互相踩。 代价是一封长信会挡住后面的信 —— 这是显式取舍。
关停：收到 SIGTERM 会终止在途回合（否则 systemd 杀掉驱动后，那个 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 只适合放非机密项。
配置
ZCode 的发现源之一是 plugins.dirs（配置里的「inline directories」）。
// ~/.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 看它报错，再逐字拷到其余三处。
验证
# 单元 + 继承的共用测试
node --test 'test/*.test.mjs'
# 共用模块四方同源（含判据自检）
bash ../../deploy/check-shared-libs.sh
# 授权桥端到端：真建会话 → 起钩子 → 以人类身份点同意/拒绝 → 验钩子结论
node test/manual/permission-e2e.mjs
# 邮件驱动端到端：桩 CLI 替掉 ZCode，真网关真邮件
node test/manual/driver-e2e.mjs
driver-e2e.mjs 用桩 CLI 把「除了模型之外」的每一环都真跑一遍：参数拼装
（尤其是 --mode）、stream-json 解析、回信策略、跨进程去重、失败必回信。
它需要 gui-lab 这个人类账号（去点界面/收信）与 zcode 的凭据。
permission-e2e.mjs 的判据设计：正向（同意→approve）之外还有四条反向对照
（拒绝→block 且原因必须来自人的拒绝、plan 档拒绝且不产生任何权限邮件、
无人可问→fail closed、非守卫工具→不表态）。它必须按「启动前快照差集 +
session_id + agent_name」三重过滤待决请求 —— 待决列表里有历史积压
（实测 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 重启不影响在跑的登录流程时再做）。 - 闭源：ZCode 是闭源客户端（deb 里
License: unknown），本插件的协议层 （MCP 分帧、钩子 schema、headless 输出格式、--mode判定规则）全是从其产物里 实测逆出来的，版本升级可能破坏。