Communitygithub.com

kangdacool/hwpx-editing-skill

Ein portabler Agenten-Skill, der Claude Code, Codex und andere LLM-Agenten lehrt, HWPX (Hangul .hwpx) Dateien zu bearbeiten, ohne sie zu beschädigen.

Was ist hwpx-editing-skill?

Dieser Skill befähigt KI-Agenten wie Claude Code und Codex, HWPX-Dateien (das XML-basierte Format von Hangul, dem koreanischen Textverarbeitungsprogramm) zuverlässig zu bearbeiten. Das Hauptproblem bei der Bearbeitung von HWPX-Dateien ist, dass sie als ZIP-Archive mit XML-Inhalt vorliegen und normale ZIP-Werkzeuge die Dateien unbrauchbar machen, indem sie unveränderte Einträge erneut komprimieren. Dieser Skill umgeht dies durch ein spezielles Repack-Skript (`scripts/hwpxlib.py:repack_preserve`), das unveränderte Einträge bytegenau kopiert und nur geänderte Teile neu komprimiert, sodass die resultierende Datei mit einer unbearbeiteten Datei byteidentisch ist. Der Skill enthält eine umfassende Bibliothek von Python-Skripten zur Überprüfung, Extraktion, Tabellenexport und Verifizierung sowie eine detaillierte Referenz (`references/hwpx-guide.md`), die Fallstricke, häufige Fehler und Best Practices für die Bearbeitung von Absätzen, Tabellen, Bildern, Gleichungen, Endnoten und mehr abdeckt. Er unterstützt nur das moderne .hwpx-Format und gibt klare Anweisungen zur Konvertierung älterer .hwp-Dateien.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor
npx skills add kangdacool/hwpx-editing-skill

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

HWPX-Bearbeitung

HWPX ist ein ZIP von XML (HWPML). Die Fallstricke, die eine Datei beschädigen, sind von außen nicht offensichtlich. Lesen Sie daher vor der Bearbeitung den entsprechenden Abschnitt von references/hwpx-guide.md und führen Sie die Skripte in scripts/ zum Neupacken und Überprüfen aus – erstellen Sie das ZIP nicht von Hand oder verlassen Sie sich auf bloßes Augenschein.

Nur HWPX. Dieses Handbuch behandelt ausschließlich .hwpx (ZIP + XML). Eine ältere .hwp (OLE-Binärdatei, Signatur D0CF11E0) muss zuerst in 한글 konvertiert werden über 다른 이름으로 저장 → HWPX(.hwpx). Die Skripte erkennen .hwp und geben eine entsprechende Meldung aus.

Die eine Regel, die am wichtigsten ist

Packen Sie ein HWPX niemals mit einem normalen ZIP-Schreiber neu. 한글 lehnt eine Datei ab, deren unveränderte Einträge erneut dekomprimiert wurden. Verwenden Sie den roherhaltenden Neupacker (scripts/hwpxlib.py:repack_preserve): Er kopiert jeden nicht bearbeiteten Eintrag bytegenau und dekomprimiert nur das, was Sie geändert haben, sodass ein No-Op-Neupacken byteidentisch zur Quelle ist – was bedeutet: „Wenn das Original in 한글 geöffnet wird, öffnet sich auch Ihre Bearbeitung.“

Arbeitsablauf

  1. Zuerst inspizieren. python scripts/inspect_hwpx.py DATEI.hwpx --breaks – sehen Sie abschnittsweise Zählungen (Absätze, Tabellen, pic, equation, Felder) und, entscheidend, welche Absätze einen versteckten pageBreak/columnBreak tragen. Wenn eine Überschrift von ihrem Inhalt getrennt ist oder eine Seite/Spalte leer ist, jagen Sie zuerst diese Umbrüche (§6-A) – greifen Sie nicht zu keepWithNext. Umbruche in Textabsätzen sind normalerweise übrig gebliebener Ballast.
  2. Lesen Sie den entsprechenden Leitfadenabschnitt in references/hwpx-guide.md (Zuordnung unten). Die XML-IDs/Referenzen (charPrIDRef, paraPrIDRef, borderFillIDRef, …) unterscheiden sich pro Datei – lesen Sie sie immer aus der tatsächlichen Datei aus, niemals annehmen.
  3. Bearbeiten Sie das XML mit lxml unter Beachtung der Invarianten:
    • Entfernen Sie nach dem Bearbeiten oder Erstellen eines Absatzes immer dessen <hp:linesegarray> (zwischengespeichertes Zeilenlayout wird veraltet → defekter Abstand). Entfernen Sie nach strukturellen Bearbeitungen das linesegarray aus dem gesamten Abschnitt, damit 한글 das Layout vollständig neu berechnet. Verwenden Sie hwpxlib.strip_linesegarray.
    • Wenn Sie einen Knoten klonen (Endnote, Tabelle, Gleichung, Bild), erbt er die id/instId des Originals → Duplikate → Instabilität. Weisen Sie neue IDs mit hwpxlib.make_uid zu, einschließlich der IDs in verschachtelten subList>p/tbl/tc/p.
    • Verwenden Sie vorhandene charPr/paraPr-Definitionen wieder, anstatt neue hinzuzufügen; wenn Sie hinzufügen müssen, aktualisieren Sie das itemCnt, sonst lehnt 한글 die Datei ab.
  4. Neupacken mit hwpxlib.repack_preserve(quelle, geändert, ausgabe, hinzugefügt): geändert = bearbeitete Einträge (XML-Deklaration oben lassen), hinzugefügt = neue Einträge wie BinData/imageN.png oder eine neue sectionN.xml (auch in content.hpf registrieren).
  5. Jede Erstellung überprüfen: python scripts/verify.py BEARBEITET.hwpx --orig ORIGINAL.hwpx. Alle harten Prüfungen müssen bestehen (Byteidentität-Selbsttest, wohlgeformtes XML inkl. content.hpf, null doppelte IDs, ZIP-Integrität + mimetype zuerst/GESPEICHERT). Es gibt auch eine minimale Änderungsdifferenz aus, damit Sie bestätigen können, dass nur die beabsichtigten Änderungen vorhanden sind.
  6. Rückwärtskompatibilität in 한글. LibreOffice kann HWPX nicht rendern, daher benötigen rendernabhängige Beurteilungen (welche Überschriften verwaist sind, ob Abstände richtig aussehen) das Öffnen der Datei in 한글 durch den Benutzer und bei Gleichungen/Inhaltsverzeichnis das Ausführen von 도구→차례 새로 고침 oder Doppelklick→Schließen zum Finalisieren. Sagen Sie dies.

