@harness-mix/cli 0.2.3 → 0.3.0

package/scripts/openclaw-mcp-tool-probe.cjs

@@ -0,0 +1,55 @@
+// OpenClaw 托管 MCP 端到端实测：推送极简 echo MCP 服务器 → 真实 agent 回合调用其工具 →
+// 捕获 tool 流帧验证 → 清理并断言注册表还原。证据落 output/openclaw-mcp-probe/。
+const fs = require("node:fs");
+const path = require("node:path");
+const { randomUUID } = require("node:crypto");
+const { OpenClawGatewayHost, OPENCLAW_CONFIG } = require("../src/main/adapters/openclaw-gateway");
+const { applyManagedMcpServers, MCP_OWNED_PREFIX } = require("../src/main/adapters/openclaw");
+
+const OUT_DIR = path.join(__dirname, "..", "output", "openclaw-mcp-probe");
+const ECHO_SERVER = path.join(OUT_DIR, "echo-mcp-server.cjs");
+
+(async () => {
+  const backup = path.join(OUT_DIR, `openclaw.json.backup-tool-${Date.now()}`);
+  fs.copyFileSync(OPENCLAW_CONFIG, backup);
+  const frames = [];
+  let ok = false;
+  try {
+    await applyManagedMcpServers([{ name: "probe", command: process.execPath, args: [ECHO_SERVER] }], (l) => console.log(l));
+    const host = await OpenClawGatewayHost.acquire((l) => console.error(l));
+    try {
+      const baseKey = `harness-mix-mcp-tool-probe-${Date.now()}`;
+      const created = await host.call("sessions.create", { key: baseKey, label: `Harness Mix MCP tool probe ${Date.now()}` });
+      const sessionKey = created?.key ?? baseKey;
+      const unwatch = host.onEvent((frame) => {
+        if (frame?.type !== "event" || frame.event !== "agent") return;
+        const p = frame.payload ?? {};
+        if (p.sessionKey && p.sessionKey !== sessionKey) return;
+        frames.push(p);
+        if (p.stream === "tool") console.log(`[tool] ${p.data?.name ?? ""} phase=${p.data?.phase} meta=${p.data?.meta ?? ""}`);
+      });
+      const accepted = await host.call("agent", {
+        message: "请调用 MCP 工具 hm_echo（若名称带前缀也用它），参数 text=HELLO_HM。完成后只回复工具返回的原始文本，不要添加别的内容。",
+        sessionKey, idempotencyKey: randomUUID(), deliver: false,
+      });
+      console.log("agent accepted:", JSON.stringify(accepted));
+      const settled = await host.call("agent.wait", { runId: accepted.runId, timeoutMs: 240_000 }, 250_000);
+      console.log("agent.wait:", JSON.stringify(settled).slice(0, 300));
+      unwatch();
+      const toolCalls = frames.filter((f) => f.stream === "tool");
+      const echoHit = toolCalls.some((f) => String(f.data?.name ?? "").includes("hm_echo") || String(f.data?.meta ?? "").includes("hm_echo"));
+      const assistantText = frames.filter((f) => f.stream === "assistant").map((f) => f.data?.delta ?? f.data?.text ?? "").join("");
+      console.log(`tool frames: ${toolCalls.length}, hm_echo hit: ${echoHit}, assistant: ${assistantText.slice(0, 120)}`);
+      fs.writeFileSync(path.join(OUT_DIR, "tool-call-evidence.json"), JSON.stringify({ capturedAt: new Date().toISOString(), frames, echoHit, assistantText }, null, 2));
+      ok = echoHit || /ECHO:HELLO_HM/.test(assistantText);
+      console.log(ok ? "TOOL PROBE OK：托管 MCP 工具被真实调用" : "TOOL PROBE 未观测到工具调用（模型未配合或 bundle 未加载）");
+    } finally { await OpenClawGatewayHost.release(); }
+  } finally {
+    await applyManagedMcpServers([], () => {});
+    if (!ok) {
+      fs.copyFileSync(backup, OPENCLAW_CONFIG);
+      console.error("已用备份还原 openclaw.json");
+    }
+  }
+  process.exit(ok ? 0 : 1);
+})().catch((e) => { console.error("FAILED:", e); process.exit(1); });

package/scripts/openclaw-thinking-probe.cjs

