dsh-model-groups 0.3.5 → 0.3.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-model-groups",
-  "version": "0.3.5",
-  "description": "DSH 网页模型选择器：供应商与密钥配置分层折叠、多密钥手动选择。支持 DSH 0.2.2-rc.1。",
+  "version": "0.3.7",
+  "description": "在 DSH 网页端按供应商和密钥配置选择模型，并为同一供应商的不同密钥分别设置模型和 API 协议。支持 DSH 0.2.2-rc.1。",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -29,8 +29,11 @@
     "native/*.patch.json",
     "scripts",
     "!scripts/settings-models-collapse.mjs",
+    "!scripts/pi-ai-protocol.mjs",
     "cordis.patch.yml",
     "README.md",
+    "docs/maintenance.md",
+    "docs/images/*.webp",
     "LICENSE"
   ],
   "engines": {

package/scripts/build.mjs

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 const root = fileURLToPath(new URL('../', import.meta.url));
 const read = name => fs.readFileSync(path.join(root, name), 'utf8');
 const withoutExports = source => source.replace(/^export /gm, '');
+const clientVersion = JSON.parse(read('package.json')).version;
 // Styles belong to the mounted plugin, not to module materialization: a
 // disposal removes them and a re-applied (memoized) module must restore them.
 const styles = `\nconst MODEL_GROUPS_CSS = ${JSON.stringify(read('src/groups.css'))};\nfunction installModelGroupsStyles() {\n  const tagId = 'dsh-model-groups/groups.css';\n  if (document.querySelector('style[data-plugin-css="' + tagId + '"]') !== null) return;\n  const style = document.createElement('style');\n  style.dataset.plugin = 'dsh-model-groups';\n  style.dataset.pluginCss = tagId;\n  style.textContent = MODEL_GROUPS_CSS;\n  document.head.appendChild(style);\n}\n`;
@@ -12,7 +13,7 @@ const settingsStyles = styleInstaller('SETTINGS_PAGE_CSS', 'installSettingsPageS
 function styleInstaller(constant, installer, file, tagId) {
   return `\nconst ${constant} = ${JSON.stringify(read(file))};\nfunction ${installer}() {\n  const tagId = ${JSON.stringify(tagId)};\n  if (document.querySelector('style[data-plugin-css="' + tagId + '"]') !== null) return;\n  const style = document.createElement('style');\n  style.dataset.plugin = 'dsh-model-groups';\n  style.dataset.pluginCss = tagId;\n  style.textContent = ${constant};\n  document.head.appendChild(style);\n}\n`;
 }
-const source = `// Generated by scripts/build.mjs; edit src instead.\nwindow.__ModuleLoader__.load({\n  id: 'dsh-model-groups',\n  factory(require) {\n    const react = require('react');\n    const react_dom = require('react-dom');\n    const react_jsx_runtime = require('react/jsx-runtime');\n    const _deepseek_ai_dsh_client_ui_primitives = require('@deepseek-ai/dsh-client-ui-primitives');\n${withoutExports(read('src/group-state.js'))}\n${withoutExports(read('src/hierarchy.js')).replace(/^import .*;\n/gm, '')}\n${read('src/model-select.js')}\n${withoutExports(read('src/fallback.js'))}\n${styles}\n${settingsStyles}\n${withoutExports(read('src/maintenance-state.js'))}\n${withoutExports(read('src/settings-page.js'))}\n${withoutExports(read('src/client.js'))}\n    return { apply, inject };\n  },\n});\n`;
+const source = `// Generated by scripts/build.mjs; edit src instead.\nwindow.__ModuleLoader__.load({\n  id: 'dsh-model-groups',\n  factory(require) {\n    const react = require('react');\n    const react_dom = require('react-dom');\n    const react_jsx_runtime = require('react/jsx-runtime');\n    const _deepseek_ai_dsh_client_ui_primitives = require('@deepseek-ai/dsh-client-ui-primitives');\n${withoutExports(read('src/group-state.js'))}\n${withoutExports(read('src/hierarchy.js')).replace(/^import .*;\n/gm, '')}\n${read('src/model-select.js')}\n${withoutExports(read('src/fallback.js'))}\n${styles}\n${settingsStyles}\nconst MODEL_GROUPS_CLIENT_VERSION = ${JSON.stringify(clientVersion)};\n${withoutExports(read('src/compatibility.js'))}\n${withoutExports(read('src/maintenance-state.js')).replace(/^import .*;\n/gm, '')}\n${withoutExports(read('src/settings-page.js')).replace(/^import .*;\n/gm, '')}\n${withoutExports(read('src/client.js'))}\n    return { apply, inject };\n  },\n});\n`;
 const target = path.join(root, 'lib/client.js');
 // Compile the classic-script bundle before writing anything.
 new Function(source);

package/scripts/doctor.mjs

@@ -1,39 +1,38 @@
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { planPatches } from './native-patches.mjs';
+import { inspectPatches } from './native-patches.mjs';
+import { compatibilityGuidance } from '../src/compatibility.js';
 
 const args = process.argv.slice(2);
 if (args.includes('--help')) {
-  console.log('Usage: node scripts/doctor.mjs --dsh-root <DSH installation directory> [--json]\nRead-only installation check. Does not read credentials or change DSH.');
+  console.log('Usage: node scripts/doctor.mjs --dsh-root <DSH installation directory> [--json]\nRead-only program compatibility check. No credentials, paths, or source text in diagnostics.');
 } else {
   try {
     const i = args.indexOf('--dsh-root');
-    if (i < 0 || !args[i + 1] || args.some((arg, index) => index !== i + 1 && !['--dsh-root', '--json'].includes(arg))) {
-      throw new Error('请用 --dsh-root 指定正在使用的 DSH 安装目录。');
-    }
+    if (i < 0 || !args[i + 1] || args.some((arg, index) => index !== i + 1 && !['--dsh-root', '--json'].includes(arg))) throw new Error('arguments');
     const pkg = JSON.parse(fs.readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));
-    const plans = planPatches(args[i + 1], 'check');
-    const missing = plans.filter(plan => plan.state !== 'patched');
-    const report = {
-      plugin: pkg.name,
-      version: pkg.version,
-      supportedDsh: pkg.engines.dsh,
-      diskPatchesReady: missing.length === 0,
-      runtimeVerified: false,
-      files: plans.map(plan => ({ target: plan.artifact.target, state: plan.state })),
-      next: missing.length > 0
-        ? '多密钥安装尚未完成：需要按 README 应用尚未安装的兼容补丁，再重启原 DSH 服务并刷新网页。'
-        : '磁盘补丁齐全。请确认原 DSH 服务已在应用补丁后重启，并刷新网页；本检查不能确认运行中的模块或浏览器缓存。',
-    };
+    const compatibility = inspectPatches(args[i + 1]);
+    const conflict = compatibility.files.some(file => file.state === 'conflict');
+    const ready = compatibility.files.every(file => file.code === 'ready');
+    const report = { plugin: pkg.name, version: pkg.version, supportedDsh: pkg.engines.dsh,
+      diskPatchesReady: ready, runtimeVerified: false, compatibility,
+      files: compatibility.files.map(file => ({ ...file, updateAvailable: file.code === 'update_available',
+        applySupported: ['ready', 'update_available', 'not_applied'].includes(file.code) })),
+      next: compatibilityGuidance(compatibility) || (ready
+        ? '磁盘补丁齐全。请确认原 DSH 服务已在应用补丁后重启，并刷新网页；本检查不能证明运行中的模块已刷新。'
+        : '请在设置 → 模型分组中确认启用，再重启原 DSH 服务并刷新网页。') };
     if (args.includes('--json')) console.log(JSON.stringify(report, null, 2));
     else {
-      console.log(`${report.plugin} ${report.version} · DSH ${report.supportedDsh}`);
-      for (const item of report.files) console.log(`${item.state}: ${item.target}`);
+      console.log(`${report.plugin} ${report.version} · DSH ${compatibility.hostVersion ?? 'unknown'}`);
+      for (const item of report.files) console.log(`${item.id}: ${item.state} / ${item.code} · SHA-256 ${item.observedSha256 ?? 'unavailable'}`);
       console.log(report.next);
     }
-    if (missing.length) process.exitCode = 2;
-  } catch (error) {
-    console.error(`无法确认多密钥安装状态：${error.message}`);
+    process.exitCode = conflict ? 1 : ready ? 0 : 2;
+  } catch {
+    const report = { diskPatchesReady: false, runtimeVerified: false, error: 'diagnostic_unavailable',
+      next: '请用 --dsh-root 指定正在使用的 DSH 安装目录；诊断失败不代表补丁已就绪，未修改任何文件。' };
+    if (args.includes('--json')) console.log(JSON.stringify(report, null, 2));
+    else console.error(report.next);
     process.exitCode = 1;
   }
 }

package/scripts/native-patches.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { compatibilitySnapshot } from '../src/compatibility.js';
 
 export const ARTIFACTS = ['pi-ai.patch.json', 'settings-models.patch.json', 'llm-typert.host.patch.json', 'llm-typert.remote-client.patch.json', 'api-remotes.patch.json'];
 const pluginRoot = fileURLToPath(new URL('../', import.meta.url));
@@ -25,13 +26,16 @@ export function transformSource(source, artifact, reverse = false) {
 
 /** Validate ALL files before any modification. Check mode is read-only. */
 export function planPatches(dshRoot, mode = 'check', artifactDirectory = path.join(pluginRoot, 'native')) {
+  return planPatchFiles(dshRoot, mode, artifactDirectory, ARTIFACTS);
+}
+function planPatchFiles(dshRoot, mode, artifactDirectory, names) {
   if (!['check', 'apply', 'revert'].includes(mode)) throw new Error('Unknown patch mode');
   const root = fs.realpathSync(dshRoot);
   const inner = path.join(root, 'node_modules/@deepseek-ai/dsh/package.json');
   const dsh = JSON.parse(fs.readFileSync(fs.existsSync(inner) ? inner : path.join(root, 'package.json'), 'utf8'));
   if (dsh.name !== '@deepseek-ai/dsh' || dsh.version !== '0.2.2-rc.1') throw new Error('This patch supports only @deepseek-ai/dsh 0.2.2-rc.1');
   const seen = new Set();
-  return ARTIFACTS.map(name => {
+  return names.map(name => {
     let artifact = JSON.parse(fs.readFileSync(path.join(artifactDirectory, name), 'utf8'));
     if (artifact.version !== '0.2.2-rc.1' || !/^@deepseek-ai\/dsh-[a-z-]+$/.test(artifact.packageName)) throw new Error('Unsupported patch package/version');
     if (!Array.isArray(artifact.replacements) || artifact.replacements.length === 0 || !/^[0-9a-f]{64}$/.test(artifact.baseSha256) || !/^[0-9a-f]{64}$/.test(artifact.resultSha256)) throw new Error('Invalid patch manifest');
@@ -46,7 +50,17 @@ export function planPatches(dshRoot, mode = 'check', artifactDirectory = path.jo
     const hash = sha256(source);
     const primary = artifact;
     if (artifact.variants !== undefined && (!Array.isArray(artifact.variants) || artifact.variants.some(variant => !/^[0-9a-f]{64}$/.test(variant.baseSha256) || !/^[0-9a-f]{64}$/.test(variant.resultSha256) || (variant.replacements !== undefined && !Array.isArray(variant.replacements))))) throw new Error('Invalid patch variants');
-    const candidates = [primary, ...(primary.variants || []).map(variant => ({ ...primary, ...variant }))];
+    if (primary.current !== undefined && typeof primary.current !== 'boolean' || primary.variants?.some(variant => variant.current !== undefined && typeof variant.current !== 'boolean')) throw new Error('Invalid current patch marker');
+    if (primary.requiresCurrent !== undefined && typeof primary.requiresCurrent !== 'boolean') throw new Error('Invalid required-current patch marker');
+    // current belongs to a revision, not the shared package metadata. Do not
+    // inherit primary.current onto legacy revisions when merging their fields.
+    const candidates = [primary, ...(primary.variants || []).map(variant => ({ ...primary, ...variant, current: variant.current === true }))];
+    const currentByBase = new Map();
+    for (const candidate of candidates) {
+      if (candidate.current !== true) continue;
+      if (currentByBase.has(candidate.baseSha256)) throw new Error('Ambiguous current patch variant');
+      currentByBase.set(candidate.baseSha256, candidate);
+    }
     // A shared pristine base is intentional for legacy revisions. Prefer current
     // output, but never guess between two different recognized patched sources.
     const patchedMatches = candidates.filter(candidate => hash === candidate.resultSha256);
@@ -58,12 +72,58 @@ export function planPatches(dshRoot, mode = 'check', artifactDirectory = path.jo
     // Verify the observed revision bidirectionally, including check/no-op plans.
     const observedPatched = transformSource(original, artifact);
     if (state === 'patched' && observedPatched !== source) throw new Error('Patch roundtrip mismatch');
-    const targetArtifact = artifact.baseSha256 === primary.baseSha256 ? primary : artifact;
+    const applySupported = primary.requiresCurrent !== true || currentByBase.has(artifact.baseSha256);
+    // A recognized old revision can still be checked/restored. It cannot be
+    // silently left behind while dependent UI/schema files upgrade around it.
+    if (mode === 'apply' && !applySupported) throw new Error('No verified current patch for this native build; no files written');
+    const targetArtifact = currentByBase.get(artifact.baseSha256) ?? (artifact.baseSha256 === primary.baseSha256 ? primary : artifact);
     const latest = transformSource(original, targetArtifact);
     const updateAvailable = state === 'patched' && sha256(latest) !== hash;
     const result = mode === 'apply' ? latest : mode === 'revert' ? original : source;
-    return { name, artifact, file, source, result, state, updateAvailable, mode: fs.statSync(file).mode & 0o777 };
+    return { name, artifact, file, source, result, state, updateAvailable, applySupported, observedSha256: hash, baseSha256: artifact.baseSha256, targetSha256: targetArtifact.resultSha256, mode: fs.statSync(file).mode & 0o777 };
+  });
+}
+
+
+/** Diagnose each program independently, without weakening the all-or-nothing planner.
+ * Output is a closed schema: program hashes/versions only, never paths or errors. */
+export function inspectPatches(dshRoot, artifactDirectory = path.join(pluginRoot, 'native')) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(pluginRoot, 'package.json'), 'utf8'));
+  let root, hostVersion = null;
+  try {
+    root = fs.realpathSync(dshRoot);
+    const inner = path.join(root, 'node_modules/@deepseek-ai/dsh/package.json');
+    const host = JSON.parse(fs.readFileSync(fs.existsSync(inner) ? inner : path.join(root, 'package.json'), 'utf8'));
+    if (host.name === '@deepseek-ai/dsh') hostVersion = host.version;
+  } catch { /* Do not expose filesystem or parser error messages. */ }
+  const files = ARTIFACTS.map(id => {
+    const item = { id, state: 'conflict', code: 'target_unavailable', installedVersion: null, observedSha256: null, baseSha256: null, targetSha256: null };
+    if (!root) return item;
+    // Collect only metadata from the exact manifest-owned, regular program path.
+    try {
+      const manifest = JSON.parse(fs.readFileSync(path.join(artifactDirectory, id), 'utf8'));
+      const prefix = `node_modules/${manifest.packageName}/`;
+      if (!/^@deepseek-ai\/dsh-[a-z-]+$/.test(manifest.packageName) || typeof manifest.target !== 'string' || !manifest.target.startsWith(prefix) || manifest.target.includes('..') || manifest.target.includes('\\')) throw new Error();
+      const file = path.resolve(root, manifest.target);
+      if (!inside(root, file) || fs.realpathSync(file) !== file || !fs.statSync(file).isFile()) throw new Error();
+      const installed = JSON.parse(fs.readFileSync(path.join(root, 'node_modules', manifest.packageName, 'package.json'), 'utf8'));
+      if (installed.name === manifest.packageName) item.installedVersion = installed.version;
+      item.observedSha256 = sha256(fs.readFileSync(file));
+    } catch { /* Safe incomplete metadata; planner still refuses unknown targets. */ }
+    try {
+      const [plan] = planPatchFiles(root, 'check', artifactDirectory, [id]);
+      Object.assign(item, { state: plan.state, code: !plan.applySupported ? 'unsupported_patch_build' : plan.updateAvailable ? 'update_available' : plan.state === 'pristine' ? 'not_applied' : 'ready',
+        baseSha256: plan.baseSha256, targetSha256: plan.targetSha256 });
+    } catch (error) {
+      const message = error?.message ?? '';
+      item.code = message === 'This patch supports only @deepseek-ai/dsh 0.2.2-rc.1' ? 'host_version'
+        : message === 'Installed native package version mismatch' ? 'package_version'
+        : message.startsWith('Refusing unrecognized content: ') ? 'unrecognized_content'
+        : error?.code === 'ENOENT' || error?.code === 'EACCES' || message === 'Unexpected target path or duplicate patch' ? 'target_unavailable' : 'patch_manifest';
+    }
+    return item;
   });
+  return compatibilitySnapshot({ schema: 1, pluginVersion: pkg.version, hostVersion, supportedDsh: pkg.engines.dsh, files });
 }
 
 function stageReplacement(file, content, mode) {
@@ -138,7 +198,7 @@ function main(args) {
   if (args.some(arg => !allowed.has(arg))) throw new Error('Unknown argument');
   const mode = (modes[0] ?? '--check').slice(2);
   const plans = planPatches(args[i + 1], mode);
-  for (const plan of plans) console.log(`${plan.artifact.target}: ${plan.state}`);
+  for (const plan of plans) console.log(`${plan.artifact.target}: ${plan.state}${plan.applySupported ? plan.updateAvailable ? ' (update available)' : '' : ' (recognized legacy build; no verified upgrade, apply disabled)'}`);
   if (mode !== 'check') console.log(`${applyPlan(plans)} native files changed. Restart the existing DSH service and refresh its page; the live process is not reloaded by this script.`);
 }
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {

package/src/auto-patch.js

@@ -15,9 +15,11 @@ export function findDshRoot(entry = process.argv[1]) {
   while (true) {
     const candidate = path.join(dir, 'node_modules/@deepseek-ai/dsh-llm-pi-ai/package.json');
     if (fs.existsSync(candidate) && fs.realpathSync(candidate) === resolved) {
-      // Full patch planning validates the DSH package/version and every target.
-      planPatches(dir, 'check');
-      return dir;
+      // Discovery must survive unknown program hashes so maintenance can explain
+      // the conflict. The planner still validates every target before any write.
+      const inner = path.join(dir, 'node_modules/@deepseek-ai/dsh/package.json');
+      const host = JSON.parse(fs.readFileSync(fs.existsSync(inner) ? inner : path.join(dir, 'package.json'), 'utf8'));
+      if (host.name === '@deepseek-ai/dsh') return dir;
     }
     const parent = path.dirname(dir);
     if (parent === dir) break;

package/src/client.js

@@ -21,8 +21,8 @@ export 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(); });

package/src/compatibility.js

@@ -0,0 +1,22 @@
+// Public program metadata only. Never include paths, source text, configuration,
+// credentials, environment variables, or arbitrary exception messages.
+export 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'];
+export const COMPATIBILITY_CODES = ['ready', 'update_available', 'not_applied', 'unsupported_patch_build', 'host_version', 'package_version', 'unrecognized_content', 'target_unavailable', 'patch_manifest'];
+export const publicVersion = value => typeof value === 'string' && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]{1,40})?$/.test(value) ? value : null;
+export const publicHash = value => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value) ? value : null;
+export 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) })) };
+}
+export 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 '';
+}

