Communitygithub.com

kangdacool/hwpx-editing-skill

LLM 에이전트(Claude Code·Codex 등)가 한글 .hwpx 파일을 안 깨고 편집하게 해주는 검증된 규칙 + 파이썬 도구 스킬. Una habilidad portable para agentes que enseña a Claude Code, Codex y otros agentes LLM a editar archivos HWPX (Hangul .hwpx) sin corromperlos.

¿Qué es hwpx-editing-skill?

Esta habilidad portable permite a agentes de IA como Claude Code y Codex editar archivos HWPX de 한글 (un formato zip de XML utilizado por el procesador de textos Hangul) sin introducir corrupción. El problema principal es que los métodos de edición y reempaquetado ingenuos dañan el archivo porque 한글 requiere que las entradas no modificadas se copien byte a byte y que solo se vuelvan a comprimir las modificadas. La habilidad proporciona un empaquetador preservador de bytes (`repack_preserve`) en `scripts/hwpxlib.py`, un inspector de estructura (`inspect_hwpx.py`), y un verificador (`verify.py`) que garantiza que el archivo resultante sea idéntico al original en las partes no tocadas. Incluye reglas detalladas para eliminar `linesegarray` después de editar párrafos, reasignar IDs al clonar nodos, y reutilizar definiciones de formato existentes. La guía de referencia (`references/hwpx-guide.md`) cubre desde la estructura básica hasta la gestión de páginas/columnas, imágenes, ecuaciones y tablas. Los scripts requieren `lxml` (y `openpyxl` para exportar tablas a Excel). La habilidad instruye al agente a trabajar siempre sobre una copia, nunca modificar el contenido del autor más allá de lo solicitado, y verificar cada cambio con `verify.py` antes de entregar el resultado al usuario.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Edición HWPX

HWPX es un zip de XML (HWPML). Las trampas que corrompen un archivo no son obvias desde fuera, por lo que lea la sección correspondiente de references/hwpx-guide.md antes de editar y ejecute los scripts en scripts/ para reempaquetar y verificar — no haga el zip manualmente ni confíe en la corrección visual.

Solo HWPX. Esto maneja exclusivamente .hwpx (zip + XML). Un .hwp heredado (binario OLE, firma D0CF11E0) debe convertirse primero en 한글 mediante 다른 이름으로 저장 → HWPX(.hwpx). Los scripts detectan .hwp y lo indican.

La regla más importante

Nunca vuelva a comprimir un HWPX con un escritor zip normal. 한글 rechaza un archivo cuyas entradas no modificadas fueron re-deflactadas. Use el reempaquetador preservador de bytes (scripts/hwpxlib.py:repack_preserve): copia byte a byte cada entrada que no tocó y re-deflacta solo lo que cambió, de modo que un reempaquetado sin cambios es byte-idéntico al origen — lo que significa "si el original se abre en 한글, su edición también se abre".

Flujo de trabajo

  1. Inspeccione primero. python scripts/inspect_hwpx.py ARCHIVO.hwpx --breaks — vea conteos por sección (párrafos, tablas, pic, ecuación, campos) y, crucialmente, qué párrafos llevan un pageBreak/columnBreak oculto. Si un encabezado está separado de su contenido o una página/columna está en blanco, cace esos saltos primero (§6-A) — no recurra a keepWithNext. Los saltos de párrafo del cuerpo suelen ser residuos.
  2. Lea la sección correspondiente de la guía en references/hwpx-guide.md (mapa abajo). Los ids/referencias XML (charPrIDRef, paraPrIDRef, borderFillIDRef, …) difieren por archivo — léalos siempre del archivo real, nunca asuma.
  3. Edite el XML con lxml, siguiendo las invariantes:
    • Después de editar o crear cualquier párrafo, elimine su <hp:linesegarray> (el diseño de línea en caché se vuelve obsoleto → espaciado roto). Después de ediciones estructurales, elimine linesegarray de toda la sección para que 한글 vuelva a diseñarlo completamente. Use hwpxlib.strip_linesegarray.
    • Cuando clone un nodo (nota al final, tabla, ecuación, imagen), hereda el id/instId del original → duplicados → inestabilidad. Reasigne ids frescos con hwpxlib.make_uid, incluyendo ids anidados de subList>p / tbl/tc/p.
    • Reutilice definiciones charPr/paraPr existentes en lugar de agregar nuevas; si debe agregar, actualice el itemCnt o 한글 rechaza el archivo.
  4. Reempaquete con hwpxlib.repack_preserve(origen, cambiados, salida, agregados): cambiados = entradas editadas (mantenga la declaración XML al inicio), agregados = nuevas entradas como BinData/imagenN.png o un nuevo seccionN.xml (también regístrelas en content.hpf).
  5. Verifique cada compilación: python scripts/verify.py EDITADO.hwpx --orig ORIG.hwpx. Todas las comprobaciones estrictas deben pasar (autocomprobación de identidad de bytes, XML bien formado incl. content.hpf, cero ids duplicados, integridad zip + mimetype primero/ALMACENADO). También imprime un diff de cambio mínimo para que pueda confirmar que solo están presentes los cambios previstos.
  6. Pruebe en 한글. LibreOffice no puede renderizar HWPX, por lo que los juicios dependientes de renderizado (qué huérfanos de encabezado, si el espaciado se ve bien) necesitan que el usuario abra el archivo en 한글 y, para ecuaciones/TDC, ejecute 도구→차례 새로 고침 o haga doble clic→cerrar para finalizar. Dígalo.

