nx-sk 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-08
+
+### Added
+
+- **口令对称加密的整库备份 / 恢复（导入导出）**：新增「加密备份」模块（CLI `backup export|import`，Web 同名面板，HTTP `POST /api/backup` 与 `POST /api/backup/restore`）。
+  - 导出：设置口令 → 整份数据（栏目 / 条目 / 设置）经 **scrypt 口令派生密钥 + AES-256-GCM** 加密为单个 `.nxskbak` 文件并在浏览器下载；文件内含随机盐，**口令不落盘**。
+  - 导入：选择备份文件并输入口令 → 解密校验后整份恢复；**恢复前自动给当前数据留安全快照**（可回滚）。
+  - 口令错误或文件被篡改：GCM 认证失败、明确报 BLOCKED，且不改动当前数据；两个动作均支持 `--dry-run`（只演练 / 只解密校验）。
+  - 口令也可用环境变量 `NX_SK_BACKUP_PASSWORD` 提供；复用 `core/crypto.js` 原语，与字段级密钥库（`core/vault.js`）相互独立。
+
+## [0.3.4] - 2026-09-26
+
+### Added
+
+- **多行值的可靠通道**：`key set <名> -`（stdin）与 `key set <名> --data @文件.json`
+  （也接受 `-` 与 JSON 字面量）。对象含 `value` 键时取它，只含一个键时取那个键，
+  多键且无 `value` 直接报错而不是猜。
+
+### Fixed
+
+- **Git Bash 下多行参数不再被静默截断**（原始事故）：转发器里 `exec node` 走的是
+  PATH 上的 node，而它可能是 Volta 之类的中转 shim，那一跳会把 `$'l1\nl2\nl3'`
+  截成 `l1` 且**不报错**——一次性凭据就这么丢掉大半。改为直连本进程的
+  `process.execPath`，并带路径失效回退（node 升级换目录时退回 PATH，重跑
+  `link:local` 即恢复）。
+- **恢复被删的 `references/40-extend.md`**：它与 SKILL.md 路由表里的条目被**同时**
+  删掉，于是「路由表 ↔ 目录双向对账」两边一起变空、照样通过——这个 ref 就这样被
+  删了两次。新增断言钉住「ref 体系整体不被削掉」（必存 ref 下限 + 编号升序唯一），
+  已做反向验证（删文件时确实变红）。
+
+### Notes
+
+- **`.cmd` 那条路修不了**：实测直连真实 `node.exe` 与走 shim 结果**完全相同**
+  （多行都截断、尖括号都失败），瓶颈是 cmd.exe 解析 `.cmd` 内容时的 `%*` 展开。
+  cmd / PowerShell 下多行值必须走 `-` 或 `@文件`。
+- 原计划要在 CLI 里做「检测到含换行就拒绝」，实测后**放弃**：损坏后 CR 是被删掉而非
+  保留（`$'a\rb'` 实际落盘 `"ab"`），零真阳性；而 `@文件` 读入的合法 CRLF 多行值含
+  CR，会被自己的检测拦住（高假阳性）。LF 截断后与合法单行值不可区分——可靠信号不存在。
+
 ## [0.3.3] - 2026-09-26
 
 ### Fixed

package/README.md

@@ -117,6 +117,8 @@ CLI 与 API 同源，skill 驱动 agent**。落到具体功能上：
 | `nx-sk entry fields [--section job]` | 字段字典 —— 填之前先看这个，别猜字段名 |
 | `nx-sk export run [--format json\|md\|both] [--section id] [--with-secrets] [--out DIR] [--dry-run]` | 整体导出 |
 | `nx-sk export list` | 历次导出与目录内文件 |
+| `nx-sk backup export [--password 口令] [--out DIR] [--dry-run]` | 口令对称加密整库，导出单个 `.nxskbak`（口令不落盘） |
+| `nx-sk backup import --file <备份> [--password 口令] [--dry-run]` | 输入口令解密、整份恢复（恢复前自动留安全快照） |
 | `nx-sk setting get \| set` | 全局设置 |
 | `nx-sk skill list \| install \| get` | 把内置 skill 装给 agent / 给外部 agent 取上下文 |
 
