@xiaoyuyu6420/dsh-backup 0.11.2 → 0.12.0

package/lib/index.js

@@ -43,7 +43,7 @@
  */
 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 { mkdir, open, copyFile, chmod, readdir, readFile, rename, rm, stat as fsStat, unlink, writeFile, link } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { hostname } from 'node:os';
 import { basename, dirname, join } from 'node:path';
@@ -396,6 +396,8 @@ const PANEL_INVOCATIONS = Object.freeze([
   panelDescriptor('setGithubRepo', ['repo']),
   panelDescriptor('doctorScan', [], true),
   panelDescriptor('doctorRepair', ['selector'], true),
+  panelDescriptor('migrateCheck', [], true),
+  panelDescriptor('setGithubToken', ['token']),
 ]);
 
 /**
@@ -469,6 +471,16 @@ class BackupPanelService extends TypertRemoteService {
   doctorRepair(selector, signal) {
     return this.ops.doctorRepair(selector, signal);
   }
+
+  /** 迁移预检：只读扫描全部会话日志（含 v1/v2/v3 各代），预测升级后哪些会话打不开。 */
+  migrateCheck(signal) {
+    return this.ops.migrateCheck(signal);
+  }
+
+  /** 配置/清除 GitHub 同步 token（面板直配；本机存储，不进归档不进同步）。 */
+  setGithubToken(token) {
+    return this.ops.setGithubToken(token);
+  }
 }
 
 export function apply(ctx, pluginConfig) {
@@ -1089,12 +1101,75 @@ export function apply(ctx, pluginConfig) {
         : '');
     if (!raw) return null;
     const env = ctx.get('launchEnvironment');
-    const token = env?.get('DSH_BACKUP_GITHUB_TOKEN')?.value || env?.get('GITHUB_TOKEN')?.value;
+    // token 来源优先级：面板/聊天配置（本机备份目录 github.token）> 环境变量。
+    // 面板值存在本机、不进归档也不进同步，跨机需重填——与凭据脱敏同一哲学。
+    const token = storedGithubToken
+      || env?.get('DSH_BACKUP_GITHUB_TOKEN')?.value
+      || env?.get('GITHUB_TOKEN')?.value;
     // 本地路径（测试/自托管）或 http(s) 全 URL 直接使用，否则视为 owner/repo。
     const repo = raw.includes('://') || /^[A-Za-z]:[\\/]|^\//.test(raw) ? raw : `https://github.com/${raw}.git`;
     return { repo: stripUserinfo(repo.split('\\').join('/')), token };
   }
 
+  // ---------- GitHub token：面板/聊天直配（本机存储） ----------
+  const GITHUB_TOKEN_FILE = 'github.token';
+  let storedGithubToken = null;
+
+  /** 启动时从备份目录根读入面板配置的 token（0600 文件）；缺失/不可读 = null。 */
+  async function loadStoredGithubToken() {
+    const { root } = paths();
+    try {
+      const t = (await readFile(`${root}/${GITHUB_TOKEN_FILE}`, 'utf8')).trim();
+      storedGithubToken = t || null;
+    } catch {
+      storedGithubToken = null;
+    }
+    return storedGithubToken;
+  }
+
+  /** token 形状校验：ghp_…/github_pat_…/40 位经典；拦住整段误粘贴的句子。非法返回原因。 */
+  function validateGithubToken(raw) {
+    const t = raw.trim();
+    if (!t) return 'token 不能为空（清除请用清除按钮或 /backup github token off）';
+    if (!/^[A-Za-z0-9_-]{20,255}$/.test(t)) return 'token 形状不对：应为 ghp_…/github_pat_… 或 40 位经典 token（字母数字与 _-，不含空格）';
+    return null;
+  }
+
+  /** 保存面板 token：备份目录根 github.token，独占创建 0600（同 vault 明文待遇）。 */
+  async function writeStoredGithubToken(t) {
+    const { root } = paths();
+    const file = `${root}/${GITHUB_TOKEN_FILE}`;
+    let fh;
+    try {
+      fh = await open(file, 'wx', 0o600);
+    } catch (e) {
+      if (!(e && e.code === 'EEXIST')) throw e;
+      fh = await open(file, 'w', 0o600);
+      if (!IS_WIN) await fh.chmod(0o600);
+    }
+    try {
+      await fh.writeFile(`${t}\n`, 'utf8');
+    } finally {
+      await fh.close();
+    }
+    if (!IS_WIN) await chmod(file, 0o600).catch(() => {});
+    storedGithubToken = t;
+  }
+
+  /** 清除面板 token（文件删除；环境变量不受影响）。 */
+  async function clearStoredGithubToken() {
+    const { root } = paths();
+    await rm(`${root}/${GITHUB_TOKEN_FILE}`, { force: true });
+    storedGithubToken = null;
+  }
+
+  /** 是否存在任何可用 token（面板存储或环境变量）——与是否配置仓库解耦，供状态徽标。 */
+  function hasGithubToken() {
+    if (storedGithubToken) return true;
+    const env = ctx.get('launchEnvironment');
+    return Boolean(env?.get('DSH_BACKUP_GITHUB_TOKEN')?.value || env?.get('GITHUB_TOKEN')?.value);
+  }
+
   /** 校验仓库地址格式（owner/repo、完整 URL 或本地路径），非法返回原因。 */
   function validateRepo(raw) {
     if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(raw)) return null;
