@xiaoyuyu6420/dsh-backup 0.6.2 → 0.7.0

package/lib/index.js

@@ -12,19 +12,23 @@
  * - `/backup auto <N小时>|off|status`      定时自动备份（1~720；保留份数由 config.keep
  *                                          支配，未配置时 <24h 3 份、否则 7 份；重启按
  *                                          上次执行时间推算下次，不重置节奏）
- * - `/backup github status|sync|repo <地址|off>`  GitHub 同步状态 / 立即同步 / 设置仓库
+ * - `/backup github status|sync|pull [--restore <前缀|latest>]|repo <地址|off>`
+ *                                        GitHub 同步状态 / 立即推送 / 拉取到本地 / 设置仓库
  * - `/backup delete|rm <前缀|latest>`      删除备份（归档 + 校验边车）
  * - `/backup --keep N`                     覆盖本次保留份数
- * - `backup_dsh` 模型工具：mode=backup|list|verify|restore|auto
- * - cordis.yml `config`：destination / keep / exclude / githubRepo（见 README）
+ * - `backup_dsh` 模型工具：mode=backup|list|verify|restore|auto（restore 支持 syncDeps）
+ * - cordis.yml `config`：destination / keep / exclude / redact / githubRepo（见 README）
  * - Settings「备份」标签页（Web）：状态、立即备份、校验、恢复、下载、
- *   自动备份开关与 GitHub 同步，经 `backupPanel` Typert Remote 命名空间访问
+ *   自动备份开关与 GitHub 同步（推送 + 拉取），经 `backupPanel` Typert Remote 命名空间访问
  * - Web 下载路由：GET /backup-download/<归档名>（仅 loopback，附件形式）
  *
- * 安全说明：备份包含明文凭据（.credentials.yaml、qq-bridge/config.json），
- * 归档与边车在 POSIX 上 chmod 600 仅本人可读写；请勿将备份目录同步到不受信位置。
- * GitHub 同步前请确认目标仓库是私有仓库。restore 会拒绝恢复含归档根目录之外
- * 条目的文件（tar 路径穿越防护）。
+ * 安全说明（v0.7.0 起）：凭据文件（.credentials.yaml / .env / qq-bridge/config.json，
+ * config.redact 可增删）默认脱敏——不进归档、不进 GitHub 同步，明文只存备份目录下
+ * 的本机 vault（vault/，POSIX 700/600），恢复时自动拷回 ~/.dsh；跨机恢复（vault 为空）
+ * 按 .redacted.json 清单提示重填。归档另携 .meta.json（主机/家目录/时间）供恢复预检：
+ * 家目录不一致时提示绝对路径风险。config.redact=false/'off' 可回到 v0.6.x 明文行为
+ * （不推荐）。归档与校验边车在 POSIX 上 chmod 600 仅本人可读写。
+ * restore 会拒绝恢复含归档根目录之外条目的文件（tar 路径穿越防护）。
  *
  * 存储说明：插件自有数据（归档、校验和、auto.json）直接经 node:fs 写入
  * （与 dsh-session 持久化、skill-filesystem 同一模式）——ctx.fs 能力是
@@ -33,7 +37,8 @@
  */
 import { createHash } from 'node:crypto';
 import { createReadStream } from 'node:fs';