Skripte (scripts/) – führen Sie diese aus, erfinden Sie sie nicht neu

SkriptZweck
hwpxlib.pyBibliothek: repack_preserve, own (echter Textkörper, schließt 각주·미주·메모 / Fußnoten·Endnoten·Memo aus), make_uid, strip_linesegarray, find_duplicate_ids, structural_counts, plus §7-Verifizierungshilfen. Importieren Sie es.
inspect_hwpx.py DATEI [--text] [--breaks]Strukturauszug; versteckte Seiten-/Spaltenumbrüche finden.
verify.py BEARBEITET [--orig ORIGINAL]Führen Sie die vollständige §7-Checkliste aus; Exit-Code ungleich Null bei Fehlschlag (CI-tauglich).
selftest.pyBeweisen Sie, dass der Neupacker verlustfrei ist, ohne eine echte Datei.
tables_to_xlsx.py DATEI [AUSGABE]Exportieren Sie Tabellen nach Excel (.xlsx), zusammengeführte Zellen erhalten (benötigt openpyxl). Zellen mit nur einem Bild/einer Gleichung → [그림]/[수식]; ältere .hwp wird mit Anleitung abgelehnt.

Skripte benötigen lxml (pip install lxml); der Tabellen→Excel-Export benötigt auch openpyxl. Python 3.10+.

Wo im Leitfaden lesen (references/hwpx-guide.md)

Laden Sie nur den Abschnitt, den Sie benötigen – der Leitfaden beginnt mit einer „흔한 실패 TOP“ (häufige Fehlermodi); überfliegen Sie dies zuerst, springen Sie dann zu:

  • §1 Struktur & Parsen – Namensräume, own(), „alle Abschnitte prüfen“, Tabellentext pro Zelle (nicht als itertext-Menge).
  • §2 Neupacken (roherhaltend) – der Kronjuwel-Neupacker. Spiegelt hwpxlib.
  • §3 Allgemeine Regeln – Entfernung von linesegarray, ID-Deduplizierung nach Klonen.
  • §4 Inhaltsbearbeitung – Absätze, Tabellen (Zellenbreitensummen müssen der Tabellenbreite entsprechen oder 한글 lehnt sie ab; Zusammenführungen), Bilder (orgSz=px×75, Größenberechnung, Überprüfung nach Inhalt nicht Extraktionsreihenfolge, matplotlib-Lesbarkeit „kleines Bild, großer Text“), Formatierung, Endnoten/Fußnoten (<hp:ctrl>-Umschließung erforderlich), Memos und Rechtschreibprüfungsbereich (keine pauschalen Regex).
  • §5 Spalten · Inhaltsverzeichnis · Gleichungen – colPr, TABLEOFCONTENTS aus Absätzen mit Gliederungsebene, 한컴-Gleichungsskript (nicht LaTeX; Tabelle der Formulare).
  • §6 Seiten-/Spaltenverwaltung – versteckte Umbrüche zuerst, Verwaiste-Überschrift-Verhinderung (keepWithNext, kein leerer Absatz nach einer Überschrift, bedingter columnBreak), Bereinigung leerer Seiten, breite Tabellen → 1-Spalten-Region + Verschieben eines secPr-Blocks über Abschnittsgrenzen hinweg.
  • §7 Verifizierungscheckliste – was verify.py automatisiert, plus den Rückwärtskompatibilitätshinweis.

Leitplanken

  • Dieses Handbuch bearbeitet nur Dokumente; es benötigt niemals die Anmeldedaten des Benutzers und ruft keine Remote-Inhalte ab oder führt sie aus. Arbeiten Sie auf einer Kopie und bewahren Sie das Original.
  • Bewahren Sie den Inhalt des Autors: Ändern Sie nur, was der Benutzer verlangt hat; die minimale Änderungsdifferenz in verify.py ist Ihr Nachweis.

Verwandte Skills