nx-sk 0.3.0

package/src/core/paths.js

@@ -0,0 +1,141 @@
+// 路径与安全校验的**唯一定义处**。别在别处再拼一次 home 路径。
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { badInput } from './errors.js';
+
+export const PROJECT_ROOT = resolve(fileURLToPath(new URL('../../', import.meta.url)));
+export const ASSETS_DIR = join(PROJECT_ROOT, 'assets');
+export const PUBLIC_DIR = join(PROJECT_ROOT, 'src', 'web', 'public');
+
+const pkg = JSON.parse(readFileSync(join(PROJECT_ROOT, 'package.json'), 'utf8'));
+export const APP_NAME = pkg.name; // 'nx-sk'
+export const APP_LABEL = 'nx-sk · 个人资源管理器';
+export const VERSION = pkg.version;
+export const SKILL_NAME = APP_NAME;
+
+// 端口只有一个来源：package.json 的 nxSk.port。服务端与 vite 代理都从这里取——
+// 散成字面量的话改一次就会漏一处，而漏掉 vite 代理的表现是「dev 模式下 /api 全 404」，
+// 很难和「端口」联系起来。
+export const DEFAULT_PORT = Number(pkg.nxSk?.port ?? 7866);
+export const DEV_VITE_PORT = Number(pkg.nxSk?.vitePort ?? 5180);
+
+/**
+ * 数据根目录：`~/nx-sk/`
+ *
+ * 骨架 ref [[05-state-storage]] 的默认是 `~/.<主题名>/`（隐藏目录）。
+ * 本项目按用户明确要求改成 `~/nx-sk/`——一眼能找到、能手动改、能整体拷走，
+ * 这对「本地绝对安全 + 支持整体导出」的诉求更重要。
+ *
+ * 环境变量覆盖**不是可选项**：没有它，测试会写脏用户的真实数据。
+ */
+export const ENV_HOME = 'NX_SK_HOME';
+export const ENV_STORE = 'NX_SK_STORE';
+export const ENV_PASSPHRASE = 'NX_SK_PASSPHRASE';
+
+const DEFAULT_HOME = join(homedir(), APP_NAME);
+
+export function appHome() {
+  const fromEnv = process.env[ENV_HOME];
+  return fromEnv ? resolve(fromEnv) : DEFAULT_HOME;
+}
+
+export function storeFile() {
+  const fromEnv = process.env[ENV_STORE];
+  return fromEnv ? resolve(fromEnv) : join(appHome(), 'store.json');
+}
+
+export function exportDir() {
+  return join(appHome(), 'export');
+}
+
+export function snapshotDir() {
+  return join(appHome(), 'backup');
+}
+
+export function vaultKeyFile() {
+  return join(appHome(), '.vaultkey');
+}
+
+export function vaultSaltFile() {
+  return join(appHome(), '.vaultsalt');
+}
+
+/** 把用户给的相对路径挂到 base 下，并保证结果仍在 base 内（拒绝 `..` 越界）。 */
+export function resolveInside(base, rel) {
+  const baseAbs = resolve(base);
+  const target = resolve(baseAbs, rel);
+  if (target !== baseAbs && !target.startsWith(baseAbs + sep)) {
+    throw badInput(`路径越界: ${rel}`);
+  }
+  return target;
+}
+
+export function isInside(parent, child) {
+  const p = resolve(parent);
+  const c = resolve(child);
+  return c === p || c.startsWith(p + sep);
+}
+
+/** 统一的展示用路径：正斜杠、home 前缀缩写成 `~/`。不参与任何文件操作。 */
+export function displayPath(p) {
+  if (!p) return '';
+  const posix = String(p).split(sep).join('/');
+  const home = homedir().split(sep).join('/');
+  return posix.startsWith(home + '/') ? '~' + posix.slice(home.length) : posix;
+}
+
+// —— 名称/ID 校验 ——
+// 名称与路径**分开校验**：用「目录名」的规则去卡文件路径会误伤 `.gitignore` 这类正常文件。
+
+/** section id：小写字母开头，只允许 [a-z0-9_-]，最长 64。 */
+export function assertSafeId(id, what = 'id') {
+  const s = String(id ?? '').trim();
+  if (!/^[a-z][a-z0-9_-]{0,63}$/.test(s)) {
+    throw badInput(`${what} 非法: ${JSON.stringify(id)}（小写字母开头，仅含 a-z 0-9 _ -，最长 64）`);
+  }
+  return s;
+}
+
+/** skill 名等：单段名称，不含路径分隔符、不是绝对路径、不含 `..`。 */
+export function assertSafeName(name, what = '名称') {
+  const s = String(name ?? '').trim();
+  if (!s) throw badInput(`${what}不能为空`);
+  if (isAbsolute(s) || s.includes('/') || s.includes('\\') || s.includes('..')) {
+    throw badInput(`${what} 非法: ${JSON.stringify(name)}（不允许路径分隔符或 '..'）`);
+  }
+  if (!/^[\w.@-]{1,64}$/.test(s)) {
+    throw badInput(`${what} 非法: ${JSON.stringify(name)}（仅允许字母数字与 . _ @ -，最长 64）`);
+  }
+  return s;
+}
+
+/**
+ * 字段 key。**允许中文**——字典是「已用字段的台账」，用户敲什么键就该存什么键
+ * （`--set 微信号=xxx` 之后 `values` 里就是 `微信号`，不用记一个英文别名）。
+ * 仍然挡掉空白、路径分隔符与 `..`：那些会让 CLI 与 URL 变难用。
+ */
+export function assertFieldKey(key) {
+  const s = String(key ?? '').trim();
+  if (!s) throw badInput('字段 key 不能为空');
+  if (s.length > 48) throw badInput(`字段 key 过长（${s.length} > 48）: ${s}`);
+  if (/[\s/\\]/.test(s) || s.includes('..')) {
+    throw badInput(`字段 key 非法: ${JSON.stringify(key)}（不允许空白、路径分隔符或 '..'；中文可以）`);
+  }
+  return s;
+}
+
+/** 归一化跨平台相对路径，用于目录树比对。 */
+export function toPosix(p) {
+  return String(p).split(sep).join('/');
+}
+
+/** 相对 base 的 posix 路径，越界返回 null。 */
+export function relPosix(base, target) {
+  const r = relative(resolve(base), resolve(target));
+  if (!r || r.startsWith('..') || isAbsolute(r)) return null;
+  return toPosix(r);
+}
+
+export { normalize as normalizePath };

