@harness-mix/cli 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.5 — 2026-09-13
+
+- Added graphical cross-Harness task handoff in the native Codex Desktop composer, with continue, execute-plan, independent-review, and reanalyze modes.
+- Added persistent, hashed handoff checkpoints with bounded redacted conversation, plan, file, Git, test, build, command, and error evidence.
+- Added task-scoped read-only MCP access for capable Harnesses while preserving bounded-summary fallback for other native protocols.
+- Added native Codex account management and Harness-scoped MCP/Skills integration controls.
+- Preserved native ownership of sessions, models, tools, credentials, permissions, and approvals across handoffs.
+
 ## 0.1.3 — 2026-09-13
 
 - Added multi-agent collaboration support (@ mentions composer, thread delegation, worktree isolation).

package/README.md

@@ -1,6 +1,6 @@
 # Harness Mix
 
-macOS/Linux 已加入源码构建与启动适配（待目标系统真机验收）；安装方式、Linux 桌面前提和支持边界见 [跨平台指南](docs/cross-platform.md)。
+macOS/Linux 已加入源码构建与启动适配；目标系统的完整桌面验收仍需在对应机器执行。安装方式、Linux 桌面前提和支持边界见 [跨平台指南](docs/cross-platform.md)。
 
 <p align="center">
   <img src="src/assets/brand-harness-mix.png" width="92" alt="Harness Mix logo">
@@ -10,12 +10,14 @@ macOS/Linux 已加入源码构建与启动适配（待目标系统真机验收
   ⭐ 如果这个项目对你有帮助，请给我们一个 <a href="https://github.com/emo-xiaoyu/harness-mix">Star</a>！ ⭐
 </p>
 
-<p align="center"><strong>Codex 原生 UI，连接多个原生 Coding Harness。</strong></p>
+<p align="center"><strong>Codex 原生 UI，连接多个原生 Coding Harness，并让任务在它们之间无缝接力。</strong></p>
 
 <p align="center">
-  <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
-  <img alt="UI" src="https://img.shields.io/badge/UI-Codex%20Desktop-412991.svg">
-  <img alt="Platform" src="https://img.shields.io/badge/platform-Windows-0078D4.svg">
+  <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
+  <img alt="UI" src="https://img.shields.io/badge/UI-Codex%20Desktop-412991.svg">
+  <img alt="Windows" src="https://img.shields.io/badge/platform-Windows-0078D4.svg">
+  <img alt="macOS" src="https://img.shields.io/badge/platform-macOS-555555.svg">
+  <img alt="Linux" src="https://img.shields.io/badge/platform-Linux-FCC624.svg">
 </p>
 
 <p align="center"><strong>当前注册的 Harness（16 个）</strong></p>
@@ -66,16 +68,29 @@ Harness Mix 是接入官方 Codex Desktop 原生界面的本地内核。它通
 - 在 Codex Desktop 原生输入框中选择 Harness 并发起会话。
 - 流式呈现回答、思考、命令执行、工具调用、文件变更和上下文压缩。
 - 调用每个 Harness 原生提供的模型、权限、上下文用量和快捷指令。
-- 会话中原地切换 Harness（`/switch <Harness 名> [备注]` 或 `codexhost/thread/harness/switch`）：会话历史与文件现场保留在 Host 线程上，切换后首轮自动携带一次性上下文信封；切回旧 Harness 时按其原生机制（Pi `--session` / Claude `resume`）恢复原会话。
+- 会话中可从原生 Harness 选择器图形化“接力当前任务”：选择目标、接力模式、交接内容和可选说明后确认；会话历史与文件现场保留在 Host 线程上。Host 会持久化脱敏的接力检查点，首轮发送紧凑摘要；支持原生 MCP 的 Harness 还可按当前任务作用域读取历史、计划、文件与测试证据。`/switch <Harness 名> [备注]` 保留为键盘入口；切回旧 Harness 时按其原生机制（Pi `--session` / Claude `resume`）恢复原会话。
 - 原生 Diff、审批与提问组件直接渲染，审批路由回原生 Harness，不代替用户作出权限决定。
 - CodeBuddy、Kiro 和 Cursor 使用原生 ACP 加厂商专用接口：提问、计划确认、配置确认、取消恢复、上下文与历史按各自协议处理。功能和验证范围见下表，不将通用 ACP 能力视为所有 CLI 都已支持。
-- 通过 Adapter 注册新 Harness，UI 侧无需理解厂商协议。
+- 通过 Adapter 注册新 Harness，UI 侧无需理解厂商协议。
+- 原生设置中的「MCP」和「Skills」是独立页面：MCP 使用服务器列表与详情编辑流程，Skills 支持把 Markdown 文件或完整技能文件夹直接拖入安装；配置在下一次原生会话打开时生效，凭据和审批继续由原生 Harness 管理。
 
 <p align="center">
   <img src="docs/images/codex-desktop-session.png" width="960" alt="Codex Desktop 原生会话中的 Harness Mix">
 </p>
