@harness-mix/cli 0.1.5 → 0.1.7

package/README.md

@@ -62,70 +62,100 @@ Harness Mix 是接入官方 Codex Desktop 原生界面的本地内核。它通
 </p>
 
 预览来自当前 Codex Desktop 原生窗口：Harness Mix 作为原生扩展入口出现在桌面工具栏和 Composer 中，会话、模型、工具与权限仍由 Codex Desktop 及各 Harness 管理。
-
-## 能做什么
-
-- 在 Codex Desktop 原生输入框中选择 Harness 并发起会话。
-- 流式呈现回答、思考、命令执行、工具调用、文件变更和上下文压缩。
-- 调用每个 Harness 原生提供的模型、权限、上下文用量和快捷指令。
-- 会话中可从原生 Harness 选择器图形化“接力当前任务”：选择目标、接力模式、交接内容和可选说明后确认；会话历史与文件现场保留在 Host 线程上。Host 会持久化脱敏的接力检查点，首轮发送紧凑摘要；支持原生 MCP 的 Harness 还可按当前任务作用域读取历史、计划、文件与测试证据。`/switch <Harness 名> [备注]` 保留为键盘入口；切回旧 Harness 时按其原生机制（Pi `--session` / Claude `resume`）恢复原会话。
-- 原生 Diff、审批与提问组件直接渲染，审批路由回原生 Harness，不代替用户作出权限决定。
-- CodeBuddy、Kiro 和 Cursor 使用原生 ACP 加厂商专用接口：提问、计划确认、配置确认、取消恢复、上下文与历史按各自协议处理。功能和验证范围见下表，不将通用 ACP 能力视为所有 CLI 都已支持。
-- 通过 Adapter 注册新 Harness，UI 侧无需理解厂商协议。
-- 在原生设置中的「MCP / Skills」按 Harness 管理全局/项目 MCP 和已确认的原生 Skills 目录；配置在下一次原生会话打开时生效，凭据和审批继续由原生 Harness 管理。
-
-<p align="center">
-  <img src="docs/images/codex-desktop-session.png" width="960" alt="Codex Desktop 原生会话中的 Harness Mix">
-</p>
 
-## 特色功能：跨 Harness 任务接力
+### 核心特性全景
+
+```mermaid
+flowchart TD
+    subgraph UI["🖥️ Codex Desktop 原生界面"]
+        Composer["Composer 输入框<br/>（# 协同 · 任务接力 · 排队）"]
+        Settings["设置面板<br/>（MCP 服务 · Skills 拖拽安装）"]
+        Sidebar["ChatGPT Web 侧边栏<br/>（上下文安全脱敏注入）"]
+    end
+
+    subgraph Core["⚡ Harness Mix 本地内核"]
+        Shim["CLI Shim<br/>（app-server 协议桥）"]
+        Host["Host Runtime<br/>（会话映射 · 检查点 · 协作编排 · 消息排队）"]
+    end
+
+    subgraph Engines["🤖 原生 Coding Harnesses（16 个已接入）"]
+        H1["Antigravity / Codex"]
+        H2["Claude Code / Pi / OMP"]
+        H3["DeepSeek / Grok / OpenCode"]
+        H4["CodeBuddy / Kiro / Cursor"]
+        H5["Hermes / Qoder / ZCode / Trae / OpenClaw"]
+    end
+
+    UI --> Shim --> Host --> Engines
+```
 
