Habilidade DOCX

O que Habilidade DOCX faz?

Quando usar

• Ler ou revisar conteúdo DOCX onde o layout é importante (tabelas, diagramas, paginação).
• Criar ou editar arquivos DOCX com formatação profissional.
• Validar o layout visual antes da entrega.

Fluxo de trabalho

1. Prefira a revisão visual (layout, tabelas, diagramas).
   • Se soffice e pdftoppm estiverem disponíveis, converta DOCX -> PDF -> PNGs.
   • Ou use scripts/render_docx.py (requer pdf2image e Poppler).
   • Se essas ferramentas estiverem faltando, instale-as ou peça ao usuário para revisar as páginas renderizadas localmente.
2. Use python-docx para edições e criação estruturada (cabeçalhos, estilos, tabelas, listas).
3. Após cada alteração significativa, renderize novamente e inspecione as páginas.
4. Se a revisão visual não for possível, extraia o texto com python-docx como fallback e destaque os riscos de layout.
5. Mantenha as saídas intermediárias organizadas e limpe após a aprovação final.

Convenções de diretórios temporários e saída

• Use tmp/docs/ para arquivos intermediários; exclua quando terminar.
• Escreva artefatos finais em output/doc/ ao trabalhar neste repositório.
• Mantenha nomes de arquivo estáveis e descritivos.

Dependências (instalar se ausentes)

Prefira uv para gerenciamento de dependências.

Pacotes Python:

uv pip install python-docx pdf2image

Se uv não estiver disponível:

python3 -m pip install python-docx pdf2image

Ferramentas de sistema (para renderização):

# macOS (Homebrew)
brew install libreoffice poppler

# Ubuntu/Debian
sudo apt-get install -y libreoffice poppler-utils

Se a instalação não for possível neste ambiente, informe ao usuário qual dependência está faltando e como instalá-la localmente.

Ambiente

Nenhuma variável de ambiente é necessária.

Comandos de renderização

DOCX -> PDF:

soffice -env:UserInstallation=file:///tmp/lo_profile_$$ --headless --convert-to pdf --outdir $OUTDIR $INPUT_DOCX

PDF -> PNGs:

pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME

Helper integrado:

python3 scripts/render_docx.py /caminho/para/arquivo.docx --output_dir /tmp/docx_pages

Expectativas de qualidade

• Entregue um documento pronto para o cliente: tipografia consistente, espaçamento, margens e hierarquia clara.
• Evite defeitos de formatação: texto recortado/sobreposto, tabelas quebradas, caracteres ilegíveis ou estilos de modelo padrão.
• Gráficos, tabelas e visuais devem ser legíveis nas páginas renderizadas, com alinhamento correto.
• Use apenas hífens ASCII. Evite U+2011 (hífen inseparável) e outros travessões Unicode.
• Citações e referências devem ser legíveis por humanos; nunca deixe tokens de ferramenta ou strings de placeholder.

Verificações finais

• Renderize novamente e inspecione cada página com zoom de 100% antes da entrega final.
• Corrija quaisquer problemas de espaçamento, alinhamento ou paginação e repita o ciclo de renderização.
• Confirme que não há sobras (arquivos temporários, renderizações duplicadas), a menos que o usuário peça para mantê-los.