Communitygithub.com

kangdacool/hwpx-editing-skill

Um conjunto de regras e ferramentas Python portáteis que permite que agentes LLM (Claude Code, Codex, etc.) editem arquivos HWPX (Hangul .hwpx) sem corrompê-los.

O que é hwpx-editing-skill?

Este skill equipa agentes LLM como Claude Code e Codex com um fluxo de trabalho seguro e validado para editar arquivos nativos do processador de texto coreano Hangul (Hangul) no formato HWPX, que é na verdade um ZIP contendo XML (HWPML). Em vez de simplesmente tentar descompactar e recompactar, o skill utiliza um script Python dedicado (`hwpxlib.py`) que preserva bytes originais de entradas não modificadas e apenas recompacta as alteradas, garantindo que o resultado seja idêntico ao original quando nenhuma edição é feita. O fluxo de trabalho orienta o agente a inspecionar a estrutura do arquivo primeiro (localizando quebras de página/coluna ocultas), ler a seção relevante do guia técnico fornecido, editar o XML com lxml seguindo invariantes críticas (como remover `linesegarray` após editar parágrafos e reatribuir IDs únicos ao clonar nós) e, finalmente, verificar a integridade do arquivo editado com um script de verificação automatizada. Ao seguir essas regras, o skill previne os modos de falha comuns que corrompem arquivos HWPX e fornece evidências de que apenas as alterações pretendidas foram feitas, permitindo que o agente execute tarefas de edição de documentos complexas de forma confiável.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Edição de HWPX

HWPX é um ZIP de XML (HWPML). As armadilhas que corrompem um arquivo não são óbvias de fora, então leia a seção relevante de references/hwpx-guide.md antes de editar, e execute os scripts em scripts/ para recompactar e verificar — não tente fazer o zip manualmente ou verificar a correção visualmente.

Apenas HWPX. Isso lida exclusivamente com .hwpx (ZIP + XML). Um .hwp legado (binário OLE, assinatura D0CF11E0) deve primeiro ser convertido no 한글 via 다른 이름으로 저장 → HWPX(.hwpx). Os scripts detectam .hwp e informam.

A regra mais importante

Nunca recrie um HWPX com um gravador ZIP normal. O 한글 rejeita um arquivo cujas entradas inalteradas foram re-deflacionadas. Use o recompactador que preserva os bytes originais (scripts/hwpxlib.py:repack_preserve): ele copia byte a byte cada entrada que você não tocou e re-deflaciona apenas o que você alterou, de modo que uma recompactação sem alterações é byte-idêntica à fonte — significando "se o original abre no 한글, sua edição também abre".

Fluxo de trabalho

  1. Inspecione primeiro. python scripts/inspect_hwpx.py ARQUIVO.hwpx --breaks — veja contagens por seção (parágrafos, tabelas, pic, equation, campos) e, crucialmente, quais parágrafos carregam uma pageBreak/columnBreak oculta. Se um título estiver separado de seu conteúdo ou uma página/coluna estiver em branco, descubra essas quebras primeiro (§6-A) — não alcance keepWithNext. Quebras de parágrafo de corpo geralmente são resquícios.
  2. Leia a seção correspondente do guia em references/hwpx-guide.md (mapeamento abaixo). Os IDs/refs XML (charPrIDRef, paraPrIDRef, borderFillIDRef, …) diferem por arquivo — sempre leia-os do arquivo real, nunca suponha.
  3. Edite o XML com lxml, seguindo as invariantes:
    • Depois de editar ou criar qualquer parágrafo, remova seu <hp:linesegarray> (layout de linha em cache fica obsoleto → espaçamento quebrado). Após edições estruturais, remova linesegarray da seção inteira para que o 한글 refaça o layout completamente. Use hwpxlib.strip_linesegarray.
    • Quando você clona um nó (nota de fim, tabela, equação, imagem), ele herda o id/instId original → duplicatas → instabilidade. Atribua novos IDs com hwpxlib.make_uid, incluindo IDs aninhados de subList>p / tbl/tc/p.
    • Reutilize definições existentes de charPr/paraPr em vez de adicionar novas; se precisar adicionar, atualize o itemCnt ou o 한글 rejeita o arquivo.
  4. Recompacte com hwpxlib.repack_preserve(src, changed, out, added): changed = entradas editadas (mantenha a declaração XML no topo), added = novas entradas como BinData/imagemN.png ou um novo sectionN.xml (também registre-as em content.hpf).
  5. Verifique cada construção: python scripts/verify.py EDITADO.hwpx --orig ORIG.hwpx. Todas as verificações rigorosas devem passar (autoverificação de identidade de byte, XML bem formado incluindo content.hpf, zero IDs duplicados, integridade do ZIP + mimetype primeiro/ARMAZENADO). Ele também imprime uma diff de alteração mínima para que você confirme que apenas as alterações pretendidas estão presentes.
  6. Teste no 한글. O LibreOffice não pode renderizar HWPX, portanto julgamentos dependentes de renderização (se cabeçalhos órfãos, se o espaçamento parece correto) precisam que o usuário abra o arquivo no 한글 e, para equações/SUMÁRIO, execute 도구 → 차례 새로 고침 ou clique duas vezes → feche para finalizar. Avise isso.

