@evandu/super-pi 0.1.130 → 0.1.132

package/dist/server/documents.js

@@ -0,0 +1,998 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * The tools the agent sees.
+ *
+ * Duplicated as literals in `agents/super-pi-documents/index.ts`, the way `KNOWLEDGE_TOOL_NAME` is:
+ * the extension runs in Pi's process and cannot import from the server, and a name that exists in
+ * only one of the two places is a name one of them will get wrong.
+ */
+export const DOCUMENT_READ_TOOL_NAME = "document_read";
+export const DOCUMENT_WRITE_TOOL_NAME = "document_write";
+/** The failure of a document that could not be read, in a form a person can act on. */
+export class DocumentError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "DocumentError";
+    }
+}
+/** The extension-to-format map. Kept as a map so the reverse direction (a format's extension) is derivable. */
+const FORMAT_BY_EXTENSION = {
+    ".pdf": "pdf",
+    ".docx": "docx",
+    ".xlsx": "xlsx",
+    ".pptx": "pptx",
+    ".ppt": "ppt",
+};
+/** The extension each format is written with. */
+const EXTENSION_BY_FORMAT = {
+    pdf: ".pdf",
+    docx: ".docx",
+    xlsx: ".xlsx",
+    pptx: ".pptx",
+    ppt: ".ppt",
+};
+/**
+ * Whether an extension names a document this layer can read.
+ *
+ * The name is checked BEFORE the bytes are sniffed, because the caller needs to know whether to
+ * attempt a parse at all - and because a `.pdf` that is really a text file is a different situation
+ * from a file with no extension that happens to be a PDF.
+ */
+export function isDocumentFormat(extension) {
+    return Object.prototype.hasOwnProperty.call(FORMAT_BY_EXTENSION, extension.toLocaleLowerCase());
+}
+/** The format an extension names, or null when it names none. */
+export function documentFormatOf(extension) {
+    return FORMAT_BY_EXTENSION[extension.toLocaleLowerCase()] ?? null;
+}
+/** The extension a format is written with. */
+export function extensionForFormat(format) {
+    return EXTENSION_BY_FORMAT[format];
+}
+/**
+ * The package each format needs, named the way a person would install it.
+ *
+ * These are the names on npm, and they are what the error message tells the person to run.
+ */
+const PACKAGE_BY_FORMAT = {
+    pdf: "pdfjs-dist",
+    docx: "mammoth",
+    xlsx: "exceljs",
+    pptx: "fflate",
+    ppt: "cfb",
+};
+/**
+ * Reads a document's text.
+ *
+ * The file is read here rather than handed in as a buffer because the parsers differ in what they
+ * want: pdfjs wants a path or a typed array, mammoth wants a buffer, exceljs wants a stream or a
+ * buffer. Reading once here keeps that difference from leaking into the callers.
+ */
+export async function extractText(path, format) {
+    const bytes = await readFile(path);
+    return extractTextFromBytes(bytes, format);
+}
+/**
+ * Reads a document's text from bytes already in hand.
+ *
+ * Split out from `extractText` so the parsers can be exercised without touching the filesystem, and
+ * so a caller that already has the bytes (an upload, an API request) does not write them to a
+ * temporary file to read them back.
+ */
+export async function extractTextFromBytes(bytes, format) {
+    if (format === "pdf")
+        return extractPdfText(bytes);
+    if (format === "docx")
+        return extractDocxText(bytes);
+    if (format === "pptx")
+        return extractPptxText(bytes);
+    if (format === "ppt")
+        return extractPptText(bytes);
+    return extractXlsxText(bytes);
+}
+/**
+ * PDF TEXT EXTRACTION.
+ *
+ * WHY THE LEGACY BUILD. pdfjs-dist's default entry is built for a browser and reaches for DOM APIs
+ * that do not exist in Node. The legacy build is the same parser without them, and it is the entry
+ * point that works under plain `node`.
+ */
+async function extractPdfText(bytes) {
+    let pdfjs;
+    try {
+        pdfjs = (await import("pdfjs-dist/legacy/build/pdf.mjs"));
+    }
+    catch (error) {
+        throw new DocumentError("missing_dependency", `读 PDF 需要安装 ${PACKAGE_BY_FORMAT.pdf}（npm install ${PACKAGE_BY_FORMAT.pdf}）`);
+    }
+    let document;
+    try {
+        // The bytes are copied into a fresh Uint8Array because pdfjs takes ownership of the buffer it is
+        // given, and a Buffer that something else still holds would be detached underneath it.
+        //
+        // The COPY IS NOT OPTIONAL. A Node Buffer is a VIEW onto a pooled ArrayBuffer, and the view
+        // usually starts partway into the pool. Handing pdfjs the buffer itself would make it read from
+        // the pool's offset - the wrong bytes, or a truncated file - so the bytes are copied into a
+        // fresh array that starts where it says it does.
+        document = await pdfjs.getDocument({
+            data: new Uint8Array(bytes),
+            // The standard fonts and the CJK character maps live in the package rather than in the
+            // document, and pdfjs will not find them on its own. Without this a PDF that uses a standard
+            // font logs a warning and its text comes out garbled - a document that reads as nonsense
+            // rather than as an error, which is the worst of both.
+            ...(await standardFontPaths()),
+        }).promise;
+    }
+    catch (error) {
+        throw translatePdfError(error);
+    }
+    const pageCount = document.numPages;
+    const pages = [];
+    const warnings = [];
+    for (let page = 1; page <= pageCount; page++) {
+        const content = await document.getPage(page);
+        const textContent = await content.getTextContent();
+        // The text items arrive as positioned runs, not lines. A PDF has no concept of a line: it has
+        // glyphs at coordinates, and reconstructing a line means deciding when the y position changed.
+        // The `hasEOL` flag the parser sets on the last item of a line is that decision, already made.
+        let pageText = "";
+        for (const item of textContent.items) {
+            if (!("str" in item))
+                continue;
+            pageText += item.str;
+            if (item.hasEOL)
+                pageText += "\n";
+            else
+                pageText += " ";
+        }
+        pages.push(pageText);
+    }
+    const text = pages.join("\n\n").replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+    if (!text) {
+        // A PDF WITH NO TEXT LAYER IS A SCAN, NOT AN EMPTY DOCUMENT. It has pages - pdfjs counted them -
+        // and the person needs to be told the difference, because "this document is empty" would send
+        // them looking for content that is there, as pixels.
+        throw new DocumentError("no_text_layer", pageCount > 0
+            ? `这份 PDF 有 ${pageCount} 页但没有文本层（很可能是扫描件）。扫描件需要 OCR，Super Pi 不做 OCR；你可以让 agent 用图片的方式看它。`
+            : "这份 PDF 没有任何可提取的内容。");
+    }
+    if (/\uFFFD/.test(text))
+        warnings.push("PDF 里有一些字符无法解码，可能使用了特殊编码的字体。");
+    return { text, format: "pdf", pages: pageCount, warnings };
+}
+/**
+ * The paths pdfjs needs to find the standard fonts and the character maps.
+ *
+ * WHY THEY ARE RESOLVED RATHER THAN GUESSED. The package's layout differs between the source
+ * checkout and the published tarball, and a hard-coded relative path breaks in one of them - which
+ * is the failure mode that the installed-layout test exists to catch. `import.meta.resolve` asks
+ * Node where the package actually is, so the path is right wherever the code runs.
+ *
+ * THE PATHS ARE PATHS, NOT URLS. pdfjs's Node build reads these files with `fs.readFile(url)` - it
+ * does not go through `fetch` - so a `file://` URL is read as the literal string "file:///F:/...",
+ * which is not a file, and every font load fails. A bare filesystem path is what that reader wants.
+ */
+async function standardFontPaths() {
+    try {
+        const fonts = await import.meta.resolve("pdfjs-dist/package.json");
+        const root = dirname(fileURLToPath(fonts));
+        return {
+            standardFontDataUrl: join(root, "standard_fonts") + "/",
+            cMapUrl: join(root, "cmaps") + "/",
+            cMapPacked: true,
+        };
+    }
+    catch {
+        // WITHOUT THESE PATHS THE PARSE STILL HAPPENS - the fonts are only needed for documents that
+        // use them, and the CJK maps only for CJK documents. A PDF with neither parses fine, so a
+        // failure to locate the package is not a reason to refuse the document.
+        return { cMapPacked: true };
+    }
+}
+/**
+ * The error pdfjs throws for a document it cannot open, translated into a code.
+ *
+ * pdfjs's own errors carry a `name` (`PasswordException`, `InvalidPDFException`, ...), which is
+ * stable across versions in a way its message text is not.
+ */
+function translatePdfError(error) {
+    const name = error?.name ?? "";
+    if (name === "PasswordException")
+        return new DocumentError("encrypted", "这份 PDF 有密码保护，Super Pi 无法读取加密文档。");
+    if (name === "InvalidPDFException" || name === "MissingPDFException")
+        return new DocumentError("corrupt", "这个文件不是有效的 PDF，或者已经损坏。");
+    return new DocumentError("corrupt", `无法解析这个 PDF：${error instanceof Error ? error.message : "未知错误"}`);
+}
+/**
+ * DOCX TEXT EXTRACTION.
+ *
+ * mammoth converts the document to HTML, which preserves the STRUCTURE - headings stay headings,
+ * lists stay lists, tables stay tables - and the HTML is then flattened to text.
+ */
+async function extractDocxText(bytes) {
+    let mammoth;
+    try {
+        mammoth = (await import("mammoth"));
+    }
+    catch {
+        throw new DocumentError("missing_dependency", `读 Word 文档需要安装 ${PACKAGE_BY_FORMAT.docx}（npm install ${PACKAGE_BY_FORMAT.docx}）`);
+    }
+    let result;
+    try {
+        result = await mammoth.extractRawText({ buffer: bytes });
+    }
+    catch (error) {
+        throw new DocumentError("corrupt", `无法解析这个 Word 文档：${error instanceof Error ? error.message : "未知错误"}`);
+    }
+    const text = result.value.replace(/\n{3,}/g, "\n\n").trim();
+    if (!text)
+        throw new DocumentError("empty", "这个 Word 文档里没有可提取的文字。");
+    const warnings = [];
+    // mammoth reports what it had to drop. Those messages are the only warning a caller will get about
+    // a lost image or an unsupported element, so they are passed through rather than discarded.
+    for (const message of result.messages ?? []) {
+        if (message.type === "warning")
+            warnings.push(`Word 转换提示：${message.message}`);
+    }
+    if (warnings.length === 0)
+        warnings.push("Word 文档里的图片不会转成文字；表格被拍平成一行行文本。");
+    return { text, format: "docx", warnings };
+}
+/**
+ * XLSX TEXT EXTRACTION.
+ *
+ * A spreadsheet is read as a table and written out as CSV, with every sheet in the workbook present
+ * and headed by its name. The alternative - one flat list of all the cells - loses which sheet a
+ * number came from, and a row of numbers without its sheet is not a fact.
+ */
+async function extractXlsxText(bytes) {
+    let ExcelJS;
+    try {
+        ExcelJS = (await import("exceljs"));
+    }
+    catch {
+        throw new DocumentError("missing_dependency", `读 Excel 需要安装 ${PACKAGE_BY_FORMAT.xlsx}（npm install ${PACKAGE_BY_FORMAT.xlsx}）`);
+    }
+    const workbook = new ExcelJS.default.Workbook();
+    try {
+        await workbook.xlsx.load(bytes);
+    }
+    catch (error) {
+        throw new DocumentError("corrupt", `无法解析这个 Excel 文件：${error instanceof Error ? error.message : "未知错误"}`);
+    }
+    const sections = [];
+    for (const sheet of workbook.worksheets) {
+        const rows = [];
+        for (let index = 1; index <= sheet.rowCount; index++) {
+            const values = sheet.getRow(index).values;
+            // exceljs's row values are 1-INDEXED, with a hole at 0. Dropping the hole is what makes the
+            // CSV columns line up with what a person sees in the spreadsheet.
+            const cells = values.slice(1).map(cell => {
+                if (cell === null || cell === undefined)
+                    return "";
+                if (cell instanceof Date)
+                    return cell.toISOString();
+                if (typeof cell === "object") {
+                    const rich = cell;
+                    if (rich.hyperlink)
+                        return rich.text ?? rich.hyperlink;
+                    if (rich.text !== undefined)
+                        return rich.text;
+                    if (rich.result !== undefined)
+                        return String(rich.result);
+                    return "";
+                }
+                return String(cell);
+            });
+            while (cells.length && cells[cells.length - 1] === "")
+                cells.pop();
+            if (cells.length)
+                rows.push(cells.map(escapeCsvCell).join(","));
+        }
+        if (!rows.length)
+            continue;
+        sections.push(`# 工作表：${sheet.name}\n${rows.join("\n")}`);
+    }
+    const text = sections.join("\n\n").trim();
+    if (!text)
+        throw new DocumentError("empty", "这个 Excel 文件里没有可提取的数据。");
+    return { text, format: "xlsx", warnings: ["Excel 的公式保留的是计算结果；图表、格式和单元格样式不会出现在文本里。"] };
+}
+/** A CSV cell that contains a comma, a quote or a newline has to be quoted, and the quotes doubled. */
+function escapeCsvCell(value) {
+    if (!/[",\n\r]/.test(value))
+        return value;
+    return `"${value.replaceAll('"', '""')}"`;
+}
+/**
+ * Builds a document's bytes.
+ *
+ * The output is a REAL document - it opens in Word, Excel and a PDF reader - not a renamed text
+ * file. The structure is simple on purpose: headings, paragraphs, lists and tables for Word;
+ * sheets of cells for Excel; lines of text for a PDF.
+ */
+export async function buildDocument(spec) {
+    if (spec.format === "docx")
+        return { bytes: await buildDocx(spec), format: "docx" };
+    if (spec.format === "xlsx")
+        return { bytes: await buildXlsx(spec), format: "xlsx" };
+    if (spec.format === "pptx")
+        return { bytes: await buildPptx(spec), format: "pptx" };
+    // THE LEGACY BINARY FORMAT HAS NO WRITER, and this guard is what keeps the fall-through from
+    // quietly producing a PDF inside a .ppt file.
+    if (spec.format === "ppt")
+        throw new DocumentError("unsupported", "旧版 .ppt 只支持读取，不支持生成；请写成 .pptx。");
+    return { bytes: await buildPdf(spec), format: "pdf" };
+}
+/** Splits Markdown into the blocks a document is built from. Exported for the tests to exercise directly. */
+export function parseMarkdownBlocks(markdown) {
+    const blocks = [];
+    const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+    let index = 0;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (!line.trim()) {
+            index++;
+            continue;
+        }
+        // A FENCE IS A UNIT. The block between the fences is code, and it is not scanned for headings or
+        // list markers - a `#` inside a shell script is a comment, not a heading.
+        if (/^\s*(```|~~~)/.test(line)) {
+            const fence = /^\s*(```|~~~)/.exec(line)[1];
+            const body = [];
+            index++;
+            while (index < lines.length && !lines[index].trim().startsWith(fence)) {
+                body.push(lines[index]);
+                index++;
+            }
+            index++;
+            blocks.push({ kind: "code", text: body.join("\n") });
+            continue;
+        }
+        const heading = /^(#{1,6})\s+(.*\S)\s*$/.exec(line);
+        if (heading) {
+            blocks.push({ kind: "heading", level: heading[1].length, text: heading[2] });
+            index++;
+            continue;
+        }
+        // A TABLE IS A UNIT TOO. A pipe-separated line followed by a separator line is a table, and the
+        // rows after it belong to it however many there are.
+        if (line.includes("|") && /^\s*\|?[\s:|-]+\|[\s:|-]*$/.test(lines[index + 1] ?? "")) {
+            const header = splitTableRow(line);
+            const rows = [];
+            index += 2;
+            while (index < lines.length && lines[index].includes("|") && lines[index].trim()) {
+                rows.push(splitTableRow(lines[index]));
+                index++;
+            }
+            blocks.push({ kind: "table", header, rows });
+            continue;
+        }
+        if (/^\s*([-*+]|\d+[.)])\s+/.test(line)) {
+            const items = [];
+            while (index < lines.length && /^\s*([-*+]|\d+[.)])\s+/.test(lines[index])) {
+                items.push(lines[index].replace(/^\s*([-*+]|\d+[.)])\s+/, ""));
+                index++;
+            }
+            blocks.push({ kind: "list", items });
+            continue;
+        }
+        const paragraph = [];
+        // THE PARAGRAPH ENDS WHERE THE NEXT BLOCK BEGINS, and the block starts it must recognize are the
+        // SAME ones the outer loop recognizes - heading, list item, AND now fence and table. A fence or a
+        // table that follows a line of prose (no blank line between) is still a fence or a table:
+        // CommonMark allows a fence to interrupt a paragraph, and the module's own rule is "a fence is a
+        // unit". The terminator used to check only headings and list items, so the fence - markers
+        // included - was swallowed into the paragraph text and reached buildDocx/buildPdf/buildPptx as
+        // literal ``` and | characters (measured by scripts/document-block-parse.test.mjs).
+        while (index < lines.length && lines[index].trim() && !/^(#{1,6})\s/.test(lines[index]) && !/^\s*([-*+]|\d+[.)])\s+/.test(lines[index]) && !/^\s*(```|~~~)/.test(lines[index]) && !(lines[index].includes("|") && /^\s*\|?[\s:|-]+\|[\s:|-]*$/.test(lines[index + 1] ?? ""))) {
+            paragraph.push(lines[index]);
+            index++;
+        }
+        blocks.push({ kind: "paragraph", text: paragraph.join("\n") });
+    }
+    return blocks;
+}
+/** Splits one pipe-separated table row into its cells, dropping the empty edge cells a leading or trailing pipe creates. */
+function splitTableRow(line) {
+    const trimmed = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+    return trimmed.split("|").map(cell => cell.trim());
+}
+/** Builds a Word document from Markdown. */
+async function buildDocx(spec) {
+    let docx;
+    try {
+        docx = (await import("docx"));
+    }
+    catch {
+        throw new DocumentError("missing_dependency", `写 Word 文档需要安装 docx（npm install docx）`);
+    }
+    const children = [];
+    if (spec.title)
+        children.push(new docx.Paragraph({ children: [new docx.TextRun({ text: spec.title, bold: true, size: 32 })] }));
+    for (const block of parseMarkdownBlocks(spec.content)) {
+        if (block.kind === "heading") {
+            const level = Math.min(Math.max(block.level, 1), 6);
+            children.push(new docx.Paragraph({ heading: docx.HeadingLevel[`HEADING_${level}`], children: [new docx.TextRun({ text: block.text })] }));
+            continue;
+        }
+        if (block.kind === "paragraph") {
+            children.push(new docx.Paragraph({ children: [new docx.TextRun({ text: block.text })] }));
+            continue;
+        }
+        if (block.kind === "list") {
+            for (const item of block.items)
+                children.push(new docx.Paragraph({ bullet: { level: 0 }, children: [new docx.TextRun({ text: item })] }));
+            continue;
+        }
+        if (block.kind === "code") {
+            for (const line of block.text.split("\n"))
+                children.push(new docx.Paragraph({ children: [new docx.TextRun({ text: line, font: "Courier New" })] }));
+            continue;
+        }
+        // A table becomes a real Word table. The header row is bold, and the column count is the widest
+        // row's, so a ragged table does not lose a cell.
+        const width = Math.max(block.header.length, ...block.rows.map(row => row.length), 1);
+        const border = { style: docx.BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
+        const borders = { top: border, bottom: border, left: border, right: border };
+        const row = (cells, bold) => new docx.TableRow({
+            children: Array.from({ length: width }, (_, cell) => new docx.TableCell({
+                borders,
+                children: [new docx.Paragraph({ children: [new docx.TextRun({ text: cells[cell] ?? "", bold })] })],
+            })),
+        });
+        children.push(new docx.Table({
+            width: { size: 100, type: docx.WidthType.PERCENTAGE },
+            rows: [row(block.header, true), ...block.rows.map(cells => row(cells, false))],
+        }));
+    }
+    const document = new docx.Document({ sections: [{ children }] });
+    return docx.Packer.toBuffer(document);
+}
+/** Builds an Excel workbook from CSV. */
+async function buildXlsx(spec) {
+    let ExcelJS;
+    try {
+        ExcelJS = (await import("exceljs"));
+    }
+    catch {
+        throw new DocumentError("missing_dependency", `写 Excel 需要安装 exceljs（npm install exceljs）`);
+    }
+    const workbook = new ExcelJS.default.Workbook();
+    // A SHEET PER SECTION. The content is CSV, and a CSV cannot hold more than one table - so the
+    // sections are separated by a sheet marker and each becomes its own sheet.
+    const sections = splitCsvSections(spec.content);
+    for (const section of sections) {
+        const sheet = workbook.addWorksheet(section.name);
+        for (const row of section.rows)
+            sheet.addRow(row);
+    }
+    const buffer = await workbook.xlsx.writeBuffer();
+    return Buffer.from(buffer);
+}
+/**
+ * Splits a CSV document into sheets.
+ *
+ * The separator is a line naming the sheet: `## Sheet name`. A CSV with no separator is one sheet,
+ * named after the document's title.
+ */
+function splitCsvSections(content, fallbackName = "Sheet1") {
+    const lines = content.replace(/\r\n/g, "\n").split("\n");
+    const sections = [];
+    let name = fallbackName;
+    let rows = [];
+    const flush = () => {
+        if (rows.length)
+            sections.push({ name, rows });
+        rows = [];
+    };
+    for (const line of lines) {
+        const marker = /^##\s+(.*\S)\s*$/.exec(line);
+        if (marker) {
+            flush();
+            name = marker[1];
+            continue;
+        }
+        if (!line.trim())
+            continue;
+        rows.push(parseCsvRow(line));
+    }
+    flush();
+    if (!sections.length)
+        sections.push({ name: fallbackName, rows: [] });
+    return sections;
+}
+/** Parses one CSV line into its cells, honouring the doubled-quote escape. */
+function parseCsvRow(line) {
+    const cells = [];
+    let current = "";
+    let quoted = false;
+    for (let index = 0; index < line.length; index++) {
+        const character = line[index];
+        if (quoted) {
+            if (character === '"') {
+                if (line[index + 1] === '"') {
+                    current += '"';
+                    index++;
+                }
+                else
+                    quoted = false;
+            }
+            else
+                current += character;
+            continue;
+        }
+        if (character === '"') {
+            quoted = true;
+            continue;
+        }
+        if (character === ",") {
+            cells.push(current);
+            current = "";
+            continue;
+        }
+        current += character;
+    }
+    cells.push(current);
+    return cells;
+}
+/**
+ * Builds a PDF.
+ *
+ * WHY PDFKIT AND NOT PDF-LIB. Two reasons, both about Chinese. The PDF standard fonts pdf-lib
+ * embeds are WinAnsi only - they have no Chinese characters at all, so a Chinese PDF came out as a
+ * document full of replacement characters, which is worse than no PDF. And pdfkit is built on
+ * fontkit, which does three things pdf-lib does not: it embeds a real CJK font, it subsets that
+ * font to the glyphs actually used (so a one-page Chinese note does not carry a multi-megabyte
+ * font), and it wraps lines the way CJK text needs - by character, since Chinese has no spaces.
+ * Hand-rolling any of those three was the alternative, and all three are exactly the kind of thing
+ * that looks done and fails on someone else's document.
+ *
+ * THE FONT FILES SHIP IN THE PACKAGE, at `assets/fonts/`, under the SIL Open Font License - the
+ * same arrangement as the knowledge base's embedding weights: no download, no network, present
+ * after `npm install`. They are loaded only when the text actually contains CJK, so an English PDF
+ * still uses the PDF standard fonts and stays tiny.
+ */
+async function buildPdf(spec) {
+    if (!spec.content.trim() && !spec.title?.trim())
+        throw new DocumentError("empty", "文档内容为空。");
+    let PDFDocument;
+    try {
+        PDFDocument = (await import("pdfkit")).default;
+    }
+    catch {
+        throw new DocumentError("missing_dependency", "生成 PDF 需要安装 pdfkit（npm install pdfkit）");
+    }
+    const hasCjk = containsCjk(spec.content) || containsCjk(spec.title ?? "");
+    const doc = new PDFDocument({ size: "A4", margins: { top: 56, bottom: 56, left: 56, right: 56 } });
+    const chunks = [];
+    doc.on("data", (chunk) => { if (chunk)
+        chunks.push(chunk); });
+    const finished = new Promise((resolve) => doc.on("end", () => resolve()));
+    let boldCjkAvailable = false;
+    if (hasCjk) {
+        const regular = cjkFontPath("NotoSansSC-Regular.otf");
+        if (!regular) {
+            // REFUSED, NOT DRAWN AS BOXES. A PDF without the glyphs is a file that looks produced and
+            // reads as garbage; the person finds out only after opening it. Saying what is missing is
+            // the only honest output here.
+            throw new DocumentError("missing_asset", "生成中文 PDF 需要 Noto Sans SC 字体（应随 Super Pi 一起安装在 assets/fonts/ 下）。文件缺失时请重新安装 Super Pi。");
+        }
+        doc.registerFont("CJK", regular);
+        const bold = cjkFontPath("NotoSansSC-Bold.otf");
+        if (bold) {
+            doc.registerFont("CJKBold", bold);
+            boldCjkAvailable = true;
+        }
+    }
+    // ONE FONT DECISION FOR THE WHOLE DOCUMENT. A CJK font carries Latin glyphs too, so a mixed
+    // Chinese-and-English document uses it throughout rather than switching fonts mid-line - which
+    // is also what keeps line wrapping uniform.
+    const font = (boldWanted) => {
+        if (!hasCjk)
+            return boldWanted ? "Helvetica-Bold" : "Helvetica";
+        return boldWanted && boldCjkAvailable ? "CJKBold" : "CJK";
+    };
+    const say = (text, options = { size: 11 }) => {
+        if (!text)
+            return;
+        doc.font(font(options.bold ?? false));
+        doc.fontSize(options.size);
+        doc.text(text);
+    };
+    if (spec.title) {
+        say(spec.title, { bold: true, size: 18 });
+        doc.moveDown(1);
+    }
+    for (const block of parseMarkdownBlocks(spec.content)) {
+        if (block.kind === "heading") {
+            say(block.text, { bold: true, size: block.level <= 2 ? 15 : 12.5 });
+            doc.moveDown(0.5);
+            continue;
+        }
+        if (block.kind === "paragraph") {
+            say(block.text);
+            doc.moveDown(0.75);
+            continue;
+        }
+        if (block.kind === "list") {
+            for (const item of block.items)
+                say(`• ${item}`);
+            doc.moveDown(0.75);
+            continue;
+        }
+        if (block.kind === "code") {
+            for (const line of block.text.split("\n"))
+                say(line, { size: 9.5 });
+            doc.moveDown(0.75);
+            continue;
+        }
+        for (const row of [block.header, ...block.rows])
+            say(row.join("  |  "), { size: 10 });
+        doc.moveDown(0.75);
+    }
+    doc.end();
+    await finished;
+    return Buffer.concat(chunks);
+}
+/**
+ * Where a shipped font lives, or null when it is missing.
+ *
+ * Resolved from `import.meta.dirname` the way the extension paths are: two `..` segments reach the
+ * package root both after `tsc -b` (dist/server/) and under `tsx watch` (src/server/).
+ */
+function cjkFontPath(fileName) {
+    try {
+        const path = resolve(import.meta.dirname, "../../assets/fonts", fileName);
+        return existsSync(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether a string contains a character the PDF standard fonts cannot represent. */
+function containsCjk(text) {
+    return /[\u2e80-\u9fff\uf900-\ufaff\uff00-\uffef]/.test(text);
+}
+/**
+ * PPTX TEXT EXTRACTION.
+ *
+ * A `.pptx` is a zip of XML parts. The slide ORDER comes from the presentation's slide list mapped
+ * through its relationships - the file names `slide1.xml`, `slide2.xml` are not the display order,
+ * and a deck reordered in PowerPoint is exactly where the numeric sort lies. Titles are picked out
+ * by the shape's placeholder type, which is how PowerPoint itself knows what a title is; the title
+ * becomes a Markdown heading, which is what the knowledge base's chunker treats as a section
+ * boundary, so a deck imported into the knowledge base chunks per slide rather than as one block.
+ */
+async function extractPptxText(bytes) {
+    let fflate;
+    try {
+        fflate = (await import("fflate"));
+    }
+    catch {
+        throw new DocumentError("missing_dependency", `读 PowerPoint 需要 ${PACKAGE_BY_FORMAT.pptx}（npm install ${PACKAGE_BY_FORMAT.pptx}）`);
+    }
+    let files;
+    try {
+        files = fflate.unzipSync(new Uint8Array(bytes));
+    }
+    catch {
+        throw new DocumentError("corrupt", "这个文件不是有效的 PowerPoint 文件（无法解压）。");
+    }
+    const decoder = new TextDecoder("utf8");
+    const readEntry = (name) => {
+        const data = files[name];
+        return data ? decoder.decode(data) : null;
+    };
+    const order = [];
+    const presentationXml = readEntry("ppt/presentation.xml");
+    if (presentationXml) {
+        const relationships = new Map();
+        const relsXml = readEntry("ppt/_rels/presentation.xml.rels");
+        if (relsXml) {
+            for (const match of relsXml.matchAll(/<Relationship\b[^>]*>/g)) {
+                const id = /\bId="([^"]+)"/.exec(match[0])?.[1];
+                const target = /\bTarget="([^"]+)"/.exec(match[0])?.[1];
+                if (id && target)
+                    relationships.set(id, target);
+            }
+        }
+        for (const match of presentationXml.matchAll(/<p:sldId\b[^>]*r:id="([^"]+)"/g)) {
+            const target = relationships.get(match[1]);
+            if (!target || !target.endsWith(".xml"))
+                continue;
+            // A rel target is relative to ppt/ (`slides/slide1.xml`) or to the package root (`/ppt/...`);
+            // both are normalised to the part name the zip uses.
+            order.push(target.replace(/^\/+/, "").replace(/^ppt\/ppt\//, "ppt/").startsWith("ppt/") ? target.replace(/^\/+/, "").replace(/^ppt\/ppt\//, "ppt/") : `ppt/${target.replace(/^\/+/, "")}`);
+        }
+    }
+    if (!order.length) {
+        // No slide list to trust (or none present): fall back to the numeric order of the files. This
+        // is the approximation, not the rule - the relationship map above is what usually runs.
+        order.push(...Object.keys(files)
+            .filter(name => /^ppt\/slides\/slide\d+\.xml$/.test(name))
+            .sort((a, b) => slideIndexOf(a) - slideIndexOf(b)));
+    }
+    if (!order.length)
+        throw new DocumentError("corrupt", "这个 PowerPoint 文件里没有幻灯片。");
+    const sections = [];
+    for (const slidePath of order) {
+        const xml = readEntry(slidePath);
+        if (!xml)
+            continue;
+        const slide = slideText(xml);
+        const lines = [];
+        if (slide.title)
+            lines.push(`# ${slide.title}`);
+        lines.push(...slide.lines);
+        const notes = slideNotes(files, slidePath, decoder);
+        if (notes)
+            lines.push(`备注：${notes.replace(/\n+/g, " ")}`);
+        if (lines.length)
+            sections.push(lines.join("\n"));
+    }
+    const text = sections.join("\n\n").trim();
+    if (!text) {
+        throw new DocumentError("empty", "这个 PPT 里没有可提取的文字（可能整份都是图片）。图形、SmartArt 和图表里的文字不在提取范围内。");
+    }
+    return { text, format: "pptx", warnings: ["图形、SmartArt 和图表里的文字不在提取范围内；版式、配色和动画不保留。"] };
+}
+/** A slide's text: its title (from the title placeholder) and every other paragraph and table row. */
+function slideText(xml) {
+    let title = "";
+    const lines = [];
+    for (const shape of xml.match(/<p:sp>[\s\S]*?<\/p:sp>/g) ?? []) {
+        const isTitle = /<p:ph[^>]*type="(?:ctrTitle|title)"/.test(shape);
+        for (const paragraph of shape.match(/<a:p\/>|<a:p>[\s\S]*?<\/a:p>/g) ?? []) {
+            const text = [...paragraph.matchAll(/<a:t>([\s\S]*?)<\/a:t>/g)].map(run => unescapeXml(run[1])).join("");
+            if (!text.trim())
+                continue;
+            if (isTitle && !title)
+                title = text.trim();
+            else
+                lines.push(text);
+        }
+    }
+    // TABLES LIVE IN graphicFrame, NOT in p:sp, so the shape pass never sees them. Each row becomes
+    // a pipe-joined line - the same flattening the Word and Excel extractors do and warn about.
+    for (const table of xml.match(/<a:tbl>[\s\S]*?<\/a:tbl>/g) ?? []) {
+        for (const row of table.match(/<a:tr[\s\S]*?<\/a:tr>/g) ?? []) {
+            const cells = [...row.matchAll(/<a:tc[\s\S]*?<\/a:tc>/g)]
+                .map(cell => [...cell[0].matchAll(/<a:t>([\s\S]*?)<\/a:t>/g)].map(run => unescapeXml(run[1])).join("").trim());
+            if (cells.some(cell => cell))
+                lines.push(cells.join(" | "));
+        }
+    }
+    return { title, lines };
+}
+/** The speaker notes one slide points at, resolved through the slide's own relationships. */
+function slideNotes(files, slidePath, decoder) {
+    const directory = slidePath.replace(/\/[^/]+$/, "");
+    const name = slidePath.split("/").pop() ?? "";
+    const relsXml = files[`${directory}/_rels/${name}.rels`];
+    if (!relsXml)
+        return null;
+    for (const match of decoder.decode(relsXml).matchAll(/<Relationship\b[^>]*>/g)) {
+        const target = /\bTarget="([^"]+)"/.exec(match[0])?.[1];
+        if (!target?.includes("notesSlide"))
+            continue;
+        const notesPath = target.replace(/^\/+/, "").replace(/^\.\.\//, "ppt/");
+        const data = files[notesPath];
+        if (!data)
+            continue;
+        // ONLY THE BODY PLACEHOLDER IS THE NOTE. A notes slide also carries the slide-number
+        // placeholder, and a writer that creates empty notes pages (pptxgenjs does, for every slide)
+        // puts the slide's ordinal in it - without this filter every slide would grow a bogus
+        // 「备注：2」 line that is the page number, not what anyone said.
+        const xml = decoder.decode(data);
+        const lines = [];
+        for (const shape of xml.match(/<p:sp>[\s\S]*?<\/p:sp>/g) ?? []) {
+            if (!/<p:ph[^>]*type="body"/.test(shape))
+                continue;
+            for (const paragraph of shape.match(/<a:p\/>|<a:p>[\s\S]*?<\/a:p>/g) ?? []) {
+                const text = [...paragraph.matchAll(/<a:t>([\s\S]*?)<\/a:t>/g)].map(run => unescapeXml(run[1])).join("");
+                if (text.trim())
+                    lines.push(text);
+            }
+        }
+        const text = lines.join("\n").trim();
+        if (text)
+            return text;
+    }
+    return null;
+}
+/** Turns the XML entities a text run may carry back into characters. `&amp;` is decoded LAST, so an escaped `&lt;` stays literal. */
+function unescapeXml(text) {
+    return text
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+        .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number(dec)))
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&");
+}
+/** A slide file's numeric index, for the fallback ordering. */
+function slideIndexOf(path) {
+    return Number(/slide(\d+)\.xml$/.exec(path)?.[1] ?? 0);
+}
+/**
+ * LEGACY .PPT TEXT EXTRACTION.
+ *
+ * A PowerPoint 97 file is an OLE compound file whose "PowerPoint Document" stream holds a tree of
+ * binary records; the text lives in TextCharsAtom (UTF-16) and TextBytesAtom (ANSI) records at
+ * varying nesting depths. The walk descends into containers and collects every text atom in stream
+ * order - which is the slide order, because PowerPoint writes them that way - but the format
+ * promises no headings, so the output is flat lines.
+ */
+async function extractPptText(bytes) {
+    let CFB;
+    try {
+        CFB = (await import("cfb"));
+    }
+    catch {
+        throw new DocumentError("missing_dependency", `读旧版 PPT 需要 ${PACKAGE_BY_FORMAT.ppt}（npm install ${PACKAGE_BY_FORMAT.ppt}）`);
+    }
+    let container;
+    try {
+        container = CFB.read(new Uint8Array(bytes), { type: "buffer" });
+    }
+    catch {
+        throw new DocumentError("corrupt", "这个文件不是有效的 PowerPoint 文件。");
+    }
+    const entry = CFB.find(container, "PowerPoint Document");
+    if (!entry?.content)
+        throw new DocumentError("corrupt", "这个文件不是有效的 PowerPoint 文件。");
+    const stream = Buffer.from(entry.content);
+    const pieces = [];
+    walkPptRecords(stream, (type, body) => {
+        if (type === PPT_TEXT_CHARS_ATOM)
+            pieces.push(body.toString("utf16le"));
+        else if (type === PPT_TEXT_BYTES_ATOM)
+            pieces.push(body.toString("latin1"));
+    });
+    const text = pieces.join("\n").replace(/\r\n?/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+    if (!text)
+        throw new DocumentError("empty", "这个 PPT 文件里没有可提取的文字。");
+    return { text, format: "ppt", warnings: ["旧版 .ppt 按文件内的出现顺序提取文字，不分页、不区分标题和正文；图片和版式不保留。另存为 .pptx 可以得到更好的效果。"] };
+}
+const PPT_TEXT_CHARS_ATOM = 0x0fa0;
+const PPT_TEXT_BYTES_ATOM = 0x0fa8;
+/**
+ * Walks a PowerPoint record stream, descending into containers.
+ *
+ * THE CONTAINER RULE IS IN THE HEADER'S LOW NIBBLE, NOT THE TYPE: a record's first short packs a
+ * version into the low 4 bits, and version 0xF marks a container whose body is more records.
+ * A truncated or lying length stops the walk rather than reading past the buffer.
+ */
+function walkPptRecords(stream, visit) {
+    const walk = (start, end) => {
+        let position = start;
+        while (position + 8 <= end) {
+            const version = stream.readUInt16LE(position) & 0x0f;
+            const type = stream.readUInt16LE(position + 2);
+            const length = stream.readUInt32LE(position + 4);
+            const bodyStart = position + 8;
+            if (bodyStart + length > end)
+                return;
+            if (version === 0x0f)
+                walk(bodyStart, bodyStart + length);
+            else
+                visit(type, stream.subarray(bodyStart, bodyStart + length));
+            position = bodyStart + length;
+        }
+    };
+    walk(0, stream.length);
+}
+/**
+ * Builds a PowerPoint deck from Markdown.
+ *
+ * THE MAPPING, stated once: a first- or second-level heading starts a new slide (its text is the
+ * slide title); everything between headings is that slide's body - paragraphs, bullets, code lines
+ * and pipe-joined table rows. A title with no slide bodies still produces its title slide.
+ *
+ * THE CANVAS IS SET EXPLICITLY, and that is not a detail. pptxgenjs DEFAULTS to a 10 × 5.625 inch
+ * canvas, and a deck laid out on that canvas while its type sizes assume a 13.33 × 7.5 one comes out
+ * systematically wrong - a body box that ends 1.2 inches below the slide edge silently loses the
+ * text that falls there, with no error anywhere. `LAYOUT_WIDE` is the 13.33 × 7.5 canvas that the
+ * sizes below are written for.
+ *
+ * THE FONT IS NAMED, and for CJK it is named as 微软雅黑 - a face the VIEWER's PowerPoint actually
+ * ships. This is the opposite of the PDF's rule, and the reason is the mechanism: a PDF EMBEDS its
+ * fonts, so a build machine's font is safe there, while a `.pptx` only stores the font's NAME and
+ * the user's PowerPoint resolves it. A name that exists only on the build machine (Noto Sans SC
+ * among them) silently substitutes on the user's machine, which is why the PDF font is not reused
+ * here. pptxgenjs writes the name into `<a:latin>`, `<a:ea>` and `<a:cs>` alike, so the Chinese
+ * glyphs get it too and not just the Latin ones.
+ */
+async function buildPptx(spec) {
+    let PptxGenJS;
+    try {
+        PptxGenJS = (await import("pptxgenjs")).default;
+    }
+    catch {
+        throw new DocumentError("missing_dependency", "写 PowerPoint 需要 pptxgenjs（npm install pptxgenjs）");
+    }
+    const blocks = parseMarkdownBlocks(spec.content);
+    if (!blocks.length && !spec.title?.trim())
+        throw new DocumentError("empty", "PPT 内容为空。");
+    const pptx = new PptxGenJS();
+    pptx.layout = "LAYOUT_WIDE";
+    if (spec.title)
+        pptx.title = spec.title;
+    const slides = [];
+    let current = null;
+    const start = (title) => {
+        current = { title, runs: [] };
+        slides.push(current);
+        return current;
+    };
+    for (const block of blocks) {
+        if (block.kind === "heading" && block.level <= 2) {
+            start(block.text);
+            continue;
+        }
+        current ??= start();
+        if (block.kind === "paragraph")
+            current.runs.push({ text: block.text, options: { breakLine: true } });
+        else if (block.kind === "list") {
+            for (const item of block.items) {
+                // A REAL BULLET, not a literal "- " in the text: `bullet` is a paragraph property, and a
+                // dash typed into the text is a dash, not a bullet.
+                current.runs.push({ text: item, options: { bullet: { code: "2022", indent: 14 }, breakLine: true } });
+            }
+        }
+        else if (block.kind === "code") {
+            for (const line of block.text.split("\n"))
+                current.runs.push({ text: line, options: { breakLine: true } });
+        }
+        else if (block.kind === "table") {
+            current.runs.push({ text: block.header.join("  |  "), options: { breakLine: true, bold: true } });
+            for (const row of block.rows)
+                current.runs.push({ text: row.join("  |  "), options: { breakLine: true } });
+        }
+        else if (block.kind === "heading")
+            current.runs.push({ text: block.text, options: { bold: true, breakLine: true } });
+    }
+    if (!slides.length)
+        start(spec.title);
+    // THE CANVAS, as constants. Every position is derived from these, so changing the layout is one
+    // edit rather than a hunt through magic numbers.
+    const W = 13.33, H = 7.5, M = 0.6;
+    for (const slide of slides) {
+        const page = pptx.addSlide();
+        if (slide.title) {
+            page.addText(slide.title, { x: M, y: 0.45, w: W - M * 2, h: 0.9, fontSize: 28, bold: true, fontFace: DECK_FONT, color: "1F2937" });
+        }
+        if (slide.runs.length) {
+            // The body box ends a margin ABOVE the slide's bottom edge. A box that runs to the edge is a
+            // box whose overflow is invisible rather than obviously wrong.
+            page.addText(slide.runs, {
+                x: M, y: slide.title ? 1.6 : M, w: W - M * 2, h: H - (slide.title ? 1.6 : M) - M,
+                fontSize: 16, fontFace: DECK_FONT, color: "374151", valign: "top", paraSpaceAfter: 6,
+            });
+        }
+    }
+    const output = await pptx.write({ outputType: "nodebuffer" });
+    return Buffer.from(output);
+}
+/**
+ * The font a generated deck asks for.
+ *
+ * 微软雅黑 because it ships with Windows and with Office on macOS, so the name in the file
+ * resolves on the machine that opens it. It is a SUGGESTION, not an embedding: a viewer without it
+ * substitutes its own, which is why nothing about the deck's correctness may depend on this face -
+ * the layout is sized with room to spare for a substitute with different glyph widths.
+ */
+const DECK_FONT = "微软雅黑";
+/**
+ * The format a file's extension names, for the callers that hold a path rather than a format.
+ */
+export function formatOfPath(path) {
+    return documentFormatOf(extname(path));
+}