dsh-model-groups 0.0.0-stage → 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# dsh-model-groups 0.3.2（0.2.2-rc.1 移植版）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+在 DSH 原生「自定义模型 API」卡片内管理**同一个供应商的多个密钥配置**，并把会话模型菜单显示为「供应商 → 密钥配置 → 模型」。这不是密钥轮换器，也不是另建一页大、小分组配置。
+
+## 使用方式
+
+1. 打开 **设置 → 模型**，新增或编辑原生的**自定义模型 API**。
+2. Provider ID、API 地址、协议只填写一次，所有密钥配置共享这些设置。
+3. 打开卡片内的 **多密钥配置** 开关，按需点击 **添加密钥配置**。每个配置分别填写配置名称、API 密钥、模型列表，然后应用。
+4. 在会话模型菜单中展开供应商，再展开需要的密钥配置，选择模型。
+
+```text
+示例供应商 A（同一个 Provider ID / API 地址）
+  配置 A（独立密钥）
+    示例模型
+  配置 B（另一份密钥）
+    示例模型
+示例供应商 B
+  示例模型
+```
+
+- **未开启多密钥配置的供应商保留原来的折叠方式**，不会平铺全部模型。
+- 供应商和密钥配置独立折叠；收起父级不清除子级折叠状态。
+- 配置数量按需增删，不设置固定的数量上限。名称去除首尾空格，长度为 1–120 个字符；保存时每个配置至少包含一个模型。
+- 相同模型 ID 可以同时出现在不同配置中；选择保留精确配置身份，不因同名而合并。
+- 只使用手动选中的配置。密钥缺失、配置移除或多密钥配置关闭时，旧配置选择会失败或从菜单移除，**不会改用其他密钥、轮换或自动故障切换**。
+- 保存前可用输入的 API 密钥获取模型；已保存的配置按其精确标识在宿主查询。不会默默改用供应商原来的密钥。
+- API 密钥使用原生的只写输入与凭据服务，不会回显已保存的明文。留空保留原凭据；替换共享引用的密钥需要明确确认。
+
+### 界面与关闭保护
+
+- 「多密钥配置」使用原版开关组件与表单字体；标题与开关左右对齐。
+- 配置名称位于卡片内部的标题栏，移除按钮在标题栏右侧；不再使用挂在边框上的图例标题。长名称与凭据引用允许换行。
+- 支持多密钥的已有自定义供应商先显示「公共设置」，再显示密钥配置；其他供应商保持原有表单顺序与折叠状态。
+- 点击关闭不会立即停用，先显示原生确认弹窗。取消、关闭按钮、Escape 或遮罩关闭只取消确认，不会改变开关或丢弃输入；确认后仍须点击「应用」才改变运行配置。
+- **有尚未保存的 API 密钥输入时禁止确认关闭**，只提供「返回密钥配置」。输入仅为空格也触发保护；凭据保存失败留下的输入同样受保护。先保存成功，或明确清空不需要的输入，再关闭。
+
+## 兼容与数据保全
+
+开启已有供应商的多密钥配置时，首个配置从原单密钥配置复制**密钥引用和模型配置**，不读取密钥值。原单密钥配置仍保留，用于关闭多密钥配置及已有旧会话。
+
+旧会话中未带配置标识的模型继续使用原来的密钥，不会按同名模型猜测新配置。会话当前仍选用旧模型时，菜单会显示「原单密钥（兼容旧会话）」子项供辨认；其他旧模型不会混入多密钥配置的可选项。切换到新配置需要主动选择。
+
+关闭并应用会保留所有已保存的密钥配置与凭据，并恢复原单密钥模式；重新开启并应用后可再次使用这些配置。正在使用密钥配置的会话需要重新开启，或手动选择单密钥模型，不会自动换用其他密钥。移除配置也不删除已存储的凭据；需要清理时请单独使用原生凭据管理。
+
+**不会自动合并以前分别建立的供应商。** 特别是 API 地址不同的渠道不能直接合并；迁移须由使用者确认共享地址、密钥和模型归属后手动完成。此次实现不改既有真实密钥、接口地址或模型列表。
+
+上一版独立的「模型分组」页脚与 `providerGroups` 显示配置已撤回；本版直接使用原生 `llm-pi-ai.providers` 下的 `multiKey`、`keyEntries`。折叠状态继续使用本机 `localStorage` 的 `dsh:model-groups:v1`；原 Provider ID 的记录仍然有效，密钥配置子项使用独立键。
+
+## 搜索与键盘
+
+- 搜索支持供应商、密钥配置及模型名称；搜索时临时展开匹配路径，清空后恢复原有折叠状态。
+- 全部展开 / 全部收起同时作用于供应商和密钥配置。
+- `↑` / `↓` 在工具条、标题和可见模型间移动；标题上的 `←` / `→` 收起 / 展开，`Enter` / 空格切换。
+- 搜索框内 `↑` / `↓` 移动高亮，`Enter` / `Tab` 选择；`Esc` 返回上一层或关闭菜单。
+- 保留官方模型目录、推理等级、加载重试、标签插槽、锁定和错误提示。渲染异常时使用同样校验配置有效性的简化菜单。
+
+## 安装与生效边界
+
+本版包括客户端插件与**原生兼容补丁**。仅安装插件不能使宿主识别同 Provider 的多个密钥；纯前端分组不能保证实际请求用对密钥。
+
+原生补丁仅适配 **DSH 0.2.2-rc.1**，同时校验包名、版本和目标文件 SHA-256。它扩展原生 pi-ai 适配器、模型设置卡片，以及宿主 / 客户端 / 浏览器内嵌的模型发现编解码。补丁不复制凭据库，不创建重复的 Provider，不启动第二个服务。
+
+本插件用于 Harness Web 界面；在 dsh-go 中请打开对应的 Harness 网页界面使用。它不向 Flutter 原生模型选择器注入界面。
+
+从 npm 获取可检查的插件目录（发布后可用）：
+
+```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
+```
+
+请保留该目录，安装会引用它。安装过程不会自动执行宿主补丁。
+
+```bash
+# 在插件目录操作；路径必须是实际安装的 DSH 根目录
+node scripts/native-patches.mjs --dsh-root /实际安装的DSH根目录 --check
+
+# 空闲时先停止原 DSH 服务，再应用补丁
+node scripts/native-patches.mjs --dsh-root /实际安装的DSH根目录 --apply
+
+# 安装客户端插件（已安装者无需重复添加）
+dsh plugin --profile web add /绝对路径/dsh-model-groups
+```
+
+检查模式只读；应用前先验证所有目标，拒绝未知版本或被其它修改覆盖的文件。原文件会备份，全部内容写入同目录临时文件成功后再逐个原子替换；后续失败会尽量回滚已替换文件，不覆盖并发的外部修改。重复应用为无操作。补丁脚本不会重启或热重载运行中的进程。
+
+**首次应用宿主补丁后须重新启动原 DSH 服务，再刷新原有页面。** 只刷新页面、只重编客户端或反复开关插件，不能保证已加载的宿主模块和缓存的客户端元数据更新。不要另起服务器替代正在使用的 GUI。新开关也会检查宿主 schema：旧宿主尚未重新加载时保持原来的单密钥界面，不暴露无法保存的新配置。
+
+后续只改模型设置客户端界面时，不代表必须重启宿主；但需核对原服务提供的实际客户端文件已更新，再刷新原页面。不要把磁盘生成成功或组件测试通过当成真实页面已经生效。刷新前先保存正在编辑的内容，避免丢失草稿。
+
+DSH 升级可能覆盖这些原生文件；不要强行把此版本补丁用于新版本，应先重新适配并验证。
+
+### 卸载 / 回退
+
+先在相关会话中切换回原单密钥模型，并关闭各供应商的多密钥配置；使用者需确认所有保存的会话 / 子代理配置都不再选择 `@dsh-key/` 内部标识。随后空闲时停止原服务，再执行：
+
+```bash
+node scripts/native-patches.mjs --dsh-root /实际安装的DSH根目录 --revert
+dsh plugin --profile web remove dsh-model-groups
+```
+
+恢复原单密钥配置后，应在回退原生 schema 前移除不再受支持的 `multiKey`、`keyEntries` 字段（先备份配置，不删除原来的密钥与模型）。回退脚本仅恢复原生代码，不扫描或修改真实会话 / 配置 / 凭据，也不会自动证明回退前提已满足。仍选择内部配置标识的旧会话在原生补丁移除后无法发送请求。
+
+## 实现与验证
+
+内部模型标识为 `@dsh-key/<配置ID>/<编码后的上游模型ID>`，只用于保存选择身份；Provider ID 不变。适配器在请求边界解析它，使用独立配置的模型元数据和凭据引用，上游收到的仍是原始模型 ID。已准备请求保留当时的配置快照；跨密钥的签名历史不会直接复用到另一密钥。
+
+```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 的 MIT 代码，见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: model-groups
+      name: dsh-model-groups