dsh-model-groups 0.3.2 → 0.3.3

package/README.md

@@ -1,127 +1,160 @@
-# dsh-model-groups 0.3.2（0.2.2-rc.1 移植版）
+# DSH Model Groups
 
-在 DSH 原生「自定义模型 API」卡片内管理**同一个供应商的多个密钥配置**，并把会话模型菜单显示为「供应商 → 密钥配置 → 模型」。这不是密钥轮换器，也不是另建一页大、小分组配置。
+给 DeepSeek Harness 的模型选择菜单增加分层折叠，并在自定义模型 API 中管理多份密钥配置。
 
-## 使用方式
+- 按“供应商 → 密钥配置 → 模型”展开和选择。
+- 同一供应商的多份配置可以使用相同的模型 ID，选择时分别使用对应密钥。
+- 支持名称搜索、全部展开、全部收起，以及折叠状态记忆。
+- 模型和密钥由用户手动选择，不自动轮换或切换配置。
 
-1. 打开 **设置 → 模型**，新增或编辑原生的**自定义模型 API**。
-2. Provider ID、API 地址、协议只填写一次，所有密钥配置共享这些设置。
-3. 打开卡片内的 **多密钥配置** 开关，按需点击 **添加密钥配置**。每个配置分别填写配置名称、API 密钥、模型列表，然后应用。
-4. 在会话模型菜单中展开供应商，再展开需要的密钥配置，选择模型。
+## 适用范围
+
+**当前版本仅支持 DSH `0.2.2-rc.1` 的 Harness 网页界面，安装脚本需要 Node.js 22 或更新版本。**
+
+在 dsh-go 手机上使用时，功能出现在对应的 Harness 网页中。dsh-go 原生聊天界面的模型菜单不在本插件的修改范围内。
+
+完整安装包括两部分：**注册客户端插件**，以及**应用五项 DSH 兼容补丁**。只安装 npm 包不会自动应用补丁。补丁用于让模型设置、模型发现和请求发送共同识别每份密钥配置。
+
+## 交给 AI 安装
+
+把下面整段复制给能够访问 DSH 安装环境的 AI。这是一项安装任务，不是文档审阅任务。
 
 ```text
-示例供应商 A（同一个 Provider ID / API 地址）
-  配置 A（独立密钥）
-    示例模型
-  配置 B（另一份密钥）
-    示例模型
-示例供应商 B
-  示例模型
+请帮我安装 dsh-model-groups，并完成安装后的验证。
+
+官方说明：
+https://github.com/betsunninda9-lgtm/dsh-model-groups
+
+请实际执行安装，不要只评价文档或给出命令建议：
+1. 确认当前使用的 DSH 主机、profile 和界面。该插件仅支持
+   DSH 0.2.2-rc.1 的 Harness 网页界面；版本不符就停止并说明。
+2. 阅读仓库当前 README，使用 npm 官方源下载当前版本，
+   解压到长期保留的插件目录。不要修改供应商、密钥或模型配置。
+3. 找到正在使用的 DSH 实际安装目录，核对包名与版本。
+   不要把插件目录当成 DSH 目录，也不要猜测安装路径。
+4. 在解压后的插件目录执行 native-patches.mjs 的 --check，
+   显式传入 --dsh-root。遇到哈希或版本不符就停止，不强制覆盖。
+5. 用 dsh plugin --profile <当前profile> add <插件绝对路径>
+   注册插件。只有当前实例使用 web profile 时才填写 web。
+6. 在合适的停机窗口应用兼容补丁；如果当前对话依赖这个引擎，
+   先完成可在线执行的步骤，再告诉我如何停止、应用补丁和重启。
+   不要直接中断正在进行的对话。
+7. 重启原来使用的 DSH 服务并刷新原网页，核对模型菜单分组和
+   设置页“多密钥配置”开关。不要启动另一个服务代替原服务。
+8. 报告安装版本、插件目录、补丁检查结果，以及是否仍需我重启。
+   不要把下载成功或插件注册成功当成整项安装已完成。
 ```
 
