@xiaoyuyu6420/dsh-backup 0.9.1 → 0.11.0

package/lib/index.js

@@ -78,6 +78,55 @@ const SENSITIVE_DEFAULTS = ['.credentials.yaml', '.env', 'qq-bridge/config.json'
 /** 备份目录下保存明文敏感文件的子目录（随备份刷新为最新一份的副本）。 */
 const VAULT_DIR = 'vault';
 
+/**
+ * 分类型备份的内容类型表（相对 ~/.dsh 根的 POSIX 路径）。
+ * 每类映射一组路径：文件用具体名、目录用目录名；mcp 用 glob（承载组合
+ * 文件，连带其他 cordis 行——MCP 无独立目录，声明嵌在 cordis 组合层里）。
+ * credentials 类反转脱敏：明文进归档（跳过 redactExcludeFlags），但这类
+ * 归档在 githubSync 里被识别并跳过，永不上一线。旧归档（meta.types 缺省）
+ * 视为全量，与分类型归档（dsh-t- 前缀）独立轮换、不进全量列表。
+ */
+const BACKUP_TYPES = Object.freeze({
+  credentials: { label: '凭据/api key', paths: ['.credentials.yaml', '.env', 'qq-bridge/config.json'], credentials: true },
+  mcp: { label: 'MCP 配置', paths: ['cordis.patch.yml', 'profiles/*/cordis.patch.yml', 'profiles/*/cordis.yml'] },
+  skills: { label: '技能', paths: ['skills'] },
+  sessions: { label: '会话', paths: ['sessions'] },
+  settings: { label: '设置', paths: ['settings.yaml'] },
+  profiles: { label: '插件 profiles', paths: ['profiles'] },
+});
+const BACKUP_TYPE_KEYS = Object.freeze(Object.keys(BACKUP_TYPES));
+/** 分类型归档前缀（与全量 dsh- 区分：独立轮换、不进全量列表、旧版插件不可见不误删）。 */
+const TYPED_PREFIX = 'dsh-t-';
+
+/**
+ * 按类型 globs 匹配归档内条目（restore 侧）：把 BACKUP_TYPES 的相对路径转成
+ * 对归档条目（${base}/ 前缀）的匹配——文件精确匹配、目录前缀匹配、含 * 的
+ * glob 转正则。返回命中的归档条目数组（去重）。与备份侧 typeTargets（文件
+ * 系统展开）对称：备份展开实际路径，恢复匹配归档条目。
+ */
+function typeEntries(types, entries, base) {
+  const out = [];
+  const seen = new Set();
+  const esc = (s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  for (const key of types) {
+    const spec = BACKUP_TYPES[key];
+    if (!spec) continue;
+    for (const rel of spec.paths) {
+      if (rel.includes('*')) {
+        const re = new RegExp(`^${esc(base)}/${esc(rel).replace(/\*/g, '[^/]+')}$`);
+        for (const e of entries) if (re.test(e) && !seen.has(e)) { seen.add(e); out.push(e); }
+      } else {
+        const fileEntry = `${base}/${rel}`;
+        const dirPrefix = `${base}/${rel}/`;
+        for (const e of entries) {
+          if ((e === fileEntry || e.startsWith(dirPrefix)) && !seen.has(e)) { seen.add(e); out.push(e); }
+        }
+      }
+    }
+  }
+  return out;
+}
+
 /** 随备份落盘的救援说明：DSH 起不来时，用户打开备份目录第一眼能看到的东西。 */
 const RESCUE_TXT = `DSH 出问题时的自救通道（不依赖 DSH 能否启动）
 ====================================================
@@ -99,9 +148,12 @@ const RESCUE_TXT = `DSH 出问题时的自救通道（不依赖 DSH 能否启动
 
 /** 双击启动器：起救援服务并自动开浏览器。按当前平台生成，避免目录里躺三个系统的文件。 */
 const RESCUE_LAUNCHERS = Object.freeze({
-  darwin: ['点我恢复.command', '#!/bin/sh\ncd "$(dirname "$0")" || exit 1\nexec node rescue.mjs serve --open\n'],
+  // 双击 .command 时 GUI 的 PATH 只有 /usr/bin:/bin:...，nvm/Homebrew 装的
+  // node 找不到——直接 exec 会静默失败且窗口即关（UX 审查 P1-3）。先依次
+  // 探测常见安装位置；全落空时给人话指引并保持窗口不关。
+  darwin: ['点我恢复.command', '#!/bin/sh\ncd "$(dirname "$0")" || exit 1\nNODE_BIN="$(command -v node)"\nif [ -z "$NODE_BIN" ]; then\n  for c in /opt/homebrew/bin/node /usr/local/bin/node "$HOME"/.nvm/versions/node/*/bin/node; do\n    if [ -x "$c" ]; then NODE_BIN="$c"; break; fi\n  done\nfi\nif [ -z "$NODE_BIN" ]; then\n  echo "没有找到 node。请先安装 Node.js（https://nodejs.org），然后重新双击本文件。"\n  echo "也可以在终端进入本目录手动执行: node rescue.mjs serve --open"\n  printf "\\n按回车键关闭窗口…"\n  read _\n  exit 1\nfi\nexec "$NODE_BIN" 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'],
+  linux: ['点我恢复.sh', '#!/bin/sh\ncd "$(dirname "$0")" || exit 1\nNODE_BIN="$(command -v node)"\nif [ -z "$NODE_BIN" ]; then\n  for c in /usr/local/bin/node /opt/node/bin/node "$HOME"/.nvm/versions/node/*/bin/node "$HOME"/.local/bin/node; do\n    if [ -x "$c" ]; then NODE_BIN="$c"; break; fi\n  done\nfi\nif [ -z "$NODE_BIN" ]; then\n  echo "没有找到 node。请先安装 Node.js，然后在终端进入本目录执行: node rescue.mjs serve --open"\n  exit 1\nfi\nexec "$NODE_BIN" rescue.mjs serve --open\n'],
 });
 
 /**
@@ -109,7 +161,8 @@ const RESCUE_LAUNCHERS = Object.freeze({
  * 纯函数、模块级：轮换分层与测试共用。
  */
 function archiveDay(name) {
-  const m = /^dsh-(\d{4})(\d{2})(\d{2})-\d{6}\d{3}\.tar\.gz$/.exec(name);
+  // dsh-t-（分类型归档）与 dsh-（全量）共用同一时间戳格式；前缀可选 t-。
+  const m = /^dsh-(?:t-)?(\d{4})(\d{2})(\d{2})-\d{6}\d{3}\.tar\.gz$/.exec(name);
   return m ? `${m[1]}-${m[2]}-${m[3]}` : null;
 }
 
@@ -329,9 +382,9 @@ function panelDescriptor(method, parameters, cancellation) {
 
 const PANEL_INVOCATIONS = Object.freeze([
   panelDescriptor('status', []),
-  panelDescriptor('backup', ['keep'], true),
+  panelDescriptor('backup', ['keep', 'types'], true),
   panelDescriptor('verify', ['selector'], true),
-  panelDescriptor('restore', ['selector', 'dryRun'], true),
+  panelDescriptor('restore', ['selector', 'dryRun', 'types', 'syncDeps'], true),
   panelDescriptor('setAuto', ['hours']),
   panelDescriptor('githubStatus', []),
   panelDescriptor('githubSyncNow', [], true),
@@ -359,9 +412,9 @@ class BackupPanelService extends TypertRemoteService {
     return this.ops.status();
   }
 
-  /** 立即备份。 */
-  backup(keep, signal) {
-    return this.ops.backup(keep, signal);
+  /** 立即备份（types 非空时分类型子集备份）。 */
+  backup(keep, types, signal) {
+    return this.ops.backup(keep, types, signal);
   }
 
   /** 校验（selector=前缀|all|latest）。 */
@@ -369,9 +422,9 @@ class BackupPanelService extends TypertRemoteService {
     return this.ops.verify(selector, signal);
   }
 
-  /** 恢复（dryRun 仅预览）。 */
-  restore(selector, dryRun, signal) {
-    return this.ops.restore(selector, dryRun, signal);
+  /** 恢复（dryRun 仅预览；types 非空时分类型 merge 恢复；syncDeps 恢复后重装 profile 依赖）。 */
+  restore(selector, dryRun, types, syncDeps, signal) {
+    return this.ops.restore(selector, dryRun, types, syncDeps, signal);
   }
 
   /** 设置自动备份（0=关闭）。 */
@@ -529,6 +582,34 @@ export function apply(ctx, pluginConfig) {
     return { out, err };
   }
 
+  /**
+   * 错误翻译层：把底层错误（fs 错误码、tar/git 的英文 stderr、JS 异常）映射
+   * 成「人话原因 + 折叠的技术细节」。所有面向用户的 catch 出口统一经此——
+   * 直接拼 err.message 会把 ENOENT/tar stderr 甩给最慌的用户（UX 审查
+   * P1-4：19 处直拼的模式级问题），在这里一处收口。
+   */
+  function friendlyReason(err) {
+    const raw = String(err && err.message ? err.message : err);
+    // 内层（如 restoreArchive 的解压失败分支）已翻译过——不重复包一层
+    if (raw.includes('技术细节: ')) return raw;
+    if (/gzip decompression failed|not in gzip format|invalid distance|unexpected end of file|Canto open|damaged|failed to open|cannot open/i.test(raw)) {
+      return `归档内容损坏或不是有效的压缩包（技术细节: ${snippet(raw, 160)}）`;
+    }
+    if (/\bENOENT\b/.test(raw)) {
+      return `需要的文件不存在——可能已被轮换清理，或路径变动（技术细节: ${snippet(raw, 160)}）`;
+    }
+    if (/\b(ENOSPC|EDQUOT)\b/.test(raw)) {
+      return `磁盘空间不足，请释放空间后重试（技术细节: ${snippet(raw, 160)}）`;
+    }
+    if (/\b(EACCES|EPERM|EROFS)\b/.test(raw)) {
+      return `权限不足，无法读写目标位置（技术细节: ${snippet(raw, 160)}）`;
+    }
+    if (/Cannot read propert|is not a function|undefined is not/i.test(raw)) {
+      return `程序内部错误，请带着下面的细节反馈给作者（技术细节: ${snippet(raw, 160)}）`;
+    }
+    return raw;
+  }
+
   function paths() {
     const env = ctx.get('launchEnvironment');
     // Windows 上 launchEnvironment 无 HOME 时退回 USERPROFILE。
@@ -679,13 +760,9 @@ export function apply(ctx, pluginConfig) {
     await rename(`${dir}/${srcName}`, `${dir}/${dstName}`);
   }
 
-  /**
-   * 清理旧的恢复前快照（dsh-pre-restore-* 归档 + 边车），仅保留 keepName
-   * 这一份。恢复是低频操作，快照又被 listBackups 排除、用户不可见，故每
-   * 次恢复后清掉前一次的快照防隐藏累积（aside 目录仍由用户自行管理）。
-   */
-  /** 清理内部快照（pre-restore / pre-upgrade 共用）：只保留最近 keepN 份。 */
-  async function prunePrefixedSnapshots(prefix, keepN, keepName, signal) {
+  /** 清理内部快照（pre-restore / pre-upgrade 共用）：只保留最近 keepN 份；protect 里的归档即使落在窗口外也强制保留。 */
+  async function prunePrefixedSnapshots(prefix, keepN, keepNames, signal) {
+    const protect = Array.isArray(keepNames) ? keepNames : [keepNames];
     const { root } = paths();
     let dirents;
     try {
@@ -700,13 +777,18 @@ export function apply(ctx, pluginConfig) {
       .reverse();
     // 归档名排序即时间序；边车跟宿主同名排序紧邻其后，按"每份归档一组"数份数
     const archiveCount = names.filter((n) => n.endsWith('.tar.gz'));
-    const staleArchives = archiveCount.slice(keepN).filter((n) => n !== keepName);
+    const staleArchives = archiveCount.slice(keepN).filter((n) => !protect.includes(n));
     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);
+  /**
+   * 恢复流程收尾的快照清理。keepNames 必须同时含新拍的快照与本次恢复的
+   * 目标归档——目标本身可能就是一份 dsh-pre-restore-* 快照，只保护新快照
+   * 会把正在恢复的归档清掉，解压必然 ENOENT（UX 审查实测的自毁死路）。
+   */
+  async function prunePreRestoreSnapshots(keepNames, signal) {
+    await prunePrefixedSnapshots('dsh-pre-restore-', 1, keepNames, signal);
   }
 
   /** 归档伴生边车集：轮换、删除与 GitHub 同步对同一归档统一处理的文件列表。 */
@@ -731,10 +813,15 @@ export function apply(ctx, pluginConfig) {
       // 内部快照（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;
+      if (!d.name.startsWith('dsh-') || SNAPSHOT_PREFIXES.some((p) => d.name.startsWith(p)) || d.name.startsWith(TYPED_PREFIX) || !d.name.endsWith('.tar.gz')) continue;
       let size;
       try {
-        size = (await fsStat(`${root}/${d.name}`)).size;
+        const st = await fsStat(`${root}/${d.name}`);
+        // 正在写入的归档（tar 直写最终文件名，写完前 size=0）先不进列表——
+        // 用户刷新撞见 0 字节条目会以为备份坏了（UX 审查 P1-7）；写入失败
+        // 残留的 0 字节文件 60 秒后仍会显示出来，不会被永久隐藏。
+        if (st.size === 0 && Date.now() - st.mtimeMs < 60_000) continue;
+        size = st.size;
       } catch {
         // 归档在列表与 stat 之间被删除（轮换/删除竞态）——大小显示为未知而非报错
         size = undefined;
@@ -787,13 +874,90 @@ export function apply(ctx, pluginConfig) {
     return createHash('sha256').update(bytes).digest('hex');
   }
 
+  async function existsStat(p) {
+    try { await fsStat(p); return true; } catch { return false; }
+  }
+
+  /**
+   * 递归展开相对 ~/.dsh 的星号通配（spawnRun 不经 shell，tar 位置参数需字面
+   * 路径）。只返回实际存在的路径。mcp 类 profiles 下各 profile 的
+   * cordis.yml / cordis.patch.yml 靠它展开。
+   */
+  async function expandGlob(rel, root) {
+    const parts = rel.split('/');
+    const out = [];
+    async function walk(i, dir, acc) {
+      if (i >= parts.length) { if (acc) out.push(acc); return; }
+      const seg = parts[i];
+      if (seg === '*') {
+        let dirents;
+        try { dirents = await readdir(dir, { withFileTypes: true }); } catch { return; }
+        for (const d of dirents) {
+          if (!d.isDirectory()) continue;
+          await walk(i + 1, `${dir}/${d.name}`, acc ? `${acc}/${d.name}` : d.name);
+        }
+      } else {
+        const next = `${dir}/${seg}`;
+        if (!(await existsStat(next))) return;
+        await walk(i + 1, next, acc ? `${acc}/${seg}` : seg);
+      }
+    }
+    await walk(0, root, '');
+    return out;
+  }
+
+  /**
+   * 把分类型名展开成归档内相对路径（${base}/ 前缀），预检存在性、展开 glob。
+   * 返回 { targets, hasCredentials }：targets 供 tar 位置参数（-C parent ...targets）；
+   * hasCredentials 标记是否含凭据类——凭据明文进归档，githubSync 据此跳过上云。
+   * 不存在的路径跳过（tar 对不存在路径会报错中止）；glob 展开后同样预检。
+   */
+  async function typeTargets(types, dshHome, base) {
+    const targets = [];
+    let hasCredentials = false;
+    const seen = new Set();
+    for (const key of types) {
+      const spec = BACKUP_TYPES[key];
+      if (!spec) continue;
+      if (spec.credentials) hasCredentials = true;
+      for (const rel of spec.paths) {
+        const matched = rel.includes('*') ? await expandGlob(rel, dshHome) : ((await existsStat(`${dshHome}/${rel}`)) ? [rel] : []);
+        for (const m of matched) {
+          const entry = `${base}/${m}`;
+          if (!seen.has(entry)) { seen.add(entry); targets.push(entry); }
+        }
+      }
+    }
+    return { targets, hasCredentials };
+  }
+
+  /** 列分类型归档（dsh-t-*，新→旧），供独立轮换与列表展示。 */
+  async function listTypedBackups() {
+    const { root } = paths();
+    let dirents;
+    try { dirents = await readdir(root, { withFileTypes: true }); } catch { return []; }
+    const backups = [];
+    for (const d of dirents) {
+      if (!d.name.startsWith(TYPED_PREFIX) || !d.name.endsWith('.tar.gz')) continue;
+      let size;
+      try { size = (await fsStat(`${root}/${d.name}`)).size; } catch { size = undefined; }
+      backups.push({ name: d.name, size });
+    }
+    return backups.sort((a, b) => (a.name < b.name ? 1 : a.name > b.name ? -1 : 0));
+  }
+
   async function doBackup(keep, signal, opts = {}) {
     const { home, dshHome, root } = paths();
     const keepN = keep && keep > 0 ? Math.floor(keep) : defaultKeep();
     // 状态文件先写：writeText 会自动创建备份目录，替代 mkdir -p（Windows 无 mkdir.exe）。
     await saveAutoState();
 
-    const prefix = typeof opts?.namePrefix === 'string' && opts.namePrefix ? opts.namePrefix : 'dsh-';
+    // 分类型备份：opts.types 非空时用 dsh-t- 前缀（独立轮换、旧版不可见），
+    // tar 按 typeTargets 子集打包而非整个 .dsh。
+    const types = Array.isArray(opts?.types) && opts.types.length
+      ? [...new Set(opts.types.filter((t) => BACKUP_TYPES[t]))]
+      : null;
+    const prefix = types ? TYPED_PREFIX : (typeof opts?.namePrefix === 'string' && opts.namePrefix ? opts.namePrefix : 'dsh-');
     const name = `${prefix}${stampNow()}.tar.gz`;
     const out = `${root}/${name}`;
     const base = dshHome.split('/').pop();
@@ -815,19 +979,34 @@ export function apply(ctx, pluginConfig) {
     // 敏感文件先从归档排除（redactExcludeFlags），其明文副本进本机 vault。
     // skipVault（pre-restore 快照）：数据可能正待恢复/已损，刷新 vault 会把
     // 仅存的凭据副本清掉——只列清单不拷贝，vault 保持上一次常规备份的状态。
-    const redacted = opts?.skipVault ? await existingSensitive(dshHome) : await refreshVault(dshHome, home, signal);
+    // 分类型备份：展开选定的类型为 tar 位置参数子集；凭据类要明文进归档，
+    // 跳过脱敏排除。types 备份不刷新 vault（归档已自含所选内容，凭据类含明文；
+    // 非凭据类子集本不含凭据文件），vault 保持上一次全量备份状态不被干扰。
+    let typePaths = null;
+    let hasCredentials = false;
+    if (types) {
+      ({ targets: typePaths, hasCredentials } = await typeTargets(types, dshHome, base));
+      if (!typePaths.length) throw new Error('选定的类型在 ~/.dsh 里没有可备份的内容（路径均不存在）');
+    }
+    const isTyped = !!types;
+    const skipVault = opts?.skipVault || isTyped;
+    const redacted = skipVault ? await existingSensitive(dshHome) : await refreshVault(dshHome, home, signal);
     const tar = await ctx.subprocess.resolveExecutable('tar');
-    await spawnRun([tar, '--exclude=*node_modules*', '--exclude=.system', ...quarantineFlags, ...redactExcludeFlags(base), ...extraExcludes(), '-czf', name, '-C', parent, base], root, signal);
+    const redactFlags = isTyped ? [] : redactExcludeFlags(base);
+    await spawnRun([tar, '--exclude=*node_modules*', '--exclude=.system', ...quarantineFlags, ...redactFlags, ...extraExcludes(), '-czf', name, '-C', parent, ...(isTyped ? typePaths : [base])], root, signal);
 
     const shaText = await sha256File(out, home, signal);
     await writeOwned(`${out}.sha256`, `${shaText}  ${out}\n`);
-    // 脱敏清单边车：恢复侧据其判断归档是否脱敏、需要从 vault 还原哪些文件。
-    if (sensitivePaths().length) {
+    // types 归档不写 .redacted.json：凭据类明文已在归档内（不靠 vault 还原），
+    // 非凭据类子集本不含凭据。全量归档照旧写脱敏清单供恢复侧从 vault 还原。
+    if (!isTyped && sensitivePaths().length) {
       await writeOwned(`${out}.redacted.json`, `${JSON.stringify({ files: redacted })}\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`);
+    // meta 记 types（分类型归档标识；缺省=全量，旧版/旧归档照读不误）；types
+    // 归档 redacted 记 0（未脱敏），hasCredentials 供 githubSync 跳过上云判断。
+    await writeOwned(`${out}.meta.json`, `${JSON.stringify({ host: hostname(), home, dshHome, createdAt: new Date().toISOString(), redacted: isTyped ? 0 : redacted.length, ...(isTyped ? { types, hasCredentials } : {}), ...(quarantined.length ? { quarantined } : {}) })}\n`);
 
     // 救援通道：每次备份把进程外恢复工具落进备份目录——宿主起不来时
     // `node rescue.mjs`（或双击启动器）仍可恢复（DSH 依赖 Node，宿主死了
@@ -857,12 +1036,16 @@ export function apply(ctx, pluginConfig) {
     // 的每日首份、再往前 4 个不同 ISO 周的每周首份（今日的档内冗余仍按 keep
     // 裁剪）。严格只比旧的"全删"多保留，绝不多删；非标准命名（解析不出日期）
     // 保持旧行为不保护。
-    const all = await listBackups();
-    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);
-    }
+    // 轮换：types 归档与全量归档分桶独立计 keep 窗口（dsh-t- 前缀），互不挤占。
+    // 统一用 rotateBase/rotateStale 变量，使下方 return 在两条路径下都可见。
+    // skipRotate：恢复流程中途拍的快照绝不顺带轮换——目标归档可能正落在
+    // keep 窗口外，轮换会删掉马上要解压的文件（review P1-3）。
+    const rotateBase = isTyped ? await listTypedBackups() : await listBackups();
+    const rotateTail = rotateBase.slice(keepN);
+    const rotateStale = opts.skipRotate
+      ? []
+      : rotateTail.filter((b) => !tierProtectedSet(rotateTail, rotateBase[0]?.name).has(b.name)).map((b) => b.name);
+    if (rotateStale.length) await removeFiles(rotateStale.flatMap((n) => sidecarsFor(n)), root, signal);
 
     // GitHub 同步（失败不回滚备份；状态记入 auto.json）
     let sync = null;
@@ -882,7 +1065,7 @@ export function apply(ctx, pluginConfig) {
       await saveAutoState();
     }
 
-    return { path: out, name, sha: shaText, total: all.length, stale: stale.length, keep: keepN, quarantined, sync };
+    return { path: out, name, sha: shaText, total: rotateBase.length, stale: rotateStale.length, keep: keepN, quarantined, sync, ...(isTyped ? { types, hasCredentials } : {}) };
   }
 
   /** 备份回执的隔离提示行：体检发现坏会话文件未入档时如实告知 + 指路修复。 */
@@ -995,6 +1178,8 @@ export function apply(ctx, pluginConfig) {
     // 配置时在 keep 集内保留）与当前备份集（归档+边车），其余文件
     // （旧副本、误入杂物）清理——git add -A 因此只会收录归档；轮换
     // 删除与误入文件一并同步移除。
+    // keep 集只含全量归档：listBackups 排除 dsh-t-（分类型归档），故类型归档
+    // 不进 GitHub 同步——含 credentials 明文者尤甚，纵深满足"凭据不上云"。
     const keep = new Set(['.gitignore']);
     if (wt.cfg.token) keep.add('.git-credentials');
     for (const b of await listBackups()) {
@@ -1146,10 +1331,10 @@ export function apply(ctx, pluginConfig) {
       // 边车缺失
     }
     if (!/^[0-9a-f]{64}$/.test(expected)) {
-      return { name, ok: false, note: '缺少或无效的 .sha256 边车文件' };
+      return { name, ok: false, note: '缺少或无效的配套校验文件（.sha256）——无法确认这份备份是否完好' };
     }
     const actual = await sha256File(archive, home, signal);
-    return { name, ok: actual === expected, note: actual === expected ? '完整' : 'sha256 不匹配（归档已损坏）' };
+    return { name, ok: actual === expected, note: actual === expected ? '完整' : '校验和不匹配（归档或校验文件之一可能损坏）' };
   }
 
   async function pickArchive(selector) {
@@ -1168,6 +1353,14 @@ export function apply(ctx, pluginConfig) {
       if (sHits.length > 1) {
         throw new Error(`"${selector}" 匹配多份快照，请加长前缀：\n${sHits.slice(0, 5).map((n) => `  ${n}`).join('\n')}`);
       }
+      // 分类型归档不在全量列表（旧版视角不可见），显式名/前缀可在此命中
+      const typed = await listTypedBackups();
+      const tExact = typed.filter((b) => b.name === selector);
+      const tHits = tExact.length ? tExact : typed.filter((b) => b.name.startsWith(selector));
+      if (tHits.length === 1) return tHits[0];
+      if (tHits.length > 1) {
+        throw new Error(`"${selector}" 匹配多份分类型归档，请加长前缀：\n${tHits.slice(0, 5).map((n) => `  ${n.name}`).join('\n')}`);
+      }
       throw new Error(`没有匹配 "${selector}" 的备份，/backup list 查看`);
     }
     throw new Error(`"${selector}" 匹配多份备份，请加长前缀：\n${hits.slice(0, 5).map((b) => `  ${b.name}`).join('\n')}`);
@@ -1176,7 +1369,17 @@ export function apply(ctx, pluginConfig) {
   /** 删除指定备份（归档 + 全部边车）；选择器经 pickArchive 精确匹配，杜绝路径穿越。 */
   async function removeBackup(selector, signal) {
     const { root } = paths();
-    const picked = await pickArchive(selector);
+    let picked;
+    try {
+      picked = await pickArchive(selector);
+    } catch (err) {
+      // 分类型归档不在 listBackups（全量视角不可见），删除时按 dsh-t- 名单单独匹配
+      const typed = await listTypedBackups();
+      const exact = typed.filter((b) => b.name === selector);
+      const hits = exact.length ? exact : typed.filter((b) => b.name.startsWith(selector));
+      if (hits.length !== 1) throw err;
+      picked = hits[0];
+    }
     await removeFiles(sidecarsFor(picked.name), root, signal);
     return { ok: true, name: picked.name, summary: `已删除备份: ${picked.name}` };
   }
@@ -1256,7 +1459,10 @@ export function apply(ctx, pluginConfig) {
       lines.push(`⚠️ 备份来自另一台机器/用户目录（${preflight.sourceHost ?? '未知主机'}，${preflight.sourceHome}），settings 内的绝对路径可能需要调整`);
     }
     if (Array.isArray(preflight.redactedFiles)) {
-      lines.push(`🔐 该归档已脱敏：${preflight.redactedFiles.length} 个凭据文件不随归档走，恢复时从本机 vault 还原（跨机恢复需重填）`);
+      // 0 个凭据文件时"已脱敏"是噪音且误导（让人以为有东西被隐去）——如实说明即可
+      lines.push(preflight.redactedFiles.length
+        ? `🔐 该归档已脱敏：${preflight.redactedFiles.length} 个凭据文件不随归档走，恢复时从本机 vault 还原（跨机恢复需重填）`
+        : '🔐 归档不含凭据文件；本机凭据不受恢复影响');
     }
     if (preflight.legacyUnaccountedCredentials) {
       lines.push('⚠️ 归档未携带脱敏清单（v0.6.x 时代格式）且不含凭据文件——恢复后凭据需从本机 vault 或原机器补齐');
@@ -1354,6 +1560,96 @@ export function apply(ctx, pluginConfig) {
       },
     );
 
+    // 安全拦截：分类型归档必须带 --types 走 merge。整包路径（挪旁+解压）会把
+    // ~/.dsh 替换成子集内容，丢失未包含的类型数据——rescue 同语义拦截。
+    if (!opts?.types && meta && Array.isArray(meta.types) && meta.types.length) {
+      throw new Error(`${picked.name} 是分类型归档（${meta.types.join(', ')}）。整包恢复会丢失其他类型数据——请带 --types ${meta.types.join(',')} 分类型恢复，或选一份全量归档（dsh- 开头）整包恢复。`);
+    }
+
+    // 分类型恢复（merge）：只把选中类型的条目解压进现有 ~/.dsh，不挪旁整包。
+    // 复用 doctorRepair 的"留档+子集解压+回滚"哲学——打破现有"绝不合并、整包
+    // 覆盖"不变量，用留档兜底。凭据类归档已含明文，直接覆盖；非凭据类
+    // mergeTargets 不含凭据文件，不碰 vault（不走下方的 vault 还原）。
+    if (Array.isArray(opts?.types) && opts.types.length) {
+      const mergeTargets = typeEntries(opts.types, entries, base);
+      if (!mergeTargets.length) {
+        throw new Error(`归档 ${picked.name} 里没有选中类型（${opts.types.join(', ')}）的条目`);
+      }
+      // 预检将覆盖的现有文件（留档依据）；目录条目 tar 解压时 mkdir 无覆盖
+      // 风险，新增项也不算覆盖——只留档现有文件。
+      const willOverwrite = [];
+      for (const entry of mergeTargets) {
+        const rel = entry.slice(`${base}/`.length);
+        const st = await fsStat(`${dshHome}/${rel}`).then((s) => s, () => null);
+        if (st && st.isFile()) willOverwrite.push({ entry, rel });
+      }
+      // 只解压文件条目：目录条目在 GNU tar 下递归消费内容会让显式成员报
+      // "Not found in archive"（exit 2），在 bsdtar 下又不递归——传文件列表在
+      // 两端行为一致（tar -x 文件成员自动补父目录；doctor 定点修复同模式）。
+      const fileTargets = mergeTargets.filter((e) => !mergeTargets.some((o) => o.startsWith(`${e}/`)));
+      if (dryRun) {
+        return {
+          archive, files: fileTargets.length, sample: fileTargets.slice(0, 24), aside: null, snapshotPath: null, dryRun: true,
+          merge: true, types: opts.types, willOverwrite: willOverwrite.map((w) => w.rel),
+          targetExists, preflight: preflightLines(preflight, profileDirs),
+        };
+      }
+      // 留档将覆盖的现有文件（.pre-merge-<时间戳>），失败可逐个还原。
+      const stamp = stampNow();
+      const kept = [];
+      for (const w of willOverwrite) {
+        const keep = `${dshHome}/${w.rel}.pre-merge-${stamp}`;
+        await mkdir(dirname(keep), { recursive: true });
+        await copyFile(`${dshHome}/${w.rel}`, keep);
+        kept.push({ ...w, keep });
+      }
+      try {
+        const tar = await ctx.subprocess.resolveExecutable('tar');
+        await spawnRun([tar, '-xzf', picked.name, '-C', parent, ...fileTargets], root, signal);
+      } catch (err) {
+        // 对齐 #28 / doctorRepair 回滚：从留档还原每个被覆盖项；连还原都失败
+        // 时把留档路径交代清楚，绝不静默停在半截状态。
+        const reason = err && err.message ? err.message : String(err);
+        const restored = new Set();
+        for (const w of willOverwrite) {
+          try { await copyFile(w.keep, `${dshHome}/${w.rel}`); restored.add(w.rel); } catch { /* 逐个失败落入下方报告 */ }
+        }
+        if (restored.size === willOverwrite.length) {
+          throw new Error(`分类型恢复失败（${reason}）。已从留档还原全部覆盖现场，数据保持恢复前状态；排查后可重试`);
+        }
+        const missing = willOverwrite.filter((w) => !restored.has(w.rel)).map((w) => w.rel);
+        throw new Error(`分类型恢复失败（${reason}），且部分现场未自动还原: ${missing.join(', ')}。对应的 *.pre-merge-${stamp} 留档仍在原目录旁，手工拷回即可`);
+      }
+      // 可选依赖重装：merge 含 profiles 时对新解出的 profile 跑 pnpm install。
+      const deps = { installed: [], failed: [], note: null };
+      if (opts?.syncDeps) {
+        const mergedProfiles = [...new Set(mergeTargets
+          .filter((n) => n.startsWith(`${base}/profiles/`) && n.endsWith('/package.json'))
+          .map((n) => n.slice(`${base}/profiles/`.length).split('/')[0]))];
+        if (mergedProfiles.length) {
+          try {
+            const pnpm = await ctx.subprocess.resolveExecutable('pnpm');
+            for (const p of mergedProfiles) {
+              try {
+                await spawnRun([pnpm, 'install', '--frozen-lockfile'], `${dshHome}/profiles/${p}`, signal);
+                deps.installed.push(p);
+              } catch {
+                await spawnRun([pnpm, 'install'], `${dshHome}/profiles/${p}`, signal);
+                deps.installed.push(p);
+              }
+            }
+          } catch {
+            deps.note = 'pnpm 不可用，跳过依赖重装（配置已恢复）';
+          }
+        }
+      }
+      return {
+        archive, files: fileTargets.length, aside: null, snapshotPath: null, dryRun: false,
+        merge: true, types: opts.types, restored: fileTargets.length,
+        kept: kept.map((k) => k.keep), deps, preflight: preflightLines(preflight, profileDirs),
+      };
+    }
+
     if (dryRun) {
       return {
         archive, files: entries.length, sample: entries.slice(0, 12), aside: null, snapshotPath: null, dryRun: true,
@@ -1366,9 +1662,9 @@ export function apply(ctx, pluginConfig) {
     // 快照用 dsh-pre-restore- 前缀与用户常规备份区分，经 listBackups 过滤
     // 后不进列表/轮换/latest 选择；每次恢复清掉上一次的快照防累积。
     const snapshot = targetExists
-      ? await doBackup(undefined, signal, { namePrefix: 'dsh-pre-restore-', skipVault: true })
+      ? await doBackup(undefined, signal, { namePrefix: 'dsh-pre-restore-', skipVault: true, skipRotate: true })
       : null;
-    if (snapshot) await prunePreRestoreSnapshots(snapshot.name, signal);
+    if (snapshot) await prunePreRestoreSnapshots([snapshot.name, picked.name], signal);
     const asideName = `${base}.pre-restore-${stampNow()}`;
     let aside = null;
     if (targetExists) {
@@ -1392,11 +1688,11 @@ export function apply(ctx, pluginConfig) {
         // 回滚失败：落入下方的人工指引分支，把位置交代清楚
       }
       if (rolledBack) {
-        throw new Error(`解压归档失败（${reason}）。已自动还原到恢复前状态，数据未丢失；排查磁盘空间/权限后可重试`);
+        throw new Error(`解压归档失败：${friendlyReason(err)}。已自动还原到恢复前状态，数据未丢失，可处理后重试`);
       }
       throw new Error(aside
-        ? `解压归档失败（${reason}），且自动还原未成功。原数据完好保存在 ${aside}，把它改名回 "${dshHome}" 即可回到恢复前状态`
-        : `解压归档失败（${reason}），且清理未成功。半截解压产物在 ${dshHome}，删除后即可重试`);
+        ? `解压归档失败：${friendlyReason(err)}，且自动还原未成功。原数据完好保存在 ${aside}，把它改名回 "${dshHome}" 即可回到恢复前状态`
+        : `解压归档失败：${friendlyReason(err)}，且清理未成功。半截解压产物在 ${dshHome}，删除后即可重试`);
     }
 
     // vault 还原：脱敏归档恢复出的 ~/.dsh 不含凭据文件，从本机 vault 拷回。
@@ -1457,6 +1753,28 @@ export function apply(ctx, pluginConfig) {
 
   /** 恢复结果的人类可读汇总（命令、模型工具与面板共用）。 */
   function summarizeRestore(r) {
+    if (r.merge) {
+      const types = (r.types ?? []).join(', ');
+      if (r.dryRun) {
+        const over = r.willOverwrite ?? [];
+        const shown = r.sample.length;
+        const tail = r.files > shown ? `\n    … 共 ${r.files} 项` : '';
+        const overLine = over.length
+          ? `\n  其中覆盖现有 ${over.length} 个（先留档 .pre-merge-*）: ${over.slice(0, 8).join(', ')}${over.length > 8 ? ' …' : ''}`
+          : '\n  均为新增，不覆盖现有文件';
+        return `📦 分类型恢复预览 —— 只预览，还没动磁盘\n  归档: ${r.archive}\n  类型: ${types}\n  将写入: ${r.files} 项${overLine}\n${(r.preflight ?? []).map((l) => `  ${l}`).join('\n')}\n\n  将写入的条目：\n${r.sample.map((s) => `    ${s}`).join('\n')}${tail}`;
+      }
+      const lines = [
+        '✅ 分类型恢复完成',
+        `  已合并写入: ${r.restored} 项 ← 来自 ${r.archive.split('/').pop()}（类型: ${types}）`,
+      ];
+      if (r.kept?.length) lines.push(`  覆盖的旧文件已留档: ${r.kept.length} 个（.pre-merge-*，确认后可自行删除）`);
+      for (const p of r.preflight ?? []) if (p.startsWith('⚠️')) lines.push(`  ${p}`);
+      if (r.deps?.note) lines.push(`  插件依赖: ${r.deps.note}`);
+      else if (r.deps?.installed?.length) lines.push(`  插件依赖: 已装好 ${r.deps.installed.join(', ')}`);
+      lines.push('  ⏸️ 待办: 重启 dsh 让恢复的类型内容生效');
+      return lines.join('\n');
+    }
     if (r.dryRun) {
       // 预览要回答两件事：确认后会发生什么（按目标是否已有数据切换口径）、
       // 凭据/依赖的 preflight 提醒。此时还没动任何文件，标题必须说清。
@@ -1464,7 +1782,7 @@ export function apply(ctx, pluginConfig) {
         ? ['   · 目标位置还没有 .dsh（首次恢复）：直接写入，不做挪动和快照']
         : [
           '   · 当前的 .dsh 整个挪到一旁，改名为 .dsh.pre-restore-<时间>，不会和新数据混在一起',
-          '   · 挪之前自动做一份快照备份；快照只保留最近一次',
+          '   · 挪之前自动做一份快照备份（恢复前快照只保留最近一次）',
           '   · 然后把这份归档的内容原样写回 .dsh',
         ];
       const pre = ['', ...moves, ...(r.preflight ?? []).map((l) => `  ${l}`)].join('\n');
@@ -1487,6 +1805,9 @@ export function apply(ctx, pluginConfig) {
     if (r.vaultMissing?.length) lines.push(`  ⚠️ 凭据缺失需手动重填: ${r.vaultMissing.join(', ')}`);
     const installed = r.deps?.installed ?? [];
     const failed = r.deps?.failed ?? [];
+    // 待办必须只有一条且顺序正确：node_modules 不随归档，先重装依赖再重启，
+    // 照"直接重启"执行会得到 cannot resolve profile bundle（UX 审查 P1-2）。
+    const depsPending = Boolean(r.deps?.note) || failed.length > 0 || (!installed.length && r.profiles?.length);
     if (r.deps?.note) {
       lines.push(`  插件依赖: 还没装 —— ${r.deps.note}；之后也可用 --sync-deps 补装`);
     } else if (failed.length) {
@@ -1494,9 +1815,11 @@ export function apply(ctx, pluginConfig) {
     } else if (installed.length) {
       lines.push(`  插件依赖: 已装好 ${installed.join(', ')}`);
     } else if (r.profiles?.length) {
-      lines.push('  插件依赖: 还没装 —— 恢复时带 --sync-deps 重装，或进各 profile 目录手动 pnpm install');
+      lines.push('  插件依赖: 还没装');
     }
-    lines.push('  ⏸️ 待办: 重启 dsh，会话和配置才会切换到恢复的内容');
+    lines.push(depsPending
+      ? '  ⏸️ 待办: 先重装插件依赖（重开 dsh 前进各 profile 目录跑 pnpm install），再重启 dsh——顺序不能反，否则起不来'
+      : '  ⏸️ 待办: 重启 dsh，会话和配置才会切换到恢复的内容');
     return lines.join('\n');
   }
 
@@ -1505,9 +1828,12 @@ export function apply(ctx, pluginConfig) {
   // 布局与格式依据宿主内置的 @deepseek-ai/dsh-session-persistence-jsonl：
   //   <会话根>/--<项目目录>--/<编码后 id>/session.jsonl.zstd（compression:'none' 时为 .jsonl）
   // zstd 文件是独立帧的拼接：首帧是带校验和的 SessionHeader 行，其后每个追加批一帧。
+  // 两条硬契约都对齐宿主读端：①行级——首行 SessionHeader、seq 连续；②容器级——
+  // 首帧解出来恰好一行 header（宿主 assertZstdHeaderFrame；外部工具把整份日志
+  // 压成单帧时内容完整可解、宿主却拒载，行级校验覆盖不到，必须单独判）。
   // Node 内置 zstd 解码器不跨帧续读，因此先按 RFC 8878 走帧字节边界
   // （魔数/帧头/块序列/校验和），再逐帧解出逻辑行。检测目标正是社区高频的
-  // "corrupt session log"灾难：并发写 seq 撞号、坏帧、尾部截断。
+  // "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']);
@@ -1525,7 +1851,9 @@ export function apply(ctx, pluginConfig) {
 
   /**
    * 按 RFC 8878 结构走查拼接帧的字节边界（不解压）：返回 [start,end] 区间数组；
-   * 结构不合法（截断/未知魔数/保留位/越界块）抛错。skippable 帧一并支持。
+   * 结构不合法（截断/未知魔数/保留位/越界块）抛错。
+   * skippable 帧直接判非法——宿主 scanZstdFrames 拒绝一切非数据帧魔数，
+   * 这类文件宿主整体拒载，容忍它们会造成「doctor 报 OK、宿主编译系统读不了」。
    */
   function walkZstdFrames(buf) {
     const frames = [];
@@ -1564,12 +1892,7 @@ export function apply(ctx, pluginConfig) {
         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;
+        throw new Error('遇 skippable 帧——宿主读端不支持任何非数据帧魔数，整个文件将被拒载');
       } else {
         throw new Error(`偏移 ${off} 处不是 zstd 帧魔数`);
       }
@@ -1577,19 +1900,32 @@ export function apply(ctx, pluginConfig) {
     return frames;
   }
 
-  /** 解出 .zstd 会话日志的全部逻辑行；任一帧损坏即抛错（错误含偏移信息）。 */
+  /**
+   * 解出 .zstd 会话日志的全部逻辑行；任一帧损坏即抛错（错误含偏移信息）。
+   * 同时对首个数据帧做宿主容器契约判定 headerFrameOk——宿主 assertZstdHeaderFrame
+   * 是字节精确的：首帧解出必须非空、且首个换行符恰在最后一个字节（即「恰好
+   * 一行、以单个 \n 结尾」）。行流拼接校验覆盖不到这条（#66）。
+   */
   function decodeZstdLog(buf) {
     const parts = [];
     let frameNo = 0;
+    let headerFrameOk;
     for (const [s, e] of walkZstdFrames(buf)) {
       frameNo += 1;
       try {
-        parts.push(zlib.zstdDecompressSync(buf.subarray(s, e)));
+        const out = zlib.zstdDecompressSync(buf.subarray(s, e));
+        parts.push(out);
+        if (headerFrameOk === undefined) {
+          headerFrameOk = out.length > 0 && out.indexOf(10) === out.length - 1;
+        }
       } 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);
+    return {
+      lines: Buffer.concat(parts).toString('utf8').split('\n').filter((l) => l.length > 0),
+      headerFrameOk,
+    };
   }
 
   /**
@@ -1670,8 +2006,15 @@ export function apply(ctx, pluginConfig) {
         return { state: 'skipped', reason: `文件 ${Math.floor(info.size / 1048576)}MB 超过深度校验上限（${Math.floor(HASH_MAX_BYTES / 1048576)}MB），不整读入内存` };
       }
       let lines;
+      let headerFrameOk;
       if (f.abs.endsWith('.zstd')) {
-        lines = decodeZstdLog(await readFile(f.abs));
+        ({ lines, headerFrameOk } = decodeZstdLog(await readFile(f.abs)));
+        // 容器契约（#66/#1047）：首帧必须解出「恰好一行 header、以单个换行
+        // 结尾」（字节精确，对齐宿主 assertZstdHeaderFrame）。单帧重写、帧内
+        // 多余空行、缺行尾的文件内容完整可解、行级校验全过，宿主却整体拒载。
+        if (headerFrameOk === false) {
+          return { state: 'bad', reason: '首帧不是恰好一行 header——违反容器契约（首帧应解出一行 SessionHeader 且以单个换行结尾；单帧重写/多余空行/缺行尾的典型形态，宿主读端会拒载）' };
+        }
       } else {
         lines = (await readFile(f.abs, 'utf8')).split('\n').filter((l) => l.length > 0);
       }
@@ -1683,7 +2026,7 @@ export function apply(ctx, pluginConfig) {
     }
   }
 
-  function summarizeDoctorScan(r) {
+  function summarizeDoctorScan(r, opts = {}) {
     if (!r.files.length) return '未找到任何会话日志——可能还没有产生过会话，或布局与预期不同。';
     const healthy = r.scanned - r.corruptCount - (r.skippedCount ?? 0);
     let head = `扫描 ${r.scanned} 个会话日志：${healthy} 健康、${r.corruptCount} 损坏`;
@@ -1692,7 +2035,9 @@ export function apply(ctx, pluginConfig) {
     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-*）`;
+    // 修复入口按调用面分流：聊天面指聊天命令；面板没有 doctor UI，指到真实可用路径
+    const hint = opts.repairHint ?? '可从备份定点修复：/backup doctor --repair [前缀|latest]（修复前会把损坏文件留档为 *.corrupt-*）';
+    return `${head}\n${detail}${more}\n\n${hint}`;
   }
 
   /** 只读扫描 ~/.dsh 下全部会话日志；不写任何文件。 */
@@ -1756,7 +2101,6 @@ export function apply(ctx, pluginConfig) {
       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 {
@@ -1765,10 +2109,10 @@ export function apply(ctx, pluginConfig) {
         } catch { /* 单个还原失败：落入下方如实报告 */ }
       }
       if (restored.size === targets.length) {
-        throw new Error(`定点修复失败（${reason}）。已从留档还原全部损坏现场，数据保持修复前状态；排查磁盘空间/权限后可重试`);
+        throw new Error(`定点修复失败：${friendlyReason(err)}。已从留档还原全部损坏现场，数据保持修复前状态，可处理后重试`);
       }
       const missing = targets.filter((t) => !restored.has(t.rel)).map((t) => t.rel);
-      throw new Error(`定点修复失败（${reason}），且部分现场未自动还原: ${missing.join(', ')}。对应的 *.corrupt-${stamp} 留档仍在原目录旁，手工拷回原位即可`);
+      throw new Error(`定点修复失败：${friendlyReason(err)}，且部分现场未自动还原: ${missing.join(', ')}。对应的 *.corrupt-${stamp} 留档仍在原目录旁，手工拷回原位即可`);
     }
 
     // 修完复检：从归档解出的副本必须健康，否则如实报告（skipped 不算失败——
@@ -1867,7 +2211,11 @@ export function apply(ctx, pluginConfig) {
       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)}`);
+      // ENOENT = 首次使用还没有 auto.json，是正常初始状态，静默按未配置处理；
+      // 其他读取失败（解析错误/权限）才值得告警，且文案要给"影响 + 出路"。
+      if (err && err.code !== 'ENOENT') {
+        console.warn(`[dsh-backup] 自动备份计划文件读取失败，定时备份已暂停（不影响已有备份）：执行 /backup auto <小时数> 可重新开启（${String(err && err.message ? err.message : err)}）`);
+      }
       return 0;
     }
   }
@@ -1880,11 +2228,17 @@ export function apply(ctx, pluginConfig) {
     return Math.max(anchor, Date.now());
   }
 
+  /** 本地时间显示：YYYY-MM-DD HH:mm——不依赖运行时 locale（裸跑环境会落 en-US）。 */
+  function formatWhen(ts) {
+    const d = new Date(ts);
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+  }
+
   function autoSummary() {
     if (!autoDispose) return '自动备份未开启（/backup auto <N小时> 开启）';
     // 绝对节奏：下次 = 上次执行 + 周期；错过（重启间隔超周期）则按现在显示，调度会立即补跑。
-    const next = new Date(nextAutoAt()).toLocaleString();
-    return `自动备份已开启：每 ${autoHours} 小时一次（已持久化，重启续跑），下次约 ${next}${lastAuto ? `；上次自动备份: ${lastAuto}` : ''}`;
+    return `自动备份已开启：每 ${autoHours} 小时一次（已持久化，重启续跑），下次 ${formatWhen(nextAutoAt())}${lastAuto ? `；上次自动备份: ${lastAuto}` : ''}`;
   }
 
   /** 链式 timeout 调度：每次触发后按上次执行时间推算下一次，重启后节奏不重置。 */
@@ -1965,7 +2319,10 @@ export function apply(ctx, pluginConfig) {
           const dryRun = parts.includes('--dry-run');
           const syncDeps = parts.includes('--sync-deps');
           const sel = parts.slice(1).find((t) => !t.startsWith('--')) || 'latest';
-          const r = await restoreArchive(sel, dryRun, invocation.signal, { syncDeps });
+          // 分类型恢复：--types skills（只把选中类型 merge 进现有 ~/.dsh，不挪旁整包）
+          const typesMatch = input.match(/--(?:types|only)\s+([\w,]+)/);
+          const types = typesMatch ? [...new Set(typesMatch[1].split(',').map((s) => s.trim()).filter(Boolean))] : undefined;
+          const r = await restoreArchive(sel, dryRun, invocation.signal, { syncDeps, ...(types ? { types } : {}) });
           return { kind: 'success', text: summarizeRestore(r) };
         }
 
@@ -2041,7 +2398,7 @@ export function apply(ctx, pluginConfig) {
 
         if (head === 'delete' || head === 'rm') {
           const sel = parts[1];
-          if (!sel) return { kind: 'error', text: '用法: /backup delete <归档名前缀|latest>' };
+          if (!sel) return { kind: 'error', text: '用法: /backup delete <归档名前缀|latest>（删除不可恢复，需要时可用 /backup 重新备份）' };
           const r = await removeBackup(sel, invocation.signal);
           return { kind: 'success', text: `🗑️ ${r.summary}` };
         }
@@ -2058,19 +2415,22 @@ export function apply(ctx, pluginConfig) {
             return { kind: 'error', text: '小时数需为 1~720 之间的数字（如 /backup auto 12）' };
           }
           await setAuto(h);
-          return { kind: 'success', text: `✅ 自动备份已开启：每 ${h} 小时执行一次（保留 ${autoKeep()} 份，已持久化）。\n${autoSummary()}` };
+          return { kind: 'success', text: `✅ 自动备份已开启：每 ${h} 小时执行一次（保留 ${autoKeep()} 份，已持久化）。\n首次备份正在执行，之后每 ${h} 小时一次。\n${autoSummary()}` };
         }
 
         let keep;
         const m = input.match(/--keep\s+(\d+)/);
         if (m) keep = Number(m[1]);
-        const r = await doBackup(keep, invocation.signal);
+        // 分类型备份：--types api,mcp,skills（逗号分隔，可多类；--only 同义）。缺省=全量。
+        const typesMatch = input.match(/--(?:types|only)\s+([\w,]+)/);
+        const types = typesMatch ? [...new Set(typesMatch[1].split(',').map((s) => s.trim()).filter(Boolean))] : undefined;
+        const r = await doBackup(keep, invocation.signal, types ? { types } : {});
         return {
           kind: 'success',
-          text: `✅ 备份完成\n  文件: ${r.path}\n  校验和: ${r.sha.slice(0, 16)}…\n  轮换: 删除 ${r.stale} 份旧备份（保留 ${r.keep} 份）${quarantineNote(r)}\n  ${autoSummary()}`,
+          text: `✅ 备份完成${types ? `（类型: ${types.join(', ')}${r.hasCredentials ? '，含明文凭据·不进 GitHub 同步' : ''}）` : ''}\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)}` };
+        return { kind: 'error', text: `备份失败: ${friendlyReason(err)}` };
       }
     },
   });
@@ -2087,6 +2447,7 @@ export function apply(ctx, pluginConfig) {
       dryRun: { type: 'boolean', description: 'mode=restore 时仅预览（不写入）；真实恢复前必须先预览并向用户展示确认' },
       syncDeps: { type: 'boolean', description: 'mode=restore 时恢复后对各 profile 执行 pnpm install 重装插件依赖' },
       repair: { type: 'boolean', description: 'mode=doctor 时从 selector 归档定点修复损坏的会话日志（缺省仅扫描）' },
+      types: { type: 'string', description: 'mode=backup/restore 时按内容类型子集操作（逗号分隔，如 credentials,mcp,skills）。backup=只打选中类型子集归档；restore=只把选中类型 merge 进现有 ~/.dsh（不挪旁整包，覆盖前留档）' },
     },
     output: {
       schema: { type: 'object', additionalProperties: true },
@@ -2115,7 +2476,8 @@ export function apply(ctx, pluginConfig) {
           return { ok: bad === 0, summary: lines.join('\n') || '暂无备份可校验。' };
         }
         if (mode === 'restore') {
-          const r = await restoreArchive(selector || 'latest', Boolean(args && args.dryRun), signal);
+          const types = typeof args?.types === 'string' && args.types.trim() ? [...new Set(args.types.split(',').map((s) => s.trim()).filter(Boolean))] : undefined;
+          const r = await restoreArchive(selector || 'latest', Boolean(args && args.dryRun), signal, { syncDeps: Boolean(args && args.syncDeps), ...(types ? { types } : {}) });
           return { ok: true, path: r.archive, summary: summarizeRestore(r) };
         }
         if (mode === 'doctor') {
@@ -2140,14 +2502,17 @@ export function apply(ctx, pluginConfig) {
             await setAuto(0);
             return { ok: true, summary: '自动备份已关闭。' };
           }
-          if (!Number.isFinite(h) || h < 1 || h > 720) return { ok: false, summary: 'hours 需为 1~720' };
+          if (!Number.isFinite(h) || h < 1 || h > 720) return { ok: false, summary: 'hours 需为 1~720 的整数（0=关闭）' };
           await setAuto(h);
-          return { ok: true, summary: `自动备份已开启：每 ${h} 小时一次（已持久化）。\n${autoSummary()}` };
+          return { ok: true, summary: `自动备份已开启：每 ${h} 小时一次（已持久化）。\n首次备份正在执行，之后每 ${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} 份）${quarantineNote(r)}` };
+        const types = typeof args?.types === 'string' && args.types.trim()
+          ? [...new Set(args.types.split(',').map((s) => s.trim()).filter(Boolean))]
+          : undefined;
+        const r = await doBackup(args && args.keep ? args.keep : undefined, signal, types ? { types } : {});
+        return { ok: true, path: r.path, sha: r.sha, summary: `备份完成: ${r.path}${types ? `（类型: ${types.join(', ')}${r.hasCredentials ? '，含明文凭据·不进 GitHub 同步' : ''}）` : ''}\nsha256: ${r.sha}\n轮换删除 ${r.stale} 份（保留 ${r.keep} 份）${quarantineNote(r)}` };
       } catch (err) {
-        return { ok: false, summary: `操作失败: ${String(err && err.message ? err.message : err)}` };
+        return { ok: false, summary: `操作失败: ${friendlyReason(err)}` };
       }
     },
   }));
@@ -2156,7 +2521,15 @@ export function apply(ctx, pluginConfig) {
   const panelOps = {
     status: async () => {
       const all = await listBackups();
+      const typed = await listTypedBackups();
       const { root, dshHome } = paths();
+      // 分类型归档单独列出并带类型清单（读各自 meta.types），供面板分区展示
+      const typedBackups = [];
+      for (const b of typed) {
+        let types = [];
+        try { types = JSON.parse(await readFile(`${root}/${b.name}.meta.json`, 'utf8')).types ?? []; } catch { /* 边车缺失 */ }
+        typedBackups.push({ name: b.name, size: typeof b.size === 'number' ? b.size : null, types });
+      }
       return {
         destination: root,
         dshHome,
@@ -2164,17 +2537,22 @@ export function apply(ctx, pluginConfig) {
         autoHours,
         lastAuto,
         backups: all.map((b) => ({ name: b.name, size: typeof b.size === 'number' ? b.size : null })),
+        typedBackups,
       };
     },
-    backup: async (keep, signal) => {
-      const r = await doBackup(keep, signal);
+    backup: async (keep, types, signal) => {
+      const validTypes = Array.isArray(types) && types.length ? [...new Set(types.filter((t) => BACKUP_TYPES[t]))] : undefined;
+      const r = await doBackup(keep, signal, validTypes ? { types: validTypes } : {});
+      // 面板回执给"成了、叫什么、存哪了"；64 位 sha 全文是噪音（完整值就在
+      // 归档旁的 .sha256），路径用文件名——目录已显示在上方总览卡
       return {
         ok: true,
-        summary: `备份完成: ${r.path}\nsha256: ${r.sha}\n轮换删除 ${r.stale} 份（保留 ${r.keep} 份）${quarantineNote(r)}`,
+        summary: `备份完成: ${r.path.split('/').pop()}${validTypes ? `（类型: ${validTypes.join(', ')}${r.hasCredentials ? '，含明文凭据·不进 GitHub 同步' : ''}）` : ''}\nsha256: ${r.sha.slice(0, 16)}…（完整校验值在归档旁的 .sha256 文件）${r.stale ? `\n轮换删除 ${r.stale} 份旧备份（保留 ${r.keep} 份）` : ''}${quarantineNote(r)}`,
         path: r.path,
         sha: r.sha,
         stale: r.stale,
         keep: r.keep,
+        ...(validTypes ? { types: validTypes, hasCredentials: Boolean(r.hasCredentials) } : {}),
       };
     },
     verify: async (selector, signal) => {
@@ -2192,11 +2570,12 @@ export function apply(ctx, pluginConfig) {
       }
       return { ok: bad === 0, summary: results.map((r) => `${r.ok ? '✅' : '❌'} ${r.name} — ${r.note}`).join('\n') || '暂无备份可校验。', results };
     },
-    restore: async (selector, dryRun, signal) => {
+    restore: async (selector, dryRun, types, syncDeps, signal) => {
       try {
-        const r = await restoreArchive(selector || 'latest', Boolean(dryRun), signal);
+        const validTypes = Array.isArray(types) && types.length ? [...new Set(types.filter((t) => BACKUP_TYPES[t]))] : undefined;
+        const r = await restoreArchive(selector || 'latest', Boolean(dryRun), signal, { syncDeps: Boolean(syncDeps), ...(validTypes ? { types: validTypes } : {}) });
         if (r.dryRun) {
-          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, dryRun: true, archive: r.archive, files: r.files, sample: r.sample, preflight: r.preflight ?? [], targetExists: r.targetExists, ...(r.merge ? { merge: true, types: r.types, willOverwrite: r.willOverwrite ?? [] } : {}), summary: summarizeRestore(r) };
         }
         return {
           ok: true,
@@ -2208,10 +2587,12 @@ export function apply(ctx, pluginConfig) {
           preflight: r.preflight ?? [],
           vaultRestored: r.vaultRestored ?? [],
           vaultMissing: r.vaultMissing ?? [],
+          ...(r.merge ? { merge: true, types: r.types, restored: r.restored, kept: r.kept ?? [] } : {}),
+          deps: r.deps,
           summary: summarizeRestore(r),
         };
       } catch (err) {
-        return { ok: false, dryRun: Boolean(dryRun), summary: String(err && err.message ? err.message : err) };
+        return { ok: false, dryRun: Boolean(dryRun), summary: friendlyReason(err) };
       }
     },
     setAuto: async (hours) => {
@@ -2220,10 +2601,10 @@ export function apply(ctx, pluginConfig) {
         return { ok: true, hours: 0, summary: '自动备份已关闭。' };
       }
       if (!Number.isFinite(hours) || hours < 1 || hours > 720) {
-        return { ok: false, summary: 'hours 需为 1~720（0=关闭）' };
+        return { ok: false, summary: '间隔需为 1~720 的整数小时（填 12 表示每 12 小时一次）' };
       }
       await setAuto(Math.floor(hours));
-      return { ok: true, hours: Math.floor(hours), summary: autoSummary() };
+      return { ok: true, hours: Math.floor(hours), summary: `自动备份已开启：每 ${Math.floor(hours)} 小时一次。\n首次备份正在执行，之后每 ${Math.floor(hours)} 小时一次。\n${autoSummary()}` };
     },
     githubStatus: async () => {
       const cfg = githubConfig();
@@ -2276,7 +2657,7 @@ export function apply(ctx, pluginConfig) {
         const r = await removeBackup(selector || 'latest', signal);
         return { ok: true, summary: r.summary };
       } catch (err) {
-        return { ok: false, summary: String(err && err.message ? err.message : err) };
+        return { ok: false, summary: friendlyReason(err) };
       }
     },
     setGithubRepo: async (repo) => {
@@ -2320,7 +2701,8 @@ export function apply(ctx, pluginConfig) {
           ok: r.corruptCount === 0,
           scanned: r.scanned,
           corruptCount: r.corruptCount,
-          summary: summarizeDoctorScan(r),
+          // 面板没有 doctor UI，指路必须指向真实可用的入口（聊天命令或救援页）
+          summary: summarizeDoctorScan(r, { repairHint: '定点修复目前要在聊天窗执行：/backup doctor --repair [前缀|latest]（修复前会把损坏文件留档为 *.corrupt-*）；DSH 起不来时可用备份目录里的救援页「体检并修复」' }),
           corrupt: r.corrupt.map((c) => ({ path: c.rel, reason: c.reason })),
         };
       } catch (err) {