egutierrez
bcbbd974e3
Documentación y políticas para la creación de agentes: - docs/creating-agents.md: guía completa paso a paso para humanos (scaffold, config, registro Matrix, avatar, verificación E2EE, arranque, troubleshooting) - .claude/policies/create_agent.md: policy para LLMs con estructura de archivos, convenciones y reglas a seguir al crear agentes - .claude/policies/index.md: índice de todas las policies disponibles - .claude/policies/create_tool.md: movido desde .claude/rules/ (misma policy) - CLAUDE.md: añadida sección de políticas, actualizada tabla de agentes con asistente-2, y actualizado el flujo de "Cómo añadir un nuevo bot" con pasos de avatar y verificación E2EE Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
177 lines
7.8 KiB
Markdown
177 lines
7.8 KiB
Markdown
# CLAUDE.md — Contexto del proyecto agents_and_robots
|
|
|
|
## Qué es este proyecto
|
|
|
|
Monorepo en Go para gestionar bots Matrix. Cada bot es un agente autónomo con personalidad, reglas de decisión y acceso a herramientas (LLM, SSH, HTTP, MCP). Los bots se comunican entre sí y con humanos a través de Matrix (mautrix-go).
|
|
|
|
**Homeserver activo:** `https://matrix-af2f3d.organic-machine.com`
|
|
**Server name:** `matrix-af2f3d.organic-machine.com`
|
|
|
|
## Filosofía de diseño — LA REGLA MÁS IMPORTANTE
|
|
|
|
El proyecto usa el patrón **pure core / impure shell** estrictamente:
|
|
|
|
```
|
|
pkg/ → PURE: solo tipos, funciones puras, cero side effects
|
|
shell/ → IMPURE: todo I/O, red, filesystem, procesos
|
|
agents/ → composición: reglas puras + ensamblado con shell en runtime.go
|
|
```
|
|
|
|
**Nunca** añadir side effects (I/O, red, llamadas a APIs) dentro de `pkg/`.
|
|
**Siempre** que el core necesite "hacer algo", produce un `[]decision.Action` (datos puros) que el shell interpreta.
|
|
|
|
El flujo es siempre:
|
|
```
|
|
Matrix event → Parse (pure) → Evaluate rules (pure) → []Action (pure data)
|
|
→ Runner.Execute (impure) → efectos reales
|
|
```
|
|
|
|
## Módulo Go
|
|
|
|
`github.com/enmanuel/agents`
|
|
|
|
## Estructura de directorios
|
|
|
|
```
|
|
pkg/decision/ → motor de reglas puro (Evaluate, Rule, MatchFunc, Action)
|
|
pkg/llm/ → tipos de LLM puros (CompleteFunc, CompletionRequest, Route)
|
|
pkg/tools/ → specs declarativas de herramientas (SSHCommandSpec, etc.)
|
|
pkg/message/ → parse y format de mensajes Matrix (puros)
|
|
pkg/personality/ → tipos de personalidad (Personality, Tone, etc.)
|
|
|
|
shell/llm/ → clientes LLM reales (anthropic.go, openai.go, factory.go)
|
|
shell/matrix/ → cliente Matrix mautrix-go (client.go, listener.go)
|
|
shell/ssh/ → ejecutor SSH real (executor.go)
|
|
shell/effects/ → Runner que interpreta []Action → side effects
|
|
shell/bus/ → comunicación inter-agente via Go channels
|
|
shell/protocols/ → adaptadores MCP (mcp.go)
|
|
|
|
agents/runtime.go → Agent{}: ensambla core + shell, maneja eventos
|
|
agents/assistant/ → reglas puras + config del assistant-bot
|
|
agents/devops/ → reglas puras + config del devops-bot
|
|
|
|
internal/config/schema.go → tipos completos del YAML de configuración
|
|
internal/config/loader.go → Load() con expand env vars, LoadMeta() sin validación
|
|
cmd/launcher/main.go → inicia agentes, tiene rulesRegistry
|
|
cmd/agentctl/main.go → CLI de gestión (list, start, stop, remove)
|
|
cmd/register/main.go → registra bots en Synapse via admin API
|
|
dev-scripts/ → scripts bash para operaciones del día a día
|
|
```
|
|
|
|
## Políticas para LLMs
|
|
|
|
Las políticas guían cómo ejecutar tareas específicas respetando la arquitectura del proyecto.
|
|
Ver índice completo en `.claude/policies/index.md`.
|
|
|
|
| Política | Cuándo aplicarla |
|
|
|----------|------------------|
|
|
| `.claude/policies/create_agent.md` | Al crear un nuevo bot/agente Matrix |
|
|
| `.claude/policies/create_tool.md` | Al añadir una nueva tool para function calling |
|
|
|
|
Documentación detallada para humanos en `docs/creating-agents.md`.
|
|
|
|
## Agentes existentes
|
|
|
|
| ID | Estado | LLM | Descripción |
|
|
|----------------|-----------|---------|------------------------------------------|
|
|
| assistant-bot | activo | GPT-4o | Asistente general, responde DMs |
|
|
| asistente-2 | activo | GPT-4o | Asistente con tools (current_time) |
|
|
| devops-bot | pendiente | Claude | SSH, deployments, healthchecks |
|
|
|
|
## Dependencias clave
|
|
|
|
```
|
|
maunium.net/go/mautrix v0.21.1 → Matrix client
|
|
github.com/sashabaranov/go-openai → OpenAI + Ollama-compatible
|
|
github.com/mark3labs/mcp-go → MCP protocol server/client
|
|
golang.org/x/crypto/ssh → SSH execution
|
|
github.com/spf13/cobra → CLI
|
|
gopkg.in/yaml.v3 → Config parsing
|
|
```
|
|
|
|
## Configuración de agentes
|
|
|
|
Cada agente vive en `agents/<id>/`:
|
|
- `config.yaml` — configuración completa (ver schema en `internal/config/schema.go`)
|
|
- `agent.go` — reglas puras que implementan `Rules() []decision.Rule`
|
|
- `prompts/system.md` — system prompt del LLM
|
|
- `data/` — datos de runtime (SQLite, crypto, logs) — en .gitignore
|
|
|
|
El `config.yaml` soporta variables de entorno con `${VAR}` y `$VAR`. El loader usa `os.ExpandEnv`.
|
|
|
|
Secciones principales del config: `agent`, `personality`, `llm`, `tools`, `matrix`, `agents` (peers), `ssh`, `security`, `schedules`, `observability`, `resilience`, `storage`.
|
|
|
|
## Cómo añadir un nuevo bot
|
|
|
|
Guía rápida (detalle completo en `docs/creating-agents.md`, policy en `.claude/policies/create_agent.md`):
|
|
|
|
1. Crear scaffold: `./dev-scripts/new-agent.sh <id> "Display Name"` o manual en `agents/<id>/`
|
|
2. Crear `agent.go` (reglas puras), `config.yaml`, `prompts/system.md`
|
|
3. Registrar en `cmd/launcher/main.go` → import + `rulesRegistry`
|
|
4. Registrar en Matrix: `./dev-scripts/register.sh <id> "Display Name"`
|
|
5. Avatar y nombre: `./dev-scripts/avatar.sh <id> static/<imagen>.jpg`
|
|
6. Verificación E2EE: `go run -tags goolm ./cmd/verify --homeserver ... --username <id> --password ... --token ...`
|
|
7. Arrancar: `./dev-scripts/start.sh <id>`
|
|
|
|
## Dev-scripts disponibles
|
|
|
|
```bash
|
|
./dev-scripts/list.sh # ver todos los bots y estado
|
|
./dev-scripts/start.sh [agent-id] # iniciar uno o todos
|
|
./dev-scripts/stop.sh [agent-id] # detener uno o todos
|
|
./dev-scripts/restart.sh [agent-id] # reiniciar uno o todos
|
|
./dev-scripts/ps.sh [agent-id] # procesos con detalle (PID, mem, CPU, uptime)
|
|
./dev-scripts/remove.sh <agent-id> # deshabilitar (sin borrar datos)
|
|
./dev-scripts/register.sh <id> [name] # registrar bot en Matrix
|
|
./dev-scripts/logs.sh [agent-id] # tail -f de logs
|
|
./dev-scripts/new-agent.sh <id> [name] # scaffold completo
|
|
|
|
# Gestión unificada del servidor
|
|
./dev-scripts/server.sh start [id] # iniciar agentes
|
|
./dev-scripts/server.sh stop [id] # detener agentes
|
|
./dev-scripts/server.sh restart [id] # reiniciar agentes
|
|
./dev-scripts/server.sh status # resumen general del servidor
|
|
./dev-scripts/server.sh ps [id] # procesos con detalle
|
|
./dev-scripts/server.sh logs [id] # tail -f de logs
|
|
./dev-scripts/server.sh kill [id] # SIGKILL forzado (emergencia)
|
|
```
|
|
|
|
PID files: `run/<id>.pid` | Log files: `run/<id>.log`
|
|
|
|
## Gestión de procesos
|
|
|
|
Los bots corren como procesos independientes lanzados por `agentctl` o `dev-scripts/start.sh`.
|
|
Cada proceso escribe su PID en `run/<id>.pid` y su log en `run/<id>.log`.
|
|
`is_running()` usa `kill -0 <pid>` para verificar sin matar el proceso.
|
|
|
|
## Variables de entorno críticas
|
|
|
|
```bash
|
|
MATRIX_HOMESERVER # URL del servidor Matrix
|
|
MATRIX_SERVER_NAME # nombre del servidor (parte después de :)
|
|
MATRIX_ADMIN_TOKEN # token admin para registrar bots (cmd/register)
|
|
MATRIX_TOKEN_<BOT> # access token de cada bot
|
|
OPENAI_API_KEY # OpenAI
|
|
ANTHROPIC_API_KEY # Anthropic/Claude
|
|
SSH_PRIVATE_KEY_PATH # clave SSH para el devops-bot
|
|
```
|
|
|
|
Nunca commitear `.env`. Plantilla en `.env.example`.
|
|
|
|
## Preferencias del usuario
|
|
|
|
- **Idioma**: español en configs/comentarios de dominio, inglés en código Go
|
|
- **Estilo**: FP estricto (pure core / impure shell), sin abstracción prematura
|
|
- **Desarrollo**: trunk-based, Gitea como remote
|
|
- **Go version**: 1.23.5 en `/usr/local/go/bin`
|
|
- **No usar** frameworks de agentes externos — arquitectura propia
|
|
|
|
## Próximas extensiones naturales
|
|
|
|
- Scheduling: cron runner en `shell/` para `ScheduleCfg`
|
|
- Conversation history: mantener `[]Message` por room en memoria/SQLite
|
|
- RBAC real: conectar `SecurityCfg.Roles` al listener
|
|
- E2EE: habilitar `encryption.enabled: true` con crypto store de mautrix
|
|
- MCP: exponer tools del devops-bot como MCP server en el puerto configurado
|
|
- A2A: agent card HTTP endpoint para comunicación con agentes externos
|