Vista general del sistema
Un resumen de una página de la arquitectura del lab: componentes, relaciones, flujo de datos, ciclo de vida y restricciones.
Propósito
Esta página es el elevator pitch del lab. Describe el sistema completo en un único lugar. Los detalles más profundos están en el resto del directorio 10-architecture/ y en las páginas de agentes y tooling.
Qué es el lab
El lab es un ecosistema de agentes local-first construido para aprendizaje aplicado y cargas de trabajo reales. Es:
- Local-first. Cada componente se ejecuta en la máquina del usuario. No hay plano de control en la nube.
- Multi-agente. Cinco agentes especializados se coordinan a través de un único Coordinator.
- Orientado a herramientas. Los agentes invocan herramientas tipadas para trabajo determinista; el razonamiento generativo se reserva para trabajo no determinista.
- Auditable. Cada misión, cada petición, cada llamada externa se registra.
- Recuperable. Las misiones se pueden pausar y reanudar. Los fallos de herramientas se reintentan. El sistema se puede reconstruir a partir del audit trail.
El lab no es un producto. Es un entorno personal de I+D que ha crecido hasta valer la pena documentarlo.
Componentes
El lab tiene los siguientes componentes de alto nivel:
Gateway
El gateway es el punto de entrada. Hay dos procesos de gateway:
| Proceso | Puerto | Propósito |
|---|---|---|
| Coordinator | 18789 | El gateway principal. El punto de entrada del usuario. |
| Scout | 18790 | El gateway especializado para el Research Worker y el Media Agent. |
Los gateways están supervisados por launchd (macOS) o systemd (Linux). Se reinician tras un crash.
Agentes
Los cinco agentes están documentados en detalle en Agentes y roles:
- Coordinator — el agente de control principal.
- Coding Assistant — el brazo de implementación.
- Research Worker — el especialista en investigación.
- Media Agent — el especialista en entretenimiento.
- Web Agent — la capacidad de automatización de navegador.
Frameworks
Los agentes usan dos frameworks principales:
- Research Framework — el orquestador, las fases, los esquemas, los adaptadores y las herramientas de dominio para investigación.
- Coding Sub-agent — el CLI de codificación con sandbox al que delega el Coding Assistant.
Herramientas
Las herramientas están documentadas en Capa de Tooling. Las cuatro categorías:
- Media tools — torrent-finder, subtitle-finder, dubbed-finder, media-info, chromecast, vlc, media-playback, media-lab-server.
- Research tools — tavily, duckduckgo, google-search, youtube-transcript, yt-dlp, perplexity.
- Web tools — la herramienta de navegador de OpenClaw.
- Code tools — codex, git, npm, pytest, etc.
Servicios externos
El lab se integra con:
- Model providers — para el Coordinator y el coding sub-agent.
- Search providers — para los adaptadores de investigación.
- Streaming services — para el Media Agent.
- Devices — para el Media Agent (Cast, hosts VLC).
Estado
El estado está documentado en Memoria y contexto:
- MEMORY.md — la memoria curada de largo plazo del lab.
- Daily logs — el registro cronológico crudo.
- Session state — el estado en memoria de la sesión actual.
- Skill artifacts — ficheros SKILL.md y TOOL.md.
- Research artifacts — las salidas tipadas del framework.
- Audit trail — cada petición, cada misión, cada llamada externa.
Flujo de datos
Una petición típica fluye por el sistema así:
El flujo es unidireccional: usuario → Coordinator → agente → framework → herramienta → externo → vuelta. No hay flujo inverso.
El flujo de datos detallado está en Flujo de datos.
Ciclo de vida
El sistema tiene tres ciclos de vida:
- Ciclo de vida de la sesión. Una sesión comienza cuando el usuario abre una conversación y termina cuando la cierra (o la sesión expira por timeout).
- Ciclo de vida de la misión. Una misión de investigación comienza cuando el Research Worker inicializa un run y termina cuando se entrega el informe (o la misión falla).
- Ciclo de vida de la petición. Una petición comienza cuando el usuario envía un mensaje y termina cuando el Coordinator devuelve una respuesta.
Los ciclos de vida los gestionan el Coordinator y el Research Worker. Los ciclos de vida de la sesión y la petición son cortos; el de la misión puede ir de minutos a horas.
Restricciones
El lab está limitado por:
- Recursos locales. Memoria, CPU y disco son finitos. El hardware del lab está documentado en Variables de entorno.
- Límites de tasa externos. Los proveedores de modelo y búsqueda tienen límites de tasa. El lab los respeta a través del request journal y el token pool.
- Autorización del usuario. Algunas operaciones requieren autorización explícita del usuario (p. ej., escribir en un sistema de producción, enviar un email).
- Sandbox del coding sub-agent. El sub-agent se ejecuta en un sandbox. El lab no puede saltarse el sandbox sin configuración explícita.
Las restricciones están documentadas en detalle en Principios de seguridad.
Capacidades
El lab puede:
- Investigar. Ejecutar misiones de investigación multi-fase con artefactos tipados e informes auditables.
- Programar. Delegar la escritura de código a un sub-agent con sandbox; revisar, integrar y testear.
- Multimedia. Buscar y reproducir contenido multimedia en dispositivos locales y remotos (TV, altavoces, etc.).
- Automatización web. Dirigir un navegador a través del árbol de accesibilidad; capturar, rellenar, navegar.
- Memoria. Recordar entre sesiones con memoria curada de largo plazo y logs diarios.
- Generación. Generar imágenes y música a través del Media Lab Server.
No capacidades
El lab explícitamente NO:
- Ejecuta un plano de control en la nube.
- Autentica múltiples usuarios (asunción de un solo usuario).
- Proporciona una interfaz de voz en tiempo real.
- Expone servicios a la internet pública sin configuración explícita del usuario.
- Opera sistemas de producción.
- Envía mensajes a canales externos sin configuración explícita del usuario.
Las no-capacidades son las fronteras que mantienen el lab seguro y predecible.