@@ -1111,7 +1186,7 @@ export function apply(ctx, pluginConfig) {
     const cfg = githubConfig();
     if (!cfg) return { reason: '未配置 githubRepo（cordis.yml config.githubRepo）' };
     if (cfg.repo.startsWith('https://') && !cfg.token) {
-      return { reason: 'https 远端缺少 token（环境变量 DSH_BACKUP_GITHUB_TOKEN 或 GITHUB_TOKEN）' };
+      return { reason: 'https 远端缺少 token：可在面板「GitHub Token」或 /backup github token <token> 配置，或环境变量 DSH_BACKUP_GITHUB_TOKEN / GITHUB_TOKEN' };
     }
     const syncDir = `${root}/${SYNC_DIR}`;
     const git = await ctx.subprocess.resolveExecutable('git');
@@ -1983,7 +2058,7 @@ export function apply(ctx, pluginConfig) {
   }
 
   /** 有界递归收集会话日志文件（相对 ~/.dsh 路径）；跳过依赖/系统目录。 */
-  async function collectSessionLogs(dir, relPrefix, depth, out) {
+  async function collectSessionLogs(dir, relPrefix, depth, out, names = SESSION_LOG_NAMES) {
     if (depth > SCAN_MAX_DEPTH || out.length >= SCAN_MAX_FILES) return;
     let dirents;
     try {
@@ -1996,8 +2071,8 @@ export function apply(ctx, pluginConfig) {
       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)) {
+        await collectSessionLogs(`${dir}/${d.name}`, rel, depth + 1, out, names);
+      } else if (names.has(d.name)) {
         out.push({ abs: `${dir}/${d.name}`, rel });
       }
     }
@@ -2071,6 +2146,238 @@ export function apply(ctx, pluginConfig) {
     return { scanned: files.length, files, corrupt, corruptCount: corrupt.length, skippedCount };
   }
 
+  // ---------- 迁移预检（migrate-check） ----------
+  //
+  // 预测「宿主升级 / 旧会话被再次打开」后哪些会话会打不开。宿主的会话格式迁移
+  // 是读时触发的纯函数：任何 open 都会跑迁移解码，写开再把旧代日志发布成 v3
+  // 新代文件——旧代文件永不改写，POSIX 硬链接原子发布（exFAT 等无硬链接文件
+  // 系统在这一步 ENOTSUP，官方讨论 #6358）。本预检把宿主
+  // @deepseek-ai/dsh-session-format* 的冻结事件清单与静态拒绝规则烤入本地
+  // （0.1.5-rc.2 校准，与 0.11.2 对齐 isHeaderLine 同一套路），覆盖"解析即判"
+  // 的规则；需要重放迁移过程的规则（chunk 折叠溯源、引用重映射、worker 复核）
+  // 不在覆盖范围，结果里如实标注。三层判定：fail=会话将打不开；migratable=
+  // 旧代但静态规则全过（首次写开会发布 v3 新代）；ok=已是当前代。
+  const MIGRATE_CURRENT_VERSION = 3;
+  /** 物理代文件名 ↔ 格式代（宿主 sessionFormatLogFilename；文件名与 header 不一致宿主拒载）。 */
+  const MIGRATE_LOG_NAMES = [
+    { name: 'session.jsonl', version: 0 },
+    { name: 'session.v1.jsonl', version: 1 },
+    { name: 'session.v2.jsonl', version: 2 },
+    { name: 'session.v3.jsonl', version: 3 },
+  ];
+  const MIGRATE_LOG_SET = new Set(MIGRATE_LOG_NAMES.flatMap((g) => [g.name, `${g.name}.zstd`]));
+  // 冻结事件清单（RELEASED_V0_EVENT_TYPES / RELEASED_V2_EVENT_TYPES，宿主
+  // 按契约不增长旧代清单）；migration 对清单外类型连 ignorable 也拒（#6355）。
+  const MIGRATE_V0_EVENT_TYPES = new Set(['agent-preset/selected', 'agent/inbox/spliced', 'approval/asked', 'approval/decided', 'approval/policy', 'assistant/chunk', 'assistant/message', 'command/done', 'command/run', 'compaction/end', 'compaction/prune', 'compaction/start', 'compaction/summary', 'feedback/record', 'goal/change', 'hook/invoked', 'hook/result', 'llm/retry', 'llm/retry-started', 'model/selection', 'permission/preset', 'plan/mode', 'request/context', 'request/header', 'sandbox/mode', 'schedule/change', 'session-log-deepseek/delivery-accepted', 'session/end-seed', 'session/title', 'session/title-llm-request', 'step/end', 'step/start', 'subagent/descriptor', 'subagent/model-selection-policy', 'team/member', 'team/message/delivered', 'team/message/queued', 'team/task', 'todo/write', 'tool-workflow/agent-end', 'tool-workflow/agent-start', 'tool-workflow/run-end', 'tool-workflow/run-start', 'tool/call', 'tool/code-dispatch', 'tool/code-dispatch-start', 'tool/result', 'turn/end', 'turn/start', 'user/message', 'web/deepseek-search-llm-request']);
+  const MIGRATE_V2_EVENT_TYPES = new Set(['agent-preset/selected', 'agent/inbox/spliced', 'approval/asked', 'approval/decided', 'approval/policy', 'assistant/attempt', 'assistant/message', 'command/done', 'command/run', 'compaction/end', 'compaction/prune', 'compaction/start', 'compaction/summary', 'feedback/record', 'goal/change', 'hook/invoked', 'hook/result', 'llm/retry', 'llm/retry-started', 'model/selection', 'permission/preset', 'plan/mode', 'request/context', 'request/header', 'sandbox/mode', 'schedule/change', 'session-log-deepseek/delivery-accepted', 'session/end-seed', 'session/title', 'session/title-llm-request', 'step/end', 'step/start', 'subagent/descriptor', 'subagent/model-selection-policy', 'team/member', 'team/message/delivered', 'team/message/queued', 'team/task', 'todo/write', 'tool-workflow/agent-end', 'tool-workflow/agent-start', 'tool-workflow/run-end', 'tool-workflow/run-start', 'tool/call', 'tool/code-dispatch', 'tool/code-dispatch-start', 'tool/result', 'turn/end', 'turn/start', 'user/message', 'web/deepseek-search-llm-request']);
+  /** v0 侧退役类型（pre-react-loop 预发布形态；宿主点名拒绝）。 */
+  const MIGRATE_V0_RETIRED_TYPES = new Set(['request/header-delta', 'mode/set']);
+  /** 消息来源 kind 白名单（v3 侧 15 类；未知 kind 在 v2→v3 边被拒——#6355 主症状）。 */
+  const MIGRATE_SOURCE_KINDS = new Set(['user', 'plugin', 'model', 'tool', 'agent-instructions', 'session-reference', 'team-message', 'goal', 'skill-invocation', 'skill-catalog', 'coordinator', 'subagent-report', 'subagent-settled', 'webhook', 'agent-message']);
+  const MIGRATE_MAX_FINDINGS = 3;
+
+  /** 从物理文件名推格式代；非代文件名（未来扩展）返回 null。 */
+  function migrateFilenameVersion(fileName) {
+    const base = fileName.replace(/\.zstd$/, '');
+    const g = MIGRATE_LOG_NAMES.find((x) => x.name === base);
+    return g ? g.version : null;
+  }
+
+  /**
+   * 对一个解出的逻辑行流做迁移静态判定。header 解析失败返回 null（交给
+   * doctor 的损坏判定，这里不重复报）。返回 { sourceVersion, findings, total }
+   * ——findings 截断到前 MIGRATE_MAX_FINDINGS 条，total 是全量计数。
+   */
+  function migrateAnalyzeLines(lines, fileVersion) {
+    let header;
+    try {
+      header = JSON.parse(lines[0]);
+    } catch {
+      return null;
+    }
+    if (!header || typeof header !== 'object' || typeof header.version !== 'number') return null;
+    const sourceVersion = header.version;
+    const findings = [];
+    let total = 0;
+    const fail = (rule, detail) => {
+      total += 1;
+      if (findings.length < MIGRATE_MAX_FINDINGS) findings.push({ rule, detail });
+    };
+    if (sourceVersion > MIGRATE_CURRENT_VERSION) {
+      fail('newer-than-host', `header version=${sourceVersion} 高于本宿主可读的 v${MIGRATE_CURRENT_VERSION}——日志由更新版本的宿主写出，读/写都会被拒（提示语会要求升级宿主）`);
+      return { sourceVersion, findings, total };
+    }
+    if (fileVersion !== null && fileVersion !== sourceVersion) {
+      fail('name-version-mismatch', `文件名标 v${fileVersion}，header 标 v${sourceVersion}——宿主按不一致直接拒载`);
+      return { sourceVersion, findings, total };
+    }
+    // 事件行静态规则。seq 游标语义与 validateSessionLines 一致：v0 有 packed 行
+    //（一条行多个 chunk），v1 起一行一事件。
+    let nextSeq = 0;
+    for (let i = 1; i < lines.length; i++) {
+      let rec;
+      try {
+        rec = JSON.parse(lines[i]);
+      } catch {
+        fail('bad-json', `第 ${i + 1} 行不是合法 JSON（${snippet(String(lines[i]))}）`);
+        continue;
+      }
+      if (!rec || typeof rec !== 'object') continue;
+      const type = typeof rec.type === 'string' ? rec.type : undefined;
+      const isPacked = type === 'text-chunks' || type === 'reasoning-chunks' || type === 'tool-call-chunks';
+      // seq 密度：宿主要求 seq 与位置严格一致（手工改号不同步引用即打不开——#6348 根因）
+      if (isPacked) {
+        const members = Array.isArray(rec.data?.texts) ? rec.data.texts.length : Array.isArray(rec.data?.args) ? rec.data.args.length : 0;
+        nextSeq += Math.max(members, 0);
+      } else if (typeof rec.seq === 'number') {
+        if (rec.seq !== nextSeq) fail('seq-gap', `第 ${i + 1} 行 seq=${rec.seq}，期望 ${nextSeq}——seq 与位置不一致，宿主判 non-dense seq 拒载`);
+        nextSeq = rec.seq + 1;
+      }
+      if (sourceVersion === 0 && type) {
+        if (MIGRATE_V0_RETIRED_TYPES.has(type)) fail('retired-type', `第 ${i + 1} 行 ${type} 是预发布退役类型，迁移点名拒绝`);
+        else if (!MIGRATE_V0_EVENT_TYPES.has(type)) fail('unknown-type-v0', `第 ${i + 1} 行事件类型 "${type}" 不在 v0 冻结清单——迁移连 ignorable 也拒（第三方插件注入的历史事件，#6297/#6355）`);
+        if (type === 'request/header' && rec.data?.reason === 'fallback') fail('request-fallback', `第 ${i + 1} 行 request/header reason="fallback" 是预发布遗留，迁移拒绝`);
+        if (type === 'subagent/descriptor' && rec.data?.version !== 3) fail('descriptor-version', `第 ${i + 1} 行 subagent/descriptor version=${JSON.stringify(rec.data?.version)}——迁移只认 3（0.1.0/0.1.1 写的是 2，#6297/#6045 主症状）`);
+        if (type === 'permission/preset') {
+          const keys = Object.keys(rec.data ?? {});
+          if (!keys.every((k) => k === 'preset') || typeof rec.data?.preset !== 'string' || !rec.data.preset) fail('permission-preset-members', `第 ${i + 1} 行 permission/preset data 含 preset 之外的成员（如 origin）或 preset 非非空字符串——0.1.1 起写入 origin 的历史日志，迁移拒绝（#6297）`);
+        }
+      }
+      if (sourceVersion === 2 && type && !MIGRATE_V2_EVENT_TYPES.has(type)) fail('unknown-type-v2', `第 ${i + 1} 行事件类型 "${type}" 不在 v2 冻结清单——v2→v3 无法安全变换（ignorable 也拒）`);
+      if (sourceVersion === 2 && (type === 'tool/code-dispatch' || type === 'tool/code-dispatch-start')) fail('ptc-reserved-v2', `第 ${i + 1} 行 ${type} 是 v3 保留 PTC 标签，v2→v3 拒绝（ignorable 也拒）`);
+      if ((sourceVersion === 2 || sourceVersion === 3) && type === 'request/header' && rec.data?.header?.system !== undefined) fail('retired-header-system', `第 ${i + 1} 行 request/header 携带退役的 header.system——v2→v3 无法保留时序地提升它${sourceVersion === 3 ? '，当前代读取同样拒绝' : ''}`);
+      const kind = rec?.data?.source?.kind;
+      if (typeof kind === 'string' && !MIGRATE_SOURCE_KINDS.has(kind)) fail('unknown-source-kind', `第 ${i + 1} 行消息来源 kind="${kind}" 不在白名单——v2→v3 边拒绝（社区插件自定义 kind，#6355）`);
+    }
+    return { sourceVersion, findings, total };
+  }
+
+  /**
+   * 单文件迁移预检：解码（复用 doctor 的帧走查）→ 判代 → 静态规则。
+   * 返回 { verdict: 'fail'|'migratable'|'ok'|'skipped', version, findings, total, reason }。
+   */
+  async function migrateAnalyzeFile(f) {
+    const fileVersion = migrateFilenameVersion(f.abs.split('/').pop());
+    try {
+      const info = await fsStat(f.abs);
+      if (info.size === 0) return { verdict: 'fail', version: fileVersion, findings: [{ rule: 'empty', detail: '空文件（0 字节）' }], total: 1 };
+      if (f.abs.endsWith('.zstd') && !HAS_NODE_ZSTD) return { verdict: 'skipped', version: fileVersion, findings: [], total: 0, reason: `运行时无内置 zstd 解码（需 Node ≥22.15/23.8），跳过预检` };
+      if (info.size > HASH_MAX_BYTES) return { verdict: 'skipped', version: fileVersion, findings: [], total: 0, reason: '文件超过读入上限，未预检' };
+      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 { verdict: 'fail', version: fileVersion, findings: [{ rule: 'empty', detail: '解出的逻辑行为空' }], total: 1 };
+      const r = migrateAnalyzeLines(lines, fileVersion);
+      if (!r) return { verdict: 'skipped', version: fileVersion, findings: [], total: 0, reason: 'header 行不可解析——按损坏处理（doctor 体检覆盖），迁移预检跳过' };
+      if (r.total > 0) return { verdict: 'fail', version: r.sourceVersion, findings: r.findings, total: r.total };
+      return { verdict: r.sourceVersion < MIGRATE_CURRENT_VERSION ? 'migratable' : 'ok', version: r.sourceVersion, findings: [], total: 0 };
+    } catch (err) {
+      return { verdict: 'skipped', version: fileVersion, findings: [], total: 0, reason: `解码失败（${String(err && err.message ? err.message : err)}）——doctor 体检会按损坏处理` };
+    }
+  }
+
+  /** .credentials.yaml 是否还是扁平布局（顶层无 version 键）——宿主首次读档会原子替换成 version:1 且不可逆（#6358：旧宿主读不回 versioned）。 */
+  async function credentialsIsFlatLayout(dshHome) {
+    let text;
+    try {
+      text = await readFile(`${dshHome}/.credentials.yaml`, 'utf8');
+    } catch {
+      return false; // 不存在/读不了 → 无事可做
+    }
+    if (!text.trim()) return false;
+    return !/^version\s*:/m.test(text) && !/^"version"\s*:/m.test(text);
+  }
+
+  /** 凭据哨兵：把扁平布局的凭据文件存进 vault/preserved（保留最近 3 份），返回存档路径。 */
+  async function preserveFlatCredentials() {
+    const { dshHome, root } = paths();
+    if (!(await credentialsIsFlatLayout(dshHome))) return null;
+    const dir = `${root}/${VAULT_DIR}/preserved`;
+    await mkdir(dir, { recursive: true });
+    const dest = `${dir}/credentials-flat-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}.yaml`;
+    await copyFile(`${dshHome}/.credentials.yaml`, dest);
+    // 轮换：只留最近 3 份（按文件名时间戳排序即时间序）
+    const old = (await readdir(dir)).filter((n) => n.startsWith('credentials-flat-')).sort();
+    for (const n of old.slice(0, Math.max(old.length - 3, 0))) await rm(`${dir}/${n}`, { force: true });
+    return dest;
+  }
+
+  /** 环境级探测：硬链接支持（v3 发布用 fs.link，exFAT 等会 ENOTSUP）+ 凭据布局。 */
+  async function migrateProbeEnvironment() {
+    const { dshHome, root } = paths();
+    const env = { hardlink: true, hardlinkNote: null, credentialsFlat: false, credentialsPreserved: null };
+    const probe = `${dshHome}/.dsh-backup-migrate-probe-${process.pid}`;
+    try {
+      await writeFile(probe, 'dsh-backup link probe');
+      try {
+        await link(probe, `${probe}.lnk`);
+      } finally {
+        await rm(`${probe}.lnk`, { force: true });
+        await rm(probe, { force: true });
+      }
+    } catch (err) {
+      env.hardlink = false;
+      env.hardlinkNote = String(err && err.code ? err.code : err);
+    }
+    env.credentialsFlat = await credentialsIsFlatLayout(dshHome);
+    if (env.credentialsFlat) {
+      try {
+        env.credentialsPreserved = await preserveFlatCredentials();
+      } catch { /* 哨兵失败不阻塞预检：vault 不可写等，摘要里仍会提示 */ }
+    }
+    return env;
+  }
+
+  /** 只读扫描：全部代文件迁移静态预检 + 环境探测；不写会话文件。 */
+  async function runMigrateCheck(signal) {
+    const { dshHome, root } = paths();
+    if (signal?.aborted) throw new Error('操作已取消');
+    const found = [];
+    await collectSessionLogs(dshHome, '', 0, found, MIGRATE_LOG_SET);
+    const sessions = [];
+    for (const f of found) {
+      if (signal?.aborted) throw new Error('操作已取消');
+      sessions.push({ rel: f.rel, ...(await migrateAnalyzeFile(f)) });
+    }
+    const env = await migrateProbeEnvironment();
+    const fails = sessions.filter((s) => s.verdict === 'fail');
+    const migratable = sessions.filter((s) => s.verdict === 'migratable');
+    const skipped = sessions.filter((s) => s.verdict === 'skipped');
+    const lines = [];
+    lines.push(`扫描 ${sessions.length} 个会话日志（含 v1/v2/v3 代）：${fails.length} 个升级后将打不开、${migratable.length} 个旧代待迁移（静态规则全过）、${skipped.length} 个未能判定`);
+    if (fails.length) {
+      lines.push('');
+      for (const s of fails.slice(0, 15)) {
+        lines.push(`  ❌ ${s.rel}（v${s.version}）`);
+        for (const fd of s.findings) lines.push(`     · [${fd.rule}] ${fd.detail}`);
+        if (s.total > s.findings.length) lines.push(`     …另有 ${s.total - s.findings.length} 处问题`);
+      }
+      if (fails.length > 15) lines.push(`  …另有 ${fails.length - 15} 个文件`);
+      lines.push('');
+      lines.push('升级前建议：先拍一份升级前快照（/backup），坏的会话可从更早归档定点修复（/backup doctor --repair）。');
+    }
+    if (!env.hardlink) {
+      lines.push('');
+      lines.push(`⚠️ 文件系统不支持硬链接（${env.hardlinkNote}）——宿主发布 v3 新代文件会失败（官方 #6358 场景）：旧会话读得了、写开就报错，且升级无法继续。建议把 ~/.dsh 挪回 APFS/ext4 等本地文件系统。`);
+    }
+    if (env.credentialsFlat) {
+      lines.push('');
+      lines.push(`⚠️ .credentials.yaml 还是旧扁平布局——宿主下次读档会把它原子替换成 version:1（不可逆，旧宿主将读不回）。${env.credentialsPreserved ? `已自动存底：${env.credentialsPreserved.replace(`${root}/`, '')}` : '自动存底失败（vault 不可写？），建议立即手动 /backup 一次。'}`);
+    }
+    lines.push('');
+    lines.push(`覆盖说明：以上为静态规则判定（宿主 ${detectHostTrain() || '未知列车'} 校准）。需要重放迁移过程的检查（chunk 折叠溯源、引用重映射、发布前 worker 复核）不在本版覆盖内——静态全过仍可能在新代发布时被宿主拒载。`);
+    const head = fails.length || !env.hardlink || env.credentialsFlat ? '⚠️' : '✅';
+    return {
+      scanned: sessions.length,
+      sessions: sessions.map((s) => ({ rel: s.rel, verdict: s.verdict, version: s.version, total: s.total, findings: s.findings, ...(s.reason ? { reason: s.reason } : {}) })),
+      env,
+      failCount: fails.length,
+      migratableCount: migratable.length,
+      skippedCount: skipped.length,
+      summary: `${head} ${lines.join('\n')}`,
+    };
+  }
+
   /**
    * 定点修复：扫描出损坏的会话日志后，从指定归档（缺省最新一份，须通过
    * sha256 校验）里提取同名条目覆盖。只动损坏的文件本身——不做整库 aside
@@ -2293,7 +2600,7 @@ export function apply(ctx, pluginConfig) {
   // ---------- /backup 命令 ----------
   ctx.commands.register({
     name: 'backup',
-    description: '备份/恢复 DSH 数据；子命令: list | verify [前缀|all] | restore <前缀|latest> [--dry-run] [--sync-deps] | doctor [--repair <前缀|latest>] | auto [N小时|off] | github status|sync|pull|repo | [--keep N]',
+    description: '备份/恢复 DSH 数据；子命令: list | verify [前缀|all] | restore <前缀|latest> [--dry-run] [--sync-deps] | doctor [--repair <前缀|latest>] | migrate-check | auto [N小时|off] | github status|sync|pull|repo|token <token|off> | [--keep N]',
     handler: async (invocation) => {
       const input = invocation.rawInput.trim();
       try {
@@ -2352,6 +2659,11 @@ export function apply(ctx, pluginConfig) {
           return { kind: 'success', text: r.summary };
         }
 
+        if (head === 'migrate-check' || head === 'migrate') {
+          const r = await runMigrateCheck(invocation.signal);
+          return { kind: r.failCount || !r.env.hardlink || r.env.credentialsFlat ? 'error' : 'success', text: r.summary };
+        }
+
         if (head === 'github') {
           const arg = parts[1] || 'status';
           if (arg === 'repo') {
@@ -2368,6 +2680,18 @@ export function apply(ctx, pluginConfig) {
             await saveAutoState();
             return { kind: 'success', text: `GitHub 同步仓库已设为: ${clean}\n${autoSummary()}` };
           }
+          if (arg === 'token') {
+            // 面板同款：存本机备份目录 github.token（0600）；off 清除。任何回执不回显 token。
+            const value = parts.slice(2).join(' ').trim();
+            if (!value || value === 'off') {
+              await clearStoredGithubToken();
+              return { kind: 'success', text: `GitHub token 已清除。${githubConfig()?.token ? '环境变量 token 仍在生效。' : ''}` };
+            }
+            const invalid = validateGithubToken(value);
+            if (invalid) return { kind: 'error', text: invalid };
+            await writeStoredGithubToken(value);
+            return { kind: 'success', text: 'GitHub token 已保存：存在本机备份目录（0600），不进归档、不进 GitHub 同步。' };
+          }
           if (arg === 'sync') {
             const s = await githubSync(invocation.signal);
             if (s.pushed) {
@@ -2452,9 +2776,9 @@ 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，syncDeps 恢复后重装 profile 依赖；恢复前自动校验并快照当前数据，解压失败自动还原；真实恢复前必须先 dryRun=true 预览并向用户展示确认）；mode=auto 设置定时备份（hours 间隔小时数，0=关闭，缺省查询）；mode=doctor 会话日志体检——检测损坏的会话历史（seq 撞号/坏帧/截断），repair=true 时从 selector 归档定点修复',
+    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 归档定点修复；mode=migrate 迁移预检——静态扫描全部代会话日志（含 v1/v2/v3 代），预测宿主升级后哪些会话会打不开、挂在哪条规则，并探测文件系统硬链接支持与凭据文件旧布局',
     parameters: {
-      mode: { type: 'string', required: true, enum: ['backup', 'list', 'verify', 'restore', 'auto', 'doctor'], description: 'backup=执行备份，list=列出备份，verify=校验完整性，restore=恢复，auto=定时备份，doctor=会话日志体检' },
+      mode: { type: 'string', required: true, enum: ['backup', 'list', 'verify', 'restore', 'auto', 'doctor', 'migrate'], description: 'backup=执行备份，list=列出备份，verify=校验完整性，restore=恢复，auto=定时备份，doctor=会话日志体检，migrate=升级迁移预检' },
       keep: { type: 'number', description: '保留的备份份数（mode=backup，默认 7）' },
       hours: { type: 'number', description: '定时备份间隔小时数（mode=auto；0=关闭；缺省=查询状态）' },
       selector: { type: 'string', description: '备份选择器（mode=verify/restore/doctor）：归档名前缀、latest 或 all' },
@@ -2509,6 +2833,19 @@ export function apply(ctx, pluginConfig) {
             corrupt: r.corrupt.map((c) => ({ path: c.rel, reason: c.reason })),
           };
         }
+        if (mode === 'migrate') {
+          const r = await runMigrateCheck(signal);
+          return {
+            ok: r.failCount === 0 && r.env.hardlink && !r.env.credentialsFlat,
+            scanned: r.scanned,
+            failCount: r.failCount,
+            migratableCount: r.migratableCount,
+            skippedCount: r.skippedCount,
+            summary: r.summary,
+            sessions: r.sessions.filter((s) => s.verdict === 'fail').map((s) => ({ path: s.rel, version: s.version, findings: s.findings })),
+            env: r.env,
+          };
+        }
         if (mode === 'auto') {
           const h = args && args.hours !== undefined ? args.hours : null;
           if (h === null) return { ok: true, summary: autoSummary() };
@@ -2629,7 +2966,7 @@ export function apply(ctx, pluginConfig) {
         // 两路都经 stripUserinfo：避免 cordis.yml config.githubRepo 内嵌 token 时经面板泄露
         repoRaw: githubState.repo ?? (typeof resolved.githubRepo === 'string' ? stripUserinfo(resolved.githubRepo) : null),
         repo: cfg ? cfg.repo : null,
-        tokenSet: Boolean(cfg?.token),
+        tokenSet: hasGithubToken(),
         syncDir: `${root}/${SYNC_DIR}`,
         lastPush: githubState.lastPush,
         lastError: githubState.lastError,
@@ -2737,6 +3074,25 @@ export function apply(ctx, pluginConfig) {
         return { ok: false, summary: String(err && err.message ? err.message : err), repaired: [], unrecoverable: [], stillBad: [] };
       }
     },
+    migrateCheck: async (signal) => {
+      try {
+        const r = await runMigrateCheck(signal);
+        return { ok: r.failCount === 0 && r.env.hardlink && !r.env.credentialsFlat, ...r };
+      } catch (err) {
+        return { ok: false, summary: String(err && err.message ? err.message : err), sessions: [], scanned: 0, failCount: 0, migratableCount: 0, skippedCount: 0, env: {} };
+      }
+    },
+    setGithubToken: async (token) => {
+      const raw = typeof token === 'string' ? token.trim() : '';
+      if (!raw || raw === 'off') {
+        await clearStoredGithubToken();
+        return { ok: true, tokenSet: hasGithubToken(), summary: `GitHub token 已清除。${hasGithubToken() ? '环境变量 token 仍在生效。' : ''}` };
+      }
+      const invalid = validateGithubToken(raw);
+      if (invalid) return { ok: false, tokenSet: hasGithubToken(), summary: invalid };
+      await writeStoredGithubToken(raw);
+      return { ok: true, tokenSet: true, summary: 'GitHub token 已保存：存在本机备份目录（0600），不进归档、不进 GitHub 同步。' };
+    },
   };
 
   // 仅在装配了 Typert registry 的 profile（Web）里挂载面板服务；其余 profile 安静跳过。
@@ -2826,11 +3182,21 @@ export function apply(ctx, pluginConfig) {
   // 再继续——命中社区"想试新版怕搞坏"的最大恐惧。首见列车只记录不拍。
   void (async () => {
     await waitForSettingsReady();
+    await loadStoredGithubToken();
     const h = await loadAutoState();
     if (h > 0 && !autoDispose) {
       autoHours = h;
       scheduleAuto();
     }
+    // 凭据哨兵：宿主首次读档会把扁平布局的 .credentials.yaml 原子替换成
+    // version:1（不可逆——旧宿主读不回 versioned，官方 #6358）。启动即检测，
+    // 是扁平就先存一份进 vault/preserved，给「升级失败想回退」留后路。
+    try {
+      const kept = await preserveFlatCredentials();
+      if (kept) console.log(`[dsh-backup] 检测到旧版扁平布局凭据文件，已先存底再让宿主迁移: ${kept}`);
+    } catch (err) {
+      console.warn(`[dsh-backup] 凭据存底失败（不影响运行）: ${String(err && err.message ? err.message : err)}`);
+    }
     const train = detectHostTrain();
     if (!train) return;
     if (lastTrain === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiaoyuyu6420/dsh-backup",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Backup, restore, download and GitHub-sync DeepSeek Harness user data (~/.dsh): /backup, scheduled auto-backup that survives restarts, sha256 checksums, integrity verify, rotation, credential redaction with a local vault (plaintext never leaves the machine), cross-machine restore preflight with github pull, and a visual Settings panel. Cross-platform (macOS/Linux/Windows). 一键备份与恢复 DSH 数据：定时自动备份、完整性校验、凭据默认脱敏（明文只存本机 vault）、跨机恢复预检与 github pull 拉取，附 Settings 可视面板。",
   "type": "module",
   "packageManager": "pnpm@11.24.0",
@@ -53,12 +53,12 @@
   ],
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-commands": "^0.1.1-rc.2 || ^0.1.2-rc.1",
-    "@deepseek-ai/dsh-fs": "^0.1.1-rc.2 || ^0.1.2-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2 || ^0.1.2-rc.1",
-    "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2 || ^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2 || ^0.1.2-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.2 || ^0.1.2-rc.1",
+    "@deepseek-ai/dsh-commands": "^0.1.1-rc.2 || ^0.1.2-rc.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-fs": "^0.1.1-rc.2 || ^0.1.2-rc.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2 || ^0.1.2-rc.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2 || ^0.1.2-rc.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2 || ^0.1.2-rc.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.2 || ^0.1.2-rc.1 || ^0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
@@ -68,7 +68,8 @@
     "zod": "^4.4.3"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20",
+    "dsh": "^0.1.1-rc.2 || ^0.1.2-rc.1 || ^0.1.5-rc.1"
   },
   "license": "MIT",
   "repository": {