dsh-model-groups 0.3.5 → 0.3.7

package/README.md

@@ -1,125 +1,89 @@
-# DSH Model Groups
+# DSH Model Groups · 模型分组
 
-为 DeepSeek Harness 网页端提供分层模型菜单与多密钥管理。同一供应商共用 Provider ID、API 地址和协议，各配置分别设置名称、密钥与模型列表。
+**在 DeepSeek Harness（DSH）网页端，按供应商、密钥配置和模型逐级选择。** 如果同一家供应商有多把 API 密钥，可以为每把密钥分别设置模型列表和 API 协议。即使模型名称一样，也能选中你要用的那份配置。插件不会自动换密钥或切换供应商。
 
-## 功能
-
-- 按“供应商 → 密钥配置 → 模型”浏览和选择。
-- 支持原地折叠、侧边面板、名称搜索、全部展开与收起。
-- 记住各级折叠状态；搜索时临时展开匹配项。
-- 不同密钥配置可使用相同模型 ID，选择时使用对应配置的密钥。
-- 手动选择配置，不自动轮换密钥或切换到其他配置。
-- 模型设置中已保存的密钥项默认折叠，名称和原密钥栏仍可见；展开编辑模型，新建和错误项保持展开，折叠不丢失草稿。
-- 实际修改补丁才提示重启；普通检查不要求重启，关闭状态标记不再被误当成待重启。
-
-## 环境要求
-
-- DeepSeek Harness **0.2.2-rc.1**。
-- Node.js **22 或以上**。
-- Harness 网页界面；在 dsh-go 中使用时，功能出现在对应网页，不影响 App 原生模型菜单。
-- DSH 安装目录可写，且目标程序文件符合支持的版本与哈希。
-
-**本版本不会自动打补丁。** 请在网页设置 → 模型分组明确选择安装。安装会校验、备份并修改五个宿主文件，之后须重启引擎。普通卸载插件不会撤销宿主修改。未知版本/文件不强制覆盖。
+支持 **DSH `0.2.2-rc.1`**、**Node.js 22 或更新版本**。本插件适用于 DSH 网页端，不替换原生 App 的模型菜单。
 
 ## 安装
 
-在目标设备的 DSH 环境中执行：
+在运行 DSH 的环境里执行（如果你使用的 DSH 配置不是 `web`，把命令中的 `web` 换成你的配置名）：
 
 ```bash
-dsh plugin --profile web add https://github.com/betsunninda9-lgtm/dsh-model-groups/releases/download/v0.3.5/dsh-model-groups-0.3.5.tgz
+dsh plugin --profile web add dsh-model-groups@latest --registry=https://registry.npmjs.org/
 ```
 
