@xiaobuyu/nodesign 0.0.1

package/server/lib/docx/numbering.js

@@ -0,0 +1,218 @@
+/**
+ * server/lib/docx/numbering.js — 自动编号（word/numbering.xml，2026-08-18）
+ *
+ * ## 为什么值得单独一个 part
+ *
+ * 「列表必须是真编号定义，不是手打 1. 2.」是 docx-craft 的结构真实性军规之一，
+ * 判据是**用户在 Word 里插一条会不会散架**：手打的编号插一条要全手改，删一条
+ * 就断号。但 2026-08-17 上线时引擎只有注释里提过 numbering，实际不产这个 part
+ * —— `para.list` 写上去会产出一个指向空处的 numId，比手打还糟。
+ * 所以军规当时被改成了诚实边界。这个模块把它变回真的。
+ *
+ * ## agent 面对的是名字不是数字
+ *
+ * OOXML 里 numId 是整数，而且 `w:num`（实例）和 `w:abstractNum`（定义）是两层。
+ * 这层间接对 agent 毫无价值，所以 token 里**按名字引用**：
+ *
+ *   tokens.numbering = { "条款": "公文条款" }          // 用内置梯队
+ *   tokens.numbering = { "自定义": { levels: [...] } }  // 自己写
+ *   块上：{ t:'p', style:'Normal', list: { name:'条款', ilvl:0 }, text:'…' }
+ *
+ * 名字→numId 的映射在 build 时算，agent 不碰。
+ *
+ * ## 内置梯队面向中文文档
+ *
+ * 中文正式文档的层级传统是 `一、`→`（一）`→`1.`→`（1）`（公文那一套），
+ * 跟英文的 `1.`→`a.`→`i.` 不是一回事。⭐ 这是「面向中文用户」这条定位在
+ * 编号这一层的具体兑现 —— 默认给对的那套，而不是给一套再让人改。
+ */
+
+import { elem, textNode, serializeNode } from './xml.js';
+import { sortChildren } from './order.js';
+
+const W = 'xmlns:w';
+const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+const DECL = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\r\n';
+const val = (name, v) => elem(name, [['w:val', v]]);
+
+/**
+ * 合法的 `w:numFmt`。闭合，跟 token schema 其他地方一个口径。
+ * 只收中文文档真会用到的那些 —— ISO 29500 里有六十多个，全放开只会让人写出
+ * Word 显示不出来的东西。
+ */
+export const NUM_FMTS = new Set([
+  'decimal',                    // 1 2 3
+  'chineseCounting',            // 一 二 三
+  'chineseCountingThousand',    // 一 二 三（万进位）
+  'ideographDigital',           // 一 二 三
+  'ideographTraditional',       // 甲 乙 丙
+  'decimalEnclosedCircle',      // ① ② ③  —— 中文文档极常用
+  'decimalEnclosedParen',       // ⑴ ⑵ ⑶
+  'decimalEnclosedFullstop',    // ⒈ ⒉ ⒊
+  'lowerLetter', 'upperLetter', 'lowerRoman', 'upperRoman',
+  'bullet', 'none',
+]);
+
+/** 一个字的宽度（小四 12pt 下约 240 twip）—— 缩进梯度按字算，不按英寸 */
+const CHAR = 240;
+
+/**
+ * 内置编号梯队。
+ * `text` 里的 `%N` 是「第 N 级的当前值」，所以 `%1.%2` 出的是 `1.1`。
+ */
+export const NUM_PRESETS = {
+  // 公文/正式报告的中文层级传统：一、→（一）→ 1. →（1）。
+  // 形态是**首行缩进两字 + 文字紧跟编号**（「　　一、总体要求」，续行顶格），
+  // 跟英文列表的悬挂缩进块是两种东西。
+  公文条款: [
+    { fmt: 'chineseCounting', text: '%1、', firstLine: 2, suff: 'nothing' },
+    { fmt: 'chineseCounting', text: '（%2）', firstLine: 2, suff: 'nothing' },
+    { fmt: 'decimal', text: '%3.', firstLine: 2, suff: 'space' },
+    { fmt: 'decimal', text: '（%4）', firstLine: 2, suff: 'nothing' },
+  ],
+  // 技术文档那一路：1. / 1.1 / 1.1.1。这个要悬挂缩进 —— 折行对齐到文字起点，
+  // 编号那一列空着，整块看起来是对齐的。
+  数字条款: [
+    { fmt: 'decimal', text: '%1.', indent: 1.5, hanging: 1.5 },
+    { fmt: 'decimal', text: '%1.%2', indent: 3, hanging: 2 },
+    { fmt: 'decimal', text: '%1.%2.%3', indent: 4.5, hanging: 2.5 },
+  ],
+  // 圈码：中文文档里"并列要点"最常见的一种。圈码本身占一个全角宽，
+  // 后面不需要间隔（suff:nothing），但要悬挂让折行对齐。
+  圈码: [
+    { fmt: 'decimalEnclosedCircle', text: '%1', indent: 1, hanging: 1, suff: 'nothing' },
+  ],
+  // 项目符号。⚠️ 故意用真实汉字区符号而不是 Symbol/Wingdings 字体的私用码位 ——
+  // 后者在没装那两个字体的机器上（我们的渲染服务器就没有）会变成豆腐块。
+  项目符号: [
+    { fmt: 'bullet', text: '●', indent: 1.5, hanging: 1.5 },
+    { fmt: 'bullet', text: '○', indent: 2.5, hanging: 1.5 },
+    { fmt: 'bullet', text: '▪', indent: 3.5, hanging: 1.5 },
+  ],
+};
+
+/** 一条 numbering 定义 → levels 数组（内置名 or 自定义都归一到这里） */
+export function resolveLevels(defn) {
+  if (typeof defn === 'string') {
+    const preset = NUM_PRESETS[defn];
+    if (!preset) {
+      throw new Error(`unknown numbering preset '${defn}'，可选：${Object.keys(NUM_PRESETS).join(' / ')}`);
+    }
+    return preset;
+  }
+  if (defn && Array.isArray(defn.levels)) return defn.levels;
+  throw new Error('numbering 定义要么是内置梯队名，要么是 { levels: [...] }');
+}
+
+/** levels 校验（闭合，跟 validateTokens 同口径）*/
+const LEVEL_KEYS = new Set(['fmt', 'text', 'indent', 'hanging', 'firstLine',
+  'indentTwip', 'hangingTwip', 'firstLineTwip', 'start', 'align', 'suff']);
+export function validateNumbering(numbering) {
+  const errs = [];
+  for (const [name, defn] of Object.entries(numbering ?? {})) {
+    let levels;
+    try { levels = resolveLevels(defn); } catch (err) { errs.push(`numbering.${name}: ${err.message}`); continue; }
+    if (!levels.length || levels.length > 9) {
+      errs.push(`numbering.${name}: 要 1-9 级，收到 ${levels.length}`);
+    }
+    levels.forEach((lv, i) => {
+      for (const k of Object.keys(lv)) {
+        if (!LEVEL_KEYS.has(k)) errs.push(`numbering.${name}.levels[${i}]: unknown key ${k}`);
+      }
+      if (!NUM_FMTS.has(lv.fmt)) {
+        errs.push(`numbering.${name}.levels[${i}].fmt: '${lv.fmt}' 不在支持的编号格式里`
+          + `（常用：decimal / chineseCounting / decimalEnclosedCircle / bullet）`);
+      }
+      if (typeof lv.text !== 'string' || !lv.text) {
+        errs.push(`numbering.${name}.levels[${i}].text: 必填，如 '%1、' 或 '%1.%2' 或 '●'`);
+      }
+      if (lv.fmt !== 'bullet' && lv.fmt !== 'none' && !/%\d/.test(lv.text ?? '')) {
+        errs.push(`numbering.${name}.levels[${i}].text: '${lv.text}' 里没有 %N 占位符，`
+          + '编号值不会出现在文档里（bullet 才不需要）');
+      }
+    });
+  }
+  return errs;
+}
+
+/**
+ * 名字 → numId 的映射。**顺序稳定**（按 Object.keys 的插入序），
+ * 这样同一份 token 每次构建出的 numId 一样 —— 保真自检和 diff 才有意义。
+ */
+export function numIdMap(numbering) {
+  const map = new Map();
+  let id = 1;
+  for (const name of Object.keys(numbering ?? {})) map.set(name, id++);
+  return map;
+}
+
+function buildLevel(lv, ilvl) {
+  // 两种缩进形态，选哪种决定的是**折行的第二行去哪儿**：
+  //   hanging（悬挂）—— 折行对齐到文字起点，编号那一列空出来。技术文档 1.1.1 那种
+  //     对齐块要这个。
+  //   firstLine（首行缩进）—— 折行回到左边距。中文公文的层级标题是这个形态：
+  //     「　　一、总体要求」，续行顶格。
+  const indentTwip = lv.indentTwip ?? Math.round((lv.indent ?? 0) * CHAR);
+  const kids = [
+    val('w:start', lv.start ?? 1),
+    val('w:numFmt', lv.fmt),
+    val('w:lvlText', lv.text),
+    val('w:lvlJc', lv.align ?? 'left'),
+  ];
+  // ⭐ w:suff 决定编号和文字之间放什么。默认是 tab —— 而 tab 会跳到下一个制表位，
+  // 于是「一、」这种两字宽的编号后面会空出一大截（首次真跑就是这么发现的）。
+  // 中文编号后面本来就带全角标点（一、 / （一） / ①），不需要再加间隔，
+  // 所以这些梯队一律 suff:'nothing'，让文字紧跟着编号。
+  if (lv.suff) kids.push(val('w:suff', lv.suff));
+  const ind = [['w:left', indentTwip]];
+  if (lv.firstLine != null || lv.firstLineTwip != null) {
+    ind.push(['w:firstLine', lv.firstLineTwip ?? Math.round(lv.firstLine * CHAR)]);
+  } else {
+    ind.push(['w:hanging', lv.hangingTwip ?? Math.round((lv.hanging ?? 1.5) * CHAR)]);
+  }
+  kids.push(elem('w:pPr', [], [elem('w:ind', ind)]));
+  return sortChildren(elem('w:lvl', [['w:ilvl', ilvl]], kids));
+}
+
+/**
+ * 产 word/numbering.xml。
+ * @param {object} numbering  tokens.numbering
+ * @returns {string|null} null = 没有编号定义，这个 part 不该存在
+ */
+export function buildNumberingXml(numbering) {
+  const names = Object.keys(numbering ?? {});
+  if (!names.length) return null;
+
+  const ids = numIdMap(numbering);
+  const abstracts = [];
+  const nums = [];
+  for (const name of names) {
+    const numId = ids.get(name);
+    const abstractId = numId;           // 一对一，不共享定义（共享只会让排错变难）
+    const levels = resolveLevels(numbering[name]);
+    abstracts.push(sortChildren(elem('w:abstractNum', [['w:abstractNumId', abstractId]], [
+      val('w:multiLevelType', levels.length > 1 ? 'multilevel' : 'singleLevel'),
+      val('w:name', name),
+      ...levels.slice(0, 9).map((lv, i) => buildLevel(lv, i)),
+    ])));
+    nums.push(elem('w:num', [['w:numId', numId]], [val('w:abstractNumId', abstractId)]));
+  }
+
+  const root = sortChildren(elem('w:numbering', [[W, NS_W]], [...abstracts, ...nums]));
+  return DECL + serializeNode(root);
+}
+
+/**
+ * 按 tokens 对象记忆化的 name→numId 映射。
+ * 每个段落都重算一次不贵，但那是"同一件事算很多遍"，而这个仓库最贵的一课就是
+ * 同一件东西有多个实例 —— 记一份。
+ */
+const memo = new WeakMap();
+export function numIdsFor(tokens) {
+  if (!tokens || typeof tokens !== 'object') return new Map();
+  let m = memo.get(tokens);
+  if (!m) { m = numIdMap(tokens.numbering); memo.set(tokens, m); }
+  return m;
+}
+
+export { textNode };

