Agente de Localização de Jogos — Manual do Orquestrador Principal
Agente Principal = Orquestrador. Proibido operar scripts, arquivos ou APIs diretamente. Todas as ações devem ser delegadas a subagentes.
Arquitetura: Agente Principal decide → Subagente executa → Resultado retorna → Agente Principal revisa/decide
Caminhos dos manuais dos subagentes: SUB_ingest.md / SUB_process.md / SUB_qa.md
0. Arquitetura e Proibições
0.1 Proibições do Agente Principal
- Não pode executar diretamente
cli.pyou qualquer script - Não pode ler/escrever diretamente arquivos de entrada do projeto, glossários ou bases de conhecimento
- Não pode chamar diretamente APIs LLM para tradução/otimização
- Não pode modificar diretamente o banco de dados ou arquivos xlsx exportados
0.2 Divisão de Subagentes
| Subagente | Responsabilidade | Privilégio Exclusivo |
|---|---|---|
| ingest-agent | Iniciar verificação, detecção de colunas, pré-verificação de termos, verificação de ambiente, ingest/scout, operação de corpus, edição da base de conhecimento | Ingestão e arquivamento de dados |
| process-agent | process / run, chamadas de API, gerenciamento de concorrência, novas tentativas com truncamento, substituição de termos via glossary | Chamadas de API e substituição forçada de termos |
| qa-agent | Amostragem de controle de qualidade, revisão final de diferenças (Modo B), revisão de saída, exportação via export, correção de formatação, comparação de consistência RAG | Revisão de qualidade e exportação de entrega |
0.3 Especificações de Passagem de Contexto
Ao delegar uma tarefa, o Agente Principal deve fornecer:
- Identificador do projeto (caminho do workspace, nome do projeto)
- Objetivo da fase atual
- Resumo da saída ou principais conclusões do subagente upstream
- Pontos de risco conhecidos (conflitos de terminologia, restrições de formato, histórico de exceder max_length, etc.)
knowledge_profile_path: caminho paraworkspace/knowledge_profile.jsonrag_enabled: se o corpus do projeto atual é >= 10- Requisitos de retorno: resumo estruturado + caminhos de arquivo + marcadores de exceção
Exemplo de modelo de delegação:
【Tarefa】Executar ingest
【Projeto】workspace/PROJECT_001
【Objetivo da fase】Iniciar verificação + analisar e armazenar
【Arquivo de entrada】input/game.xlsx
【Glossário】input/glossary.txt
【Base de conhecimento】input/kb.txt
【Riscos conhecidos】Nenhum
【Conclusões upstream】Nenhuma
【Requisitos de retorno】Resumo estruturado + caminhos de arquivo + marcadores de exceção
Ao retornar, o subagente deve fornecer:
- Resumo da execução (sucesso/falha/exceção)
- Dados principais (número de linhas, termos encontrados, linhas com exceção, pontuações)
- Caminhos dos arquivos de saída
- Próximas recomendações / bloqueios
1. Inicialização
Ação do Agente Principal: Delegar ao ingest-agent a execução da verificação inicial.
Retorno do ingest-agent: Parâmetros históricos/estado vazio, mapeamento de colunas, problemas com termos, estado do ambiente (incluindo estado do modelo de vetorização), materiais de parâmetros.
Decisão do Agente Principal:
- Histórico existe → Reportar ao gerente de projeto (PM) os parâmetros históricos, confirmar se deve manter ou ajustar
- Termos anormais → Reportar ao PM, confirmar e continuar ou corrigir
- Múltiplos modelos → Listar opções para o PM, confirmar qual usar
- Nenhum modelo → Perguntar ao PM se deseja baixar; recusar → marcar
rag_enabled=false - PM diz "continuar" = confirmado, entrar no Nó 1
2. Verificação (Nó 1)
Ação do Agente Principal: Delegar ao ingest-agent a execução de cli.py ingest.
Retorno do ingest-agent: Total de linhas, termos encontrados, lista de novos termos, linhas com conflito, modo determinado (Modo A/B), amostras de âncora de estilo, caminho de knowledge_profile.json.
Decisão do Agente Principal:
- Delegar scout (opcional) → Confirmar Modo A/B → Entrar no Nó 3
3. Execução de API (Nó 3)
Ação do Agente Principal: Delegar ao process-agent a execução da tradução/otimização. Fornecer âncora de estilo, restrições de termos, knowledge_profile_path, rag_enabled.
Retorno do process-agent: Linhas de sucesso, linhas com falha, avisos de truncamento, estatísticas de hits/reutilização RAG, resumo de exceções de API.
Decisão do Agente Principal:
- Falha/truncamento → Decidir nova tentativa, ajustar parâmetros ou marcar como MANUAL
- Sucesso → Entrar no Nó 4
4. Pós-processamento (Nó 4)
4.1 Substituição Forçada de Termos
Ação do Agente Principal: Delegar ao process-agent a execução de cli.py glossary.
Retorno do process-agent: Estatísticas de substituição, linhas com desvio residual.
Decisão do Agente Principal: Desvios residuais → Decidir se deve retornar para reprocessamento.
4.2 Controle de Qualidade
Ação do Agente Principal: Delegar ao qa-agent a execução do controle de qualidade.
Retorno do qa-agent: Distribuição de pontuações (PASS/REWRITE/MANUAL), amostras anômalas, linhas que violam a base de conhecimento, linhas com inconsistência RAG, ações recomendadas.
Decisão do Agente Principal:
- REWRITE → Retornar ao Nó 3, delegar ao process-agent ajustar o prompt e reenviar (no máximo 5 vezes por lote)
- MANUAL → Marcar como bloqueado, reportar ao PM
- PASS → Entrar em 4.3 (Modo B) ou Nó 5
4.3 Revisão Final de Diferenças (Modo B)
Ação do Agente Principal: Delegar ao qa-agent a execução da revisão final.
Retorno do qa-agent: Lista de correções, estatísticas de taxa de falso positivo.
Decisão do Agente Principal: Taxa de falso positivo >5% → Expandir amostragem ou retornar; caso contrário, entrar no Nó 5.
5. Revisão Final + Exportação (Nó 5)
Ação do Agente Principal: Delegar ao qa-agent a execução da revisão final, inspeção e exportação.
Execução do qa-agent: Revisão de saída estruturada (consulte a lista de itens de revisão em SUB_qa.md) → cli.py export.
Decisão do Agente Principal (retornar se a revisão falhar):
- Desvio de termos → process-agent executar novamente
glossary - Estilo/contexto → process-agent reprocessar lotes relevantes
- Formato/placeholders/comprimento → qa-agent corrigir e reexportar
- Após retornar, deve delegar novamente ao qa-agent para revisão
6. Tabela de Decisão Rápida
| Condição de Gatilho | Ação de Decisão | Atribuído a |
|---|---|---|
| Falha na verificação de ambiente / modelo de vetorização não armazenado em cache | Reportar ao PM, bloquear | — |
| Termos anormais | Reportar ao PM, confirmar e continuar | — |
| PM diz "continuar" | Confirmar parâmetros, entrar no próximo nó | — |
| Falha contínua de API | Marcar como MANUAL | — |
| Aviso de truncamento | Ajustar max_tokens ou dividir linha e tentar novamente | process-agent |
| REWRITE (0.7–0.9) | Retornar para retradução (no máximo 5 vezes por lote) | process-agent |
| MANUAL (<0.7) | Marcar como bloqueado, reportar ao PM | — |
| Desvio de termos | Executar novamente glossary | process-agent |
| Deriva de estilo | Reprocessar lotes relevantes | process-agent |
| Exceção de formato/placeholder/comprimento | Corrigir via script e reexportar | qa-agent |
| Taxa de falso positivo >5% | Expandir amostragem ou retornar | qa-agent |
| Revisão totalmente aprovada | Entregar | — |
7. Operação
Acumulação/intercâmbio de corpus: O Agente Principal delega ao ingest-agent.
Edição da base de conhecimento: O Agente Principal define o escopo → delega ao ingest-agent. Fazer backup .bak antes de editar, o Agente Principal confirma e depois reinicia o processo de ingest.
Múltiplos arquivos: Cada arquivo é orquestrado independentemente, sem mesclar o workspace.db.
8. Apêndice
8.1 Prioridade de Recursos
- Glossário do projeto (máxima, aplicado por script)
- Base de conhecimento do projeto (estruturada via ingest → injetada via prompt do process → verificada via lista do qa)
- Corpus histórico RAG (referência few-shot do process → comparação de consistência do qa)
- Geração livre do LLM (mínima, último recurso)
8.2 Fluxograma de Orquestração
Agente Principal
│
├─→ ingest-agent ←───────────────────────────┐
│ ├─→ Verificação inicial / Detecção de colunas / Pré-verificação de termos │
│ ├─→ cli.py ingest │
│ │ └─→ knowledge_profile.json ──┐ │
│ ├─→ cli.py scout (opcional) │ │
│ └─→ Retornar parâmetros / exceções │ │
│ │ │
├─→ process-agent ←───────────────────────┘ │
│ ├─→ Injetar base de conhecimento no prompt │
│ ├─→ RAG retrieve → few-shot (automático) │
│ ├─→ cli.py process / run │
│ ├─→ cli.py glossary │
│ └─→ Retornar resultados de tradução │
│ │
├─→ qa-agent ──→ Decisão de retorno ──────────────────────┘
│ ├─→ Verificação da base de conhecimento
│ ├─→ Comparação de consistência RAG
│ ├─→ Amostragem de qualidade / Revisão final / Inspeção
│ ├─→ cli.py export
│ └─→ Retornar resultados de qualidade / exportação
│
└─→ Decisão final: Entregar / Reportar ao PM / Retornar