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
parent 42816b4d1e
commit 3a6d572020
7 changed files with 183 additions and 25 deletions
--- a/plugins/zcode-mail-bridge/lib/mcp-rpc.mjs
+++ b/plugins/zcode-mail-bridge/lib/mcp-rpc.mjs
@ -40,7 +40,8 @@ const failure = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, mes
 * 处理一条已解析的 JSON-RPC 消息。
 *
 * @param {any} msg 解析后的消息
- * @param {{tools: Array<{name:string, description:string, inputSchema:object}>,
+ * @param {{tools: Array<{name:string, description:string, inputSchema:object,
+ *          annotations?: object}>,
 *          call: (name: string, args: object) => Promise<string>}} ctx
 * @returns {Promise<object|null>} 要写回的消息；notification（无 id）返回 null
 */
@ -81,7 +82,11 @@ export async function handleMessage(msg, ctx) {
            tools: ctx.tools.map(t => ({
              name: t.name,
              description: t.description,
-              inputSchema: t.inputSchema
+              inputSchema: t.inputSchema,
+              // annotations 必须透传：ZCode 用它算风险等级（readOnlyHint→low /
+              // destructiveHint→high），而 plan 档下「非破坏性的 MCP 工具直接放行」
+              // 依赖它。漏传的后果不是「少个提示」，而是工具在该档下全被拒。
+              ...(t.annotations ? { annotations: t.annotations } : {})
            }))
          });

--- a/plugins/zcode-mail-bridge/lib/tools.mjs
+++ b/plugins/zcode-mail-bridge/lib/tools.mjs
@ -45,7 +45,36 @@ const str = (v, fallback = '') => (typeof v === 'string' ? v : fallback);
 const obj = v => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});

 /**
- * 构造工具集。
+ * MCP 工具的 `annotations`（MCP 规范里的提示字段）。
+ *
+ * # 为什么这个字段在本项目里是**功能开关**而不是装饰
+ *
+ * ZCode 把 MCP 工具的风险参数这样算（逐字逆自 CLI 产物）：
+ *
+ *   annotations.readOnlyHint === true  → riskLevel "low"
+ *   annotations.destructiveHint === true → riskLevel "high"
+ *   两者都没有 → "medium"
+ *   needsApproval = true   ← **硬编码为真，与注解无关**
+ *
+ * 而它的档位判定是：
+ *
+ *   build 档：needsApproval || destructive || sideEffectScope !== "none"  → **ask**
+ *   plan  档：permissionName === "mcp" && !destructive                     → **allow**
+ *
+ * 两条合起来推出一个不那么直观的结论：
+ *
+ *   在 `build` 档下，**每一个 MCP 工具都会要求审批**（needsApproval 恒为真），
+ *   而 headless 模式没有交互式审批客户端 —— 于是全被拒。
+ *   在 `plan` 档下，**只要不声明 destructive，MCP 工具直接放行**。
+ *
+ * 所以 `destructiveHint` 的取值直接决定工具能不能用。声明时必须按真实语义：
+ * 这些工具都不销毁任何东西（读信、发信、传附件、查地址），所以是 false；
+ * 只有真的会破坏用户环境的能力（比如替模型跑 shell 命令）才该是 true。
+ */
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
+const WRITE_SAFE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false };
+
+/** 构造工具集。
 *
 * @param {{client: import('./gateway.mjs').GatewayClient, agentName: string}} deps
 */
@ -69,6 +98,7 @@ export function buildTools({ client, agentName }) {
  // ─── 读 ────────────────────────────────────────────────────────
  tools.push({
    name: 'read_inbox',
+    annotations: READ_ONLY,
    description:
      '查阅收件箱中的邮件。收到新邮件通知后应立即调用此工具。' +
      '每封含 mail_id、发件人、主题、正文与附件清单（带 attachment_id）。',
@ -100,6 +130,7 @@ export function buildTools({ client, agentName }) {

  tools.push({
    name: 'read_mail',
+    annotations: READ_ONLY,
    description: '读取一封邮件的完整正文、附件清单与可投递地址（mail_id 从 read_inbox 获得）。',
    inputSchema: {
      type: 'object',
@ -125,6 +156,7 @@ export function buildTools({ client, agentName }) {

  tools.push({
    name: 'read_thread',
+    annotations: READ_ONLY,
    description: '查看一封邮件所在线索的完整往来（谁回了谁、谁还没回）。多方协作时用它避免重复提问。',
    inputSchema: {
      type: 'object',
@ -148,6 +180,7 @@ export function buildTools({ client, agentName }) {
  // ─── 写 ────────────────────────────────────────────────────────
  tools.push({
    name: 'send_mail',
+    annotations: WRITE_SAFE,
    description:
      '发送邮件。三维地址 name@path.session：省略 session 投递到默认会话，' +
      '.new 强制新建，.具体别名 必须已存在。回复来信请传 reply_to。',
@ -215,6 +248,7 @@ export function buildTools({ client, agentName }) {

  tools.push({
    name: 'forward_mail',
+    annotations: WRITE_SAFE,
    description:
      '转发一封邮件给新的收件人（自动引用原文与附件）。与回复不同：回复落回原会话，转发按目标地址另行定位会话。',
    inputSchema: {
@ -241,6 +275,7 @@ export function buildTools({ client, agentName }) {
  // ─── 附件 ──────────────────────────────────────────────────────
  tools.push({
    name: 'upload_attachment',
+    annotations: WRITE_SAFE,
    description:
      '上传本地文件作为邮件附件，返回 attachment_id。' +
      '拿到 id 后必须在 send_mail 的 attachment_ids 里带上，附件才会随邮件发出。',
@ -263,6 +298,7 @@ export function buildTools({ client, agentName }) {

  tools.push({
    name: 'download_attachment',
+    annotations: WRITE_SAFE,
    description: '下载邮件附件到本地文件。attachment_id 从 read_inbox 的附件清单里取。',
    inputSchema: {
      type: 'object',
@ -286,6 +322,7 @@ export function buildTools({ client, agentName }) {
  // ─── 寻址发现 ──────────────────────────────────────────────────
  tools.push({
    name: 'suggest_address',
+    annotations: READ_ONLY,
    description:
      '查询可用的收件人地址，用于精准发信。不带参数给候选收件人名；带 name 给它可用的' +
      '工作目录；name+path 都带则给该目录下可续谈的会话与现成地址。',
@ -313,6 +350,7 @@ export function buildTools({ client, agentName }) {

  tools.push({
    name: 'list_contacts',
+    annotations: READ_ONLY,
    description: '列出自己参与过的全部会话及各自的可投递地址、未读数、剩余往返预算。',
    inputSchema: {
      type: 'object',
@ -328,6 +366,7 @@ export function buildTools({ client, agentName }) {

  tools.push({
    name: 'session_participants',
+    annotations: READ_ONLY,
    description:
      '列出某条会话的全部参与方（发件人/收件人/抄送方）及各自的可投递地址，并标出谁还没回应。' +
      '要回给抄收方或向第三方转达时先用它拿地址。',
@ -348,6 +387,7 @@ export function buildTools({ client, agentName }) {
  // ─── 连接与登记 ────────────────────────────────────────────────
  tools.push({
    name: 'connect_to_server',
+    annotations: WRITE_SAFE,
    description:
      '连接到 AgentMail Gateway：用当前配置的身份完成登记，并报告连通性。' +
      '首次安装或换了 Gateway 地址时调用。',