harness-mix 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.1 — 2026-09-12
+
+- Added native ACP adapters for CodeBuddy, Kiro CLI, Cursor CLI and Qoder.
+- Added explicit ACP bridge configuration for ZCode and Trae without claiming an unverified vendor entry point.
+- Renamed WorkBuddy to CodeBuddy while preserving legacy task, history and preference identifiers.
+- Added image capability negotiation, bounded ACP event draining, idle/hard turn timeouts, cancellation fallback and stuck-tool diagnostics.
+- Added durable multi-agent recovery checkpoints and verified DSH → CodeBuddy collaboration.
+- Updated the README and native integration documentation with installation, verification and capability limits.

package/README.md

@@ -12,7 +12,7 @@
   <img alt="Platform" src="https://img.shields.io/badge/platform-Windows-0078D4.svg">
 </p>
 
-Harness Mix 是接入官方 Codex Desktop 原生界面的本地内核：通过本地编译的 CLI Shim 接管桌面的 app-server 协议，把 Pi、Claude Code、DeepSeek Harness、Antigravity 和 Codex 统一进同一套原生 UI。会话生命周期、模型调用、多轮对话、审批与文件差异全部由本仓库的 Host Runtime + Protocol Core + 原生适配器管理；凭据与权限决定仍属于各原生 Harness。
+Harness Mix 是接入官方 Codex Desktop 原生界面的本地内核。它通过本地编译的 CLI Shim 对接桌面的 app-server 协议，把 Codex、Pi、Claude Code、DeepSeek Harness、CodeBuddy、Kiro CLI、Cursor CLI 等原生 Coding Harness 接入同一套 UI。Host Runtime 与 Protocol Core 管理任务映射、协作和事件投影；模型调用、工具执行、原生会话与凭据仍由各 Harness 自己管理。
 
 ![Harness Mix 首页](docs/images/harness-mix-home.png)
 
@@ -22,7 +22,8 @@ Harness Mix 是接入官方 Codex Desktop 原生界面的本地内核：通过
 - 流式呈现回答、思考、命令执行、工具调用、文件变更和上下文压缩。
 - 调用每个 Harness 原生提供的模型、权限、上下文用量和快捷指令。
 - 会话中原地切换 Harness（`/switch <Harness 名> [备注]` 或 `codexhost/thread/harness/switch`）：会话历史与文件现场保留在 Host 线程上，切换后首轮自动携带一次性上下文信封；切回旧 Harness 时按其原生机制（Pi `--session` / Claude `resume`）恢复原会话。
-- 原生 Diff、审批与提问组件直接渲染，审批路由回原生 Harness，不代替用户作出权限决定。
+- 原生 Diff、审批与提问组件直接渲染，审批路由回原生 Harness，不代替用户作出权限决定。
+- CodeBuddy、Kiro 和 Cursor 使用原生 ACP 加厂商专用接口：提问、计划确认、配置确认、取消恢复、上下文与历史按各自协议处理。功能和验证范围见下表，不将通用 ACP 能力视为所有 CLI 都已支持。
 - 通过 Adapter 注册新 Harness，UI 侧无需理解厂商协议。
 
 ![Harness Mix 会话](docs/images/harness-mix-session.png)
@@ -38,16 +39,22 @@ Harness Mix 是接入官方 Codex Desktop 原生界面的本地内核：通过
 | Pi | `pi --mode rpc` | 会话恢复、模型目录、Usage、原生命令、Fork |
 | Oh My Pi | `omp --mode rpc`（Pi 家族协议，见 `pi-family.js`） | 与 Pi 同源：会话、模型、思考档位、权限、Fork、Usage |
 | Claude Code | `@anthropic-ai/claude-agent-sdk` 的 `query()` | 持久会话、流式消息、工具、权限、模型与 Resume |
-| DeepSeek Harness | `npm run dsh -- web` | Web Remote、Typert RPC、WebSocket 事件、会话与模型控制 |
+| DeepSeek Harness | 普通任务 `npm run dsh -- web`；协作主任务 `npm run dsh -- --profile acp` | Web Remote/Typert RPC；主任务使用官方 ACP 的会话级 MCP；WebSocket 事件、会话与模型控制 |
 | OpenCode | `opencode serve`（原生 HTTP / SSE，见 `opencode.js`） | 会话、模型目录、权限模式、图片、Fork |
 | Grok | `grok agent stdio`（独立适配 ACP 基础消息与 `_x.ai/*` 厂商扩展，见 `grok.js`） | 会话、模型、思考档位、原生命令目录、Token Usage、原生 Fork |
 | OpenClaw | 本机 Gateway loopback WebSocket（`openclaw-gateway.js` + `openclaw.js`） | 会话与恢复、流式增量、工具与命令输出、exec/plugin 审批回路由、模型与思考档位逐轮覆盖 |
 | Hermes | `hermes acp`（ACP over stdio，共享 `acp.js` 工厂） | 会话持久化/恢复/Fork、流式回答与思考、工具、审批、模型选择 |