package/server/lib/docx/order.js

@@ -0,0 +1,152 @@
+/**
+ * order.js — OOXML 子元素规范顺序表 + 排序构建器 + 顺序体检。
+ *
+ * 顺序错了 Word 会报「文档已损坏」或静默修复（丢内容），所以：
+ *   - 我们产出的每个属性容器都经 sortChildren() 排序；
+ *   - checkOrder() 可以对任意 document.xml/styles.xml 做顺序体检。
+ *
+ * 表的来源：ECMA-376 CT_* 序列（先按 minimax references/openxml_element_order.md
+ * 抄底，再拿 DocumentFormat.OpenXml 的 OpenXmlValidator 实测校准——那份
+ * references 上一轮已证明不能盲信，凡我们要发射的组合都过了 validator）。
+ */
+
+const T = {
+  'w:pPr': [
+    'w:pStyle', 'w:keepNext', 'w:keepLines', 'w:pageBreakBefore', 'w:framePr',
+    'w:widowControl', 'w:numPr', 'w:suppressLineNumbers', 'w:pBdr', 'w:shd',
+    'w:tabs', 'w:suppressAutoHyphens', 'w:kinsoku', 'w:wordWrap',
+    'w:overflowPunct', 'w:topLinePunct', 'w:autoSpaceDE', 'w:autoSpaceDN',
+    'w:bidi', 'w:adjustRightInd', 'w:snapToGrid', 'w:spacing', 'w:ind',
+    'w:contextualSpacing', 'w:mirrorIndents', 'w:suppressOverlap', 'w:jc',
+    'w:textDirection', 'w:textAlignment', 'w:outlineLvl', 'w:divId',
+    'w:cnfStyle', 'w:rPr', 'w:sectPr', 'w:pPrChange',
+  ],
+  'w:rPr': [
+    'w:rStyle', 'w:rFonts', 'w:b', 'w:bCs', 'w:i', 'w:iCs', 'w:caps',
+    'w:smallCaps', 'w:strike', 'w:dstrike', 'w:outline', 'w:shadow',
+    'w:emboss', 'w:imprint', 'w:noProof', 'w:snapToGrid', 'w:vanish',
+    'w:webHidden', 'w:color', 'w:spacing', 'w:w', 'w:kern', 'w:position',
+    'w:sz', 'w:szCs', 'w:highlight', 'w:u', 'w:effect', 'w:bdr', 'w:shd',
+    'w:fitText', 'w:vertAlign', 'w:rtl', 'w:cs', 'w:em', 'w:lang',
+    'w:eastAsianLayout', 'w:specVanish', 'w:oMath', 'w:rPrChange',
+  ],
+  'w:tblPr': [
+    'w:tblStyle', 'w:tblpPr', 'w:tblOverlap', 'w:bidiVisual',
+    'w:tblStyleRowBandSize', 'w:tblStyleColBandSize', 'w:tblW', 'w:jc',
+    'w:tblCellSpacing', 'w:tblInd', 'w:tblBorders', 'w:shd', 'w:tblLayout',
+    'w:tblCellMar', 'w:tblLook', 'w:tblCaption', 'w:tblDescription',
+    'w:tblPrChange',
+  ],
+  'w:trPr': [
+    'w:cnfStyle', 'w:divId', 'w:gridBefore', 'w:gridAfter', 'w:wBefore',
+    'w:wAfter', 'w:cantSplit', 'w:trHeight', 'w:tblHeader',
+    'w:tblCellSpacing', 'w:jc', 'w:hidden', 'w:ins', 'w:del', 'w:trPrChange',
+  ],
+  'w:tcPr': [
+    'w:cnfStyle', 'w:tcW', 'w:gridSpan', 'w:hMerge', 'w:vMerge',
+    'w:tcBorders', 'w:shd', 'w:noWrap', 'w:tcMar', 'w:textDirection',
+    'w:tcFitText', 'w:vAlign', 'w:hideMark', 'w:headers', 'w:cellIns',
+    'w:cellDel', 'w:cellMerge', 'w:tcPrChange',
+  ],
+  'w:sectPr': [
+    'w:headerReference', 'w:footerReference', 'w:footnotePr', 'w:endnotePr',
+    'w:type', 'w:pgSz', 'w:pgMar', 'w:paperSrc', 'w:pgBorders', 'w:lnNumType',
+    'w:pgNumType', 'w:cols', 'w:formProt', 'w:vAlign', 'w:noEndnote',
+    'w:titlePg', 'w:textDirection', 'w:bidi', 'w:rtlGutter', 'w:docGrid',
+    'w:printerSettings', 'w:sectPrChange',
+  ],
+  'w:style': [
+    'w:name', 'w:aliases', 'w:basedOn', 'w:next', 'w:link', 'w:autoRedefine',
+    'w:hidden', 'w:uiPriority', 'w:semiHidden', 'w:unhideWhenUsed',
+    'w:qFormat', 'w:locked', 'w:personal', 'w:personalCompose',
+    'w:personalReply', 'w:rsid', 'w:pPr', 'w:rPr', 'w:tblPr', 'w:trPr',
+    'w:tcPr', 'w:tblStylePr',
+  ],
+  'w:tblStylePr': ['w:pPr', 'w:rPr', 'w:tblPr', 'w:trPr', 'w:tcPr'],
+  'w:styles': ['w:docDefaults', 'w:latentStyles', 'w:style'],
+  'w:docDefaults': ['w:rPrDefault', 'w:pPrDefault'],
+  'w:tbl': ['w:tblPr', 'w:tblGrid', 'w:tr'],
+  'w:tblBorders': ['w:top', 'w:left', 'w:bottom', 'w:right', 'w:insideH', 'w:insideV'],
+  'w:tcBorders': ['w:top', 'w:left', 'w:bottom', 'w:right', 'w:insideH', 'w:insideV', 'w:tl2br', 'w:tr2bl'],
+  'w:pBdr': ['w:top', 'w:left', 'w:bottom', 'w:right', 'w:between', 'w:bar'],
+  'w:tblCellMar': ['w:top', 'w:left', 'w:bottom', 'w:right'],
+  'w:tcMar': ['w:top', 'w:left', 'w:bottom', 'w:right'],
+  'w:numPr': ['w:ilvl', 'w:numId', 'w:numberingChange', 'w:ins'],
+  'w:abstractNum': ['w:nsid', 'w:multiLevelType', 'w:tmpl', 'w:name',
+    'w:styleLink', 'w:numStyleLink', 'w:lvl'],
+  'w:lvl': ['w:start', 'w:numFmt', 'w:lvlRestart', 'w:pStyle', 'w:isLgl',
+    'w:suff', 'w:lvlText', 'w:lvlPicBulletId', 'w:legacy', 'w:lvlJc',
+    'w:pPr', 'w:rPr'],
+  'w:num': ['w:abstractNumId', 'w:lvlOverride'],
+  'w:numbering': ['w:numPicBullet', 'w:abstractNum', 'w:num', 'w:numIdMacAtCleanup'],
+};
+
+/** 「pPr 必须第一、sectPr 必须最后」这类交错容器的松规则 */
+const LOOSE = {
+  'w:p':    { first: 'w:pPr', last: null },
+  'w:r':    { first: 'w:rPr', last: null },
+  'w:body': { first: null, last: 'w:sectPr' },
+  'w:tr':   { first: 'w:trPr', last: null },
+  'w:tc':   { first: 'w:tcPr', last: null },
+};
+
+export const ORDER_TABLES = T;
+
+/** 按规范表就地排序一个元素的直属子元素（稳定排序，未知名字保持相对位置放最后并报错可选） */
+export function sortChildren(node, { strictUnknown = true } = {}) {
+  const table = T[node.name];
+  if (!table) return node;
+  const rank = new Map(table.map((n, i) => [n, i]));
+  const unknown = node.children.filter((c) => c.type === 'elem' && !rank.has(c.name));
+  if (unknown.length && strictUnknown) {
+    throw new Error(`sortChildren(${node.name}): unknown child ${unknown[0].name}`);
+  }
+  const elems = node.children.filter((c) => c.type === 'elem');
+  const rest = node.children.filter((c) => c.type !== 'elem');
+  elems.sort((a, b) => (rank.get(a.name) ?? 9999) - (rank.get(b.name) ?? 9999));
+  node.replaceChildren([...elems, ...rest]);
+  return node;
+}
+
+/**
+ * 顺序体检：递归检查一棵树，返回违规列表 [{ path, parent, child, msg }]
+ */
+export function checkOrder(root, path = `/${root.name}`, out = []) {
+  const table = T[root.name];
+  const elems = root.children.filter((c) => c.type === 'elem');
+  if (table) {
+    const rank = new Map(table.map((n, i) => [n, i]));
+    let prev = -1;
+    let prevName = null;
+    for (const c of elems) {
+      const r = rank.get(c.name);
+      if (r === undefined) {
+        out.push({ path, parent: root.name, child: c.name, msg: 'unknown child (not in order table)' });
+        continue;
+      }
+      if (r < prev) {
+        out.push({ path, parent: root.name, child: c.name, msg: `out of order: ${c.name} after ${prevName}` });
+      }
+      if (r >= prev) { prev = r; prevName = c.name; }
+    }
+  }
+  const loose = LOOSE[root.name];
+  if (loose) {
+    if (loose.first) {
+      const idx = elems.findIndex((c) => c.name === loose.first);
+      if (idx > 0) out.push({ path, parent: root.name, child: loose.first, msg: `${loose.first} must be first child` });
+    }
+    if (loose.last) {
+      const idx = elems.findIndex((c) => c.name === loose.last);
+      if (idx >= 0 && idx !== elems.length - 1) {
+        out.push({ path, parent: root.name, child: loose.last, msg: `${loose.last} must be last child` });
+      }
+    }
+  }
+  let i = 0;
+  for (const c of elems) {
+    i += 1;
+    checkOrder(c, `${path}/${c.name}[${i}]`, out);
+  }
+  return out;
+}

