kordoc im Test: HWP, HWPX und PDF nach Markdown parsen

HWP 3.x, HWP 5.x, HWPX, PDF: die Formatabdeckung von kordoc

kordoc ist ein in TypeScript geschriebenes Werkzeug, das die Formate parst, die in koreanischen Behörden tatsächlich kursieren: HWP 3.x, HWP 5.x, HWPX, HWPML, PDF, XLS, XLSX und DOCX, dazu PNG-, JPG- und WebP-Bilder mit automatischer OCR. Der Autor beschreibt im README seine Herkunft: sieben Jahre als Beamter im koreanischen Dokumentenalltag, gebaut wurde das Werkzeug genau für diesen Papierkram. Herauskommen soll Markdown in einem Zustand, den LLMs direkt weiterverarbeiten können. Die Metadaten zeigen 1.781 Sterne, 318 Forks und die Lizenz MIT, gepflegt wird das Repository chrisryugj/kordoc aktiv, der letzte Push liegt zum Redaktionsschnitt Ende August 2026 zurück.

Pro Format gibt es eine eigene Engine. HWPX wird als ZIP mit XML-DOM behandelt, HWP 5.x läuft über OLE2/CFB inklusive Wiederherstellung beschädigter Container, das alte HWP 3.x bringt eine johab-zu-Unicode-Konvertierung und eine Tabelle mit 5.893 Hanja-Einträgen mit. Für PDF nutzt das Projekt pdfjs-dist mit linienbasierter Tabellenerkennung und XY-Cut-Lesereihenfolge.

npx -y kordoc setup: der Assistent für MCP und AI-Clients

Die Installation ist bewusst auf KI-Arbeitsplätze zugeschnitten. Der Befehl npx -y kordoc setup startet einen interaktiven Assistenten, der installierte Clients erkennt und deren Konfigurationsdateien automatisch patcht. Das README nennt Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, Gemini CLI, Zed, Antigravity und Codex; erkannte Clients werden markiert, unter Windows kapselt der Assistent den Aufruf automatisch als cmd /c npx, sodass keine manuelle JSON-Bearbeitung nötig ist. Nach einem Neustart des Clients stehen 15 Dokumentwerkzeuge bereit, darunter parse_document, parse_table, fill_form, patch_document und generate_document.

Zwei Stolperfallen dokumentiert das README ehrlich. Bleibt eine Meldung wie MODULE_NOT_FOUND oder Cannot find module dist/cli.js, hilft npm uninstall -g kordoc gefolgt von npx -y kordoc@latest setup, um eine kaputte Altinstallation zu entfernen. Blockiert PowerShell das Skript mit einer PSSecurityException, ist das eine Standard-Sicherheitsrichtlinie gegen unsignierte .ps1-Dateien; der Weg führt über die cmd oder über Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. Wer nur die CLI will, kommt mit npx kordoc <Datei> ganz ohne Setup aus.

Tabellen ohne Verlust: 1.673 von 1.673 laut README

Tabellen sind in Behördendokumenten der kritische Teil, und hier legt kordoc Messwerte vor. Laut README wurde ein HWPX-Korpus aus 291 Dokumenten gegen einen unabhängigen Extraktor verglichen: 1.673 von 1.673 Tabellen und 27.714 von 27.714 Zellen blieben verlustfrei erhalten. Dervergleichbare hwpx-zu-pdf-Abgleich über 6 Dokumentenpaare mit 69 Tabellen erreichte demnach 98,6 Prozent Matching, davon 65,2 Prozent vollständige Übereinstimmung. Auch PDFs ohne Tabellenlinien sollen erkannt werden, ebenso Neufassungsvergleichstabellen aus Gesetzesänderungen, ein Format, das laut Releasenotes v3.16.2 erst nach einem Parserfehler richtig rekonstruiert wurde.

Diese Zahlen sind Selbstauskunft des Projekts, die Testgates sind im README beschrieben, aber nicht extern geprüft. Für den eigenen Einsatz heißt das: Genau das eigene Korpus nachziehen und die Ausgabe auf verschachtelte Tabellen hin prüfen, bevor man automatisiert weiterverarbeitet.

patchHwpx und patchHwp: Roundtrip ohne Byteverlust am Original

Das zentrale Designmerkmal ist der Patch-Pfad. Nachdem Markdown extrahiert und bearbeitet wurde, übernehmen patchHwpx für HWPX und patchHwp für HWP-5.x-Binärdateien den geänderten Text zurück in die Originaldatei, ohne unveränderte Bytes anzutasten. Schrift, Größe und Ausrichtung des Originals bleiben erhalten, nur die geänderten Absätze oder Tabellenzellen werden ersetzt. Ab v3.7 lassen sich sogar Zeilen in Tabellen hinzufügen oder löschen, ab v3.8 auch leere Zellen füllen, jeweils mit Übernahme der Ursprungsformatierung.