-
-## 原生接入
+
+## 特色功能：跨 Harness 任务接力
+
+一个 Harness 负责分析，另一个执行方案，再切回原 Harness 复核——整个过程都留在同一个 Codex Desktop 原生任务窗口中。点击输入框旁带接力角标的 Harness 图标，选择目标 Harness 和接力方式即可，不需要复制 Prompt、另开终端或重新整理上下文。
+
+- **现场不丢**：保留任务标题、对话记录、工作目录、未提交文件、Git 状态和 Review 记录。
+- **上下文可追溯**：Host 创建持久化、带内容哈希的接力检查点；目标先收到紧凑摘要，支持原生 MCP 时还可按需读取历史、计划、文件与脱敏测试证据。
+- **四种接力方式**：继续执行、执行上一方案、独立审查、重新分析，可在确认弹窗中选择要交接的内容并补充说明。
+- **可以切回来**：每个 Harness 的原生 Session、模型和选项独立保存；切回时使用其原生恢复能力继续原会话。
+- **原生安全边界不变**：不迁移账号凭据、审批决定、待审批状态、原始 Tool Call ID 或私有协议对象；目标 Harness 必须重新核对真实工作区并自行发起权限请求。
+
+不支持按需读取工具的 Harness 会明确退化为有界摘要，不会伪装成完整上下文迁移。完整流程、数据结构和验收边界见 [跨 Harness 接力设计](docs/harness-handoff-design.md) 与 [Harness 管理说明](docs/harness-management.md)。
+
+## 原生接入
 
 通过 Codex Desktop 内的 Harness 选择器统一查看连接、筛选模型和保存每个 Harness 的新对话默认模型。具体流程与原生边界见 [Harness 管理说明](docs/harness-management.md)。
 
@@ -104,78 +119,9 @@ CodeBuddy、Kiro CLI、Cursor CLI、Qoder、ZCode 和 Trae 均已接入默认选
 
 能力只在 Adapter 的 `manifest` 中声明。界面根据真实能力显示入口，不靠 Harness 名称猜测功能；厂商特有字段会保留在原生引用和载荷中。
 
-## 架构
-
-```mermaid
-flowchart TB
-  Desktop[Codex Desktop 原生 UI] --> Shim[Harness Mix CLI Shim]
-  Shim --> Host[原生 Host 入口 src/main/native]
-  Host --> Runtime[Host Runtime]
-  Runtime --> Core[Protocol Core]
-  Runtime --> Store[(Thread and session store)]
-  Runtime --> Registry[Adapter registry]
-  Registry --> Antigravity[Antigravity CLI]
-  Registry --> Codex[Codex app-server]
-  Registry --> Pi[Pi RPC]
-  Registry --> OMP[Oh My Pi RPC]
-  Registry --> Claude[Claude Agent SDK]
-  Registry --> DSH[DSH Web Remote]
-  Registry --> OpenCode[OpenCode Server HTTP / SSE]
-  Registry --> Grok[Grok native stdio + vendor extensions]
-  Registry --> OpenClaw[OpenClaw Gateway loopback WS]
-  Registry --> Hermes[Hermes ACP stdio]
-  Registry --> Qoder[Qoder 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
-src/
-├─ main/
-│  ├─ adapters/          # 每个 Harness 的原生适配器
-│  ├─ harness-adapter/   # Manifest、能力与适配器契约
-│  ├─ host/              # 编排、恢复、持久化与事件投影
-│  ├─ native/            # 原生模式：Launcher、Shim、Host 入口、协议桥
-│  └─ protocol-core/     # Thread / Turn / Item 统一语义
-├─ native-ui/
-│  ├─ renderer-extension/  # 注入 Codex Desktop 的渲染扩展（选择器、模型目录）
-│  ├─ desktop-control/     # CDP 控制器与请求桥
-│  └─ shared-contracts/    # 渲染侧与内核共享的协议契约
-└─ assets/icons/         # Harness 与模型图标（编译期嵌入）
-```
-
-新增 Harness 时，实现同形 Adapter 并注册到 `src/main/adapters/index.js`。核心形态如下：
-
-```js
-module.exports = {
-  manifest: {
-    id,
-    name,
-    icon,
-    capabilities: { streaming, tools, approvals, models, resume, fork, usage }
-  },
-  create(emit) {
-    return {
-      inspect,
-      open,
-      send,
-      cancel,
-      close,
-      respond,
-      listModelsFor,
-      setModel,
-      fork
-    };
-  }
-};
-```
-
 ## 本地运行
 
