nx-sk 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 本文件格式参考 [Keep a Changelog](https://keepachangelog.com/)，中文正文。
 
+## [0.7.0] - 2026-10-13
+
+### Added
+
+- **导入缺省「合并」：只增不减，不再整份替换**。`backup import` 旧行为是整份替换——跨源导入一个老结构的备份，本机栏目结构、条目、附件台账全被覆盖成备份的样子（原始事故：求职栏目的「附件资料」组消失）。现在缺省按「只增不减」合并：补缺失的栏目/条目/附件台账、补空字段、把备份多出的分组与字段只增补进已有栏目（复用 `mergeTemplate`）；**两边都有值且不同 → 保留本地**、列入冲突清单交用户处理；本地已有数据与结构**永不删改**。KV 栏目按名称匹配（跨机器 id 不可靠），普通栏目按 id。导入完成输出完整报告（CLI 文本 / 面板弹窗）：新增、补空、冲突、结构差异、附件统计、快照路径；`--dry-run` 可先看计划不落盘。`--replace` 保留旧的整份替换语义。敏感字段的补空值自动用本机 vaultKey 重新加密；报告里的值一律打码，密钥明文不进报告。
+- **`backup export --with-files`：附件原件入包（压缩包式）**。附件台账随包携带升级为**恒定行为**（v3 格式——0.5.x–0.6.2 的包根本不含 `files`，任何一次导入都会把台账清零，本次一并根修并加了回归钉）；`--with-files` 再把台账指向的原件读成 `{rel → {b64, sha256}}` 单块加密嵌入 `filesData`（与主数据同一把口令派生 key）。导入时自动落盘还原（sha256 校验；磁盘已有且内容不同以磁盘为准）；v2 旧包继续可导，缺原件在报告里如实列出。
+
+### Changed
+
+- 面板「加密备份」：导出加「连附件原件一起打包」勾选；导入拆成「解密并导入（合并）」与「整份替换…」（danger 确认）两个动作；结果以报告弹窗呈现；超过 28MB 的包提示走 CLI（接口请求体上限 32MB）。
+
+## [0.6.2] - 2026-10-12
+
+### Fixed
+
+- **加密备份：跨机器恢复后 store.json 里 secret 字段仍是密文**。0.6.1 把 secret 字段解开成明文后直接落回 store.json——丢了本机「落盘密文」防护。回归到 0.5.1 的设计：导出时用本机 vaultKey **解开** secret 字段、整包口令加密入 `.nxskbak`；导入时解开整包后**用本机 vaultKey 重新加密** secret 字段再写回 store.json。两条安全边界各自独立：本地靠 vaultKey、传递靠口令。
+
 ## [0.6.1] - 2026-10-12
 
 ### Changed

package/README.md

@@ -124,8 +124,8 @@ CLI 与 API 同源，skill 驱动 agent**。落到具体功能上：
 | `nx-sk file open <id>` | 用系统默认程序打开原件 |
 | `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 backup export [--password 口令] [--out DIR] [--with-files] [--dry-run]` | 口令对称加密整库，导出单个 `.nxskbak`（口令不落盘；`--with-files` 连附件原件） |
+| `nx-sk backup import --file <备份> [--password 口令] [--replace] [--dry-run]` | 解密导入：缺省「合并」（只增补、不覆盖已有值，冲突列清单），`--replace` 整份替换；动手前自动留安全快照 |
 | `nx-sk setting get \| set` | 全局设置 |
 | `nx-sk skill list \| install \| get` | 把内置 skill 装给 agent / 给外部 agent 取上下文 |
 
@@ -207,13 +207,20 @@ nx-sk export list
 
 ```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 export --password '你的备份口令' --with-files  # 连附件原件一起打包
+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 import --file ~/nx-sk/backup/xxx.nxskbak --password '你的备份口令' --replace  # 才是整份替换
 # 口令也可用环境变量 NX_SK_BACKUP_PASSWORD 提供
 ```
 
-Web 面板的「加密备份」页同样支持：导出在浏览器下载 `.nxskbak`，导入选择文件并输入口令；
-口令错误或文件损坏会明确报错、不改动当前数据。
+**导入缺省是「合并」**：只增补（补缺失的栏目/条目/附件、补空字段、结构只增不减），
+不覆盖你已填过的值——两边都有值且不同时保留本地、列入冲突清单由你处理；
+导入完成给出完整报告。`--replace` 才整份替换（灾难恢复 / 跨机器迁移用）。
+两种方式都先自动留安全快照。
+
+Web 面板的「加密备份」页同样支持：导出在浏览器下载 `.nxskbak`（可勾选连附件一起打包），
+导入选择文件并输入口令、报告以弹窗呈现；口令错误或文件损坏会明确报错、不改动当前数据。
 
 ## 数据与安全
 
@@ -225,7 +232,7 @@ Web 面板的「加密备份」页同样支持：导出在浏览器下载 `.nxsk
 | 快照 | 每次破坏性写入前整库备份到 `~/nx-sk/backup/`（最多 20 份），拷回即回滚 |
 | 导出 | `~/nx-sk/export/`，默认不含凭据明文 |
 | 附件 | `~/nx-sk/files/` 存二进制原件，元数据在 `store.json` 的 `files`（sha256 去重；条目 `file` 字段存附件 id 即建立链接；`file restore` 可逆） |
-| 加密备份 | `.nxskbak`：整库经 scrypt(口令)+AES-256-GCM 加密，口令不落盘；恢复前自动留安全快照 |
+| 加密备份 | `.nxskbak`：整库经 scrypt(口令)+AES-256-GCM 加密，口令不落盘；附件台账恒随包（`--with-files` 连原件）；导入缺省「合并」只增不减，`--replace` 整份替换；动手前自动留安全快照 |
 | 服务绑定 | 默认 `127.0.0.1`，不暴露到局域网；写操作校验 `Origin` |
 | 数据损坏 | `store.json` 解析失败会先被改名为 `.corrupt-<时间戳>.json`，不会静默覆盖 |
 
@@ -258,7 +265,7 @@ nx-sk skill get nx-sk 10-sections-entries   # 裸名 → references/10-sections-
 ## 开发
 
 ```bash
-pnpm test        # = lint + build + 冒烟（98 项断言） + 单测（116 项）
+pnpm test        # = lint + build + 冒烟（99 项断言） + 单测（127 项）
 ```
 
 | 目录 | 职责 |

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

@@ -82,15 +82,23 @@ cp ~/nx-sk/backup/20260924-144238-entry-remove-e_xxx.json ~/nx-sk/store.json
 ## 五、口令加密备份 / 恢复（导入导出）
 
 整份数据用**口令派生密钥 + AES-256-GCM** 对称加密为单个 `.nxskbak` 文件；口令不落盘。
+附件**台账**始终随包；`--with-files` 再把原件本体也嵌进包里（v3 格式）。
 
 ```bash
 nx-sk backup export --password '备份口令'                 # → ~/nx-sk/backup/nx-sk-backup-<时间>.nxskbak
+nx-sk backup export --password '备份口令' --with-files    # 连附件原件一起打包（体积显著变大）
 nx-sk backup export --password '备份口令' --out D:/备份    # 指定输出目录
-nx-sk backup import --file <备份>.nxskbak --password '备份口令' --dry-run  # 只解密校验，不改动
-nx-sk backup import --file <备份>.nxskbak --password '备份口令'            # 整份恢复
+
+nx-sk backup import --file <备份>.nxskbak --password '口令' --dry-run  # 只解密 + 出合并计划，不改动
+nx-sk backup import --file <备份>.nxskbak --password '口令'            # 缺省「合并」导入
+nx-sk backup import --file <备份>.nxskbak --password '口令' --replace  # 整份替换（旧行为）
 ```
 
 - 导出时文件内写入**随机盐**，密钥由 `scrypt(口令, 盐)` 派生；恢复时用同一口令派生同一把密钥。
 - **口令错误 / 文件被篡改**：GCM 认证失败、明确报 BLOCKED，且不改动当前数据。
-- 恢复（整份替换）前会**自动给当前数据另留一份安全快照**（`…-before-restore.json`），可回滚。
-- 口令也可用环境变量 `NX_SK_BACKUP_PASSWORD` 提供；Web「加密备份」页提供同样能力（浏览器下载 / 选择文件导入）。
+- **导入（缺省 = 合并）只增不减**：补缺失的栏目/条目/附件台账、补空字段、把备份多出的分组与字段补进已有栏目；**两边都有值且不同 → 保留本地**、列入冲突清单由你处理；本地已有数据与结构**永不删改**。报告会列出新增/补空/冲突/结构差异的完整明细。
+- **`--replace` 才是整份替换**（灾难恢复 / 跨机器迁移用）：当前数据被备份整体覆盖。
+- 两种方式都会**先自动留安全快照**（`…-before-import.json` / `…-before-restore.json`），可回滚。
+- 敏感字段在包内是明文（靠口令保护），导入时自动用**本机 vaultKey** 重新加密落盘——报告里的值一律打码，密钥明文不进报告。
+- 带 `--with-files` 的包导入时自动还原附件原件（sha256 校验；磁盘已有且内容不同则以磁盘为准）；v2 旧包可导入，但不含原件，报告会如实列出缺哪些文件。
+- 口令也可用环境变量 `NX_SK_BACKUP_PASSWORD` 提供；Web「加密备份」页提供同样能力（浏览器下载 / 选择文件导入；超大包建议走 CLI）。

package/package.json

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

package/src/modules/backup/index.js

@@ -10,10 +10,11 @@ export default {
       id: 'backup.export',
       cli: ['backup', 'export'],
       http: ['POST', '/api/backup'],
-      summary: '把整份数据用口令对称加密（AES-256-GCM）导出为单个备份文件；口令不落盘',
+      summary: '把整份数据用口令对称加密（AES-256-GCM）导出为单个备份文件；口令不落盘；--with-files 连附件原件一起打包',
       flags: {
         password: { type: 'string', hint: '备份口令（也可用环境变量 NX_SK_BACKUP_PASSWORD），恢复时需再次输入' },
         out: { type: 'string', hint: '输出目录，缺省 ~/nx-sk/backup' },
+        'with-files': { type: 'boolean', hint: '把附件原件一并嵌进备份（体积显著变大；恢复时自动还原附件库）' },
         'dry-run': { type: 'boolean', hint: '只演练：生成密文但不写文件、不下载' },
       },
       run: (ctx, meta) => (meta?.transport === 'http'
@@ -25,15 +26,19 @@ export default {
       id: 'backup.import',
       cli: ['backup', 'import'],
       http: ['POST', '/api/backup/restore'],
-      summary: '选择加密备份文件并输入口令，解密后整份恢复；恢复前自动给当前数据留安全快照',
+      summary: '解密备份并导入：缺省合并进当前数据（只增补、不覆盖已有值，冲突列出待手动处理），--replace 才整份替换；两种方式都先留安全快照',
       flags: {
         password: { type: 'string', hint: '导出时设置的口令（也可用环境变量 NX_SK_BACKUP_PASSWORD）' },
         file: { type: 'string', hint: '备份文件路径（CLI 用）' },
         content: { type: 'string', hint: '备份文件内容（Web 上传时自动带）' },
-        'dry-run': { type: 'boolean', hint: '只解密校验，不替换数据、不留快照' },
+        replace: { type: 'boolean', hint: '整份替换（旧行为）：当前数据被备份整体覆盖；缺省是合并' },
+        'dry-run': { type: 'boolean', hint: '只解密校验并出合并计划，不写数据、不留快照' },
       },
       run: (ctx) => (ctx.content !== undefined
-        ? service.restoreBackup({ content: ctx.content, password: ctx.password, 'dry-run': ctx['dry-run'] })
+        ? service.restoreBackup({
+          content: ctx.content, password: ctx.password,
+          replace: ctx.replace === true, 'dry-run': ctx['dry-run'],
+        })
         : service.importBackup(ctx)),
       render: (d) => service.renderRestore(d),
     },