chrisryugj/kordoc · 上手攻略

  • 仓库：chrisryugj/kordoc
  • 链接：https://github.com/chrisryugj/kordoc
  • 分类：agent / RAG 文档解析
  • 作者：spark
  • 更新：2026-10-14

§0 三证 checklist

  • ✅ GitHub URL 已 fetch（web_fetch 200 OK）
  • ✅ README 主模块 anchor：CLI / MCP / 라이브러리 / 벤치마크 / CHANGELOG 全部已读
  • ⚠️ 顶会 venue 不适用（工程工具型仓库，无论文锚点）

§1 这是什么 / 解决什么问题

kordoc 是一个专门解决"韩文办公文档 → LLM 可消费格式"这一长尾问题的工具，由在韩国光进区厅与 HWP 文件搏斗 7 年的公务员开发。它针对的不是泛用 PDF 解析（这块已经有 Marker、Unstructured、Mistral OCR 等），而是韩文圈独有的格式生态：

  • 韩文专有格式：HWP 3.x、HWP 5.x、HWPX、HWPML（一手 4 类）
  • 标准办公格式：PDF、XLS/XLSX、DOCX、PPTX
  • 图像：PNG、JPG、WebP（带 OCR）

它做的事不是单纯的"转文本"，而是把办公文档转成结构化 IR + Markdown + 面向 RAG 的 chunk，并提供反向Markdown → HWPX 的能力。配合 MCP server，可以直接把 Claude Desktop / Claude Code / Cursor / Codex 等 AI 客户端接到这套转换能力上，等同于给 AI 加上一双能读懂韩文公文的眼睛。

§2 快速安装

2.1 环境前置

  • Node.js ≥ 20（macOS / Linux / Windows 三平台均支持）
  • 不依赖 Hancom Office（한컴오피스）本体，直接解析文件
  • 默认安装含 PDF / OCR 依赖；不需要 OCR 时可加 --omit=optional 跳过以加快安装

2.2 最小化安装（CLI 即装即用）

npm install kordoc
# 或者不安装、直接 npx：
npx kordoc --help

2.3 接到 AI 客户端（MCP）

# 自动注册到 Claude Desktop / Claude Code / Cursor / Codex
npx -y kordoc setup

# Claude Code 插件市场安装
/plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc

setup 注册后需重启 AI 客户端，注册成功即暴露 17 个 MCP 工具（解析 / 比较 / 生成 / 渲染 / 表单填充 等）。

2.4 离线 / 封闭网络部署

环境变量 KORDOC_OFFLINE=1 阻断所有外部网络请求，OCR 也走本地 CPU（不依赖云端 API）。配合 KORDOC_ROOT 限定 MCP 访问目录可用于安全审计场景。

§3 核心用法（可直接复制）

3.1 CLI 一行转 HWP/HWPX

# 单文件
npx kordoc 문서.hwpx -o 문서.md

# 批量（并行 4 worker）
npx kordoc *.pdf --jobs 4 -d ./결과

# 输出 JSON + 指定页范围
npx kordoc 문서.pdf --format json --pages 1-3

# 扫描版 PDF → OCR → Markdown
npx kordoc 스캔본.pdf --ocr -o 스캔본.md

# Markdown 反向生成公文 HWPX
npx kordoc generate 보고서.md --preset 보고서 -o 보고서.hwpx

# 公文表单自动填充
npx kordoc fill --template gian -j 값.json -o 기안문.hwpx

--jobs 是文件级并行转换，会同时占用更多内存，机器小的话降到 2 即可。

3.2 Node.js SDK

import { parse, markdownToHwpx } from "kordoc"
import { writeFile } from "node:fs/promises"

const result = await parse("문서.hwpx")
if (result.success) {
  console.log(result.markdown)        // 转好的 Markdown
  // result.blocks  → 结构化数据
  // result.metadata → 文档元信息
}

const hwpx = await markdownToHwpx("# 추진계획\n\n본문", {
  gongmun: { preset: "보고서" },   // 公文 preset
})
await writeFile("보고서.hwpx", Buffer.from(hwpx))

3.3 RAG 用 chunk 输出

npx kordoc 문서.pdf --format chunks --table-format gfm -o chunks.json

--table-format gfm（API 中为 tableFormat: "gfm"）能让合并 / 嵌套表不用 HTML 也能用 GFM 管道表表达，索引系统直接吃；子表会以"父子独立表 + 封面"形式输出。

Python / Java 用户另有 sdk/python/、sdk/java/ 两个 SDK，可作为常驻 worker 进程被调用（协议见 docs/parse-worker-protocol.md）。

