需要解析韩文 HWP/HWPX/PDF 为…

在 Node.js、CLI 或 MCP 环境中解析韩文 HWP、HWPX、PDF 文档，提取 Markdown、IRBlock、元数据、表格、表单字段，并支持文档对比与 Markdown 反向生成 HWPX。

适用场景

解决思路

1. 安装核心库：运行 `npm install kordoc`。
2. 安装 PDF 支持（可选 peer dependency）：运行 `npm install pdfjs-dist`。
3. 无需安装 CLI：运行 `npx kordoc document.hwpx`。
4. 自动检测并解析任意文档：从 `kordoc` 导入 `parse`，用 `readFileSync` 读取文件并传入 `buffer.buffer`（必须是 `ArrayBuffer`）调用 `await parse(buffer.buffer)`。
5. 解析成功后读取 `result.markdown`（完整 Markdown 字符串）、`result.blocks`（`IRBlock[]` 结构化数据）、`result.metadata`（`title`、`author`、`createdAt`、`pageCount` 等）、`result.outline`（`OutlineItem[]` 文档结构）、`result.warnings`（`ParseWarning[]` 跳过元素）。
6. 解析失败时读取 `result.error` 与 `result.code`，例如 `ENCRYPTED`、`ZIP_BOMB`、`IMAGE_BASED_PDF` 等。
7. 按格式解析：从 `kordoc` 导入 `parseHwpx`、`parseHwp`、`parsePdf`、`detectFormat`；先用 `detectFormat(buffer.buffer)` 得到 `hwpx`、`hwp`、`pdf` 或 `unknown`，再调用对应解析器并传入 `buffer.buffer`。
8. 使用解析选项：调用 `parse(buffer.buffer, { pages: ... })` 指定页码，如 `pages` 设为 `1-3` 或 `[1, 5, 10]`；为图片型 PDF 传入 `ocr` 异步函数，参数为 `pageImage`、`pageNumber`、`mimeType`，返回识别文本。
9. 处理 `IRBlock`：遍历 `result.blocks`，按 `block.type` 判断 `heading`、`paragraph`、`table`、`list`、`image`、`separator`。
10. 处理 heading block：读取 `block.level`、`block.text`、`block.bbox`（包含 `x`、`y`、`width`、`height`、`page`）。
11. 处理 table block：将 block 视为 `IRTable`，遍历 `table.rows`，再遍历每行 `cell`，读取 `cell.text`、`cell.colspan`、`cell.rowspan`。
12. 处理 paragraph block：读取 `block.text`、`block.style`（`InlineStyle`，如 `bold`、`italic`、`fontSize` 等）、`block.pageNumber`。
13. 将 blocks 转回 Markdown：从 `kordoc` 导入 `blocksToMarkdown`，调用 `blocksToMarkdown(result.blocks)`。
14. 文档比较：从 `kordoc` 导入 `compare`，读取两个 `ArrayBuffer`（如 `readFileSync('v1.hwp').buffer` 与 `readFileSync('v2.hwpx').buffer`，支持跨格式），调用 `await compare(bufA, bufB)`。
15. 读取比较结果：`diff.stats` 包含 `added`、`removed`、`modified`、`unchanged`；遍历 `diff.diffs`，每项 `d.type` 为 `added`、`removed`、`modified`、`unchanged`，读取 `d.blockA`、`d.blockB`，表格块可读取 `d.cellDiffs`（`CellDiff[]`）。
16. 表单字段提取：解析成功后从 `kordoc` 导入 `extractFormFields`，调用 `extractFormFields(result.blocks)`；读取 `form.confidence`（0.0–1.0），遍历 `form.fields` 读取 `field.label`、`field.value`、`field.row`、`field.col`。
17. Markdown 转 HWPX：从 `kordoc` 导入 `markdownToHwpx`，准备 Markdown 字符串（可含标题、正文、表格），调用 `await markdownToHwpx(markdown)` 得到 `hwpxBuffer`，用 `writeFileSync('output.hwpx', Buffer.from(hwpxBuffer))` 写入文件。
18. CLI 基本转换输出到 stdout：运行 `npx kordoc document.hwpx`。
19. CLI 保存到文件：运行 `npx kordoc document.hwp -o output.md`。
20. CLI 批量把 PDF 转到一个目录：运行 `npx kordoc *.pdf -d ./converted/`。
21. CLI JSON 输出包含 blocks 和 metadata：运行 `npx kordoc report.hwpx --format json`。
22. CLI 只解析指定页：运行 `npx kordoc report.hwpx --pages 1-3`。
23. CLI watch 模式自动转换新文件：运行 `npx kordoc watch ./incoming -d ./output`。
24. CLI watch 模式加 webhook 通知：运行 `npx kordoc watch ./docs --webhook https://api.example.com/hook`。
25. 配置 MCP server：在 MCP 配置（Claude Desktop、Cursor、Windsurf）中加入 `mcpServers.kordoc`，`command` 为 `npx`，`args` 为 `-y` 和 `kordoc-mcp`。
26. 使用 MCP 工具 `parse_document`：解析 HWP/HWPX/PDF → Markdown + metadata + outline + warnings。
27. 使用 MCP 工具 `detect_format`：通过 magic bytes 检测文件格式。
28. 使用 MCP 工具 `parse_metadata`：只提取 metadata（快速，不完整解析）。
29. 使用 MCP 工具 `parse_pages`：解析指定页码范围。
30. 使用 MCP 工具 `parse_table`：提取文档中第 N 个表格。
31. 使用 MCP 工具 `compare_documents`：比较两个文档（支持跨格式）。
32. 使用 MCP 工具 `parse_form`：将表单字段提取为结构化 JSON。
33. 编写 TypeScript 时从 `kordoc` 导入所需类型：`ParseResult`、`ParseSuccess`、`ParseFailure`、`ErrorCode`、`IRBlock`、`IRBlockType`、`IRTable`、`IRCell`、`CellContext`、`DocumentMetadata`、`OutlineItem`、`ParseWarning`、`WarningCode`、`BoundingBox`、`InlineStyle`、`ParseOptions`、`FileType`、`OcrProvider`、`WatchOptions`、`DiffResult`、`BlockDiff`、`CellDiff`、`DiffChangeType`、`FormField`、`FormResult`。
34. 批量处理文件：用 `glob('./docs/**/*.{hwp,hwpx,pdf}')` 查找文件；对每个文件执行 `readFileSync`，用 `detectFormat(buffer.buffer)` 检测；若为 `unknown` 则跳过。
35. 批量处理错误处理：解析失败时，若 `result.code` 为 `ENCRYPTED` 则警告并跳过；若为 `IMAGE_BASED_PDF` 则警告需要 OCR；否则输出 `Failed: ${file} — ${result.error}`；成功后输出 `Parsed ${file}: ${result.blocks.length} blocks`。
36. 提取所有表格：解析成功后用 `result.blocks.filter(b => b.type === 'table') as IRTable[]`，遍历每个表格和行，将单元格文本用 ` | ` 连接并打印为 Markdown 行。
37. 使用 Tesseract.js OCR：调用 `parse(buffer.buffer, { ocr: async (pageImage, pageNumber, mimeType) => { ... } })`，在回调中把 `pageImage` 转为 `Blob`，用 `URL.createObjectURL` 生成 URL，调用 `Tesseract.recognize(url, 'kor+eng')`，返回 `data.text`，之后 `URL.revokeObjectURL(url)`。
38. 编程式 watch API：从 `kordoc` 导入 `watch`，调用 `watch('./incoming', { output: './converted', webhook: process.env.WEBHOOK_URL, onFile: async (file, result) => { if (result.success) console.log(`Converted: ${file}`) } })`；用 `watcher.stop()` 停止监听。
39. 处理 `buffer.buffer` vs `Buffer`：kordoc 需要 `ArrayBuffer`，不要传 Node.js `Buffer`；总是传 `readFileSync('file').buffer` 或对 `Uint8Array` 使用 `.buffer`。
40. 处理 PDF 表格未检测：安装 `pdfjs-dist`：`npm install pdfjs-dist`；无边框表格由 kordoc 自动使用基于聚类的启发式处理。
41. 处理 `IMAGE_BASED_PDF` 错误：PDF 含扫描图像且无文本层；在 parse options 中提供 `ocr` 函数。
42. 处理 `ENCRYPTED` 错误：HWP DRM/密码保护文件没有解密密钥无法解析，无绕过方法。
43. 处理韩文字符乱码：确保终端/文件使用 UTF-8 编码；kordoc 默认输出 UTF-8 Markdown。
44. 处理大文件慢：使用 `pages` 选项只解析所需页，如 `parse(buf, { pages: '1-5' })`；只提取 metadata 更快：使用 `parse_metadata` MCP 工具或直接检查 `result.metadata`。
45. 处理 HWP 表格列错误：升级到 `v1.6.1+`；更早版本在 `LIST_HEADER` 解析中有 2-byte offset misalignment，导致列爆炸。

适用边界 · 注意事项

• HWP 文件被 DRM 或密码保护且没有解密密钥时，不要用 kordoc，无法解析。
• PDF 是纯扫描图片且没有可提供 OCR 服务时，不要指望直接解析文本，需先提供 `ocr` 函数。
• 需要完全不依赖特定第三方库/CLI，或不想安装 npm 包时，不适用。