Scripts (scripts/) — ejecute estos, no reinvente

ScriptPropósito
hwpxlib.pyBiblioteca: repack_preserve, own (texto del cuerpo real, excluye 각주·미주·메모 / nota al pie·nota al final·memo), make_uid, strip_linesegarray, find_duplicate_ids, structural_counts, más ayudantes de verificación §7. Impórtelo.
inspect_hwpx.py ARCHIVO [--text] [--breaks]Volcado de estructura; encuentre saltos de página/columna ocultos.
verify.py EDITADO [--orig ORIG]Ejecute la lista de verificación completa §7; salida distinta de cero en fallo (comprobable en CI).
selftest.pyDemuestre que el reempaquetador es sin pérdidas sin un archivo real.
tables_to_xlsx.py ARCHIVO [SALIDA]Exporte tablas a Excel (.xlsx), celdas combinadas preservadas (necesita openpyxl). Celdas con solo imagen/ecuación → [그림]/[수식]; .hwp heredado es rechazado con orientación.

Los scripts necesitan lxml (pip install lxml); la exportación tabla→Excel también necesita openpyxl. Python 3.10+.

Dónde leer en la guía (references/hwpx-guide.md)

Cargue solo la sección que necesite — la guía abre con un "흔한 실패 TOP" (modos de fallo principales); hojee eso primero, luego salte a:

  • §1 Estructura y análisis — espacios de nombres, own(), "verificar todas las secciones", texto de tabla por celda (no itertext masivo).
  • §2 Reempaquetado (preservador de bytes) — el reempaquetador joya de la corona. Espejo de hwpxlib.
  • §3 Reglas comunes — eliminación de linesegarray, deduplicación de ids después de clonar.
  • §4 Edición de contenido — párrafos, tablas (la suma de anchos de celda debe igualar el ancho de la tabla o 한글 lo rechaza; combinaciones), imágenes (orgSz=px×75, cálculo de tamaño, verificar por contenido no orden de extracción, legibilidad de matplotlib "figura pequeña, texto grande"), formato, notas al final/notas al pie (requerido envoltorio <hp:ctrl>), memos y alcance de auditoría de erratas (sin regex general).
  • §5 Columnas · TDC · ecuaciones — colPr, TABLEOFCONTENTS desde párrafos de nivel de esquema, script de ecuación 한컴 (no LaTeX; tabla de formas).
  • §6 Gestión de página/columna — saltos ocultos primero, prevención de encabezado huérfano (keepWithNext, sin párrafo vacío después de un encabezado, columnBreak condicional), limpieza de páginas en blanco, tablas anchas → región de 1 columna + mover un bloque secPr a través de límites de sección.
  • §7 Lista de verificación — qué automatiza verify.py, más la advertencia de prueba en 한글.

Barreras de protección

  • Esto edita documentos solamente; nunca necesita las credenciales del usuario, y no obtiene ni ejecuta contenido remoto. Trabaje sobre una copia y conserve el original.
  • Preserve el contenido del autor: solo cambie lo que el usuario pidió; el diff de cambio mínimo en verify.py es su prueba.

Skills relacionados