@luchenglong/cli-bridge 0.2.8 → 0.2.10

package/CHANGELOG.md

@@ -9,6 +9,97 @@ GitHub Release（`scripts/verify.mjs` 在 CI 与 prepack 双重锁一致）。
 > - CodeBuddy 线：[docs/history/codebuddy/CHANGELOG.md](docs/history/codebuddy/CHANGELOG.md)（终版 1.6.2）
 > - MiMo 线：[docs/history/mimo/CHANGELOG.md](docs/history/mimo/CHANGELOG.md)（终版 1.2.9）
 
+## [0.2.10] - 2026-10-20
+
+> ⚠️ **0.2.9 的 dynamic 沙箱形态在 opencode / mimo 两家是坏的**，本版修复。若你在用这两家的
+> dynamic 形态，请升级。
+
+### Fixed
+- **`dynamic/opencode.host.js` 与 `dynamic/mimo.host.js` 运行即 `ReferenceError`**（0.2.9 已发布）。
+  根因：这两家的代码被拆进片文件（`opencode-exe.mjs` / `mimo-pure.mjs`）后，它们的 dynamic
+  **模板里漏了片文件占位标记**，build 只在模板声明占位时才内联片文件 —— 于是生成物里
+  `candidateExePaths` / `parseMimoJson` 只有引用、没有定义。实测证据：修前 `apply()` 直接抛
+  `ReferenceError: candidateExePaths is not defined`；修后两家 `apply()` 正常。
+  已补占位并重建，生成物内符号定义数 0 → 1。
+- **新增永久防线**：`tests/{opencode,mimo}/dynamic-template.test.mjs` 断言生成物里片文件符号
+  **"定义数 = 1"**（而不是"出现过"）—— 纯求值检查抓不到这类缺陷，因为未定义标识符只在函数
+  被调用时才炸。
+- **EOL 与 `.gitattributes` 不一致**：`providers/codebuddy*.mjs` 等工作区曾被写成 CRLF
+  （PowerShell 默认行为），而仓库要求 `eol=lf`，导致生成物按 CRLF 源拼出、别的机器 clone 后
+  `build --check` 必然 drift（`dynamic/codebuddy.host.js` 甚至被 git 当二进制）。
+  已规范化全部源码为 LF 并重建；`git ls-files --eol` 复核全部 `w/lf`。
+
+### Added
+- **模型下拉改为「手动拉取」（契约 §3.2）** —— 用户反馈 codebuddy 各产品面都自动拿不到可用
+  清单，希望加刷新按钮、每次手动拉取：
+  - `settings.meta()` **不再自动探测**（面板同步回调，探测会拖慢首屏；且探不到时下拉空着，
+    用户分不清"没模型"与"没拉到"）。现在只读缓存，字段声明 `refresh: { label }` 即渲染按钮。
+  - 新增可选契约 `settings.refreshModels(settings, env) → { ok, ids, labels?, source, error? }`，
+    已由 5 家实现（codebuddy / opencode / mimo / claude / codex）；agy 无模型字段故不适用。
+  - 新端点 `POST /cli-bridge/settings/models`（body `{provider}`）：**业务失败恒返回 HTTP 200**
+    + `{ok:false, error}`，不用 4xx/5xx —— 否则前端容易把"没拉到"当网络故障静默吞掉。
+  - `client.js` 渲染「拉取可用模型」按钮 + 进行中态 + 结果/错误文本；拿到 options 只更新展示态，
+    用户选中仍走原有 POST 保存。
+  - 各家的 `source` 如实标注（`account-live` / `live` / `opencode-models` / `mimo-models`）。
+
+### 说明（各团队实测发现并修掉的真缺陷）
+- claude：异步探测在 spawn 失败时 `error` 与 `close` 各推进一次候选游标，会**跳过后面能跑的
+  候选**（用户填错 binPath 就再也走不到有效 exe）；已加 per-attempt 守卫 + 回归钉子。
+- codex：live `GET /models` 无超时，端点卡住会让面板一直转圈；已加 AbortController 上界（20s）。
+- codebuddy/claude：`meta()` 与 `refreshModels` 的"产品面/缓存键"口径必须同源，否则会出现
+  「刷新成功但下拉仍空」。已统一取值来源并各加用例。
+- codebuddy：探测进程的环境曾硬编码 `process.env`，不尊重调用者传入的 env，导致测试无法隔离
+  （会回落到本机真实 CLI 并"假装成功"）。现传入 env 可覆盖。
+
+## [0.2.9] - 2026-10-20
+
+### Added
+- **两家新 provider：`claude`（Claude Code）与 `codex`（OpenAI Codex CLI）**，四形态全覆盖
+  （描述符 / 持久 Agent Preset / dynamic 沙箱宿主 / MCP 工具面），`PROVIDER_IDS` 由 4 家扩到 6 家：
+  - `claude`：工具 `claude_run` / `claude_continue` / `claude_status` + `claude_models`；
+    preset `claude-first`。走 `-p --output-format stream-json --verbose`，从 `system`/`assistant`/
+    `result` 事件折叠实时步骤；sessionId 取 `result.session_id`，续聊走 `--resume`。
+  - `codex`：工具 `codex_run` / `codex_continue` / `codex_status` + `codex_models`；
+    preset `codex-first`。走 `exec --json`，从 `thread.started`/`turn.started`/`item.completed`/
+    `turn.completed` 折叠；sessionId 取 `thread_id`，续聊走 `exec resume <id>`。
+  - 两者默认权限都按「非交互无 TTY」处理（claude `--dangerously-skip-permissions`；codex
+    `-c approval_policy` + `sandbox_mode`），并把可选项暴露成设置项
+    （claude `maxBudgetUsd`；codex `sandboxMode` / `approvalPolicy`）。
+- **模型清单一律实时、绝不冒充**（延续 0.2.6/0.2.7 对 codebuddy 的整改纪律）：
+  - `claude_models` 唯一权威来源 = 无效模型触发的服务端 400 报文
+    （「The supported API model names are …」），实测本机为 `deepseek-flash, deepseek-v4-pro`；
+    `~/.claude/settings.json` 里配置的 `ANTHROPIC_DEFAULT_*_MODEL` 只作诊断线索，不进可用清单。
+  - `codex_models` 默认只走 live（`GET {base_url}/models` + Bearer，实测 OpenRouter 返回 469 项；
+    过滤后可对话的 80 项）；本地 `model_catalog_json` / `models.json` 仅在**显式**
+    `source=catalog|builtin` 时返回并逐项标注，绝不冒充实时。任何失败（含 200 但 0 个模型、
+    畸形载荷、401）一律 `ok:false` + 可操作错误。
+
+### Changed
+- **`PRESET_DIRS`（provider id → `preset/<dir>/`）统一为单一来源**：原先在
+  `scripts/build.mjs`、`home-plugin/.../preset-declarations.mjs`、`scripts/verify.mjs`
+  各硬编码一份，新增 provider 漏改任一处就会出现「产物静默不生成」或误导性的
+  「plugin-list missing」。现统一从 `providers/registry.mjs` 导入，加第 N 家 provider 三处零改动。
+- **keystone 测试去掉同类硬编码**（否则新预设静默不被覆盖）：
+  `tests/keystone/scheduling-gate.test.mjs` 的 apply 映射改为按 `PRESET_DIRS` 动态 import；
+  `tests/keystone/preset-config-contract.test.mjs` 与 `persona-prompt-vars.test.mjs`
+  的目录清单改为从 registry 派生 —— 现在自动覆盖全部 7 个 preset（含 `claude-first` /
+  `codex-first` / 成员预设 `mimo-member`）。
+- `package.json` description 更新为六家；`.snapshot-backup*/` 加入 `.gitignore` 并移出 git 索引。
+
+### Fixed
+- `home-plugin/cli-bridge-indicator/lib/client.js` 由 606 行压到 600 行（红线内）。压缩只用
+  无损手段（合并重复的头部叙述、删一处多余空行）；**保留红线 4**：`__ModuleLoader__.load({ id })`
+  逐字等于包名，`tests/keystone/client-ui-surface.test.mjs` 的「声明必须存在」守卫未被削弱
+  （曾尝试把两张查表合并成一条声明，会破坏该守卫的正则，已回退）。
+
+### 说明（实测更正，防回归）
+codex 团队用真实 CLI 更正了三处易错事实，已在描述符里加防线并有单测钉死：
+1. `codex exec` **不接受** `-a/--ask-for-approval`（那是根命令的旗）→ 审批只能
+   `-c approval_policy="…"`；
+2. `codex exec resume` **没有** `-C/-s/-o/--add-dir` → cwd 交 spawn、沙箱走 `-c sandbox_mode="…"`；
+3. `item.completed` 里 `item.type==="error"` 是**告警**（续聊会带一条「原模型与当前模型不同」），
+   不是致命错；成功判据 = 退出码 0 + 收到 `turn.completed` + 无顶层错误。
+
 ## [0.2.8] - 2026-10-18
 
 > 用户使用 agy 优先模式时整轮失败：

