dsh-plugin-snapshot 0.1.1 → 0.3.6

package/lib/apply-all.js

@@ -0,0 +1,73 @@
+/**
+ * 批量更新：一次 pnpm add 装多个包。
+ *
+ * 为什么不是「循环调单包接口」：
+ *  - 每个包一次 pnpm add 会把依赖树重解 N 次，慢且容易在中间态失败；
+ *  - 一次装多个只有一次解析、一次写 lock，失败也是整体失败，配合快照更好收场。
+ */
+import { applyOne } from './auto-update.js';
+import { validateInstallTargets } from './install-guard.js';
+import { revertPackages } from './snapshot.js';
+
+export function registerApplyAll(deps) {
+  const { reg, cfg, needProfile, send, readBody, createSnapshot, findPnpm } = deps;
+
+  reg('/dsh-plugin-snapshot/api/apply-all', async (request, response) => {
+    try {
+      const body = await readBody(request);
+      const list = Array.isArray(body && body.items) ? body.items.slice(0, 60) : [];
+      if (!list.length) return send(response, 200, { ok: false, error: '没有可更新的目标' });
+
+      const dir = needProfile(cfg);
+      const check = validateInstallTargets(dir, list.map((it) => ({ name: String((it && it.name) || ""), version: String((it && it.version) || "") })));
+      if (!check.approved.length) {
+        return send(response, 200, { ok: false, error: '目标全部未通过校验', rejected: check.rejected });
+      }
+
+      const pnpmCjs = findPnpm();
+      if (!pnpmCjs) return send(response, 200, { ok: false, error: '找不到 pnpm' });
+
+      const snapshot = createSnapshot(dir, cfg);
+      /* 逐包执行：单个包失败不影响其余，且能精确定位失败项 */
+      const results = [];
+      for (const it of check.approved) {
+        try {
+          const r = await applyOne(dir, pnpmCjs, { name: it.name, candidate: it.version, resolved: it.version }, cfg.logger);
+          results.push({ name: it.name, version: it.version, ok: r.ok, kind: r.kind });
+        } catch (e) {
+          results.push({ name: it.name, version: it.version, ok: false, kind: "threw", error: String((e && e.message) || e) });
+        }
+      }
+
+      const okList = results.filter((x) => x.ok);
+      const badList = results.filter((x) => !x.ok);
+
+      /* 部分失败：只把失败包的版本号改回快照值，成功的保留（与自动更新同一套分层回退） */
+      let recovery = 'none';
+      if (badList.length) {
+        try {
+          const reverted = revertPackages(dir, cfg, snapshot.name, badList.map((x) => x.name));
+          if (reverted.length === badList.length) {
+            recovery = 'package-level';
+          } else {
+            recovery = 'package-level-partial';
+          }
+          const inst = await runPnpm(pnpmCjs, ['install', '--no-frozen-lockfile', '--ignore-scripts'], dir, 600000);
+          if (inst.code !== 0) recovery += '-install-failed';
+        } catch (e) {
+          recovery = 'package-level-error';
+        }
+      }
+      send(response, 200, {
+        ok: badList.length === 0,
+        count: okList.length,
+        failedCount: badList.length,
+        failed: badList,
+        rejected: check.rejected,
+        snapshot: snapshot.name,
+        recovery,
+        needRestart: okList.length > 0
+      });
+    } catch (e) { send(response, 200, { ok: false, error: String((e && e.message) || e) }); }
+  }, { write: true });
+}

package/lib/auto-update.js

