nx-sk 0.3.4 → 0.6.0

package/src/modules/backup/service.js

@@ -0,0 +1,283 @@
+// 加密备份 / 恢复：整份数据用「口令派生密钥 + AES-256-GCM」对称加密。
+//
+// 导出：用户设置口令 → 随机盐写进备份文件，密钥由 scrypt(口令, 盐) 派生（口令不落盘）。
+// 导入：用户输入口令 → 用文件里的盐派生同一把密钥解密；口令错误 GCM 校验失败、明确报错。
+//
+// 复用 core/crypto.js 的原语（deriveKey / encryptValue / decryptValue），
+// 与字段级密钥库（core/vault.js）相互独立：备份口令是一次性的，不写进 vault。
+//
+// 跨机器恢复：store.json 里凭据原本是「本机 vault key（AES-256-GCM + kid）」加密的，
+// 备份打包会把这份密文**再裹一层**——用备份口令派生 key 重加密一份副本，写进
+// `reWrapped`。导入时先解开 reWrapped 拿明文，再用**目标机器**的 vault key 重新加密，
+// 写回主字段、丢掉 reWrapped。这样：
+//   - 备份包在 A 机器上能独立解开（不依赖 A 的 ~/.vaultkey / NX_SK_PASSPHRASE）
+//   - 导入 B 机器后，凭据绑的是 B 的本地密钥，跟其他密文一样走 decryptValue
+//   - 没有「reWrapped 的密文只能输口令解」的尾巴——一次导入就兑回本机
+// 没有 reWrapped 的密文（早期版本/未带口令的导出）依然走 kid 校验；换机会得到明确 BLOCKED。
+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 { 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 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;
+}
+
+/**
+ * 给 payload 里的每条密文字段加一层「口令派生的重加密」。
+ *
+ * 输入是 buildBackup 准备好的 store payload；输出是**新对象**，原对象不变。
+ * 已带 reWrapped 的不再二次包——避免循环。
+ */
+async function reWrapSecretsInPlace(payload, password, salt) {
+  const sections = payload.sections || [];
+  const entries = payload.entries || [];
+  const transportKey = deriveKey(password, salt);
+  const { key: vaultKey } = await resolveVaultKey();
+
+  const newEntries = [];
+  let reWrapped = 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) || v.reWrapped) continue;
+      // 用本机 vault key 解开 → 用口令派生 key 重加密 → 挂到 reWrapped 上。
+      // 原来的密文保留——A 机用原 vaultKey 仍能解（不动既有逻辑）。
+      const plain = decryptValue(vaultKey, v);
+      nextValues[def.key] = { ...v, reWrapped: encryptValue(transportKey, plain) };
+      touched = true; reWrapped++;
+    }
+    newEntries.push(touched ? { ...e, values: nextValues } : e);
+  }
+  return { ...payload, entries: newEntries, _reWrapped: reWrapped };
+}
+
+/**
+ * 反向：把 reWrapped 副本兑回本机 vault key。
+ * 拿不到口令（密码错）会抛 BLOCKED；拿到口令则静默完成，用户不感知。
+ */
+async function unwrapSecretsToLocal(payload, password, salt) {
+  const sections = payload.sections || [];
+  const entries = payload.entries || [];
+  const transportKey = deriveKey(password, salt);
+  const { key: vaultKey } = await resolveVaultKey();
+
+  const newEntries = [];
+  let unwrapped = 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) || !v.reWrapped) continue;
+      const plain = decryptValue(transportKey, v.reWrapped);
+      // tenant 用来保留 A 机原 blob 的非密文字段（如 v/alg）但**不能**包含 iv/ct/tag/kid——
+      // 这些必须来自新的 encryptValue（用本机 vaultKey 生成的）。否则 spread 后会把
+      // 新的 iv/ct/tag 覆盖回 A 机的旧值，写进 store.json 的密文就解不开了。
+      const { reWrapped: _rw, iv: _oldIv, ct: _oldCt, tag: _oldTag, kid: _oldKid, ...tenant } = v;
+      void _rw; void _oldIv; void _oldCt; void _oldTag; void _oldKid;
+      nextValues[def.key] = { ...encryptValue(vaultKey, plain), ...tenant };
+      touched = true; unwrapped++;
+    }
+    newEntries.push(touched ? { ...e, values: nextValues } : e);
+  }
+  return { ...payload, entries: newEntries, _reWrapped: unwrapped };
+}
+
+/** 生成加密备份：返回归档对象（HTTP 端据此让浏览器下载）与条目计数。 */
+export async function buildBackup(ctx) {
+  const password = passwordFrom(ctx);
+  const store = await loadStore();
+  const raw = {
+    version: store.version,
+    settings: store.settings,
+    sections: store.sections,
+    entries: store.entries,
+    exports: store.exports,
+  };
+
+  const salt = randomBytes(16);
+  const wrapKey = deriveKey(password, salt);
+  const payload = await reWrapSecretsInPlace(raw, password, salt);
+  const data = encryptValue(wrapKey, 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,
+    reWrapped: payload._reWrapped || 0,
+  };
+  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 负载 + archive（带 salt）。口令错误在此抛 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, salt: archive.salt };
+}
+
+/** 恢复：解密 → 把 reWrapped 兑回本机 vault key → 留安全快照 → 整份替换。 */
+export async function restoreBackup({ content, password, 'dry-run': dryRun }) {
+  const { payload, createdAt, salt } = decryptBackup(String(content ?? ''), password);
+
+  if (dryRun) {
+    return {
+      status: 'dry-run', dryRun: true,
+      backupCreatedAt: createdAt || '',
+      sections: payload.sections.length,
+      entries: payload.entries.length,
+      reWrapped: payload._reWrapped || 0,
+    };
+  }
+
+  // 把 reWrapped 兑回本机 vault key：解口令派生密文 → 用本机 vaultKey 重加密。
+  // 失败（口令对但 reWrapped 损坏）会被 unwrapSecretsToLocal 抛 BLOCKED。
+  const unwrapped = await unwrapSecretsToLocal(payload, password, salt);
+
+  // 覆盖前留一份可回滚快照（落到 backup/ 目录），避免误操作丢数据
+  const safety = await snapshotStore('before-restore');
+
+  await saveStore({
+    version: unwrapped.version,
+    settings: unwrapped.settings,
+    sections: unwrapped.sections,
+    entries: unwrapped.entries,
+    exports: Array.isArray(unwrapped.exports) ? unwrapped.exports : [],
+  });
+
+  return {
+    status: 'restored',
+    backupCreatedAt: createdAt || '',
+    sections: unwrapped.sections.length,
+    entries: unwrapped.entries.length,
+    reWrapped: unwrapped._reWrapped || 0,
+    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）`
+      + (d.reWrapped ? `\n携带口令派生重加密的密文字段: ${d.reWrapped} 个（其他机器用本次口令可解开）` : '');
+  }
+  return [
+    `已生成加密备份（AES-256-GCM，口令派生密钥、口令不落盘）`,
+    `文件: ${d.file}　${d.bytes} 字节`,
+    `内容: ${d.sections} 个栏目 / ${d.entries} 条条目`,
+    `携带口令派生重加密的密文字段: ${d.reWrapped || 0} 个（其他机器用本次口令可解开）`,
+    `恢复时需要输入本次设置的口令。`,
+  ].join('\n');
+}
+
+export function renderRestore(d) {
+  if (d.status === 'dry-run') {
+    return `试运行（未改动当前数据）\n备份可正常解密: ${d.sections} 个栏目 / ${d.entries} 条条目`
+      + `，含口令派生重加密的密文字段 ${d.reWrapped || 0} 个，生成于 ${d.backupCreatedAt || '未知'}`;
+  }
+  return [
+    `已从加密备份恢复：${d.sections} 个栏目 / ${d.entries} 条条目`,
+    `兑回本机密钥库的密文字段: ${d.reWrapped || 0} 个`,
+    `备份生成于: ${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/service.js

@@ -13,6 +13,8 @@ import { completeness, displaySensitive, serializeEntry } from '../../core/rende
 import { newId, nowIso } from '../../core/ids.js';
 import { decryptValue, encryptValue, isCipherBlob, maskValue } from '../../core/crypto.js';
 import { resolveVaultKey, sensitiveViewer } from '../../core/vault.js';
+import * as att from '../../core/attachments.js';
+import { displayPath } from '../../core/paths.js';
 
 export function mustFindSection(store, ref) {
   const s = findSection(store, ref);
@@ -100,6 +102,13 @@ function normalizeValue(def, raw) {
     }
     return list;
   }
+  if (type === 'file') {
+    // 值 = 附件 id（或唯一文件名）。id 全局唯一，天然做到「各条目附件互不串台」；
+    // 同一份原件被多条条目引用也没问题（sha256 去重后是同一个 id）。
+    // 不校验存在性——附件可能被还原/删掉，前端按「引用的附件不存在」展示。
+    const s = String(raw).trim();
+    return s === '' ? null : s;
+  }
   const s = String(raw);
   return s.trim() === '' ? null : s;
 }
@@ -174,7 +183,12 @@ export async function listEntries({ section, q } = {}) {
     if (!viewers.has(sec.id)) viewers.set(sec.id, await sensitiveViewer(sec, list.filter((x) => x.section === sec.id)));
     const item = serializeEntry(sec, e, { decrypt: viewers.get(sec.id) });
     if (q) {
-      const hay = [item.title, sec.title, ...Object.values(item.values).map((v) => (v === null ? '' : Array.isArray(v) ? v.join(',') : String(v)))]
+      // file 字段值是附件 id，把解析出的附件名也加进搜索文本，才能按「简历/成绩单」搜到条目
+      const fileNames = sec.fields
+        .filter((f) => f.type === 'file')
+        .map((f) => att.findFileRecord(store, e.values?.[f.key])?.name || '');
+      const hay = [item.title, sec.title, ...fileNames,
+        ...Object.values(item.values).map((v) => (v === null ? '' : Array.isArray(v) ? v.join(',') : String(v)))]
         .join('\n').toLowerCase();
       if (!hay.includes(String(q).toLowerCase())) continue;
     }
@@ -189,7 +203,21 @@ export async function getEntry(ref, { mask, section } = {}) {
   const sec = store.sections.find((s) => s.id === entry.section);
   if (!sec) throw notFound(`条目 ${entry.id} 指向的栏目已不存在: ${entry.section}`);
   const decrypt = await sensitiveViewer(sec, [entry]);
-  return { ...serializeEntry(sec, entry, { mask: !!mask, decrypt }), sectionTitle: sec.title, mask: !!mask };
+  const serialized = serializeEntry(sec, entry, { mask: !!mask, decrypt });
+  // 附带 file 字段引用的附件信息：键 = 字段值（即附件 id / 文件名），值为名称 / 路径 / 链接
+  const files = {};
+  for (const f of sec.fields.filter((x) => x.type === 'file')) {
+    const ref = serialized.values[f.key];
+    if (!ref) continue;
+    const rec = att.findFileRecord(store, ref);
+    if (!rec) continue;
+    const links = att.fileLinks(rec);
+    files[ref] = {
+      id: rec.id, name: rec.name, ext: rec.ext, isImage: att.isImageExt(rec.ext),
+      path: displayPath(att.fileRecordAbs(rec)), url: links.url, downloadUrl: links.downloadUrl,
+    };
+  }
+  return { ...serialized, sectionTitle: sec.title, mask: !!mask, files };
 }
 
 export async function addEntry({ section, title, set, data, tags, 'dry-run': dryRun } = {}) {
@@ -312,6 +340,7 @@ export async function fieldDictionary({ section } = {}) {
     groups: sec.groups,
     fields: sec.fields.map((x) => ({
       key: x.key, label: x.label, type: x.type, group: x.group,
+      kind: x.kind || '',
       hint: x.hint || '', options: x.options || null, sensitive: isSensitiveField(sec, x.key),
     })),
   });
@@ -498,6 +527,10 @@ export function renderEntryGet(d) {
   ];
   for (const [k, v] of Object.entries(d.values)) {
     if (v === null) continue;
+    if (d.files && d.files[v]) {
+      lines.push(`  ${k.padEnd(24)} ${d.files[v].name}　${d.files[v].path}`);
+      continue;
+    }
     lines.push(`  ${k.padEnd(24)} ${Array.isArray(v) ? v.join('、') : (typeof v === 'boolean' ? (v ? '是' : '否') : String(v))}`);
   }
   if (d.missing.length) {

package/src/modules/files/index.js

@@ -0,0 +1,114 @@
+import * as service from './service.js';
+
+export default {
+  id: 'files',
+  title: '附件',
+  order: 650,
+  view: () => import('./view.jsx'),
+  // 一组同级实体，每个附件有标识，用户会想替换/还原/删除其中一个 → 集合资源
+  resource: 'file',
+  actions: [
+    {
+      id: 'file.list',
+      cli: ['file', 'list'],
+      http: ['GET', '/api/files'],
+      summary: '列附件（可按栏目/关键字过滤）；返回「哪些栏目在引用附件」与存储目录。组织方式由栏目驱动，无预定义分类',
+      flags: {
+        section: { type: 'string', hint: '只看某栏目引用的附件（none = 只列没有任何条目引用的）' },
+        category: { type: 'string', enum: ['resume', 'avatar', 'transcript', 'certificate', 'document', 'other'], hint: '按磁盘分类过滤（内部属性，一般不用）' },
+        q: { type: 'string', hint: '关键字（名称 / 备注 / 标签 / 引用它的栏目条目）' },
+      },
+      run: (ctx) => service.listFiles(ctx),
+      render: (d) => service.renderFileList(d),
+    },
+    {
+      id: 'file.get',
+      cli: ['file', 'get'],
+      http: ['GET', '/api/files/:ref'],
+      summary: '读单个附件的台账：物理路径、链接、被哪些栏目/条目/字段引用、原始位置、标签、备注',
+      args: ['ref'],
+      run: (ctx) => service.getFile(ctx.ref),
+      render: (d) => service.renderFileGet(d),
+    },
+    {
+      id: 'file.add',
+      cli: ['file', 'add'],
+      http: ['POST', '/api/files'],
+      summary: '导入附件：--path 本机路径默认移动（--copy 仅复制）；Web 上传走 content(base64)+name。同内容自动去重',
+      flags: {
+        path: { type: 'string', hint: '本机文件路径（默认把原件移动进库）' },
+        content: { type: 'string', hint: 'base64 内容（Web 上传自动带，可为 data URL）' },
+        name: { type: 'string', hint: '文件名（content 上传时必填）' },
+        category: { type: 'string', enum: ['resume', 'avatar', 'transcript', 'certificate', 'document', 'other'] },
+        copy: { type: 'boolean', hint: '只复制、保留原件（默认移动）' },
+        tags: { type: 'array' },
+        note: { type: 'string' },
+        'dry-run': { type: 'boolean', hint: '只校验与计算落点，不移动、不写入' },
+      },
+      run: (ctx) => service.addFile(ctx),
+      render: (d) => service.renderFileChange(d),
+    },
+    {
+      id: 'file.update',
+      cli: ['file', 'update'],
+      http: ['PATCH', '/api/files/:ref'],
+      summary: '改附件：名称、分类（物理文件随之移动）、标签、备注',
+      args: ['ref'],
+      flags: {
+        name: { type: 'string' },
+        category: { type: 'string', enum: ['resume', 'avatar', 'transcript', 'certificate', 'document', 'other'] },
+        tags: { type: 'array' },
+        note: { type: 'string' },
+        'dry-run': { type: 'boolean' },
+      },
+      run: (ctx) => service.updateFile(ctx.ref, ctx),
+      render: (d) => service.renderFileChange(d),
+    },
+    {
+      id: 'file.remove',
+      cli: ['file', 'remove'],
+      http: ['DELETE', '/api/files/:ref'],
+      summary: '删附件（连物理原件一起删）；写前自动留台账快照。要保留原件请用 file restore',
+      args: ['ref'],
+      flags: { 'dry-run': { type: 'boolean' } },
+      run: (ctx) => service.removeFile(ctx.ref, ctx),
+      render: (d) => service.renderFileChange(d),
+    },
+    {
+      id: 'file.content',
+      cli: ['file', 'content'],
+      http: ['GET', '/api/files/:ref/content'],
+      // raw：HTTP 不走 JSON 包装，直接流式输出文件本体（浏览器内预览/下载）
+      raw: true,
+      summary: '取附件本体：浏览器内直接预览（?download=1 强制下载）；CLI 打印物理路径与链接',
+      args: ['ref'],
+      flags: { download: { type: 'boolean', hint: '强制下载而非内联预览' } },
+      run: (ctx) => service.contentInfo(ctx.ref, ctx),
+      serveRaw: (ctx, frame) => service.serveRaw(ctx, frame),
+      render: (d) => service.renderContent(d),
+    },
+    {
+      id: 'file.restore',
+      cli: ['file', 'restore'],
+      http: ['POST', '/api/files/:ref/restore'],
+      summary: '可逆操作：把附件移回原始位置并撤销台账（--copy 只导出副本、库中保留；--to 指定目录）',
+      args: ['ref'],
+      flags: {
+        to: { type: 'string', hint: '目标目录（Web 上传件无原始位置时必填）' },
+        copy: { type: 'boolean', hint: '只导出副本，库中保留原件与台账' },
+        'dry-run': { type: 'boolean' },
+      },
+      run: (ctx) => service.restoreFileAction(ctx.ref, ctx),
+      render: (d) => service.renderFileChange(d),
+    },
+    {
+      id: 'file.open',
+      cli: ['file', 'open'],
+      http: null, // 本机动作，不通过 HTTP 暴露
+      summary: '用系统默认程序打开附件原件',
+      args: ['ref'],
+      run: (ctx) => service.openFileAction(ctx.ref),
+      render: (d) => service.renderOpen(d),
+    },
+  ],
+};