@harness-mix/cli 0.1.3

package/docs/harness-management.md

@@ -0,0 +1,44 @@
+# Harness 管理
+
+入口：右上角「Harness 管理」、左下角设置，或 `Ctrl+,`。
+
+## 连接
+
+按当前适配器注册表检查本机安装状态，包括 CodeBuddy、Kiro CLI 和 Cursor CLI。检测不会发送用户消息；程序可用不等于账号已登录。Kiro/Cursor 提供官方安装链接与刷新检测，不猜测 npm 安装包。
+
+CodeBuddy 的旧名称 Workbuddy 自动兼容，已有原生会话 ID 不变。配置路径、专用协议和验证边界见 [原生 ACP 适配说明](native-acp.md)。
+
+## 账号
+
+| Harness | 读取状态 | 管理方式 |
+| --- | --- | --- |
+| Codex | 原生 `account/read` | 原生 `account/login/start` 打开浏览器；支持取消、完成通知与退出登录 |
+| 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 不复制账号密钥。当前使用各原生程序的本机账号环境，不提供独立多账号池。
+
+修改登录前会检查该 Harness 是否有运行中的任务。Codex 登录连接保留至完成、取消或五分钟超时；关闭设置不会取消浏览器登录，应用退出会取消待完成的登录。
+
+## 模型
+
+- 按 Harness 读取原生模型目录，支持按名称和供应商筛选。
+- 「保存为新对话默认」写入 Harness Mix 的本地非敏感偏好，刷新与重启后保留，不改写原生模型配置。
+- 同名模型按供应商区分。默认选择只允许来自该 Harness 实际返回的目录。
+- 「应用到当前对话」通过现有原生 `setModel` 链路执行；任务运行中不能切换。
+- 选择「跟随原生默认」可清除 Harness Mix 的默认模型覆盖。
+- 配置或登录完成后刷新状态和目录，使新的供应商与模型可见。
+
+## 验证
+
+```powershell
+npm run test:native-ui
+npm run smoke:native-ui
+npm run e2e:native
+```
+
+`test:native-ui` 覆盖账号字段白名单、模型供应商身份、并发默认值保存、登录连接生命周期和设置页渲染逻辑。`smoke:native-ui` 使用 Electron 与模拟原生响应，检查 Renderer 注入及设置界面的关键交互。
+
+`e2e:native` 是只读协议验收：读取可用 Harness 与模型目录，不执行登录/退出或修改凭据。完整账号管理和 DSH 原生页面重开仍需在真实 Codex Desktop 重启验收中人工确认，不能由这条命令代替。

package/docs/kiro-cursor-integration.md

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

package/docs/multi-agent-collaboration.md

