Visión General de Arquitectura
gz-ia está estructurado siguiendo una arquitectura desacoplada y modular en capas concéntricas, donde la responsabilidad de cada paquete está rígidamente delimitada para garantizar extensibilidad, testeabilidad y resistencia a fallos.
Diagrama de Capas del Sistema
Detalle de las Tres Capas Principales
1. Capa de Clientes (internal/clients/)
Esta capa maneja la interacción directa con el usuario, procesa argumentos y formatea las respuestas:
- [
internal/clients/cli](file:///home/gountzjs/eworkspace/projects/gountz-harness/internal/clients/cli): Construida sobrespf13/cobra. Proporciona el árbol completo de comandos y subcomandos (chat,session,update,version). No contiene lógica de negocio; valida parámetros e invoca a los servicios de dominio. - [
internal/clients/tui](file:///home/gountzjs/eworkspace/projects/gountz-harness/internal/clients/tui): Construida concharmbracelet/bubbletea,lipglossyhuh. Proporciona la experiencia visual guiada con menús accesibles, banners de telemetría y diálogos interactivos de confirmación.
2. Capa de Servicios de Dominio (internal/features/)
El núcleo operativo de la CLI de gz-ia, completamente desacoplado de la terminal:
- [
session](file:///home/gountzjs/eworkspace/projects/gountz-harness/internal/features/session): Orquesta el ciclo de vida de cada sesión, gestiona los drivers de los agentes (agy,claude,opencode,pi-agent), controla procesos en segundo plano y almacena atómicamente la metadata en.harness/sessions/<id>.json. - [
workspace](file:///home/gountzjs/eworkspace/projects/gountz-harness/internal/features/workspace): Administra el ciclo de vida de los Git Worktrees efímeros, la creación de ramasharness/<id>y el fallback seguro en directorios planos si Git no está inicializado. - [
logger](file:///home/gountzjs/eworkspace/projects/gountz-harness/internal/features/logger): Captura y persiste el log estructurado de etapas de razonamiento y acciones en formato JSONL (.events.jsonl). - [
metrics](file:///home/gountzjs/eworkspace/projects/gountz-harness/internal/features/metrics): Agrega y analiza métricas de ejecución: duración total, pasos completados, consumo de tokens (input, output, caché) y llamadas a herramientas por cada agente y subagente. - [
updater](file:///home/gountzjs/eworkspace/projects/gountz-harness/internal/features/updater): Comprueba actualizaciones contra Nexus REST API o Forgejo, gestiona descargas y reemplaza atómicamente el ejecutable.
3. Microkernel Orchy (packages/orchy/)
Un paquete autónomo y reutilizable ubicado en packages/orchy que provee:
- Inversión de Control (IoC):
ServiceContaineryKernelContextpara registrar dependencias desacopladas. - Honest Microkernel & Circuit Breaker: Supervisa el estado de salud de cada herramienta registrada (
HEALTHY,DEGRADED,DEAD) medianteToolProxy. - Servidor MCP Nativo: Exposición de herramientas a cualquier agente compatible con el protocolo MCP (Model Context Protocol) a través de canales estándar (
io.Reader/io.Writer). - Baterías Incluidas: Plugins nativos para operaciones sobre worktrees (
worktree_readyworktree_get).