kordoc解析HWP系列实战：HWP3·HWP5·HWPX·HWPML四大格式引擎区别与选择指南

kordoc解析HWP系列实战：HWP3·HWP5·HWPX·HWPML四大格式引擎区别与选择指南

【免费下载链接】kordoc모두 파싱해버리겠다 — 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项目地址: https://gitcode.com/gh_mirrors/ko/kordoc

kordoc 是一款开源的韩文文档解析工具，能把 HWP、HWPX、HWP3、HWPML 等韩国主流文档格式一键转换为 Markdown 和结构化数据。它内部实现了四套独立的格式解析引擎，分别对应韩文文档三十多年的演化历史。本文带你搞清楚这四大引擎的区别，并根据你的文档情况快速选出正确的处理方式。

为什么会有四套解析引擎？

韩文文档并非一种格式，而是四代格式：

如果你的文档来源混杂（比如既有 90 年代的扫描件母本、又有最新生成的 HWPX 公文），单引擎方案必然顾此失彼。kordoc 的做法是：四个引擎各管一段，输出统一。

格式识别：靠"魔法字节"自动分流

你不需要告诉 kordoc 文档是什么格式。src/detect.ts 中的detectFormat()会读取文件头部的"魔法字节"自动判定：

• HWPX：PK\x03\x04（ZIP 特征，与 DOCX/XLSX 同族）
• HWP 5.x：\xD0\xCF\x11\xE0（OLE2 复合文档头）
• HWP 3.x：30 字节文本签名HWP Document File V3.00
• HWPML：<?xml且包含<HWPML标签
• HWP 5.x 与 XLS 撞车时（同为 OLE2）：打开容器检查内部流名，有Workbook就是 Excel，有FileHeader/BodyText就是 HWP

识别完成后，parse()自动分派到对应引擎，用户侧只需一条命令：

npx kordoc 문서.hwpx -o 문서.md

四大引擎逐个拆解

HWP 3.x 引擎：破译 90 年代的"二进制考古"

这是最古老、也最棘手的一个引擎，实现位于 src/hwp3/。它的挑战在于：

• 单一二进制流：没有现代容器的目录结构，文档由 30 字节签名 + 128 字节 DocInfo + 1008 字节 DocSummary + 可压缩的 Body 顺序拼接而成（见 src/hwp3/records.ts）
• JOHAB 字符集：韩文用"初声·中声·终声"三个 6 位代码组合表记，kordoc 内置 src/hwp3/johab.ts 把组合字还原为标准 Unicode 音节，另附5,893 个汉字/符号的查找回退
• 表格按几何复原：HWP3 不存行列结构，只存每个单元格的 x/y/w/h 坐标，src/hwp3/table.ts 通过坐标推断行/列边界与合并关系
• 加密文档：1996 年版的打开密码由 src/hwp3/crypto.ts 负责解密

HWP 5.x 引擎：韩国公文主战场的重火力

HWP 5.x 是韩国政府日常办公的主力格式，引擎核心在 src/hwp5/parser.ts。它的技术要点：

• 记录流（record stream）：正文是二进制记录序列，每条记录带 4 字节头（tagId 10 位 + level 10 位 + size 12 位），压缩记录用 zlib 解压——见 src/hwp5/record.ts
• 21 种控制字符：表格、绘图、公式、脚注、页眉等都以控制字符嵌入段落流，由 src/hwp5/body.ts 分派处理
• 损坏文件容错：CFB 容器损坏时，src/hwp5/cfb-lenient.ts 走宽松解析路径尽力抢救
• 分发用文档解密：政府常见的"分发用 HWP"采用 MSVC LCG + AES-128 ECB 双重保护，src/hwp5/aes.ts 为纯 JS 实现，离线可用

HWPX 引擎：现代开放格式，功能最全

HWPX 本质是"打包成 ZIP 的 XML 文档"，是 kordoc 功能覆盖最深的引擎（src/hwpx/parser.ts 为入口，实现拆分为 8 个模块）：

• 节式 XML 遍历：src/hwpx/section-walker.ts 以段落/表格/图形"相互递归簇"的方式遍历节 XML，支持嵌套表格与合并单元格
• 样式驱动标题识别：src/hwpx/styles.ts 从 head.xml 解析样式与编号规则，自动识别标题层级
• 损坏 ZIP 自愈：中央目录损坏时直接扫描 Local File Header 重建结构（src/hwpx/zip-sections.ts）
• 附加能力：打开密码、表单自动填写（HWPX 是唯一支持"原始格式保留填表"的格式）、Markdown 反向生成 HWPX、布局保真渲染

HWPML 引擎：轻量 XML 变体

HWPML 是 XML 化的 HWP 试验格式，由 src/hwpml/parser.ts 负责。特点：

• 通过ParaShape的HeadingType属性识别标题（大纲级 1~6 直接映射 Markdown 标题）
• 支持合并单元格表格
• 内置 50MB 上限与表格 5000 行 × 500 列的 DoS 防御

统一的秘密：IR 中间表示

四套引擎"殊途同归"的关键在于IR（Intermediate Representation）模式，详见 docs/architecture.md：

Buffer → detectFormat()（魔法字节）→ 格式专属引擎 → IRBlock[] → blocksToMarkdown() → Markdown

无论底层是二进制流还是 XML，四个引擎都先把文档归一化为同一套IRBlock[]（段落、标题、表格、图片……），再由统一的 Markdown 生成器输出。这带来两个实际好处：

1. 输出质量一致：HWP3 里一个 1997 年的表格和 HWPX 里的嵌套表格，产出的 Markdown 管道表格式完全一致
2. 下游能力共享：RAG 分块、新旧文档对比（diff）、表单识别、个人信息脱敏等功能全部建立在 IR 之上，四种格式通吃

如何选择：一张速查表

验证数据：不是"能读"，是"读对"

引擎可靠性有硬指标背书（完整方法见 docs/benchmarks.md）：

• HWPX：2,286 份文档、9,865 个可见表格，结构一致率100%
• HWP 5.x ↔ HWPX 配对：1,120 对文档、4,258 个表格，跨格式表格结构一致率100%
• PDF 对照：744 对样本文字还原率 99.83%

上手只需两步

npm install kordoc npx kordoc 문서.hwpx -o 문서.md

更多选项（页码范围、JSON 输出、OCR、批量并行）请参阅 docs/usage.md。四种格式、四套引擎、一条命令——把韩文文档地狱交给 kordoc，你只管拿 Markdown。

【免费下载链接】kordoc모두 파싱해버리겠다 — 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项目地址: https://gitcode.com/gh_mirrors/ko/kordoc