kordoc

Распарсим всё — разберём их все.

Корейские документы — настоящий ад. Это решение создал госслужащий, который провёл в этой системе семь лет.

Преобразуйте HWP 3.x/5.x, HWPX, HWPML, PDF, XLS/XLSX, DOCX, PPTX и PNG/JPG/WebP в Markdown и структурированные данные. Используйте kordoc как библиотеку, CLI или MCP-сервер.

한국어 · Руководство по использованию · Результаты тестирования · История изменений

📊 Общий результат 0.963 в открытом тестировании PDF — opendataloader-bench, 200 документов. В сравнении от 2026-09-29 занял первое место среди 12 опубликованных парсеров. Подробности измерений
🇰🇷 Совпадение структуры таблиц в корейских документах — 100%: обработаны все 10,461 видимые таблицы из 2,429 исходных документов HWPX. Проверка версии 4.22.0

Если этот инструмент экономит ваше время, поставьте ему ⭐ на GitHub — так его смогут найти и другие.

▶ Нажмите, чтобы посмотреть видео на YouTube. Озвучка на корейском языке.

Новое видео: kordoc занял первое место в открытом тестировании · 2026-09-27 · 1 мин 31 сек · корейский язык

Установка

Node.js 20+ · macOS / Linux / Windows

npm install kordoc

Запустить CLI без глобальной установки можно командой npx kordoc. Зависимости для PDF/OCR устанавливаются по умолчанию; если исключить их с помощью --omit=optional, соответствующие функции будут недоступны.

Подключение AI-агента

npx -y kordoc setup

Команда регистрирует MCP в установленных клиентах, таких как Claude Desktop, Claude Code, Cursor и Codex. Перезапустите клиент, чтобы получить доступ к 17 инструментам для разбора, сравнения, создания, рендеринга и других задач.

Плагин Claude Code:

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

Инструкция по ручной настройке MCP и устранению проблем при установке

Быстрый старт

CLI

npx kordoc document.hwpx -o document.md
npx kordoc *.pdf --jobs 4 -d ./output
npx kordoc document.pdf --format json --pages 1-3
npx kordoc scan.pdf --ocr -o scan.md
npx kordoc generate report.md --preset report -o report.hwpx
npx kordoc fill --template gian -j values.json -o draft.hwpx

Параметр --jobs обрабатывает файлы параллельно и увеличивает расход памяти. Подробнее о пакетном преобразовании

Для наборов стилей report, plan, gaejosik и bangchim цитата в блоке после заголовка # (> …하고자 함) становится сводным блоком. В gaejosik при включённой обложке (это настройка по умолчанию) такой блок размещается под заголовком обложки на первой странице основного текста; при cover: false первый заголовок # становится заголовком главы, а цитата остаётся примечанием ※. Сводка должна состоять из одного предложения (запятые допустимы) и занимать не более трёх строк. Если она длиннее или состоит из нескольких предложений, появится предупреждение. Для набора стилей ministry цитаты в блоках > ▪ … оформляются как сводные блоки с показателями эффективности независимо от места в документе.

JavaScript / TypeScript

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

const result = await parse("document.hwpx")
if (result.success) {
  console.log(result.markdown)
  // result.blocks: structured data; result.metadata: document metadata
}

const hwpx = await markdownToHwpx("# Plan\n\nBody text", {
  gongmun: { preset: "report" },
})
await writeFile("report.hwpx", Buffer.from(hwpx))

Параметры разбора, API, формы и примеры рендеринга

Возможности

Задача	Возможности
Чтение	Markdown, IR, текст страниц, фрагменты для RAG и локальный OCR
Сравнение и редактирование	Различия между блоками и ячейками, патчи HWPX/HWP с сохранением форматирования
Создание	Преобразование Markdown → HWPX, шаблоны государственных документов, таблицы, формулы и диаграммы
Заполнение форм	Поля, элементы управления для ввода по щелчку, два шаблона черновиков и размещение печати
Проверка	Предварительный просмотр HWPX/HWP и фрагментов областей, валидация, проверка стилей и маскирование персональных данных