package/server/lib/docx/rawzip.js

@@ -0,0 +1,172 @@
+/**
+ * rawzip.js — 面向 docx 的最小 ZIP 读写器，核心卖点是「保真」：
+ * 没被替换的 entry，local header + 压缩数据 + data descriptor 原样字节拷贝；
+ * 只有被替换/新增的 entry 走 zlib deflateRaw 重压。
+ *
+ * 覆盖范围 = OOXML 容器实际会遇到的:
+ *   - 方法 0 (store) / 8 (deflate)
+ *   - bit3 data descriptor（流式写出的 zip）
+ *   - 不支持 zip64 / 加密 / 分卷（docx 不会用；遇到即抛错，调用方退回只读）
+ */
+
+import { deflateRawSync, inflateRawSync } from 'node:zlib';
+import { crc32 } from 'node:zlib';
+
+const EOCD_SIG = 0x06054b50;
+const CEN_SIG = 0x02014b50;
+const LOC_SIG = 0x04034b50;
+
+/**
+ * @param {Buffer} buf
+ * @returns {{ entries: Map<string, Entry>, order: string[] }}
+ * Entry = { name, method, crc, csize, usize, flags, cenExtra..., locRaw:Buffer|null, replaced:Buffer|null }
+ */
+export function readZip(buf) {
+  // 找 EOCD（从尾部回扫，容忍 comment）
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65535); i--) {
+    if (buf.readUInt32LE(i) === EOCD_SIG) { eocd = i; break; }
+  }
+  if (eocd < 0) throw new Error('EOCD not found (not a zip)');
+  const count = buf.readUInt16LE(eocd + 10);
+  const cenOfs = buf.readUInt32LE(eocd + 16);
+  if (cenOfs === 0xffffffff) throw new Error('zip64 not supported');
+
+  const entries = new Map();
+  const order = [];
+  let p = cenOfs;
+  for (let i = 0; i < count; i++) {
+    if (buf.readUInt32LE(p) !== CEN_SIG) throw new Error(`bad central dir at ${p}`);
+    const flags = buf.readUInt16LE(p + 8);
+    const method = buf.readUInt16LE(p + 10);
+    const mtime = buf.readUInt16LE(p + 12);
+    const mdate = buf.readUInt16LE(p + 14);
+    const crc = buf.readUInt32LE(p + 16);
+    const csize = buf.readUInt32LE(p + 20);
+    const usize = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const attrs = buf.readUInt32LE(p + 38);
+    const locOfs = buf.readUInt32LE(p + 42);
+    const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+    if ((flags & 0x1) !== 0) throw new Error('encrypted zip not supported');
+    if (csize === 0xffffffff || usize === 0xffffffff) throw new Error('zip64 not supported');
+
+    // local header：算出这个 entry 的完整原始片段 [local header + data (+ descriptor)]
+    if (buf.readUInt32LE(locOfs) !== LOC_SIG) throw new Error(`bad local header for ${name}`);
+    const locNameLen = buf.readUInt16LE(locOfs + 26);
+    const locExtraLen = buf.readUInt16LE(locOfs + 28);
+    const dataStart = locOfs + 30 + locNameLen + locExtraLen;
+    let rawEnd = dataStart + csize;
+    if (flags & 0x8) {
+      // data descriptor: 可带可不带签名 0x08074b50
+      if (buf.readUInt32LE(rawEnd) === 0x08074b50) rawEnd += 16; else rawEnd += 12;
+    }
+    const entry = {
+      name, flags, method, mtime, mdate, crc, csize, usize, attrs,
+      cenExtra: Buffer.from(buf.subarray(p + 46 + nameLen, p + 46 + nameLen + extraLen)),
+      comment: Buffer.from(buf.subarray(p + 46 + nameLen + extraLen, p + 46 + nameLen + extraLen + commentLen)),
+      locRaw: Buffer.from(buf.subarray(locOfs, rawEnd)),
+      dataOfs: dataStart - locOfs,
+      replaced: null,
+    };
+    entries.set(name, entry);
+    order.push(name);
+    p += 46 + nameLen + extraLen + commentLen;
+  }
+  return { entries, order };
+}
+
+export function entryData(zip, name) {
+  const e = zip.entries.get(name);
+  if (!e) return null;
+  if (e.replaced) return e.replaced;
+  const raw = e.locRaw.subarray(e.dataOfs, e.dataOfs + e.csize);
+  if (e.method === 0) return Buffer.from(raw);
+  if (e.method === 8) return inflateRawSync(raw);
+  throw new Error(`unsupported method ${e.method} for ${name}`);
+}
+
+export function replaceEntry(zip, name, content) {
+  const e = zip.entries.get(name);
+  if (!e) throw new Error(`no such entry: ${name}`);
+  e.replaced = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
+}
+
+export function addEntry(zip, name, content) {
+  if (zip.entries.has(name)) return replaceEntry(zip, name, content);
+  const e = {
+    name, flags: 0x800 /* utf8 name */, method: 8, mtime: 0, mdate: 0x2100 /* 1996-08-00 stable */,
+    crc: 0, csize: 0, usize: 0, attrs: 0,
+    cenExtra: Buffer.alloc(0), comment: Buffer.alloc(0),
+    locRaw: null, dataOfs: 0,
+    replaced: Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8'),
+  };
+  zip.entries.set(name, e);
+  zip.order.push(name);
+}
+
+export function writeZip(zip) {
+  const chunks = [];
+  const cen = [];
+  let offset = 0;
+  for (const name of zip.order) {
+    const e = zip.entries.get(name);
+    let locBuf; let crc; let csize; let usize; let method; let flags;
+    if (e.replaced == null) {
+      locBuf = e.locRaw;                       // 原样拷贝（保真核心）
+      crc = e.crc; csize = e.csize; usize = e.usize; method = e.method; flags = e.flags;
+    } else {
+      const data = e.replaced;
+      const packed = deflateRawSync(data, { level: 9 });
+      method = packed.length < data.length ? 8 : 0;
+      const body = method === 8 ? packed : data;
+      crc = crc32(data) >>> 0;
+      csize = body.length; usize = data.length;
+      flags = 0x800; // utf8 filename，不用 descriptor
+      const nameBuf = Buffer.from(name, 'utf8');
+      const head = Buffer.alloc(30);
+      head.writeUInt32LE(LOC_SIG, 0);
+      head.writeUInt16LE(20, 4);       // version needed
+      head.writeUInt16LE(flags, 6);
+      head.writeUInt16LE(method, 8);
+      head.writeUInt16LE(e.mtime, 10);
+      head.writeUInt16LE(e.mdate, 12);
+      head.writeUInt32LE(crc, 14);
+      head.writeUInt32LE(csize, 18);
+      head.writeUInt32LE(usize, 22);
+      head.writeUInt16LE(nameBuf.length, 26);
+      head.writeUInt16LE(0, 28);
+      locBuf = Buffer.concat([head, nameBuf, body]);
+    }
+    const nameBuf = Buffer.from(name, 'utf8');
+    const c = Buffer.alloc(46);
+    c.writeUInt32LE(CEN_SIG, 0);
+    c.writeUInt16LE(20, 4); c.writeUInt16LE(20, 6);
+    c.writeUInt16LE(flags, 8);
+    c.writeUInt16LE(method, 10);
+    c.writeUInt16LE(e.mtime, 12); c.writeUInt16LE(e.mdate, 14);
+    c.writeUInt32LE(crc, 16);
+    c.writeUInt32LE(csize, 20); c.writeUInt32LE(usize, 24);
+    c.writeUInt16LE(nameBuf.length, 28);
+    c.writeUInt16LE(e.cenExtra.length, 30);
+    c.writeUInt16LE(e.comment.length, 32);
+    c.writeUInt32LE(e.attrs, 38);
+    c.writeUInt32LE(offset, 42);
+    cen.push(Buffer.concat([c, nameBuf, e.cenExtra, e.comment]));
+    chunks.push(locBuf);
+    offset += locBuf.length;
+  }
+  const cenStart = offset;
+  let cenSize = 0;
+  for (const c of cen) { chunks.push(c); cenSize += c.length; }
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(EOCD_SIG, 0);
+  eocd.writeUInt16LE(zip.order.length, 8);
+  eocd.writeUInt16LE(zip.order.length, 10);
+  eocd.writeUInt32LE(cenSize, 12);
+  eocd.writeUInt32LE(cenStart, 16);
+  chunks.push(eocd);
+  return Buffer.concat(chunks);
+}