-此包只用于 DSH 0.2.2-rc.1 网页端。安装或更新插件后需重启原引擎使新后端生效，再刷新页面。已有 beta.3～beta.5 的磁盘补丁会保留，不会自动重打或还原。需要新折叠界面时，在模型分组设置页点击“更新多密钥补丁”，完成后重启原引擎并刷新网页；旧补丁可直接更新或还原，不需要先关闭多密钥。未打补丁时仍可使用普通模型；多密钥需在本页安装补丁并再次重启后启用。
+如果 npm 尚未同步到你需要的版本，可以把 `dsh-model-groups@latest` 换成 [GitHub 0.3.7 正式版安装包](https://github.com/betsunninda9-lgtm/dsh-model-groups/releases/download/v0.3.7/dsh-model-groups-0.3.7.tgz) 的下载地址。安装后，**重启正在使用的 DSH 引擎，再刷新网页**。只想给现有模型分组？装好就可以用，不需要启用多密钥。
 
-## 使用
+## 在对话中选模型
 
-1. 打开 **设置 → 模型**，新增或编辑自定义模型 API。
-2. 填写供应商公共的 Provider ID、API 地址和协议。
-3. 开启 **多密钥配置**，为每份配置填写名称、密钥和模型列表，点击“应用”。
-4. 在会话模型菜单中展开供应商和配置，选择需要的模型。
+打开输入框旁的模型菜单，展开供应商，选择模型。启用了多密钥的供应商会多一级 **密钥配置**。你可以搜索模型或配置名称、展开或收起全部分组，也可以在菜单底部切换 **侧边面板** 或 **原地折叠**。清空搜索后会恢复原来的展开状态。
 
-```text
-示例供应商 A
-  配置 A
-    示例模型
-  配置 B
-    示例模型
-示例供应商 B
-  示例模型
-```
+开启多密钥前就已选中普通模型的会话会保留原选择，菜单中标为 **原单密钥（兼容旧会话）**。
 
-已有单密钥配置与旧会话选择会保留。开启多密钥后，可在模型菜单手动选择新配置；插件不会自动合并已有供应商或迁移会话选择。
-
-关闭多密钥配置会保留已保存的配置与凭据，删除配置也不会同时删除凭据。有尚未保存的密钥输入时，需要先保存或清空，才能确认关闭。
-
-窄屏侧边面板会根据可用空间调整各级宽度；三级并列时，较长名称可能截断。
-
-## 更新
+## 为同一家供应商添加多把密钥
 
-使用对应发布版本的安装命令更新，随后按加载日志提示重启引擎并刷新网页。兼容补丁已经存在且未变化时，不会重复应用。
+### 启用多密钥
 
-DSH 升级前请确认插件兼容范围。新版本或未知文件会被拒绝，需要等待对应适配，不能强制套用旧补丁。
+1. 在网页打开 **设置 → 模型分组**，点击 **启用多密钥 → 确认执行**。
+2. 等页面提示已更新 DSH 文件后，**重启 DSH 引擎，再刷新网页**。只刷新网页不够。
 
-DSHMarket 的收录需经过社区审核。普通插件的市场更新跟随 npm `latest`，不会自动跟随 GitHub 发布包或 npm `beta` 标签。
+这一步会检查并备份 DSH 程序文件，再安装补丁。安装目录必须可写；如果文件版本无法识别，插件会停止，不会强行覆盖。
 
-## 安装诊断
+### 添加密钥配置
 
-没有出现“多密钥配置”开关时，先确认原引擎已在启用多密钥后重启，并刷新原网页。仍未恢复，可在已安装插件目录执行：
+1. 打开 **设置 → 模型**，新增或编辑一个支持多密钥的供应商。在 **公共设置** 中填写共享的 API 地址和默认协议。
+2. 打开 **多密钥配置**，为第一项填写配置名称、API 密钥和模型列表；有更多密钥就点击 **添加密钥配置**。
+3. 如果某把密钥需要不同的 API 协议，在 **分组 API 协议** 中选择；不确定时保留 **跟随供应商**，并以供应商说明为准。可选协议包括 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages。
+4. 点击 **应用**（新建时点击 **创建提供商**）。已保存的配置默认收起；要修改模型列表，点击 **展开详情**。编辑时将已保存的密钥输入框留空，原密钥会保留。
 
-```bash
-node scripts/doctor.mjs --dsh-root /opt/dsh --json
-```
+![展开后的密钥配置：分别填写 API 密钥、配置名称和协议，并可添加模型](docs/images/key-configuration.webp)
 
-`/opt/dsh` 请替换为实际 DSH 安装目录。五项文件应为 `patched`。该命令只读检查程序文件，不读取密钥；磁盘状态正常不代表运行中的模块已刷新。
+*展开一项密钥配置后，可以设置该项的 API 协议和模型列表。截图中的内部密钥引用已遮盖。*
 
-自动安装日志位于原引擎日志中。遇到文件不受支持、目录布局不兼容或权限不足时，请提供程序包版本与文件 SHA-256，勿提供密钥。
+<details>
+<summary>查看开关位置、折叠效果和添加按钮</summary>
 
-原文件备份保存在 `DSH_HOME/dsh-model-groups/<安装目录指纹>/backups`，不会随插件包更新丢失。安装意外中断可能留下 `patch.lock`；确认没有安装进程后再处理，不要并发重试。
+**找到开关**：新建供应商时，选择 **自定义模型 API**，在 **API 协议** 下方打开 **多密钥配置**。
 
-## 独立补丁管理页（0.3.5）
+![自定义模型 API 表单中，多密钥配置开关位于 API 协议下方](docs/images/provider-multi-key-toggle.webp)
 
-网页设置 → 模型分组，提供：**启用多密钥 / 关闭多密钥**，以及次要操作 **关闭并卸载插件**。点操作后只确认一次，无需勾选或输入英文。首次安装不会修改宿主，点击刷新也只读检查。详细检查折叠显示，可以复制脱敏诊断。
+**查看多份配置**：点击 **展开详情** 编辑对应配置，不必逐个展开其他配置。
 
-普通卸载保留宿主修改，后续引擎升级、其他插件修改同一文件可能冲突；补丁被覆盖后旧多密钥选择可能失效。页面会持续警告，而非只弹一次。磁盘校验不等于运行中模块已刷新；操作完成需重启原引擎。无法证明运行中版本时不显示虚假生效结论。
+![两份密钥配置均已折叠，各自保留独立的展开入口](docs/images/collapsed-key-configurations.webp)
 
-本阶段已实现手动补丁生命周期与诊断细分。**备用模型批量切换、私有配置归档和清理尚未接入页面，不声称已完成上一轮设计的全部迁移功能。** 多密钥配置、别名选择、历史子智能体策略及未能完成的检查改为风险提示，不再锁死操作。确认关闭意味着接受旧选择可能失效、旧配置可能影响原版引擎重启的风险；不声称无损迁移。文件冲突、已确认运行任务或共用安装的其他引擎仍阻止操作。没有修改凭据或聊天历史，不会自动请求模型、偷偷切换 DeepSeek 或拆分供应商。
+**继续添加**：在配置列表下方点击 **添加密钥配置**。每份密钥配置至少需要一个模型。
 
-安装和移除都要求已认证的 owner、短期一次性票据、完整文件校验和互斥锁。未知文件不覆盖。移除只操作本插件已知补丁；卸载必须在还原验证成功后才执行。断连、卸载失败、仅要求重启不算成功。恢复标记与备份保留；重新安装补丁时仅在明确确认应用并验证成功后清理自身恢复标记。
+![添加密钥配置按钮及每份配置至少需要一个模型的提示](docs/images/add-key-configuration.webp)
 
-检查范围限当前 home/安装，维护时先停止任务、保存草稿，不要在其他页变更选择或配置；插件锁不是全局请求屏障。未验证的依赖或活动状态会明确提示但不冒充已发现危险；请自行确保所有任务已停止。依赖检查不是无损卸载证明。诊断只展示固定错误类别，不展示秘密、表达式正文或原始路径。
+</details>
 
-## 卸载与还原（手工备用路径）
+如果只想让某个供应商恢复使用单密钥，先保存或清空尚未保存的密钥输入，再关掉该供应商的 **多密钥配置** 并点击 **应用**。已保存的多密钥配置不会被删除。
 
-普通插件列表移除仍不会自动还原宿主补丁或删除凭据；更新/HMR 也不会触发还原。开发预览版可优先用上述专用入口。手工完整还原前，请先：
+## 更新
 
-1. 将相关会话和子代理切换回普通单密钥模型。
-2. 关闭多密钥配置，备份配置并清理原版 DSH 不支持的 `multiKey`、`keyEntries` 字段，保留仍需使用的凭据。
-3. 在独立维护目录保留插件包，确保卸载后仍能运行还原脚本。
+1. 在原 DSH 配置中用目标正式版本重新执行安装命令，**不需要先卸载**。重启 DSH 引擎并刷新网页。
+2. 打开 **设置 → 模型分组**。如果出现 **更新多密钥补丁**，点击并确认；更新完成后，再重启引擎并刷新网页。没有更新提示就不用重复操作。
 
-普通卸载不还原补丁。以下为高级手工备用路径（本预览启动不再自动应用）：
+已识别且受支持的旧补丁可以直接更新，不用逐版安装。若提示文件冲突或不支持更新，请先复制诊断反馈；不要先卸载、还原补丁或删除配置。升级 **DSH 本身**前，请先确认目标 DSH 版本是否受插件支持。
 
-```bash
-dsh plugin --profile web remove dsh-model-groups
-```
+## 关闭或卸载
 
-随后安排维护窗口，停止原服务，在保留的插件目录执行：
+**如果已启用多密钥，不要直接从插件列表或命令行卸载。** 那样只会移除插件，不会还原 DSH 文件。
 
-```bash
-node scripts/native-patches.mjs --dsh-root /opt/dsh --revert
-```
+1. 保存设置草稿、停止运行中的任务，并把仍使用多密钥模型的会话、默认模型及子代理切回普通模型。建议先在各供应商设置里关闭 **多密钥配置** 并应用。
+2. 打开 **设置 → 模型分组**，选择 **关闭多密钥**（保留模型分组插件），或 **关闭并卸载插件**（先还原 DSH 文件，再卸载），然后确认。
+3. 页面提示需要重启时，**重启 DSH 引擎并刷新网页**。
 
-完成后启动原服务并刷新网页。还原脚本按校验过的文件版本恢复代码，不修改会话或凭据。仍引用 `@dsh-key/` 模型的会话在还原后无法继续使用该选择。
+![模型分组设置页：多密钥已启用，可以关闭多密钥或关闭并卸载插件](docs/images/multi-key-management.webp)
 
-## 开发
+*「设置 → 模型分组」在多密钥已启用时的界面（0.3.6）。按钮会随当前状态变化。*
 
-```bash
-npm run build
-npm test
-npm run check:build
-```
+关闭或卸载不会删除 API 密钥、供应商配置、聊天历史或备份，也不会替你切换模型。还原后，旧会话里的多密钥模型可能无法继续使用；原版 DSH 也可能无法读取残留的多密钥设置。遇到这种情况请先反馈诊断，不要直接删除密钥或整个配置。
 
-设置 `DSH_ROOT` 可启用依赖对应 DSH 程序文件的回归测试。源码包含层级、选择器交互、面板布局及补丁安装与恢复测试。
+## 遇到问题
 
-## 许可证
+- **找不到多密钥开关**：先确认已在 **设置 → 模型分组** 启用，并已重启引擎、刷新网页。只有支持多密钥的供应商编辑页会显示此开关，只能填写凭据的简化页面不会显示。
+- **不确定是否已经生效**：设置页的 **刷新检查** 只检查文件，不会修改文件或重启引擎。若刚启用、更新或关闭多密钥，请重启引擎再刷新网页。
+- **无法启用、更新或卸载**：打开 **设置 → 模型分组 → 检查详情与脱敏诊断**，点击 **复制脱敏诊断**，附在 [GitHub Issue](https://github.com/betsunninda9-lgtm/dsh-model-groups/issues) 中。该诊断不包含 API 密钥、文件路径、配置正文或聊天记录。
 
-[MIT](LICENSE)。包含改编自 DeepSeek Harness 的代码，保留原版权声明。
+开发、测试和命令行恢复说明见 [维护指南](docs/maintenance.md)。项目基于 [MIT 许可证](LICENSE) 开源。部分模型选择器代码改编自 DeepSeek Harness，保留原始版权声明。

package/docs/maintenance.md

@@ -0,0 +1,47 @@
+# 开发与维护指南
+
+日常安装和使用见 [README](../README.md)。
+
+## 本地验证
+
+需要 Node.js 22 或更新版本。修改网页端源码后，重新生成并提交客户端产物：
+
+```bash
+npm run build
+npm test
+npm run check:build
+```
+
+`npm run check:build` 只比对产物，不会覆盖它。历史版本升级测试读取 Git 历史，建议使用完整克隆。部分集成测试需要指定受支持的 DSH 安装目录；未指定时会跳过相应场景。需要覆盖其他已知构建时，可通过 `PI_AI_SOURCES` 传入只包含程序代码的文件，多个路径用系统路径分隔符隔开。集成测试在临时副本中写入，不要提供用户配置或凭据。
+
+```bash
+DSH_ROOT=/path/to/dsh npm test
+```
+
+## 两类网页代码
+
+- 插件自己的网页界面位于 `src/`，由 `npm run build` 生成 `lib/client.js`。
+- DSH 的「设置 → 模型」由宿主提供，发布包中的 `native/*.patch.json` 为已验证的程序文件补丁，不随客户端构建重新生成。若修改模型设置页补丁生成器，必须提供哈希匹配的原始程序文件，并验证相关构建的启用、升级及还原，不要直接编辑分发补丁或用其他构建的文件替换。
+
+```bash
+node scripts/settings-models-collapse.mjs --source /path/to/pristine-client.js
+node scripts/settings-models-collapse.mjs --source /path/to/pristine-client.js --check
+```
+
+## 诊断与恢复
+
+只读诊断（请替换实际安装路径）：
+
+```bash
+node scripts/doctor.mjs --dsh-root /path/to/dsh --json
+```
+
+遇到文件校验冲突或无法更新时，先保留现场并收集脱敏诊断。不要强制覆盖程序文件、删除配置或重建密钥。若此前从测试分支安装，可在原 DSH 配置中使用 README 的正式版本命令直接替换插件包，再按更新流程检查补丁。
+
+若插件已误卸载或无法打开网页设置，在处理多密钥模型引用后，先停止正在使用的 DSH 引擎，再从保留的插件目录执行：
+
+```bash
+node scripts/native-patches.mjs --dsh-root /path/to/dsh --revert
+```
+
+确认恢复完成后，重新启动同一个 DSH 引擎并刷新网页。备份存放在 `DSH_HOME/dsh-model-groups/<安装目录指纹>/backups`。若因异常中断遗留同目录下的 `patch.lock`，请先确认没有补丁维护进程正在运行，切勿并发重试。原版 DSH 可能无法识别 `@dsh-key/` 路由以及 `multiKey`、`keyEntries` 等设置；恢复前请按 README 处理相关模型引用和配置，避免影响启动。

package/lib/client.js

@@ -1270,6 +1270,31 @@ function installSettingsPageStyles() {
   document.head.appendChild(style);
 }
 
+const MODEL_GROUPS_CLIENT_VERSION = "0.3.7";
+// Public program metadata only. Never include paths, source text, configuration,
+// credentials, environment variables, or arbitrary exception messages.
+const PATCH_IDS = ['pi-ai.patch.json', 'settings-models.patch.json', 'llm-typert.host.patch.json', 'llm-typert.remote-client.patch.json', 'api-remotes.patch.json'];
+const COMPATIBILITY_CODES = ['ready', 'update_available', 'not_applied', 'unsupported_patch_build', 'host_version', 'package_version', 'unrecognized_content', 'target_unavailable', 'patch_manifest'];
+const publicVersion = value => typeof value === 'string' && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]{1,40})?$/.test(value) ? value : null;
+const publicHash = value => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value) ? value : null;
+function compatibilitySnapshot(value) {
+  if (!value || value.schema !== 1 || !Array.isArray(value.files) || value.files.length > PATCH_IDS.length) return null;
+  return { schema: 1, pluginVersion: publicVersion(value.pluginVersion), hostVersion: publicVersion(value.hostVersion), supportedDsh: publicVersion(value.supportedDsh),
+    files: value.files.filter(item => item && PATCH_IDS.includes(item.id)).map(item => ({ id: item.id,
+      state: ['patched', 'pristine', 'conflict'].includes(item.state) ? item.state : 'conflict',
+      code: COMPATIBILITY_CODES.includes(item.code) ? item.code : 'patch_manifest',
+      installedVersion: publicVersion(item.installedVersion), observedSha256: publicHash(item.observedSha256),
+      baseSha256: publicHash(item.baseSha256), targetSha256: publicHash(item.targetSha256) })) };
+}
+function compatibilityGuidance(snapshot) {
+  const codes = snapshot?.files.map(item => item.code) ?? [];
+  if (codes.includes('host_version') || codes.includes('package_version')) return '宿主程序版本不在本版支持范围。先核对插件与 DSH 的兼容版本；不要强行降级、覆盖文件或删除配置。';
+  if (codes.includes('unrecognized_content') || codes.includes('target_unavailable') || codes.includes('patch_manifest') || codes.includes('unsupported_patch_build')) return '已停止整批更新，未覆盖未知文件。先在原 profile 更新最新版插件，重启原引擎并刷新网页后复查；仍不支持时，复制脱敏诊断反馈。不要先卸载、还原补丁或删除配置；如需进一步适配，只提供被标记的程序文件，不提供密钥、配置或聊天记录。';
+  if (codes.includes('update_available')) return '已识别历史补丁，可直接更新到最新版，不需要逐版安装或先关闭多密钥。请保存草稿、停止任务，确认更新后重启原引擎并刷新网页。';
+  return '';
+}
+
+const MAINTENANCE_CLIENT_PROTOCOL = 2;
 const MAINTENANCE_CONFIRMATION = 'CONFIRM PATCH OPERATION';
 const MAINTENANCE_ENDPOINT = '/dsh-model-groups/maintenance';
 const MAINTENANCE_KEYS = ['dsh:model-groups:v1', 'dsh:model-groups:mode'];