Scripts (scripts/) — execute estes, não recrie

ScriptPropósito
hwpxlib.pyBiblioteca: repack_preserve, own (texto real do corpo, exclui 각주·미주·메모 / nota de rodapé·nota de fim·memorando), make_uid, strip_linesegarray, find_duplicate_ids, structural_counts, além de auxiliares de verificação §7. Importe-a.
inspect_hwpx.py ARQUIVO [--text] [--breaks]Despejo da estrutura; encontre quebras ocultas de página/coluna.
verify.py EDITADO [--orig ORIG]Execute a lista de verificação completa §7; saída com código diferente de zero em falha (integrável a CI).
selftest.pyProve que o recompactador é sem perdas sem um arquivo real.
tables_to_xlsx.py ARQUIVO [SAÍDA]Exporte tabelas para Excel (.xlsx), células mescladas preservadas (precisa de openpyxl). Células com apenas imagem/equação → [그림]/[수식]; .hwp legado é recusado com orientação.

Os scripts precisam de lxml (pip install lxml); a exportação de tabelas para Excel também precisa de openpyxl. Python 3.10+.

Onde ler no guia (references/hwpx-guide.md)

Carregue apenas a seção que você precisa — o guia abre com um "흔한 실패 TOP" (principais modos de falha); folheie isso primeiro, depois vá para:

  • §1 Estrutura e análise — namespaces, own(), "verifique todas as seções", texto de tabela por célula (não itertext em massa).
  • §2 Recompactação (preservação de bytes) — o recompactador principal. Espelha hwpxlib.
  • §3 Regras comuns — remoção de linesegarray, dedup de ID após clonagem.
  • §4 Edição de conteúdo — parágrafos, tabelas (soma das larguras das células deve igualar a largura da tabela ou 한글 rejeita; mesclagens), imagens (orgSz=px×75, cálculo de tamanho, verifique por conteúdo não ordem de extração, legibilidade matplotlib "figura pequena, texto grande"), formatação, notas de fim/rodapé (encapsulamento <hp:ctrl> obrigatório), memorandos, e escopo de auditoria de erros de digitação (sem regex genérico).
  • §5 Colunas · SUMÁRIO · equações — colPr, TABLEOFCONTENTS a partir de parágrafos de nível de estrutura, script de equação 한컴 (não LaTeX; tabela de formulários).
  • §6 Gerenciamento de página/coluna — quebras ocultas primeiro, prevenção de cabeçalhos órfãos (keepWithNext, sem parágrafo vazio após um cabeçalho, columnBreak condicional), limpeza de páginas em branco, tabelas largas → região de 1 coluna + mover um bloco secPr entre seções.
  • §7 Lista de verificação de verificação — o que verify.py automatiza, além da ressalva do teste no 한글.

Proteções

  • Isso edita apenas documentos; nunca precisa das credenciais do usuário e não busca nem executa conteúdo remoto. Trabalhe em uma cópia e mantenha o original.
  • Preserve o conteúdo do autor: altere apenas o que o usuário pediu; a diff de alteração mínima em verify.py é sua prova.

Habilidades Relacionadas