package/src/core/render.js

@@ -0,0 +1,144 @@
+// 纯渲染逻辑（不碰磁盘、不碰平台）——值格式化、条目序列化、栏目全量视图。
+// 放 core 是为了能单测：这些函数决定了「读出去的形状」，是最该被钉住的契约。
+//
+// 这里**不解密**：解密需要密钥（异步、且属于安全边界），所以由调用方把一个
+// `decrypt(blob) => 明文` 传进来（core/vault.js 的 `sensitiveViewer` 负责造它）。
+// 这样 render 保持纯函数，而「什么时候允许看明文」仍然只有一个决策点。
+import { isCipherBlob, maskValue } from './crypto.js';
+import { FILL_LABELS, fillPolicy, isExcludedField, isSensitiveField } from './fields.js';
+
+export function isBlank(v) {
+  if (v === null || v === undefined) return true;
+  if (Array.isArray(v)) return v.length === 0;
+  return String(v).trim() === '';
+}
+
+/** 值 → 人读字符串（bool / tags / 数组 / 标量）。 */
+export function formatValue(value) {
+  if (isBlank(value)) return '';
+  if (Array.isArray(value)) return value.map(String).join('、');
+  if (typeof value === 'boolean') return value ? '是' : '否';
+  return String(value);
+}
+
+/**
+ * 敏感字段的展示形态。
+ *
+ * **默认原文**：这是本机单人工具，数据是给自己看的——默认打码等于每次都先拦自己一道。
+ * 落盘仍然是密文（AES-256-GCM），所以「store.json 泄露」不等于「凭据泄露」。
+ * 想看打码形态（投屏 / 截图时）显式传 `mask: true`。
+ *
+ * 三种输入都要处理：
+ *   密文对象 → 有 decrypt 就解开，没有就标「需要密钥」
+ *   明文     → 历史数据可能存的是明文，原样返回
+ *   空       → null
+ */
+export function displaySensitive(raw, { mask = false, decrypt } = {}) {
+  if (raw === null || raw === undefined || raw === '') return null;
+  if (!isCipherBlob(raw)) return mask ? maskValue(String(raw)) : String(raw);
+  if (!decrypt) return mask ? '[已加密]' : '[需要密钥才能解密]';
+  try {
+    const plain = decrypt(raw);
+    return mask ? maskValue(plain) : plain;
+  } catch {
+    return '[无法解密：密钥或密文与写入时不一致]';
+  }
+}
+
+/**
+ * 条目的**唯一序列化出口**（面板、`entry list`、`section dump` 共用一份）。
+ * 两个出口各写一遍序列化，迟早会分叉成「CLI 看得到、面板看不到」。
+ */
+export function serializeEntry(section, entry, { mask = false, decrypt } = {}) {
+  const c = completeness(section, entry);
+  const values = {};
+  for (const def of section.fields) {
+    const raw = entry.values?.[def.key];
+    if (isBlank(raw)) { values[def.key] = null; continue; }
+    values[def.key] = isSensitiveField(section, def.key)
+      ? displaySensitive(raw, { mask, decrypt })
+      : raw;
+  }
+  return {
+    id: entry.id,
+    section: entry.section,
+    title: entry.title,
+    tags: entry.tags || [],
+    createdAt: entry.createdAt,
+    updatedAt: entry.updatedAt,
+    completeness: {
+      filled: c.filled,
+      total: c.total,
+      ratio: c.ratio,
+      excluded: c.excluded.length,
+      excludedFilled: c.excludedFilled,
+    },
+    missing: c.missing.map((x) => ({ key: x.key, label: x.label })),
+    // 与 missing 并列：这些是**主动不填**的字段，不是「还没填」。
+    // 两者混在一起会让「补全清单」和「不填清单」分不开。
+    excluded: c.excluded,
+    values,
+  };
+}
+
+/**
+ * 完整度：**只统计照常填的字段**。给「AI 帮我补全信息」当导航用。
+ *
+ * `optional` / `avoid` 两类字段既不计入 `total` 也不计入 `filled`——
+ * 否则「还缺 N 项」会永远挂着一批用户主动决定不填的字段，导航就失效了。
+ * 它们不会凭空消失：`excluded` 单独列出来，`excludedFilled` 记录其中已填了几个
+ * （用户可能没改策略却还是填了值，这个数能提示策略该更新了）。
+ */
+export function completeness(section, entry) {
+  const fields = section?.fields || [];
+  const counted = fields.filter((d) => !isExcludedField(d));
+  const excluded = fields.filter((d) => isExcludedField(d));
+  const missing = [];
+  let filled = 0;
+  for (const def of counted) {
+    if (isBlank(entry?.values?.[def.key])) missing.push(def);
+    else filled++;
+  }
+  const total = counted.length;
+  return {
+    filled,
+    total,
+    ratio: total ? Math.round((filled / total) * 100) : 0,
+    missing,
+    excluded: excluded.map((d) => ({ key: d.key, label: d.label, fill: fillPolicy(d), fillLabel: FILL_LABELS[fillPolicy(d)] })),
+    excludedFilled: excluded.filter((d) => !isBlank(entry?.values?.[d.key])).length,
+  };
+}
+
+/** 栏目的纯数据视图：所有条目 + 全部字段（含未填），供 `section dump` 与面板用。 */
+export function dumpSection(section, entries, { mask = false, decrypt } = {}) {
+  const mine = entries.filter((e) => e.section === section.id);
+  return {
+    section: {
+      id: section.id,
+      title: section.title,
+      description: section.description,
+      order: section.order,
+      template: section.template,
+      kv: section.kv === true,
+      titleField: section.titleField,
+      titleLabel: section.titleLabel,
+      fields: section.fields.length,
+    },
+    groups: section.groups,
+    fields: section.fields.map((x) => ({
+      key: x.key,
+      label: x.label,
+      type: x.type,
+      group: x.group,
+      hint: x.hint || '',
+      options: x.options || null,
+      sensitive: isSensitiveField(section, x.key),
+      // 填写策略要跟着字段字典出去，否则面板与 agent 不知道哪个格子「不用填」
+      fill: fillPolicy(x),
+      fillLabel: FILL_LABELS[fillPolicy(x)],
+    })),
+    count: mine.length,
+    entries: mine.map((e) => serializeEntry(section, e, { mask, decrypt })),
+  };
+}

