kordoc

本地服务

github.com生产力2.8k今天更新

代码仓库访问官网

关于 kordoc

kordoc 是面向韩文文档处理的库、CLI 和 MCP 服务，可将多种文档转换为 Markdown 与结构化数据，也支持编辑、生成和检验。它覆盖 HWP、HWPX、PDF、Office 文件及图像，并提供本地 OCR。

主要功能

01解析文档为 Markdown 和结构化数据
02支持 HWP、HWPX、PDF 和 Office 格式
03比较文档并保留格式编辑
04生成文档并填写表单
05检查文档并遮盖个人信息
06本地 OCR 与预览

适用场景

01将 HWP 或 PDF 转为 Markdown
02比较不同版本的文档
03从模板填写公文表单
04为 RAG 准备结构化文本块

MCP 相关

kordoc 提供 MCP 服务，向 MCP 客户端开放 18 个用于解析、比较、生成、检验和渲染的工具。`npx -y kordoc setup` 可为已安装的客户端注册 MCP。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "chrisryugj-kordoc": {
      "command": "npx",
      "args": [
        "-y",
        "kordoc"
      ]
    }
  }
}

启动命令npx -y kordoc

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmkordoc4.24.16stdio

工具

收录的工具列表 · 更新于今天

参数	类型	必填	说明
ocr	any	否	对扫描件/图像 PDF 文本进行 OCR（内置 PP-OCRv5 korean，首次使用时自动下载约 18MB）。true=仅识别没有文本层或文本层损坏的页面，正常页面保持不变。"force"=即使存在文本层也忽略，并强制重新识别所有页面。如果 parse 结果中有 NEEDS_OCR 警告，请使用此选项重试。
plain	boolean	否	纯文本 Markdown——仅保留文字，不包含图片占位符、链接 URL、下划线/粗体标记（保留标题、列表和表格结构，默认关闭，对应 CLI --plain）。
tables	boolean	否	PDF 表格检测（默认 true；设为 false 可关闭，对应 CLI --no-tables）。对于因将边框框误识别为表格而导致阅读顺序颠倒的文档（如双栏试卷），仅提取符合自然阅读顺序的文本（#64）。
password	string	否	受密码保护文档的打开密码（#59；支持 HWPX、HWP3、HWP5。解析因 ENCRYPTED 失败时，请使用此选项重试。韩컴 DRM 保护的文档不适用）。
file_path	string	是	要解析的文档文件绝对路径（HWP、HWPX、PDF、XLSX、DOCX、PNG/JPG/WebP）。
formula_ocr	boolean	否	启用 PDF 公式 OCR（MFD+MFR ONNX，首次使用时自动下载约 155MB 的模型，对应 CLI --formula-ocr）。
html_tables	boolean	否	将所有表格转换为 HTML——包括管道表格，并为每个标签换行缩进（默认关闭，对应 CLI --html-tables）。
script_tags	boolean	否	将上标/下标表示为 <sup>·<sub>，避免将"10⁴ m²"展开为"104 m2"——默认：HWPX、HWP、DOCX 开启，PDF 关闭（论文和公式 PDF 建议设为 true）；设为 false 时全部输出为纯文本。对应 CLI --script-tags / --no-script-tags。
table_format	enum	否	"gfm"：所有表格均输出为 GFM 管道表格，不使用 HTML——单元格内的表格会移出并作为独立表格置于父表之后，并用 <!-- <table id parent_id /> --> 标记保留关联关系（用于 RAG 索引；不能与 html_tables 同时使用；对应 CLI --table-format）。gfm
keep_layout_tables	boolean	否	保留不可见边框的布局表格，维持原始表格结构（默认关闭=按可见内容处理：框架视为文本，用单元格拼成的分数视为公式）。若要生成可通过 patch_document 还原的编辑版本，请开启此选项（CLI --keep-layout-tables）。
remove_header_footer	boolean	否	自动移除 PDF 页眉/页脚（默认 true；设为 false 可关闭，对应 CLI --no-header-footer）。
keep_empty_paragraphs	boolean	否	保留空段落 — 正文保留空 paragraph 块，表格单元格保留空行（#57，默认关闭，对应 CLI --keep-empty-paragraphs）
dedupe_running_headers	boolean	否	去除 HWP5 布局表中跨页重复的运行页眉（默认关闭 — 注意避免误删各附件重新编号的内容，对应 CLI --dedupe-headers）
keep_trailing_empty_cols	boolean	否	保留表格最右侧的空列（格式填写栏）（#47，默认关闭：裁剪末尾空列，对应 CLI --keep-empty-cols）
include_field_placeholders	boolean	否	也输出未填写的占位符说明 — 保留空白格式文档中各栏的用途（#92，默认关闭，对应 CLI --include-field-placeholders）

