Communitygithub.com

kangdacool/hwpx-editing-skill

Compétence portable pour agents IA (Claude Code, Codex, etc.) permettant d'éditer des fichiers HWPX (Hancom .hwpx) sans les corrompre, avec des scripts Python et des règles validées.

Qu'est-ce que hwpx-editing-skill ?

Cette compétence fournit un ensemble de règles éprouvées et d'outils Python permettant aux agents LLM comme Claude Code et Codex d'éditer des fichiers HWPX (format natif de Hancom Word) sans les corrompre. Le HWPX étant un fichier XML compressé (ZIP), les erreurs courantes incluent une recompression incorrecte, des IDs en double après clonage de nœuds, ou une suppression insuffisante des balises de mise en page obsolètes. La compétence repose sur un repackeur préservant les octets (`repack_preserve`) qui copie intacts les éléments non modifiés et ne re-déflate que ceux qui ont été édités, garantissant ainsi une fidélité parfaite au fichier source. Elle inclut des scripts d'inspection, de vérification et d'export, notamment un outil d'export de tableaux vers Excel avec conservation des cellules fusionnées. Le guide de référence (en coréen) détaille les sections clés : structure, règles communes, gestion des pages/colonnes, et vérifications. Cette compétence est experte dans l'édition de documents Hancom sans altération du contenu original et sans nécessiter d'accès utilisateur ou de contenu distant.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Édition HWPX

HWPX est une archive ZIP contenant du XML (HWPML). Les pièges qui corrompent un fichier ne sont pas évidents de l'extérieur. Il est donc impératif de lire la section pertinente de references/hwpx-guide.md avant toute édition et d'exécuter les scripts dans scripts/ pour reconstituer et vérifier — ne pas créer manuellement l'archive ZIP ni se fier à une simple inspection visuelle.

HWPX uniquement. Cela ne concerne que les fichiers .hwpx (ZIP + XML). Un fichier .hwp hérité (binaire OLE, signature D0CF11E0) doit d'abord être converti dans Hancom via Enregistrer sous → HWPX(.hwpx). Les scripts détectent .hwp et le signalent.

La règle la plus importante

Ne jamais rezipper un HWPX avec un compresseur ZIP standard. Hancom rejette un fichier dont les entrées inchangées ont été re-déflatées. Utilisez le repackeur préservant les octets (scripts/hwpxlib.py:repack_preserve) : il copie octet par octet chaque entrée que vous n'avez pas touchée et ne re-déflate que ce que vous avez modifié, de sorte qu'une opération sans changement produit un fichier identique octet par octet à la source — ce qui garantit que « si l'original s'ouvre dans Hancom, votre édition s'ouvre aussi ».

