模型档案切换 fan56/dsh-profile-switch

dsh-profile-switch

一个 dsh 插件：具名模型配置档案，你可以通过宿主原生的 ask-user 流程进行交互式切换和配置——一套实现同时适用于 TUI 和 Web 界面，并在无头环境下快速失败并给出指引。

一个模型配置档案是你的整个模型配置的快照：

- 默认模型 + 思考级别（保存的 /model 选择），以及
- 可选的按子代理的模型/思考覆盖。

在不同上下文之间切换（work ↔ personal）变成一条命令，而不是一次 /model 加逐个代理的巡览。

“profile”在 dsh 中有两种不同含义——本插件指的是模型这一种。 dsh 的 profile（~/.dsh/profiles//、dsh --profile ）是启动时的插件组合；它在进程运行期间无法更改。本插件所切换的模型配置档案存放在 ~/.dsh/model-profiles.json 中，在运行时生效，并且作用域限定于绑定它们的 workspace 树。

安装

dsh plugin --profile add @aiwayds/dsh-profile-switch

需要 dsh ≥ 0.2.0-rc.2（peer 依赖下限）。该插件附带本地化的 Plugin-Manager 元数据（locale/en.json / locale/zh.json）以及一个 icon.svg，因此在宿主的 Plugin Manager 中会以正确的标题、描述和图标呈现。

该插件以 inject: ['commands', 'userQuestions'] 挂载——两者都是 dsh-base 服务，因此它可以与任何界面和任何插件栈共存。

设计上无需设置： 自 dsh 0.1.7 起，插件的 static Config 就是它的设置页注册，而本插件没有声明任何设置——它的数据是向导编辑的存储和下方的树绑定，通过命令管理，而非表单字段。无需从 0.1.7 之前的 settings.yaml 迁移任何内容。

命令

/profile-switch

一个问题：此 workspace 树绑定到哪个配置档案。回答后会分层应用该配置档案：

1. 实时默认模型——当存在实时选择通道时：在 TUI 上通过 dsh-tui-pi 的选择桥接，在 Web 上通过会话控制器。当前对话会立即在新模型上继续。没有通道时，摘要会说明这一点；该路由仍会在下一个会话通过树绑定生效。
2. 树绑定——将 .dsh-profile 写入当前目录（沿树向上最近的该文件生效，类似 .nvmrc 风格），因此此树中的每个新会话都会从该配置档案组装其初始选择。其他树不受影响：切换是 workspace 作用域的，绝不是机器全局的。
3. 子代理覆盖——在应用时不写入任何位置。每个代理的运行时模型/思考在生成时由代理文件 frontmatter 基线 ⊕ 此绑定配置档案的覆盖组合而成（每次派发时重新计算，包括续接），这正是使切换完全限定于 workspace 作用域的原因。

该切换有意不写入全局的 agent-default-model 设置——那仍然是 /model 的写入操作，而跨越树边界恰恰是配置文件切换绝不能做的事。

当树被绑定时，列表还会带有 (unbind this tree)：移除该固定（有保护——手工装饰的固定文件绝不会被覆盖；插件会拒绝并说明原因）。

/profile-cfg

配置向导——先是一个操作菜单，然后是匹配的流程：

| 操作 | 它会询问什么 |
| new | 名称 → 默认模型链 → 每个子代理的覆盖 |
| edit | 选择一个配置文件 → 重新回答同一条链（当前值会显示在问题中） |
| save-current | 名称 → 捕获当前实时选择（或部署默认值）→ 可选地快照每个已发现代理的基线 |
| rename | 选择一个配置文件 → 新名称 |
| delete | 选择一个配置文件 → 确认（最后一个剩余的配置文件会被拒绝） |

每个模型选择都是一条由独立的 ask-user 问题组成的三步收窄链——提供商 → 该提供商的模型 → 该模型的思考级别——因为每一步的选项都取决于前一个答案。所有三个列表都从已安装的 llm 适配器实时读取（listProviders / listModels / resolveModelInfo），因此思考级别正是适配器所提供的——绝不硬编码（llm-deepseek 路由会拒绝 medium；只有适配器知道某个模型接受什么）。没有列出任何内容的提供商会回退到手动输入模型 id；没有可选 effort 的模型会跳过思考步骤。

在任何地方取消（Esc / 关闭问题）都会中止向导，且不保存任何内容——存储只在最后写入一次。

子代理覆盖（配合 dsh-subagent-registry）

当安装了 dsh-subagent-registry 时，new/edit 向导会针对你已发现的代理（~/.dsh/agents/.md）添加一个多选，然后对每个选中的代理执行同样的提供商 → 模型 → 思考链——其中 (inherit) 位于每一步的开头。组合语义：

- 已记录的非空值优先于代理文件的 frontmatter；
- 空条目（两步都继承）记录一个显式继承；
- 配置文件中不存在的代理从基线组合。