-开发环境需要 Windows、近期 Node.js LTS 和 npm。应用不会读取或保存 Harness 的账户密钥，请先在对应的原生 CLI 中完成安装与登录。
+开发环境需要 Windows、macOS 或 Linux，近期 Node.js LTS 和 npm。应用不会读取或保存 Harness 的账户密钥，请先在对应的原生 CLI 中完成安装与登录；平台前提和真机验收范围见 [跨平台指南](docs/cross-platform.md)。
 
 ```powershell
 git clone https://github.com/emo-xiaoyu/harness-mix.git
@@ -241,22 +187,6 @@ npm run e2e:codex
 
 部分 E2E 会启动真实 Harness，可能需要本机安装、登录或模型额度。测试生成物写入 `output/`，不应提交到仓库。
 
-## 设计原则
-
-1. **原生能力优先**：Adapter 翻译协议，不重新实现 Harness。
-2. **诚实声明能力**：只有完成接线和验证的能力才进入 `manifest`。
-3. **惰性恢复**：打开历史任务只读取本地投影，发送新消息时才恢复原生进程。
-4. **可回放事件**：Core Event 保持稳定顺序，可用于恢复、投影和确定性校验。
-5. **凭据隔离**：账号、令牌、沙箱和权限决定由原生程序管理。
-
-## 项目状态
-
-- [内核迁移状态](CORE-MIGRATION-STATUS.md)
-- [下一步计划](NEXT-STEPS.md)
-- [Codex Desktop 原生接入说明](docs/native-codex.md)
-
-Harness Mix 参考了 [codex-host](https://github.com/BytePioneer-AI/codex-host) 的插件化组织方式，并使用 [OpenAI Codex](https://github.com/openai/codex) 官方 app-server 协议完成 Codex 原生接入。
-
-## License
+## License
 
 Harness Mix 基于 [Apache License 2.0](LICENSE) 发布。第三方组件仍适用各自的许可证；归属信息见 [NOTICE](NOTICE)。

package/docs/chatgpt-web-sidebar.md

@@ -1,6 +1,6 @@
 # ChatGPT 网页侧边对话
 
-> 历史设计记录：当前 Harness Mix 原生模式不包含下文所述的 `side-chat` / `web-chat` 实现，相关源码和 `smoke:web-chat` 入口已不在当前仓库中。本文仅保留方案边界，不能作为当前功能或可执行验收说明。
+> `side-chat` / `web-chat` 是历史设计，相关源码和 `smoke:web-chat` 入口已不在当前仓库中。当前原生模式只增强 Codex Desktop 自带的 Quick chat，提供“添加到会话”上下文桥。
 
 ## 官方实现参考
 
@@ -20,6 +20,12 @@
 
 “添加到当前 Harness”优先导入网页选中文字；未选择时读取当前页面已加载的用户与助手消息文本，附带页面标题和来源链接。只填入草稿，由用户点击发送。图片附件不会自动下载或导入；网页未加载的历史消息也不会导入。网页结构变化导致读取失败时会显示提示，可选中文字重试。
 
+当前实现位于 `src/native-ui/renderer-extension/src/renderer-chatgpt-context.ts`。Quick chat 标题栏的“添加到会话”优先使用面板内选中文字，否则读取当前已打开聊天中明确标记为 user/assistant 的已加载消息；内容经脱敏、最多 12 条/24000 字符截断后，作为“不可信历史资料”写入当前主 Composer 草稿。只写草稿，不自动发送，同一草稿只允许一条引用。
+
+- 添加到其他 Harness：发送时由当前 Harness 创建/继续它自己的原生 Session，使用该 Harness 的模型、工具、权限和账号额度；不继承 ChatGPT 的会话 ID、系统提示或工具状态。
+- 添加到 Codex：发送时由当前 Composer 绑定的 Codex 账号处理并消耗该账号额度；同样只是上下文引用，不把 ChatGPT conversation 恢复成 Codex Thread。新任务使用 Composer 当前选择的账号，旧任务保持原账号。
+- 两种目标共用原生 Composer 和同一份上下文包。发送前可用现有 Harness/账号选择器确认目标，Quick chat 不增加第二套会话 UI。
+
 登录和模型选择使用网站原生界面。浏览器会话由 Electron 管理；应用不读取、导出或代理 Cookie、Token。远程页面启用 sandbox、contextIsolation，关闭 nodeIntegration，不注入本地 IPC preload。登录弹窗使用相同浏览器会话。
 
 实现：`src/main/side-chat/web.js`、`src/renderer/web-chat.js`、`src/renderer/web-chat.css`。原 app-server 侧边模块保留在源码中，但生产入口和 preload 已停止接入它。

package/docs/cross-platform.md

@@ -71,3 +71,18 @@ npm start -- --no-update
 CI 增加 Windows/macOS/Linux 的 Node 22/24 内核测试和本机构建，真实 Shim fixture 检查路由、Unicode、带空格参数、环境变量及 EOF；这些不需要账户。配置 CI 不等于已执行 CI。当前 Windows 开发机不能代替 macOS/Linux 真机结果。
 
 在每种目标 OS/CPU 上运行 `npm run check`、`npm run test:core-all`、`npm run build:native`、`npm run test:platform`、`npm run test:shim`、`npm run e2e:native`，再启动真实桌面，逐个验证所需 Harness 的模型列表、Thinking、流式工具输出、原生审批、取消、历史恢复及退出清理。记录 OS、CPU、桌面版本和证据后，才能增加该平台的 `desktop-e2e` 记录。后续发布矩阵需要覆盖 macOS Intel/Apple Silicon、Linux x64/arm64，不能用单个平台的构建文件混发。
+
+## Native npm 包发布
+
+平台包的名字固定为 `@harness-mix/native-<platform>-<arch>`。在目标机器完成构建和 Shim fixture 后，从仓库根目录执行：
+
+```sh
+node scripts/publish-native-package.cjs darwin arm64 --publish
+node scripts/publish-native-package.cjs darwin x64 --publish
+node scripts/publish-native-package.cjs linux x64 --publish
+node scripts/publish-native-package.cjs linux arm64 --publish
+node scripts/publish-native-package.cjs win32 x64 --publish
+node scripts/publish-native-package.cjs win32 arm64 --publish
+```
+
+脚本默认检查目标二进制是否存在，再生成带 `os`/`cpu` 限制的包；本次可用 `--source-only` 发布平台元数据占位包，安装时会提示目标机器执行 `npm run build:native`。主包通过 `optionalDependencies` 选择平台包。当前已发布 `@harness-mix/native-win32-x64@0.1.4`，其余目标先发布 source-only `0.1.4`，正式二进制完成后必须升级版本，不能覆盖同一 npm 版本。

package/docs/harness-handoff-design.md

@@ -0,0 +1,377 @@
+# Harness 跨会话任务接力设计
+
+> 实施状态（2026-09-13）：P0–P4 已在当前工作区落地，包括持久化检查点、脱敏证据、四种图形化模式、受当前任务约束的只读 MCP 查询，以及 `checkpoint-created → verifying → active/failed` 状态。P5 已完成脚本级链路与真实 Electron 组件渲染，尚未重启用户正在运行的 Codex Desktop 做 A → B → A 人工验收。
+
+## 1. 背景
+
+Harness Mix 支持在同一个 Codex Desktop 原生任务窗口中使用不同的 Coding Harness。典型场景包括：
+
+- Harness A 完成问题分析，由 Harness B 继续编码。
+- Harness A 给出解决方案，由 Harness B 执行方案。
+- Harness A 完成修改，由 Harness B 独立审查。
+- 当前 Harness 暂停、不可用或额度不足，切换其他 Harness 继续任务。
+- 完成阶段性工作后切回原 Harness 复核。
+
+任务接力的目标不是简单切换模型，也不是创建一个互不相关的新会话，而是在保留任务窗口、对话记录和文件现场的前提下，更换继续执行任务的原生 Harness。
+
+## 2. 设计目标
+
+任务接力需要满足以下目标：
+
+1. 保留同一个 Harness Mix 任务窗口、标题和可见对话历史。
+2. 保留工作目录、文件变更、Git 状态和 Review 记录。
+3. 让目标 Harness 获得足够的任务语义和验证证据。
+4. 支持以后切回原 Harness，并恢复其原生会话。
+5. 不复制或代理账号凭据。
+6. 不迁移审批决定、待审批状态或私有工具状态。
+7. 不把不同 Harness 的工具调用协议强行互相转换。
+8. 所有交互继续在 Codex Desktop 原生界面中呈现，不增加第二套任务 UI。
+
+## 3. 当前实现
+
+当前实现采用“Host 线程保留 + 一次性上下文信封”的方式。
+
+### 3.1 切换过程
+
+切换时：
+
+1. 确认当前任务没有正在执行的回合、待结算的文件变更或正在建立的 Harness 连接。
+2. 关闭当前 Harness 的原生进程。
+3. 将当前 Harness 的原生 Session ID、会话文件、模型和选项写入 `harnessChain`。
+4. 将任务的当前执行者切换为目标 Harness。
+5. 如果目标 Harness 以前执行过该任务，恢复它原来的原生 Session；否则创建新的原生 Session。
+6. 创建 `pendingHandoff`，等待用户发送下一条真实消息。
+7. 下一条消息发送时注入隐藏的 `[Harness Mix handoff]` 上下文信封。
+8. 信封成功发送后清除 `pendingHandoff`。
+
+`/switch <Harness 名> [备注]` 仍可作为键盘入口；图形入口位于任务输入框旁的 Harness 选择器中。
+
+### 3.2 当前交接内容
+
+当前上下文信封包含：
+
+- 任务标题和工作目录。
+- 消息总数。
+- 最近最多 10 条用户或助手消息，并保持真实先后顺序。
+- 总文本预算最多 24,000 字符。
+- 普通消息最多保留 4,000 字符。
+- 最新一条助手方案最多保留 12,000 字符。
+- 最近计划。
+- 最多 20 个变更文件。
+- 用户填写的交接说明。
+
+目标 Harness 被明确要求使用自己的工具检查真实文件状态，再继续修改。
+
+### 3.3 当前不会传递的内容
+
+当前实现不会向目标 Harness 传递：
+
+- 原始工具调用栈。
+- Tool Call ID、Interaction ID 或审批 ID。
+- Shell 和其他工具的完整原始输出。
+- 待审批、待回答或尚未完成的交互状态。
+- 原 Harness 的私有内存和私有协议状态。
+- 凭据、令牌、账号密钥或敏感环境变量。
+
+如果测试结果或错误信息已经写入原 Harness 的最终回答，它会作为助手消息的一部分进入交接上下文；如果信息只存在于工具卡片中，则当前不会完整传递。
+
+## 4. 当前方案的局限
+
+一次性 Prompt 信封实现简单，但存在以下限制：
+
+- 对话较长时必须截断，无法保证所有历史都进入目标上下文。
+- 工具结果主要依赖原 Harness 是否在最终回答中主动总结。
+- 大量上下文一次性注入会占用目标 Harness 的上下文窗口。
+- 目标 Harness 无法按需获取某条历史、某个测试结果或某个文件证据。
+- 信封发送后即清除，缺少可重复查询和审计的交接对象。
+- 仅靠自然语言摘要难以稳定表达计划状态、错误来源和验证结果。
+
+## 5. 推荐方案：持久化接力检查点
+
+推荐将任务接力升级为：
+
+> Host 持久化的 Handoff Checkpoint + 紧凑首轮摘要 + 按需读取上下文和证据。
+
+切换时不再只生成临时 Prompt，而是创建一份不可变、可审计的接力检查点。目标 Harness 首轮收到紧凑摘要，并可按需读取详细信息。
+
+### 5.1 核心流程
+
+```text
+源 Harness
+  ↓
+Host 创建 Handoff Checkpoint
+  ├─ 任务目标与约束
+  ├─ 决策和计划状态
+  ├─ 对话索引
+  ├─ 文件与 Diff 证据
+  ├─ 测试和错误证据
+  └─ 来源与内容哈希
+  ↓
+切换到目标 Harness
+  ↓
+目标 Harness 接收紧凑摘要
+  ↓
+目标 Harness 按需读取历史或证据
+  ↓
+目标 Harness 核对工作区后继续执行
+```
+
+### 5.2 建议的数据结构
+
+```json
+{
+  "checkpointId": "handoff-...",
+  "threadId": "thread-...",
+  "sourceHarnessId": "claude-code",
+  "targetHarnessId": "pi",
+  "createdAt": 1789300000000,
+  "intent": "execute-plan",
+  "note": "按上一位给出的方案继续执行",
+  "task": {
+    "title": "修复登录模块",
+    "cwd": "E:/project",
+    "objective": "...",
+    "constraints": ["..."],
+    "decisions": ["..."]
+  },
+  "plan": {
+    "completed": ["..."],
+    "inProgress": ["..."],
+    "pending": ["..."]
+  },
+  "conversationRefs": [
+    { "messageId": "...", "role": "assistant", "digest": "..." }
+  ],
+  "fileState": {
+    "gitHead": "...",
+    "diffDigest": "...",
+    "changedFiles": ["src/login.js"]
+  },
+  "evidenceRefs": ["evidence-1", "evidence-2"],
+  "unresolved": ["..."],
+  "contentDigest": "..."
+}
+```
+
+该对象应保存在 Host 的独立持久化存储中，不写入用户项目目录，也不要求某个 Harness 自己维护。
+
+## 6. 标准化证据记录
+
+工具调用不应原样迁移，但可以转换为有界、脱敏、只读的证据记录。
+
+```json
+{
+  "evidenceId": "evidence-1",
+  "kind": "test",
+  "sourceHarnessId": "claude-code",
+  "command": "npm run test:core-all",
+  "exitCode": 0,
+  "summary": "核心测试全部通过",
+  "stdoutExcerpt": "...",
+  "stderrExcerpt": "",
+  "files": [],
+  "createdAt": 1789300000000,
+  "contentDigest": "..."
+}
+```
+
+### 6.1 建议保留的证据
+
+- 测试命令、退出码和结果摘要。
+- 构建命令、退出码和关键诊断。
+- 有界、脱敏后的 stdout/stderr 片段。
+- Git 状态和 Diff 摘要。
+- 文件变更路径与内容哈希。
+- 未解决错误及其来源。
+- 只读检查结果。
+
+### 6.2 明确禁止迁移的内容
+
+- 凭据、令牌和敏感环境变量。
+- 原生审批结果或待审批状态。
+- 可重放的 Tool Call ID 和 Interaction ID。
+- 未完成操作的自动重试指令。
+- 原 Harness 专用的内部对象或协议帧。
+- 未经脱敏的完整环境信息。
+
+证据内容需要经过统一脱敏和大小限制，并标记为来自历史会话的不可信数据。
+
+## 7. 按需上下文读取
+
+目标 Harness 不需要一次性接收全部历史。Host 可以提供只读查询能力：
+
+- `handoff/get`：读取检查点摘要。
+- `handoff/conversation/list`：分页读取相关对话。
+- `handoff/evidence/list`：列出测试、错误和构建证据。
+- `handoff/evidence/read`：读取指定证据。
+- `handoff/files/list`：读取文件变化和 Diff 摘要。
+- `handoff/plan/read`：读取结构化计划状态。
+
+具体传输方式应按 Harness 的真实能力选择：
+
+- 支持原生 MCP 的 Harness：提供只读、当前任务授权的本地 MCP 工具。
+- 支持其他原生扩展协议的 Harness：通过对应 Adapter 映射只读读取能力。
+- 不支持按需工具的 Harness：退化为有界的一次性上下文信封，并明确声明限制。
+
+不能假定所有 Harness 都支持同一种工具协议。
+
+## 8. 图形交互设计
+
+### 8.1 入口
+
+已由 Harness Mix 管理的任务，在输入框旁当前 Harness 图标上显示接力角标。点击后，选择其他可用 Harness。
+
+### 8.2 接力确认弹窗
+
+弹窗建议包含：
+
+- 当前 Harness → 目标 Harness。
+- 接力模式。
+- 可选交接说明。
+- 将要交接的内容预览。
+- 当前回合运行状态。
+- 取消和确认接力按钮。
+
+### 8.3 接力模式
+
+建议提供四种模式：
+
+| 模式 | 行为 |
+| --- | --- |
+| 继续执行 | 沿用当前目标、计划和未完成步骤 |
+| 执行上一方案 | 优先携带最新方案、待办和验证要求 |
+| 独立审查 | 保留证据，但要求目标 Harness 重新检查结论 |
+| 重新分析 | 重点携带目标和文件现场，弱化上一 Harness 的结论 |
+
+### 8.4 内容预览
+
+用户可查看或选择是否包含：
+
+- 最新方案。
+- 近期对话。
+- 当前计划。
+- 测试和构建证据。
+- 文件变更摘要。
+- 未解决错误。
+
+凭据、审批和私有工具状态不应出现在可选项中，因为它们始终禁止迁移。
+
+## 9. 目标 Harness 的接管确认
+
+目标 Harness 不应直接相信历史数据。建议在开始编辑前完成接管确认：
+
+1. 读取接力摘要。
+2. 检查当前工作目录。
+3. 检查 Git 状态和 Diff。
+4. 核对关键文件和未完成计划。
+5. 报告接管成功，或说明检查点与真实文件状态之间的差异。
+
+Host 可将接力状态表示为：
+
+```text
+checkpoint-created → target-opening → verifying → active
+                                     ↘ failed
+```
+
+接管失败时保留检查点和原 Harness 会话引用，允许用户切回或更换其他 Harness。
+
+## 10. 原生所有权与安全边界
+
+任务接力不能改变 Harness Mix 的原生所有权原则：
+
+- 每个 Harness 继续拥有自己的原生 Session、模型调用和工具执行。
+- 每个 Harness 继续使用自己的账号和凭据存储。
+- 权限请求由目标 Harness 按自己的协议重新发起。
+- Host 不复制审批结果，不自动批准任何请求。
+- Host 只保存非敏感任务检查点和脱敏证据。
+- 历史文本、证据和摘要统一标记为不可信数据，不能提升为高优先级指令。
+- 目标 Harness 必须以真实文件状态为最终依据。
+
+## 11. 官方 Codex 的特殊边界
+
+Codex Desktop 中的“官方原生 Codex”任务由官方 app-server 直接拥有，不经过 Harness Mix HostRuntime。Harness Mix 无法诚实地原地更换这种线程的执行者。
+
+可支持的方式是“一键克隆为 Harness Mix 管理任务”：
+
+1. 读取允许访问的任务上下文。
+2. 创建新的 Harness Mix Host 任务。
+3. 创建首个 Handoff Checkpoint。
+4. 在原生界面中打开新任务。
+
+这种方式可以在交互上接近接力，但底层是新任务，界面必须明确提示，不能伪装成原官方线程。
+
+使用 Harness Mix 管理的 `Codex（协作）` 时，可以参与真正的同任务跨 Harness 接力。
+
+## 12. 当前实现与推荐方案对比
+
+| 当前实现 | 推荐实现 |
+| --- | --- |
+| 一次性 Prompt 信封 | 持久化 Handoff Checkpoint |
+| 固定截取近期文本 | 紧凑摘要加按需分页读取 |
+| 传递变更文件清单 | 传递 Diff 摘要、哈希和来源 |
+| 工具结果依赖最终回答 | 标准化、脱敏的证据记录 |
+| 信封发送后清除 | 检查点可审计、可重复查询 |
+| 新 Harness 直接继续 | 先核对工作区并确认接管 |
+| 单一接力行为 | 继续、执行方案、审查、重新分析四种模式 |
+
+## 13. 分阶段实施计划
+
+### P0：持久化接力基础
+
+- 定义 `HandoffCheckpoint` 和 `HandoffEvidence` 数据结构。
+- 增加独立、串行化的 Host 存储。
+- 在切换时生成不可变检查点。
+- 保留当前一次性信封作为兼容投影。
+- 使用稳定内容哈希支持去重和审计。
+
+### P1：证据归一化
+
+- 从 Core Item 中抽取测试、命令、错误和文件证据。
+- 统一脱敏、截断和大小限制。
+- 禁止保存凭据、审批状态和可重放工具 ID。
+- 增加证据来源与内容哈希。
+
+### P2：图形化模式与预览
+
+- 在接力弹窗中增加四种接力模式。
+- 增加“将要交接的内容”预览。
+- 展示运行中、检查中、接管成功和失败状态。
+- 保持所有 UI 位于现有原生任务界面。
+
+### P3：按需读取能力
+
+- 实现 Host 侧只读 Handoff API。
+- 对支持原生 MCP 的 Harness 提供受限读取工具。
+- 为其他 Adapter 提供能力映射或明确降级。
+- 增加分页、权限校验和当前任务作用域限制。
+
+### P4：接管确认与恢复
+
+- 目标 Harness 首轮执行确定性工作区核对。
+- 记录目标接管确认和差异。
+- 接管失败时支持重试、切回或更换目标。
+- 重启后保留检查点，但不自动重放可能产生副作用的操作。
+
+### P5：真实桌面验收
+
+- Harness A 给出长方案，Harness B 完整接收并执行。
+- Harness A 产生测试失败证据，Harness B 按需读取并修复。
+- Harness B 修改文件后切回 Harness A 审查。
+- 验证运行中阻止接力、不可用 Harness、接管失败和重启恢复。
+- 验证凭据、审批与原始工具 ID 从未进入检查点。
+- 在真实重启后的 Codex Desktop 中验证选择、弹窗、确认、首轮发送和切回流程。
+
+## 14. 验收标准
+
+推荐方案完成后，应满足：
+
+- 用户不需要输入命令即可完成任务接力。
+- 任务窗口、标题、对话和文件现场保持不变。
+- 最新长方案不会因普通单轮截断而丢失关键内容。
+- 目标 Harness 可以按需读取历史和标准化证据。
+- 工具调用协议和审批状态不会跨 Harness 迁移。
+- 接力检查点可持久化、查询、校验和审计。
+- 不支持按需读取的 Harness 会明确降级，不静默丢失能力。
+- 切回旧 Harness 时恢复其原生会话和模型选项。
+- 所有凭据、权限和审批继续由各原生 Harness 所有。
+- 真实桌面完成 A → B → A 的端到端接力验证。

package/docs/harness-management.md

@@ -18,7 +18,9 @@ CodeBuddy 的旧名称 Workbuddy 自动兼容，已有原生会话 ID 不变。
 | DeepSeek Harness | 原生 Web Remote 模型目录中的供应商 | 在独立、安全隔离的应用窗口中打开 DSH 原生管理页面，进入设置管理供应商 |
 | CodeBuddy / Kiro CLI / Cursor CLI | 可执行文件版本检测；打开会话后读取原生目录 | 在各自 CLI 完成原生登录，再刷新检测；不读取或复制登录凭据 |
 
-Pi / DSH 显示「已配置」而非「已登录」，目录存在不能证明凭据通过在线验证。登录与配置仍使用原生程序自己的账号存储，Harness Mix 不复制账号密钥。当前使用各原生程序的本机账号环境，不提供独立多账号池。
+Pi / DSH 显示「已配置」而非「已登录」，目录存在不能证明凭据通过在线验证。登录与配置仍使用原生程序自己的账号存储，Harness Mix 不复制账号密钥。Codex 例外地支持多个原生隔离档案：默认账号继续使用官方 Desktop 的 `CODEX_HOME`，附加账号各自由 Codex app-server 在独立 `CODEX_HOME` 内完成设备码登录、令牌刷新与额度读取；Harness Mix 只保存档案 ID、显示名和活动选择。
+
+切换 Codex 账号只作用于下一条新任务，不会改写正在运行或已经创建的任务。附加账号的新任务通过 Codex Adapter 固定到创建时的账号档案，因此可以在编辑器账号菜单中无感换号，同时在「账号」设置页并行查看各账号的 5 小时/7 天额度和刷新时间。
 
 修改登录前会检查该 Harness 是否有运行中的任务。Codex 登录连接保留至完成、取消或五分钟超时；关闭设置不会取消浏览器登录，应用退出会取消待完成的登录。
 
@@ -31,14 +33,39 @@ Pi / DSH 显示「已配置」而非「已登录」，目录存在不能证明
 - 选择「跟随原生默认」可清除 Harness Mix 的默认模型覆盖。
 - 配置或登录完成后刷新状态和目录，使新的供应商与模型可见。
 
+## 任务接力
+
+已由 Harness Mix 管理的任务可以在同一个原生任务窗口中更换 Harness。点击输入框旁带接力角标的当前 Harness 图标，选择另一个可用 Harness；确认弹窗会显示接力方向，可选择“继续执行”“执行上一方案”“独立审查”或“重新分析”，并可勾选交接内容、填写可选说明。当前回合仍在运行时需要先停止或等待完成。
+
+接力只关闭当前原生进程并更换底层原生会话，任务标题、可见对话、工作目录、文件变更和 Review 记录不变。Host 会在自己的数据目录中保存不可重放的脱敏检查点，包含对话、计划、标准化工具证据、Core 文件记录以及切换瞬间的 Git HEAD、状态和 Diff 摘要。目标 Harness 收到的下一条真实消息会附带紧凑摘要；支持原生 MCP 的 Harness 可通过只读、当前任务作用域的工具按需读取详细证据，不支持时会明确降级为有界摘要。目标仍需用自己的工具核对真实文件状态。切回用过的 Harness 时，支持恢复的适配器会恢复原生会话及其模型设置。
+
+接力不会传递凭据、环境密钥、审批决定、待审批状态、原始 Tool Call ID 或 Harness 私有协议对象。目标 Harness 的权限请求仍由它自己重新发起，Host 不会自动批准或自动重放操作。
+
+官方 Codex 任务由官方 app-server 直接拥有，不经过 HostRuntime，因此不会显示接力入口；需要使用 Harness Mix 管理的 `Codex（协作）` 才能参与这种跨 Harness 接力。`/switch <Harness 名> [备注]` 继续作为键盘快捷入口。
+
+## MCP 与 Skills
+
+设置页把「MCP」和「Skills」拆成两个独立入口，均可按 Harness 和作用域管理。全局配置适用于该 Harness 的全部项目；项目配置按服务名覆盖全局配置。MCP 使用接近 Codex 的服务器列表与详情编辑流程，支持搜索、逐项添加参数、启停和删除。MCP 只保存 stdio 可执行文件与参数，禁止保存令牌、密码和环境变量。账号与凭据继续由原生 Harness 环境管理。
+
+Harness Mix 不改写各 Harness 已有的 MCP 配置文件。启用的托管配置在新建、恢复、Fork 或回退后的下一次原生会话打开时，通过各 Harness 的原生会话配置接口传入。正在运行的会话不会热改配置。Claude Code 与 OpenCode 可返回原生连接状态和工具名称；其他已接入 Harness 会区分「已配置」「已传入会话」和「连接状态未报告」，不会把保存成功当成已连接。
+
+Skills 从每个 Harness 已声明的原生目录发现：全部 16 个 Harness 都登记了全局/项目根目录，所以设置页不再出现「暂未配置原生技能目录」。根目录来自各 Harness 官方文档与已安装程序自身的扫描代码，例如 Codex 的 `~/.agents/skills` 与兼容保留的 `$CODEX_HOME/skills`、Kiro 专用的 `.kiro/skills`、Trae IDE 的 `.trae/skills` 与 TraeCode CLI 的 `.traecli/skills`、Hermes 的 `~/.hermes/skills`。打开原生会话时会先创建缺失的根目录，已安装但从未运行过的 Harness 也能立即发现技能；某个目录创建失败只会提示并跳过，不会阻止会话打开。可以把单个 Markdown 文件直接拖入并作为 `SKILL.md` 安装，也可以拖入或选择根目录含 `SKILL.md` 的完整技能文件夹。拖入内容经过同一套限制：拒绝路径逃逸、同名覆盖、超过 10 MB 或 500 个文件的技能。原有本机绝对目录安装协议仍兼容。停用会把整个技能目录移动到相邻的 Harness Mix 保留目录，恢复时原样移回；不删除技能内容。共享 `.agents/skills` 的修改会影响读取同一目录的 Harness。
+
+当前 MCP 会话注入支持 Claude Code、Codex（协作入口）、OpenCode、Grok、Antigravity，以及使用通用 ACP 接入的 CodeBuddy、Kiro、Cursor、Qoder 和 Hermes。DSH 配置托管 MCP 后会使用其官方 ACP profile 打开该会话；未配置时仍走 Web Remote。Pi/OMP 的 MCP 扩展机制不是通用原生 MCP 声明，当前只保留已有协作工具注入；设置页会明确显示不支持。每个 Harness 都登记了原生技能根目录，只有链接到其他位置的目录（junction/symlink）保持只读。
+
 ## 验证
 
 ```powershell
 npm run test:native-ui
+npm run test:integrations
+npm run smoke:integrations-ui
+npm run e2e:integrations
 npm run smoke:native-ui
 npm run e2e:native
 ```
 
 `test:native-ui` 覆盖账号字段白名单、模型供应商身份、并发默认值保存、登录连接生命周期和设置页渲染逻辑。`smoke:native-ui` 使用 Electron 与模拟原生响应，检查 Renderer 注入及设置界面的关键交互。
 
+`test:integrations` 覆盖作用域覆盖、持久化、敏感字段拒绝、原生状态投影和 Skills 安装/停用/恢复。`smoke:integrations-ui` 在隔离的 Electron Renderer 中执行设置页完整交互。`e2e:integrations` 默认使用 Claude Code 打开真实原生会话，验证 MCP 连接、工具发现和项目 Skill 加载；可用 `--harness=opencode` 等参数验证其他已安装 Harness。该验收不发送模型消息，也不会自动处理审批。
+
 `e2e:native` 是只读协议验收：读取可用 Harness 与模型目录，不执行登录/退出或修改凭据。完整账号管理和 DSH 原生页面重开仍需在真实 Codex Desktop 重启验收中人工确认，不能由这条命令代替。