dsh-model-groups 0.3.4 → 0.3.6

package/src/maintenance-host.js

@@ -0,0 +1,250 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+const digest = value => crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const messages = {
+  inspection_unknown: '宿主依赖未完整验证。',
+  config_inspection_failed: '配置依赖未完整验证。',
+  default_inspection_failed: '默认模型依赖未完整验证。',
+  session_service_missing: '会话查询服务不可用，会话依赖未完整验证。',
+  session_inspection_failed: '部分会话依赖未完整验证。',
+  agent_inspection_failed: '部分智能体依赖未完整验证。',
+  activity_unverified: '部分任务活动状态未验证，请确认任务已结束。',
+  process_inspection_failed: '引擎进程活动状态未完整验证。',
+  profile_unknown: '部分配置组合依赖未完整验证。',
+  cross_profile_bundle: '其他配置仍安装或选择本插件，卸载后可能受影响。',
+  alias_dependency: '观察到多密钥模型路由，卸载后相关路由可能不可用。',
+  key_config_dependency: '观察到多密钥配置，维护不会自动删除这些配置。',
+  expression_unknown: '配置含动态表达式，无法证明不存在依赖。',
+  active_turns: '存在正在运行或维护中的任务，请先等待任务结束。',
+  other_process: '发现其他引擎进程，无法验证它们的活动状态。',
+};
+
+// These scalar configuration fields cannot supply a plugin, model route or key
+// collection. Unknown fields/roots remain conservative. Never infer safety from
+// expression text, plugin enablement, or a name/id that might itself be dynamic.
+const nonRouteScalars = new Set([
+  'apiKey', 'apiKeyEnv', 'baseURL', 'baseUrl', 'endpoint', 'timeout', 'timeoutMs',
+  'maxRetries', 'temperature', 'topP', 'maxTokens', 'contextWindow',
+  'enabled', 'disabled', 'label', 'description', 'locale', 'language', 'port', 'host',
+]);
+
+/** Pure scanner: never evaluates expressions or returns inspected values. */
+export function dependencySignals(value) {
+  const result = { alias: 0, keys: 0, expression: 0 };
+  const seen = new WeakSet();
+  const routeCollections = new Set(['providers', 'profiles', 'keyEntries', 'models', 'modelOverrides', 'allowedModels', 'plugins']);
+  const walk = (input, safeScalar = false, field, parentField) => {
+    if (typeof input === 'string') { if (input.startsWith('@dsh-key/')) result.alias++; return; }
+    if (!input || typeof input !== 'object') return;
+    if (Object.hasOwn(input, '__jsExpr')) {
+      if (!safeScalar) result.expression++;
+      return;
+    }
+    if (seen.has(input)) { result.expression++; return; }
+    seen.add(input);
+    if (!Array.isArray(input)) {
+      if (input.multiKey === true || (input.keyEntries && typeof input.keyEntries === 'object' && Object.keys(input.keyEntries).length)) result.keys++;
+      if (Object.hasOwn(input, 'multiKey') && typeof input.multiKey !== 'boolean' && !input.multiKey?.__jsExpr) result.expression++;
+      if (Object.hasOwn(input, 'keyEntries') && (!input.keyEntries || typeof input.keyEntries !== 'object' || Array.isArray(input.keyEntries))) result.expression++;
+    }
+    // Safety applies only to the immediate scalar slot, never a whole subtree.
+    const configFields = field === undefined || field === 'config' || ['value', 'base', 'user'].includes(field) || routeCollections.has(parentField);
+    for (const [key, child] of Object.entries(input)) walk(child,
+      configFields && !Array.isArray(input) && !routeCollections.has(field) && nonRouteScalars.has(key), key, field);
+    seen.delete(input);
+  };
+  walk(value);
+  return result;
+}
+
+// Fingerprints never serialize arbitrary host objects, credentials or expression text.
+// Unknown shapes remain an explicit inspection signal, not an assertion of safety.
+function routeProjection(value, ancestors = new WeakSet()) {
+  if (value === undefined || value === null) return value;
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'object' || ancestors.has(value)) throw new Error('Invalid route projection');
+  if (Object.hasOwn(value, '__jsExpr')) return { __jsExpr: true };
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) return value.map(item => routeProjection(item, ancestors));
+    const result = {};
+    for (const key of ['provider', 'model', 'reasoningEffort', 'agentProvider', 'agentModel', 'allowedModels']) {
+      if (!Object.hasOwn(value, key)) continue;
+      const child = value[key];
+      if (key === 'allowedModels') {
+        if (!Array.isArray(child)) throw new Error('Invalid route policy');
+      } else if (child != null && typeof child !== 'string' && !(typeof child === 'object' && Object.hasOwn(child, '__jsExpr'))) {
+        throw new Error('Invalid route scalar');
+      }
+      result[key] = routeProjection(child, ancestors);
+    }
+    return result;
+  } finally { ancestors.delete(value); }
+}
+
+/** Fold explicit routes only; message bodies and Session objects are never projected. */
+export function sessionDependencies(events) {
+  if (!Array.isArray(events)) throw new Error('Invalid session observation');
+  let lastUsed, pending;
+  const sameSelection = (a, b) => a && b && a.provider === b.provider && a.model === b.model && a.reasoningEffort === b.reasoningEffort;
+  const durable = [];
+  let openTurns = 0;
+  for (const event of events) {
+    if (!event || typeof event.type !== 'string') throw new Error('Invalid event observation');
+    if (event.type === 'model/selection') {
+      if (!event.data || typeof event.data.model !== 'string') throw new Error('Invalid selection observation');
+      pending = routeProjection(event.data);
+    }
+    if (event.type === 'request/header') {
+      const header = event.data?.header, route = header?.config;
+      if (!route || typeof route.provider !== 'string' || typeof route.model !== 'string') throw new Error('Invalid route observation');
+      lastUsed = routeProjection({ provider: route.provider, model: route.model,
+        reasoningEffort: header.adapterDefaults?.reasoningEffort === true ? undefined : route.reasoningEffort });
+      durable.push(lastUsed);
+      if (sameSelection(pending, lastUsed)) pending = undefined;
+    }
+    if (event.type === 'subagent/descriptor') {
+      if (typeof event.data?.agentModel !== 'string') throw new Error('Invalid descriptor observation');
+      durable.push(routeProjection({ provider: event.data.agentProvider, model: event.data.agentModel }));
+    }
+    if (event.type === 'subagent/model-selection-policy') {
+      if (!Array.isArray(event.data?.allowedModels)) throw new Error('Invalid policy observation');
+      durable.push(routeProjection(event.data.allowedModels));
+    }
+    if (event.type === 'turn/start') openTurns++;
+    if (event.type === 'turn/end') openTurns = Math.max(0, openTurns - 1);
+  }
+  return { routes: [pending ?? lastUsed, ...durable], openTurns };
+}
+
+/** Read-only inspection bounded to the supplied home and installation. No global-install claim. */
+export function createHostInspection(ctx, root, home) {
+  return async function inspect() {
+    const counts = new Map(), observations = new Set(), dependencies = new Set();
+    const block = (code, count = 1) => counts.set(code, (counts.get(code) || 0) + count);
+    const observe = value => {
+      const signals = dependencySignals(value), routes = [], seen = new WeakSet();
+      const collect = input => {
+        if (!input || typeof input !== 'object' || seen.has(input)) return;
+        seen.add(input);
+        if (Object.hasOwn(input, '__jsExpr')) return;
+        if (['provider', 'model', 'agentProvider', 'agentModel', 'allowedModels'].some(key => Object.hasOwn(input, key))) routes.push(routeProjection(input));
+        for (const child of Object.values(input)) collect(child);
+      };
+      collect(value);
+      const observation = digest([signals.alias > 0, signals.keys > 0, signals.expression > 0, routes]);
+      if (dependencies.has(observation)) return;
+      dependencies.add(observation);
+      observations.add(observation);
+      if (signals.alias) block('alias_dependency');
+      if (signals.keys) block('key_config_dependency');
+      if (signals.expression) block('expression_unknown');
+    };
+    try {
+      const require = createRequire(path.join(root, 'package.json'));
+      const boot = await import(pathToFileURL(require.resolve('@deepseek-ai/dsh-app-boot')).href);
+      const profile = ctx.profileContext;
+      if (!profile || !Array.isArray(profile.overlays) || fs.realpathSync(profile.home) !== fs.realpathSync(home)) throw new Error('Unknown launch scope');
+      const profilesRoot = path.join(home, boot.PROFILES_DIR);
+      const directories = fs.readdirSync(profilesRoot, { withFileTypes: true });
+      let currentFound = false;
+      for (const entry of directories.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory()) { block('profile_unknown'); continue; }
+        const dir = path.join(profilesRoot, entry.name);
+        const current = fs.realpathSync(dir) === fs.realpathSync(profile.dir);
+        currentFound ||= current;
+        try {
+          const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+          observations.add(digest([entry.name, Object.hasOwn(manifest.dependencies || {}, 'dsh-model-groups'), manifest.dsh?.profile?.bundles?.includes('dsh-model-groups') === true]));
+          if (!current && (Object.hasOwn(manifest.dependencies || {}, 'dsh-model-groups') || manifest.dsh?.profile?.bundles?.includes('dsh-model-groups'))) block('cross_profile_bundle');
+          const loaded = boot.loadProfileDirectory('dsh', dir, profile.installAnchor, { readOnly: true });
+          if (loaded.skippedBundles.length) block('profile_unknown', loaded.skippedBundles.length);
+          const context = { ...profile, dir, patchPath: loaded.patchPath, home, overlays: current ? profile.overlays : [] };
+          const patches = boot.readProfilePatches('dsh', context, loaded);
+          // Scan raw layers too: disabled rows and overridden residual config must not disappear.
+          observe(patches);
+          // Raw layers retain disabled/overridden residues without composing or evaluating them.
+        } catch { block('profile_unknown'); }
+      }
+      if (!currentFound) block('profile_unknown');
+    } catch { block('profile_unknown'); }
+    try {
+      for (const { entry, inherited, override } of ctx.configEditor.configuration()) observe({
+        plugin: entry.options.name, config: entry.options.config, base: inherited, user: override,
+      });
+    } catch { block('config_inspection_failed'); }
+    try { observe(routeProjection(ctx.agentDefaultModel.currentSelection())); }
+    catch { block('default_inspection_failed'); }
+    // Do not call settings.describe: it evaluates expressions a second time.
+    try {
+      if (typeof ctx.sessionQuery?.listSessions !== 'function' || typeof ctx.sessionQuery?.readSession !== 'function') {
+        block('session_service_missing'); block('activity_unverified');
+      } else {
+        const sessions = await ctx.sessionQuery.listSessions();
+        if (!Array.isArray(sessions)) throw new Error('Invalid session list');
+        for (const record of sessions) {
+          try {
+            const id = record?.header?.id;
+            if (typeof id !== 'string' || !id) throw new Error('Invalid session identity');
+            observations.add(digest(['session', id, record.live === true]));
+            const loaded = await ctx.sessionQuery.readSession(id);
+            if (loaded.session?.id !== id) throw new Error('Invalid session snapshot identity');
+            if (!Array.isArray(loaded.events)) throw new Error('Invalid session events');
+            // Activity survives malformed route observations in this same snapshot.
+            let openTurns = 0;
+            for (const event of loaded.events) {
+              if (event?.type === 'turn/start') openTurns++;
+              if (event?.type === 'turn/end') openTurns = Math.max(0, openTurns - 1);
+            }
+            observations.add(digest(['activity', id, openTurns]));
+            if (record.live === true && openTurns) block('active_turns');
+            const state = sessionDependencies(loaded.events);
+            observe(state.routes);
+            observations.add(digest(['session', id, state.routes]));
+            // Historical unfinished turns are dependency observations, never activity locks.
+            if (typeof record.live !== 'boolean') block('activity_unverified');
+          } catch { block('session_inspection_failed'); block('activity_unverified'); }
+        }
+      }
+    } catch { block('session_inspection_failed'); block('activity_unverified'); }
+    try {
+      for (const agent of ctx.agents.list()) {
+        // Inspect activity independently: a broken model service must not hide a live agent.
+        try {
+          const status = agent.status, phase = agent.phase?.kind;
+          observations.add(digest(['agent', typeof agent.id === 'string' ? agent.id : null,
+            typeof status === 'string' ? status : null, typeof phase === 'string' ? phase : null]));
+          // Host status is idle/running; maintenance is an idle-status exclusive phase.
+          if (status === 'running' || phase === 'maintenance') block('active_turns');
+          else if (status !== 'idle' || (agent.phase && phase !== 'idle')) block('activity_unverified');
+        } catch { block('activity_unverified'); }
+        try { observe(routeProjection(agent.options)); observe(routeProjection(agent.model.current())); }
+        catch { block('agent_inspection_failed'); }
+      }
+    } catch { block('agent_inspection_failed'); block('activity_unverified'); }
+    // Bounded process observation: no credentials/configuration files are opened.
+    // A second Node DSH process is unknown, not presumed inactive. This is not a cross-home lock.
+    try {
+      for (const entry of fs.readdirSync('/proc', { withFileTypes: true })) {
+        if (!entry.isDirectory() || !/^\d+$/.test(entry.name) || Number(entry.name) === process.pid) continue;
+        let command;
+        try { command = fs.readFileSync(`/proc/${entry.name}/cmdline`, 'utf8').split('\0'); }
+        catch (error) { if (error.code === 'ENOENT' || error.code === 'ESRCH') continue; throw error; }
+        if (/(?:^|\/)node(?:js)?$/.test(command[0] || '') && command.slice(1).some(arg => {
+          if (!path.isAbsolute(arg)) return /^(?:dsh|@deepseek-ai\/dsh)(?:\/|$)/.test(arg);
+          const relative = path.relative(root, arg);
+          return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)
+            && /(?:^|\/)dsh(?:\/|$)|@deepseek-ai\/dsh/.test(arg);
+        })) {
+          block('other_process'); observations.add(digest(entry.name));
+        }
+      }
+    } catch { block('process_inspection_failed'); }
+    const blockers = [...counts].sort(([a], [b]) => a.localeCompare(b)).map(([code, count]) => ({ code, message: messages[code], count }));
+    return { blockers, fingerprint: digest([[...observations].sort(), blockers]) };
+  };
+}