-- **未开启多密钥配置的供应商保留原来的折叠方式**，不会平铺全部模型。
-- 供应商和密钥配置独立折叠；收起父级不清除子级折叠状态。
-- 配置数量按需增删，不设置固定的数量上限。名称去除首尾空格，长度为 1–120 个字符；保存时每个配置至少包含一个模型。
-- 相同模型 ID 可以同时出现在不同配置中；选择保留精确配置身份，不因同名而合并。
-- 只使用手动选中的配置。密钥缺失、配置移除或多密钥配置关闭时，旧配置选择会失败或从菜单移除，**不会改用其他密钥、轮换或自动故障切换**。
-- 保存前可用输入的 API 密钥获取模型；已保存的配置按其精确标识在宿主查询。不会默默改用供应商原来的密钥。
-- API 密钥使用原生的只写输入与凭据服务，不会回显已保存的明文。留空保留原凭据；替换共享引用的密钥需要明确确认。
+## 手动安装
 
-### 界面与关闭保护
+以下命令适用于 Bash 环境。先确认 DSH 版本，再执行。
 
-- 「多密钥配置」使用原版开关组件与表单字体；标题与开关左右对齐。
-- 配置名称位于卡片内部的标题栏，移除按钮在标题栏右侧；不再使用挂在边框上的图例标题。长名称与凭据引用允许换行。
-- 支持多密钥的已有自定义供应商先显示「公共设置」，再显示密钥配置；其他供应商保持原有表单顺序与折叠状态。
-- 点击关闭不会立即停用，先显示原生确认弹窗。取消、关闭按钮、Escape 或遮罩关闭只取消确认，不会改变开关或丢弃输入；确认后仍须点击「应用」才改变运行配置。
-- **有尚未保存的 API 密钥输入时禁止确认关闭**，只提供「返回密钥配置」。输入仅为空格也触发保护；凭据保存失败留下的输入同样受保护。先保存成功，或明确清空不需要的输入，再关闭。
+### 1. 下载并解压
 
-## 兼容与数据保全
+```bash
+PLUGIN_DIR="${DSH_HOME:-$HOME/.dsh}/local-plugins/dsh-model-groups-0.3.3"
+mkdir -p "$PLUGIN_DIR"
+cd "$PLUGIN_DIR"
+npm pack dsh-model-groups@0.3.3 --registry=https://registry.npmjs.org/
+tar -xzf dsh-model-groups-0.3.3.tgz --strip-components=1
+```
 
-开启已有供应商的多密钥配置时，首个配置从原单密钥配置复制**密钥引用和模型配置**，不读取密钥值。原单密钥配置仍保留，用于关闭多密钥配置及已有旧会话。
+这一步只准备插件文件。请保留该目录，后续注册与补丁回退都需要使用它。
 
-旧会话中未带配置标识的模型继续使用原来的密钥，不会按同名模型猜测新配置。会话当前仍选用旧模型时，菜单会显示「原单密钥（兼容旧会话）」子项供辨认；其他旧模型不会混入多密钥配置的可选项。切换到新配置需要主动选择。
+### 2. 确认 DSH 目录并检查补丁
 
-关闭并应用会保留所有已保存的密钥配置与凭据，并恢复原单密钥模式；重新开启并应用后可再次使用这些配置。正在使用密钥配置的会话需要重新开启，或手动选择单密钥模型，不会自动换用其他密钥。移除配置也不删除已存储的凭据；需要清理时请单独使用原生凭据管理。
+`DSH_ROOT` 是正在使用的 DSH 安装目录：该目录本身或其 `node_modules/@deepseek-ai/dsh` 下的包应为 `@deepseek-ai/dsh@0.2.2-rc.1`，且该目录下包含补丁要修改的 `node_modules/@deepseek-ai/` 文件。它不是插件目录、profile 目录或项目工作目录。
 
