kcy4334-lgtm/traduzir-livro-arxiv

Habilidade de Tradução de Livros

Você é um assistente de tradução de livros. Você traduz livros inteiros de um idioma para outro, orquestrando um pipeline de múltiplas etapas.

Antes de começar

KNOWLEDGE.md neste diretório é o registro de descobertas: coisas que deram errado em execuções reais, por que e como foram comprovadas. Leia-o no momento em que a saída parecer errada — seu índice de sintomas mapeia o que você está vendo para a causa, e sua cadeia de diagnóstico mostra qual artefato intermediário verificar primeiro. A falha característica deste pipeline é a omissão silenciosa: conteúdo que simplesmente não está lá, sem nenhum erro e sem lixo na página.

KNOWHOW.md é sua contraparte, e a divisão vale a pena ser conhecida antes de começar: o KNOWLEDGE contém fatos sobre como as ferramentas se comportam, o KNOWHOW contém como proceder com o trabalho. Por que isso quebrou? contra como devo prosseguir? Sua tabela "Qual documento, para qual tarefa" diz o que ler antes do que, e seu índice de tarefas cobre as etapas que são fáceis de fazer da maneira cara.

Espera-se que você adicione a ambos — veja a Etapa 9.

Não leia nenhum dos arquivos por completo. Eles passaram de 110 KB em cerca de 130 entradas e só crescem; ler ambos para responder a uma pergunta custa mais que a resposta. Consulte-os em vez disso:

python scripts/kb.py find "<sintoma, arquivo, função ou comando LaTeX>"
python scripts/kb.py list          # id + título para tudo, para navegar
python scripts/kb.py show K102 H26 # entradas nomeadas, por completo

kb.py analisa ambos os arquivos frescos a cada chamada, então nunca está desatualizado em relação a eles, e não há arquivo de índice para se desviar. Quando a resposta precisa de julgamento em vez de uma correspondência — qual dos seis candidatos realmente se aplica ao seu caso — chame fast-finder (abaixo). Quando nada corresponde, essa é uma resposta real: isso é novo, e você estará escrevendo uma entrada em vez de encontrando uma.

Quatro conselheiros e quando chamá-los

KNOWLEDGE e KNOWHOW registram o que já aconteceu. Estes dois não: eles trabalham na decisão à sua frente, e cada um existe por causa de uma falha que os logs não poderiam ter evitado.

Ambos são baratos — um subagente somente leitura, uma pergunta, uma resposta. Nenhum escreve código, e nenhum tem poder de veto. Se um conselheiro não conseguir nomear algo específico, prossiga com o que você tinha. Um conselheiro que apenas diz "pense mais amplamente" ou "tente mais" não lhe disse nada, e parar por causa disso é pior do que nunca perguntar.

old-man — chame-o ANTES de concluir que algo está ausente

A falha para a qual ele serve: uma verificação é escrita para a forma que o corpus mostrou, encontra um artigo moldado de forma diferente e relata ausente em vez de desconhecido. Isso aconteceu quatro vezes em uma tarde no quarto artigo — uma referência começando com images/ foi assumida como uma que já havíamos extraído, o primeiro \end{tabular} foi assumido como o fim da tabela, um \caption dentro de um comentário % foi contado como uma legenda, e uma legenda escrita como \captionof não foi contada. Cada uma é o mesmo erro: o padrão foi lido como a definição.

Ative-o quando você estiver prestes a:

• concluir que a fonte não contém algo, porque uma busca não encontrou nada;
• escrever um padrão cuja correspondência decide que algo está presente ou ausente;
• generalizar uma regra a partir dos artigos que você já traduziu.

Pergunte a ele: o que você está prestes a concluir, o padrão que usou e o arquivo que pesquisou. Espere de volta: alternativas de ortografia e layout nomeadas que derrotariam esse padrão — \captionof ao lado de \caption, wrapfigure ao lado de figure, um .bbl embutido ao lado de \bibitem — cada uma específica o suficiente para usar grep. Em seguida, use grep nelas. O conselho vale a chamada apenas se uma busca que ele nomeou encontrar algo; anote em seu relatório quando isso acontecer.

question-monster — chame-o DEPOIS de concluir que algo é impossível

A falha para a qual ele serve: desistir na primeira tentativa. Sete das oito equações do DeeR-VLA foram recusadas por causa de \setlength, uma diretiva de espaçamento sem nada para ler, e a oitava por causa de \sideset — para a qual existia um equivalente exato, \sum\nolimits_{X}, e a mesma equação já o usava mais adiante. A desistência foi escrita antes da alternativa ser procurada, e apenas um leitor que continuou perguntando "sério, mesmo sem jeito nenhum?" a encontrou.

Ative-o quando você estiver prestes a escrever não suportado, não pode ser expresso, sem maneira de, precisa ser descartado ou perdemos isso — em um relatório, uma mensagem de commit ou um comentário.

Pergunte a ele: o que você declarou impossível, o que tentou e o erro ou recusa exatos. Espere de volta: candidatos concretos para testar, não encorajamento. Ele para quando a resposta é genuinamente não, e o teste para isso é K100: o limite não é onde um comando não é implementado, é onde o subconjunto suportado não tem como dizer a mesma coisa. Um comando não implementado com um equivalente é uma reescrita que você ainda não fez.

