kordoc (Chrisryugj)

科尔多克

全部挖掉。

](https://www.npmjs.com/package/kordoc) 

*如果在大韩民国是第二个的话，那将是可悲的文件地狱。在那里坚持了7年的公务员创造的。*

HWP3.x/5.x、HWPX、PDF、XLS、XLSX、DOCX-解析、比较、分析和生成来自政府部门的所有文档。

英语

kordoc 데모

______________________________________________________________________

-安装30秒（AI代理联动）

MacOS/Linux/Windows通用只需要.Node.js 18+。

npx -y kordoc setup

交互式向导包括：

1. 选择您正在使用的AI客户端编号（Claude Desktop/Cursor/Claude Code/Windsurf/VS Code/Gemini CLI/Zed/Antigravity-安装的是 [감지됨] 显示）
2. 自动修补配置文件→重新启动客户端

Windows也会自动 cmd /c npx 包装。不需要手动编辑JSON。重新启动后，将使用8个文档解析工具（parse_document, parse_table, fill_form 等）活性化。

如果只使用CLI 无需安装 npx kordoc 立即使用。下面 命令行界面 请参见部分。

MODULE_NOT_FOUND / Cannot find module ...\dist\cli.js 浮起来的话：过去已破坏的全局安装仍然存在。向下解决： ``powershell npm uninstall -g kordoc npx -y kordoc@latest setup ``

在Windows PowerShell中 npx.ps1 파일을 로드할 수 없습니다 · PSSecurityException 等我醒来：没有PowerShell默认安全策略签名 .ps1 阻止的标准行为（与kordoc无关）。你可以用下面的一个。 方法1-在命令提示符（cmd）窗口中运行 （最安全） 窗口键→ cmd 搜索→Enter→在黑窗口中： `` npx -y kordoc setup ` **方法2-仅放宽一次PowerShell执行策略** 管理员权限PowerShell： `powershell Set-ExecutionPolicy -Scope CurrentUser RemoteSigned ` 之后重新启动PowerShell→ npx -y kordoc setup` 原封不动。

______________________________________________________________________

💡 可以用kordoc做什么？

超越单纯的文本提取， 处理公文的所有过程自动化。

• 📄 任何文档都可以标记为: HWP3 （旧版本）， HWP（5.x）， HWPX, HWPML, PDF, XLS, XLSX, DOCX 文件立即 Markdown转换为。AI（LLM）使文档处于最佳阅读和分析状态。
• 📊 复杂的表（Table）完整再现：分析无线PDF或复杂合并的HWP表格结构，并将其恢复到正确的标注表。
• 🔍 自动生成新旧对照表：分析两个文档的差异，一目了然地显示发生了什么变化。（还可以比较HWP和HWPX！）
• 📝 将Markdown重新转换为HWPX：重新生成AI创建的报告表单（HWPX）。现在，复制-粘贴将从Nogada中解放出来。
• 自动填写表单：如果您在公文表单模板（申请表、报告）中输入值，则会自动填空。100%保留原始格式（字体、大小、对齐方式）。
• 🤖 AI代理集成（MCP）: Claude, Cursor直接从 kordoc可以调用读取和编码文档。

______________________________________________________________________

v2.7.1更改

• 🕰️ 添加HWP 3.0（旧版本）解析器 -1996~2002年Hancom使用的单一binary格式（"HWP Document File V3.00" 特征）文本提取。现有kordoc拒绝的旧版本判决书/公文等可以进行搜索索引。商用组合型（johab）→Unicode+5893个汉字/符号lookup。表cell/前言/脚注的nested paragraph递归提取。 @爱德华金/rhwp 将的Rust实现移植到TypeScript。

v2.5.0更改

• 🏛️ 创建与MacOS Hancom Office兼容的HWPX (#4) — markdownToHwpx() 解决了制作的HWPX被MacOS Hancom拒绝的问题，称“文件被破坏”。以完全规范的形式从最小螺旋线重写表XML。 ` 必需属性10种+ ///, 里面 包装器+ ///，paragraph包装。 Preview/PrvText.txt 添加+ borderFill` 添加id=1（SOLID 0.12 mm）。
• 🔓 用于HWP 5.x部署的文档COM回退 (#25) — .hwp 在二进制中，“此文档是用于分发的更高版本的文档……”在只有警告占位符的情况下，如果是Windows+Hancom Office环境，则自动 HWPFrame.HwpObject 用COM API重试。v2.4.0的HWPX DRM回退基础架构 .hwp 扩展到。

v2.4.0 변경사항

• 🔓 自动提取用于部署HWPX DRM的文档 -使用Hancom Office COM API自动提取与公共部署DRM相关的HWPX文件。 manifest.xml检测到加密→ HWPFrame.HwpObject的 GetPageText按页提取→Markdown转换。在Windows+Hancom Office安装环境中无需设置即可工作。

v2.3.0 변경사항

• 📄 添加HWPML2.x解析器 -基于XML的编译文档（.hwp XML方式）解析支持。 npx kordoc 在中 지원하지 않는 파일 형식 现在可以将出现错误的基于XML的公文转换为Markdown。自动区分HWP5.x二进制文件（检测XML签名）。
• 🧩 嵌套表格标记 -在HWPX/HWP5中，位于单元内部嵌套表所在的位置 [중첩 테이블 #N] 插入标记。大的嵌套表（≥3行+≥2列）分开为单独的块，小的在单元格内平坦化。HWP5将以前内容完全丢失的恢复为标记。
• 🖼️ 修复HWPX图像提取错误 — binaryItemIDRef不带扩展名（"image1"）解决了从保存的HWPX提取图像失败的问题。恢复到ZIP中的文件名regex匹配。
• 📄 改进PDF页眉/页脚检测 -文本重复模式+y坐标群集混合。基于位置检测每个页面的动态标题（章节名等）。检测区域从10%扩展到12%。

v2.2.4 변경사항

• 📝 自动填充表单（Form Filler） -自动在文档表单模板中填充值。标签-值单元格模式，复选框（□→☑，括号空格（일반( )통→일반(3)통），注释（(한자：)→(한자：金)）支持。
• 🏛️ HWPX原始格式保留模式 — fillHwpx()通过直接操作HWPX XML，在保留字体、大小、对齐等原始格式100%的情况下，只替换值。
• 📊 合并单元格HTML表格输出 — colspan/rowspan使用HTML代替GFM ``输出到以保存结构。
• 🔧 markdownToHwpx格式增强 -大幅改善反向转换时的格式支持，如heading/bold/italic/table。
• 🤖 MCP fill_form工具 -添加新的MCP工具，AI代理可以直接填写表单（共8个）。

v2.2.1 변경사항

• 🔧 改善标记渲染 -GFM特殊字符（~）避免转义导致删除线错误分析，表单元格内 | 字符转义，嵌套表格文本分隔符 | → / 通过更改GFM解析器防止冲突。
• 📝 段落间距正常化 -通过在paragraph块之间插入空行，从标记行渲染为单独的段落。

v2.2.0 변경사항

• 🛡️ 加强安全7件 -防止XLSX/DOCX Billion Laughs（XXE）、阻止Watch SSRF重定向和十进制IP、symlink、防止HWP5 lenient decompression bomb、CFB FAT扇区上限、buildTableDirect内存暴增。
• 💥 防止Crash — Math.min/max(...spread) 修改堆栈溢出（15个），限制Watch并发处理（MAX_CONCURRENT=3）。
• 🐛 提高准确性 -Levenshtein相同长度相似度1.0错误修复，MCP parse_metadata XLSX/DOCX错误分类修复，PDF字体大小统计内存优化（40MB→~50条目）。
• 📦 品质 -CLI JSON Uint 8 Array base64转换， isPathTraversal 修改合法文件名错误。

v2.1.0 변경사항

• 📄 解析大型HWPX政府文件 — `

>` 修改结构中缺少嵌套表的解析。

• 📰 检测PDF二级布局 -检测多段论文、报告的栏目结构，按阅读顺序提取。
• 🛡️ 增强输入验证 -字体大小NaN/负数后卫，colSpan/rowSpan NaN后卫。

v2.0 변경사항

• 🔓 支持部署（有限阅览）HWP解析 -官方锁定用于分发的HWP文件现在也将被解析。AES-128ECB解密，纯JS实现。 rhwp（MIT）算法移植。
• 修复损坏的HWP文件 -将标准CFB模块拒绝的文件直接恢复到FAT/目录解析。移植rhwp LenientCfb Reader。
• 提取HWP 5脚注/美洲/超链接 -连接脚注正文文本、提取超链接URL和XSS杀菌。
• 修改HWPX表合并密林 -修改colspan/rowspan网格计算错误。
• 增强的安全性 -验证CFB扇区大小，三重路径一致应用sanitizeHref。

v1.8.0 변경사항

• 添加XLSX解析器 -解析Excel电子表格。支持共享字符串、合并单元格和多页。按图纸创建heading+table块。
• 添加DOCX解析器 -解析Word文档。基于样式的标题、编号（列表）、脚注、超链接、图像提取、vMerge/gridSpan表格合并。
• 大幅改善挖孔质量 -PDF/HWPX/HWP5/XLSX前格式质量分数73→93分。
• 修改了17条生产评论 --CLI --no-header-footer 标志反转错误，允许MCP XLSX/DOCX扩展名，ZIP bomb保护共享实用化，href XSS杀菌增强，PDF timeout计时器清理，HWP5BinData O（n）优化，cluster index Of O（n²)→O（n）、SSRF IPv6阻止等。

v1.7.x 변경사항

• 图像提取（HWP/HWPX） -从ZIP条目和HWP5 BinData流中提取二进制图像。
• 部分解析（Graceful Degradation） -单个页面失败不会中断整个解析。
• 进度回调 — onProgress 回调。从CLI [3/15 pages] 显示形状。
• 直接输入文件路径 — parse("path/to/file.hwp") 字符串过载。
• 过滤PDF标题/脚注 — removeHeaderFooter 选项。
• 增强的安全性 -ZIP bomb跟踪，SSRF防护，XSS防护，空字节检测，PDF超时。
• pdfjs dist v5호환 -响应constructPath运算符格式的更改。

v1.6.1 수정사항

• 修改HWP5表单元格偏移 -修复LIST_HEADER解析时因2字节偏移密写而错误地将rowAddr读取为colSpan的致命错误。解决了3排桌子变成6排的问题。基于colAddr/rowAddr的直接放置提高了合并表的准确度。
• 修改HWP5TAB控制字符 -TAB（0x0009）缺少行内控件的14字节扩展数据跳过 ࣐Ā 修正了输出垃圾字符的错误。

v1.6.0 기능

• 基于群集的表格检测（PDF） -从无线PDF中以文本对齐模式推论表格结构。使用baseline组ping+X坐标群集检测两列或更多表格。基于线的检测失败时的中间层回退。
• 检测韩语特殊表格 — 구분/항목/종류/기준 等，将韩国公文key-value模式自动转换为双列表格。
• 韩国语语节中断复原 -改善了PDF单元内按韩文字符呈现的细微差异处理。将单元格换行合并阈值扩展到8个字符，自动连接1个字符的调查。
• 过滤空表 -自动删除装饰线中的空白表格。

v1.5.0 기능

• 基于直线的表格检测（PDF） -移植OpenDataLoader核心算法。从PDF图形命令中提取水平/垂直线，将网格组织为交叉点，将文本映射为bbox overlap→单元格。自动检测colspan/rowspan。无线PDF是现有的人类回退。
• IRBlock v2 -6种块类型： heading, paragraph, table, list, image, separator。新建字段： bbox, style, pageNumber, level, href, footnoteText.
• 解析结果v2 — outline （文档结构）， warnings 添加（跳过的元素，隐藏文本）字段。
• PDF增强功能 -XY-Cut读取顺序、基于字体大小的标题检测、hidden text过滤（提示投射防御）、所有块的反弹框。
• HWP5改进 -CHAR_SHAPE解析、基于样式的标题检测、OLE/图像跳过警告。
• HWPX改进 -header.xml样式解析，超链接/脚注提取。
• 检测列表 -自动将表后面的编号段落转换为ordered list块。
• MCP服务器 -在parse_document响应中 outline, warnings 包括。

v1.4.x 기능

• 比较文档（Diff） -通过IR级块比较生成新旧对照表。HWP支持HWPX交叉格式。
• 识别表单 -自动从公文表中提取label-value对。姓名、所属、电话号码等。
• 结构化解析 — IRBlock[]和 DocumentMetadata直接访问。利用超出标注范围的数据。
• 页面范围 — parse(buffer, { pages: "1-3" }) -只需要快速浏览所需页面。
• 标记语言→ HWPX -反向转换。将AI生成的内容直接转换为公文。
• OCR集成 -基于图像的PDF也可以直接提供文本提取（Tesseract、Claude Vision等提供程序）。
• Watch模式 — kordoc watch ./수신함 -d ./변환결과 --webhook https://...
• 7个MCP工具 --parse_document、detect_format、parse_metadata、parse_pages、parse_table、compare_documents、parse_form
• 错误代码 — "ENCRYPTED", "ZIP_BOMB", "IMAGE_BASED_PDF" 等结构化错误处理

______________________________________________________________________

安装

npm install kordoc

# PDF 파싱이 필요하면 (선택)
npm install pdfjs-dist

快速入门

解析文档

import { parse } from "kordoc"
import { readFileSync } from "fs"

const buffer = readFileSync("사업계획서.hwpx")
const result = await parse(buffer.buffer)

if (result.success) {
  console.log(result.markdown)       // 마크다운 텍스트
  console.log(result.blocks)         // IRBlock[] 구조화 데이터
  console.log(result.metadata)       // { title, author, createdAt, ... }
}

文档比较（新旧对照表）

import { compare } from "kordoc"

const diff = await compare(구버전Buffer, 신버전Buffer)
// diff.stats → { added: 3, removed: 1, modified: 5, unchanged: 42 }
// diff.diffs → BlockDiff[] (테이블은 셀 단위 diff 포함)

也可以比较HWP与HWPX的交叉格式。

提取表单字段

import { parse, extractFormFields } from "kordoc"

const result = await parse(buffer)
if (result.success) {
  const form = extractFormFields(result.blocks)
  // form.fields → [{ label: "성명", value: "홍길동", row: 0, col: 0 }, ...]
  // form.confidence → 0.85
}

自动填充表单

import { fillForm } from "kordoc"
import { readFileSync, writeFileSync } from "fs"

const template = readFileSync("신청서.hwpx")

// HWPX 원본 서식 보존 모드 — 글꼴, 크기, 정렬 100% 유지
const result = await fillForm(template.buffer, {
  성명: "홍길동",
  주민등록번호: "900101-1234567",
  주소: "서울특별시 광진구 능동로 120",
}, { format: "hwpx-preserve" })

writeFileSync("신청서_작성완료.hwpx", Buffer.from(result.buffer!))
// result.filled → [{ label: "성명", value: "홍길동" }, ...]
// result.unmatched → 매칭 실패한 키 목록

创建HWPX（反向转换）

import { markdownToHwpx } from "kordoc"

const hwpxBuffer = await markdownToHwpx("# 제목\n\n본문 텍스트\n\n| 이름 | 직급 |\n| --- | --- |\n| 홍길동 | 과장 |")
writeFileSync("출력.hwpx", Buffer.from(hwpxBuffer))

页面范围

const result = await parse(buffer, { pages: "1-3" })      // 1~3 페이지만
const result = await parse(buffer, { pages: [1, 5, 10] })  // 특정 페이지

OCR（图像PDF）

const result = await parse(buffer, {
  ocr: async (pageImage, pageNumber, mimeType) => {
    return await myOcrService.recognize(pageImage)
  }
})

命令行界面

npx kordoc 사업계획서.hwpx                          # 터미널 출력
npx kordoc 보고서.hwp -o 보고서.md                  # 파일 저장
npx kordoc *.pdf -d ./변환결과/                     # 일괄 변환
npx kordoc 검토서.hwpx --format json               # JSON (blocks + metadata 포함)
npx kordoc 보고서.hwpx --pages 1-3                  # 페이지 범위
npx kordoc fill 신청서.hwpx -f '성명=홍길동,주소=서울' -o 결과.hwpx  # 양식 채우기
npx kordoc fill 신청서.hwpx -j values.json -o 결과.hwpx             # JSON 파일로 채우기
npx kordoc fill 신청서.hwpx --dry-run                               # 필드 목록만 확인
npx kordoc watch ./수신함 -d ./변환결과              # 폴더 감시 모드
npx kordoc watch ./문서 --webhook https://api/hook  # 웹훅 알림

MCP服务器（Claude/Cursor/Windsurf）

自动安装（推荐）:

npx -y kordoc setup

通过交互式检测AI客户端，自动修补配置文件。在Windows上 cmd /c npx 包装也是自动的。详细内容如下 30秒安装 节。

手动注册（MacOS/Linux）:

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

手动注册（Windows-Claude Desktop .cmd 找不到时）:

{
  "mcpServers": {
    "kordoc": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "kordoc", "mcp"]
    }
  }
}

8个工具：

API

核心函数

高级函数

类型

import type {
  ParseResult, ParseSuccess, ParseFailure, FileType,
  IRBlock, IRTable, IRCell, CellContext,
  DocumentMetadata, ParseOptions, ErrorCode,
  DiffResult, BlockDiff, CellDiff, DiffChangeType,
  FormField, FormResult, FillResult, HwpxFillResult, FillOutputFormat,
  OcrProvider, WatchOptions,
} from "kordoc"

支持的格式

保安

增强的生产级安全性：防止ZIP bomb、防止XXE/Billion Laughs、防止压缩炸弹、阻止路径循环、消除MCP错误、限制文件大小（500MB）。有关详细信息，请访问 安全.md 参考。

创建者

大韩民国地方公务员。在广津区政府与HWP文件斗争了7年后制作了这个。 在5个公共项目中解析并验证了数千份真实的官方文件。

许可证

麻省理工学院

该项目包括以下开源：

• rhwp （MIT，edwardkim）-用于HWP5部署的解密和lenient CFB解析算法
• OpenDataLoader PDF （Apache 2.0，Hancom Inc.）-PDF表格检测算法
• 循环流化床 （Apache 2.0，SheetJS）-HWP5 OLE2容器解析
• pdfjs分布 （Apache 2.0，Mozilla）-提取PDF文本
• Jzip （MIT、Stuart Knightley等）-基于ZIP的格式解析

有关详细信息，请访问 通知 请参考文件。