详细介绍

kordoc

把一切都解析出来。

这是韩国数一数二的“文档地狱”。一位在那里熬过 7 年的公务员开发了它。

将 HWP 3.x·5.x、HWPX、HWPML、PDF、XLS·XLSX、DOCX、PPTX、PNG·JPG·WebP 转换为 Markdown 和结构化数据。可用作库、CLI 或 MCP 服务。

English · 详细用法 · 基准测试 · 变更日志

kordoc 将同一法规附表作为 HWP·HWPX·PDF·扫描图像输入时的实际输出

_{这是将同一份法规附表以 HWP·HWPX·PDF·扫描图像输入时的实际输出。四种情况下，合并单元格（rowspan·colspan）都会被识别为结构相同的表格。扫描图像会自动启用 OCR。}

📊 PDF 公开基准测试综合得分 0.964：opendataloader-bench 的 200 份文档测试中，得分高于公开排行榜上的 12 个解析器（4.22.14 测得）。测量条件
🇰🇷 韩国公文表格结构 100%：原始 HWPX 的 2,424 份文档中，所有 10,342 个可见表格的结构均匹配。验证结果

如果觉得有用，请在 GitHub 点一个 ⭐。这能帮助其他人找到这个工具。

视频：公开基准测试测量过程（2026-09-27 版，1 分 31 秒）· 批量填写表单演示

安装

Node.js 20 或更高版本 · macOS / Linux / Windows

npm install kordoc

无需安装即可通过 npx kordoc 运行 CLI。PDF·OCR 依赖项默认安装；若通过 --omit=optional 排除，则相应功能会受到限制。

连接到 AI Agent

npx -y kordoc setup

在已安装的客户端中注册 MCP，例如 Claude Desktop·Claude Code·Cursor·Codex。重启客户端后，即可使用 18 个工具，用于解析·比较·生成·校对·渲染等操作。

Claude Code 插件：

/plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc

手动注册 MCP 和安装问题排查

快速开始

CLI

npx kordoc 문서.hwpx -o 문서.md
npx kordoc *.pdf --jobs 4 -d ./결과
npx kordoc 문서.pdf --format json --pages 1-3
npx kordoc 스캔본.pdf --ocr -o 스캔본.md
npx kordoc generate 보고서.md --preset 보고서 -o 보고서.hwpx
npx kordoc fill --template gian -j 값.json -o 기안문.hwpx
npx kordoc lint 보고서.hwpx --gate --preset 보고서

--jobs 用于按文件并行转换，也会增加内存使用量。并行转换指南

JavaScript / TypeScript

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

const result = await parse("문서.hwpx")
if (result.success) {
  console.log(result.markdown)
  // result.blocks: 구조화 데이터, result.metadata: 문서 정보
}

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

解析选项·API·表单·渲染示例

主要功能

操作	功能
读取	文档 → Markdown·IR·逐页正文·RAG 分块，本地 OCR
比较·编辑	按块·单元格比较，保留 HWPX·HWP 格式的补丁，按样例格式原样写入新内容
编写	Markdown → HWPX，公文预设·部门格式样例（`--template`）、表格·公式·图表
表单	填写字段·占位框，两种标准起草文件，盖章
校对	拼写规范·公共语言，结构·AI 文风门禁，预算计算依据核算，按块校对打开的文档（`lint-blocks`）
查看·安全	HWPX·HWP 预览·区域提取，个人信息遮盖

用于保留格式补丁的 Markdown 可通过 --keep-layout-tables 提取。无法应用的编辑会报告跳过原因。保留格式编辑 · CLI 全部功能

验证结果

4.22.14 · 2026-10-19 验证。基于固定语料库和参考标准测得的结果。

