模型排序 Wany-i/dsh-model-order

dsh-model-order

在 DeepSeek Harness 里调整模型顺序 —— 就在能看见它们的地方调。
消息框的模型菜单会跟着变，因为那本来就是同一个顺序。

dsh-model-order 在设置 → 模型页里，为每个 llm-pi-ai 路由的 provider 卡片加一块排序区。上移、下移、置顶、置底，按名称排序，或者恢复原样。你在这里定的顺序，就是消息框模型菜单显示的顺序。

功能 · 兼容性 · 安装 · 快速开始 · 配置 · 权限与数据 · 实现原理 · 排错 · 开发

功能

| 功能 | 说明 |
| ↕ 单步移动 | 上移 / 下移，与相邻模型互换位置 |
| ⇈ 移到两端 | 一次置顶或置底 |
| 🔤 按名称排序 | 自然序，m2 排在 m10 前；大小写不敏感且稳定 |
| ↩ 撤销 / 恢复 | 把顺序还原 —— 见两条恢复路径 |
| 🔒 顺序就存在你的配置里 | 顺序就是你已有的 models 数组，没有第二份需要同步 |
| 🧩 不改任何官方文件 | 通过官方 Models 页对外开放的插槽接入 |

顺序来自哪里

在 DSH 里，模型顺序只有一个事实来源：provider 配置里的 models 数组。下游每一层都保持它：

cordis.patch.yml providers.<route>.models: [ … ] │ ▼ dsh-llm-pi-ai · resolveRouteModels() 保持配置的顺序 ▼ ctx.llm.listModels(provider) 保持 ▼ buildModelCatalog() 保持，且按 provider 分组 ▼ 设置 → 模型页 按此渲染，并标出序号 1、2、3 …
▼ 消息框模型菜单 按此渲染；「组内模型顺序不变」

所以设置页的列表和消息框的菜单并不是两套需要保持一致的东西 —— 它们是同一个顺序被读了两次。这也是为什么在设置里改顺序，消息框就会跟着变，以及为什么本插件完全不需要去动消息框。

两条恢复路径

「恢复」在不同路由上含义不同，而决定权在 DSH 自己的适配器手里：

| 路由类型 | 按钮 | 行为 |
| pi-ai 内置目录覆盖的路由（anthropic、openai 等） | 恢复默认顺序 | 移除该路由的 models 列表，回落到 pi-ai 内置目录 |
| 手写声明的路由（router、中转、自建端点） | 撤销本次更改 | 把列表还原成打开卡片时的顺序，不删除任何内容 |

第二行是安全闸，不是功能缺失。对内置目录不描述的路由，pi-ai 适配器明确拒绝解析空的模型列表（"the installed catalog does not describe this route, so its models must be listed in configuration"）。对这类路由执行 unset 会让它一个模型都不剩并报 catalog error。因此本插件只在真正安全的地方提供破坏性重置，在其余地方提供非破坏性的撤销。若确实要对声明路由做真正的重置，请自行删除其 models 配置项 —— 一旦不可行，你会立刻看到报错。

兼容性

| 项 | 值 |
| DSH | web 与 desktop profile，>=0.2.0-rc.1 <0.3.0-0（已对 0.2.0-rc.2 验证） |
| Node | >=20（仅构建需要；插件直接发布预构建产物） |
| 依赖 | dsh-client-ui-settings-models（声明插槽）、dsh-client-ui-settings（设置读写）、dsh-client-ui-renderer（插槽注册表） |
| 作用范围 | llm-pi-ai 路由。DeepSeek 官方、DeepSeek 账号与第三方适配器家族均不受影响 |

安装 / 卸载

从 GitHub 安装（lib/ 已入库提交，无需本地构建）
dsh plugin --profile desktop add github:Wany-i/dsh-model-order

或从本地检出安装
npm install && npm run build
dsh plugin --profile desktop add file:/absolute/path/to/dsh-model-order

装完重启 DeepSeek Harness，然后硬刷新页面（Ctrl+F5）以重新拉取浏览器半边。

| 操作 | 命令 |
| 升级 | 重新执行 add，然后重启 |
| 卸载 | dsh plugin --profile desktop remove dsh-model-order |

快速开始

1. 打开设置 → 模型。
2. 找到你已经配置过模型的某个路由（例如 router），展开它的卡片。
3. 用箭头移动模型，或点按名称排序。
4. 打开消息框的模型菜单 —— 顺序已经一致。