@@ -1286,14 +1311,16 @@ function maintenanceSnapshot(value) {
     || !(value.warnings == null || (Array.isArray(value.warnings) && value.warnings.every(warning => warning && typeof warning.code === 'string'
       && (warning.count == null || (Number.isSafeInteger(warning.count) && warning.count > 0)))))
     || !value.patches.every(patch => patch && ['patched', 'pristine', 'conflict'].includes(patch.state)
-      && (patch.updateAvailable == null || typeof patch.updateAvailable === 'boolean'))
+      && (patch.updateAvailable == null || typeof patch.updateAvailable === 'boolean')
+      && (patch.applySupported == null || typeof patch.applySupported === 'boolean'))
     || !value.blockers.every(blocker => blocker && typeof blocker.code === 'string' && typeof blocker.message === 'string'
       && (blocker.count == null || (Number.isSafeInteger(blocker.count) && blocker.count > 0)))) {
     throw new Error('Invalid maintenance snapshot');
   }
-  return { phase: value.phase, restartRequired: value.restartRequired, canApply: value.canApply,
+  return { phase: value.phase, maintenanceProtocol: value.maintenanceProtocol === MAINTENANCE_CLIENT_PROTOCOL ? MAINTENANCE_CLIENT_PROTOCOL : null,
+    pluginVersion: publicVersion(value.pluginVersion), compatibility: compatibilitySnapshot(value.compatibility), restartRequired: value.restartRequired, canApply: value.canApply,
     canRestoreOnly: value.canRestoreOnly, canRestore: value.canRestore,
-    token: value.token ?? null, patches: value.patches.map(patch => ({ state: patch.state, updateAvailable: patch.updateAvailable === true })),
+    token: value.token ?? null, patches: value.patches.map(patch => ({ state: patch.state, updateAvailable: patch.updateAvailable === true, applySupported: patch.applySupported !== false })),
     blockers: value.blockers.map(blocker => ({ code: blocker.code, count: blocker.count ?? null })),
     warnings: (value.warnings ?? []).map(warning => ({ code: warning.code, count: warning.count ?? null })) };
 }