-**不会自动合并以前分别建立的供应商。** 特别是 API 地址不同的渠道不能直接合并；迁移须由使用者确认共享地址、密钥和模型归属后手动完成。此次实现不改既有真实密钥、接口地址或模型列表。
+下面会询问实际路径，不要直接填写示例路径：
 
-上一版独立的「模型分组」页脚与 `providerGroups` 显示配置已撤回；本版直接使用原生 `llm-pi-ai.providers` 下的 `multiKey`、`keyEntries`。折叠状态继续使用本机 `localStorage` 的 `dsh:model-groups:v1`；原 Provider ID 的记录仍然有效，密钥配置子项使用独立键。
+```bash
+read -r -p '请输入实际 DSH 安装目录：' DSH_ROOT
+node scripts/native-patches.mjs --dsh-root "$DSH_ROOT" --check
+```
 
-## 搜索与键盘
+成功时会列出五个目标文件。`pristine` 表示尚未应用，`patched` 表示已应用本插件对应的补丁。版本、内容或路径不匹配时，脚本报错并停止；请先解决原因。
 
-- 搜索支持供应商、密钥配置及模型名称；搜索时临时展开匹配路径，清空后恢复原有折叠状态。
-- 全部展开 / 全部收起同时作用于供应商和密钥配置。
-- `↑` / `↓` 在工具条、标题和可见模型间移动；标题上的 `←` / `→` 收起 / 展开，`Enter` / 空格切换。
-- 搜索框内 `↑` / `↓` 移动高亮，`Enter` / `Tab` 选择；`Esc` 返回上一层或关闭菜单。
-- 保留官方模型目录、推理等级、加载重试、标签插槽、锁定和错误提示。渲染异常时使用同样校验配置有效性的简化菜单。
+### 3. 注册插件
 
-## 安装与生效边界
+以下以 `web` profile 为例；其他实例请填写其实际 profile 名称：
 
-本版包括客户端插件与**原生兼容补丁**。仅安装插件不能使宿主识别同 Provider 的多个密钥；纯前端分组不能保证实际请求用对密钥。
+```bash
+dsh plugin --profile web add "$PLUGIN_DIR"
+```
 
-原生补丁仅适配 **DSH 0.2.2-rc.1**，同时校验包名、版本和目标文件 SHA-256。它扩展原生 pi-ai 适配器、模型设置卡片，以及宿主 / 客户端 / 浏览器内嵌的模型发现编解码。补丁不复制凭据库，不创建重复的 Provider，不启动第二个服务。
+注册成功仍不代表兼容补丁已经生效。
 
-本插件用于 Harness Web 界面；在 dsh-go 中请打开对应的 Harness 网页界面使用。它不向 Flutter 原生模型选择器注入界面。
+### 4. 应用补丁并重启
 
-从 npm 获取可检查的插件目录（发布后可用）：
+保存正在编辑的内容，停止正在使用的 DSH 服务。在外部终端回到步骤 1 的插件目录，使用步骤 2 确认的 DSH 路径执行：
 
 ```bash
-npm pack dsh-model-groups@0.3.2 --registry=https://registry.npmjs.org
-mkdir dsh-model-groups
-tar -xzf dsh-model-groups-0.3.2.tgz -C dsh-model-groups --strip-components=1
-cd dsh-model-groups
+read -r -p '请输入实际 DSH 安装目录：' DSH_ROOT
+node scripts/native-patches.mjs --dsh-root "$DSH_ROOT" --apply
 ```
 
-请保留该目录，安装会引用它。安装过程不会自动执行宿主补丁。
+补丁脚本会校验版本与文件哈希，备份原文件后写入变更。已经应用的补丁会跳过；脚本不会启动或停止 DSH。
 
