dsh-model-switch 0.4.20 → 0.4.22

package/README.zh.md

@@ -1,206 +1,216 @@
-# Model Switch
-
-[English](README.md) | 中文
-
-在 DeepSeek Harness 中为 Main、Subagent、Web Search、图像生成、当前会话和 Plan 执行模型配置明确路由。Model Switch 只使用 DSH 公开服务和 Provider 自有 Adapter；不修改 DSH Core，也不管理 Provider 登录凭证。
-
-<p align="center"><img src="docs/screenshots/composer-picker.png" alt="包含 Model、Effort、Context 和 Fast 的 Composer Picker" width="314"></p>
-
-Picker 在切换页面或关闭搜索时保留键盘焦点，不覆盖搜索框的自动聚焦。从摘要页按 Escape 会关闭 Picker，并将焦点还给触发按钮。
-
-## 路由
-
-| 路由 | 行为 |
-| --- | --- |
-| Main 模型 | 新建会话的默认 provider、model 和可选 effort；不迁移已有会话。 |
-| Subagent | 跟随当前父请求，或使用固定 provider/model/effort；Workflow 显式覆盖始终优先。 |
-| Composer Picker | 只修改当前会话，并提交 catalog 中的原始 model id；Main 默认值保持不变。 |
-| Plan Review | 在发送 Plan 审核确认前，先提交执行模型。 |
-| Web Search | 保留官方 `web_search`；部署显式启用后，通过 Provider 动态声明的独立搜索适配器路由。 |
-| 图像生成 | 提供一个稳定的 `generate_image` 工具，通过选定的 Codex 或 Grok Adapter 路由。 |
-
-无效、不可用或不受支持的路由会明确失败。Model Switch 不会静默换到另一个 provider 或模型。
-
-空闲的空白会话可以选择 External Agent。提交中、等待首个 turn 以及运行期间，从请求开始就锁定所选执行运行时，不等待首 token 或原生绑定：Antigravity 保留其模型和 effort 选择；DSH 保留 LLM provider 选择，但禁用 Agent provider。会话一旦有过用户消息，Composer 和 Plan Review 仍显示 Agent 角色行但将其禁用，除非该会话已经绑定原生运行时。当前会话成功打开 Antigravity 原生会话后，Picker 会在该会话内禁用其他 provider，同时保留 Antigravity 模型与 effort 控件。DSH 全局 Picker 锁仍拥有最高优先级。
-
-## 配置 Main 和 Subagent
-
-打开 **设置 → Model Switch**。Main 修改只影响新建会话。Subagent 可以跟随 Main，也可以使用固定 provider、model 和 effort。
-官方 DSH `0.1.7-alpha.2` 在非本机浏览器将 ConfigForms 设为仅内存模式，页面会明确显示不可用；请在 Host 的 127.0.0.1 页面打开设置。此模式下 Picker 也拒绝模型切换：已发布的 `session.selectModel` 会同时写入全局默认模型，但只读 Main 表单无法安全恢复。远端编辑与真正仅会话的切换需要上游提供受鉴权的 ConfigForm 通道及仅会话的选择接口；本插件不会绕过官方策略。
-
-切换 Main 或固定 Subagent 的 provider/model 时，会用目标模型的默认 effort 替换旧模型的 effort；目标模型不支持推理时不传 effort。
-
-![Model Switch 设置中的固定 Subagent 路由](docs/screenshots/settings-subagent.png)
-
-Follow Main 先读取当前父请求，再读取配置的 Main 默认值。固定路由会在官方 Subagent descriptor 创建前注入。DSH 0.1.2-alpha.4 会在该 descriptor 中携带 provider、model 和固定 reasoning effort。
-
-## 自定义模型如何出现在 Picker
-
-Model Switch 不会把自身设置中任意填写的字符串变成模型。Provider 插件必须先把模型发布到 DSH 官方 Model Catalog：
-
-```text
-Provider 配置
-→ Provider 将模型行发布到 DSH Catalog
-→ 当前会话 Model Directory 提供 provider/model 元数据
-→ Model Switch 对 Catalog 行分组
-→ Picker 提交原始 provider id 和 model id
-```
-
-Catalog 提供 provider 名称、model id/name、reasoning efforts 和 default effort。已经保存但不再出现在 Catalog 中的路由，会在 Settings 中显示为 unavailable；Picker 不会假装它仍可路由。
-
-### 变体 id 规则
-
-Model Switch 按 provider，以及剥离以下后缀后的 model id 对 Catalog 行分组：
-
-| Catalog model id | Picker 变体 |
-| --- | --- |
-| `acme-v1` | 标准模型 |
-| `acme-v1-fast` | Fast |
-| `acme-v1-128k` | Context 128K |
-| `acme-v1-1m` | Context 1M |
-| `acme-v1-1m-fast` | Context 1M + Fast |
-
-规则：
-
-- `-fast` 生成 Fast 轴。
-- `-<n>k` 和 `-<n>m` 生成 Context 档位；可以与 `-fast` 按任意顺序组合。
-- `reasoning.efforts` 生成 Effort 选项；`reasoning.defaultEffort` 是初始值。
-- 切换 Fast、Context 或 Thinking 变体时，只有目标 Catalog 行支持当前 effort 才会保留；否则改用目标行的默认 effort，目标没有默认值时不传 effort。
-- Catalog 中存在 reasoning 元数据时，该模型行具备 Thinking 能力。
-- 无法识别的 id 不会被丢弃，而是作为独立 model family 显示。
-
-组合选择必须由 Provider 发布组合行。只有 `acme-v1-fast` 和 `acme-v1-1m` 不能表示 Fast + 1M；还必须发布 `acme-v1-1m-fast`。Picker 永远不会合成 Provider 没有发布的 model id。
-
-## Plan Review
-
-Plan Review 拥有独立于 Main 的执行模型草稿。**确认执行**会先把该模型提交到当前会话，再回答待处理的 Plan 审核。提交被拒绝时，审核保持待处理并允许重试；若会话模型已切换但部署默认模型未能还原，提示会在答复之后给出，而不是扣住你的决定。**拒绝**和**去聊天里说**不会执行 Plan。
-
-**拒绝**会发送提问方给出的选项，并把卡片反馈框里的文字作为答复自身的 `custom` 文本一并提交 —— plan 模式会把它作为"继续规划"的理由回报给模型，所以打回时可以带上要改什么。**去聊天里说**会撤下这张卡、把输入框还给你，用你自己的话说明；它在 Host 提供 `dismiss()` 时用它，在旧代际用 `cancel()`，两者都没有时明确指出这一点。审核一旦落定，**确认执行**与**拒绝**关闭，而**去聊天里说**与"重新加载"始终可达，卡片不会变成死路。失败会保留线上错误码（如 `session/writer-held: …`），而不是只给一句本地化文案。
-
-**设置为目标并执行** 会先把这份 Plan 设为当前会话的 goal、再答复，于是 `dsh-goal-round-driver` 能在退出计划模式后继续推进。它调用已发布的 `remote.goals.create`；若已存在一个未完成的 goal，会先 `clear` 再 `create`，让新 Plan 拿到完整轮次预算，并在替换后提示。目标设置被拒时审核保持待处理、错误带真实错误码（如 `GOAL_AGENT_NOT_LIVE: …`）；部署未挂 goal 服务时该按钮禁用并给出原因，其余三个动作照常可用。objective 取计划全文（trim 后）：goal 域不设长度上限，但它会作为模型可见上下文出现在每一轮续跑里，所以计划很长时每轮都花 token。
-
-卡片正文只显示计划的首行标题与首段摘要，**完整计划**会由官方 ui-plan 自动开到右侧侧边栏（头部的"查看完整计划"可随时再开）。接管的 composer 条目无权渲染官方的 `conversation.plan-review.actions` 槽位（每个子槽只允许一个声明者），因此卡片直接驱动 ui-plan 已注册的 opener——计划文档的地址与参数始终由 ui-plan 自己构造（见 `docs/seam-gap.md`）。
-
-**退出计划时的上下文压缩（0.4.20）**：当这次批准**切换了执行模型**（Provider/模型变化，仅改推理强度不算），且估算的下次请求输入超过阈值（Token 数，默认 200,000，可在设置里调整，0 = 关闭）时，卡片会先调用 Host 的压缩端点——**用切换后的模型**摘要一次历史——再提交模型、再答复；「设置为目标并执行」同样先压缩再设目标。未切换模型的批准完全不触发。压缩无可压缩历史时提示后继续执行；压缩出错时执行中止、审核保持待处理并可重试。
-
-![带执行模型 Picker 的 Plan Review](docs/screenshots/plan-review.png)
-
-## 发送时的上下文保护
-
-当发送后的实际请求将使用与上次不同的模型或窗口档位时，Model Switch 会在目标请求发出前检查完整待发上下文。仅在选择器中选模型不会压缩。超出目标可用容量时，使用切换前的模型、通过私有压缩引擎压缩一次历史；不会改 DSH 自身的自动压缩设置。进度以插件通知出现在正文中。预算包含完成提示和待提交的模型切换提示；摘要仍超限时会阻止请求。失败时用户消息留在会话里，不会发送目标模型请求，也不会出现切换成功提示。可在 **设置 → 模型切换 → 发送时自动检查并压缩上下文** 关闭（默认开启）。原生 External Agent 运行时的内部上下文不会被当成 DSH 可压缩历史。
-
-## 自动审查模型（Auto review）
-
-官方 `@deepseek-ai/dsh-experimental-auto-review`（Auto 权限预设的逐调用审查）把审查请求固定在会话自身的路由上。本插件通过 `cordis.patch.yml` 的行替换接管这一行：官方行被禁用，改挂 `dsh-model-switch/auto-review`，它在作用域子上下文里运行**同一份官方 `apply`**，只把 `llm.stream` 的 `provider/model` 改写为设置里固定的审查模型。设置页「自动审查模型」默认关闭 = 审查跟随当前会话模型；打开时从主模型种子化、可再改成任意 Provider/模型，保存后对下一次审查立即生效。审查未配置官方能力包（`@deepseek-ai/dsh-experimental-auto-review` 未随 profile 启动）时本行不挂载，Auto 预设保持官方的关闭状态；官方行若已在别处注册，本行明确报错而不产生第二个 `registerAuto`。
-
-## Model Switch 不会改变什么
-
-- `web_fetch` 及其配置的 provider
-- Vision 路由、`read_image` 和普通聊天附件
-- Provider 登录、凭证或 Provider 设置卡
-- 官方 Agent Presets
-- 已有的 Provider 专属图像工具
-- Main 默认值修改前已经存在的会话
-- 全局压缩策略、标题或 DSH Core
-
-## 安装
-
-Model Switch 交付的是预构建代码，安装不需要任何构建授权。从 npm 注册表安装：
-
-```sh
-dsh plugin --profile web add --force dsh-model-switch
-```
-
-打包好的 tarball 可以在不走注册表的情况下安装同一份构建：
-
-```sh
-dsh plugin --profile web add --force ./dsh-model-switch-0.4.17.tgz
-```
-
-然后只安装实际使用的 Provider Adapter。此版本已在官方 DeepSeek Harness `0.1.7-rc.2` 上检查，并在 `0.2.0-rc.2` 上验证：
-
-```sh
-dsh plugin --profile web add --force \
-  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.14.tgz
-dsh plugin --profile web add --force \
-  https://github.com/NOirBRight/dsh-llm-codex/releases/latest/download/dsh-llm-codex-0.3.23.tgz
-dsh plugin --profile web add --force \
-  https://github.com/NOirBRight/dsh-llm-grok/releases/latest/download/dsh-llm-grok-0.3.19.tgz
-```
-
-### 搜索供应商统一接入（0.4.7）
-
-搜索列表来自 Host 上已有的 `ModelSwitchAdapterRegistry`，Provider 自声明名称和独立搜索模型；浏览器只收到普通元数据，不收到凭据或可执行函数。注册、卸载会通知订阅者；原地修改模型声明最迟由 20 秒心跳更新。`ProviderDirectory` 继续负责客户端 role/usage，不另造注册表。 已发布 0.2.8 的 `sortCatalogGroups` 只排序硬编码 LLM 路由；Model Switch 自行按实时 `catalogRoutes` 排序，因此 Owner 公布 Agent catalog id 时会跟随已保存的卡片顺序。原生 `catalogId` / `unknown` 账户样式仍需要比已发布 0.2.8 更新的 Owner。模型原生联网不等于独立 `web_search` 适配器。
-
-DeepSeek 薄适配器调用官方公开 `DeepSeekSearchProvider`，复用用户的 `web-search-deepseek` 设置和公开凭据服务；Codex 复用 ChatGPT 登录，Grok 复用已有订阅凭据。缺凭据、配置错误、模型不支持均明确失败，不静默切换。
-
-**注册不等于选中全局路由。** 安装插件不再覆盖 Web 配置。部署时先用 `dsh --profile web --dump-config` 查看完整 Web 配置，只把 `searchProvider` 改为 `model-switch`，其余字段原样保留。注意 id 定位的 patch 会整体替换 `config`，不会深度合并；不能只写 searchProvider，也不能把自定义 fetchProvider 写死成 http。
-
-然后在 Model Switch 设置中选择请求的供应商/模型。全局已选 Model Switch、但没有完整且受支持的搜索配置时，官方选择层返回 `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`，不会回退 DeepSeek。全局未选 Model Switch 时，下拉框不控制官方搜索；未固定全局供应商且有多个可用 provider 时会明确报歧义。卸载前应恢复部署原来的搜索路由。官方 `web_search`、`web_fetch` 均不替换。
-
-本轮分支、测试命令及 3082 live 证据见 [搜索接入审计](docs/search-provider-audit.md)。经授权复用生产 DeepSeek 凭据后，Flash/Pro 的 3082 真实搜索均通过，三家均已有成功证据。Picker 测试夹具及审查发现的元数据恢复问题已修正，保留 v0.4.6 兼容性后全量 172 个测试通过。生产推广仍须先在 lab 安装验收同一组不可变发布产物。
-
-如果 profile 已安装 `dsh-composer-picker`，请先移除它。Model Switch 已经拥有 Composer Picker 和 Plan Review 席位；同时安装会产生重复或竞争 UI。
-
-生产 profile 必须使用已发布的注册表版本或 GitHub tag，不能使用工作区本地依赖。安装或修改路由后重启对应的 DSH profile。
-
-## 兼容性
-
-DSH Host peer 和开发依赖接受 `>=0.1.7-alpha.2`，包括 rc.1 和后续版本。开发锁文件解析到 rc.2。Cordis 接受 `>=4.0.4 <5.0.0`。
-
-已验证版本：`0.1.7-alpha.2`、`0.1.7-rc.1`、`0.1.7-rc.2`、`0.2.0-rc.2`。0.2.0 的声明覆盖三处差异：Host 改名的提问撤下动词（`cancel()` → `dismiss()`）、`session.selectModel` 不 await 的部署默认值写入、以返回值报出的 `ModelDirectory.select` 拒绝；三者均已在 lab（3082/3085）与真实桌面会话中逐一验证。
-
-`package.json#dsh.compatibility.dshReleases` 中的已验证版本是证据，不是允许列表。新增验证声明前要审查公开 API 变化并测试新 Host 版本。
-
-## 开发
-
-需要 Node 22.19+ 和 pnpm。
-
-```sh
-pnpm install
-pnpm run check
-```
-
-`check` 会构建 Host/Client artifacts，运行单元测试和 Cordis/Settings 组合测试，检查提取后的发布包，并验证 bundle 可复现。产品范围见 [PRODUCT.md](PRODUCT.md)，实现约束见 [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md)。
-
-## 正式版安装（Latest）
-
-本版在官方 DeepSeek Harness `0.1.7-rc.2` 与 `0.2.0-rc.2` 上验证了 Main、子代理、Composer、Plan Review 与能力路由；发布包只包含构建后的 Host/Client 产物，不包含兄弟仓库源码或本机路径。
-
-Latest 安装命令（资产文件名必须与当前 latest Release 一致）：
-
-~~~sh
-dsh plugin --profile web add --force \
-  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.14.tgz
-dsh plugin --profile web add --force \
-  https://github.com/NOirBRight/dsh-model-switch/releases/latest/download/dsh-model-switch-0.4.16.tgz
-~~~
-
-固定版本安装命令：
-
-~~~sh
-dsh plugin --profile web add --force \
-  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/download/v0.2.14/dsh-llm-providers-ui-0.2.14.tgz
-dsh plugin --profile web add --force \
-  https://github.com/NOirBRight/dsh-model-switch/releases/download/v0.4.16/dsh-model-switch-0.4.16.tgz
-~~~
-
-更新、卸载与验证：
-
-~~~sh
-# 更新到最新 Release
-dsh plugin --profile web add --force \
-  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.14.tgz
-dsh plugin --profile web add --force \
-  https://github.com/NOirBRight/dsh-model-switch/releases/latest/download/dsh-model-switch-0.4.16.tgz
-# 验证加载与版本
-dsh plugin --profile web list
-# 只卸载本插件
-dsh plugin --profile web remove dsh-model-switch
-~~~
-
-配置入口：Web 使用「设置」中的本插件页面；Host-only 插件使用 profile 的 dsh.profile.bundles 配置。先复制本 README 的最小 YAML/JSON 示例，再填写凭据或后端地址。
-
-回滚：重新安装不可变的 v0.4.15 归档并恢复已记录的 profile；不需要降级 Host。失败时查看 journalctl --user -u dsh-web.service，不要将源码 checkout 链入生产 profile。
-
-Release 与完整性：[v0.4.16](https://github.com/NOirBRight/dsh-model-switch/releases/tag/v0.4.16) · [SHA256](https://github.com/NOirBRight/dsh-model-switch/releases/download/v0.4.16/dsh-model-switch-0.4.16.tgz.sha256)。
+# Model Switch
+
+[English](README.md) | 中文
+
+在 DeepSeek Harness 中为 Main、Subagent、Web Search、图像生成、当前会话和 Plan 执行模型配置明确路由。Model Switch 只使用 DSH 公开服务和 Provider 自有 Adapter；不修改 DSH Core，也不管理 Provider 登录凭证。
+
+<p align="center"><img src="docs/screenshots/composer-picker.png" alt="包含 Model、Effort、Context 和 Fast 的 Composer Picker" width="314"></p>
+
+Picker 在切换页面或关闭搜索时保留键盘焦点，不覆盖搜索框的自动聚焦。从摘要页按 Escape 会关闭 Picker，并将焦点还给触发按钮。
+
+## 路由
+
+| 路由 | 行为 |
+| --- | --- |
+| Main 模型 | 新建会话的默认 provider、model 和可选 effort；不迁移已有会话。 |
+| Subagent | 跟随当前父请求，或使用固定 provider/model/effort；Workflow 显式覆盖始终优先。 |
+| Composer Picker | 只修改当前会话，并提交 catalog 中的原始 model id；Main 默认值保持不变。 |
+| Plan Review | 在发送 Plan 审核确认前，先提交执行模型。 |
+| Web Search | 保留官方 `web_search`；部署显式启用后，通过 Provider 动态声明的独立搜索适配器路由。 |
+| 图像生成 | 提供一个稳定的 `generate_image` 工具，通过选定的 Codex 或 Grok Adapter 路由。 |
+
+无效、不可用或不受支持的路由会明确失败。Model Switch 不会静默换到另一个 provider 或模型。
+
+空闲的空白会话可以选择 External Agent。提交中、等待首个 turn 以及运行期间，从请求开始就锁定所选执行运行时，不等待首 token 或原生绑定：Antigravity 保留其模型和 effort 选择；DSH 保留 LLM provider 选择，但禁用 Agent provider。会话一旦有过用户消息，Composer 和 Plan Review 仍显示 Agent 角色行但将其禁用，除非该会话已经绑定原生运行时。当前会话成功打开 Antigravity 原生会话后，Picker 会在该会话内禁用其他 provider，同时保留 Antigravity 模型与 effort 控件。DSH 全局 Picker 锁仍拥有最高优先级。
+
+## 配置 Main 和 Subagent
+
+打开 **设置 → Model Switch**。Main 修改只影响新建会话。Subagent 可以跟随 Main，也可以使用固定 provider、model 和 effort。
+官方 DSH `0.1.7-alpha.2` 在非本机浏览器将 ConfigForms 设为仅内存模式，页面会明确显示不可用；请在 Host 的 127.0.0.1 页面打开设置。此模式下 Picker 也拒绝模型切换：已发布的 `session.selectModel` 会同时写入全局默认模型，但只读 Main 表单无法安全恢复。远端编辑与真正仅会话的切换需要上游提供受鉴权的 ConfigForm 通道及仅会话的选择接口；本插件不会绕过官方策略。
+
+切换 Main 或固定 Subagent 的 provider/model 时，会用目标模型的默认 effort 替换旧模型的 effort；目标模型不支持推理时不传 effort。
+
+![Model Switch 设置中的固定 Subagent 路由](docs/screenshots/settings-subagent.png)
+
+Follow Main 先读取当前父请求，再读取配置的 Main 默认值。固定路由会在官方 Subagent descriptor 创建前注入。DSH 0.1.2-alpha.4 会在该 descriptor 中携带 provider、model 和固定 reasoning effort。
+
+## 自定义模型如何出现在 Picker
+
+Model Switch 不会把自身设置中任意填写的字符串变成模型。Provider 插件必须先把模型发布到 DSH 官方 Model Catalog：
+
+```text
+Provider 配置
+→ Provider 将模型行发布到 DSH Catalog
+→ 当前会话 Model Directory 提供 provider/model 元数据
+→ Model Switch 对 Catalog 行分组
+→ Picker 提交原始 provider id 和 model id
+```
+
+Catalog 提供 provider 名称、model id/name、reasoning efforts 和 default effort。已经保存但不再出现在 Catalog 中的路由，会在 Settings 中显示为 unavailable；Picker 不会假装它仍可路由。
+
+### 变体 id 规则
+
+Model Switch 按 provider，以及剥离以下后缀后的 model id 对 Catalog 行分组：
+
+| Catalog model id | Picker 变体 |
+| --- | --- |
+| `acme-v1` | 标准模型 |
+| `acme-v1-fast` | Fast |
+| `acme-v1-128k` | Context 128K |
+| `acme-v1-1m` | Context 1M |
+| `acme-v1-1m-fast` | Context 1M + Fast |
+
+规则：
+
+- `-fast` 生成 Fast 轴。
+- `-<n>k` 和 `-<n>m` 生成 Context 档位；可以与 `-fast` 按任意顺序组合。
+- `reasoning.efforts` 生成 Effort 选项；`reasoning.defaultEffort` 是初始值。
+- 切换 Fast、Context 或 Thinking 变体时，只有目标 Catalog 行支持当前 effort 才会保留；否则改用目标行的默认 effort，目标没有默认值时不传 effort。
+- Catalog 中存在 reasoning 元数据时，该模型行具备 Thinking 能力。
+- 无法识别的 id 不会被丢弃，而是作为独立 model family 显示。
+
+组合选择必须由 Provider 发布组合行。只有 `acme-v1-fast` 和 `acme-v1-1m` 不能表示 Fast + 1M；还必须发布 `acme-v1-1m-fast`。Picker 永远不会合成 Provider 没有发布的 model id。
+
+## Plan Review
+
+Plan Review 拥有独立于 Main 的执行模型草稿。**确认执行**会先把该模型提交到当前会话，再回答待处理的 Plan 审核。提交被拒绝时，审核保持待处理并允许重试；若会话模型已切换但部署默认模型未能还原，提示会在答复之后给出，而不是扣住你的决定。**拒绝**和**去聊天里说**不会执行 Plan。
+
+**拒绝**会发送提问方给出的选项，并把卡片反馈框里的文字作为答复自身的 `custom` 文本一并提交 —— plan 模式会把它作为"继续规划"的理由回报给模型，所以打回时可以带上要改什么。**去聊天里说**会撤下这张卡、把输入框还给你，用你自己的话说明；它在 Host 提供 `dismiss()` 时用它，在旧代际用 `cancel()`，两者都没有时明确指出这一点。审核一旦落定，**确认执行**与**拒绝**关闭，而**去聊天里说**与"重新加载"始终可达，卡片不会变成死路。失败会保留线上错误码（如 `session/writer-held: …`），而不是只给一句本地化文案。
+
+**设置为目标并执行** 会先把这份 Plan 设为当前会话的 goal、再答复，于是 `dsh-goal-round-driver` 能在退出计划模式后继续推进。它调用已发布的 `remote.goals.create`；若已存在一个未完成的 goal，会先 `clear` 再 `create`，让新 Plan 拿到完整轮次预算，并在替换后提示。目标设置被拒时审核保持待处理、错误带真实错误码（如 `GOAL_AGENT_NOT_LIVE: …`）；部署未挂 goal 服务时该按钮禁用并给出原因，其余三个动作照常可用。objective 取计划全文（trim 后）：goal 域不设长度上限，但它会作为模型可见上下文出现在每一轮续跑里，所以计划很长时每轮都花 token。
+
+卡片正文只显示计划的首行标题与首段摘要，**完整计划**会由官方 ui-plan 自动开到右侧侧边栏（头部的"查看完整计划"可随时再开）。接管的 composer 条目无权渲染官方的 `conversation.plan-review.actions` 槽位（每个子槽只允许一个声明者），因此卡片直接驱动 ui-plan 已注册的 opener——计划文档的地址与参数始终由 ui-plan 自己构造（见 `docs/seam-gap.md`）。
+
+![带执行模型 Picker 的 Plan Review](docs/screenshots/plan-review.png)
+
+## 发送时的上下文保护
+
+当发送后的实际请求将使用与上次不同的模型或窗口档位时，Model Switch 会在目标请求发出前检查完整待发上下文。仅在选择器中选模型不会压缩。超出目标可用容量时，使用切换前的模型、通过私有压缩引擎压缩一次历史；不会改 DSH 自身的自动压缩设置。进度以插件通知出现在正文中。预算包含完成提示和待提交的模型切换提示；摘要仍超限时会阻止请求。失败时用户消息留在会话里，不会发送目标模型请求，也不会出现切换成功提示。可在 **设置 → 模型切换 → 发送时自动检查并压缩上下文** 关闭（默认开启）。原生 External Agent 运行时的内部上下文不会被当成 DSH 可压缩历史。
+
+## 自动审查模型（Auto review）
+
+官方 `@deepseek-ai/dsh-experimental-auto-review`（Auto 权限预设的逐调用审查）把审查请求固定在会话自身的路由上。本插件通过 `cordis.patch.yml` 的行替换接管这一行：官方行被禁用，改挂 `dsh-model-switch/auto-review`，它在作用域子上下文里运行**同一份官方 `apply`**，只把 `llm.stream` 的 `provider/model` 改写为设置里固定的审查模型。设置页「自动审查模型」默认关闭 = 审查跟随当前会话模型；打开时从主模型种子化、可再改成任意 Provider/模型，保存后对下一次审查立即生效。审查未配置官方能力包（`@deepseek-ai/dsh-experimental-auto-review` 未随 profile 启动）时本行不挂载，Auto 预设保持官方的关闭状态；官方行若已在别处注册，本行明确报错而不产生第二个 `registerAuto`。
+
+## 压缩模型（Compaction model）
+
+官方压缩——`/compact` 与 DSH 的自动压缩——默认使用会话当前的目标模型做摘要。「压缩模型」卡片（默认关闭）改为固定摘要路由：打开时从主模型种子化、可再改成任意 Provider/模型，保存后对下一次压缩立即生效。两个字段都留空即回到官方默认。保存时若恰有压缩进行中，可能被打断并在下次重试。
+
+路由如何到达压缩引擎取决于部署在哪一层组合 agent。Web 面把压缩放进每个 Agent 预设的隔离 `compaction` 组里，而 profile patch 无法寻址 preset `plugins` 列表内部的行——因此本插件整表替换各预设行（与 Web 预设编辑器保存修改用的是同一套 id 定位机制），把该组的官方 `compaction-basic` 换成 `model-switch-compaction`，由它挂载**同一份官方 `BasicCompactionEngine`**、只覆盖 `summarizationProvider`/`summarizationModel`（只填其一忽略）。进程级组合 agent 的面（如 TUI）则走顶层行替换。两个后果：DSH 发布若改动这些预设，随包副本需要同步（本插件的逐版本核对覆盖这一步）；部署若用 Web 编辑器改预设，会写出自己的整表行、并从那之后自行负责合并。
+
+已知问题（上游侧，见 `docs/seam-gap.md`）：当工作集持续超过官方引擎的压力阈值时，自动压缩可能每步触发，并反复重试摘要过不了官方「摘要必须更小」守卫的小片段——表现为"不停自动压缩"，本插件不控制该行为（已在同一会话做过插件开/关 A/B 对照）。可用的缓解（都在转发行配置上）：`auto: false`（保留 `/compact`）、调高 `thresholdRatio`、减少挂载的工具 schema，或固定一个摘要更精炼的压缩模型。
+
+## 供应商配置组（Provider groups）
+
+「供应商配置组」卡片为每个供应商保存一组路由——压缩、子代理、审查三条路由一起存；当**主模型的供应商**发生变化时自动应用，无论变化来自输入框选择器选模型、还是在 Main 卡片上保存成别的供应商。应用是一次完整替换：三条路由一次性写入上方对应卡片，覆盖卡片当前值**（包括手动修改）**；组里没有固定的项回到该能力的默认值（压缩/审查跟随会话模型、子代理跟随主模型）。切换到没有配置组的供应商时现有路由保持不变，同一供应商内部切换不会重写路由。存储是 profile 级的（共享设置命名空间），不按会话生效，且只由这两个切换面触发——TUI 等其他切换不会动路由。编辑器里首次配置某供应商时从当前生效路由种子化；每行能力开关的关闭态表示"用该能力的默认值"并按默认存储；「删除该组」彻底移除该组（删掉最后一组时同时清掉存储字段）。搜索与图片路由不在本功能范围内。应用失败不会让切换或主模型保存失败：选择器侧记录警告并照常完成切换，Main 卡片侧提示"主模型已保存，但供应商组应用失败 …"，路由保持原样。
+
+## Model Switch 不会改变什么
+
+- `web_fetch` 及其配置的 provider
+- Vision 路由、`read_image` 和普通聊天附件
+- Provider 登录、凭证或 Provider 设置卡
+- 官方 Agent Presets
+- 已有的 Provider 专属图像工具
+- Main 默认值修改前已经存在的会话
+- 全局压缩策略、标题或 DSH Core
+
+## 安装
+
+Model Switch 交付的是预构建代码，安装不需要任何构建授权。从 npm 注册表安装：
+
+```sh
+dsh plugin --profile web add --force dsh-model-switch
+```
+
+打包好的 tarball 可以在不走注册表的情况下安装同一份构建：
+
+```sh
+dsh plugin --profile web add --force ./dsh-model-switch-0.4.17.tgz
+```
+
+然后只安装实际使用的 Provider Adapter。此版本已在官方 DeepSeek Harness `0.1.7-rc.2` 上检查，并在 `0.2.0-rc.2` 上验证：
+
+```sh
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.14.tgz
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-llm-codex/releases/latest/download/dsh-llm-codex-0.3.23.tgz
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-llm-grok/releases/latest/download/dsh-llm-grok-0.3.19.tgz
+```
+
+### 搜索供应商统一接入（0.4.7）
+
+搜索列表来自 Host 上已有的 `ModelSwitchAdapterRegistry`，Provider 自声明名称和独立搜索模型；浏览器只收到普通元数据，不收到凭据或可执行函数。注册、卸载会通知订阅者；原地修改模型声明最迟由 20 秒心跳更新。`ProviderDirectory` 继续负责客户端 role/usage，不另造注册表。 已发布 0.2.8 的 `sortCatalogGroups` 只排序硬编码 LLM 路由；Model Switch 自行按实时 `catalogRoutes` 排序，因此 Owner 公布 Agent catalog id 时会跟随已保存的卡片顺序。原生 `catalogId` / `unknown` 账户样式仍需要比已发布 0.2.8 更新的 Owner。模型原生联网不等于独立 `web_search` 适配器。
+
+DeepSeek 薄适配器调用官方公开 `DeepSeekSearchProvider`，复用用户的 `web-search-deepseek` 设置和公开凭据服务；Codex 复用 ChatGPT 登录，Grok 复用已有订阅凭据。缺凭据、配置错误、模型不支持均明确失败，不静默切换。
+
+**注册不等于选中全局路由。** 安装插件不再覆盖 Web 配置。部署时先用 `dsh --profile web --dump-config` 查看完整 Web 配置，只把 `searchProvider` 改为 `model-switch`，其余字段原样保留。注意 id 定位的 patch 会整体替换 `config`，不会深度合并；不能只写 searchProvider，也不能把自定义 fetchProvider 写死成 http。
+
+然后在 Model Switch 设置中选择请求的供应商/模型。全局已选 Model Switch、但没有完整且受支持的搜索配置时，官方选择层返回 `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`，不会回退 DeepSeek。全局未选 Model Switch 时，下拉框不控制官方搜索；未固定全局供应商且有多个可用 provider 时会明确报歧义。卸载前应恢复部署原来的搜索路由。官方 `web_search`、`web_fetch` 均不替换。
+
+本轮分支、测试命令及 3082 live 证据见 [搜索接入审计](docs/search-provider-audit.md)。经授权复用生产 DeepSeek 凭据后，Flash/Pro 的 3082 真实搜索均通过，三家均已有成功证据。Picker 测试夹具及审查发现的元数据恢复问题已修正，保留 v0.4.6 兼容性后全量 172 个测试通过。生产推广仍须先在 lab 安装验收同一组不可变发布产物。
+
+如果 profile 已安装 `dsh-composer-picker`，请先移除它。Model Switch 已经拥有 Composer Picker 和 Plan Review 席位；同时安装会产生重复或竞争 UI。
+
+生产 profile 必须使用已发布的注册表版本或 GitHub tag，不能使用工作区本地依赖。安装或修改路由后重启对应的 DSH profile。
+
+## 兼容性
+
+DSH Host peer 和开发依赖接受 `>=0.1.7-alpha.2`，包括 rc.1 和后续版本。开发锁文件解析到 rc.2。Cordis 接受 `>=4.0.4 <5.0.0`。
+
+已验证版本：`0.1.7-alpha.2`、`0.1.7-rc.1`、`0.1.7-rc.2`、`0.2.0-rc.2`。0.2.0 的声明覆盖三处差异：Host 改名的提问撤下动词（`cancel()` → `dismiss()`）、`session.selectModel` 不 await 的部署默认值写入、以返回值报出的 `ModelDirectory.select` 拒绝；三者均已在 lab（3082/3085）与真实桌面会话中逐一验证。
+
+`package.json#dsh.compatibility.dshReleases` 中的已验证版本是证据，不是允许列表。新增验证声明前要审查公开 API 变化并测试新 Host 版本。
+
+## 开发
+
+需要 Node 22.19+ 和 pnpm。
+
+```sh
+pnpm install
+pnpm run check
+```
+
+`check` 会构建 Host/Client artifacts，运行单元测试和 Cordis/Settings 组合测试，检查提取后的发布包，并验证 bundle 可复现。产品范围见 [PRODUCT.md](PRODUCT.md)，实现约束见 [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md)。
+
+## 正式版安装（Latest）
+
+本版在官方 DeepSeek Harness `0.1.7-rc.2` 与 `0.2.0-rc.2` 上验证了 Main、子代理、Composer、Plan Review 与能力路由；发布包只包含构建后的 Host/Client 产物，不包含兄弟仓库源码或本机路径。
+
+Latest 安装命令（资产文件名必须与当前 latest Release 一致）：
+
+~~~sh
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.14.tgz
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-model-switch/releases/latest/download/dsh-model-switch-0.4.16.tgz
+~~~
+
+固定版本安装命令：
+
+~~~sh
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/download/v0.2.14/dsh-llm-providers-ui-0.2.14.tgz
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-model-switch/releases/download/v0.4.16/dsh-model-switch-0.4.16.tgz
+~~~
+
+更新、卸载与验证：
+
+~~~sh
+# 更新到最新 Release
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.14.tgz
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-model-switch/releases/latest/download/dsh-model-switch-0.4.16.tgz
+# 验证加载与版本
+dsh plugin --profile web list
+# 只卸载本插件
+dsh plugin --profile web remove dsh-model-switch
+~~~
+
+配置入口：Web 使用「设置」中的本插件页面；Host-only 插件使用 profile 的 dsh.profile.bundles 配置。先复制本 README 的最小 YAML/JSON 示例，再填写凭据或后端地址。
+
+回滚：重新安装不可变的 v0.4.15 归档并恢复已记录的 profile；不需要降级 Host。失败时查看 journalctl --user -u dsh-web.service，不要将源码 checkout 链入生产 profile。
+
+Release 与完整性：[v0.4.16](https://github.com/NOirBRight/dsh-model-switch/releases/tag/v0.4.16) · [SHA256](https://github.com/NOirBRight/dsh-model-switch/releases/download/v0.4.16/dsh-model-switch-0.4.16.tgz.sha256)。