@@ -0,0 +1,73 @@
+// OpenClaw Gateway 思考流探针：开启 reasoningLevel=stream 后跑一个真实回合，
+// 捕获 agent 广播原始帧（重点 stream:"thinking"），为适配器投影与能力声明提供实测证据。
+// 用法：node scripts/openclaw-thinking-probe.cjs [modelId]
+const fs = require("node:fs");
+const path = require("node:path");
+const { randomUUID } = require("node:crypto");
+const { OpenClawGatewayHost } = require("../src/main/adapters/openclaw-gateway");
+
+const OUT_DIR = path.join(__dirname, "..", "output", "openclaw-thinking-probe");
+
+(async () => {
+  fs.mkdirSync(OUT_DIR, { recursive: true });
+  const host = await OpenClawGatewayHost.acquire((line) => console.error(line));
+  const frames = [];
+  try {
+    const key = `harness-mix-thinking-probe-${Date.now()}`;
+    const created = await host.call("sessions.create", { key, label: `Harness Mix thinking probe ${Date.now()}` });
+    console.log("sessions.create ->", JSON.stringify(created));
+    const sessionKey = created?.key ?? key;
+
+    // 两个独立维度：thinkingLevel 控制推理投入，reasoningLevel=stream 才把思考流广播给客户端
+    let patched = null;
+    try {
+      patched = await host.call("sessions.patch", { key: sessionKey, reasoningLevel: "stream", thinkingLevel: "medium" });
+    } catch (error) {
+      console.error("sessions.patch FAILED:", error.message, "code=", error.code);
+    }
+    console.log("sessions.patch ->", JSON.stringify(patched));
+
+    const modelArg = process.argv[2] || undefined;
+    if (modelArg) console.log("using model override:", modelArg);
+
+    const unwatch = host.onEvent((frame) => {
+      if (frame?.type !== "event" || frame.event !== "agent") return;
+      const p = frame.payload ?? {};
+      if (p.sessionKey && p.sessionKey !== sessionKey) return;
+      frames.push(p);
+      const data = p.data ?? {};
+      const brief = typeof data.delta === "string" ? data.delta : typeof data.text === "string" ? data.text : "";
+      console.log(`[stream=${p.stream}] ${(brief || JSON.stringify(data)).slice(0, 160).replace(/\n/g, "\\n")}`);
+    });
+
+    const accepted = await host.call("agent", {
+      message: "一个三位数，各位数字之和为 18，百位比个位大 3，且它是 4 的倍数。求这个数，并给出推理过程。",
+      sessionKey,
+      idempotencyKey: randomUUID(),
+      deliver: false,
+      thinking: "high",
+      ...(modelArg ? { model: modelArg } : {}),
+    });
+    console.log("agent ->", JSON.stringify(accepted));
+    if (!accepted?.runId) throw new Error("未返回 runId");
+    const settled = await host.call("agent.wait", { runId: accepted.runId, timeoutMs: 240_000 }, 250_000);
+    console.log("agent.wait ->", JSON.stringify(settled));
+    unwatch();
+
+    const described = await host.call("sessions.describe", { key: sessionKey }).catch((e) => ({ error: e.message }));
+    console.log("sessions.describe ->", JSON.stringify(described?.session ?? described));
+
+    const summary = {};
+    for (const f of frames) summary[f.stream] = (summary[f.stream] ?? 0) + 1;
+    const hasThinking = frames.some((f) => f.stream === "thinking" && (f.data?.delta || f.data?.text));
+    console.log("stream summary ->", JSON.stringify(summary), "thinkingVerified=", hasThinking);
+
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const outFile = path.join(OUT_DIR, `thinking-frames-${stamp}.json`);
+    fs.writeFileSync(outFile, JSON.stringify({ capturedAt: new Date().toISOString(), key, frames, described: described?.session ?? null, summary, hasThinking }, null, 2));
+    console.log("saved ->", outFile);
+  } finally {
+    await OpenClawGatewayHost.release();
+  }
+  process.exit(0);
+})().catch((e) => { console.error("FAILED:", e); process.exit(1); });

package/scripts/salvage-rollout-writes.cjs

@@ -0,0 +1,72 @@
+// One-off salvage: extract Write/Edit tool-call payloads for out/ paths from a
+// ZCode model-io rollout journal and replay the write+edit chain to rebuild
+// final file contents. Used to recover the promo-video generation scripts
+// after the workspace out/ tree was deleted. Not part of any suite.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const journal = process.argv[2];
+const destRoot = process.argv[3];
+if (!journal || !destRoot) {
+  console.error('usage: node salvage-rollout-writes.cjs <rollout.jsonl> <destRoot>');
+  process.exit(1);
+}
+
+const lines = fs.readFileSync(journal, 'utf8').split('\n').filter(Boolean);
+const occurrences = []; // {fp, tool, lineIdx, content?, old?, new?} in journal order
+
+const normalize = fp => String(fp).replace(/\\/g, '/').replace(/^[A-Za-z]:\/+/, '').replace(new RegExp(`^${path.basename(process.cwd())}/`), '');
+
+function scan(node, lineIdx) {
+  if (Array.isArray(node)) { for (const x of node) scan(x, lineIdx); return; }
+  if (!node || typeof node !== 'object') return;
+  const isToolCall = (node.type === 'tool_use') || (typeof node.id === 'string' && node.id.startsWith('call_') && typeof node.name === 'string' && node.input && typeof node.input === 'object');
+  if (isToolCall && node.input && typeof node.input.file_path === 'string') {
+    const fp = normalize(node.input.file_path);
+    if (/(^|\/)out\//.test(fp)) {
+      occurrences.push({
+        fp, tool: node.name, lineIdx,
+        content: node.input.content != null ? String(node.input.content) : null,
+        old: node.input.old_string != null ? String(node.input.old_string) : null,
+        next: node.input.new_string != null ? String(node.input.new_string) : null,
+        replaceAll: node.input.replace_all === true,
+      });
+    }
+  }
+  for (const v of Object.values(node)) scan(v, lineIdx);
+}
+
+let idx = 0;
+for (const line of lines) {
+  idx += 1;
+  try { scan(JSON.parse(line), idx); } catch { /* malformed line */ }
+}
+
+// Replay: last Write wins as the base, then Edits that appear AFTER it in order.
+// Edits before the last Write are already baked into that Write's content.
+const byPath = new Map();
+for (const occ of occurrences) {
+  if (!byPath.has(occ.fp)) byPath.set(occ.fp, []);
+  byPath.get(occ.fp).push(occ);
+}
+
+const summary = [];
+for (const [fp, chain] of byPath) {
+  const lastWriteIdx = chain.map(o => o.tool === 'Write').lastIndexOf(true);
+  if (lastWriteIdx === -1) { summary.push(`SKIP (no Write captured)\t${fp}`); continue; }
+  let text = chain[lastWriteIdx].content;
+  let applied = 0, skipped = 0;
+  for (const occ of chain.slice(lastWriteIdx + 1)) {
+    if (occ.tool !== 'Edit' || occ.old == null || occ.next == null) continue;
+    const count = text.split(occ.old).length - 1;
+    if (count === 0 || (!occ.replaceAll && count > 1)) { skipped += 1; continue; }
+    text = occ.replaceAll ? text.split(occ.old).join(occ.next) : text.replace(occ.old, occ.next);
+    applied += 1;
+  }
+  const abs = path.join(destRoot, fp);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, text);
+  summary.push(`OK\tline ${chain[lastWriteIdx].lineIdx} (+${applied}edits, ${skipped}skipped)\t${fp}\t${text.length} chars`);
+}
+console.log(summary.join('\n'));
+console.log(`FILES ${summary.filter(s => s.startsWith('OK')).length} / paths ${byPath.size}`);