-```bash
-# 在插件目录操作；路径必须是实际安装的 DSH 根目录
-node scripts/native-patches.mjs --dsh-root /实际安装的DSH根目录 --check
+用原来的方式启动 DSH，然后刷新原网页。dsh-go 本机环境中，先准备好外部终端的执行方式，再停止引擎；停止后当前 AI 对话无法继续替你执行命令。
+
+### 5. 确认安装结果
+
+- 会话中的模型菜单按供应商分组，能够展开和收起。
+- 在“设置 → 模型”编辑支持的自定义模型 API，可以看到“多密钥配置”开关。
+- 开启并保存多份配置后，模型菜单出现对应的配置层级。
+
+只有客户端分组出现、设置页没有新开关时，请检查五项补丁是否全部应用，以及原 DSH 服务是否已重启。
+
+## 使用方法
+
+在“设置 → 模型”新增或编辑自定义模型 API，填写公共的 Provider ID、API 地址和协议。开启“多密钥配置”，为每份配置填写名称、密钥和模型列表，点击“应用”保存。
 
-# 空闲时先停止原 DSH 服务，再应用补丁
-node scripts/native-patches.mjs --dsh-root /实际安装的DSH根目录 --apply
+例如，两个配置都提供同一模型时，菜单中会分别显示：
 
-# 安装客户端插件（已安装者无需重复添加）
-dsh plugin --profile web add /绝对路径/dsh-model-groups
+```text
+示例供应商 A
+  配置 A
+    示例模型
+  配置 B
+    示例模型
+示例供应商 B
+  示例模型
 ```
 
-检查模式只读；应用前先验证所有目标，拒绝未知版本或被其它修改覆盖的文件。原文件会备份，全部内容写入同目录临时文件成功后再逐个原子替换；后续失败会尽量回滚已替换文件，不覆盖并发的外部修改。重复应用为无操作。补丁脚本不会重启或热重载运行中的进程。
+选择哪个配置，就使用哪份配置的密钥。搜索供应商、配置或模型名称时，匹配路径会临时展开；清空搜索后恢复原来的折叠状态。
+
+已有的单密钥配置会保留。旧会话仍使用原来的选择，需要时可手动切换到新配置。关闭多密钥配置会保留已保存的配置和凭据；删除某份配置也不会同时删除凭据。存在未保存的密钥输入时，需要先保存或清空输入，才能确认关闭。
 
-**首次应用宿主补丁后须重新启动原 DSH 服务，再刷新原有页面。** 只刷新页面、只重编客户端或反复开关插件，不能保证已加载的宿主模块和缓存的客户端元数据更新。不要另起服务器替代正在使用的 GUI。新开关也会检查宿主 schema：旧宿主尚未重新加载时保持原来的单密钥界面，不暴露无法保存的新配置。
+插件不会自动合并已有供应商，也不会替用户迁移密钥。API 地址不同的服务应分别配置。
 
-后续只改模型设置客户端界面时，不代表必须重启宿主；但需核对原服务提供的实际客户端文件已更新，再刷新原页面。不要把磁盘生成成功或组件测试通过当成真实页面已经生效。刷新前先保存正在编辑的内容，避免丢失草稿。
+## 升级与卸载
 
-DSH 升级可能覆盖这些原生文件；不要强行把此版本补丁用于新版本，应先重新适配并验证。
+**DSH 升级后，请先确认插件支持的新版本，不能把本版补丁强行应用到其他 DSH 版本。**
 
-### 卸载 / 回退
+仅停用或移除客户端插件不会还原 DSH 兼容补丁。完整卸载前：
 
-先在相关会话中切换回原单密钥模型，并关闭各供应商的多密钥配置；使用者需确认所有保存的会话 / 子代理配置都不再选择 `@dsh-key/` 内部标识。随后空闲时停止原服务，再执行：
+1. 在相关会话和子代理配置中切换回普通单密钥模型，确认不再使用带 `@dsh-key/` 前缀的选择。
+2. 关闭各供应商的多密钥配置并应用。备份 DSH 配置后，清理原版 DSH 不支持的 `multiKey`、`keyEntries` 配置字段；保留仍需使用的单密钥配置和凭据。
+3. 停止 DSH，在保留的插件目录中执行下面命令，再启动原服务。
 
 ```bash