-| Qoder | `qoder acp`（阿里 Qoder CLI，共享 `acp.js` 工厂） | 会话、流式回答与思考、工具、审批、模型选择 |
-| Workbuddy | `codebuddy acp`（腾讯 Workbuddy / CodeBuddy CLI，共享 `acp.js` 工厂） | 会话、流式回答与思考、工具、审批、模型选择 |
-| ZCode | `zcode acp`（智谱 AI ZCode CLI，共享 `acp.js` 工厂） | 会话、流式回答与思考、工具、审批、GLM 模型识别 |
-| Trae | `traecli acp serve`（字节跳动 Trae CLI Agent，共享 `acp.js` 工厂） | 会话、流式回答与思考、工具、审批、模型选择 |
-
+| Qoder | `qodercli --acp` / `qoder --acp`（官方 CLI，`native-acp.js`） | 原生会话、配置、审批、工具、恢复；图片按握手能力启用 |
+| CodeBuddy | `codebuddy --acp` + `_codebuddy.ai/*` | 原生提问与提交重试、审批作用范围、取消后重连恢复、模型/思考/模式、原生历史导入、去重 Token/Credits |
+| Kiro CLI | `kiro-cli acp --agent-engine v3 --auth-method cli` + `_kiro/*` | 原生提问、带作用范围的 consent、模型/effort、上下文查询、原生压缩与 fork（后两项需握手支持） |
+| Cursor CLI | `cursor-agent acp` + `cursor/*` | 单选/多选提问、计划接受/拒绝、原生模型变体/模式、会话恢复、完成后的 Diff 投影 |
+| ZCode | 需显式配置兼容 ACP 桥接程序（尚未验证） | 本机 0.16.5 仅确认 `app-server --stdio`；不能直接作为 ACP 启动 |
+| Trae | 需显式配置兼容 ACP 程序（尚未验证） | 官方 trae-agent 未发现 ACP 入口；不再使用猜测的启动/安装命令 |
+
+CodeBuddy、Kiro CLI、Cursor CLI、Qoder、ZCode 和 Trae 均已接入默认选择器、模型偏好、侧栏图标与共享 ACP 引擎；其中只有已安装且握手成功的 Harness 才会进入真实运行。原 Workbuddy 已更名为 CodeBuddy；旧任务、切换历史、模型偏好与名称别名保留兼容。DSH 协作主任务也使用官方 ACP，普通任务继续使用 Web Remote。
+
+2026-09-12 健康检查：Pi、DSH、Claude Code、Codex、Grok、CodeBuddy 的真实文本回路通过；OpenCode 被账户余额阻断，Qoder 被 Credits 额度阻断，OMP、Hermes、Kiro、Cursor 本机未安装。图片真实回路通过 Antigravity、Pi、Claude Code、Codex、Grok、CodeBuddy；DSH 与 OpenClaw 的当前模型拒绝图片，Qoder/OpenCode 分别被额度/余额阻断。ZCode、Trae 目前只有显式 ACP 桥接配置入口，未证明官方 CLI 提供 ACP 服务。报告见 [`output/harness-health/1789191914230/report.json`](output/harness-health/1789191914230/report.json) 和 [`output/harness-health/1789191791797/report.json`](output/harness-health/1789191791797/report.json)；完整安装与边界见 [原生 ACP 深度适配](docs/native-acp.md)。
+
 能力只在 Adapter 的 `manifest` 中声明。界面根据真实能力显示入口，不靠 Harness 名称猜测功能；厂商特有字段会保留在原生引用和载荷中。
 
 ## 架构
@@ -71,9 +78,11 @@ flowchart TB
   Registry --> OpenClaw[OpenClaw Gateway loopback WS]
   Registry --> Hermes[Hermes ACP stdio]
   Registry --> Qoder[Qoder ACP stdio]
-  Registry --> Workbuddy[Workbuddy ACP stdio]
-  Registry --> ZCode[ZCode ACP stdio]
-  Registry --> Trae[Trae ACP stdio]
+  Registry --> CodeBuddy[CodeBuddy ACP + native extensions]
+  Registry --> Kiro[Kiro ACP + native extensions]
+  Registry --> Cursor[Cursor ACP + native extensions]
+  Registry --> ZCode[ZCode 显式 ACP 桥接入口 未验证]
+  Registry --> Trae[Trae 显式 ACP 入口 未验证]
 ```
 
 ```text
@@ -117,15 +126,32 @@ module.exports = {
 };
 ```
 
-## 本地运行
-
-开发环境需要 Windows、近期 Node.js LTS 和 npm。应用不会读取或保存 Harness 的账户密钥，请先在对应的原生 CLI 中完成安装与登录。
+## 本地运行
+
+开发环境需要 Windows、近期 Node.js LTS 和 npm。应用不会读取或保存 Harness 的账户密钥，请先在对应的原生 CLI 中完成安装与登录。
 
 ```powershell
 git clone https://github.com/emo-xiaoyu/harness-mix.git
 cd harness-mix