-一个 Harness 负责分析，另一个执行方案，再切回原 Harness 复核——整个过程都留在同一个 Codex Desktop 原生任务窗口中。点击输入框旁带接力角标的 Harness 图标，选择目标 Harness 和接力方式即可，不需要复制 Prompt、另开终端或重新整理上下文。
+| 功能模块 | 核心能力 | 交互入口与特点 |
+| :--- | :--- | :--- |
+| **🔄 跨 Harness 任务接力** | 4 种接力模式（继续执行 / 执行计划 / 独立审查 / 重新分析）平滑交接 | 输入框接力角标 / `/switch`；持久化脱敏检查点与证据追溯 |
+| **🤝 多 Agent 协同编排** | 输入 `#` 唤起目标 Harness，胶囊标签直观管理，主控强约束派发 | 输入框 `#` 菜单；支持循环审查验证、子任务级联取消与超时熔断 |
+| **🧩 原生 Skills 管理** | 全量覆盖 16 个 Harness 原生技能目录，会话启动自动预建根目录 | 设置 → Skills；支持单个 `SKILL.md` 或完整文件夹直接拖拽安装 |
+| **🛠️ 原生 MCP 扩展** | 支持本地 stdio 与远程 Streamable HTTP / SSE 协议 | 设置 → MCP；支持自定义 Header 传递，按 Harness 独立生效 |
+| **📋 原生消息队列** | 完整接入 Codex 会话排队机制（增删改查、排序、插队抢占与自动排空） | 原生 Composer 队列；当前回合完成后自动顺序调度执行排队消息 |
+| **✅ 可配置验证门禁** | 任务级 off / advisory / required 策略，内置一致性检查与自定义验证命令 | 命令面板 `/gate`、`/verify`；强制模式保护隔离分支合并与推送 |
+| **💾 会话存储治理** | schema v3 分片惰性加载、无损紧凑存储、迁移备份与体积诊断 | 冷启动只读任务索引；打开任务时才恢复对应 Core checkpoint |
+| **🌐 ChatGPT 侧边栏桥接** | 安全脱敏提取当前会话上下文并一键生成结构化草稿 | Web 快捷聊天面板；直通注入 ChatGPT，实现跨工具无缝协作 |
+| **👤 账户与用量隔离** | Codex 多账户隔离与即时切换；实时追踪 Token / Credits 用量 | 原生侧边栏与设置面板；各 Harness 凭据、模型与审批原生自理 |
 
-- **现场不丢**：保留任务标题、对话记录、工作目录、未提交文件、Git 状态和 Review 记录。
-- **上下文可追溯**：Host 创建持久化、带内容哈希的接力检查点；目标先收到紧凑摘要，支持原生 MCP 时还可按需读取历史、计划、文件与脱敏测试证据。
-- **四种接力方式**：继续执行、执行上一方案、独立审查、重新分析，可在确认弹窗中选择要交接的内容并补充说明。
-- **可以切回来**：每个 Harness 的原生 Session、模型和选项独立保存；切回时使用其原生恢复能力继续原会话。
-- **原生安全边界不变**：不迁移账号凭据、审批决定、待审批状态、原始 Tool Call ID 或私有协议对象；目标 Harness 必须重新核对真实工作区并自行发起权限请求。
+<p align="center">
+  <img src="docs/images/codex-desktop-session.png" width="960" alt="Codex Desktop 原生会话中的 Harness Mix">
+</p>
 
