nx-sk 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 本文件格式参考 [Keep a Changelog](https://keepachangelog.com/)，中文正文。
 
+## 0.28.0 (2026-11-10)
+
+**全量 TypeScript 化：后端与前端源码统一为 `.ts/.tsx`；字段与模块改为注册表驱动。对外行为不变。**
+
+### Changed
+
+- **源码全量 TypeScript**：`src/**` 不再有 `.js/.jsx`；`pnpm build` 先用 `tsc -p tsconfig.build.json`
+  产出 `dist/**/*.js`（`.ts` 导入后缀在 emit 时改写），再把面板构建到 `dist/web/public`。
+- **字段收敛为穷举注册表**：服务端 `FIELD_BEHAVIOR` / `FIELD_SEAL`、前端 `FIELD_CONTROLS`
+  都是 `Record<FieldType, …>`；`FIELD_TYPES` 加一项而漏实现/漏控件，会直接编译失败。
+- **模块「目录即声明」**：`src/modules/<id>/index.ts` 自动装载，新增模块不再需要改注册表与 eslint 清单。
+- **前端只消费 `shared`**：类型与零依赖纯函数从 `src/shared/**` 引入，eslint 边界规则覆盖 `.ts/.tsx`，
+  继续拦住 `import '../../core/**'` 与 `import '../../modules/**'`。
+
+### Fixed
+
+- **导出 ZIP 时表格的敏感列按列定义解密**：此前 `plainValues` 只处理 `entrylist`，含敏感列的表格会带密文出包，
+  换机器后永久不可解（独立提交 `fc4b9e2`）。
+
+### 说明
+
+- 命令、HTTP 响应形状、面板文案与交互、`store.json` 格式均未变化；`engines.node` 仍是 `>=18.17`。
+- 贡献者：单测直接执行 `.ts` 需要 Node `>=22.18`；改了后端源码要重新 `pnpm build`。
+
 ## 0.27.0 (2026-11-08)
 
 **表格字段重做：列头 ⋮ 属性菜单、行列都有抓手、去掉了那一整块「列设置」表单。**

package/README.md

@@ -11,13 +11,26 @@ nx-sk serve          # 打开面板（http://127.0.0.1:7866）
 
 ## 安装
 
+**要求 Node.js >= 18.17。** 包内是构建好的 `dist/`（纯 JS），运行时不需要 TypeScript。
+
+```bash
+npm i -g nx-sk        # 命令名就是包名
+nx-sk version
+nx-sk serve           # 打开面板
+```
+
+## 开发
+
+**开发/测试需要 Node >= 22.18**（单测用 `node --test` 直接跑 `.ts`，依赖 Node 原生类型剥离）；
+运行 CLI 与面板仍只需 >= 18.17。改了后端要重新构建——`dist/` 是运行时唯一入口。
+
 命令名就是包名。**推荐做成全局垫片**（全局 node_modules 里是指向本项目的软链，
 改代码立刻生效，不用重新安装）：
 
 ```bash
 cd <本项目>
 pnpm install          # 只为构建面板；CLI 侧零依赖
-pnpm run build        # 产出 src/web/public，serve 才有面板可服务
+pnpm run build        # tsc → dist/**/*.js，vite → dist/web/public
 npm link              # → 全局多了 nx-sk / nx-sk.cmd / nx-sk.ps1
 nx-sk version         # 从任何目录都能跑
 nx-sk serve           # 打开面板
@@ -45,7 +58,7 @@ nx-sk serve           # 打开面板
 >
 > 别忘了 `chmod +x ~/.local/bin/nx-sk`。验证：`cd / && nx-sk version`。
 
-> 不想污染全局也行：`node bin/nx-sk.mjs <子命令>` 等价，或 `npx --no-install . <子命令>`。
+> 不想污染全局也行：先 `pnpm build`，再 `node bin/nx-sk.mjs <子命令>`，或 `npx --no-install . <子命令>`。
 
 ### skill：用**软链垫片**（推荐）
 
@@ -516,9 +529,9 @@ pnpm test        # = lint + build + 冒烟 + 单测
 | --- | --- |
 | `bin/nx-sk.mjs` | 唯一入口，只转发 argv + 兜异常 |
 | `src/core/` | 零业务语义：paths / errors / store / fsx / crypto / vault / fields / attachments / render / ids / open |
-| `src/modules/<域>/` | `index.js`(action 声明) + `service.js`(业务) + `view.jsx`(面板) |
+| `src/modules/<域>/` | `index.js`(action 声明) + `service.js`(业务)。**不声明视图** |
 | `src/runtime/` | registry / spec / cli / api / server —— 装配层，不写业务 |
-| `src/web/frontend/` | React 壳 + 组件 + 视图注册表 |
+| `src/web/frontend/` | React 壳 + 组件 + `modules/<域>/view.jsx` + 视图注册表（视图只住这里） |
 | `assets/nx-sk/` | 随包分发的 skill（SKILL.md + references/） |
 | `tests/unit/` · `tests/smoke.mjs` | 一致性断言 + 端到端冒烟 |
 
@@ -553,7 +566,7 @@ agent 手册** —— 它写在创建本项目的脚手架 skill `server-cli-web
 | 把打码值当成新值写回去 | 密钥字段被写成 `sk-1****cdef` 这串掩码，**原凭据永久丢失** | 写入前比对掩码：相等就当成「未改动」保留原密文；含 `******` 的值直接拒绝 |
 | 删条目/栏目没有留退路 | 误删即不可逆；这是用户的**唯一一份**个人信息 | 破坏性写操作一律先 `transfer export` 导出，导出的包就是唯一回退手段 —— 不另设本地备份模块 |
 | store.json 解析失败就当空库继续 | 下一次写入把用户数据永久覆盖 | 先把损坏文件改名为 `store.json.corrupt-<时间>.json`，再降级返回空结构 |
-| 前端 import 了 `node:*` 或 `core/` | Vite 把 Node 侧代码打进浏览器包，dev 模式白屏 | lint 的 `files` 同时覆盖 `view.jsx`，禁掉 `node:*` / `core` / `runtime` / `service.js` |
+| 前端 import 了 `node:*` 或 `core/` | Vite 把 Node 侧代码打进浏览器包，dev 模式白屏 | lint 的 `files` 覆盖整个 `src/web/frontend/**`（视图都在这里），禁掉 `node:*` / `core` / `runtime` / `service.js` |
 | 新增模块忘了往 eslint 互依禁列里补一行 | **静默**：新模块变成「谁都可以依赖」，且规则随模块数增加持续衰减 | 在禁列旁留注释说明它是**逐模块枚举**的、漏补是静默的；加模块前先读 `eslint.config.js` |
 | 代理前缀 `/api` 与前端源码目录 `api/` 撞车 | 只在 dev 模式整页白屏，报错却是 404 / ECONNREFUSED，离根因很远 | vite 代理加 `bypass`，按「是不是前端资源」分流；并用测试钉住 `shouldServeLocally` |
 | 把「上传 / 选择」放到附件中心，再让条目去引用 | 条目里看不到上传入口，用户不知道该在哪儿加文件；附件中心还被迫预定义分类与槽位，跟栏目脱节 | **上传 / 选择发生在栏目条目里**（`file` 字段的值 = 附件 id）；附件中心由栏目驱动、只做统一展示与库存管理，**不预定义分类、不做指派** |

package/bin/nx-sk.mjs

@@ -1,7 +1,25 @@
 #!/usr/bin/env node
-// nx-sk 的唯一可执行入口：只做两件事——转发 argv、兜住未捕获的异常。
-// 所有命令分发都在 src/runtime/cli.js（那里才是命令表）。
-import { runCli } from '../src/runtime/cli.js';
+// nx-sk 的唯一可执行入口：转发 argv、兜住未捕获的异常。
+// 所有命令分发都在 dist/runtime/cli.js（那里才是命令表）——只跑构建产物，
+// 不在运行时做 TypeScript 类型剥离（Node 对 node_modules 下的 .ts 直接拒绝）。
+//
+// 首次从源码仓库直接跑、或改了后端还没构建时，dist 不存在：给一句能照做的提示，
+// 而不是把 ERR_MODULE_NOT_FOUND 的栈甩给用户。
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const cliUrl = new URL('../dist/runtime/cli.js', import.meta.url);
+
+if (!existsSync(fileURLToPath(cliUrl))) {
+  process.stderr.write(
+    'nx-sk: 找不到构建产物 dist/runtime/cli.js。\n'
+      + '源码仓库需要先构建：pnpm build（npm run build）——它会先 tsc 产出 dist，再构建面板。\n'
+      + '如果你是用 npm 全局安装的，这说明包不完整，请重装：npm i -g nx-sk。\n',
+  );
+  process.exit(1);
+}
+
+const { runCli } = await import(cliUrl.href);
 
 runCli(process.argv.slice(2)).catch((err) => {
   const message = err && err.message ? err.message : String(err);

package/{src → dist}/core/argsafe.js

@@ -12,8 +12,7 @@
 // 又会拦住用 --data 写入的合法 CRLF 多行值（高假阳性）；LF 截断后则与合法单行值
 // 完全不可区分。可靠的信号不存在，因此只能提供可靠通道 + 修好通道本身。
 import { readFileSync } from 'node:fs';
-import { badInput } from './errors.js';
-
+import { badInput } from "./errors.js";
 /**
  * `--data` 的值：JSON 字面量 / `@文件路径` / `-`（stdin）。
  *
@@ -21,33 +20,34 @@ import { badInput } from './errors.js';
  * 「读 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
+    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() === '-';
+    return String(raw ?? '').trim() === '-';
 }
-
 function parseJson(text, src) {
-  try {
-    return JSON.parse(text);
-  } catch (e) {
-    throw badInput(`--data 不是合法 JSON（${src}）: ${e.message}`);
-  }
+    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/... 形式的路径`);
-  }
+    try {
+        return readFileSync(p, 'utf8');
+    }
+    catch (e) {
+        // 路径写法是最常见的坑：Git Bash 的 /tmp 在 node 侧看不到（真实事故 ENOENT），
+        // 所以错误里直接把 Windows 路径形式写出来，省掉一轮排查。
+        throw badInput(`读取文件失败: ${p}（${e.message}）—— Windows 上请用 C:/Users/... 形式的路径`);
+    }
 }
-

package/dist/core/attachments.js

@@ -0,0 +1,463 @@
+// 附件（二进制原件）的磁盘管理：~/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";
+import { behaviorOf } from "./fields/registry.js";
+/**
+ * 「这个字段有没有可能引用附件」——问行为体本身，而不是在这里复述一份类型清单。
+ *
+ * 探针同时覆盖三种引用载体（附件 id 字符串 / 资料袋 file item / 资料袋 text 正文里的
+ * `![x](f_xxx)`）。`refs` 对探针仍返回空数组的类型（text / tags / table / entrylist…）
+ * 就是不可能引用的类型。这样以后加一种「能挂附件」的类型，只要它自己的 refs 认这些
+ * 载体，这里自动算数，不用回来改 attachments。
+ */
+const REF_PROBES = [
+    'f_probe', // file：单值 id（也涵盖 "f_x,f_y" 形态）
+    '![x](f_probe)', // md：正文里的图片引用
+    [{ kind: 'file', fileId: 'f_probe' }, { kind: 'text', text: '![x](f_probe)' }], // source：资料袋
+];
+const mayReferenceFiles = (f) => REF_PROBES.some((probe) => behaviorOf(f.type).refs(f, probe).length > 0);
+// —— 分类 ——
+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,
+    };
+}
+/**
+ * 一个 `file` 字段的值 → 附件 id 数组（**全仓库唯一的归一化入口**）。
+ *
+ * 字段可以挂**多个**附件：新写入统一存数组（哪怕只有一个）。要吃下三种历史形态：
+ * 单值字符串、id 数组、以及旧版把多个 id **连写成一个字符串**（`"f_a,f_b"`——
+ * 0.8.0 之前 `--set` 不拆逗号），所以字符串统一按分隔符拆开。
+ * 去空、去重、保序：同一个附件在一个字段里出现两次没有意义。
+ */
+export function fileIdsOf(value) {
+    const raw = value === null || value === undefined
+        ? []
+        : (Array.isArray(value) ? value : [value]);
+    const out = [];
+    for (const x of raw) {
+        for (const piece of String(x ?? '').split(/[,，、;；]+/)) {
+            const id = piece.trim();
+            if (!id || out.includes(id))
+                continue;
+            out.push(id);
+        }
+    }
+    return out;
+}
+/** 附件定位：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;
+}
+/**
+ * 反向链接：哪些条目的**哪些字段**引用了这个附件。
+ *
+ * 三种引用方式都要认，否则附件中心会把「只在正文里贴过」的图片、
+ * 或「躺在原始资料袋里」的原始文件判成未引用，然后被 cleanup 删掉：
+ *   1. `file` 字段 —— 值是附件 id（或唯一文件名），一个字段可挂多个，
+ *      按 `fileIdsOf` 逐个成员判断，**任一** id 命中即算。
+ *   2. `md` 字段  —— 正文里的 `![说明](f_xxx)`（见 mdimages.mdImageIds）。
+ *      图片是**内嵌在 markdown 里**的，和 file 字段一样是正式引用。
+ *   3. `source` 字段 —— 原始资料袋里 kind='file' 的 item（袋是溯源的锚点：
+ *      字段值是从这份原件整理出来的，原件被删，溯源就成了空话）。
+ * 同一个（条目, 字段）只出一条。附件中心据此显示「被哪些栏目 / 条目 / 字段用到」。
+ */
+export function fileReferences(store, rec) {
+    if (!rec)
+        return [];
+    // 按 **id** 判定命中，不做对象引用比较（`===`）：调用方拿到的往往是
+    // listFiles 加工过的副本，引用比较会静默失配 —— 附件就被误判成「未引用」了。
+    // 正文里也可能是文件名而不是 id，所以两种解析结果都算命中。
+    const targetId = String(rec.id ?? '');
+    const targetName = String(rec.name ?? '');
+    const hits = (refs) => refs.some((ref) => {
+        if (targetId && ref === targetId)
+            return true;
+        const found = findFileRecord(store, ref);
+        if (!found)
+            return false;
+        return (targetId && found.id === targetId) || (targetName && found.name === targetName);
+    });
+    const out = [];
+    for (const sec of store.sections || []) {
+        // 一次栏目只扫一遍条目，别在字段循环里反复全表扫
+        const entries = (store.entries || []).filter((e) => e.section === sec.id);
+        if (!entries.length)
+            continue;
+        const refFields = (sec.fields || []).filter(mayReferenceFiles);
+        if (!refFields.length)
+            continue;
+        for (const e of entries) {
+            const push = (f) => out.push({
+                sectionId: sec.id, sectionTitle: sec.title,
+                entryId: e.id, entryTitle: e.title,
+                fieldKey: f.key, fieldLabel: f.label,
+            });
+            // 引用口径由各类型的 `refs` 决定：附件中心的「谁引用了它」**不**把资料袋正文里
+            // 内嵌的图算进来（既有行为，P2 不改）；导出打包才算（见 transfer.referencedFileIds）。
+            for (const f of refFields) {
+                const ids = behaviorOf(f.type).refs(f, e.values?.[f.key]);
+                if (ids.length && hits(ids))
+                    push(f);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * 附件中心的分组素材：哪些栏目**可能**引用附件。
+ * 中心据此按栏目筛选 / 分组 —— 组织方式**完全由栏目驱动，不预定义任何分类或槽位**。
+ * 带 `file` / `md` 字段的栏目都算数：md 字段正文里贴的图也是正式引用；
+ * `source` 袋也算——袋里的原始文件是溯源的锚点，同样要能按栏目筛出来。
+ */
+export function collectFileSections(store) {
+    return (store.sections || [])
+        .filter((s) => (s.fields || []).some(mayReferenceFiles))
+        .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;
+    // 改名时**不带扩展名**就把原扩展名接回去——否则物理文件丢掉 .jpg/.pdf，
+    // 一切按扩展名认类型的地方（内联预览 / Content-Type / 系统默认程序打开 /
+    // 历史迁移 / 导入还原出来的文件）都会哑掉，而台账里的 ext 字段还骗人说没丢。
+    let wanted = name || rec.name;
+    const originalExt = rec.ext || extname(rec.name).toLowerCase();
+    if (name && originalExt && !extname(wanted))
+        wanted += originalExt;
+    const fileName = safeFileName(wanted);
+    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);
+        });
+    });
+}