package/src/maintenance-state.js

@@ -0,0 +1,186 @@
+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'];
+const ACTION_CAPABILITIES = { apply: 'canApply', 'restore-only': 'canRestoreOnly', 'restore-and-uninstall': 'canRestore' };
+
+// Never project arbitrary server messages, patch paths, or tokens into the DOM.
+export function maintenanceSnapshot(value) {
+  const phases = ['idle', 'applied', 'restored', 'removing', 'removed', 'failed'];
+  if (!value || !phases.includes(value.phase) || typeof value.restartRequired !== 'boolean'
+    || !Object.values(ACTION_CAPABILITIES).every(key => typeof value[key] === 'boolean')
+    || !(value.token == null || (typeof value.token === 'string' && value.token.length > 0))
+    || (Object.values(ACTION_CAPABILITIES).some(key => value[key]) && !(typeof value.token === 'string' && value.token.length > 0))
+    || !Array.isArray(value.patches) || !Array.isArray(value.blockers)
+    || !(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.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, 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, 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 })) };
+}
+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')
+    && (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: '补丁状态冲突，不会强制覆盖。请复制脱敏诊断；不要先卸载、还原或删除配置。',
+    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: '补丁文件检查失败，无法验证磁盘状态；不会修改未知文件。',
+    not_removable: '当前插件状态不允许安全卸载。',
+    not_applicable: '当前状态不允许安全应用补丁。',
+    manager_unavailable: '插件管理服务不可用，请稍后重试。',
+    host_unknown: '无法验证宿主版本，不会修改未知文件。',
+    state_changed: '状态已发生变化，请刷新检查后重新打开操作并确认。',
+    apply_failed: '补丁应用未完成，请刷新检查，不要视为成功。',
+    restore_failed: '原版恢复未完成，请刷新检查，不要视为成功。',
+    remove_failed: '卸载未完成，请刷新检查并使用安装诊断排查。',
+    remove_unverified: '无法验证卸载结果，请刷新检查，不要视为成功。',
+    verify_failed: '安全验证失败，不会强制覆盖文件。',
+    busy: '维护或其他任务正在运行，请结束后刷新。',
+    confirmation_required: '安全确认已失效，请刷新检查后重新打开操作并确认。',
+    maintenance_failed: '维护失败，请刷新检查并使用安装诊断排查。',
+    inspection_unknown: '无法确认运行状态，请先停止任务并使用安装诊断排查。',
+    profile_unknown: '无法确认当前配置档，不会执行维护。',
+    cross_profile_bundle: '其他配置档也在使用此插件，请先处理跨配置档依赖。',
+    alias_dependency: '仍有会话或配置引用多密钥模型，请先切换为普通模型再检查；本预览不会自动转换。',
+    key_config_dependency: '仍有多密钥配置依赖：请先禁用 multiKey 并清理 keyEntries 配置；已保存的密钥会保留。本预览不会自动转换。',
+    expression_unknown: '存在无法安全判断的配置表达式，请先人工检查配置。',
+    other_process: '其他引擎进程可能正在使用补丁，请先停止相关进程。',
+  };
+  return (labels[blocker.code.toLowerCase()] || '安全检查未通过，请先处理运行中的任务或使用安装诊断排查。')
+    + (blocker.count ? `（${blocker.count} 项）` : '');
+}
+
+// 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', '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',
+    'host_unknown', 'state_changed', 'apply_failed', 'restore_failed', 'remove_failed', 'remove_unverified',
+    'verify_failed', 'busy', 'confirmation_required', 'maintenance_failed', 'inspection_unknown', 'profile_unknown',
+    'cross_profile_bundle', 'alias_dependency', 'key_config_dependency', 'expression_unknown', 'other_process']);
+  const diagnosticItem = item => {
+    const code = item.code.toLowerCase();
+    return { code: knownCodes.has(code) ? code : 'unknown', count: item.count };
+  };
+  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) ?? [],
+    warnings: snapshot?.warnings.map(diagnosticItem) ?? [],
+  }, null, 2);
+}
+export function maintenanceWarningText(warning) {
+  const labels = {
+    alias_dependency: '旧多密钥模型选择可能影响后续使用或重启；本页不会自动切换服务或模型。',
+    key_config_dependency: '旧多密钥配置可能影响后续使用或重启；关闭会保留密钥和历史，不自动转换配置。',
+    expression_unknown: '部分配置表达式无法完整检查，请留意关闭后的使用和重启情况。',
+  };
+  const code = warning.code.toLowerCase();
+  const inspection = ['config_inspection_failed', 'session_inspection_failed', 'session_service_missing', 'process_inspection_failed', 'profile_inspection_failed', 'inspection_unknown', 'default_inspection_failed', 'agent_inspection_failed', 'activity_unverified'];
+  return (labels[code] || (inspection.includes(code) ? '检查不完整，无法确认全部依赖；这只是提醒，不会额外禁用操作。' : '部分使用情况未能验证，不等于安全；这只是提醒，不会额外禁用操作。'))
+    + (warning.count ? `（${warning.count} 项）` : '');
+}
+
+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;
+  const listeners = new Set();
+  const update = next => { if (disposed) return; state = { ...state, ...next }; for (const listener of listeners) listener(); };
+  async function readSnapshot(options) {
+    const response = await request(MAINTENANCE_ENDPOINT, { credentials: 'same-origin', cache: 'no-store', ...options });
+    if (!response.ok) throw new Error('Maintenance HTTP error');
+    const envelope = await response.json();
+    if (envelope?.ok !== true) throw new Error('Maintenance refused');
+    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' && !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.versionMismatch ? '网页与插件后端版本不一致，已停止维护。请重启原引擎并刷新网页后复查。' : snapshot.phase === 'failed' ? '维护操作失败，未确认完成。请刷新检查，不要强制覆盖。' : '' });
+  }
+  async function run(action = null) {
+    if (disposed || state.busy || (action && !maintenanceCanAction(state.snapshot, action))) return;
+    const sequence = ++generation;
+    const token = state.snapshot?.token;
+    const current = () => !disposed && sequence === generation;
+    update({ busy: true, error: '' });
+    try {
+      // Recheck immediately before using the confirmed token; a changed state needs new consent.
+      let snapshot = await readSnapshot({ method: 'GET' });
+      if (!current()) return;
+      if (action) {
+        if (snapshot.token !== token || !maintenanceCanAction(snapshot, action)) {
+          accept(snapshot);
+          update({ error: '状态已发生变化或操作被阻止，未执行操作。请检查当前状态并重新打开操作并确认。' });
+          return;
+        }
+        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, ...(clientVersion === null ? {} : { maintenanceProtocol: MAINTENANCE_CLIENT_PROTOCOL, clientVersion }) }) });
+        if (!current()) return;
+      }
+      accept(snapshot);
+    } catch {
+      if (current()) update({ snapshot: null,
+        error: action ? '未能确认维护结果：连接中断、请求被拒绝或响应无效不代表成功。请刷新检查。' : '状态检查失败，请确认连接后刷新重试。' });
+    } finally { if (current()) update({ busy: false }); }
+  }
+  const operate = (action, checked) => checked === true && Object.hasOwn(ACTION_CAPABILITIES, action) ? run(action) : Promise.resolve();
+  return {
+    getSnapshot: () => state,
+    subscribe: listener => { listeners.add(listener); return () => listeners.delete(listener); },
+    activate: () => { disposed = false; generation++; update({ busy: false }); },
+    refresh: () => run(),
+    operate,
+    apply: checked => operate('apply', checked),
+    restoreOnly: checked => operate('restore-only', checked),
+    restore: checked => operate('restore-and-uninstall', checked),
+    dispose: () => { disposed = true; generation++; listeners.clear(); },
+  };
+}