Wichtig ist die Ehrlichkeitsregel aus dem README: Nicht unterstützte Bearbeitungen werden über eine Skip-Liste gemeldet, statt stillschweigend verworfen zu werden. Für den Datenfluss bedeutet das, dass ein Agent etwa parse_document, dann eine Textänderung, dann patch_document durchläuft und am Ende eine gültige HWPX-Datei erhält, die im Behördenworkflow ohne Nachformatieren weitergeht. Das unterscheidet kordoc von Konvertern, die nur eine Richtung kennen.

kordoc render, kordoc seal und der chart-Fence

Drei Zusatzwerkzeuge runden das Bild ab. kordoc render erzeugt SVG-Vorschauen von HWPX-Dateien, ohne dass Hangul auf dem Server installiert sein muss. Bei Dateien mit Hangul-Layoutcache, dem linesegarray, wird das Original-Layout aus den gespeicherten Koordinaten reproduziert; bei künstlich erzeugten Dateien ohne Cache übernimmt eine reine TypeScript-Reflow-Engine, laut README mit 98 Prozent Übereinstimmung bei gemessenen Zeilenumbrüchen. Mehrseitige Ausgabe, Suchbegriff-Hervorhebung und Formen wie Rechtecke oder Pfeile werden gezeichnet, ein persistenter render-worker verarbeitet Folgeläufe ohne Node-Kaltstart.

kordoc seal sucht Ankerformulierungen wie (인) oder 서명 또는 인 und platziert ein Stempel-PNG als schwebendes Objekt vor dem Text, ohne Tabellen oder Seiten zu vergrößern. Bei verschachtelten Tabellen, Textrahmen und Tab-Absätzen ist die Position laut README eine Näherung, die über das warnings-Feld gemeldet wird und sich mit --dx beziehungsweise --dy in Millimetern feinjustieren lässt. Ein chart-Fence im Markdown erzeugt ab v3.16 nativen Hangul-Chart-Space in 20 Diagrammtypen, ungültige Fences fallen auf Codeblöcke zurück.

Regierungsformulare ab v4.0 und die Grenzen des Projekts

Version 4.0 brachte einen Generator für koreanische Regierungsstandarddokumente, entstanden laut README durch das vollständige Dekodieren von 16 offiziellen Formulartypen und 60 real durchlaufenden Genehmigungsdokumenten. Dazu gehören Berichte mit Deckblatt und Römernummerierung, Entwürfe mit automatischem Schlusssatz, Presets für Bekanntmachungen und Pressemitteilungen sowie acht Ebenen der Aufzählungsnummerierung. kordoc lint prüft die Ergebnisse gegen 13 Formatregeln. Das eingebettete OCR aus v4.2 liest gescannte PDFs und Bilder mit PP-OCRv5 korean lokal auf der CPU, ohne API-Schlüssel und ohne externen Dienst, und wählt nur Seiten mit defekter Textebene aus.

Grenzen sind erkennbar: Das Baseline-Material nennt keine formale Sicherheitsprüfung, keine Support-Zusage und keine Verfügbarkeitsgarantie über den MIT-Lizenztext hinaus. Fehlerbilder wie die Stempel-Näherung bei verschachtelten Tabellen sind dokumentiert, der Rest der Robustheit hängt am eigenen Korpus. Für nicht-koreanische Formate bleibt das Werkzeug ein guter Allround-PDF- und Office-Konverter, der eigentliche Mehrwert liegt aber klar in HWP und HWPX.

Redaktionelles Fazit

kordoc passt für Teams und KI-Agenten, die koreanische Behördendokumente im Format HWP, HWPX oder PDF verarbeiten müssen und eine lokale Lösung ohne Cloud-Dienst suchen. Weniger geeignet ist es für rein deutsch- oder englischsprachige Dokumentenfluten, denn der Kernwert liegt in HWP und HWPX samt koreanischer OCR über PP-OCRv5. Vor dem Produktiveinsatz sollte man die eigene Dateisammlung mit npx kordoc gegenprüfen, besonders Tabellen mit verschachtelten Zellen und Scan-PDFs, und die Meldungen im warnings-Feld lesen, die bei Näherungswerten etwa bei kordoc seal auftreten.

Offizielle Quellen

1. Official documentation
2. Official README
3. Project repository
4. Release notes