package/PROVIDER-CONTRACT.md

@@ -8,10 +8,18 @@
 
 ## 0. 命名与硬约束（红线）
 
-- provider id（全小写，用于事件通道/设置分区/文件名/工具名）：`agy` | `codebuddy` | `mimo`。
-- preset id（保持旧包不变，旧会话头引用）：`cordis-agy` | `codebuddy-first` | `cordis-mimo`。
-- 模型工具名（保持旧包不变）：`agy_run/agy_continue/agy_status(/agy_quota)`、
-  `codebuddy_run/codebuddy_continue/codebuddy_status`、`mimo_run/mimo_continue/mimo_status(/mimo_settings)`。
+- provider id（全小写，用于事件通道/设置分区/文件名/工具名）：
+  `agy` | `codebuddy` | `mimo` | `opencode` | `claude` | `codex`。
+  **唯一 id 轴 = `providers/registry.mjs` 的 `PROVIDER_IDS`**；preset 目录映射的
+  **唯一来源**是同文件的 `PRESET_DIRS`（`build.mjs` / `preset-declarations.mjs` /
+  `verify.mjs` 都从它导入，**禁止**再各写一份——漏改会静默不产物或报误导性错误）。
+- preset id：`cordis-agy` | `codebuddy-first` | `cordis-mimo`（三家旧包，**保持旧值不变**，
+  旧会话头引用）；`opencode-first` | `claude-first` | `codex-first`（本包新增，直接用
+  `<id>-first`）。注意 preset **目录名**与 presetId 不一定相同（agy/mimo 是旧包历史遗留）。
+- 工具名（旧包语义逐字保持）：`agy_run/agy_continue/agy_status(/agy_quota)`、
+  `codebuddy_run/codebuddy_continue/codebuddy_status(/codebuddy_models)`、
+  `mimo_run/mimo_continue/mimo_status(/mimo_settings)`、`opencode_run/…(/opencode_models)`、
+  `claude_run/…(/claude_models)`、`codex_run/…(/codex_models)`。
 - 客户端契约（红线 4）：浏览器半注册 id **必须**等于包名 `@luchenglong/cli-bridge`；
   该文件是 keystone（`home-plugin/cli-bridge-indicator/lib/client.js`），provider 作者**不碰**。
 - 动态沙箱形态禁止 `import/require`；派生文件一律由 `node scripts/build.mjs` 生成，