package/src/index.js

@@ -1,7 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { findDshRoot } from './auto-patch.js';
-import { createMaintenance, maintenanceHandler } from './maintenance.js';
+import { createMaintenance, createUnavailableMaintenance, maintenanceHandler } from './maintenance.js';
 import { createHostInspection } from './maintenance-host.js';
 
 // Neither disposal nor ordinary package removal restores patches: HMR and updates
@@ -21,11 +21,7 @@ export function apply(ctx) {
     ctx.logger.error('多密钥安装校验失败，未强制覆盖未知文件。请查看维护页。');
   }
   ctx.inject(['webServer', 'connection', 'pluginManager'], child => {
-    const inspect = root ? createHostInspection(child, root, home) : async () => ({ blockers: [{ code: 'HOST_UNKNOWN', message: '无法验证当前宿主安装，禁止恢复。' }], fingerprint: '' });
-    const controller = root ? createMaintenance({ root, home, inspect, manager: child.pluginManager }) : {
-      snapshot: async () => ({ phase: 'failed', restartRequired: false, patches: [], blockers: (await inspect()).blockers, canRestore: false, canRestoreOnly: false, canApply: false, token: null }),
-      restore: async () => { throw { code: 'HOST_UNKNOWN', message: '无法验证当前宿主安装。' }; },
-    };
+    const controller = root ? createMaintenance({ root, home, inspect: createHostInspection(child, root, home), manager: child.pluginManager }) : createUnavailableMaintenance();
     child.effect(() => child.webServer.register({ kind: 'exact', path: '/dsh-model-groups/maintenance', handler: maintenanceHandler(controller, child.connection) }));
     child.effect(() => child.webServer.register({ kind: 'exact', path: '/dsh-model-groups/status', handler(req, res) {
       const admission = child.connection.admit(req);

package/src/maintenance-state.js

@@ -1,3 +1,5 @@
+import { compatibilitySnapshot, publicVersion } from './compatibility.js';
+export const MAINTENANCE_CLIENT_PROTOCOL = 2;
 export const MAINTENANCE_CONFIRMATION = 'CONFIRM PATCH OPERATION';
 export const MAINTENANCE_ENDPOINT = '/dsh-model-groups/maintenance';
 const MAINTENANCE_KEYS = ['dsh:model-groups:v1', 'dsh:model-groups:mode'];
@@ -14,14 +16,16 @@ export 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 })) };
 }
@@ -29,14 +33,17 @@ export 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));
 }
 export function maintenanceCanRestore(snapshot) { return maintenanceCanAction(snapshot, 'restore-and-uninstall'); }
 export 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: '状态检查失败，请使用安装诊断排查。',