-不支持按需读取工具的 Harness 会明确退化为有界摘要，不会伪装成完整上下文迁移。完整流程、数据结构和验收边界见 [跨 Harness 接力设计](docs/harness-handoff-design.md) 与 [Harness 管理说明](docs/harness-management.md)。
+## 原生 Harness 功能支持矩阵
+
+> 💡 **设计原则**：所有能力严格在 Adapter `manifest` 中诚实声明，界面按真实能力渲染，不依靠名称猜测。凭据、模型、工具与权限审批始终由原生 Harness 独立掌控。
+
+| Harness | 原生接入协议 | 流式输出 | 思考推理 | 工具审批 | 用户提问 | 会话恢复/Fork | 图片附件 | 原生 Skills | MCP 扩展 |
+| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+| **Antigravity** | `agy` CLI (`stream-json` / Hook) | ✅ | ✅ | ✅ | ✅ | ✅ / ✅ | ✅ | ✅ | ✅ |
+| **Codex** | `codex app-server --stdio` | ✅ | ✅ | ✅ | ✅ | ✅ / ✅ | ✅ | ✅ | ✅ |
+| **Claude Code** | `@anthropic-ai/claude-agent-sdk` | ✅ | ✅ | ✅ | ✅ | ✅ / ✅ | ✅ | ✅ | ✅ |
+| **Pi** | `pi --mode rpc` | ✅ | ✅ | ✅ | ✅ | ✅ / ✅ | ✅ | ✅ | ➖ |
+| **Oh My Pi** | `omp --mode rpc` (`pi-family.js`) | ✅ | ✅ | ✅ | ✅ | ✅ / ✅ | ✅ | ✅ | ➖ |
+| **DeepSeek** | 普通 Web Remote / 协作 ACP | ✅ | ✅ | ✅ | ✅ | ✅ / ✅ | ✅ | ✅ | ✅ |
+| **OpenCode** | `opencode serve` (HTTP / SSE) | ✅ | ✅ | ✅ | ✅ | ✅ / ✅ | ✅ | ✅ | ✅ |
+| **Grok** | `grok agent stdio` (`_x.ai/*`) | ✅ | ✅ | ✅ | ✅ | ✅ / ✅ | ✅ | ✅ | ✅ |
+| **OpenClaw** | Gateway WebSocket Loopback | ✅ | ➖ | ✅ | ➖ | ✅ / ➖ | ✅ | ✅ | ➖ |
+| **Hermes** | `hermes acp` | ✅ | ✅ | ✅ | ✅ | ✅ / ✅ | ➖ | ✅ | ✅ |
+| **CodeBuddy** | `codebuddy --acp` (`_codebuddy.ai/*`) | ✅ | ✅ | ✅ | ✅ | ✅ / ➖ | ✅ | ✅ | ✅ |
+| **Kiro CLI** | `kiro-cli acp` (`_kiro/*`) | ✅ | ✅ | ✅ | ✅ | ✅ / ✅ | ➖ | ✅ | ✅ |
+| **Cursor CLI** | `cursor-agent acp` (`cursor/*`) | ✅ | ✅ | ✅ | ✅ | ✅ / ➖ | ➖ | ✅ | ✅ |
+| **Qoder** | `qoder --acp` | ✅ | ➖ | ✅ | ➖ | ✅ / ➖ | ✅ | ✅ | ✅ |
+| **ZCode** | 兼容 ACP 桥接程序 | ✅ | ➖ | ✅ | ➖ | ✅ / ➖ | ➖ | ✅ | ✅ |
+| **Trae** | 兼容 ACP 桥接程序 | ✅ | ➖ | ✅ | ➖ | ✅ / ➖ | ➖ | ✅ | ✅ |
+
+<sub>注：✅ 为原生支持并已打通；➖ 为上游协议当前未开放或未声明；只有本机已安装且握手成功的 Harness 才会进入真实运行。详见 [原生 ACP 深度适配](docs/native-acp.md) 与 [Harness 管理说明](docs/harness-management.md)。</sub>
+
+## 核心功能特色
+
+### 🔄 跨 Harness 任务接力（Task Handoff）
+一个 Harness 负责深入分析，另一个编写具体实现，再切回原 Harness 交叉复核——整个过程无缝保留在同一个 Codex Desktop 原生窗口中：
+- **现场完整保留**：保留对话历史、未提交代码改动、Git 状态与 Review 记录。
+- **持久化检查点**：创建带哈希的接力快照，自动脱敏测试证据与敏感密钥，支持随时暂停与恢复。
+- **独立会话恢复**：每个 Harness 的原生 Session 与参数独立保存，切回时调用其原生恢复机制（如 Pi `--session` 或 Claude `resume`）。
+- **四种接力方式**：支持「继续执行」、「执行上一方案」、「独立审查」与「重新分析」。
+
+### 🤝 多 Agent 协同编排（Multi-Agent Collaboration）
+- **触发符解耦**：在原生输入框输入 `#` 调出协同菜单（`#pi`、`#claude`、`#codex`、`#dsh`），完全保留官方 `@` 菜单给 Codex 原生功能。
+- **标签可视化**：已选协同 Agent 在输入框顶部呈现为胶囊标签，支持点击快速删除或 Backspace 撤销。
+- **严谨编排约束**：自动为主控 Coordinator 注入硬约束，严禁越界派发给未指定的 Harness；完善级联取消与子任务超时熔断机制。
+
+### 🧩 原生 Skills 与 MCP 管理
+- **16 平台免配置预建**：打开会话时自动预建全部 16 个 Harness 声明的原生 Skills 根目录，新安装 Harness 也能即开即用。
+- **拖拽安装**：在「设置 → Skills」中可将单个 `SKILL.md` 或完整技能文件夹直接拖拽安装，自带安全路径校验。
+- **作用域与安全停用**：支持 Global（全局）与 Project（项目级）无缝切换；停用时安全移入保留目录，绝不损坏用户源文件。
+- **远程 MCP 支持**：支持配置带自定义 Headers 的 Streamable HTTP / SSE 远程服务。
 