package/src/core/store.js

@@ -0,0 +1,317 @@
+// 状态读写：原子写 + 按 mtime 失效的缓存 + 读-改-写事务 + 版本迁移。
+// 所有模块都通过这里碰磁盘，不自己拼路径、不自己 JSON.parse。
+import fsp from 'node:fs/promises';
+import { join } from 'node:path';
+import { displayPath, snapshotDir, storeFile } from './paths.js';
+import { ensureDir, pathExists, writeAtomic, writeJsonAtomic } from './fsx.js';
+import { instantiateTemplate, seedSections } from './fields.js';
+import { nowIso, stamp } from './ids.js';
+
+/** v2：密钥栏目从 8 字段模板改成单字段 KV（名称 → 值）。
+ *  v3：栏目有了 `kv` 标记——KV 栏目是一张表（面板渲染成表格，key 命令默认作用在它上面），
+ *      并去掉 `settings.kvSection` 这个冗余概念。 */
+export const STORE_VERSION = 3;
+export const MAX_SNAPSHOTS = 20;
+export const MAX_EXPORT_HISTORY = 30;
+
+export function defaultSettings() {
+  return {
+    exportDir: '', // 空 = ~/nx-sk/export
+    exportFormat: 'both', // json | md | both
+    includeSecretsInExport: true, // 默认含明文：本机单人工具，自己看不拦自己
+    defaultSection: 'job',
+  };
+}
+
+function emptyStore(seed) {
+  const at = nowIso();
+  return {
+    version: STORE_VERSION,
+    settings: defaultSettings(),
+    // 只有「store 文件压根不存在」才播种。文件在、但 sections 为空
+    // 说明用户自己删光了栏目——这时候再播种会把它变回来，等于删不掉。
+    sections: seed ? seedSections(at) : [],
+    entries: [],
+    exports: [],
+  };
+}
+
+function normalizeSection(raw) {
+  if (!raw || typeof raw !== 'object' || !raw.id) return null;
+  return {
+    id: String(raw.id),
+    title: String(raw.title || raw.id),
+    description: String(raw.description || ''),
+    order: Number.isFinite(raw.order) ? raw.order : 50,
+    template: raw.template ? String(raw.template) : null,
+    kv: raw.kv === true,
+    titleField: raw.titleField ? String(raw.titleField) : null,
+    titleLabel: String(raw.titleLabel || '名称'),
+    groups: Array.isArray(raw.groups) ? raw.groups.map((g) => ({ id: String(g.id), title: String(g.title || g.id) })) : [],
+    fields: Array.isArray(raw.fields) ? raw.fields.map((x) => ({ ...x, key: String(x.key), label: String(x.label || x.key) })) : [],
+    createdAt: raw.createdAt || null,
+    updatedAt: raw.updatedAt || null,
+  };
+}
+
+function normalizeEntry(raw) {
+  if (!raw || typeof raw !== 'object' || !raw.id) return null;
+  return {
+    id: String(raw.id),
+    section: String(raw.section || ''),
+    title: String(raw.title || ''),
+    tags: Array.isArray(raw.tags) ? raw.tags.map(String) : [],
+    values: raw.values && typeof raw.values === 'object' ? { ...raw.values } : {},
+    createdAt: raw.createdAt || null,
+    updatedAt: raw.updatedAt || null,
+  };
+}
+
+// v1 的密钥模板字段。迁移时**不动 values 里这些键**——只把 keyValue 搬到 value，
+// 并把字典缩成单字段。「不再显示」和「删掉」是两件事：删掉就再也找不回来了。
+const LEGACY_SECRET_KEYS = ['keyValue', 'provider', 'baseUrl', 'model', 'purpose', 'expiresAt', 'quota', 'note'];
+
+/**
+ * v1 → v2：把「密钥」栏目从 8 字段模板迁成单字段 KV。
+ *
+ * 幂等：只有 `version < 2` 才调用，且落盘后 version 变 2，不会再触发。
+ */
+function migrateSecretToKv(store) {
+  const sec = store.sections.find((s) => s.id === 'secret');
+  if (!sec) return null;
+  const looksLegacy = sec.fields.some((x) => LEGACY_SECRET_KEYS.includes(x.key))
+    && !sec.fields.some((x) => x.key === 'value');
+  if (!looksLegacy) return null;
+
+  const tpl = instantiateTemplate('secret', { id: sec.id, title: sec.title, order: sec.order });
+  const moved = [];
+  for (const e of store.entries.filter((x) => x.section === sec.id)) {
+    const v = e.values || (e.values = {});
+    const empty = v.value === undefined || v.value === null || v.value === '';
+    if (empty && v.keyValue !== undefined && v.keyValue !== null && v.keyValue !== '') {
+      v.value = v.keyValue;
+      moved.push(e.id);
+    }
+  }
+  sec.groups = tpl.groups;
+  sec.fields = tpl.fields;
+  sec.titleField = tpl.titleField;
+  sec.titleLabel = tpl.titleLabel;
+  sec.template = 'secret';
+  sec.description = tpl.description;
+  sec.updatedAt = nowIso();
+
+  const stillHolding = store.entries
+    .filter((e) => e.section === sec.id)
+    .reduce((n, e) => n + LEGACY_SECRET_KEYS.filter((k) => k !== 'keyValue'
+      && e.values?.[k] !== undefined && e.values?.[k] !== null && e.values?.[k] !== '').length, 0);
+
+  return {
+    section: sec.id,
+    fieldsBefore: LEGACY_SECRET_KEYS.length + 1,
+    fieldsAfter: tpl.fields.length,
+    entries: store.entries.filter((e) => e.section === sec.id).length,
+    movedValues: moved.length,
+    legacyValuesKept: stillHolding,
+  };
+}
+
+/**
+ * v2 → v3：把「密钥」栏目标成 KV 表，并把误当字段用的键值搬进值列。
+ *
+ * 背景：面板早先那行「KV 直填」在 KV 栏目里也把 `089=xxx` 当成**新字段**登记了
+ * （字段名 = `089`），而用户的本意是「加一个新键」。这里把「唯一一个非空且不是 value
+ * 的字段值」搬进 value —— 该条目就变成「标题 = 键名，value = 值」的正常样子。
+ * 其余留在 values 里的键**一律不删**（不再显示 ≠ 删掉）。
+ */
+function migrateKvToTable(store, oldSettings) {
+  const marked = store.sections.filter((s) => s.kv);
+  const target = marked[0]
+    || store.sections.find((s) => s.id === String(oldSettings?.kvSection || 'secret'));
+  if (!target) return null;
+
+  const tpl = instantiateTemplate('secret', { id: target.id, title: target.title, order: target.order });
+  const fieldsBefore = target.fields.length;
+  const moved = [];
+
+  for (const e of store.entries.filter((x) => x.section === target.id)) {
+    const v = e.values || (e.values = {});
+    const valueEmpty = v.value === undefined || v.value === null || v.value === '';
+    if (!valueEmpty) continue;
+    const others = Object.keys(v).filter((k) => k !== 'value' && v[k] !== undefined && v[k] !== null && v[k] !== '');
+    if (others.length === 1) { v.value = v[others[0]]; moved.push(`${e.title}:${others[0]}`); }
+  }
+
+  target.kv = true;
+  target.fields = tpl.fields;
+  target.groups = tpl.groups;
+  target.titleField = tpl.titleField;
+  target.titleLabel = tpl.titleLabel;
+  target.template = 'secret';
+  target.description = tpl.description;
+  target.updatedAt = nowIso();
+
+  return {
+    section: target.id,
+    fieldsBefore,
+    fieldsAfter: tpl.fields.length,
+    movedValues: moved.length,
+    movedDetail: moved,
+  };
+}
+
+export function normalize(data) {
+  if (!data || typeof data !== 'object') return emptyStore(true);
+  const oldVersion = Number(data.version || 1);
+  const rawSettings = data.settings && typeof data.settings === 'object' ? data.settings : {};
+  const base = emptyStore(false);
+  base.version = STORE_VERSION;
+  base.settings = { ...base.settings, ...rawSettings };
+  // v3 起 kvSection 没了：哪个栏目是 KV，由栏目自己的 kv 标记说了算
+  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.exports = Array.isArray(data.exports) ? data.exports.slice(0, MAX_EXPORT_HISTORY) : [];
+  if (oldVersion < 2) base._migration = migrateSecretToKv(base);
+  if (oldVersion < 3) {
+    const m = migrateKvToTable(base, rawSettings);
+    if (m) base._migration = { ...(base._migration || {}), ...m };
+  }
+  return base;
+}
+
+let cache = null;
+let cachePath = null;
+let cacheMtime = -1;
+let cacheCorruptNote = null;
+let cacheMigrationNote = null;
+
+export function storePathInUse() {
+  return storeFile();
+}
+
+/** 最近一次读盘时把损坏文件挪走的记录（bootstrap / health 会展示）。 */
+export function corruptNote() {
+  return cacheCorruptNote;
+}
+
+/** 最近一次数据迁移的记录（含原始快照路径），供 bootstrap 展示。 */
+export function migrationNote() {
+  return cacheMigrationNote;
+}
+
+export async function loadStore(explicitPath) {
+  const p = explicitPath || storeFile();
+  try {
+    const st = await fsp.stat(p);
+    if (cache && cachePath === p && cacheMtime === st.mtimeMs) return cache;
+    const raw = await fsp.readFile(p, 'utf8');
+    let parsed = null;
+    let corrupt = null;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (e) {
+      // 读失败**降级返回空结构**（工具不该启动即崩），但先把损坏文件留一份——
+      // 直接返回空结构的话，下一次写入就把用户的数据永久覆盖了。
+      corrupt = join(p + '.corrupt-' + stamp() + '.json');
+      try { await fsp.rename(p, corrupt); } catch { /* 尽力 */ }
+      cacheCorruptNote = { from: p, to: corrupt, error: String(e && e.message) };
+    }
+    const oldVersion = Number((parsed && parsed.version) || 1);
+    const next = normalize(parsed);
+
+    if (!corrupt && oldVersion < STORE_VERSION && next._migration) {
+      // 迁移前先把**原始文件**原样留一份（不是迁移后的），出问题能整份退回
+      const snapshot = join(snapshotDir(), `${stamp()}-migrate-v${oldVersion}-to-v${STORE_VERSION}.json`);
+      await ensureDir(snapshotDir());
+      try { await fsp.copyFile(p, snapshot); } catch { /* 尽力 */ }
+      cacheMigrationNote = {
+        from: oldVersion,
+        to: STORE_VERSION,
+        snapshot: displayPath(snapshot),
+        snapshotRaw: snapshot,
+        ...next._migration,
+      };
+      delete next._migration;
+      // 就地落盘：version 写进去之后就不会再迁移（幂等）
+      await saveStore(next, p);
+      return next;
+    }
+
+    delete next._migration;
+    cache = next;
+    cachePath = p;
+    // 解析失败时文件已被挪走，mtime 用 -1 强制下次重新判断
+    cacheMtime = corrupt ? -1 : st.mtimeMs;
+    return cache;
+  } catch {
+    cache = emptyStore(true);
+    cachePath = p;
+    cacheMtime = -1;
+    return cache;
+  }
+}
+
+export async function saveStore(next, explicitPath) {
+  const p = explicitPath || storeFile();
+  const data = normalize(next);
+  delete data._migration;
+  await ensureDir(join(p, '..'));
+  // 原子写：临时文件 + rename。中断时用户要么看到旧数据，要么看到新数据。
+  await writeAtomic(p, JSON.stringify(data, null, 2) + '\n');
+  cache = data;
+  cachePath = p;
+  cacheMtime = -1;
+  try { cacheMtime = (await fsp.stat(p)).mtimeMs; } catch { /* 保持 -1 */ }
+  return data;
+}
+
+/**
+ * 读-改-写事务：fn 直接改传入的**深拷贝**；抛错则不落盘。
+ * structuredClone 是必需的——直接改缓存对象会让「抛错不落盘」名存实亡。
+ */
+export async function mutateStore(fn, explicitPath) {
+  const cur = structuredClone(await loadStore(explicitPath));
+  const result = fn(cur);
+  await saveStore(cur, explicitPath);
+  return result === undefined ? cur : result;
+}
+
+/** 破坏性写入前留一份可回滚快照。 */
+export async function snapshotStore(reason, explicitPath) {
+  const cur = await loadStore(explicitPath);
+  const dir = snapshotDir();
+  await ensureDir(dir);
+  const file = join(dir, `${stamp()}-${reason}.json`);
+  await writeJsonAtomic(file, cur);
+  await pruneSnapshots(dir);
+  return file;
+}
+
+async function pruneSnapshots(dir) {
+  try {
+    const items = (await fsp.readdir(dir)).filter((n) => n.endsWith('.json')).sort();
+    const extra = items.length - MAX_SNAPSHOTS;
+    for (let i = 0; i < extra; i++) await fsp.rm(join(dir, items[i]), { force: true });
+  } catch { /* 清理失败不影响主流程 */ }
+}
+
+export async function listSnapshots() {
+  const dir = snapshotDir();
+  try {
+    const items = (await fsp.readdir(dir)).filter((n) => n.endsWith('.json')).sort().reverse();
+    const out = [];
+    for (const name of items.slice(0, MAX_SNAPSHOTS)) {
+      const p = join(dir, name);
+      const st = await fsp.stat(p);
+      out.push({ name, path: p, bytes: st.size, at: st.mtime.toISOString() });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+export async function storeExists() {
+  return pathExists(storeFile());
+}