如果某张卡片显示的是「该路由没有自己的模型列表…」而不是排序区，说明该路由在你的配置里没有 models 列表，它在沿用 pi-ai 内置目录。在为它声明模型之前没有可排序的内容 —— 见上文。

配置

没有。本插件没有自己的设置命名空间，也没有任何持久化偏好：它编辑的顺序就是你的配置，所以没有别的东西需要配置或同步。

增删模型请在同一张卡片里用官方编辑器完成；本插件只改它们的先后次序。

权限与数据

- 无网络访问。 插件不会建立任何连接。
- 不新增存储。 除了你所排序的那个路由的 models 数组，不写任何内容。
- 不修改任何模型字段。 每个操作都是对你配置里既有条目对象的重新排列：id、name、contextWindow、maxTokens、input，以及本插件根本不认识的任何字段，都逐字原样保留。不新增，也不删除。
- 写入带 revision 栅栏。 每次写入都携带编辑前读到的设置 revision，因此来自另一个标签页或外部 cordis.patch.yml 编辑的并发改动会被拒绝，而不是被静默覆盖。
- 只读部署保持只读。 控件会禁用并给出说明。

实现原理

1. 官方 Models 页对外开放了 settings.models.provider-card 插槽，专供仓库外的插件使用；凡渲染 provider 行的卡片都会以 entryKey = settingsNs 派发它。
2. 本插件在 pi-ai 家族的命名空间（llm-pi-ai）下注册一个 keyed 条目。不修改任何官方文件；未组合该家族的部署根本不会派发到这块区域。
3. 排序区通过 ctx.configForms 读取该路由用户层的 models 数组，并以单条 { op: 'set', path: ['providers', route, 'models'], value: [...] } 写回。
4. 整数组替换不是取巧 —— 它是设置层唯一支持的方式。其路径操作只做一层浅比较、不下钻数组节点，官方编辑器写模型列表时也是同样做法。

纯逻辑部分（src/order.ts、src/client/section.ts）不含 React、不含 DOM，因此可被直接测试；tsconfig 要求源码只使用可擦除语法，这样 node 无需构建即可直接运行它们。

排错

| 现象 | 原因与处理 |
| 完全没有出现排序区 | 浏览器半边未加载。重新执行 dsh plugin --profile desktop add <spec>，重启 DSH，再硬刷新页面。 |
| 任何卡片上都不出现 | pi-ai 家族被组合在 llm-pi-ai 以外的设置 entry id 下。派发键就是这个 id，需在 src/client/index.ts 的 PROVIDER_NAMESPACES 里写上它。此时插件不会渲染，也不会误动作。 |
| 我的路由上有，但某个未配置的内置路由上没有 | 符合预期：你从未配置过的路由不会显示说明，以免整页被提示淹没。 |
| 显示「该路由没有自己的模型列表」 | 符合预期：该路由沿用 pi-ai 内置目录。为它声明 models 后即可排序。 |
| 控件被禁用 | 设置文档为只读，或客户端处于 memory 模式（非 loopback 浏览器且无 Host 持久化）。 |
| 提示「设置在别处被改动…」 | 另一写入方推进了 revision，列表已刷新。请在刷新后的列表上重试。 |
| 排序结果看起来不对 | 采用自然序、大小写不敏感，优先按 name，否则按 id。 |
| 我的路由没有「恢复」入口 | 它是手写声明路由；请改用撤销本次更改，或自行删除 models。 |

开发

npm install
npm run verify # 类型检查 + 构建 + 全部测试
npm run watch # 变更即重建

| 路径 | 内容 |
| src/order.ts | 纯排序：移动、按名称排序、还原到捕获顺序 |
| src/client/section.ts | 纯形状知识：models 在哪、写入 op 长什么样 |
| src/client/ModelOrderCard.tsx | 插槽贡献组件 |
| src/client/index.ts | 注册与设置读写面 |
| src/index.ts | 宿主半边 —— 刻意留空 |
| test/order.spec.mjs、test/section.spec.mjs | 纯模块的行为契约 |
| test/patch.spec.mjs | 打包契约：patch ↔ manifest ↔ bundle |
| test/bundle.spec.mjs | 集成：加载构建产物并跑通注册链路 |

集成面的类型声明来自官方已发布包，并锁定为与运行时相同的版本。若要适配另一个 DSH 版本，请同步对齐 @deepseek-ai/* 这批 devDependency 的版本。

package.json 里的仓库地址指向 Wany-i/dsh-model-order；若你在别的账号下发布，请一并修改。

许可证

MIT