-## 原生接入
-
-通过 Codex Desktop 内的 Harness 选择器统一查看连接、筛选模型和保存每个 Harness 的新对话默认模型。具体流程与原生边界见 [Harness 管理说明](docs/harness-management.md)。
-
-| Harness | 原生接口 | 当前接入重点 |
-| --- | --- | --- |
-| Antigravity | `agy` CLI (`stream-json` / PreToolUse Hook) | 流式输出、Gemini 模型目录与思考档位、Desktop 审批与提问桥接、文件变更、配额查询与 Fork |
-| Codex | `codex app-server --stdio` | Thread / Turn / Item、流式事件、审批、Usage、Resume、Fork、Compact |
-| 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`；协作主任务 `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 | `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 名称猜测功能；厂商特有字段会保留在原生引用和载荷中。
-
 ## 本地运行
 
 开发环境需要 Windows、macOS 或 Linux，近期 Node.js LTS 和 npm。应用不会读取或保存 Harness 的账户密钥，请先在对应的原生 CLI 中完成安装与登录；平台前提和真机验收范围见 [跨平台指南](docs/cross-platform.md)。
-
-```powershell
-git clone https://github.com/emo-xiaoyu/harness-mix.git
-cd harness-mix
+```powershell
+git clone https://github.com/emo-xiaoyu/harness-mix.git
+cd harness-mix
 npm install
 ```
 

package/docs/harness-management.md

@@ -43,15 +43,15 @@ Pi / DSH 显示「已配置」而非「已登录」，目录存在不能证明
 
 官方 Codex 任务由官方 app-server 直接拥有，不经过 HostRuntime，因此不会显示接力入口；需要使用 Harness Mix 管理的 `Codex（协作）` 才能参与这种跨 Harness 接力。`/switch <Harness 名> [备注]` 继续作为键盘快捷入口。
 
-## MCP / Skills
+## MCP 与 Skills
 
-设置页的「MCP / Skills」按 Harness 和作用域管理扩展。全局配置适用于该 Harness 的全部项目；项目配置按服务名覆盖全局配置。MCP 只保存 stdio 可执行文件与参数，禁止保存令牌、密码和环境变量。账号与凭据继续由原生 Harness 环境管理。
+设置页把「MCP」和「Skills」拆成两个独立入口，均可按 Harness 和作用域管理。全局配置适用于该 Harness 的全部项目；项目配置按服务名覆盖全局配置。MCP 使用接近 Codex 的服务器列表与详情编辑流程，支持搜索、逐项添加参数、启停和删除。MCP 只保存 stdio 可执行文件与参数，禁止保存令牌、密码和环境变量。账号与凭据继续由原生 Harness 环境管理。
 
 Harness Mix 不改写各 Harness 已有的 MCP 配置文件。启用的托管配置在新建、恢复、Fork 或回退后的下一次原生会话打开时，通过各 Harness 的原生会话配置接口传入。正在运行的会话不会热改配置。Claude Code 与 OpenCode 可返回原生连接状态和工具名称；其他已接入 Harness 会区分「已配置」「已传入会话」和「连接状态未报告」，不会把保存成功当成已连接。
 