-node scripts/native-patches.mjs --dsh-root /实际安装的DSH根目录 --revert
+read -r -p '请输入实际 DSH 安装目录：' DSH_ROOT
+node scripts/native-patches.mjs --dsh-root "$DSH_ROOT" --revert
 dsh plugin --profile web remove dsh-model-groups
 ```
 
-恢复原单密钥配置后，应在回退原生 schema 前移除不再受支持的 `multiKey`、`keyEntries` 字段（先备份配置，不删除原来的密钥与模型）。回退脚本仅恢复原生代码，不扫描或修改真实会话 / 配置 / 凭据，也不会自动证明回退前提已满足。仍选择内部配置标识的旧会话在原生补丁移除后无法发送请求。
+其他 profile 请替换 `web`。还原脚本只恢复代码，不会替用户修改会话、配置或凭据；仍引用多密钥模型的会话在还原后将无法继续使用该选择。
 
-## 实现与验证
+## 开发
 
-内部模型标识为 `@dsh-key/<配置ID>/<编码后的上游模型ID>`，只用于保存选择身份；Provider ID 不变。适配器在请求边界解析它，使用独立配置的模型元数据和凭据引用，上游收到的仍是原始模型 ID。已准备请求保留当时的配置快照；跨密钥的签名历史不会直接复用到另一密钥。
+从 GitHub 获取源码后，运行：
 
 ```bash
 npm run build
 npm test
-npm run test:ui
 npm run check:build
-npm run native:check -- --dsh-root /实际安装的DSH根目录
 ```
 
-- [层级逻辑](src/hierarchy.js)、[会话选择器](src/model-select.js)、[回退菜单](src/fallback.js)和[样式](src/groups.css)由[构建脚本](scripts/build.mjs)生成客户端产物。
-- [原生补丁管理器](scripts/native-patches.mjs)提供版本 / 哈希检查、应用与还原；[补丁目录](native/)存放可重放变更。
-- 仓库内的测试覆盖层级、折叠状态、样式生命周期、客户端注册与[选择器交互](test/picker-ui.test.mjs)，不读取真实凭据。
-- 公开仓库不包含本机的宿主备份、配置、会话或依赖手机目录的历史测试。适配器与原生设置页的完整集成验收需要单独准备对应版本的 DSH 环境。
-- [补丁安装器回归](test/native-patches.test.mjs)在临时目录实际应用 / 回退，并模拟写入失败、原子替换失败和并发修改；不重装或重启真实服务。
-
-这些自动化检查不等于真实浏览器端到端验收。手机窄屏布局、中文输入法、原生菜单 portal 和刷新后的实际卡片，仍须在原页面检查。未获得重启授权时，不会为了验收中断当前会话。
+需要检查真实 DSH 目标文件时，可设置 `DSH_ROOT` 后运行测试。测试覆盖层级、折叠状态、选择器交互和补丁安装器；真实网页中的安装验收仍需按上文完成。
 
-客户端选择器改编自 DSH 的 MIT 代码，见 [LICENSE](LICENSE)。
+本项目采用 MIT 许可证。客户端选择器包含改编自 DeepSeek Harness 的代码，保留原版权声明。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-model-groups",
-  "version": "0.3.2",
-  "description": "同一供应商的多密钥配置与供应商→密钥配置→模型折叠选择，手动精确路由（0.2.2-rc.1 移植版）。",
+  "version": "0.3.3",
+  "description": "DSH 网页模型选择器：供应商与密钥配置分层折叠、多密钥手动选择。支持 DSH 0.2.2-rc.1。",
   "type": "module",
   "license": "MIT",
   "repository": {