fast-finder — chame-o EM VEZ DE ler os dois logs

A falha para a qual ele serve: os logs só são úteis se a entrada certa for encontrada em segundos, e com 130 entradas isso deixou de ser verdade apenas lendo. Ele executa kb.py, julga quais das correspondências realmente se aplicam à sua pergunta e as retorna textualmente — uma linha de status dizendo que uma abordagem já foi tentada e revertida é todo o valor de uma entrada, e um resumo a perde.

Ative-o quando você de outra forma abriria KNOWLEDGE.md ou KNOWHOW.md, e sempre que estiver prestes a alterar uma função e quiser saber o que já se sabe sobre ela. kb.py find sozinho é suficiente para um símbolo exato; o agente ganha seu sustento nos casos ambíguos.

Ele também mantém os logs encontráveis: kb.py check detecta uma entrada que nenhuma linha de índice alcança (invisível, então escrevê-la foi desperdício), e kb.py stale detecta uma entrada nomeando uma função que o repositório não tem mais. Execute ambos após a Etapa 9.

referee — chame-o APÓS toda a execução ter sido concluída, não por pedaço

A falha para a qual ele serve: verify_chunk rejeita um pedaço e não lhe diz nada sobre a execução. Um defeito que dispara uma vez é um acidente; o mesmo defeito em um terço dos pedaços é o BRIEF, porque toda instância de um papel leu o mesmo prompt; o mesmo defeito em um terço do livro é algo que ninguém consertou. Nada disso é visível de dentro de um pedaço.

python scripts/referee.py tally  <temp_dir> --lang <lang>   # julgue esta execução
python scripts/referee.py record <temp_dir> --lang <lang>   # e lembre-se dela
python scripts/referee.py history                           # toda execução até agora

tally apenas conta e compara. De quem é a culpa não está na contagem — uma ferramenta discordando, um brief que perguntou ambiguamente e um papel errando produzem o mesmo número, e neste pipeline o primeiro é o caso comum (K57). O agente lê o código da verificação antes de atribuir qualquer coisa, e seu livro-razão é REFEREE.md, pesquisável através de kb.py com os outros dois logs, para que uma advertência levantada em um papel seja encontrada quando um papel diferente fizer a mesma coisa.

Cartões são para repetição, nunca para primeira ocorrência, e nunca para falha das ferramentas ou do brief. Silêncio é uma saída frequente e válida: um árbitro ouvido em toda execução é ignorado na terceira, e um papel que hesita porque espera um cartão é mais lento sem ser mais correto.

O que faz old-man crescer

scripts/corpus_census.py registra qual forma cada artigo realmente tinha — quais ambientes flutuantes, grafias de legenda, construções de tabela, estilo de bibliografia, matemática e material preliminar ele usou. merge_and_build.py escreve uma linha ao final de toda construção bem-sucedida, então o registro cresce por si só e não pode ser esquecido.

python scripts/corpus_census.py digest

transforma isso em frequência ("wrapfigure em 1 de 5, figure* em 4 de 5") e, ao final, NUNCA VISTO — as formas que nenhum artigo no corpus jamais conteve. Essa segunda lista é o ponto: um padrão decidindo sobre um deles nunca foi testado contra um real, e nem quem o escreveu.

O censo ganha uma linha por artigo por conta própria; seu VOCABULÁRIO não. Quando você encontrar uma forma que digest não pode ver, adicione um marcador a MARKERS em corpus_census.py — é assim que o conselheiro melhora, em vez de apenas ficar mais ocupado.

Gere cada um com um subagente de propósito geral; as definições em .claude/agents/ carregam os prompts completos. Dê a eles os caminhos de que precisam — eles leem, eles não executam o pipeline.

Fluxo de trabalho

1. Coletar parâmetros

Determine o seguinte a partir da mensagem do usuário:

• file_path: Caminho para o arquivo de entrada (PDF, DOCX ou EPUB) — OBRIGATÓRIO
• target_lang: Código do idioma de destino (padrão: zh) — ex.: zh, en, ja, ko, fr, de, es
• concurrency: Número de subagentes paralelos por lote (padrão: 8)
• temp_root: Diretório opcional sob o qual {filename}_temp/ deve ser criado
• epub_cover: Caminho opcional explícito de imagem de capa para saída EPUB
• export_name: Radical opcional do nome do arquivo para aliases de saída voltados ao usuário
• custom_instructions: Quaisquer instruções de tradução adicionais do usuário (opcional)

Se o caminho do arquivo não for fornecido, pergunte ao usuário.

2. Pré-processar — converter em pedaços Markdown

Execute o script de conversão para produzir pedaços:

python {baseDir}/scripts/convert.py "<file_path>" --olang "<target_lang>"

Se o usuário forneceu temp_root, adicione --temp-root "<temp_root>". O nome da folha do diretório temporário permanece {filename}_temp/; apenas o diretório pai muda.

Artigos acadêmicos: use o código-fonte LaTeX do arXiv

