MailUI4Agents/plugins/zcode-mail-bridge

zcode-mail-bridge —— AgentMail 的 ZCode 适配

让 ZCode 作为 AgentMail 里的一个 Agent：收到来信就起一轮， 把结论回信。

2026-10-02：MCP 工具面已内置于网关。 原先本目录自带一个 MCP 服务器（mcp/server.mjs，stdio）+ 一套执行门禁 （run_command / write_file + PermissionRequest 钩子）。两者都已删除：

• MCP 工具面现在由网关提供：POST /api/v1/mcp（Streamable HTTP，11 个工具）。 工具直接包装网关自己的 handler，所以工作区收窄、会话收窄、配额、冷静期 全部是同一份代码。接入端只需填一个 URL —— 不装插件、不起进程、不配环境变量。
• 执行门禁随之删除。那套双进程审批（MCP 进程问人、ZCode 钩子进程等回答、 落盘授权表对齐）依赖本地 MCP 进程；进程没了，它就成了无人装载的死代码。 本平台现在没有执行面：平台自带的 32 项危险工具被禁用，AgentMail 侧 不提供任何执行类工具 —— 这是失败关闭。 detectModeEnforcement() 自报的 native 含义也随之收窄为「模型无执行面」。

详见网关侧 server/internal/mcp/。

组成

.zcode-plugin/plugin.json   插件清单（仅元数据；不再声明 mcpServers / hooks）
src/index.mjs               ★ 邮件驱动：SSE 订阅 → 去重 → 起一轮 → 按策略回信
src/zcode-run.mjs           跑一轮（headless CLI + stream-json 解析）
src/prompt.mjs              由邮件构造提示词与回信文案
src/turn-mode.mjs           档位 → `--mode` 映射 + 自带工具禁用清单
lib/gateway.mjs             网关 HTTP 客户端
lib/explicit-sends.mjs      模型自己发过信的记录（与工具跨进程对齐）
lib/{addressing,inbox-format,bounded,discovery,attachment-ids,
     permission-mode,permission-grants,relay-key,sse-client,
     catchup,relay-dedup,relay-policy,workspace,mail-session-id,
     is-main}.js
                            ← 与 pi/dsh/opencode 三桥**逐字节同源**（见下）

## 邮件驱动怎么工作

SSE 订阅 → 去重 → 解析工作目录与档位 → 跑一轮 → 按策略回信 → 心跳。
一轮一次（同一目录并发跑两轮会互相踩，见「已知缺口」）。

收到来信就自动开工，不需要人先打开 ZCode：

SSE 收到 new_mail → 去重 → 解析工作目录与档位 → 跑一轮 headless ZCode → 取最终文本 → 决定要不要回信 → 投递

一轮长这样（`--mode` 是**必传**的，见下）：

```bash
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）。 现在 workspace 档故意用 yolo（见上文 2 节），所以「mode 是不是 yolo」 已经不是安全性质 —— 真正的性质是「我们自己的门禁在不在管」，由 denylistForTier 与 ourGateIsActive 两个函数表达，且都有测试钉住。 buildRunArgs 收不到 mode 会直接抛错；--allowed-tools 会被它直接拒掉 （本版本 CLI 的 help 里写着这个选项，但解析器报 Unknown option）。

回信策略（与另三桥同源，复用 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）
AGENTMAIL_ZCODE_MODE_MAP	覆盖档位→mode 映射（workspace:yolo,full:yolo），平台修好钩子后只改配置即可恢复
AGENTMAIL_ZCODE_DISALLOWED_TOOLS	整表替换禁用清单（空格/逗号分隔）。传空串 = 一张空清单，与「没设置」不同

密钥怎么给：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: <插件目录>
  （旧输出曾含 hooks/mcp 计数；两者已随执行门禁与本地 MCP 一并移除）

谁在维护"同源"

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


# 邮件驱动端到端：桩 CLI 替掉 ZCode，真网关真邮件
node test/manual/driver-e2e.mjs

已知缺口与残余风险

残余风险（新姿态必须说清楚的代价）

• 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/--disallowed-tools 的语义） 全是从其产物里实测逆出来的，版本升级可能破坏。
• ** --allowed-tools 在 help 里写着但不可用**：解析器报 Unknown option， 退回 usage。所以「只放行只读自带工具 + 我们的工具」这种白名单姿态做不到， 只能用黑名单。buildRunArgs 现在会为此直接抛错，而不是拼出一条跑不起来的命令。
• 驱动与 MCP 服务器是两个进程：模型自己发过信的记录、以及「一直同意」表， 都靠落盘对齐（lib/explicit-sends.mjs / lib/grants-file.mjs）。 两边解析出不同路径就会出现「刚点过一直同意又问你一遍」与「同一件事发两封信」。