§4 典型适用场景

  1. 政府 / 公共部门 RAG 落地：直接把成堆的 HWP / HWPX 公文喂给向量库，不需要先人工转 PDF。
  2. 企业法务 / 合规：HWPX ↔ HWP 双向 diff、子段落级比较、自动生成新版本 patch（compare / patch --json）。
  3. AI 助手读韩文公文：通过 MCP 让 Claude / Cursor 直接读 HWP、填表单（fill）、做敏感性遮蔽（마스킹）。
  4. 离线 / 内网部署：KORDOC_OFFLINE=1 让金融、政务内网也能跑完整 OCR + 解析链路。
  5. 公文自动生成：Markdown 写正文，按 보고서 / 계획서 / 개조식 / 서울방침 preset 一键导出 HWPX，配合 fill 自动套版（标准 기안문两种）。
  6. PDF 公开榜单冲分：参看 opendataloader-bench 200 篇公开 PDF 综合 0.963（OCR 关闭仍 0.939），4.21.22 部署数据。

§5 坑与注意

  1. 版本号跳跃快：2026-09-29 → 2026-10-13 的 17 天内连续发了 v4.21.15 → v4.21.31 共 17 个小版本，多为 PDF 读取细节调整。生产环境最好固定主版本号（npm install kordoc@^4.21），不要锁 latest 到天。
  2. --jobs 不要乱开：worker 数太高会把 4GB 内存级别的 PDF 内存堆满。ocr 与 --jobs 共用要谨慎，光学识别任务的瞬时内存比纯文本转换高一个量级。
  3. 生成端的"摘要上框"规则严格：报告 / 计划书 / 개조식 / 서울방침 的引用块（> …）会被自动映射成"目的概要框"，且只接受≤3 行、单句（允许含逗号），写多即触发 warning。업무报告 用 > ▪ … 块，占位独立。覆盖前请先看 docs/gongmunseo-engine-spec.md。
  4. 渲染（reflow）并不完美逐页对齐：4.21.31 部署后쪽 수 일치 784 → 858/866、그림 위치 ±2pt 16.5% → 94.2%、글 위치 ±1.5pt 53.7% → 96.8%。少数边角 case（页眉 / 页脚 / 跨页框）仍会贴位偏移，--keep-layout-tables 有助于减少此类问题。
  5. CHANGELOG.md 真的要看：每周都有 PDF 쪽 번호 매김·어절 경계修复点，例如 v4.21.18 把 OCR 末尾空白字符的"行中段"重组成正确 어절，v4.21.15 解决了 "이루어⏎진다면" 这类 줄 끝 띄어쓰기被错误粘连的问题。
  6. GROWTH 외부 PDF 데이터 측은 OCR 끄는 편이 안전：opendataloader-bench 측정값은 기본값 0.963、OCR 끔 0.939 — 公共 PDF가 많으면 OCR을 끄는 게 점수가 약간 더 좋습니다（--no-ocr）。
  7. 填充表单（fill）只换同行：根据 v4.21.26~28 的更新，空字段能正常填，但 셀 자체의 행 추가 / 삭제 / 리터럴 <br> 의 모호한 매칭은跳过。需要在文档內编辑表格请用 patch --json。

§6 与同类对比

工具 强项 弱项 / 差距
kordoc 韩文办公套件（HWP·HWPX·PDF·Office·图像 + 反向 HWPX 生成 + MCP 生态） 비한글 문서 처리는 여타 도구 대비 우위不明显；生成端的细节仍需逐 preset 调节
Marker / MarkItDown 通用 Markdown 化、纯 Python 部署简单 对 HWP / HWPX 完全不识别；韩文 PDF 어절 F1 0.98 上下
Unstructured 生态完整、多分区支持 韩文特定的 쪽 넘김 / 어절 / 공문서 양식逻辑无法覆盖
Mistral OCR 印刷质量 PDF 强 API 依赖 / 封闭网络不宜 / 韩文公文体例不熟
PDFPlumber / PyMuPDF 表格 + 像素层可控 需要自行实现 读取순서 / 쪽 넘김 / 어절 정리，无法直接生成 HWPX

主要定位差异：竞品是"Generic PDF → Markdown"工具，kordoc 是"韩文办公全程"工具——从 HWP/HWPX 正反向到 PDF/OCR 到公文表单填写一条龙。

§7 一句话推荐

如果你或你的团队需要让 AI 读懂 / 写出韩文 HWP / HWPX / 公文（尤其是公共部门 / 法律 / RAG 场景），kordoc 是当下唯一同时具备正反向转换 + MCP 集成 + 封闭网络可跑 + 自带表单 / diff / 마스킹的开源工具——直接 npx kordoc 문서.hwpx -o out.md 起步，需要 AI 集成再追加 npx -y kordoc setup。