Visión general de la arquitectura de pi

源码版本v0.73.1

badlogic/pi-mono es un monorepo en TypeScript que con cinco paquetes npm arma una pila entera: "API unificada de LLM → Agent genérico → asistente de codificación → UI de terminal/web". Esta página da un mapa panorámico; las siguientes desglosan cada capa.

Los cinco paquetes

Paquete	Nombre npm	Rol
ai	@mariozechner/pi-ai	API unificada de LLM, 9 providers integrados, descubrimiento automático de modelos
agent	@mariozechner/pi-agent-core	Agent genérico, bucle while doble + ejecución de herramientas
coding-agent	@mariozechner/pi-coding-agent	CLI de asistente de codificación, herramientas read/bash/edit/write + gestión de sesión
tui	@mariozechner/pi-tui	Librería de UI de terminal, renderizado diferencial (differential rendering) + salida sincronizada
web-ui	@mariozechner/pi-web-ui	Componentes de chat web, Lit Web Components

Directorio de fuentes: packages/

Estratificación

Una frase por capa

• pi-ai: unifica 9 LLMs (Anthropic, OpenAI, Google, Bedrock...) en dos funciones stream/streamSimple, despachando por model.api desde un registro. Ver fachada de stream.
• pi-agent-core: la clase Agent mantiene el estado, runLoop procesa interrupciones/colas en el bucle externo y llamadas a herramientas en el interno, con streaming + bucle de herramientas. Ver bucle while doble.
• pi-coding-agent: envuelve Agent con AgentSession, añade herramientas, system prompt, persistencia de sesión y tres modos de ejecución. Ver capa de orquestación AgentSession.
• pi-tui: renderizado diferencial + salida sincronizada vía DECSET 2026 para evitar parpadeo en la terminal. Ver clase TUI de renderizado diferencial.
• pi-web-ui: los componentes Lit tienen su propia instancia de Agent, envuelven streamSimple con un proxy CORS a través de createStreamFn. Ver AgentInterface host de sesión.

Motivación de la estratificación

¿Por qué no hacer un solo paquete grande? Porque los consumidores de cada capa son distintos: los componentes web no pueden depender del fs de Node; la TUI no debería cargar con el IndexedDB del navegador; el Agent genérico no debería saber que existe la "codificación". Con la estratificación, la web puede tomar pi-agent-core + pi-ai y correr su propio agent saltándose las herramientas del asistente de codificación; el CLI de codificación puede cambiar de UI (modo tui o rpc) sin tocar la lógica de orquestación. pi-ai se mantiene como paquete independiente para que cualquier proyecto pueda usar la API unificada de LLM sin atarse al concepto de agent.

Lecturas equivocadas comunes

• "pi es un coding agent": no es exacto. pi-coding-agent es la aplicación de capa superior; pi-ai y pi-agent-core son infraestructura genérica reutilizable por sí sola.
• "La capa UI sólo renderiza": tanto la web como la terminal participan en el streaming: la web reemplaza Agent.streamFn para inyectar el proxy CORS, la terminal se suscribe a eventos para decidir cuándo repintar.

Orden de lectura recomendado

Primero fachada de stream para entender cómo se invoca al LLM, luego bucle while doble para ver el bucle de herramientas, después capa de orquestación AgentSession para ver cómo se ensambla el asistente de codificación, y por último, según interés, pi-tui o pi-web-ui.