Ryanzucchi/Eldritch_Lich / .agents/skills/exportacao-multiplos-formatos
exportacao-multiplos-formatos
VerifiedPipeline de exportação de manuscritos para DOCX, PDF, ePub, Markdown e TXT com preservação de formatação e metadados. Ativar ao implementar funcionalidades de exportação de textos (UC-008, UC-064, UC-089, UC-197) ou importação de formatos externos (UC-194, UC-195, UC-196).
exportacao-multiplos-formatos
Descrição
A skill exportacao-multiplos-formatos especifica o pipeline de conversão de documentos entre o formato interno JSON ProseMirror e os formatos externos usados por escritores e editoras (DOCX, PDF, ePub, Markdown, TXT). Ela define os conversores recomendados, o fluxo de processamento assíncrono em background para exportações grandes, a estrutura de metadados incluídos em cada formato e os casos especiais de formatação literária (notas de rodapé, numeração de capítulos).
Quando usar
Gatilhos concretos e observáveis:
- Implementação das ações de exportação no menu do editor (UC-008, UC-064, UC-197).
- Importação de manuscritos externos (Scrivener/DOCX/ePub) para o editor (UC-194, UC-195, UC-196).
- Geração do PDF ilustrado do universo (wiki + fichas + grafo) em UC-089.
Quando NÃO usar:
- Para exportação de dados de usuário por conformidade LGPD (usar
conformidade-com-lgpd-e-gdpr-por-design). - Para portabilidade do grafo GUF em formato JSON-LD (coberto pela mesma skill LGPD).
Pré-requisitos
- DOCX:
docx(Node.js) oupython-docx(Python). - PDF:
puppeteer(headless Chrome) ou@react-pdf/renderer. - ePub:
epub-gen(Node.js). - Markdown: conversão nativa do JSON ProseMirror para Markdown via
prosemirror-markdown. - Importação DOCX:
mammoth.jspara extração de texto e estilos básicos do .docx. - Fila de processamento assíncrono (ver skill
queue-de-tarefas-assincrona-com-bull) para exportações de documentos longos.
Processo (passo a passo executável)
-
Exportação (fluxo geral):
- Usuário clica "Exportar como [formato]" no menu do editor.
- Para documentos menores que
SYNC_EXPORT_MAX_WORDSpalavras: processar sincronamente e retornar o arquivo para download direto. - Para documentos maiores: enfileirar job de exportação na fila Bull, retornar
202 Acceptedcomjob_id, notificar o usuário via WebSocket quando o arquivo estiver pronto.
-
Exportação para DOCX:
- Percorrer a árvore de nós do JSON ProseMirror e mapear para objetos
docx:paragraph→Paragraph;heading→Headingcom nível;bold/italic→TextRuncom estilos.- Notas de rodapé →
FootnoteReference+Footnotedo pacotedocx.
- Incluir metadados no
Properties: título, autor, data de exportação.
- Percorrer a árvore de nós do JSON ProseMirror e mapear para objetos
-
Exportação para PDF (via Puppeteer):
- Renderizar o documento como HTML estilizado em uma página Express interna.
- Usar Puppeteer para capturar a página e gerar o PDF com
page.pdf({ format: 'A4', printBackground: true }). - Incluir cabeçalho com título do manuscrito e rodapé com número de página.
-
Exportação para ePub:
- Dividir o documento por nós
headingde nível 1 (capítulos) para gerar a estrutura de navegação do ePub. - Incluir metadados Dublin Core: título, autor, idioma, ISBN (se cadastrado na ficha do projeto).
- Dividir o documento por nós
-
Importação de DOCX:
- Usar
mammoth.jspara extrair o HTML simplificado do arquivo .docx. - Converter o HTML extraído para JSON ProseMirror via
DOMParser+ serializer customizado. - Criar um novo documento no projeto com o conteúdo importado e marcar como
is_imported = true.
- Usar
Parâmetros e configuração
| Parâmetro | Descrição | Padrão |
|---|---|---|
SYNC_EXPORT_MAX_WORDS | Máximo de palavras para exportação síncrona | 50000 |
PDF_PAGE_FORMAT | Formato de página do PDF exportado | A4 |
PDF_MARGIN_MM | Margens do PDF em milímetros | { top: 25, bottom: 25, left: 30, right: 30 } |
EPUB_SPLIT_BY | Nível de heading usado para dividir capítulos no ePub | 1 |
Armadilhas e como evitá-las
- Armadilha: Gerar PDFs de romances longos (300+ páginas) de forma síncrona na requisição HTTP, causando timeout de 30+ segundos e experiência péssima para o usuário.
Mitigação: Usar a fila Bull para processar exportações de documentos acima de
SYNC_EXPORT_MAX_WORDSpalavras em background. O usuário recebe feedback visual "Exportação em andamento..." e uma notificação push quando o arquivo estiver disponível para download.
Critérios de validação (Definition of Done)
- Um romance de 80.000 palavras é exportado para DOCX com formatação preservada (negrito, itálico, capítulos) em menos de 30 segundos via processamento em fila.
- A importação de um arquivo .docx de 50 páginas gera um documento JSON ProseMirror válido sem perder o texto.
Exemplos
Exportação DOCX (documento pequeno):
GET /api/documents/42/export?format=docx → retorna imediatamente Content-Disposition: attachment; filename="Kael-e-as-Sombras.docx".
Exportação PDF (documento grande):
POST /api/documents/42/export { format: 'pdf' } → { status: 202, job_id: "job-abc123" } → WebSocket: { event: 'export_ready', download_url: '/downloads/job-abc123.pdf', expires_in: '24h' }.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |