harness-mix 0.1.0

package/src/main/adapters/pi-family.js

@@ -0,0 +1,315 @@
+const { execFile } = require("node:child_process");
+const os = require("node:os");
+const path = require('node:path');
+const { JsonlProcess, cliSpawn } = require("../host/jsonl");
+const { sessionUsage, latestUsage } = require('./pi-usage');
+const { recordNative } = require('../harness-adapter/fixture-recorder');
+
+function toolText(content) {
+  const text = Array.isArray(content) ? content.filter(b => b.type === 'text').map(b => b.text).join('\n') : String(content ?? '');
+  return text.length > 24000 ? text.slice(0, 24000) + '\n[桌面预览已截断]' : text;
+}
+
+function firstLine(value) {
+  if (value == null) return "";
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  return text.split("\n").find((line) => line.trim())?.slice(0, 120) ?? "";
+}
+
+function summarizeContent(content) {
+  if (!Array.isArray(content)) return firstLine(content);
+  const text = content.find((block) => block.type === "text")?.text;
+  return firstLine(text ?? "");
+}
+
+function sanitizeName(title) {
+  return String(title || "").replace(/["&|<>^%]/g, "").trim().slice(0, 40) || "Harness Mix 任务";
+}
+
+/** 工具结果里的图片块 → 统一 artifact 事件（各 Harness 返回产物在桌面层对齐呈现；超大图片不入会话存档） */
+function imageArtifacts(content, toolCallId) {
+  if (!Array.isArray(content)) return [];
+  const out = [];
+  content.forEach((block, i) => {
+    if (block?.type !== "image" || typeof block.data !== "string" || !block.data) return;
+    if (block.data.length > 5_000_000) return;
+    out.push({ kind: "artifact", artifact: { id: `${toolCallId ?? "pi"}-img-${i}`, type: "image", name: block.name || "图片", mime: block.mimeType || "image/png", data: block.data } });
+  });
+  return out;
+}
+
+/** project() 可能返回数组（工具结果同时有摘要与图片产物），统一展开投影 */
+function emitAll(emitEvent, mapped) {
+  for (const item of Array.isArray(mapped) ? mapped : [mapped]) if (item) emitEvent(item);
+}
+
+/** Pi 家族（Pi / Oh My Pi）的权限模型 = 项目信任（project trust）：启动时用 --approve / --no-approve 覆盖一次 */
+const PI_PERMISSION_MODES = [
+  { id: "default", label: "默认", hint: "按全局设置处理项目级设置与扩展（defaultProjectTrust）" },
+  { id: "approve", label: "信任项目", hint: "本次信任该项目的设置与扩展（--approve）" },
+  { id: "no-approve", label: "忽略项目资源", hint: "本次不加载项目级设置与扩展（--no-approve）" },
+];
+
+/**
+ * Pi 家族 Adapter 工厂：Pi 与 Oh My Pi（OMP，Pi 的 fork）共用 --mode rpc 协议。
+ * 会话/模型/工具/权限都由原生程序维护，这里只做事件投影。
+ * @param {{ id: string, name: string, icon: string, bin: string, packageHint: string, aliases?: string[] }} options
+ */
+function piFamily({ id, name, icon, bin, packageHint, aliases }) {
+  const manifest = {
+    id,
+    name,
+    icon,
+    aliases: aliases ?? [id],
+    capabilities: { collaborationTools: true, streaming: true, thinking: true, tools: true, approvals: true, questions: true, models: true, thinkingLevels: true, permissionModes: true, resume: true, fork: true, forkFromMessage: true, compaction: true, usage: true, contextUsage: true, attachments: true },
+  };
+
+  function forwardEvent(process, event, emit) {
+    recordNative(manifest.id, event);
+    if (event.type !== 'agent_settled') { emitAll(emit, project(event)); return; }
+    // Capture the native leaf before exposing completion; later forks use this boundary.
+    void process.command({ type: 'get_entries' }).then(data => {
+      emit({ ...project(event), nativeRef: { sessionId: event.sessionId, checkpointId: data.leafId } });
+    }, () => emitAll(emit, project(event)));
+  }
+
+  function spawnProcess(args, cwd, hooks, collaboration) {
+    if (collaboration) args.push('--extension', path.join(__dirname, '../host/collaboration-pi.mjs'));
+    const { command, args: cliArgs } = cliSpawn(bin, ["--mode", "rpc", ...args]);
+    return new JsonlProcess(command, cliArgs, { cwd, ...(collaboration ? { env: { ...process.env, ...collaboration.env } } : {}) }, hooks);
+  }
+
+  function create(emit) {
+    return {
+      manifest,
+
+      async inspect() {
+        const result = await new Promise((resolve) => {
+          const { command, args } = cliSpawn(bin, ["--version"]);
+          execFile(command, args, { windowsHide: true }, (error, stdout) => resolve({ ok: !error, stdout }));
+        });
+        return result.ok
+          ? { available: true, detail: `${bin} ${String(result.stdout).trim()}` }
+          : { available: false, detail: `未找到 ${bin} CLI（${packageHint}）` };
+      },
+
+      async open({ thread, emit: emitEvent, diagnostic, collaboration }) {
+        const args = thread.restore && thread.nativeSessionFile
+          ? ['--session', thread.nativeSessionFile]
+          : ["--session-id", thread.nativeSessionId, "--name", sanitizeName(thread.title)];
+        if (thread.options?.permissionMode === "approve") args.push("--approve");
+        if (thread.options?.permissionMode === "no-approve") args.push("--no-approve");
+        const process = spawnProcess(args, thread.cwd, {
+          onEvent: event => forwardEvent(process, event, emitEvent),
+          onDiagnostic: (message) => diagnostic(message),
+        }, collaboration);
+        const state = await process.command({ type: "get_state" });
+        let model = state?.model ? { id: state.model.id, name: state.model.name, provider: state.model.provider } : undefined;
+        // 应用草稿期选择的模型与思考档位（仍由原生程序执行切换）
+        if (thread.options?.model?.provider) {
+          model = await process.command({ type: "set_model", provider: thread.options.model.provider, modelId: thread.options.model.id })
+            .then((m) => ({ id: m.id ?? thread.options.model.id, name: m.name ?? thread.options.model.name, provider: m.provider ?? thread.options.model.provider }))
+            .catch(() => model);
+        }
+        if (thread.options?.thinking) await process.command({ type: "set_thinking_level", level: thread.options.thinking }).catch(() => {});
+        return {
+          process,
+          collaborationEnabled: !!collaboration,
+          nativeSessionId: state?.sessionId ?? thread.nativeSessionId,
+          nativeSessionFile: state?.sessionFile,
+          model,
+        };
+      },
+
+      async send(session, text, _hooks, attachments) {
+        // 图片走 RPC 原生 images 字段（base64）；文本附件由 Host 内联进 text
+        const images = (attachments?.images ?? []).map((a) => ({ type: 'image', data: a.data, mimeType: a.mime }));
+        await session.process.command({ type: "prompt", message: text, ...(images.length ? { images } : {}) });
+      },
+
+      async cancel(session) {
+        await session.process.command({ type: "abort" });
+      },
+
+      async listCommands(session) {
+        const data = session ? await session.process.command({ type: 'get_commands' }) : null;
+        return [{ id: 'compact', label: '压缩上下文', description: `由 ${name} 原生总结并压缩当前会话`, action: 'execute' },
+          ...(data?.commands ?? []).filter(c => c.name !== 'compact').map(c => ({ id: c.name, label: '/' + c.name, description: c.description, action: 'insert', text: '/' + c.name + ' ' }))];
+      },
+      async executeCommand(session, commandId, { emit }) {
+        if (commandId !== 'compact') throw new Error(`未知 ${name} 指令`);
+        await session.process.command({ type: 'compact' });
+        emit({ kind: 'text-delta', text: `上下文已由 ${name} 压缩。` });
+        emit({ kind: 'completed', finalAnswer: true });
+      },
+
+      async listModels() {
+        // 需要进程内目录，由 runtime 在 open 后调用 listModels(session)
+        return null;
+      },
+
+      async listModelsFor(session) {
+        const data = await session.process.command({ type: "get_available_models" });
+        const models = Array.isArray(data?.models) ? data.models : [];
+        return models.map((m) => ({ id: m.id, name: m.name || m.id, provider: m.provider }));
+      },
+
+      async setModel(session, model) {
+        const data = await session.process.command({ type: "set_model", provider: model.provider, modelId: model.id });
+        return data ? { id: data.id ?? model.id, name: data.name ?? model.name, provider: data.provider ?? model.provider } : model;
+      },
+
+      /** 审批/提问应答：extension_ui_response 子协议 */
+      async respond(session, _requestId, response) {
+        const payload = { type: "extension_ui_response", id: _requestId };
+        if (response.cancelled) payload.cancelled = true;
+        else if (response.confirmed !== undefined) payload.confirmed = response.confirmed;
+        else payload.value = response.optionId ?? response.value ?? "";
+        session.process.send(payload);
+      },
+
+      async setThinkingLevel(session, level) {
+        await session.process.command({ type: "set_thinking_level", level });
+      },
+
+      /** 上下文窗口占用：原生统计（与压缩/页脚同源） */
+      async getContextUsage(session) {
+        const data = await session.process.command({ type: "get_session_stats" });
+        return sessionUsage(data);
+      },
+
+      /** 目录探测：临时起一个无会话 RPC 进程，拿模型目录与思考档位后即销毁（带缓存由 runtime 负责） */
+      async describe() {
+        const process = spawnProcess(["--no-session"], os.tmpdir(), {});
+        try {
+          const modelsData = await process.command({ type: "get_available_models" });
+          const levelsData = await process.command({ type: "get_available_thinking_levels" }).catch(() => null);
+          return {
+            models: (modelsData?.models ?? []).map((m) => ({ id: m.id, name: m.name || m.id, provider: m.provider, contextWindow: m.contextWindow })),
+            thinkingLevels: (levelsData?.levels ?? []).map((l) => ({ id: l, label: l })),
+            permissionModes: PI_PERMISSION_MODES,
+          };
+        } finally {
+          process.stop();
+        }
+      },
+
+      async describeFor(session) {
+        const [models, levels] = await Promise.all([
+          this.listModelsFor(session),
+          session.process.command({ type: 'get_available_thinking_levels' }),
+        ]);
+        return { models, thinkingLevels: (levels?.levels ?? []).map(id => ({ id, label: id })), permissionModes: PI_PERMISSION_MODES };
+      },
+
+      /** 任务级 Fork：另起进程，用 CLI --fork 从源会话分叉出全新原生会话 */
+      async fork(sourceThread, { emit: emitEvent, diagnostic, message }) {
+        const process = spawnProcess(["--fork", sourceThread.nativeSessionId, "--name", `${sanitizeName(sourceThread.title)} · Fork`], sourceThread.cwd, {
+          onEvent: event => forwardEvent(process, event, emitEvent),
+          onDiagnostic: (message) => diagnostic(message),
+        });
+        try {
+          if (message) {
+            const data = await process.command({ type: 'get_entries' });
+            const entries = new Map(data.entries.map(entry => [entry.id, entry]));
+            const branch = [];
+            for (let entry = entries.get(data.leafId); entry; entry = entries.get(entry.parentId)) branch.unshift(entry);
+            let checkpoint = message.coreTurn?.nativeTurnRef?.checkpointId;
+            if (!checkpoint) {
+              const final = message.coreItems?.filter(item => item.phase === 'final').map(item => item.content).join('') || message.text;
+              const matches = branch.filter(entry => entry.type === 'message' && entry.message.role === 'assistant'
+                && entry.message.content?.filter(block => block.type === 'text').map(block => block.text).join('') === final);
+              if (matches.length !== 1) throw new Error('这条旧回复缺少可唯一定位的原生记录，请从最新回复分支。');
+              checkpoint = matches[0].id;
+            }
+            const index = branch.findIndex(entry => entry.id === checkpoint);
+            if (index < 0) throw new Error('该回复不在当前原生会话分支中');
+            const nextUser = branch.slice(index + 1).find(entry => entry.type === 'message' && entry.message.role === 'user');
+            if (nextUser) {
+              const result = await process.command({ type: 'fork', entryId: nextUser.id });
+              if (result?.cancelled) throw new Error('原生 Harness 取消了分支操作');
+            }
+          }
+          const state = await process.command({ type: 'get_state' });
+          if (!state?.sessionId || state.sessionId === sourceThread.nativeSessionId) throw new Error(`${name} 未返回新的 Fork 会话`);
+          return { session: { process, nativeSessionId: state.sessionId, nativeSessionFile: state.sessionFile, model: state.model } };
+        } catch (error) { process.stop(); throw error; }
+      },
+
+      async close(session) {
+        session.process.stop();
+      },
+    };
+  }
+
+  /** 原生事件 → 统一事件投影（事件转换层） */
+  function project(event) {
+    const mapped = projectEvent(event);
+    const nativeRef = {
+      sessionId: event.sessionId,
+      itemId: event.message?.id,
+      toolCallId: event.toolCallId,
+      ...(event.type === 'extension_ui_request' ? { interactionId: String(event.id) } : {}),
+    };
+    const enrich = value => value ? { ...value, nativeRef } : value;
+    return Array.isArray(mapped) ? mapped.map(enrich) : enrich(mapped);
+  }
+
+  function projectEvent(event) {
+    switch (event.type) {
+      case 'message_end':
+        return latestUsage(event.message);
+      case "message_update": {
+        const delta = event.assistantMessageEvent || {};
+        if (delta.type === "text_delta" && delta.delta) return { kind: "text-delta", text: delta.delta };
+        if (delta.type === "thinking_delta" && delta.delta) return { kind: "thinking-delta", text: delta.delta };
+        return null;
+      }
+      case "tool_execution_start":
+        return { kind: "tool", toolCallId: event.toolCallId, title: event.toolName || "工具", state: "running", detail: firstLine(event.args ? Object.values(event.args)[0] : ""), input: toolText(event.args?.command ?? JSON.stringify(event.args ?? {}, null, 2)) };
+      case "tool_execution_update":
+        return { kind: "tool", toolCallId: event.toolCallId, title: event.toolName || "工具", state: "running", detail: summarizeContent(event.partialResult?.content), output: toolText(event.partialResult?.content) };
+      case "tool_execution_end":
+        return [
+          { kind: "tool", toolCallId: event.toolCallId, title: event.toolName || "工具", state: event.isError ? "error" : "done", detail: summarizeContent(event.result?.content), output: toolText(event.result?.content) },
+          ...imageArtifacts(event.result?.content, event.toolCallId),
+        ];
+      case "extension_ui_request": {
+        if (event.method === "notify") return { kind: "notice", level: event.notifyType || "info", text: event.message || event.title || "通知" };
+        if (event.method === "setStatus") return event.statusText ? { kind: "status", text: event.statusText } : null;
+        if (["select", "confirm", "input", "editor"].includes(event.method)) {
+          return {
+            kind: "approval",
+            requestId: event.id,
+            method: event.method,
+            title: event.title || "Harness 请求确认",
+            message: event.message,
+            placeholder: event.placeholder ?? event.prefill,
+            options: Array.isArray(event.options) ? event.options.map((o) => ({ id: String(o), label: String(o) })) : undefined,
+          };
+        }
+        return null;
+      }
+      case "agent_settled":
+        return { kind: "completed", finalAnswer: true };
+      case "agent_end":
+        return event.willRetry ? { kind: "status", text: "请求失败，自动重试中…" } : null;
+      case "auto_retry_start":
+        return { kind: "status", text: `自动重试（${event.attempt}/${event.maxAttempts}）…` };
+      case "auto_retry_end":
+        return event.success ? { kind: "status", text: "重试成功" } : { kind: "error", message: `自动重试失败：${event.finalError || "未知错误"}` };
+      case "compaction_start":
+        return { kind: "status", text: "上下文压缩中…" };
+      case "compaction_end":
+        return event.result ? { kind: "status", text: `压缩完成（${event.result.tokensBefore} → ${event.result.estimatedTokensAfter} tokens）` } : null;
+      case "extension_error":
+        return { kind: "notice", level: "error", text: `扩展错误：${event.error}` };
+      default:
+        return null;
+    }
+  }
+
+  return { manifest, create, project };
+}
+
+module.exports = { piFamily, PI_PERMISSION_MODES };

package/src/main/adapters/pi-usage.js

@@ -0,0 +1,24 @@
+const valid = n => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+const clean = obj => Object.fromEntries(Object.entries(obj).filter(([, v]) => valid(v)));
+
+// Same native accounting as codex-host/pi-usage: cache tokens are separate
+// from uncached input. Session totals and latest-request cache rate must not mix.
+function sessionUsage(data = {}) {
+  const t = data.tokens ?? {}, c = data.contextUsage ?? {};
+  return { ...clean({ input: t.input, output: t.output, cacheRead: t.cacheRead,
+    cacheWrite: t.cacheWrite, totalTokens: t.total, cost: data.cost,
+  }), tokens: valid(c.tokens) ? c.tokens : null,
+    contextWindow: valid(c.contextWindow) && c.contextWindow > 0 ? c.contextWindow : null,
+    contextPercent: valid(c.tokens) && valid(c.contextWindow) && c.contextWindow > 0
+      ? 100 * c.tokens / c.contextWindow : null };
+}
+
+function latestUsage(message) {
+  if (message?.role !== 'assistant' || !message.usage) return null;
+  const { input, cacheRead, cacheWrite } = message.usage;
+  const total = input + cacheRead + cacheWrite;
+  return { kind: 'usage', usage: { cacheHitPercent:
+    [input, cacheRead, cacheWrite].every(valid) && total > 0 ? 100 * cacheRead / total : null } };
+}
+
+module.exports = { sessionUsage, latestUsage };

package/src/main/adapters/pi.js

@@ -0,0 +1,10 @@
+// Pi Adapter：pi.cmd --mode rpc。实现共享自 Pi 家族工厂（见 pi-family.js）。
+const { piFamily } = require('./pi-family');
+
+module.exports = piFamily({
+  id: 'pi',
+  name: 'Pi',
+  icon: 'pinumber1_80899.svg',
+  bin: 'pi',
+  packageHint: 'npm i -g @earendil-works/pi-coding-agent',
+});

package/src/main/adapters/qoder.js

@@ -0,0 +1,35 @@
+// Qoder Agent Adapter：阿里 Qoder CLI（通过 ACP 协议或 stdio 桥接）。
+// 共享 ACP 家族工厂（见 acp.js）。
+const { execFile } = require('node:child_process');
+const { cliSpawn } = require('../host/jsonl');
+const { acpAdapter } = require('./acp');
+
+module.exports = acpAdapter({
+  id: 'qoder',
+  name: 'Qoder',
+  bin: process.env.HARNESS_MIX_QODER_EXECUTABLE || 'qodercli',
+  args: ['--acp'],
+  executable: false,
+  images: false,
+  fork: false,
+  thinking: true,
+  permissions: true,
+  questions: true,
+  compaction: false,
+  usage: true,
+  contextUsage: false,
+  async inspectCustom() {
+    const cli = cliSpawn(process.env.HARNESS_MIX_QODER_EXECUTABLE || 'qodercli', ['--version']);
+    return new Promise(resolve => {
+      execFile(cli.command, cli.args, { windowsHide: true, timeout: 5000 }, (err, stdout) => {
+        if (err) {
+          return resolve({
+            available: false,
+            detail: '未找到 Qoder CLI（请运行 npm i -g @qoder-ai/qodercli 并登录）',
+          });
+        }
+        resolve({ available: true, detail: `qodercli ${String(stdout || '').trim()}` });
+      });
+    });
+  },
+});

package/src/main/adapters/trae.js

@@ -0,0 +1,19 @@
+// Trae Agent Adapter：字节跳动 Trae CLI / Agent（通过 ACP 协议或 stdio 桥接）。
+// 共享 ACP 家族工厂（见 acp.js）。
+const { acpAdapter } = require('./acp');
+
+module.exports = acpAdapter({
+  id: 'trae',
+  name: 'Trae',
+  bin: process.env.HARNESS_MIX_TRAE_EXECUTABLE || 'traecli',
+  args: ['acp', 'serve'],
+  executable: false,
+  images: false,
+  fork: false,
+  thinking: true,
+  permissions: true,
+  questions: true,
+  compaction: false,
+  usage: true,
+  contextUsage: false,
+});

package/src/main/adapters/workbuddy.js

@@ -0,0 +1,67 @@
+// Workbuddy Agent Adapter：腾讯 Workbuddy / CodeBuddy CLI（通过 ACP 协议或 stdio 桥接）。
+// 共享 ACP 家族工厂（见 acp.js）。
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const { cliSpawn } = require('../host/jsonl');
+const { acpAdapter } = require('./acp');
+
+function findWorkbuddyCli() {
+  if (process.env.HARNESS_MIX_WORKBUDDY_EXECUTABLE) {
+    return { type: 'exe', path: process.env.HARNESS_MIX_WORKBUDDY_EXECUTABLE };
+  }
+  const candidates = [
+    'C:\\Program Files\\WorkBuddy\\resources\\app.asar.unpacked\\cli\\bin\\codebuddy',
+    path.join(process.env.LOCALAPPDATA || '', 'Programs', 'WorkBuddy', 'resources', 'app.asar.unpacked', 'cli', 'bin', 'codebuddy'),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return { type: 'script', path: candidate };
+    }
+  }
+  return null;
+}
+
+module.exports = acpAdapter({
+  id: 'workbuddy',
+  name: 'Workbuddy',
+  bin: 'codebuddy',
+  args: ['--acp'],
+  executable: false,
+  images: false,
+  fork: false,
+  thinking: true,
+  permissions: true,
+  questions: true,
+  compaction: false,
+  usage: true,
+  contextUsage: false,
+  resolveCommand(argv) {
+    const found = findWorkbuddyCli();
+    if (found?.type === 'script') {
+      return { command: process.execPath, args: [found.path, ...argv] };
+    }
+    if (found?.type === 'exe') {
+      return { command: found.path, args: argv };
+    }
+    return null;
+  },
+  async inspectCustom() {
+    const found = findWorkbuddyCli();
+    if (found?.type === 'script') {
+      return new Promise(resolve => {
+        execFile(process.execPath, [found.path, '--version'], { windowsHide: true, timeout: 5000 }, (err, stdout) => {
+          if (err) return resolve({ available: false, detail: 'WorkBuddy CLI 启动失败' });
+          resolve({ available: true, detail: `codebuddy ${stdout.trim()} · WorkBuddy 桌面版内置` });
+        });
+      });
+    }
+    const cli = cliSpawn('codebuddy', ['--version']);
+    return new Promise(resolve => {
+      execFile(cli.command, cli.args, { windowsHide: true, timeout: 5000 }, (err, stdout) => {
+        if (err) return resolve({ available: false, detail: '未找到 WorkBuddy / CodeBuddy CLI（未在 PATH 或默认目录）' });
+        resolve({ available: true, detail: `codebuddy ${stdout.trim()}` });
+      });
+    });
+  },
+});

package/src/main/adapters/zcode.js

@@ -0,0 +1,38 @@
+// ZCode Agent Adapter：智谱 AI ZCode CLI。
+// 共享 ACP 家族工厂（见 acp.js）。
+const fs = require('node:fs');
+const { execFile } = require('node:child_process');
+const { cliSpawn } = require('../host/jsonl');
+const { acpAdapter } = require('./acp');
+
+module.exports = acpAdapter({
+  id: 'zcode',
+  name: 'ZCode',
+  bin: process.env.HARNESS_MIX_ZCODE_EXECUTABLE || 'zcode',
+  args: ['acp'],
+  executable: false,
+  images: false,
+  fork: false,
+  thinking: true,
+  permissions: true,
+  questions: true,
+  compaction: false,
+  usage: true,
+  contextUsage: false,
+  async inspectCustom() {
+    const desktopPath = 'C:\\Program Files\\ZCode';
+    const hasDesktop = fs.existsSync(desktopPath);
+    const cli = cliSpawn('zcode', ['--version']);
+    return new Promise(resolve => {
+      execFile(cli.command, cli.args, { windowsHide: true, timeout: 5000 }, (err, stdout) => {
+        if (err) {
+          const hint = hasDesktop
+            ? '检测到 ZCode 桌面版，但其核心引擎为 ZCode V4 Protocol (app-server) 而非 ACP 协议，需专用协议适配器'
+            : '未找到 ZCode CLI';
+          return resolve({ available: false, detail: hint });
+        }
+        resolve({ available: true, detail: `zcode ${String(stdout || '').trim()}` });
+      });
+    });
+  },
+});

package/src/main/harness-adapter/contract-test.js

@@ -0,0 +1,53 @@
+const { validateAdapterContract } = require('./contract');
+const { validateManifest, normalizeCapabilities } = require('./manifest');
+const { validateCapabilities } = require('../shared-contracts');
+
+// Adapter Contract Tests（§23）：每个 Adapter 执行同一组测试。
+// 本组为结构性测试（不启动原生进程）；声明了能力后的行为验证由 e2e:* 承担。
+function runAdapterContractTests(adapter, test) {
+  const label = adapter?.manifest?.id ?? 'unknown';
+
+  test(`[${label}] manifest 合法（id/name/capabilities）`, () => {
+    const errors = validateManifest(adapter.manifest);
+    if (errors.length) throw new Error(errors.join('; '));
+  });
+
+  test(`[${label}] 归一化能力通过 shared-contracts 校验`, () => {
+    const normalized = normalizeCapabilities(adapter.manifest?.capabilities);
+    const errors = validateCapabilities(normalized);
+    if (errors.length) throw new Error(errors.join('; '));
+  });
+
+  test(`[${label}] 契约方法齐备（能力声明 ⇒ 方法存在）`, () => {
+    const errors = validateAdapterContract(adapter);
+    if (errors.length) throw new Error(errors.join('; '));
+  });
+
+  test(`[${label}] 会话生命周期方法签名（open/send/cancel/close）`, () => {
+    for (const name of ['open', 'send', 'cancel', 'close']) {
+      if (typeof adapter[name] !== 'function') throw new Error(`missing ${name}()`);
+    }
+  });
+
+  const caps = adapter.manifest?.capabilities ?? {};
+  if (caps.resume === true) {
+    test(`[${label}] 声明了 session.resume ⇒ open() 接受 restore 线程`, () => {
+      // 结构性验证：open 为函数且 runtime 以 thread.restore 驱动原生恢复路径；
+      // 真实恢复行为由 e2e 验证，这里保证入口存在且幂等可调用。
+      if (typeof adapter.open !== 'function') throw new Error('missing open()');
+    });
+  }
+  if (caps.fork === true) {
+    test(`[${label}] 声明了 session.fork ⇒ fork() 存在`, () => {
+      if (typeof adapter.fork !== 'function') throw new Error('missing fork()');
+    });
+  }
+  if (caps.approvals !== true) {
+    test(`[${label}] 未声明 approval ⇒ 不要求 respond 实现审批语义`, () => {
+      // 显式记录反向约束：能力未声明时契约不强制（§23）
+      if (!adapter.manifest) throw new Error('unreachable');
+    });
+  }
+}
+
+module.exports = { runAdapterContractTests };

package/src/main/harness-adapter/contract.js

@@ -0,0 +1,34 @@
+// 统一 Harness Adapter 契约（§20/§21）。
+// 方法是否必须存在由 Manifest capability 声明决定（§21：不是每个能力都必须存在）。
+// 命名沿用现行 Adapter 形状：open 同时承担 createSession / resumeSession
+// （thread.restore 决定路径），respond 即 respondInteraction。
+const CONTRACT_METHODS = [
+  { name: 'inspect', when: () => true },
+  { name: 'open', when: () => true },        // createSession / resumeSession
+  { name: 'send', when: () => true },
+  { name: 'cancel', when: () => true },
+  { name: 'close', when: () => true },
+  { name: 'respond', when: (c) => c.approvals === true || c.questions === true }, // respondInteraction
+  { name: 'fork', when: (c) => c.fork === true },
+  { name: 'listCommands', when: (c) => c.compaction === true },
+  { name: 'executeCommand', when: (c) => c.compaction === true },
+  { name: 'listModelsFor', when: (c) => c.models === true }, // listModels(session)：open 后按会话取目录
+  { name: 'setModel', when: (c) => c.models === true },
+  { name: 'setThinkingLevel', when: (c) => c.thinkingLevels === true },
+];
+
+/** 结构性契约校验：方法存在性与能力声明一致（行为验证由真实 Harness E2E 承担） */
+function validateAdapterContract(adapter) {
+  const errors = [];
+  if (!adapter || typeof adapter !== 'object') return ['adapter must be an object'];
+  const caps = adapter.manifest?.capabilities ?? {};
+  for (const { name, when } of CONTRACT_METHODS) {
+    const required = when(caps);
+    const present = typeof adapter[name] === 'function';
+    if (required && !present) errors.push(`adapter missing required method: ${name}()`);
+    // 未声明能力却提供实现不算错误（允许超前实现），但不允许声明了却没有实现
+  }
+  return errors;
+}
+
+module.exports = { CONTRACT_METHODS, validateAdapterContract };