@@ -1301,14 +1328,17 @@ function maintenanceCanAction(snapshot, action) {
   const capability = Object.hasOwn(ACTION_CAPABILITIES, action) ? ACTION_CAPABILITIES[action] : null;
   return !!capability && !!snapshot && ['idle', 'applied', 'restored', 'failed'].includes(snapshot.phase) && snapshot[capability]
     && typeof snapshot.token === 'string' && snapshot.token.length > 0
-    && !snapshot.patches.some(patch => patch.state === 'conflict');
+    && !snapshot.patches.some(patch => patch.state === 'conflict')
+    && (action !== 'apply' || !snapshot.patches.some(patch => patch.applySupported === false));
 }
 function maintenanceCanRestore(snapshot) { return maintenanceCanAction(snapshot, 'restore-and-uninstall'); }
 function maintenanceBlockerText(blocker) {
   const labels = {
     active_sessions: '存在正在运行的会话，请先停止运行中的任务。',
     active_turns: '存在正在运行的回合，请先等待结束或停止。',
-    patch_conflict: '补丁状态冲突，请先人工诊断，不会强制覆盖。',
+    patch_conflict: '补丁状态冲突，不会强制覆盖。请复制脱敏诊断；不要先卸载、还原或删除配置。',
+    client_version_mismatch: '网页与插件后端版本不一致，已禁止维护。请重启原引擎并刷新网页后重新检查。',
+    unsupported_patch_build: '此宿主构建尚无经过验证的新版协议补丁，已阻止不完整更新；仍可关闭或卸载，不会改动密钥。',
     backup_missing: '缺少可验证的原版备份，无法安全恢复。',
     restart_required: '需要重启原引擎后重新检查。',
     inspection_failed: '状态检查失败，请使用安装诊断排查。',
@@ -1334,8 +1364,8 @@ function maintenanceBlockerText(blocker) {
     inspection_unknown: '无法确认运行状态，请先停止任务并使用安装诊断排查。',
     profile_unknown: '无法确认当前配置档，不会执行维护。',
     cross_profile_bundle: '其他配置档也在使用此插件，请先处理跨配置档依赖。',
-    alias_dependency: '仍有会话或配置引用多密钥模型，请先切换为普通模型再检查；本预览不会自动转换。',
-    key_config_dependency: '仍有多密钥配置依赖：请先禁用 multiKey 并清理 keyEntries 配置；已保存的密钥会保留。本预览不会自动转换。',
+    alias_dependency: '仍有会话或设置在使用多密钥模型。请先切换为普通模型；插件不会自动转换。',
+    key_config_dependency: '仍有供应商启用了多密钥。请先在「设置 → 模型」中关闭对应开关并保存；已保存的密钥会保留，配置不会自动转换。',
     expression_unknown: '存在无法安全判断的配置表达式，请先人工检查配置。',
     other_process: '其他引擎进程可能正在使用补丁，请先停止相关进程。',
   };
@@ -1346,7 +1376,7 @@ function maintenanceBlockerText(blocker) {
 // Copy only allowlisted codes and enumerated state: unknown codes may contain secrets or paths.
 function maintenanceDiagnostic(state) {
   const snapshot = state.snapshot;
-  const knownCodes = new Set(['active_sessions', 'active_turns', 'patch_conflict', 'backup_missing', 'restart_required',
+  const knownCodes = new Set(['active_sessions', 'active_turns', 'patch_conflict', 'client_version_mismatch', 'unsupported_patch_build', 'backup_missing', 'restart_required',
     'inspection_failed', 'config_inspection_failed', 'session_inspection_failed', 'session_service_missing',
     'process_inspection_failed', 'profile_inspection_failed', 'patch_inspection_failed', 'default_inspection_failed',
     'agent_inspection_failed', 'activity_unverified', 'not_removable', 'not_applicable', 'manager_unavailable',
@@ -1360,6 +1390,8 @@ function maintenanceDiagnostic(state) {
   return JSON.stringify({
     status: snapshot?.phase ?? 'unknown', busy: !!state.busy, resultUnverified: !!state.error,
     restartRequired: snapshot?.restartRequired ?? null,
+    maintenanceProtocol: snapshot?.maintenanceProtocol ?? null, pluginVersion: publicVersion(snapshot?.pluginVersion),
+    compatibility: compatibilitySnapshot(snapshot?.compatibility),
     capabilities: snapshot ? { apply: snapshot.canApply, close: snapshot.canRestoreOnly, uninstall: snapshot.canRestore } : null,
     patches: snapshot?.patches.map(patch => patch.state) ?? [],
     blockers: snapshot?.blockers.map(diagnosticItem) ?? [],
@@ -1378,7 +1410,8 @@ function maintenanceWarningText(warning) {
     + (warning.count ? `（${warning.count} 项）` : '');
 }
 
-function createMaintenanceController({ request = (...args) => fetch(...args), storage = () => globalThis.localStorage } = {}) {
+function createMaintenanceController({ request = (...args) => fetch(...args), storage = () => globalThis.localStorage,
+  clientVersion = typeof MODEL_GROUPS_CLIENT_VERSION === 'string' ? MODEL_GROUPS_CLIENT_VERSION : null } = {}) {
   let state = { snapshot: null, busy: false, error: '', cleanupWarning: false, patchedWarning: false };
   let disposed = false;
   let generation = 0;
@@ -1389,17 +1422,22 @@ function createMaintenanceController({ request = (...args) => fetch(...args), st
     if (!response.ok) throw new Error('Maintenance HTTP error');
     const envelope = await response.json();
     if (envelope?.ok !== true) throw new Error('Maintenance refused');
-    return maintenanceSnapshot(envelope.value);
+    const snapshot = maintenanceSnapshot(envelope.value);
+    if (clientVersion !== null && (snapshot.maintenanceProtocol !== MAINTENANCE_CLIENT_PROTOCOL || snapshot.pluginVersion !== clientVersion)) {
+      return { ...snapshot, versionMismatch: true, canApply: false, canRestoreOnly: false, canRestore: false, token: null,
+        blockers: [...snapshot.blockers, { code: 'CLIENT_VERSION_MISMATCH', count: null }] };
+    }
+    return snapshot;
   }
   function accept(snapshot) {
     let cleanupWarning = false;
-    if (snapshot.phase === 'removed') {
+    if (snapshot.phase === 'removed' && !snapshot.versionMismatch) {
       for (const key of MAINTENANCE_KEYS) {
         try { storage()?.removeItem(key); } catch { cleanupWarning = true; }
       }
     }
     update({ snapshot, cleanupWarning, patchedWarning: snapshot.patches.some(patch => patch.state === 'patched'),
-      error: snapshot.phase === 'failed' ? '维护操作失败，未确认完成。请刷新检查，不要强制覆盖。' : '' });
+      error: snapshot.versionMismatch ? '网页与插件后端版本不一致，已停止维护。请重启原引擎并刷新网页后复查。' : snapshot.phase === 'failed' ? '维护操作失败，未确认完成。请刷新检查，不要强制覆盖。' : '' });
   }
   async function run(action = null) {
     if (disposed || state.busy || (action && !maintenanceCanAction(state.snapshot, action))) return;
@@ -1419,7 +1457,7 @@ function createMaintenanceController({ request = (...args) => fetch(...args), st
         }
         update({ snapshot: { ...snapshot, canApply: false, canRestoreOnly: false, canRestore: false, token: null } });
         snapshot = await readSnapshot({ method: 'POST', headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ action, token, confirmation: MAINTENANCE_CONFIRMATION }) });
+          body: JSON.stringify({ action, token, confirmation: MAINTENANCE_CONFIRMATION, ...(clientVersion === null ? {} : { maintenanceProtocol: MAINTENANCE_CLIENT_PROTOCOL, clientVersion }) }) });
         if (!current()) return;
       }
       accept(snapshot);
@@ -1453,8 +1491,11 @@ function ModelGroupsSettingsPage() {
   const snapshot = state.snapshot;
   const phaseLabels = { idle: '检查完成，可选择操作', applied: '多密钥已应用（磁盘状态）', restored: '多密钥已关闭，插件仍保留（磁盘状态）', removing: '正在卸载，尚未确认完成', removed: '已确认关闭多密钥并卸载插件', failed: '维护失败，未确认完成' };
   const updatesAvailable = snapshot?.patches.some(patch => patch.updateAvailable) ?? false;
-  const statusLabel = snapshot?.phase === 'idle'
-    ? snapshot.patches.length && snapshot.patches.every(patch => patch.state === 'patched') ? '多密钥已启用（磁盘状态）'
+  const statusLabel = snapshot?.versionMismatch ? '网页与维护后端版本不一致，请先重启并刷新' : snapshot?.phase === 'idle'
+    ? snapshot.patches.some(patch => patch.state === 'conflict') ? '磁盘文件校验冲突，已停止整批维护'
+      : snapshot.patches.some(patch => patch.applySupported === false) ? '旧补丁已识别，但此构建不支持新版协议补丁'
+      : updatesAvailable ? '旧多密钥补丁已应用，新版更新待确认'
+      : snapshot.patches.length && snapshot.patches.every(patch => patch.state === 'patched') ? '多密钥已启用（磁盘状态）'
       : snapshot.patches.length && snapshot.patches.every(patch => patch.state === 'pristine') ? '多密钥已关闭（磁盘状态）' : '磁盘状态待处理，请查看操作限制'
     : phaseLabels[snapshot?.phase];
   const patchLabels = { patched: '已应用', pristine: '原版', conflict: '冲突（不会强制覆盖）' };
@@ -1467,16 +1508,18 @@ function ModelGroupsSettingsPage() {
     catch { setCopyStatus('无法复制，请检查浏览器剪贴板权限。'); }
   };
   return h('section', { className: 'mg-maintenance', 'aria-label': '模型分组设置', 'aria-busy': state.busy },
-    h('h2', null, '模型分组 · 多密钥管理'),
-    h('p', null, '选择操作，再确认一次即可。不会调用 AI，不会显示或删除 API 密钥。'),
+    h('h2', null, '多密钥管理'),
+    h('p', null, '在这里启用、更新或关闭多密钥。如果只想按供应商浏览模型，无需启用多密钥。'),
+    snapshot?.pluginVersion && h('p', { className: 'mg-maintenance-help' }, `插件 ${snapshot.pluginVersion} · DSH ${snapshot.compatibility?.hostVersion ?? '版本未确认'}`),
     h('section', { className: 'mg-maintenance-card', 'aria-label': '当前状态' },
       h('div', { className: 'mg-maintenance-row' }, h('h3', null, '当前状态'), h('button', { type: 'button', disabled: state.busy, onClick: refresh }, state.busy ? '处理中…' : '刷新检查')),
       h('p', { role: 'status', 'aria-live': 'polite', className: 'mg-maintenance-help' }, state.busy ? '正在检查或执行维护，请勿关闭或重复操作。' : snapshot ? statusLabel : '尚无可验证状态，请刷新检查。'),
       state.error && h('p', { role: 'alert', className: 'mg-maintenance-error' }, state.error),
-      state.patchedWarning && h('p', { role: 'alert', className: 'mg-maintenance-error' }, '警告：从普通插件列表卸载只移除插件，仍会留下宿主补丁，可能造成升级、文件冲突及旧多密钥模型依赖问题。请使用这里的“关闭并卸载插件”。'),
-      snapshot?.restartRequired && h('p', { role: 'status' }, '本进程已实际修改宿主文件，需要重启原引擎并刷新；页面刷新或插件重载不等于进程重启。'),
+      state.patchedWarning && h('p', { role: 'alert', className: 'mg-maintenance-error' }, '从普通插件列表卸载只移除插件，不会还原 DSH 文件。需要卸载时，请使用此页的「关闭并卸载插件」。'),
+      snapshot?.restartRequired && h('p', { role: 'status' }, 'DSH 程序文件已更新，需要重启 DSH 引擎，再刷新网页。只刷新网页不会生效。'),
+      compatibilityGuidance(snapshot?.compatibility) && h('p', { role: 'status', className: 'mg-maintenance-help' }, compatibilityGuidance(snapshot.compatibility)),
       updatesAvailable && h('p', { role: 'status' }, '多密钥补丁有更新可用；确认后将备份、校验并更新已识别的旧补丁。'),
-      snapshot?.phase === 'removed' && h('p', { role: 'status' }, '卸载已确认：仅清理本插件的两个浏览器显示偏好，密钥、历史和备份均保留。'),
+      snapshot?.phase === 'removed' && !snapshot.versionMismatch && h('p', { role: 'status' }, '卸载已确认：仅清理本插件的两个浏览器显示偏好，密钥、历史和备份均保留。'),
       snapshot?.warnings.length > 0 && h('p', { className: 'mg-maintenance-warning', role: 'status' }, '部分使用情况未验证，关闭前请阅读提示；检查提醒不会额外禁用操作。'),
       snapshot?.blockers.length > 0 && h('div', { role: 'alert' }, h('strong', null, '操作限制（各按钮以安全权限为准）'), h('ul', null, ...snapshot.blockers.map((blocker, index) => h('li', { key: index }, maintenanceBlockerText(blocker))))),
       state.cleanupWarning && h('p', { role: 'status' }, '卸载已确认，但浏览器阻止清理本插件的显示偏好；其他数据未受影响。')),
@@ -1486,15 +1529,20 @@ function ModelGroupsSettingsPage() {
       !anyAllowed && h('p', null, '请刷新检查或处理上方操作限制。检查提醒本身不会禁用按钮。'),
       pending && h('div', { role: 'dialog', 'aria-labelledby': confirmationId, 'aria-describedby': `${confirmationId}-help`, className: 'mg-maintenance-dialog' },
         h('h3', { id: confirmationId }, `确认${actions.find(([action]) => action === pending)[1]}？`),
-        h('p', { id: `${confirmationId}-help` }, pending === 'apply' ? '将备份、校验并修改宿主文件以启用多密钥。不会自动换服务或模型。请保存草稿、停止任务，完成后重启原引擎。' : '将校验并恢复宿主原版，关闭多密钥。密钥、配置和历史保留，不自动换服务或模型；旧多密钥选择和配置可能影响后续使用或重启。请保存草稿、停止任务，完成后重启原引擎。'),
-        h('p', null, '请先停止所有任务。部分使用情况未能检查不等于安全；检查提醒不会替代您的判断。'),
-        pending === 'restore-and-uninstall' && h('p', null, '确认原版恢复成功后才卸载插件；只有确认卸载完成才清理本插件的两个浏览器显示偏好。连接中断不代表成功。'),
+        h('p', { id: `${confirmationId}-help` }, pending === 'apply'
+          ? `插件会检查并备份 DSH 程序文件，再${updatesAvailable ? '更新多密钥补丁' : '启用多密钥'}。不会自动切换模型。`
+          : '插件会还原 DSH 程序文件，保留密钥、配置和聊天记录。请先将仍使用多密钥的会话和默认模型改为普通模型；残留的多密钥配置可能影响 DSH 启动。'),
+        h('p', null, '请先保存草稿并停止所有任务。完成后按提示重启 DSH 引擎，再刷新网页。'),
+        snapshot?.warnings.length > 0 && h('p', null, '部分使用情况无法检查，请先阅读页面中的检查详情。'),
+        pending === 'restore-and-uninstall' && h('p', null, '还原成功后才会卸载插件。确认卸载后会清除本浏览器中的模型菜单显示偏好；连接中断不代表卸载成功。'),
         h('div', { className: 'mg-maintenance-actions' }, h('button', { type: 'button', onClick: () => setPending(null) }, '取消'), h('button', { type: 'button', disabled: state.busy || !maintenanceCanAction(snapshot, pending), onClick: confirm }, '确认执行')))),
     h('details', { className: 'mg-maintenance-card' },
       h('summary', null, '检查详情与脱敏诊断'),
-      h('p', null, '这里只验证磁盘和安全权限，运行时是否已切换未知。每次确认后会重新检查；状态变化需重新确认。未知文件不会强制覆盖，检查不完整仅提醒；操作仍以各自安全权限为准。'),
+      h('p', null, '这里能检查 DSH 文件，但无法确认正在运行的引擎是否已加载更新。确认操作后会再次检查；如果状态变化，需要重新确认。无法识别的文件不会被覆盖。'),
       snapshot?.warnings.length > 0 && h('ul', null, ...snapshot.warnings.map((warning, index) => h('li', { key: index }, maintenanceWarningText(warning)))),
-      snapshot && h('ul', null, ...snapshot.patches.map((patch, index) => h('li', { key: index }, `宿主文件 ${index + 1}：${patchLabels[patch.state]}${patch.updateAvailable ? '（更新可用）' : ''}`))),
+      snapshot && h('ul', null, ...snapshot.patches.map((patch, index) => h('li', { key: index }, `宿主文件 ${index + 1}：${patchLabels[patch.state]}${patch.applySupported === false ? '（此构建不支持新版补丁）' : patch.updateAvailable ? '（更新可用）' : ''}`))),
+      snapshot?.compatibility && h('ul', null, ...snapshot.compatibility.files.map(item => h('li', { key: item.id }, `${item.id} · ${item.installedVersion ?? '版本未知'} · ${item.code} · SHA-256 ${item.observedSha256 ?? '不可读取'}`))),
+      h('p', null, '诊断仅含程序版本、固定文件标识与程序 SHA-256，不含文件路径、配置正文、密钥或聊天。升级失败请先保留现场，不要用另一构建的文件覆盖。'),
       h('button', { type: 'button', onClick: copy }, '复制脱敏诊断'),
       h('p', { role: 'status' }, copyStatus)));
 }
@@ -1522,8 +1570,8 @@ function apply(ctx) {
       statusNotice.setAttribute('role', 'status');
       statusNotice.style.cssText = 'position:fixed;bottom:16px;right:16px;max-width:min(360px,80vw);z-index:1000;background:var(--dsw-alias-bg-base,#fff);color:var(--dsw-alias-label-primary,#222);padding:12px;border:1px solid currentColor;border-radius:8px;box-sizing:border-box;pointer-events:none;';
       statusNotice.textContent = status.failed
-        ? '多密钥自动补丁未完成。请回到 App 对话查看引擎日志或运行安装诊断，勿强制覆盖。请暂勿编辑模型配置；可到「设置 → 模型分组」检查并安全恢复。'
-        : '多密钥补丁已自动安装。请先保存其他页面的草稿，再到 App 重启原引擎并刷新此网页。请暂勿编辑模型配置，避免新旧模块混用；维护入口仍可使用。';
+        ? '无法检查多密钥功能所需的 DSH 文件。请打开「设置 → 模型分组」查看详情，不要手动覆盖文件。'
+        : 'DSH 程序文件已更新。请先保存草稿，再重启 DSH 引擎并刷新网页。重启前请暂缓修改模型设置。';
       document.body.appendChild(statusNotice);
     }).catch(() => {});
   ctx.on('dispose', () => { statusDisposed = true; statusNotice?.remove(); });