Agente de Localización de Videojuegos — Manual del Orquestador Principal
Agente Principal = Orquestador. Prohibido operar directamente scripts, archivos o APIs. Todas las acciones de ejecución deben delegarse a subagentes.
Arquitectura: Agente Principal decide → Subagente ejecuta → Resultado se retorna → Agente Principal revisa/decide
Ruta de manuales de subagentes: SUB_ingest.md / SUB_process.md / SUB_qa.md
0. Arquitectura y Prohibiciones
0.1 Prohibiciones del Agente Principal
- No ejecutar directamente
cli.pyni ningún script - No leer/escribir directamente archivos de entrada del proyecto, glosarios o bases de conocimiento
- No invocar directamente la API de LLM para traducción/optimización
- No modificar directamente la base de datos o el xlsx exportado
0.2 División de Subagentes
| Subagente | Responsabilidad | Permisos Exclusivos |
|---|---|---|
| ingest-agent | Escaneo inicial, detección de columnas, verificación previa de glosario, comprobación del entorno, ingest/scout, gestión de corpus, edición de base de conocimiento | Ingesta y archivado de datos |
| process-agent | process / run, llamadas API, gestión de concurrencia, reintentos por truncamiento, reemplazo de glosario (glossary) | Llamadas API y reemplazo forzoso de glosario |
| qa-agent | Muestreo de control de calidad, revisión final diferencial (Modo B), revisión de salida, exportación (export), corrección de formato, comparación de consistencia RAG | Control de calidad, revisión y exportación de entrega |
0.3 Normas de Transmisión de Contexto
Al asignar una tarea, el Agente Principal debe incluir:
- Identificador del proyecto (ruta del workspace, nombre del proyecto)
- Objetivo de la fase actual
- Resumen de salida o conclusiones clave del subagente upstream
- Puntos de riesgo conocidos (conflictos de glosario, restricciones de formato, historial de excesos de max_length, etc.)
knowledge_profile_path: ruta aworkspace/knowledge_profile.jsonrag_enabled: si el corpus del proyecto actual es >= 10- Requisitos de retorno: resumen estructurado + ruta de archivo + marcador de anomalía
Ejemplo de plantilla de asignación:
【Tarea】Ejecutar ingest
【Proyecto】workspace/PROJECT_001
【Objetivo de fase】Escaneo inicial + análisis e ingesta
【Archivo de entrada】input/game.xlsx
【Glosario】input/glossary.txt
【Base de conocimiento】input/kb.txt
【Riesgos conocidos】Ninguno
【Conclusiones upstream】Ninguna
【Requisitos de retorno】Resumen estructurado + ruta de archivo + marcador de anomalía
Al retornar, el Subagente debe proporcionar:
- Resumen de ejecución (éxito/fallo/anomalía)
- Datos clave (número de filas, aciertos de glosario, números de fila con anomalías, puntuación)
- Rutas de archivos de salida
- Sugerencias para el siguiente paso / elementos bloqueantes
1. Inicio
Acción del Agente Principal: Asignar al ingest-agent para ejecutar el escaneo inicial.
Retorno del ingest-agent: Parámetros históricos/estado vacío, mapeo de columnas, problemas de glosario, estado del entorno (incluido estado del modelo de vectorización), materiales de parámetros.
Decisión del Agente Principal:
- Historial existente → Informar al PM de los parámetros históricos, confirmar si se reutilizan o se ajustan
- Anomalía en glosario → Informar al PM, confirmar y continuar o corregir
- Múltiples modelos → Listar opciones al PM, confirmar cuál usar
- Sin modelo → Preguntar al PM si desea descargar uno; si se niega → marcar
rag_enabled=false - Si el PM dice "continuar" = confirmación, pasar a Nodo 1
2. Escaneo (Nodo 1)
Acción del Agente Principal: Asignar al ingest-agent para ejecutar cli.py ingest.
Retorno del ingest-agent: Número total de filas, aciertos de glosario, lista de nuevos términos, filas con conflicto, modo determinado (Modo A/B), muestra de anclaje de estilo, ruta de knowledge_profile.json.
Decisión del Agente Principal:
- Asignar scout (opcional) → Confirmar Modo A/B → Pasar a Nodo 3
3. Ejecución de API (Nodo 3)
Acción del Agente Principal: Asignar al process-agent para ejecutar traducción/optimización. Incluir anclaje de estilo, restricciones de glosario, knowledge_profile_path, rag_enabled.
Retorno del process-agent: Número de filas exitosas, números de fila fallidas, advertencias de truncamiento, estadísticas de aciertos/reutilización de RAG, resumen de anomalías de API.
Decisión del Agente Principal:
- Fallo/truncamiento → Decidir reintentar, ajustar parámetros o marcar como MANUAL
- Éxito → Pasar a Nodo 4
4. Postprocesamiento (Nodo 4)
4.1 Reemplazo Forzoso de Glosario
Acción del Agente Principal: Asignar al process-agent para ejecutar cli.py glossary.
Retorno del process-agent: Estadísticas de reemplazo, números de fila con desviación residual.
Decisión del Agente Principal: Desviación residual → Decidir si reenviar a reprocesamiento.
4.2 Control de Calidad
Acción del Agente Principal: Asignar al qa-agent para ejecutar control de calidad.
Retorno del qa-agent: Distribución de puntuaciones (PASS/REWRITE/MANUAL), muestras anómalas, números de fila con violaciones de base de conocimiento, números de fila con inconsistencia RAG, acciones sugeridas.
Decisión del Agente Principal:
- REWRITE → Reenviar a Nodo 3, asignar al process-agent para ajustar prompt y reenviar (máximo 5 veces por lote)
- MANUAL → Marcar como bloqueante, informar al PM
- PASS → Pasar a 4.3 (Modo B) o Nodo 5
4.3 Revisión Final Diferencial (Modo B)
Acción del Agente Principal: Asignar al qa-agent para ejecutar la revisión final.
Retorno del qa-agent: Lista de correcciones, estadísticas de tasa de falsos positivos.
Decisión del Agente Principal: Tasa de falsos positivos >5% → Ampliar muestreo o reenviar; de lo contrario, pasar a Nodo 5.
5. Revisión Final + Exportación (Nodo 5)
Acción del Agente Principal: Asignar al qa-agent para ejecutar revisión final, inspección y exportación.
Ejecución del qa-agent: Revisión de salida estructurada (ver lista de elementos de revisión en SUB_qa.md) → cli.py export.
Decisión del Agente Principal (reenvío si la revisión no pasa):
- Desviación de glosario → process-agent ejecuta de nuevo
glossary - Estilo/contexto → process-agent reprocesa los lotes relevantes
- Formato/placeholder/longitud → qa-agent corrige y vuelve a exportar
- Después del reenvío, se debe reasignar al qa-agent para revisión
6. Tabla de Decisiones Rápidas
| Condición desencadenante | Acción de decisión | Objeto asignado |
|---|---|---|
| Fallo en comprobación de entorno / modelo de vectorización no almacenado en caché | Informar al PM, bloquear | — |
| Anomalía en glosario | Informar al PM, confirmar y continuar | — |
| PM dice "continuar" | Confirmar parámetros, pasar al siguiente nodo | — |
| Fallos consecutivos de API | Marcar como MANUAL | — |
| Advertencia de truncamiento | Ajustar max_tokens o dividir filas y reintentar | process-agent |
| REWRITE (0.7–0.9) | Reenviar para retraducción (máximo 5 veces por lote) | process-agent |
| MANUAL (<0.7) | Marcar como bloqueante, informar al PM | — |
| Desviación de glosario | Ejecutar de nuevo glossary | process-agent |
| Deriva de estilo | Reprocesar lotes relevantes | process-agent |
| Anomalía de formato/placeholder/longitud | Corregir con script y reexportar | qa-agent |
| Tasa de falsos positivos >5% | Ampliar muestreo o reenviar | qa-agent |
| Revisión completamente aprobada | Entregar | — |
7. Operaciones
Acumulación/Intercambio de corpus: El Agente Principal asigna al ingest-agent para ejecutar.
Edición de base de conocimiento: El Agente Principal decide el alcance → asigna al ingest-agent para ejecutar. Hacer copia de seguridad .bak antes de editar, el Agente Principal confirma y luego reinicia la ingesta.
Múltiples archivos: Cada archivo se programa de forma independiente, no se fusiona workspace.db.
8. Apéndice
8.1 Prioridad de Recursos
- Glosario del proyecto (máxima prioridad, aplicado por script)
- Base de conocimiento del proyecto (ingesta estructurada → inyección en prompt de process → verificación en lista de QA)
- Corpus histórico RAG (referencia few-shot en process → comparación de consistencia en QA)
- Generación libre del LLM (mínima prioridad, último recurso)
8.2 Diagrama de Flujo de Programación
Agente Principal
│
├─→ ingest-agent ←───────────────────────────┐
│ ├─→ Escaneo inicial / Detección de columnas / Verificación previa de glosario │
│ ├─→ cli.py ingest │
│ │ └─→ knowledge_profile.json ──┐ │
│ ├─→ cli.py scout (opcional) │ │
│ └─→ Retorno de parámetros / anomalías │
│ │ │
├─→ process-agent ←───────────────────────┘ │
│ ├─→ Inyección de base de conocimiento en prompt │
│ ├─→ RAG retrieve → few-shot (automático) │
│ ├─→ cli.py process / run │
│ ├─→ cli.py glossary │
│ └─→ Retorno de resultados de traducción │
│ │
├─→ qa-agent ──→ Decisión de reenvío ───────────┘
│ ├─→ Verificación contra lista de base de conocimiento │
│ ├─→ Comparación de consistencia RAG │
│ ├─→ Muestreo de control de calidad / Revisión final / Inspección │
│ ├─→ cli.py export │
│ └─→ Retorno de resultados de control de calidad / exportación │
│
└─→ Decisión final: Entrega / Informar al PM / Reenvío