Criação, edição e análise de arquivos DOCX
Visão Geral
O usuário pode solicitar que você crie, edite ou analise o conteúdo de um arquivo .docx. Um arquivo .docx é essencialmente um arquivo ZIP contendo arquivos XML e outros recursos que você pode ler ou editar. Você dispõe de diferentes ferramentas e workflows para diferentes tarefas.
Árvore de Decisão do Workflow
Leitura/Análise de Conteúdo
Use as seções "Extração de texto" ou "Acesso XML bruto" abaixo
Criação de Novo Documento
Use o workflow "Criando um novo documento Word"
Edição de Documento Existente
-
Documento próprio + alterações simples Use o workflow "Edição OOXML básica"
-
Documento de terceiros Use o "Workflow de redlining" (recomendado como padrão)
-
Documentos jurídicos, acadêmicos, empresariais ou governamentais Use o "Workflow de redlining" (obrigatório)
Leitura e análise de conteúdo
Extração de texto
Se você precisar apenas ler o conteúdo textual de um documento, converta o documento para markdown usando pandoc. O pandoc oferece excelente suporte para preservar a estrutura do documento e pode mostrar alterações controladas:
# Converter documento para markdown com alterações controladas
pandoc --track-changes=all caminho-para-arquivo.docx -o saida.md
# Opções: --track-changes=accept/reject/all
Acesso XML bruto
Você precisa de acesso XML bruto para: comentários, formatação complexa, estrutura do documento, mídia incorporada e metadados. Para qualquer um desses recursos, você precisará descompactar um documento e ler seu conteúdo XML bruto.
Descompactando um arquivo
python ooxml/scripts/unpack.py <arquivo_office> <diretoria_saida>
Estruturas de arquivo principais
word/document.xml- Conteúdo principal do documentoword/comments.xml- Comentários referenciados em document.xmlword/media/- Imagens e arquivos de mídia incorporados- Alterações controladas usam tags
<w:ins>(inserções) e<w:del>(exclusões)
Criando um novo documento Word
Ao criar um novo documento Word do zero, use o docx-js, que permite criar documentos Word usando JavaScript/TypeScript.
Workflow
- OBRIGATÓRIO - LEIA O ARQUIVO INTEIRO: Leia
docx-js.md(~500 linhas) completamente do início ao fim. NUNCA defina limites de alcance ao ler este arquivo. Leia o conteúdo completo do arquivo para obter sintaxe detalhada, regras críticas de formatação e melhores práticas antes de prosseguir com a criação do documento. - Crie um arquivo JavaScript/TypeScript usando componentes Document, Paragraph, TextRun (Você pode assumir que todas as dependências estão instaladas; caso contrário, consulte a seção de dependências abaixo)
- Exporte como .docx usando Packer.toBuffer()
Editando um documento Word existente
Ao editar um documento Word existente, use a biblioteca Document (uma biblioteca Python para manipulação OOXML). A biblioteca gerencia automaticamente a configuração da infraestrutura e fornece métodos para manipulação de documentos. Para cenários complexos, você pode acessar o DOM subjacente diretamente através da biblioteca.
Workflow
- OBRIGATÓRIO - LEIA O ARQUIVO INTEIRO: Leia
ooxml.md(~600 linhas) completamente do início ao fim. NUNCA defina limites de alcance ao ler este arquivo. Leia o conteúdo completo do arquivo para obter a API da biblioteca Document e padrões XML para edição direta de arquivos de documento. - Descompacte o documento:
python ooxml/scripts/unpack.py <arquivo_office> <diretoria_saida> - Crie e execute um script Python usando a biblioteca Document (veja a seção "Document Library" em ooxml.md)
- Compacte o documento final:
python ooxml/scripts/pack.py <diretoria_entrada> <arquivo_office>
A biblioteca Document fornece tanto métodos de alto nível para operações comuns quanto acesso direto ao DOM para cenários complexos.
Workflow de redlining para revisão de documentos
Este workflow permite planejar alterações controladas abrangentes usando markdown antes de implementá-las em OOXML. CRÍTICO: Para alterações controladas completas, você deve implementar TODAS as alterações sistematicamente.
Estratégia de Lotes: Agrupe alterações relacionadas em lotes de 3 a 10 alterações. Isso torna a depuração gerenciável enquanto mantém a eficiência. Teste cada lote antes de passar para o próximo.
Princípio: Edições Mínimas e Precisas
Ao implementar alterações controladas, marque apenas o texto que realmente muda. Repetir texto inalterado dificulta a revisão das edições e parece pouco profissional. Divida as substituições em: [texto inalterado] + [exclusão] + [inserção] + [texto inalterado]. Preserve o RSID da execução original para o texto inalterado, extraindo o elemento <w:r> do original e reutilizando-o.
Exemplo - Alterando "30 dias" para "60 dias" em uma frase:
# RUIM - Substitui a frase inteira
'<w:del><w:r><w:delText>O prazo é de 30 dias.</w:delText></w:r></w:del><w:ins><w:r><w:t>O prazo é de 60 dias.</w:t></w:r></w:ins>'
# BOM - Apenas marca o que mudou, preserva o <w:r> original para o texto inalterado
'<w:r w:rsidR="00AB12CD"><w:t>O prazo é de </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> dias.</w:t></w:r>'
Workflow de alterações controladas
-
Obter representação markdown: Converta o documento para markdown com as alterações controladas preservadas:
pandoc --track-changes=all caminho-para-arquivo.docx -o atual.md -
Identificar e agrupar alterações: Revise o documento e identifique TODAS as alterações necessárias, organizando-as em lotes lógicos:
Métodos de localização (para encontrar alterações no XML):
- Números de seção/cabeçalho (ex.: "Seção 3.2", "Artigo IV")
- Identificadores de parágrafo se numerados
- Padrões grep com texto circundante único
- Estrutura do documento (ex.: "primeiro parágrafo", "bloco de assinatura")
- NÃO use números de linha do markdown - eles não correspondem à estrutura XML
Organização em lotes (agrupe 3-10 alterações relacionadas por lote):
- Por seção: "Lote 1: Emendas da Seção 2", "Lote 2: Atualizações da Seção 5"
- Por tipo: "Lote 1: Correções de datas", "Lote 2: Alterações de nomes das partes"
- Por complexidade: Comece com substituições de texto simples, depois aborde alterações estruturais complexas
- Sequencial: "Lote 1: Páginas 1-3", "Lote 2: Páginas 4-6"
-
Ler documentação e descompactar:
- OBRIGATÓRIO - LEIA O ARQUIVO INTEIRO: Leia
ooxml.md(~600 linhas) completamente do início ao fim. NUNCA defina limites de alcance ao ler este arquivo. Preste atenção especial às seções "Document Library" e "Tracked Change Patterns". - Descompacte o documento:
python ooxml/scripts/unpack.py <arquivo.docx> <dir> - Anote o RSID sugerido: O script de descompactação sugerirá um RSID para usar em suas alterações controladas. Copie este RSID para uso na etapa 4b.
- OBRIGATÓRIO - LEIA O ARQUIVO INTEIRO: Leia
-
Implementar alterações em lotes: Agrupe as alterações logicamente (por seção, por tipo ou por proximidade) e implemente-as juntas em um único script. Esta abordagem:
- Facilita a depuração (lote menor = mais fácil isolar erros)
- Permite progresso incremental
- Mantém a eficiência (tamanho de lote de 3-10 alterações funciona bem)
Agrupamentos de lote sugeridos:
- Por seção do documento (ex.: "Alterações na Seção 3", "Definições", "Cláusula de rescisão")
- Por tipo de alteração (ex.: "Alterações de datas", "Atualizações de nomes das partes", "Substituições de termos legais")
- Por proximidade (ex.: "Alterações nas páginas 1-3", "Alterações na primeira metade do documento")
Para cada lote de alterações relacionadas:
a. Mapear texto para XML: Use grep no
word/document.xmlpara verificar como o texto está dividido entre elementos<w:r>.b. Criar e executar script: Use
get_nodepara encontrar nós, implemente as alterações e depoisdoc.save(). Consulte a seção "Document Library" em ooxml.md para padrões.Nota: Sempre execute grep no
word/document.xmlimediatamente antes de escrever um script para obter os números de linha atuais e verificar o conteúdo do texto. Os números de linha mudam após cada execução do script. -
Empacotar o documento: Após todos os lotes estarem concluídos, converta o diretório descompactado de volta para .docx:
python ooxml/scripts/pack.py descompactado documento-revisado.docx -
Verificação final: Faça uma verificação abrangente do documento completo:
- Converta o documento final para markdown:
pandoc --track-changes=all documento-revisado.docx -o verificacao.md - Verifique se TODAS as alterações foram aplicadas corretamente:
grep "frase original" verificacao.md # NÃO deve encontrá-la grep "frase substituta" verificacao.md # Deve encontrá-la - Verifique se nenhuma alteração não intencional foi introduzida
- Converta o documento final para markdown:
Convertendo Documentos para Imagens
Para analisar visualmente documentos Word, converta-os para imagens usando um processo de duas etapas:
-
Converter DOCX para PDF:
soffice --headless --convert-to pdf documento.docx -
Converter páginas PDF para imagens JPEG:
pdftoppm -jpeg -r 150 documento.pdf paginaIsso cria arquivos como
pagina-1.jpg,pagina-2.jpg, etc.
Opções:
-r 150: Define resolução para 150 DPI (ajuste para equilíbrio entre qualidade e tamanho)-jpeg: Saída em formato JPEG (use-pngpara PNG, se preferir)-f N: Primeira página a converter (ex.:-f 2começa da página 2)-l N: Última página a converter (ex.:-l 5para na página 5)pagina: Prefixo para arquivos de saída
Exemplo para intervalo específico:
pdftoppm -jpeg -r 150 -f 2 -l 5 documento.pdf pagina # Converte apenas as páginas 2-5
Diretrizes de Estilo de Código
IMPORTANTE: Ao gerar código para operações DOCX:
- Escreva código conciso
- Evite nomes de variáveis verbosos e operações redundantes
- Evite comandos print desnecessários
Dependências
Dependências necessárias (instale se não estiverem disponíveis):
- pandoc:
sudo apt-get install pandoc(para extração de texto) - docx:
npm install -g docx(para criar novos documentos) - LibreOffice:
sudo apt-get install libreoffice(para conversão para PDF) - Poppler:
sudo apt-get install poppler-utils(para pdftoppm converter PDF para imagens) - defusedxml:
pip install defusedxml(para análise XML segura)