-npm install
-```
+npm install
+```
+
+### 从 npm 安装
+
+Harness Mix 发布为 Windows x64 npm 包，包内包含已构建的 Shim、Desktop Controller 和 Renderer 扩展。安装后可从任意工作目录启动：
+
+```powershell
+npm install --global harness-mix
+harness-mix
+```
+
+升级到最新版本：
+
+```powershell
+npm update --global harness-mix
+```
+
+首次运行会重启已打开的 Codex Desktop。npm 包只分发 Harness Mix 本身；各 Harness 的 CLI、登录状态、模型额度和权限仍需按下表在本机单独安装和配置。
 
 ### 运行方式
 
@@ -136,10 +162,15 @@ npm start
 
 常用原生依赖：
 
-- Codex：安装 `@openai/codex`，确保 `codex` 命令可用。
-- Pi：确保 `pi.cmd` 可用。
-- Claude Code：SDK 已由 npm 依赖安装，认证仍由 Claude Code 环境管理。
-- DeepSeek Harness：使用本项目锁定的 `@deepseek-ai/dsh@0.1.2-rc.1`。可通过 `HARNESS_MIX_DSH_ROOT` 显式指定源码目录，但版本必须被内核支持。
+- Codex：安装 `@openai/codex`，确保 `codex` 命令可用。
+- Pi：确保 `pi.cmd` 可用。
+- Claude Code：SDK 已由 npm 依赖安装，认证仍由 Claude Code 环境管理。
+- DeepSeek Harness：使用本项目锁定的 `@deepseek-ai/dsh@0.1.2-rc.1`。可通过 `HARNESS_MIX_DSH_ROOT` 显式指定源码目录，但版本必须被内核支持。
+- CodeBuddy：安装官方 `codebuddy` CLI 并完成登录；旧 WorkBuddy 安装也可通过兼容别名继续使用。
+- Kiro CLI：安装 `kiro-cli`，启用 `acp` 子命令并完成 CLI 登录。
+- Cursor CLI：安装 `cursor-agent` 并完成 CLI 登录。
+- Qoder：安装 `qodercli`（或 `qoder`）并完成 CLI 登录；ACP 入口由本机版本决定。
+- ZCode / Trae：只有在拥有已验证的 ACP 兼容桥接程序时才配置 `HARNESS_MIX_ZCODE_ACP_EXECUTABLE` / `HARNESS_MIX_TRAE_EXECUTABLE`，项目不会猜测官方入口。
 
 原生接入方式、数据目录和验证说明见 [原生 Codex 接入](docs/native-codex.md)。
 
@@ -165,7 +196,7 @@ npm run e2e:codex
 
 ## 设计原则
 
-1. **原生能力优先**：Adapter 翻译协议，不重新实现 Harness。
+1. **原生能力优先**：Adapter 翻译协议，不重新实现 Harness。
 2. **诚实声明能力**：只有完成接线和验证的能力才进入 `manifest`。
 3. **惰性恢复**：打开历史任务只读取本地投影，发送新消息时才恢复原生进程。
 4. **可回放事件**：Core Event 保持稳定顺序，可用于恢复、投影和确定性校验。

package/config/codex-desktop-compatibility.json

@@ -18,6 +18,12 @@
       "level": "protocol-and-smoke",
       "checkedAt": "2026-09-11",
       "notes": "Install inspection, protocol suite, native build and offscreen Electron smoke passed; full restarted Desktop acceptance remains pending."
+    },
+    {
+      "desktopVersion": "26.908.4834.0",
+      "level": "desktop-e2e",
+      "checkedAt": "2026-09-13",
+      "notes": "Restarted isolated Desktop acceptance passed with the 26.908 connection snapshot and draft identity contracts: Renderer request bridge ready, native input editable, Pi selected with its model, external turn routed through Harness Mix HostRuntime, and exact live Pi response rendered."
     }
   ]
 }

package/docs/harness-management.md

@@ -4,7 +4,9 @@
 
 ## 连接
 
-分别检查 Codex、Claude Code、Pi、DeepSeek Harness 的本机安装状态，显示原生接口、诊断信息和检查耗时。检测不会发送用户消息。程序可用不等于账号已登录。
+按当前适配器注册表检查本机安装状态，包括 CodeBuddy、Kiro CLI 和 Cursor CLI。检测不会发送用户消息；程序可用不等于账号已登录。Kiro/Cursor 提供官方安装链接与刷新检测，不猜测 npm 安装包。
+
+CodeBuddy 的旧名称 Workbuddy 自动兼容，已有原生会话 ID 不变。配置路径、专用协议和验证边界见 [原生 ACP 适配说明](native-acp.md)。
 
 ## 账号
 
@@ -14,6 +16,7 @@
 | Claude Code | 原生 `claude auth status --json` | 打开原生认证窗口执行 `claude auth login/logout`，完成后刷新 |
 | Pi | 原生 RPC 模型目录中的供应商 | 打开 Pi 原生交互终端，使用 `/login` 与 `/logout` |
 | DeepSeek Harness | 原生 Web Remote 模型目录中的供应商 | 在独立、安全隔离的应用窗口中打开 DSH 原生管理页面，进入设置管理供应商 |
