MailUI4Agents

jianf/MailUI4Agents

Fork 0

Commit Graph

Author	SHA1	Message	Date
JianFeeeee	3a6d572020	feat(zcode): 工具加 MCP 注解 + headless 档位映射改为 plan（否则一个工具都用不了） ## 逆出 ZCode 的 MCP 权限判定，并据此让工具真的可用逐字逆自 CLI 产物： Ari(): annotations.readOnlyHint === true → riskLevel "low" annotations.destructiveHint === true → riskLevel "high" needsApproval = true ← 硬编码为真，与注解无关 checkBuildMode(): needsApproval \|\| destructive \|\| sideEffectScope !== "none" → ask checkPlanMode(): permissionName === "mcp" && !destructive → allow 两条合起来的结论不直观但很关键： - build 档下每一个 MCP 工具都要审批（needsApproval 恒真），而 headless 模式没有交互式审批客户端 ⇒ 全被拒。实测：模型连 read_inbox 都调不动，只能从提示词里猜；更糟的是它绕道用 Bash 去读网关的 sqlite WAL 文件（它自己在回信里如实交代了这件事）。 - plan 档下只要不声明 destructive，MCP 工具直接放行。于是两处改动： 1. `lib/tools.mjs` 给每个工具加真实注解（读类 readOnlyHint，写类 destructiveHint:false——它们确实不破坏任何东西）；`lib/mcp-rpc.mjs` 透传 annotations。漏传不是"少个提示"，而是工具在该档下全被拒。 2. `src/turn-mode.mjs` 的 workspace 档映射从 build 改为 plan。 build 在本环境等于「什么都不能做」，那不是保守而是不可用；plan 才是真的 fail-closed：危险的自带工具被平台直接拒，能用的只有我们声明为非破坏性的工具。日志会明确写出为什么退档。可用 `AGENTMAIL_ZCODE_MODE_MAP` 覆盖（平台修好钩子后只改配置就能恢复 build，不必等发版）。 ## 真模型验证场景 A 的判据同时加强：正文本标记只出现在邮件正文里（驱动的提示词只带主题与 mail_id），所以模型必须真的读信才可能答对。通过 —— 约 20-30 秒一轮。反过来说，早先那版「通过」是假的：标记在主题里，模型从提示词抄一遍就行。 ## 仍然做不到的（见 README 已知缺口）授权桥（PermissionRequest 钩子）在本版本（3.10.2 / CLI 0.16.5）不可用：有时根本不触发，触发时在 ~5ms 内失败且命令从未被 spawn （用「钩子写 marker 文件」的副作用验证，process 与 command 两种类型都一样）。所以 workspace 档「危险操作问人」目前在 headless 下无法实现。单元 329/329。	2026-09-12 16:49:28 +08:00
JianFeeeee	e0e6f86d94	feat(zcode): AgentMail 的 ZCode 插件 —— MCP 工具面 + 官方宿主启动验证 ZCode 用插件扩展能力（.zcode-plugin/plugin.json 声明 skills/commands/hooks/ mcpServers），所以适配它的正确形状是插件而不是又一个独立桥进程。本提交是第一步：把 AgentMail 的工具面做成 MCP 服务器。协议层（lib/mcp-rpc.mjs）手写，不引 @modelcontextprotocol/sdk：协议面只有 initialize / notifications/initialized / tools/list / tools/call，手写可省掉一条构建链与 1MB 打包产物（与 pi/opencode/dsh 三桥零运行时依赖的取向一致），并让这一层成为可穷举的纯函数。分帧照官方插件产物实测确认是换行分隔 JSON（Content-Length 出现 0 次，StdioServerTransport + split("\n")）。工具面（lib/tools.mjs）与另三个桥同名同参，渲染走共用的 addressing/inbox-format/discovery（逐字节同源，已纳入 check-shared-libs.sh）。测试里有一条断言直接拿 pi 桥的工具名做对照：少一个就让某平台行为与其它平台不同，那种问题只在单平台复现，排查代价最高。两处按真实缺陷定的行为： - 工具失败回 result+isError 而非 JSON-RPC error —— 后者会让模型看不到失败原因，只能重试（opencode 连试 6 次发不出附件正是这个后果） - attachment_ids 声明放宽为 anyOf 数组/字符串并在桥侧归一 —— 模型常写成 JSON 字符串，服务端严格解码会拒（同样来自 opencode 那次失败）入口 mcp/server.mjs 修掉一个真实缺陷：stdin 关闭即 process.exit 会杀掉在途请求，表现为「协议全对但访问网关的调用完全没有响应」。现按在途计数 drain，且把 stdout 写入也计入，避免最后一条响应卡在缓冲区。顺带修 check-shared-libs.sh 的一个既有假绿：本机 PATH 上的 diff 是鸿蒙 SDK 工具链的 diff，不认 -q 且对不同的文件仍返回 0 —— 于是该检查器一直是永真输出。改用 cmp -s，并加自检（判据本身必须先被证明能发现差异）。反向验证：让 zcode 或 pi 的共用模块分叉，检查器都正确报错并返回 1。验证： - 单元 33 项 + 继承共用测试 87 项 = 120/120 - `zcode plugins list` → agentmail@inline [enabled]，mcp: plugin:agentmail:agentmail - 经官方 `node zcode.cjs __zcode-plugin-host <server.mjs>` 启动 → 握手与 tools/list 正常 - 真实网关调用：以 zcode 身份 read_inbox / suggest_address / list_contacts 均返回	2026-09-12 13:47:51 +08:00

Author

SHA1

Message

Date

JianFeeeee

