@xiaobuyu/nodesign 0.0.1

package/server/lib/doc-extract.js

@@ -0,0 +1,156 @@
+/**
+ * lib/doc-extract.js —— 把 Office 文档变成 agent 读得懂的文本。
+ *
+ * 起因：用户往上下文托盘里拖一份 .docx（"照这份需求做一版海报"），agent 拿
+ * Read 一读得到的是二进制乱码 —— **而且它不会报错**，只会当成一份读不懂的
+ * 文件继续往下干，最后交出一个跟需求无关的东西。PDF 不在此列：SDK 的 Read
+ * 原生支持，2026-08-07 真跑验过（暗号字符串原样读回来了）。
+ *
+ * ## 为什么 docx 用库、xlsx/pptx 自己拆
+ *
+ * docx 的正文结构真的复杂（编号、表格、脚注、样式继承），mammoth 是这块
+ * 做得最正的库，没必要重写。
+ *
+ * xlsx 和 pptx 这边，npm 上要么是已经不在公共源上维护的（SheetJS），要么
+ * 拖着 OCR 引擎和整个 pdf.js（officeparser 带 tesseract.js）—— 这台机器
+ * 是 3.8G 的 Spot，底座内存已经按 MB 记着账。而这两种格式要的东西恰好是
+ * OOXML 里最简单的一角：zip 里几个 XML，取 `<t>` 节点的文字。所以这两种
+ * 自己拆，用 fflate（零依赖）解 zip。
+ *
+ * ## 出的是什么
+ *
+ * 纯文本 + 结构记号（工作表名 / 幻灯页号 / 表格行用 tab 分列）。**不做排版
+ * 还原** —— agent 要的是"这份文件说了什么"，版式它自己会重新设计，那本来
+ * 就是它的活。
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/** 认得的扩展名 → 人话名字 */
+export const DOC_KINDS = {
+  '.docx': 'Word 文档',
+  '.xlsx': 'Excel 表格',
+  '.pptx': 'PowerPoint 演示文稿',
+};
+
+/** 单份文件最多抽这么多字符 —— 一本书全塞进上下文没有意义 */
+export const MAX_CHARS = 60_000;
+
+export function isExtractable(p) {
+  return Object.hasOwn(DOC_KINDS, path.extname(String(p || '')).toLowerCase());
+}
+
+/** XML 里取某个标签的全部文字（`<a:t>` / `<w:t>` / `<t>`），按出现顺序 */
+function textsOf(xml, tag) {
+  const out = [];
+  const re = new RegExp(`<(?:\\w+:)?${tag}(?:\\s[^>]*)?>([\\s\\S]*?)</(?:\\w+:)?${tag}>`, 'g');
+  let m;
+  while ((m = re.exec(xml))) out.push(unescapeXml(m[1]));
+  return out;
+}
+
+function unescapeXml(s) {
+  return String(s)
+    .replace(/<[^>]+>/g, '')            // 内嵌标签（<w:tab/> 之类）先去掉
+    .replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
+    .replace(/&amp;/g, '&');            // & 必须最后还原，否则 &amp;lt; 会被解两次
+}
+
+async function unzip(absPath) {
+  const { unzipSync } = await import('fflate');
+  const buf = await fs.readFile(absPath);
+  const files = unzipSync(new Uint8Array(buf));
+  const dec = new TextDecoder('utf-8');
+  return {
+    names: Object.keys(files),
+    read: (name) => (files[name] ? dec.decode(files[name]) : null),
+  };
+}
+
+/** docx —— 交给 mammoth，它把编号、表格、标题都翻对 */
+async function extractDocx(absPath) {
+  const mammoth = (await import('mammoth')).default || (await import('mammoth'));
+  const { value, messages } = await mammoth.extractRawText({ path: absPath });
+  const warn = (messages || []).filter(m => m.type === 'warning').length;
+  return { text: value || '', note: warn ? `${warn} 处格式没能完全还原（不影响正文）` : null };
+}
+
+/**
+ * xlsx —— 共享字符串表 + 每张表的单元格。
+ *
+ * `<c>` 的 `t="s"` 表示值是**共享字符串表的下标**不是字面量，这是 xlsx 里
+ * 最容易搞错的一处：不查表的话整张表会读成一列数字。
+ */
+async function extractXlsx(absPath) {
+  const zip = await unzip(absPath);
+  const shared = textsOf(zip.read('xl/sharedStrings.xml') || '', 'si')
+    .map(s => s.trim());
+
+  // 工作表显示名在 workbook.xml 里，文件名是 sheet1.xml —— 两者顺序对应
+  const wb = zip.read('xl/workbook.xml') || '';
+  const names = [...wb.matchAll(/<(?:\w+:)?sheet\b[^>]*\bname="([^"]*)"/g)].map(m => unescapeXml(m[1]));
+
+  const sheetFiles = zip.names
+    .filter(n => /^xl\/worksheets\/sheet\d+\.xml$/.test(n))
+    .sort((a, b) => (+a.match(/(\d+)/)[1]) - (+b.match(/(\d+)/)[1]));
+
+  const parts = [];
+  sheetFiles.forEach((file, i) => {
+    const xml = zip.read(file) || '';
+    const rows = [];
+    for (const rowXml of xml.split(/<\/(?:\w+:)?row>/)) {
+      const cells = [];
+      const re = /<(?:\w+:)?c\b([^>]*)>([\s\S]*?)<\/(?:\w+:)?c>/g;
+      let m;
+      while ((m = re.exec(rowXml))) {
+        const isShared = /\bt="s"/.test(m[1]);
+        const raw = textsOf(m[2], 'v')[0] ?? textsOf(m[2], 't')[0] ?? '';
+        cells.push(isShared ? (shared[Number(raw)] ?? '') : raw);
+      }
+      if (cells.some(c => c !== '')) rows.push(cells.join('\t'));
+    }
+    if (rows.length) parts.push(`## 工作表：${names[i] || `sheet${i + 1}`}\n${rows.join('\n')}`);
+  });
+  return { text: parts.join('\n\n'), note: parts.length ? null : '表格是空的' };
+}
+
+/** pptx —— 每页一节，取文本框里的文字 */
+async function extractPptx(absPath) {
+  const zip = await unzip(absPath);
+  const slides = zip.names
+    .filter(n => /^ppt\/slides\/slide\d+\.xml$/.test(n))
+    .sort((a, b) => (+a.match(/(\d+)/)[1]) - (+b.match(/(\d+)/)[1]));
+
+  const parts = slides.map((file, i) => {
+    const lines = textsOf(zip.read(file) || '', 't').map(s => s.trim()).filter(Boolean);
+    return `## 第 ${i + 1} 页\n${lines.join('\n') || '(这一页没有文字)'}`;
+  });
+  return { text: parts.join('\n\n'), note: parts.length ? null : '没找到幻灯页' };
+}
+
+/**
+ * 抽一份文档的文本。
+ * @returns {Promise<{ kind, text, chars, truncated, note }>}
+ * @throws 扩展名不认识 / 文件坏了
+ */
+export async function extractDocument(absPath) {
+  const ext = path.extname(absPath).toLowerCase();
+  const kind = DOC_KINDS[ext];
+  if (!kind) {
+    throw Object.assign(new Error(`不支持的格式：${ext || '(无扩展名)'}`), { code: 'UNSUPPORTED' });
+  }
+  const fn = ext === '.docx' ? extractDocx : ext === '.xlsx' ? extractXlsx : extractPptx;
+  const { text, note } = await fn(absPath);
+  const clean = String(text || '').replace(/\r\n/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
+  const truncated = clean.length > MAX_CHARS;
+  return {
+    kind,
+    text: truncated ? clean.slice(0, MAX_CHARS) : clean,
+    chars: clean.length,
+    truncated,
+    note,
+  };
+}

package/server/lib/docx/build-from-source.js

@@ -0,0 +1,260 @@
+/**
+ * build-from-source.js — 「token 源文件 → .docx」这一步。
+ *
+ * ⭐**token JSON 是真相源，.docx 是构建产物。** 所以 agent 改的永远是那份
+ * JSON，不是 docx —— 直接改产物等于让源和产物各说各话，下一次构建就把手改
+ * 的东西抹掉了（这条是 [[nodesign-truth-sources]] 那笔债的预防）。
+ *
+ * 源文件形状：
+ * {
+ *   "preset":  "公文",             // 词典条目名。风格**名字层开放**：这是起点不是牢笼
+ *   "tokens":  { ... },            // 在 preset 之上覆写；不给 preset 时它就是全部
+ *   "content": [ {t:'p', ...} ],   // 正文块
+ *   "header":  "页眉文字",          // 可选
+ *   "footer":  "页脚文字"           // 可选
+ * }
+ *
+ * schema 是**闭合**的：`validateTokens` 见到没登记过的键直接报错。闭合的是
+ * 「哪些问题必须回答」，不是「答案是什么」—— 这跟「不预设范式」不打架。
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { PRESETS, validateTokens, indentConflict, PARA_KEYS, RUN_KEYS } from './tokens.js';
+import { buildDocx } from './build.js';
+import { lintDocxSource } from './text-lint.js';
+
+/** 深合并：对象递归，其余（含数组）整体替换 —— 数组是有序整体，逐项合并只会得到怪东西 */
+function merge(base, over) {
+  if (!over || typeof over !== 'object' || Array.isArray(over)) return over === undefined ? base : over;
+  const out = { ...(base && typeof base === 'object' && !Array.isArray(base) ? base : {}) };
+  for (const [k, v] of Object.entries(over)) out[k] = merge(out[k], v);
+  return out;
+}
+
+export class DocxSourceError extends Error {
+  constructor(message, detail) { super(message); this.detail = detail; }
+}
+
+/**
+ * 递归剥掉 `_` 开头的键 —— 源文件里的行内注释约定。
+ *
+ * 为什么要有：JSON 没有注释语法，而 token 表最需要注释的地方恰恰是**字段旁边**
+ * （`firstLineChars: 200` 边上写一句「= 两字符，随字号缩放」比写在文档里管用
+ * 得多）。闭合 schema 会把这些键当"未登记字段"拒掉，所以在校验前剥干净。
+ *
+ * 顺带：agent 自己写源文件时也能用这个约定给自己留话，下次回来还看得懂。
+ */
+function stripNotes(v) {
+  if (Array.isArray(v)) return v.map(stripNotes);
+  if (v && typeof v === 'object') {
+    return Object.fromEntries(
+      Object.entries(v).filter(([k]) => !k.startsWith('_')).map(([k, x]) => [k, stripNotes(x)]),
+    );
+  }
+  return v;
+}
+
+/**
+ * content 块的闭合校验（2026-08-18）。
+ *
+ * 以前只有 `styles` 那三层查键名，**块级完全不查** —— 于是块上写错的键会被
+ * 静默忽略。最贵的一次是起手模板自己教错：页脚写 `{"para": {align, indent}}`，
+ * 而 buildPara 只读平铺在块上的键，那份页脚的居中**从来没生效过**，而且不报错。
+ *
+ * 「写了没生效」比「写了报错」坏得多：报错你会改，不报错你会以为已经做到了。
+ */
+const P_BLOCK_KEYS = new Set(['t', 'style', 'text', 'runs', 'sizePt', 'list', ...PARA_KEYS]);
+const RUN_OBJ_KEYS = new Set(['text', 'br', 'fld', 'link', ...RUN_KEYS]);
+const TABLE_BLOCK_KEYS = new Set(['t', 'widthsTwip', 'rows']);
+
+/** 超链接目标必须带协议 —— w:hyperlink 走的是 TargetMode="External" 的关系，
+ *  相对路径和 #书签是另外两种机制（后者要 w:anchor），这个引擎不做 */
+const LINK_SCHEME = /^(https?:\/\/|mailto:|tel:)/i;
+
+function validateContent(content, numbering, { noLinks = false } = {}) {
+  const errs = [];
+  const numNames = new Set(Object.keys(numbering ?? {}));
+  const checkList = (list, where) => {
+    if (!list) return;
+    const name = typeof list === 'string' ? list : list.name;
+    if (!name || !numNames.has(name)) {
+      errs.push(`${where}.list: 没有名为 '${name ?? '(未写 name)'}' 的编号定义`
+        + (numNames.size ? `，现有：${[...numNames].join(' / ')}` : '（tokens.numbering 是空的，先定义再引用）'));
+    }
+  };
+  const hint = (k) => (k === 'para'
+    ? '：块级直接格式是**平铺**在块上的，没有 para 包层 —— 写 {"t":"p","align":"center"}，不是 {"para":{"align":"center"}}'
+    : (k === 'border' ? '：键名是复数 borders' : ''));
+
+  const checkPara = (b, where) => {
+    for (const k of Object.keys(b)) {
+      if (!P_BLOCK_KEYS.has(k)) errs.push(`${where}: unknown key ${k}${hint(k)}`);
+    }
+    checkList(b.list, where);
+    const indErr = indentConflict(b.indent);
+    if (indErr) errs.push(`${where}.indent: ${indErr}`);
+    for (const [i, r] of (b.runs ?? []).entries()) {
+      if (typeof r === 'string') continue;
+      if (!r || typeof r !== 'object') { errs.push(`${where}.runs[${i}]: 只能是字符串或对象`); continue; }
+      for (const k of Object.keys(r)) {
+        if (!RUN_OBJ_KEYS.has(k)) errs.push(`${where}.runs[${i}]: unknown key ${k}`);
+      }
+      if (r.link != null) {
+        if (noLinks) {
+          errs.push(`${where}.runs[${i}].link: 页眉页脚里暂不支持超链接（要单独的关系表，还没做）`);
+        } else if (typeof r.link !== 'string' || !LINK_SCHEME.test(r.link)) {
+          errs.push(`${where}.runs[${i}].link: 要带协议的完整地址（https:// / mailto: / tel:），拿到的是 ${JSON.stringify(r.link)}`);
+        } else if (r.text == null) {
+          errs.push(`${where}.runs[${i}].link: 链接要有可点的字 —— link 只能配着 text 用`);
+        }
+      }
+    }
+  };
+
+  for (const [i, b] of content.entries()) {
+    if (!b || typeof b !== 'object') continue;   // t 认不出那条由调用方报，别重复
+    if (b.t === 'p') checkPara(b, `content[${i}]`);
+    else if (b.t === 'table') {
+      for (const k of Object.keys(b)) {
+        if (!TABLE_BLOCK_KEYS.has(k)) errs.push(`content[${i}]: unknown key ${k}${hint(k)}`);
+      }
+      for (const [ri, row] of (b.rows ?? []).entries()) {
+        for (const [ci, cell] of (row ?? []).entries()) {
+          if (cell && typeof cell === 'object') checkPara(cell, `content[${i}].rows[${ri}][${ci}]`);
+        }
+      }
+    }
+  }
+  return errs;
+}
+
+/**
+ * 解析源对象 → { tokens, content, opts }。不碰文件系统，方便单测。
+ */
+export function resolveSource(rawSrc) {
+  if (!rawSrc || typeof rawSrc !== 'object') {
+    throw new DocxSourceError('源文件不是一个 JSON 对象');
+  }
+  const src = stripNotes(rawSrc);
+
+  // 顶层也要闭合（2026-08-18）。以前这里只读认识的几个键，**别的一律静默忽略**
+  // —— 这就是"写了没生效"那个病在最外面一层的版本。写这段注释时我自己刚踩到：
+  // 把 numbering 放在源文件顶层（它其实住在 tokens 里），如果没有这道闸，
+  // 那份编号定义会被安静地丢掉，然后 agent 对着一份没有编号的文档发愁。
+  const SRC_KEYS = new Set(['v', 'preset', 'tokens', 'content', 'header', 'footer']);
+  const strayTop = Object.keys(src).filter(k => !SRC_KEYS.has(k));
+  if (strayTop.length) {
+    throw new DocxSourceError(
+      `源文件顶层有认不出的键：${strayTop.join(', ')}`,
+      `顶层只有这几个：${[...SRC_KEYS].join(' / ')}。`
+      + '排版相关的字段（fonts / base / styles / numbering / page / lang）都住在 tokens 里面，'
+      + '不在顶层。字段全集见 references/token-schema.md。',
+    );
+  }
+
+  let tokens;
+  if (src.preset) {
+    const make = PRESETS[src.preset];
+    if (!make) {
+      throw new DocxSourceError(
+        `没有叫「${src.preset}」的词典条目`,
+        `现有：${Object.keys(PRESETS).join(' / ')}。要别的风格就不写 preset，直接给完整 tokens。`,
+      );
+    }
+    tokens = merge(make(), src.tokens);
+  } else {
+    tokens = src.tokens;
+    if (!tokens) throw new DocxSourceError('既没给 preset 也没给 tokens，不知道按什么排版');
+  }
+
+  const errs = validateTokens(tokens);
+  if (errs.length) {
+    throw new DocxSourceError('token 没过校验', errs.slice(0, 12).join('\n'));
+  }
+
+  const content = src.content;
+  if (!Array.isArray(content) || !content.length) {
+    throw new DocxSourceError('content 是空的，构建出来会是一份白纸');
+  }
+  // 早点把块类型的错说清楚 —— 让它掉进 buildBody 里报 `unknown block: undefined`
+  // 对 agent 是没有信息量的
+  const blockErrs = validateContent(content, tokens.numbering);
+  if (blockErrs.length) {
+    throw new DocxSourceError('content 里有认不出的字段', blockErrs.join('\n'));
+  }
+  const bad = content.findIndex(b => !b || !['p', 'table', 'pageBreak'].includes(b.t));
+  if (bad >= 0) {
+    throw new DocxSourceError(
+      `content[${bad}] 的 t 认不出：${JSON.stringify(content[bad]?.t)}`,
+      "块类型只有三种：{t:'p'} 段落、{t:'table'} 表格、{t:'pageBreak'} 分页。",
+    );
+  }
+
+  // ⚠️ 页眉/页脚以前**完全不过校验** —— 而它恰好是这套校验为之而写的那个 bug 的
+  // 案发现场（起手模板教的 `{"para":{align:'center'}}` 页脚居中从来没生效过）。
+  // content 修好了、页脚照旧静默丢：`{"para":{align:'center'}}` 不报错，生成的
+  // `<w:ftr>` 里根本没有 `<w:pPr>/<w:jc>`。同一份判据必须盖到这两处。
+  const header = hdrFtr(src.header);
+  const footer = hdrFtr(src.footer);
+  for (const [name, blocks] of [['header', header], ['footer', footer]]) {
+    if (!Array.isArray(blocks) || !blocks.length) continue;
+    const errs = validateContent(blocks, tokens.numbering, { noLinks: true });
+    if (errs.length) {
+      throw new DocxSourceError(`${name}（页${name === 'header' ? '眉' : '脚'}）里有认不出的字段`,
+        `${errs.join('\n')}\n（页眉页脚跟 content 里的块是同一套写法：对齐/缩进这些键**平铺在块上**，`
+        + '不要包一层 para。）');
+    }
+  }
+
+  return { tokens, content, opts: { header, footer } };
+}
+
+/**
+ * 页眉页脚两种写法都收：
+ *   "第一页"                     → 一行纯文字（最常见，别逼人写块数组）
+ *   [{t:'p', runs:[..., {fld:'PAGE'}]}]  → 完整块，页码域这类要靠它
+ *
+ * ⚠️ 页码是**域**（`{fld:'PAGE'}`），不是你手写的那个数字 —— 写死 "1" 的页脚
+ * 在第二页还是 1。要真页码就得用块写法。
+ */
+function hdrFtr(v) {
+  if (v == null) return undefined;
+  if (Array.isArray(v)) return v;
+  return [{ t: 'p', style: 'Normal', text: String(v) }];
+}
+
+/**
+ * 读源文件、构建、写产物。
+ * @returns {Promise<{outPath:string, bytes:number, blocks:number, styles:number, preset:string|null}>}
+ */
+export async function buildFromSource(sourceAbsPath, outAbsPath) {
+  let raw;
+  try {
+    raw = await fs.readFile(sourceAbsPath, 'utf8');
+  } catch {
+    throw new DocxSourceError(`读不到源文件：${path.basename(sourceAbsPath)}`);
+  }
+  let src;
+  try {
+    src = JSON.parse(raw);
+  } catch (err) {
+    throw new DocxSourceError('源文件不是合法 JSON', err.message);
+  }
+
+  const { tokens, content, opts } = resolveSource(src);
+  const buf = await buildDocx(tokens, content, opts);
+  await fs.writeFile(outAbsPath, buf);
+  // 构建成功后跑字符/版式体检（text-lint.js）—— 报不挡建：这些是符号惯例与
+  // 一致性问题，闭合 schema 和渲染目视都照不到的那一层
+  let lint = { errors: [], notes: [] };
+  try { lint = lintDocxSource({ tokens, content, opts }); } catch { /* 体检自己不许成为故障源 */ }
+  return {
+    outPath: outAbsPath,
+    bytes: buf.length,
+    blocks: content.length,
+    styles: Object.keys(tokens.styles ?? {}).length,
+    preset: src.preset ?? null,
+    lint,
+  };
+}