@nimoxie/dsh-model-organizer 0.3.6 → 0.5.11

package/README.md

@@ -1,73 +1,94 @@
-# dsh-model-organizer
-
-给 DSH（DeepSeek Harness）换个更好用的模型选择器：**按供应商分组、可折叠、可拖拽排序**。
-
-## 它解决什么问题
-
-官方那个模型下拉是一个扁平长列表——供应商只是粘性小标题，模型多的时候要滚很久，也没法按自己的习惯排序。这个插件把它改成两级：**根层先选「模型」或「推理等级」，模型层里按供应商分组**，供应商和模型的顺序都能直接拖。
-
-## 功能
-
-**输入框的模型菜单**
-- 根层与官方一致：「模型」「推理等级」两个入口——「推理等级」**常驻**，未配置等级的模型上置灰、不可点
-- 「模型」里保留本插件的改进：按供应商分组、可折叠，顺序与设置页浮窗一致，当前模型字体加粗高亮
-- 模型多于 4 个时，「模型」层顶部有官方同款的「搜索模型」框（0.2.0-rc.2 起官方才有此样式，旧版自动隐藏）
-- 外观完全沿用官方样式（同一个菜单表面、同一套图标，含官方的毛玻璃背景）
-
-**排序**
-- 在「设置 → 模型」右下角的浮窗里，**直接拖动**供应商行或模型行
-- 模型顺序通过官方设置接口持久化（跟着 DSH 的配置走，不存浏览器）；供应商顺序只记在当前浏览器里
-
-## 安装
-
-`<profile>` 是你的目标环境：浏览器版用 `web`，桌面客户端用 `desktop`。
-
-```sh
-dsh plugin --profile <profile> add @nimoxie/dsh-model-organizer
-```
-
-- 浏览器版（`web`）：装完重启服务（关掉再 `dsh web`）。
-- 桌面客户端（`desktop`）：桌面 profile 由客户端独占管理，请在客户端的「插件管理」页添加本包（包名 `@nimoxie/dsh-model-organizer`）。
-
-卸载（CLI 可管理的环境）：
-
-```sh
-dsh plugin --profile <profile> remove @nimoxie/dsh-model-organizer
-```
-
-也可以从 GitHub 或本地目录装（开发用）：
-
-```sh
-dsh plugin --profile <profile> add github:NimoXie15/dsh-model-organizer
-dsh plugin --profile <profile> add link:/absolute/path/to/dsh-model-organizer
-```
-
-> **兼容性**：已在 DSH `0.1.7`、`0.2.0-rc.1`（web）、`0.2.0-rc.2`（桌面端）上核验，`0.1.5` 起都可用。
->
-> 升级插件后如果界面没变化，按 **Ctrl+Shift+R** 强刷一次（浏览器可能还在用缓存的旧版本）。
-
-## 想让「推理等级」可用，需要模型自己声明
-
-「推理等级」入口常驻菜单根层；只有模型声明了等级，它才可点、才会在按钮上显示当前等级。在模型配置里加上（`llm-pi-ai.providers.<供应商>.models[]`；0.2.x 在 profile 的 `cordis.patch.yml`，0.1.x 在 `settings.yaml`）：
-
-```yaml
-# llm-pi-ai.providers.<供应商>.models[]（0.2.x 在 profile 的 cordis.patch.yml；0.1.x 在 settings.yaml）
-- id: <你的模型 ID>
-  reasoningEfforts:      # 键=菜单里显示的等级，值=选中时发给模型的 API 参数；只有 off 可以留空
-    off:
-    high: high
-```
-
-## 已知限制
-
-- 排序浮窗只列「设置 → 模型」里自己添加的供应商；**DeepSeek 官方供应商不能排序**，它们在设置页卡片和输入框菜单里都**固定在顶部**，照常出现、可选
-- 供应商顺序、浮窗位置只存在当前浏览器；模型顺序存在 DSH 的用户配置里，同一份 DSH 的所有设备共用——两台机器各装一份 DSH 则互不相通
-- 不修改 DSH 本体，只通过官方提供的扩展点接入
-
-## 许可
-
-MIT
-
----
-
-想自己改这个插件、或者想了解它内部怎么实现的，见 [DEVELOPMENT.md](./DEVELOPMENT.md)。
+# dsh-model-organizer
+
+给 DSH（DeepSeek Harness）换个更好用的模型选择器：**按供应商分组、可折叠、可拖拽排序**。
+
+## 它解决什么问题
+
+官方那个模型下拉是一个扁平长列表——供应商只是粘性小标题，模型多的时候要滚很久，也没法按自己的习惯排序。这个插件把它改成两级：**根层先选「模型」或「推理等级」，模型层里按供应商分组**，供应商和模型的顺序都能直接拖。
+
+## 功能
+
+**输入框的模型菜单**
+- 根层与官方一致：「模型」「推理等级」两个入口——「推理等级」**常驻**，未配置等级的模型上置灰、不可点
+- 「模型」里保留本插件的改进：按供应商分组、可折叠，顺序与设置页浮窗一致，当前模型字体加粗高亮
+- 模型多于 4 个时，「模型」层顶部有官方同款的「搜索模型」框（0.2.0-rc.2 起官方才有此样式，旧版自动隐藏）
+- 外观完全沿用官方样式（同一个菜单表面、同一套图标，含官方的毛玻璃背景）
+
+**排序**
+- 在「设置 → 模型」右下角的浮窗里，**直接拖动**供应商行或模型行
+- 模型顺序通过官方设置接口持久化（跟着 DSH 的配置走，不存浏览器）；供应商顺序只记在当前浏览器里
+
+**设置页：本插件自己的页面（接管「模型」这一行）**
+- 「设置 → 模型」这一行被本插件接管，点开就是本插件自己的页面（导航里仍然只有「模型」一行，本插件不会多占一格）。左栏最上是**只读的「官方（内置）」分组**——DeepSeek 官方那几条路由：悬停提示「官方路由 · 请到官方模型页编辑（点击前往）」，点一下会切回官方模型页（导航仍然是「模型」一行，配置不动）。下面是自己添加的供应商，按「官方目录 / 自定义供应商」分组，**都能拖动排序**（顺序只记在本机），行的悬停与抓握光标与设置页浮窗完全一致
+- 右栏编辑选中供应商：API 地址、API 格式（三种协议）即时保存；密钥粘贴后写入凭据库（页面读不回明文，可清除）
+- 模型列表的每一行是和供应商行同构的**一整行**（绿点 + 名称 + 参数摘要）：**按住整行就能拖动排序**（手感和官方模型页右下角浮窗里的供应商行一致），**单击打开「模型详情」弹窗**，在里面改这个模型的全部配置——模型 ID、显示名、上下文窗口、最大输出 token、输入模态（文本 / 图片）、推理等级（继承 / 不支持 / 自定义）、是否启用，也可以删除该模型；**保存后立即写回 DSH 配置**（保存按钮只在弹窗里；页面底部那个旧按钮和行内输入框都没了）
+- 模型列表右上角有「**获取可用模型**」：调用官方发现接口（DSH 目录里已有的供应商不发网络请求；自己加的网关才会去问 `GET {baseURL}/models`），弹出「选择要添加的模型」——可搜索、可全选，**勾选后点「添加所选」才写回配置**，取消或关闭不影响现有配置
+- 左栏列表末尾有虚线框「**+ 添加模型提供商**」（与官方模型页同一形态）：填路由 ID、显示名称、API 地址、API 格式、密钥、**至少一个模型 ID** 即可新建一条供应商路由；路由 ID 会做非空 / 字符集 / 重名校验，配置与密钥引用在**同一次写入**里落地
+- 模型 ID 是**必填**的：自己添加的路由不在 DSH 的目录里，配置里没有模型它就解析不出来（DSH 会直接报 "resolves no models"）。填好 API 地址与密钥后可以点「**从网关获取**」，它会按你填的地址去问一次网关，把模型 ID 自动填进来；也可以手动输入，多个用逗号或空格分隔
+- 供应商详情右上角（启用开关左边）有一个**垃圾桶图标按钮**（和界面其它图标同一套素材，悬停/读屏为「删除供应商」）：先弹确认，确认后移除这条自建路由的配置，并清理本页为它派生的密钥引用（别处配置的密钥不动）；官方路由不提供这个按钮
+- 每条模型行右侧有两个**带圆角边框的图标按钮**：**🔗 测试连接** = 让宿主去问该供应商的模型列表，并检查这个模型 ID 在不在其中（自建路由会真的访问网关、用已保存的密钥；目录已描述的路由直接读目录）。点击后图标变成**转圈**，结果换成 **✓**（可达且在列表）/ **⚠**（可达但不在列表）/ **✗**（失败），颜色区分、悬停看原因，**图标与按钮尺寸始终不变**；**🗑** = 从配置里删掉这个模型（每条路由至少保留一个）
+- 每行左侧的**绿点就是启用开关**：亮＝启用，暗＝停用。**启用 = 这一项出现在本插件的模型菜单里**；停用只是把它从**本插件的模型选择菜单**里移除（聊天框的模型菜单不再列出），**DSH 配置原样保留、随时可以点回来**。供应商行和模型行是同一个语义；状态与拖拽顺序一样存在本机
+- **默认接管官方「模型」页**：设置里**永远只有「模型」一行**（我们那格在两种状态下都隐藏），点它打开的就是被接管的那一页。**没有开关，按钮即状态**：本页标题右侧的「官方模型页」= 把这一行交还官方页；官方页浮窗里的「模型管理页」= 重新接替。两个方向都不改变菜单，只切换这一行背后的页
+- **每次打开「模型」都是我们的页**：接管状态不写盘（装了插件就以本插件的页为准）；「交还官方页」**只对这一次打开设置有效** —— 关掉设置再进来，又是本插件的页（重载/重启同理）。判定照官方条目的优先级**相对计算**（官方 −1 赢 / 官方 +1 交还），不写死数值
+- 两页互相能到：本页头部有「官方模型页」，官方模型页右下角的浮窗里有「模型管理页」（实现见 DEVELOPMENT.md 的 B3 一节）。浮窗的头部**始终渲染**：本插件能排序的供应商少于 2 个时只收起列表，返回本页的按钮不会跟着消失
+- 本插件不删改官方页面，只接管「模型」这一行的落点；导航里始终只有「模型」一行（做法见 [DEVELOPMENT.md](./DEVELOPMENT.md) 的 B2 / B3 两节）
+
+## 安装
+
+`<profile>` 是你的目标环境：浏览器版用 `web`，桌面客户端用 `desktop`。
+
+```sh
+dsh plugin --profile <profile> add @nimoxie/dsh-model-organizer
+```
+
+- 浏览器版（`web`）：装完重启服务（关掉再 `dsh web`）。
+- 桌面客户端（`desktop`）：桌面 profile 由客户端独占管理，请在客户端的「插件管理」页添加本包（包名 `@nimoxie/dsh-model-organizer`）。
+
+卸载（CLI 可管理的环境）：
+
+```sh
+dsh plugin --profile <profile> remove @nimoxie/dsh-model-organizer
+```
+
+也可以从 GitHub 或本地目录装（开发用）：
+
+```sh
+dsh plugin --profile <profile> add github:NimoXie15/dsh-model-organizer
+dsh plugin --profile <profile> add link:/absolute/path/to/dsh-model-organizer
+```
+
+> **兼容性**：已在 DSH `0.1.7`、`0.2.0-rc.1`（web）、`0.2.0-rc.2`、`0.2.1-rc.2`（桌面端）上核验，`0.1.5` 起都可用。
+>
+> 升级插件后如果界面没变化，按 **Ctrl+Shift+R** 强刷一次（浏览器可能还在用缓存的旧版本）。
+
+## 想让「推理等级」可用，需要模型自己声明
+
+「推理等级」入口常驻菜单根层；只有模型声明了等级，它才可点、才会在按钮上显示当前等级。
+
+0.5.0 起在「模型详情」弹窗里直接设置：推理等级选「继承」（沿用该模型已有的声明）、「不支持」，或「自定义」——自定义时逐行添加等级，**键 = 菜单里显示的等级，值 = 选中时发给模型的 API 参数**（只有 `off` 可以留空）。
+
+也可以直接在 profile 配置里给这个模型声明（0.2.x 在 `cordis.patch.yml`，0.1.x 在 `settings.yaml`）：
+
+```yaml
+# 该供应商的 models[] 条目（0.2.x 在 profile 的 cordis.patch.yml；0.1.x 在 settings.yaml）
+- id: <你的模型 ID>
+  reasoningEfforts:      # 键=菜单里显示的等级，值=选中时发给模型的 API 参数；只有 off 可以留空
+    off:
+    high: high
+```
+
+## 已知限制
+
+- 「测试连接」验证的是**地址 / 密钥 / 网关可达性，以及这个模型 ID 是否在网关返回的列表里** —— 它不会真的发一条消息给模型（DSH 的远程接口没有这个能力，客户端也读不回密钥）。所以「✓」只代表这条路由和这个 ID 是通的，不等于这个模型一定能补全
+- 设置页右下角的排序浮窗**只列你自己添加的供应商**（写进配置的那些），官方路由**根本不进这个浮窗**；想在左栏看到官方路由，看顶部只读的「官方（内置）」分组
+- 浮窗里排出的供应商顺序会**镜像**到官方模型页的卡片上；官方卡片（DeepSeek 官方等）被刻意保持在最前面
+- 供应商顺序、浮窗位置只存在当前浏览器；模型顺序存在 DSH 的用户配置里，同一份 DSH 的所有设备共用——两台机器各装一份 DSH 则互不相通
+- 不修改 DSH 本体，只通过官方提供的扩展点接入
+
+## 许可
+
+MIT
+
+---
+
+想自己改这个插件、或者想了解它内部怎么实现的，见 [DEVELOPMENT.md](./DEVELOPMENT.md)。