@@ -0,0 +1,89 @@
+# 多 Agent 协作
+
+## 用法
+
+重新启动 Harness Mix 后，新建或恢复一个 Pi / Oh My Pi / Claude Code / **Codex（协作）** / Grok / OpenCode / **Antigravity** 任务，输入 `@`，在 **Agents** 页选择目标 Harness；**会话** 页单独提供历史引用。左右键切换分页，上下键选择，Enter/Tab 插入。Codex（协作）通过 Host Adapter 使用原生 app-server；原来的 Codex 入口仍为官方直通。可用目标来自 Host 注册的 Adapter；未就绪的目标不可选。示例：
+
+```text
+你负责实现后端。
+@claude-code 审查 API 设计，只读，不修改文件。
+@pi 为 tests/ 编写测试，不修改 src/。
+收齐结果后由你运行验证并总结。
+```
+
+也可直接输入 `@pi`、`@claude`、`@dsh`、`@codex` 等已注册 ID/别名。显式 `[名称](harness-mix://agent/pi)` 引用可随草稿复制；代码块、行内代码和邮箱里的 @ 不作为路由元数据。提及本身由主模型结合用户任务理解，Host 不按文字片段盲目拆任务。
+
+## 执行方式
+
+借鉴 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["harness-mix"]`（V2 schema，运行时最高优先级、不写任何用户配置文件），DSH 协作主任务通过官方 `dsh --profile acp` 的 session-scoped MCP 注入，Antigravity 协作主任务通过 bridge 目录自动生成的 `.agents/plugins/harness-mix` plugin 及 loopback 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` 取消子任务。
+5. 结果作为真正的原生工具结果返回主模型，由主模型验证、整合并继续执行。Host 额外投影原生 `collabAgentToolCall` 协作卡片（真实子任务 ID、Harness 名称、提示词、最终状态、Worktree 补丁与改动摘要），原生桌面渲染扩展支持点击直接跳转定位到子会话、内联展开语法高亮 Diff 查看改动、以及一键合并回主项目。
+
+`list_agents` 提供真实可用性。旧 `/delegate` 仍是独立的手动委派入口，其完成结果只回投父任务工具卡片，不自动调用父模型。
+
+## 执行边界
+
+- 同一主任务最多四个同时运行的子任务，每轮最多创建十六个；子任务不注入协作工具，不允许递归委派。
+- 模型工具委派默认共享主任务目录，子 Agent 使用独立原生会话。开发完成后再委派审查，审查意见通过 `message_agent` 发回原开发者，修复后复用原审查会话复审。主任务应等待依赖步骤完成并避免同时修改相同文件。主任务负责共享目录整体文件快照。显式 `isolation=worktree`（或 Git 项目中的 `auto`）仍创建隔离分支与工作区，保存主目录当前非忽略文件作为起点，保留用户暂存区；隔离改动不会自动出现在主目录。
+- 协作不创建独立面板或第二套 UI。父子关系通过原生 `parentThreadId` 投影，子任务进入 Codex 原生任务体系；委派和跟进显示为原生协作卡片；普通工具及轮询仍显示为 MCP 工具卡片，审批在相应原生子任务中处理，文件变化由原生 Changes 界面展示。
+- 主任务可调用 `review_delegation_changes` 在原生工具卡片中审查 worktree patch。只有用户明确要求应用时才可调用 `apply_delegation_changes`，并必须提交刚审查得到的 digest。应用前检查 Git patch 冲突；冲突时结构化输出冲突文件清单及处置指引（工作区手动解决、推送到远程分支开 PR、或一键丢弃）。系统提供 `codexhost/thread/workspace/discard` 一键安全清除 worktree 与删除临时分支，以及 `codexhost/thread/workspace/push` 提交快照并直接推送到 Git 远程分支。worktree 默认保留供检查，不自动删除。隔离子任务有独立审查快照；共享子任务仍由主任务记录整体快照。旧 `/delegate` 手动入口仍为共享目录。
+- 同目录的无关任务仍受原有执行互斥约束。父任务结束/取消、Host 关闭会取消尚未完成的子任务；30 分钟未完成的子任务会超时。
+- 协作 HTTP 桥仅绑定 loopback，以每个主任务的随机本地能力标识鉴权；工具参数校验，子任务归属检查，外部 Origin 拒绝。该标识不是模型账户令牌。Host 不读取或代理原生账户密钥。
+- Claude 的 `canUseTool` 和 Codex MCP elicitation 继续走原生审批。需要确认时，用户在相应任务的审批界面处理；自动验证不会代答。
+- 主任务 Fork 会重新绑定自己的协作身份，不复用源任务的子任务访问权。
+- task_id、父子会话、任务文本、结果和 worktree 起点在独立串行存储中持久化；重启后在途任务变为 interrupted，不自动重复执行有副作用的操作。点击「继续协作」向原主任务发送续跑请求，主模型用 `list_delegations` / `resume_delegation` 恢复原子会话。原生会话丢失或无法恢复会明确报错。会话鉴权标识不持久化，重启重新签发。
+
+## 支持与验证范围
+
+| 入口 | 状态 |
+| --- | --- |
+| Pi 主任务 | 原生扩展工具；Pi→Pi、Pi→Claude 两条真实模型链路通过 |
+| Claude Code 主任务 | SDK MCP 注入；本机真实运行触发原生工具审批，未代答，尚未完成模型闭环验收 |
+| Oh My Pi 主任务 | 同 Pi 家族的扩展接线；本机未安装 OMP，真实验收未完成 |
+| Codex（协作）主任务 | 已接入选择器、模型/强度、恢复归属、@ 菜单；桌面使用配套 CLI。真实请求已到原生 MCP 审批，尚未完成需授权的闭环 |
+| Grok 主任务 | L1：`session/new`/`session/load` 原生 `mcpServers` 槽注入，恢复会话同样携带；真实模型闭环验收待跑 |
+| 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 |
+| Antigravity 主任务 | 支持主编排（通过 `.agents/plugins/harness-mix` MCP 自动挂载及指导词注入）；已接入协同工具与卡片投影 |
+| 官方 Codex 桌面直通任务 | 保持官方直通，不展示 Host 的 @ 协作菜单；不要把 Adapter 接线等同于已支持这个入口 |
+| 其他 Harness 主任务 | Agents 页明确提示需要切换可编排的主 Agent，目标不可选；历史引用仍可用；可使用旧 /delegate |
+| 子任务目标 | 所有已注册且本机可用的 Adapter；不代表每一对组合都已实测 |
+
+```powershell
+npm run test:collaboration
+npm run test:collaboration-recovery
+npm run smoke:collaboration-ui
+npm run e2e:collaboration -- --lead=pi --worker=claude
+npm run check
+npm run test:core-all
+npm run test:native-protocol
+npm run e2e:native
+npm run build:native
+```
+
+`test:collaboration` 使用真实 MCP stdio 子进程、本地鉴权桥和受控原生会话 Adapter 验证并发、结果、跟进、取消、跨任务访问限制、历史引用提示和共享快照策略。UI smoke 只检查原生输入框内的 Harness/历史会话选择、图标、标识、键盘选取和清理，截图位于 `output/collaboration-ui/mentions.png`。协作过程由 Native Protocol 的原生工具卡片测试覆盖。这不是完整 Codex Desktop 的交互验收；构建过程不会重启当前桌面。
+
+2026-09-12 验证：Pi→Claude 两个真实子任务分别在不同 worktree 运行，DSH→CodeBuddy 两个真实子任务也在独立 worktree 完成并由 DSH 主会话汇总 `COLLAB_VERIFIED`。恢复测试覆盖持久化身份、原子会话续跑、不重复建任务；Git 测试覆盖脏目录起点、暂存区保留、过期预览拒绝、冲突时不部分应用。Native Protocol 覆盖父子任务归属与原生 MCP 工具卡片，Electron 仅覆盖原生输入框中的协作引用增强。Runtime 保持 Adapter `open()` 返回对象的同一身份，避免原生回调更新到浅拷贝而被活动回合闸门丢弃。
+## 统一历史
+
+设置 → 会话导入 → 全部历史，支持按标题、目录和会话 ID 搜索、分页、导入并打开。Pi、Claude、Codex 从本机原生历史发现会话；其余 Harness 当前聚合 Host 已管理的历史，并在来源名称上标为「Host 历史」，尚未接入各自 CLI 的外部会话扫描。
+
+导入只创建投影和原生会话引用，不启动模型；再次发送时原生恢复。重复导入返回同一任务。输入 `@` 可从「会话」页选择一条记录；Host 最多读取三条引用，每条只附加最近十二条用户/助手文本，并明确标记为不可执行的历史数据。引用不会创建、恢复或占用原生会话。原始完整工具、隐藏状态和分支数据仍留在原生存储，因此这不是原生历史的无损迁移。原生运行状态未知时，应先关闭其他客户端的同一会话。
+
+## 2026-09-11 Codeg 协作流程修复
+
+- Agents 与历史会话分栏，修复原生 @ 大菜单与协作菜单同时弹出；提示不可用主 Agent 的能力边界。
+- 默认共享目录，使开发与审查读取同一份实际文件；保留显式隔离工作区。多任务等待在任一结果可收取时返回。
+- 新增可更新的原生计划，子任务卡片投影真实会话 ID 与 Harness 名称，跟进复用原会话。
+- 实测 Pi 主任务 + 两个独立 Pi 原生子会话：开发者写入错误样本 41 → 审查者 REVIEW_FAIL → message_agent 交回原开发者修为 42 → 原审查者 REVIEW_PASS → 主模型完成计划并汇总。测试验证文件实际导出值以及两个会话均收到跟进。日志：`output/collaboration-cycle.log`。
+- Pi → Claude 写文件测试到达原生审批，未代答，跨 Harness 写文件闭环尚未通过；不能据此声称全部 Harness 组合已验收。
+
+```powershell
+npm run e2e:collaboration -- --lead=pi --worker=pi --cycle
+```
+
+桌面实测与隔离增强：Pi 主 Agent 切换、Agents/会话切页、Claude 提及精确插入（无重复 @）、图标标识和草稿清理通过。原生协作卡片已实装「↗ 查看 @agent 会话」跳转子任务 Thread、「🔍 查看产物 Diff」语法高亮展开与「✓ 合并改动到主项目」操作；Worktree 隔离环境已实装补丁冲突结构化指引、`discardWorkspace` 一键丢弃临时分支与 `pushWorkspace` 远程分支推送协议支持。截图与报告在 `output/collaboration-ui/desktop-*.png` 和 `desktop-report.json`。

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