Извлекайте Markdown для патчей с сохранением форматирования с помощью --keep-layout-tables. Неподдерживаемые изменения пропускаются с указанием причины. Полный справочник по CLI и API

Валидация

Проверка версии 4.22.5 · 2026-10-17. Результаты получены на фиксированных корпусах с использованием заданных критериев сравнения.

Целевой формат	Объём	Результат
HWPX	2,429 документов · 10,461 таблица	Совпадение структуры таблиц: 10,461/10,461 · 100%
HWP 5.x ↔ HWPX	1,131 пара · 4,317 таблиц	Совпадение структуры таблиц в парах документов: 100%
Текст PDF	744 пары	Полнота по символам: 99.872% · точность: 99.670% · порядок чтения: 99.244% · F1 границ слов: 99.037%
Таблицы PDF	708 пар · 2,331 таблица	Обнаружение: 99.87% · совпадение структуры: 98.16% · F1 ячеек: 0.9918
Переносы строк HWPX	25,581 многострочный абзац	Совпадение начала каждой строки: 25,332/25,581 · 99.0266%
Вложенные таблицы PDF (текстовый слой)	29 документов · 101 таблица	Совпадение структуры и содержимого ячеек: 101/101 · 100%
Приложения к нормативным актам	272 документа · 346 таблиц	HWP: 346/346, PDF: 342/346 · 98.84%
Все PDF	1,888 документов с оценкой из 2,070	Охват текста: 99.80%
OCR	53 документа · 102 страницы	CER: 0.0412 · полнота по символам: 99.02%

Структура таблиц, содержимое ячеек и визуальное соответствие — отдельные метрики. Результат 100% для вложенных таблиц относится только к этим 101 таблицам, а не ко всему разбору PDF или вёрстке страниц. Область проверки, исключения и сравнение каждого документа приведены в описании тестирования.

Проверка улучшений версии 4.22.5 (2026-10-17): в ходе десяти чередующихся раундов число абзацев с точным совпадением начал строк выросло с 25,326 до 25,332/25,581, точность извлечения содержимого ячеек PDF — с 0.990311 до 0.990677, а полнота по символам — с 0.99865 до 0.99872. Исправления затронули табуляцию нулевой ширины, интервалы символов, отступы маркеров списков, высоту строк и разделённые таблицы, а также продолжения таблиц PDF, заголовки разделов и отсутствующие глифы. F1 ячеек приложений к нормативным актам вырос с 0.99739 до 0.99778; точное совпадение структуры осталось на уровне 342/346. Ещё пять раундов, побочные эффекты и проверка upstream (на корейском) · Пять предыдущих раундов (на корейском)

Объединённые угловые ячейки сохраняются в исходной логической сетке при объединении пустых строк. Восстановлены шесть числовых глифов в воспроизведённом PDF; ограничения, связанные с отрисовкой правил в HTML и глифами незарегистрированных шрифтов, описаны отдельно (на корейском).

Внешнее тестирование opendataloader-bench на 200 документах проведено на том же корпусе с кандидатом на выпуск версии 4.22.5: общий результат — 0.963 с настройками по умолчанию и 0.939 с отключённым OCR. Параметры и инструкция по воспроизведению

Последние обновления

Последний выпуск: 4.22.5 · 2026-10-17

