refactor(zcode): 删掉本地 MCP 服务器与整套执行门禁 —— MCP 已内置网关
## 删了什么
**本地 MCP 服务器**（工具面已内置于网关 `POST /api/v1/mcp`，见 457d160）：
mcp/server.mjs stdio JSON-RPC 入口
lib/tools.mjs 11 个工具（手抄网关语义 —— 已抓到两次抄错）
lib/mcp-rpc.mjs 手写协议层
test/{tools,mcp-rpc,generic-mcp}.test.mjs
**执行门禁整条链**（用户裁定：直接移除）：
lib/action-tools.mjs run_command / write_file
lib/approval.mjs 授权判定
lib/grants-file.mjs 「一直同意」跨进程持久化
lib/hook-policy.mjs 档位判定
hooks/permission.mjs PermissionRequest 钩子
hooks/hooks.json 钩子注册
test/{action-tools,approval,grants-file,hook-policy}.test.mjs
test/manual/{gate-e2e.py,permission-e2e.mjs,gate-e2e-evidence.json}
## 为什么执行门禁可以整条删，而不是留着
`run_command` / `write_file` 的门禁是**双进程审批**设计：MCP 进程问人、
ZCode 钩子进程等回答、中间靠落盘授权表对齐。三样都依赖**本地 MCP 进程**。
进程没了之后：
没有任何代码装载 buildActionTools ← 实测确认（只剩测试在测它）
也就是说它已经是死代码，而死代码 + 它的判据会让人误以为「这个平台有执行面」。
留着比删掉更危险。
本平台现在的姿态是**失败关闭**：平台自带 32 项危险工具被禁用，
AgentMail 侧不提供任何执行类工具 ⇒ 模型没有执行面。
## detectModeEnforcement 重写
它原本有三条依据，现在只剩一条还成立：
1. ~~平台 PermissionRequest 钩子~~ —— 目录整个删了。**留着「钩子是否注册」
的判据只会说谎。**
2. ~~我们自己的门禁~~ —— 删了。
3. ✅ `--disallowed-tools` 禁用清单 —— 仍在，且现在是**唯一**那道。
报 `native` 的含义随之收窄为「该档位真的**没有执行面**」，而不是以前那个
「有人会来问」。降级路径（清单被清空 ⇒ advisory）仍有效，实测：
正常配置 → native | 平台自带危险工具已禁用 32 项…⇒ 模型无任何执行面
清单清空 → advisory | 禁用清单自检未通过…禁用清单就是唯一那道
## 清单与 package.json
`.zcode-plugin/plugin.json` 去掉 `mcpServers` 与 `hooks`（两者的目标都已不存在）。
`package.json` 去掉 `main` 与 `verify`（已无本地入口）。
## 误删与自查
删 `test/permission-grants.test.mjs` 时**误删了一个仍在使用的共用库的测试**
—— `lib/permission-grants.js` 四方同源，dsh / opencode / pi 都还在用。
`deploy/check-shared-libs.sh` 立刻报「共用测试缺失」把它抓出来，已恢复。
若没有那道检查，这会是一个静默的覆盖损失。
## 验证
node --test 'test/*.test.mjs' 293/293 绿（原 352，删掉 59 格死代码判据）
deploy/check-shared-libs.sh 四方同源 rc=0
detectModeEnforcement 实测 native / advisory 两条路径都对
## 后续
本目录现在只剩**邮件驱动**（SSE 订阅 → 起一轮 → 回信）与共用库。
若将来要在 zcode 侧恢复执行能力，需要重新设计门禁 —— 现有形状不能复用，
因为它的双进程模型随本地 MCP 进程一起消失了。
This commit is contained in:
@ -1,169 +1,43 @@
|
||||
# zcode-mail-bridge —— AgentMail 的通用 MCP 服务（+ ZCode 适配）
|
||||
# zcode-mail-bridge —— AgentMail 的 ZCode 适配
|
||||
|
||||
**`mcp/server.mjs` 是一个通用 MCP 服务器**：任何支持 MCP 的宿主挂上它就能收发邮件，
|
||||
不需要为 AgentMail 写专用插件。
|
||||
让 [ZCode](https://zcode.z.ai) 作为 AgentMail 里的一个 Agent：**收到来信就起一轮，
|
||||
把结论回信**。
|
||||
|
||||
```bash
|
||||
AGENTMAIL_GATEWAY_URL=http://127.0.0.1:8180 \
|
||||
AGENTMAIL_AGENT_NAME=my-agent \
|
||||
AGENTMAIL_AGENT_SECRET=<secret> \
|
||||
AGENTMAIL_MCP_PLATFORM=my-host \ # 可选，默认 mcp；用于服务端统计平台
|
||||
node mcp/server.mjs
|
||||
```
|
||||
|
||||
宿主配置里写 `{"command":"node","args":["…/mcp/server.mjs"],"env":{…}}` 即可。
|
||||
协议是 stdio 上的换行分隔 JSON-RPC（`lib/mcp-rpc.mjs`，零依赖手写），暴露 11 个邮件
|
||||
工具。工具名、参数名与渲染文本与 pi / dsh / opencode 三桥一致。
|
||||
|
||||
## ZCode 适配（本目录其余部分）
|
||||
|
||||
ZCode 用**插件**扩展能力（`.zcode-plugin/plugin.json` 声明
|
||||
`skills` / `commands` / `hooks` / `mcpServers`），所以适配它的正确形状是一个插件，
|
||||
而不是又一个常驻桥进程。本目录同时还是那个插件（`src/index.mjs` 的邮件驱动、
|
||||
`hooks/` 的授权钩子都只服务 ZCode）。
|
||||
> **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 ZCode 插件清单（MCP 服务器 + hooks 目录）
|
||||
mcp/server.mjs ★ 通用 MCP 服务器（stdio，换行分隔 JSON-RPC）
|
||||
hooks/permission.mjs PermissionRequest 钩子：把授权问给人、等决定、回结论
|
||||
hooks/hooks.json 钩子注册（matcher + 进程型钩子 + 超时）
|
||||
src/index.mjs ★ 邮件驱动（仅 ZCode）：收到来信 → 起一轮 ZCode → 回信
|
||||
.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/mcp-rpc.mjs 协议层（纯函数，可穷举测试）
|
||||
lib/tools.mjs 11 个 AgentMail 工具（与另三个桥同名同参）
|
||||
src/turn-mode.mjs 档位 → `--mode` 映射 + 自带工具禁用清单
|
||||
lib/gateway.mjs 网关 HTTP 客户端
|
||||
lib/hook-policy.mjs 档位判定（纯函数）
|
||||
lib/grants-file.mjs 「一直同意」的跨进程持久化（仅 ZCode 钩子用）
|
||||
lib/explicit-sends.mjs 模型自己发过信的记录（工具与驱动跨进程对齐）
|
||||
lib/action-tools.mjs ⚠ 已不在 MCP 面内（见下方「为什么没有 run_command」）
|
||||
lib/approval.mjs 授权判定共用库（ZCode 钩子路径）
|
||||
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
|
||||
permission-mode,permission-grants,relay-key,sse-client,
|
||||
catchup,relay-dedup,relay-policy,workspace,mail-session-id,
|
||||
is-main}.js
|
||||
← 与 pi/dsh/opencode 三桥**逐字节同源**（见下）
|
||||
|
||||
## 为什么没有 run_command / write_file
|
||||
## 邮件驱动怎么工作
|
||||
|
||||
`lib/action-tools.mjs` 里的两个「会动机器」工具曾挂在 MCP 面上。**2026-10-02 移除**：
|
||||
|
||||
它们的门禁是为 ZCode headless 的**双进程审批**设计的（MCP 服务器进程问人、
|
||||
ZCode 钩子进程等回答、中间靠落盘授权表对齐）。一旦通用化、脱离那个宿主，
|
||||
这套门禁的前提就不成立——挂在通用服务上等于提供一个没有审批的旁路。
|
||||
|
||||
现在 MCP 面只有邮件与附件能力。需要动机器的宿主请用**它自己的**工具
|
||||
（Claude Desktop / codex 等都有各自受管的执行能力），并由它们自己决定是否审批。
|
||||
|
||||
`lib/action-tools.mjs` / `lib/approval.mjs` / `lib/grants-file.mjs` 与 `hooks/`
|
||||
源码仍在仓库里，供 ZCode 的**桌面模式**（人开着 ZCode 干活、平台自己问人）
|
||||
继续使用；只是不再由通用 MCP 面装载。
|
||||
|
||||
`test/generic-mcp.test.mjs` 钉死了这一边界：挂回执行工具、改回硬编码平台、
|
||||
或让文案指回 ZCode 插件设置，都会让判据转红。
|
||||
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）执行门禁 —— 已从 MCP 面移除（2026-10-02）
|
||||
|
||||
~~`lib/action-tools.mjs` + `lib/approval.mjs`~~ **不在通用 MCP 面内**。
|
||||
ZCode headless 下它曾是本平台真正的安全边界（禁用 32 项自带工具，
|
||||
模型只能经 `run_command` / `write_file` 动手，两者逐次请示发件人）。
|
||||
|
||||
通用化后这套门禁**失效**：它依赖 ZCode 特有的双进程审批（MCP 进程问、
|
||||
钩子进程答、落盘表对齐）。挂在通用服务上 = 一个没有审批的旁路。
|
||||
所以移除，理由与取舍见上文「为什么没有 run_command / write_file」。
|
||||
|
||||
源码保留（桌面模式的 ZCode 仍走它），但 `mcp/server.mjs` 不再装载。
|
||||
`src/prompt.mjs` 的能力说明也已改成如实告知「本平台没有执行面」——
|
||||
否则模型会去找不存在的工具，整轮浪费在换名字重试上。
|
||||
历史档位语义（`plan` 直接拒绝 / `workspace` 请示 / `full` 直接执行）
|
||||
见 `src/turn-mode.mjs` 与下文的「三道不可动摇的规矩」。
|
||||
|
||||
<details>
|
||||
<summary>（历史，已不适用于 MCP 面）原执行门禁的三道规矩</summary>
|
||||
|
||||
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 次、
|
||||
最后放弃整个任务的教训。
|
||||
|
||||
</details>
|
||||
|
||||
### 2b）授权桥（`PermissionRequest` 钩子）—— 交互（桌面）模式用
|
||||
|
||||
**注意：headless 驱动这条路上这个钩子不参与**（`--mode yolo` 下平台不做任何权限判定，
|
||||
钩子根本不会触发）。它保留给「人自己开着 ZCode 干活」的场景，那时没有桥进程在跑，
|
||||
钩子就是唯一的授权通道。
|
||||
|
||||
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 干活时并没有桥在跑）。
|
||||
|
||||
### 3）邮件驱动（`src/index.mjs`）
|
||||
SSE 订阅 → 去重 → 解析工作目录与档位 → 跑一轮 → 按策略回信 → 心跳。
|
||||
一轮一次（同一目录并发跑两轮会互相踩，见「已知缺口」）。
|
||||
|
||||
收到来信就自动开工，不需要人先打开 ZCode：
|
||||
|
||||
@ -244,7 +118,7 @@ ZCode 的发现源之一是 `plugins.dirs`（配置里的「inline directories
|
||||
```
|
||||
- agentmail@inline [enabled]
|
||||
inline/inline: <插件目录>
|
||||
skills: 0, commands: 0, hooks: 1, mcp: plugin:agentmail:agentmail
|
||||
（旧输出曾含 hooks/mcp 计数；两者已随执行门禁与本地 MCP 一并移除）
|
||||
```
|
||||
|
||||
## 谁在维护"同源"
|
||||
@ -266,38 +140,12 @@ 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
|
||||
|
||||
# 门禁端到端（真模型、真网关、真邮件）：批了→真执行；拒了→真不执行
|
||||
# ★ 不要写成 `python3 gate-e2e.py | tee log` 再取 `$?` —— 那是 tee 的退出码（恒 0），
|
||||
# 失败会被吃掉。实测踩过：脚本自己打印 5/6（有失败），后台任务却报 exit-code 0。
|
||||
bash -c 'set -o pipefail; python3 test/manual/gate-e2e.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 的凭据。
|
||||
|
||||
`permission-e2e.mjs` 的判据设计：正向（同意→approve）之外还有四条反向对照
|
||||
（拒绝→block 且原因必须来自人的拒绝、plan 档拒绝且**不产生**任何权限邮件、
|
||||
无人可问→fail closed、非守卫工具→不表态）。它必须按「启动前快照差集 +
|
||||
`session_id` + `agent_name`」三重过滤待决请求 —— 待决列表里有历史积压
|
||||
（实测 6 条，含其它 Agent 的），只取「第一条新的」会拿到一条无关请求，
|
||||
于是人点了同意而钩子在等自己那条，最后超时。
|
||||
|
||||
## 已知缺口与残余风险
|
||||
|
||||
|
||||
Reference in New Issue
Block a user