package/src/maintenance.js

@@ -0,0 +1,188 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+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
+// remains unverified; checking disk must never create persistent restart state.
+const processChangesKey = Symbol.for('dsh-model-groups.maintenance.process-changes.v1');
+const processChanges = globalThis[processChangesKey] ??= new Map();
+export function maintenanceStorage(root, home) {
+  return path.join(home, BUNDLE_NAME, sha256(fs.realpathSync(root)).slice(0, 16));
+}
+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;
+  const rootKey = fs.realpathSync(root);
+  const storage = maintenanceStorage(root, home);
+  const marker = path.join(storage, 'restore-pending.json');
+  const restartRequired = () => (processChanges.get(rootKey)?.length ?? 0) > 0;
+  function changeFiles(plans) {
+    try { applyPlan(plans, path.join(storage, 'backups')); }
+    finally {
+      // Record actual observed disk changes, not an attempted/no-op operation.
+      // Also retain evidence if verification later fails or a partial write survives.
+      const changes = plans.flatMap(plan => {
+        try {
+          const current = fs.readFileSync(plan.file, 'utf8');
+          return plan.source !== plan.result && current === plan.result
+            ? [{ file: plan.file, before: sha256(plan.source), after: sha256(current) }] : [];
+        } catch { return []; }
+      });
+      if (changes.length) processChanges.set(rootKey, [...(processChanges.get(rootKey) ?? []), ...changes]);
+    }
+  }
+  const patchPlans = () => planPatches(root, 'revert', artifacts);
+  const generic = (code, message) => ({ code, message });
+  async function assessment() {
+    const blockers = [];
+    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');
+      blockers.push(...report.blockers);
+    } catch { blockers.push(generic('INSPECTION_FAILED', '部分配置和会话使用情况未能检查；关闭后可能需要重新配置普通模型。')); }
+    try {
+      const bundles = await manager.listBundles();
+      const bundle = bundles.find(item => item.name === BUNDLE_NAME);
+      removable = !!bundle?.removable;
+       if (!removable) blockers.push(generic('NOT_REMOVABLE', '当前插件不属于可卸载的 profile 依赖，请使用安装它的原 profile 管理器。'));
+    } catch { blockers.push(generic('MANAGER_UNAVAILABLE', '插件管理器不可用，无法安全卸载。')); }
+    // 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', '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, 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 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, 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 && restoreBlockers.length === 0,
+      notice: '关闭会保留密钥和聊天记录，不自动更换服务。旧多密钥选择可能失效，旧配置可能影响重启；使用情况未完整检查时仍可确认继续。普通插件列表卸载不会还原补丁。' };
+  }
+  async function snapshot() {
+    const report = await assessment();
+    const value = view(report);
+    if (value.canRestore || value.canRestoreOnly || value.canApply) {
+      if (!ticket || ticket.stamp !== report.stamp || ticket.expires < now()) ticket = { token: crypto.randomBytes(32).toString('hex'), stamp: report.stamp, expires: now() + 120000 };
+      value.token = ticket.token;
+    }
+    return value;
+  }
+  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', '确认已失效，请重新检查并明确确认。');
+    }
+    const expected = ticket; ticket = undefined;
+    const action = input.action;
+    busy = true;
+    let locked = false;
+    const lock = path.join(storage, 'patch.lock');
+    try {
+      fs.mkdirSync(storage, { recursive: true, mode: 0o700 });
+      // Same inter-process lock as automatic installation. Never remove somebody else's lock.
+      fs.mkdirSync(lock, { mode: 0o700 }); locked = true;
+      const report = await assessment();
+      const permissions = view(report, true);
+       const permitted = action === 'apply' ? permissions.canApply : action === 'restore-only' ? permissions.canRestoreOnly : permissions.canRestore;
+       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 && 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);
+          if (!stat.isFile() || stat.isSymbolicLink()) throw generic('VERIFY_FAILED', '恢复标记异常。');
+          fs.unlinkSync(marker);
+        }
+        phase = 'applied';
+        return view(await assessment());
+      }
+      fs.writeFileSync(marker, JSON.stringify({ version: 1, purpose: 'explicit-restore-and-uninstall' }), { mode: 0o600 });
+      // Fresh synchronous planning checks concurrent target edits again; applyPlan performs an additional check.
+      changeFiles(patchPlans());
+      if (!patchPlans().every(p => p.state === 'pristine')) throw generic('VERIFY_FAILED', '原版文件复查失败，未宣告卸载成功。');
+      phase = 'restored';
+      if (action === 'restore-only') return view(await assessment());
+      phase = 'removing';
+      const result = await manager.removeBundle(BUNDLE_NAME);
+      if (!result || result.application !== 'applied' || result.error || (result.packageResult && (result.packageResult.exitCode !== 0 || result.packageResult.timedOut))) throw generic('REMOVE_FAILED', '已确认原版文件，但插件卸载失败。请保留恢复标记并在插件列表中重试卸载；是否需要重启以文件修改记录为准。');
+      const remaining = (await manager.listBundles()).find(item => item.name === BUNDLE_NAME);
+      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, 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';
+      throw ['STATE_CHANGED', 'VERIFY_FAILED', 'REMOVE_FAILED', 'REMOVE_UNVERIFIED'].includes(error?.code) ? error : generic('MAINTENANCE_FAILED', '维护未完成。未宣告成功；如已还原文件，恢复标记会阻止自动重新打补丁。请检查后重试。');
+    } finally {
+      busy = false;
+      if (locked) fs.rmdirSync(lock);
+    }
+  }
+  return { snapshot, restore, isBusy: () => busy };
+}
+
+/** Every request requires the host's authenticated owner admission, even on stock DSH. */
+export function maintenanceHandler(controller, connection) {
+  return async (req, res) => {
+    const send = (status, body) => { res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' }); res.end(JSON.stringify(body)); };
+    try {
+      const admission = connection.admit(req);
+      if (!admission?.peer || admission.peer.principal?.kind !== 'owner') return send(admission?.rejection || 403, { ok: false, error: { code: 'FORBIDDEN', message: '需要已登录的主机所有者。' } });
+      if (req.method === 'GET') return send(200, { ok: true, value: await controller.snapshot() });
+      if (req.method !== 'POST') return send(405, { ok: false, error: { code: 'METHOD', message: '不支持此操作。' } });
+      if (!/^application\/json(?:;|$)/i.test(req.headers['content-type'] || '')) return send(415, { ok: false, error: { code: 'CONTENT_TYPE', message: '只接受 JSON。' } });
+      let body = '', length = 0;
+      for await (const chunk of req) { length += Buffer.byteLength(chunk); if (length > 4096) return send(413, { ok: false, error: { code: 'BODY_LIMIT', message: '请求过大。' } }); body += chunk; }
+      let input;
+      try { input = JSON.parse(body); } catch { return send(400, { ok: false, error: { code: 'JSON', message: '请求格式错误。' } }); }
+      return send(200, { ok: true, value: await controller.restore(input) });
+    } catch (error) {
+      return send(409, { ok: false, error: { code: error?.code || 'FAILED', message: error?.code ? error.message : '检查或维护失败，请重新检查。' } });
+    }
+  };
+}