@@ -0,0 +1,286 @@
+/**
+ * 自动更新：DSH 启动后检查一次，逐包安装，退出码不可信，失败分层回退。
+ *
+ * 这一版的执行模型对齐桌面工具 v3.2.6 的升级链路：
+ *   - 逐包执行：单包失败不影响其余，天然支持部分成功；
+ *   - 退出码四态判定：回读 node_modules 里的真实版本，不信 pnpm 的退出码；
+ *   - 瞬时失败重试一次（8 秒），确定性失败不重试；
+ *   - 分层回退：部分成功走包级回退，全失败走整体恢复，恢复失败就停手。
+ *
+ * 插件形态做不到的那一条：EPERM 后关闭 DSH 再重试——关掉 DSH 等于自杀。
+ * 这种情况会如实标为 failed 并提示需要手动关闭后重试。
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { checkUpdates } from './updates.js';
+import { createSnapshot, restoreSnapshot, revertPackages } from './snapshot.js';
+import { parseSemver, atomicWrite, dataDir, tsStr } from './util.js';
+import { findPnpm, runPnpm } from './exec.js';
+import { partitionByProbe } from './probe.js';
+
+const FILE = 'auto-update.json';
+
+/** 网络类瞬时失败：值得再试一次 */
+const TRANSIENT = /ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|Tarball|ERR_PNPM_FETCH(?!_404)/i;
+/** 确定性失败：重试不会改变结果，直接放弃 */
+const DETERMINISTIC = /Unable to detect compiler type|ERR_PNPM_UNSUPPORTED_ENGINE|ERR_PNPM_NO_MATCHING_VERSION|ERR_PNPM_FETCH_404|404 Not Found|ERR_PNPM_OUTDATED_LOCKFILE/i;
+/** 已知无害的退出码 1：构建脚本被忽略，但文件已到位 */
+
+export function statePath(cfg) {
+  const base = (cfg && cfg.dataDir) ? cfg.dataDir : dataDir();
+  return join(base, FILE);
+}
+
+export function readAutoState(cfg) {
+  try { return JSON.parse(readFileSync(statePath(cfg), 'utf8')); }
+  catch (e) { return null; }
+}
+
+function writeAutoState(cfg, patch) {
+  const next = Object.assign({ updatedAt: Date.now(), updatedAtText: tsStr() }, patch);
+  try { atomicWrite(statePath(cfg), JSON.stringify(next, null, 2)); } catch (e) { /* 记录失败不影响主流程 */ }
+  return next;
+}
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+/** 判定候选版本是否在允许的升级档位内；预发布永不自动安装 */
+export function isAllowedLevel(resolved, candidate, scope) {
+  const a = parseSemver(resolved);
+  const b = parseSemver(candidate);
+  if (!a || !b) return false;
+  if (b.pre) return false;
+  const s = scope || 'patch';
+  if (s === 'patch') return a.major === b.major && a.minor === b.minor && b.patch > a.patch;
+  if (s === 'minor') {
+    if (a.major !== b.major) return false;
+    if (b.minor > a.minor) return true;
+    return b.minor === a.minor && b.patch > a.patch;
+  }
+  return b.major > a.major || b.minor > a.minor || b.patch > a.patch;
+}
+
+/** 兼容旧名 */
+export function isPatchLevel(resolved, candidate) {
+  return isAllowedLevel(resolved, candidate, 'patch');
+}
+
+/** 回读磁盘上的真实版本——这是「退出码不可信」的落地方式 */
+export function verifyInstalled(dir, name, want) {
+  try {
+    const p = join(dir, 'node_modules', ...String(name).split('/'), 'package.json');
+    const v = JSON.parse(readFileSync(p, 'utf8')).version;
+    if (String(v) === String(want)) return true;
+    /* 忽略 build metadata：pnpm 可能把 1.2.3+build9 规范化成 1.2.3 */
+    const a = parseSemver(v);
+    const b = parseSemver(want);
+    if (!a || !b) return false;
+    if (a.major !== b.major || a.minor !== b.minor || a.patch !== b.patch) return false;
+    return String(a.pre || '') === String(b.pre || '');
+  } catch (e) { return false; }
+}
+
+/**
+ * 四态判定：把退出码与磁盘版本交叉。
+ *   0/到位        → 成功
+ *   0/未到位      → 失败（可能被缓存跳过）
+ *  ≠0/到位 + 仅构建脚本告警 → 成功 + 警告
+ *  ≠0/到位 + 其他错误 → 「安装结果未知」，按失败处理
+ *  ≠0/未到位     → 失败
+ */
+export function classifyResult(exitCode, installed, output) {
+  const out = String(output || '');
+  if (exitCode === 0 && installed) return { ok: true, kind: "success" };
+  if (exitCode === 0 && !installed) return { ok: false, kind: "cache-skip" };
+  if (exitCode !== 0 && installed) {
+    /* 磁盘版本到位 = 目标达成，这是唯一可信的判据。
+       只有「目标包根本没装上」类错误才判失败。
+       不要用白名单反向枚举：PEER_DEP_ISSUES、EPERM、超时后输出为空、
+       LOCKFILE_BREAKING_CHANGE 都会命中——而那时包其实已经装好了。 */
+    if (/ERR_PNPM_NO_MATCHING_VERSION|ERR_PNPM_UNSUPPORTED_ENGINE|ERR_PNPM_FETCH_404|404 Not Found/i.test(out)) {
+      return { ok: false, kind: "unverified" };
+    }
+    return { ok: true, kind: "warn", warning: "退出码非 0，但磁盘版本已到位" };
+  }
+  return { ok: false, kind: "failed" };
+}
+
+/** 输出里是否只有「构建脚本被忽略」这类无害告警 */
+export function onlyBenignBuildWarnings(output) {
+  const out = String(output || '');
+  /* 白名单判定：只认已知无害的 pnpm 错误码，其余一律判失败。
+     早期实现是黑名单 + 末行无条件 return true，任何未知错误码都会被吞成成功。 */
+  const benign = ["ERR_PNPM_IGNORED_BUILDS", "ERR_PNPM_APPROVE_SCRIPTS", "ERR_PNPM_WARN_ONLY"];
+  const codes = out.match(/ERR_PNPM_[A-Z_]+/g) || [];
+  if (codes.some((c) => benign.indexOf(c) < 0)) return false;
+  /* 没有 pnpm 错误码时，只有明确的「构建脚本被忽略」提示才算无害 */
+  if (codes.length === 0) return /Ignored build scripts/i.test(out);
+  return true;
+}
+
+/** 装一个包：执行 → 校验 → 瞬时失败重试一次 → 四态判定 */
+export async function applyOne(dir, pnpmCjs, t, logger) {
+  const spec = t.name + '@' + t.candidate;
+  const once = async () => {
+    const r = await runPnpm(pnpmCjs, ['add', spec, '--save-exact', '--ignore-scripts'], dir, 900000);
+    const installed = verifyInstalled(dir, t.name, t.candidate);
+    return { code: r.code, output: r.output, installed, timedOut: r.timedOut === true };
+  };
+
+  /* 三次退避：registry 抖动往往持续几十秒，单次 8 秒不够 */
+  const DELAYS = [8000, 30000, 90000];
+  let res = await once();
+  let verdict = classifyResult(res.code, res.installed, res.output);
+
+  for (let i = 0; i < DELAYS.length && !verdict.ok; i++) {
+    if (!TRANSIENT.test(res.output) || DETERMINISTIC.test(res.output)) break;
+    if (logger) logger.warn('[auto] ' + t.name + ' 瞬时失败，' + (DELAYS[i] / 1000) + ' 秒后第 ' + (i + 1) + ' 次重试');
+    await sleep(DELAYS[i]);
+    res = await once();
+    verdict = classifyResult(res.code, res.installed, res.output);
+  }
+
+  return Object.assign({}, t, verdict, {
+    exitCode: res.code,
+    timedOut: res.timedOut === true,
+    output: String(res.output).slice(-1200)
+  });
+}
+
+/**
+ * 跑一次自动更新。
+ * @returns {Promise<object>} 结果对象，同时写入 auto-update.json
+ */
+export async function runAutoUpdate(cfg, needProfile, logger) {
+  const started = Date.now();
+  let dir;
+  try {
+    dir = needProfile(cfg);
+  } catch (e) {
+    return writeAutoState(cfg, { outcome: 'error', error: String((e && e.message) || e), durationMs: Date.now() - started });
+  }
+
+  let report;
+  try {
+    report = await checkUpdates(dir, cfg);
+  } catch (e) {
+    return writeAutoState(cfg, { outcome: 'error', error: String((e && e.message) || e), durationMs: Date.now() - started });
+  }
+
+  const exclude = Array.isArray(cfg && cfg.autoExclude) ? cfg.autoExclude : [];
+  const targets = (report.items || []).filter((x) => {
+    if (exclude.indexOf(x.name) >= 0) return false;
+    if (x.state !== 'updatable') return false;
+    return isAllowedLevel(x.resolved || x.declared, x.candidate, cfg && cfg.autoUpdateScope);
+  });
+
+  if (!targets.length) {
+    return writeAutoState(cfg, {
+      outcome: 'no-update',
+      checked: (report.items || []).length,
+      durationMs: Date.now() - started
+    });
+  }
+
+  const pnpmCjs = findPnpm();
+  if (!pnpmCjs) {
+    return writeAutoState(cfg, { outcome: 'error', error: '找不到 pnpm', targets: targets.map((t) => t.name) });
+  }
+
+  /* 占用探测：把正被 DSH 锁住的包从本轮计划里剔掉，避免装到一半才失败 */
+  const probe = partitionByProbe(dir, targets.map((x) => x.name));
+  const runnable = targets.filter((x) => probe.runnable.indexOf(x.name) >= 0);
+  if (probe.fatal && probe.fatal.length) {
+    /* 探针回滚失败：包目录已停留在临时名，本轮必须中止且明确告警 */
+    if (logger) logger.error("[auto] 探针回滚失败，已中止本轮: " + JSON.stringify(probe.fatal));
+    return writeAutoState(cfg, {
+      outcome: "probe-damaged",
+      fatal: probe.fatal,
+      durationMs: Date.now() - started
+    });
+  }
+  if (!runnable.length) {
+    if (logger) logger.warn("[auto] 全部目标都被占用，本次跳过");
+    return writeAutoState(cfg, {
+      outcome: "locked-abort",
+      locked: probe.locked,
+      blockedCount: targets.length,
+      durationMs: Date.now() - started
+    });
+  }
+  if (probe.locked.length && logger) {
+    logger.warn("[auto] 跳过被占用的 " + probe.locked.length + " 个: " + probe.locked.map((x) => x.name).join(", "));
+  }
+
+  let snapshot;
+  try {
+    snapshot = createSnapshot(dir, cfg);
+  } catch (e) {
+    return writeAutoState(cfg, { outcome: 'error', error: '快照失败，已放弃本次自动更新：' + String((e && e.message) || e) });
+  }
+
+  if (logger) logger.info('[auto] 开始逐包更新 ' + runnable.length + ' 个，快照 ' + snapshot.name);
+
+  const results = [];
+  for (const t of runnable) {
+    try {
+      results.push(await applyOne(dir, pnpmCjs, t, logger));
+    } catch (e) {
+      results.push(Object.assign({}, t, { ok: false, kind: 'threw', error: String((e && e.message) || e) }));
+    }
+  }
+
+  const succeeded = results.filter((r) => r.ok);
+  const failed = results.filter((r) => !r.ok);
+
+  /* ---- 分层回退 ---- */
+  let recovery = 'none';
+  if (failed.length && succeeded.length) {
+    /* 部分成功：只把失败包的版本号改回去，成功的保留 */
+    const names = failed.map((f) => f.name);
+    const reverted = revertPackages(dir, cfg, snapshot.name, names);
+    /* 回退数量对不上（例如失败包不在任何依赖节里）时不能声称「已包级回退」 */
+    const level = reverted.length === names.length ? 'package-level' : 'package-level-partial';
+    if (logger) logger.warn('[auto] 部分成功，包级回退 ' + reverted.length + '/' + names.length + ' 个');
+    const inst = await runPnpm(pnpmCjs, ['install', '--no-frozen-lockfile', '--ignore-scripts'], dir, 600000);
+    const instOk = inst.code === 0 || onlyBenignBuildWarnings(inst.output);
+    recovery = instOk ? level : level + '-install-failed';
+  } else if (failed.length && !succeeded.length) {
+    /* 全部失败：整体恢复 */
+    try {
+      restoreSnapshot(dir, cfg, snapshot.name);
+      recovery = 'full';
+      /* 清单回退了，磁盘也必须回退 —— 否则是「清单旧、node_modules 新」的假回滚 */
+      const inst1 = await runPnpm(pnpmCjs, ['install', '--frozen-lockfile', '--ignore-scripts'], dir, 900000);
+      if (inst1.code !== 0) {
+        const inst2 = await runPnpm(pnpmCjs, ['install', '--no-frozen-lockfile', '--ignore-scripts'], dir, 900000);
+        if (inst2.code !== 0) recovery = 'full-manifest-only';
+      }
+      if (logger) logger.warn('[auto] 全部失败，已整体恢复快照 ' + snapshot.name);
+    } catch (e) {
+      recovery = 'full-failed';
+      if (logger) logger.error('[auto] 整体恢复失败，需人工介入：' + String((e && e.message) || e));
+    }
+  }
+
+  const outcome = failed.length === 0
+    ? 'updated'
+    : (succeeded.length > 0 ? 'partial' : (recovery === 'full' ? 'failed-rolled-back' : 'failed-rollback-error'));
+
+  const state = writeAutoState(cfg, {
+    outcome,
+    snapshot: snapshot.name,
+    recovery,
+    count: succeeded.length,
+    failedCount: failed.length,
+    skippedLocked: probe.locked,
+    succeeded: succeeded.map((r) => ({ name: r.name, version: r.candidate, kind: r.kind })),
+    failed: failed.map((r) => ({ name: r.name, version: r.candidate, kind: r.kind, exitCode: r.exitCode, output: r.output })),
+    needRestart: succeeded.length > 0,
+    durationMs: Date.now() - started
+  });
+
+  if (logger) logger.info('[auto] 结束: ' + outcome + '，成功 ' + succeeded.length + '，失败 ' + failed.length);
+  return state;
+}
+