@@ -161,6 +163,18 @@ nx-sk export run --format both --out D:/备份/nx-sk
 nx-sk export list
 ```
 
+加密备份 / 恢复（口令对称加密，AES-256-GCM；导出设口令、恢复输口令）：
+
+```bash
+nx-sk backup export --password '你的备份口令'            # 写成 ~/nx-sk/backup/*.nxskbak
+nx-sk backup import --file ~/nx-sk/backup/xxx.nxskbak --password '你的备份口令' --dry-run  # 先只解密校验
+nx-sk backup import --file ~/nx-sk/backup/xxx.nxskbak --password '你的备份口令'            # 整份恢复
+# 口令也可用环境变量 NX_SK_BACKUP_PASSWORD 提供
+```
+
+Web 面板的「加密备份」页同样支持：导出在浏览器下载 `.nxskbak`，导入选择文件并输入口令；
+口令错误或文件损坏会明确报错、不改动当前数据。
+
 ## 数据与安全
 
 | 项 | 位置 / 做法 |
@@ -170,6 +184,7 @@ nx-sk export list
 | 密文密钥 | 环境变量 `NX_SK_PASSPHRASE`（scrypt 派生 + 盐）优先，否则 `~/nx-sk/.vaultkey`（32 字节随机，0600） |
 | 快照 | 每次破坏性写入前整库备份到 `~/nx-sk/backup/`（最多 20 份），拷回即回滚 |
 | 导出 | `~/nx-sk/export/`，默认不含凭据明文 |
+| 加密备份 | `.nxskbak`：整库经 scrypt(口令)+AES-256-GCM 加密，口令不落盘；恢复前自动留安全快照 |
 | 服务绑定 | 默认 `127.0.0.1`，不暴露到局域网；写操作校验 `Origin` |
 | 数据损坏 | `store.json` 解析失败会先被改名为 `.corrupt-<时间戳>.json`，不会静默覆盖 |
 
@@ -197,7 +212,6 @@ nx-sk skill get nx-sk 10-sections-entries   # 裸名 → references/10-sections-
 | `10-sections-entries` | 填/改信息的完整命令与 AI 补全流程 |
 | `20-secrets` | 密文机制、密钥来源、排查「解不开」 |
 | `30-export-backup` | 导出、快照与回滚 |
-| `40-extend` | 改这个项目本身：闭环落点表与静默失效点 |
 
 ## 开发
 
@@ -215,7 +229,9 @@ pnpm test        # = lint + build + 冒烟（56 项断言） + 单测（40 项
 | `assets/nx-sk/` | 随包分发的 skill（SKILL.md + references/） |
 | `tests/unit/` · `tests/smoke.mjs` | 一致性断言 + 端到端冒烟 |
 
-**加一个功能域要碰的 12 处**（其中 3 处没有任何断言会替你发现）见 `assets/nx-sk/references/40-extend.md`。
+**加一个功能域要碰的 12 处**（其中 3 处没有任何断言会替你发现）属于**开发规范、不属于随包分发的
+agent 手册** —— 它写在创建本项目的脚手架 skill `server-cli-web-scaffold` 的
+`references/A07-extension-loop.md`，`assets/nx-sk/` 里只放「怎么用 nx-sk」。
 
 ## License
 

package/assets/nx-sk/SKILL.md

@@ -73,7 +73,6 @@ nx-sk key remove OPENAI_KEY               # 删除，写前自动留快照
 | `10-sections-entries` | **动手填/改信息时必读**——栏目与条目的完整命令、AI 补全个人信息的推荐流程、字段字典怎么扩、读命令与写命令的参数陷阱 |
 | `20-secrets` | 存/读大模型 key、密文机制、密钥来源（环境变量 vs 本机密钥文件）、什么时候会解不开 |
 | `30-export-backup` | 整体导出、只导出某个栏目、快照与回滚、明文密钥的取舍 |
-| `40-extend` | 要**改这个项目本身**（加一个栏目模板、加一个功能域）时——闭环落点表与静默失效点 |
 
 取 ref 全文（外部 agent 用这条，不必进终端翻文件）：
 

package/assets/nx-sk/references/00-design.md

@@ -112,5 +112,5 @@ CLI 侧这四个取值分别渲染成不同的可读提示，退出码只有「
 | 删条目/栏目不留快照 | 误删即不可逆；这是用户的**唯一一份**个人信息 | 所有破坏性写操作先 `snapshotStore()` 到 `~/nx-sk/backup/` |
 | store.json 解析失败就当空库继续 | 下一次写入把用户数据永久覆盖 | 先把损坏文件改名为 `store.json.corrupt-<时间>.json`，再降级返回空结构 |
 | 前端 import 了 `node:*` 或 `core/` | Vite 把 Node 侧代码打进浏览器包，dev 模式白屏 | lint 的 `files` 同时覆盖 `view.jsx`，禁掉 `node:*` / `core` / `runtime` / `service.js` |
-| 新增模块忘了往 eslint 互依禁列里补一行 | **静默**：新模块变成「谁都可以依赖」，且规则随模块数增加持续衰减 | 把「加模块必补禁列」写进 `40-extend` 的闭环表，并在禁列旁留注释说明漏补是静默的 |
+| 新增模块忘了往 eslint 互依禁列里补一行 | **静默**：新模块变成「谁都可以依赖」，且规则随模块数增加持续衰减 | 在禁列旁留注释说明它是**逐模块枚举**的、漏补是静默的；加模块前先读 `eslint.config.js` |
 | 代理前缀 `/api` 与前端源码目录 `api/` 撞车 | 只在 dev 模式整页白屏，报错却是 404 / ECONNREFUSED，离根因很远 | vite 代理加 `bypass`，按「是不是前端资源」分流；并用测试钉住 `shouldServeLocally` |

package/assets/nx-sk/references/10-sections-entries.md

@@ -31,7 +31,7 @@ store.json（~/nx-sk/store.json 或 $NX_SK_STORE）
 - `remove` 目标不存在时**报 `NOT_FOUND`**（不静默成功），就是为了让「打错一个字」当场暴露。
 - `dump` 是「快速获得一个栏目的全部信息」的正解：字段字典 + 全部条目 + 每个条目的完整度与**未填清单**。
 
-内置模板：`job`（求职 / 个人信息，约 70 字段 / 9 分组）、`secret`（密钥，**单字段 KV**——细节见 `20-secrets`）。
+内置模板 5 个：`job`（求职 / 个人信息，75 字段 / 9 分组）、`projects`（项目经历）、`internships`（实习/工作经历）、`campus`（校内职务/实践）、`secret`（密钥，**单字段 KV**——细节见 `20-secrets`）。三类经历栏目（projects / internships / campus）**一个项目 / 一段经历 = 一个条目**，角色、时间、技术栈都是独立字段——不要往 job 栏目里塞经历。
 
 ## 三、条目命令
 

package/assets/nx-sk/references/20-secrets.md

@@ -91,6 +91,43 @@ nx-sk section list                           # 列表里 KV 栏目带 [KV 表]
 - **重复写同一个值不会重写密文**：返回 `{ status: 'skipped', unchanged: true }`。
   每次加密都用新 IV，无脑重写只会产生一堆无意义的新密文和新快照。
 
+### 多行值：走 stdin 或 `@文件`（真实事故）
+
+Windows 上命令经启动器转发时，**命令行参数里的换行会被截断**，而命令**照样报成功**——
+一次性凭据（多行私钥、恢复码、证书）就这么静默丢掉后半截。同一条通道还会让含 `<` `>`
+的参数整串失败（被当成重定向符，报「系统找不到指定的路径」）。
+
+值的可靠通道有两条，任选：
+
+```bash
+printf '%s' "$KEY" | nx-sk key set OPENAI_KEY -        # stdin：值的位置参数写 -
+nx-sk key set OPENAI_KEY --data @C:/Users/me/值.json    # 文件：--data @路径（含 value 键）
+```
+
+`--data` 也接受 `-`（从 stdin 读 JSON）与直接给 JSON 字面量；对象含 `value` 键时取它，
+只含一个键时取那个键，多键且无 `value` 直接报错（不猜）。
+
+**路径必须用 Windows 形式**（`C:/Users/...`）：Git Bash 的 `/tmp` 在 node 侧看不到
+（实测 ENOENT），node 侧拿到的会是 `D:\tmp\...` 这种对不上的路径。
+
+#### 哪些情况下命令行参数本身是安全的
+
+实测（Windows 11 · Volta · Git Bash）分两种情况，**别当成一回事**：
+
+| 你在哪敲 | 命令行多行参数 | 说明 |
+| --- | --- | --- |
+| **Git Bash / WSL 终端** | ✅ **安全** | 0.3.4 起转发器直连真实 `node.exe`，绕开了会截断参数的那一跳 |
+| **cmd.exe / PowerShell** | ❌ **损坏** | 瓶颈是 cmd 解析 `.cmd` 文件内容（`%*` 展开），换 node 也治不了 |
+
+所以：**cmd / PowerShell 下多行值一律走 `-` 或 `@文件`**，这是硬要求；
+Git Bash 下裸参数已经能用，但脚本里要可移植的话，仍然推荐上面两条通道。
+
+> 没有「检测到损坏就报错」这回事——**做不到**。损坏后的值里 CR 是被**删掉**而非保留
+> （`$'a\rb'` 实际落盘 `"ab"`），所以「含 CR 即损坏」既抓不到真实损坏（零真阳性）、
+> 又会拦住用 `@文件` 写入的**合法 CRLF 多行值**（高假阳性）。而 LF 截断后与一个合法的
+> 单行值完全不可区分。可靠信号不存在，因此只能「提供可靠通道 + 修好通道本身」，
+> 不能靠事后检测兜底。
+
 ## 三、密文机制
 
 - 算法 **AES-256-GCM**（`core/crypto.js`）。每个值独立 IV，带认证标签。

package/assets/nx-sk/references/30-export-backup.md

@@ -78,3 +78,19 @@ cp ~/nx-sk/backup/20260924-144238-entry-remove-e_xxx.json ~/nx-sk/store.json
 | 内容 | 结构化 + 可读的 Markdown；凭据默认含明文（`--no-secrets` 可打码） | 原样的整库 JSON（含密文） |
 | 位置 | `~/nx-sk/export/`（可改） | `~/nx-sk/backup/`（固定） |
 | 回滚用 | 不能直接回滚（形状不同） | 能，拷回 store.json 即可 |
+
+## 五、口令加密备份 / 恢复（导入导出）
+
+整份数据用**口令派生密钥 + AES-256-GCM** 对称加密为单个 `.nxskbak` 文件；口令不落盘。
+
+```bash
+nx-sk backup export --password '备份口令'                 # → ~/nx-sk/backup/nx-sk-backup-<时间>.nxskbak
+nx-sk backup export --password '备份口令' --out D:/备份    # 指定输出目录
+nx-sk backup import --file <备份>.nxskbak --password '备份口令' --dry-run  # 只解密校验，不改动
+nx-sk backup import --file <备份>.nxskbak --password '备份口令'            # 整份恢复
+```
+
+- 导出时文件内写入**随机盐**，密钥由 `scrypt(口令, 盐)` 派生；恢复时用同一口令派生同一把密钥。
+- **口令错误 / 文件被篡改**：GCM 认证失败、明确报 BLOCKED，且不改动当前数据。
+- 恢复（整份替换）前会**自动给当前数据另留一份安全快照**（`…-before-restore.json`），可回滚。
+- 口令也可用环境变量 `NX_SK_BACKUP_PASSWORD` 提供；Web「加密备份」页提供同样能力（浏览器下载 / 选择文件导入）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-sk",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "nx-sk · 本机个人资源管理器（server-cli-web 骨架）：栏目化存储个人信息与大模型密钥，CLI 与 Web 同源，敏感字段密文落盘。",
   "type": "module",
   "bin": {

package/src/core/argsafe.js

@@ -0,0 +1,53 @@
+// CLI 参数安全：把「命令行传不了的东西」换成可传的形式。
+//
+// 为什么不放 runtime/spec.js：那里的 coerce() 是 CLI 与 HTTP **共用**的纯净解码器，
+// 而 HTTP 没有「命令行通道」这回事。CLI 专属的通道问题集中在 CLI 适配层解决。
+//
+// 背景（真实事故，见 ref 20-secrets）：Windows 上值经命令行参数传递时，启动器 shim
+// （Volta shim / npm 生成的 .cmd）会把换行当命令分隔符截断、把 < > 当重定向符，
+// 而命令**报成功**——一次性凭据就这么静默丢掉大半。文件与管道是可靠通道。
+//
+// 为什么不在这里做「检测损坏就报错」：实测做不到（详见 cli.js 的 expandSafeArgs）。
+// 损坏后的值里 CR 是被**删掉**而非保留，所以「含 CR」既抓不到损坏（零真阳性）、
+// 又会拦住用 --data 写入的合法 CRLF 多行值（高假阳性）；LF 截断后则与合法单行值
+// 完全不可区分。可靠的信号不存在，因此只能提供可靠通道 + 修好通道本身。
+import { readFileSync } from 'node:fs';
+import { badInput } from './errors.js';
+
+/**
+ * `--data` 的值：JSON 字面量 / `@文件路径` / `-`（stdin）。
+ *
+ * takeStdin 由调用方注入——CLI 传 readFileSync(0)，测试能换桩。
+ * 「读 stdin」因此不是一个无法测试的隐式依赖，也让本模块保持纯函数（不自己碰 fd 0）。
+ */
+export function parseDataArg(raw, takeStdin) {
+  const s = String(raw ?? '').trim();
+  if (!s) throw badInput('--data 需要一个 JSON 字面量、@文件路径，或 -（从 stdin 读）');
+  if (s === '-' || s === '@-') return parseJson(takeStdin(), '-');
+  if (s.startsWith('@')) return parseJson(readText(s.slice(1)), s.slice(1));
+  return parseJson(s, '--data'); // 直接给的字面 JSON
+}
+
+/** 值本身走 stdin 的入口（`key set NAME -`）。true 表示「这个值来自 stdin」。 */
+export function parseStdinValue(raw) {
+  return String(raw ?? '').trim() === '-';
+}
+
+function parseJson(text, src) {
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw badInput(`--data 不是合法 JSON（${src}）: ${e.message}`);
+  }
+}
+
+function readText(p) {
+  try {
+    return readFileSync(p, 'utf8');
+  } catch (e) {
+    // 路径写法是最常见的坑：Git Bash 的 /tmp 在 node 侧看不到（真实事故 ENOENT），
+    // 所以错误里直接把 Windows 路径形式写出来，省掉一轮排查。
+    throw badInput(`读取文件失败: ${p}（${e.message}）—— Windows 上请用 C:/Users/... 形式的路径`);
+  }
+}
+

package/src/modules/backup/index.js

@@ -0,0 +1,41 @@
+import * as service from './service.js';
+
+export default {
+  id: 'backup',
+  title: '加密备份',
+  order: 750,
+  view: () => import('./view.jsx'),
+  actions: [
+    {
+      id: 'backup.export',
+      cli: ['backup', 'export'],
+      http: ['POST', '/api/backup'],
+      summary: '把整份数据用口令对称加密（AES-256-GCM）导出为单个备份文件；口令不落盘',
+      flags: {
+        password: { type: 'string', hint: '备份口令（也可用环境变量 NX_SK_BACKUP_PASSWORD），恢复时需再次输入' },
+        out: { type: 'string', hint: '输出目录，缺省 ~/nx-sk/backup' },
+        'dry-run': { type: 'boolean', hint: '只演练：生成密文但不写文件、不下载' },
+      },
+      run: (ctx, meta) => (meta?.transport === 'http'
+        ? service.buildBackup(ctx)
+        : service.exportBackup(ctx)),
+      render: (d) => service.renderBackup(d),
+    },
+    {
+      id: 'backup.import',
+      cli: ['backup', 'import'],
+      http: ['POST', '/api/backup/restore'],
+      summary: '选择加密备份文件并输入口令，解密后整份恢复；恢复前自动给当前数据留安全快照',
+      flags: {
+        password: { type: 'string', hint: '导出时设置的口令（也可用环境变量 NX_SK_BACKUP_PASSWORD）' },
+        file: { type: 'string', hint: '备份文件路径（CLI 用）' },
+        content: { type: 'string', hint: '备份文件内容（Web 上传时自动带）' },
+        'dry-run': { type: 'boolean', hint: '只解密校验，不替换数据、不留快照' },
+      },
+      run: (ctx) => (ctx.content !== undefined
+        ? service.restoreBackup({ content: ctx.content, password: ctx.password, 'dry-run': ctx['dry-run'] })
+        : service.importBackup(ctx)),
+      render: (d) => service.renderRestore(d),
+    },
+  ],
+};

package/src/modules/backup/service.js

@@ -0,0 +1,188 @@
+// 加密备份 / 恢复：整份数据用「口令派生密钥 + AES-256-GCM」对称加密。
+//
+// 导出：用户设置口令 → 随机盐写进备份文件，密钥由 scrypt(口令, 盐) 派生（口令不落盘）。
+// 导入：用户输入口令 → 用文件里的盐派生同一把密钥解密；口令错误 GCM 校验失败、明确报错。
+//
+// 复用 core/crypto.js 的原语（deriveKey / encryptValue / decryptValue），
+// 与字段级密钥库（core/vault.js）相互独立：备份口令是一次性的，不写进 vault。
+import fsp from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { resolve } from 'node:path';
+import { displayPath, snapshotDir } from '../../core/paths.js';
+import { ensureDir, fileSize, pathExists, writeAtomic } from '../../core/fsx.js';
+import { loadStore, saveStore, snapshotStore } from '../../core/store.js';
+import { deriveKey, encryptValue, decryptValue } from '../../core/crypto.js';
+import { badInput, blocked } from '../../core/errors.js';
+import { nowIso, stamp } from '../../core/ids.js';
+
+export const BACKUP_KIND = 'encrypted-backup';
+export const BACKUP_VERSION = 1;
+export const ENV_BACKUP_PASSWORD = 'NX_SK_BACKUP_PASSWORD';
+const EXT = '.nxskbak';
+
+function passwordFrom(ctx) {
+  const pw = ctx?.password ?? process.env[ENV_BACKUP_PASSWORD];
+  const s = String(pw ?? '');
+  if (!s) {
+    throw badInput(
+      `备份口令不能为空（用 --password，或设置环境变量 ${ENV_BACKUP_PASSWORD}）。` +
+      '口令用于加密备份文件，导入时需要再次输入。',
+    );
+  }
+  return s;
+}
+
+/** 生成加密备份：返回归档对象（HTTP 端据此让浏览器下载）与条目计数。 */
+export async function buildBackup(ctx) {
+  const password = passwordFrom(ctx);
+  const store = await loadStore();
+  const payload = {
+    version: store.version,
+    settings: store.settings,
+    sections: store.sections,
+    entries: store.entries,
+    exports: store.exports,
+  };
+
+  const salt = randomBytes(16);
+  const key = deriveKey(password, salt);
+  const data = encryptValue(key, JSON.stringify(payload));
+  const archive = {
+    app: 'nx-sk',
+    kind: BACKUP_KIND,
+    v: BACKUP_VERSION,
+    createdAt: nowIso(),
+    kdf: 'scrypt',
+    salt: salt.toString('base64'),
+    data,
+  };
+  const counts = { sections: store.sections.length, entries: store.entries.length };
+  if (ctx['dry-run']) return { dryRun: true, counts };
+  return { archive, counts };
+}
+
+/** CLI 导出：把加密备份写成文件（缺省放到 ~/nx-sk/backup）。 */
+export async function exportBackup(ctx) {
+  const built = await buildBackup(ctx);
+  if (built.dryRun) return { status: 'skipped', dryRun: true, ...built.counts };
+  const { archive, counts } = built;
+  const dir = ctx.out ? resolve(ctx.out) : snapshotDir();
+  const name = `nx-sk-backup-${stamp()}${EXT}`;
+  await ensureDir(dir);
+  const file = resolve(dir, name);
+  await writeAtomic(file, JSON.stringify(archive, null, 2) + '\n');
+  return {
+    status: 'ok',
+    file: displayPath(file),
+    fileRaw: file,
+    bytes: await fileSize(file),
+    encrypted: true,
+    ...counts,
+  };
+}
+
+function parseArchive(text) {
+  let archive;
+  try {
+    archive = JSON.parse(text);
+  } catch (e) {
+    throw badInput(`备份文件不是合法 JSON（${e.message}）——请确认选择的是 nx-sk 导出的 ${EXT} 文件`);
+  }
+  if (!archive || archive.app !== 'nx-sk' || archive.kind !== BACKUP_KIND || !archive.data) {
+    throw badInput(`不是 nx-sk 的加密备份文件（缺少 app/kind 标记）`);
+  }
+  if (archive.v !== BACKUP_VERSION) {
+    throw badInput(`备份文件版本不受支持: v${archive.v}`);
+  }
+  return archive;
+}
+
+/** 用口令解密归档文本 → 备份时的 store 负载。口令错误在此抛 BLOCKED。 */
+export function decryptBackup(text, password) {
+  const archive = parseArchive(text);
+  if (!String(password ?? '')) throw badInput('请输入备份时设置的口令。');
+  let payload;
+  try {
+    const key = deriveKey(password, archive.salt);
+    payload = JSON.parse(decryptValue(key, archive.data));
+  } catch (e) {
+    if (e && (e.code === 'BLOCKED' || /解密失败/.test(String(e.message)))) {
+      throw blocked('解密失败：口令不正确，或备份文件已损坏。请确认输入的是导出时设置的口令。');
+    }
+    throw e;
+  }
+  if (!payload || !Array.isArray(payload.sections) || !Array.isArray(payload.entries)) {
+    throw badInput('备份内容缺少 sections / entries，无法恢复。');
+  }
+  return { payload, createdAt: archive.createdAt };
+}
+
+/** 恢复：解密 → 先给当前数据留安全快照 → 整份替换（写入会过 normalize 迁移到当前版本）。 */
+export async function restoreBackup({ content, password, 'dry-run': dryRun }) {
+  const { payload, createdAt } = decryptBackup(String(content ?? ''), password);
+
+  if (dryRun) {
+    return {
+      status: 'dry-run', dryRun: true,
+      backupCreatedAt: createdAt || '',
+      sections: payload.sections.length,
+      entries: payload.entries.length,
+    };
+  }
+
+  // 覆盖前留一份可回滚快照（落到 backup/ 目录），避免误操作丢数据
+  const safety = await snapshotStore('before-restore');
+
+  await saveStore({
+    version: payload.version,
+    settings: payload.settings,
+    sections: payload.sections,
+    entries: payload.entries,
+    exports: Array.isArray(payload.exports) ? payload.exports : [],
+  });
+
+  return {
+    status: 'restored',
+    backupCreatedAt: createdAt || '',
+    sections: payload.sections.length,
+    entries: payload.entries.length,
+    safetySnapshot: displayPath(safety),
+  };
+}
+
+/** CLI 导入：从文件读取归档文本后恢复。 */
+export async function importBackup(ctx) {
+  const file = resolve(String(ctx.file ?? ''));
+  if (!ctx.file || !(await pathExists(file))) {
+    throw badInput(`找不到备份文件: ${ctx.file || '（未用 --file 指定）'}`);
+  }
+  const text = await fsp.readFile(file, 'utf8');
+  return restoreBackup({
+    content: text,
+    password: ctx.password ?? process.env[ENV_BACKUP_PASSWORD],
+    'dry-run': ctx['dry-run'],
+  });
+}
+
+export function renderBackup(d) {
+  if (d.status === 'skipped') {
+    return `试运行（未写盘、未下载）\n将加密备份: ${d.sections} 个栏目 / ${d.entries} 条条目（AES-256-GCM）`;
+  }
+  return [
+    `已生成加密备份（AES-256-GCM，口令派生密钥、口令不落盘）`,
+    `文件: ${d.file}　${d.bytes} 字节`,
+    `内容: ${d.sections} 个栏目 / ${d.entries} 条条目`,
+    `恢复时需要输入本次设置的口令。`,
+  ].join('\n');
+}
+
+export function renderRestore(d) {
+  if (d.status === 'dry-run') {
+    return `试运行（未改动当前数据）\n备份可正常解密: ${d.sections} 个栏目 / ${d.entries} 条条目，生成于 ${d.backupCreatedAt || '未知'}`;
+  }
+  return [
+    `已从加密备份恢复：${d.sections} 个栏目 / ${d.entries} 条条目`,
+    `备份生成于: ${d.backupCreatedAt || '未知'}`,
+    `恢复前的当前数据已留安全快照: ${d.safetySnapshot}`,
+  ].join('\n');
+}

package/src/modules/backup/view.jsx

@@ -0,0 +1,145 @@
+import { useRef, useState } from 'react';
+import { api } from '../../web/frontend/api/client.js';
+import { useStore } from '../../web/frontend/store.jsx';
+import { CliHints, Empty, Modal } from '../../web/frontend/components/ui.jsx';
+
+function fileStamp() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+function downloadText(filename, text) {
+  const blob = new Blob([text], { type: 'application/json;charset=utf-8' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+
+export default function BackupView() {
+  const { toast, guard, dialog, reload } = useStore();
+  const [pw, setPw] = useState('');
+  const [pw2, setPw2] = useState('');
+  const [restorePw, setRestorePw] = useState('');
+  const [picked, setPicked] = useState(null);
+  const [result, setResult] = useState(null);
+  const fileRef = useRef(null);
+
+  const doExport = guard(async () => {
+    if (!pw) { toast('请先设置备份口令', 'bad'); return; }
+    if (pw !== pw2) { toast('两次输入的口令不一致', 'bad'); return; }
+    const r = await api('/api/backup', { method: 'POST', body: { password: pw } });
+    const filename = `nx-sk-backup-${fileStamp()}.nxskbak`;
+    downloadText(filename, JSON.stringify(r.archive, null, 2) + '\n');
+    toast(`已生成加密备份：${r.counts.sections} 栏目 / ${r.counts.entries} 条目`);
+    setPw(''); setPw2('');
+  });
+
+  const onPick = async (e) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    const text = await file.text();
+    setPicked({ name: file.name, bytes: file.size, text });
+  };
+
+  const doRestore = guard(async () => {
+    if (!picked) { toast('请先选择备份文件', 'bad'); return; }
+    if (!restorePw) { toast('请输入备份口令', 'bad'); return; }
+    const ok = await dialog({
+      danger: true,
+      confirmText: '解密并整份恢复',
+      message: '恢复会用备份内容整份替换当前数据。',
+      detail: `备份文件：${picked.name}\n恢复前会自动给当前数据留一份安全快照（可回滚）。`,
+    });
+    if (!ok) return;
+    const r = await api('/api/backup/restore', {
+      method: 'POST',
+      body: { password: restorePw, content: picked.text },
+    });
+    setResult(r);
+    setRestorePw('');
+    setPicked(null);
+    if (fileRef.current) fileRef.current.value = '';
+    await reload();
+  });
+
+  return (
+    <>
+      <div className="toolbar rowgap pad">
+        <strong>加密备份</strong>
+        <span className="muted">整份数据用口令对称加密（AES-256-GCM）；导出设口令、恢复输口令，口令不落盘</span>
+      </div>
+
+      <div className="card">
+        <div className="colhead">加密导出</div>
+        <div className="pad stack">
+          <div className="grid">
+            <div className="field">
+              <div className="flabel"><span>设置备份口令</span><span className="fkey">建议至少 6 位</span></div>
+              <div className="fctrl">
+                <input type="password" autoComplete="new-password" value={pw} onChange={(e) => setPw(e.target.value)} placeholder="备份口令" />
+              </div>
+            </div>
+            <div className="field">
+              <div className="flabel"><span>再输入一次</span></div>
+              <div className="fctrl">
+                <input type="password" autoComplete="new-password" value={pw2} onChange={(e) => setPw2(e.target.value)} placeholder="确认口令" />
+              </div>
+            </div>
+          </div>
+          <div className="hint">导出为单个 .nxskbak 文件并在浏览器下载；文件内含随机盐，密钥由口令经 scrypt 派生。恢复时需要输入同一口令。</div>
+          <div className="rowgap">
+            <button className="btn" onClick={doExport}>加密导出并下载</button>
+          </div>
+        </div>
+      </div>
+
+      <div className="card">
+        <div className="colhead">解密恢复（导入）</div>
+        <div className="pad stack">
+          <div className="grid">
+            <div className="field">
+              <div className="flabel"><span>备份文件</span><span className="fkey">.nxskbak</span></div>
+              <div className="fctrl">
+                <input ref={fileRef} type="file" accept=".nxskbak,application/json" onChange={onPick} />
+              </div>
+            </div>
+            <div className="field">
+              <div className="flabel"><span>输入备份口令</span></div>
+              <div className="fctrl">
+                <input type="password" autoComplete="off" value={restorePw} onChange={(e) => setRestorePw(e.target.value)} placeholder="导出时设置的口令" />
+              </div>
+            </div>
+          </div>
+          {picked ? (
+            <div className="row">
+              <span className="mono name">{picked.name}</span>
+              <span className="acts"><span className="tag">{picked.bytes} 字节</span></span>
+            </div>
+          ) : <Empty>还没有选择备份文件。</Empty>}
+          <div className="hint">口令错误或文件损坏会明确报错、不会改动当前数据；确认恢复前会先留安全快照。</div>
+          <div className="rowgap">
+            <button className="btn danger" onClick={doRestore}>解密并恢复</button>
+          </div>
+        </div>
+      </div>
+
+      <CliHints module="backup" />
+
+      {result ? (
+        <Modal title="恢复完成" onClose={() => setResult(null)}>
+          <div className="stack">
+            <div>已从加密备份恢复：{result.sections} 个栏目 / {result.entries} 条条目</div>
+            <div className="muted">备份生成于 {result.backupCreatedAt || '未知'}</div>
+            <pre className="block">恢复前的安全快照：{result.safetySnapshot}</pre>
+          </div>
+        </Modal>
+      ) : null}
+    </>
+  );
+}

package/src/modules/entries/index.js

@@ -129,6 +129,9 @@ export default {
       args: ['name', 'value'],
       flags: {
         value: { type: 'string', hint: '值的另一种给法（值以 - 开头时用 --value=<值>）' },
+        // 多行值经命令行会被 Windows 启动器 shim 截断成首行且不报错（见 ref 20-secrets），
+        // 文件与 stdin 是可靠通道。取 value 键；没有则取对象里唯一那个键。
+        data: { type: 'string', hint: '@文件.json（含 value 键），或 -（从 stdin 读原文）' },
         section: { type: 'string' },
         'dry-run': { type: 'boolean' },
       },