SeraphinaGlacia/ZUFE-Thesis-Skill

ZUFE Thesis Typesetter

Visão Geral

Use este Skill para converter seu trabalho acadêmico do Word em um PDF/LaTeX no formato ZUFE-Thesis. Siga rigorosamente os três fluxos:

• Fluxo A: Portaria rigorosa e preparação inteligente.
• Fluxo B: Extração formal do DOCX, livro-razão de conteúdo, confirmação semântica e escrita nos modelos.
• Fluxo C: Compilação, diagnóstico, garantia de qualidade e instruções de entrega.

O feedback principal deve ser dado na conversa para usuários não técnicos. Os scripts são responsáveis por verificações consistentes, extração, escrita de arquivos, compilação e geração de evidências legíveis por máquina.

Contrato Principal

Deve ser executado a partir do diretório raiz do template ZUFE-Thesis. Antes de modificar qualquer arquivo, confirme se a assinatura do template está completa.

Se o usuário ainda não preparou o projeto do template, explique que este Skill depende do template LaTeX original ZUFE-Thesis e siga a ordem abaixo:

1. Por padrão, oriente o usuário a usar o repositório original no GitHub: https://github.com/sqsssq/ZUFE-Thesis.
2. Se o GitHub estiver indisponível devido à rede, com a confirmação do usuário, use o link alternativo nacional: https://gitee.com/cwf818/ZUFE-Thesis.
3. Se ambos GitHub e Gitee estiverem indisponíveis, pare a conversão e solicite ao usuário que forneça um pacote zip do template, um diretório completo do template já extraído ou outra fonte confiável.

O agente pode ajudar a baixar, extrair ou mudar para o diretório raiz do template após confirmação do usuário, mas não pode pular silenciosamente a preparação do template, nem continuar a conversão em diretórios vazios, no repositório deste Skill ou em diretórios que faltem a assinatura do template.

Entrada padrão:

workspace/input/thesis.docx
workspace/input/metadata.yaml

Produtos intermediários padrão:

workspace/intermediate/thesis.json
workspace/intermediate/extracted.md

Saída padrão:

main.pdf
workspace/output/report.md
workspace/output/qa_report.md

Ordem dos Fluxos

Execute os fluxos em ordem, não pule a portaria só porque scripts posteriores podem remediar algo.

1. Fluxo A: Verifique template, workspace, DOCX, metadata, saídas antigas, ambiente Python DOCX, ambiente LaTeX/Biber.
2. Fluxo B: Escreva cada bloco visível ou extraível do Word em thesis.json; o agente atribui slots semânticos e confirma conteúdos de baixa confiança com o usuário; o script renderiza apenas os mapeamentos confirmados.
3. Fluxo C: Arquivar artefatos de compilação antigos, executar xelatex -> biber -> xelatex -> xelatex, diagnosticar falhas, fazer reparos mecânicos limitados e verificar qualidade do novo PDF.

Uso de Scripts

Todos os scripts aceitam --root e geram JSON ou escrevem relatórios JSON. O agente usa JSON para tomar decisões e traduz os resultados em uma breve lista que usuários comuns possam entender.