-Skills 从已确认的原生目录发现：Claude Code、Codex、Pi 和 OpenCode 支持全局或项目目录。安装只接受本机绝对目录、必须包含 `SKILL.md`，拒绝符号链接、同名覆盖、超过 10 MB 或 500 个文件的目录。停用会把整个技能目录移动到相邻的 Harness Mix 保留目录，恢复时原样移回；不删除技能内容。共享 `.agents/skills` 的修改会影响读取同一目录的 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 不提供文件写入操作。
+当前 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）保持只读。
 
 ## 验证
 

package/docs/multi-agent-collaboration.md

@@ -2,16 +2,16 @@
 
 ## 用法
 
-重新启动 Harness Mix 后，新建或恢复一个 Pi / Oh My Pi / Claude Code / **Codex（协作）** / Grok / OpenCode / **Antigravity** 任务，输入 `@`，在 **Agents** 页选择目标 Harness；**会话** 页单独提供历史引用。左右键切换分页，上下键选择，Enter/Tab 插入。Codex（协作）通过 Host Adapter 使用原生 app-server；原来的 Codex 入口仍为官方直通。可用目标来自 Host 注册的 Adapter；未就绪的目标不可选。示例：
+重新启动 Harness Mix 后，新建或恢复一个 Pi / Oh My Pi / Claude Code / **Codex（协作）** / Grok / OpenCode / **Antigravity** 任务，在原生输入框中输入 `#`，在 **Agents** 页选择目标 Harness；**会话** 页单独提供历史引用。已选 Agent 以内联标签显示在输入框顶部，可点击或在光标位于正文开头时按 Backspace 移除。左右键切换分页，上下键选择，Enter/Tab 插入，Escape 关闭。`@` 保留给 Codex 原生功能，不会调出 Harness Mix 协作选择器。Codex（协作）通过 Host Adapter 使用原生 app-server；原来的 Codex 入口仍为官方直通。可用目标来自 Host 注册的 Adapter；未就绪的目标不可选。示例：
 
 ```text
 你负责实现后端。
-@claude-code 审查 API 设计，只读，不修改文件。
-@pi 为 tests/ 编写测试，不修改 src/。
+#claude-code 审查 API 设计，只读，不修改文件。
+#pi 为 tests/ 编写测试，不修改 src/。
 收齐结果后由你运行验证并总结。
 ```
 
-也可直接输入 `@pi`、`@claude`、`@dsh`、`@codex` 等已注册 ID/别名。显式 `[名称](harness-mix://agent/pi)` 引用可随草稿复制；代码块、行内代码和邮箱里的 @ 不作为路由元数据。提及本身由主模型结合用户任务理解，Host 不按文字片段盲目拆任务。
+也可直接输入 `#pi`、`#claude`、`#dsh`、`#codex` 等已注册 ID/别名。显式 `[名称](harness-mix://agent/pi)` 引用可随草稿复制；代码块和行内代码中的 `#` 不作为路由元数据。选择本身由主模型结合用户任务理解，Host 不按文字片段盲目拆任务。
 
 ## 执行方式
 
@@ -44,12 +44,12 @@
 | Pi 主任务 | 原生扩展工具；Pi→Pi、Pi→Claude 两条真实模型链路通过 |
 | Claude Code 主任务 | SDK MCP 注入；本机真实运行触发原生工具审批，未代答，尚未完成模型闭环验收 |
 | Oh My Pi 主任务 | 同 Pi 家族的扩展接线；本机未安装 OMP，真实验收未完成 |