package/scripts/storage-verification-test.cjs

@@ -69,6 +69,17 @@ const { ThreadStore } = require('../src/main/host/thread-store');
     const failed = await gates.run(thread);
     assert.equal(failed.status, 'failed');
     assert.equal(gates.inspect(thread).satisfied, true, 'advisory failures do not block delivery');
+    // advisory()：off 策略的 apply 零配置安全网——跑内建检查，不跑用户命令、
+    // 不写 latestReport、不改线程策略；显式策略下不附加
+    gates.configure(thread, { mode: 'off', commands: [`"${process.execPath}" -e "process.exit(3)"`] });
+    const advisory = await gates.advisory(thread);
+    assert.equal(advisory.mode, 'advisory');
+    assert.deepEqual(advisory.commands, [], 'advisory 不跑用户命令');
+    assert.ok(advisory.checks.some(check => check.id === 'turnCompleted'), '内建检查在列');
+    assert.equal(gates.inspect(thread).policy.mode, 'off', '线程策略保持 off');
+    assert.equal(gates.inspect(thread).report, null, 'advisory 不写 latestReport');
+    gates.configure(thread, { mode: 'advisory' });
+    assert.equal(await gates.advisory(thread), null, '显式策略下不附加安全网');
     assert.throws(() => normalizePolicy({ commands: [{ command: '' }] }), /Invalid verification command/);
     assert.throws(() => normalizePolicy({ commands: [{ command: 'tool --token sk-1234567890abcdef' }] }), /credential-like data/);
     console.log('PASS: schema v2 compact migration, backup, storage metrics and configurable verification gates');

package/scripts/zcode-adapter-test.cjs