-import { mkdir, open, copyFile, readdir, readFile, rename, stat as fsStat, unlink, writeFile } from 'node:fs/promises';
+import { mkdir, open, copyFile, readdir, readFile, rename, rm, stat as fsStat, unlink, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
 import { dirname, join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
@@ -51,6 +56,16 @@ const MAX_GITHUB_BYTES = 90 * 1024 * 1024;
 const SYNC_DIR = '.github-sync';
 /** Web 下载路由前缀（无尾斜杠：prefix 匹配语义为 pathname.startsWith(prefix + '/')）。 */
 const DOWNLOAD_PREFIX = '/backup-download';
+/**
+ * 默认脱敏的敏感文件（相对 ~/.dsh 根的 POSIX 路径）：凭据与环境变量文件
+ * 明文绝不进归档、绝不进 GitHub 同步——真实值只落本机 vault（备份目录下
+ * `vault/`，结构镜像 ~/.dsh）。恢复时从 vault 自动还原；跨机恢复（vault 为
+ * 空）则提示重填。config.redact 数组可追加；false/'off' 关闭整套（回到
+ * v0.6.x 明文行为，不推荐）。
+ */
+const SENSITIVE_DEFAULTS = ['.credentials.yaml', '.env', 'qq-bridge/config.json'];
+/** 备份目录下保存明文敏感文件的子目录（随备份刷新为最新一份的副本）。 */
+const VAULT_DIR = 'vault';
 
 /**
  * `backupPanel` Remote 命名空间的调用描述符（src-json codec）。手工经
@@ -83,6 +98,7 @@ const PANEL_INVOCATIONS = Object.freeze([
   panelDescriptor('setAuto', ['hours']),
   panelDescriptor('githubStatus', []),
   panelDescriptor('githubSyncNow', [], true),
+  panelDescriptor('githubPull', [], true),
   panelDescriptor('removeEntry', ['selector'], true),
   panelDescriptor('setGithubRepo', ['repo']),
 ]);
@@ -134,6 +150,11 @@ class BackupPanelService extends TypertRemoteService {
     return this.ops.githubSyncNow(signal);
   }
 
+  /** 从 GitHub 拉取备份集到本地（新机恢复第一步，不自动恢复）。 */
+  githubPull(signal) {
+    return this.ops.githubPull(signal);
+  }
+
   /** 删除指定备份（归档 + 校验边车）。 */
   removeEntry(selector, signal) {
     return this.ops.removeEntry(selector, signal);
@@ -224,6 +245,73 @@ export function apply(ctx, pluginConfig) {
     return list.filter((p) => typeof p === 'string' && p.length > 0).map((p) => `--exclude=${p}`);
   }
 
+  /** 生效的脱敏清单：默认集 + config.redact 追加（false/'off' 整体关闭）。 */
+  function sensitivePaths() {
+    const cfg = pluginConfig?.redact;
+    if (cfg === false || cfg === 'off' || cfg === 'none') return [];
+    const extra = Array.isArray(cfg) ? cfg.filter((p) => typeof p === 'string' && p.trim().length) : [];
+    return [...new Set([...SENSITIVE_DEFAULTS, ...extra.map((p) => p.trim())])];
+  }
+
+  /**
+   * 归档排除模式（tar 成员路径以 `<base>/` 开头，如 `.dsh/.credentials.yaml`）。
+   * GNU/bsdtar 的 --exclude 对成员路径做 glob 匹配：`<base>/<rel>` 精确
+   * 命中根级文件，再加一条任意目录前缀的同名模式覆盖深层出现
+   * （rel 本身可含 glob）。
+   */
+  function redactExcludeFlags(base) {
+    return sensitivePaths().flatMap((rel) => [`--exclude=${base}/${rel}`, `--exclude=*/${rel}`]);
+  }
+
+  /**
+   * 列出 ~/.dsh 中现存的敏感文件（相对路径），不拷贝。供跳过 vault 刷新
+   * 的内部快照（pre-restore）仍能记录正确的脱敏清单边车。
+   */
+  async function existingSensitive(dshHome) {
+    const out = [];
+    for (const rel of sensitivePaths()) {
+      const ok = await fsStat(`${dshHome}/${rel}`).then(() => true, () => false);
+      if (ok) out.push(rel);
+    }
+    return out;
+  }
+
+  /**
+   * 刷新本机 vault：把 ~/.dsh 中现存的敏感文件按相对路径镜像到
+   * `<备份目录>/vault/`（先清空旧镜像，vault 永远对应最新一次备份）。
+   * 返回实际入库的相对路径列表。目录 700 / 文件 600（POSIX）。
+   */
+  async function refreshVault(dshHome, home, signal) {
+    const { root } = paths();
+    const rels = sensitivePaths();
+    const vaultDir = `${root}/${VAULT_DIR}`;
+    if (!rels.length) return [];
+    if (signal?.aborted) throw new Error('操作已取消');
+    await rm(vaultDir, { recursive: true, force: true });
+    const stored = [];
+    for (const rel of rels) {
+      const src = `${dshHome}/${rel}`;
+      const ok = await fsStat(src).then(() => true, (err) => {
+        if (err && err.code === 'ENOENT') return false;
+        throw err;
+      });
+      if (!ok) continue;
+      const dst = `${vaultDir}/${rel}`;
+      await mkdir(dirname(dst), { recursive: true });
+      await copyFile(src, dst);
+      stored.push(rel);
+    }
+    if (stored.length && !IS_WIN) {
+      const chmod = await ctx.subprocess.resolveExecutable('chmod');
+      try {
+        await spawnRun([chmod, '-R', 'go-rwx', vaultDir], home, signal);
+      } catch {
+        // chmod 失败不阻断备份：vault 已在用户私有目录下，权限收紧是纵深防御
+      }
+    }
+    return stored;
+  }
+
   function stampNow() {
     const now = new Date();
     const pad = (n, w = 2) => String(n).padStart(w, '0');
@@ -289,12 +377,18 @@ 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 !== keepName && d.name !== `${keepName}.sha256`)
+      .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);
   }
 
+  /** 归档伴生边车集：轮换、删除与 GitHub 同步对同一归档统一处理的文件列表。 */
+  function sidecarsFor(name) {
+    return [name, `${name}.sha256`, `${name}.meta.json`, `${name}.redacted.json`];
+  }
+
   async function listBackups() {
     const { root } = paths();
     let dirents;
@@ -363,11 +457,21 @@ export function apply(ctx, pluginConfig) {
 
     // tar 以备份目录为 cwd、用纯文件名传 -f：Windows 上 GNU tar（msys）会把
     // 含盘符冒号的绝对路径当远程归档（"Cannot connect to C"），bsdtar 则两者皆可。
+    // 敏感文件先从归档排除（redactExcludeFlags），其明文副本进本机 vault。
+    // skipVault（pre-restore 快照）：数据可能正待恢复/已损，刷新 vault 会把
+    // 仅存的凭据副本清掉——只列清单不拷贝，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', ...extraExcludes(), '-czf', name, '-C', parent, base], root, signal);
+    await spawnRun([tar, '--exclude=*node_modules*', '--exclude=.system', ...redactExcludeFlags(base), ...extraExcludes(), '-czf', name, '-C', parent, base], root, signal);
 
     const shaText = await sha256File(out, home, signal);
     await writeOwned(`${out}.sha256`, `${shaText}  ${out}\n`);
+    // 脱敏清单边车：恢复侧据其判断归档是否脱敏、需要从 vault 还原哪些文件。
+    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`);
 
     // 安全：备份含明文凭据（.credentials.yaml / qq-bridge/config.json），收紧为仅本人可读写。
     // Windows 无 chmod，用户目录 ACL 默认私有。
@@ -380,7 +484,7 @@ export function apply(ctx, pluginConfig) {
     const all = await listBackups();
     const stale = all.slice(keepN).map((b) => b.name);
     if (stale.length) {
-      await removeFiles(stale.flatMap((n) => [n, `${n}.sha256`]), root, signal);
+      await removeFiles(stale.flatMap((n) => sidecarsFor(n)), root, signal);
     }
 
     // GitHub 同步（失败不回滚备份；状态记入 auto.json）
@@ -428,17 +532,15 @@ export function apply(ctx, pluginConfig) {
   }
 
   /**
-   * 把当前备份集推送到 GitHub 仓库。工作树位于 `<备份目录>/.github-sync`：
-   * 归档与边车复制进去，git add -A 同时记录轮换删除，commit 后
-   * `push HEAD:main --force-with-lease`。https 远端的 token 只写入工作树内
-   * 的 .git-credentials（credential helper），不进进程参数。
+   * 校验同步配置并准备好同步工作树（init + remote + token 凭据 + gitignore）。
+   * 推送（githubSync）与拉取（githubPull）共用；未配置/缺 token 返回 reason。
    */
-  async function githubSync(signal) {
+  async function ensureSyncWorktree(signal) {
     const { root } = paths();
     const cfg = githubConfig();
-    if (!cfg) return { skipped: '未配置 githubRepo（cordis.yml config.githubRepo）' };
+    if (!cfg) return { reason: '未配置 githubRepo（cordis.yml config.githubRepo）' };
     if (cfg.repo.startsWith('https://') && !cfg.token) {
-      return { skipped: 'https 远端缺少 token（环境变量 DSH_BACKUP_GITHUB_TOKEN 或 GITHUB_TOKEN）' };
+      return { reason: 'https 远端缺少 token（环境变量 DSH_BACKUP_GITHUB_TOKEN 或 GITHUB_TOKEN）' };
     }
     const syncDir = `${root}/${SYNC_DIR}`;
     const git = await ctx.subprocess.resolveExecutable('git');
@@ -481,16 +583,37 @@ export function apply(ctx, pluginConfig) {
     }
     // token 文件绝不能进仓库：git add -A 会把它当普通文件提交
     await writeOwned(`${syncDir}/.gitignore`, '.git-credentials\n');
+    return { cfg, syncDir, git };
+  }
+
+  /**
+   * 把当前备份集推送到 GitHub 仓库。工作树位于 `<备份目录>/.github-sync`：
+   * 归档与边车复制进去，git add -A 同时记录轮换删除，commit 后
+   * `push HEAD:main --force-with-lease`。https 远端的 token 只写入工作树内
+   * 的 .git-credentials（credential helper），不进进程参数。
+   */
+  async function githubSync(signal) {
+    const { root } = paths();
+    const wt = await ensureSyncWorktree(signal);
+    if (wt.reason) return { skipped: wt.reason };
+    const { syncDir, git } = wt;
+    // pull 之后本地工作树可能领先/分叉：push 前先对齐远端，保证 force-with-lease
+    // 有基准（远端被其他机器推送过时直接 reset 到远端再叠加本地备份集）。
+    try {
+      await spawnRun([git, 'fetch', 'origin', 'main'], syncDir, signal);
+      await spawnRun([git, 'reset', '--hard', 'origin/main'], syncDir, signal);
+    } catch {
+      // 远端尚无 main（首次推送）或不可达：继续走本地提交路径，push 自会报错
+    }
 
     // 镜像工作树：只保留 .gitignore、凭据文件（.git-credentials，token
     // 配置时在 keep 集内保留）与当前备份集（归档+边车），其余文件
     // （旧副本、误入杂物）清理——git add -A 因此只会收录归档；轮换
     // 删除与误入文件一并同步移除。
     const keep = new Set(['.gitignore']);
-    if (cfg.token) keep.add('.git-credentials');
+    if (wt.cfg.token) keep.add('.git-credentials');
     for (const b of await listBackups()) {
-      keep.add(b.name);
-      keep.add(`${b.name}.sha256`);
+      for (const f of sidecarsFor(b.name)) keep.add(f);
     }
     let entries = [];
     try {
@@ -511,8 +634,14 @@ export function apply(ctx, pluginConfig) {
         tooBig.push(b.name);
         continue;
       }
-      await copyFile(`${root}/${b.name}`, `${syncDir}/${b.name}`);
-      await copyFile(`${root}/${b.name}.sha256`, `${syncDir}/${b.name}.sha256`);
+      for (const f of sidecarsFor(b.name)) {
+        await copyFile(`${root}/${f}`, `${syncDir}/${f}`).catch((err) => {
+          // .redacted.json 等可选边车随归档存在性浮动：缺失即跳过（ENOENT），
+          // 其余复制错误（EACCES 等）照常抛出——同步镜像必须与源一致。
+          if (err && err.code === 'ENOENT') return;
+          throw err;
+        });
+      }
     }
     await spawnRun([git, 'add', '-A'], syncDir, signal);
     const status = await spawnRun([git, 'status', '--porcelain'], syncDir, signal);
@@ -530,6 +659,65 @@ export function apply(ctx, pluginConfig) {
     return `GitHub 同步: ${s.skipped || '无变更'}${s.tooBig?.length ? `\n跳过超大文件: ${s.tooBig.join(', ')}` : ''}`;
   }
 
+  /**
+   * 从 GitHub 同步仓库拉取备份集到本地备份目录（新机恢复的第一步）：
+   * fetch + reset --hard origin/main 对齐远端，然后把本地缺失的归档与
+   * 边车从工作树拷回备份目录。仅拉取，不自动恢复——覆盖式恢复必须经
+   * restore 的校验/预览/快照链，由用户显式发起。
+   * 拉回的归档先做 sha256 校验（边车随仓库走），损坏即报且不落列表。
+   */
+  async function githubPull(signal) {
+    const { root, home } = paths();
+    const wt = await ensureSyncWorktree(signal);
+    if (wt.reason) throw new Error(wt.reason);
+    const { syncDir, git } = wt;
+    await spawnRun([git, 'fetch', 'origin', 'main'], syncDir, signal);
+    await spawnRun([git, 'reset', '--hard', 'origin/main'], syncDir, signal);
+
+    let entries = [];
+    try {
+      entries = await readdir(syncDir, { withFileTypes: true });
+    } catch {
+      entries = [];
+    }
+    const wanted = entries
+      .filter((e) => e.isFile() && /^dsh-[A-Za-z0-9._-]+\.tar\.gz$/.test(e.name))
+      .map((e) => e.name);
+    const pulled = [];
+    const corrupt = [];
+    for (const name of wanted) {
+      const exists = await fsStat(`${root}/${name}`).then(() => true, () => false);
+      if (exists) continue;
+      // 先拷到临时名，sha256 校验通过再转正：损坏归档绝不进备份列表
+      const staging = `${root}/.pull-${name}`;
+      await copyFile(`${syncDir}/${name}`, staging);
+      let shaOk = false;
+      try {
+        const text = await readFile(`${syncDir}/${name}.sha256`, 'utf8');
+        const expected = text.trim().split(/\s+/)[0];
+        const actual = await sha256File(staging, home, signal);
+        shaOk = /^[0-9a-f]{64}$/.test(expected) && actual === expected;
+      } catch {
+        shaOk = false;
+      }
+      if (!shaOk) {
+        await unlink(staging).catch(() => {});
+        corrupt.push(name);
+        continue;
+      }
+      await rename(staging, `${root}/${name}`);
+      // 边车随归档转正（缺失的可选边车跳过）
+      for (const side of [`${name}.sha256`, `${name}.meta.json`, `${name}.redacted.json`]) {
+        await copyFile(`${syncDir}/${side}`, `${root}/${side}`).catch((err) => {
+          if (err && err.code === 'ENOENT') return;
+          throw err;
+        });
+      }
+      pulled.push(name);
+    }
+    return { pulled, corrupt, total: wanted.length };
+  }
+
   // ---------- Web 下载路由（仅 loopback，附件形式） ----------
   async function handleDownload(req, res) {
     try {
@@ -590,11 +778,11 @@ export function apply(ctx, pluginConfig) {
     throw new Error(`"${selector}" 匹配多份备份，请加长前缀：\n${hits.slice(0, 5).map((b) => `  ${b.name}`).join('\n')}`);
   }
 
-  /** 删除指定备份（归档 + 校验边车）；选择器经 pickArchive 精确匹配，杜绝路径穿越。 */
+  /** 删除指定备份（归档 + 全部边车）；选择器经 pickArchive 精确匹配，杜绝路径穿越。 */
   async function removeBackup(selector, signal) {
     const { root } = paths();
     const picked = await pickArchive(selector);
-    await removeFiles([picked.name, `${picked.name}.sha256`], root, signal);
+    await removeFiles(sidecarsFor(picked.name), root, signal);
     return { ok: true, name: picked.name, summary: `已删除备份: ${picked.name}` };
   }
 
@@ -641,7 +829,47 @@ export function apply(ctx, pluginConfig) {
     return { type: f[0][0], name: f.slice(nameIdx).join(' ').replace(/\/$/, '') };
   }
 
-  async function restoreArchive(selector, dryRun, signal) {
+  /**
+   * 读取归档的机器元数据 / 脱敏清单边车，构造恢复预检信息（边车缺失的
+   * v0.6.x 老归档返回 redacted=null、host=null，预检静默降级）。
+   */
+  async function readArchiveMeta(archiveName) {
+    const { root } = paths();
+    let meta = null;
+    let redactedFiles = null;
+    try {
+      meta = JSON.parse(await readFile(`${root}/${archiveName}.meta.json`, 'utf8'));
+    } catch {
+      // 老归档无 meta 边车
+    }
+    try {
+      redactedFiles = JSON.parse(await readFile(`${root}/${archiveName}.redacted.json`, 'utf8'))?.files ?? [];
+    } catch {
+      // 未脱敏（或老归档）无清单
+    }
+    return { meta, redactedFiles };
+  }
+
+  /**
+   * 恢复预检：跨机（home 与备份机器不一致）绝对路径提示 + 脱敏归档的
+   * vault 可还原性 + 随归档恢复的 profile 依赖（node_modules 被排除，
+   * 恢复后需重装）。返回人类可读的提示行数组（无提示返回空）。
+   */
+  function preflightLines(preflight, profileDirs) {
+    const lines = [];
+    if (preflight.homeChanged) {
+      lines.push(`⚠️ 备份来自另一台机器/用户目录（${preflight.sourceHost ?? '未知主机'}，${preflight.sourceHome}），settings 内的绝对路径可能需要调整`);
+    }
+    if (Array.isArray(preflight.redactedFiles)) {
+      lines.push(`🔐 该归档已脱敏：${preflight.redactedFiles.length} 个凭据文件不随归档走，恢复时从本机 vault 还原（跨机恢复需重填）`);
+    }
+    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}`;
@@ -683,14 +911,31 @@ export function apply(ctx, pluginConfig) {
       throw new Error(`归档包含不安全条目（拒绝恢复）：${bad.slice(0, 3).join(', ')}，恢复已中止`);
     }
 
-    if (dryRun) return { archive, files: entries.length, sample: entries.slice(0, 12), aside: null, snapshotPath: null, dryRun: true };
+    // 预检（dry-run 与真实恢复共用）：跨机 home 对比 + 脱敏清单 + profile 依赖。
+    const { meta, redactedFiles } = await readArchiveMeta(picked.name);
+    const preflight = {
+      homeChanged: Boolean(meta && typeof meta.home === 'string' && meta.home !== home),
+      sourceHost: meta?.host ?? null,
+      sourceHome: meta?.home ?? null,
+      redactedFiles,
+    };
+    const profileDirs = [...new Set(entries
+      .filter((n) => n.startsWith(`${base}/profiles/`) && n.endsWith('/package.json'))
+      .map((n) => n.slice(`${base}/profiles/`.length).split('/')[0]))];
+
+    if (dryRun) {
+      return {
+        archive, files: entries.length, sample: entries.slice(0, 12), aside: null, snapshotPath: null, dryRun: true,
+        preflight: preflightLines(preflight, profileDirs),
+      };
+    }
 
     // 恢复前自动快照当前数据，并把当前数据移到旁边（而非合并覆盖）。
     // 快照用 dsh-pre-restore- 前缀与用户常规备份区分，经 listBackups 过滤
     // 后不进列表/轮换/latest 选择；每次恢复清掉上一次的快照防累积。
-    const snapshot = await doBackup(undefined, signal, { namePrefix: 'dsh-pre-restore-' });
-    await prunePreRestoreSnapshots(snapshot.name, signal);
-    let aside = null;
+    // 现有数据存在性先行：~/.dsh 已缺失（数据全失/新机首恢复）时没有可
+    // 快照的内容，跳过快照直接解压——先快照后判存在的旧序会让 tar 对
+    // 不存在的 .dsh 报错，恢复在最需要的场景反而失败。
     let current = false;
     try {
       await fsStat(dshHome);
@@ -701,13 +946,91 @@ export function apply(ctx, pluginConfig) {
       if (!err || err.code !== 'ENOENT') throw err;
       current = false;
     }
+    const snapshot = current
+      ? await doBackup(undefined, signal, { namePrefix: 'dsh-pre-restore-', skipVault: true })
+      : null;
+    if (snapshot) await prunePreRestoreSnapshots(snapshot.name, signal);
+    let aside = null;
     if (current) {
       const asideName = `${base}.pre-restore-${stampNow()}`;
       await renameBeside(parent, base, asideName, signal);
       aside = `${parent}/${asideName}`;
     }
     await spawnRun([tar, '-xzf', picked.name, '-C', parent], root, signal);
-    return { archive, files: entries.length, sample: [], aside, snapshotPath: snapshot.path, dryRun: false };
+
+    // vault 还原：脱敏归档恢复出的 ~/.dsh 不含凭据文件，从本机 vault 拷回。
+    // vault 为空（跨机首恢复）时逐项记入 missing，由调用方提示重填——凭据
+    // 无法从归档恢复是脱敏设计的直接代价，明确告知优于静默缺文件。
+    const vaultRestored = [];
+    const vaultMissing = [];
+    if (Array.isArray(redactedFiles) && redactedFiles.length) {
+      const vaultDir = `${root}/${VAULT_DIR}`;
+      for (const rel of redactedFiles) {
+        const src = `${vaultDir}/${rel}`;
+        const have = await fsStat(src).then(() => true, (err) => {
+          if (err && err.code === 'ENOENT') return false;
+          throw err;
+        });
+        if (!have) {
+          vaultMissing.push(rel);
+          continue;
+        }
+        const dst = `${dshHome}/${rel}`;
+        await mkdir(dirname(dst), { recursive: true });
+        await copyFile(src, dst);
+        vaultRestored.push(rel);
+      }
+    }
+
+    // 可选依赖重装：node_modules 不随归档，--sync-deps 对每个恢复出的 profile
+    // 跑 pnpm install --frozen-lockfile（与 DSH 自身的装配套路一致）。pnpm
+    // 不可用时降级为提示，不判恢复失败——配置与会话已经恢复到位。
+    const deps = { installed: [], failed: [], note: null };
+    if (opts?.syncDeps && profileDirs.length) {
+      try {
+        const pnpm = await ctx.subprocess.resolveExecutable('pnpm');
+        for (const p of profileDirs) {
+          try {
+            await spawnRun([pnpm, 'install', '--frozen-lockfile'], `${dshHome}/profiles/${p}`, signal);
+            deps.installed.push(p);
+          } catch (err) {
+            // lockfile 与声明漂移时 frozen 会失败：退回普通 install 再试一次
+            try {
+              await spawnRun([pnpm, 'install'], `${dshHome}/profiles/${p}`, signal);
+              deps.installed.push(p);
+            } catch (err2) {
+              deps.failed.push(p);
+            }
+          }
+        }
+      } catch {
+        deps.note = '未找到 pnpm，请在各 profile 目录手动执行 pnpm install';
+      }
+    }
+
+    return {
+      archive, files: entries.length, sample: [], aside, snapshotPath: snapshot ? snapshot.path : null, dryRun: false,
+      preflight: preflightLines(preflight, profileDirs), vaultRestored, vaultMissing, deps, profiles: profileDirs,
+    };
+  }
+
+  /** 恢复结果的人类可读汇总（命令、模型工具与面板共用）。 */
+  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 使恢复的会话与配置生效。');
+    return lines.join('\n');
   }
 
   // ---------- 自动备份与 GitHub 同步状态（落盘，重启续跑） ----------
@@ -805,7 +1128,7 @@ export function apply(ctx, pluginConfig) {
   // ---------- /backup 命令 ----------
   ctx.commands.register({
     name: 'backup',
-    description: '备份/恢复 DSH 数据；子命令: list | verify [前缀|all] | restore <前缀|latest> [--dry-run] | auto [N小时|off] | [--keep N]',
+    description: '备份/恢复 DSH 数据；子命令: list | verify [前缀|all] | restore <前缀|latest> [--dry-run] [--sync-deps] | auto [N小时|off] | github status|sync|pull|repo | [--keep N]',
     handler: async (invocation) => {
       const input = invocation.rawInput.trim();
       try {
@@ -839,15 +1162,10 @@ export function apply(ctx, pluginConfig) {
 
         if (head === 'restore') {
           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);
-          if (r.dryRun) {
-            return { kind: 'success', text: `📦 恢复预览（未写入）\n  归档: ${r.archive}\n  条目: ${r.files} 项\n${r.sample.map((s) => `    ${s}`).join('\n')}` };
-          }
-          return {
-            kind: 'success',
-            text: `✅ 恢复完成\n  来源: ${r.archive}（${r.files} 项）\n  恢复前快照: ${r.snapshotPath}\n${r.aside ? `  旧数据已移至: ${r.aside}\n` : ''}  请重启 dsh 使恢复的会话与配置生效。`,
-          };
+          const r = await restoreArchive(sel, dryRun, invocation.signal, { syncDeps });
+          return { kind: 'success', text: summarizeRestore(r) };
         }
 
         if (head === 'github') {
@@ -877,6 +1195,27 @@ export function apply(ctx, pluginConfig) {
             }
             return { kind: 'success', text: summarizeSync(s) };
           }
+          if (arg === 'pull') {
+            // /backup github pull [--restore <前缀|latest>]：拉取不自动恢复（覆盖
+            // 式恢复必须走显式 restore），--restore 由用户点名后才执行。
+            const restoreIdx = parts.indexOf('--restore');
+            const restoreSel = restoreIdx >= 0 ? parts[restoreIdx + 1] : null;
+            const p = await githubPull(invocation.signal);
+            const lines = [];
+            if (p.pulled.length) {
+              lines.push(`✅ 已拉取 ${p.pulled.length} 份备份:\n${p.pulled.map((n) => `  ${n}`).join('\n')}`);
+            } else {
+              lines.push(`远端共 ${p.total} 份备份，本地均已存在。`);
+            }
+            if (p.corrupt.length) lines.push(`⚠️ sha256 校验失败、已跳过: ${p.corrupt.join(', ')}`);
+            if (restoreSel) {
+              const r = await restoreArchive(restoreSel, false, invocation.signal);
+              lines.push(summarizeRestore(r));
+            } else {
+              lines.push('用 /backup restore <前缀|latest> [--dry-run] 恢复；跨机恢复后凭据需按提示重填。');
+            }
+            return { kind: 'success', text: lines.join('\n') };
+          }
           if (arg === 'status') {
             const cfg = githubConfig();
             const text = cfg
@@ -884,7 +1223,7 @@ export function apply(ctx, pluginConfig) {
               : 'GitHub 同步未配置：/backup github repo <owner/repo> 设置，或在 cordis.yml 的 config.githubRepo 配置。';
             return { kind: 'success', text };
           }
-          return { kind: 'error', text: '用法: /backup github status|sync|repo <地址|off>' };
+          return { kind: 'error', text: '用法: /backup github status|sync|pull [--restore <前缀|latest>]|repo <地址|off>' };
         }
 
         if (head === 'delete' || head === 'rm') {
@@ -926,13 +1265,14 @@ export function apply(ctx, pluginConfig) {
   // ---------- backup_dsh 模型工具 ----------
   ctx.tools.register(defineTool({
     name: 'backup_dsh',
-    description: '备份、校验或恢复 DSH 用户数据（~/.dsh 的会话、配置、技能、凭据）。mode=backup 立即备份（keep 指定保留份数）；mode=list 列出备份；mode=verify 校验完整性（selector=前缀或 all，缺省最新一份）；mode=restore 恢复（selector=前缀或 latest，dryRun 仅预览；恢复前自动校验并快照当前数据）；mode=auto 设置定时备份（hours 间隔小时数，0=关闭，缺省查询）。注意：备份包含明文凭据，请勿将备份目录同步到不受信位置。',
+    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=关闭，缺省查询）。',
     parameters: {
       mode: { type: 'string', required: true, enum: ['backup', 'list', 'verify', 'restore', 'auto'], description: 'backup=执行备份，list=列出备份，verify=校验完整性，restore=恢复，auto=定时备份' },
       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 时仅预览恢复内容，不写入' },
+      syncDeps: { type: 'boolean', description: 'mode=restore 时恢复后对各 profile 执行 pnpm install 重装插件依赖' },
     },
     output: {
       schema: { type: 'object', additionalProperties: true },
@@ -962,12 +1302,7 @@ export function apply(ctx, pluginConfig) {
         }
         if (mode === 'restore') {
           const r = await restoreArchive(selector || 'latest', Boolean(args && args.dryRun), signal);
-          if (r.dryRun) return { ok: true, summary: `恢复预览（未写入）: ${r.archive}\n条目 ${r.files} 项，含:\n${r.sample.map((s) => `  ${s}`).join('\n')}` };
-          return {
-            ok: true,
-            path: r.archive,
-            summary: `恢复完成: ${r.archive}（${r.files} 项）\n恢复前快照: ${r.snapshotPath}\n${r.aside ? `旧数据已移至: ${r.aside}\n` : ''}请重启 dsh 生效。`,
-          };
+          return { ok: true, path: r.archive, summary: summarizeRestore(r) };
         }
         if (mode === 'auto') {
           const h = args && args.hours !== undefined ? args.hours : null;
@@ -1032,7 +1367,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, summary: `归档 ${r.files} 项` };
+          return { ok: true, dryRun: true, archive: r.archive, files: r.files, sample: r.sample, preflight: r.preflight ?? [], summary: summarizeRestore(r) };
         }
         return {
           ok: true,
@@ -1041,7 +1376,10 @@ export function apply(ctx, pluginConfig) {
           files: r.files,
           aside: r.aside,
           snapshotPath: r.snapshotPath,
-          summary: `恢复完成（${r.files} 项）${r.aside ? `\n旧数据已移至 ${r.aside}` : ''}\n请重启 dsh 生效。`,
+          preflight: r.preflight ?? [],
+          vaultRestored: r.vaultRestored ?? [],
+          vaultMissing: r.vaultMissing ?? [],
+          summary: summarizeRestore(r),
         };
       } catch (err) {
         return { ok: false, dryRun: Boolean(dryRun), summary: String(err && err.message ? err.message : err) };
@@ -1090,6 +1428,19 @@ export function apply(ctx, pluginConfig) {
         return { ok: false, summary: message, pushed: false, tooBig: [] };
       }
     },
+    githubPull: async (signal) => {
+      try {
+        const p = await githubPull(signal);
+        const lines = [];
+        if (p.pulled.length) lines.push(`已拉取 ${p.pulled.length} 份备份`);
+        else lines.push(`远端共 ${p.total} 份备份，本地均已存在。`);
+        if (p.corrupt.length) lines.push(`sha256 校验失败、已跳过: ${p.corrupt.join(', ')}`);
+        lines.push('在上方备份列表中选择归档恢复；跨机恢复后凭据需按提示重填。');
+        return { ok: true, summary: lines.join('\n'), pulled: p.pulled, corrupt: p.corrupt, total: p.total };
+      } catch (err) {
+        return { ok: false, summary: String(err && err.message ? err.message : err), pulled: [], corrupt: [], total: 0 };
+      }
+    },
     removeEntry: async (selector, signal) => {
       try {
         const r = await removeBackup(selector || 'latest', signal);