+| CodeBuddy / Kiro CLI / Cursor CLI | 可执行文件版本检测；打开会话后读取原生目录 | 在各自 CLI 完成原生登录，再刷新检测；不读取或复制登录凭据 |
 
 Pi / DSH 显示「已配置」而非「已登录」，目录存在不能证明凭据通过在线验证。登录与配置仍使用原生程序自己的账号存储，Harness Mix 不复制账号密钥。当前使用各原生程序的本机账号环境，不提供独立多账号池。
 

package/docs/kiro-cursor-integration.md

@@ -0,0 +1,3 @@
+# CodeBuddy / Kiro / Cursor 接入
+
+原有基础接入说明已更新为 [原生 ACP 深度适配](native-acp.md)，包含 CodeBuddy 更名兼容、厂商专用接口、测试证据与未支持能力。

package/docs/multi-agent-collaboration.md

@@ -17,7 +17,7 @@
 
 借鉴 Codeg 的 [委派工具](https://github.com/xintaofei/codeg/blob/main/src-tauri/src/acp/delegation/tool_schema.json) 和 [Agent 引用路由](https://github.com/xintaofei/codeg/blob/main/src-tauri/src/acp/agent_mentions.rs)：
 
-1. Host 为主任务提供会话绑定的协作工具。Claude 通过 SDK 的 MCP 配置，Codex Adapter 通过 app-server 的线程 MCP 配置，Pi/OMP 通过原生扩展加载，Grok 通过原生 `session/new` 的 `mcpServers` 槽注入（L1），OpenCode 通过 `OPENCODE_CONFIG_CONTENT` 内联配置注入 `mcp.servers`（L2，运行时最高优先级、不写任何用户配置文件）。
+1. Host 为主任务提供会话绑定的协作工具。Claude 通过 SDK 的 MCP 配置，Codex Adapter 通过 app-server 的线程 MCP 配置，Pi/OMP 通过原生扩展加载，Grok 通过原生 `session/new` 的 `mcpServers` 槽注入（L1），OpenCode 通过 `OPENCODE_CONFIG_CONTENT` 内联配置注入 `mcp["harness-mix"]`（V2 schema，运行时最高优先级、不写任何用户配置文件），DSH 协作主任务通过官方 `dsh --profile acp` 的 session-scoped MCP 注入；DSH 普通任务仍走 Web Remote。
 2. 主模型调用 `delegate_to_agent(agent_type, task)`，立即取得 `task_id`，可以继续发起其他任务。
 3. Host 创建带 `parentThreadId` 的独立原生会话。任务中需要的上下文由主模型明确传递，不复制其他 Harness 的隐藏状态、账户或权限。
 4. `update_agent_plan(steps)` 发布开发、审查、返工和最终验收计划；步骤状态为 pending / in_progress / completed。`get_delegation_status(task_ids, wait_ms)` 收取状态和最终文本；单次等待不超过 60 秒。`message_agent` 在已结束的子会话中继续对话，`cancel_delegation` 取消子任务。
@@ -46,8 +46,8 @@
 | Oh My Pi 主任务 | 同 Pi 家族的扩展接线；本机未安装 OMP，真实验收未完成 |
 | Codex（协作）主任务 | 已接入选择器、模型/强度、恢复归属、@ 菜单；桌面使用配套 CLI。真实请求已到原生 MCP 审批，尚未完成需授权的闭环 |
 | Grok 主任务 | L1：`session/new`/`session/load` 原生 `mcpServers` 槽注入，恢复会话同样携带；真实模型闭环验收待跑 |
-| OpenCode 主任务 | L2：`OPENCODE_CONFIG_CONTENT` 内联配置注入 `mcp.servers`（V2 schema），会话结束即失效；真实模型闭环验收待跑 |
-| DSH 主任务 | 调研结论：DSH 自带 `@deepseek-ai/dsh-mcp-client`（stdio 配置：`transport/serverName/command/args/env`），门存在；host.call 会话通道的 MCP 注入点待上游确认，确认前保持 target-only |
+| OpenCode 主任务 | L2：`OPENCODE_CONFIG_CONTENT` 使用 `mcp["harness-mix"]`（V2 schema），会话结束即失效；本机真实请求已到官方 API，但被账户余额阻断 |
+| DSH 主任务 | 官方 `dsh --profile acp` 接收 session-scoped `harness-mix` MCP；DSH→CodeBuddy 两个 worktree 子任务和最终 `COLLAB_VERIFIED` 已通过真实模型回路。普通 DSH 任务继续使用 Web Remote |
 | 官方 Codex 桌面直通任务 | 保持官方直通，不展示 Host 的 @ 协作菜单；不要把 Adapter 接线等同于已支持这个入口 |
 | 其他 Harness 主任务（含 Antigravity） | Agents 页明确提示需要切换可编排的主 Agent，目标不可选；历史引用仍可用；可使用旧 /delegate |
 | 子任务目标 | 所有已注册且本机可用的 Adapter；不代表每一对组合都已实测 |
@@ -66,7 +66,7 @@ npm run build:native
 
 `test:collaboration` 使用真实 MCP stdio 子进程、本地鉴权桥和受控原生会话 Adapter 验证并发、结果、跟进、取消、跨任务访问限制、历史引用提示和共享快照策略。UI smoke 只检查原生输入框内的 Harness/历史会话选择、图标、标识、键盘选取和清理，截图位于 `output/collaboration-ui/mentions.png`。协作过程由 Native Protocol 的原生工具卡片测试覆盖。这不是完整 Codex Desktop 的交互验收；构建过程不会重启当前桌面。
 
-2026-09-10 验证：Pi→Claude 两个真实子任务分别在不同 worktree 运行，结果返回主模型并汇总通过。恢复测试覆盖持久化身份、原子会话续跑、不重复建任务；Git 测试覆盖脏目录起点、暂存区保留、过期预览拒绝、冲突时不部分应用。Native Protocol 覆盖父子任务归属与原生 MCP 工具卡片，Electron 仅覆盖原生输入框中的协作引用增强。
+2026-09-12 验证：Pi→Claude 两个真实子任务分别在不同 worktree 运行，DSH→CodeBuddy 两个真实子任务也在独立 worktree 完成并由 DSH 主会话汇总 `COLLAB_VERIFIED`。恢复测试覆盖持久化身份、原子会话续跑、不重复建任务；Git 测试覆盖脏目录起点、暂存区保留、过期预览拒绝、冲突时不部分应用。Native Protocol 覆盖父子任务归属与原生 MCP 工具卡片，Electron 仅覆盖原生输入框中的协作引用增强。Runtime 保持 Adapter `open()` 返回对象的同一身份，避免原生回调更新到浅拷贝而被活动回合闸门丢弃。
 
 ## 统一历史
 

package/docs/native-acp.md

@@ -0,0 +1,122 @@
+# CodeBuddy、Kiro CLI、Cursor CLI 与其他原生 ACP 接入
+
+CodeBuddy、Kiro CLI、Cursor CLI 和 Qoder 使用原生 ACP stdio，并在 `native-acp.js`、
+`acp-interactions.js` 中处理厂商差异。ZCode、Trae 也复用此引擎，但当前只有显式
+ACP 程序配置入口，尚未验证可用桥接程序，不能称为已完成官方原生接入。
+不替换原生账号、不代理模型供应商、不自动批准工具请求。
+
+## 安装与旧名称兼容
+
+| Harness ID | 原生启动 | 可选路径变量 | 安装入口 |
+| --- | --- | --- | --- |
+| `codebuddy` | `codebuddy --acp` | `HARNESS_MIX_CODEBUDDY_EXECUTABLE` | [CodeBuddy CLI](https://www.codebuddy.ai/docs/cli/overview) |
+| `kiro-cli` | `kiro-cli acp --agent-engine v3 --auth-method cli` | `HARNESS_MIX_KIRO_EXECUTABLE` | [Kiro CLI](https://kiro.dev/docs/cli/) |
+| `cursor-cli` | `cursor-agent acp` | `HARNESS_MIX_CURSOR_EXECUTABLE` | [Cursor CLI](https://cursor.com/docs/cli/installation) |
+| `qoder` | `qodercli --acp` / `qoder --acp` | `HARNESS_MIX_QODER_EXECUTABLE` | [Qoder 官方 ACP 文档](https://docs.qoder.com/cli/acp) |
+| `zcode` | 显式指定 ACP 桥接程序，无附加参数 | `HARNESS_MIX_ZCODE_ACP_EXECUTABLE` | [ZCode](https://zcode.z.ai/)；本机原生 CLI 仅确认 app-server |
+| `trae` | 显式指定兼容 ACP 程序，无附加参数 | `HARNESS_MIX_TRAE_EXECUTABLE` | [官方 trae-agent](https://github.com/bytedance/trae-agent)；未确认 ACP 支持 |
+
+Qoder 在 Windows 上识别 npm 包并直接启动官方 JavaScript bundle。ZCode 的
+`app-server --stdio` 使用厂商协议，不能直接填入 ACP 程序路径。旧的 `zcode acp`、
+`traecli acp serve` 缺少官方依据，已移除；未配置桥接时明确显示不可用。
+Trae 官方开源项目的命令名是 `trae-cli`，不代表它具备 ACP 服务模式。
+本项目不自动安装第三方桥接器，也不复制其凭据同步或默认 yolo 策略。
+
+CodeBuddy 优先使用明确指定的路径，再搜索 PATH 和 WorkBuddy 桌面自带的
+CodeBuddy CLI。旧变量 `HARNESS_MIX_WORKBUDDY_EXECUTABLE` 继续有效，新变量优先。
+`workbuddy` 是兼容别名；只注册一个 CodeBuddy 适配器。启动时迁移 Host 任务和
+Harness 切换历史中的旧 ID，保留原生会话 ID、文件位置和对话内容。
+Renderer 读取旧默认模型和分组偏好时同步迁移旧名称。
+
+Cursor 在 Windows 上识别官方版本目录并直接运行其 Node bundle。
+不使用含义不明确的 `agent` 命令，因为它也可能属于 Grok。
+显式路径无效会报错，不能静默转向其他安装。
+
+## 专用适配
+
+| 能力 | CodeBuddy | Kiro CLI | Cursor CLI |
+| --- | --- | --- | --- |
+| 模型/配置 | 原生 model、thought_level、mode；等待确认 | 原生 model、effortLevel；auto 不显示独立 effort | 保留完整模型变体及原生执行模式 |
+| 审批 | 保留原生 optionId 与单次/持久范围 | 原生选项；consent 携带会话/工作区及资源元数据 | 原生 optionId 与作用范围 |
+| 提问 | AskUserQuestion → resolveInterruption；旧 question 回调；失败可重试 | `_kiro/userInput` 文字/选项 | `cursor/ask_question` 单选/多选 |
+| 计划 | ACP plan 投影 | ACP plan 投影 | `cursor/create_plan` 接受/拒绝/取消 |
+| 取消 | 等待取消完成，再关闭、重连、load 同一会话并恢复确认过的配置 | 原生 cancel；超时关闭并报故障 | 原生 cancel；超时关闭并报故障 |
+| 恢复 | session/load；加载期间不重复输出历史 | session/load | session/load |
+| 压缩/fork | 不支持 | 仅调用握手声明的 compact/fork；不伪造检查点 | 不支持 |
+| 用量 | 按原生 model request ID 去重 Token/Credits；标准 ACP 上下文 | 原生上下文百分比、usage 元数据 Credits 去重 | 不声明用量 |
+| 原生历史导入 | JSONL 当前 parent 链，校验 cwd/session/path/大小/环 | 仅现有 Host 历史与原生恢复 | 仅现有 Host 历史与原生恢复 |
+
+共享处理包括：每会话独立进程、会话级 MCP 注入、拒绝并发提交和忙时改配置、
+30 秒启动/配置/取消超时、忽略其他会话和旧连接事件、工具终态去重、仅在工具
+成功后投影原生完整 Diff。已知 Cursor 损坏的 diff header 回退保持为工具输出，
+不猜测文件内容。Credits 保持独立字段，不换算为美元。
+
+多选问题目前通过输入 JSON 字符串数组表达；选项会展示在问题中，提交时按原生
+选项 ID 校验。CodeBuddy 允许原生提问支持的自定义回答。
+
+## 能力边界
+
+- 这是针对本项目接口实现的适配，不是完整移植 codex-host 的插件系统。
+- 原生子 Agent 的独立卡片、后台生命周期与子会话历史浏览尚未实现。
+  CodeBuddy 带 parentToolCallId 的子 Agent 内容不会混入父回答。
+- Kiro fork 只读取并校验原生 session.json/messages.jsonl 的最新完整 turn_end，
+  将真实 messageId 传入原生 fork；压缩、tombstone 或缺失边界明确拒绝。
+- Kiro 原生历史导入、Cursor 的内部 SQLite 历史导入未实现；恢复已有 Host
+  任务使用原生 session/load，不读写其私有数据库。
+- CodeBuddy/Kiro/Cursor/Qoder 的图片以 ACP image block 传递，仅在原生握手声明
+  `promptCapabilities.image` 时接受；缺失能力时拒绝，不能静默丢图。2026-09-12
+  实机图片回路在 CodeBuddy 通过；Kiro/Cursor 未安装，Qoder 被额度阻断。DSH 和
+  OpenClaw 的当前模型明确拒绝图片，属于模型能力限制而非 Host 丢图。
+- 精确消息回退、CodeBuddy/Cursor fork、账号配额查询不声明支持。
+- Kiro autopilot 不伪装为 Host 权限级别；未知扩展请求明确报不支持。
+- 部分 CLI 不提供原生 Diff 或用量，缺失时不从当前文件/估算值补造。
+- CodeBuddy/Kiro/Cursor/Qoder/ZCode/Trae 的 ACP 会话可接收每会话 MCP 定义，
+  但只有本机安装且握手成功的程序才会开放入口；ZCode、Trae 仍需显式兼容 ACP
+  桥接器，不能把其 app-server 或普通 CLI 当成 ACP。
+- DSH 协作主任务走官方 `dsh --profile acp`，由同一 ACP 引擎接收 session-scoped
+  MCP；普通 DSH 任务继续使用 Web Remote。Runtime 保持 Adapter `open()` 返回
+  的会话对象身份，避免原生回调更新到浅拷贝而被活动回合闸门丢弃。
+
+## 验证
+
+```powershell
+npm run test:native-acp-depth
+npm run test:kiro-cursor
+npm run test:core-all
+npm run test:native-ui
+npm run e2e:native-acp
+npm run e2e:native
+npm run health:harnesses -- --live
+npm run health:harnesses -- --live --image-only --image=<绝对图片路径>
+```
+
+深度协议测试使用模拟原生子进程，覆盖取消/重连后继续、配置确认、忙时拒绝、
+会话隔离、审批原生 ID、提问失败重试、多选、计划拒绝、Kiro 上下文/fork、
+Diff 去重、历史 parent 环和 Credits 去重。这些测试不是模型执行证据。
+
+2026-09-12 实机结果：CodeBuddy 2.132.0 返回 17 个模型和 8 个模式，完成文本
+回复后关闭进程，session/load 同一原生会话并再次回复成功。此版本当前模型未
+返回独立思考选项，因此未伪造档位。Kiro/Cursor 未在 PATH 和默认目录发现，
+真实模型、专用交互以及重启桌面验收待安装登录后完成。日志保存在
+`output/native-acp-live/1789182835967/report.json`（本地构建产物，不提交）。
+
+Qoder 1.1.49 实机完成 ACP 初始化、创建会话，返回 1 个模型和 5 个原生模式。
+文本请求返回账号 Credits 额度耗尽，因此模型回复、恢复和工具执行尚未通过实机验证。
+日志：`output/native-acp-live/1789187177461/report.json`。
+新增六种协议配置的模拟进程回归、延迟 ACP 最终事件回归和图片握手拒绝测试；
+ZCode/Trae 的模拟测试只验证共享引擎，不能作为其官方 CLI 已接通的证据。
+
+2026-09-12 全 Harness 健康检查（均在独立临时工作目录执行）：文本回路通过
+Pi、DSH、Claude Code、Codex、Grok、CodeBuddy；OpenCode 被账户余额阻断，Qoder
+被 Credits 额度阻断，OMP、Hermes、Kiro、Cursor 未安装。图片回路通过
+Antigravity、Pi、Claude Code、Codex、Grok、CodeBuddy；DSH/OpenClaw 的当前模型
+拒绝图片，Qoder/OpenCode 分别被额度/余额阻断。报告：
+`output/harness-health/1789191914230/report.json`（文本）和
+`output/harness-health/1789191791797/report.json`（图片）。
+
+## 参考与图标
+
+协议字段对照了 [codex-host 7cc4db87](https://github.com/BytePioneer-AI/codex-host/tree/7cc4db87fe5e5aa7f232e592a6ff8f0ff96534c9/packages/adapters)
+的 codebuddy、kiro-cli、cursor-cli 实现及接口说明；其测试结果不视为本项目证据。
+CodeBuddy 和 Cursor 图标取自该提交的官方品牌资源副本，Kiro 沿用仓库已有
+官方 SVG。品牌标志归原所有者所有，不表示厂商背书。

package/docs/native-codex.md

@@ -9,7 +9,7 @@ Codex Desktop 原生输入框 / Harness 选择器
   → 本地编译的 Harness Mix CLI Shim (harness-mix-shim.exe)
   → Harness Mix 原生 Host 入口 (src/main/native/host.js)
   → Harness Mix 本地 HostRuntime (src/main/host/runtime.js) & ProtocolCore
-  → 本地 Harness 适配器 (Pi / Claude Code / DeepSeek / Antigravity / Codex)
+  → 本地 Harness 适配器（Pi / Claude Code / DeepSeek / Antigravity / Codex / CodeBuddy / Kiro / Cursor / Qoder）
   → Codex app-server 事件投影 (src/main/native/protocol.js)
   → Codex Desktop 原生流式文本、工具、审批和 Diff 组件
 ```
@@ -38,25 +38,48 @@ npm start
 
 ## 自动更新
 
-每次 `npm start` 会先检查 `origin` 上游：可快进且无本地改动时自动拉取、按需重装依赖并重建原生组件，然后继续启动。分叉、本地领先或工作区有未提交改动时跳过并打印原因；更新失败（如离线）不影响启动。
+启动时自动检查更新，按安装形态走两条通道：
 
-- `npm run update`：只检查并应用更新，不启动桌面。
+- **git 检出（开发形态）**：可快进且工作区干净时自动拉取、按需重装依赖并重建原生组件；`install` / `build` 失败自动回退到更新前的提交。分叉、本地领先或工作区有未提交改动时跳过并打印原因。
+- **npm 全局安装**：从 registry 发现新版本后，先停止桌面，再用 `npm install -g harness-mix@<版本>` 应用（校验由 npm integrity 承担），失败自动重试并挂起至下次启动；连续两次启动未成功会自动回滚到上一版本。
+
+所有变更操作持有更新锁（`%APPDATA%\harness-mix\codexhost\update.lock`），状态记录在 `update-state.json`；应用成功后启动器自行重启加载新代码。任何更新失败（如离线、占用、权限）都不阻塞启动。
+
+- `npm run update`：只检查并应用更新，不启动桌面（应用时会先停一次桌面）。
 - `npm start -- --no-update` 或 `HARNESS_MIX_AUTO_UPDATE=0`：跳过本次更新检查。
+- `HARNESS_MIX_UPDATE_REGISTRY`：自定义 registry；`HARNESS_MIX_UPDATE_PRERELEASE=1`：允许预发布版本。
+
+## Shim 与原生组件（Rust）
+
+`harness-mix-shim.exe`、`harness-mix-appx.exe` 与 `harness-mix-secret.exe` 由 `src/main/native/rs` 下的 Rust workspace 构建（`npm run build:native`），零外部 crate 依赖：Shim 仅用 std 并给自身挂 kill-on-close Job Object，AppX 手写 COM 声明，Secret 手写 DPAPI/kernel32 声明；任意干净的 Rust 工具链即可构建。Shim 产物经 e2e:native 全链路验证，Job Object 级联清理由 `npm run test:native-job-object` 验证。
+
+## 进程监管
+
+- Shim 启动即把自身加入 Job Object（`KILL_ON_JOB_CLOSE`）：node 宿主、官方 app-server、各家 CLI 与 pwsh 终端全部随 shim 级联清理，强杀或崩溃也不例外。
+- 宿主每 5s 写心跳（`%APPDATA%\harness-mix\codexhost\runtime\instance.json`）；`uncaughtException` / `unhandledRejection` / `SIGBREAK` 会写入同目录 `crash-<ts>.json` 并尝试优雅收尾。
+- 启动器在重启桌面前清扫本项目残留进程（仅匹配 shim 二进制路径与 `native-host.cjs` / `desktop-controller.mjs` 入口），并把上次异常退出时运行中的任务标记为 interrupted，重新发送即可继续。
+- 适配器与终端统一经 `src/main/native/process-utils.js` 的 `terminateTree()`（Windows `taskkill /T /F`）终止进程树。
 
-## Shim 与激活器（Rust）
+## 安全存储与诊断
 
-`harness-mix-shim.exe` 与 `harness-mix-appx.exe` 由 `src/main/native/rs` 下的 Rust workspace 构建（`npm run build:native`），零外部 crate 依赖：Shim 仅用 std，AppX 手写 COM 声明，任意干净的 Rust 工具链即可构建。产物经 e2e:native 全链路验证。
+- `harness-mix-secret.exe`（DPAPI，当前用户范围）提供平台保险箱：`set / get / delete / list`，密文落盘 `<data>\secrets.dat`；JS 入口 `src/main/native/secure-store.js`，helper 缺失时明确报错、绝不降级为明文。当前没有默认凭据写入，供后续功能（私有 registry token、直连模型密钥等）使用。
+- `host-traffic.jsonl` 与 `shim-invocations.log` 均为 5MB × 3 轮转；写盘前对 Bearer/API key 形态与敏感字段键做脱敏（`src/main/native/redact.js`）。
+- `npm run diagnostics`：把版本、桌面兼容状态、更新/实例状态、脱敏日志尾与最近崩溃报告打包为 zip 输出到 `output/`，供问题反馈。
 
 默认 Host 数据目录为 `%APPDATA%\harness-mix\codexhost`，可用 `CODEXHOST_DATA_DIR` 覆盖。
 
 本项目仅保存以下非凭据配置到该目录的 `harness-mix-settings.json`，以适配 Windows AppX 环境传递：
 
 - `HARNESS_MIX_DSH_ROOT`：可选 DSH 源码目录。
+- `HARNESS_MIX_CODEBUDDY_EXECUTABLE`、`HARNESS_MIX_KIRO_EXECUTABLE`、`HARNESS_MIX_CURSOR_EXECUTABLE`：可选原生 CLI 路径。CodeBuddy 兼容旧的 `HARNESS_MIX_WORKBUDDY_EXECUTABLE`，新变量优先。接口与验收见 [原生 ACP 深度适配](native-acp.md)。
 - `CODEXHOST_PI_COMMAND`、`CODEXHOST_CLAUDE_COMMAND`、`CODEXHOST_DEEPSEEK_HARNESS_COMMAND`、`CODEXHOST_ANTIGRAVITY_COMMAND`：可选原生命令路径。
 
 环境变量优先于该文件；删除文件中的对应字段即可恢复默认。账号认证使用各原生程序和上游配置机制，本项目不保存凭据。
 
-DSH 默认使用本项目安装的 `0.1.2-rc.1`，不会修改 `E:\dsh\deepseek-harness`。该源码目录当前 `0.1.2-alpha.5` 不满足上游适配器的版本要求。
+DSH Web Remote 与协作 ACP 默认使用 `HARNESS_MIX_DSH_ROOT`（未设置时为
+`E:\dsh\deepseek-harness`）中的原生源码；当前本机健康检查版本为
+`0.1.5-rc.2`。原生 Host 包装脚本在未设置该变量时才回退到项目安装的
+`@deepseek-ai/dsh@0.1.2-rc.1`。两条路径都不修改 DSH 源码或复制账号凭据。
 
 ## 验证