package/server/lib/docx/render.js

@@ -0,0 +1,92 @@
+/**
+ * render.js — docx → PDF → PNG 的 QC 渲染链路。
+ *
+ * ⭐**必须是异步的。** 第一版写成 `execFileSync`，实测一份 55 页中文文档
+ * 把事件循环**整整堵死 11.7 秒** —— 期间全站所有 HTTP、WebSocket 心跳、
+ * agent 流式输出一起停摆。而触发它的不是"用户主动导出"，是**一张卡片滚进
+ * 视口**：画布上有人放了一份长文档，所有人的站就冻一次。
+ * node 是单线程，凡是要等外部进程的地方一律不许用 *Sync。
+ *
+ * 三条已实证的军规：
+ *   1. per-run 独立 LO profile + 可写 HOME（多会话并发抢默认 profile 是必然事件）
+ *   2. soffice 吃不下中文文件名 → 进场先拷成 ASCII 名
+ *   3. FONTCONFIG_FILE 指向 fonts/nodesign-cjk.conf（中文字体替身映射，
+ *      per-run 生效，不污染系统 fontconfig）
+ *
+ * ⚠️ 失败也要收摊：`mkdtemp` 一建出来就进 try，任何一步抛都在 finally 里删掉
+ * scratch —— 第一版是"抛了就拿不到 res，调用方无从 cleanup"，每失败一次漏
+ * 一个约 870KB 的目录在 /tmp（跟数据库抢同一个根分区）。
+ */
+
+import { promises as fs } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// 二进制路径走启动探测（Mac/Win 的 LibreOffice 不在 PATH；没探到就原名让 ENOENT 原样报）
+import { resolveBinary } from '../../runtime/capabilities.js';
+
+const run = promisify(execFile);
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const FONTCONF = join(HERE, 'fonts', 'nodesign-cjk.conf');
+
+/** 单份文档的渲染上限。超时的天花板同时也是"最坏情况占用一个 soffice 槽多久" */
+const SOFFICE_TIMEOUT = 120_000;
+const PDFTOPPM_TIMEOUT = 60_000;
+
+async function exists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+/**
+ * @param {string} docxPath
+ * @param {object} opts { pngPages?: [from,to] | true, dpi?: number, timeoutMs?: number }
+ * @returns {Promise<{ pdf: string, pngs: string[], scratch: string, ms: number }>}
+ *   产物落在独立 scratch 目录里，**调用方成功拿到之后自己收**（cleanupRender）。
+ *   失败的话这里已经收干净了，调用方不用管。
+ */
+export async function renderDocx(docxPath, opts = {}) {
+  const scratch = await fs.mkdtemp(join(tmpdir(), 'ndocx-'));
+  const t0 = Date.now();
+  try {
+    const inFile = join(scratch, 'in.docx');       // 军规2：ASCII 文件名
+    await fs.copyFile(docxPath, inFile);
+    const env = {
+      ...process.env,
+      HOME: scratch,                                // 军规1：可写 HOME
+      FONTCONFIG_FILE: FONTCONF,                    // 军规3：字体替身
+    };
+    await run(resolveBinary('libreoffice', 'soffice'), [
+      `-env:UserInstallation=file://${scratch}/loprofile`,  // 军规1：独立 profile
+      '--headless', '--convert-to', 'pdf', '--outdir', scratch, inFile,
+    ], { env, timeout: opts.timeoutMs ?? SOFFICE_TIMEOUT });
+
+    const pdf = join(scratch, 'in.pdf');
+    if (!await exists(pdf)) throw new Error('soffice produced no pdf');
+
+    const pngs = [];
+    if (opts.pngPages) {
+      const args = ['-png', '-r', String(opts.dpi ?? 120)];
+      if (Array.isArray(opts.pngPages)) {
+        args.push('-f', String(opts.pngPages[0]), '-l', String(opts.pngPages[1]));
+      }
+      await run(resolveBinary('poppler', 'pdftoppm'), [...args, pdf, join(scratch, 'page')], { timeout: PDFTOPPM_TIMEOUT });
+      // pdftoppm 按总页数补零（55 页 → page-01…page-55），宽度统一，
+      // 所以字典序等于数字序 —— 这条核过，不是碰运气
+      for (const f of (await fs.readdir(scratch)).sort()) {
+        if (f.startsWith('page-') && f.endsWith('.png')) pngs.push(join(scratch, f));
+      }
+    }
+    return { pdf, pngs, scratch, ms: Date.now() - t0 };
+  } catch (err) {
+    await fs.rm(scratch, { recursive: true, force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+export async function cleanupRender(res) {
+  if (!res?.scratch) return;
+  await fs.rm(res.scratch, { recursive: true, force: true }).catch(() => {});
+}