Flux de travail

  1. Inspectez d'abord. python scripts/inspect_hwpx.py FICHIER.hwpx --breaks — affiche les comptes par section (paragraphes, tableaux, pic, equation, champs) et, surtout, quels paragraphes portent un pageBreak/columnBreak caché. Si un en-tête est séparé de son contenu ou si une page/colonne est vide, cherchez ces sauts en premier (§6-A) — n'utilisez pas keepWithNext. Les sauts de paragraphe de corps sont généralement des vestiges inutiles.
  2. Lisez la section correspondante du guide dans references/hwpx-guide.md (voir le tableau ci-dessous). Les IDs/références XML (charPrIDRef, paraPrIDRef, borderFillIDRef, …) diffèrent selon le fichier — lisez-les toujours depuis le fichier réel, ne les supposez jamais.
  3. Éditez le XML avec lxml, en respectant les invariants :
    • Après avoir édité ou créé un paragraphe, supprimez son <hp:linesegarray> (la mise en page en cache devient obsolète → espacement cassé). Après des modifications structurelles, supprimez linesegarray de toute la section pour que Hancom refasse entièrement la mise en page. Utilisez hwpxlib.strip_linesegarray.
    • Lorsque vous clônez un nœud (note de fin, tableau, équation, image), il hérite de l'id/instId d'origine → doublons → instabilité. Réaffectez des identifiants frais avec hwpxlib.make_uid, y compris les IDs imbriqués dans subList>p / tbl/tc/p.
    • Réutilisez les définitions existantes charPr/paraPr plutôt que d'en ajouter de nouvelles ; si vous devez en ajouter, mettez à jour itemCnt sinon Hancom rejette le fichier.
  4. Reconstituez avec hwpxlib.repack_preserve(src, changed, out, added) : changed = entrées éditées (conservez la déclaration XML en haut), added = nouvelles entrées comme BinData/imageN.png ou un nouveau sectionN.xml (enregistrez-les aussi dans content.hpf).
  5. Vérifiez chaque construction : python scripts/verify.py EDITED.hwpx --orig ORIG.hwpx. Toutes les vérifications strictes doivent réussir (auto-test d'identité octet par octet, XML bien formé incluant content.hpf, zéro ID en double, intégrité ZIP + mimetype en premier/STORED). Il affiche également un diff de changement minimal pour confirmer que seules les modifications prévues sont présentes.
  6. Testez un aller-retour dans Hancom. LibreOffice ne peut pas afficher HWPX, donc les jugements dépendant du rendu (quels orphelins de titre, si l'espacement est correct) nécessitent que l'utilisateur ouvre le fichier dans Hancom et, pour les équations/TOC, exécute Outils→Mise à jour ou double-clique→fermer pour finaliser. Mentionnez-le.

Scripts (scripts/) — exécutez-les, ne réinventez pas

ScriptObjectif
hwpxlib.pyBibliothèque : repack_preserve, own (texte réel du corps, exclut notes de bas de page, notes de fin, mémos), make_uid, strip_linesegarray, find_duplicate_ids, structural_counts, et utilitaires de vérification §7. Importez-la.
inspect_hwpx.py FICHIER [--text] [--breaks]Dump de structure ; trouve les sauts de page/colonne cachés.
verify.py EDITED [--orig ORIG]Exécute la checklist complète §7 ; sortie non nulle en cas d'échec (intégrable en CI).
selftest.pyProuve que le repackeur est sans perte sans fichier réel.
tables_to_xlsx.py FICHIER [OUT]Exporte les tableaux vers Excel (.xlsx), cellules fusionnées conservées (nécessite openpyxl). Les cellules contenant uniquement une image/équation → [그림]/[수식] ; les .hwp hérités sont refusés avec des instructions.

Les scripts nécessitent lxml (pip install lxml) ; l'export tableau→Excel nécessite également openpyxl. Python 3.10+.

Où lire dans le guide (references/hwpx-guide.md)

Chargez uniquement la section dont vous avez besoin — le guide commence par un « 흔한 실패 TOP » (principaux modes d'échec) ; parcourez-le d'abord, puis allez directement à :

  • §1 Structure et analyse — espaces de noms, own(), « vérifier toutes les sections », texte des tableaux par cellule (pas itertext en bloc).
  • §2 Repack (préservation des octets) — le repackeur vedette. Correspond à hwpxlib.
  • §3 Règles communes — suppression de linesegarray, déduplication des ID après clonage.
  • §4 Édition de contenu — paragraphes, tableaux (la somme des largeurs de cellules doit égaler la largeur du tableau sinon Hancom le rejette ; fusions), images (orgSz=px×75, calcul de taille, vérification par contenu pas par ordre d'extraction, lisibilité matplotlib « petit graphique, grand texte »), mise en forme, notes de fin/bas de page (obligatoirement encapsulées dans <hp:ctrl>), mémos, et portée de la vérification des coquilles (pas d'expression régulière globale).
  • §5 Colonnes · TOC · équations — colPr, TABLEOFCONTENTS à partir des paragraphes de niveau plan, script d'équation Hancom (pas LaTeX ; tableau des formes).
  • §6 Gestion des pages/colonnes — sauts cachés d'abord, prévention des titres orphelins (keepWithNext, pas de paragraphe vide après un titre, columnBreak conditionnel), nettoyage des pages blanches, tableaux larges → région à 1 colonne + déplacement d'un bloc secPr entre sections.
  • §7 Liste de vérification — ce que verify.py automatise, plus la mise en garde sur l'aller-retour.

Garde-fous

  • Cette compétence édite uniquement des documents ; elle n'a jamais besoin des identifiants de l'utilisateur, et elle ne récupère ni n'exécute de contenu distant. Travaillez sur une copie et conservez l'original.
  • Préservez le contenu de l'auteur : modifiez uniquement ce que l'utilisateur a demandé ; le diff de changement minimal dans verify.py est votre preuve.

Skills associés