Версия	Основные изменения
4.22.5	Исправлены табуляции нулевой ширины, смещения символов, отступы для маркеров списка, разбиение таблиц и высота строк; восстановлены частичные ячейки PDF, заголовки разделов и отсутствующие глифы
4.22.4	Исправлены изображения, границы, шрифты пробелов, вертикальное выравнивание по базовой линии и расположение цитат; восстановлены ячейки со списками, примечания, заголовки форм и строки списков, разбитые на части, в PDF
4.22.3	Улучшена перекомпоновка таблиц, изображений и необязательных переносов; восстановлены продолжения таблиц и независимые строки в PDF; объединённые угловые ячейки сохраняются при сворачивании пустых строк
4.22.2	Исправлены позиции частичного редактирования, обтекание изображений и пробелы фиксированной ширины; сохранены отдельные блоки заголовков PDF и пронумерованные строки; восстановлены контактные столбцы и содержимое затенённых строк
4.22.1	Исправлено смешение координат для выпрямленных и высокоразрешённых фрагментов при OCR областей с рисунками в PDF со слоем текста; выпрямление всей страницы по-прежнему включено
4.22.0	Вложенные таблицы PDF: 94/101 → 101/101; сохраняются ячейки на границах страниц, подписи HWP и примечания внутри ячеек таблиц. Координаты строк OCR и выбор модели; установка OCR формул стала легче
4.21.33	Потоковое расположение столбцов концевых сносок, подстрочные сноски в разделённых таблицах, интервалы между ячейками — совпадение позиций строк основного текста: 95.9% → 97.5%, ячеек: 99.5% → 99.7%
4.21.32	Отображение и перекомпоновка макета страницы — ячейки таблиц и плавающие объекты, пересекающие границы страниц. Совпадение позиций строк в ячейках: 97.4% → 99.5%, основного текста: 87.2% → 95.9%
4.21.31	Улучшено совпадение при отображении и перекомпоновке макета; таблицы в примечаниях сохраняются (#149), добавлена поддержка встроенных математических выражений по выбору (#150), исправлены проблемы, выявленные при проверке безопасности
4.21.23	OCR текста внутри изображений в HWP и HWPX (`ocr: true`, #143)
4.21.0	Стили для документов министерств `--agency`, контактные таблицы в пресс-релизах

Используйте --ocr --ocr-lines --format json, чтобы экспортировать координаты рамок строк OCR и значения достоверности. Выберите детектор и разрешение с помощью --ocr-det и --ocr-det-long-side. Строки OCR и модели

Подробности о каждом выпуске см. в журнале изменений.

Часто задаваемые вопросы

Как преобразовать файл HWP или HWPX в Markdown?

npx kordoc document.hwp -o document.md. Команда читает файл напрямую, без Hancom Office. Чтобы преобразовать сразу несколько файлов, выполните npx kordoc *.hwpx -d ./output.

Как предоставить Claude, Cursor или другому AI-агенту доступ к документам на корейском языке?

Выполните npx -y kordoc setup, чтобы зарегистрировать MCP-сервер. После этого агент сможет читать, сравнивать и заполнять файлы HWP, PDF и Excel, указанные по пути к файлу.

Работает ли сервер в изолированной от внешней сети среде?

Да. KORDOC_OFFLINE=1 блокирует весь исходящий трафик, а OCR выполняется на локальном CPU без ключа API. Развёртывание в автономной среде

Можно ли использовать сервер для индексации RAG?

Параметр --format chunks формирует структурные фрагменты с цепочками заголовков, а также отдельные фрагменты таблиц. Используйте --table-format gfm (API: tableFormat: "gfm"), чтобы выводить таблицы без HTML. Для работы из Python или Java воспользуйтесь Python SDK или Java SDK.

Документация и безопасность

Руководство по использованию: полное описание CLI, инструментов MCP, API и поддерживаемых форматов
Java SDK · Python SDK: разбор документов из систем на Java и Python с помощью постоянно работающего обработчика механизма (протокол обработчика, на корейском языке)
Создание государственных документов · Архитектура
Развёртывание в автономной среде: KORDOC_OFFLINE=1; ограничение доступа MCP к файлам с помощью KORDOC_ROOT
Политика безопасности · Лицензия MIT · Уведомления о сторонних компонентах

Об авторе

Государственный служащий в Корее. Создал этот проект после семи лет работы с файлами HWP в районной администрации Кванчжин-гу в Сеуле. Решение проверено на тысячах реальных государственных документов в рамках пяти проектов государственного сектора.