@@ -126,13 +134,46 @@ meta(env) → {
     allowCustom?: boolean,       // select 允许自定义输入（defaultModel 就是它）
     placeholder?: string,
     note?: string,               // 字段下方说明
-    secret?: boolean             // 凭据字段：必须同时列入 secretKeys
+    secret?: boolean,            // 凭据字段：必须同时列入 secretKeys
+    refresh?: {                  // 可选：给 select 加「手动拉取」按钮（见 §3.2）
+      label?: string             //   按钮文案，缺省「拉取可用项」
+    }
   } ]
 }
 ```
 
 diagnose(settings, env) 返回一行文本（卡片底部「诊断」区）；无诊断给 ''。
 
+### 3.2 手动拉取（`refreshModels`）—— 面板不自动探测
+
+**背景**：模型可用列表只能问服务端/端点，而"问"要起子进程、可能联网、可能因为某个
+产品面没登录而失败。早期做法是在 `meta()` 里同步探针（`spawnSync` + 缓存），带来两个问题：
+① 面板首屏可能被拖慢；② 探不到时下拉空着，用户无法区分"没模型"与"没拉到"。
+
+**现在**：`meta()` **只读缓存、绝不主动探测**；探测改由用户点按钮显式触发。
+provider 若希望自己的某个 select 字段支持手动拉取，则：
+
+1. 在 `meta()` 的该字段上加 `refresh: { label: '拉取可用模型' }`；
+2. 实现 `settings.refreshModels(settings, env)`（**可选**，async）：
+
+```
+refreshModels(settings, env) → Promise<{
+  ok: boolean,
+  ids?: string[],        // 可用项 id（keystone 转成 options:[{value,label}]）
+  labels?: object,       // 可选：id → 展示文案
+  source?: string,       // 数据来源标注，面板会显示（如 'account-live' / 'live'）
+  error?: string         // ok:false 时必填且要可行动（告诉用户下一步怎么做）
+}>
+```
+
+**铁律**：探测失败必须 `ok:false` + 可操作错误，**绝不**返回 `{ok:true, ids:[]}`
+或把静态表冒充成权威清单（这是本项目反复踩过的坑，0.2.6~0.2.9 都在修它）。
+
+keystone 提供端点 `POST /cli-bridge/settings/models`（body `{ provider: '<id>' }`），
+固定返回 HTTP 200 + `{ ok, provider, options, source, error }` —— 用 `ok` 表达业务失败，
+不用 HTTP 状态码，以免前端把"没拉到"当成网络错误而静默。client.js 渲染按钮、处理 loading
+与错误展示，并把拿到的 options 合并进当前字段（不落盘，纯展示态；用户选中后照常走 POST 保存）。
+
 ### 3.1 调度区（顶层 `_scheduling`，非 provider 分区 —— 新增 provider 零改动接入）
 
 `{DSH_HOME}/cli-bridge-settings.json` 顶层另有 `_scheduling` 区（下划线前缀 = 非 provider
@@ -233,3 +274,44 @@ export function check(env) → true | throw                             // --che
   node: 模块，dynamic 沙箱形态若拿不到 fetch 则 preflight 报 `DESKTOP_UNREACHABLE`
   并提示改用 mimocode 后端（保持旧包语义）。
 
+## 10. claude / codex 的实测事实（0.2.9 接入，改动前必读）
+
+两家都是**在真机上跑出来的**，下面每条都有单测或 `check()` 防线钉住，别凭直觉"顺手修正"。
+
+### claude（Claude Code，实测 2.0.76）
+- 非交互：`claude -p <prompt> --output-format text|json|stream-json [--verbose]`。
+  `stream-json` 必须配 `--verbose`，否则只吐结果不吐事件。
+- 事件：`system`（含 `session_id` / `model` / `tools` / `permissionMode` / `apiKeySource`）→
+  `assistant`（`message`）→ `result`（`subtype` / `is_error` / `result` / `session_id` /
+  `total_cost_usd` / `usage` / `modelUsage`）。
+- **成功判定陷阱**：`is_error=true` 时退出码可能是 0 也可能是 1，且 `subtype` 仍可能是
+  `"success"`（无效模型实测就是这个形状）。判定必须 `is_error === false && exitCode === 0`。
+- 续聊：`--resume <session_id>` / `-c|--continue` / `--fork-session`。
+- 模型清单：**唯一权威来源 = 无效模型触发的服务端 400 报文**
+  `"The supported API model names are X, Y, ..."`。`~/.claude/settings.json` 的 env 块里
+  `ANTHROPIC_DEFAULT_*_MODEL` / `ANTHROPIC_MODEL` 是**用户配置的别名映射，不是服务端可用
+  全集**（实测两者不一致），只能作诊断线索。
+- 权限：`-p` 无 TTY，任何需要交互批准的动作都会挂到超时，故 auto 模式映射为
+  `--dangerously-skip-permissions`（或 plan 态 `--permission-mode plan`）。
+
+### codex（OpenAI Codex CLI，实测 0.98.0）
+- 非交互：`codex exec [opts] <prompt>`；`--json` 出事件流，不加就是纯文本。
+- 事件：`thread.started`（`thread_id`）→ `turn.started` → `item.completed`（`item`）→
+  `turn.completed`（`usage`）。
+- **`codex exec` 不接受 `-a/--ask-for-approval`**（那是根命令 `codex` 的旗，clap 会报
+  unexpected argument）→ 审批只能 `-c approval_policy="…"`。
+- **`codex exec resume` 不支持 `-C/-s/-o/--add-dir`** → cwd 交给 spawn 的 `cwd`，
+  沙箱走 `-c sandbox_mode="…"`。
+- **`item.completed` 里 `item.type==="error"` 是告警，不是致命错**（`resume --last` 会带一条
+  「此会话原模型与当前模型不同」）。致命只有顶层 `error` / `turn.failed`；
+  成功判据 = 退出码 0 + 收到 `turn.completed` + 无顶层错误。
+- 非 git 目录必须 `--skip-git-repo-check`。
+- 退出码：0 成功；1 运行错误（stdout 仍是合法事件流）；2 参数错误。
+- 配置/凭据：`~/.codex/config.toml`（`model` / `model_provider` /
+  `[model_providers.<name>]` 的 `base_url` + `experimental_bearer_token` /
+  `model_catalog_json`）、`~/.codex/auth.json`（`OPENAI_API_KEY` / `OPENAI_BASE_URL`）；
+  `CODEX_HOME` 可覆盖目录。**模型清单默认只走 live**（`GET {base_url}/models`），
+  本地 `model_catalog_json` / `models.json` 仅在显式 `source=catalog|builtin` 时返回。
+- npm 全局安装得到的是 `.cmd` shim：无 shell 时 spawn 不了，走 shell 会把 prompt 二次解释。
+  因此命中 `.cmd/.bat` 时**明确报错并指引指向真实 exe**，不静默套 shell、不静默降级。
+

package/README.md

@@ -4,13 +4,14 @@
 
 > 一个用于 **DeepSeek Harness (DSH)** 的 Cordis 插件包：把编码/构建/调试/排查等实际工作
 > **优先派发给本机 CLI agent** —— Google **Antigravity（`agy`）**、腾讯 **CodeBuddy Code**、
-> 小米 **MiMo（MiMoCode CLI / MiMo Desktop）** —— DSH 全程掌控这些 CLI（非交互、无提示），
-> 并在 **限流 / 网络不通** 时弹窗让用户选择是否回退到 **DSH 本地 API 配置**；会话标题栏提供
-> **一盏聚合实时状态灯**（三家分区），设置面板统一三家偏好与凭据。
+> 小米 **MiMo（MiMoCode）**、**OpenCode**、**Claude Code**、**OpenAI Codex CLI** —— DSH 全程
+> 掌控这些 CLI（非交互、无提示），并在 **限流 / 网络不通** 时弹窗让用户选择是否回退到
+> **DSH 本地 API 配置**；会话标题栏提供 **一盏聚合实时状态灯**（六家分区），设置面板统一
+> 各家的偏好与凭据。
 >
 > 本包整合并取代三个旧包：`agy-first-bridge`（1.7.1 终版）、`codebuddy-first-bridge`（1.6.2 终版）、
 > `mimo-first-bridge`（1.2.9 终版）。旧包已 deprecated，功能全部并入此处；迁移见
-> [docs/MIGRATION.md](docs/MIGRATION.md)。
+> [docs/MIGRATION.md](docs/MIGRATION.md)。`opencode` / `claude` / `codex` 为本包新增。
 
 ![聚合状态灯的几种状态](assets/indicator-states.svg)
 
@@ -25,7 +26,7 @@
    **工具名与入参语义与旧包逐字一致**，历史会话提示词零改动继续可用。
 2. **一段 CLI 优先策略提示**（每家各自 POLICY 段），让模型在所有模式下优先把实际工作
    派发给对应 CLI，原生工具只用于只读查询与最终验证。
-3. **一盏聚合状态灯（家级插件，随 DSH 启动加载）**：标题栏 pill 汇总三家状态
+3. **一盏聚合状态灯（家级插件，随 DSH 启动加载）**：标题栏 pill 汇总各家状态
    （绿=就绪/成功、黄=运行中、红=失败、灰=不可用、琥珀=本地回退、preset 高亮=本会话运行在桥接预设下）；
    悬停看当前步骤，点击展开按 provider、按项目（工作目录）的活动面板 ——
    每项目实时步骤折叠（当前工具 + 参数摘要 + 轨迹）、runs/tokens 累计、最近完成运行。
@@ -42,12 +43,12 @@
 
 | 形态 | 位置 | 能力 | 状态灯 |
 | --- | --- | --- | --- |
-| **持久 Agent Preset**（推荐） | [`preset/<dir>/`](preset/) | 工具 + POLICY + 回退弹窗 + 三家预设（`cordis-agy` / `codebuddy-first` / `cordis-mimo`） | ✅（家级灯自动点亮） |
+| **持久 Agent Preset**（推荐） | [`preset/<dir>/`](preset/) | 工具 + POLICY + 回退弹窗 + 各家预设（`cordis-agy` / `codebuddy-first` / `cordis-mimo` / `opencode-first` / `claude-first` / `codex-first`） | ✅（家级灯自动点亮） |
 | **家级插件（指示灯+设置+声明注册）** | [`home-plugin/cli-bridge-indicator/`](home-plugin/cli-bridge-indicator/) | HTTP 路由 + 浏览器 pill/面板/设置 + **preset 声明制注册** | 本体 |
 | **动态宿主（沙箱插件）** | [`dynamic/<id>.host.js`](dynamic/)（由模板生成） | 无 preset 时在任意组合里挂载工具 | ✅（经收集器汇入） |
-| **MCP stdio server** | [`mcp/cli-bridge-mcp.mjs`](mcp/)（bin `cli-bridge-mcp`） | 任何 MCP 客户端（Claude Code/Cursor/DSH 外部）直连本机三家 CLI | ✅（快照文件桥接，见下） |
+| **MCP stdio server** | [`mcp/cli-bridge-mcp.mjs`](mcp/)（bin `cli-bridge-mcp`） | 任何 MCP 客户端（Claude Code/Cursor/DSH 外部）直连本机各 CLI | ✅（快照文件桥接，见下） |
 
-MCP 接入（一个 server 暴露全部三家工具；只想要一家用兼容入口或 `--provider=`）：
+MCP 接入（一个 server 暴露全部各家工具；只想要一家用兼容入口或 `--provider=`）：
 
 ```json
 {
@@ -110,7 +111,7 @@ home-plugin/cli-bridge-indicator/
 preset/standard-base.mjs + preset/<dir>/plugin-list.mjs ── scripts/build.mjs ──> agent.cordis.yml / preset.yml / dynamic/*.host.js
 ```
 
-- 开发/移植第三家 CLI？契约见 [PROVIDER-CONTRACT.md](PROVIDER-CONTRACT.md)，一次实现一个描述符即可接入全部形态。
+- 再接入一家 CLI（第 N 家）？契约见 [PROVIDER-CONTRACT.md](PROVIDER-CONTRACT.md)，一次实现一个描述符即可接入全部形态。
 - 为什么 preset id 和工具名不变？旧会话头/提示词引用它们（红线清单在契约 §0）。
 - 生成物为什么提交进仓库？fresh clone 直接可装可用；`node scripts/build.mjs --check` 在 CI/prepack 防漂移。
 
@@ -122,7 +123,7 @@ npm install -g @luchenglong/cli-bridge        # MCP 用：cli-bridge-mcp 已在
 
 DSH 接线（home-plugin bundle + presets + 指示灯一次装齐）见 **[docs/INSTALL.md](docs/INSTALL.md)**。
 要点：包带 `dsh.bundle.patch`（bundle 面自注册），DSH profile 加入该 bundle 后
-三盏能力 + 三家 preset + 设置面板 + 状态灯一次到位；本仓库脚本 `npm run deploy:local`
+各家能力 + 各家 preset + 设置面板 + 状态灯一次到位；本仓库脚本 `npm run deploy:local`
 只做到「暂存目录」，不改运行时接线（需先停 DSH）。
 
 ## 开发
@@ -145,7 +146,7 @@ npm run check                 # 三闸门全量
 - [docs/RELEASE-SOP.md](docs/RELEASE-SOP.md) — 发版流程与红线检查
 - [docs/FALLBACK-AND-INDICATOR.md](docs/FALLBACK-AND-INDICATOR.md) — 回退弹窗与状态灯语义详解
 - [PROVIDER-CONTRACT.md](PROVIDER-CONTRACT.md) — provider 接入契约（冻结）
-- [CHANGELOG.md](CHANGELOG.md) + [docs/history/](docs/history/) — 统一历史与三家 lineage 全量历史
+- [CHANGELOG.md](CHANGELOG.md) + [docs/history/](docs/history/) — 统一历史与三条旧 lineage 的全量历史
 
 ## 许可
 

package/docs/HANDOVER.md

@@ -2,30 +2,32 @@
 
 > 面向接手这个仓库/这台机器的下一个人（或下一个 Agent）。
 > 目标：**不读完所有历史也能安全改动、发布、排障**。历史事故与红线集中在 §5 与 §10。
-> 最近一次更新：2026-10-16（0.2.4：**第四个 provider OpenCode** 接入 + 状态灯淡出修复 +
-> 版本单一来源；运行时改为 **npm registry 标准安装**，不再依赖本地开发目录）。
+> 最近一次更新：2026-10-20（**0.2.10：模型下拉改为「手动拉取」+ 修掉 0.2.9 里
+> opencode/mimo 的 dynamic 形态 ReferenceError（模板漏片文件占位）+ 源码 EOL 规范化为 LF**）。
+> 此前的 claude/codex 接入见 §14，OpenCode 见 §13。
 
 ---
 
 ## 1. 这是什么
 
-`@luchenglong/cli-bridge` 把**本机四个编码 CLI**（agy / CodeBuddy / MiMo / **OpenCode**）以同一套
-provider 描述符接入 DSH，并有四种落地形态（preset / 动态宿主 / 家级宿主插件+指示灯 / MCP stdio server）。
+`@luchenglong/cli-bridge` 把**本机六个编码 CLI**（agy / CodeBuddy / MiMo / OpenCode /
+**Claude Code** / **OpenAI Codex**）以同一套 provider 描述符接入 DSH，并有四种落地形态
+（preset / 动态宿主 / 家级宿主插件+指示灯 / MCP stdio server）。
 它由三个旧包（`agy-first-bridge` / `codebuddy-first-bridge` / `mimo-first-bridge`）合并而来，
-旧包的工具名、预设 id、策略文案**逐字保留**（兼容承诺，见 §5）。OpenCode 是统一包首个**新增**
-provider（无旧包可迁，无兼容包袱），见 §13。
+旧包的工具名、预设 id、策略文案**逐字保留**（兼容承诺，见 §5）。`opencode` / `claude` / `codex`
+是统一包**新增**的 provider（无旧包可迁，无兼容包袱），见 §13 与 §14。
 
 ## 2. 当前状态快照
 
 | 项 | 值 |
 | --- | --- |
-| 版本 | **0.2.4**（三处版本锁：`package.json` / `mcp/cli-bridge-mcp.mjs` 的 `SERVER_VERSION` / `CHANGELOG.md` 顶部；`verify.mjs` 机器比对） |
-| npm | `@luchenglong/cli-bridge@0.2.4`（`latest`；shasum `08ca3325376e96abc935435784106fd1ee158ba4`，68 files / 376.0 kB） |
-| GitHub | `new-256/cli-bridge`，`main` @ `acf6f09`；tag `v0.2.1` / `v0.2.2` / `v0.2.3` / `v0.2.4` |
+| 版本 | **0.2.10**（三处版本锁：`package.json` / `mcp/cli-bridge-mcp.mjs` 的 `SERVER_VERSION` / `CHANGELOG.md` 顶部；`verify.mjs` 机器比对） |
+| npm | `@luchenglong/cli-bridge@0.2.10`（`latest`；shasum 以 `npm view` 为准，100+ files） |
+| GitHub | `new-256/cli-bridge`，`main` 见 `git log`；tag `v0.2.1` … `v0.2.10` |
 | 旧包 | 三个都已在 npm 标 **deprecated**（提示迁移到统一包）：`agy-first-bridge@1.7.1`、`codebuddy-first-bridge@1.6.2`、`mimo-first-bridge@1.2.9` |
 | 旧仓 | `new-256/agy-first-bridge`、`new-256/mimo-first-bridge`：README 顶部已加迁移横幅且 **archived（只读）**；`codebuddy-first-bridge` 在 GitHub 上不存在 |
-| 测试 | **327 pass / 0 fail**（33 个 `*.test.mjs`），四闸门 `npm run check` 全绿 |
-| 本机运行时 | DSH Desktop；`dsh-home/profiles/web` 以 **npm registry 标准依赖** `@luchenglong/cli-bridge: "0.2.4"` + pnpm 快照部署（2026-10-15 起不再用 `file:`） |
+| 测试 | **600 tests / 599 pass / 0 fail / 1 skip**（既有跳过），四闸门 `npm run check` 全绿 |
+| 本机运行时 | DSH Desktop；`dsh-home/profiles/web` 以 **npm registry 标准依赖** + pnpm 快照部署（不用 `file:`）。⚠ 已发布 ≠ 运行时已切，切版本要用户自己做 |
 
 **已知遗留 / 未处理项**（均有意为之，非故障）：
 - 家级补丁 `dsh-home\cordis.patch.yml` 里四条 MCP 行**仍是注释状态** —— 与旧版本交接文档
@@ -375,11 +377,103 @@ npm whoami          # 应输出 luchenglong
 
 ---
 
+## 14. Claude Code / OpenAI Codex provider（0.2.9 新增）
+
+两家都是**在真机上探测**后实现的，不要凭直觉改 argv —— 有一条错就会被 CLI 直接拒（`unexpected argument`）。
+完整实测事实见 `PROVIDER-CONTRACT.md` §10，这里只记要点与坑。
+
+### 文件与命名
+- `providers/claude.mjs`(508) + `claude-exe.mjs`(112) / `claude-models.mjs`(334) / `claude-policy.mjs`(37)
+- `providers/codex.mjs`(544) + `codex-cli.mjs`(471) / `codex-models.mjs`(107)
+- preset `preset/{claude,codex}-first/`；dynamic `dynamic/{claude,codex}.host.template.mjs`；MCP `mcp/providers/{claude,codex}.mjs`
+- 工具：`claude_run/_continue/_status/_models`、`codex_run/_continue/_status/_models`
+
+### 关键差异（与 agy/codebuddy/mimo/opencode 比）
+| 维度 | claude | codex |
+| --- | --- | --- |
+| 非交互 | `-p --output-format stream-json --verbose` | `exec --json` |
+| sessionId | `result.session_id` | `thread.started.thread_id` |
+| 续聊 | `--resume <id>` / `-c` | `exec resume <id>` / `--last` |
+| 成功判定 | **`is_error===false && exit===0`**（subtype 不可靠！） | exit 0 + `turn.completed` + 无顶层 error |
+| 模型清单 | 无效模型触发 400 报文 | `GET {base_url}/models`（live） |
+
+### 三个必须知道的坑
+1. **claude 的成功判定不能看 subtype**：无效模型时 `is_error=true` 但 `subtype` 仍是 `"success"`、
+   退出码可能是 0 也可能是 1。只看 subtype 或只看 exit code 都会把失败当成功。
+2. **`codex exec` 不吃根命令的旗**：`-a/--ask-for-approval` 只属于 `codex`，`codex exec` 会报
+   unexpected argument；审批走 `-c approval_policy="…"`。同理 `exec resume` 没有 `-C/-s/-o/--add-dir`。
+3. **`item.completed` 的 `item.type==="error"` 是告警不是致命错**（`resume --last` 会带一条
+   「此模型与原会话不同」）。把它当致命错会让正常续聊全判失败。
+
+### 配置/凭据（本机实际布局，都不是官方直连）
+- claude 走了 **DeepSeek 的 Anthropic 兼容端点**：`~/.claude/settings.json` 的 env 块里
+  `ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic` + `ANTHROPIC_AUTH_TOKEN` +
+  `ANTHROPIC_DEFAULT_*_MODEL=deepseek-v4-pro[1M]`。所以实测可用模型是 `deepseek-flash,
+  deepseek-v4-pro`，**不是** Claude 官方模型名。
+- codex 走了 **OpenRouter**：`~/.codex/config.toml` 里 `model_provider="custom"`、
+  `base_url=https://openrouter.ai/api/v1`、`experimental_bearer_token`。实时 `/models` 返回 469 项。
+- 因此两家的"可用模型"完全取决于用户配的端点，**不能硬编码模型名**；只能实时问端点。
+
+### 手动验收脚本（会真联网/真花钱，故不进 `node --test`）
+```
+node tests/e2e/lead-live-smoke.mjs     # 走描述符的 buildArgv→真 CLI→parseJson→buildResult 全链路
+node tests/codex/helpers/live-cli-smoke.mjs
+node tests/claude/helpers/verify-real-cli.mjs
+```
+
+---
+
+## 15. 模型下拉的「手动拉取」与两条新坑（0.2.10）
+
+### 15.1 机制（契约 §3.2）
+面板**不再自动探测**模型清单。原因：探测要起子进程/联网，面板是同步回调 —— 拖慢首屏；
+且探不到时下拉空着，用户分不清"这家没模型"与"没拉到"。
+
+现在：`meta()` 只读缓存 → 字段声明 `refresh: { label: '拉取可用模型' }` 即渲染按钮 →
+点击 `POST /cli-bridge/settings/models {provider}` → keystone 调该 provider 的
+`settings.refreshModels(settings, env)` → 返回 `{ok, ids, labels?, source, error?}` →
+前端把 `ids` 变成下拉选项（只更新展示态，选中后照常 POST 保存）。
+
+**铁律**：失败必须 `ok:false` + 可操作错误，端点恒返回 **HTTP 200**（业务失败不用 4xx，
+否则前端会当网络错误静默吞掉）。`source` 会显示给用户（`account-live` / `live` / …）。
+
+已实现：codebuddy / opencode / mimo / claude / codex（agy 无模型字段）。
+各家的探测来源不同，别混：codebuddy=无效模型触发 400 报文；claude=同机制（Anthropic 兼容端点）；
+codex=`GET {base_url}/models`；opencode=`opencode models`；mimo=`mimo models`。
+
+### 15.2 坑一：dynamic 模板的片文件占位（**0.2.9 真实事故**）
+把 `providers/<id>.mjs` 拆成片文件（`<id>-*.mjs`）后，**必须确认 `dynamic/<id>.host.template.mjs`
+里有片文件占位行**，否则 build 不会内联那些片 —— 生成物里符号只有引用没有定义，运行时
+`ReferenceError`（且**纯语法检查/new Function 求值都抓不到**，因为未定义标识符只在函数被
+调用时才炸）。0.2.9 就是这样让 opencode/mimo 的 dynamic 形态坏掉的。
+
+现在有永久防线：`tests/{opencode,mimo,claude,codex}/dynamic-template.test.mjs` 断言生成物里
+片文件符号的**定义数 = 1**（不是"出现过"）。加新片文件时请照抄这个断言。
+
+排查手法：`node tests/e2e/sandbox-smoke.mjs [id]` —— 求值 + 逐片符号定义数一把过。
+
+### 15.3 坑二：EOL 必须 LF（否则别的机器 build --check 必然 drift）
+`.gitattributes` 要求 `eol=lf`，但 **PowerShell 的 `Set-Content` / `[IO.File]::WriteAllLines`
+在 Windows 默认写 CRLF**。一旦源文件是 CRLF，build 按它拼出的生成物也是 CRLF，于是：
+- 本机 `build --check` 可能通过（源和产物一起是 CRLF）；
+- 但别人 clone（git 按 eol=lf 检出）+ 跑 `build --check` → **必然 drift**；
+- 严重时 git 会把生成物当二进制（`git ls-files --eol` 显示 `i/-text w/-text`）。
+
+用法：`node tests/e2e/normalize-eol.mjs`（干跑）/ `--apply`（规范化）。
+发版前建议：规范化 EOL → `node scripts/build.mjs` → `build --check` 必须 `up to date` →
+`git ls-files --eol providers/ dynamic/` 全部 `w/lf`。
+
+---
+
 ### 交接最小检查单
 
-- [ ] `npm run check` 全绿（327 测试）
+- [ ] `npm run check` 全绿（600 测试）
 - [ ] `node mcp/cli-bridge-mcp.mjs --check` 显示 `scheduling.source` 且版本与 package.json 一致
-- [ ] `GET $env:DSH_WEB_URL/cli-bridge/status` 返回**四家** + `scheduling`
-- [ ] 设置面板有 `总设置 | AGY | CB | MIMO | OPENCODE` 五个标签；OpenCode 卡能选模型并保存落盘
+- [ ] `GET $env:DSH_WEB_URL/cli-bridge/status` 返回**六家** + `scheduling`
+- [ ] 设置面板有 `总设置 | AGY | CB | MIMO | OPENCODE | CLAUDE | CODEX` 七类卡片；
+      有「默认模型」的那几张，点「拉取可用模型」能拿到清单（拿不到会显示具体原因）
 - [ ] 起一个 opencode 任务：灯亮 → 完成后 **60 秒内灭**（§6.1）
-- [ ] 知道红线在 §5、生效时机在 §7.2、排障在 §10、OpenCode 在 §13
+- [ ] 知道红线在 §5、生效时机在 §7.2、排障在 §10、OpenCode 在 §13、claude/codex 在 §14、
+      手动拉取与两条新踩的坑在 §15
+- [ ] **`PRESET_DIRS` 只在 `providers/registry.mjs` 一处** —— 加 provider 别再在
+      `build.mjs` / `preset-declarations.mjs` / `verify.mjs` 里各写一份（0.2.9 收敛的坑）

package/dynamic/agy.host.js

@@ -1112,7 +1112,7 @@ function isBridgeEnabled(selfId, ids, io) {
 }
 
 
-const SCHED_ALL_IDS = ["agy","codebuddy","mimo","opencode"]
+const SCHED_ALL_IDS = ["agy","codebuddy","mimo","opencode","claude","codex"]
 
 
 return {