没有该注册表时，覆盖将没有消费者，因此会跳过按代理的部分并附上说明，配置文件只保存主默认模型——检测是一个契约成员探测（composeAgentRuntime / readModelProfilesDoc / workspaceProfileName），与 dsh-tui-pi 确立的约定相同。

界面

| | TUI | web | headless |
| 问题渲染 | dsh-tui-pi 的 ask-user 停靠面板 | web 编辑器接管 | — |
| 实时默认模型切换 | 是（tui-pi 桥接） | 是（会话控制器） | 不适用 |
| 树绑定 + 存储 | 是 | 是 | 通过文件 |
| 无回答者行为 | — | — | 快速失败并给出指引 |

在没有 ask-user 回答者的界面上（headless 运行一个任务后退出），这些命令会快速失败并给出指向非交互路径的指引：写入 /.dsh-profile 并直接编辑 ~/.dsh/model-profiles.json。不会有任何挂起。

存储与文件

- ~/.dsh/model-profiles.json — 存储文件（遵循 $DSH_HOME）。带版本（version: 1），可自愈（损坏/未知文件会降级为预置的 work / personal / other 配置文件，绝不抛错），原子写入（临时同级文件 + 重命名）。此文件是一份共享契约： dsh-subagent-registry 会读取它（生成时组合），dsh-tui-pi 的会话引导也会读取它（从 pin 进行新会话预置）。Schema：

{
"version": 1,
"current": "work", // informational, last applied anywhere
"profiles": [
{
"name": "work",
"defaultModel": { "provider": "zai-coding-cn", "model": "glm-5.3", "reasoningEffort": "high" },
"agents": {
"workhorse": { "model": "volc-ark-plan/deepseek-v4-flash", "thinking": "high" },
"oldfox": {} // empty entry = explicit inherit
}
}
]
}

- /.dsh-profile — 树级 pin：一行，命名该配置文件；允许空行和 # 注释。插件在切换时覆盖它，仅当它解析为恰好一行条目时——手工修饰过的文件会被拒绝并上报，绝不会被覆盖。

与 dsh-tui-pi 的关系

模型配置文件功能从 dsh-tui-pi 迁移到了这里（此前它作为仅 TUI 面板承载该功能）。配对关系：

- 搭配提供 dshTuiModelSelection 桥接的 dsh-tui-pi： /profile-switch 也会实时切换当前 TUI 会话的默认模型；
- 搭配没有该桥接的较旧/较新 tui-pi：其他一切照常工作；实时部分降级为“此树中的下一个会话”，摘要中会说明这一点；
- tui-pi 的 /agents 管理器中的按 agent 编辑入口会以相同的 schema 写入同一个存储——两个编辑器共存；
- 建议在 TUI 上使用 dsh-tui-pi ≥ 2.18.1。 tui-pi 2.16.0–2.18.0 在将面板迁移到这里时，从它的永不中止调度列表中去掉了这些命令名，因此超过 90 秒的 /profile-cfg 会话会回显一个虚假的 aborted due to timeout（面板本身仍在工作； 2.18.1 恢复了调度）。在 web/无头界面上不存在此类防护，任何插件版本都可与任何版本配对。

任何地方都不需要手动配置配置文件：dsh plugin add 会协调 bundle 条目，bundle 补丁会挂载插件，命令会在配置文件启动的每个界面上注册。

卸载

dsh plugin --profile remove @aiwayds/dsh-profile-switch

该插件不拥有任何守护进程，也不持有任何宿主资源，因此卸载在下次启动时即可干净完成。你的数据会被有意保留：

- ~/.dsh/model-profiles.json — 如果你想删除该存储，就删掉它；
- /.dsh-profile pin — 按树删除（rm .dsh-profile）；命名了不存在配置文件的 pin 不会绑定任何内容。

开发

pnpm installmarkdown
pnpm build && pnpm check && pnpm test # 单元测试套件（先构建）
node scripts/smoke-boot.mjs # 真实主机启动门禁（需要全局 dsh）
pnpm contract # 与注册表的写↔读握手
（在无法解析注册表的地方自动跳过）

契约检查在真实文件上证明了部署后的三仓库形态：插件的存储写入（pin + 每代理覆盖）通过注册表的 composeAgentRuntime 组合回来——覆盖优先，显式继承和基线回退成立，并且探测环节确认 registryDetected() 通过配置文件的同级 node_modules 解析，与实时部署中完全一致。在没有注册表的机器/配置文件上，它会降级为有文档记录的跳过，因此可以在任何地方运行。

scripts/link-dsh-closure.mjs 将 node_modules/@deepseek-ai/ 重新指向全局 dsh CLI 自身的闭包，以便类型检查和测试只看到一个 cordis。CI 在 Node 22/24 上运行相同的步骤以及启动冒烟测试，并且每日计划会监视上游 rc/stable 的漂移。

许可证 — MIT。