kordoc：把韩国公文格式的 HWP 与 HWPX 变成 Markdown，再原样写回去
该项目围绕「, HWP HWPX PDF Office Markdown . CLI MCP | Convert Korean documents (HWP, HWPX, PDF, Office) to Markdown, CLI and MCP server with form filling and diff.」构建，适用于实际场景的开源实践，提供可复用的工具链与集成方式。
秒懂
- 它是什么？
- kordoc 是一个面向韩国公文场景的文档转换工具，支持 HWP、HWPX、PDF、Office 与图片 OCR，并提供 CLI 与 MCP 服务器。它的核心卖点不是单向转换，而是保留原始格式的往返编辑。
- 适合谁用？
- kordoc 适合需要批量处理韩国公文、尤其是要把 HWP 或 HWPX 转成 Markdown 喂给 LLM，再让 AI 修改后写回原文件的工程师。它不适合只需要简单文本提取的临时任务，因为安装与学习成本都偏高。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 2 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是韩国公文的格式地狱
kordoc 的 README 开门见山，作者自称在韩国政府机关工作了七年，受够了公文处理。韩国公文中 HWP 和 HWPX 是主流格式，而这两种格式在国际工具链中支持极差。大多数通用文档解析库对 HWP 的二进制结构毫无办法，HWPX 虽然是 XML 但内部布局复杂，普通解析器拿到的只是碎片。kordoc 的目标是把这些格式转成 Markdown，让 AI 能读，同时保留足够信息以便写回。它面向的是需要与韩国政府、公共机构打交道的开发者，或者那些要在企业内部处理大量公文的人。这不是一个通用文档工具，它的设计决策几乎全部围绕韩国公文的特定惯例展开。
转换不是终点，往返编辑才是核心
kordoc 最与众不同的地方在于 patchHwpx 与 patchHwp 这两个命令。文档声称它们能在转换后的 Markdown 上做修改，然后把这些修改写回原始 HWPX 或 HWP 二进制文件，且不触碰未修改部分的格式。这意味着你可以在 Markdown 里让 AI 改一段文字，然后原文件的字体、字号、对齐方式都不变，只有那段文字被替换。从 v3.7 起还支持在表格里增删行，v3.8 起支持向 HWP 5.x 的空单元格写入值。这种设计避免了常见的转换后格式全毁的问题。它把文档当成一个可以局部修补的对象，而不是重新生成。这对公文场景很重要，因为格式本身就是文件合法性的一部分。
表格与页面边界的恢复机制
README 给出了具体数字：HWPX 语料 291 份文档中，表格 1,673 个与单元格 27,714 个全部无损恢复，同一文档的 hwpx 与 pdf 对照中表格匹配率 98.6%。它还提到能从无边框的 PDF 中检测并恢复表格。页面恢复方面，v4.7.3 引入了基于 HWPX linesegarray 与 HWP5 PARA_LINE_SEG 的实际页面边界恢复，替代了此前的按章节近似。它用四种信号组合判断真实页号，包括 vertpos 回退、显式分页、跨页表格的单元格流重置等。没有排版缓存的文件则退回章节近似，并用 pageMode 字段区分 layout 与 section 两种模式。这个设计很务实，它不假装所有文件都有精确页面信息。
安装与 MCP 接入方式
安装只需要 Node.js 18 以上，运行 `npx -y kordoc setup` 会启动一个交互式向导。向导会检测你装了哪些 AI 客户端，包括 Claude Desktop、Cursor、Claude Code、Windsurf、VS Code、Gemini CLI、Zed 等，然后自动修改配置文件。Windows 下会自动用 `cmd /c npx` 包装，避免 PowerShell 的执行策略问题。重启客户端后就有 15 个文档工具可用，包括 parse_document、parse_table、fill_form、patch_document、generate_document。如果只用 CLI，可以直接 `npx kordoc <파일>`。它还支持作为 Claude Code 插件安装，通过 `/plugin marketplace add chrisryugj/kordoc` 添加，之后提到 .hwp 或 .hwpx 文件时会自动触发相关技能。这种安装方式把复杂的环境配置封装掉了，对不熟悉 Node 生态的用户比较友好。
渲染与 OCR 的本地化策略
kordoc 的渲染功能分两条路径。有排版缓存的文件直接用缓存坐标生成 SVG，没有缓存的文件则用纯 TypeScript 的 reflow 引擎重新排版。v3.15 的 reflow 引擎声称实测行断行 98% 一致，但这是作者自述的测试数字，无法独立验证。OCR 方面 v4.2 引入了本地 CPU 推理，使用 PP-OCRv5 韩文模型，不需要 API 密钥。它只对文本层损坏的页面做 OCR，而不是整本扫描。这避免了把清晰页面也过一遍 OCR 的浪费。对于扫描件中的表格，它会检测栅格线来恢复表格结构。这些功能都强调本地运行，对处理敏感公文、不能把文件发到外部服务的机构来说是个实际考量。
已知限制与失败模式
kordoc 不是万能的。印章放置功能明确标注了局限：嵌套表格、文本框、包含 Tab 或换行的段落中，位置是近似的，需要用 `--dx` 与 `--dy` 参数手动微调。多页表格在中间页返回空 Markdown，README 解释这是因为内部表示里跨页表格只算作起始页的一个块。v4.7.3 还提到，当使用 pages 过滤器但文件只有章节近似页面信息时，会触发 PAGE_BOUNDARY_APPROXIMATE 警告。另外，文档指出如果之前装过损坏的全局版本，会遇到 MODULE_NOT_FOUND 错误，需要先卸载再重装。这些限制说明 kordoc 对输入文件的类型和状态很敏感，不是所有 HWP 文件都能得到相同质量的输出。
替代方案与维护成本
对于不涉及 HWP 格式的场景，Pandoc 是更通用的选择，它支持 DOCX、Markdown、PDF 等多种格式，但完全不懂 HWP 的二进制结构。对于 PDF 表格恢复，现有 Python 库如 camelot 或 pdfplumber 各有侧重，但都不处理韩国公文的特定排版惯例。kordoc 的差异化在于它专门针对 HWP/HWPX 做了深度适配，包括政府标准公文格式、印章放置、新老条文对照表这些特定功能。维护方面，项目以 MIT 许可证发布，最近的发布记录显示更新频率很高，v4.9 到 v4.10 之间几天就有一个版本。这意味着修复缺陷很积极，但也意味着 API 可能变化较快，升级时需要留意 changelog。由于它是 npm 包，通过 `npx` 调用，依赖链相对简单，不需要额外运行时。
编辑结论
kordoc 适合需要批量处理韩国公文、尤其是要把 HWP 或 HWPX 转成 Markdown 喂给 LLM，再让 AI 修改后写回原文件的工程师。它不适合只需要简单文本提取的临时任务，因为安装与学习成本都偏高。也不适合对输出格式有严格排版要求的场景，因为渲染与表格恢复都有已知近似。采用前应先用你手头最复杂的公文文件跑一次 `npx kordoc <파일>`，检查转换后的 Markdown 结构是否完整，特别是嵌套表格与跨页内容。若你的工作流只涉及 DOCX 或 PDF，且不处理韩国公文，那么直接用 Pandoc 或现有 PDF 解析库更省事。kordoc 的价值集中在 HWP/HWPX 这一特定格式与韩国公文惯例上，离开这个场景它的优势就不存在了。
社区笔记