-| Codex（协作）主任务 | 已接入选择器、模型/强度、恢复归属、@ 菜单；桌面使用配套 CLI。真实请求已到原生 MCP 审批，尚未完成需授权的闭环 |
+| 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 接线等同于已支持这个入口 |
+| 官方 Codex 桌面直通任务 | 保持官方直通，不展示 Host 的 # 协作菜单；不要把 Adapter 接线等同于已支持这个入口 |
 | 其他 Harness 主任务 | Agents 页明确提示需要切换可编排的主 Agent，目标不可选；历史引用仍可用；可使用旧 /delegate |
 | 子任务目标 | 所有已注册且本机可用的 Adapter；不代表每一对组合都已实测 |
 
@@ -72,11 +72,11 @@ npm run build:native
 
 设置 → 会话导入 → 全部历史，支持按标题、目录和会话 ID 搜索、分页、导入并打开。Pi、Claude、Codex 从本机原生历史发现会话；其余 Harness 当前聚合 Host 已管理的历史，并在来源名称上标为「Host 历史」，尚未接入各自 CLI 的外部会话扫描。
 
-导入只创建投影和原生会话引用，不启动模型；再次发送时原生恢复。重复导入返回同一任务。输入 `@` 可从「会话」页选择一条记录；Host 最多读取三条引用，每条只附加最近十二条用户/助手文本，并明确标记为不可执行的历史数据。引用不会创建、恢复或占用原生会话。原始完整工具、隐藏状态和分支数据仍留在原生存储，因此这不是原生历史的无损迁移。原生运行状态未知时，应先关闭其他客户端的同一会话。
+导入只创建投影和原生会话引用，不启动模型；再次发送时原生恢复。重复导入返回同一任务。输入 `#` 可从「会话」页选择一条记录；Host 最多读取三条引用，每条只附加最近十二条用户/助手文本，并明确标记为不可执行的历史数据。引用不会创建、恢复或占用原生会话。原始完整工具、隐藏状态和分支数据仍留在原生存储，因此这不是原生历史的无损迁移。原生运行状态未知时，应先关闭其他客户端的同一会话。
 
 ## 2026-09-11 Codeg 协作流程修复
 
-- Agents 与历史会话分栏，修复原生 @ 大菜单与协作菜单同时弹出；提示不可用主 Agent 的能力边界。
+- Agents 与历史会话分栏，使用 `#` 调出协作菜单，`@` 保留给原生功能；提示不可用主 Agent 的能力边界。
 - 默认共享目录，使开发与审查读取同一份实际文件；保留显式隔离工作区。多任务等待在任一结果可收取时返回。
 - 新增可更新的原生计划，子任务卡片投影真实会话 ID 与 Harness 名称，跟进复用原会话。
 - 实测 Pi 主任务 + 两个独立 Pi 原生子会话：开发者写入错误样本 41 → 审查者 REVIEW_FAIL → message_agent 交回原开发者修为 42 → 原审查者 REVIEW_PASS → 主模型完成计划并汇总。测试验证文件实际导出值以及两个会话均收到跟进。日志：`output/collaboration-cycle.log`。