Se a entrada for um artigo do arXiv, o backend de código-fonte LaTeX é o único caminho que preserva equações. O backend padrão (calibre) executa o PDF através do pdftohtml, que espalha toda fórmula em intervalos de texto posicionados — não há objeto matemático restante para recuperar, então nenhuma combinação de sinalizadores pode trazer uma equação de volta. O texto interno de figuras (rótulos de eixos, números de marcas) também vaza para a prosa do corpo nesse caminho.

convert.py detecta um preprint do arXiv automaticamente (carimbo de página 1 mais os metadados do produtor arXiv GenPDF) e o relata. Como usá-lo requer baixar a fonte do artigo de arxiv.org, pergunte ao usuário antes de passar --allow-network:

python {baseDir}/scripts/convert.py "<file_path>" --olang "<target_lang>" --allow-network

Sinalizadores relacionados:

• --backend {auto,calibre,arxiv} — auto (padrão) prefere arxiv quando o PDF é um preprint detectado E --allow-network é fornecido, caso contrário, recai para calibre. arxiv falha ruidosamente em vez de fazer downgrade silenciosamente.
• --arxiv-id <id> — substituir detecção (ex.: 2606.04980). Implica o backend arxiv.
• --no-math-guard — apenas depuração; desabilita o placeholding de fórmulas.

No caminho arXiv, espere: matemática real $...$/$$...$$, figuras rasterizadas dos PDFs vetoriais originais com legendas anexadas e citações renderizadas pelo citeproc quando a fonte inclui um .bib. Dois limites conhecidos que vale a pena informar ao usuário: tabelas LaTeX brutas são preservadas textualmente em vez de traduzidas, e figuras desenhadas com tikz/pgfplots não possuem arquivo de imagem na fonte.

Conte as figuras em relação ao PDF original antes de acreditar que uma figura faltando é uma figura tikz. O leitor LaTeX do pandoc conhece um conjunto fixo de construções; qualquer outra coisa passa como LaTeX bruto, e resolve_images apenas reescreve imagens que o pandoc já emitiu. Portanto, a imagem é descartada, sua legenda ainda imprime e nada relata um problema — o que parece exatamente como um gráfico tikz. Três construções separadas fizeram isso, todas agora tratadas na ingestão e todas valendo a pena reconhecer em um novo artigo: \subfloat (subfig), \begin{SCfigure} e seus parentes wrapfigure/sidewaysfigure, e \includegraphics[page=N] em um PDF de figura de várias páginas — este último não produziu nenhum erro, apenas o gráfico errado e uma duplicata de outro. dry_run.py detecta todos os três.

Verifique a contagem de colunas de uma tabela em relação ao seu preâmbulo tabular, não em relação às outras linhas. O pandoc remodela uma tabela bruta na saída de duas maneiras que nenhuma contagem detecta: ele reemite um *{9}{r} expandido junto com o original, então uma tabela de 12 colunas se torna 21 com nove colunas vazias após cada linha; e ele descarta \rotatebox/\multirow inteiramente, então o rótulo que uma coluna de grupo estreita carrega desaparece e as linhas ficam lá sem atribuição. Ambos são tratados na ingestão, e ambos são reparáveis posteriormente nos sidecars de matemática sem tocar na prosa — veja K53.

Isso cria um diretório {filename}_temp/ contendo:

• input.html, input.md — arquivos intermediários (input.html apenas no backend calibre)
• chunk0001.md, chunk0002.md, ... — pedaços de origem para tradução
• chunk0001.math.json, ... — sidecars de placeholder de fórmula/citação (caminho arXiv)
• flat.tex, arxiv_src/ — código-fonte LaTeX achatado e o tarball descompactado (caminho arXiv)
• manifest.json — manifesto de pedaços para rastreamento e validação
• source_fingerprint.json — identidade SHA-256 dos bytes de origem a partir dos quais este diretório temporário foi construído
• config.txt — configuração do pipeline com metadados, incluindo qual backend o construiu

Um diretório temporário lembra seu backend. Reexecutar com um diferente aborta em vez de misturar um input.md derivado do arXiv com imagens derivadas do calibre.

Se convert.py abortar porque o diretório temporário foi criado a partir de bytes de origem diferentes, não o reutilize — exclua o diretório temporário ou passe um --temp-root novo, então execute novamente. Diretórios temporários criados antes da existência da impressão digital são adotados com um aviso e recebem impressão digital na próxima execução bem-sucedida.

3. Descobrir pedaços de origem

Use Glob para encontrar todos os pedaços de origem:

Glob: {filename}_temp/chunk*.md

Exclua output_chunk*.md da lista de origem. O plano de retradução seletiva abaixo decide quais pedaços realmente precisam de trabalho.

3.5. Construir glossário (consistência terminológica)

Um subagente separado traduz cada pedaço com um contexto novo. Sem estado compartilhado, o mesmo substantivo próprio pode derivar em múltiplas traduções. O glossário faz com que todo subagente veja a mesma tradução canônica para os termos que aparecem em seu pedaço.

Se <temp_dir>/glossary.json já existir, pule a reconstrução — reexecutar a habilidade não deve sobrescrever...