3a6d572020

feat(zcode): 工具加 MCP 注解 + headless 档位映射改为 plan（否则一个工具都用不了）

## 逆出 ZCode 的 MCP 权限判定，并据此让工具真的可用

逐字逆自 CLI 产物：

  Ari():  annotations.readOnlyHint === true → riskLevel "low"
          annotations.destructiveHint === true → riskLevel "high"
          needsApproval = true   ← **硬编码为真，与注解无关**
  checkBuildMode(): needsApproval || destructive || sideEffectScope !== "none" → ask
  checkPlanMode():  permissionName === "mcp" && !destructive → allow

两条合起来的结论不直观但很关键：

- **build 档下每一个 MCP 工具都要审批**（needsApproval 恒真），而 headless
  模式没有交互式审批客户端 ⇒ 全被拒。实测：模型连 read_inbox 都调不动，
  只能从提示词里猜；更糟的是它**绕道**用 Bash 去读网关的 sqlite WAL 文件
  （它自己在回信里如实交代了这件事）。
- **plan 档下只要不声明 destructive，MCP 工具直接放行**。

于是两处改动：

1. `lib/tools.mjs` 给每个工具加真实注解（读类 readOnlyHint，写类
   destructiveHint:false——它们确实不破坏任何东西）；`lib/mcp-rpc.mjs` 透传
   annotations。**漏传不是"少个提示"，而是工具在该档下全被拒**。
2. `src/turn-mode.mjs` 的 workspace 档映射从 build 改为 **plan**。
   build 在本环境等于「什么都不能做」，那不是保守而是不可用；plan 才是真的
   fail-closed：危险的自带工具被平台直接拒，能用的只有我们声明为非破坏性的工具。
   日志会明确写出为什么退档。可用 `AGENTMAIL_ZCODE_MODE_MAP` 覆盖
   （平台修好钩子后只改配置就能恢复 build，不必等发版）。

## 真模型验证

场景 A 的判据同时加强：**正文本标记只出现在邮件正文里**（驱动的提示词只带主题
与 mail_id），所以模型必须真的读信才可能答对。通过 —— 约 20-30 秒一轮。

反过来说，早先那版「通过」是假的：标记在主题里，模型从提示词抄一遍就行。

## 仍然做不到的（见 README 已知缺口）

授权桥（PermissionRequest 钩子）在本版本（3.10.2 / CLI 0.16.5）**不可用**：
有时根本不触发，触发时在 ~5ms 内失败且**命令从未被 spawn**
（用「钩子写 marker 文件」的副作用验证，process 与 command 两种类型都一样）。
所以 workspace 档「危险操作问人」目前在 headless 下无法实现。

单元 329/329。

2026-09-12 16:49:28 +08:00

JianFeeeee

e0e6f86d94

feat(zcode): AgentMail 的 ZCode 插件 —— MCP 工具面 + 官方宿主启动验证

ZCode 用插件扩展能力（.zcode-plugin/plugin.json 声明 skills/commands/hooks/
mcpServers），所以适配它的正确形状是**插件**而不是又一个独立桥进程。

本提交是第一步：把 AgentMail 的工具面做成 MCP 服务器。

协议层（lib/mcp-rpc.mjs）手写，不引 @modelcontextprotocol/sdk：
协议面只有 initialize / notifications/initialized / tools/list / tools/call，
手写可省掉一条构建链与 1MB 打包产物（与 pi/opencode/dsh 三桥零运行时依赖的
取向一致），并让这一层成为可穷举的纯函数。分帧照官方插件产物实测确认是
换行分隔 JSON（Content-Length 出现 0 次，StdioServerTransport + split("\n")）。

工具面（lib/tools.mjs）与另三个桥**同名同参**，渲染走共用的
addressing/inbox-format/discovery（逐字节同源，已纳入 check-shared-libs.sh）。
测试里有一条断言直接拿 pi 桥的工具名做对照：少一个就让某平台行为与其它平台不同，
那种问题只在单平台复现，排查代价最高。

两处按真实缺陷定的行为：
- 工具失败回 result+isError 而非 JSON-RPC error —— 后者会让模型看不到失败原因，
  只能重试（opencode 连试 6 次发不出附件正是这个后果）
- attachment_ids 声明放宽为 anyOf 数组/字符串并在桥侧归一 —— 模型常写成
  JSON 字符串，服务端严格解码会拒（同样来自 opencode 那次失败）

入口 mcp/server.mjs 修掉一个真实缺陷：stdin 关闭即 process.exit 会杀掉在途请求，
表现为「协议全对但访问网关的调用完全没有响应」。现按在途计数 drain，
且把 stdout 写入也计入，避免最后一条响应卡在缓冲区。

顺带修 check-shared-libs.sh 的一个既有假绿：本机 PATH 上的 diff 是鸿蒙 SDK
工具链的 diff，不认 -q 且对不同的文件仍返回 0 —— 于是该检查器**一直是永真输出**。
改用 cmp -s，并加自检（判据本身必须先被证明能发现差异）。反向验证：
让 zcode 或 pi 的共用模块分叉，检查器都正确报错并返回 1。

验证：
- 单元 33 项 + 继承共用测试 87 项 = 120/120
- `zcode plugins list` → agentmail@inline [enabled]，mcp: plugin:agentmail:agentmail
- 经官方 `node zcode.cjs __zcode-plugin-host <server.mjs>` 启动 → 握手与 tools/list 正常
- 真实网关调用：以 zcode 身份 read_inbox / suggest_address / list_contacts 均返回

2026-09-12 13:47:51 +08:00

2 Commits