@@ -86,4 +86,4 @@ npm run build:native
 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`。
+桌面实测与隔离增强：Pi 主 Agent 切换、Agents/会话切页、Claude 选择精确插入、图标标识和草稿清理通过。原生协作卡片已实装「↗ 查看 Agent 会话」跳转子任务 Thread、「🔍 查看产物 Diff」语法高亮展开与「✓ 合并改动到主项目」操作；Worktree 隔离环境已实装补丁冲突结构化指引、`discardWorkspace` 一键丢弃临时分支与 `pushWorkspace` 远程分支推送协议支持。截图与报告在 `output/collaboration-ui/desktop-*.png` 和 `desktop-report.json`。

package/docs/storage-verification-design.md

@@ -0,0 +1,49 @@
+# 会话存储与验证门禁设计
+
+状态：已实现第二阶段（2026-09-15）。
+
+## 目标与边界
+
+会话存储必须长期可恢复，且不能通过截断对话或工具证据换取表面上的体积下降。验证门禁负责判断一次任务是否达到用户配置的交付标准，但不改变原生 Harness 的回合、权限或审批结果。
+
+## 会话存储 schema v2
+
+`threads.json` 从无版本数组升级为 `{ schemaVersion, savedAt, threads }`。加载器继续接受旧数组并在首次保存时迁移；覆盖前保存 `threads.json.bak`，写入仍使用临时文件和原子替换。
+
+Core checkpoint 是历史的唯一执行投影。保存时移除可以从 Core 无损重建的 `message.coreTurn`、`message.coreItems`、助手文本、工具列表、Usage 和当前回合视图，启动时由 `CoreSession.sync()` 恢复。这消除了同一回答、Reasoning 和工具输出在 `messages`、`tools` 与 `coreState` 中的重复，不删除用户输入、附件元数据、Review 引用或原生 Session 引用。载入完成后会释放原始 `coreState` 副本，仅在保存快照期间短暂生成，避免常驻内存同时保留 Core 与完整 checkpoint 两份状态。
+
+Host 提供：
+
+- `codexhost/storage/inspect`：返回文件大小、逻辑大小、紧凑后大小以及最大的 20 个任务。
+- `codexhost/storage/optimize`：显式重写为当前 schema，并返回优化前后统计。
+
+## 分片存储 schema v3
+
+首次保存 v2 后，Host 会生成 `threads/index.json` 和 `threads/records/<threadId>.json`。旧 `threads.json` 不删除，并额外保留 `threads.json.bak`。索引只包含侧栏所需的标题、Harness、路径、时间、状态、首条预览和记录大小；冷启动只读取索引。`thread/read`、发送、接力或配置等首次真正访问任务的操作才同步载入该任务记录并恢复它的 Core checkpoint。
+
+保存时只重写已经载入的任务记录，未打开任务不会被读取或重写；索引最后原子替换，因此中途失败仍保留上一份可用索引。删除任务时在索引成功保存后删除对应记录文件。
+
+## 任务级验证门禁
+
+策略包含：
+
+- `mode`: `off`、`advisory` 或 `required`。
+- `autoRun`: 回合和文件 Review 结算后自动运行。
+- 内置检查：回合成功、无待处理交互、无运行中工具、Review 无错误、可选 Git 工作区干净。
+- 最多八条用户显式配置的验证命令，每条具有 1 秒至 10 分钟超时。
+
+命令仅在任务工作目录执行，输出各保留末尾 16,000 字符并经统一脱敏器处理；包含疑似明文凭据的命令会被拒绝，应由原生进程环境提供所需认证。报告持久化退出码、超时、耗时和有界 stdout/stderr。`advisory` 仅报告；`required` 的最新报告必须属于当前最后一轮且成功，才能合并或推送隔离工作区。新回合会自然令旧报告失效。
+
+Host 方法：
+
+- `codexhost/thread/verification/get`
+- `codexhost/thread/verification/configure`
+- `codexhost/thread/verification/run`
+
+原生命令面板提供 `/verify`、`/gate-required`、`/gate-advisory` 和 `/gate-off`。完整配置可以直接输入，例如 `/gate required --auto --clean -- npm run test:ci`；也可以通过 Host 协议写入多条命令。
+
+每次运行还会向对应的终态 Turn 投影一个 `verification_report` Core Item。Desktop 将它显示为 Harness Mix 验证工具卡片；接力检查点会把该报告作为脱敏的 `verification` 证据携带。重复验证更新同一回合的报告，不制造重复卡片。
+
+## 后续阶段
+
+下一阶段应增加设置页中的图形化策略编辑器和报告详情视图，并用真实大体积数据副本记录冷启动 RSS、索引加载耗时、单任务水合耗时与增量保存耗时。只有真实重启后的 Desktop 验收完成，才能宣称 UI 完整交付。