fix(zcode): 真模型跑通后发现的三处缺陷（register / 工具活动日志 / SSE 关停）

真模型端到端（场景 A 通过：6893 事件、175 秒、530 字回信）把三处只有真跑才
暴露的问题照了出来：

1. **register 调不通**：驱动按 pi 的客户端 API 写了 `client.register()`，
   而本插件的 GatewayClient 没有这个方法 —— 靠此前手工注册过才没暴露。
   补上后才发现第二个坑：`/agent/register` 的认证与其它接口**不同**，
   它只认 `Authorization: Bearer` 或 **body 里的 `secret`**，不认 `X-Agent-Secret`
   头（其它接口认）。实测报错：
     HTTP 400 需要 Authorization: Bearer <密钥> 或 body 里的 secret
   所以没密钥时把 secret 放进 body。

2. **一轮 6893 条事件，日志里什么也看不见**：邮件驱动的会话没有界面，
   「模型正在干什么」只能来自日志，否则一个五分钟的回合与一个卡死的回合
   在外部完全一样。新增 `describeRunEvent`，只记工具调用与权限事件
   （全记等于没有日志），并由 runTurn 通过 onEvent 逐个交出来。

3. **关停没真断 SSE**：驱动调的是 `client.stopSSE?.()`，而客户端没有这个方法
   （`?.` 让它静默变成空操作）。改成持有 createSSEClient 的句柄并在关停时 stop。

验证：单元 325/325、授权桥 e2e 5/5、驱动 e2e（桩）7/7、快照握手 12 项。

plugins/zcode-mail-bridge/lib/gateway.mjs

@@ -50,6 +50,28 @@ export class GatewayClient {
     return headers;
   }
 
