V4TIME/V4SKILL

Skill Docx

Criar, ler, editar e usar modelos de arquivos Microsoft Word .docx com python-docx por meio de pequenos CLIs. Ela lida com texto, estilos, listas, tabelas, imagens, cabeçalhos/rodapés, modelos {{token}}, controlar alterações (listar/aceitar/rejeitar), comentários (listar/adicionar/excluir), campos de sumário e número de página, e verificações de integridade do pacote. Não renderiza documentos (PDF precisa do LibreOffice — consulte Convertendo para PDF) nem edita .doc legado.

Quando Usar

• O usuário pede para gerar um documento do Word (relatório, carta, contrato).
• Você precisa do texto, estrutura, estilos ou imagens incorporadas de um .docx.
• Você deve alterar um .docx existente: substituir texto, editar células de tabela, inserir/excluir parágrafos, aplicar estilos, mesclar execuções fragmentadas.
• Você tem um modelo .docx com {{placeholders}} para preencher a partir de dados.
• O documento tem controle de alterações para revisar, aceitar ou rejeitar.
• Você precisa ler comentários de revisores, ou adicionar/excluir comentários.
• Um .docx não abre ou se comporta de forma estranha e você precisa de um diagnóstico de corrupção.
• O documento precisa de um sumário ou rodapés "Página X de Y".
• Não é para: .doc (legado), .odt ou trabalho de layout WYSIWYG.

Pré-requisitos

• Python 3.10+ com python-docx instalado: pip install python-docx (o nome de importação é docx; lxml vem junto).
• Comentários add usa a API nativa no python-docx >= 1.2 e um fallback XML em versões mais antigas — ambos são automáticos.
• Para blocos de imagem: os arquivos de imagem devem existir localmente (PNG/JPEG).

Como Executar

Todos os helpers estão em scripts/ ao lado deste arquivo. Execute-os com a ferramenta terminal; cada um suporta --help e imprime JSON na saída padrão.

python scripts/docx_create.py spec.json out.docx
python scripts/docx_read.py out.docx --text
python scripts/docx_edit.py replace out.docx --find old --replace new
python scripts/docx_template.py tpl.docx values.json filled.docx
python scripts/docx_revisions.py list out.docx
python scripts/docx_comments.py list out.docx
python scripts/docx_validate.py out.docx

Referência Rápida

Tarefa	Comando
Criar a partir de especificação JSON	docx_create.py spec.json out.docx
Texto completo (corpo+tabelas+cabeçalhos/rodapés)	docx_read.py f.docx --text
Esboço de títulos + formas de tabela	docx_read.py f.docx --structure
Estilos realmente usados	docx_read.py f.docx --styles
Extrair imagens incorporadas	docx_read.py f.docx --images outdir/
Detectar alterações controladas/comentários	docx_read.py f.docx --revisions
Localizar/substituir (formatação mantida)	docx_edit.py replace f.docx --find A --replace B -o out.docx
Definir célula de tabela	docx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X
Inserir parágrafo antes do índice N	docx_edit.py insert f.docx --index N --text X --style Normal
Excluir parágrafo N	docx_edit.py delete f.docx --index N
Aplicar estilo ao parágrafo N	docx_edit.py style f.docx --index N --style "Heading 1"
Mesclar execuções adjacentes de formato igual	docx_edit.py normalize f.docx -o out.docx
Inserir campo de sumário antes do parágrafo N	docx_edit.py toc f.docx --index N -o out.docx
Rodapés "Página X de Y"	docx_edit.py page-numbers f.docx
Preencher {{tokens}}	docx_template.py tpl.docx values.json out.docx --strict
Listar revisões (id/autor/data/texto)	docx_revisions.py list f.docx
Aceitar / rejeitar todas as revisões	docx_revisions.py accept-all f.docx -o out.docx (ou reject-all)
Aceitar / rejeitar uma revisão	docx_revisions.py accept f.docx --id 3 -o out.docx
Listar comentários (+texto âncora)	docx_comments.py list f.docx
Adicionar comentário ancorado ao texto	docx_comments.py add f.docx --target "frase" --text "nota" --author Voce
Excluir comentário por id	docx_comments.py delete f.docx --id 0
Verificar integridade do pacote	docx_validate.py f.docx (código de saída 1 em caso de erro)

Procedimento