@@ -62,8 +69,8 @@ export 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: '其他引擎进程可能正在使用补丁，请先停止相关进程。',
   };
@@ -74,7 +81,7 @@ export function maintenanceBlockerText(blocker) {
 // Copy only allowlisted codes and enumerated state: unknown codes may contain secrets or paths.
 export 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',
@@ -88,6 +95,8 @@ export 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) ?? [],
@@ -106,7 +115,8 @@ export function maintenanceWarningText(warning) {
     + (warning.count ? `（${warning.count} 项）` : '');
 }
 
-export function createMaintenanceController({ request = (...args) => fetch(...args), storage = () => globalThis.localStorage } = {}) {
+export 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;
@@ -117,17 +127,22 @@ export function createMaintenanceController({ request = (...args) => fetch(...ar
     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;
@@ -147,7 +162,7 @@ export function createMaintenanceController({ request = (...args) => fetch(...ar
         }
         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);

package/src/maintenance.js

@@ -1,9 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { planPatches, applyPlan, sha256 } from '../scripts/native-patches.mjs';
+import { planPatches, inspectPatches, applyPlan, sha256 } from '../scripts/native-patches.mjs';
 
 export const BUNDLE_NAME = 'dsh-model-groups';
+export const MAINTENANCE_PROTOCOL = 2;
+const pluginPackage = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const pluginVersion = pluginPackage.version;
 // Process-local evidence survives controller replacement and module HMR, but not an
 // engine restart. The restoration marker only suppresses automatic patching: it is
 // not evidence that this process has loaded old code. A new process's runtime
@@ -17,6 +20,18 @@ export function restorationPending(root, home) {
   return fs.existsSync(path.join(maintenanceStorage(root, home), 'restore-pending.json'));
 }
 
+// Discovery failure is a host diagnostic, not a stale-client mismatch. Keep the
+// same public handshake even when no safe root or maintenance ticket exists.
+export function createUnavailableMaintenance() {
+  const blocker = { code: 'HOST_UNKNOWN', message: '无法验证当前宿主安装，不会修改未知文件。' };
+  return {
+    snapshot: async () => ({ phase: 'failed', maintenanceProtocol: MAINTENANCE_PROTOCOL, pluginVersion,
+      compatibility: { schema: 1, pluginVersion, hostVersion: null, supportedDsh: pluginPackage.engines.dsh, files: [] },
+      restartRequired: false, patches: [], blockers: [blocker], warnings: [], canRestore: false, canRestoreOnly: false, canApply: false, token: null }),
+    restore: async () => { throw { ...blocker }; },
+  };
+}
+
 /** Local-only transaction. Inspection and removal are injected to keep tests off the live host. */
 export function createMaintenance({ root, home, inspect, manager, artifacts, now = Date.now }) {
   let phase = 'idle', busy = false, ticket;
@@ -43,9 +58,16 @@ export function createMaintenance({ root, home, inspect, manager, artifacts, now
   const generic = (code, message) => ({ code, message });
   async function assessment() {
     const blockers = [];
-    let plans = [], removable = false;
-    try { plans = patchPlans(); }
+    let plans = [], removable = false, compatibility;
+    try {
+      plans = patchPlans();
+      if (plans.some(plan => plan.applySupported === false)) blockers.push(generic('UNSUPPORTED_PATCH_BUILD', '此宿主构建仅能识别旧补丁，尚无经过验证的新版协议补丁；不会执行不完整更新。仍可关闭或卸载。'));
+    }
     catch { blockers.push(generic('PATCH_CONFLICT', '宿主版本或文件校验不匹配；未修改任何宿主文件，请先处理冲突。')); }
+    compatibility = plans.length ? { schema: 1, pluginVersion, hostVersion: '0.2.2-rc.1', supportedDsh: pluginPackage.engines.dsh,
+      files: plans.map(p => ({ id: p.name, state: p.state, code: !p.applySupported ? 'unsupported_patch_build' : p.updateAvailable ? 'update_available' : p.state === 'pristine' ? 'not_applied' : 'ready', installedVersion: p.artifact.version,
+        observedSha256: p.observedSha256, baseSha256: p.baseSha256, targetSha256: p.targetSha256 })) } : inspectPatches(root, artifacts);
+    compatibility.pluginVersion = pluginVersion;
     try {
       const report = await inspect();
       if (!report || !Array.isArray(report.blockers) || typeof report.fingerprint !== 'string') throw new Error('inspection');
@@ -60,20 +82,21 @@ export function createMaintenance({ root, home, inspect, manager, artifacts, now
     // Dependency observations describe consequences, not permission to overwrite files.
     // Only proven activity, other engines sharing the installation and file conflicts
     // stop patch changes. Unknown observations remain visible for explicit consent.
-    const hardCodes = new Set(['patch_conflict', 'active_turns', 'other_process', 'not_removable', 'manager_unavailable']);
+    const hardCodes = new Set(['patch_conflict', 'unsupported_patch_build', 'active_turns', 'other_process', 'not_removable', 'manager_unavailable']);
     const warnings = blockers.filter(b => !hardCodes.has(b.code.toLowerCase()));
     const hard = blockers.filter(b => hardCodes.has(b.code.toLowerCase()));
-    return { plans, blockers: hard, warnings, removable, stamp: sha256(JSON.stringify([hard, removable, plans.map(p => [p.name, sha256(p.source), !!p.updateAvailable, sha256(JSON.stringify(p.artifact))])])) };
+    return { plans, compatibility, blockers: hard, warnings, removable, stamp: sha256(JSON.stringify([pluginVersion, compatibility, hard, removable, plans.map(p => [p.name, sha256(p.source), !!p.updateAvailable, p.applySupported, sha256(JSON.stringify(p.artifact))])])) };
   }
   function view(report, executing = false) {
     const valid = report.plans.length > 0 && !report.blockers.some(b => b.code.toLowerCase() === 'patch_conflict');
-    const dependencies = report.blockers.filter(b => !['not_removable', 'manager_unavailable'].includes(b.code.toLowerCase()));
-    const installBlockers = dependencies;
+    const restoreBlockers = report.blockers.filter(b => b.code.toLowerCase() !== 'unsupported_patch_build');
+    const dependencies = restoreBlockers.filter(b => !['not_removable', 'manager_unavailable'].includes(b.code.toLowerCase()));
+    const installBlockers = report.blockers.filter(b => !['not_removable', 'manager_unavailable'].includes(b.code.toLowerCase()));
     const available = (!busy || executing) && phase !== 'removed';
-    return { phase, restartRequired: restartRequired(), patches: report.plans.map(p => ({ name: p.name, state: p.state, updateAvailable: !!p.updateAvailable })), blockers: report.blockers, warnings: report.warnings,
+    return { phase, maintenanceProtocol: MAINTENANCE_PROTOCOL, pluginVersion, compatibility: report.compatibility, restartRequired: restartRequired(), patches: report.plans.length ? report.plans.map(p => ({ name: p.name, state: p.state, updateAvailable: !!p.updateAvailable, applySupported: p.applySupported !== false })) : report.compatibility.files.map(p => ({ name: p.id, state: p.state, updateAvailable: p.code === 'update_available', applySupported: ['ready', 'update_available', 'not_applied'].includes(p.code) })), blockers: report.blockers, warnings: report.warnings,
       token: null, canApply: available && valid && installBlockers.length === 0 && report.plans.some(p => p.state === 'pristine' || p.updateAvailable),
       canRestoreOnly: available && valid && dependencies.length === 0 && report.plans.some(p => p.state === 'patched'),
-      canRestore: available && valid && report.blockers.length === 0,
+      canRestore: available && valid && restoreBlockers.length === 0,
       notice: '关闭会保留密钥和聊天记录，不自动更换服务。旧多密钥选择可能失效，旧配置可能影响重启；使用情况未完整检查时仍可确认继续。普通插件列表卸载不会还原补丁。' };
   }
   async function snapshot() {
@@ -87,6 +110,7 @@ export function createMaintenance({ root, home, inspect, manager, artifacts, now
   }
   async function restore(input) {
     if (busy) throw generic('BUSY', '已有维护任务正在执行。');
+    if (input?.maintenanceProtocol !== MAINTENANCE_PROTOCOL || input?.clientVersion !== pluginVersion) throw generic('CLIENT_VERSION_MISMATCH', '网页与维护后端版本不一致，请重启原引擎并刷新网页后重新确认。');
     if (!['apply', 'restore-only', 'restore-and-uninstall'].includes(input?.action) || input?.confirmation !== 'CONFIRM PATCH OPERATION' ||
       !ticket || typeof input.token !== 'string' || input.token !== ticket.token || ticket.expires < now()) {
       throw generic('CONFIRMATION_REQUIRED', '确认已失效，请重新检查并明确确认。');
@@ -106,7 +130,7 @@ export function createMaintenance({ root, home, inspect, manager, artifacts, now
        if (!permitted || report.stamp !== expected.stamp) throw generic('STATE_CHANGED', '文件或任务状态发生变化，请确认没有任务运行后重试。');
       if (action === 'apply') {
         changeFiles(planPatches(root, 'apply', artifacts));
-        if (!patchPlans().every(p => p.state === 'patched' && !p.updateAvailable)) throw generic('VERIFY_FAILED', '补丁验证失败。');
+        if (!patchPlans().every(p => p.state === 'patched' && !p.updateAvailable && p.applySupported !== false)) throw generic('VERIFY_FAILED', '补丁验证失败。');
         // Never delete a computed or unverified path; only this exact owned marker.
         if (fs.existsSync(marker)) {
           const stat = fs.lstatSync(marker);
@@ -129,7 +153,7 @@ export function createMaintenance({ root, home, inspect, manager, artifacts, now
       if (remaining?.installed || remaining?.removable || remaining?.enabled) throw generic('REMOVE_UNVERIFIED', '尚未确认插件依赖已移除，请检查插件列表；补丁不会自动重新安装。');
       if (!patchPlans().every(p => p.state === 'pristine')) throw generic('VERIFY_FAILED', '卸载后宿主文件再次变化，不能确认完整恢复。');
       phase = 'removed';
-      return { phase, restartRequired: restartRequired(), patches: patchPlans().map(p => ({ name: p.name, state: p.state, updateAvailable: !!p.updateAvailable })), blockers: [], canRestore: false, canRestoreOnly: false, canApply: false, token: null,
+      return { phase, maintenanceProtocol: MAINTENANCE_PROTOCOL, pluginVersion, compatibility: (await assessment()).compatibility, restartRequired: restartRequired(), patches: patchPlans().map(p => ({ name: p.name, state: p.state, updateAvailable: !!p.updateAvailable, applySupported: p.applySupported !== false })), blockers: [], canRestore: false, canRestoreOnly: false, canApply: false, token: null,
         notice: '已确认原版文件和插件依赖移除状态。密钥、历史和安全备份未删除；运行时状态未验证，是否需要重启以本进程实际文件修改记录为准。' };
     } catch (error) {
       phase = 'failed';