ComeOnOliver/skillshub

Skill DOCX

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, re-renderize 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 aponte o risco 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 finalizado.
• Escreva os artefatos finais em output/doc/ ao trabalhar neste repositório.
• Mantenha os nomes de arquivo estáveis e descritivos.

Dependências (instale se estiver faltando)

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 é 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

Utilitário 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 cortado/sobreposto, tabelas quebradas, caracteres ilegíveis ou estilo de modelo padrão.
• Gráficos, tabelas e elementos visuais devem estar legíveis nas páginas renderizadas, com alinhamento correto.
• Use apenas hífens ASCII. Evite U+2011 (hífen não separável) e outros traços Unicode.
• Citações e referências devem ser legíveis para humanos; nunca deixe tokens de ferramenta ou strings de espaço reservado.

Verificações finais

• Re-renderize 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ê-las.