@luchenglong/cli-bridge 0.2.9 → 0.2.10

package/CHANGELOG.md

@@ -9,6 +9,48 @@ 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

package/PROVIDER-CONTRACT.md

@@ -134,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

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/claude.host.js

@@ -585,7 +585,7 @@ function createRunner(o) {
 //  - 模型清单只认服务端权威探测；拿不到 = ok:false + 可操作错误（绝不静默空数组/配置冒充）。
 // import { createStatusEngine, createRunner, clampInt, isLimited } from '../core/bridge-kit.mjs'
 // import { claudeExeCandidates, claudePathHint, resolveExePrefix, splitExeSpec, CLAUDE_BIN_ENV_VARS } from './claude-exe.mjs'
-// import { PROBE_MODEL, parseSupportedModels, probeSupportedModels, probeSupportedModelsSyncCached, readConfiguredModels, listAccountModels, resetModelsCache } from './claude-models.mjs'
+// import { PROBE_MODEL, parseSupportedModels, probeSupportedModels, readCachedModels, readConfiguredModels, listAccountModels, resetModelsCache } from './claude-models.mjs'
 // 单行 re-export（build 内联时整行剥离；多行形态风险见 build.mjs 的 stripModuleSyntax 注释）。
 
 function nowIso() { return new Date().toISOString() }
@@ -593,6 +593,19 @@ function nowIso() { return new Date().toISOString() }
 // 权限模式的用户可见取值（auto 由 DSH plan 状态决定；其余直通 CLI）。
 const MODE_ENUM = ['auto', 'plan', 'accept-edits', 'bypass']
 
+// 手动拉取（契约 §3.2）的探测时限与失败指引。
+// 失败文案必须「可操作」：面板只会把 error 原样显示给用户，没写下一步等于没帮上忙。
+const REFRESH_TIMEOUT_MS = 30000
+const REFRESH_HINT = '排查顺序：① 确认设置面板的「claude 可执行文件路径」或 CLAUDE_BIN 指向真实 claude（原生 .exe 优先）；② 确认 ~/.claude/settings.json 的 env 里 ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN 指向可用端点（该面若未登录，先在终端跑一次 claude 完成登录）；③ 再点一次「拉取可用模型」。'
+
+/** 缓存年龄的短文案（面板 note 用；只描述事实，不假装新鲜）。 */
+function ageText(ms) {
+  const min = Math.floor(Math.max(0, Number(ms) || 0) / 60000)
+  if (min < 1) return '刚刚拉取'
+  if (min < 60) return min + ' 分钟前拉取'
+  return Math.floor(min / 60) + ' 小时前拉取'
+}
+
 // ── 三工具 schema ─────────────────────────────────────────────────────────────
 const RUN_PARAMS = {
   type: 'object',
@@ -967,11 +980,17 @@ function defineProvider (deps = {}) {
         }
         return out
       },
+      /**
+       * 设置面板元数据（契约 §3.2）：**只读缓存、绝不探测**。
+       * 面板是同步回调，而探测要起子进程打网络（3-5s）——放在这里会把首屏拖慢，且探不到时
+       * 用户无法区分「没模型」与「没拉到」。故探测改为用户点「拉取可用模型」→
+       * settings.refreshModels() 显式触发；成功后写回同一份缓存，这里下次渲染直接命中。
+       */
       meta: (env2) => {
         const e = env2 && typeof env2 === 'object' ? env2 : {}
         const s = currentSettings()
-        const probe = (function () { try { return probeSupportedModelsSyncCached(e, { binPath: s.binPath }) } catch (err) { return { ok: false, ids: [], error: String(err && err.message || err) } } })()
-        const options = (probe.ok ? probe.ids : []).map((id) => ({ value: id, label: id }))
+        const cached = readCachedModels(e, { binPath: s.binPath })
+        const options = (cached ? cached.ids : []).map((id) => ({ value: id, label: id }))
         const exeCandidates = claudeExeCandidates(e, '')
         return {
           titleSuffix: 'Claude Code',
@@ -985,10 +1004,12 @@ function defineProvider (deps = {}) {
             {
               key: 'defaultModel', label: '默认模型', type: 'select', allowCustom: true,
               options,
+              // 面板据此渲染「手动拉取」按钮（契约 §3.2）；meta() 自身永不探测。
+              refresh: { label: '拉取可用模型' },
               placeholder: '留空 = 由 claude 自身配置（~/.claude/settings.json）决定',
               note: options.length
-                ? '共 ' + options.length + ' 个服务端权威可用模型（探测所得）。调用时传 model 可覆盖本项。'
-                : '未能获取服务端权威模型清单（探测失败：' + String(probe.error || 'unknown').slice(0, 140) + '）—— 下拉为空，但可手动输入模型名。配置里的 ANTHROPIC_*_MODEL 只是别名映射，不作为候选展示。'
+                ? '共 ' + options.length + ' 个服务端权威可用模型（' + ageText(cached.ageMs) + '，源：' + cached.mode + '）。点「拉取可用模型」重新获取；调用时传 model 可覆盖本项。'
+                : '还没拉取过（或上次没拉到）：点「拉取可用模型」向端点取权威清单；空表示尚未拉取 / 该面未登录。可直接手动输入模型名 —— 配置里的 ANTHROPIC_*_MODEL 只是别名映射，不作为候选展示。'
             },
             {
               key: 'maxBudgetUsd', label: '单次最大花费（美元）', type: 'text',
@@ -998,6 +1019,38 @@ function defineProvider (deps = {}) {
           ]
         }
       },
+
+      /**
+       * 手动拉取（契约 §3.2）：面板「拉取可用模型」按钮 → keystone
+       * POST /cli-bridge/settings/models → 这里。这是本 provider 唯一的面板探测入口。
+       *
+       * 复用 listAccountModels（异步 probeSupportedModels + 配置诊断），不写第二套探测；
+       * 其成功路径已把权威清单写回 modelsCache，随后 meta() 直接命中（无需再探测）。
+       * 铁律：失败 = ok:false + 可操作错误 + 空 ids，绝不返回 {ok:true, ids:[]}；
+       * 也绝不把 settings.json 里的别名映射冒充成服务端可用全集。
+       */
+      async refreshModels(settings, env2) {
+        const e = (env2 && typeof env2 === 'object') ? env2 : env
+        const s = descriptor.settings.normalize(settings)
+        const got = await listAccountModels(e, {
+          binPath: s.binPath,
+          timeoutMs: REFRESH_TIMEOUT_MS,
+          refresh: true
+        })
+        if (!got.ok) {
+          return { ok: false, ids: [], source: 'account-live', error: String(got.error || 'probe failed') + ' ' + REFRESH_HINT }
+        }
+        const ids = (got.models || []).map((m) => m.id).filter(Boolean)
+        if (!ids.length) {
+          // 走到这里说明探测自称成功却没给出任何 id —— 那是 bug，不是「无模型」，
+          // 必须显式失败，绝不能让面板显示一个空清单当成功。
+          return { ok: false, ids: [], source: 'account-live', error: '探测声称成功但未返回任何模型 id（内部不一致）。' + REFRESH_HINT }
+        }
+        // labels 只给「配置里还映射着某个 ANTHROPIC_*_MODEL」的项加注（纯展示，value 仍是 id）。
+        const labels = {}
+        for (const m of got.models) if (m.configuredAs) labels[m.id] = m.id + '  [' + m.configuredAs + ']'
+        return { ok: true, ids, labels, source: 'account-live' }
+      },
       diagnose: (settings, env2) => {
         const s = settings && typeof settings === 'object' ? settings : {}
         const e = env2 && typeof env2 === 'object' ? env2 : {}
@@ -1200,18 +1253,23 @@ function claudePathHint(env) {
 //   ~/.claude/settings.json 的 env.ANTHROPIC_DEFAULT_*_MODEL 只是「别名映射」，
 //   不是服务端可用全集 —— 红线：绝不把它冒充成可用清单，也绝不静默返回空数组。
 //
-// 落盘/缓存：面板（settings.meta）是同步回调，必须 spawnSync；探测一次约 3-5s，
-// 故结果进 5 分钟缓存（与 codebuddy catalog 同策略），避免每次渲染都打网络。
+// 缓存与「谁探测」（契约 §3.2 手动拉取）：
+//   • settings.meta() 是同步回调，且**不再自动探测** —— 它只调 readCachedModels() 读这里的
+//     缓存（纯读、不 spawn、不联网）；没命中就留空，由 note 提示用户点「拉取可用模型」。
+//   • 探测只有一条路：settings.refreshModels() → 异步 probeSupportedModels()（用户显式触发）。
+//     成功后经 cachedModels() 写回同一个缓存，下次 meta() 直接命中 —— 面板首屏不再被拖慢。
+//   • 5 分钟 TTL 只约束**工具调用**（claude_models 的重复调用）；面板展示的是「上次拉取到的
+//     权威清单」，过期也照旧展示，但 note 会标注拉取时间（宁可显式标旧，也不让下拉莫名清空）。
 // import { claudeExeCandidates, claudeProbeCandidates, splitExeSpec, quoteShellArg } from './claude-exe.mjs'
 // 故意无效的探测模型名（服务端必然拒绝；保持带前缀，便于日志辨认来源）。
 const PROBE_MODEL = '__clb_probe_invalid__'
 const MODELS_TTL_MS = 5 * 60 * 1000
 
-// 探测结果缓存：key（后端/端点标识） → { at, ids }
+// 探测结果缓存：key（后端/端点标识） → { at, value }
 const modelsCache = new Map()
 
 /** 清空探测缓存（测试与「模型变更后刷新」用）。 */
-function resetModelsCache() { modelsCache.clear(); syncModelsCache.clear() }
+function resetModelsCache() { modelsCache.clear() }
 
 // 缓存键 = 候选可执行文件集合（同一台机器可能切换 CLAUDE_BIN / 面板路径，键必须跟着变，
 // 否则会把「上一个 exe 的探测结果」错配给新 exe）。
@@ -1220,8 +1278,18 @@ function candidateKey(env, binPath) {
   return list.length ? list.join('|') : 'claude'
 }
 
+/** 缓存的键（面板读缓存与工具探测必须用同一把键，否则写进去读不出来）。 */
+function modelsCacheKey(env, binPath) {
+  return 'claude:' + candidateKey(env, binPath)
+}
+
+/** 缓存里只可能存「成功的权威清单」；失败绝不入缓存（否则会把坏状态固化）。 */
+function isUsableProbe(v) {
+  return !!(v && v.ok === true && Array.isArray(v.ids) && v.ids.length)
+}
+
 /**
- * 缓存包装：TTL 内直接返回上次成功结果；失败不写缓存（下次仍然重试，绝不把失败固化）。
+ * 缓存包装（异步工具路径）：TTL 内直接返回上次成功结果；失败不写缓存。
  * @param {string} key
  * @param {() => Promise<object>|object} load
  * @param {number} [nowMs]
@@ -1231,11 +1299,47 @@ function cachedModels(key, load, nowMs) {
   const hit = modelsCache.get(key)
   if (hit && at - hit.at < MODELS_TTL_MS) return hit.value
   return Promise.resolve().then(load).then((v) => {
-    if (v && v.ok && Array.isArray(v.ids) && v.ids.length) modelsCache.set(key, { at, value: v })
+    if (isUsableProbe(v)) modelsCache.set(key, { at, value: v })
     return v
   })
 }
 
+/**
+ * 只读缓存（settings.meta 专用）：纯读、不 spawn、不联网。
+ * 与 cachedModels 的区别：这里**不受 TTL 限制** —— 面板展示的是「上次真正拉取到的那份
+ * 服务端清单」，附 ageMs 让 note 如实标注新旧；空/过期与否都不该凭空清空用户看到的下拉。
+ *
+ * 为什么要「精确键未命中 → 取最近一次成功结果」：keystone 渲染面板时只把 env 传给
+ * meta()，**拿不到面板里保存的 binPath**（settingsView 里 createProvider 只带 env），
+ * 而缓存键含候选 exe 集合 → 用户一旦填过 binPath，精确键必然错开，下拉会在拉取成功后
+ * 仍然空着（看起来像按钮没起作用）。这不算降级：清单是 claude 自己 settings.json 里
+ * 端点+凭据裁决的，与走哪个候选 exe 无关（exe 只决定探测能否跑起来），且 note 会带上
+ * 「N 分钟前拉取 / 源 account-live」，用户看到的是真实的探测结果与真实的年龄。
+ * @param {object} env
+ * @param {{binPath?: string, nowMs?: number}} [opts]
+ * @returns {{ids: string[], mode: string, exe: (string|null), at: number, ageMs: number}|null}
+ */
+function readCachedModels(env, opts) {
+  const o = opts || {}
+  const at = Number(o.nowMs) || Date.now()
+  const exact = modelsCache.get(modelsCacheKey(env, o.binPath))
+  let hit = isUsableProbe(exact && exact.value) ? exact : null
+  if (!hit) {
+    for (const entry of modelsCache.values()) {
+      if (!isUsableProbe(entry.value)) continue
+      if (!hit || entry.at > hit.at) hit = entry
+    }
+  }
+  if (!hit) return null
+  return {
+    ids: hit.value.ids.slice(),
+    mode: hit.value.mode || 'account-live',
+    exe: hit.value.exe || null,
+    at: hit.at,
+    ageMs: Math.max(0, at - hit.at)
+  }
+}
+
 /**
  * 从 400 报文里解析「服务端支持的模型名」。
  * 主格式（实测）：`The supported API model names are A, B, but you passed Z.`
@@ -1356,68 +1460,8 @@ function probeFailureText(reasons, tried) {
 }
 
 /**
- * 同步探测（供 settings.meta 面板下拉；无 spawnSync 能力 → 明确 ok:false）。
- * @param {object} env
- * @param {{binPath?: string, timeoutMs?: number}} [opts]
- * @returns {{ok: boolean, ids: string[], mode: string, exe?: string, error?: string}}
- */
-function probeSupportedModelsSync(env, opts) {
-  const o = opts || {}
-  const child = (function () { try { const p = globalThis.process; return (p && typeof p.getBuiltinModule === 'function') ? p.getBuiltinModule('node:child_process') : null } catch (x) { return null } })()
-  if (!child || typeof child.spawnSync !== 'function') {
-    return { ok: false, ids: [], mode: 'account-live', error: 'no spawnSync capability in this host form' }
-  }
-  const cands = claudeProbeCandidates(env, o.binPath)
-  const probeList = cands.length ? cands : ['claude']
-  const timeout = Math.max(3000, Math.min(Number(o.timeoutMs) || 12000, 30000))
-  const reasons = []
-  const proc = globalThis.process
-  for (const exe of probeList) {
-    const spec = splitExeSpec(exe)
-    const argv = spec.prefixArgs.concat(probeArgv())
-    const cmd = spec.shell ? [spec.cmd].concat(argv).map(quoteShellArg).join(' ') : spec.cmd
-    const r = child.spawnSync(cmd, spec.shell ? [] : argv, {
-      encoding: 'utf8', timeout, windowsHide: true, shell: !!spec.shell,
-      env: Object.assign({}, (proc && proc.env) || {}, {})
-    })
-    if (!r || r.error) { reasons.push(exe + ': ' + String((r && r.error && (r.error.code || r.error.message)) || 'spawn failed')); continue }
-    const got = extractProbeIds(r.stdout, r.stderr)
-    if (got.ids && got.ids.length) return { ok: true, ids: got.ids, mode: 'account-live', exe }
-    const head = String(got.errorText || '').replace(/\s+/g, ' ').trim().slice(0, 160)
-    reasons.push(exe + ': exit ' + r.status + '，未解析出可用模型清单' + (head ? ' — ' + head : ''))
-  }
-  return { ok: false, ids: [], mode: 'account-live', error: probeFailureText(reasons, probeList.length) }
-}
-
-// 同步探测缓存（面板每次渲染都会取，避免反复 spawnSync 打网络）。
-const syncModelsCache = new Map()
-// 失败结果的反向缓存 TTL：成功缓存 5 分钟；失败只缓存 60 秒。
-// 为什么必须有反向缓存：面板是同步回调，CLI 缺失/未登录时一次 spawnSync 可能阻塞数秒，
-// 每次渲染都重探会让设置面板卡顿。60 秒足够让用户装好 CLI/登录后立刻看到新结果，
-// 又不会把「当时读不到」长期固化成假象（状态照旧 ok:false + 可操作错误，语义不变）。
-const NEGATIVE_TTL_MS = 60 * 1000
-
-/**
- * 带缓存的同步探测（settings.meta 专用；面板是同步回调，只能 spawnSync）。
- * 成功/失败都进缓存（TTL 不同），失败语义保持不变：ok:false + 可操作错误。
- * @returns {{ok: boolean, ids: string[], mode: string, exe?: string, error?: string}}
- */
-function probeSupportedModelsSyncCached(env, opts) {
-  const o = opts || {}
-  const key = 'sync:claude:' + candidateKey(env, o.binPath)
-  const at = Date.now()
-  const hit = syncModelsCache.get(key)
-  if (hit) {
-    const ttl = hit.value && hit.value.ok ? MODELS_TTL_MS : NEGATIVE_TTL_MS
-    if (at - hit.at < ttl) return hit.value
-  }
-  const v = probeSupportedModelsSync(env, o)
-  syncModelsCache.set(key, { at, value: v })
-  return v
-}
-
-/**
- * 异步探测（MCP / preset / dynamic 三形态共用）：起一次真实 CLI 调用，解析 400 报文。
+ * 异步探测（唯一探测实现：MCP / preset / dynamic 三形态 + 面板「拉取可用模型」共用）：
+ * 起一次真实 CLI 调用，解析 400 报文。
  * 铁律：只认探测结果；失败 = ok:false + 可操作错误，绝不回落到配置文件/静态表。
  * @param {object} env
  * @param {{binPath?: string, timeoutMs?: number}} [opts]
@@ -1454,20 +1498,33 @@ function probeSupportedModels(env, opts) {
       let out = ''
       let err = ''
       const timer = setTimeout(() => { try { c.kill() } catch (e) { } }, Math.max(5000, Math.min(Number(o.timeoutMs) || 30000, 90000)))
+      // 一个候选只允许结算一次：spawn 失败时 'error' 与 'close' 会先后都触发，
+      // 两个回调各调一次 attempt() 会把后面的候选整个跳过（idx 多走一格）——
+      // 实测后果是「binPath 填错 → 明明 CLAUDE_BIN 里那个能跑，探测却直接失败」。
+      let settled = false
+      const nextCandidate = (reason) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        if (reason) reasons.push(reason)
+        attempt()
+      }
       c.stdout.on('data', (d) => { out += d; if (out.length > 400000) out = out.slice(-200000) })
       c.stderr.on('data', (d) => { err += d; if (err.length > 200000) err = err.slice(-100000) })
       c.on('error', (e) => {
-        clearTimeout(timer)
-        reasons.push(exe + ': ' + String((e && e.code) || (e && e.message) || 'spawn error'))
-        attempt()
+        nextCandidate(exe + ': ' + String((e && e.code) || (e && e.message) || 'spawn error'))
       })
       c.on('close', (code) => {
-        clearTimeout(timer)
+        if (settled) return
         const got = extractProbeIds(out, err)
-        if (got.ids && got.ids.length) { resolve({ ok: true, ids: got.ids, mode: 'account-live', exe }); return }
+        if (got.ids && got.ids.length) {
+          settled = true
+          clearTimeout(timer)
+          resolve({ ok: true, ids: got.ids, mode: 'account-live', exe })
+          return
+        }
         const head = String(got.errorText || '').replace(/\s+/g, ' ').trim().slice(0, 160)
-        reasons.push(exe + ': exit ' + code + '，未解析出可用模型清单' + (head ? ' — ' + head : ''))
-        attempt()
+        nextCandidate(exe + ': exit ' + code + '，未解析出可用模型清单' + (head ? ' — ' + head : ''))
       })
     }
     attempt()
@@ -1483,7 +1540,7 @@ function probeSupportedModels(env, opts) {
  */
 async function listAccountModels(env, opts) {
   const o = opts || {}
-  const key = 'claude:' + candidateKey(env, o.binPath)
+  const key = modelsCacheKey(env, o.binPath)
   if (o.refresh) modelsCache.delete(key)
   const probe = await cachedModels(key, () => probeSupportedModels(env, o))
   const cfg = readConfiguredModels(env)