对象	规模	结果
HWPX	2,424 份文档 · 10,342 个表格	表格结构匹配 10,342/10,342 · 100%
HWP 5.x ↔ HWPX	1,130 对 · 4,315 个表格	配对文档的表格结构匹配 100%
PDF 正文	744 对	字符还原率 99.879% · 准确率 99.670% · 阅读顺序 99.247% · 词组 F1 99.049%
PDF 表格	708 对 · 2,331 个表格	表格检测率 99.87% · 结构匹配 98.16% · 单元格 F1 0.9918
HWPX 重新排版	多行段落 25,187 个（12 个文件夹）	所有行首匹配 24,941/25,187 · 99.02%
PDF 嵌套表格（文本层）	29 份文档 · 101 个表格	结构·单元格内容 101/101 · 100%
法规附表	272 份 · 346 个表格	HWP 346/346，PDF 342/346 · 98.84%
PDF 整体	1,911 份文档中评测 1,729 份	正文覆盖率 99.80%
OCR	53 份文档 · 102 页	CER 0.0409 · 字符还原率 99.02%
opendataloader-bench	200 份 PDF 文档	默认综合得分 0.964 · 关闭 OCR 0.939

表格结构得分、单元格内容和屏幕还原是不同指标。嵌套表格 100% 仅适用于上述 101 个表格，并不代表所有 PDF·排版结果都完全匹配。评测范围·排除标准·各选项数值·复现方法见基准测试详情。

자주 묻는 질문

Q. HWP·HWPX 파일을 Markdown으로 바꾸려면? npx kordoc 문서.hwp -o 문서.md 한 줄입니다. 한컴오피스 없이 파일을 직접 읽으며, 여러 파일은 npx kordoc *.hwpx -d ./output으로 한 번에 바꿉니다.

Q. Claude·Cursor 같은 AI가 한글 문서를 읽게 하려면? npx -y kordoc setup으로 MCP를 등록하면 AI가 파일 경로만 받아 HWP·PDF·엑셀을 읽고, 비교하고, 양식을 채웁니다.

Q. 인터넷이 막힌 폐쇄망에서도 되나요? 됩니다. KORDOC_OFFLINE=1이 외부 통신을 모두 막고, OCR도 API 키 없이 로컬 CPU에서 돕니다. 폐쇄망 설치

Q. RAG 색인용으로 쓸 수 있나요? --format chunks가 제목 경로를 붙인 구조 청크와 독립 표 청크를 냅니다. 표를 HTML 없이 받으려면 --table-format gfm(API는 tableFormat: "gfm")을 씁니다. Python·Java에서는 Python SDK·Java SDK로 부릅니다.

Q. OCR 줄 좌표나 다른 모델이 필요하면? --ocr --ocr-lines --format json이 줄별 상자·신뢰도를 내고, --ocr-det·--ocr-det-long-side로 검출 모델과 해상도를 고릅니다. OCR 줄·모델 선택

문서·보안

상세 사용법: 전체 CLI·MCP 도구·API·지원 포맷
Java SDK · Python SDK: 상주 엔진 워커로 Java·Python 시스템에서 파싱 (워커 프로토콜)
공문서 생성 가이드 · 아키텍처
폐쇄망 설치: KORDOC_OFFLINE=1, MCP 접근 범위 KORDOC_ROOT
보안 정책 · 라이선스 MIT · 오픈소스 고지

만든 사람

대한민국 지방공무원. 광진구청에서 7년간 HWP 파일과 싸우다가 이걸 만들었습니다. 5개 공공 프로젝트에서 수천 건의 실제 관공서 문서를 파싱하며 검증했습니다.

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

版本	主要变更
4.24.1	校对修复：块校对中的稀疏表格内存暴涨·千韩元规则二次时间复杂度·预算核算（列表行·小计 (A)·比例行），阻止 `generate --template` 覆盖样例
4.24.0	按块校对 `lintBlocks`：将打开的文档中的段落·表格单元格作为块传入后，按块 id·块内位置返回问题（CLI `lint-blocks`、MCP `lint_document`、工作器、Python SDK）
4.23.1	样例生成中的标题表格签字栏按职务划分，修复计算依据行·表格单元格中的千韩元单位误报
4.23.0	根据部门格式样例生成新文档（`generate --template`），校对预算文档（`lint --budget`），MCP `lint_document`
4.22.18	修复 kordoc 生成报告中的标题样式·章节横幅·摘要框补丁，以及修复修订跟踪 HWP 补丁结果在 한글 中不可见的问题

kordoc

关于 kordoc

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

kordoc

安装

快速开始

CLI

JavaScript / TypeScript

主要功能

验证结果

最近更新

자주 묻는 질문

문서·보안

만든 사람

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？