pi-webdav-backup 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ddldxiacan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,355 @@
+# pi WebDAV 备份扩展
+
+把 pi 的**插件、扩展、模型配置**自动备份到任意 WebDAV 服务（坚果云 / Nextcloud / 群晖 / 自建 rclone）。
+
+零第三方依赖，只用 Node 内置模块。密钥默认不明文落盘（DPAPI / 环境变量 / 命令）。
+
+---
+
+## 安装
+
+一行命令（pi 官方包机制）：
+
+```bash
+pi install git:github.com/ddldxiacan/pi-webdav-backup@v1
+```
+
+只想试一下、不安装（仅本次运行生效）：
+
+```bash
+pi -e git:github.com/ddldxiacan/pi-webdav-backup
+```
+
+其他方式：
+
+```bash
+pi install npm:pi-webdav-backup            # 已发布到 npm 时
+pi install /path/to/pi-webdav-backup       # 本地目录（下载 ZIP 解压后）
+```
+
+手动安装：把 `extensions/webdav-backup.ts` 与 `extensions/webdav-backup/` 拷到 `~/.pi/agent/extensions/`。
+
+装好后在 pi 里运行 **`/reload`** 加载。
+
+> 本包带 `pi-package` 关键字，会出现在 [pi.dev 包画廊](https://pi.dev/packages)。
+
+运行时产生的文件：
+
+```
+~/.pi/agent/webdav-backup.json        ← 备份配置（/backup-setup 生成）
+~/.pi/agent/secrets.dpapi.json        ← DPAPI 加密的密钥（自动创建，0600）
+```
+
+---
+
+## 快速开始
+
+```
+/backup-setup       # 向导：填地址、账号、密码（默认 DPAPI 加密保存），自动测连接
+/backup             # 立即备份
+/backup verify      # 体检：密钥来源 / 明文告警 / 连接性
+/backup check       # 单独测连接
+/backup list        # 看远端已有备份
+/backup restore     # 选一个备份恢复到临时目录
+```
+
+配置写入 `~/.pi/agent/webdav-backup.json`。
+
+---
+
+## 命令一览
+
+| 命令 | 作用 |
+|---|---|
+| `/backup` | 立即备份（同步执行，完成后通知） |
+| `/backup check` | 测试 WebDAV 连通性与认证 |
+| `/backup list` | 列出远端备份文件 |
+| `/backup dry` | 试运行：只扫描统计，不上传 |
+| `/backup status` | 查看上次备份时间 |
+| `/backup prune` | 清理旧备份（保留 `keepVersions` 个） |
+| `/backup restore` | 交互选择备份并恢复到临时目录 |
+| `/backup verify` | 配置体检：密钥来源、明文告警、连接性 |
+| `/backup keys list` | 列出已加密保存的密钥 |
+| `/backup keys set <名称>` | 用 DPAPI 加密保存密钥 |
+| `/backup keys rm <名称>` | 删除密钥 |
+| `/backup keys migrate` | 把配置里的明文密钥迁成加密引用 |
+| `/backup-setup` | 配置向导（默认走 DPAPI 加密） |
+| `/backup-cron [HH:MM]` | 安装每日定时备份（Windows 计划任务） |
+| `/backup-cron remove` | 移除定时任务 |
+| `/backup-log` | 查看最近 20 行日志 |
+
+命令行也可直接用：
+
+```bash
+node ~/.pi/agent/extensions/webdav-backup/cli.mjs backup --json
+node ~/.pi/agent/extensions/webdav-backup/cli.mjs doctor --json
+node ~/.pi/agent/extensions/webdav-backup/cli.mjs migrate --method dpapi
+node ~/.pi/agent/extensions/webdav-backup/cli.mjs restore --list
+node ~/.pi/agent/extensions/webdav-backup/cli.mjs restore --file pi-agent-20260924-120000.tar.gz --to D:\restore
+```
+
+---
+
+## 密钥不明文落盘
+
+`remote.password` 与 `encryptKey` 不直接写明文，而是写**引用**：
+
+| 语法 | 说明 | 适用 |
+|---|---|---|
+| `dpapi:名称` | **推荐**。Windows DPAPI 用户级加密存入 `secrets.dpapi.json`，本机本用户可解，**无需主密码** | Windows |
+| `$ENV_VAR` / `${ENV_VAR}` | 环境变量（也支持 `$A-$B` 拼接，`$$` 转义） | 跨平台 |
+| `file:路径` | 从文件读取（自动去换行；相对路径基于 `~/.pi/agent`） | 跨平台 |
+| `!命令` | 执行命令取 stdout（可对接密码管理器 CLI） | 跨平台 |
+| `plain:值` | 显式声明明文（会告警，仅调试用） | — |
+| 其他值 | 视为明文（**会告警**） | — |
+
+> 该语法与 pi 自身的 `resolve-config-value` 约定一致，`auth.json` 的 `key` 字段也支持 `$ENV_VAR` 与 `!命令`。
+
+### 推荐做法
+
+```jsonc
+{
+  "remote": {
+    "url": "https://dav.jianguoyun.com/dav/",
+    "username": "you@example.com",
+    "password": "dpapi:webdav-password"      // 不是明文
+  },
+  "encrypt": true,
+  "encryptKey": "dpapi:backup-key"           // 不是明文
+}
+```
+
+密钥本身这样存：
+
+```
+/backup keys set webdav-password      # 提示输入，DPAPI 加密入库
+/backup keys set backup-key
+/backup keys list                     # 只看名称与时间，不显示明文
+```
+
+已有明文配置？一条命令迁走（自动备份原文件）：
+
+```
+/backup keys migrate
+```
+
+非 Windows 或偏好环境变量：
+
+```bash
+node cli.mjs migrate --method env    # 写入用户环境变量（setx）
+node cli.mjs migrate --method file   # 写入 0600 权限的 secrets/ 目录
+```
+
+### 体检
+
+```
+/backup verify
+```
+
+输出密钥来源、是否明文、DPAPI 是否可用、连接是否通过。有明文会直接标 ⚠️。
+
+> **DPAPI 的边界**：防御的是「配置文件/备份被拷走或误传到云端」。不防御已经能以你的身份运行代码的本机恶意程序。若需更强隔离，用 `!命令` 对接外部密码管理器。
+
+### 环境变量方式也支持
+
+不想改配置文件时，仍可用环境变量（优先级低于配置里的值）：
+
+```powershell
+setx PI_WEBDAV_BACKUP_PASSWORD "你的应用密码"
+setx PI_WEBDAV_BACKUP_KEY "你的加密口令"
+```
+
+---
+
+## 备份什么
+
+默认备份 `~/.pi/agent/` 下**除以下内容外**的所有文件：
+
+| 排除项 | 原因 |
+|---|---|
+| `sessions/**` | 会话历史，通常很大（可用 `includeSessions` 打开） |
+| `tmp/**`、`web-search-cache/**` | 缓存 |
+| `**/node_modules/**` | 可重装 |
+| `**/*.log` | 日志 |
+
+包含：`extensions/`（你写的扩展）、`models.json`、`models-store.json`、`settings.json`、`trust.json`、`auth.json`、`npm/package.json` 等。
+
+### 敏感文件脱敏（重要）
+
+**未加密**备份时，`auth.json` 与 `webdav-backup.json` 会先脱敏再上传：
+
+- 按字段名匹配：`key` / `token` / `secret` / `password` / `credential` / `cookie` / `private` …
+- **并按值的形状匹配**：`sk-…`、`ghp_…`、`AIza…`、JWT、32 位以上随机串
+- 命中替换为 `__REDACTED__`，结构保留
+- 解析失败时整文件替换为占位符，**绝不原样上传**
+
+> 脱敏是「尽力而为」的防泄漏措施。真正的安全做法是开启 `encrypt`。
+
+---
+
+## 配置项
+
+```jsonc
+{
+  "enabled": true,
+
+  "remote": {
+    "url": "https://dav.jianguoyun.com/dav/",   // 见下方各服务填法
+    "username": "you@example.com",
+    "password": "dpapi:webdav-password",        // 密钥引用，见上文；留空则读 $PI_WEBDAV_BACKUP_PASSWORD
+    "remoteDir": "pi-backup",                    // 远端目录
+    "remoteName": "pi-agent"                     // 文件名前缀
+  },
+
+  "scope": ["."],                  // 相对 ~/.pi/agent 的路径，可写 ["extensions", "models.json"]
+  "exclude": [],                   // 额外 glob 排除规则
+  "includeSessions": false,        // 是否备份会话历史
+  "snapshot": false,               // 见下文「两种模式」
+
+  "encrypt": false,                // AES-256-GCM 加密
+  "encryptKey": "dpapi:backup-key",  // 密钥引用（≥16 位），或 $PI_WEBDAV_BACKUP_KEY
+
+  "backupOnExit": true,            // 退出 pi 时自动备份
+  "backupOnExitMinIntervalMinutes": 30,   // 两次自动备份最小间隔
+  "backupOnExitTimeoutMs": 600000,        // 自动备份等待上限
+
+  "keepVersions": 10,              // 保留最近 N 个归档（0 = 不清理）
+  "timeoutMs": 60000,
+  "insecureTls": false             // 自签名证书时才设 true
+}
+```
+
+### 各服务 URL 填法
+
+| 服务 | url | username | password |
+|---|---|---|---|
+| **坚果云** | `https://dav.jianguoyun.com/dav/` | 注册邮箱 | **应用密码**（账户信息 → 安全选项 → 添加应用密码） |
+| **Nextcloud** | `https://云地址/remote.php/dav/files/<用户名>/` | 用户名 | 登录密码或应用密码 |
+| **群晖 WebDAV** | `https://NAS地址:5006/<共享文件夹>` | DSM 账号 | DSM 密码 |
+| **自建 rclone serve** | `http://主机:端口/` | `--user` 指定的值 | `--pass` 指定的值 |
+
+> ⚠️ 密码建议用 `dpapi:` 引用而非明文，见下方「密钥不明文落盘」：
+> ```
+> /backup keys set webdav-password
+> # 然后在配置里写 "password": "dpapi:webdav-password"
+> ```
+> 也可用环境变量：`setx PI_WEBDAV_BACKUP_PASSWORD "你的应用密码"`
+
+---
+
+## 两种备份模式
+
+### 归档模式（默认，`snapshot: false`）
+
+每次打包成一个 `pi-agent-<时间戳>.tar.gz`（可选 `.pibak` 加密）上传。
+
+- ✅ 单个文件，下载/归档方便
+- ✅ 天然有版本历史
+- ⚠️ 每次全量上传
+
+### 快照模式（`snapshot: true`）
+
+逐文件上传到 `pi-backup/pi-agent/`，用远端 `manifest.json` 做增量比对。
+
+- ✅ 只传变化的文件，第二次起非常快
+- ✅ 能单独恢复某一个文件
+- ⚠️ 只保留最新状态，无历史版本
+
+**建议**：日常用**快照模式**（省流量），配合每周一次归档（可另配一个 `remoteName`）。
+
+---
+
+## 退出自动备份怎么工作
+
+`session_shutdown`（`reason: quit`）触发时：
+
+1. 检查 `enabled` / `backupOnExit`
+2. 距上次自动备份不足 `backupOnExitMinIntervalMinutes` → 跳过（避免反复开关 pi 重复上传）
+3. 否则 **spawn 一个分离子进程**执行上传，立刻返回
+
+用分离进程的原因：pi 退出时若被 `SIGTERM`/关窗打断，留在主进程的上传会被中断；分离进程不受影响，且不会卡住退出。
+
+日志写在 `~/.pi/agent/webdav-backup.log`。
+
+### 每日定时备份
+
+```powershell
+# 在 pi 里：/backup-cron 03:00     或命令行：
+node "$env:USERPROFILE\.pi\agent\extensions\webdav-backup\cli.mjs" install-cron --time 03:00
+```
+
+需要管理员权限（创建计划任务）。移除：`/backup-cron remove`。
+
+---
+
+## 恢复
+
+```
+/backup restore          # 选择备份 → 恢复到临时目录
+```
+
+**默认恢复到临时目录，不会直接覆盖 `~/.pi/agent`** —— 因为恢复旧配置可能覆盖你当前的密钥。
+
+恢复后自行拷贝需要的文件：
+
+```powershell
+# 归档恢复结果示例
+# C:\Users\...\Temp\pi-restore-XXXX\restored\extensions\...
+copy "$env:TEMP\pi-restore-XXXX\restored\extensions\*.ts" "$env:USERPROFILE\.pi\agent\extensions\"
+```
+
+指定目标目录（谨慎）：
+
+```bash
+node cli.mjs restore --file pi-agent-20260924-120000.tar.gz --to D:\pi-restore
+```
+
+### 加密备份的恢复
+
+需要 `encryptKey` 一致（配置文件或 `$PI_WEBDAV_BACKUP_KEY`）。密钥不对会明确报错，不会写出损坏文件。
+
+解包过程会**拒绝绝对路径与 `..` 穿越**，防止恶意归档写出到目标目录之外。
+
+---
+
+## 测试
+
+```bash
+cd pi-webdav-backup
+npm test
+# 等价于：node extensions/webdav-backup/run-tests.mjs
+```
+
+扩展契约校验（模拟 pi 加载器导入入口文件）：
+
+```bash
+node extensions/webdav-backup/verify-load.mjs
+```
+
+6 个测试文件、277 项断言，用内置的内存 WebDAV 服务端做真实 HTTP 往返：
+
+| 文件 | 覆盖 |
+|---|---|
+| `test.mjs` | 收集/排除、归档、加密往返、快照增量、prune |
+| `test-cli.mjs` | 真实子进程调用 CLI、退出备份、DPAPI 端到端、doctor、日志、状态 |
+| `test-restore.mjs` | 归档/加密/快照恢复、目录穿越防护 |
+| `test-redact.mjs` | 脱敏（含「字段名无关但值是密钥」的回归用例） |
+| `test-secrets.mjs` | dpapi/$ENV/file/!命令/plain 各分支、明文告警、三种迁移方式 |
+| `test-auth-migrate.mjs` | `auth.json` 明文密钥审计与迁移（迁移前自动备份、可回滚） |
+
+---
+
+## 故障排查
+
+| 现象 | 处理 |
+|---|---|
+| 401 认证失败 | 坚果云必须用**应用密码**；确认 `username` 是邮箱 |
+| 404 路径不存在 | 检查 `url` 结尾斜杠与路径；Nextcloud 要带 `/remote.php/dav/files/<用户名>/` |
+| 403 拒绝访问 | 远端目录权限不足；坚果云需先在网页版建好目录 |
+| TLS 证书错误 | 自签名证书才设 `insecureTls: true`（有中间人风险） |
+| 备份很慢 | 改用 `snapshot: true`；或把 `includeSessions` 关掉 |
+| 退出时没备份 | 看 `webdav-backup.log`；确认 `backupOnExit: true` 且距上次已过间隔 |
+| 想立刻看到日志 | `/backup-log` |
+| DPAPI 解密失败 | 密文只能在本机本用户下解；换机器/换用户需重新 `/backup keys set` |
+| 提示「环境变量未设置」 | `/backup keys set` 改用 dpapi，或先设好该环境变量 |
+| 配置体检 | `/backup verify` 一次看全部状态 |

package/extensions/webdav-backup/audit-real.mjs

@@ -0,0 +1,84 @@
+/**
+ * 用真实 ~/.pi/agent 内容做一次 dry-run + 审计，确认：
+ *   1. 迁移后的 auth.json 引用形态能被正确处理
+ *   2. 明文审计通过
+ *   3. 迁移遗留的 auth.json.bak-* 不在待上传列表里
+ */
+import { loadConfig } from "./config.mjs";
+import { runBackup, auditForPlaintext } from "./backup.mjs";
+import { collectFiles } from "./collect.mjs";
+import { resolveAgentDir } from "./config-paths.mjs";
+
+const agentDir = resolveAgentDir();
+console.log("agentDir:", agentDir);
+
+const loaded = loadConfig();
+console.log("配置文件存在:", loaded.ok || loaded.errors.every((e) => /不存在/.test(e)) ? "是" : "否");
+if (loaded.config) {
+  for (const w of loaded.warnings) console.log("  警告:", w);
+}
+
+// 尚未创建配置时用默认值跑本地扫描（dry-run 不连网）
+const cfg = loaded.config ?? {
+  enabled: true,
+  url: "https://example.invalid/dav",
+  username: "",
+  password: "",
+  remoteDir: "pi-backup",
+  remoteName: "pi-agent",
+  scope: ["."],
+  exclude: [
+    "tmp/**",
+    "web-search-cache/**",
+    "npm/node_modules/**",
+    "sessions/**",
+    "**/*.log",
+    "**/node_modules/**",
+    "secrets/**",
+    "secrets.dpapi.json",
+    "**/*.bak-*",
+    "**/*.bak",
+    "**/*.orig",
+    "**/*.old",
+    "**/*.save",
+  ],
+  includeSessions: false,
+  snapshot: false,
+  encrypt: false,
+  encryptKey: null,
+  timeoutMs: 60000,
+  insecureTls: false,
+  keepVersions: 10,
+};
+console.log("（未创建配置文件，使用默认范围与排除规则）");
+console.log("远端:", cfg.url);
+
+const { files, skipped, totalSize } = collectFiles({
+  agentDir,
+  scope: cfg.scope,
+  exclude: [...cfg.exclude, ...(cfg.includeSessions ? [] : ["sessions/**"])],
+});
+
+console.log(`\n待备份文件 ${files.length} 个，${(totalSize / 1024).toFixed(1)} KB，跳过 ${skipped} 项`);
+console.log("文件列表:");
+for (const f of files) console.log("  ", f.rel);
+
+const baks = files.filter((f) => /\.bak/.test(f.rel));
+console.log("\n待备份列表中的 .bak 文件:", baks.length === 0 ? "无 ✅" : baks.map((b) => b.rel).join(", "));
+
+const audit = auditForPlaintext(files, { agentDir, config: cfg });
+console.log("\n明文审计:", audit.clean ? "通过 ✅" : "发现问题 ❌");
+for (const l of audit.leaks) console.log("  ", l.rel, "—", l.reason);
+
+// 确认 auth.json 上传后确实不含原明文（对比注册表值）
+const { readFileSync } = await import("node:fs");
+const { join } = await import("node:path");
+const { redactSensitive } = await import("./backup.mjs");
+
+const authRel = files.find((f) => f.rel.endsWith("auth.json"));
+if (authRel) {
+  const before = readFileSync(join(agentDir, authRel.rel), "utf8");
+  const after = redactSensitive(authRel.rel, Buffer.from(before), { aggressive: true }).toString("utf8");
+  console.log("\nauth.json 磁盘原文:", before.replace(/\s+/g, " ").slice(0, 120));
+  console.log("auth.json 上传形态:", after.replace(/\s+/g, " ").slice(0, 120));
+}

package/extensions/webdav-backup/auth-migrate.mjs

@@ -0,0 +1,242 @@
+/**
+ * auth-migrate.mjs — 把 auth.json 里的明文 API 密钥改为安全引用
+ *
+ * pi 的 auth.json 结构：
+ *   { "<provider>": { "type": "api_key", "key": "<明文 或 $ENV_VAR 或 !命令>" } }
+ *
+ * auth-storage.js 的 read() 会对 key 调用 resolveConfigValue，
+ * 因此 $ENV_VAR / !命令 / ${VAR} 引用是被官方支持的。
+ *
+ * 迁移策略（每项单独选择）：
+ *   env   → $PI_PI_KEY_<PROVIDER>      （默认，与其它 pi 用法一致，跨平台）
+ *   dpapi → dpapi:auth-<provider>      （Windows，无主密码）
+ *   keep  → 不动
+ *
+ * 重要：key 为空字符串时 pi 用它表达“未配置”，必须保留为空，不能改成引用，
+ * 否则会把“未登录”变成“引用一个不存在的变量”。
+ */
+
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { getAgentDir } from "./config-paths.mjs";
+import {
+  setDpapiSecret,
+  dpapiAvailable,
+  setUserEnvVar,
+  readUserEnvVar,
+  envVarVisible,
+} from "./secrets.mjs";
+
+export function authJsonPath() {
+  return join(getAgentDir(), "auth.json");
+}
+
+/** 判断 key 是否已是引用形式 */
+function isReference(key) {
+  if (typeof key !== "string") return false;
+  const t = key.trim();
+  if (!t) return false;
+  if (t.startsWith("$") || t.startsWith("!") || t.startsWith("dpapi:") || t.startsWith("file:")) return true;
+  return false;
+}
+
+/** 由 provider id 生成合法环境变量名 */
+export function envVarNameFor(providerId) {
+  const normalized = String(providerId)
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return `PI_PI_KEY_${normalized}`;
+}
+
+function readAuth() {
+  const p = authJsonPath();
+  if (!existsSync(p)) return null;
+  try {
+    const raw = readFileSync(p, "utf8").replace(/^\uFEFF/, "").trim();
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    return { __parseError: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/**
+ * 扫描 auth.json，列出需要迁移的明文密钥。
+ */
+export function scanAuthSecrets() {
+  const data = readAuth();
+  if (data === null) {
+    return { ok: false, error: `auth.json 不存在：${authJsonPath()}`, items: [] };
+  }
+  if (data.__parseError) {
+    return { ok: false, error: `auth.json 不是合法 JSON：${data.__parseError}`, items: [] };
+  }
+
+  const items = [];
+  for (const [providerId, cred] of Object.entries(data)) {
+    if (!cred || typeof cred !== "object") continue;
+    const key = cred.key;
+    if (typeof key !== "string") continue;
+
+    if (key.trim() === "") {
+      items.push({ provider: providerId, kind: "empty", keyLength: 0, action: "skip", reason: "空值表示未配置，保持原样" });
+      continue;
+    }
+    if (isReference(key)) {
+      items.push({ provider: providerId, kind: "reference", action: "skip", reason: "已是安全引用", current: key });
+      continue;
+    }
+    items.push({
+      provider: providerId,
+      kind: "plaintext",
+      keyLength: key.length,
+      action: "migrate",
+      suggestedEnv: envVarNameFor(providerId),
+      suggestedDpapi: `dpapi:auth-${providerId}`,
+    });
+  }
+  return { ok: true, items, path: authJsonPath() };
+}
+
+/**
+ * 执行迁移。
+ *
+ * @param {object} opts
+ * @param {"env"|"dpapi"} opts.method
+ * @param {Record<string, "env"|"dpapi"|"keep">} [opts.perProvider]
+ * @param {(s: string) => void} [opts.log]
+ * @param {boolean} [opts.dryRun]
+ */
+export async function migrateAuthJson({ method = "env", perProvider = {}, log = () => {}, dryRun = false } = {}) {
+  const scan = scanAuthSecrets();
+  if (!scan.ok) return { ok: false, error: scan.error };
+
+  const targets = scan.items.filter((it) => it.kind === "plaintext");
+  if (targets.length === 0) {
+    return { ok: true, migrated: 0, message: "auth.json 中没有明文密钥，无需迁移", skipped: scan.items };
+  }
+
+  if (dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      wouldMigrate: targets.map((t) => {
+        const m = perProvider[t.provider] ?? method;
+        return {
+          provider: t.provider,
+          method: m,
+          target: m === "dpapi" ? t.suggestedDpapi : `$${t.suggestedEnv}`,
+        };
+      }),
+    };
+  }
+
+  const data = readAuth();
+  const p = authJsonPath();
+  const backup = `${p}.bak-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+  copyFileSync(p, backup);
+  log(`已备份 auth.json → ${backup}`);
+
+  const changes = [];
+  const warnings = [];
+
+  for (const item of targets) {
+    const chosen = perProvider[item.provider] ?? method;
+    if (chosen === "keep") {
+      log(`跳过 ${item.provider}（用户选择保留）`);
+      continue;
+    }
+
+    const plaintext = data[item.provider].key;
+
+    if (chosen === "dpapi") {
+      if (!dpapiAvailable()) {
+        warnings.push(`${item.provider}：DPAPI 不可用，已跳过`);
+        continue;
+      }
+      const name = `auth-${item.provider}`;
+      try {
+        setDpapiSecret(name, plaintext);
+      } catch (e) {
+        warnings.push(`${item.provider}：DPAPI 保存失败 — ${e instanceof Error ? e.message : String(e)}`);
+        continue;
+      }
+      data[item.provider].key = `dpapi:${name}`;
+      changes.push({ provider: item.provider, to: `dpapi:${name}`, method: "dpapi" });
+      log(`${item.provider} → dpapi:${name}`);
+      continue;
+    }
+
+    // env（默认）
+    const envName = envVarNameFor(item.provider);
+    try {
+      const r = setUserEnvVar(envName, plaintext);
+      if (!r.ok) {
+        warnings.push(`${item.provider}：${r.note}`);
+        continue;
+      }
+    } catch (e) {
+      warnings.push(`${item.provider}：写入环境变量失败 — ${e instanceof Error ? e.message : String(e)}`);
+      continue;
+    }
+
+    // 写入注册表后当前进程看不到；从注册表读回确认
+    const readBack = readUserEnvVar(envName);
+    if (readBack === undefined) {
+      warnings.push(`${item.provider}：环境变量 ${envName} 写入后读回失败，已跳过以免丢失密钥`);
+      continue;
+    }
+    if (readBack !== plaintext) {
+      warnings.push(`${item.provider}：环境变量 ${envName} 读回值不一致，已跳过以免丢失密钥`);
+      continue;
+    }
+
+    // 让当前进程立刻可用（这样本次运行不需要重启也能用）
+    process.env[envName] = plaintext;
+
+    data[item.provider].key = `$${envName}`;
+    changes.push({ provider: item.provider, to: `$${envName}`, method: "env", envName });
+    log(`${item.provider} → $${envName}`);
+  }
+
+  if (changes.length === 0) {
+    return { ok: false, error: "没有任何条目迁移成功", warnings, backup };
+  }
+
+  writeFileSync(p, JSON.stringify(data, null, 2), { encoding: "utf8", mode: 0o600 });
+  try {
+    chmodSync(p, 0o600);
+  } catch {
+    /* ignore */
+  }
+
+  // 校验：迁移后文件里不应再出现明文
+  const after = readFileSync(p, "utf8");
+  const stillPlain = scanAuthSecrets().items.filter((i) => i.kind === "plaintext");
+
+  return {
+    ok: stillPlain.length === 0,
+    migrated: changes.length,
+    changes,
+    warnings,
+    backup,
+    remainingPlaintext: stillPlain.map((s) => s.provider),
+    envVarsNeedRestart: changes.filter((c) => c.method === "env").map((c) => c.envName),
+    fileNote: after.length > 0 ? undefined : undefined,
+  };
+}
+
+/** 还原：从备份恢复 auth.json */
+export function restoreAuthJson(backupPath) {
+  const p = authJsonPath();
+  if (!existsSync(backupPath)) return { ok: false, error: `备份不存在：${backupPath}` };
+  copyFileSync(backupPath, p);
+  return { ok: true, restoredFrom: backupPath };
+}