@@ -0,0 +1,95 @@
+# 原生 Codex UI 接入
+
+`npm start`、`npm run start:codex`、`Start-Codex.cmd` 均启动原生模式（唯一模式）。
+
+## 调用链
+
+```text
+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 / CodeBuddy / Kiro / Cursor / Qoder）
+  → Codex app-server 事件投影 (src/main/native/protocol.js)
+  → Codex Desktop 原生流式文本、工具、审批和 Diff 组件
+```
+
+外部 Thread 支持「调整方向」：会话运行中发送新消息会取消当前 Turn、等待其完全终结（含文件快照结算），再将新输入作为独立新 Turn 启动；超时、目标过期或并发冲突一律失败，绝不自动启动非预期 Turn。
+
+这是完全内化于本项目的自研自建架构：
+- **无上游 npm 依赖**：Launcher、Shim、Host Runtime 与 Renderer 扩展源码均维护在本项目（`src/main/native` 与 `src/native-ui`），不依赖任何上游 npm 包。
+- **内核 100% 属于 Harness Mix**：由本项目的 `HostRuntime`、`ProtocolCore` 与原生适配器（`src/main/adapters`）直接管理会话生命周期、模型调用、多轮对话、交互审批与文件差异。
+- **图标与资源自主集成**：Harness 品牌图标及各厂商模型图标直接从 `src/assets/icons` 提取并在本地编译时嵌入 Renderer 扩展。
+- **单内核**：原生模式接入 Codex 原生 UI，会话内核只有 HostRuntime + ProtocolCore 一套。
+
+## 启动与配置
+
+需要 Node.js 22.19+（22 系列）或 Node.js 24、Rust 工具链（rustup，推荐 `x86_64-pc-windows-gnu` 主机以免依赖 Visual Studio）、官方 Codex Desktop，以及已配置的原生 Harness。
+
+```powershell
+npm install
+npm run check:native  # 只检查安装，不重启桌面
+npm start
+```
+
+`check:native` 同时输出当前 Codex Desktop 的兼容状态：`verified` 表示该精确版本已完成重启桌面 E2E，`observed` 表示仅通过协议/构建/离屏 smoke，`unverified` 表示版本尚未进入证据矩阵。明确列入阻止名单的版本拒绝启动；设置 `HARNESS_MIX_STRICT_COMPATIBILITY=1` 时，只有 `verified` 版本可以启动。矩阵位于 `config/codex-desktop-compatibility.json`，不得把单元测试或离屏 smoke 记录成完整桌面验收。
+
+**启动器会重启当前 Codex Desktop。** 保存正在进行的工作后再启动，包括当前 Codex 对话所在的桌面。不要同时运行旧版 `launch-codex.cjs` 后台进程。
+
+## 自动更新
+
+启动时自动检查更新，按安装形态走两条通道：
+
+- **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`）终止进程树。
+
+## 安全存储与诊断
+
+- `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 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 源码或复制账号凭据。
+
+## 验证
+
+```powershell
+npm run check
+npm run smoke:native-ui
+npm run e2e:native
+npm run e2e:native:pi
+npm run e2e:native:dsh
+npm run e2e:native:claude
+```
+
+`e2e:native` 启动真实 Shim 与 Host，检查官方协议透传和 Pi、Claude、DSH 的可用目录。三个具名 E2E 会发送简短真实请求，验证原生 `thread/start`、`turn/start`、流式结果和 `turn/completed`。报告写入 `output/native-host/`。它们不重启当前桌面；桌面完整重启后的 UI 仍需单独验收。