@xiaobuyu/nodesign 0.0.1

package/server/lib/docx/xml.js

@@ -0,0 +1,291 @@
+/**
+ * xml.js — OOXML 专用的「保真 DOM」：parse / serialize / 增删改。
+ *
+ * 设计目标（与通用 XML 库刚好相反）：
+ *   1. 没碰过的节点，serialize 时逐字节还原输入（保真编辑的地基）。
+ *      做法：每个节点保留原始片段（openRaw/closeRaw/raw），只有被
+ *      标脏（dirty）或新建的节点才走规范化序列化。
+ *   2. 自检闸门：parse 完立刻 serialize 一遍，若与输入不等，说明这份
+ *      XML 用了我们没覆盖的语法（DTD/CDATA/PI 等），parseXml 直接抛错，
+ *      调用方退回「不编辑」而不是带病手术。
+ *
+ * 覆盖的语法子集 = Word/LibreOffice/我们自己产出的 OOXML 实际用到的：
+ *   声明、元素（含自闭合）、属性、文本、注释、CDATA（原样保留）。
+ *   不支持 DTD / 外部实体（OOXML 不用，遇到即拒——顺带挡住 XXE）。
+ */
+
+const NAME_RE = /^[^\s"'<>/=]+/;
+
+export class XmlNode {
+  constructor(type) {
+    this.type = type;        // 'elem' | 'text' | 'comment' | 'cdata' | 'decl'
+    this.name = '';
+    this.attrs = [];         // [ [name, value(decoded)] ... ] 保序
+    this.children = [];
+    this.parent = null;
+    this.selfClosing = false;
+    // 保真用的原始片段（parse 时填；一旦 dirty 就失效）
+    this.openRaw = null;     // '<w:p w:x="1">' 或自闭合的整个 tag
+    this.closeRaw = null;    // '</w:p>'
+    this.raw = null;         // text/comment/cdata/decl 的原文
+    this.dirty = false;
+  }
+
+  markDirty() {
+    let n = this;
+    while (n && !n.dirty) { n.dirty = true; n = n.parent; }
+  }
+
+  attr(name) {
+    const hit = this.attrs.find(([k]) => k === name);
+    return hit ? hit[1] : null;
+  }
+
+  setAttr(name, value) {
+    const hit = this.attrs.find(([k]) => k === name);
+    if (hit) hit[1] = value; else this.attrs.push([name, value]);
+    this.markDirty();
+  }
+
+  removeAttr(name) {
+    const i = this.attrs.findIndex(([k]) => k === name);
+    if (i >= 0) { this.attrs.splice(i, 1); this.markDirty(); }
+  }
+
+  /** 直属子元素（跳过 text/comment） */
+  childElems(name) {
+    const out = [];
+    for (const c of this.children) {
+      if (c.type === 'elem' && (!name || c.name === name)) out.push(c);
+    }
+    return out;
+  }
+
+  firstChild(name) {
+    for (const c of this.children) {
+      if (c.type === 'elem' && c.name === name) return c;
+    }
+    return null;
+  }
+
+  /** 深度优先找所有指定名字的后代元素 */
+  find(name, out = []) {
+    for (const c of this.children) {
+      if (c.type !== 'elem') continue;
+      if (c.name === name) out.push(c);
+      c.find(name, out);
+    }
+    return out;
+  }
+
+  /** 元素的全部文本内容（w:t 语义下已解码） */
+  text() {
+    if (this.type === 'text') return decodeEntities(this.raw ?? '');
+    let s = '';
+    for (const c of this.children) s += c.text();
+    return s;
+  }
+
+  append(child) {
+    child.parent = this;
+    this.children.push(child);
+    this.markDirty();
+    return child;
+  }
+
+  insertBefore(child, ref) {
+    const i = this.children.indexOf(ref);
+    child.parent = this;
+    if (i < 0) this.children.push(child); else this.children.splice(i, 0, child);
+    this.markDirty();
+    return child;
+  }
+
+  remove(child) {
+    const i = this.children.indexOf(child);
+    if (i >= 0) { this.children.splice(i, 1); this.markDirty(); }
+  }
+
+  replaceChildren(list) {
+    for (const c of list) c.parent = this;
+    this.children = list;
+    this.markDirty();
+  }
+}
+
+export function elem(name, attrs = [], children = []) {
+  const n = new XmlNode('elem');
+  n.name = name;
+  n.attrs = attrs.map(([k, v]) => [k, String(v)]);
+  for (const c of children) { c.parent = n; n.children.push(c); }
+  n.dirty = true;
+  return n;
+}
+
+export function textNode(s) {
+  const n = new XmlNode('text');
+  n.raw = encodeText(String(s));
+  n.dirty = true;
+  return n;
+}
+
+export function decodeEntities(s) {
+  return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (m, body) => {
+    if (body[0] === '#') {
+      const code = body[1] === 'x' || body[1] === 'X'
+        ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : m;
+    }
+    return { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" }[body] ?? m;
+  });
+}
+
+export function encodeText(s) {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+export function encodeAttr(s) {
+  return encodeText(s).replace(/"/g, '&quot;')
+    // 属性值里的换行/Tab 若不转义，解析器会按空格归一（丢信息）
+    .replace(/\n/g, '&#10;').replace(/\t/g, '&#9;').replace(/\r/g, '&#13;');
+}
+
+/**
+ * @param {string} input
+ * @returns {{ decl: string|null, root: XmlNode, trailing: string }}
+ */
+export function parseXml(input) {
+  let pos = 0;
+  const len = input.length;
+  let decl = null;
+
+  if (input.startsWith('')) throw new Error('BOM-prefixed XML not supported (strip first)');
+  if (input.startsWith('<?xml')) {
+    const end = input.indexOf('?>');
+    if (end < 0) throw new Error('unterminated XML declaration');
+    decl = input.slice(0, end + 2);
+    pos = end + 2;
+  }
+
+  const rootWrap = new XmlNode('elem'); // 假根，容纳声明后的空白+根元素
+  const stack = [rootWrap];
+
+  while (pos < len) {
+    const top = stack[stack.length - 1];
+    if (input[pos] === '<') {
+      if (input.startsWith('<!--', pos)) {
+        const end = input.indexOf('-->', pos);
+        if (end < 0) throw new Error('unterminated comment');
+        const n = new XmlNode('comment');
+        n.raw = input.slice(pos, end + 3);
+        n.parent = top; top.children.push(n);
+        pos = end + 3;
+      } else if (input.startsWith('<![CDATA[', pos)) {
+        const end = input.indexOf(']]>', pos);
+        if (end < 0) throw new Error('unterminated CDATA');
+        const n = new XmlNode('cdata');
+        n.raw = input.slice(pos, end + 3);
+        n.parent = top; top.children.push(n);
+        pos = end + 3;
+      } else if (input.startsWith('<!', pos) || input.startsWith('<?', pos)) {
+        throw new Error(`unsupported markup at ${pos}: ${input.slice(pos, pos + 24)}`);
+      } else if (input.startsWith('</', pos)) {
+        const end = input.indexOf('>', pos);
+        if (end < 0) throw new Error('unterminated close tag');
+        const name = input.slice(pos + 2, end).trim();
+        if (top === rootWrap || top.name !== name) {
+          throw new Error(`close tag mismatch: </${name}> vs <${top.name}>`);
+        }
+        top.closeRaw = input.slice(pos, end + 1);
+        stack.pop();
+        pos = end + 1;
+      } else {
+        // open tag / self-closing tag
+        const start = pos;
+        pos++;
+        const m = NAME_RE.exec(input.slice(pos));
+        if (!m) throw new Error(`bad tag name at ${pos}`);
+        const node = new XmlNode('elem');
+        node.name = m[0];
+        pos += m[0].length;
+        // attributes
+        for (;;) {
+          while (pos < len && /\s/.test(input[pos])) pos++;
+          if (input[pos] === '>') { pos++; break; }
+          if (input[pos] === '/' && input[pos + 1] === '>') { node.selfClosing = true; pos += 2; break; }
+          const am = NAME_RE.exec(input.slice(pos));
+          if (!am) throw new Error(`bad attribute at ${pos}: ${input.slice(pos, pos + 20)}`);
+          const aname = am[0];
+          pos += aname.length;
+          while (pos < len && /\s/.test(input[pos])) pos++;
+          if (input[pos] !== '=') throw new Error(`attribute without value at ${pos}`);
+          pos++;
+          while (pos < len && /\s/.test(input[pos])) pos++;
+          const q = input[pos];
+          if (q !== '"' && q !== "'") throw new Error(`unquoted attribute at ${pos}`);
+          const vEnd = input.indexOf(q, pos + 1);
+          if (vEnd < 0) throw new Error('unterminated attribute value');
+          node.attrs.push([aname, decodeEntities(input.slice(pos + 1, vEnd))]);
+          pos = vEnd + 1;
+        }
+        node.openRaw = input.slice(start, pos);
+        node.parent = top;
+        top.children.push(node);
+        if (!node.selfClosing) stack.push(node);
+      }
+    } else {
+      const next = input.indexOf('<', pos);
+      const end = next < 0 ? len : next;
+      const n = new XmlNode('text');
+      n.raw = input.slice(pos, end);
+      n.parent = top; top.children.push(n);
+      pos = end;
+    }
+  }
+  if (stack.length !== 1) throw new Error(`unclosed element <${stack[stack.length - 1].name}>`);
+  const rootElems = rootWrap.children.filter((c) => c.type === 'elem');
+  if (rootElems.length !== 1) throw new Error('expected exactly one root element');
+
+  const doc = { decl, root: rootElems[0], wrap: rootWrap };
+
+  // 自检闸门：序列化必须逐字节还原输入
+  const echo = serialize(doc);
+  if (echo !== input) {
+    const at = firstDiff(echo, input);
+    throw new Error(`fidelity self-check failed at byte ${at}: `
+      + JSON.stringify(input.slice(Math.max(0, at - 40), at + 40)));
+  }
+  return doc;
+}
+
+function firstDiff(a, b) {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) if (a[i] !== b[i]) return i;
+  return n;
+}
+
+export function serialize(doc) {
+  let out = doc.decl ?? '';
+  for (const c of doc.wrap.children) out += serializeNode(c);
+  return out;
+}
+
+export function serializeNode(node) {
+  if (node.type === 'text' || node.type === 'comment' || node.type === 'cdata' || node.type === 'decl') {
+    return node.raw ?? '';
+  }
+  // 干净节点：原始片段直出
+  if (!node.dirty && node.openRaw != null) {
+    if (node.selfClosing) return node.openRaw;
+    let out = node.openRaw;
+    for (const c of node.children) out += serializeNode(c);
+    return out + node.closeRaw;
+  }
+  // 脏/新建节点：规范化输出
+  let tag = `<${node.name}`;
+  for (const [k, v] of node.attrs) tag += ` ${k}="${encodeAttr(v)}"`;
+  if (node.children.length === 0) return `${tag}/>`;
+  let out = `${tag}>`;
+  for (const c of node.children) out += serializeNode(c);
+  return `${out}</${node.name}>`;
+}

package/server/lib/docx-pages.js

@@ -0,0 +1,187 @@
+/**
+ * lib/docx-pages.js — .docx 的页图（画布缩略图 + 产物窗翻页都吃这一份）
+ *
+ * ## 一次渲染，全篇入缓存
+ *
+ * LibreOffice 起一次要几百毫秒和一两百 MB，**但它一次就能出整份 PDF** ——
+ * 所以缓存的粒度是「一份文档的所有页」，不是「一页」。打开一份 20 页的文档
+ * 花的是一次渲染，翻页零成本。按页渲染的话翻一页起一次 soffice，1 vCPU 上
+ * 会被翻页操作打死。
+ *
+ * ## 缓存
+ *
+ * `<cacheDir>/<sha1(路径|mtime|size|dpi)>/page-N.png` + `meta.json`。
+ * key 带 mtime + size —— agent 一 rebuild，key 就变，自然重渲，不需要主动失效。
+ * 旧目录留着不清（跟 covers / variants 同口径）。
+ *
+ * ## 并发
+ *
+ * 两道：**同一份文档的并发请求合并成一次渲染**（in-flight 去重，这条最值钱 ——
+ * 一扇窗打开会同时请求首页缩略图和当前页），以及一个总闸。总闸先给宽松值，
+ * 真跑出问题再收 —— 这台机器 1 vCPU / 8G 无 swap，soffice 峰值实测 171MB。
+ */
+
+import path from 'node:path';
+import { platform } from '../runtime/platform.js';
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { renderDocx, cleanupRender } from './docx/render.js';
+
+const CACHE_DIR = path.join(platform.cacheRoot, 'docx-pages');
+
+/** 缓存的渲染精度。缩略图从这份缩，不另跑 LibreOffice */
+const CACHE_DPI = 120;
+
+/**
+ * 渲染管线的"代"。字体替身表换代（2026-08-19 雅黑→MiSans、仿宋→朱雀仿宋）时
+ * 旧缓存的画面已经不是现在会渲出来的样子，但 key 只认 mtime —— 不换代的话
+ * 旧页图会一直供到文档下次被改（cover.js 的 RENDER_GEN 同一课）。
+ */
+const RENDER_GEN = 'fonts-v2';
+
+/** 总并发闸。先宽松，真撞上再收 */
+const MAX_CONCURRENT = 3;
+
+let running = 0;
+const waiters = [];
+async function withSlot(fn) {
+  if (running >= MAX_CONCURRENT) await new Promise((r) => waiters.push(r));
+  running += 1;
+  try { return await fn(); } finally {
+    running -= 1;
+    waiters.shift()?.();
+  }
+}
+
+/** 同一份文档正在渲的那次（key → Promise），合并并发请求 */
+const inflight = new Map();
+
+function keyOf(absPath, stat) {
+  return crypto.createHash('sha1')
+    .update(`${absPath}|${stat.mtimeMs}|${stat.size}|${CACHE_DPI}|${RENDER_GEN}`)
+    .digest('hex');
+}
+
+/**
+ * 确保这份 docx 的所有页图在缓存里。
+ * @returns {Promise<{ dir: string, count: number }>}
+ */
+export async function ensurePages(absPath) {
+  const stat = await fs.stat(absPath);
+  const key = keyOf(absPath, stat);
+  const dir = path.join(CACHE_DIR, key);
+
+  // 已经渲过
+  try {
+    const meta = JSON.parse(await fs.readFile(path.join(dir, 'meta.json'), 'utf8'));
+    if (meta?.count > 0) return { dir, count: meta.count };
+  } catch { /* 没缓存，往下渲 */ }
+
+  if (inflight.has(key)) return inflight.get(key);
+
+  const job = withSlot(async () => {
+    // 拿到槽位之后再查一遍 —— 排队期间别人可能已经渲完了
+    try {
+      const meta = JSON.parse(await fs.readFile(path.join(dir, 'meta.json'), 'utf8'));
+      if (meta?.count > 0) return { dir, count: meta.count };
+    } catch { /* 确实没有 */ }
+
+    const res = await renderDocx(absPath, { pngPages: true, dpi: CACHE_DPI });
+    try {
+      await fs.mkdir(dir, { recursive: true });
+      let n = 0;
+      for (const png of res.pngs) {
+        n += 1;
+        await fs.copyFile(png, path.join(dir, `page-${n}.png`));
+      }
+      // 中间产物 PDF 顺手留下（产物窗的「PDF 视图」直接吃它）——渲染链路本来就
+      // 经过它，扔掉再为 PDF 视图单开一次 soffice 是白烧
+      await fs.copyFile(res.pdf, path.join(dir, 'doc.pdf'));
+      await fs.writeFile(path.join(dir, 'meta.json'), JSON.stringify({ count: n, dpi: CACHE_DPI, ms: res.ms }));
+      return { dir, count: n };
+    } finally {
+      await cleanupRender(res);
+    }
+  }).finally(() => inflight.delete(key));
+
+  inflight.set(key, job);
+  return job;
+}
+
+/**
+ * 取一页的图。
+ * @param {string} absPath  .docx 绝对路径
+ * @param {number} page     1-based
+ * @param {{width?:number}} opts  给了 width 就缩到这个宽度并转 webp（缩略图用）
+ * @returns {Promise<{ buf: Buffer, mime: string, count: number }>}
+ */
+export async function pageImage(absPath, page, opts = {}) {
+  const { dir, count } = await ensurePages(absPath);
+  if (!count) throw Object.assign(new Error('这份文档渲染出来是空的'), { status: 422 });
+  const n = Math.min(Math.max(1, Number(page) || 1), count);
+  const src = path.join(dir, `page-${n}.png`);
+
+  if (!opts.width) {
+    return { buf: await fs.readFile(src), mime: 'image/png', count };
+  }
+  // 缩略图从缓存的大图缩 —— 不为了小一号再起一次 LibreOffice
+  const { default: sharp } = await import('sharp');
+  const buf = await sharp(src).resize({ width: Math.round(opts.width), withoutEnlargement: true })
+    .webp({ quality: 82 }).toBuffer();
+  return { buf, mime: 'image/webp', count };
+}
+
+/** 页数（窗口要用它画翻页控件）。会触发渲染，跟取图共用缓存和闸门 */
+export async function pageCount(absPath) {
+  return (await ensurePages(absPath)).count;
+}
+
+/**
+ * 圈选截图（docx 版，2026-08-19）：用户在产物窗的页图上框了一块 —— 这里没有
+ * DOM 也没有 chromium，"用户所见"就是 LibreOffice 渲的那张页图，所以直接从
+ * 页图缓存裁，跟 region-shot（chromium 版）出同一种规格的 webp。
+ *
+ * @param {string} absPath  .docx 绝对路径
+ * @param {number} page     1-based
+ * @param {{x,y,w,h}} region  坐标基准 = 页图原始像素（CACHE_DPI 下的 PNG，
+ *   前端拿 naturalWidth 换算好再送 —— 服务端不知道用户把图缩放成了多大）
+ * @returns {Promise<{ buf: Buffer, page: number }>}
+ */
+export async function regionShotFromPage(absPath, page, region, { pad = 32, longEdge = 1200 } = {}) {
+  const { dir, count } = await ensurePages(absPath);
+  if (!count) throw Object.assign(new Error('这份文档渲染出来是空的'), { status: 422 });
+  const n = Math.min(Math.max(1, Number(page) || 1), count);
+  const src = path.join(dir, `page-${n}.png`);
+  const { default: sharp } = await import('sharp');
+  const meta = await sharp(src).metadata();
+  const left = Math.max(0, Math.round(region.x) - pad);
+  const top = Math.max(0, Math.round(region.y) - pad);
+  const width = Math.min(meta.width - left, Math.round(region.w) + pad * 2);
+  const height = Math.min(meta.height - top, Math.round(region.h) + pad * 2);
+  if (!(width >= 1) || !(height >= 1)) {
+    throw Object.assign(new Error('圈选区域落在页面之外'), { status: 400 });
+  }
+  const buf = await sharp(src).extract({ left, top, width, height })
+    .resize({ width: longEdge, height: longEdge, fit: 'inside', withoutEnlargement: true })
+    .webp({ quality: 82 }).toBuffer();
+  return { buf, page: n };
+}
+
+/**
+ * 整份 PDF（产物窗「PDF 视图」用，跟着 .docx 的 mtime 走 —— 永不陈旧，这是
+ * 它做成按需视图而不是落盘文件的全部理由）。
+ * @returns {Promise<{ buf: Buffer }>}
+ */
+export async function docPdf(absPath) {
+  const { dir } = await ensurePages(absPath);
+  const p = path.join(dir, 'doc.pdf');
+  try {
+    return { buf: await fs.readFile(p) };
+  } catch { /* 加 PDF 缓存之前渲的旧目录里没有它 → 补一次 */ }
+  const job = withSlot(async () => {
+    const res = await renderDocx(absPath, {});
+    try { await fs.copyFile(res.pdf, p); } finally { await cleanupRender(res); }
+  });
+  await job;
+  return { buf: await fs.readFile(p) };
+}