• scripts/check_template.py: Verifica a assinatura do template ZUFE-Thesis.
• scripts/prepare_workspace.py: Cria workspace/, coloca o DOCX no caminho padrão e pode arquivar saídas antigas com aprovação do usuário.
• scripts/check_env.py: Verifica Python, python-docx, xelatex, biber e pacotes TeX essenciais do template.
• scripts/prescan_docx.py: Pré-escaneamento leve do DOCX e extração de candidatos para metadata no Fluxo A. Não deve gerar thesis.json oficial.
• scripts/import_docx.py: Extração formal do Fluxo B, gerando thesis.json e extracted.md.
• scripts/export_assets.py: Extrai mídia do DOCX para Images/word_media/ e registra evidência.
• scripts/render_basicinfo.py: Escreve metadados, resumo e palavras-chave em chapters/basicinfo.tex.
• scripts/render_chapters.py: Escreve o mapeamento de capítulos confirmados em chapters/*.tex e chapters/mainbody.tex.
• scripts/render_bib.py: Escreve o BibTeX confirmado em Reference.bib, sem inventar referências.
• scripts/check_flow_b_gate.py: Impede a conclusão do Fluxo B se ainda houver blocos de origem não processados, não confirmados ou não renderizados.
• scripts/build.py: Arquivar main.pdf antigo, limpar arquivos de compilação temporários e executar a cadeia de compilação fixa.
• scripts/diagnose_build.py: Classifica falhas de compilação em problemas acionáveis.
• scripts/qa.py: Verifica frescor do PDF, texto, sinais chave, referências não resolvidas, loop fechado de BibTeX/citação, resíduos do template e placeholders.

Responsabilidades do Agente

O agente é responsável por julgamentos semânticos; os scripts não podem substituí-lo:

• Determinar se um parágrafo é título de seção, corpo do texto, resumo, referência, agradecimento, apêndice, legenda de figura/tabela ou ruído descartável.
• Consolidar problemas de baixa confiança e confirmar com o usuário.
• Explicar na conversa onde está travado, o motivo e os próximos passos.
• Não descartar conteúdo silenciosamente, nem colocar conteúdo no lugar errado.
• Não adivinhar faculdade, curso, data, orientador ou tipo de relatório a partir do nome do arquivo; metadata só pode vir de evidências do Word ou confirmação do usuário.
• Não ignorar problemas de estilo em nível de run como se fossem problemas de texto comum; sobrescrito, subscrito e tamanho de fonte anormal em tabelas devem ser expostos nos Fluxos B/C.
• O Fluxo C não corrige semântica do documento; erros de atribuição de conteúdo devem retornar ao Fluxo B.

Restrições Rígidas de Qualidade de Conversão

• Parágrafos do DOCX não podem manter apenas texto simples; devem preservar evidências de bold, italic, superscript, subscript e tamanho de fonte em nível de run. Números sobrescritos devem ser renderizados como \textsuperscript{...}, não achatados para texto normal.
• Números sobrescritos suspeitos de serem referências no Word não podem ser silenciosamente reescritos para texto simples. Para converter para \cite/\supercite oficial, o mapeamento de referências deve ser confirmado primeiro; caso contrário, pelo menos mantenha o sobrescrito visual.
• Numeração manual de figuras/tabelas no corpo do Word, como 图2.1, 图 2.1, 表1.2, não pode ser copiada diretamente para o código fonte final do capítulo. O agente deve confirmar o bloco de figura/tabela correspondente, atribuir um label estável e reescrever o corpo como 图~\ref{...} ou 表~\ref{...}; se não puder confirmar, bloquear o Fluxo B.
• Aspas ASCII duplas no texto comum devem ser convertidas para aspas esquerdas/direitas do LaTeX ``...''; aspas inteligentes chinesas são mantidas por padrão. Não aplique conversão de aspas a LaTeX raw, caminhos de imagem, comandos de citação e fórmulas.
• Quando faltar resumo em inglês ou palavras-chave em inglês, o usuário deve escolher: confirmar deixar em branco, fornecer manualmente ou permitir geração; não deixe em branco por padrão nem gere automaticamente com base no conteúdo chinês. Se o usuário permitir geração, explique que é uma complementação de conteúdo e registre a autorização em metadata.
• Ao gerar chapters/basicinfo.tex, deve incluir globalmente \hypersetup{hidelinks,pdfborder={0 0 0},pdfborderstyle={/S/U/W 0}} para evitar bordas coloridas em links de figuras e URLs no PDF.
• Tabelas usam por padrão o tamanho de fonte do template \zihao{5}. Não use incondicionalmente \resizebox{\textwidth}{!}{...}, pois isso amplia tabelas estreitas e quebra o tamanho da fonte.
• Apenas quando a largura natural da tabela exceder a largura do texto e não houver alternativa mais segura de largura de coluna, é permitido reduzir a tabela; é proibido ampliar tabelas para "preencher a largura do texto".
• Notas de rodapé, notas finais, fórmulas, hyperlinks, comentários, marcas de revisão, caixas de texto, cabeçalhos/rodapés e outros conteúdos não convertidos automaticamente devem entrar em unsupported_features, não podem ser ignorados silenciosamente.

Referências Detalhadas

• Antes de executar o Fluxo A, leia references/flow-a-gatekeeping.md.
• Ao diagnosticar ou reparar ambiente, leia references/environment-sop.md.
• Leia references/environment-setup-and-repair.md apenas quando precisar de comandos de plataforma, detalhes de instalação, correção de PATH ou instalação de pacotes TeX.
• Antes de fazer extração ou renderização no Fluxo B, leia references/flow-b-conversion.md.
• Antes de compilar ou fazer QA no Fluxo C, leia references/flow-c-export-and-qa.md.
• Antes de editar manualmente thesis.json, leia references/thesis-json-schema.md.

Feedback ao Usuário

Usuários não técnicos não precisam abrir relatórios primeiro. Dê no chat:

• Onde a portaria está travando.
• Por que continuar seria inseguro.
• O que o agente pode corrigir automaticamente.
• Que operações exigem aprovação ou fornecimento de arquivos pelo usuário.

Para usuários técnicos que precisam de detalhes, complemente com o caminho do relatório.