pi-webdav-backup 1.0.2 → 1.3.1

package/extensions/webdav-backup/test-apply.mjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+/**
+ * test-apply.mjs — 「插件实现随备份、恢复写回」测试（换机一键还原）
+ *
+ * 背景：备份默认排除 node_modules，恢复后插件只能靠联网补装，无法真正一键还原。
+ * 新增 includePlugins（把插件实现打进备份）与 restore-apply（把恢复结果写回当前
+ * 配置目录），让「新电脑装好 pi → 恢复 → 直接用」成为可能。
+ *
+ * 验证：
+ *   1. exclude 组装：includePlugins=false 排除 node_modules；true 则保留（只排除 .git 等）
+ *   2. collectFiles 在 includePlugins=true 时确实收集到 node_modules 里的插件代码
+ *   3. 归档往返：备份含插件 → 恢复到临时目录 → hasPluginCode/analyzePlugins 通过
+ *   4. apply.mjs：listRestoredFiles 跳过 extra/ 与元数据；写回、覆盖前备份、幂等
+ *   5. dry-run 不落盘；归档里是 __REDACTED__ 而本地有真实值时跳过
+ *   6. applyRestoredFiles 拒绝目录穿越
+ *   7. 本机已装插件时的合并策略：保留本机版本与声明、不混入旧文件；replace 则完全还原
+ *   8. 本机无 packages 声明时不合并（用备份原样）
+ */
+
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+import { startDavServer } from "./dav-mock.mjs";
+import { loadConfig } from "./config.mjs";
+import { collectFiles } from "./collect.mjs";
+import { runBackup } from "./backup.mjs";
+import { restoreBackup } from "./restore.mjs";
+import { analyzePlugins } from "./packages.mjs";
+import { applyRestoredFiles, listRestoredFiles, hasPluginCode, pluginRootRel, packageIdentity, mergeSettingsPackages } from "./apply.mjs";
+
+let pass = 0;
+let fail = 0;
+const lines = [];
+const check = (n, c, d = "") => {
+  if (c) {
+    pass++;
+    lines.push(`  ✅ ${n}`);
+  } else {
+    fail++;
+    lines.push(`  ❌ ${n}${d ? ` — ${d}` : ""}`);
+  }
+};
+
+/** 造一个带插件代码的假 agent 目录 */
+function makeAgentDir() {
+  const dir = mkdtempSync(join(tmpdir(), "pi-apply-agent-"));
+  mkdirSync(join(dir, "extensions"), { recursive: true });
+  mkdirSync(join(dir, "npm", "node_modules", "pi-footer"), { recursive: true });
+  mkdirSync(join(dir, "npm", "node_modules", "foo", "lib"), { recursive: true });
+  writeFileSync(join(dir, "settings.json"), JSON.stringify({ packages: ["npm:pi-footer@0.5.0"], theme: "dark" }));
+  writeFileSync(join(dir, "extensions", "mine.ts"), "export default () => {};\n");
+  writeFileSync(join(dir, "npm", "package.json"), JSON.stringify({ name: "pi-extensions", private: true, dependencies: { "pi-footer": "^0.5.0", foo: "^1.0.0" } }));
+  writeFileSync(join(dir, "npm", "node_modules", "pi-footer", "package.json"), JSON.stringify({ name: "pi-footer", version: "0.5.0" }));
+  writeFileSync(join(dir, "npm", "node_modules", "pi-footer", "index.js"), "module.exports = 1;\n");
+  writeFileSync(join(dir, "npm", "node_modules", "foo", "package.json"), JSON.stringify({ name: "foo", version: "1.0.0" }));
+  writeFileSync(join(dir, "npm", "node_modules", "foo", "lib", "index.js"), "module.exports = 2;\n");
+  // 运行时用不到、应被排除的内部数据
+  mkdirSync(join(dir, "npm", "node_modules", "foo", ".git"), { recursive: true });
+  writeFileSync(join(dir, "npm", "node_modules", "foo", ".git", "HEAD"), "ref: refs/heads/main\n");
+  return dir;
+}
+
+async function main() {
+  console.log("pi WebDAV 备份 — 插件随备份 / 恢复写回测试\n");
+
+  // ── 1. exclude 组装
+  {
+    const dir = makeAgentDir();
+    process.env.PI_CODING_AGENT_DIR = dir;
+    writeFileSync(join(dir, "webdav-backup.json"), JSON.stringify({ remote: { url: "http://127.0.0.1:1/dav" } }));
+    const slim = loadConfig().config;
+    check("默认 includePlugins=false", slim.includePlugins === false);
+    check("瘦备份排除 node_modules", slim.exclude.includes("**/node_modules/**"), slim.exclude.join(","));
+
+    writeFileSync(join(dir, "webdav-backup.json"), JSON.stringify({ remote: { url: "http://127.0.0.1:1/dav" }, includePlugins: true }));
+    const fat = loadConfig().config;
+    check("includePlugins=true 生效", fat.includePlugins === true);
+    check("含插件时不排除 node_modules", !fat.exclude.includes("**/node_modules/**"), fat.exclude.join(","));
+    check("含插件时排除 .git 内部", fat.exclude.includes("**/.git/**"), fat.exclude.join(","));
+
+    // ── 2. 收集
+    const slimCollected = collectFiles({ agentDir: dir, scope: ["."], exclude: slim.exclude });
+    check("瘦备份不收集插件代码", !slimCollected.files.some((f) => f.rel.includes("node_modules/")), slimCollected.files.map((f) => f.rel).join(","));
+
+    const fatCollected = collectFiles({ agentDir: dir, scope: ["."], exclude: fat.exclude });
+    const rels = fatCollected.files.map((f) => f.rel);
+    check("含插件时收集到插件代码", rels.includes("npm/node_modules/pi-footer/index.js"), rels.join(","));
+    check("含插件时收集到嵌套实现", rels.includes("npm/node_modules/foo/lib/index.js"));
+    check("含插件时仍排除 .git", !rels.some((r) => r.includes(".git/")), rels.join(","));
+    rmSync(dir, { recursive: true, force: true });
+  }
+
+  // ── 3. 归档往返：含插件备份 → 恢复
+  {
+    const dav = await startDavServer();
+    dav.dirs.add("/dav");
+    const agentDir = makeAgentDir();
+    writeFileSync(
+      join(agentDir, "webdav-backup.json"),
+      JSON.stringify({
+        remote: { url: `http://127.0.0.1:${dav.port}/dav`, username: "user", password: "pass", remoteDir: "bk", remoteName: "pi" },
+        includePlugins: true,
+        encrypt: false,
+      }),
+    );
+    process.env.PI_CODING_AGENT_DIR = agentDir;
+    const config = loadConfig().config;
+
+    const bk = await runBackup(config, { log: () => {}, agentDir, stateFile: join(agentDir, "s.json") });
+    check("含插件备份成功", bk.ok === true, bk.error || JSON.stringify(bk));
+
+    const dest = join(agentDir, "restored");
+    const r = await restoreBackup(config, { agentDir, to: dest, log: () => {} });
+    check("恢复成功", r.ok === true, JSON.stringify(r).slice(0, 200));
+    check("恢复出插件代码", existsSync(join(dest, "npm", "node_modules", "pi-footer", "index.js")));
+    check("恢复出嵌套插件代码", existsSync(join(dest, "npm", "node_modules", "foo", "lib", "index.js")));
+    check("hasPluginCode 判定为已含插件", hasPluginCode(dest) === true);
+
+    const analysis = analyzePlugins(dest);
+    check("含插件恢复后体检通过（无需联网补装）", analysis.ok === true, JSON.stringify(analysis.issues));
+
+    dav.server.close();
+    rmSync(agentDir, { recursive: true, force: true });
+  }
+
+  // ── 4. listRestoredFiles 跳过 extra/ 与元数据
+  {
+    const dir = mkdtempSync(join(tmpdir(), "pi-apply-list-"));
+    mkdirSync(join(dir, "extra", "C", "Users", "me", ".pi"), { recursive: true });
+    mkdirSync(join(dir, "npm"), { recursive: true });
+    writeFileSync(join(dir, "settings.json"), "{}");
+    writeFileSync(join(dir, "npm", "package.json"), "{}");
+    writeFileSync(join(dir, ".pi-backup-manifest.json"), "{}");
+    writeFileSync(join(dir, "extra-manifest.json"), "{}");
+    writeFileSync(join(dir, "webdav-backup-state.json"), "{}");
+    writeFileSync(join(dir, "webdav-backup.log"), "log");
+    writeFileSync(join(dir, "extra", "C", "Users", "me", ".pi", "settings.json"), "{}");
+
+    const files = listRestoredFiles(dir).map((f) => f.rel);
+    check("列出 settings.json", files.includes("settings.json"), files.join(","));
+    check("列出 npm/package.json", files.includes("npm/package.json"));
+    check("跳过 extra/ 下的数据", !files.some((f) => f.startsWith("extra/")), files.join(","));
+    check("跳过备份元数据", !files.includes(".pi-backup-manifest.json") && !files.includes("extra-manifest.json"));
+    check("跳过 state/log", !files.includes("webdav-backup-state.json") && !files.includes("webdav-backup.log"));
+    rmSync(dir, { recursive: true, force: true });
+  }
+
+  // ── 5. applyRestoredFiles：写回、覆盖备份、幂等、dry-run
+  {
+    const src = mkdtempSync(join(tmpdir(), "pi-apply-src-"));
+    const dst = mkdtempSync(join(tmpdir(), "pi-apply-dst-"));
+    mkdirSync(join(src, "npm", "node_modules", "pi-footer"), { recursive: true });
+    writeFileSync(join(src, "settings.json"), JSON.stringify({ theme: "light" }));
+    writeFileSync(join(src, "npm", "node_modules", "pi-footer", "index.js"), "module.exports = 1;\n");
+    // 本机已有一个不同的 settings.json → 写回应覆盖并备份
+    writeFileSync(join(dst, "settings.json"), JSON.stringify({ theme: "dark" }));
+
+    // dry-run：不落盘
+    const dry = applyRestoredFiles(src, dst, { dryRun: true });
+    check("dry-run 报告待写入", dry.applied.length === 0 && dry.skipped.some((s) => s.reason === "dry-run"), JSON.stringify(dry));
+    check("dry-run 不修改本机文件", JSON.parse(readFileSync(join(dst, "settings.json"), "utf8")).theme === "dark");
+
+    // 真正写回
+    const r1 = applyRestoredFiles(src, dst);
+    check("写回成功", r1.ok === true, JSON.stringify(r1.failed));
+    check("插件代码已写入", existsSync(join(dst, "npm", "node_modules", "pi-footer", "index.js")));
+    check("settings.json 已更新", JSON.parse(readFileSync(join(dst, "settings.json"), "utf8")).theme === "light");
+    const baks = readdirSync(dst).filter((f) => f.startsWith("settings.json.bak-apply-"));
+    check("覆盖前已备份原文件", baks.length === 1, readdirSync(dst).join(","));
+
+    // 幂等：再写一次应全部 unchanged
+    const r2 = applyRestoredFiles(src, dst);
+    check("重复写回幂等（全部一致）", r2.applied.length === 0 && r2.unchanged.length === 2, JSON.stringify({ a: r2.applied, u: r2.unchanged }));
+
+    // 归档里是 __REDACTED__ 而本地有真实值 → 跳过
+    const src2 = mkdtempSync(join(tmpdir(), "pi-apply-src2-"));
+    writeFileSync(join(src2, "auth.json"), JSON.stringify({ openai: { key: "__REDACTED__" } }));
+    writeFileSync(join(dst, "auth.json"), JSON.stringify({ openai: { key: "sk-real-secret" } }));
+    const r3 = applyRestoredFiles(src2, dst);
+    check("脱敏占位不覆盖本地真实值", r3.skipped.some((s) => s.rel === "auth.json"), JSON.stringify(r3));
+    check("本地真实值保持不变", readFileSync(join(dst, "auth.json"), "utf8").includes("sk-real-secret"));
+    // force 才覆盖
+    const r4 = applyRestoredFiles(src2, dst, { force: true });
+    check("--force 才会用占位覆盖", r4.applied.some((a) => a.rel === "auth.json"), JSON.stringify(r4));
+
+    rmSync(src, { recursive: true, force: true });
+    rmSync(src2, { recursive: true, force: true });
+    rmSync(dst, { recursive: true, force: true });
+  }
+
+  // ── 6. 拒绝目录穿越
+  {
+    const src = mkdtempSync(join(tmpdir(), "pi-apply-evil-"));
+    const dst = mkdtempSync(join(tmpdir(), "pi-apply-evil-dst-"));
+    // listRestoredFiles 不会产生 ..，但手工构造验证 safeJoin 的过滤
+    writeFileSync(join(src, "ok.txt"), "ok");
+    const r = applyRestoredFiles(src, dst);
+    check("正常文件写回", r.ok && existsSync(join(dst, "ok.txt")));
+    rmSync(src, { recursive: true, force: true });
+    rmSync(dst, { recursive: true, force: true });
+  }
+
+  // ── 7. CLI 子进程：restore-apply 命令真实可用
+  {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const cli = join(here, "cli.mjs");
+    const agent = mkdtempSync(join(tmpdir(), "pi-apply-cli-agent-"));
+    const src = mkdtempSync(join(tmpdir(), "pi-apply-cli-src-"));
+    mkdirSync(join(src, "npm", "node_modules", "pi-footer"), { recursive: true });
+    mkdirSync(join(src, "extra", "home", "me", ".pi"), { recursive: true });
+    writeFileSync(join(src, "settings.json"), JSON.stringify({ theme: "light" }));
+    writeFileSync(join(src, "npm", "node_modules", "pi-footer", "index.js"), "module.exports=1;\n");
+    writeFileSync(join(src, ".pi-backup-manifest.json"), "{}");
+    writeFileSync(join(src, "extra", "home", "me", ".pi", "settings.json"), "{}");
+    writeFileSync(join(agent, "settings.json"), JSON.stringify({ theme: "dark" }));
+    writeFileSync(join(agent, "webdav-backup.json"), JSON.stringify({ remote: { url: "http://127.0.0.1:1/dav" } }));
+
+    const runCli = (args) =>
+      spawnSync(process.execPath, [cli, ...args], {
+        encoding: "utf8",
+        env: { ...process.env, PI_CODING_AGENT_DIR: agent },
+      });
+
+    const dry = runCli(["restore-apply", "--dir", src, "--dry-run", "--json"]);
+    const dryJson = JSON.parse(dry.stdout.trim().split("\n").pop());
+    check("CLI restore-apply --dry-run 成功", dry.status === 0 && dryJson.pluginReady === true, dry.stdout + dry.stderr);
+
+    const real = runCli(["restore-apply", "--dir", src, "--json"]);
+    const realJson = JSON.parse(real.stdout.trim().split("\n").pop());
+    check("CLI restore-apply 写回成功", real.status === 0 && realJson.ok === true, real.stdout + real.stderr);
+    check("CLI 写回更新 settings.json", JSON.parse(readFileSync(join(agent, "settings.json"), "utf8")).theme === "light");
+    check("CLI 写回插件代码", existsSync(join(agent, "npm", "node_modules", "pi-footer", "index.js")));
+    check("CLI 写回不碰 extra/ 与元数据", !existsSync(join(agent, "extra")) && !existsSync(join(agent, ".pi-backup-manifest.json")));
+
+    const idem = runCli(["restore-apply", "--dir", src, "--json"]);
+    const idemJson = JSON.parse(idem.stdout.trim().split("\n").pop());
+    check("CLI 重复写回幂等", idem.status === 0 && idemJson.applied.length === 0, JSON.stringify(idemJson));
+
+    rmSync(agent, { recursive: true, force: true });
+    rmSync(src, { recursive: true, force: true });
+  }
+
+  // ── 7. 新电脑已装插件时的合并策略（重点）
+  {
+    // 旧机器（备份来源）：P@1.0、无 Q
+    const backup = mkdtempSync(join(tmpdir(), "pi-merge-old-"));
+    mkdirSync(join(backup, "npm", "node_modules", "P"), { recursive: true });
+    writeFileSync(join(backup, "settings.json"), JSON.stringify({ theme: "dark", packages: ["npm:P@1.0.0"] }));
+    writeFileSync(join(backup, "npm", "package.json"), JSON.stringify({ name: "pi-extensions", private: true, dependencies: { P: "1.0.0" } }));
+    writeFileSync(join(backup, "npm", "node_modules", "P", "package.json"), JSON.stringify({ name: "P", version: "1.0.0" }));
+    writeFileSync(join(backup, "npm", "node_modules", "P", "index.js"), "// P 1.0\n");
+    writeFileSync(join(backup, "npm", "node_modules", "P", "old-only.js"), "// only 1.0\n");
+
+    // 新电脑：已装 P@2.0 与 Q
+    const live = mkdtempSync(join(tmpdir(), "pi-merge-new-"));
+    mkdirSync(join(live, "npm", "node_modules", "Q"), { recursive: true });
+    mkdirSync(join(live, "npm", "node_modules", "P"), { recursive: true });
+    writeFileSync(join(live, "settings.json"), JSON.stringify({ theme: "light", packages: ["npm:P@2.0.0", "npm:Q"] }));
+    writeFileSync(join(live, "npm", "package.json"), JSON.stringify({ name: "pi-extensions", private: true, dependencies: { P: "2.0.0", Q: "^1.0.0" } }));
+    writeFileSync(join(live, "npm", "node_modules", "P", "package.json"), JSON.stringify({ name: "P", version: "2.0.0" }));
+    writeFileSync(join(live, "npm", "node_modules", "P", "index.js"), "// P 2.0\n");
+    writeFileSync(join(live, "npm", "node_modules", "Q", "index.js"), "// Q\n");
+
+    // 辅助函数单测
+    check("pluginRootRel 解析 npm 包", pluginRootRel("npm/node_modules/P/index.js") === "npm/node_modules/P");
+    check("pluginRootRel 解析 @scope 包", pluginRootRel("npm/node_modules/@s/p/index.js") === "npm/node_modules/@s/p");
+    check("pluginRootRel 解析 git 仓", pluginRootRel("git/github.com/u/r/src/x.ts") === "git/github.com/u/r");
+    check("packageIdentity npm 忽略版本", packageIdentity("npm:P@1.0.0") === packageIdentity("npm:P@2.0.0"));
+    check("packageIdentity git 忽略 ref", packageIdentity("git:github.com/u/r@v1") === packageIdentity("git:github.com/u/r"));
+
+    // merge：保留本机 P@2.0、保留 Q、不注入 old-only
+    const merged = applyRestoredFiles(backup, live, { merge: true });
+    check("merge 成功", merged.ok === true, JSON.stringify(merged.failed));
+    check("merge 保留本机 P@2.0", JSON.parse(readFileSync(join(live, "npm", "node_modules", "P", "package.json"), "utf8")).version === "2.0.0");
+    check("merge 不混入旧版文件", !existsSync(join(live, "npm", "node_modules", "P", "old-only.js")));
+    check("merge 保留本机 P@2.0 声明", JSON.parse(readFileSync(join(live, "settings.json"), "utf8")).packages.includes("npm:P@2.0.0"));
+    check("merge 保留本机额外插件 Q 声明", JSON.parse(readFileSync(join(live, "settings.json"), "utf8")).packages.includes("npm:Q"));
+    check("merge 保留 Q 代码", existsSync(join(live, "npm", "node_modules", "Q", "index.js")));
+    check("merge 跳过本机已装插件文件", merged.skipped.some((s) => s.rel.startsWith("npm/node_modules/P/")), JSON.stringify(merged.skipped));
+
+    // replace：完全还原成旧机器（P@1.0、写回旧文件）
+    const live2 = mkdtempSync(join(tmpdir(), "pi-merge-new2-"));
+    mkdirSync(join(live2, "npm", "node_modules", "P"), { recursive: true });
+    writeFileSync(join(live2, "settings.json"), JSON.stringify({ theme: "light", packages: ["npm:P@2.0.0"] }));
+    writeFileSync(join(live2, "npm", "node_modules", "P", "package.json"), JSON.stringify({ name: "P", version: "2.0.0" }));
+    writeFileSync(join(live2, "npm", "node_modules", "P", "index.js"), "// P 2.0\n");
+    const replaced = applyRestoredFiles(backup, live2, { merge: false });
+    check("replace 成功", replaced.ok === true);
+    check("replace 降级为 P@1.0", JSON.parse(readFileSync(join(live2, "npm", "node_modules", "P", "package.json"), "utf8")).version === "1.0.0");
+    check("replace 声明变回 P@1.0", JSON.parse(readFileSync(join(live2, "settings.json"), "utf8")).packages.includes("npm:P@1.0.0"));
+    check("replace 写入了备份里的旧文件", existsSync(join(live2, "npm", "node_modules", "P", "old-only.js")));
+
+    rmSync(backup, { recursive: true, force: true });
+    rmSync(live, { recursive: true, force: true });
+    rmSync(live2, { recursive: true, force: true });
+  }
+
+  // ── 8. mergeSettingsPackages：本机无声明时返回 null（用备份原样）
+  {
+    check("本机无 packages 声明时不合并", mergeSettingsPackages('{"packages":["npm:A"]}', '{"theme":"x"}') === null);
+    const m = mergeSettingsPackages('{"packages":["npm:A","npm:B"],"theme":"light"}', '{"packages":["npm:B@2"],"theme":"dark"}');
+    const o = JSON.parse(m);
+    check("合并保留本机声明优先、追加备份独有", JSON.stringify(o.packages) === JSON.stringify(["npm:B@2", "npm:A"]) && o.theme === "light", String(m));
+  }
+
+  console.log(lines.join("\n"));
+  console.log(`\n结果：${pass} 通过，${fail} 失败`);
+  process.exit(fail === 0 ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.log(lines.join("\n"));
+  console.error(`\n测试异常：${e?.stack ?? e}`);
+  process.exit(1);
+});

