dsh-shared-kb 0.0.0-stage → 1.0.0

package/lib/parse/parser.js

@@ -0,0 +1,643 @@
+/**
+ * 文档解析：把各种来源统一成 { blocks, pages, type, warnings, outline }。
+ *
+ * 原则：
+ *  - 重量级依赖（mupdf）首次使用才动态 import，没装就只解析纯文本类，
+ *    不因为某个 PDF 让整个插件起不来；
+ *  - 每个解析器都给出 page 号（能给的给），因为「第几页」是复核的锚点；
+ *  - 解析失败不吞异常，返回 warnings + 已解析出的部分，让上层决定是否标记 partial。
+ */
+import { readFile } from "node:fs/promises";
+import { extOf, isTextualExt } from "../core/paths.js";
+import { badRequest } from "../core/errors.js";
+
+export const PARSER_VERSION = 4;
+
+/** 支持扩展名 → 解析器名 */
+export const PARSERS = Object.freeze({
+  ".pdf": "pdf",
+  ".docx": "docx",
+  ".xlsx": "xlsx",
+  ".xlsm": "xlsx",
+  ".pptx": "pptx",
+  ".epub": "epub",
+  ".md": "markdown",
+  ".markdown": "markdown",
+  ".txt": "text",
+  ".csv": "csv",
+  ".json": "text",
+  ".html": "html",
+  ".htm": "html",
+  ".log": "text",
+  ".yml": "text",
+  ".yaml": "text",
+});
+
+export const SUPPORTED_EXTS = Object.freeze(Object.keys(PARSERS));
+
+export function kindForPath(path) {
+  const ext = extOf(path);
+  const parser = PARSERS[ext];
+  if (!parser) {
+    throw badRequest(
+      `不支持的文件类型 ${ext || "(无扩展名)"}；支持：${SUPPORTED_EXTS.join(" ")}`,
+      { supported: SUPPORTED_EXTS }
+    );
+  }
+  return parser;
+}
+
+function decodeText(buffer) {
+  // BOM 优先
+  if (buffer.length >= 3 && buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf) {
+    return new TextDecoder("utf-8").decode(buffer.subarray(3));
+  }
+  if (buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) {
+    return new TextDecoder("utf-16le").decode(buffer.subarray(2));
+  }
+  if (buffer.length >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff) {
+    return new TextDecoder("utf-16be").decode(buffer.subarray(2));
+  }
+  // 先按 UTF-8 严格解码；失败再按 GB18030（中文 Windows 纯文本常见）
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+  } catch {
+    try {
+      return new TextDecoder("gb18030").decode(buffer);
+    } catch {
+      return new TextDecoder("utf-8").decode(buffer);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Markdown / 纯文本
+// ---------------------------------------------------------------------------
+
+/** 按 ATX 标题切段：# ## ### …，代码块内的 # 不算标题。 */
+export function markdownToBlocks(markdown) {
+  const lines = String(markdown ?? "").split(/\r?\n/);
+  const blocks = [];
+  let heading = "";
+  let level = 0;
+  let buffer = [];
+  let inFence = false;
+  let fenceMark = "";
+
+  const push = () => {
+    const text = buffer.join("\n").trim();
+    buffer = [];
+    if (text === "") return;
+    blocks.push({ text, heading, level });
+  };
+
+  for (const line of lines) {
+    const fence = line.match(/^\s*(```+|~~~+)/);
+    if (fence) {
+      if (!inFence) {
+        inFence = true;
+        fenceMark = fence[1][0];
+      } else if (fence[1][0] === fenceMark) {
+        inFence = false;
+      }
+      buffer.push(line);
+      continue;
+    }
+    if (!inFence) {
+      const atx = line.match(/^(#{1,6})\s+(.*)$/);
+      if (atx) {
+        push();
+        heading = atx[2].trim();
+        level = atx[1].length;
+        continue;
+      }
+    }
+    buffer.push(line);
+  }
+  push();
+  return blocks;
+}
+
+export async function parseMarkdown(path) {
+  const text = decodeText(await readFile(path));
+  const blocks = markdownToBlocks(text);
+  return {
+    blocks: blocks.length > 0 ? blocks : [{ text, heading: "", level: 0 }],
+    pages: null,
+    type: "markdown",
+    warnings: [],
+    outline: blocks.filter((b) => b.heading).map((b) => ({ title: b.heading, level: b.level })),
+  };
+}
+
+export async function parseText(path) {
+  const text = decodeText(await readFile(path));
+  // 纯文本没有结构，按空行分段，每段不超过 2000 字
+  const paras = text.split(/\n{2,}/).map((p) => p.trim()).filter((p) => p !== "");
+  const blocks = [];
+  for (const para of paras) {
+    if (para.length <= 2000) {
+      blocks.push({ text: para, heading: "", level: 0 });
+    } else {
+      for (let i = 0; i < para.length; i += 2000) {
+        blocks.push({ text: para.slice(i, i + 2000), heading: "", level: 0 });
+      }
+    }
+  }
+  return { blocks, pages: null, type: "text", warnings: [], outline: [] };
+}
+
+export async function parseCsv(path) {
+  const text = decodeText(await readFile(path));
+  const lines = text.split(/\r?\n/).filter((line) => line.trim() !== "");
+  if (lines.length === 0) return { blocks: [], pages: null, type: "csv", warnings: [], outline: [] };
+  const header = lines[0];
+  const cols = header.split(",").length;
+  const blocks = [{ text: `表头：${header}`, heading: "表头", level: 1 }];
+  // 每 40 行一组，组头带上表头，检索命中时能知道每列是什么
+  const GROUP = 40;
+  for (let i = 1; i < lines.length; i += GROUP) {
+    const slice = lines.slice(i, i + GROUP);
+    const body = slice.join("\n");
+    blocks.push({
+      text: `列：${header}\n${body}`,
+      heading: `第 ${i}–${i + slice.length - 1} 行`,
+      level: 2,
+      page: Math.ceil(i / GROUP),
+    });
+  }
+  return { blocks, pages: Math.ceil(lines.length / GROUP), type: "csv", warnings: [], outline: [] };
+}
+
+export async function parseHtml(path) {
+  const text = decodeText(await readFile(path));
+  const blocks = htmlToBlocks(text);
+  return { blocks, pages: null, type: "html", warnings: [], outline: [] };
+}
+
+/** 极简 HTML → 块：去掉 script/style，按块级标签断段，标题标签转 heading。 */
+export function htmlToBlocks(html) {
+  const cleaned = String(html ?? "")
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<\/(p|div|section|article|li|tr|h[1-6]|br)\s*>/gi, "\n\n")
+    .replace(/<h([1-6])[^>]*>/gi, (_m, lv) => `\n\n__H${lv}__`)
+    .replace(/<[^>]+>/g, " ");
+  const decoded = cleaned
+    .replace(/&nbsp;/g, " ")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, "\"")
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&");
+  const blocks = [];
+  let heading = "";
+  let level = 0;
+  for (const rawChunk of decoded.split(/\n{2,}/)) {
+    const chunk = rawChunk.trim();
+    if (chunk === "") continue;
+    const h = chunk.match(/^__H([1-6])__([\s\S]*)$/);
+    if (h) {
+      heading = h[2].replace(/\s+/g, " ").trim();
+      level = Number(h[1]);
+      continue;
+    }
+    const text = chunk.replace(/\s+/g, " ").trim();
+    if (text !== "") blocks.push({ text, heading, level });
+  }
+  return blocks;
+}
+
+// ---------------------------------------------------------------------------
+// DOCX / PPTX / XLSX（jszip + fast-xml-parser，零额外重依赖）
+// ---------------------------------------------------------------------------
+
+async function loadZip(path) {
+  const { default: JSZip } = await import("jszip");
+  const data = await readFile(path);
+  return JSZip.loadAsync(data);
+}
+
+function xmlParser() {
+  return { ignoreAttributes: false, attributeNamePrefix: "@_", trimValues: true };
+}
+
+/** 从 DOCX 的 word/document.xml 抽段落、表格与标题层级。 */
+export async function parseDocx(path) {
+  const zip = await loadZip(path);
+  const docFile = zip.file("word/document.xml");
+  if (!docFile) throw new Error("不是有效的 docx：缺少 word/document.xml");
+  const xml = await docFile.async("string");
+  const { XMLParser } = await import("fast-xml-parser");
+  const parser = new XMLParser({ ...xmlParser(), isArray: (name) => ["w:p", "w:tbl", "w:tr"].includes(name) });
+  const tree = parser.parse(xml);
+
+  const blocks = [];
+  const warnings = [];
+  const outline = [];
+  // 标题样式：w:pStyle 的 w:val 形如 Heading1 / 1 / 标题 1
+  const headingLevel = (styleId) => {
+    if (!styleId) return 0;
+    const s = String(styleId);
+    const m = s.match(/(?:heading|标题)\s*([1-6])/i) || s.match(/^([1-6])$/);
+    return m ? Number(m[1]) : 0;
+  };
+
+  const textOfNode = (node, out) => {
+    if (node == null) return;
+    if (Array.isArray(node)) {
+      for (const item of node) textOfNode(item, out);
+      return;
+    }
+    if (typeof node !== "object") return;
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "w:t") {
+        const parts = Array.isArray(value) ? value : [value];
+        for (const part of parts) {
+          if (typeof part === "string") out.push(part);
+          else if (part && typeof part["#text"] === "string") out.push(part["#text"]);
+        }
+      } else if (key === "w:tab") {
+        out.push("\t");
+      } else if (key === "w:br") {
+        out.push("\n");
+      } else if (key !== "w:pPr" && key !== "w:rPr") {
+        textOfNode(value, out);
+      }
+    }
+  };
+
+  const walk = (node, heading, level) => {
+    if (node == null) return;
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item, heading, level);
+      return;
+    }
+    if (typeof node !== "object") return;
+
+    if (Array.isArray(node["w:p"])) {
+      for (const p of node["w:p"]) {
+        const styleId = p?.["w:pPr"]?.["w:pStyle"]?.["@_w:val"];
+        const lv = headingLevel(styleId);
+        const out = [];
+        textOfNode(p, out);
+        const text = out.join("").trim();
+        if (text === "") continue;
+        if (lv > 0) {
+          outline.push({ title: text, level: lv });
+          blocks.push({ text, heading: text, level: lv });
+        } else {
+          blocks.push({ text, heading, level });
+        }
+      }
+    }
+    if (Array.isArray(node["w:tbl"])) {
+      for (const tbl of node["w:tbl"]) {
+        const rows = [];
+        for (const tr of tbl?.["w:tr"] ?? []) {
+          const cells = [];
+          for (const tc of tr?.["w:tc"] ?? []) {
+            const out = [];
+            textOfNode(tc, out);
+            cells.push(out.join("").replace(/\s+/g, " ").trim());
+          }
+          if (cells.some((c) => c !== "")) rows.push(cells.join(" | "));
+        }
+        if (rows.length > 0) {
+          // 表格每 30 行一块，避免超大表把一块撑爆
+          for (let i = 0; i < rows.length; i += 30) {
+            const slice = rows.slice(i, i + 30);
+            blocks.push({ text: slice.join("\n"), heading: heading || "表格", level: Math.max(level, 1) });
+          }
+        }
+      }
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "w:p" || key === "w:tbl") continue;
+      if (key.startsWith("@_") || key === "#text") continue;
+      walk(value, heading, level);
+    }
+  };
+
+  walk(tree, "", 0);
+  if (blocks.length === 0) warnings.push("文档中没有可提取的文字（可能是纯图片文档）");
+  return { blocks, pages: null, type: "docx", warnings, outline };
+}
+
+/** PPTX：每张幻灯片一块，标题单独作为 heading。 */
+export async function parsePptx(path) {
+  const zip = await loadZip(path);
+  const slides = Object.keys(zip.files)
+    .filter((name) => /^ppt\/slides\/slide\d+\.xml$/.test(name))
+    .sort((a, b) => Number(a.match(/slide(\d+)/)[1]) - Number(b.match(/slide(\d+)/)[1]));
+  if (slides.length === 0) throw new Error("不是有效的 pptx：找不到 ppt/slides");
+  const { XMLParser } = await import("fast-xml-parser");
+  const parser = new XMLParser({ ...xmlParser(), isArray: (name) => name === "a:p" });
+  const blocks = [];
+  const outline = [];
+
+  for (let i = 0; i < slides.length; i += 1) {
+    const xml = await zip.file(slides[i]).async("string");
+    const tree = parser.parse(xml);
+    const texts = [];
+    const collect = (node) => {
+      if (node == null) return;
+      if (Array.isArray(node)) {
+        for (const item of node) collect(item);
+        return;
+      }
+      if (typeof node !== "object") return;
+      if (typeof node["a:t"] === "string") texts.push(node["a:t"]);
+      else if (Array.isArray(node["a:t"])) for (const t of node["a:t"]) if (typeof t === "string") texts.push(t);
+      for (const [key, value] of Object.entries(node)) {
+        if (key === "a:t") continue;
+        collect(value);
+      }
+    };
+    collect(tree);
+    const lines = texts.map((t) => t.trim()).filter((t) => t !== "");
+    if (lines.length === 0) continue;
+    const title = lines[0].length <= 80 ? lines[0] : "";
+    const body = lines.slice(title ? 1 : 0).join("\n");
+    const label = `第 ${i + 1} 张幻灯片`;
+    if (title) outline.push({ title, level: 1 });
+    blocks.push({
+      text: `${label}${title ? `\n标题：${title}` : ""}${body ? `\n${body}` : ""}`,
+      heading: title || label,
+      level: 1,
+      page: i + 1,
+    });
+  }
+  return { blocks, pages: slides.length, type: "pptx", warnings: [], outline };
+}
+
+/** XLSX：每个工作表一块组，每 40 行一组带表头。 */
+export async function parseXlsx(path) {
+  const zip = await loadZip(path);
+  const { XMLParser } = await import("fast-xml-parser");
+  const parser = new XMLParser(xmlParser());
+
+  const sharedFile = zip.file("xl/sharedStrings.xml");
+  const shared = [];
+  if (sharedFile) {
+    const tree = parser.parse(await sharedFile.async("string"));
+    for (const si of tree?.["sst"]?.["si"] ?? []) {
+      const parts = [];
+      const collect = (node) => {
+        if (node == null) return;
+        if (typeof node === "string") {
+          parts.push(node);
+          return;
+        }
+        if (Array.isArray(node)) {
+          for (const item of node) collect(item);
+          return;
+        }
+        if (typeof node !== "object") return;
+        if (typeof node["t"] === "string") parts.push(node["t"]);
+        for (const [key, value] of Object.entries(node)) {
+          if (key === "t" || key === "rPh") continue;
+          collect(value);
+        }
+      };
+      collect(si);
+      shared.push(parts.join(""));
+    }
+  }
+
+  // 工作表名
+  const workbookFile = zip.file("xl/workbook.xml");
+  const sheetNames = [];
+  if (workbookFile) {
+    const tree = parser.parse(await workbookFile.async("string"));
+    for (const sheet of tree?.["workbook"]?.["sheets"]?.["sheet"] ?? []) {
+      sheetNames.push(String(sheet?.["@_name"] ?? `Sheet${sheetNames.length + 1}`));
+    }
+  }
+
+  const sheetFiles = Object.keys(zip.files)
+    .filter((name) => /^xl\/worksheets\/sheet\d+\.xml$/.test(name))
+    .sort((a, b) => Number(a.match(/sheet(\d+)/)[1]) - Number(b.match(/sheet(\d+)/)[1]));
+
+  const blocks = [];
+  const outline = [];
+  for (let s = 0; s < sheetFiles.length; s += 1) {
+    const name = sheetNames[s] ?? `Sheet${s + 1}`;
+    outline.push({ title: name, level: 1 });
+    const tree = parser.parse(await zip.file(sheetFiles[s]).async("string"));
+    const rows = tree?.["worksheet"]?.["sheetData"]?.["row"] ?? [];
+    const lines = [];
+    for (const row of rows) {
+      const cells = [];
+      for (const c of row?.["c"] ?? []) {
+        const type = c?.["@_t"];
+        let value = "";
+        if (type === "s") {
+          const idx = Number(c?.["v"]);
+          value = Number.isInteger(idx) ? shared[idx] ?? "" : "";
+        } else if (type === "inlineStr") {
+          value = String(c?.["is"]?.["t"] ?? "");
+        } else {
+          value = String(c?.["v"] ?? "");
+        }
+        if (value !== "") cells.push(value);
+      }
+      if (cells.length > 0) lines.push(cells.join(" | "));
+    }
+    if (lines.length === 0) continue;
+    const header = lines[0];
+    const GROUP = 40;
+    for (let i = 1; i < lines.length; i += GROUP) {
+      const slice = lines.slice(i, i + GROUP);
+      blocks.push({
+        text: `工作表：${name}\n表头：${header}\n${slice.join("\n")}`,
+        heading: name,
+        level: 2,
+        page: Math.floor(i / GROUP) + 1,
+      });
+    }
+    if (lines.length === 1) {
+      blocks.push({ text: `工作表：${name}\n表头：${header}`, heading: name, level: 2, page: 1 });
+    }
+  }
+  return { blocks, pages: sheetFiles.length, type: "xlsx", warnings: [], outline };
+}
+
+/** EPUB：容器 → spine 顺序读 XHTML。 */
+export async function parseEpub(path) {
+  const zip = await loadZip(path);
+  const containerFile = zip.file("META-INF/container.xml");
+  if (!containerFile) throw new Error("不是有效的 epub：缺少 META-INF/container.xml");
+  const { XMLParser } = await import("fast-xml-parser");
+  const parser = new XMLParser(xmlParser());
+  const container = parser.parse(await containerFile.async("string"));
+  const opfPath = container?.["container"]?.["rootfiles"]?.["rootfile"]?.["@_full-path"];
+  if (!opfPath) throw new Error("epub 缺少 OPF 路径");
+  const opf = parser.parse(await zip.file(opfPath).async("string"));
+  const baseDir = opfPath.includes("/") ? opfPath.slice(0, opfPath.lastIndexOf("/") + 1) : "";
+  const manifest = new Map();
+  for (const item of opf?.["package"]?.["manifest"]?.["item"] ?? []) {
+    manifest.set(String(item?.["@_id"]), String(item?.["@_href"] ?? ""));
+  }
+  const blocks = [];
+  const outline = [];
+  let page = 0;
+  for (const itemref of opf?.["package"]?.["spine"]?.["itemref"] ?? []) {
+    const href = manifest.get(String(itemref?.["@_idref"]));
+    if (!href) continue;
+    const full = decodeURIComponent(baseDir + href);
+    const file = zip.file(full);
+    if (!file) continue;
+    page += 1;
+    const html = await file.async("string");
+    const titleMatch = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    const chapterTitle = titleMatch ? titleMatch[1].replace(/<[^>]+>/g, "").trim() : "";
+    if (chapterTitle) outline.push({ title: chapterTitle, level: 1 });
+    for (const block of htmlToBlocks(html)) {
+      blocks.push({ ...block, page, heading: block.heading || chapterTitle, level: block.level || (chapterTitle ? 1 : 0) });
+    }
+  }
+  return { blocks, pages: page, type: "epub", warnings: [], outline };
+}
+
+// ---------------------------------------------------------------------------
+// PDF（mupdf，可选依赖）
+// ---------------------------------------------------------------------------
+
+let mupdfPromise = null;
+async function loadMupdf() {
+  if (!mupdfPromise) {
+    mupdfPromise = import("mupdf").catch(() => null);
+  }
+  return mupdfPromise;
+}
+
+/** 判定一页文字层是否可信：字符数过少或大量替换字符 → 视为扫描页。 */
+export function pageTextQuality(text) {
+  const s = String(text ?? "");
+  const printable = (s.match(/[\p{L}\p{N}\p{P}\s]/gu) ?? []).length;
+  const replacement = (s.match(/\uFFFD/g) ?? []).length;
+  const ratio = s.length === 0 ? 0 : printable / s.length;
+  return {
+    chars: s.replace(/\s+/g, "").length,
+    replacementRatio: s.length === 0 ? 0 : replacement / s.length,
+    printableRatio: ratio,
+    suspicious: s.replace(/\s+/g, "").length < 20 || ratio < 0.6,
+  };
+}
+
+export async function parsePdf(path) {
+  const mupdfModule = await loadMupdf();
+  if (!mupdfModule) {
+    throw new Error("解析 PDF 需要 mupdf（可选 peer 依赖），当前未安装。请运行 npm i mupdf，或改用文字类格式导入");
+  }
+  const mupdf = mupdfModule.default ?? mupdfModule;
+  const data = await readFile(path);
+  const doc = mupdf.Document.openDocument(
+    new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
+    "application/pdf"
+  );
+  const pageCount = doc.countPages();
+  const blocks = [];
+  const warnings = [];
+  const scannedPages = [];
+  let outline = [];
+  try {
+    const raw = doc.loadOutline();
+    outline = (Array.isArray(raw) ? raw : [])
+      .map((o) => (typeof o === "string" ? o : o?.title))
+      .filter((t) => typeof t === "string" && t.trim() !== "")
+      .slice(0, 500)
+      .map((title) => ({ title: title.trim(), level: 1 }));
+  } catch {
+    outline = [];
+  }
+
+  for (let i = 0; i < pageCount; i += 1) {
+    const page = doc.loadPage(i);
+    let text = "";
+    try {
+      const structured = page.toStructuredText("preserve-whitespace");
+      text = structured.asText();
+    } catch {
+      text = "";
+    }
+    const quality = pageTextQuality(text);
+    if (quality.suspicious) scannedPages.push(i + 1);
+    const trimmed = text.trim();
+    if (trimmed !== "") {
+      for (const paragraph of trimmed.split(/\n{2,}/)) {
+        const p = paragraph.trim();
+        if (p !== "") blocks.push({ text: p, heading: "", level: 0, page: i + 1 });
+      }
+    }
+    page.destroy?.();
+  }
+  doc.destroy?.();
+
+  if (scannedPages.length > 0) {
+    warnings.push(
+      `${scannedPages.length}/${pageCount} 页没有可信文字层（第 ${scannedPages.slice(0, 20).join("、")}${scannedPages.length > 20 ? "…" : ""} 页），这些页需要 OCR 或查看原页图片`
+    );
+  }
+  if (blocks.length === 0) warnings.push("PDF 中没有提取到文字层；可能是纯扫描件");
+
+  return { blocks, pages: pageCount, type: "pdf", warnings, outline, scannedPages };
+}
+
+/** 渲染某一页为 PNG（供查看原页 / 外部 OCR）。 */
+export async function renderPdfPage(path, pageNo, { dpi = 150 } = {}) {
+  const mupdfModule = await loadMupdf();
+  if (!mupdfModule) throw new Error("渲染 PDF 需要 mupdf，当前未安装");
+  const mupdf = mupdfModule.default ?? mupdfModule;
+  const data = await readFile(path);
+  const doc = mupdf.Document.openDocument(
+    new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
+    "application/pdf"
+  );
+  const index = Math.max(0, Math.min(doc.countPages() - 1, Number(pageNo) - 1));
+  const page = doc.loadPage(index);
+  const zoom = dpi / 72;
+  const pixmap = page.toPixmap(mupdf.Matrix.scale(zoom, zoom), mupdf.ColorSpace.DeviceRGB, false, true);
+  const png = pixmap.asPNG();
+  page.destroy?.();
+  doc.destroy?.();
+  return Buffer.from(png);
+}
+
+// ---------------------------------------------------------------------------
+// 统一入口
+// ---------------------------------------------------------------------------
+
+const PARSER_FNS = {
+  pdf: parsePdf,
+  docx: parseDocx,
+  xlsx: parseXlsx,
+  pptx: parsePptx,
+  epub: parseEpub,
+  markdown: parseMarkdown,
+  text: parseText,
+  csv: parseCsv,
+  html: parseHtml,
+};
+
+/**
+ * 解析任意受支持文件。
+ * @returns {Promise<{blocks, pages, type, warnings, outline, scannedPages?}>}
+ */
+export async function parseFile(path) {
+  const kind = kindForPath(path);
+  const fn = PARSER_FNS[kind];
+  if (!fn) throw badRequest(`没有为 ${kind} 注册解析器`);
+  const result = await fn(path);
+  return {
+    blocks: Array.isArray(result.blocks) ? result.blocks : [],
+    pages: result.pages ?? null,
+    type: result.type ?? kind,
+    warnings: Array.isArray(result.warnings) ? result.warnings : [],
+    outline: Array.isArray(result.outline) ? result.outline : [],
+    scannedPages: result.scannedPages ?? [],
+    parserVersion: PARSER_VERSION,
+  };
+}