package/lib/doctor.js

@@ -62,28 +62,41 @@ export function judgeCompatibility(pkg, dshVersion) {
 }
 
 function patchIds(text) {
+  /* 早期实现用「缩进 >= 4 空格」判断 insert 块边界，2 空格缩进的合法 YAML 会漏采。
+     改为记录 insert 行自身的缩进深度，块结束条件与宽度无关。 */
   const ids = [];
   let inInsert = false;
+  let insertIndent = -1;
   for (const raw of String(text).split(/\r?\n/)) {
     const line = raw.replace(/\s+$/, '');
-    if (/^\s*-?\s*insert:\s*$/.test(line)) { inInsert = true; continue; }
+    const indent = (line.match(/^\s*/) || [''])[0].length;
+    if (/^\s*-?\s*insert:\s*$/.test(line)) { inInsert = true; insertIndent = indent; continue; }
     if (!inInsert) continue;
     if (/^\s*$/.test(line) || /^\s*#/.test(line)) continue;
-    const m = /^\s*-?\s*id:\s*([^\s#]+)\s*$/.exec(line);
+    const m = /^\s*-?\s*id:\s*['"]?([^\s#'"]+)['"]?\s*$/.exec(line);
     if (m) { ids.push(m[1]); continue; }
-    if (/^\s*-?\s*[a-zA-Z_]+:/.test(line) && !/^\s{4,}/.test(line)) inInsert = false;
+    /* 出现与 insert 同级或更浅的键，说明块已结束 */
+    if (indent <= insertIndent && /^\s*-?\s*[a-zA-Z_]+:/.test(line)) { inInsert = false; }
   }
   return Array.from(new Set(ids));
 }
 
 function hasNative(dir) {
+  /* 早期实现只扫 build/prebuilds/native 三个目录名，.node 放在 lib/ 或 dist/ 会漏报。
+     改为全树递归（深度上限 4、条目上限 2000），每层 readdir 单独 catch。 */
+  let seen = 0;
   const walk = (d, depth) => {
-    if (depth > 2) return false;
+    if (depth > 4 || seen > 2000) return false;
     let items = [];
     try { items = readdirSync(d, { withFileTypes: true }); } catch (e) { return false; }
     for (const e of items) {
+      if (++seen > 2000) return false;
       if (e.isFile() && e.name.endsWith('.node')) return true;
-      if (e.isDirectory() && /^(build|prebuilds|native)$/.test(e.name) && walk(join(d, e.name), depth + 1)) return true;
+      if (e.isDirectory()) {
+        const n = e.name;
+        if (n === 'node_modules' || n === '.git' || n === 'test' || n === 'tests' || n === 'docs') continue;
+        if (walk(join(d, n), depth + 1)) return true;
+      }
     }
     return false;
   };
@@ -97,7 +110,9 @@ export function scanPlugins(profileDir, dshVersion) {
   const items = [];
   for (const name of Object.keys(prof.deps)) {
     const dir = join(nm, ...name.split('/'));
-    const enabled = prof.bundles.indexOf(name) >= 0;
+    /* bundles 不存在或为空时无法判断启用状态：标 null 而不是一律 false */
+    const hasBundleList = Array.isArray(prof.bundles) && prof.bundles.length > 0;
+    const enabled = hasBundleList ? (prof.bundles.indexOf(name) >= 0) : null;
     const pkgFile = join(dir, 'package.json');
     if (!existsSync(pkgFile)) {
       items.push({ name, enabled, installed: false, error: '已声明但未安装（node_modules 缺失）', declared: String(prof.deps[name]) });

package/lib/exec.js

@@ -0,0 +1,101 @@
+/**
+ * 执行外部命令：定位 pnpm 并用受控参数调用。
+ *
+ * 注意：本文件是 ESM，不能出现 require（那会在运行时抛错并被 catch 吞掉，
+ * 表现为「找不到 pnpm」）。
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/** 传给 pnpm 子进程的环境变量白名单：剔除 NPM_TOKEN 等凭据 */
+const SAFE_ENV = [
+  'PATH', 'Path', 'PATHEXT', 'SystemRoot', 'windir', 'ComSpec', 'TEMP', 'TMP',
+  'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'HOMEDRIVE', 'HOMEPATH',
+  'LANG', 'LC_ALL', 'TZ',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy',
+  'NPM_CONFIG_REGISTRY', 'npm_config_registry',
+  'NPM_CONFIG_USERCONFIG', 'npm_config_userconfig', 'NPM_CONFIG_CACHE', 'npm_config_cache', 'COREPACK_HOME'
+];
+
+function safeEnv() {
+  const out = {};
+  for (const k of SAFE_ENV) { if (process.env[k] !== undefined) out[k] = process.env[k]; }
+  out.ELECTRON_RUN_AS_NODE = '1';
+  return out;
+}
+
+/** 定位 pnpm 的 JS 入口：优先 DSH 运行时，其次 profile 自带的 */
+export function findPnpm() {
+  const cands = [];
+  try {
+    const base = join(homedir(), '.dsh', 'dsh-runtimes');
+    for (const name of readdirSync(base)) {
+      cands.push(join(base, name, 'dependencies', 'pnpm', 'bin', 'pnpm.cjs'));
+    }
+  } catch (e) { /* 没有 runtimes 目录 */ }
+  cands.push(join(homedir(), '.dsh', 'profiles', 'desktop', 'node_modules', 'pnpm', 'bin', 'pnpm.cjs'));
+  for (const c of cands) if (existsSync(c)) return c;
+  return null;
+}
+
+/**
+ * 从 node_modules/.modules.yaml 读 pnpm 的实际 store 目录。
+ * 不传 --store-dir 时 pnpm 会用自己的默认 store，与已装的 node_modules 不匹配，
+ * 直接报 ERR_PNPM_UNEXPECTED_STORE —— 这是自动更新全部失败的真实原因。
+ */
+export function detectStoreDir(profileDir) {
+  const BS = String.fromCharCode(92);
+  try {
+    const f = join(profileDir, 'node_modules', '.modules.yaml');
+    const txt = readFileSync(f, 'utf8');
+    /* pnpm 8 写 JSON 风格（带引号）；pnpm 9+ 写普通 YAML（不带引号）。两种都要认。 */
+    let v = null;
+    const m1 = new RegExp(String.fromCharCode(34) + "storeDir" + String.fromCharCode(34) + BS + "s*:" + BS + "s*" + String.fromCharCode(34) + "([^" + String.fromCharCode(34) + "]+)" + String.fromCharCode(34)).exec(txt);
+    if (m1) v = m1[1];
+    if (!v) {
+      const m2 = new RegExp("^storeDir:" + BS + "s*(.+)$", "m").exec(txt);
+      if (m2) {
+        let raw = m2[1].trim();
+        if (raw[0] === String.fromCharCode(34) || raw[0] === String.fromCharCode(39)) raw = raw.slice(1);
+        if (raw[raw.length - 1] === String.fromCharCode(34) || raw[raw.length - 1] === String.fromCharCode(39)) raw = raw.slice(0, -1);
+        if (raw) v = raw;
+      }
+    }
+    if (v) {
+      const out = v.split(BS + BS).join(BS).trim();
+      if (out) return out;
+    }
+  } catch (e) { /* 解析失败 */ }
+  /* 解析不出来就返回 null，让 pnpm 用默认 store。
+     猜一个路径比不猜更危险：猜错会 ERR_PNPM_UNEXPECTED_STORE，每个包都失败。 */
+  return null;
+}
+
+/** 跑一次 pnpm，返回 { code, output }，不抛异常 */
+export function runPnpm(pnpmCjs, args, cwd, timeoutMs) {
+  /* 自动补 --store-dir：让 pnpm 用 node_modules 实际链的那个 store */
+  let finalArgs = args;
+  try {
+    if (args.indexOf('--store-dir') < 0) {
+      const store = detectStoreDir(cwd);
+      if (store) finalArgs = args.concat(['--store-dir', store]);
+    }
+  } catch (e) { /* 探测失败就用默认 */ }
+
+  return new Promise((resolve) => {
+    execFile(process.execPath, [pnpmCjs].concat(finalArgs), {
+      cwd,
+      timeout: timeoutMs || 600000,
+      maxBuffer: 32 * 1024 * 1024,
+      env: safeEnv()
+    }, (err, stdout, stderr) => {
+      const code = err ? (typeof err.code === 'number' ? err.code : 1) : 0;
+      /* killed=true 表示被超时杀掉 */
+      const timedOut = !!(err && err.killed);
+      resolve({ code, timedOut, output: String(stdout || '') + String(stderr || '') });
+    });
+  });
+}
+

package/lib/index.js

@@ -19,12 +19,16 @@ try {
   defineTool = null;
 }
 if (typeof defineTool !== 'function') {
+  /* 宿主未提供 @deepseek-ai/dsh-tools 时降级为恒等函数：工具仍会注册，但不做 schema 校验。至少留一条日志。 */
+  console.warn('[dsh-plugin-snapshot] 未加载到 @deepseek-ai/dsh-tools，工具定义降级为恒等映射（无 schema 校验）');
   defineTool = (options) => options;
 }
 import { resolveProfileDir, readProfile } from './profile.js';
 import { createSnapshot, listSnapshots, restoreSnapshot } from './snapshot.js';
 import { checkUpdates } from './updates.js';
 import { scanPlugins, detectConflicts, priorityOf } from './doctor.js';
+import { mountRoutes } from './routes.js';
+import { runAutoUpdate } from './auto-update.js';
 import { Logger, dataDir } from './util.js';
 
 export const name = 'dsh-plugin-snapshot';
@@ -39,14 +43,22 @@ const TOOL = {
 
 function makeCtx(config) {
   const cfg = config || {};
-  return {
+  /* 透传用户的全部配置，再对已知字段做归一化。
+     审查发现：早期实现只挑 6 个字段复制，导致 autoExclude / autoUpdateScope 全部丢失，
+     用户在配置里写什么都无效。 */
+  return Object.assign({}, cfg, {
     profileDir: cfg.profileDir || '',
     registry: cfg.registry || '',
     dataDir: cfg.dataDir || dataDir(),
-    snapshotsKeep: cfg.snapshotsKeep || 7,
-    concurrency: cfg.concurrency || 8,
+    snapshotsKeep: Number(cfg.snapshotsKeep) > 0 ? Number(cfg.snapshotsKeep) : 7,
+    concurrency: Number(cfg.concurrency) > 0 ? Number(cfg.concurrency) : 8,
+    /* 默认关闭：安装本插件不应静默修改整个 profile 的依赖树 */
+    /* 配置可能来自 JSON5/YAML，写成字符串 "true" 时也应生效 */
+    autoUpdate: cfg.autoUpdate === true || String(cfg.autoUpdate).toLowerCase() === 'true',
+    autoUpdateScope: cfg.autoUpdateScope || 'patch',
+    autoExclude: Array.isArray(cfg.autoExclude) ? cfg.autoExclude : [],
     logger: new Logger()
-  };
+  });
 }
 
 function needProfile(cfg) {
@@ -119,10 +131,11 @@ export function apply(ctx, config) {
       },
       async execute(args) {
         const a = args || {};
-        if (a.registry) cfg.registry = String(a.registry);
-        const dir = needProfile(cfg);
-        cfg.logger.info('check updates in ' + dir);
-        const r = await checkUpdates(dir, cfg);
+        /* 不改 cfg：registry 是单次调用的参数，写回会永久污染后续调用与自动更新 */
+        const localCfg = a.registry ? Object.assign({}, cfg, { registry: String(a.registry) }) : cfg;
+        const dir = needProfile(localCfg);
+        localCfg.logger.info('check updates in ' + dir);
+        const r = await checkUpdates(dir, localCfg);
         const items = a.onlyUpdatable ? r.items.filter((x) => x.state === 'updatable') : r.items;
         return { profile: r.profile, registry: r.registry, summary: r.summary, items: items.map((x) => ({
           name: x.name, declared: x.declared, resolved: x.resolved || '', candidate: x.candidate || '', state: x.state, reason: x.reason || ''
@@ -293,7 +306,31 @@ export function apply(ctx, config) {
       }
     }));
 
-    ctx.logger?.info?.('[dsh-plugin-snapshot] tools registered on ' + needProfileSafe(cfg));
+        /* 设置页 UI 通过同源 HTTP 取数据：客户端不能直接调工具，只能走路由 */
+    ctx.inject(['webServer'], (hostCtx) => {
+      try {
+        mountRoutes(hostCtx, cfg, needProfile);
+        ctx.logger?.info?.('[dsh-plugin-snapshot] panel routes mounted');
+      } catch (e) {
+        ctx.logger?.warn?.('[dsh-plugin-snapshot] panel routes failed: ' + String((e && e.message) || e));
+      }
+    });
+    /* 自动更新默认不启用。只有配置里显式写 autoUpdate: true 才会注册定时器，
+       避免「装一个快照工具，45 秒后它静默改了整个依赖树」。
+       启用后的策略：默认仅补丁版、不自动重启、失败回滚到更新前的快照。 */
+    if (cfg.autoUpdate === true) {
+      ctx.effect(() => {
+        const autoTimer = setTimeout(() => {
+          runAutoUpdate(cfg, needProfile, cfg.logger).catch(() => {});
+        }, 45000);
+        return () => clearTimeout(autoTimer);
+      }, 'dsh-plugin-snapshot: auto update');
+      ctx.logger?.info?.('[dsh-plugin-snapshot] 自动更新已启用，scope=' + cfg.autoUpdateScope);
+    } else {
+      ctx.logger?.info?.('[dsh-plugin-snapshot] 自动更新未启用（配置 autoUpdate: true 可开启）');
+    }
+
+ctx.logger?.info?.('[dsh-plugin-snapshot] tools registered on ' + needProfileSafe(cfg));
   });
 
   function needProfileSafe(c) {

package/lib/install-guard.js

@@ -0,0 +1,51 @@
+/**
+ * 安装目标校验。
+ *
+ * 审查发现的问题：写接口只校验包名/版本号格式，因此可以安装任意 npm 包、
+ * 可以降级、可以装 dist-tag（latest / next），与「不做安装」的边界声明矛盾。
+ *
+ * 这里收紧为：
+ *   1) 包必须已在 profile.dependencies 中（拒绝新增依赖）；
+ *   2) 版本必须是精确的语义化版本（拒绝 latest / next 等 dist-tag）；
+ *   3) 拒绝预发布版本；
+ *   4) 目标版本必须严格高于当前版本（拒绝降级与重复安装）。
+ */
+import { readProfile, readLockVersions } from './profile.js';
+import { parseSemver, cmpSemver, isValidPkgName } from './util.js';
+
+/** 精确版本：1.2.3 / 1.2.3-beta.1 / 1.2.3+build */
+const EXACT = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+
+export function validateInstallTargets(profileDir, items) {
+  const approved = [];
+  const rejected = [];
+
+  let deps = {};
+  let lock = {};
+  try { deps = readProfile(profileDir).deps || {}; } catch (e) { deps = {}; }
+  try { lock = readLockVersions(profileDir) || {}; } catch (e) { lock = {}; }
+
+  for (const it of items || []) {
+    const name = String((it && it.name) || '');
+    const version = String((it && it.version) || '');
+    const push = (reason) => rejected.push({ name, version, reason });
+
+    if (!isValidPkgName(name)) { push('非法包名'); continue; }
+    if (!EXACT.test(version)) { push('版本号必须是精确语义化版本，不接受 dist-tag'); continue; }
+    if (!Object.prototype.hasOwnProperty.call(deps, name)) { push('该包不在 profile 依赖中，拒绝新增'); continue; }
+
+    const curStr = String(lock[name] || deps[name]);
+    const next = parseSemver(version);
+    if (!next) { push('目标版本 ' + version + ' 无法解析'); continue; }
+    if (!parseSemver(curStr)) { push('当前声明 ' + curStr + ' 无法解析，无法判定升级方向'); continue; }
+    if (next.pre) { push('拒绝预发布版本'); continue; }
+    const cmp = cmpSemver(version, curStr);
+    if (cmp === null) { push('版本号无法解析'); continue; }
+    if (cmp <= 0) { push('目标版本不高于当前安装版本，拒绝降级/重复安装'); continue; }
+
+    approved.push({ name, version });
+  }
+
+  return { approved, rejected };
+}
+