aiskillstore/marketplace

Criação, edição e análise de DOCX

Visão Geral

Um usuário pode pedir para você criar, editar ou analisar 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ê tem diferentes ferramentas e workflows disponíveis para diferentes tarefas.

Árvore de Decisão de Workflow

Leitura/Análise de Conteúdo

Use as seções "Extração de texto" ou "Acesso direto ao XML" abaixo

Criação de Novo Documento

Use o workflow "Criando um novo documento Word"

Edição de Documento Existente

• Seu próprio documento + alterações simples Use o workflow "Edição OOXML básica"

• Documento de outra pessoa Use o "Workflow de redlining" (recomendado por 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ê só precisa ler o conteúdo de texto de um documento, converta-o 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 controle de alterações
pandoc --track-changes=all caminho-para-arquivo.docx -o saida.md
# Opções: --track-changes=aceitar/rejeitar/todas

Acesso direto ao XML

Você precisa de acesso direto ao XML 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> <diretório_de_saída>

Estruturas de arquivo chave

• word/document.xml - Conteúdo principal do documento
• word/comments.xml - Comentários referenciados em document.xml
• word/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 docx-js, que permite criar documentos Word usando JavaScript/TypeScript.

Workflow

1. OBRIGATÓRIO - LEIA O ARQUIVO INTEIRO: Leia docx-js.md (~500 linhas) completamente do início ao fim. NUNCA defina limites de intervalo ao ler este arquivo. Leia o conteúdo completo do arquivo para obter a sintaxe detalhada, regras críticas de formatação e melhores práticas antes de prosseguir com a criação do documento.
2. Crie um arquivo JavaScript/TypeScript usando os 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)
3. 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 de OOXML). A biblioteca lida automaticamente com a configuração de infraestrutura e fornece métodos para manipulação de documentos. Para cenários complexos, você pode acessar o DOM subjacente diretamente por meio da biblioteca.

Workflow

1. OBRIGATÓRIO - LEIA O ARQUIVO INTEIRO: Leia ooxml.md (~600 linhas) completamente do início ao fim. NUNCA defina limites de intervalo ao ler este arquivo. Leia o conteúdo completo do arquivo para obter a API da biblioteca Document e padrões XML para editar diretamente os arquivos do documento.
2. Descompacte o documento: python ooxml/scripts/unpack.py <arquivo_office> <diretório_de_saída>
3. Crie e execute um script Python usando a biblioteca Document (veja a seção "Biblioteca Document" em ooxml.md)
4. Empacote o documento final: python ooxml/scripts/pack.py <diretório_de_entrada> <arquivo_office>

A biblioteca Document fornece métodos de alto nível para operações comuns e 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 loteamento: 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 torna as edições mais difíceis de revisar 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 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 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

1. Obter representação markdown: Converta o documento para markdown com alterações controladas preservadas:

   pandoc --track-changes=all caminho-para-arquivo.docx -o atual.md
   

2. 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 de grep com texto único ao redor
   • Estrutura do documento (ex.: "primeiro parágrafo", "bloco de assinatura")
   • NÃO use números de linha do markdown - eles não mapeiam para a estrutura XML

   Organização de 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 data", "Lote 2: Alterações de nome de parte"
   • Por complexidade: Comece com substituições de texto simples, depois lide com alterações estruturais complexas
   • Sequencial: "Lote 1: Páginas 1-3", "Lote 2: Páginas 4-6"

3. 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 intervalo ao ler este arquivo. Preste atenção especial às seções "Biblioteca Document" e "Padrões de Alteração Controlada".
   • Descompacte o documento: python ooxml/scripts/unpack.py <arquivo.docx> <diretório>
   • Observe 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.

4. 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 data", "Atualizações de nome de parte", "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 texto em word/document.xml para verificar como o texto está dividido entre elementos <w:r>.

   b. Criar e executar script: Use get_node para encontrar nós, implemente as alterações e depois doc.save(). Veja a seção "Biblioteca Document" em ooxml.md para padrões.

   Nota: Sempre use grep em word/document.xml imediatamente 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 de script.

5. Empacotar o documento: Após todos os lotes estarem completos, converta o diretório descompactado de volta para .docx:

   python ooxml/scripts/pack.py descompactado documento-revisado.docx
   

6. 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 encontrar
     grep "frase substituída" verificacao.md  # Deve encontrar
     

   • Verifique se nenhuma alteração não intencional foi introduzida

Convertendo Documentos para Imagens

Para analisar visualmente documentos Word, converta-os para imagens usando um processo de duas etapas:

1. Converter DOCX para PDF:

   soffice --headless --convert-to pdf documento.docx
   

2. Converter páginas PDF para imagens JPEG:

   pdftoppm -jpeg -r 150 documento.pdf pagina
   

   Isso cria arquivos como pagina-1.jpg, pagina-2.jpg, etc.

Opções:

• -r 150: Define a resolução para 150 DPI (ajuste para equilíbrio qualidade/tamanho)
• -jpeg: Formato de saída JPEG (use -png para PNG, se preferir)
• -f N: Primeira página a converter (ex.: -f 2 inicia da página 2)
• -l N: Última página a converter (ex.: -l 5 para 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 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 ​​verbosas e operações redundantes
• Evite instruções print desnecessárias

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 segura de XML)