@xiaoyuyu6420/dsh-backup 0.8.0 → 0.9.1

package/lib/index.js

@@ -15,12 +15,18 @@
  * - `/backup github status|sync|pull [--restore <前缀|latest>]|repo <地址|off>`
  *                                        GitHub 同步状态 / 立即推送 / 拉取到本地 / 设置仓库
  * - `/backup delete|rm <前缀|latest>`      删除备份（归档 + 校验边车）
+ * - `/backup doctor [--repair <前缀|latest>]`  会话日志体检：按帧走查 zstd 拼接
+ *                                          日志 + seq 连续性校验，检出损坏文件；
+ *                                          --repair 从指定归档定点恢复损坏的会话
  * - `/backup --keep N`                     覆盖本次保留份数
- * - `backup_dsh` 模型工具：mode=backup|list|verify|restore|auto（restore 支持 syncDeps）
+ * - `backup_dsh` 模型工具：mode=backup|list|verify|restore|auto|doctor（restore 支持 syncDeps）
  * - cordis.yml `config`：destination / keep / exclude / redact / githubRepo（见 README）
  * - Settings「备份」标签页（Web）：状态、立即备份、校验、恢复、下载、
  *   自动备份开关与 GitHub 同步（推送 + 拉取），经 `backupPanel` Typert Remote 命名空间访问
  * - Web 下载路由：GET /backup-download/<归档名>（仅 loopback，附件形式）
+ * - 救援通道（进程外）：每次备份把 rescue.mjs + 双击启动器（点我恢复.command/.bat/.sh）
+ *   + RESCUE.txt 写进备份目录——DSH 起不来时双击/`node rescue.mjs` 打开零依赖
+ *   救援网页（列表/校验/恢复/doctor），Node 活着就能自救
  *
  * 安全说明（v0.7.0 起）：凭据文件（.credentials.yaml / .env / qq-bridge/config.json，
  * config.redact 可增删）默认脱敏——不进归档、不进 GitHub 同步，明文只存备份目录下
@@ -35,11 +41,14 @@
  * 模型面的沙箱 surface（workspace-write 会拒绝 Desktop），不适用于宿主
  * 插件的自有存储。
  */