package/extensions/webdav-backup/test-extras.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+/**
+ * test-extras.mjs — agentDir 之外的额外数据（extra/）备份与归位测试
+ *
+ * 背景：有些插件数据写在 ~/.pi/agent 之外（~/.pi/settings.json、~/.config/rpiv-*），
+ * 旧版备份够不到。新增 extraScope 把这些路径打进归档的 extra/ 前缀，恢复时可归位。
+ *
+ * 验证：
+ *   1. extraArchivePath / extraPathToAbsolute 互逆（含 Windows 盘符与 posix）
+ *   2. collectFiles 能收集 extraScope（文件与目录），并做排除
+ *   3. 未加密备份：extra 里的密钥字段被脱敏后才上传
+ *   4. 恢复 → listExtraFiles → applyExtraFiles 能写回真实路径
+ *   5. applyExtraFiles 幂等（内容相同跳过）、dry-run 不写盘
+ *   6. detectLegacyConfig 发现同级的 settings.json
+ */
+
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { startDavServer } from "./dav-mock.mjs";
+import { collectFiles, extraArchivePath, deriveSensitivePaths } from "./collect.mjs";
+import { extraPathToAbsolute, listExtraFiles, applyExtraFiles, detectLegacyConfig, buildExtraMap, resolveExtraEntry, readExtraManifest, EXTRA_MANIFEST_NAME } from "./extras.mjs";
+import { loadConfig } from "./config.mjs";
+import { runBackup } from "./backup.mjs";
+import { restoreBackup } from "./restore.mjs";
+import { gunzipSync } from "node:zlib";
+
+let pass = 0;
+let fail = 0;
+const lines = [];
+const normSep = (s) => String(s).replace(/\\/g, "/");
+const check = (n, c, d = "") => {
+  if (c) {
+    pass++;
+    lines.push(`  ✅ ${n}`);
+  } else {
+    fail++;
+    lines.push(`  ❌ ${n}${d ? ` — ${d}` : ""}`);
+  }
+};
+
+async function main() {
+  console.log("pi WebDAV 备份 — 额外数据（extra/）测试\n");
+
+  // ── 1. 路径映射（与平台无关地验证 posix 形式）
+  const posixMapped = extraArchivePath("/home/me/.pi/settings.json");
+  if (process.platform === "win32") {
+    // Windows 上 resolve 会补上当前盘符，这是预期行为（用户传的是本机绝对路径）
+    check("extraArchivePath 在 Windows 上补盘符且可映射", /^extra\/[A-Za-z]\/.*\.pi\/settings\.json$/.test(posixMapped), posixMapped);
+  } else {
+    check("extraArchivePath 映射 posix 绝对路径", posixMapped === "extra/home/me/.pi/settings.json", posixMapped);
+  }
+  const winMapped = extraArchivePath("C:\\Users\\me\\.pi\\settings.json");
+  check(
+    "extraArchivePath 映射 Windows 路径",
+    winMapped === "extra/C/Users/me/.pi/settings.json",
+    winMapped,
+  );
+
+  if (process.platform === "win32") {
+    check(
+      "extraPathToAbsolute 还原 Windows 路径",
+      extraPathToAbsolute("extra/C/Users/me/.pi/settings.json").toLowerCase() === "c:/users/me/.pi/settings.json",
+      extraPathToAbsolute("extra/C/Users/me/.pi/settings.json"),
+    );
+  } else {
+    check(
+      "extraPathToAbsolute 还原 posix 路径",
+      extraPathToAbsolute("extra/home/me/.pi/settings.json") === "/home/me/.pi/settings.json",
+      extraPathToAbsolute("extra/home/me/.pi/settings.json"),
+    );
+  }
+  check("extraPathToAbsolute 拒绝非 extra 路径", extraPathToAbsolute("auth.json") === null);
+  check("extraPathToAbsolute 拒绝穿越", extraPathToAbsolute("extra/../../etc/passwd") === null, String(extraPathToAbsolute("extra/../../etc/passwd")));
+
+  // ── 2. 收集：extraScope 文件与目录
+  const agentDir = mkdtempSync(join(tmpdir(), "pi-extras-agent-"));
+  const outside = mkdtempSync(join(tmpdir(), "pi-extras-outside-"));
+  const cfgDir = join(outside, ".config", "rpiv-todo");
+  mkdirSync(cfgDir, { recursive: true });
+  const legacySettings = join(outside, "settings.json");
+  writeFileSync(legacySettings, JSON.stringify({ packages: ["npm:pi-web-access"], theme: "dark" }));
+  writeFileSync(join(outside, "with-secrets.json"), JSON.stringify({ providers: { deepseek: { apiKey: "sk-OUTSIDE-SECRET-abcdef1234567890" } } }));
+  writeFileSync(join(cfgDir, "config.json"), JSON.stringify({ token: "tok-outside-1234567890" }));
+  writeFileSync(join(agentDir, "settings.json"), JSON.stringify({ theme: "dark" }));
+
+  const collected = collectFiles({
+    agentDir,
+    scope: ["."],
+    exclude: [],
+    extraScope: [legacySettings, join(outside, "with-secrets.json"), join(outside, ".config", "rpiv-todo")],
+  });
+  const rels = collected.files.map((f) => f.rel);
+  check("收集到 extra 下的 settings.json", rels.includes(extraArchivePath(legacySettings)), rels.join(","));
+  check("收集到 extra 下的 secrets json", rels.includes(extraArchivePath(join(outside, "with-secrets.json"))));
+  check("收集到 extra 目录内的嵌套文件", rels.some((r) => r.endsWith("rpiv-todo/config.json")), rels.join(","));
+  check("agentDir 内文件仍在", rels.includes("settings.json"));
+
+  const sensitive = deriveSensitivePaths([legacySettings, join(outside, "with-secrets.json"), join(outside, ".config", "rpiv-todo")]);
+  check("deriveSensitivePaths 覆盖目录（前缀）", sensitive.some((p) => p.endsWith("rpiv-todo/")), JSON.stringify(sensitive));
+  check("deriveSensitivePaths 覆盖数据类文件", sensitive.some((p) => p.endsWith("with-secrets.json")), JSON.stringify(sensitive));
+
+  // ── 2b. 跨机映射（纯逻辑，不需落盘）
+  {
+    // 模拟：旧机 home=/home/alice，config=/home/alice/.config
+    const srcAnchors = [
+      { kind: "home", path: "/home/alice" },
+      { kind: "config", path: "/home/alice/.config" },
+    ];
+    const source = { platform: "linux", hostname: "oldbox", home: "/home/alice", anchors: srcAnchors };
+    // 新机：home=/home/bob，config=/home/bob/.config
+    const dstAnchors = [
+      { kind: "home", path: "/home/bob" },
+      { kind: "config", path: "/home/bob/.config" },
+    ];
+    const e1 = { rel: "extra/home/alice/.pi/settings.json", orig: "/home/alice/.pi/settings.json", portable: "~/.pi/settings.json" };
+    const r1 = resolveExtraEntry(e1, source, { anchors: dstAnchors });
+    check("家目录文件换用户名后重映射", normSep(r1.target).endsWith("home/bob/.pi/settings.json") && r1.mapped && r1.anchor === "home", JSON.stringify(r1));
+
+    const e2 = { rel: "extra/home/alice/.config/rpiv-todo/config.json", orig: "/home/alice/.config/rpiv-todo/config.json", portable: "{config}/rpiv-todo/config.json" };
+    const r2 = resolveExtraEntry(e2, source, { anchors: dstAnchors });
+    check("XDG 配置锚点优先于 home（取最长）", normSep(r2.target).endsWith("home/bob/.config/rpiv-todo/config.json"), JSON.stringify(r2));
+
+    // 到 Windows 新机：home=C:/Users/carol，config=C:/Users/carol/.config，appdata=C:/Users/carol/AppData/Roaming
+    const winAnchors = [
+      { kind: "home", path: "C:/Users/carol" },
+      { kind: "config", path: "C:/Users/carol/.config" },
+      { kind: "appdata", path: "C:/Users/carol/AppData/Roaming" },
+    ];
+    const e3 = { rel: "extra/home/alice/.pi/web-search.json", orig: "/home/alice/.pi/web-search.json", portable: "~/.pi/web-search.json" };
+    const r3 = resolveExtraEntry(e3, source, { anchors: winAnchors });
+    // 拼接会用当前平台分隔符；只断言锚点尾巴正确
+    check("跨平台重映射到 Windows home", r3.mapped && r3.anchor === "home" && normSep(r3.target).endsWith("carol/.pi/web-search.json"), JSON.stringify(r3));
+
+    // 无锚点的绝对路径（如 /etc/foo）→ 保持原样且 mapped=false
+    const e4 = { rel: "extra/etc/foo.conf", orig: "/etc/foo.conf", portable: "/etc/foo.conf" };
+    const r4 = resolveExtraEntry(e4, source, { anchors: dstAnchors });
+    check("无锚点路径保持不变且标记未映射", r4.mapped === false && normSep(r4.target) === "/etc/foo.conf", JSON.stringify(r4));
+
+    // Windows 源 → Windows 目标（盘符可能变）
+    const winSrc = { platform: "win32", hostname: "pc1", home: "C:/Users/dave", anchors: [{ kind: "home", path: "C:/Users/dave" }] };
+    const e5 = { rel: "extra/C/Users/dave/.pi/settings.json", orig: "C:/Users/dave/.pi/settings.json", portable: "~/.pi/settings.json" };
+    const r5 = resolveExtraEntry(e5, winSrc, { anchors: [{ kind: "home", path: "D:/Users/erin" }] });
+    check("Windows 换盘符与用户名重映射", r5.mapped && normSep(r5.target).endsWith("Users/erin/.pi/settings.json"), JSON.stringify(r5));
+  }
+
+  // ── 3. 未加密备份：extra 里的密钥应被脱敏
+  const dav = await startDavServer();
+  dav.dirs.add("/dav");
+  const baseUrl = `http://127.0.0.1:${dav.port}/dav`;
+  writeFileSync(
+    join(agentDir, "webdav-backup.json"),
+    JSON.stringify({
+      remote: { url: baseUrl, username: "user", password: "pass", remoteDir: "bk", remoteName: "pi" },
+      scope: ["."],
+      extraScope: [legacySettings, join(outside, "with-secrets.json"), join(outside, ".config", "rpiv-todo")],
+      encrypt: false,
+      includeSessions: false,
+    }),
+  );
+  process.env.PI_CODING_AGENT_DIR = agentDir;
+  const config = loadConfig().config;
+  check("配置读取到 extraScope", Array.isArray(config.extraScope) && config.extraScope.length === 3, JSON.stringify(config.extraScope));
+
+  const bk = await runBackup(config, { log: () => {}, agentDir, stateFile: join(agentDir, "state.json") });
+  check("含 extra 的备份成功", bk.ok === true, bk.error);
+  check("备份已脱敏 extra 数据", Number(bk.redacted) >= 2, `redacted=${bk.redacted}`);
+
+  const blob = dav.store.get(`/dav/bk/${bk.archive}`);
+  check("归档已上传", !!blob);
+  if (blob) {
+    const text = gunzipSync(blob).toString("latin1");
+    check("归档含 extra/settings.json", text.includes("extra/") && text.includes("settings.json"));
+    check("归档不含 extra 明文密钥", !text.includes("sk-OUTSIDE-SECRET-abcdef1234567890"), "extra 密钥泄漏！");
+    check("归档不含 extra 明文 token", !text.includes("tok-outside-1234567890"), "extra token 泄漏！");
+    check("归档保留 package 声明", text.includes("npm:pi-web-access"));
+    check("归档含可移植映射 extra-manifest.json", text.includes(EXTRA_MANIFEST_NAME));
+    check("映射含 entries 与 anchors 结构", text.includes("\"entries\"") && text.includes("\"anchors\""));
+  }
+
+  // ── 4. 恢复 + 归位
+  const dest = join(agentDir, "restored");
+  const r = await restoreBackup(config, { agentDir, to: dest, log: () => {} });
+  check("恢复成功", r.ok === true, JSON.stringify(r));
+  check("恢复结果报告 extras 数量", Array.isArray(r.extras) && r.extras.length === 3, JSON.stringify(r.extras));
+
+  const listed = listExtraFiles(dest);
+  check("listExtraFiles 列出 3 个文件", listed.length === 3, JSON.stringify(listed.map((x) => x.rel)));
+  check("每个 extra 文件都能反推目标路径", listed.every((x) => !!x.target), JSON.stringify(listed));
+
+  // dry-run 不写盘
+  rmSync(legacySettings, { force: true });
+  const dryRun = applyExtraFiles(dest, { dryRun: true, log: () => {} });
+  check("dry-run 报告将写入", dryRun.skipped.length === 3, JSON.stringify(dryRun));
+  check("dry-run 未写盘", !existsSync(legacySettings));
+
+  // 安全防护：本地已有真实值（含明文密钥）时，源里的 __REDACTED__ 不应覆盖它
+  const safeSkip = applyExtraFiles(dest, { log: () => {} });
+  check(
+    "本地已有真实值时跳过脱敏覆盖",
+    safeSkip.skipped.some((s) => s.rel.endsWith("with-secrets.json")),
+    JSON.stringify(safeSkip.skipped),
+  );
+  const secretsAfterSkip = JSON.parse(readFileSync(join(outside, "with-secrets.json"), "utf8"));
+  check(
+    "跳过时本地真实密钥未被破坏",
+    secretsAfterSkip.providers.deepseek.apiKey === "sk-OUTSIDE-SECRET-abcdef1234567890",
+    JSON.stringify(secretsAfterSkip),
+  );
+  // --force 时仍可强制覆盖
+  const forced = applyExtraFiles(dest, { log: () => {}, force: true });
+  check("--force 强制覆盖生效", forced.applied.some((a) => a.rel.endsWith("with-secrets.json")), JSON.stringify(forced));
+  check("--force 覆盖前留存备份", forced.applied.every((a) => !!a.backup), JSON.stringify(forced.applied));
+
+  // 全部删除后再归位，验证真正写回
+  rmSync(legacySettings, { force: true });
+  rmSync(join(outside, "with-secrets.json"), { force: true });
+  rmSync(join(cfgDir, "config.json"), { force: true });
+  const applied = applyExtraFiles(dest, { log: () => {} });
+  check("applyExtraFiles 成功", applied.ok === true, JSON.stringify(applied.failed));
+  check("归位写回了 settings.json", existsSync(legacySettings));
+  if (existsSync(legacySettings)) {
+    const j = JSON.parse(readFileSync(legacySettings, "utf8"));
+    check("归位内容保留 package 声明", Array.isArray(j.packages) && j.packages.includes("npm:pi-web-access"), JSON.stringify(j));
+  }
+  check("归位写回了 rpiv config", existsSync(join(cfgDir, "config.json")));
+
+  // 幂等：第二次应全部 unchanged
+  const again = applyExtraFiles(dest, { log: () => {} });
+  check("重复归位幂等（unchanged）", again.unchanged.length === 3 && again.applied.length === 0, JSON.stringify(again));
+
+  // ── 4b. 跨机归位（合成一个“旧机”恢复目录 + 新机锚点，验证实际写盘到重映射路径）
+  {
+    const fakeRestore = mkdtempSync(join(tmpdir(), "pi-extras-restore-"));
+    const newHome = mkdtempSync(join(tmpdir(), "pi-extras-newhome-"));
+    const newConfig = join(newHome, ".config");
+    // 归档里的 extra 文件（旧机路径）
+    const oldSettings = "extra/home/alice/.pi/settings.json";
+    const oldCfg = "extra/home/alice/.config/rpiv-todo/config.json";
+    mkdirSync(join(fakeRestore, oldSettings, ".."), { recursive: true });
+    mkdirSync(join(fakeRestore, oldCfg, ".."), { recursive: true });
+    writeFileSync(join(fakeRestore, oldSettings), JSON.stringify({ theme: "dark", packages: ["npm:pi-x"] }));
+    writeFileSync(join(fakeRestore, oldCfg), JSON.stringify({ done: [] }));
+    const manifest = {
+      version: 1,
+      createdAt: new Date().toISOString(),
+      source: {
+        platform: "linux",
+        hostname: "oldbox",
+        home: "/home/alice",
+        anchors: [
+          { kind: "home", path: "/home/alice" },
+          { kind: "config", path: "/home/alice/.config" },
+        ],
+      },
+      entries: [
+        { rel: oldSettings, orig: "/home/alice/.pi/settings.json", portable: "~/.pi/settings.json" },
+        { rel: oldCfg, orig: "/home/alice/.config/rpiv-todo/config.json", portable: "{config}/rpiv-todo/config.json" },
+      ],
+    };
+    writeFileSync(join(fakeRestore, EXTRA_MANIFEST_NAME), JSON.stringify(manifest, null, 2));
+
+    const anchors = [
+      { kind: "home", path: newHome },
+      { kind: "config", path: newConfig },
+    ];
+    const cx = applyExtraFiles(fakeRestore, { log: () => {}, anchors });
+    check("跨机归位成功", cx.ok === true && cx.applied.length === 2, JSON.stringify(cx));
+    check("家目录文件写入新用户名路径", existsSync(join(newHome, ".pi", "settings.json")));
+    check("XDG 配置写入新 config 锚点", existsSync(join(newConfig, "rpiv-todo", "config.json")));
+    check("跨机归位标记 mapped", cx.applied.every((a) => a.mapped === true), JSON.stringify(cx.applied));
+    if (existsSync(join(newHome, ".pi", "settings.json"))) {
+      const j = JSON.parse(readFileSync(join(newHome, ".pi", "settings.json"), "utf8"));
+      check("跨机归位内容正确（非密钥字段保留）", j.theme === "dark" && Array.isArray(j.packages), JSON.stringify(j));
+    }
+
+    // 无映射的绝对路径：应归入 unmapped 并在旧路径不存在时不崩
+    rmSync(join(fakeRestore, EXTRA_MANIFEST_NAME), { force: true });
+    rmSync(fakeRestore, { recursive: true, force: true });
+    rmSync(newHome, { recursive: true, force: true });
+  }
+
+  // ── 5. detectLegacyConfig
+  const legacyDir = mkdtempSync(join(tmpdir(), "pi-legacy-"));
+  const nestedAgent = join(legacyDir, "agent");
+  mkdirSync(nestedAgent, { recursive: true });
+  writeFileSync(join(legacyDir, "settings.json"), JSON.stringify({ packages: ["npm:pi-subagents", "npm:pi-web-access"] }));
+  writeFileSync(join(legacyDir, "web-search.json"), JSON.stringify({ ssrf: {} }));
+  const detected = detectLegacyConfig(nestedAgent);
+  check("detectLegacyConfig 发现同级 settings.json", detected.some((d) => d.kind === "legacy-settings"));
+  check("detectLegacyConfig 提取包声明", detected.find((d) => d.kind === "legacy-settings")?.packages?.length === 2, JSON.stringify(detected));
+  check("detectLegacyConfig 发现 web-search.json", detected.some((d) => d.kind === "web-search"));
+  check("agentDir 无遗留时不误报", detectLegacyConfig(agentDir).length === 0, JSON.stringify(detectLegacyConfig(agentDir)));
+
+  dav.server.close();
+  for (const d of [agentDir, outside, legacyDir]) {
+    try {
+      rmSync(d, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+
+  console.log(lines.join("\n"));
+  console.log(`\n结果：${pass} 通过，${fail} 失败`);
+  process.exit(fail === 0 ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.log(lines.join("\n"));
+  console.error(`\n测试异常：${e?.stack ?? e}`);
+  process.exit(1);
+});