用途
kordoc 用于将韩国常见的政府及办公文档格式解析为可编辑的 Markdown 和结构化数据。它支持 HWP 5.x、HWPX 和 PDF 三种格式，可处理专有的 HWP 二进制格式，适合需要批量转换、内容提取或文档对比的自动化流程。
主要能力
- 多格式解析：自动检测格式并解析 HWP、HWPX、PDF 为 Markdown 和 IRBlock[] 结构化数据。
- 表格与表单处理：提取文档中的表格，识别表单字段（如姓名、地址等），并返回置信度。
- 文档对比：支持跨格式（如 HWP 与 HWPX）比较两个文档的差异，输出新增、删除、修改和未变更的统计。
- 反向生成：可将 Markdown 转换回 HWPX 格式。
- OCR 支持：对基于图像的 PDF 提供可插拔的 OCR 接口，可集成 Tesseract.js 等。
- MCP 服务器：提供 kordoc-mcp 工具，供 Claude Desktop、Cursor、Windsurf 等客户端调用，支持 parse_document、detect_format、parse_metadata、parse_pages、parse_table、compare_documents、parse_form 等工具。
- 监视模式：CLI 支持 watch 模式，可自动转换新文件并支持 webhook 通知。
使用方式
- 安装：核心库通过
npm install kordoc安装；PDF 支持需额外安装pdfjs-dist。CLI 可直接使用npx kordoc而无需安装。 - CLI：例如
npx kordoc document.hwpx输出到标准输出，npx kordoc document.hwp -o output.md保存到文件，npx kordoc *.pdf -d ./converted/批量转换，--format json输出 JSON，--pages 1-3指定页面范围，watch子命令监视目录。 - 编程 API：核心函数包括
parse、parseHwpx、parseHwp、parsePdf、detectFormat、blocksToMarkdown、compare、extractFormFields、markdownToHwpx、watch。需传入 ArrayBuffer（如readFileSync("file").buffer）。解析选项支持pages和ocr。 - MCP 配置：在 MCP 配置中添加
{"mcpServers": {"kordoc": {"command": "npx", "args": ["-y", "kordoc-mcp"]}}}。
适用场景
- 批量转换韩国政府或企业文档为 Markdown 以进行内容管理或搜索。
- 从 HWP/HWPX/PDF 中提取表格和表单数据用于数据分析。
- 比较文档版本差异，支持跨格式对比。
- 在 AI 代理或聊天客户端中通过 MCP 服务器调用文档解析能力。
- 生成 HWPX 文档作为输出。
限制
- 加密或受密码保护的 HWP 文件无法解析，无绕过方法。
- 基于图像的 PDF 需要提供 OCR 函数，否则返回 IMAGE_BASED_PDF 错误。
- PDF 表格检测依赖 pdfjs-dist，无边框表格使用聚类启发式。
- 大文件解析较慢，建议使用 pages 选项或仅提取元数据。
- 输出默认 UTF-8，终端或文件需使用 UTF-8 以避免韩文字符乱码。
- HWP 表格列错位问题需升级到 v1.6.1+。
- buffer 需为 ArrayBuffer，而非 Node.js Buffer。