Doc

Habilidade DOCX

Quando usar

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

Fluxo de trabalho

1. Prefira 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 faltarem, 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 (títulos, estilos, tabelas, listas).
3. Após cada mudança significativa, re-renderize e inspecione as páginas.
4. Se a revisão visual não for possível, extraia texto com python-docx como fallback e avise sobre risco de layout.
5. Mantenha outputs intermediários organizados e limpe após aprovação final.

Convenções de temp e output

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

Dependências (instale se faltarem)

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 do 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 obrigató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 incluído:

python3 scripts/render_docx.py /path/to/file.docx --output_dir /tmp/docx_pages

Expectativas de qualidade

• Entregue um documento pronto para cliente: tipografia consistente, espaçamento, margens e hierarquia clara.
• Evite defeitos de formatação: texto cortado/sobreposto, tabelas quebradas, caracteres ilegíveis ou styling de template 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 não-quebrável) e outros dashes Unicode.
• Citações e referências devem ser legíveis por humanos; nunca deixe tokens de ferramenta ou strings de placeholder.

Verificações finais

• Re-renderize e inspecione cada página em zoom 100% antes da entrega final.
• Corrija qualquer problema de espaçamento, alinhamento ou paginação e repita o loop de renderização.
• Confirme que não há resquícios (arquivos temporários, renderizações duplicadas), a menos que o usuário peça para mantê-los.