nx-sk 0.4.0 → 0.6.1

package/src/core/attachments.js

@@ -0,0 +1,378 @@
+// 附件（二进制原件）的磁盘管理：~/nx-sk/files/ 下存储，元数据随 store.json 落盘。
+//
+// 设计要点：
+//   - 本机路径导入**默认移动**（用户明确要求：提交附件 = 把文件搬进 nx-sk 目录），
+//     `--copy` 才保留原件；Web 上传只有「复制」语义（浏览器删不掉任意路径的文件）。
+//   - 「可逆」：`file restore` 能把附件移回原始位置（或指定目录），并撤销台账记录；
+//     `--copy` 则只导出一份副本、库中保留。
+//   - 同 sha256 去重：完全相同的文件不重复占空间，直接回已有记录。
+//   - 元数据是**台账**：物理文件永远以台账 rel 为准；所有移动先改物理文件、再在事务里改台账。
+//   - 链接方式：条目里 `file` 字段的值 = 附件 id（或唯一文件名）。id 全局唯一，
+//     天然实现「各条目各自的附件空间互不串台」；同一份原件也可被多条条目复用（去重后同 id）。
+//     附件**不预定义任何分类/槽位结构**：附件中心按「哪些栏目在用它」动态分组（见 fileReferences）。
+import { createHash } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { basename, dirname, extname, join, parse, resolve, sep } from 'node:path';
+import { badInput } from './errors.js';
+import { displayPath, filesDir, isInside, toPosix } from './paths.js';
+import { ensureDir, hashFile } from './fsx.js';
+import { newId, nowIso } from './ids.js';
+
+// —— 分类 ——
+export const FILE_CATEGORIES = [
+  { id: 'resume', label: '简历' },
+  { id: 'avatar', label: '头像' },
+  { id: 'transcript', label: '成绩单' },
+  { id: 'certificate', label: '证书' },
+  { id: 'document', label: '文档' },
+  { id: 'other', label: '其他' },
+];
+
+export const CATEGORY_IDS = FILE_CATEGORIES.map((c) => c.id);
+export const categoryLabel = (id) => FILE_CATEGORIES.find((c) => c.id === id)?.label || '其他';
+
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp', '.svg', '.avif', '.ico']);
+const DOC_EXT = new Set(['.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx', '.txt', '.md', '.csv', '.wps', '.ofd']);
+
+export function isImageExt(ext) {
+  return IMAGE_EXT.has(String(ext || '').toLowerCase());
+}
+
+/** 按扩展名猜分类；猜不准归「其他」（头像/简历这种语义由调用方显式给）。 */
+export function categoryFromExt(ext) {
+  const e = String(ext || '').toLowerCase();
+  if (isImageExt(e)) return 'other';
+  if (DOC_EXT.has(e)) return 'document';
+  return 'other';
+}
+
+// —— 流式输出的 MIME ——
+export const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.pdf': 'application/pdf',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.ppt': 'application/vnd.ms-powerpoint',
+  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/plain; charset=utf-8',
+  '.csv': 'text/csv; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.bmp': 'image/bmp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.wps': 'application/octet-stream',
+  '.ofd': 'application/octet-stream',
+};
+
+// Windows 保留设备名，做文件名会让文件无法正常访问。
+const RESERVED_STEMS = new Set(['con', 'prn', 'aux', 'nul',
+  ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+  ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`)]);
+
+/** 把任意来源的名字收成跨平台可用的单段文件名（保留中文）。 */
+export function safeFileName(name) {
+  let s = String(name ?? '')
+    .replace(/[<>:"/\\|?*\x00-\x1f]/g, '_')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^\.+/, '');
+  if (!s) s = 'file';
+  const stem = parse(s).name;
+  if (RESERVED_STEMS.has(stem.toLowerCase())) s = `_${s}`;
+  return s.slice(0, 140);
+}
+
+/** 在台账里为「分类 + 文件名」找一个不冲突的 posix 相对路径（`(2)` 递增）。 */
+function uniqueRel(store, category, fileName, excludeId = null) {
+  const { name: stem, ext } = parse(fileName);
+  let rel = toPosix(join(category, fileName));
+  let n = 1;
+  while (store.files.some((r) => r.id !== excludeId && r.rel === rel)) {
+    n += 1;
+    rel = toPosix(join(category, `${stem} (${n})${ext}`));
+  }
+  return rel;
+}
+
+// —— 台账记录 ——
+export function normalizeFileRecord(raw) {
+  if (!raw || typeof raw !== 'object' || !raw.id || !raw.rel) return null;
+  const name = String(raw.name || basename(String(raw.rel)));
+  return {
+    id: String(raw.id),
+    // 分类只是**磁盘分目录**用的内部属性（`files/<分类>/`），不是用户要维护的「槽位」。
+    category: CATEGORY_IDS.includes(raw.category) ? raw.category : 'other',
+    name,
+    rel: toPosix(String(raw.rel)),
+    originalName: String(raw.originalName || name),
+    ext: String(raw.ext || extname(name).toLowerCase()),
+    bytes: Number(raw.bytes) || 0,
+    sha256: String(raw.sha256 || ''),
+    // 原始绝对路径（posix）；Web 上传没有，留空——还原时需显式给目标目录
+    sourcePath: String(raw.sourcePath || ''),
+    mode: ['move', 'copy', 'upload'].includes(raw.mode) ? raw.mode : 'upload',
+    tags: Array.isArray(raw.tags) ? raw.tags.map(String) : [],
+    note: String(raw.note || ''),
+    createdAt: raw.createdAt || null,
+    updatedAt: raw.updatedAt || null,
+  };
+}
+
+/** 附件定位：id 优先，其次唯一文件名。 */
+export function findFileRecord(store, ref) {
+  const key = String(ref ?? '').trim();
+  if (!key) return null;
+  const byId = store.files.find((r) => r.id === key);
+  if (byId) return byId;
+  const byName = store.files.filter((r) => r.name === key);
+  if (byName.length === 1) return byName[0];
+  return null;
+}
+
+/**
+ * 反向链接：哪些条目的 `file` 字段引用了这个附件。
+ * 条目里 `file` 字段的值 = 附件 id（或唯一文件名），所以按记录反查即可。
+ * 附件中心据此显示「被哪些栏目 / 条目 / 字段用到」——**完全由栏目驱动**，不预定义结构。
+ */
+export function fileReferences(store, rec) {
+  if (!rec) return [];
+  const out = [];
+  for (const sec of store.sections || []) {
+    const fileFields = (sec.fields || []).filter((f) => f.type === 'file');
+    if (!fileFields.length) continue;
+    for (const e of store.entries || []) {
+      if (e.section !== sec.id) continue;
+      for (const f of fileFields) {
+        const v = String(e.values?.[f.key] ?? '').trim();
+        if (!v) continue;
+        if (findFileRecord(store, v) !== rec) continue;
+        out.push({
+          sectionId: sec.id, sectionTitle: sec.title,
+          entryId: e.id, entryTitle: e.title,
+          fieldKey: f.key, fieldLabel: f.label,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * 附件中心的分组素材：哪些栏目带 `file` 字段。
+ * 中心据此按栏目筛选 / 分组 —— 组织方式**完全由栏目驱动，不预定义任何分类或槽位**。
+ */
+export function collectFileSections(store) {
+  return (store.sections || [])
+    .filter((s) => (s.fields || []).some((f) => f.type === 'file'))
+    .map((s) => ({ id: s.id, title: s.title }));
+}
+
+export function fileRecordAbs(rec) {
+  return join(filesDir(), rec.rel.split('/').join(sep));
+}
+
+export function fileLinks(rec) {
+  const u = `/api/files/${encodeURIComponent(rec.id)}/content`;
+  return { url: u, downloadUrl: `${u}?download=1` };
+}
+
+/** 对外（CLI / Web）的完整描述：物理路径 + 展示路径 + 链接（+ 可选的反向引用）。 */
+export function describeFile(rec, store = null) {
+  const abs = fileRecordAbs(rec);
+  return {
+    ...rec,
+    categoryLabel: categoryLabel(rec.category),
+    isImage: isImageExt(rec.ext),
+    path: abs,
+    displayPath: displayPath(abs),
+    sourceDisplay: rec.sourcePath ? displayPath(rec.sourcePath) : '',
+    usedBy: store ? fileReferences(store, rec) : [],
+    ...fileLinks(rec),
+  };
+}
+
+function buildRecord({ id, category, rel, srcAbs, originalName, ext: e, bytes, sha, mode, tags, note }) {
+  return normalizeFileRecord({
+    id, category, name: basename(rel), rel,
+    originalName: originalName || basename(rel),
+    ext: e, bytes, sha256: sha,
+    sourcePath: srcAbs ? toPosix(srcAbs) : '',
+    mode,
+    tags: Array.isArray(tags) ? tags.map(String) : [],
+    note: String(note || ''),
+    createdAt: nowIso(), updatedAt: nowIso(),
+  });
+}
+
+/**
+ * 从本机路径导入。默认**移动**，copy=true 才复制。
+ * dryRun 只做读取与落点计算，不碰目标位置。
+ */
+export async function importLocalFile(store, opts = {}) {
+  const { path: src, category, copy, tags, note, name, dryRun } = opts;
+  if (!src) throw badInput('缺少文件路径：--path <本机文件路径>');
+  const srcAbs = resolve(String(src));
+  let st;
+  try { st = await fsp.stat(srcAbs); } catch {
+    throw badInput(`读不到文件: ${displayPath(srcAbs)}`);
+  }
+  if (!st.isFile()) throw badInput(`不是文件: ${displayPath(srcAbs)}`);
+  if (isInside(filesDir(), srcAbs)) {
+    throw badInput('该文件已经在附件库目录里，无需重复导入');
+  }
+
+  const sha = await hashFile(srcAbs);
+  const dup = store.files.find((r) => r.sha256 === sha);
+  if (dup) return { record: dup, duplicate: true, dryRun: false };
+
+  const e = extname(srcAbs).toLowerCase();
+  const cat = category || categoryFromExt(e);
+  const fileName = safeFileName(name || basename(srcAbs));
+  const rel = uniqueRel(store, cat, fileName);
+  const record = buildRecord({
+    id: newId('f'), category: cat, rel, srcAbs, originalName: basename(srcAbs),
+    ext: e, bytes: st.size, sha, mode: copy ? 'copy' : 'move', tags, note,
+  });
+  if (dryRun) return { record, duplicate: false, dryRun: true };
+
+  const dst = join(filesDir(), rel.split('/').join(sep));
+  await ensureDir(dirname(dst));
+  if (copy) {
+    await fsp.copyFile(srcAbs, dst);
+  } else {
+    try {
+      await fsp.rename(srcAbs, dst);
+    } catch (err) {
+      // EXDEV：跨卷 rename 不被支持，退成「复制 + 删原件」，语义不变
+      if (err && err.code === 'EXDEV') {
+        await fsp.copyFile(srcAbs, dst);
+        await fsp.unlink(srcAbs);
+      } else throw err;
+    }
+  }
+  return { record, duplicate: false, dryRun: false, moved: !copy };
+}
+
+function decodeBase64(content) {
+  let b64 = String(content || '');
+  const comma = b64.indexOf(',');
+  if (b64.startsWith('data:') && comma >= 0) b64 = b64.slice(comma + 1);
+  let buf;
+  try { buf = Buffer.from(b64, 'base64'); } catch {
+    throw badInput('上传内容不是合法的 base64');
+  }
+  if (!buf.length) throw badInput('上传内容为空');
+  return buf;
+}
+
+/** Web 上传：base64（或 data URL）内容直接写进库。 */
+export async function importContent(store, opts = {}) {
+  const { content, name, category, tags, note, dryRun } = opts;
+  if (content === undefined || content === null) throw badInput('缺少上传内容');
+  if (!name) throw badInput('上传必须带文件名');
+  const buf = decodeBase64(content);
+  const sha = createHash('sha256').update(buf).digest('hex');
+  const dup = store.files.find((r) => r.sha256 === sha);
+  if (dup) return { record: dup, duplicate: true, dryRun: false };
+
+  const originalName = safeFileName(name);
+  const e = extname(originalName).toLowerCase();
+  const cat = category || categoryFromExt(e);
+  const rel = uniqueRel(store, cat, originalName);
+  const record = buildRecord({
+    id: newId('f'), category: cat, rel, srcAbs: null, originalName,
+    ext: e, bytes: buf.length, sha, mode: 'upload', tags, note,
+  });
+  if (dryRun) return { record, duplicate: false, dryRun: true };
+
+  const dst = join(filesDir(), rel.split('/').join(sep));
+  await ensureDir(dirname(dst));
+  await fsp.writeFile(dst, buf);
+  return { record, duplicate: false, dryRun: false, moved: false };
+}
+
+/**
+ * 改分类 / 文件名：物理文件先搬到新落点，返回新记录（由 service 在事务里落台账）。
+ */
+export async function relocateFile(store, rec, { category, name }) {
+  const cat = category || rec.category;
+  const fileName = safeFileName(name || rec.name);
+  const same = cat === rec.category && fileName === rec.name;
+  const rel = same ? rec.rel : uniqueRel(store, cat, fileName, rec.id);
+  if (!same) {
+    const oldAbs = fileRecordAbs(rec);
+    const newAbs = join(filesDir(), rel.split('/').join(sep));
+    await ensureDir(dirname(newAbs));
+    await fsp.copyFile(oldAbs, newAbs);
+    await fsp.unlink(oldAbs);
+  }
+  return normalizeFileRecord({ ...rec, category: cat, name: basename(rel), rel, updatedAt: nowIso() });
+}
+
+/** 删除物理原件；文件本就不存在视为成功（台账是权威）。 */
+export async function deletePhysical(rec) {
+  try {
+    await fsp.unlink(fileRecordAbs(rec));
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return;
+    throw err;
+  }
+}
+
+function nonClashPath(dir, fileName) {
+  const { name: stem, ext } = parse(fileName);
+  let dst = join(dir, fileName);
+  let n = 1;
+  const exists = async (p) => { try { await fsp.access(p); return true; } catch { return false; } };
+  return (async () => {
+    while (await exists(dst)) { n += 1; dst = join(dir, `${stem} (${n})${ext}`); }
+    return dst;
+  })();
+}
+
+/**
+ * 还原 / 导出：把附件复制到目标位置；copy=false（默认）时再删掉库内原件
+ * （由 service 负责撤销台账记录）。
+ */
+export async function restoreFile(store, rec, { to, copy } = {}) {
+  const targetDir = resolve(String(to || (rec.sourcePath ? dirname(rec.sourcePath) : '')));
+  if (!targetDir || targetDir === sep) {
+    throw badInput('该附件没有原始位置，需要给目标目录：--to <目录>');
+  }
+  const dst = await nonClashPath(targetDir, rec.name);
+  if (!copy && isInside(filesDir(), dst)) {
+    throw badInput('还原落点在附件库目录内，会自己覆盖自己；换一个目录');
+  }
+  await ensureDir(targetDir);
+  await fsp.copyFile(fileRecordAbs(rec), dst);
+  if (!copy) await fsp.unlink(fileRecordAbs(rec));
+  return { path: dst, displayPath: displayPath(dst), kept: copy === true };
+}
+
+/** 以正确的 Content-Type 把附件流式输出给浏览器；download=true 时强制下载。 */
+export function streamRecord(res, rec, { download = false } = {}) {
+  const file = fileRecordAbs(rec);
+  return new Promise((resolve, reject) => {
+    const rs = createReadStream(file);
+    rs.once('error', reject);
+    rs.once('open', () => {
+      res.writeHead(200, {
+        'content-type': MIME_TYPES[rec.ext] || 'application/octet-stream',
+        'content-disposition': `${download ? 'attachment' : 'inline'}; filename*=UTF-8''${encodeURIComponent(rec.name)}`,
+        'cache-control': 'no-cache',
+      });
+      rs.pipe(res);
+      rs.once('end', resolve);
+      rs.once('error', reject);
+    });
+  });
+}

package/src/core/fields.js

@@ -1,9 +1,9 @@
 // 字段字典：栏目的字段模板是**数据**，不是代码分支。
 // agent 与面板都从同一份声明渲染，所以「CLI 能填的字段」与「面板能填的字段」不可能分叉。
 //
-// type 取值：text | textarea | number | date | month | bool | select | tags | secret
+// type 取值：text | textarea | number | date | month | bool | select | tags | secret | file
 
-export const FIELD_TYPES = ['text', 'textarea', 'number', 'date', 'month', 'bool', 'select', 'tags', 'secret'];
+export const FIELD_TYPES = ['text', 'textarea', 'number', 'date', 'month', 'bool', 'select', 'tags', 'secret', 'file'];
 
 /**
  * 字段的**填写策略**——回答「这个字段值不值得填」，与 type 正交。
@@ -128,6 +128,12 @@ const JOB_FIELDS = [
   f('acceptAdjustment', '是否接受调剂', 'bool', 'job', { hint: '是否接受岗位或城市调剂' }),
   f('jobNote', '求职备注', 'textarea', 'job', { hint: '补充说明' }),
 
+  // —— 附件资料（统一附件库；值 = 附件 id，直接在字段里上传或从附件库选一个） ——
+  f('resumeFile', '简历附件', 'file', 'files', { kind: 'doc', hint: '简历 PDF/Word 原件；在本字段直接上传，或从附件库选一个' }),
+  f('avatar', '头像图片', 'file', 'files', { kind: 'image', hint: '证件照/头像图片原件' }),
+  f('transcript', '成绩单', 'file', 'files', { kind: 'doc', hint: '在校成绩单原件' }),
+  f('certificateScan', '证书扫描件', 'file', 'files', { kind: 'doc', fill: 'optional', hint: '获奖/资格证书扫描件（不必填）' }),
+
   // —— 其他 ——
   f('religion', '宗教信仰', 'text', 'extra', { hint: '没有就写「无」' }),
   f('unionVolunteer', '是否自愿加入公司工会', 'bool', 'extra'),
@@ -186,6 +192,7 @@ const TEMPLATES = {
       { id: 'emergency', title: '紧急联系' },
       { id: 'about', title: '自我描述' },
       { id: 'job', title: '求职意向' },
+      { id: 'files', title: '附件资料' },
       { id: 'extra', title: '其他' },
     ],
     fields: JOB_FIELDS,
@@ -313,6 +320,55 @@ export function syncSectionGroups(groups, fields) {
   return out;
 }
 
+/**
+ * 模板增量合并：把模板里**尚未出现在栏目**的分组与字段补进去（只增，绝不改/删）。
+ *
+ * 为什么需要它：栏目实例化时字段字典是**深拷贝**（见 instantiateTemplate），
+ * 从此「栏目自己的字段集独立演化」。于是模板后续新增的字段（例如给求职加
+ * 「附件资料」组的 4 个 `file` 字段）**不会回溯**到已经存在的栏目——
+ * 面板按栏目自己的字典渲染，老栏目里就永远看不到上传入口。
+ *
+ * 合并规则（尽量少动用户数据）：
+ *   - 分组：按模板顺序排列；栏目已有的分组**沿用栏目自己的定义**（标题可能被改过），
+ *     模板没有的自定义分组原顺序附在后面。
+ *   - 字段：栏目已有的字段原样保留（含用户改过的 label/hint/fill）；缺的模板字段
+ *     插到「模板顺序里它前一个字段」之后，未在模板中的自定义字段保持原位。
+ */
+export function mergeTemplate(section, template) {
+  const existingGroups = section?.groups || [];
+  const existingFields = section?.fields || [];
+  const groupById = new Map(existingGroups.map((g) => [g.id, g]));
+  const fieldKeys = new Set(existingFields.map((f) => f.key));
+
+  const groups = [];
+  const seenGroup = new Set();
+  for (const g of template?.groups || []) {
+    groups.push(groupById.get(g.id) || { ...g });
+    seenGroup.add(g.id);
+  }
+  for (const g of existingGroups) if (!seenGroup.has(g.id)) groups.push(g);
+  const addedGroups = (template?.groups || []).filter((g) => !existingGroups.some((x) => x.id === g.id)).map((g) => g.id);
+
+  const tplOrder = new Map((template?.fields || []).map((f, i) => [f.key, i]));
+  const fields = [...existingFields];
+  const addedFields = [];
+  for (const tf of template?.fields || []) {
+    if (fieldKeys.has(tf.key)) continue;
+    // 插到第一个「模板序更靠后」的既有字段之前；找不到就追加到末尾
+    const ti = tplOrder.get(tf.key);
+    let insertAt = fields.length;
+    for (let i = 0; i < fields.length; i += 1) {
+      const oi = tplOrder.get(fields[i].key);
+      if (oi !== undefined && oi > ti) { insertAt = i; break; }
+    }
+    fields.splice(insertAt, 0, { ...tf });
+    fieldKeys.add(tf.key);
+    addedFields.push(tf.key);
+  }
+
+  return { groups, fields, addedGroups, addedFields };
+}
+
 export function fieldByKey(section, key) {
   return (section?.fields || []).find((x) => x.key === key) || null;
 }

package/src/core/paths.js

@@ -50,6 +50,11 @@ export function exportDir() {
   return join(appHome(), 'export');
 }
 
+/** 附件统一存储目录：`~/nx-sk/files/`（简历、头像、成绩单等二进制原件都落在这里）。 */
+export function filesDir() {
+  return join(appHome(), 'files');
+}
+
 export function snapshotDir() {
   return join(appHome(), 'backup');
 }

package/src/core/render.js

@@ -133,6 +133,7 @@ export function dumpSection(section, entries, { mask = false, decrypt } = {}) {
       group: x.group,
       hint: x.hint || '',
       options: x.options || null,
+      kind: x.kind || '',
       sensitive: isSensitiveField(section, x.key),
       // 填写策略要跟着字段字典出去，否则面板与 agent 不知道哪个格子「不用填」
       fill: fillPolicy(x),

package/src/core/store.js

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { displayPath, snapshotDir, storeFile } from './paths.js';
 import { ensureDir, pathExists, writeAtomic, writeJsonAtomic } from './fsx.js';
 import { instantiateTemplate, seedSections, syncSectionGroups } from './fields.js';
+import { normalizeFileRecord } from './attachments.js';
 import { nowIso, stamp } from './ids.js';
 
 /** v2：密钥栏目从 8 字段模板改成单字段 KV（名称 → 值）。
@@ -32,6 +33,7 @@ function emptyStore(seed) {
     // 说明用户自己删光了栏目——这时候再播种会把它变回来，等于删不掉。
     sections: seed ? seedSections(at) : [],
     entries: [],
+    files: [],
     exports: [],
   };
 }
@@ -176,6 +178,7 @@ export function normalize(data) {
   delete base.settings.kvSection;
   base.sections = (Array.isArray(data.sections) ? data.sections : []).map(normalizeSection).filter(Boolean);
   base.entries = (Array.isArray(data.entries) ? data.entries : []).map(normalizeEntry).filter(Boolean);
+  base.files = (Array.isArray(data.files) ? data.files : []).map(normalizeFileRecord).filter(Boolean);
   base.exports = Array.isArray(data.exports) ? data.exports.slice(0, MAX_EXPORT_HISTORY) : [];
   if (oldVersion < 2) base._migration = migrateSecretToKv(base);
   if (oldVersion < 3) {

package/src/modules/backup/service.js

@@ -1,22 +1,28 @@
 // 加密备份 / 恢复：整份数据用「口令派生密钥 + AES-256-GCM」对称加密。
 //
-// 导出：用户设置口令 → 随机盐写进备份文件，密钥由 scrypt(口令, 盐) 派生（口令不落盘）。
-// 导入：用户输入口令 → 用文件里的盐派生同一把密钥解密；口令错误 GCM 校验失败、明确报错。
+// 导出：用户设置口令 → 先把 secret 栏目的密文字段用**本机 vaultKey 解开**（明文），
+//       再把整份 payload 用口令派生 key 加密落到备份文件；口令不落盘。
+// 导入：用户输入口令 → 解密后 payload 里的 secret 字段就是明文；直接写回 store.json。
 //
-// 复用 core/crypto.js 的原语（deriveKey / encryptValue / decryptValue），
-// 与字段级密钥库（core/vault.js）相互独立：备份口令是一次性的，不写进 vault。
+// 这样跨机器恢复：B 机拿到口令后 secret 字段就是明文，**不再依赖 A 机的 vaultKey**。
+// 这是 store.json 内的密文被解开的瞬态——落回磁盘后字段仍是 vaultKey 加密形态（每次
+// `key set` 会重新用 B 机 vaultKey 加密），所以单机的"落盘密文"防护没退化。
+//
+// 复用 core/crypto.js 的原语（deriveKey / encryptValue / decryptValue）。
 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 { decryptValue, deriveKey, encryptValue, isCipherBlob } from '../../core/crypto.js';
 import { badInput, blocked } from '../../core/errors.js';
 import { nowIso, stamp } from '../../core/ids.js';
+import { isSensitiveField } from '../../core/fields.js';
+import { resolveVaultKey } from '../../core/vault.js';
 
 export const BACKUP_KIND = 'encrypted-backup';
-export const BACKUP_VERSION = 1;
+export const BACKUP_VERSION = 2;
 export const ENV_BACKUP_PASSWORD = 'NX_SK_BACKUP_PASSWORD';
 const EXT = '.nxskbak';
 
@@ -32,11 +38,39 @@ function passwordFrom(ctx) {
   return s;
 }
 
+/**
+ * 把 payload 里 secret 栏目的密文字段解开成明文（不修改其他字段）。
+ * 用本机 vaultKey 解：A 机本地能解；导出文件不依赖 A 机后续状态。
+ */
+async function unsealSecretsForExport(payload) {
+  const sections = payload.sections || [];
+  const entries = payload.entries || [];
+  const { key: vaultKey } = await resolveVaultKey();
+
+  const newEntries = [];
+  let unsealed = 0;
+  for (const e of entries) {
+    const sec = sections.find((s) => s.id === e.section);
+    if (!sec || !e.values) { newEntries.push(e); continue; }
+    const nextValues = { ...e.values };
+    let touched = false;
+    for (const def of sec.fields || []) {
+      if (!isSensitiveField(sec, def.key)) continue;
+      const v = nextValues[def.key];
+      if (!isCipherBlob(v)) continue;
+      nextValues[def.key] = decryptValue(vaultKey, v);
+      touched = true; unsealed++;
+    }
+    newEntries.push(touched ? { ...e, values: nextValues } : e);
+  }
+  return { ...payload, entries: newEntries, _unsealed: unsealed };
+}
+
 /** 生成加密备份：返回归档对象（HTTP 端据此让浏览器下载）与条目计数。 */
 export async function buildBackup(ctx) {
   const password = passwordFrom(ctx);
   const store = await loadStore();
-  const payload = {
+  const raw = {
     version: store.version,
     settings: store.settings,
     sections: store.sections,
@@ -45,8 +79,9 @@ export async function buildBackup(ctx) {
   };
 
   const salt = randomBytes(16);
-  const key = deriveKey(password, salt);
-  const data = encryptValue(key, JSON.stringify(payload));
+  const wrapKey = deriveKey(password, salt);
+  const payload = await unsealSecretsForExport(raw);
+  const data = encryptValue(wrapKey, JSON.stringify(payload));
   const archive = {
     app: 'nx-sk',
     kind: BACKUP_KIND,
@@ -56,7 +91,11 @@ export async function buildBackup(ctx) {
     salt: salt.toString('base64'),
     data,
   };
-  const counts = { sections: store.sections.length, entries: store.entries.length };
+  const counts = {
+    sections: store.sections.length,
+    entries: store.entries.length,
+    unsealed: payload._unsealed || 0,
+  };
   if (ctx['dry-run']) return { dryRun: true, counts };
   return { archive, counts };
 }
@@ -117,7 +156,7 @@ export function decryptBackup(text, password) {
   return { payload, createdAt: archive.createdAt };
 }
 
-/** 恢复：解密 → 先给当前数据留安全快照 → 整份替换（写入会过 normalize 迁移到当前版本）。 */
+/** 恢复：解密 → 留安全快照 → 整份替换（secret 字段已是明文，落盘后下次写入时由 B 机 vaultKey 重新加密）。 */
 export async function restoreBackup({ content, password, 'dry-run': dryRun }) {
   const { payload, createdAt } = decryptBackup(String(content ?? ''), password);
 
@@ -127,6 +166,7 @@ export async function restoreBackup({ content, password, 'dry-run': dryRun }) {
       backupCreatedAt: createdAt || '',
       sections: payload.sections.length,
       entries: payload.entries.length,
+      unsealed: payload._unsealed || 0,
     };
   }
 
@@ -146,6 +186,7 @@ export async function restoreBackup({ content, password, 'dry-run': dryRun }) {
     backupCreatedAt: createdAt || '',
     sections: payload.sections.length,
     entries: payload.entries.length,
+    unsealed: payload._unsealed || 0,
     safetySnapshot: displayPath(safety),
   };
 }
@@ -166,23 +207,27 @@ export async function importBackup(ctx) {
 
 export function renderBackup(d) {
   if (d.status === 'skipped') {
-    return `试运行（未写盘、未下载）\n将加密备份: ${d.sections} 个栏目 / ${d.entries} 条条目（AES-256-GCM）`;
+    return `试运行（未写盘、未下载）\n将加密备份: ${d.sections} 个栏目 / ${d.entries} 条条目（AES-256-GCM）`
+      + (d.unsealed ? `\n含明文保存的密钥字段: ${d.unsealed} 个（其他机器用本次口令可解开）` : '');
   }
   return [
     `已生成加密备份（AES-256-GCM，口令派生密钥、口令不落盘）`,
     `文件: ${d.file}　${d.bytes} 字节`,
     `内容: ${d.sections} 个栏目 / ${d.entries} 条条目`,
+    `本次解开为明文的密钥字段: ${d.unsealed || 0} 个（其他机器用本次口令可解开）`,
     `恢复时需要输入本次设置的口令。`,
   ].join('\n');
 }
 
 export function renderRestore(d) {
   if (d.status === 'dry-run') {
-    return `试运行（未改动当前数据）\n备份可正常解密: ${d.sections} 个栏目 / ${d.entries} 条条目，生成于 ${d.backupCreatedAt || '未知'}`;
+    return `试运行（未改动当前数据）\n备份可正常解密: ${d.sections} 个栏目 / ${d.entries} 条条目`
+      + `，含明文密钥字段 ${d.unsealed || 0} 个，生成于 ${d.backupCreatedAt || '未知'}`;
   }
   return [
     `已从加密备份恢复：${d.sections} 个栏目 / ${d.entries} 条条目`,
+    `从备份中拿到的明文密钥字段: ${d.unsealed || 0} 个`,
     `备份生成于: ${d.backupCreatedAt || '未知'}`,
     `恢复前的当前数据已留安全快照: ${d.safetySnapshot}`,
   ].join('\n');
-}
+}