企业官网建设流程全解析

kordoc解析选项详解：OCR·页数·纯文本·HTML表格，17个参数逐个拆解

【免费下载链接】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、PDF、DOCX 等韩国办公文档一键转成 Markdown 的开源转换工具，而它 CLI 里藏着的 17 个解析选项才是真正决定转换质量的关键。本文带你逐个拆解--ocr、--pages、--plain、--html-tables等参数的作用、默认值和适用场景，帮你快速写出最合适的 kordoc 解析命令。

先搞清楚：选项都在哪里定义？

所有解析选项集中定义在 src/cli.ts 中，官方完整的 CLI 参考见 docs/usage.md。安装后无需配置，直接npx kordoc 文件.hwpx即可开始。

选项可以分成 4 大类：

一、内容范围类：页数与密码

1️⃣--pages：只转换指定页

npx kordoc 보고서.pdf --pages 1-3

支持1-3、1,3,5-7等多种写法（见 src/cli.ts）。PDF 和带排版缓存的 HWP 文件按真实物理页截取；没有缓存的 HWPX 按"章节近似"定位。做 RAG 切片或只处理合同某几页时非常实用。

2️⃣--password：打开加密文档

npx kordoc 잠긴문서.hwpx --password '密码' -o 결과.md

仅支持 HWPX / HWP3 / HWP5 的"打开密码"，韩方 DRM 加密不在范围内。解析选项如何传递到解析器，可以看 src/cli/convert.ts。

二、识别增强类：OCR 三件套 ⚡

扫描件转 Markdown 的救命参数，按强度递增排列：

3️⃣--ocr：按需 OCR

npx kordoc 스캔본.pdf --ocr

只对"扫出来的、没有文字层的页"启用内置 PP-OCRv5 韩语模型（约 18MB，首次自动下载）。这是处理扫描公文、扫描报表的最快方式。

4️⃣--ocr-force：强制全页 OCR

即使 PDF 有文字层也全部重新识别——适合"OCR 质量烂过原文字层"的老扫描仪文档。代价是速度明显变慢，按需使用。

5️⃣--formula-ocr：数式 OCR

npx kordoc 논문.pdf --formula-ocr

用 MFD+MFR ONNX 模型（约 155MB）把数学公式识别成$…$/$$…$$。处理学术论文、试题集时的必备选项。

💡 小贴士：完全无文字层的 PDF 直接转会得到IMAGE_BASED_PDF错误码，此时加上--ocr即可，错误码对照表见 docs/usage.md。

三、结构裁剪类：让输出更干净 🧹

6️⃣--plain：纯文本 Markdown

npx kordoc 보고서.hwpx --plain -o 결과.md

去掉图片占位符、链接 URL、加粗/下划线等装饰，只保留标题、列表和表格结构。做索引、喂 RAG 向量库时最干净——这也是官方文档推荐的"色인·RAG 용"选项（见 docs/usage.md）。

7️⃣--no-images：只留文字

不提取、不输出图片字节，跳过 PDF 的 PNG 编码，速度更快。适合纯文本归档。

8️⃣--no-tables：关闭 PDF 表格检测

双栏试卷这类文档，边框线会被误判成表格导致阅读顺序错乱（#64），加上它就能按自然阅读顺序输出纯文本。

9️⃣--no-header-footer：保留页眉页脚

kordoc 默认（3页以上）会自动剔除重复的 PDF 页眉页脚。如果页眉里有日期、文件编号这类有信息量的内容，用这个参数关掉清理。

🔟--keep-empty-paragraphs：保留空段落

默认会删掉空段落。HWPX 里"空行=格式"，需要原文段落数=输出行数时开启。

1️⃣1️⃣--keep-empty-cols：保留表格右侧空列

空白申请单末尾的"填写栏"空列默认会被裁掉，表单类文档建议开启（#47）。

1️⃣2️⃣--include-field-placeholders：保留未填写的填写提示

空白模板里"（ここに氏名を記入）"这类只在编辑时可见的填写提示默认不输出，开启后表单用途说明得以保留。

四、表格控制类：复杂表格不崩 📊

kordoc 的一大强项是 HWPX 公文表格 100% 结构还原，而下面几个参数决定了表格"保不保得住"：

1️⃣3️⃣--html-tables：全部表格转 HTML

npx kordoc 보고서.hwpx --html-tables -o 결과.md

所有表格（包括 Markdown 管道表格）统一输出为 HTML 表格，每个标签单独一行缩进。下游解析器对嵌套复杂表格兼容性更好时用。

1️⃣4️⃣--keep-layout-tables：保留无边界框架表格

默认按"视觉所见"输出——无可见边框的框架表格会被拆成纯文字段落。要拿到原始表格结构（尤其配合patch回写编辑）时必须加它：

npx kordoc 원본.hwpx --keep-layout-tables -o 편집.md

1️⃣5️⃣--script-tags/--no-script-tags：上下标开关

控制是否用<sup>/<sub>标记上下标。HWPX·HWP·DOCX 默认开启，PDF 默认关闭——处理论文、公式 PDF 时建议显式开启，避免 "10⁴ m²" 被展平成 "104 m2"。

1️⃣6️⃣--dedupe-headers：去重重复页头

HWP5 文档里每页重复出现的"跑页头"会累加，开启后去重。注意它可能误删附件重新编号，默认关闭。

1️⃣7️⃣--inline-images/--image-refs：图片两种走法

• --inline-images（仅 HWP5）：图片转 base64 data URI 直接嵌进 Markdown，单文件即走；
• --image-refs（配合--format json）：几百张图的文档避免 base64 撑爆内存，只留images/文档名/文件路径引用（#65）。

配套基础参数速查 🗂️

除 17 个解析选项外，还有 4 个基础输出控制参数同样高频：

三组实战命令模板

# 场景1：扫描件公文 → 干净纯文本 npx kordoc 민원서류.pdf --ocr --plain --no-images -o 민원.md # 场景2：HWPX 申请单 → 保留全部结构，供 patch 回写 npx kordoc 신청서.hwpx --keep-layout-tables --keep-empty-cols \ --include-field-placeholders -o 편집.md # 场景3：批量 PDF + 并行 + RAG 切块 npx kordoc *.pdf --jobs 4 -d ./결과/ --format chunks

总结：一张表记住 17 个参数

掌握这 17 个参数，基本能覆盖 90% 的文档解析场景。更多参数细节、API 用法和错误码对照，请查阅官方文档 docs/usage.md 与 README.md。

【免费下载链接】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