@@ -0,0 +1,329 @@
+// ZCode native app-server adapter coverage: runs the adapter against a fixture
+// ZCode Protocol app-server (same framing, method set and event shapes as
+// zcode.cjs 0.16.5). Fully offline. Invoked as
+//   node zcode-adapter-test.cjs            -> driver
+//   node zcode-adapter-test.cjs app-server --stdio  -> fixture (via env override)
+const assert = require('node:assert/strict');
+
+const mode = process.argv[2];
+
+if (mode === 'app-server') {
+  // Fixture: minimal ZCode app-server speaking the verified protocol subset.
+  let nextId = 100;
+  let turnCount = 0;
+  const seenModes = [];
+  const send = payload => process.stdout.write(`${JSON.stringify(payload)}\n`);
+  const notify = (method, params) => send({ method, params });
+  let buffer = '';
+  // server→client 请求的处理注册表：应答到达时回调
+  const pendingServerRequests = new Map();
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    buffer += chunk;
+    let i;
+    while ((i = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, i); buffer = buffer.slice(i + 1);
+      let message;
+      try { message = JSON.parse(line); } catch { continue; }
+      // jsonrpc:false 模式下客户端帧不得携带 jsonrpc 字段
+      assert.equal(message.jsonrpc, undefined, 'client frames must not carry a jsonrpc key');
+      const { id, method, params } = message;
+      if (id !== undefined && pendingServerRequests.has(id)) {
+        pendingServerRequests.get(id)(message);
+        pendingServerRequests.delete(id);
+        continue;
+      }
+      if (method === 'session/create') {
+        const prefsId = nextId++;
+        pendingServerRequests.set(prefsId, data => {
+          assert.deepEqual(data.result, { nativeSearchEnhancementsEnabled: false, memoryEnabled: false, askUserQuestionAutoResolutionEnabled: true, modelContextBudgetStrategy: 'preflight-v1' });
+          send({ id, result: { session: { sessionId: 'sess-fix', mode: 'build', status: 'idle' }, projection: { contextUsed: 0, contextWindow: 200000, status: 'idle' } } });
+        });
+        send({ id: prefsId, method: 'session/requestRuntimePreferences', params: { sessionId: 'sess-fix', scope: 'runtime-materialization' } });
+      } else if (method === 'session/subscribe') {
+        assert.equal(params.deliveryKind, 'desktop-continuous');
+        send({ id, result: { sessionId: params.sessionId, eventSeq: 0, events: [] } });
+        notify('state.updated', { scope: 'session', sessionId: params.sessionId, revision: 1, patch: { model: { available: [
+          { ref: { providerId: 'account:fixture-plan', modelId: 'glm-4.6' }, label: 'GLM-4.6', contextWindow: 200000, reasoning: { levels: [{ value: 'low' }, { value: 'high' }], defaultLevel: 'high' } },
+          { ref: { providerId: 'account:fixture-plan', modelId: 'glm-4.5-air' }, label: 'GLM-4.5 Air' },
+        ] }, projection: { contextUsed: 1234, contextWindow: 200000 } } });
+      } else if (method === 'session/setModel') {
+        assert.ok(params.model?.options?.reasoningLevel, 'setModel 必须携带 reasoningLevel');
+        send({ id, result: { sessionId: params.sessionId, accepted: true } });
+      } else if (method === 'session/setThoughtLevel') {
+        send({ id, result: { sessionId: params.sessionId, accepted: true } });
+      } else if (method === 'session/setMode') {
+        assert.ok(['plan', 'build', 'edit', 'yolo'].includes(params.mode), `setMode 必须使用规范模式枚举，收到 ${params.mode}`);
+        assert.equal(params.expectedRevision, undefined, 'setMode 无需 expectedRevision');
+        seenModes.push(params.mode);
+        assert.deepEqual(seenModes, ['build', 'yolo'].slice(0, seenModes.length), `setMode 序列应为 open 应用线程选项→显式切换：${seenModes}`);
+        send({ id, result: { sessionId: params.sessionId, mode: params.mode, accepted: true } });
+      } else if (method === 'provider/updateAccountConfig') {
+        // 安全属性:账号声明必须零密钥——仅凭据条目名(connectionKey)参与链接
+        const providerIds = Object.keys(params.providers ?? {});
+        assert.ok(providerIds.length > 0 && providerIds.every(id => /^account:/.test(id)), '推送必须使用内置 account: 供应商 id');
+        for (const id of providerIds) {
+          const access = params.providers[id]?.access ?? {};
+          assert.deepEqual(Object.keys(access).sort(), ['entitled', 'type'], 'access 不得携带密钥字段');
+          assert.equal(access.type, 'zhipu-account');
+          const state = params.states?.[id] ?? {};
+          assert.ok(/^account-provider:.*:api-key$/.test(state.connectionKey ?? ''), 'states 需携带凭据条目名 connectionKey');
+        }
+        assert.ok(!JSON.stringify(params).includes('apiKey'), '推送体不得包含 apiKey 值');
+        send({ id, result: { receivedRevision: params.revision, providerCount: providerIds.length, status: 'received' } });
+      } else if (method === 'session/send') {
+        assert.ok(['hello', '带路径图', '纯base64图', '流恢复', '拒绝流程', '重连后回合'].includes(params.content), `意外的回合内容：${params.content}`);
+        if (Array.isArray(params.attachments)) {
+          // 实测约束：dataBase64 通道只会退化为元数据占位符，附件必须走 localPath
+          for (const attachment of params.attachments) {
+            assert.equal(attachment.kind, 'image', 'Harness Mix 只路由图片附件');
+            assert.ok(attachment.filename && attachment.mimeType, '附件必须带 filename 与 mimeType');
+            assert.ok(typeof attachment.localPath === 'string' && attachment.localPath, '附件必须走 localPath 通道');
+            assert.equal(attachment.dataBase64, undefined, '不得使用会降级的 dataBase64 通道');
+            assert.ok(Number.isInteger(attachment.sizeBytes) && attachment.sizeBytes > 0, '附件需携带 sizeBytes 提示');
+          }
+        }
+        send({ id, result: { accepted: true, sessionId: params.sessionId, stateRevision: 2 } });
+        const push = payload => send({ method: 'session/event', params: { deliveryKind: 'desktop-continuous', eventId: `evt-${nextId++}`, type: payload.type, payload } });
+        turnCount += 1;
+        if (params.content === '流恢复') {
+          // 流恢复重放：上游断流后 agent 重发“尾窗口（+增量）”，eventId 是新的，
+          // 去重拦不住——适配器必须剪掉与累积文本的重叠，只下发增量。
+          const replay = () => {
+            push({ type: 'turn.started', turnNumber: turnCount, input: params.content });
+            push({ type: 'model.streaming', kind: 'text_delta', delta: 'abcdefgh1234' });
+            push({ type: 'model.streaming', kind: 'text_delta', delta: 'abcdefgh1234' });
+            push({ type: 'model.streaming', kind: 'text_delta', delta: 'abcdefgh1234下一步' });
+            push({ type: 'model.streaming', kind: 'text_delta', delta: '继续' });
+            push({ type: 'turn.completed', response: 'abcdefgh1234下一步继续', tokenCount: 5, usage: { inputTokens: 3, outputTokens: 2 }, toolCallCount: 0, duration: 0.1 });
+          };
+          setTimeout(replay, 30);
+          continue;
+        }
+        if (turnCount > 1) {
+          // 附件回合：简化事件流，回合直接完成
+          const simple = () => {
+            push({ type: 'turn.started', turnNumber: turnCount, input: params.content });
+            push({ type: 'part.delta', messageId: 'm2', partId: 'p3', field: 'text', delta: '图已收到' });
+            push({ type: 'turn.completed', response: '图已收到', tokenCount: 9, usage: { inputTokens: 5, outputTokens: 4 }, toolCallCount: 0, duration: 0.2 });
+          };
+          setTimeout(simple, 30);
+          continue;
+        }
+        const runTurn = () => {
+          push({ type: 'turn.started', turnNumber: 0, input: params.content });
+          push({ type: 'part.delta', messageId: 'm1', partId: 'p1', field: 'reasoning', delta: '思考' });
+          push({ type: 'part.delta', messageId: 'm1', partId: 'p2', field: 'text', delta: '你' });
+          push({ type: 'part.delta', messageId: 'm1', partId: 'p2', field: 'text', delta: '好' });
+          push({ type: 'tool.updated', kind: 'scheduled', toolCallId: 't1', toolName: 'read_file', input: { path: 'a.txt' } });
+          push({ type: 'tool.updated', kind: 'result', toolCallId: 't1', toolName: 'read_file', output: 'file body' });
+          push({ type: 'tool.updated', kind: 'scheduled', toolCallId: 't2', toolName: 'write_file', input: { path: 'b.txt' } });
+          const permId = nextId++;
+          pendingServerRequests.set(permId, data => {
+            const decision = data.result?.decision;
+            push({ type: 'permission.resolved', toolCallId: 't2', decision });
+            if (decision === 'allow') push({ type: 'tool.updated', kind: 'result', toolCallId: 't2', toolName: 'write_file', output: 'written' });
+            else push({ type: 'tool.updated', kind: 'result', toolCallId: 't2', toolName: 'write_file', output: `decision:${decision}` });
+            const askId = nextId++;
+            pendingServerRequests.set(askId, askData => {
+              push({ type: 'turn.completed', response: `你好（${decision}/${askData.result?.value}）`, tokenCount: 42, usage: { inputTokens: 30, outputTokens: 12 }, toolCallCount: 2, duration: 1.5, cacheStats: { cacheReadTokens: 7 } });
+            });
+            send({ id: askId, method: 'interaction/requestUserInput', params: { requestId: 'ask-1', prompt: '继续吗？', inputType: 'choice', choices: ['是', '否'] } });
+          });
+          send({ id: permId, method: 'interaction/requestPermission', params: { requestId: 'perm-1', toolCallId: 't2', toolName: 'write_file', riskLevel: 'medium', reason: '写入文件', input: { path: 'b.txt' }, options: [{ kind: 'allow_once' }] } });
+        };
+        // send 的应答先落盘，再在下一个 tick 推事件
+        setTimeout(runTurn, 30);
+      } else if (method === 'session/setModel') {
+        send({ id, result: { sessionId: params.sessionId, accepted: true } });
+      } else if (method === 'session/stop') {
+        send({ id, result: { sessionId: params.sessionId, accepted: true, stateRevision: 3 } });
+      } else if (method === 'session/events') {
+        send({ id, result: { sessionId: params.sessionId, eventSeq: 0, events: [] } });
+      } else if (method === 'session/close') {
+        send({ id, result: { sessionId: params.sessionId } });
+      } else if (id !== undefined) {
+        send({ id, error: { code: -32601, message: `Method not found: ${method}` } });
+      }
+    }
+  });
+  setTimeout(() => process.exit(0), 60000);
+  return;
+}
+
+// --- driver: exercise the adapter against the fixture via the env override ---
+const path = require('node:path');
+const fs = require('node:fs');
+const os = require('node:os');
+const zcode = require('../src/main/adapters/zcode');
+
+(async () => {
+  // 隔离:fixture 内置目录(account: fixture-plan)+ 凭据键名,不触碰真实安装
+  const fixtureBase = fs.mkdtempSync(path.join(os.tmpdir(), 'zcode-fixture-'));
+  const fixtureBuiltin = path.join(fixtureBase, 'zcode-builtin.json');
+  fs.writeFileSync(fixtureBuiltin, JSON.stringify({
+    schemaVersion: 1, revision: 42,
+    config: { providerConfigRules: { providerRules: [{ providerId: 'account:fixture-plan', config: { access: { type: 'zhipu-account', entitled: true }, builtinModelIds: ['glm-4.6', 'glm-4.5-air'] } }] }, modelConfigRules: { providerModelRules: [], manualProviderModelRules: [] } },
+  }));
+  fs.writeFileSync(path.join(fixtureBase, 'credentials.json'), JSON.stringify({ 'account-provider:coding-plan:account:fixture-plan:account:1:api-key': 'enc:v1:fake' }));
+  const previous = {
+    BUILTIN: process.env.HARNESS_MIX_ZCODE_BUILTIN_CONFIG,
+    EXEC: process.env.HARNESS_MIX_ZCODE_EXECUTABLE,
+    CREDENTIALS: process.env.HARNESS_MIX_ZCODE_CREDENTIALS,
+    SECRET: process.env.ZCODE_CREDENTIAL_SECRET,
+    DATA: process.env.ZCODE_DATA_BASE_DIR,
+  };
+  process.env.HARNESS_MIX_ZCODE_EXECUTABLE = __filename;
+  process.env.HARNESS_MIX_ZCODE_BUILTIN_CONFIG = fixtureBuiltin;
+  process.env.HARNESS_MIX_ZCODE_CREDENTIALS = path.join(fixtureBase, 'credentials.json');
+  delete process.env.ZCODE_DATA_BASE_DIR;
+  assert.deepEqual(zcode.resolveLaunch(), { command: process.execPath, args: [__filename, 'app-server', '--stdio'] });
+  assert.equal(zcode.manifest.capabilities.permissionModes, true, 'manifest 必须声明 permissionModes 能力');
+  assert.equal(zcode.manifest.capabilities.attachments, true, 'manifest 必须声明 attachments 能力');
+  assert.equal(zcode.manifest.capabilities.collaborationTools, true, 'manifest 必须声明 collaborationTools（工人/团队成员角色）');
+  const adapter = zcode.create();
+  const events = [];
+  let session;
+  try {
+    session = await adapter.open({
+      thread: { cwd: process.cwd(), options: { permissionMode: 'build' } },
+      emit: event => events.push(event),
+      diagnostic: () => {},
+      // 协作描述符在 open 时传入（工人/成员角色不需要 harness 侧 MCP 工具）
+      collaboration: { command: process.execPath, args: ['bridge.cjs'], env: { HARNESS_MIX_COLLAB_KEY: 'fixture' } },
+    });
+    assert.equal(session.state.sessionId, 'sess-fix');
+    const sessionEvent = events.find(event => event.kind === 'session');
+    assert.equal(sessionEvent.nativeSessionId, 'sess-fix');
+
+    const models = await adapter.listModelsFor(session);
+    assert.deepEqual(models.map(model => model.id), ['glm-4.6', 'glm-4.5-air']);
+    assert.equal(models[0].provider, 'account:fixture-plan');
+    assert.deepEqual(models[0].efforts, ['low', 'high']);
+    assert.equal(models[0].defaultEffort, 'high');
+    const selected = await adapter.setModel(session, models[0]);
+    assert.equal(selected.id, 'glm-4.6');
+    await adapter.setThinkingLevel(session, 'low');
+
+    // 权限模式目录与官方桌面选择器一致；线程选项在 open 时已生效
+    const catalog = await adapter.describeFor(session);
+    assert.deepEqual(catalog.permissionModes.map(mode => mode.id), ['plan', 'build', 'edit', 'yolo']);
+    assert.equal(catalog.permissionModes.find(mode => mode.default)?.id, 'build', '原生默认档是 build');
+    assert.equal(catalog.permissionModes.find(mode => mode.dangerous)?.id, 'yolo', '完全访问必须标记 dangerous');
+    await adapter.setPermissionMode(session, 'yolo');
+    await assert.rejects(() => adapter.setPermissionMode(session, 'auto'), /未知的 ZCode 权限模式/, '目录外模式必须拒绝');
+
+    // 权限/提问卡片先于回合结束出现，respond 后回合才完成
+    const settled = adapter.send(session, 'hello');
+    await assert.rejects(
+      () => Promise.race([settled, new Promise((_, reject) => setTimeout(() => reject(new Error('回合提前结束')), 400))]),
+      /回合提前结束/, '权限未应答时回合必须保持等待');
+    const waitFor = async predicate => {
+      for (let i = 0; i < 200; i++) {
+        const found = events.find(predicate);
+        if (found) return found;
+        await new Promise(resolve => setTimeout(resolve, 30));
+      }
+      return null;
+    };
+    const approval = await waitFor(event => event.kind === 'approval' && String(event.requestId).includes('requestPermission'));
+    assert.ok(approval, '权限卡片必须投影');
+    assert.ok(approval.title.includes('write_file'));
+    await adapter.respond(session, approval.requestId, { optionId: 'accept' });
+    const question = await waitFor(event => event.kind === 'approval' && String(event.requestId).includes('requestUserInput'));
+    assert.ok(question, '提问卡片必须投影');
+    assert.deepEqual(question.options.map(option => option.id), ['是', '否']);
+    await adapter.respond(session, question.requestId, { optionId: '是' });
+    await settled;
+
+    assert.equal(events.filter(event => event.kind === 'thinking-delta').map(event => event.text).join(''), '思考', 'reasoning delta 投影');
+    assert.equal(events.filter(event => event.kind === 'text-delta').map(event => event.text).join(''), '你好');
+    const tools = events.filter(event => event.kind === 'tool');
+    assert.deepEqual(tools.map(tool => `${tool.toolCallId}:${tool.state}`), ['t1:running', 't1:done', 't2:running', 't2:done']);
+    assert.equal(tools[1].output, 'file body');
+    assert.equal(tools[3].output, 'written');
+    const usageEvent = events.find(event => event.kind === 'usage');
+    assert.deepEqual(usageEvent.usage, { inputTokens: 30, outputTokens: 12, cachedInputTokens: 7, totalTokens: 42 });
+    assert.ok(events.some(event => event.kind === 'completed' && event.finalAnswer === true));
+    const context = await adapter.getContextUsage(session);
+    // projectUsage 只认 tokens/contextUsedTokens；usedTokens 键永远匹配不上
+    assert.deepEqual(context, { tokens: 1234, contextWindow: 200000 });
+
+    // 附件：runtime 已给路径的图直接走 localPath；纯 base64 落盘为临时文件后同通道发送
+    await adapter.send(session, '带路径图', null, { images: [
+      { name: 'shot.png', mime: 'image/png', data: 'aGVsbG8=', path: path.join(fixtureBase, 'shot.png') },
+    ] });
+    await adapter.send(session, '纯base64图', null, { images: [
+      { name: 'paste.png', mime: 'image/png', data: Buffer.from('png-bytes').toString('base64') },
+    ] });
+    const textAfter = events.filter(event => event.kind === 'text-delta').map(event => event.text).join('');
+    assert.ok(textAfter.includes('图已收到'), '附件回合必须完成');
+    assert.equal(session.state.tempFiles.length, 1, '仅 base64-only 图片落盘');
+    const tempFile = session.state.tempFiles[0];
+    assert.ok(fs.existsSync(tempFile), 'base64 附件必须物化为临时文件');
+    assert.equal(fs.readFileSync(tempFile).toString(), 'png-bytes', '落盘内容必须与 base64 解码一致');
+
+    // 流恢复重放去重：重放窗口整体与累积文本尾部重叠，只允许增量透出
+    const trim = zcode.trimStreamReplayOverlap;
+    assert.equal(trim('', 'abc'), 'abc', '空累积不裁剪');
+    assert.equal(trim('你好', 'xy'), 'xy', '无重叠不裁剪');
+    assert.equal(trim(`xx${'0123456789AB'}`, `${'0123456789AB'}cd`), 'cd', '12 字符重叠必须裁剪');
+    assert.equal(trim(`xx${'0123456789A'}`, `${'0123456789A'}cd`), `${'0123456789A'}cd`, '11 字符重叠低于阈值不裁剪');
+    assert.equal(trim('abcdefgh1234', 'abcdefgh1234'), '', '纯重放（无增量）整段丢弃');
+    const replayMark = events.length;
+    await adapter.send(session, '流恢复');
+    const replayText = events.slice(replayMark).filter(event => event.kind === 'text-delta').map(event => event.text).join('');
+    assert.equal(replayText, 'abcdefgh1234下一步继续', '重放窗口必须剪掉，只透出增量');
+    assert.ok(events.slice(replayMark).some(event => event.kind === 'completed'), '流恢复回合必须正常完成');
+
+    // 取消：向 server 发送 session/stop 并本地结算；旧回合迟到的 turn.completed
+    // 不得结算新回合（suppressCompletions 直到下一次 turn.started 才复位）
+    await adapter.cancel(session);
+    assert.equal(session.state.suppressCompletions, true, '取消后必须压制迟到 completion');
+    await adapter.close(session);
+    assert.equal(fs.existsSync(tempFile), false, 'close 后必须清理附件临时文件');
+
+    // 拒绝权限：decline 必须映射为 {decision:'deny'}（fixture 会把 decision 回显进回合响应）
+    {
+      const declineEvents = [];
+      const declineSession = await adapter.open({ thread: { cwd: process.cwd() }, emit: e => declineEvents.push(e), diagnostic: () => {} });
+      try {
+        const declineWaitFor = async predicate => {
+          for (let i = 0; i < 100; i++) {
+            const hit = declineEvents.find(predicate);
+            if (hit) return hit;
+            await new Promise(resolve => setTimeout(resolve, 30));
+          }
+          return null;
+        };
+        const turn = adapter.send(declineSession, '拒绝流程', null);
+        const approval = await declineWaitFor(event => event.kind === 'approval' && String(event.requestId).includes('requestPermission'));
+        assert.ok(approval, 'decline 流程：权限卡片必须投影');
+        await adapter.respond(declineSession, approval.requestId, { optionId: 'decline' });
+        const question = await declineWaitFor(event => event.kind === 'approval' && String(event.requestId).includes('requestUserInput'));
+        assert.ok(question, 'decline 流程：提问卡片必须投影');
+        await adapter.respond(declineSession, question.requestId, { optionId: '是' });
+        await turn;
+        const denyTool = declineEvents.find(event => event.kind === 'tool' && event.toolCallId === 't2' && event.state === 'done');
+        assert.equal(denyTool?.output, 'decision:deny', 'decline 应答必须是 deny（不得短路成 cancelled）');
+        // 进程死亡自愈：下一次 send 重连恢复（resume 失败则回退新会话），不得永久挂起
+        declineSession.proc.stop();
+        for (let i = 0; i < 100 && !declineSession.state.closed; i++) await new Promise(resolve => setTimeout(resolve, 30));
+        assert.equal(declineSession.state.closed, true, '进程死后 closed 必须置位');
+        declineEvents.length = 0;
+        // '流恢复' 分支无权限交互：重连后的新 fixture 进程第一轮即可自动完成
+        await adapter.send(declineSession, '流恢复', null);
+        assert.equal(declineSession.state.closed, false, 'send 自愈后 closed 必须复位');
+        assert.ok(declineEvents.some(event => event.kind === 'completed'), '重连回合必须完成');
+      } finally { await adapter.close(declineSession); }
+    }
+    console.log('zcode adapter: protocol framing, session lifecycle, model catalog, permissions, questions, deltas, tools, usage, attachments, collaboration, decline-to-deny, crash self-heal and cancel PASS');
+  } finally {
+    for (const [key, value] of Object.entries(previous)) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+    fs.rmSync(fixtureBase, { recursive: true, force: true });
+    session?.proc?.stop();
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/scripts/zcode-live-probe.cjs

@@ -0,0 +1,66 @@
+// Live probe against the real ZCode app-server (needs the desktop install and
+// a logged-in shared credential). Verifies: session/send attachments end-to-end
+// (localPath channel), mcp/list contents. Run: node scripts/zcode-live-probe.cjs
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const assert = require('node:assert');
+
+const zcode = require('../src/main/adapters/zcode');
+
+// 64x64 solid red PNG generated via System.Drawing and verified decodable by
+// ZCode's Read tool. Inline "tiny red PNG" snippets circulating in docs have
+// proven undecodable, so this exact payload is the verified one.
+const RED_PNG_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACJSURBVHhe7dAhAQBAEITA7Z/sW/15KoAYg2Rv+2ZjsGkAg00DGGwawGDTAAabBjDYNIDBpgEMNg1gsGkAg00DGGwawGDTAAabBjDYNIDBpgEMNg1gsGkAg00DGGwawGDTAAabBjDYNIDBpgEMNg1gsGkAg00DGGwawGDTAAabBjDYNIDBpgEMNgeiYnGlP5FKrAAAAABJRU5ErkJggg==';
+const redPng = () => Buffer.from(RED_PNG_BASE64, 'base64');
+
+async function ask(adapter, session, events, text, attachments) {
+  events.length = 0;
+  await adapter.send(session, text, null, attachments);
+  return events.filter(e => e.kind === 'text-delta').map(e => e.text).join('');
+}
+
+async function main() {
+  const probeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'zcode-probe-'));
+  const image = path.join(probeDir, 'solid-red.png');
+  fs.writeFileSync(image, redPng());
+  const events = [];
+  const adapter = zcode.create();
+  // Hard watchdog: a wedged turn (e.g. an attachment error path that never
+  // settles) must not hang the probe forever.
+  const watchdog = setTimeout(() => { console.error('PROBE WATCHDOG: 240s budget exceeded'); process.exit(2); }, 240_000);
+  watchdog.unref();
+  const session = await adapter.open({
+    thread: { cwd: probeDir },
+    emit: event => {
+      events.push(event);
+      process.stdout.write(`[event] ${JSON.stringify(event).slice(0, 180)}\n`);
+      // Throwaway probe dir: auto-answer any permission card so the turn settles.
+      if (event.kind === 'approval') adapter.respond(session, event.requestId, { optionId: event.options?.[0]?.id }).catch(() => {});
+    },
+    diagnostic: line => process.stdout.write(`[diag] ${String(line).slice(0, 400)}\n`),
+  });
+  try {
+    console.log('sessionId:', session.state.sessionId);
+
+    try {
+      const mcp = await session.proc.request('mcp/list', { workspace: { workspacePath: probeDir, workspaceKey: probeDir } });
+      console.log('\n=== mcp/list ===\n', JSON.stringify(mcp).slice(0, 1800));
+    } catch (error) {
+      console.log('mcp/list failed:', error.message.slice(0, 300));
+    }
+
+    const answer = await ask(adapter, session, events,
+      '我给你发了一张本地图片文件。只能用 Read 工具查看它（禁止使用 Bash），然后回答：图片是什么颜色？只回答颜色词。',
+      { images: [{ name: 'solid-red.png', mime: 'image/png', data: RED_PNG_BASE64, path: image }] });
+    console.log('\n=== localPath attachment answer ===\n', answer.slice(0, 300));
+    assert.match(answer, /红|red/i, 'model should see the red image via localPath');
+
+    console.log('\nLIVE PROBE PASS');
+  } finally {
+    await adapter.close(session).catch(() => {});
+    setTimeout(() => { try { fs.rmSync(probeDir, { recursive: true, force: true }); } catch { /* windows eperm racing the just-killed child */ } }, 1500);
+  }
+}
+
+main().catch(error => { console.error('PROBE FAILED:', error); process.exit(1); });