-import { createHash } from 'node:crypto';
-import { createReadStream } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, readFileSync, realpathSync } from 'node:fs';
 import { mkdir, open, copyFile, readdir, readFile, rename, rm, stat as fsStat, unlink, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import { hostname } from 'node:os';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as zlib from 'node:zlib';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { settingsNamespace, SettingsConflictError } from '@deepseek-ai/dsh-settings';
@@ -69,6 +78,141 @@ const SENSITIVE_DEFAULTS = ['.credentials.yaml', '.env', 'qq-bridge/config.json'
 /** 备份目录下保存明文敏感文件的子目录（随备份刷新为最新一份的副本）。 */
 const VAULT_DIR = 'vault';
 
+/** 随备份落盘的救援说明：DSH 起不来时，用户打开备份目录第一眼能看到的东西。 */
+const RESCUE_TXT = `DSH 出问题时的自救通道（不依赖 DSH 能否启动）
+====================================================
+
+最简单：双击「点我恢复」文件（macOS .command / Windows .bat / Linux .sh），
+浏览器会自动打开救援页面，点按钮即可校验/恢复/修复。
+
+没有双击文件或想用终端:
+  node rescue.mjs                        打开救援网页（同上）
+  node rescue.mjs list                   列出备份
+  node rescue.mjs verify all             校验完整性
+  node rescue.mjs restore latest         预览恢复；加 --yes 执行
+  node rescue.mjs doctor                 会话日志体检
+  node rescue.mjs doctor --repair        修复损坏的会话日志
+
+恢复是整体替换：现有 .dsh 会先自动快照并挪到一旁（.dsh.pre-restore-*），
+凭据从本目录 vault/ 自动补回。rescue.mjs / 启动器 / 本说明由 dsh-backup 每次备份时更新。
+`;
+
+/** 双击启动器：起救援服务并自动开浏览器。按当前平台生成，避免目录里躺三个系统的文件。 */
+const RESCUE_LAUNCHERS = Object.freeze({
+  darwin: ['点我恢复.command', '#!/bin/sh\ncd "$(dirname "$0")" || exit 1\nexec node rescue.mjs serve --open\n'],
+  win32: ['点我恢复.bat', '@echo off\r\nchcp 65001 >nul\r\ncd /d "%~dp0"\r\nnode rescue.mjs serve --open\r\npause\r\n'],
+  linux: ['点我恢复.sh', '#!/bin/sh\ncd "$(dirname "$0")" || exit 1\nexec node rescue.mjs serve --open\n'],
+});
+
+/**
+ * 从归档名解析自然日（dsh-YYYYMMDD-HHMMSSmmm）；解析不出返回 null。
+ * 纯函数、模块级：轮换分层与测试共用。
+ */
+function archiveDay(name) {
+  const m = /^dsh-(\d{4})(\d{2})(\d{2})-\d{6}\d{3}\.tar\.gz$/.exec(name);
+  return m ? `${m[1]}-${m[2]}-${m[3]}` : null;
+}
+
+/** ISO 周号（周一为首日，YYYY-Www）：跨日/跨周分层保留的桶键。 */
+function isoWeekOf(day) {
+  const dt = new Date(`${day}T00:00:00Z`);
+  const dayNum = (dt.getUTCDay() + 6) % 7;
+  dt.setUTCDate(dt.getUTCDate() - dayNum + 3);
+  const firstThursday = new Date(Date.UTC(dt.getUTCFullYear(), 0, 4));
+  const fday = (firstThursday.getUTCDay() + 6) % 7;
+  firstThursday.setUTCDate(firstThursday.getUTCDate() - fday + 3);
+  return `${dt.getUTCFullYear()}-W${String(1 + Math.round((dt - firstThursday) / 604800000)).padStart(2, '0')}`;
+}
+
+/**
+ * 分级轮换的保护集：tailDesc（keep 窗口外、新→旧）里，每个自然日的首份受
+ * 保护（最多 7 个不同日）；某日已见或日额用尽时，落至周级——该 ISO 周首份
+ * 受保护（最多 4 个不同周；日级保护同时登记其所在周，避免同周重复占额）。
+ * 今日的档内冗余不保护（keep 窗口已覆盖今日）。返回受保护的归档名集合。
+ */
+function tierProtectedSet(tailDesc, newestName) {
+  const protectedNames = new Set();
+  const daySeen = new Set();
+  const weekSeen = new Set();
+  const today = newestName ? archiveDay(newestName) : null;
+  let daysLeft = 7;
+  let weeksLeft = 4;
+  for (const b of tailDesc) {
+    const d = archiveDay(b.name);
+    if (!d || d === today) continue;
+    const wk = isoWeekOf(d);
+    if (!daySeen.has(d) && daysLeft > 0) {
+      daySeen.add(d);
+      weekSeen.add(wk);
+      daysLeft -= 1;
+      protectedNames.add(b.name);
+    } else if (!weekSeen.has(wk) && weeksLeft > 0) {
+      weekSeen.add(wk);
+      weeksLeft -= 1;
+      protectedNames.add(b.name);
+    }
+  }
+  return protectedNames;
+}
+
+/**
+ * 探测正在运行的宿主版本（升级前快照的触发依据）。
+ * 关键约束：必须测"正在跑的宿主"，而不是 profile 里 hoisted 的 peer 包——
+ * 用户经全局 CLI / `npx @deepseek-ai/dsh web` 升级宿主时，profile 的 peer
+ * 包纹丝不动，peer 代理会永远 stale、快照永不触发。
+ * 优先级：
+ *   1. env DSH_VERSION（宿主未来若提供则最准）
+ *   2. process.argv[1] 真实路径向上扫：宿主 bin 位于
+ *      <...>/node_modules/@deepseek-ai/dsh/ 下（覆盖全局/npm/npx 缓存/
+ *      本地目录安装），或自身就在包目录内
+ *   3. createRequire 解析 @deepseek-ai/dsh/package.json（解析链恰含宿主时命中）
+ *   4. peer @dsh-settings 版本代理（最后兜底：测的是 profile 列车，仅覆盖
+ *      "重装插件/刷新 hoisted 包带动列车"的场景）
+ * 全部失败返回 null（快照特性静默停用，绝不影响装配）。
+ */
+function detectHostTrain() {
+  const fromEnv = process.env.DSH_VERSION;
+  if (typeof fromEnv === 'string' && fromEnv.trim()) return fromEnv.trim();
+  try {
+    if (process.argv[1]) {
+      let dir = dirname(realpathSync(process.argv[1]));
+      for (let i = 0; i < 8 && dir !== dirname(dir); i += 1) {
+        const candidates = [join(dir, 'node_modules', '@deepseek-ai', 'dsh', 'package.json')];
+        if (basename(dir) === 'dsh' && basename(dirname(dir)) === '@deepseek-ai') {
+          candidates.push(join(dir, 'package.json'));
+        }
+        for (const c of candidates) {
+          try {
+            const v = JSON.parse(readFileSync(c, 'utf8')).version;
+            if (typeof v === 'string' && v) return v;
+          } catch { /* 尝试下一个候选 */ }
+        }
+        dir = dirname(dir);
+      }
+    }
+  } catch { /* argv 异常走兜底 */ }
+  try {
+    const v = JSON.parse(readFileSync(createRequire(import.meta.url).resolve('@deepseek-ai/dsh/package.json'), 'utf8')).version;
+    if (typeof v === 'string' && v) return v;
+  } catch { /* 宿主不在本插件的解析链上 */ }
+  const candidates = [];
+  try {
+    candidates.push(createRequire(import.meta.url).resolve('@deepseek-ai/dsh-settings/package.json'));
+  } catch { /* exports 未暴露 package.json */ }
+  try {
+    for (const rel of ['../node_modules/@deepseek-ai/dsh-settings/package.json', '../../node_modules/@deepseek-ai/dsh-settings/package.json', '../../../node_modules/@deepseek-ai/dsh-settings/package.json']) {
+      candidates.push(fileURLToPath(new URL(rel, import.meta.url)));
+    }
+  } catch { /* URL 解析异常 */ }
+  for (const p of candidates) {
+    try {
+      const v = JSON.parse(readFileSync(p, 'utf8')).version;
+      if (typeof v === 'string' && v) return v;
+    } catch { /* 尝试下一个候选 */ }
+  }
+  return null;
+}
+
 /** Settings 命名空间：经 `ctx.settings` 提供（持久化到 $DSH_HOME/settings.yaml）。 */
 const NS = settingsNamespace('dsh-backup');
 
@@ -194,6 +338,8 @@ const PANEL_INVOCATIONS = Object.freeze([
   panelDescriptor('githubPull', [], true),
   panelDescriptor('removeEntry', ['selector'], true),
   panelDescriptor('setGithubRepo', ['repo']),
+  panelDescriptor('doctorScan', [], true),
+  panelDescriptor('doctorRepair', ['selector'], true),
 ]);
 
 /**
@@ -257,6 +403,16 @@ class BackupPanelService extends TypertRemoteService {
   setGithubRepo(repo) {
     return this.ops.setGithubRepo(repo);
   }
+
+  /** 会话日志体检（只读扫描，不写任何文件）。 */
+  doctorScan(signal) {
+    return this.ops.doctorScan(signal);
+  }
+
+  /** 从指定归档定点修复损坏的会话日志（缺省最新一份）。 */
+  doctorRepair(selector, signal) {
+    return this.ops.doctorRepair(selector, signal);
+  }
 }
 
 export function apply(ctx, pluginConfig) {
@@ -528,7 +684,8 @@ export function apply(ctx, pluginConfig) {
    * 这一份。恢复是低频操作，快照又被 listBackups 排除、用户不可见，故每
    * 次恢复后清掉前一次的快照防隐藏累积（aside 目录仍由用户自行管理）。
    */
-  async function prunePreRestoreSnapshots(keepName, signal) {
+  /** 清理内部快照（pre-restore / pre-upgrade 共用）：只保留最近 keepN 份。 */
+  async function prunePrefixedSnapshots(prefix, keepN, keepName, signal) {
     const { root } = paths();
     let dirents;
     try {
@@ -536,11 +693,20 @@ export function apply(ctx, pluginConfig) {
     } catch {
       return;
     }
-    const keepSet = new Set(sidecarsFor(keepName));
-    const stale = dirents
-      .filter((d) => d.name.startsWith('dsh-pre-restore-') && (d.name.endsWith('.tar.gz') || d.name.endsWith('.sha256') || d.name.endsWith('.meta.json') || d.name.endsWith('.redacted.json')) && !keepSet.has(d.name))
-      .map((d) => d.name);
-    if (stale.length) await removeFiles(stale, root, signal);
+    const names = dirents
+      .filter((d) => d.name.startsWith(prefix) && (d.name.endsWith('.tar.gz') || d.name.endsWith('.sha256') || d.name.endsWith('.meta.json') || d.name.endsWith('.redacted.json')))
+      .map((d) => d.name)
+      .sort()
+      .reverse();
+    // 归档名排序即时间序；边车跟宿主同名排序紧邻其后，按"每份归档一组"数份数
+    const archiveCount = names.filter((n) => n.endsWith('.tar.gz'));
+    const staleArchives = archiveCount.slice(keepN).filter((n) => n !== keepName);
+    const staleSet = new Set(staleArchives.flatMap((n) => sidecarsFor(n)));
+    if (staleSet.size) await removeFiles([...staleSet], root, signal);
+  }
+
+  async function prunePreRestoreSnapshots(keepName, signal) {
+    await prunePrefixedSnapshots('dsh-pre-restore-', 1, keepName, signal);
   }
 
   /** 归档伴生边车集：轮换、删除与 GitHub 同步对同一归档统一处理的文件列表。 */
@@ -548,6 +714,9 @@ export function apply(ctx, pluginConfig) {
     return [name, `${name}.sha256`, `${name}.meta.json`, `${name}.redacted.json`];
   }
 
+  /** 内部快照前缀（恢复前 / 升级前）：不进用户列表、不参与轮换与 keep 配额。 */
+  const SNAPSHOT_PREFIXES = Object.freeze(['dsh-pre-restore-', 'dsh-pre-upgrade-']);
+
   async function listBackups() {
     const { root } = paths();
     let dirents;
@@ -559,10 +728,10 @@ export function apply(ctx, pluginConfig) {
     }
     const backups = [];
     for (const d of dirents) {
-      // 恢复前自动快照（dsh-pre-restore-*）是内部安全网，不进用户列表、
-      // 不参与轮换、不被 pickArchive 的 latest/前缀误选——经 listBackups
-      // 过滤即可同时收口这三处入口。
-      if (!d.name.startsWith('dsh-') || d.name.startsWith('dsh-pre-restore-') || !d.name.endsWith('.tar.gz')) continue;
+      // 内部快照（dsh-pre-restore-* / dsh-pre-upgrade-*）不进用户列表、
+      // 不参与轮换、不被 pickArchive 的 latest 误选；显式前缀仍可选中
+      // （见 pickArchive 的快照回退分支）。
+      if (!d.name.startsWith('dsh-') || SNAPSHOT_PREFIXES.some((p) => d.name.startsWith(p)) || !d.name.endsWith('.tar.gz')) continue;
       let size;
       try {
         size = (await fsStat(`${root}/${d.name}`)).size;
@@ -575,6 +744,22 @@ export function apply(ctx, pluginConfig) {
     return backups.sort((a, b) => (a.name < b.name ? 1 : a.name > b.name ? -1 : 0));
   }
 
+  /** 列出内部快照归档名（新→旧），prefix 传 'dsh-pre-' 可同时取两类。 */
+  async function listSnapshotNames(prefix = 'dsh-pre-') {
+    const { root } = paths();
+    let dirents;
+    try {
+      dirents = await readdir(root, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    return dirents
+      .filter((d) => d.name.endsWith('.tar.gz') && SNAPSHOT_PREFIXES.some((p) => d.name.startsWith(p)) && d.name.startsWith(prefix))
+      .map((d) => d.name)
+      .sort()
+      .reverse();
+  }
+
   async function writeOwned(p, content) {
     await mkdir(dirname(p), { recursive: true });
     await writeFile(p, content, 'utf8');
@@ -614,6 +799,17 @@ export function apply(ctx, pluginConfig) {
     const base = dshHome.split('/').pop();
     const parent = dshHome.slice(0, -(base.length + 1)) || '/';
 
+    // 备份前体检联动：损坏的会话日志**不入档**——坏字节一旦进了归档，轮换会在
+    // 不知情的情况下删掉最后一份好副本。检出项记入 meta.quarantined，恢复侧
+    // 如实提示。体检失败不阻断备份（fail-open）。
+    let quarantined = [];
+    if (!opts?.skipScan) {
+      try {
+        quarantined = (await runDoctorScan(signal)).corrupt.map((c) => c.rel);
+      } catch { /* 扫描异常按无隔离处理 */ }
+    }
+    const quarantineFlags = quarantined.map((rel) => `--exclude=${base}/${rel}`);
+
     // tar 以备份目录为 cwd、用纯文件名传 -f：Windows 上 GNU tar（msys）会把
     // 含盘符冒号的绝对路径当远程归档（"Cannot connect to C"），bsdtar 则两者皆可。
     // 敏感文件先从归档排除（redactExcludeFlags），其明文副本进本机 vault。
@@ -621,7 +817,7 @@ export function apply(ctx, pluginConfig) {
     // 仅存的凭据副本清掉——只列清单不拷贝，vault 保持上一次常规备份的状态。
     const redacted = opts?.skipVault ? await existingSensitive(dshHome) : await refreshVault(dshHome, home, signal);
     const tar = await ctx.subprocess.resolveExecutable('tar');
-    await spawnRun([tar, '--exclude=*node_modules*', '--exclude=.system', ...redactExcludeFlags(base), ...extraExcludes(), '-czf', name, '-C', parent, base], root, signal);
+    await spawnRun([tar, '--exclude=*node_modules*', '--exclude=.system', ...quarantineFlags, ...redactExcludeFlags(base), ...extraExcludes(), '-czf', name, '-C', parent, base], root, signal);
 
     const shaText = await sha256File(out, home, signal);
     await writeOwned(`${out}.sha256`, `${shaText}  ${out}\n`);
@@ -629,8 +825,26 @@ export function apply(ctx, pluginConfig) {
     if (sensitivePaths().length) {
       await writeOwned(`${out}.redacted.json`, `${JSON.stringify({ files: redacted })}\n`);
     }
-    // 机器元数据边车：跨机恢复的预检依据（home 不一致 → 绝对路径提示）。
-    await writeOwned(`${out}.meta.json`, `${JSON.stringify({ host: hostname(), home, dshHome, createdAt: new Date().toISOString(), redacted: redacted.length })}\n`);
+    // 机器元数据边车：跨机恢复的预检依据（home 不一致 → 绝对路径提示）；
+    // quarantined 记录体检隔离、未入档的损坏会话文件。
+    await writeOwned(`${out}.meta.json`, `${JSON.stringify({ host: hostname(), home, dshHome, createdAt: new Date().toISOString(), redacted: redacted.length, ...(quarantined.length ? { quarantined } : {}) })}\n`);
+
+    // 救援通道：每次备份把进程外恢复工具落进备份目录——宿主起不来时
+    // `node rescue.mjs`（或双击启动器）仍可恢复（DSH 依赖 Node，宿主死了
+    // Node 一定活着）。复制失败不阻断备份：rescue 缺席只影响灾时体验。
+    try {
+      await copyFile(new URL('../rescue/rescue.mjs', import.meta.url), `${root}/rescue.mjs`);
+      await writeOwned(`${root}/RESCUE.txt`, RESCUE_TXT);
+      const launcher = RESCUE_LAUNCHERS[process.platform];
+      if (launcher) {
+        const [name, content] = launcher;
+        await writeOwned(`${root}/${name}`, content);
+        if (!IS_WIN) {
+          const chmod = await ctx.subprocess.resolveExecutable('chmod');
+          await spawnRun([chmod, '755', `${root}/${name}`], home, signal);
+        }
+      }
+    } catch { /* 老安装缺文件等场景静默跳过 */ }
 
     // 安全：备份含明文凭据（.credentials.yaml / qq-bridge/config.json），收紧为仅本人可读写。
     // Windows 无 chmod，用户目录 ACL 默认私有。
@@ -639,9 +853,13 @@ export function apply(ctx, pluginConfig) {
       await spawnRun([chmod, '600', out, `${out}.sha256`], home, signal);
     }
 
-    // 轮换：只保留最近 keepN 份
+    // 分级轮换：keep 窗口之外的尾巴不再一刀切全删——保留最近 7 个不同自然日
+    // 的每日首份、再往前 4 个不同 ISO 周的每周首份（今日的档内冗余仍按 keep
+    // 裁剪）。严格只比旧的"全删"多保留，绝不多删；非标准命名（解析不出日期）
+    // 保持旧行为不保护。
     const all = await listBackups();
-    const stale = all.slice(keepN).map((b) => b.name);
+    const tail = all.slice(keepN);
+    const stale = tail.filter((b) => !tierProtectedSet(tail, all[0]?.name).has(b.name)).map((b) => b.name);
     if (stale.length) {
       await removeFiles(stale.flatMap((n) => sidecarsFor(n)), root, signal);
     }
@@ -664,7 +882,14 @@ export function apply(ctx, pluginConfig) {
       await saveAutoState();
     }
 
-    return { path: out, name, sha: shaText, total: all.length, stale: stale.length, keep: keepN, sync };
+    return { path: out, name, sha: shaText, total: all.length, stale: stale.length, keep: keepN, quarantined, sync };
+  }
+
+  /** 备份回执的隔离提示行：体检发现坏会话文件未入档时如实告知 + 指路修复。 */
+  function quarantineNote(r) {
+    return Array.isArray(r?.quarantined) && r.quarantined.length
+      ? `\n⚠️ ${r.quarantined.length} 个损坏会话文件未入档（防轮换毁掉好副本）；/backup doctor --repair 修复后可正常备份`
+      : '';
   }
 
   // ---------- GitHub 同步 ----------
@@ -934,7 +1159,17 @@ export function apply(ctx, pluginConfig) {
     const exact = all.filter((b) => b.name === selector);
     const hits = exact.length ? exact : all.filter((b) => b.name.startsWith(selector));
     if (hits.length === 1) return hits[0];
-    if (!hits.length) throw new Error(`没有匹配 "${selector}" 的备份，/backup list 查看`);
+    if (!hits.length) {
+      // 显式前缀可命中内部快照（升级前/恢复前）——latest 永不落入此分支
+      const snaps = await listSnapshotNames('dsh-pre-');
+      const sExact = snaps.filter((n) => n === selector);
+      const sHits = sExact.length ? sExact : snaps.filter((n) => n.startsWith(selector));
+      if (sHits.length === 1) return { name: sHits[0], size: undefined };
+      if (sHits.length > 1) {
+        throw new Error(`"${selector}" 匹配多份快照，请加长前缀：\n${sHits.slice(0, 5).map((n) => `  ${n}`).join('\n')}`);
+      }
+      throw new Error(`没有匹配 "${selector}" 的备份，/backup list 查看`);
+    }
     throw new Error(`"${selector}" 匹配多份备份，请加长前缀：\n${hits.slice(0, 5).map((b) => `  ${b.name}`).join('\n')}`);
   }
 
@@ -1023,26 +1258,28 @@ export function apply(ctx, pluginConfig) {
     if (Array.isArray(preflight.redactedFiles)) {
       lines.push(`🔐 该归档已脱敏：${preflight.redactedFiles.length} 个凭据文件不随归档走，恢复时从本机 vault 还原（跨机恢复需重填）`);
     }
+    if (preflight.legacyUnaccountedCredentials) {
+      lines.push('⚠️ 归档未携带脱敏清单（v0.6.x 时代格式）且不含凭据文件——恢复后凭据需从本机 vault 或原机器补齐');
+    }
+    if (Array.isArray(preflight.quarantinedFiles) && preflight.quarantinedFiles.length) {
+      lines.push(`⚠️ 备份时体检隔离了 ${preflight.quarantinedFiles.length} 个损坏会话文件（未入档）——这些会话恢复后缺失，可用 /backup doctor --repair 从更早归档修复`);
+    }
     if (profileDirs.length) {
       lines.push(`📦 归档含 ${profileDirs.length} 个 profile 的依赖声明（node_modules 不随归档），恢复后用 --sync-deps 或手动 pnpm install 重装插件`);
     }
     return lines;
   }
 
-  async function restoreArchive(selector, dryRun, signal, opts = {}) {
-    const { home, dshHome, root } = paths();
-    const picked = await pickArchive(selector);
-    const archive = `${root}/${picked.name}`;
-
-    // 恢复前强制校验：损坏的归档绝不覆盖现有数据。
-    const v = await verifyOne(picked.name, home, signal);
-    if (!v.ok) throw new Error(`校验未通过（${v.note}），恢复已中止`);
-
+  /**
+   * 列出归档全部条目并做安全校验（restoreArchive 与 doctorRepair 共用）：
+   * cwd 为备份目录、-f 用纯文件名（规避 Windows GNU tar 盘符冒号问题），
+   * 逐行解析 -tvzf 输出并拒绝备份根之外的任何条目——含不安全条目直接抛错。
+   */
+  async function safeArchiveEntries(pickedName, signal) {
+    const { root, dshHome } = paths();
     const base = dshHome.split('/').pop();
-    const parent = dshHome.slice(0, -(base.length + 1)) || '/';
     const tar = await ctx.subprocess.resolveExecutable('tar');
-    // 同 doBackup：cwd 为备份目录，-f 用纯文件名，规避 Windows GNU tar 的盘符冒号问题。
-    const listed = await spawnRun([tar, '-tvzf', picked.name], root, signal);
+    const listed = await spawnRun([tar, '-tvzf', pickedName], root, signal);
     // tar 路径穿越防护：逐行解析 -tvzf 输出（双布局，见 parseTarEntry），
     // 条目必须是普通文件/目录、相对路径且位于备份根目录之下；任一违规
     // 即整体拒绝，恢复绝不触碰备份根之外的文件。
@@ -1070,6 +1307,21 @@ export function apply(ctx, pluginConfig) {
     if (bad.length) {
       throw new Error(`归档包含不安全条目（拒绝恢复）：${bad.slice(0, 3).join(', ')}，恢复已中止`);
     }
+    return entries;
+  }
+
+  async function restoreArchive(selector, dryRun, signal, opts = {}) {
+    const { home, dshHome, root } = paths();
+    const picked = await pickArchive(selector);
+    const archive = `${root}/${picked.name}`;
+
+    // 恢复前强制校验：损坏的归档绝不覆盖现有数据。
+    const v = await verifyOne(picked.name, home, signal);
+    if (!v.ok) throw new Error(`校验未通过（${v.note}），恢复已中止`);
+
+    const base = dshHome.split('/').pop();
+    const parent = dshHome.slice(0, -(base.length + 1)) || '/';
+    const entries = await safeArchiveEntries(picked.name, signal);
 
     // 预检（dry-run 与真实恢复共用）：跨机 home 对比 + 脱敏清单 + profile 依赖。
     const { meta, redactedFiles } = await readArchiveMeta(picked.name);
@@ -1078,14 +1330,34 @@ export function apply(ctx, pluginConfig) {
       sourceHost: meta?.host ?? null,
       sourceHome: meta?.home ?? null,
       redactedFiles,
+      quarantinedFiles: Array.isArray(meta?.quarantined) ? meta.quarantined : null,
+      // 老归档无 .redacted.json：无法声明凭据保障。若归档里也没有任何敏感
+      // 路径条目，恢复出的数据将缺凭据——如实提示，优于静默缺文件。
+      legacyUnaccountedCredentials: !Array.isArray(redactedFiles)
+        && sensitivePaths().length > 0
+        && !entries.some((e) => sensitivePaths().some((rel) => e.endsWith(`/${rel}`))),
     };
     const profileDirs = [...new Set(entries
       .filter((n) => n.startsWith(`${base}/profiles/`) && n.endsWith('/package.json'))
       .map((n) => n.slice(`${base}/profiles/`.length).split('/')[0]))];
 
+    // 现有数据探测：~/.dsh 已缺失（数据全失/新机首恢复）时没有可快照的
+    // 内容，跳过快照与挪旁直接解压——先快照后判存在的旧序会让 tar 对不
+    // 存在的 .dsh 报错，恢复在最需要的场景反而失败。ENOENT 视为首次恢
+    // 复；其他 stat 失败（如 EACCES）中止恢复，不在不明状态下动现有数
+    // 据。预览（dry-run）也据此切换「挪旁+快照」与「直接写入」两种口径。
+    const targetExists = await fsStat(dshHome).then(
+      () => true,
+      (err) => {
+        if (err && err.code === 'ENOENT') return false;
+        throw err;
+      },
+    );
+
     if (dryRun) {
       return {
         archive, files: entries.length, sample: entries.slice(0, 12), aside: null, snapshotPath: null, dryRun: true,
+        targetExists,
         preflight: preflightLines(preflight, profileDirs),
       };
     }
@@ -1093,30 +1365,39 @@ export function apply(ctx, pluginConfig) {
     // 恢复前自动快照当前数据，并把当前数据移到旁边（而非合并覆盖）。
     // 快照用 dsh-pre-restore- 前缀与用户常规备份区分，经 listBackups 过滤
     // 后不进列表/轮换/latest 选择；每次恢复清掉上一次的快照防累积。
-    // 现有数据存在性先行：~/.dsh 已缺失（数据全失/新机首恢复）时没有可
-    // 快照的内容，跳过快照直接解压——先快照后判存在的旧序会让 tar 对
-    // 不存在的 .dsh 报错，恢复在最需要的场景反而失败。
-    let current = false;
-    try {
-      await fsStat(dshHome);
-      current = true;
-    } catch (err) {
-      // dshHome 不存在（ENOENT）视为首次恢复、无现有数据可移开；其他 stat
-      // 失败（如 EACCES）中止恢复，不跳过 aside 直接覆盖现有数据
-      if (!err || err.code !== 'ENOENT') throw err;
-      current = false;
-    }
-    const snapshot = current
+    const snapshot = targetExists
       ? await doBackup(undefined, signal, { namePrefix: 'dsh-pre-restore-', skipVault: true })
       : null;
     if (snapshot) await prunePreRestoreSnapshots(snapshot.name, signal);
+    const asideName = `${base}.pre-restore-${stampNow()}`;
     let aside = null;
-    if (current) {
-      const asideName = `${base}.pre-restore-${stampNow()}`;
+    if (targetExists) {
       await renameBeside(parent, base, asideName, signal);
       aside = `${parent}/${asideName}`;
     }
-    await spawnRun([tar, '-xzf', picked.name, '-C', parent], root, signal);
+    try {
+      const tar = await ctx.subprocess.resolveExecutable('tar');
+      await spawnRun([tar, '-xzf', picked.name, '-C', parent], root, signal);
+    } catch (err) {
+      // 挪旁之后解压失败会让 .dsh 处于空位——这是恢复流程里用户最容易慌
+      // 的时刻。尽力自动回滚：清掉半截解压产物、把原数据改回原名；连回滚
+      // 都失败时，错误消息必须带上数据位置和手工还原方法，绝不抛裸异常。
+      const reason = err && err.message ? err.message : String(err);
+      let rolledBack = false;
+      try {
+        await rm(dshHome, { recursive: true, force: true });
+        if (targetExists) await renameBeside(parent, asideName, base, signal);
+        rolledBack = true;
+      } catch {
+        // 回滚失败：落入下方的人工指引分支，把位置交代清楚
+      }
+      if (rolledBack) {
+        throw new Error(`解压归档失败（${reason}）。已自动还原到恢复前状态，数据未丢失；排查磁盘空间/权限后可重试`);
+      }
+      throw new Error(aside
+        ? `解压归档失败（${reason}），且自动还原未成功。原数据完好保存在 ${aside}，把它改名回 "${dshHome}" 即可回到恢复前状态`
+        : `解压归档失败（${reason}），且清理未成功。半截解压产物在 ${dshHome}，删除后即可重试`);
+    }
 
     // vault 还原：脱敏归档恢复出的 ~/.dsh 不含凭据文件，从本机 vault 拷回。
     // vault 为空（跨机首恢复）时逐项记入 missing，由调用方提示重填——凭据
@@ -1177,28 +1458,368 @@ export function apply(ctx, pluginConfig) {
   /** 恢复结果的人类可读汇总（命令、模型工具与面板共用）。 */
   function summarizeRestore(r) {
     if (r.dryRun) {
-      const pre = r.preflight?.length ? `\n${r.preflight.map((l) => `  ${l}`).join('\n')}` : '';
-      return `📦 恢复预览（未写入）\n  归档: ${r.archive}\n  条目: ${r.files} 项${pre}\n${r.sample.map((s) => `    ${s}`).join('\n')}`;
-    }
-    const lines = ['✅ 恢复完成', `  来源: ${r.archive}（${r.files} 项）`];
-    if (r.snapshotPath) lines.push(`  恢复前快照: ${r.snapshotPath}`);
-    if (r.aside) lines.push(`  旧数据已移至: ${r.aside}`);
-    for (const p of r.preflight ?? []) lines.push(`  ${p}`);
-    if (r.vaultRestored?.length) lines.push(`🔐 本机 vault 已还原 ${r.vaultRestored.length} 个凭据文件`);
-    if (r.vaultMissing?.length) lines.push(`⚠️ 以下凭据文件不在本机 vault，需重填: ${r.vaultMissing.join(', ')}`);
-    if (r.deps?.installed?.length) lines.push(`📦 已重装 profile 依赖: ${r.deps.installed.join(', ')}`);
-    if (r.deps?.failed?.length) lines.push(`⚠️ 依赖重装失败: ${r.deps.failed.join(', ')}`);
-    if (r.deps?.note) lines.push(`⚠️ ${r.deps.note}`);
-    lines.push('  请重启 dsh 使恢复的会话与配置生效。');
+      // 预览要回答两件事：确认后会发生什么（按目标是否已有数据切换口径）、
+      // 凭据/依赖的 preflight 提醒。此时还没动任何文件，标题必须说清。
+      const moves = r.targetExists === false
+        ? ['   · 目标位置还没有 .dsh（首次恢复）：直接写入，不做挪动和快照']
+        : [
+          '   · 当前的 .dsh 整个挪到一旁，改名为 .dsh.pre-restore-<时间>，不会和新数据混在一起',
+          '   · 挪之前自动做一份快照备份；快照只保留最近一次',
+          '   · 然后把这份归档的内容原样写回 .dsh',
+        ];
+      const pre = ['', ...moves, ...(r.preflight ?? []).map((l) => `  ${l}`)].join('\n');
+      const shown = r.sample.length;
+      const tail = r.files > shown ? `\n    … 共 ${r.files} 项` : '';
+      return `📦 恢复预览 —— 只是预览，还没动你磁盘上的任何文件\n  归档: ${r.archive}\n  将写入: ${r.files} 项${pre}\n\n  将写入的文件：\n${r.sample.map((s) => `    ${s}`).join('\n')}${tail}`;
+    }
+    // 回执按「发生了什么 / 数据在哪 / 接下来做什么」组织；preflight 里只有
+    // 跨机路径提醒在恢复后仍然成立（🔐📦 两行会被下面的实际结果取代）。
+    const lines = [
+      '✅ 恢复完成',
+      `  已替换: .dsh 全部内容 ← 来自 ${r.archive.split('/').pop()}（${r.files} 项）`,
+    ];
+    if (r.aside) lines.push(`  旧数据没丢: 在 ${r.aside}（确认一切正常后可自行删除）`);
+    if (r.snapshotPath) lines.push(`  保险快照: ${r.snapshotPath.split('/').pop()}（在备份目录内，只保留最近一次）`);
+    for (const p of r.preflight ?? []) {
+      if (p.startsWith('⚠️')) lines.push(`  ${p}`);
+    }
+    if (r.vaultRestored?.length) lines.push(`  凭据: 已从本机 vault 补回 ${r.vaultRestored.length} 个`);
+    if (r.vaultMissing?.length) lines.push(`  ⚠️ 凭据缺失需手动重填: ${r.vaultMissing.join(', ')}`);
+    const installed = r.deps?.installed ?? [];
+    const failed = r.deps?.failed ?? [];
+    if (r.deps?.note) {
+      lines.push(`  插件依赖: 还没装 —— ${r.deps.note}；之后也可用 --sync-deps 补装`);
+    } else if (failed.length) {
+      lines.push(`  ⚠️ 插件依赖安装失败: ${failed.join(', ')}（进对应 profile 目录手动 pnpm install）${installed.length ? `；已装: ${installed.join(', ')}` : ''}`);
+    } else if (installed.length) {
+      lines.push(`  插件依赖: 已装好 ${installed.join(', ')}`);
+    } else if (r.profiles?.length) {
+      lines.push('  插件依赖: 还没装 —— 恢复时带 --sync-deps 重装，或进各 profile 目录手动 pnpm install');
+    }
+    lines.push('  ⏸️ 待办: 重启 dsh，会话和配置才会切换到恢复的内容');
     return lines.join('\n');
   }
 
+  // ---------- 会话日志体检（doctor） ----------
+  //
+  // 布局与格式依据宿主内置的 @deepseek-ai/dsh-session-persistence-jsonl：
+  //   <会话根>/--<项目目录>--/<编码后 id>/session.jsonl.zstd（compression:'none' 时为 .jsonl）
+  // zstd 文件是独立帧的拼接：首帧是带校验和的 SessionHeader 行，其后每个追加批一帧。
+  // Node 内置 zstd 解码器不跨帧续读，因此先按 RFC 8878 走帧字节边界
+  // （魔数/帧头/块序列/校验和），再逐帧解出逻辑行。检测目标正是社区高频的
+  // "corrupt session log"灾难：并发写 seq 撞号、坏帧、尾部截断。
+  const ZSTD_MAGIC = 0xfd2fb528;
+  const SESSION_LOG_NAMES = new Set(['session.jsonl.zstd', 'session.jsonl']);
+  const SCAN_SKIP_DIRS = new Set(['node_modules', '.system', '.git', 'vault']);
+  const SCAN_MAX_FILES = 4000;
+  const SCAN_MAX_DEPTH = 8;
+  // Node 内置 zstd API 要 v22.15 / v23.8 才进 node:zlib；更老运行时没有这个
+  // 导出。必须用命名空间导入 + 运行时探测——具名导入是静态校验的，在缺导出
+  // 的运行时上会让整个插件模块加载失败，比少一个体检功能严重得多。
+  const HAS_NODE_ZSTD = typeof zlib.zstdDecompressSync === 'function';
+
+  /** 截断超长内容用于缺陷描述。 */
+  function snippet(text, max = 60) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+  }
+
+  /**
+   * 按 RFC 8878 结构走查拼接帧的字节边界（不解压）：返回 [start,end] 区间数组；
+   * 结构不合法（截断/未知魔数/保留位/越界块）抛错。skippable 帧一并支持。
+   */
+  function walkZstdFrames(buf) {
+    const frames = [];
+    let off = 0;
+    while (off < buf.length) {
+      if (buf.length - off < 4) throw new Error(`尾部截断（余 ${buf.length - off} 字节不成帧）`);
+      const magic = buf.readUInt32LE(off);
+      if (magic === ZSTD_MAGIC) {
+        let pos = off + 4;
+        if (pos >= buf.length) throw new Error('帧头描述符缺失');
+        const desc = buf[pos++];
+        if (desc & 0x08) throw new Error('帧头保留位置位');
+        const singleSegment = Boolean(desc & 0x20);
+        const checksum = Boolean(desc & 0x04);
+        const dictSize = [0, 1, 2, 4][desc & 0x03];
+        const fcsSize = singleSegment ? [1, 2, 4, 8][desc >> 6] : [0, 2, 4, 8][desc >> 6];
+        if (!singleSegment) pos += 1; // Window_Descriptor
+        pos += dictSize + fcsSize;
+        if (pos > buf.length) throw new Error('帧头越界');
+        let last = false;
+        while (!last) {
+          if (buf.length - pos < 3) throw new Error('块头截断');
+          const bh = buf.readUIntLE(pos, 3);
+          last = Boolean(bh & 0x01);
+          const btype = (bh >> 1) & 0x03;
+          const bsize = bh >> 3;
+          if (btype === 3) throw new Error('保留块类型');
+          // Raw/Compressed 块占 bsize 字节；RLE 块只占 1 字节
+          pos += 3 + (btype === 1 ? 1 : bsize);
+          if (pos > buf.length) throw new Error('块数据越界');
+        }
+        if (checksum) {
+          if (buf.length - pos < 4) throw new Error('帧校验和截断');
+          pos += 4;
+        }
+        frames.push([off, pos]);
+        off = pos;
+      } else if (magic >= 0x184d2a50 && magic <= 0x184d2a5f) {
+        if (buf.length - off < 8) throw new Error('skippable 帧头截断');
+        const size = buf.readUInt32LE(off + 4);
+        const end = off + 8 + size;
+        if (end > buf.length) throw new Error('skippable 帧数据越界');
+        frames.push([off, end]);
+        off = end;
+      } else {
+        throw new Error(`偏移 ${off} 处不是 zstd 帧魔数`);
+      }
+    }
+    return frames;
+  }
+
+  /** 解出 .zstd 会话日志的全部逻辑行；任一帧损坏即抛错（错误含偏移信息）。 */
+  function decodeZstdLog(buf) {
+    const parts = [];
+    let frameNo = 0;
+    for (const [s, e] of walkZstdFrames(buf)) {
+      frameNo += 1;
+      try {
+        parts.push(zlib.zstdDecompressSync(buf.subarray(s, e)));
+      } catch (err) {
+        throw new Error(`第 ${frameNo} 帧解压失败（${e - s}B）：${String(err && err.message ? err.message : err)}`);
+      }
+    }
+    return Buffer.concat(parts).toString('utf8').split('\n').filter((l) => l.length > 0);
+  }
+
+  /**
+   * 校验逻辑行流：首行必须是 SessionHeader（type:"session"），其后每行是一条存储
+   * 记录——裸事件要求 seq 精确连续（events[i].seq === i），packed chunk 行按成员数
+   * 推进游标（语义对齐 dsh-session 的 buildRow/expandRow：成员 k 的 seq = seq0+k，
+   * 成员数 = texts/args 长度）。返回缺陷描述；无缺陷返回 null。
+   */
+  function validateSessionLines(lines) {
+    let header;
+    try {
+      header = JSON.parse(lines[0]);
+    } catch {
+      return `首行不是 JSON（${snippet(String(lines[0]))}）`;
+    }
+    if (!header || typeof header !== 'object' || header.type !== 'session' || typeof header.id !== 'string') {
+      return '首行不是有效的 SessionHeader（缺 type:"session" 或 id）';
+    }
+    let nextSeq = 0;
+    for (let i = 1; i < lines.length; i++) {
+      let rec;
+      try {
+        rec = JSON.parse(lines[i]);
+      } catch {
+        return `第 ${i + 1} 行不是合法 JSON（${snippet(String(lines[i]))}）`;
+      }
+      if (!rec || typeof rec !== 'object') return `第 ${i + 1} 行记录不是对象`;
+      if (rec.type === 'text-chunks' || rec.type === 'reasoning-chunks' || rec.type === 'tool-call-chunks') {
+        const data = rec.data ?? {};
+        const members = Array.isArray(data.texts) ? data.texts.length : Array.isArray(data.args) ? data.args.length : 0;
+        if (!Number.isSafeInteger(rec.seq0) || members <= 0) return `第 ${i + 1} 行 packed 行缺少 seq0 或成员列表`;
+        if (rec.seq0 !== nextSeq) return `第 ${i + 1} 行 packed 行 seq0=${rec.seq0} 与游标 ${nextSeq} 不接续`;
+        nextSeq += members;
+      } else if (typeof rec.seq === 'number') {
+        if (rec.seq !== nextSeq) return `第 ${i + 1} 行 seq=${rec.seq} 撞号/跳号（期望 ${nextSeq}）`;
+        nextSeq = rec.seq + 1;
+      }
+      // 无 seq 且非 packed 的行（未来格式扩展）：放行，交由宿主自身加载判定
+    }
+    return null;
+  }
+
+  /** 有界递归收集会话日志文件（相对 ~/.dsh 路径）；跳过依赖/系统目录。 */
+  async function collectSessionLogs(dir, relPrefix, depth, out) {
+    if (depth > SCAN_MAX_DEPTH || out.length >= SCAN_MAX_FILES) return;
+    let dirents;
+    try {
+      dirents = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return; // 不可读目录静默跳过（权限/竞态不构成体检故障）
+    }
+    for (const d of dirents) {
+      if (out.length >= SCAN_MAX_FILES) return;
+      const rel = relPrefix ? `${relPrefix}/${d.name}` : d.name;
+      if (d.isDirectory()) {
+        if (SCAN_SKIP_DIRS.has(d.name)) continue;
+        await collectSessionLogs(`${dir}/${d.name}`, rel, depth + 1, out);
+      } else if (SESSION_LOG_NAMES.has(d.name)) {
+        out.push({ abs: `${dir}/${d.name}`, rel });
+      }
+    }
+  }
+
+  /**
+   * 单个会话日志体检：非空 → 可解码（zstd 帧走查+逐帧解压，或原样文本）→
+   * SessionHeader + 存储记录流校验。返回 { state:'ok' } 或
+   * { state:'bad', reason }（缺陷描述）或 { state:'skipped', reason }
+   * （无法深度校验：运行时缺 zstd 支持，或文件超过读入上限——不算损坏）。
+   */
+  async function validateSessionFile(f) {
+    try {
+      const info = await fsStat(f.abs);
+      if (info.size === 0) return { state: 'bad', reason: '空文件（0 字节）' };
+      if (f.abs.endsWith('.zstd') && !HAS_NODE_ZSTD) {
+        return { state: 'skipped', reason: `运行时 Node（${process.version}）无内置 zstd 解码，跳过深度校验（需 ≥22.15/23.8）` };
+      }
+      if (info.size > HASH_MAX_BYTES) {
+        return { state: 'skipped', reason: `文件 ${Math.floor(info.size / 1048576)}MB 超过深度校验上限（${Math.floor(HASH_MAX_BYTES / 1048576)}MB），不整读入内存` };
+      }
+      let lines;
+      if (f.abs.endsWith('.zstd')) {
+        lines = decodeZstdLog(await readFile(f.abs));
+      } else {
+        lines = (await readFile(f.abs, 'utf8')).split('\n').filter((l) => l.length > 0);
+      }
+      if (!lines.length) return { state: 'bad', reason: '解出的逻辑行为空' };
+      const defect = validateSessionLines(lines);
+      return defect === null ? { state: 'ok' } : { state: 'bad', reason: defect };
+    } catch (err) {
+      return { state: 'bad', reason: String(err && err.message ? err.message : err) };
+    }
+  }
+
+  function summarizeDoctorScan(r) {
+    if (!r.files.length) return '未找到任何会话日志——可能还没有产生过会话，或布局与预期不同。';
+    const healthy = r.scanned - r.corruptCount - (r.skippedCount ?? 0);
+    let head = `扫描 ${r.scanned} 个会话日志：${healthy} 健康、${r.corruptCount} 损坏`;
+    if (r.skippedCount) head += `、${r.skippedCount} 个未能深度校验（运行时缺 zstd 支持或文件过大）`;
+    if (!r.corruptCount) return `✅ ${head}`;
+    const shown = r.corrupt.slice(0, 15);
+    const more = r.corrupt.length > shown.length ? `\n  …另有 ${r.corrupt.length - shown.length} 个损坏文件` : '';
+    const detail = shown.map((c) => `  ❌ ${c.rel}\n     ${c.reason}`).join('\n');
+    return `${head}\n${detail}${more}\n\n可从备份定点修复：/backup doctor --repair [前缀|latest]（修复前会把损坏文件留档为 *.corrupt-*）`;
+  }
+
+  /** 只读扫描 ~/.dsh 下全部会话日志；不写任何文件。 */
+  async function runDoctorScan(signal) {
+    const { dshHome } = paths();
+    if (signal?.aborted) throw new Error('操作已取消');
+    const found = [];
+    await collectSessionLogs(dshHome, '', 0, found);
+    const files = [];
+    for (const f of found) {
+      if (signal?.aborted) throw new Error('操作已取消');
+      const verdict = await validateSessionFile(f);
+      files.push({ rel: f.rel, ok: verdict.state === 'ok', skipped: verdict.state === 'skipped', reason: verdict.reason });
+    }
+    const corrupt = files.filter((x) => !x.ok && !x.skipped);
+    const skippedCount = files.filter((x) => x.skipped).length;
+    return { scanned: files.length, files, corrupt, corruptCount: corrupt.length, skippedCount };
+  }
+
+  /**
+   * 定点修复：扫描出损坏的会话日志后，从指定归档（缺省最新一份，须通过
+   * sha256 校验）里提取同名条目覆盖。只动损坏的文件本身——不做整库 aside
+   * 切换；每个被覆盖的损坏文件先就地留档为 `<原名>.corrupt-<时间戳>`。
+   * 归档里没有对应条目的文件列入 unrecoverable（提示改用全量恢复）。
+   */
+  async function runDoctorRepair(selector, signal) {
+    const { home, dshHome, root } = paths();
+    const scan = await runDoctorScan(signal);
+    if (!scan.corruptCount) return { repaired: [], unrecoverable: [], stillBad: [], scanned: scan.scanned, summary: summarizeDoctorScan(scan) };
+
+    const picked = await pickArchive(selector || 'latest');
+    const v = await verifyOne(picked.name, home, signal);
+    if (!v.ok) throw new Error(`归档校验未通过（${v.note}），定点修复已中止`);
+    const base = dshHome.split('/').pop();
+    const parent = dshHome.slice(0, -(base.length + 1)) || '/';
+    const entries = await safeArchiveEntries(picked.name, signal);
+    const entrySet = new Set(entries);
+
+    const targets = [];
+    const unrecoverable = [];
+    for (const c of scan.corrupt) {
+      const entry = `${base}/${c.rel}`;
+      if (entrySet.has(entry)) targets.push({ ...c, entry });
+      else unrecoverable.push(c.rel);
+    }
+
+    // 覆盖前留档损坏现场：文件名即证据链（seq 撞号样本对排查宿主 bug 有价值）
+    const stamp = stampNow();
+    const kept = [];
+    for (const t of targets) {
+      const keep = `${dshHome}/${t.rel}.corrupt-${stamp}`;
+      await mkdir(dirname(keep), { recursive: true });
+      await copyFile(`${dshHome}/${t.rel}`, keep);
+      kept.push(keep);
+    }
+
+    // 提取可能半途失败、只替换了一部分目标——对齐恢复流程 #28 的回滚哲学：
+    // 用留档副本尽力还原每个目标的修复前状态；连还原都失败时把留档路径
+    // 交代清楚，绝不静默停在最糟的中间态。
+    try {
+      const tar = await ctx.subprocess.resolveExecutable('tar');
+      await spawnRun([tar, '-xzf', picked.name, '-C', parent, ...targets.map((t) => t.entry)], root, signal);
+    } catch (err) {
+      const reason = err && err.message ? err.message : String(err);
+      const restored = new Set();
+      for (let i = 0; i < targets.length; i++) {
+        try {
+          await copyFile(kept[i], `${dshHome}/${targets[i].rel}`);
+          restored.add(targets[i].rel);
+        } catch { /* 单个还原失败：落入下方如实报告 */ }
+      }
+      if (restored.size === targets.length) {
+        throw new Error(`定点修复失败（${reason}）。已从留档还原全部损坏现场，数据保持修复前状态；排查磁盘空间/权限后可重试`);
+      }
+      const missing = targets.filter((t) => !restored.has(t.rel)).map((t) => t.rel);
+      throw new Error(`定点修复失败（${reason}），且部分现场未自动还原: ${missing.join(', ')}。对应的 *.corrupt-${stamp} 留档仍在原目录旁，手工拷回原位即可`);
+    }
+
+    // 修完复检：从归档解出的副本必须健康，否则如实报告（skipped 不算失败——
+    // 缺 zstd 支持的运行时根本检不出 zstd 文件损坏，能进 targets 的都是可校验的）
+    const stillBad = [];
+    for (const t of targets) {
+      const verdict = await validateSessionFile({ abs: `${dshHome}/${t.rel}`, rel: t.rel });
+      if (verdict.state === 'bad') stillBad.push(`${t.rel}（${verdict.reason}）`);
+    }
+
+    const lines = [`🩹 定点修复完成（来源: ${picked.name}）`];
+    if (targets.length) lines.push(`  已恢复 ${targets.length} 个文件${stillBad.length ? '' : '，复检全部健康'}`);
+    for (const k of kept) lines.push(`  损坏现场已留档: ${k}`);
+    if (unrecoverable.length) lines.push(`  ⚠️ 归档中无对应副本、无法定点修复: ${unrecoverable.join(', ')}`);
+    if (stillBad.length) lines.push(`  ❌ 修复后复检仍异常: ${stillBad.join('; ')}`);
+    lines.push('  请重启 dsh 后确认会话历史加载正常。');
+    return { repaired: targets.map((t) => t.rel), unrecoverable, stillBad, scanned: scan.scanned, summary: lines.join('\n') };
+  }
+
   // ---------- 自动备份与 GitHub 同步状态（落盘，重启续跑） ----------
   let autoDispose = null;
   let autoHours = 0;
   let lastAuto = null;
   let lastAutoAt = null;
   let githubState = { repo: null, lastPush: null, lastError: null };
+  // 上次见到的宿主列车（detectHostTrain 代理值）：null=尚未记录（首启动只记
+  // 录不拍快照），非 null 且变化 → 升/降级 → 自动拍 dsh-pre-upgrade- 快照。
+  let lastTrain = null;
+
+  /**
+   * 等待 settings 用户层加载完成（describe 出现 revision）。启动钩子若在
+   * settings 装配完成前运行，resolvedConfig 会拿到 base 默认值——升级快照
+   * 就会落进默认目录而不是用户配置的目的地（e2e 实测的分裂写场景）。
+   * 注意两段等待：先等 services 异步装配出 settingsService（ctx.inject 的
+   * 回调在宿主组合期才触发），再等用户层装载出 revision。全程无 settings
+   * 的 profile（headless 等）等满上限后按默认目的地继续——钩子是异步的，
+   * 不阻塞装配。
+   */
+  async function waitForSettingsReady(capMs = 10000) {
+    const t0 = Date.now();
+    while (!settingsService && Date.now() - t0 < capMs) {
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    while (settingsService && Date.now() - t0 < capMs) {
+      try {
+        const desc = describeOwn(settingsService, NS);
+        if (desc && typeof desc.revision === 'number') return;
+      } catch { /* 未就绪，继续等 */ }
+      await new Promise((r) => setTimeout(r, 200));
+    }
+  }
 
   /** 自动备份的保留份数：config.keep 支配（未配置时 <24h 3 份、否则 7 份）。 */
   function autoKeep() {
@@ -1207,9 +1828,23 @@ export function apply(ctx, pluginConfig) {
     return Number.isFinite(k) && k > 0 ? Math.floor(k) : (autoHours >= 24 ? 7 : 3);
   }
 
+  // 启动钩子与备份链路可能并发保存 auto.json（多实例/多 profile 亦然）——
+  // 并发 writeFile 同一路径会撕裂（实测产出 A+B 拼接体）。走"临时文件 +
+  // 原子改名"：读者要么见到旧完整文件、要么见到新完整文件，绝不撕裂；
+  // 与宿主 settings 持久化的 writeFileAtomic 同一模式。
   async function saveAutoState() {
     const { root } = paths();
-    await writeOwned(`${root}/auto.json`, `${JSON.stringify({ hours: autoHours, lastAutoAt, github: githubState })}\n`);
+    const target = `${root}/auto.json`;
+    // 临时名用 UUID：时间戳+实例内序号在"多实例同毫秒启动"时仍会撞名
+    // （先到者 rename 走，后到者 ENOENT），UUID 跨实例唯一
+    const tmp = `${target}.${randomUUID()}.tmp`;
+    try {
+      await writeOwned(tmp, `${JSON.stringify({ hours: autoHours, lastAutoAt, github: githubState, lastTrain })}\n`);
+      await rename(tmp, target);
+    } catch (err) {
+      await rm(tmp, { force: true }).catch(() => {});
+      throw err;
+    }
   }
 
   async function loadAutoState() {
@@ -1229,6 +1864,7 @@ export function apply(ctx, pluginConfig) {
       // 故一律视为非法 → null，从当前时间起算 catch-up。
       const lastTs = typeof parsed?.lastAutoAt === 'string' ? Date.parse(parsed.lastAutoAt) : NaN;
       lastAutoAt = Number.isNaN(lastTs) || lastTs > Date.now() ? null : parsed.lastAutoAt;
+      lastTrain = typeof parsed?.lastTrain === 'string' && parsed.lastTrain ? parsed.lastTrain : null;
       return Number.isFinite(h) && h >= 1 && h <= 720 ? Math.floor(h) : 0;
     } catch (err) {
       console.warn(`[dsh-backup] auto.json 无法读取，自动备份计划已重置: ${String(err && err.message ? err.message : err)}`);
@@ -1289,7 +1925,7 @@ export function apply(ctx, pluginConfig) {
   // ---------- /backup 命令 ----------
   ctx.commands.register({
     name: 'backup',
-    description: '备份/恢复 DSH 数据；子命令: list | verify [前缀|all] | restore <前缀|latest> [--dry-run] [--sync-deps] | auto [N小时|off] | github status|sync|pull|repo | [--keep N]',
+    description: '备份/恢复 DSH 数据；子命令: list | verify [前缀|all] | restore <前缀|latest> [--dry-run] [--sync-deps] | doctor [--repair <前缀|latest>] | auto [N小时|off] | github status|sync|pull|repo | [--keep N]',
     handler: async (invocation) => {
       const input = invocation.rawInput.trim();
       try {
@@ -1301,9 +1937,13 @@ export function apply(ctx, pluginConfig) {
           const all = await listBackups();
           const total = all.reduce((s, b) => s + (b.size || 0), 0);
           const lines = all.map((b) => `  ${b.name}${b.size !== undefined ? `  ${(b.size / 1048576).toFixed(1)}MB` : ''}`);
+          // 内部快照分区展示：升级前（最多 2 份）/ 恢复前（最近 1 份），可按前缀选用
+          const snaps = await listSnapshotNames('dsh-pre-');
+          const snapLines = snaps.map((n) => `  ${n}${n.startsWith('dsh-pre-upgrade-') ? '  （升级前快照）' : '  （恢复前快照）'}`);
+          const snapText = snapLines.length ? `\n\n内部快照（可 restore 前缀选用，不占保留配额）:\n${snapLines.join('\n')}` : '';
           const text = all.length
-            ? `已有备份 (${all.length} 份，共 ${(total / 1048576).toFixed(1)}MB):\n${lines.join('\n')}\n\n${autoSummary()}`
-            : `暂无备份。输入 /backup 执行首次备份。\n\n${autoSummary()}`;
+            ? `已有备份 (${all.length} 份，共 ${(total / 1048576).toFixed(1)}MB):\n${lines.join('\n')}${snapText}\n\n${autoSummary()}`
+            : `暂无备份。输入 /backup 执行首次备份。${snapText}\n\n${autoSummary()}`;
           return { kind: 'success', text };
         }
 
@@ -1329,6 +1969,18 @@ export function apply(ctx, pluginConfig) {
           return { kind: 'success', text: summarizeRestore(r) };
         }
 
+        if (head === 'doctor') {
+          const repairIdx = parts.indexOf('--repair');
+          if (repairIdx < 0) {
+            const r = await runDoctorScan(invocation.signal);
+            return { kind: r.corruptCount ? 'error' : 'success', text: summarizeDoctorScan(r) };
+          }
+          const selArg = parts[repairIdx + 1];
+          const sel = selArg && !selArg.startsWith('--') ? selArg : 'latest';
+          const r = await runDoctorRepair(sel, invocation.signal);
+          return { kind: 'success', text: r.summary };
+        }
+
         if (head === 'github') {
           const arg = parts[1] || 'status';
           if (arg === 'repo') {
@@ -1415,7 +2067,7 @@ export function apply(ctx, pluginConfig) {
         const r = await doBackup(keep, invocation.signal);
         return {
           kind: 'success',
-          text: `✅ 备份完成\n  文件: ${r.path}\n  校验和: ${r.sha.slice(0, 16)}…\n  轮换: 删除 ${r.stale} 份旧备份（保留 ${r.keep} 份）\n  ${autoSummary()}`,
+          text: `✅ 备份完成\n  文件: ${r.path}\n  校验和: ${r.sha.slice(0, 16)}…\n  轮换: 删除 ${r.stale} 份旧备份（保留 ${r.keep} 份）${quarantineNote(r)}\n  ${autoSummary()}`,
         };
       } catch (err) {
         return { kind: 'error', text: `备份失败: ${String(err && err.message ? err.message : err)}` };
@@ -1426,14 +2078,15 @@ export function apply(ctx, pluginConfig) {
   // ---------- backup_dsh 模型工具 ----------
   ctx.tools.register(defineTool({
     name: 'backup_dsh',
-    description: '备份、校验或恢复 DSH 用户数据（~/.dsh 的会话、配置、技能）。凭据文件默认脱敏：不进归档、不进 GitHub 同步，明文只存本机 vault，恢复时自动还原。mode=backup 立即备份（keep 指定保留份数）；mode=list 列出备份；mode=verify 校验完整性（selector=前缀或 all，缺省最新一份）；mode=restore 恢复（selector=前缀或 latest，dryRun 仅预览，syncDeps 恢复后重装 profile 依赖；恢复前自动校验并快照当前数据）；mode=auto 设置定时备份（hours 间隔小时数，0=关闭，缺省查询）。',
+    description: '备份、校验、恢复或体检 DSH 用户数据（~/.dsh 的会话、配置、技能）。凭据文件默认脱敏：不进归档、不进 GitHub 同步，明文只存本机 vault，恢复时自动还原。mode=backup 立即备份（keep 指定保留份数）；mode=list 列出备份；mode=verify 校验完整性（selector=前缀或 all，缺省最新一份）；mode=restore 恢复（selector=前缀或 latest，syncDeps 恢复后重装 profile 依赖；恢复前自动校验并快照当前数据，解压失败自动还原；真实恢复前必须先 dryRun=true 预览并向用户展示确认）；mode=auto 设置定时备份（hours 间隔小时数，0=关闭，缺省查询）；mode=doctor 会话日志体检——检测损坏的会话历史（seq 撞号/坏帧/截断），repair=true 时从 selector 归档定点修复',
     parameters: {
-      mode: { type: 'string', required: true, enum: ['backup', 'list', 'verify', 'restore', 'auto'], description: 'backup=执行备份，list=列出备份，verify=校验完整性，restore=恢复，auto=定时备份' },
+      mode: { type: 'string', required: true, enum: ['backup', 'list', 'verify', 'restore', 'auto', 'doctor'], description: 'backup=执行备份，list=列出备份，verify=校验完整性，restore=恢复，auto=定时备份，doctor=会话日志体检' },
       keep: { type: 'number', description: '保留的备份份数（mode=backup，默认 7）' },
       hours: { type: 'number', description: '定时备份间隔小时数（mode=auto；0=关闭；缺省=查询状态）' },
-      selector: { type: 'string', description: '备份选择器（mode=verify/restore）：归档名前缀、latest 或 all' },
-      dryRun: { type: 'boolean', description: 'mode=restore 时仅预览恢复内容，不写入' },
+      selector: { type: 'string', description: '备份选择器（mode=verify/restore/doctor）：归档名前缀、latest 或 all' },
+      dryRun: { type: 'boolean', description: 'mode=restore 时仅预览（不写入）；真实恢复前必须先预览并向用户展示确认' },
       syncDeps: { type: 'boolean', description: 'mode=restore 时恢复后对各 profile 执行 pnpm install 重装插件依赖' },
+      repair: { type: 'boolean', description: 'mode=doctor 时从 selector 归档定点修复损坏的会话日志（缺省仅扫描）' },
     },
     output: {
       schema: { type: 'object', additionalProperties: true },
@@ -1465,6 +2118,21 @@ export function apply(ctx, pluginConfig) {
           const r = await restoreArchive(selector || 'latest', Boolean(args && args.dryRun), signal);
           return { ok: true, path: r.archive, summary: summarizeRestore(r) };
         }
+        if (mode === 'doctor') {
+          if (args && args.repair) {
+            const r = await runDoctorRepair(selector || 'latest', signal);
+            return { ok: r.stillBad.length === 0 && r.unrecoverable.length === 0, summary: r.summary, repaired: r.repaired, unrecoverable: r.unrecoverable, stillBad: r.stillBad };
+          }
+          const r = await runDoctorScan(signal);
+          return {
+            ok: r.corruptCount === 0,
+            scanned: r.scanned,
+            corruptCount: r.corruptCount,
+            skippedCount: r.skippedCount,
+            summary: summarizeDoctorScan(r),
+            corrupt: r.corrupt.map((c) => ({ path: c.rel, reason: c.reason })),
+          };
+        }
         if (mode === 'auto') {
           const h = args && args.hours !== undefined ? args.hours : null;
           if (h === null) return { ok: true, summary: autoSummary() };
@@ -1477,7 +2145,7 @@ export function apply(ctx, pluginConfig) {
           return { ok: true, summary: `自动备份已开启：每 ${h} 小时一次（已持久化）。\n${autoSummary()}` };
         }
         const r = await doBackup(args && args.keep ? args.keep : undefined, signal);
-        return { ok: true, path: r.path, sha: r.sha, summary: `备份完成: ${r.path}\nsha256: ${r.sha}\n轮换删除 ${r.stale} 份（保留 ${r.keep} 份）` };
+        return { ok: true, path: r.path, sha: r.sha, summary: `备份完成: ${r.path}\nsha256: ${r.sha}\n轮换删除 ${r.stale} 份（保留 ${r.keep} 份）${quarantineNote(r)}` };
       } catch (err) {
         return { ok: false, summary: `操作失败: ${String(err && err.message ? err.message : err)}` };
       }
@@ -1502,7 +2170,7 @@ export function apply(ctx, pluginConfig) {
       const r = await doBackup(keep, signal);
       return {
         ok: true,
-        summary: `备份完成: ${r.path}\nsha256: ${r.sha}\n轮换删除 ${r.stale} 份（保留 ${r.keep} 份）`,
+        summary: `备份完成: ${r.path}\nsha256: ${r.sha}\n轮换删除 ${r.stale} 份（保留 ${r.keep} 份）${quarantineNote(r)}`,
         path: r.path,
         sha: r.sha,
         stale: r.stale,
@@ -1528,7 +2196,7 @@ export function apply(ctx, pluginConfig) {
       try {
         const r = await restoreArchive(selector || 'latest', Boolean(dryRun), signal);
         if (r.dryRun) {
-          return { ok: true, dryRun: true, archive: r.archive, files: r.files, sample: r.sample, preflight: r.preflight ?? [], summary: summarizeRestore(r) };
+          return { ok: true, dryRun: true, archive: r.archive, files: r.files, sample: r.sample, preflight: r.preflight ?? [], targetExists: r.targetExists, summary: summarizeRestore(r) };
         }
         return {
           ok: true,
@@ -1645,6 +2313,34 @@ export function apply(ctx, pluginConfig) {
       }
       return { ok: true, repo: clean, summary: `GitHub 同步仓库已设为: ${clean}` };
     },
+    doctorScan: async (signal) => {
+      try {
+        const r = await runDoctorScan(signal);
+        return {
+          ok: r.corruptCount === 0,
+          scanned: r.scanned,
+          corruptCount: r.corruptCount,
+          summary: summarizeDoctorScan(r),
+          corrupt: r.corrupt.map((c) => ({ path: c.rel, reason: c.reason })),
+        };
+      } catch (err) {
+        return { ok: false, summary: String(err && err.message ? err.message : err), corrupt: [] };
+      }
+    },
+    doctorRepair: async (selector, signal) => {
+      try {
+        const r = await runDoctorRepair(typeof selector === 'string' && selector ? selector : undefined, signal);
+        return {
+          ok: r.stillBad.length === 0 && r.unrecoverable.length === 0,
+          summary: r.summary,
+          repaired: r.repaired,
+          unrecoverable: r.unrecoverable,
+          stillBad: r.stillBad,
+        };
+      } catch (err) {
+        return { ok: false, summary: String(err && err.message ? err.message : err), repaired: [], unrecoverable: [], stillBad: [] };
+      }
+    },
   };
 
   // 仅在装配了 Typert registry 的 profile（Web）里挂载面板服务；其余 profile 安静跳过。
@@ -1730,11 +2426,34 @@ export function apply(ctx, pluginConfig) {
   });
 
   // 启动时恢复持久化的定时备份计划（不阻塞插件装配）；错过则 delay=0 立即补跑。
+  // 同处做升级前快照：宿主列车变化（升/降级）先拍一份 dsh-pre-upgrade- 安全网
+  // 再继续——命中社区"想试新版怕搞坏"的最大恐惧。首见列车只记录不拍。
   void (async () => {
+    await waitForSettingsReady();
     const h = await loadAutoState();
     if (h > 0 && !autoDispose) {
       autoHours = h;
       scheduleAuto();
     }
+    const train = detectHostTrain();
+    if (!train) return;
+    if (lastTrain === null) {
+      lastTrain = train;
+      try {
+        await saveAutoState();
+      } catch { /* 记录失败不致命：下次启动重新记录 */ }
+      return;
+    }
+    if (lastTrain === train) return;
+    const oldTrain = lastTrain;
+    try {
+      const snap = await doBackup(undefined, undefined, { namePrefix: 'dsh-pre-upgrade-' });
+      await prunePrefixedSnapshots('dsh-pre-upgrade-', 2, snap.name);
+      lastTrain = train;
+      await saveAutoState();
+      console.log(`[dsh-backup] 宿主列车变化（${oldTrain} → ${train}），已自动拍升级前快照: ${snap.name}${snap.quarantined?.length ? `（${snap.quarantined.length} 个损坏会话文件未入档）` : ''}`);
+    } catch (err) {
+      console.warn(`[dsh-backup] 升级前快照失败（不影响运行，下次启动会重试）: ${String(err && err.message ? err.message : err)}`);
+    }
   })();
 }