1. Criar. Escreva uma especificação JSON com write_file, depois execute scripts/docx_create.py. A especificação suporta: page (tamanho + margens em mm), strings header/footer, footer_page_numbers (adiciona um rodapé de campo "Página X de Y"), styles (estilos de parágrafo personalizados com fonte, tamanho, negrito/itálico, color hexadecimal), e blocks — heading (nível 1-9), paragraph (ou text ou uma lista runs onde cada execução pode definir bold/italic/underline), bullet_list, numbered_list, table (linha header renderizada em negrito, rows, opcional estilo de tabela interno como Table Grid), image (path, opcional width_mm), toc (campo de Sumário), e page_break. O formato completo da especificação está documentado no topo de scripts/docx_create.py.
2. Ler. Use scripts/docx_read.py com exatamente uma flag de modo. --text retorna parágrafos do corpo, todo o texto de células de tabela e texto de cabeçalho/rodapé como JSON. --structure retorna o esboço de títulos mais contagens de parágrafos/tabelas/seções. --images DIR copia cada arquivo em word/media/ para fora do pacote.
3. Editar. Use scripts/docx_edit.py. replace percorre corpo, tabelas (aninhadas inclusive), cabeçalhos e rodapés, e preserva a formatação das execuções; adicione --body-only para pular cabeçalhos/rodapés. Passe -o out.docx para manter o original; omita para editar no local. Índices de parágrafo para insert/delete/style/toc referem-se à ordem do corpo de --structure/--text. Execute normalize primeiro em documentos que passaram por edição pesada no Word — ele mescla execuções adjacentes com formatação idêntica para que localizar-substituir posterior corresponda de forma confiável.
4. Revisar revisões. docx_revisions.py list relata cada w:ins e w:del (id, autor, data, texto afetado) em qualquer lugar no corpo, tabelas, cabeçalhos ou rodapés. accept-all / reject-all resolve-os em massa; accept/reject --id N lida com uma única revisão. Aceitar mantém inserções e descarta texto deletado; rejeitar faz o inverso.
5. Comentários. docx_comments.py list retorna o id, autor, data, texto do corpo de cada comentário e o texto do documento ao qual está ancorado. add --target "alguma frase" ancora um novo comentário à primeira ocorrência dessa frase (as execuções são divididas conforme necessário; a formatação é preservada). delete --id N remove o comentário e seus marcadores sem tocar no texto do documento.
6. Modelo. Coloque tokens no estilo {{nome}} no documento. Execute scripts/docx_template.py com um objeto JSON de valores. Use --strict para falhar quando tokens permanecerem não preenchidos; a saída JSON lista contagens de filled e unfilled_tokens de qualquer maneira.
7. Verificar (sempre): releia a saída com --text ou --structure, e execute docx_validate.py em qualquer coisa que você produziu por meio de cirurgia de revisão/comentário.

Convertendo para PDF

Nenhum script necessário. Quando o LibreOffice estiver instalado, converta sem cabeça:

soffice --headless --convert-to pdf --outdir outdir/ file.docx

Verifique a disponibilidade primeiro (command -v soffice || command -v libreoffice). Se nenhum existir, informe ao usuário que a conversão para PDF está indisponível neste ambiente, em vez de improvisar — python-docx não pode renderizar PDFs, e a fidelidade do layout requer um renderizador real.

Armadilhas

• Tokens divididos entre execuções. O Word frequentemente fragmenta o texto em várias execuções. Os helpers de substituição colapsam execuções correspondentes (a substituição herda a formatação da primeira execução); executar docx_edit.py normalize primeiro reduz a fragmentação para todas as edições posteriores.
• Cobertura de revisões. docx_revisions.py resolve inserções e exclusões no nível de execução (a grande maioria). Revisões de marca de parágrafo e linha de tabela, registros de alteração de formato e movimentos são detectados por --revisions mas não resolvidos automaticamente — consulte references/revisions-and-comments.md e encaminhe-os para o Word.
• Encadeamento de comentários. Respostas e status "resolvido" residem em commentsExtended.xml, que esta skill ignora; comentários que ela adiciona são comentários simples de nível superior.
• Resultados de campos são calculados pelo Word. toc, page-numbers e as opções de especificação toc/footer_page_numbers escrevem códigos de campo. O Word/LibreOffice preenche as entradas e números reais quando o arquivo é aberto (o Word pode solicitar a atualização de campos); python-docx nunca calcula, então o texto do espaço reservado é exibido até então.
• Validação é uma verificação de integridade, não validação de esquema. docx_validate.py verifica o zip, partes necessárias, alvos de relacionamento, bytes mágicos de imagem e estilos referenciados. NÃO é validação XSD — um arquivo pode passar e ainda conter XML que o Word não gosta.
• Nomes de estilos devem existir. Aplicar um estilo que não está definido no documento gera KeyError. Estilos embutidos como Heading 1, List Bullet, List Number, Table Grid existem no modelo padrão; estilos personalizados devem ser declarados primeiro na especificação de criação.
• Listas numeradas reiniciam. List Number depende da numeração padrão do Word; listas separadas em um documento podem continuar a numeração em vez de reiniciar. Avise usuários que precisam de numeração precisa de várias listas.
• Gravações em células substituem formatação. set-cell usa cell.text = ..., o que redefine as execuções nessa célula para formatação simples.
• Codificação. Todos os arquivos de especificação/valores JSON são lidos como UTF-8 explicitamente; nunca confie em padrões de localidade ao escrever seu próprio código de cola.
• Não descompacte e use sed no XML. Edite por meio dos scripts (ou python-docx); substituição de texto bruto em document.xml corrompe arquivos facilmente. Use patch/write_file apenas para as entradas JSON, nunca no .docx em si.

Verificação

• Após criar/editar/modelo, execute docx_read.py out.docx --text e verifique se as strings esperadas aparecem (e strings antigas sumiram).
• Após aceitar/rejeitar, docx_revisions.py list deve retornar [] (ou apenas os ids que você deixou intencionalmente); após cirurgia de comentário, docx_comments.py list deve refletir a mudança e a saída --text deve estar inalterada.
• docx_validate.py out.docx sai com 0 e "ok": true em um pacote saudável — execute-o após qualquer manipulação de revisão/comentário/campo.
• Para modelos executados com --strict, ou verifique unfilled_tokens == [].
• Verificações de estrutura: --structure deve mostrar o esboço de títulos e formas de tabela esperados; --styles confirma que estilos personalizados foram aplicados.