+  /**
+   * 向网关登记自己（`POST /agent/register`）。
+   *
+   * 驱动启动时调一次。**不能省**：没登记过的新部署只会在心跳与 SSE 上
+   * 反复受拒，而日志里只有看不见的 4xx —— 而驱动的日志是唯一能被看到的地方。
+   *
+   * 注意这个端点的认证方式与其它接口**不同**：它只认
+   * `Authorization: Bearer <key>` 或 **body 里的 `secret`**，
+   * 不认 `X-Agent-Secret` 头（其它接口认）。实测踩过：
+   *   HTTP 400 需要 Authorization: Bearer <密钥> 或 body 里的 secret
+   * 所以没密钥时把 secret 放进 body。
+   */
+  async register(extra = {}) {
+    if (!this.agentName) throw new Error('缺少 AGENTMAIL_AGENT_NAME');
+    if (!this.agentKey && !this.agentSecret) {
+      throw new Error('缺少 AGENTMAIL_AGENT_KEY 或 AGENTMAIL_AGENT_SECRET');
+    }
+    const body = { name: this.agentName, platform: 'zcode', ...extra };
+    if (!this.agentKey) body.secret = this.agentSecret;
+    return this.post('/agent/register', body);
+  }
+
   async get(path) {
     const res = await fetch(`${this.baseURL}/api/v1${path}`, { headers: this.authHeaders() });
     return this.#parse(res, path);

plugins/zcode-mail-bridge/src/index.mjs

@@ -107,6 +107,24 @@ export function describeError(e) {
   return e?.message || String(e);
 }
 
+/**
+ * 把 ZCode 的事件流里「值得进日志」的那几条提出来。
+ *
+ * 一轮实测能吐 6893 条事件，全记等于没有日志。只记两类：
+ * **工具调用**（模型在干什么、有没有触发授权）与**错误**。
+ * 邮件驱动的会话没有界面，这两类是唯一能回答
+ * 「它是不是卡住了 / 为什么一直没有授权询问」的信息。
+ */
+export function describeRunEvent(event) {
+  const t = String(event?.type || '');
+  if (t === 'tool.call.started') return `工具 ${event.toolName || '?'}`;
+  if (t.startsWith('tool.permission')) {
+    return `权限 ${event.decision || event.behavior || '?'}（${event.toolName || event.ruleId || '?'}）`;
+  }
+  if (/error|failed|denied|aborted/i.test(t)) return `事件 ${t}`;
+  return null;
+}
+
 /**
  * 造一个驱动实例。
  *
@@ -188,7 +206,7 @@ export function createDriver({ client, runTurnFn = runTurn, logFn = log, env = p
       logFn(`注意：--mode ${mode} 不会产生权限询问（本档如此设计）`);
     }
 
-    const prompt = buildMailPrompt({ agentName: CONFIG.agentName, data });
+    const prompt = buildMailPrompt({ agentName: CFG.agentName, data });
 
     const outcome = await runTurnFn(
       {
@@ -207,11 +225,18 @@ export function createDriver({ client, runTurnFn = runTurn, logFn = log, env = p
           AGENTMAIL_PERMISSION_MODE: tier,
           AGENTMAIL_MAIL_SUBJECT: data?.subject || '',
           AGENTMAIL_REPLY_TO: data?.mail_id || ''
+        },
+        onEvent: event => {
+          const line = describeRunEvent(event);
+          if (line) logFn(line);
         }
       },
-      { log: logFn, onChild: kill => {
+      {
+        log: logFn,
+        onChild: kill => {
           currentKill = kill;
-        } }
+        }
+      }
     );
     currentKill = null;
 
@@ -375,12 +400,21 @@ async function main() {
     log,
     onEvent: (type, data) => driver.handleEvent(type, data)
   });
+  // 留住句柄：关停时要真的断开，否则重连定时器还在跑（进程虽然马上就退，
+  // 但那是侥幸而不是设计）。
+  const sse = createSSEClient({
+    authHeaders: () => client.authHeaders(),
+    baseURL: client.baseURL,
+    path: '/api/v1/events/stream',
+    log,
+    onEvent: (type, data) => driver.handleEvent(type, data)
+  });
 
   const shutdown = reason => {
     log(`收到 ${reason}，关停中…（已处理 ${driver.stats.turns} 轮，回信 ${driver.stats.relays} 封）`);
     if (timer) clearInterval(timer);
     driver.abort();
-    client.stopSSE?.();
+    sse.stop();
     // 给杀进程留一点时间再退：自己先死会把 ZCode 变成孤儿。
     setTimeout(() => process.exit(0), 1200);
   };

plugins/zcode-mail-bridge/src/zcode-run.mjs

@@ -103,7 +103,8 @@ export function parseStreamLine(line) {
  * @param {{prompt:string, cwd:string, mode:string, maxTurns?:number,
  *          resumeSessionId?:string, turnTimeoutMs?:number,
  *          env?:Record<string,string>, cliPath?:string, nodePath?:string,
- *          onChild?:(kill:(signal?:string)=>void)=>void}} opts
+ *          onChild?:(kill:(signal?:string)=>void)=>void,
+ *          onEvent?:(event:any)=>void}} opts
  * @param {{spawn?:Function, log?:Function}} [deps] spawn 可注入以便测试
  * @returns {Promise<{sessionId:string, response:string, events:any[], exitCode:number,
  *                    unparsable:number, timedOut:boolean, killed:boolean,
@@ -239,6 +240,16 @@ export function runTurn(opts, deps = {}) {
           result = parsed;
         } else {
           events.push(parsed.event);
+          // 逐个事件交给调用方：邮件驱动的会话没有界面，
+          // 「模型正在干什么」只能靠日志，否则一个五分钟的回合在外部看起来
+          // 与一个卡死的回合完全一样。
+          if (typeof opts.onEvent === 'function') {
+            try {
+              opts.onEvent(parsed.event);
+            } catch {
+              /* 调用方的日志出错不该影响这一轮 */
+            }
+          }
         }
       }
     });

plugins/zcode-mail-bridge/test/manual/driver-real-e2e.mjs

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+/**
+ * 真模型端到端：**唯一用真 ZCode + 真模型跑的一段**。
+ *
+ * 前两个脚本分别验了「授权钩子」（桩 stdin/stdout）与「驱动」（桩 CLI）。
+ * 这个验的是它们合起来、并且模型真的在其中的那一环：
+ *
+ *   人来信 → 驱动起一轮 ZCode（真模型）→ 模型调 read_inbox 读信
+ *          → 模型调 Bash（触发 PermissionRequest 钩子）
+ *          → 钩子把授权询问发给人类 → 人在界面上点同意
+ *          → 钩子收到决定并放行 → bash 执行 → 模型把结论说出来
+ *          → 驱动把最终文本回信 → 人收到回信
+ *
+ * 用**本地 llmsproxy**（`http://127.0.0.1:8081/v1`）作为模型，不走 Z.AI OAuth ——
+ * 服务器上没有浏览器，让 headless 依赖一次人工登录不合适。
+ *
+ * # 判据设计
+ *
+ * - **A（不需要授权）**：让模型把一句话原样回过来。判据是回信里出现那个唯一标记 ——
+ *   这同时证明「模型读了信」「模型产出了文本」「驱动把文本回了出去」。
+ * - **B（需要授权）**：让模型用 bash 打出一个唯一标记。判据是**三个观测点都要成立**：
+ *     ① 出现了一条属于本会话的待决权限（钩子真的把询问发出去了）
+ *     ② 人点同意后回信里出现那个标记（工具真的执行了）
+ *     ③ 该次 bash 审批请求只出现一次（不是每次工具都问，也不是没问）
+ *   ②单独成立不够 —— 模型可以不用 bash、直接编出那句话。所以还要看它有没有真的
+ *   走过审批（①），以及最终工作目录里有没有痕迹（下面用文件系统核对）。
+ *
+ * 用法: node test/manual/driver-real-e2e.mjs [--scenario a|b|all]
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm, readFile, readdir } from 'node:fs/promises';
+import { mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DRIVER = join(HERE, '../../src/index.mjs');
+const GATEWAY = process.env.GATEWAY || 'http://127.0.0.1:8180';
+const HUMAN = { username: 'gui-lab', password: 'gui123456' };
+const SCENARIO = (process.argv.includes('--scenario')
+  ? process.argv[process.argv.indexOf('--scenario') + 1]
+  : 'all') || 'all';
+
+const results = [];
+const record = (name, state, detail) => {
+  results.push({ name, state, detail });
+  const icon = state === '通过' ? '✓' : state === '失败' ? '✗' : '?';
+  console.log(`  ${icon} ${name}${detail ? ` —— ${detail}` : ''}`);
+};
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+async function login() {
+  const res = await fetch(`${GATEWAY}/api/v1/auth/login`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(HUMAN)
+  });
+  if (!res.ok) throw new Error(`登录失败 HTTP ${res.status}`);
+  return (res.headers.getSetCookie?.() ?? []).map(c => c.split(';')[0]).join('; ');
+}
+
+/** 人类发信给 zcode，返回 session_id。 */
+async function humanSend(cookie, subject, body) {
+  const res = await fetch(`${GATEWAY}/api/v1/me/mail/send`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Cookie: cookie },
+    body: JSON.stringify({ to: 'zcode', subject, body })
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`发信失败 HTTP ${res.status} ${JSON.stringify(data).slice(0, 200)}`);
+  return data;
+}
+
+/** 收件箱里按唯一标记找 zcode 的回信。 */
+async function findReply(cookie, marker, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const res = await fetch(`${GATEWAY}/api/v1/me/mail/inbox?limit=30`, { headers: { Cookie: cookie } });
+    if (res.ok) {
+      const data = await res.json().catch(() => ({}));
+      const hit = (data.mails || []).find(
+        m =>
+          String(m.subject || '').includes(marker) &&
+          String(m.from_name || '') === 'zcode' &&
+          !String(m.subject || '').startsWith('处理失败')
+      );
+      if (hit) return hit;
+    }
+    await sleep(1000);
+  }
+  return null;
+}
+
+async function findFailure(cookie, marker, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const res = await fetch(`${GATEWAY}/api/v1/me/mail/inbox?limit=30`, { headers: { Cookie: cookie } });
+    if (res.ok) {
+      const data = await res.json().catch(() => ({}));
+      const hit = (data.mails || []).find(
+        m => String(m.subject || '').includes(marker) && String(m.subject || '').startsWith('处理失败')
+      );
+      if (hit) return hit;
+    }
+    await sleep(1000);
+  }
+  return null;
+}
+
+/** 等一条属于指定会话的待决权限（按启动前快照差集 + session_id 过滤）。 */
+async function waitPending(cookie, sessionId, before, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const res = await fetch(`${GATEWAY}/api/v1/permission/pending?all=true`, { headers: { Cookie: cookie } });
+    if (res.ok) {
+      const { requests } = await res.json().catch(() => ({ requests: [] }));
+      const hit = (requests || []).find(
+        r => !before.has(r.mail_id) && r.agent_name === 'zcode' && (!sessionId || r.session_id === sessionId)
+      );
+      if (hit) return hit;
+    }
+    await sleep(800);
+  }
+  return null;
+}
+
+async function decide(cookie, mailId, decision) {
+  const res = await fetch(`${GATEWAY}/api/v1/permission/decide`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Cookie: cookie },
+    body: JSON.stringify({ mail_id: mailId, decision, note: 'real-e2e' })
+  });
+  return res.ok;
+}
+
+async function main() {
+  const work = await mkdtemp(join(tmpdir(), 'zc-real-'));
+  const cfgDir = join(work, 'cfg');
+  const wsRoot = join(work, 'ws');
+  mkdirSync(cfgDir, { recursive: true });
+  mkdirSync(wsRoot, { recursive: true });
+
+  let env = { ...process.env };
+  try {
+    env.AGENTMAIL_AGENT_SECRET = (await readFile('/root/gotmp/zcode-agent-secret.txt', 'utf8')).trim();
+  } catch {}
+  if (!env.AGENTMAIL_AGENT_SECRET) {
+    console.error('拿不到 zcode 凭据');
+    process.exit(2);
+  }
+  env = {
+    ...env,
+    AGENTMAIL_GATEWAY_URL: GATEWAY,
+    AGENTMAIL_AGENT_NAME: 'zcode',
+    // 真 CLI（不是桩）：走 ~/.zcode/cli/config.json 里配的本地 llmsproxy
+    AGENTMAIL_ZCODE_CLI: '/opt/ZCode/resources/glm/zcode.cjs',
+    AGENTMAIL_CONFIG_DIR: cfgDir,
+    AGENTMAIL_WORKSPACE_ROOT: wsRoot,
+    AGENTMAIL_TURN_TIMEOUT_MS: '420000',
+    AGENTMAIL_PERMISSION_WAIT_MS: '150000'
+  };
+
+  const cookie = await login();
+  console.log('已登录人类账号\n');
+
+  // 启动前快照（避免把历史待决请求当成我们刚建的）
+  const before = new Set();
+  {
+    const res = await fetch(`${GATEWAY}/api/v1/permission/pending?all=true`, { headers: { Cookie: cookie } });
+    const { requests } = await res.json().catch(() => ({ requests: [] }));
+    for (const r of requests || []) before.add(r.mail_id);
+    if (before.size) console.log(`启动前已有 ${before.size} 条历史待决请求（已排除）\n`);
+  }
+
+  const driver = spawn(process.execPath, [DRIVER], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  const log = [];
+  driver.stdout.on('data', d => log.push(d.toString()));
+  driver.stderr.on('data', d => log.push(d.toString()));
+  const stopAndWait = async () => {
+    if (driver.exitCode !== null) return;
+    const done = new Promise(r => driver.once('exit', r));
+    driver.kill('SIGTERM');
+    await Promise.race([done, sleep(6000)]);
+  };
+
+  try {
+    let ready = false;
+    for (let i = 0; i < 40 && !ready; i++) {
+      await sleep(300);
+      ready = log.join('').includes('驱动就绪');
+      if (driver.exitCode !== null) break;
+    }
+    if (!ready) {
+      record('驱动启动', '失败', log.join('').slice(-300) || `退出码 ${driver.exitCode}`);
+      return;
+    }
+    console.log('驱动就绪（真 CLI + 本地模型）\n');
+
+    // ── A. 不需要授权：模型读信 → 产出文本 → 驱动回信 ──────────
+    if (SCENARIO === 'a' || SCENARIO === 'all') {
+      const marker = `ZC-A-${Date.now()}`;
+      console.log(`── A: 纯文本问答（标记 ${marker}）`);
+      await humanSend(cookie, `真模型验证A ${marker}`, `请把下面这一行原样回给我，不要改动：${marker}`);
+      const reply = await findReply(cookie, marker, 300000);
+      if (!reply) {
+        const fail = await findFailure(cookie, marker, 3000);
+        record('A · 模型读信并回信', '失败', fail ? `收到失败信：${String(fail.body).slice(0, 80)}` : '5 分钟内没有回信');
+      } else if (String(reply.body || '').includes(marker)) {
+        record('A · 模型读信并回信', '通过', `回信含标记，正文 ${String(reply.body).length} 字`);
+      } else {
+        record('A · 模型读信并回信', '失败', `回信正文没有标记：${String(reply.body).slice(0, 80)}`);
+      }
+    }
+
+    // ── B. 需要授权：模型调 Bash → 钩子问人 → 人同意 → 执行 ────
+    if (SCENARIO === 'b' || SCENARIO === 'all') {
+      const marker = `ZC-B-${Date.now()}`;
+      console.log(`\n── B: 需要授权的工具（标记 ${marker}）`);
+      const sent = await humanSend(
+        cookie,
+        `真模型验证B ${marker}`,
+        `请用 bash 工具执行这条命令，并把它的**原始输出**回给我（不要自己编）：\n\necho ${marker}\n\n` +
+          `执行完请只回一行，内容就是那条命令的输出。`
+      );
+      const sessionId = sent.session_id;
+
+      // ① 钩子应当把授权请求发给人类
+      const pending = await waitPending(cookie, sessionId, before, 300000);
+      if (!pending) {
+        record('B① · 授权询问送达人类', '失败', '5 分钟内没有收到该会话的待决权限');
+      } else {
+        record('B① · 授权询问送达人类', '通过', `问题：${String(pending.question).slice(0, 40)}`);
+        before.add(pending.mail_id);
+
+        // ② 人点同意 → 工具应当执行 → 回信里出现标记
+        const okDecide = await decide(cookie, pending.mail_id, '同意');
+        if (!okDecide) record('B② · 决策接口', '失败', 'decide 返回非 2xx');
+        const reply = await findReply(cookie, marker, 300000);
+        if (!reply) {
+          const fail = await findFailure(cookie, marker, 3000);
+          record('B② · 批准后工具执行且回信', '失败', fail ? `失败信：${String(fail.body).slice(0, 80)}` : '5 分钟内没有回信');
+        } else if (String(reply.body || '').includes(marker)) {
+          record('B② · 批准后工具执行且回信', '通过', `回信含标记（说明命令真的跑了）：${String(reply.body).slice(0, 60)}`);
+        } else {
+          record('B② · 批准后工具执行且回信', '失败', `回信里没有标记：${String(reply.body).slice(0, 90)}`);
+        }
+      }
+
+      // ③ 该工具在本次会话只该问一次（不是每次调用都问，也不是没问）
+      await sleep(2000);
+      const res = await fetch(`${GATEWAY}/api/v1/permission/pending?all=true`, { headers: { Cookie: cookie } });
+      const { requests } = await res.json().catch(() => ({ requests: [] }));
+      const mine = (requests || []).filter(r => r.session_id === sessionId && r.agent_name === 'zcode');
+      if (mine.length === 0) {
+        record('B③ · 同一会话不重复追问', '通过', '没有遗留的待决权限');
+      } else {
+        record('B③ · 同一会话不重复追问', '无法判定', `仍有 ${mine.length} 条待决（可能是模型又发起了新的工具调用）`);
+      }
+    }
+  } finally {
+    await stopAndWait();
+    await rm(work, { recursive: true, force: true });
+  }
+
+  const pass = results.filter(r => r.state === '通过').length;
+  const fail = results.filter(r => r.state === '失败').length;
+  const unknown = results.filter(r => r.state === '无法判定').length;
+  console.log(`\n结果：${pass} 通过 / ${fail} 失败 / ${unknown} 无法判定`);
+  console.log('\n驱动日志尾部：');
+  console.log(`  ${log.join('').split('\n').slice(-12).join('\n  ')}`);
+  process.exit(fail > 0 ? 1 : 0);
+}
+
+main().catch(e => {
+  console.error('验证脚本自身出错:', e);
+  process.exit(2);
+});