Merge 67dd486207 into da71eaebd2
This commit is contained in:
Jhonatan carvajal antigua
GitHub
commit
d1830f8169
806
README-IMPROVED.md
Normal file
806
README-IMPROVED.md
Normal file
@ -0,0 +1,806 @@
|
|||||||
|
# 🤖 Jarvis — Personal AI Assistant
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<strong>Your Personal AI Assistant Running on Your Own Devices</strong>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<a href="https://github.com/jeturing/Jarvis/actions/workflows/ci.yml?branch=main"><img src="https://img.shields.io/github/actions/workflow/status/jeturing/Jarvis/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
|
||||||
|
<a href="https://github.com/jeturing/Jarvis/releases"><img src="https://img.shields.io/github/v/release/jeturing/Jarvis?include_prereleases&style=for-the-badge" alt="GitHub release"></a>
|
||||||
|
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
## 📋 Tabla de Contenidos
|
||||||
|
|
||||||
|
- [¿Qué es Jarvis?](#qué-es-jarvis)
|
||||||
|
- [Características Principales](#características-principales)
|
||||||
|
- [Arquitectura del Sistema](#arquitectura-del-sistema)
|
||||||
|
- [Diagrama de Uso](#diagrama-de-uso)
|
||||||
|
- [Instalación Rápida](#instalación-rápida)
|
||||||
|
- [Configuración](#configuración)
|
||||||
|
- [Uso Básico](#uso-básico)
|
||||||
|
- [Canales Soportados](#canales-soportados)
|
||||||
|
- [Documentación Completa](#documentación-completa)
|
||||||
|
- [Desarrollo](#desarrollo)
|
||||||
|
- [Contribuir](#contribuir)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ¿Qué es Jarvis?
|
||||||
|
|
||||||
|
**Jarvis** es un **asistente personal de IA** que se ejecuta en tus propios dispositivos. Es una plataforma local-first, auto-hospedada y diseñada para control de usuario único.
|
||||||
|
|
||||||
|
### Beneficios Clave
|
||||||
|
|
||||||
|
✅ **Privacidad Total** — Todo se ejecuta localmente, tus datos nunca salen de tu control
|
||||||
|
✅ **Multi-Canal** — Conecta con WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Teams y más
|
||||||
|
✅ **Multi-Plataforma** — Funciona en macOS, iOS, Android, Linux y Windows (WSL2)
|
||||||
|
✅ **Extensible** — Sistema robusto de plugins para añadir funcionalidad
|
||||||
|
✅ **Siempre Activo** — Daemon persistente vía systemd/launchd
|
||||||
|
✅ **Capacidades de Voz** — Voice Wake y Talk Mode en macOS/iOS/Android
|
||||||
|
✅ **Canvas Visual** — Espacio de trabajo visual controlado por el agente
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Características Principales
|
||||||
|
|
||||||
|
### 🔐 Seguridad y Privacidad
|
||||||
|
- **Local-First**: Todos tus datos permanecen en tu dispositivo
|
||||||
|
- **Sin Servidor Central**: No hay dependencia de servicios de terceros
|
||||||
|
- **Emparejamiento Seguro**: Sistema de códigos para autorización DM
|
||||||
|
- **Lista de Permitidos**: Control granular de quién puede interactuar
|
||||||
|
|
||||||
|
### 💬 Multi-Canal
|
||||||
|
- **Mensajería Unificada**: Una interfaz para todos tus canales de chat
|
||||||
|
- **13+ Canales Integrados**: WhatsApp, Telegram, Discord, Slack, Signal, y más
|
||||||
|
- **Enrutamiento Inteligente**: Mensajes dirigidos al agente correcto
|
||||||
|
- **Respuestas Contextuales**: Mantiene contexto en conversaciones grupales
|
||||||
|
|
||||||
|
### 🛠️ Herramientas Poderosas
|
||||||
|
- **Browser Tool**: Automatización web con Playwright
|
||||||
|
- **Canvas Tool**: Espacio de trabajo visual con A2UI
|
||||||
|
- **Image Tool**: Análisis y generación de imágenes
|
||||||
|
- **Bash Tool**: Ejecución de comandos del sistema
|
||||||
|
- **Cron Tool**: Tareas programadas
|
||||||
|
- **Memory Tool**: Almacenamiento y recuperación de contexto
|
||||||
|
|
||||||
|
### 🤖 IA Avanzada
|
||||||
|
- **Múltiples Modelos**: Claude, GPT, Gemini, Bedrock, Ollama (local)
|
||||||
|
- **Failover Automático**: Rotación automática si un modelo falla
|
||||||
|
- **Streaming de Herramientas**: Ejecución de herramientas en tiempo real
|
||||||
|
- **Multi-Agente**: Agentes aislados por workspace/canal
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Arquitectura del Sistema
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Interfaces de Usuario │
|
||||||
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ macOS │ │ iOS │ │ Android │ │ CLI / Web UI │ │
|
||||||
|
│ │ App │ │ App │ │ App │ │ │ │
|
||||||
|
│ └──────────┘ └──────────┘ └──────────┘ └─────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
│ WebSocket / HTTP
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Gateway (Servidor) │
|
||||||
|
│ • Gestión de sesiones y enrutamiento de mensajes │
|
||||||
|
│ • Catálogo de modelos IA y autenticación │
|
||||||
|
│ • Trabajos programados (cron) y webhooks │
|
||||||
|
│ • Herramienta de navegador compartida │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Runtime de Agente (Pi Agent) │
|
||||||
|
│ • Ejecución de modelos IA (Claude, GPT, etc.) │
|
||||||
|
│ • Streaming de herramientas en tiempo real │
|
||||||
|
│ • Gestión de contexto de sesión │
|
||||||
|
│ • Failover automático de modelos │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Capa Multi-Canal │
|
||||||
|
│ WhatsApp │ Telegram │ Signal │ Discord │ Slack │ iMessage │
|
||||||
|
│ Teams │ Matrix │ Zalo │ BlueBubbles │ LINE │ Voice Call │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Servicios Externos (IA) │
|
||||||
|
│ Anthropic Claude │ OpenAI GPT │ Google Gemini │ AWS Bedrock │
|
||||||
|
│ Ollama (Local) │ Otros proveedores │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
📖 **Profundizar**: Ver [ARCHITECTURE.md](docs/ARCHITECTURE.md) para detalles completos de arquitectura
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Diagrama de Uso
|
||||||
|
|
||||||
|
### Flujo de Mensaje Completo
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 1. Usuario envía mensaje desde canal (WhatsApp, Telegram, etc.)│
|
||||||
|
└───────────────────────┬─────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 2. Canal recibe mensaje y lo normaliza │
|
||||||
|
│ • Extrae texto, medios, contexto de respuesta │
|
||||||
|
│ • Añade metadata del canal │
|
||||||
|
└───────────────────────┬─────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 3. Verificación de seguridad │
|
||||||
|
│ • Verifica lista de permitidos │
|
||||||
|
│ • Valida emparejamiento para DMs │
|
||||||
|
│ • Comprueba permisos de grupo │
|
||||||
|
└───────────────────────┬─────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 4. Gateway enruta mensaje │
|
||||||
|
│ • Determina sesión apropiada │
|
||||||
|
│ • Verifica modo de activación (mention/reply/always) │
|
||||||
|
│ • Encola o ejecuta inmediatamente │
|
||||||
|
└───────────────────────┬─────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 5. Agente procesa mensaje │
|
||||||
|
│ • Carga contexto de sesión │
|
||||||
|
│ • Ejecuta modelo IA con herramientas │
|
||||||
|
│ • Stream de llamadas y resultados de herramientas │
|
||||||
|
└───────────────────────┬─────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 6. Ejecución de herramientas (si es necesario) │
|
||||||
|
│ • Browser (automatización web) │
|
||||||
|
│ • Bash (ejecutar comandos) │
|
||||||
|
│ • Canvas (workspace visual) │
|
||||||
|
│ • Memory (recuperar contexto) │
|
||||||
|
│ • Otras herramientas personalizadas │
|
||||||
|
└───────────────────────┬─────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 7. Agente genera respuesta │
|
||||||
|
│ • Basada en resultados de herramientas │
|
||||||
|
│ • Aplica modo de thinking (low/high/always) │
|
||||||
|
│ • Formatea para canal destino │
|
||||||
|
└───────────────────────┬─────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 8. Respuesta enviada de vuelta │
|
||||||
|
│ • Formatea para protocolo específico del canal │
|
||||||
|
│ • Fragmenta mensajes largos si es necesario │
|
||||||
|
│ • Añade indicadores de escritura/reacciones │
|
||||||
|
└───────────────────────┬─────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 9. Usuario recibe respuesta en su canal │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
📖 **Profundizar**: Ver [Flujo de Datos](docs/ARCHITECTURE.md#data-flow) en documentación de arquitectura
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Instalación Rápida
|
||||||
|
|
||||||
|
### Requisitos Previos
|
||||||
|
|
||||||
|
- **Node.js ≥ 22.12.0**
|
||||||
|
- **npm, pnpm o bun**
|
||||||
|
- **macOS, Linux o Windows (WSL2)**
|
||||||
|
|
||||||
|
### Instalación con npm
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Instalar globalmente
|
||||||
|
npm install -g moltbot@latest
|
||||||
|
|
||||||
|
# Ejecutar asistente de configuración
|
||||||
|
moltbot onboard --install-daemon
|
||||||
|
```
|
||||||
|
|
||||||
|
### Instalación desde Código Fuente
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Clonar repositorio
|
||||||
|
git clone https://github.com/jeturing/Jarvis.git
|
||||||
|
cd Jarvis
|
||||||
|
|
||||||
|
# Instalar dependencias
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# Construir proyecto
|
||||||
|
pnpm ui:build
|
||||||
|
pnpm build
|
||||||
|
|
||||||
|
# Ejecutar asistente de configuración
|
||||||
|
pnpm moltbot onboard --install-daemon
|
||||||
|
```
|
||||||
|
|
||||||
|
### Instalación con Docker
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Usando Docker Compose
|
||||||
|
docker-compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
📖 **Profundizar**: Ver [Guía de Instalación Completa](docs/README-ES.md#configuración-y-despliegue)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuración
|
||||||
|
|
||||||
|
### Estructura de Configuración
|
||||||
|
|
||||||
|
```
|
||||||
|
~/.clawdbot/
|
||||||
|
├── config/
|
||||||
|
│ ├── .moltbot.yaml # Configuración principal
|
||||||
|
│ ├── models.json # Perfiles de modelos IA
|
||||||
|
│ └── skills/ # Configuraciones de skills
|
||||||
|
├── credentials/
|
||||||
|
│ ├── anthropic.json # Tokens OAuth
|
||||||
|
│ ├── openai.json
|
||||||
|
│ └── channels/ # Credenciales de canales
|
||||||
|
├── sessions/
|
||||||
|
│ ├── main/ # Datos de sesión principal
|
||||||
|
│ └── groups/ # Sesiones de grupos
|
||||||
|
└── logs/
|
||||||
|
├── gateway.log # Logs del gateway
|
||||||
|
└── agent.log # Logs del agente
|
||||||
|
```
|
||||||
|
|
||||||
|
### Archivo de Configuración Principal
|
||||||
|
|
||||||
|
Edita `~/.clawdbot/config/.moltbot.yaml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# ========================================
|
||||||
|
# Configuración del Gateway
|
||||||
|
# ========================================
|
||||||
|
gateway:
|
||||||
|
mode: local # 'local' o 'remote'
|
||||||
|
port: 18789 # Puerto del servidor
|
||||||
|
bind: loopback # 'loopback' o 'all'
|
||||||
|
verbose: true # Logging detallado
|
||||||
|
|
||||||
|
# ========================================
|
||||||
|
# Configuración de Agentes
|
||||||
|
# ========================================
|
||||||
|
agents:
|
||||||
|
default:
|
||||||
|
model: claude-4.5-sonnet # Modelo IA por defecto
|
||||||
|
thinking: high # Nivel de thinking (low/high/always)
|
||||||
|
temperature: 0.7 # Temperatura del modelo
|
||||||
|
max_tokens: 8192 # Tokens máximos
|
||||||
|
|
||||||
|
# ========================================
|
||||||
|
# Configuración de Canales
|
||||||
|
# ========================================
|
||||||
|
channels:
|
||||||
|
# WhatsApp
|
||||||
|
whatsapp:
|
||||||
|
enabled: true
|
||||||
|
pairing: code # Método de emparejamiento
|
||||||
|
allowlist:
|
||||||
|
- "+1234567890" # Números permitidos
|
||||||
|
|
||||||
|
# Telegram
|
||||||
|
telegram:
|
||||||
|
enabled: true
|
||||||
|
bot_token: "${TELEGRAM_BOT_TOKEN}"
|
||||||
|
|
||||||
|
# Discord
|
||||||
|
discord:
|
||||||
|
enabled: true
|
||||||
|
bot_token: "${DISCORD_BOT_TOKEN}"
|
||||||
|
|
||||||
|
# Signal
|
||||||
|
signal:
|
||||||
|
enabled: true
|
||||||
|
phone: "+1234567890"
|
||||||
|
|
||||||
|
# Slack
|
||||||
|
slack:
|
||||||
|
enabled: true
|
||||||
|
bot_token: "${SLACK_BOT_TOKEN}"
|
||||||
|
|
||||||
|
# ========================================
|
||||||
|
# Configuración de Herramientas
|
||||||
|
# ========================================
|
||||||
|
tools:
|
||||||
|
browser:
|
||||||
|
enabled: true
|
||||||
|
headless: true # Navegador sin interfaz
|
||||||
|
timeout: 30000 # Timeout en ms
|
||||||
|
|
||||||
|
canvas:
|
||||||
|
enabled: true
|
||||||
|
port: 8080 # Puerto Canvas
|
||||||
|
|
||||||
|
bash:
|
||||||
|
enabled: true
|
||||||
|
timeout: 60000 # Timeout comandos
|
||||||
|
|
||||||
|
memory:
|
||||||
|
enabled: true
|
||||||
|
max_size: 1000 # Entradas máximas
|
||||||
|
|
||||||
|
# ========================================
|
||||||
|
# Configuración de Sandbox (Opcional)
|
||||||
|
# ========================================
|
||||||
|
sandbox:
|
||||||
|
enabled: false
|
||||||
|
docker_image: "jarvis/sandbox"
|
||||||
|
|
||||||
|
# ========================================
|
||||||
|
# Configuración de Plugins
|
||||||
|
# ========================================
|
||||||
|
plugins:
|
||||||
|
- name: matrix
|
||||||
|
enabled: true
|
||||||
|
config:
|
||||||
|
homeserver: "https://matrix.org"
|
||||||
|
|
||||||
|
- name: voice-call
|
||||||
|
enabled: false
|
||||||
|
config:
|
||||||
|
provider: "twilio"
|
||||||
|
|
||||||
|
# ========================================
|
||||||
|
# Configuración de Skills
|
||||||
|
# ========================================
|
||||||
|
skills:
|
||||||
|
- workspace1
|
||||||
|
- workspace2
|
||||||
|
```
|
||||||
|
|
||||||
|
### Variables de Entorno
|
||||||
|
|
||||||
|
Crea un archivo `.env` en la raíz del proyecto:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# ========================================
|
||||||
|
# Tokens de API de IA
|
||||||
|
# ========================================
|
||||||
|
ANTHROPIC_API_KEY=sk-ant-api03-...
|
||||||
|
OPENAI_API_KEY=sk-...
|
||||||
|
|
||||||
|
# ========================================
|
||||||
|
# Tokens de Canales
|
||||||
|
# ========================================
|
||||||
|
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
|
||||||
|
DISCORD_BOT_TOKEN=MTk4...
|
||||||
|
SLACK_BOT_TOKEN=xoxb-...
|
||||||
|
|
||||||
|
# ========================================
|
||||||
|
# Configuración del Gateway
|
||||||
|
# ========================================
|
||||||
|
CLAWDBOT_GATEWAY_PORT=18789
|
||||||
|
CLAWDBOT_GATEWAY_BIND=loopback
|
||||||
|
|
||||||
|
# ========================================
|
||||||
|
# Configuración de Modo
|
||||||
|
# ========================================
|
||||||
|
CLAWDBOT_PROFILE=production # 'production' o 'dev'
|
||||||
|
CLAWDBOT_SKIP_CHANNELS=0
|
||||||
|
|
||||||
|
# ========================================
|
||||||
|
# Configuración de Depuración
|
||||||
|
# ========================================
|
||||||
|
CLAWDBOT_DEBUG=0
|
||||||
|
CLAWDBOT_VERBOSE=0
|
||||||
|
```
|
||||||
|
|
||||||
|
### Diagrama de Configuración
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────────────────────────────────────────────────────┐
|
||||||
|
│ Proceso de Configuración │
|
||||||
|
└────────────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
1. INSTALACIÓN
|
||||||
|
│
|
||||||
|
├─→ Instalar paquete npm/pnpm
|
||||||
|
│
|
||||||
|
└─→ Ejecutar: moltbot onboard --install-daemon
|
||||||
|
|
||||||
|
2. CONFIGURACIÓN INTERACTIVA
|
||||||
|
│
|
||||||
|
├─→ Seleccionar modelos IA (Claude, GPT, etc.)
|
||||||
|
│ └─→ Añadir tokens API o OAuth
|
||||||
|
│
|
||||||
|
├─→ Configurar canales
|
||||||
|
│ ├─→ WhatsApp (emparejamiento QR)
|
||||||
|
│ ├─→ Telegram (bot token)
|
||||||
|
│ ├─→ Discord (bot token)
|
||||||
|
│ ├─→ Signal (phone number)
|
||||||
|
│ └─→ Otros canales
|
||||||
|
│
|
||||||
|
├─→ Configurar herramientas
|
||||||
|
│ ├─→ Browser (Playwright)
|
||||||
|
│ ├─→ Canvas (A2UI)
|
||||||
|
│ ├─→ Bash (comandos)
|
||||||
|
│ └─→ Memory (almacenamiento)
|
||||||
|
│
|
||||||
|
└─→ Configurar seguridad
|
||||||
|
├─→ Listas de permitidos
|
||||||
|
├─→ Políticas de emparejamiento DM
|
||||||
|
└─→ Permisos de grupo
|
||||||
|
|
||||||
|
3. VERIFICACIÓN
|
||||||
|
│
|
||||||
|
├─→ Ejecutar: moltbot doctor
|
||||||
|
│ └─→ Verifica configuración y detecta problemas
|
||||||
|
│
|
||||||
|
└─→ Ejecutar: moltbot channels status
|
||||||
|
└─→ Verifica estado de canales
|
||||||
|
|
||||||
|
4. INICIO DEL GATEWAY
|
||||||
|
│
|
||||||
|
├─→ Modo Daemon: moltbot daemon start
|
||||||
|
│ └─→ Gateway se ejecuta en segundo plano
|
||||||
|
│
|
||||||
|
└─→ Modo Manual: moltbot gateway --port 18789
|
||||||
|
└─→ Gateway se ejecuta en primer plano
|
||||||
|
|
||||||
|
5. EMPAREJAMIENTO DE CANALES
|
||||||
|
│
|
||||||
|
├─→ WhatsApp: Escanear código QR
|
||||||
|
│
|
||||||
|
├─→ Otros canales: Aprobar códigos de emparejamiento
|
||||||
|
│ └─→ Ejecutar: moltbot pairing approve <canal> <código>
|
||||||
|
│
|
||||||
|
└─→ Verificar conexiones
|
||||||
|
└─→ Ejecutar: moltbot channels status --probe
|
||||||
|
|
||||||
|
6. ¡LISTO!
|
||||||
|
└─→ Enviar mensaje de prueba
|
||||||
|
└─→ Ejecutar: moltbot agent --message "Hola Jarvis"
|
||||||
|
```
|
||||||
|
|
||||||
|
📖 **Profundizar**: Ver [Guía de Configuración Completa](docs/README-ES.md#configuración-y-despliegue)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Uso Básico
|
||||||
|
|
||||||
|
### Iniciar el Gateway
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Modo daemon (recomendado)
|
||||||
|
moltbot daemon install
|
||||||
|
moltbot daemon start
|
||||||
|
moltbot daemon status
|
||||||
|
|
||||||
|
# Modo manual (desarrollo)
|
||||||
|
moltbot gateway --port 18789 --verbose
|
||||||
|
```
|
||||||
|
|
||||||
|
### Enviar Mensajes
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Enviar mensaje a un contacto
|
||||||
|
moltbot message send --to +1234567890 --message "Hola desde Jarvis"
|
||||||
|
|
||||||
|
# Enviar mensaje a un grupo
|
||||||
|
moltbot message send --to group_id --message "Hola grupo"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Interactuar con el Agente
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Modo interactivo
|
||||||
|
moltbot agent --message "¿Cuál es el clima hoy?"
|
||||||
|
|
||||||
|
# Con modo de thinking alto
|
||||||
|
moltbot agent --message "Analiza este documento" --thinking high
|
||||||
|
|
||||||
|
# Ejecutar comando y devolver resultado al canal
|
||||||
|
moltbot agent --message "Lista archivos en /home" --reply-back telegram
|
||||||
|
```
|
||||||
|
|
||||||
|
### Gestionar Canales
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Ver estado de todos los canales
|
||||||
|
moltbot channels status
|
||||||
|
|
||||||
|
# Ver estado con verificación de conexión
|
||||||
|
moltbot channels status --probe
|
||||||
|
|
||||||
|
# Ver estado de un canal específico
|
||||||
|
moltbot channels status whatsapp
|
||||||
|
|
||||||
|
# Reiniciar un canal
|
||||||
|
moltbot channels restart telegram
|
||||||
|
```
|
||||||
|
|
||||||
|
### Gestionar Emparejamiento
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Listar solicitudes de emparejamiento pendientes
|
||||||
|
moltbot pairing list
|
||||||
|
|
||||||
|
# Aprobar un emparejamiento
|
||||||
|
moltbot pairing approve telegram ABC123
|
||||||
|
|
||||||
|
# Rechazar un emparejamiento
|
||||||
|
moltbot pairing reject whatsapp XYZ789
|
||||||
|
|
||||||
|
# Ver lista de permitidos
|
||||||
|
moltbot pairing allowlist
|
||||||
|
```
|
||||||
|
|
||||||
|
### Gestionar Modelos
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Listar modelos disponibles
|
||||||
|
moltbot models list
|
||||||
|
|
||||||
|
# Ver configuración de modelos
|
||||||
|
moltbot models config
|
||||||
|
|
||||||
|
# Probar un modelo
|
||||||
|
moltbot models test claude-4.5-sonnet
|
||||||
|
|
||||||
|
# Cambiar modelo por defecto
|
||||||
|
moltbot config set agents.default.model claude-4.5-sonnet
|
||||||
|
```
|
||||||
|
|
||||||
|
### Gestionar Skills
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Listar skills disponibles
|
||||||
|
moltbot skills list
|
||||||
|
|
||||||
|
# Instalar un skill
|
||||||
|
moltbot skills install workspace1
|
||||||
|
|
||||||
|
# Actualizar skills
|
||||||
|
moltbot skills update
|
||||||
|
|
||||||
|
# Ver configuración de skills
|
||||||
|
moltbot skills config
|
||||||
|
```
|
||||||
|
|
||||||
|
### Diagnóstico
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Ejecutar diagnóstico completo
|
||||||
|
moltbot doctor
|
||||||
|
|
||||||
|
# Ver logs del gateway
|
||||||
|
moltbot logs gateway
|
||||||
|
|
||||||
|
# Ver logs del agente
|
||||||
|
moltbot logs agent
|
||||||
|
|
||||||
|
# Ver logs de un canal
|
||||||
|
moltbot logs channel telegram
|
||||||
|
```
|
||||||
|
|
||||||
|
📖 **Profundizar**: Ver [Comandos CLI](docs/README-ES.md#cli)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Canales Soportados
|
||||||
|
|
||||||
|
### Canales Integrados
|
||||||
|
|
||||||
|
| Canal | Biblioteca | Estado | Documentación |
|
||||||
|
|-------|-----------|--------|---------------|
|
||||||
|
| **WhatsApp** | @whiskeysockets/baileys | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **Telegram** | grammy | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **Signal** | signal-cli | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **iMessage** | imsg | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **Discord** | discord.js | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **Slack** | @slack/bolt | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **Google Chat** | Chat API | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
|
||||||
|
### Canales de Extensión
|
||||||
|
|
||||||
|
| Canal | Ubicación | Estado | Documentación |
|
||||||
|
|-------|-----------|--------|---------------|
|
||||||
|
| **BlueBubbles** | extensions/bluebubbles | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **Microsoft Teams** | extensions/msteams | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **Matrix** | extensions/matrix | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **Zalo** | extensions/zalo | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **Zalo Personal** | extensions/zalouser | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **Twitch** | extensions/twitch | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **Mattermost** | extensions/mattermost | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **LINE** | extensions/line | ✅ Estable | [Ver docs](docs/channels/) |
|
||||||
|
| **Voice Call** | extensions/voice-call | 🔶 Beta | [Ver docs](docs/channels/) |
|
||||||
|
|
||||||
|
### Características de Canal
|
||||||
|
|
||||||
|
- ✅ **Emparejamiento DM**: Lista de permitidos basada en código
|
||||||
|
- ✅ **Enrutamiento de grupo**: Control de menciones
|
||||||
|
- ✅ **Etiquetas de respuesta**: Respuestas basadas en hilos
|
||||||
|
- ✅ **Fragmentación de mensajes**: Límites específicos por canal
|
||||||
|
- ✅ **Reacciones**: Reconocimientos
|
||||||
|
- ✅ **Indicadores de escritura**: Estado en tiempo real
|
||||||
|
- ✅ **Redacción de medios**: Capacidades de privacidad
|
||||||
|
|
||||||
|
📖 **Profundizar**: Ver [Documentación de Canales](docs/README-ES.md#canales-de-mensajería)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Documentación Completa
|
||||||
|
|
||||||
|
### 📚 Documentación Principal
|
||||||
|
|
||||||
|
- **[README Español (Completo)](docs/README-ES.md)** - Documentación completa en español
|
||||||
|
- **[Arquitectura](docs/ARCHITECTURE.md)** - Arquitectura técnica detallada del sistema
|
||||||
|
- **[Componentes](docs/COMPONENTS.md)** - Descripción de componentes individuales (próximamente)
|
||||||
|
- **[Desarrollo](docs/DEVELOPMENT.md)** - Guía para desarrolladores (próximamente)
|
||||||
|
- **[Plugin Development](docs/PLUGIN-DEVELOPMENT.md)** - Crear plugins personalizados (próximamente)
|
||||||
|
- **[API Reference](docs/API-REFERENCE.md)** - Referencia completa de API (próximamente)
|
||||||
|
- **[Deployment](docs/DEPLOYMENT.md)** - Guías de despliegue (próximamente)
|
||||||
|
|
||||||
|
### 🔧 Configuración y Administración
|
||||||
|
|
||||||
|
- **Gateway**: Ver [docs/gateway/](docs/gateway/)
|
||||||
|
- **Canales**: Ver [docs/channels/](docs/channels/)
|
||||||
|
- **Seguridad**: Ver [docs/security/](docs/security/)
|
||||||
|
- **CLI**: Ver [docs/cli/](docs/cli/)
|
||||||
|
|
||||||
|
### 💡 Conceptos y Guías
|
||||||
|
|
||||||
|
- **Modelos IA**: Ver [docs/concepts/](docs/concepts/)
|
||||||
|
- **Sesiones**: Ver [docs/concepts/](docs/concepts/)
|
||||||
|
- **Herramientas**: Ver [docs/tools/](docs/tools/)
|
||||||
|
- **Plugins**: Ver [docs/plugins/](docs/plugins/)
|
||||||
|
|
||||||
|
### 🚀 Inicio Rápido
|
||||||
|
|
||||||
|
- **Getting Started**: Ver [docs/start/](docs/start/)
|
||||||
|
- **Instalación**: Ver [docs/install/](docs/install/)
|
||||||
|
- **Plataformas**: Ver [docs/platforms/](docs/platforms/)
|
||||||
|
|
||||||
|
### 📖 Referencia
|
||||||
|
|
||||||
|
- **Testing**: Ver [docs/testing.md](docs/testing.md)
|
||||||
|
- **Environment**: Ver [docs/environment.md](docs/environment.md)
|
||||||
|
- **Debugging**: Ver [docs/debugging.md](docs/debugging.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Desarrollo
|
||||||
|
|
||||||
|
### Configuración del Entorno de Desarrollo
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Clonar repositorio
|
||||||
|
git clone https://github.com/jeturing/Jarvis.git
|
||||||
|
cd Jarvis
|
||||||
|
|
||||||
|
# 2. Instalar dependencias
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# 3. Construir UI
|
||||||
|
pnpm ui:build
|
||||||
|
|
||||||
|
# 4. Construir proyecto
|
||||||
|
pnpm build
|
||||||
|
|
||||||
|
# 5. Ejecutar en modo desarrollo
|
||||||
|
pnpm gateway:watch # Auto-recarga en cambios
|
||||||
|
```
|
||||||
|
|
||||||
|
### Scripts de Desarrollo
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Desarrollo
|
||||||
|
pnpm dev # Ejecutar CLI en modo dev
|
||||||
|
pnpm gateway:watch # Gateway con auto-recarga
|
||||||
|
pnpm gateway:dev # Gateway dev sin canales
|
||||||
|
pnpm tui:dev # UI de terminal dev
|
||||||
|
|
||||||
|
# Build
|
||||||
|
pnpm build # Compilar TypeScript
|
||||||
|
pnpm ui:build # Construir UI web
|
||||||
|
pnpm canvas:a2ui:bundle # Empaquetar Canvas A2UI
|
||||||
|
|
||||||
|
# Testing
|
||||||
|
pnpm test # Ejecutar todos los tests
|
||||||
|
pnpm test:watch # Tests en modo watch
|
||||||
|
pnpm test:coverage # Tests con cobertura
|
||||||
|
pnpm test:e2e # Tests end-to-end
|
||||||
|
|
||||||
|
# Linting & Formatting
|
||||||
|
pnpm lint # Lint TypeScript
|
||||||
|
pnpm lint:fix # Fix problemas de lint
|
||||||
|
pnpm format # Verificar formato
|
||||||
|
pnpm format:fix # Fix formato
|
||||||
|
|
||||||
|
# Plataformas
|
||||||
|
pnpm ios:build # Construir app iOS
|
||||||
|
pnpm android:run # Ejecutar app Android
|
||||||
|
pnpm mac:package # Empaquetar app macOS
|
||||||
|
```
|
||||||
|
|
||||||
|
### Estructura del Proyecto
|
||||||
|
|
||||||
|
```
|
||||||
|
/
|
||||||
|
├── src/ # Código fuente TypeScript
|
||||||
|
├── extensions/ # Plugins de canal y extensiones
|
||||||
|
├── apps/ # Aplicaciones nativas (macOS, iOS, Android)
|
||||||
|
├── docs/ # Documentación
|
||||||
|
├── skills/ # Paquetes de skills de workspace
|
||||||
|
├── scripts/ # Scripts de utilidad
|
||||||
|
├── test/ # Fixtures de test y helpers
|
||||||
|
└── ui/ # UI web (Control UI)
|
||||||
|
```
|
||||||
|
|
||||||
|
📖 **Profundizar**: Ver [Estructura Completa](docs/README-ES.md#estructura-de-directorios)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Contribuir
|
||||||
|
|
||||||
|
¡Las contribuciones son bienvenidas! Por favor lee [CONTRIBUTING.md](CONTRIBUTING.md) para detalles sobre nuestro código de conducta y el proceso para enviar pull requests.
|
||||||
|
|
||||||
|
### Cómo Contribuir
|
||||||
|
|
||||||
|
1. **Fork el repositorio**
|
||||||
|
2. **Crea una rama** para tu feature (`git checkout -b feature/AmazingFeature`)
|
||||||
|
3. **Commit tus cambios** (`git commit -m 'Add some AmazingFeature'`)
|
||||||
|
4. **Push a la rama** (`git push origin feature/AmazingFeature`)
|
||||||
|
5. **Abre un Pull Request**
|
||||||
|
|
||||||
|
### Áreas de Contribución
|
||||||
|
|
||||||
|
- 🐛 **Bug fixes**: Reporta o arregla bugs
|
||||||
|
- ✨ **Nuevas características**: Propón o implementa nuevas features
|
||||||
|
- 📝 **Documentación**: Mejora la documentación
|
||||||
|
- 🔌 **Plugins**: Crea nuevos plugins de canal o herramientas
|
||||||
|
- 🧪 **Tests**: Añade o mejora tests
|
||||||
|
- 🌐 **Traducciones**: Traduce documentación a otros idiomas
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Licencia
|
||||||
|
|
||||||
|
Este proyecto está licenciado bajo la Licencia MIT - ver el archivo [LICENSE](LICENSE) para detalles.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Soporte
|
||||||
|
|
||||||
|
¿Necesitas ayuda? Aquí tienes algunas opciones:
|
||||||
|
|
||||||
|
- 📖 **Documentación**: Revisa la [documentación completa](docs/README-ES.md)
|
||||||
|
- 🐛 **Issues**: Reporta bugs en [GitHub Issues](https://github.com/jeturing/Jarvis/issues)
|
||||||
|
- 💬 **Discusiones**: Únete a [GitHub Discussions](https://github.com/jeturing/Jarvis/discussions)
|
||||||
|
- 📧 **Email**: Contacta al equipo de desarrollo
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Agradecimientos
|
||||||
|
|
||||||
|
Gracias a todos los contribuidores que han ayudado a hacer este proyecto posible.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Seguridad
|
||||||
|
|
||||||
|
Para reportar vulnerabilidades de seguridad, por favor lee [SECURITY.md](SECURITY.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<strong>Hecho con ❤️ por la comunidad</strong>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<sub>Si encuentras útil este proyecto, considera darle una ⭐ en GitHub</sub>
|
||||||
|
</p>
|
||||||
814
docs/ARCHITECTURE.md
Normal file
814
docs/ARCHITECTURE.md
Normal file
@ -0,0 +1,814 @@
|
|||||||
|
# Moltbot Architecture Documentation
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
1. [Overview](#overview)
|
||||||
|
2. [High-Level Architecture](#high-level-architecture)
|
||||||
|
3. [Core Components](#core-components)
|
||||||
|
4. [Data Flow](#data-flow)
|
||||||
|
5. [Message Routing](#message-routing)
|
||||||
|
6. [Agent Execution Model](#agent-execution-model)
|
||||||
|
7. [Plugin Architecture](#plugin-architecture)
|
||||||
|
8. [Security Model](#security-model)
|
||||||
|
9. [Storage & Persistence](#storage--persistence)
|
||||||
|
10. [Network Architecture](#network-architecture)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Moltbot is designed as a **local-first, extensible AI assistant platform** with a microkernel-inspired architecture. The system consists of a central Gateway (control plane) and modular components (channels, tools, plugins) that communicate through well-defined interfaces.
|
||||||
|
|
||||||
|
### Design Principles
|
||||||
|
|
||||||
|
1. **Local-First**: Everything runs on user's devices; no central server dependency
|
||||||
|
2. **Privacy-Focused**: User data never leaves their control
|
||||||
|
3. **Extensible**: Plugin system for adding channels, tools, and functionality
|
||||||
|
4. **Multi-Platform**: Works on macOS, iOS, Android, Linux, Windows (WSL2)
|
||||||
|
5. **Resilient**: Graceful degradation; continues working when components fail
|
||||||
|
6. **Developer-Friendly**: Clear APIs, TypeScript types, comprehensive testing
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## High-Level Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ User Interfaces │
|
||||||
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ macOS │ │ iOS │ │ Android │ │ CLI / Web UI │ │
|
||||||
|
│ │ App │ │ App │ │ App │ │ │ │
|
||||||
|
│ └──────────┘ └──────────┘ └──────────┘ └─────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
↓ WebSocket / HTTP
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Gateway Server │
|
||||||
|
│ ┌─────────────────────────────────────────────────────────────┐│
|
||||||
|
│ │ WebSocket Control Plane ││
|
||||||
|
│ │ • Session Management ││
|
||||||
|
│ │ • Message Routing ││
|
||||||
|
│ │ • Model Catalog ││
|
||||||
|
│ │ • Discovery Service (mDNS) ││
|
||||||
|
│ └─────────────────────────────────────────────────────────────┘│
|
||||||
|
│ │ │
|
||||||
|
│ ┌──────────────┬───────────┴───────────┬──────────────────┐ │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ ▼ ▼ ▼ ▼ │
|
||||||
|
│ ┌──────┐ ┌──────────┐ ┌───────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ Chat │ │ Model │ │ Browser │ │ Cron Scheduler │ │
|
||||||
|
│ │Registry│ │ Catalog │ │ Tool │ │ │ │
|
||||||
|
│ └──────┘ └──────────┘ └───────────┘ └─────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Agent Runtime Layer │
|
||||||
|
│ ┌─────────────────────────────────────────────────────────────┐│
|
||||||
|
│ │ Pi Agent (RPC Mode) ││
|
||||||
|
│ │ • Tool Streaming ││
|
||||||
|
│ │ • Block Streaming ││
|
||||||
|
│ │ • Model Failover ││
|
||||||
|
│ │ • Auth Profile Rotation ││
|
||||||
|
│ │ • Session Context Management ││
|
||||||
|
│ └─────────────────────────────────────────────────────────────┘│
|
||||||
|
│ │ │
|
||||||
|
│ ┌──────────────┬───────────┴───────────┬──────────────────┐ │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ ▼ ▼ ▼ ▼ │
|
||||||
|
│ ┌──────┐ ┌──────────┐ ┌───────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ Tool │ │ Session │ │ Memory │ │ Sandbox │ │
|
||||||
|
│ │Registry│ │ Manager │ │ Store │ │ (Optional) │ │
|
||||||
|
│ └──────┘ └──────────┘ └───────────┘ └─────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Channel Layer (Multi-Protocol) │
|
||||||
|
│ ┌──────────┬──────────┬──────────┬──────────┬──────────────┐ │
|
||||||
|
│ │ WhatsApp │ Telegram │ Signal │ Discord │ Slack │ │
|
||||||
|
│ └──────────┴──────────┴──────────┴──────────┴──────────────┘ │
|
||||||
|
│ ┌──────────┬──────────┬──────────┬──────────┬──────────────┐ │
|
||||||
|
│ │ iMessage │ Teams │ Matrix │ Zalo │ BlueBubbles │ │
|
||||||
|
│ └──────────┴──────────┴──────────┴──────────┴──────────────┘ │
|
||||||
|
│ ┌──────────┬──────────┬──────────┬──────────┬──────────────┐ │
|
||||||
|
│ │ Twitch │Mattermost│ LINE │ Nostr │ Voice Call │ │
|
||||||
|
│ └──────────┴──────────┴──────────┴──────────┴──────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ External Services │
|
||||||
|
│ ┌──────────┬──────────┬──────────┬──────────┬──────────────┐ │
|
||||||
|
│ │ Anthropic│ OpenAI │ AWS │ Ollama │ Google │ │
|
||||||
|
│ │ Claude │ GPT │ Bedrock │ (Local) │ Gemini │ │
|
||||||
|
│ └──────────┴──────────┴──────────┴──────────┴──────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Components
|
||||||
|
|
||||||
|
### 1. Gateway Server
|
||||||
|
|
||||||
|
**Responsibility**: Central control plane for all communication and orchestration.
|
||||||
|
|
||||||
|
**Key Modules**:
|
||||||
|
- `server.ts` - Main WebSocket server
|
||||||
|
- `chat-registry.ts` - Active chat session registry
|
||||||
|
- `model-catalog.ts` - Available AI models catalog
|
||||||
|
- `browser-tool.ts` - Shared browser automation tool
|
||||||
|
- `discovery.ts` - mDNS service discovery
|
||||||
|
|
||||||
|
**APIs**:
|
||||||
|
```typescript
|
||||||
|
interface GatewayServer {
|
||||||
|
start(): Promise<void>;
|
||||||
|
stop(): Promise<void>;
|
||||||
|
registerChat(chat: ChatSession): void;
|
||||||
|
unregisterChat(chatId: string): void;
|
||||||
|
routeMessage(message: InboundMessage): Promise<void>;
|
||||||
|
getModelCatalog(): ModelCatalog;
|
||||||
|
getBrowserTool(): BrowserTool;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Communication**:
|
||||||
|
- WebSocket (ws://) for real-time bidirectional communication
|
||||||
|
- HTTP REST API for management operations
|
||||||
|
- mDNS for local network discovery
|
||||||
|
|
||||||
|
### 2. Agent Runtime
|
||||||
|
|
||||||
|
**Responsibility**: Execute AI models and manage agent sessions.
|
||||||
|
|
||||||
|
**Key Modules**:
|
||||||
|
- `pi-embedded-runner.ts` - Pi Agent executor
|
||||||
|
- `session-manager.ts` - Session lifecycle management
|
||||||
|
- `tool-registry.ts` - Available tools catalog
|
||||||
|
- `model-auth.ts` - Model authentication and failover
|
||||||
|
|
||||||
|
**Execution Flow**:
|
||||||
|
```typescript
|
||||||
|
interface AgentRuntime {
|
||||||
|
createSession(config: SessionConfig): AgentSession;
|
||||||
|
executeMessage(session: AgentSession, message: string): AsyncGenerator<AgentEvent>;
|
||||||
|
executeTools(session: AgentSession, tools: ToolCall[]): Promise<ToolResult[]>;
|
||||||
|
streamResponse(session: AgentSession): AsyncGenerator<ResponseChunk>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Session Management**:
|
||||||
|
- **Main Session**: Primary agent for user interactions
|
||||||
|
- **Group Sessions**: Isolated agents for group chats
|
||||||
|
- **Sub-Sessions**: Spawned agents for specific tasks
|
||||||
|
- **Queue Modes**: Serial (one at a time) vs Concurrent (parallel)
|
||||||
|
|
||||||
|
### 3. Channel Layer
|
||||||
|
|
||||||
|
**Responsibility**: Handle messaging protocol specifics and normalize messages.
|
||||||
|
|
||||||
|
**Channel Interface**:
|
||||||
|
```typescript
|
||||||
|
interface Channel {
|
||||||
|
name: string;
|
||||||
|
type: ChannelType;
|
||||||
|
|
||||||
|
// Lifecycle
|
||||||
|
init(config: ChannelConfig): Promise<void>;
|
||||||
|
start(): Promise<void>;
|
||||||
|
stop(): Promise<void>;
|
||||||
|
|
||||||
|
// Messaging
|
||||||
|
send(message: OutboundMessage): Promise<void>;
|
||||||
|
receive(handler: MessageHandler): void;
|
||||||
|
|
||||||
|
// Status
|
||||||
|
getStatus(): ChannelStatus;
|
||||||
|
getConnections(): Connection[];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Message Normalization**:
|
||||||
|
```typescript
|
||||||
|
interface NormalizedMessage {
|
||||||
|
id: string;
|
||||||
|
channel: string;
|
||||||
|
from: string;
|
||||||
|
to: string;
|
||||||
|
text: string;
|
||||||
|
media?: MediaAttachment[];
|
||||||
|
replyTo?: string;
|
||||||
|
timestamp: number;
|
||||||
|
metadata: Record<string, unknown>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Channel Types**:
|
||||||
|
- **Built-in**: WhatsApp, Telegram, Signal, Discord, Slack, iMessage
|
||||||
|
- **Extensions**: Teams, Matrix, Zalo, BlueBubbles, Twitch, etc.
|
||||||
|
|
||||||
|
### 4. Tool System
|
||||||
|
|
||||||
|
**Responsibility**: Provide capabilities to agents beyond text generation.
|
||||||
|
|
||||||
|
**Tool Interface**:
|
||||||
|
```typescript
|
||||||
|
interface Tool {
|
||||||
|
name: string;
|
||||||
|
description: string;
|
||||||
|
schema: JSONSchema;
|
||||||
|
|
||||||
|
execute(params: unknown, context: ToolContext): Promise<ToolResult>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Built-in Tools**:
|
||||||
|
- **Browser Tool**: Web automation, screenshots, form filling
|
||||||
|
- **Canvas Tool**: Visual workspace with A2UI
|
||||||
|
- **Image Tool**: Image analysis and generation
|
||||||
|
- **Message Tool**: Send messages across channels
|
||||||
|
- **Session Tool**: Spawn sub-agents
|
||||||
|
- **Bash Tool**: Execute shell commands
|
||||||
|
- **Web Tool**: Fetch URLs, web search, readability
|
||||||
|
- **Memory Tool**: Store and retrieve context
|
||||||
|
- **Cron Tool**: Schedule tasks
|
||||||
|
|
||||||
|
**Tool Execution Pipeline**:
|
||||||
|
```
|
||||||
|
User Message → Agent → Tool Call → Tool Execute → Tool Result → Agent → Response
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Plugin System
|
||||||
|
|
||||||
|
**Responsibility**: Enable extensibility through modular plugins.
|
||||||
|
|
||||||
|
**Plugin Types**:
|
||||||
|
1. **Channel Plugins**: Add new messaging integrations
|
||||||
|
2. **Tool Plugins**: Add custom agent tools
|
||||||
|
3. **Auth Plugins**: Add OAuth handlers
|
||||||
|
4. **Memory Plugins**: Add storage backends
|
||||||
|
5. **Hook Plugins**: Add global event handlers
|
||||||
|
|
||||||
|
**Plugin Lifecycle**:
|
||||||
|
```typescript
|
||||||
|
interface Plugin {
|
||||||
|
manifest: PluginManifest;
|
||||||
|
|
||||||
|
// Lifecycle
|
||||||
|
init(services: PluginServices): Promise<void>;
|
||||||
|
start(): Promise<void>;
|
||||||
|
stop(): Promise<void>;
|
||||||
|
|
||||||
|
// Hooks
|
||||||
|
hooks?: Record<string, HookHandler>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Plugin Discovery**:
|
||||||
|
- Auto-detect from `extensions/` directory
|
||||||
|
- Auto-detect from `node_modules/@moltbot/` packages
|
||||||
|
- Validate manifest and config schema
|
||||||
|
- Load and initialize plugins
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data Flow
|
||||||
|
|
||||||
|
### Inbound Message Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
External Channel (WhatsApp, Telegram, etc.)
|
||||||
|
↓
|
||||||
|
Channel Handler
|
||||||
|
↓
|
||||||
|
Message Normalization
|
||||||
|
↓
|
||||||
|
Allowlist Check
|
||||||
|
↓
|
||||||
|
Gateway Router
|
||||||
|
↓
|
||||||
|
Session Selection
|
||||||
|
↓
|
||||||
|
Agent Execution
|
||||||
|
↓
|
||||||
|
Tool Streaming
|
||||||
|
↓
|
||||||
|
Response Generation
|
||||||
|
↓
|
||||||
|
Channel Formatting
|
||||||
|
↓
|
||||||
|
Outbound Message
|
||||||
|
↓
|
||||||
|
External Channel
|
||||||
|
```
|
||||||
|
|
||||||
|
### Detailed Flow Steps
|
||||||
|
|
||||||
|
1. **Channel Receives Message**
|
||||||
|
- Raw message from external protocol
|
||||||
|
- Protocol-specific handling (e.g., Baileys for WhatsApp)
|
||||||
|
|
||||||
|
2. **Message Normalization**
|
||||||
|
- Convert to `NormalizedMessage` format
|
||||||
|
- Extract text, media, reply context
|
||||||
|
- Add metadata
|
||||||
|
|
||||||
|
3. **Allowlist Check**
|
||||||
|
- Verify sender is allowed
|
||||||
|
- Check pairing status for DMs
|
||||||
|
- Validate group membership
|
||||||
|
|
||||||
|
4. **Gateway Routing**
|
||||||
|
- Determine target session
|
||||||
|
- Check activation mode (mention, reply, always-on)
|
||||||
|
- Queue or execute immediately
|
||||||
|
|
||||||
|
5. **Agent Execution**
|
||||||
|
- Load session context
|
||||||
|
- Execute model with tools
|
||||||
|
- Stream tool calls and responses
|
||||||
|
|
||||||
|
6. **Tool Execution**
|
||||||
|
- Execute tools as needed
|
||||||
|
- Stream tool results back to agent
|
||||||
|
- Handle tool errors gracefully
|
||||||
|
|
||||||
|
7. **Response Generation**
|
||||||
|
- Agent generates response
|
||||||
|
- Apply thinking mode (low/high/always)
|
||||||
|
- Format for target channel
|
||||||
|
|
||||||
|
8. **Channel Formatting**
|
||||||
|
- Convert to channel-specific format
|
||||||
|
- Chunk long messages if needed
|
||||||
|
- Add reactions/typing indicators
|
||||||
|
|
||||||
|
9. **Outbound Message**
|
||||||
|
- Send via channel handler
|
||||||
|
- Track delivery status
|
||||||
|
- Handle errors and retries
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Message Routing
|
||||||
|
|
||||||
|
### Routing Rules
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface RoutingConfig {
|
||||||
|
// Main session routing
|
||||||
|
mainSession: {
|
||||||
|
activationMode: 'always' | 'mention' | 'reply' | 'dm-only';
|
||||||
|
replyBack: boolean;
|
||||||
|
allowedChannels: string[];
|
||||||
|
};
|
||||||
|
|
||||||
|
// Group session routing
|
||||||
|
groupSessions: {
|
||||||
|
enabled: boolean;
|
||||||
|
isolateByGroup: boolean;
|
||||||
|
activationMode: 'mention' | 'reply';
|
||||||
|
};
|
||||||
|
|
||||||
|
// Cross-channel routing
|
||||||
|
crossChannel: {
|
||||||
|
enabled: boolean;
|
||||||
|
routes: ChannelRoute[];
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Activation Modes
|
||||||
|
|
||||||
|
1. **Always-On**: Every message triggers agent
|
||||||
|
2. **Mention**: Only messages mentioning bot trigger agent
|
||||||
|
3. **Reply**: Only replies to bot messages trigger agent
|
||||||
|
4. **DM-Only**: Only direct messages trigger agent
|
||||||
|
|
||||||
|
### Session Isolation
|
||||||
|
|
||||||
|
- **Main Session**: Primary agent for user
|
||||||
|
- **Group Session**: Separate agent per group chat
|
||||||
|
- **Workspace Session**: Separate agent per workspace
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Agent Execution Model
|
||||||
|
|
||||||
|
### Session Context
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface SessionContext {
|
||||||
|
sessionId: string;
|
||||||
|
chatId: string;
|
||||||
|
channel: string;
|
||||||
|
|
||||||
|
// Context window
|
||||||
|
messages: Message[];
|
||||||
|
maxTokens: number;
|
||||||
|
|
||||||
|
// Configuration
|
||||||
|
model: string;
|
||||||
|
temperature: number;
|
||||||
|
thinkingMode: 'low' | 'high' | 'always';
|
||||||
|
|
||||||
|
// Tools
|
||||||
|
availableTools: Tool[];
|
||||||
|
toolResults: ToolResult[];
|
||||||
|
|
||||||
|
// Memory
|
||||||
|
memory: MemoryStore;
|
||||||
|
skills: Skill[];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Execution Pipeline
|
||||||
|
|
||||||
|
```
|
||||||
|
Message → Load Context → Execute Model → Stream Tools → Generate Response → Save Context
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tool Streaming
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface ToolStreamEvent {
|
||||||
|
type: 'tool_call' | 'tool_result' | 'text_chunk' | 'thinking';
|
||||||
|
data: unknown;
|
||||||
|
}
|
||||||
|
|
||||||
|
async function* streamAgentExecution(
|
||||||
|
session: SessionContext,
|
||||||
|
message: string
|
||||||
|
): AsyncGenerator<ToolStreamEvent> {
|
||||||
|
// Stream tool calls and results in real-time
|
||||||
|
yield* piAgent.execute(session, message);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Model Failover
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface ModelFailoverConfig {
|
||||||
|
primary: ModelConfig;
|
||||||
|
fallbacks: ModelConfig[];
|
||||||
|
retryAttempts: number;
|
||||||
|
retryDelay: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
async function executeWithFailover(
|
||||||
|
config: ModelFailoverConfig,
|
||||||
|
request: ModelRequest
|
||||||
|
): Promise<ModelResponse> {
|
||||||
|
// Try primary model
|
||||||
|
try {
|
||||||
|
return await execute(config.primary, request);
|
||||||
|
} catch (error) {
|
||||||
|
// Try fallback models
|
||||||
|
for (const fallback of config.fallbacks) {
|
||||||
|
try {
|
||||||
|
return await execute(fallback, request);
|
||||||
|
} catch (fallbackError) {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
throw error;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Plugin Architecture
|
||||||
|
|
||||||
|
### Plugin System Design
|
||||||
|
|
||||||
|
```
|
||||||
|
┌──────────────────────────────────────┐
|
||||||
|
│ Plugin Discovery │
|
||||||
|
│ • extensions/ │
|
||||||
|
│ • node_modules/@moltbot/ │
|
||||||
|
└──────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
↓
|
||||||
|
┌──────────────────────────────────────┐
|
||||||
|
│ Plugin Loader │
|
||||||
|
│ • Validate manifest │
|
||||||
|
│ • Load config schema │
|
||||||
|
│ • Initialize plugin │
|
||||||
|
└──────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
↓
|
||||||
|
┌──────────────────────────────────────┐
|
||||||
|
│ Plugin Runtime │
|
||||||
|
│ • Register hooks │
|
||||||
|
│ • Inject services │
|
||||||
|
│ • Execute plugin logic │
|
||||||
|
└──────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Plugin Manifest
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "my-plugin",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"type": "channel",
|
||||||
|
"exports": {
|
||||||
|
".": "./dist/index.js",
|
||||||
|
"./config-schema": "./dist/config-schema.js"
|
||||||
|
},
|
||||||
|
"hooks": ["channel", "message:received", "message:sent"],
|
||||||
|
"permissions": ["network", "fs", "env"],
|
||||||
|
"dependencies": {
|
||||||
|
"some-lib": "^1.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Plugin Services
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface PluginServices {
|
||||||
|
gateway: GatewayClient;
|
||||||
|
config: ConfigProvider;
|
||||||
|
logger: Logger;
|
||||||
|
http: HttpClient;
|
||||||
|
storage: StorageProvider;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Plugin Hooks
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface PluginHooks {
|
||||||
|
'plugin:init': (plugin: Plugin) => Promise<void>;
|
||||||
|
'plugin:start': (plugin: Plugin) => Promise<void>;
|
||||||
|
'plugin:stop': (plugin: Plugin) => Promise<void>;
|
||||||
|
|
||||||
|
'message:received': (message: NormalizedMessage) => Promise<void>;
|
||||||
|
'message:sent': (message: NormalizedMessage) => Promise<void>;
|
||||||
|
|
||||||
|
'agent:before': (session: SessionContext) => Promise<void>;
|
||||||
|
'agent:after': (session: SessionContext, response: string) => Promise<void>;
|
||||||
|
|
||||||
|
'tool:before': (tool: Tool, params: unknown) => Promise<void>;
|
||||||
|
'tool:after': (tool: Tool, result: ToolResult) => Promise<void>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security Model
|
||||||
|
|
||||||
|
### Authentication
|
||||||
|
|
||||||
|
1. **Pairing System**
|
||||||
|
- Code-based pairing for DMs
|
||||||
|
- One-time pairing codes
|
||||||
|
- Allowlist management
|
||||||
|
|
||||||
|
2. **Channel Authentication**
|
||||||
|
- OAuth tokens (Discord, Slack, etc.)
|
||||||
|
- Bot tokens (Telegram)
|
||||||
|
- Session persistence (WhatsApp, Signal)
|
||||||
|
|
||||||
|
3. **Model Authentication**
|
||||||
|
- API keys (Anthropic, OpenAI)
|
||||||
|
- OAuth (Google, AWS)
|
||||||
|
- Profile rotation on failure
|
||||||
|
|
||||||
|
### Authorization
|
||||||
|
|
||||||
|
1. **Allowlists**
|
||||||
|
- Per-channel allowlists
|
||||||
|
- Phone numbers for WhatsApp
|
||||||
|
- User IDs for Telegram
|
||||||
|
- Handle-based for Discord
|
||||||
|
|
||||||
|
2. **Group Policies**
|
||||||
|
- Mention-only mode
|
||||||
|
- Reply-only mode
|
||||||
|
- Admin-only commands
|
||||||
|
|
||||||
|
3. **Tool Permissions**
|
||||||
|
- Per-tool enable/disable
|
||||||
|
- Execution timeouts
|
||||||
|
- Resource limits
|
||||||
|
|
||||||
|
### Privacy
|
||||||
|
|
||||||
|
1. **Local-First**
|
||||||
|
- All data stored locally
|
||||||
|
- No external server dependency
|
||||||
|
- User controls all data
|
||||||
|
|
||||||
|
2. **Session Isolation**
|
||||||
|
- Separate sessions per chat
|
||||||
|
- No cross-session data leaks
|
||||||
|
- Clear session boundaries
|
||||||
|
|
||||||
|
3. **Media Handling**
|
||||||
|
- Temporary storage with lifecycle
|
||||||
|
- Automatic cleanup
|
||||||
|
- Optional media redaction
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Storage & Persistence
|
||||||
|
|
||||||
|
### File System Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
~/.clawdbot/
|
||||||
|
├── config/
|
||||||
|
│ ├── .moltbot.yaml # Main config
|
||||||
|
│ ├── models.json # Model profiles
|
||||||
|
│ └── skills/ # Skill configs
|
||||||
|
├── credentials/
|
||||||
|
│ ├── anthropic.json # OAuth tokens
|
||||||
|
│ ├── openai.json
|
||||||
|
│ └── channels/ # Channel credentials
|
||||||
|
├── sessions/
|
||||||
|
│ ├── main/ # Main session data
|
||||||
|
│ ├── groups/ # Group sessions
|
||||||
|
│ └── agents/ # Agent-specific data
|
||||||
|
├── media/
|
||||||
|
│ ├── audio/ # Audio files
|
||||||
|
│ ├── images/ # Image files
|
||||||
|
│ └── videos/ # Video files
|
||||||
|
├── memory/
|
||||||
|
│ ├── vectors/ # Vector embeddings
|
||||||
|
│ └── cache/ # Cached data
|
||||||
|
└── logs/
|
||||||
|
├── gateway.log # Gateway logs
|
||||||
|
├── agent.log # Agent logs
|
||||||
|
└── channels/ # Per-channel logs
|
||||||
|
```
|
||||||
|
|
||||||
|
### Session Storage
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface SessionStore {
|
||||||
|
// Session CRUD
|
||||||
|
create(session: SessionContext): Promise<void>;
|
||||||
|
read(sessionId: string): Promise<SessionContext>;
|
||||||
|
update(session: SessionContext): Promise<void>;
|
||||||
|
delete(sessionId: string): Promise<void>;
|
||||||
|
|
||||||
|
// Message history
|
||||||
|
addMessage(sessionId: string, message: Message): Promise<void>;
|
||||||
|
getMessages(sessionId: string, limit: number): Promise<Message[]>;
|
||||||
|
|
||||||
|
// Context management
|
||||||
|
getContext(sessionId: string): Promise<SessionContext>;
|
||||||
|
saveContext(sessionId: string, context: SessionContext): Promise<void>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Memory Store
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface MemoryStore {
|
||||||
|
// Vector storage
|
||||||
|
addEmbedding(key: string, embedding: number[]): Promise<void>;
|
||||||
|
searchEmbeddings(query: number[], k: number): Promise<SearchResult[]>;
|
||||||
|
|
||||||
|
// Key-value storage
|
||||||
|
set(key: string, value: unknown): Promise<void>;
|
||||||
|
get(key: string): Promise<unknown>;
|
||||||
|
delete(key: string): Promise<void>;
|
||||||
|
|
||||||
|
// Context retrieval
|
||||||
|
recall(query: string): Promise<MemoryResult[]>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Network Architecture
|
||||||
|
|
||||||
|
### Local Mode
|
||||||
|
|
||||||
|
```
|
||||||
|
┌───────────────────────┐
|
||||||
|
│ User Device │
|
||||||
|
│ ┌─────────────────┐ │
|
||||||
|
│ │ Gateway Server │ │
|
||||||
|
│ │ (localhost) │ │
|
||||||
|
│ └─────────────────┘ │
|
||||||
|
│ ↓ │
|
||||||
|
│ ┌─────────────────┐ │
|
||||||
|
│ │ Agent Runtime │ │
|
||||||
|
│ └─────────────────┘ │
|
||||||
|
│ ↓ │
|
||||||
|
│ ┌─────────────────┐ │
|
||||||
|
│ │ Channels │ │
|
||||||
|
│ └─────────────────┘ │
|
||||||
|
└───────────────────────┘
|
||||||
|
↓
|
||||||
|
External Services
|
||||||
|
(Anthropic, OpenAI)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Remote Gateway Mode
|
||||||
|
|
||||||
|
```
|
||||||
|
┌───────────────────────┐ ┌───────────────────────┐
|
||||||
|
│ Client Device │ │ Remote Server │
|
||||||
|
│ ┌─────────────────┐ │ WS │ ┌─────────────────┐ │
|
||||||
|
│ │ Gateway Client │──┼────────┼──│ Gateway Server │ │
|
||||||
|
│ │ (Control UI) │ │ │ │ (Headless) │ │
|
||||||
|
│ └─────────────────┘ │ │ └─────────────────┘ │
|
||||||
|
└───────────────────────┘ │ ↓ │
|
||||||
|
│ ┌─────────────────┐ │
|
||||||
|
│ │ Agent Runtime │ │
|
||||||
|
│ └─────────────────┘ │
|
||||||
|
│ ↓ │
|
||||||
|
│ ┌─────────────────┐ │
|
||||||
|
│ │ Channels │ │
|
||||||
|
│ └─────────────────┘ │
|
||||||
|
└───────────────────────┘
|
||||||
|
↓
|
||||||
|
External Services
|
||||||
|
```
|
||||||
|
|
||||||
|
### Service Discovery
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface DiscoveryService {
|
||||||
|
// mDNS advertisement
|
||||||
|
advertise(service: ServiceInfo): Promise<void>;
|
||||||
|
stopAdvertise(): Promise<void>;
|
||||||
|
|
||||||
|
// Discovery
|
||||||
|
discover(serviceType: string): Promise<ServiceInfo[]>;
|
||||||
|
watch(serviceType: string, handler: ServiceHandler): void;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scalability Considerations
|
||||||
|
|
||||||
|
### Vertical Scaling
|
||||||
|
- Single-user design (no multi-tenancy)
|
||||||
|
- Resource limits per tool
|
||||||
|
- Session cleanup policies
|
||||||
|
- Media file size limits
|
||||||
|
|
||||||
|
### Horizontal Scaling
|
||||||
|
- Not applicable (personal assistant)
|
||||||
|
- Remote Gateway for headless servers
|
||||||
|
- Multiple client devices connecting to single gateway
|
||||||
|
|
||||||
|
### Performance Optimizations
|
||||||
|
- Message chunking for large responses
|
||||||
|
- Lazy loading of plugins
|
||||||
|
- Caching of model responses
|
||||||
|
- Connection pooling for channels
|
||||||
|
- Parallel tool execution (where safe)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Reliability & Fault Tolerance
|
||||||
|
|
||||||
|
### Error Handling
|
||||||
|
- Graceful degradation when components fail
|
||||||
|
- Model failover on API errors
|
||||||
|
- Channel reconnection on disconnect
|
||||||
|
- Tool timeout handling
|
||||||
|
|
||||||
|
### Monitoring
|
||||||
|
- Gateway status endpoint
|
||||||
|
- Channel connection status
|
||||||
|
- Agent execution metrics
|
||||||
|
- Tool execution tracing
|
||||||
|
|
||||||
|
### Logging
|
||||||
|
- Structured logging with tslog
|
||||||
|
- Per-component log levels
|
||||||
|
- Configurable log output (file, console)
|
||||||
|
- Log rotation and retention
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Future Architecture Considerations
|
||||||
|
|
||||||
|
### Planned Enhancements
|
||||||
|
- Distributed tracing
|
||||||
|
- Performance profiling
|
||||||
|
- Advanced memory systems (RAG, embeddings)
|
||||||
|
- Multi-agent coordination
|
||||||
|
- Enhanced sandbox isolation
|
||||||
|
|
||||||
|
### Extensibility Points
|
||||||
|
- Custom model providers
|
||||||
|
- Custom channel protocols
|
||||||
|
- Custom tool implementations
|
||||||
|
- Custom memory backends
|
||||||
|
- Custom authentication providers
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**End of Architecture Documentation**
|
||||||
883
docs/COMPONENTS.md
Normal file
883
docs/COMPONENTS.md
Normal file
@ -0,0 +1,883 @@
|
|||||||
|
# Components Documentation
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
1. [Overview](#overview)
|
||||||
|
2. [Gateway Components](#gateway-components)
|
||||||
|
3. [Agent Runtime Components](#agent-runtime-components)
|
||||||
|
4. [Channel Components](#channel-components)
|
||||||
|
5. [Tool Components](#tool-components)
|
||||||
|
6. [Plugin System Components](#plugin-system-components)
|
||||||
|
7. [Configuration Components](#configuration-components)
|
||||||
|
8. [Storage Components](#storage-components)
|
||||||
|
9. [Utility Components](#utility-components)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This document provides detailed information about each component in the Jarvis system. Components are organized by layer and functionality.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Gateway Components
|
||||||
|
|
||||||
|
### Server (`src/gateway/server.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Main WebSocket server that handles all client connections and orchestration.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- Accept WebSocket connections from clients
|
||||||
|
- Route messages to appropriate handlers
|
||||||
|
- Manage active chat sessions
|
||||||
|
- Coordinate tool execution
|
||||||
|
- Handle cron jobs and webhooks
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class GatewayServer {
|
||||||
|
constructor(config: GatewayConfig);
|
||||||
|
|
||||||
|
async start(): Promise<void>;
|
||||||
|
async stop(): Promise<void>;
|
||||||
|
|
||||||
|
registerChat(chat: ChatSession): void;
|
||||||
|
unregisterChat(chatId: string): void;
|
||||||
|
|
||||||
|
async routeMessage(message: InboundMessage): Promise<void>;
|
||||||
|
|
||||||
|
getModelCatalog(): ModelCatalog;
|
||||||
|
getBrowserTool(): BrowserTool;
|
||||||
|
getDiscoveryService(): DiscoveryService;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Configuration**:
|
||||||
|
```yaml
|
||||||
|
gateway:
|
||||||
|
mode: local # 'local' or 'remote'
|
||||||
|
port: 18789
|
||||||
|
bind: loopback # 'loopback' or 'all'
|
||||||
|
verbose: true
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Chat Registry (`src/gateway/chat-registry.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Maintains registry of all active chat sessions.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- Register new chat sessions
|
||||||
|
- Track active sessions
|
||||||
|
- Clean up inactive sessions
|
||||||
|
- Provide session lookup
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class ChatRegistry {
|
||||||
|
register(chat: ChatSession): void;
|
||||||
|
unregister(chatId: string): void;
|
||||||
|
|
||||||
|
get(chatId: string): ChatSession | undefined;
|
||||||
|
getAll(): ChatSession[];
|
||||||
|
|
||||||
|
findByChannel(channel: string): ChatSession[];
|
||||||
|
findByUser(userId: string): ChatSession[];
|
||||||
|
|
||||||
|
cleanup(): void;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Data Structure**:
|
||||||
|
```typescript
|
||||||
|
interface ChatSession {
|
||||||
|
id: string;
|
||||||
|
channel: string;
|
||||||
|
userId: string;
|
||||||
|
groupId?: string;
|
||||||
|
|
||||||
|
agent: AgentSession;
|
||||||
|
context: SessionContext;
|
||||||
|
|
||||||
|
createdAt: number;
|
||||||
|
lastActivityAt: number;
|
||||||
|
|
||||||
|
metadata: Record<string, unknown>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Model Catalog (`src/gateway/model-catalog.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Maintains catalog of available AI models and their configurations.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- List available models
|
||||||
|
- Provide model configurations
|
||||||
|
- Handle model authentication
|
||||||
|
- Track model usage and costs
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class ModelCatalog {
|
||||||
|
getAvailableModels(): ModelInfo[];
|
||||||
|
getModel(modelId: string): ModelInfo | undefined;
|
||||||
|
|
||||||
|
getAuthProfile(modelId: string): AuthProfile;
|
||||||
|
setAuthProfile(modelId: string, profile: AuthProfile): void;
|
||||||
|
|
||||||
|
getUsageStats(modelId: string): UsageStats;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Model Info Structure**:
|
||||||
|
```typescript
|
||||||
|
interface ModelInfo {
|
||||||
|
id: string;
|
||||||
|
name: string;
|
||||||
|
provider: 'anthropic' | 'openai' | 'google' | 'bedrock' | 'ollama';
|
||||||
|
|
||||||
|
capabilities: {
|
||||||
|
vision: boolean;
|
||||||
|
tools: boolean;
|
||||||
|
streaming: boolean;
|
||||||
|
};
|
||||||
|
|
||||||
|
limits: {
|
||||||
|
maxTokens: number;
|
||||||
|
contextWindow: number;
|
||||||
|
rateLimit: RateLimit;
|
||||||
|
};
|
||||||
|
|
||||||
|
pricing: {
|
||||||
|
inputCostPer1k: number;
|
||||||
|
outputCostPer1k: number;
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Browser Tool (`src/gateway/browser-tool.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Shared browser automation tool using Playwright.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- Launch and manage browser instances
|
||||||
|
- Execute browser automation tasks
|
||||||
|
- Capture screenshots and PDFs
|
||||||
|
- Handle browser profiles and cookies
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class BrowserTool {
|
||||||
|
async launch(options: LaunchOptions): Promise<BrowserInstance>;
|
||||||
|
async close(instanceId: string): Promise<void>;
|
||||||
|
|
||||||
|
async navigate(instanceId: string, url: string): Promise<void>;
|
||||||
|
async screenshot(instanceId: string, options: ScreenshotOptions): Promise<Buffer>;
|
||||||
|
async pdf(instanceId: string, options: PDFOptions): Promise<Buffer>;
|
||||||
|
|
||||||
|
async click(instanceId: string, selector: string): Promise<void>;
|
||||||
|
async type(instanceId: string, selector: string, text: string): Promise<void>;
|
||||||
|
async fill(instanceId: string, selector: string, value: string): Promise<void>;
|
||||||
|
|
||||||
|
async evaluate(instanceId: string, script: string): Promise<unknown>;
|
||||||
|
async snapshot(instanceId: string): Promise<PageSnapshot>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Configuration**:
|
||||||
|
```yaml
|
||||||
|
tools:
|
||||||
|
browser:
|
||||||
|
enabled: true
|
||||||
|
headless: true
|
||||||
|
timeout: 30000
|
||||||
|
viewport:
|
||||||
|
width: 1280
|
||||||
|
height: 720
|
||||||
|
profiles:
|
||||||
|
- name: default
|
||||||
|
cookies: []
|
||||||
|
localStorage: {}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Discovery Service (`src/gateway/discovery.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Service discovery using mDNS for local network.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- Advertise gateway service
|
||||||
|
- Discover other gateways
|
||||||
|
- Handle service announcements
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class DiscoveryService {
|
||||||
|
async advertise(service: ServiceInfo): Promise<void>;
|
||||||
|
async stopAdvertise(): Promise<void>;
|
||||||
|
|
||||||
|
async discover(serviceType: string): Promise<ServiceInfo[]>;
|
||||||
|
watch(serviceType: string, handler: ServiceHandler): void;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Agent Runtime Components
|
||||||
|
|
||||||
|
### Pi Agent Runner (`src/agents/pi-embedded-runner.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Execute AI models in RPC mode with tool streaming.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- Execute model requests
|
||||||
|
- Stream tool calls and results
|
||||||
|
- Handle model authentication
|
||||||
|
- Manage failover on errors
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class PiAgentRunner {
|
||||||
|
constructor(config: AgentConfig);
|
||||||
|
|
||||||
|
async* execute(
|
||||||
|
session: SessionContext,
|
||||||
|
message: string
|
||||||
|
): AsyncGenerator<AgentEvent>;
|
||||||
|
|
||||||
|
async executeTools(
|
||||||
|
session: SessionContext,
|
||||||
|
tools: ToolCall[]
|
||||||
|
): Promise<ToolResult[]>;
|
||||||
|
|
||||||
|
async streamResponse(
|
||||||
|
session: SessionContext
|
||||||
|
): AsyncGenerator<ResponseChunk>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Event Types**:
|
||||||
|
```typescript
|
||||||
|
type AgentEvent =
|
||||||
|
| { type: 'tool_call', data: ToolCall }
|
||||||
|
| { type: 'tool_result', data: ToolResult }
|
||||||
|
| { type: 'text_chunk', data: string }
|
||||||
|
| { type: 'thinking', data: string }
|
||||||
|
| { type: 'error', data: Error };
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Session Manager (`src/agents/session-manager.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Manage agent session lifecycle and context.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- Create and destroy sessions
|
||||||
|
- Load and save session context
|
||||||
|
- Manage message history
|
||||||
|
- Handle session isolation
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class SessionManager {
|
||||||
|
createSession(config: SessionConfig): AgentSession;
|
||||||
|
destroySession(sessionId: string): void;
|
||||||
|
|
||||||
|
getSession(sessionId: string): AgentSession | undefined;
|
||||||
|
getAllSessions(): AgentSession[];
|
||||||
|
|
||||||
|
async loadContext(sessionId: string): Promise<SessionContext>;
|
||||||
|
async saveContext(sessionId: string, context: SessionContext): Promise<void>;
|
||||||
|
|
||||||
|
async addMessage(sessionId: string, message: Message): Promise<void>;
|
||||||
|
async getMessages(sessionId: string, limit: number): Promise<Message[]>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Session Context**:
|
||||||
|
```typescript
|
||||||
|
interface SessionContext {
|
||||||
|
sessionId: string;
|
||||||
|
chatId: string;
|
||||||
|
channel: string;
|
||||||
|
|
||||||
|
messages: Message[];
|
||||||
|
maxTokens: number;
|
||||||
|
|
||||||
|
model: string;
|
||||||
|
temperature: number;
|
||||||
|
thinkingMode: 'low' | 'high' | 'always';
|
||||||
|
|
||||||
|
availableTools: Tool[];
|
||||||
|
toolResults: ToolResult[];
|
||||||
|
|
||||||
|
memory: MemoryStore;
|
||||||
|
skills: Skill[];
|
||||||
|
|
||||||
|
metadata: Record<string, unknown>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Tool Registry (`src/agents/tool-registry.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Registry of available tools for agents.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- Register tools
|
||||||
|
- Validate tool schemas
|
||||||
|
- Execute tool calls
|
||||||
|
- Track tool usage
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class ToolRegistry {
|
||||||
|
register(tool: Tool): void;
|
||||||
|
unregister(toolName: string): void;
|
||||||
|
|
||||||
|
get(toolName: string): Tool | undefined;
|
||||||
|
getAll(): Tool[];
|
||||||
|
|
||||||
|
async execute(
|
||||||
|
toolName: string,
|
||||||
|
params: unknown,
|
||||||
|
context: ToolContext
|
||||||
|
): Promise<ToolResult>;
|
||||||
|
|
||||||
|
validateParams(toolName: string, params: unknown): boolean;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tool Interface**:
|
||||||
|
```typescript
|
||||||
|
interface Tool {
|
||||||
|
name: string;
|
||||||
|
description: string;
|
||||||
|
schema: JSONSchema;
|
||||||
|
|
||||||
|
execute(params: unknown, context: ToolContext): Promise<ToolResult>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Model Auth (`src/agents/model-auth.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Handle model authentication and token management.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- Store API keys and OAuth tokens
|
||||||
|
- Refresh expired tokens
|
||||||
|
- Rotate auth profiles on failure
|
||||||
|
- Secure credential storage
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class ModelAuth {
|
||||||
|
async getAuthProfile(modelId: string): Promise<AuthProfile>;
|
||||||
|
async setAuthProfile(modelId: string, profile: AuthProfile): Promise<void>;
|
||||||
|
|
||||||
|
async refreshToken(modelId: string): Promise<void>;
|
||||||
|
async rotateProfile(modelId: string): Promise<void>;
|
||||||
|
|
||||||
|
async validateCredentials(modelId: string): Promise<boolean>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Auth Profile**:
|
||||||
|
```typescript
|
||||||
|
interface AuthProfile {
|
||||||
|
type: 'api_key' | 'oauth';
|
||||||
|
|
||||||
|
// For API keys
|
||||||
|
apiKey?: string;
|
||||||
|
|
||||||
|
// For OAuth
|
||||||
|
accessToken?: string;
|
||||||
|
refreshToken?: string;
|
||||||
|
expiresAt?: number;
|
||||||
|
|
||||||
|
metadata: Record<string, unknown>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Channel Components
|
||||||
|
|
||||||
|
### Base Channel Interface (`src/channels/base.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Common interface for all channel implementations.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- Define channel lifecycle
|
||||||
|
- Normalize messages
|
||||||
|
- Handle errors gracefully
|
||||||
|
|
||||||
|
**Interface**:
|
||||||
|
```typescript
|
||||||
|
interface Channel {
|
||||||
|
name: string;
|
||||||
|
type: ChannelType;
|
||||||
|
|
||||||
|
// Lifecycle
|
||||||
|
init(config: ChannelConfig): Promise<void>;
|
||||||
|
start(): Promise<void>;
|
||||||
|
stop(): Promise<void>;
|
||||||
|
|
||||||
|
// Messaging
|
||||||
|
send(message: OutboundMessage): Promise<void>;
|
||||||
|
receive(handler: MessageHandler): void;
|
||||||
|
|
||||||
|
// Status
|
||||||
|
getStatus(): ChannelStatus;
|
||||||
|
getConnections(): Connection[];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WhatsApp Channel (`src/whatsapp/`)
|
||||||
|
|
||||||
|
**Purpose**: WhatsApp integration using Baileys library.
|
||||||
|
|
||||||
|
**Key Files**:
|
||||||
|
- `bot.ts` - Main bot implementation
|
||||||
|
- `send.ts` - Message sending
|
||||||
|
- `markdown.ts` - Markdown to WhatsApp formatting
|
||||||
|
- `qr.ts` - QR code pairing
|
||||||
|
|
||||||
|
**Configuration**:
|
||||||
|
```yaml
|
||||||
|
channels:
|
||||||
|
whatsapp:
|
||||||
|
enabled: true
|
||||||
|
pairing: code
|
||||||
|
allowlist:
|
||||||
|
- "+1234567890"
|
||||||
|
session: main
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Telegram Channel (`src/telegram/`)
|
||||||
|
|
||||||
|
**Purpose**: Telegram integration using grammY library.
|
||||||
|
|
||||||
|
**Key Files**:
|
||||||
|
- `bot.ts` - Main bot implementation
|
||||||
|
- `handlers.ts` - Message handlers
|
||||||
|
- `markdown.ts` - Markdown to Telegram formatting
|
||||||
|
- `keyboard.ts` - Inline keyboard support
|
||||||
|
|
||||||
|
**Configuration**:
|
||||||
|
```yaml
|
||||||
|
channels:
|
||||||
|
telegram:
|
||||||
|
enabled: true
|
||||||
|
bot_token: "${TELEGRAM_BOT_TOKEN}"
|
||||||
|
allowlist:
|
||||||
|
- "username1"
|
||||||
|
- "username2"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Signal Channel (`src/signal/`)
|
||||||
|
|
||||||
|
**Purpose**: Signal integration using signal-cli.
|
||||||
|
|
||||||
|
**Key Files**:
|
||||||
|
- `bot.ts` - Main bot implementation
|
||||||
|
- `cli.ts` - signal-cli wrapper
|
||||||
|
- `send.ts` - Message sending
|
||||||
|
|
||||||
|
**Configuration**:
|
||||||
|
```yaml
|
||||||
|
channels:
|
||||||
|
signal:
|
||||||
|
enabled: true
|
||||||
|
phone: "+1234567890"
|
||||||
|
allowlist:
|
||||||
|
- "+0987654321"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Discord Channel (`src/discord/`)
|
||||||
|
|
||||||
|
**Purpose**: Discord integration using discord.js.
|
||||||
|
|
||||||
|
**Key Files**:
|
||||||
|
- `bot.ts` - Main bot implementation
|
||||||
|
- `handlers.ts` - Event handlers
|
||||||
|
- `markdown.ts` - Markdown to Discord formatting
|
||||||
|
- `embeds.ts` - Rich embed support
|
||||||
|
|
||||||
|
**Configuration**:
|
||||||
|
```yaml
|
||||||
|
channels:
|
||||||
|
discord:
|
||||||
|
enabled: true
|
||||||
|
bot_token: "${DISCORD_BOT_TOKEN}"
|
||||||
|
dm:
|
||||||
|
policy: pairing
|
||||||
|
allowFrom: []
|
||||||
|
guilds:
|
||||||
|
- guild_id: "123456789"
|
||||||
|
channels: ["general", "bot-commands"]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Slack Channel (`src/slack/`)
|
||||||
|
|
||||||
|
**Purpose**: Slack integration using Bolt framework.
|
||||||
|
|
||||||
|
**Key Files**:
|
||||||
|
- `bot.ts` - Main bot implementation
|
||||||
|
- `handlers.ts` - Event handlers
|
||||||
|
- `blocks.ts` - Block Kit formatting
|
||||||
|
|
||||||
|
**Configuration**:
|
||||||
|
```yaml
|
||||||
|
channels:
|
||||||
|
slack:
|
||||||
|
enabled: true
|
||||||
|
bot_token: "${SLACK_BOT_TOKEN}"
|
||||||
|
signing_secret: "${SLACK_SIGNING_SECRET}"
|
||||||
|
dm:
|
||||||
|
policy: pairing
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tool Components
|
||||||
|
|
||||||
|
### Browser Tool (`src/browser/`)
|
||||||
|
|
||||||
|
**Purpose**: Web automation using Playwright.
|
||||||
|
|
||||||
|
**Key Files**:
|
||||||
|
- `browser-tool.ts` - Main tool implementation
|
||||||
|
- `playwright-bridge.ts` - Playwright wrapper
|
||||||
|
- `snapshot.ts` - Page snapshot generation
|
||||||
|
- `profiles.ts` - Browser profile management
|
||||||
|
|
||||||
|
**Tool Schema**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
name: "browser",
|
||||||
|
description: "Automate web browsing",
|
||||||
|
schema: {
|
||||||
|
action: "navigate" | "click" | "type" | "screenshot",
|
||||||
|
url?: string,
|
||||||
|
selector?: string,
|
||||||
|
text?: string
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Canvas Tool (`src/canvas-host/`)
|
||||||
|
|
||||||
|
**Purpose**: Visual workspace with A2UI framework.
|
||||||
|
|
||||||
|
**Key Files**:
|
||||||
|
- `index.ts` - Main canvas implementation
|
||||||
|
- `a2ui/` - A2UI framework bundles
|
||||||
|
- `renderer.ts` - DOM rendering
|
||||||
|
- `websocket.ts` - Real-time updates
|
||||||
|
|
||||||
|
**Tool Schema**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
name: "canvas",
|
||||||
|
description: "Create visual workspace",
|
||||||
|
schema: {
|
||||||
|
action: "create" | "update" | "render",
|
||||||
|
content?: string,
|
||||||
|
layout?: string
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Bash Tool (`src/process/`)
|
||||||
|
|
||||||
|
**Purpose**: Execute shell commands safely.
|
||||||
|
|
||||||
|
**Key Files**:
|
||||||
|
- `exec.ts` - Command execution
|
||||||
|
- `spawn-utils.ts` - Process spawning utilities
|
||||||
|
- `command-queue.ts` - Command queuing
|
||||||
|
|
||||||
|
**Tool Schema**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
name: "bash",
|
||||||
|
description: "Execute shell commands",
|
||||||
|
schema: {
|
||||||
|
command: string,
|
||||||
|
timeout?: number,
|
||||||
|
cwd?: string,
|
||||||
|
env?: Record<string, string>
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Memory Tool (`src/memory/`)
|
||||||
|
|
||||||
|
**Purpose**: Store and retrieve contextual information.
|
||||||
|
|
||||||
|
**Key Files**:
|
||||||
|
- `index.ts` - Main memory implementation
|
||||||
|
- `vector-store.ts` - Vector embeddings
|
||||||
|
- `cache.ts` - Caching layer
|
||||||
|
|
||||||
|
**Tool Schema**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
name: "memory",
|
||||||
|
description: "Store and recall information",
|
||||||
|
schema: {
|
||||||
|
action: "store" | "recall" | "search",
|
||||||
|
key?: string,
|
||||||
|
value?: unknown,
|
||||||
|
query?: string
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Plugin System Components
|
||||||
|
|
||||||
|
### Plugin Discovery (`src/plugins/discovery.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Auto-detect and validate plugins.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- Scan plugin directories
|
||||||
|
- Validate manifests
|
||||||
|
- Check dependencies
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class PluginDiscovery {
|
||||||
|
async discoverPlugins(): Promise<PluginManifest[]>;
|
||||||
|
async validateManifest(manifest: PluginManifest): Promise<boolean>;
|
||||||
|
async checkDependencies(manifest: PluginManifest): Promise<boolean>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Plugin Loader (`src/plugins/loader.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Load and initialize plugins.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- Load plugin modules
|
||||||
|
- Initialize plugins
|
||||||
|
- Register hooks
|
||||||
|
- Inject services
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class PluginLoader {
|
||||||
|
async load(manifest: PluginManifest): Promise<Plugin>;
|
||||||
|
async init(plugin: Plugin): Promise<void>;
|
||||||
|
async start(plugin: Plugin): Promise<void>;
|
||||||
|
async stop(plugin: Plugin): Promise<void>;
|
||||||
|
|
||||||
|
registerHooks(plugin: Plugin): void;
|
||||||
|
injectServices(plugin: Plugin, services: PluginServices): void;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Plugin Services (`src/plugins/services.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Provide services to plugins.
|
||||||
|
|
||||||
|
**Services**:
|
||||||
|
```typescript
|
||||||
|
interface PluginServices {
|
||||||
|
gateway: GatewayClient;
|
||||||
|
config: ConfigProvider;
|
||||||
|
logger: Logger;
|
||||||
|
http: HttpClient;
|
||||||
|
storage: StorageProvider;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuration Components
|
||||||
|
|
||||||
|
### Config Loader (`src/config/index.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Load and validate configuration.
|
||||||
|
|
||||||
|
**Responsibilities**:
|
||||||
|
- Load YAML configuration
|
||||||
|
- Validate with Zod schemas
|
||||||
|
- Merge environment variables
|
||||||
|
- Handle migrations
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class ConfigLoader {
|
||||||
|
async load(path: string): Promise<Config>;
|
||||||
|
async validate(config: unknown): Promise<Config>;
|
||||||
|
async save(path: string, config: Config): Promise<void>;
|
||||||
|
|
||||||
|
merge(configs: Partial<Config>[]): Config;
|
||||||
|
migrate(oldConfig: unknown): Config;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Config Schema (`src/config/schema.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Zod schemas for configuration validation.
|
||||||
|
|
||||||
|
**Schemas**:
|
||||||
|
```typescript
|
||||||
|
const ConfigSchema = z.object({
|
||||||
|
gateway: GatewayConfigSchema,
|
||||||
|
agents: AgentsConfigSchema,
|
||||||
|
channels: ChannelsConfigSchema,
|
||||||
|
tools: ToolsConfigSchema,
|
||||||
|
sandbox: SandboxConfigSchema,
|
||||||
|
plugins: PluginsConfigSchema,
|
||||||
|
skills: SkillsConfigSchema,
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Path Manager (`src/config/paths.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Manage system paths.
|
||||||
|
|
||||||
|
**Paths**:
|
||||||
|
```typescript
|
||||||
|
class PathManager {
|
||||||
|
getConfigDir(): string;
|
||||||
|
getCredentialsDir(): string;
|
||||||
|
getSessionsDir(): string;
|
||||||
|
getMediaDir(): string;
|
||||||
|
getMemoryDir(): string;
|
||||||
|
getLogsDir(): string;
|
||||||
|
|
||||||
|
resolve(relativePath: string): string;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Storage Components
|
||||||
|
|
||||||
|
### Session Store (`src/sessions/`)
|
||||||
|
|
||||||
|
**Purpose**: Persist session data.
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class SessionStore {
|
||||||
|
async create(session: SessionContext): Promise<void>;
|
||||||
|
async read(sessionId: string): Promise<SessionContext>;
|
||||||
|
async update(session: SessionContext): Promise<void>;
|
||||||
|
async delete(sessionId: string): Promise<void>;
|
||||||
|
|
||||||
|
async addMessage(sessionId: string, message: Message): Promise<void>;
|
||||||
|
async getMessages(sessionId: string, limit: number): Promise<Message[]>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Memory Store (`src/memory/`)
|
||||||
|
|
||||||
|
**Purpose**: Vector storage for contextual memory.
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class MemoryStore {
|
||||||
|
async addEmbedding(key: string, embedding: number[]): Promise<void>;
|
||||||
|
async searchEmbeddings(query: number[], k: number): Promise<SearchResult[]>;
|
||||||
|
|
||||||
|
async set(key: string, value: unknown): Promise<void>;
|
||||||
|
async get(key: string): Promise<unknown>;
|
||||||
|
async delete(key: string): Promise<void>;
|
||||||
|
|
||||||
|
async recall(query: string): Promise<MemoryResult[]>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Utility Components
|
||||||
|
|
||||||
|
### Logger (`src/logger.ts`)
|
||||||
|
|
||||||
|
**Purpose**: Structured logging with tslog.
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class Logger {
|
||||||
|
debug(message: string, ...args: unknown[]): void;
|
||||||
|
info(message: string, ...args: unknown[]): void;
|
||||||
|
warn(message: string, ...args: unknown[]): void;
|
||||||
|
error(message: string, ...args: unknown[]): void;
|
||||||
|
|
||||||
|
child(name: string): Logger;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Terminal Utils (`src/terminal/`)
|
||||||
|
|
||||||
|
**Purpose**: Terminal UI utilities.
|
||||||
|
|
||||||
|
**Key Files**:
|
||||||
|
- `palette.ts` - Color palette
|
||||||
|
- `table.ts` - Table formatting
|
||||||
|
- `progress.ts` - Progress bars
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Markdown Utils (`src/markdown/`)
|
||||||
|
|
||||||
|
**Purpose**: Markdown parsing and rendering.
|
||||||
|
|
||||||
|
**Key APIs**:
|
||||||
|
```typescript
|
||||||
|
class MarkdownUtils {
|
||||||
|
parse(markdown: string): MarkdownNode[];
|
||||||
|
render(nodes: MarkdownNode[]): string;
|
||||||
|
|
||||||
|
toHTML(markdown: string): string;
|
||||||
|
toPlainText(markdown: string): string;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**End of Components Documentation**
|
||||||
356
docs/INDEX.md
Normal file
356
docs/INDEX.md
Normal file
@ -0,0 +1,356 @@
|
|||||||
|
# Índice de Documentación de Jarvis
|
||||||
|
|
||||||
|
## 📚 Documentación Completa del Proyecto
|
||||||
|
|
||||||
|
Este directorio contiene toda la documentación del proyecto Jarvis, un asistente personal de IA que se ejecuta en tus propios dispositivos.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Documentos Principales
|
||||||
|
|
||||||
|
### [README-ES.md](README-ES.md)
|
||||||
|
**Documentación completa en español**
|
||||||
|
|
||||||
|
Incluye:
|
||||||
|
- Visión general del proyecto
|
||||||
|
- ¿Qué es Jarvis?
|
||||||
|
- Arquitectura del sistema
|
||||||
|
- Componentes principales
|
||||||
|
- Canales de mensajería soportados
|
||||||
|
- Tecnologías utilizadas
|
||||||
|
- Sistema de plugins
|
||||||
|
- Configuración y despliegue
|
||||||
|
- Desarrollo
|
||||||
|
- Estructura de directorios
|
||||||
|
|
||||||
|
📖 **Recomendado como punto de partida** para entender todo el proyecto.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### [ARCHITECTURE.md](ARCHITECTURE.md)
|
||||||
|
**Documentación técnica de arquitectura**
|
||||||
|
|
||||||
|
Incluye:
|
||||||
|
- Arquitectura de alto nivel
|
||||||
|
- Componentes del sistema
|
||||||
|
- Flujo de datos
|
||||||
|
- Enrutamiento de mensajes
|
||||||
|
- Modelo de ejecución de agentes
|
||||||
|
- Arquitectura de plugins
|
||||||
|
- Modelo de seguridad
|
||||||
|
- Almacenamiento y persistencia
|
||||||
|
- Arquitectura de red
|
||||||
|
|
||||||
|
📖 **Recomendado para desarrolladores** que necesitan entender la arquitectura técnica.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### [COMPONENTS.md](COMPONENTS.md)
|
||||||
|
**Documentación de componentes individuales**
|
||||||
|
|
||||||
|
Incluye:
|
||||||
|
- Componentes del Gateway
|
||||||
|
- Componentes del Runtime de Agente
|
||||||
|
- Componentes de Canales
|
||||||
|
- Componentes de Herramientas
|
||||||
|
- Componentes del Sistema de Plugins
|
||||||
|
- Componentes de Configuración
|
||||||
|
- Componentes de Almacenamiento
|
||||||
|
- Componentes de Utilidades
|
||||||
|
|
||||||
|
📖 **Recomendado para desarrolladores** que trabajan en componentes específicos.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📖 Documentación por Categoría
|
||||||
|
|
||||||
|
### 🎯 Inicio Rápido
|
||||||
|
|
||||||
|
| Documento | Descripción |
|
||||||
|
|-----------|-------------|
|
||||||
|
| [start/](start/) | Guías de inicio rápido y tutoriales |
|
||||||
|
| [install/](install/) | Guías de instalación paso a paso |
|
||||||
|
| [Getting Started](start/) | Guía para principiantes |
|
||||||
|
|
||||||
|
### ⚙️ Configuración
|
||||||
|
|
||||||
|
| Documento | Descripción |
|
||||||
|
|-----------|-------------|
|
||||||
|
| [README-ES.md#configuración-y-despliegue](README-ES.md#configuración-y-despliegue) | Guía completa de configuración |
|
||||||
|
| [gateway/](gateway/) | Configuración del Gateway |
|
||||||
|
| [environment.md](environment.md) | Variables de entorno |
|
||||||
|
|
||||||
|
### 💬 Canales
|
||||||
|
|
||||||
|
| Documento | Descripción |
|
||||||
|
|-----------|-------------|
|
||||||
|
| [channels/](channels/) | Documentación de todos los canales |
|
||||||
|
| [README-ES.md#canales-de-mensajería](README-ES.md#canales-de-mensajería) | Lista de canales soportados |
|
||||||
|
|
||||||
|
### 🔐 Seguridad
|
||||||
|
|
||||||
|
| Documento | Descripción |
|
||||||
|
|-----------|-------------|
|
||||||
|
| [security/](security/) | Guías de seguridad |
|
||||||
|
| [ARCHITECTURE.md#security-model](ARCHITECTURE.md#security-model) | Modelo de seguridad |
|
||||||
|
|
||||||
|
### 🛠️ Desarrollo
|
||||||
|
|
||||||
|
| Documento | Descripción |
|
||||||
|
|-----------|-------------|
|
||||||
|
| [README-ES.md#desarrollo](README-ES.md#desarrollo) | Guía de desarrollo |
|
||||||
|
| [testing.md](testing.md) | Guías de testing |
|
||||||
|
| [debugging.md](debugging.md) | Guías de depuración |
|
||||||
|
|
||||||
|
### 🔌 Plugins
|
||||||
|
|
||||||
|
| Documento | Descripción |
|
||||||
|
|-----------|-------------|
|
||||||
|
| [plugins/](plugins/) | Documentación de plugins |
|
||||||
|
| [ARCHITECTURE.md#plugin-architecture](ARCHITECTURE.md#plugin-architecture) | Arquitectura de plugins |
|
||||||
|
|
||||||
|
### 🤖 Conceptos de IA
|
||||||
|
|
||||||
|
| Documento | Descripción |
|
||||||
|
|-----------|-------------|
|
||||||
|
| [concepts/](concepts/) | Conceptos fundamentales |
|
||||||
|
| [README-ES.md#tecnologías-utilizadas](README-ES.md#tecnologías-utilizadas) | Modelos IA soportados |
|
||||||
|
|
||||||
|
### 🖥️ Plataformas
|
||||||
|
|
||||||
|
| Documento | Descripción |
|
||||||
|
|-----------|-------------|
|
||||||
|
| [platforms/](platforms/) | Guías específicas de plataforma |
|
||||||
|
| macOS | Documentación de macOS |
|
||||||
|
| iOS | Documentación de iOS |
|
||||||
|
| Android | Documentación de Android |
|
||||||
|
|
||||||
|
### 📚 Referencia
|
||||||
|
|
||||||
|
| Documento | Descripción |
|
||||||
|
|-----------|-------------|
|
||||||
|
| [reference/](reference/) | Documentación de referencia |
|
||||||
|
| [cli/](cli/) | Referencia de comandos CLI |
|
||||||
|
| [tools/](tools/) | Referencia de herramientas |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🗺️ Mapa de Navegación
|
||||||
|
|
||||||
|
### Para Nuevos Usuarios
|
||||||
|
|
||||||
|
1. **Empezar aquí**: [README-ES.md](README-ES.md) - Visión general completa
|
||||||
|
2. **Instalar**: [install/](install/) - Guías de instalación
|
||||||
|
3. **Configurar**: [README-ES.md#configuración-y-despliegue](README-ES.md#configuración-y-despliegue)
|
||||||
|
4. **Usar**: [start/](start/) - Guías de uso básico
|
||||||
|
|
||||||
|
### Para Desarrolladores
|
||||||
|
|
||||||
|
1. **Arquitectura**: [ARCHITECTURE.md](ARCHITECTURE.md) - Entender el sistema
|
||||||
|
2. **Componentes**: [COMPONENTS.md](COMPONENTS.md) - Componentes individuales
|
||||||
|
3. **Desarrollo**: [README-ES.md#desarrollo](README-ES.md#desarrollo) - Setup de desarrollo
|
||||||
|
4. **Testing**: [testing.md](testing.md) - Guías de testing
|
||||||
|
|
||||||
|
### Para Crear Plugins
|
||||||
|
|
||||||
|
1. **Sistema de Plugins**: [ARCHITECTURE.md#plugin-architecture](ARCHITECTURE.md#plugin-architecture)
|
||||||
|
2. **Ejemplos**: [extensions/](../extensions/) - Plugins existentes
|
||||||
|
3. **Plugin SDK**: Ver código en `src/plugin-sdk/`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Estructura de Documentación
|
||||||
|
|
||||||
|
```
|
||||||
|
docs/
|
||||||
|
├── README-ES.md # 📖 Documentación completa en español
|
||||||
|
├── ARCHITECTURE.md # 🏗️ Arquitectura técnica
|
||||||
|
├── COMPONENTS.md # 🔧 Componentes individuales
|
||||||
|
├── INDEX.md # 📋 Este archivo (índice)
|
||||||
|
│
|
||||||
|
├── start/ # 🚀 Inicio rápido
|
||||||
|
│ ├── getting-started.md
|
||||||
|
│ └── wizard.md
|
||||||
|
│
|
||||||
|
├── install/ # 📦 Instalación
|
||||||
|
│ ├── docker.md
|
||||||
|
│ └── updating.md
|
||||||
|
│
|
||||||
|
├── channels/ # 💬 Canales
|
||||||
|
│ ├── whatsapp.md
|
||||||
|
│ ├── telegram.md
|
||||||
|
│ ├── discord.md
|
||||||
|
│ └── ...
|
||||||
|
│
|
||||||
|
├── gateway/ # 🌐 Gateway
|
||||||
|
│ ├── configuration.md
|
||||||
|
│ ├── security.md
|
||||||
|
│ └── doctor.md
|
||||||
|
│
|
||||||
|
├── concepts/ # 💡 Conceptos
|
||||||
|
│ ├── models.md
|
||||||
|
│ ├── session.md
|
||||||
|
│ ├── groups.md
|
||||||
|
│ └── agent.md
|
||||||
|
│
|
||||||
|
├── cli/ # 💻 CLI
|
||||||
|
│ └── commands.md
|
||||||
|
│
|
||||||
|
├── tools/ # 🛠️ Herramientas
|
||||||
|
│ ├── browser.md
|
||||||
|
│ ├── canvas.md
|
||||||
|
│ └── skills.md
|
||||||
|
│
|
||||||
|
├── plugins/ # 🔌 Plugins
|
||||||
|
│ └── development.md
|
||||||
|
│
|
||||||
|
├── security/ # 🔐 Seguridad
|
||||||
|
│ └── best-practices.md
|
||||||
|
│
|
||||||
|
├── platforms/ # 🖥️ Plataformas
|
||||||
|
│ ├── macos/
|
||||||
|
│ ├── ios/
|
||||||
|
│ ├── android/
|
||||||
|
│ └── linux/
|
||||||
|
│
|
||||||
|
├── reference/ # 📚 Referencia
|
||||||
|
│ └── RELEASING.md
|
||||||
|
│
|
||||||
|
├── automation/ # 🤖 Automatización
|
||||||
|
├── debug/ # 🐛 Depuración
|
||||||
|
├── diagnostics/ # 🔍 Diagnósticos
|
||||||
|
├── nodes/ # 📡 Nodos
|
||||||
|
├── providers/ # 🏢 Proveedores
|
||||||
|
├── web/ # 🌐 Web UI
|
||||||
|
│
|
||||||
|
├── assets/ # 🎨 Assets
|
||||||
|
├── images/ # 🖼️ Imágenes
|
||||||
|
└── _layouts/ # 📄 Layouts
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔍 Búsqueda por Tema
|
||||||
|
|
||||||
|
### Instalación y Configuración
|
||||||
|
- [Instalación](install/)
|
||||||
|
- [Configuración](README-ES.md#configuración-y-despliegue)
|
||||||
|
- [Variables de entorno](environment.md)
|
||||||
|
- [Docker](install/docker.md)
|
||||||
|
|
||||||
|
### Canales de Mensajería
|
||||||
|
- [Todos los canales](channels/)
|
||||||
|
- [WhatsApp](channels/whatsapp.md)
|
||||||
|
- [Telegram](channels/telegram.md)
|
||||||
|
- [Discord](channels/discord.md)
|
||||||
|
- [Signal](channels/signal.md)
|
||||||
|
- [Slack](channels/slack.md)
|
||||||
|
|
||||||
|
### Desarrollo
|
||||||
|
- [Setup de desarrollo](README-ES.md#desarrollo)
|
||||||
|
- [Arquitectura](ARCHITECTURE.md)
|
||||||
|
- [Componentes](COMPONENTS.md)
|
||||||
|
- [Testing](testing.md)
|
||||||
|
- [Debugging](debugging.md)
|
||||||
|
|
||||||
|
### Plugins y Extensiones
|
||||||
|
- [Sistema de plugins](ARCHITECTURE.md#plugin-architecture)
|
||||||
|
- [Desarrollo de plugins](plugins/)
|
||||||
|
- [Plugins existentes](../extensions/)
|
||||||
|
|
||||||
|
### Herramientas
|
||||||
|
- [Browser Tool](tools/browser.md)
|
||||||
|
- [Canvas Tool](tools/canvas.md)
|
||||||
|
- [Skills](tools/skills.md)
|
||||||
|
|
||||||
|
### Seguridad
|
||||||
|
- [Modelo de seguridad](ARCHITECTURE.md#security-model)
|
||||||
|
- [Mejores prácticas](security/best-practices.md)
|
||||||
|
- [Gateway security](gateway/security.md)
|
||||||
|
|
||||||
|
### Plataformas
|
||||||
|
- [macOS](platforms/macos/)
|
||||||
|
- [iOS](platforms/ios/)
|
||||||
|
- [Android](platforms/android/)
|
||||||
|
- [Linux](platforms/linux/)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Diagramas
|
||||||
|
|
||||||
|
Los documentos incluyen varios diagramas ASCII para visualizar:
|
||||||
|
|
||||||
|
- **Arquitectura del Sistema**: [ARCHITECTURE.md](ARCHITECTURE.md#high-level-architecture)
|
||||||
|
- **Flujo de Datos**: [ARCHITECTURE.md](ARCHITECTURE.md#data-flow)
|
||||||
|
- **Flujo de Mensajes**: [README-ES.md](README-ES.md#arquitectura-del-sistema)
|
||||||
|
- **Diagrama de Uso**: Ver README mejorado en raíz del proyecto
|
||||||
|
- **Diagrama de Configuración**: Ver README mejorado en raíz del proyecto
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔗 Enlaces Útiles
|
||||||
|
|
||||||
|
### Repositorio
|
||||||
|
- **Código fuente**: https://github.com/jeturing/Jarvis
|
||||||
|
- **Issues**: https://github.com/jeturing/Jarvis/issues
|
||||||
|
- **Pull Requests**: https://github.com/jeturing/Jarvis/pulls
|
||||||
|
- **Discussions**: https://github.com/jeturing/Jarvis/discussions
|
||||||
|
|
||||||
|
### Comunidad
|
||||||
|
- **Discord**: (Añadir enlace si existe)
|
||||||
|
- **Foro**: (Añadir enlace si existe)
|
||||||
|
|
||||||
|
### Recursos Externos
|
||||||
|
- **Anthropic Claude**: https://www.anthropic.com/
|
||||||
|
- **OpenAI GPT**: https://openai.com/
|
||||||
|
- **Playwright**: https://playwright.dev/
|
||||||
|
- **grammY (Telegram)**: https://grammy.dev/
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🤝 Contribuir a la Documentación
|
||||||
|
|
||||||
|
¿Encontraste un error o quieres mejorar la documentación?
|
||||||
|
|
||||||
|
1. **Reporta issues**: [GitHub Issues](https://github.com/jeturing/Jarvis/issues)
|
||||||
|
2. **Envía PRs**: Sigue las guías en [CONTRIBUTING.md](../CONTRIBUTING.md)
|
||||||
|
3. **Discute mejoras**: [GitHub Discussions](https://github.com/jeturing/Jarvis/discussions)
|
||||||
|
|
||||||
|
### Guías para Contribuir
|
||||||
|
|
||||||
|
- Mantén un tono claro y profesional
|
||||||
|
- Incluye ejemplos de código cuando sea posible
|
||||||
|
- Añade diagramas ASCII para conceptos complejos
|
||||||
|
- Actualiza el índice cuando añadas nuevos documentos
|
||||||
|
- Verifica que todos los enlaces funcionen
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📄 Licencia
|
||||||
|
|
||||||
|
La documentación está licenciada bajo la misma licencia MIT que el proyecto principal. Ver [LICENSE](../LICENSE).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚡ Actualizaciones Recientes
|
||||||
|
|
||||||
|
- **2024-01**: Creación de documentación completa en español
|
||||||
|
- **2024-01**: Añadida documentación de arquitectura técnica
|
||||||
|
- **2024-01**: Añadida documentación de componentes
|
||||||
|
- **2024-01**: Creado índice de navegación
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📧 Contacto
|
||||||
|
|
||||||
|
¿Necesitas más ayuda?
|
||||||
|
|
||||||
|
- **Email**: (Añadir email de contacto)
|
||||||
|
- **Discord**: (Añadir enlace de Discord)
|
||||||
|
- **Twitter**: (Añadir handle de Twitter)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<strong>¡Feliz aprendizaje y desarrollo con Jarvis! 🤖</strong>
|
||||||
|
</p>
|
||||||
979
docs/README-ES.md
Normal file
979
docs/README-ES.md
Normal file
@ -0,0 +1,979 @@
|
|||||||
|
# 🦞 Moltbot - Documentación Completa del Proyecto
|
||||||
|
|
||||||
|
## Índice
|
||||||
|
1. [Visión General](#visión-general)
|
||||||
|
2. [¿Qué es Moltbot?](#qué-es-moltbot)
|
||||||
|
3. [Arquitectura del Sistema](#arquitectura-del-sistema)
|
||||||
|
4. [Componentes Principales](#componentes-principales)
|
||||||
|
5. [Canales de Mensajería](#canales-de-mensajería)
|
||||||
|
6. [Tecnologías Utilizadas](#tecnologías-utilizadas)
|
||||||
|
7. [Sistema de Plugins](#sistema-de-plugins)
|
||||||
|
8. [Configuración y Despliegue](#configuración-y-despliegue)
|
||||||
|
9. [Desarrollo](#desarrollo)
|
||||||
|
10. [Estructura de Directorios](#estructura-de-directorios)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Visión General
|
||||||
|
|
||||||
|
**Moltbot** (también conocido como Jarvis o Clawdbot) es un **asistente personal de IA** que se ejecuta en tus propios dispositivos. Es una plataforma local-first, auto-hospedada y diseñada para control de usuario único.
|
||||||
|
|
||||||
|
### Características Principales
|
||||||
|
|
||||||
|
✅ **Multi-canal**: Conecta con WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, Matrix, Zalo y más
|
||||||
|
✅ **Capacidades de voz**: Wake Voice, Talk Mode (entrada/salida de voz en macOS/iOS/Android)
|
||||||
|
✅ **Canvas en vivo**: Espacio de trabajo visual controlado por agente con framework A2UI
|
||||||
|
✅ **Herramientas de primera clase**: Browser, Canvas, Cron, Sessions, acciones de Discord/Slack
|
||||||
|
✅ **Enrutamiento multi-agente**: Aisla agentes por espacio de trabajo/canal
|
||||||
|
✅ **Asistente de configuración**: `moltbot onboard` para configuración fácil
|
||||||
|
✅ **Daemon siempre activo**: vía systemd/launchd
|
||||||
|
✅ **Soporte Gateway remoto**: para servidores Linux sin interfaz gráfica
|
||||||
|
✅ **Privacidad**: Se ejecuta localmente, sin dependencia de servidor
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ¿Qué es Moltbot?
|
||||||
|
|
||||||
|
Moltbot es un asistente de IA personal que:
|
||||||
|
|
||||||
|
### Propósito Principal
|
||||||
|
- Asistente de IA personal siempre activo usando modelos Claude/OpenAI
|
||||||
|
- Gateway de mensajería multi-canal (bandeja de entrada unificada entre plataformas)
|
||||||
|
- Funciona en macOS, iOS, Android, Linux, Windows (WSL2)
|
||||||
|
- Enfocado en privacidad: se ejecuta localmente, sin dependencia de servidor
|
||||||
|
|
||||||
|
### Casos de Uso
|
||||||
|
1. **Asistente Personal**: Responde preguntas, ejecuta tareas, gestiona calendarios
|
||||||
|
2. **Centro de Mensajería Unificado**: Una interfaz para todos tus canales de chat
|
||||||
|
3. **Automatización**: Ejecuta scripts, gestiona tareas programadas (cron)
|
||||||
|
4. **Navegación Web**: Automatización de navegador con Playwright
|
||||||
|
5. **Procesamiento de Medios**: Transcripción de audio, análisis de imágenes, procesamiento de video
|
||||||
|
6. **Desarrollo**: Asistente de código, revisión de código, depuración
|
||||||
|
|
||||||
|
### Ventajas Únicas
|
||||||
|
- **Control Total**: Tú posees tus datos y configuración
|
||||||
|
- **Sin Servidor Central**: No hay dependencia de servicios de terceros
|
||||||
|
- **Extensible**: Sistema de plugins robusto para añadir funcionalidad
|
||||||
|
- **Multi-Plataforma**: Funciona en todos los sistemas operativos principales
|
||||||
|
- **Seguro**: Autenticación local, políticas de lista de permitidos
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Arquitectura del Sistema
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────────────────────────────────────────────┐
|
||||||
|
│ Gateway (Servidor WebSocket) │
|
||||||
|
│ - Plano de control para sesiones/canales │
|
||||||
|
│ - Registro de chat y enrutamiento de mensajes │
|
||||||
|
│ - Catálogo de modelos y perfiles de autenticación │
|
||||||
|
│ - Trabajos cron, webhooks, herramienta de navegador│
|
||||||
|
└────────────────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌────────────────────────────────────────────────────┐
|
||||||
|
│ Runtime de Agente (Pi Agent) │
|
||||||
|
│ - Modo RPC embedding │
|
||||||
|
│ - Streaming de herramientas y bloques │
|
||||||
|
│ - Failover de modelos/rotación de auth │
|
||||||
|
│ - Ventana de contexto de sesión │
|
||||||
|
│ - Entorno sandbox (Docker opcional) │
|
||||||
|
└────────────────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌────────────────────────────────────────────────────┐
|
||||||
|
│ Capa Multi-Canal │
|
||||||
|
│ - Manejadores de canal base │
|
||||||
|
│ - Análisis de mensajes entrantes │
|
||||||
|
│ - Enrutamiento y formato salientes │
|
||||||
|
│ - Políticas de lista de permitidos/emparejamiento DM│
|
||||||
|
│ - Enrutamiento de menciones en grupo │
|
||||||
|
└────────────────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌────────────────────────────────────────────────────┐
|
||||||
|
│ Sistema de Herramientas │
|
||||||
|
│ - Browser (automatización web) │
|
||||||
|
│ - Canvas (espacio de trabajo visual) │
|
||||||
|
│ - Image (analizar/generar) │
|
||||||
|
│ - Message (enviar entre canales) │
|
||||||
|
│ - Session (generar sub-agentes) │
|
||||||
|
│ - Bash (ejecutar comandos) │
|
||||||
|
│ - Web (fetch, search, readability) │
|
||||||
|
│ - Memory (recordar contexto) │
|
||||||
|
│ - Cron (programar tareas) │
|
||||||
|
│ - Acciones Discord/Slack/WhatsApp │
|
||||||
|
└────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Flujo de Mensajes
|
||||||
|
|
||||||
|
1. **Entrada**: Mensaje recibido desde canal (WhatsApp, Telegram, etc.)
|
||||||
|
2. **Enrutamiento**: Gateway determina sesión y agente apropiado
|
||||||
|
3. **Procesamiento**: Agente procesa mensaje con herramientas disponibles
|
||||||
|
4. **Ejecución**: Herramientas se ejecutan (browser, bash, memory, etc.)
|
||||||
|
5. **Respuesta**: Agente genera respuesta basada en resultados
|
||||||
|
6. **Salida**: Mensaje enviado de vuelta al canal original o cruzado
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Componentes Principales
|
||||||
|
|
||||||
|
### 1. Gateway (`src/gateway/`)
|
||||||
|
|
||||||
|
El **Gateway** es el corazón del sistema. Es un servidor WebSocket que:
|
||||||
|
|
||||||
|
- **Gestiona todas las sesiones** de chat activas
|
||||||
|
- **Enruta mensajes** entre canales y agentes
|
||||||
|
- **Mantiene catálogo de modelos** (Claude, GPT, Bedrock)
|
||||||
|
- **Ejecuta trabajos cron** y webhooks
|
||||||
|
- **Proporciona herramienta de navegador** compartida
|
||||||
|
- **Maneja descubrimiento** de servicios (mDNS)
|
||||||
|
|
||||||
|
**Archivos clave:**
|
||||||
|
- `server.ts` - Servidor principal WebSocket
|
||||||
|
- `chat-registry.ts` - Registro de chats activos
|
||||||
|
- `model-catalog.ts` - Catálogo de modelos AI
|
||||||
|
- `browser-tool.ts` - Integración de Playwright
|
||||||
|
|
||||||
|
### 2. Runtime de Agente (`src/agents/`)
|
||||||
|
|
||||||
|
El **Runtime de Agente** ejecuta modelos de IA y gestiona interacciones:
|
||||||
|
|
||||||
|
- **Integración Pi Agent** (`pi-embedded-runner.ts`) - Ejecuta Claude/GPT en modo RPC
|
||||||
|
- **Gestión de sesiones** (`session-*.ts`) - Aisla contextos de chat
|
||||||
|
- **Streaming de herramientas** - Streaming en tiempo real de uso de herramientas
|
||||||
|
- **Failover de modelos** - Rotación automática si un modelo falla
|
||||||
|
- **Manejo de perfiles de auth** - OAuth y claves API
|
||||||
|
|
||||||
|
**Archivos clave:**
|
||||||
|
- `pi-embedded-runner.ts` - Ejecutor principal de agente
|
||||||
|
- `session-manager.ts` - Gestor de sesiones de chat
|
||||||
|
- `tool-registry.ts` - Registro de herramientas disponibles
|
||||||
|
- `model-auth.ts` - Autenticación de modelos
|
||||||
|
|
||||||
|
### 3. Canales (`src/channels/`, `extensions/`)
|
||||||
|
|
||||||
|
**Canales integrados** (en `src/`):
|
||||||
|
- `whatsapp/` - WhatsApp (biblioteca Baileys)
|
||||||
|
- `telegram/` - Telegram (grammY)
|
||||||
|
- `signal/` - Signal (signal-cli)
|
||||||
|
- `imessage/` - iMessage (imsg)
|
||||||
|
- `discord/` - Discord (discord.js)
|
||||||
|
- `slack/` - Slack (Bolt)
|
||||||
|
|
||||||
|
**Canales de extensión** (en `extensions/`):
|
||||||
|
- `msteams/` - Microsoft Teams
|
||||||
|
- `matrix/` - Matrix con soporte E2E
|
||||||
|
- `zalo/`, `zalouser/` - Mensajería vietnamita
|
||||||
|
- `bluebubbles/` - Relay iMessage
|
||||||
|
- Y más de 20 extensiones de canal
|
||||||
|
|
||||||
|
**Características:**
|
||||||
|
- Emparejamiento DM (lista de permitidos basada en código)
|
||||||
|
- Enrutamiento de grupo/canal con control de menciones
|
||||||
|
- Etiquetas de respuesta para respuestas basadas en hilos
|
||||||
|
- Fragmentación de mensajes por canal
|
||||||
|
- Reconocimientos de reacción
|
||||||
|
- Indicadores de escritura
|
||||||
|
|
||||||
|
### 4. Sistema de Plugins (`src/plugins/`)
|
||||||
|
|
||||||
|
El **sistema de plugins** permite extensibilidad:
|
||||||
|
|
||||||
|
**Tipos de plugins:**
|
||||||
|
- **Plugins de canal** - Nuevas integraciones de mensajería
|
||||||
|
- **Plugins de auth** - Manejadores OAuth
|
||||||
|
- **Plugins de herramientas** - Herramientas personalizadas de agente
|
||||||
|
- **Plugins de memoria** - Backends de almacenamiento personalizados
|
||||||
|
- **Plugins de hooks** - Manejadores de eventos globales
|
||||||
|
|
||||||
|
**Archivos clave:**
|
||||||
|
- `discovery.ts` - Auto-detecta plugins
|
||||||
|
- `loader.ts` - Carga plugins validados
|
||||||
|
- `manifest.ts` - Validación de esquema de manifiesto
|
||||||
|
- `services.ts` - Proveedores de inyección de servicios
|
||||||
|
|
||||||
|
### 5. Herramienta de Navegador (`src/browser/`)
|
||||||
|
|
||||||
|
La **herramienta de navegador** proporciona automatización web:
|
||||||
|
|
||||||
|
- **Automatización Chromium** vía Playwright
|
||||||
|
- **Snapshots conscientes de IA** de páginas
|
||||||
|
- **Rellenado de formularios e interacción**
|
||||||
|
- **Generación de screenshots y PDF**
|
||||||
|
- **Perfiles personalizados** con cookies/almacenamiento
|
||||||
|
- **Puente CDP** para depuración DevTools
|
||||||
|
|
||||||
|
**Archivos clave:**
|
||||||
|
- `browser-tool.ts` - API principal de herramienta
|
||||||
|
- `playwright-bridge.ts` - Puente Playwright
|
||||||
|
- `snapshot.ts` - Generación de snapshots de página
|
||||||
|
|
||||||
|
### 6. Pipeline de Medios (`src/media/`)
|
||||||
|
|
||||||
|
El **pipeline de medios** maneja procesamiento de medios:
|
||||||
|
|
||||||
|
- Procesamiento de imagen/audio/video
|
||||||
|
- Hooks de transcripción
|
||||||
|
- Almacén de archivos con límites de tamaño
|
||||||
|
- Detección de tipo MIME
|
||||||
|
- Gestión de ciclo de vida temporal
|
||||||
|
|
||||||
|
**Archivos clave:**
|
||||||
|
- `index.ts` - API principal de medios
|
||||||
|
- `transcription.ts` - Hooks de transcripción de audio
|
||||||
|
- `file-store.ts` - Almacenamiento persistente de archivos
|
||||||
|
|
||||||
|
### 7. Canvas Host (`src/canvas-host/`)
|
||||||
|
|
||||||
|
El **Canvas Host** proporciona un espacio de trabajo visual:
|
||||||
|
|
||||||
|
- Framework A2UI para renderizado
|
||||||
|
- Actualización de estado en tiempo real
|
||||||
|
- Serialización de DOM
|
||||||
|
- Integración WebSocket
|
||||||
|
|
||||||
|
**Archivos clave:**
|
||||||
|
- `index.ts` - API principal de Canvas
|
||||||
|
- `a2ui/` - Paquetes de framework A2UI
|
||||||
|
|
||||||
|
### 8. CLI (`src/cli/`)
|
||||||
|
|
||||||
|
La **CLI** proporciona interfaz de línea de comandos:
|
||||||
|
|
||||||
|
**Comandos principales:**
|
||||||
|
- `gateway` - Iniciar servidor gateway
|
||||||
|
- `agent` - Ejecutar agente AI
|
||||||
|
- `onboard` - Asistente de configuración
|
||||||
|
- `models` - Gestionar modelos AI
|
||||||
|
- `channels` - Gestionar canales
|
||||||
|
- `cron` - Gestionar trabajos programados
|
||||||
|
- `daemon` - Gestionar servicio daemon
|
||||||
|
- `plugins` - Gestionar plugins
|
||||||
|
- `skills` - Gestionar skills
|
||||||
|
|
||||||
|
**Archivos clave:**
|
||||||
|
- `index.ts` - Entry point de CLI
|
||||||
|
- `commands/` - Implementaciones de comandos
|
||||||
|
|
||||||
|
### 9. Configuración (`src/config/`)
|
||||||
|
|
||||||
|
El **sistema de configuración** gestiona ajustes:
|
||||||
|
|
||||||
|
- Carga de configuración YAML
|
||||||
|
- Validación de esquema Zod
|
||||||
|
- Almacenamiento de sesión
|
||||||
|
- Gestión de rutas
|
||||||
|
- Migraciones de configuración
|
||||||
|
|
||||||
|
**Archivos clave:**
|
||||||
|
- `index.ts` - Cargador principal de configuración
|
||||||
|
- `schema.ts` - Esquema de validación Zod
|
||||||
|
- `paths.ts` - Resolución de rutas de sistema
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Canales de Mensajería
|
||||||
|
|
||||||
|
### Canales Integrados
|
||||||
|
|
||||||
|
| Canal | Biblioteca | Estado |
|
||||||
|
|-------|-----------|--------|
|
||||||
|
| **WhatsApp** | @whiskeysockets/baileys | ✅ Estable |
|
||||||
|
| **Telegram** | grammy | ✅ Estable |
|
||||||
|
| **Signal** | signal-cli | ✅ Estable |
|
||||||
|
| **iMessage** | imsg | ✅ Estable |
|
||||||
|
| **Discord** | discord.js | ✅ Estable |
|
||||||
|
| **Slack** | @slack/bolt | ✅ Estable |
|
||||||
|
| **Google Chat** | Chat API | ✅ Estable |
|
||||||
|
|
||||||
|
### Canales de Extensión
|
||||||
|
|
||||||
|
| Canal | Ubicación | Estado |
|
||||||
|
|-------|-----------|--------|
|
||||||
|
| **BlueBubbles** | extensions/bluebubbles | ✅ Estable |
|
||||||
|
| **Microsoft Teams** | extensions/msteams | ✅ Estable |
|
||||||
|
| **Matrix** | extensions/matrix | ✅ Estable |
|
||||||
|
| **Zalo** | extensions/zalo | ✅ Estable |
|
||||||
|
| **Zalo Personal** | extensions/zalouser | ✅ Estable |
|
||||||
|
| **Twitch** | extensions/twitch | ✅ Estable |
|
||||||
|
| **Mattermost** | extensions/mattermost | ✅ Estable |
|
||||||
|
| **Nextcloud Talk** | extensions/nextcloud-talk | ✅ Estable |
|
||||||
|
| **Tlon** | extensions/tlon | ✅ Estable |
|
||||||
|
| **Nostr** | extensions/nostr | ✅ Estable |
|
||||||
|
| **LINE** | extensions/line | ✅ Estable |
|
||||||
|
| **Voice Call** | extensions/voice-call | ✅ Beta |
|
||||||
|
|
||||||
|
### Características de Canal
|
||||||
|
|
||||||
|
- **Emparejamiento DM**: Lista de permitidos basada en código
|
||||||
|
- **Enrutamiento de grupo**: Control de menciones
|
||||||
|
- **Etiquetas de respuesta**: Respuestas basadas en hilos
|
||||||
|
- **Fragmentación de mensajes**: Límites específicos por canal
|
||||||
|
- **Reacciones**: Reconocimientos
|
||||||
|
- **Indicadores de escritura**: Estado en tiempo real
|
||||||
|
- **Redacción de medios**: Capacidades de privacidad
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tecnologías Utilizadas
|
||||||
|
|
||||||
|
### Stack Backend
|
||||||
|
|
||||||
|
| Tecnología | Versión | Propósito |
|
||||||
|
|------------|---------|-----------|
|
||||||
|
| **TypeScript** | 5.9+ | Lenguaje principal |
|
||||||
|
| **Node.js** | ≥22.12.0 | Runtime |
|
||||||
|
| **Hono** | 4.11.4 | Framework HTTP |
|
||||||
|
| **Express** | 5.2 | Servidor WebSocket (legacy) |
|
||||||
|
| **ws** | 8.19 | Biblioteca WebSocket |
|
||||||
|
| **Zod** | 4.3 | Validación de esquema |
|
||||||
|
|
||||||
|
### Integración AI/Modelo
|
||||||
|
|
||||||
|
| Tecnología | Propósito |
|
||||||
|
|------------|-----------|
|
||||||
|
| **@mariozechner/pi-agent-core** | Agente Pi de Anthropic |
|
||||||
|
| **@mariozechner/pi-tui** | UI de terminal para agente |
|
||||||
|
| **Anthropic SDK** | API Claude |
|
||||||
|
| **OpenAI SDK** | API ChatGPT |
|
||||||
|
| **AWS Bedrock SDK** | Modelos AWS |
|
||||||
|
| **Ollama SDK** | Soporte LLM local |
|
||||||
|
|
||||||
|
### Mensajería & Comunicación
|
||||||
|
|
||||||
|
| Biblioteca | Canal |
|
||||||
|
|-----------|-------|
|
||||||
|
| **@whiskeysockets/baileys** | WhatsApp |
|
||||||
|
| **grammy** | Telegram |
|
||||||
|
| **@slack/bolt** | Slack |
|
||||||
|
| **discord.js** | Discord |
|
||||||
|
| **@line/bot-sdk** | LINE |
|
||||||
|
| **signal-cli** | Signal |
|
||||||
|
| **imsg** | iMessage |
|
||||||
|
|
||||||
|
### Automatización de Navegador
|
||||||
|
|
||||||
|
| Tecnología | Propósito |
|
||||||
|
|------------|-----------|
|
||||||
|
| **Playwright Core** | 1.58 - Automatización web |
|
||||||
|
| **chromium-bidi** | 13.0 - Protocolo DevTools Chrome |
|
||||||
|
| **Sharp** | 0.34 - Procesamiento de imágenes |
|
||||||
|
| **pdfjs-dist** | Manipulación de PDF |
|
||||||
|
|
||||||
|
### Base de Datos & Almacenamiento
|
||||||
|
|
||||||
|
| Tecnología | Propósito |
|
||||||
|
|------------|-----------|
|
||||||
|
| **SQLite-vec** | Almacenamiento vectorial para memoria |
|
||||||
|
| **LanceDB** | Búsqueda vectorial (extensión) |
|
||||||
|
| **Sistema de archivos** | Persistencia de sesión/configuración |
|
||||||
|
| **proper-lockfile** | Control de acceso concurrente |
|
||||||
|
|
||||||
|
### CLI & DevOps
|
||||||
|
|
||||||
|
| Tecnología | Propósito |
|
||||||
|
|------------|-----------|
|
||||||
|
| **Commander.js** | Análisis de argumentos CLI |
|
||||||
|
| **@clack/prompts** | Prompts CLI interactivos |
|
||||||
|
| **Chalk** | Colores de terminal |
|
||||||
|
| **dotenv** | Configuración de entorno |
|
||||||
|
| **YAML** | Soporte de formato de configuración |
|
||||||
|
|
||||||
|
### Herramientas de Desarrollo
|
||||||
|
|
||||||
|
| Tecnología | Propósito |
|
||||||
|
|------------|-----------|
|
||||||
|
| **TypeScript** | Verificación de tipos estricta |
|
||||||
|
| **Vitest** | Ejecutor de tests |
|
||||||
|
| **oxlint** | Linting (OxC) |
|
||||||
|
| **oxfmt** | Formateo |
|
||||||
|
| **tsx** | Ejecución TS |
|
||||||
|
| **Playwright Core** | Testing E2E |
|
||||||
|
| **Wireit** | Orquestación de tareas de build |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Sistema de Plugins
|
||||||
|
|
||||||
|
### Arquitectura de Plugins
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ Descubrimiento de Plugins │
|
||||||
|
│ - Auto-detecta desde extensions/ │
|
||||||
|
│ - Auto-detecta desde node_modules/@moltbot/│
|
||||||
|
│ - Validación de manifiesto │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ Cargador de Plugins │
|
||||||
|
│ - Validación de esquema de configuración │
|
||||||
|
│ - Inicialización de runtime │
|
||||||
|
│ - Registro de hooks │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ Proveedores de Servicios │
|
||||||
|
│ - Acceso a cliente Gateway │
|
||||||
|
│ - Proveedor de configuración │
|
||||||
|
│ - Inyección de logger │
|
||||||
|
│ - Utilidades de cliente HTTP │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tipos de Plugins
|
||||||
|
|
||||||
|
#### 1. Plugins de Canal
|
||||||
|
Añaden nuevos canales de mensajería:
|
||||||
|
```typescript
|
||||||
|
export function createChannelPlugin(): ChannelPlugin {
|
||||||
|
return {
|
||||||
|
name: 'my-channel',
|
||||||
|
type: 'channel',
|
||||||
|
init: async (config) => {
|
||||||
|
// Inicializar canal
|
||||||
|
},
|
||||||
|
send: async (message) => {
|
||||||
|
// Enviar mensaje
|
||||||
|
},
|
||||||
|
receive: async (handler) => {
|
||||||
|
// Recibir mensajes
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. Plugins de Herramientas
|
||||||
|
Añaden herramientas personalizadas para agentes:
|
||||||
|
```typescript
|
||||||
|
export function createToolPlugin(): ToolPlugin {
|
||||||
|
return {
|
||||||
|
name: 'my-tool',
|
||||||
|
type: 'tool',
|
||||||
|
schema: z.object({
|
||||||
|
input: z.string()
|
||||||
|
}),
|
||||||
|
execute: async (params) => {
|
||||||
|
// Ejecutar herramienta
|
||||||
|
return { result: 'done' }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. Plugins de Auth
|
||||||
|
Añaden manejadores OAuth personalizados:
|
||||||
|
```typescript
|
||||||
|
export function createAuthPlugin(): AuthPlugin {
|
||||||
|
return {
|
||||||
|
name: 'my-auth',
|
||||||
|
type: 'auth',
|
||||||
|
authorize: async (credentials) => {
|
||||||
|
// Manejar OAuth
|
||||||
|
return { token: 'access_token' }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4. Plugins de Memoria
|
||||||
|
Añaden backends de almacenamiento personalizados:
|
||||||
|
```typescript
|
||||||
|
export function createMemoryPlugin(): MemoryPlugin {
|
||||||
|
return {
|
||||||
|
name: 'my-memory',
|
||||||
|
type: 'memory',
|
||||||
|
store: async (key, value) => {
|
||||||
|
// Almacenar valor
|
||||||
|
},
|
||||||
|
retrieve: async (key) => {
|
||||||
|
// Recuperar valor
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 5. Plugins de Hooks
|
||||||
|
Añaden manejadores de eventos globales:
|
||||||
|
```typescript
|
||||||
|
export function createHookPlugin(): HookPlugin {
|
||||||
|
return {
|
||||||
|
name: 'my-hook',
|
||||||
|
type: 'hook',
|
||||||
|
hooks: {
|
||||||
|
'message:received': async (message) => {
|
||||||
|
// Manejar mensaje recibido
|
||||||
|
},
|
||||||
|
'message:sent': async (message) => {
|
||||||
|
// Manejar mensaje enviado
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Esquema de Manifiesto de Plugin
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "plugin-name",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"description": "Plugin description",
|
||||||
|
"exports": {
|
||||||
|
".": "./dist/index.js",
|
||||||
|
"./config-schema": "./dist/config-schema.js"
|
||||||
|
},
|
||||||
|
"hooks": ["channel", "tool"],
|
||||||
|
"permissions": ["network", "fs"],
|
||||||
|
"dependencies": {
|
||||||
|
"some-lib": "^1.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Ciclo de Vida de Plugin
|
||||||
|
|
||||||
|
1. **Descubrimiento** - Auto-detecta plugins desde directorios conocidos
|
||||||
|
2. **Validación** - Valida manifiesto y esquema de configuración
|
||||||
|
3. **Carga** - Carga módulo de plugin
|
||||||
|
4. **Inicialización** - Ejecuta función init de plugin
|
||||||
|
5. **Registro** - Registra hooks y herramientas
|
||||||
|
6. **Ejecución** - Plugin maneja eventos y llamadas
|
||||||
|
7. **Apagado** - Limpieza durante apagado de gateway
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuración y Despliegue
|
||||||
|
|
||||||
|
### Archivo de Configuración Principal
|
||||||
|
|
||||||
|
El archivo `.moltbot.yaml` (o `.clawdbot.yaml`) controla toda la configuración:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# Configuración de Gateway
|
||||||
|
gateway:
|
||||||
|
mode: local # o 'remote'
|
||||||
|
port: 18789
|
||||||
|
bind: loopback # o 'all'
|
||||||
|
verbose: true
|
||||||
|
|
||||||
|
# Configuración de Agentes
|
||||||
|
agents:
|
||||||
|
default:
|
||||||
|
model: claude-4.5-sonnet
|
||||||
|
thinking: high
|
||||||
|
temperature: 0.7
|
||||||
|
max_tokens: 8192
|
||||||
|
|
||||||
|
# Configuración de Canales
|
||||||
|
channels:
|
||||||
|
whatsapp:
|
||||||
|
enabled: true
|
||||||
|
pairing: code
|
||||||
|
allowlist:
|
||||||
|
- "+1234567890"
|
||||||
|
|
||||||
|
telegram:
|
||||||
|
enabled: true
|
||||||
|
bot_token: "${TELEGRAM_BOT_TOKEN}"
|
||||||
|
|
||||||
|
discord:
|
||||||
|
enabled: true
|
||||||
|
bot_token: "${DISCORD_BOT_TOKEN}"
|
||||||
|
|
||||||
|
# Configuración de Herramientas
|
||||||
|
tools:
|
||||||
|
browser:
|
||||||
|
enabled: true
|
||||||
|
headless: true
|
||||||
|
timeout: 30000
|
||||||
|
|
||||||
|
canvas:
|
||||||
|
enabled: true
|
||||||
|
port: 8080
|
||||||
|
|
||||||
|
# Configuración de Sandbox
|
||||||
|
sandbox:
|
||||||
|
enabled: false
|
||||||
|
docker_image: "moltbot/sandbox"
|
||||||
|
|
||||||
|
# Configuración de Plugins
|
||||||
|
plugins:
|
||||||
|
- name: matrix
|
||||||
|
enabled: true
|
||||||
|
config:
|
||||||
|
homeserver: "https://matrix.org"
|
||||||
|
|
||||||
|
# Configuración de Skills
|
||||||
|
skills:
|
||||||
|
- workspace1
|
||||||
|
- workspace2
|
||||||
|
```
|
||||||
|
|
||||||
|
### Variables de Entorno
|
||||||
|
|
||||||
|
Archivo `.env`:
|
||||||
|
```bash
|
||||||
|
# Tokens de API
|
||||||
|
ANTHROPIC_API_KEY=sk-ant-...
|
||||||
|
OPENAI_API_KEY=sk-...
|
||||||
|
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
|
||||||
|
DISCORD_BOT_TOKEN=MTk4...
|
||||||
|
|
||||||
|
# Configuración de Gateway
|
||||||
|
CLAWDBOT_GATEWAY_PORT=18789
|
||||||
|
CLAWDBOT_GATEWAY_BIND=loopback
|
||||||
|
|
||||||
|
# Configuración de Modo
|
||||||
|
CLAWDBOT_PROFILE=production # o 'dev'
|
||||||
|
CLAWDBOT_SKIP_CHANNELS=0
|
||||||
|
|
||||||
|
# Configuración de Depuración
|
||||||
|
CLAWDBOT_DEBUG=0
|
||||||
|
CLAWDBOT_VERBOSE=0
|
||||||
|
```
|
||||||
|
|
||||||
|
### Instalación
|
||||||
|
|
||||||
|
#### Instalación rápida (npm)
|
||||||
|
```bash
|
||||||
|
npm install -g moltbot@latest
|
||||||
|
moltbot onboard --install-daemon
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Desde fuente (desarrollo)
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/moltbot/moltbot.git
|
||||||
|
cd moltbot
|
||||||
|
pnpm install
|
||||||
|
pnpm ui:build
|
||||||
|
pnpm build
|
||||||
|
pnpm moltbot onboard --install-daemon
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Docker
|
||||||
|
```bash
|
||||||
|
docker-compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
### Despliegue como Daemon
|
||||||
|
|
||||||
|
#### macOS (launchd)
|
||||||
|
```bash
|
||||||
|
moltbot daemon install
|
||||||
|
moltbot daemon start
|
||||||
|
moltbot daemon status
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Linux (systemd)
|
||||||
|
```bash
|
||||||
|
moltbot daemon install
|
||||||
|
systemctl --user start moltbot-gateway
|
||||||
|
systemctl --user status moltbot-gateway
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Windows (WSL2)
|
||||||
|
```bash
|
||||||
|
# En WSL2
|
||||||
|
moltbot daemon install
|
||||||
|
moltbot daemon start
|
||||||
|
```
|
||||||
|
|
||||||
|
### Gateway Remoto
|
||||||
|
|
||||||
|
Para servidores sin interfaz gráfica:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# En servidor remoto
|
||||||
|
gateway:
|
||||||
|
mode: remote
|
||||||
|
bind: all
|
||||||
|
port: 18789
|
||||||
|
|
||||||
|
# En cliente local
|
||||||
|
agents:
|
||||||
|
gateway_url: "ws://your-server:18789"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Desarrollo
|
||||||
|
|
||||||
|
### Configuración de Entorno de Desarrollo
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Clonar repositorio
|
||||||
|
git clone https://github.com/moltbot/moltbot.git
|
||||||
|
cd moltbot
|
||||||
|
|
||||||
|
# 2. Instalar dependencias
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# 3. Construir UI
|
||||||
|
pnpm ui:build
|
||||||
|
|
||||||
|
# 4. Construir proyecto
|
||||||
|
pnpm build
|
||||||
|
|
||||||
|
# 5. Ejecutar en modo desarrollo
|
||||||
|
pnpm gateway:watch # Auto-recarga en cambios
|
||||||
|
```
|
||||||
|
|
||||||
|
### Scripts de Desarrollo
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Desarrollo
|
||||||
|
pnpm dev # Ejecutar CLI en modo dev
|
||||||
|
pnpm gateway:watch # Gateway con auto-recarga
|
||||||
|
pnpm gateway:dev # Gateway dev sin canales
|
||||||
|
pnpm tui:dev # UI de terminal dev
|
||||||
|
|
||||||
|
# Build
|
||||||
|
pnpm build # Compilar TypeScript
|
||||||
|
pnpm ui:build # Construir UI web
|
||||||
|
pnpm canvas:a2ui:bundle # Empaquetar Canvas A2UI
|
||||||
|
|
||||||
|
# Testing
|
||||||
|
pnpm test # Ejecutar todos los tests
|
||||||
|
pnpm test:watch # Tests en modo watch
|
||||||
|
pnpm test:coverage # Tests con cobertura
|
||||||
|
pnpm test:e2e # Tests end-to-end
|
||||||
|
pnpm test:live # Tests con APIs reales
|
||||||
|
|
||||||
|
# Linting & Formatting
|
||||||
|
pnpm lint # Lint TypeScript
|
||||||
|
pnpm lint:fix # Fix problemas de lint
|
||||||
|
pnpm format # Verificar formato
|
||||||
|
pnpm format:fix # Fix formato
|
||||||
|
|
||||||
|
# Plataformas
|
||||||
|
pnpm ios:build # Construir app iOS
|
||||||
|
pnpm ios:run # Ejecutar app iOS
|
||||||
|
pnpm android:assemble # Ensamblar app Android
|
||||||
|
pnpm android:run # Ejecutar app Android
|
||||||
|
pnpm mac:package # Empaquetar app macOS
|
||||||
|
```
|
||||||
|
|
||||||
|
### Estructura de Testing
|
||||||
|
|
||||||
|
```
|
||||||
|
test/
|
||||||
|
├── unit/ # Tests unitarios
|
||||||
|
├── e2e/ # Tests end-to-end
|
||||||
|
├── integration/ # Tests de integración
|
||||||
|
└── fixtures/ # Datos de prueba
|
||||||
|
```
|
||||||
|
|
||||||
|
**Configuraciones de Vitest:**
|
||||||
|
- `vitest.config.ts` - Configuración principal
|
||||||
|
- `vitest.unit.config.ts` - Tests unitarios
|
||||||
|
- `vitest.e2e.config.ts` - Tests E2E
|
||||||
|
- `vitest.live.config.ts` - Tests con APIs reales
|
||||||
|
- `vitest.extensions.config.ts` - Tests de extensiones
|
||||||
|
- `vitest.gateway.config.ts` - Tests de gateway
|
||||||
|
|
||||||
|
### Requisitos de Cobertura de Tests
|
||||||
|
|
||||||
|
- **Líneas**: 70%
|
||||||
|
- **Funciones**: 70%
|
||||||
|
- **Ramas**: 70%
|
||||||
|
- **Declaraciones**: 70%
|
||||||
|
|
||||||
|
### Estándares de Código
|
||||||
|
|
||||||
|
- **TypeScript estricto**: Verificación de tipos completa
|
||||||
|
- **ESLint**: Linting con oxlint
|
||||||
|
- **Prettier**: Formateo con oxfmt
|
||||||
|
- **Pre-commit hooks**: Ejecuta lint + format antes de commit
|
||||||
|
- **Límite de LOC**: ~700 líneas por archivo (guía)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Estructura de Directorios
|
||||||
|
|
||||||
|
```
|
||||||
|
/
|
||||||
|
├── src/ # Código fuente TypeScript
|
||||||
|
│ ├── agents/ # Runtime de agente y gestión de sesiones
|
||||||
|
│ ├── gateway/ # Servidor gateway y registro de chat
|
||||||
|
│ ├── channels/ # Infraestructura base de canales
|
||||||
|
│ ├── cli/ # Comandos de interfaz de línea de comandos
|
||||||
|
│ ├── browser/ # Herramienta de automatización de navegador
|
||||||
|
│ ├── canvas-host/ # Host de Canvas y framework A2UI
|
||||||
|
│ ├── media/ # Pipeline de procesamiento de medios
|
||||||
|
│ ├── plugins/ # Sistema de plugins y cargador
|
||||||
|
│ ├── config/ # Sistema de configuración
|
||||||
|
│ ├── whatsapp/ # Integración WhatsApp
|
||||||
|
│ ├── telegram/ # Integración Telegram
|
||||||
|
│ ├── signal/ # Integración Signal
|
||||||
|
│ ├── discord/ # Integración Discord
|
||||||
|
│ ├── slack/ # Integración Slack
|
||||||
|
│ ├── imessage/ # Integración iMessage
|
||||||
|
│ ├── routing/ # Enrutamiento de mensajes
|
||||||
|
│ ├── security/ # Auth y políticas de seguridad
|
||||||
|
│ ├── memory/ # Gestión de memoria/contexto
|
||||||
|
│ ├── tts/ # Integración text-to-speech
|
||||||
|
│ ├── wizard/ # Flujo de asistente de onboarding CLI
|
||||||
|
│ ├── web/ # Frontend WebChat y Control UI
|
||||||
|
│ ├── utils/ # Utilidades compartidas
|
||||||
|
│ └── ...
|
||||||
|
│
|
||||||
|
├── extensions/ # Plugins de canal y extensiones
|
||||||
|
│ ├── bluebubbles/ # Plugin BlueBubbles
|
||||||
|
│ ├── matrix/ # Plugin Matrix
|
||||||
|
│ ├── msteams/ # Plugin Microsoft Teams
|
||||||
|
│ ├── zalo/ # Plugin Zalo
|
||||||
|
│ ├── zalouser/ # Plugin Zalo Personal
|
||||||
|
│ ├── voice-call/ # Plugin Voice Call
|
||||||
|
│ └── ...
|
||||||
|
│
|
||||||
|
├── apps/ # Aplicaciones nativas
|
||||||
|
│ ├── macos/ # App macOS (SwiftUI)
|
||||||
|
│ ├── ios/ # App iOS (SwiftUI)
|
||||||
|
│ └── android/ # App Android (Kotlin)
|
||||||
|
│
|
||||||
|
├── docs/ # Documentación
|
||||||
|
│ ├── start/ # Guías de inicio
|
||||||
|
│ ├── install/ # Guías de instalación
|
||||||
|
│ ├── channels/ # Documentación de canales
|
||||||
|
│ ├── concepts/ # Documentación de conceptos
|
||||||
|
│ ├── cli/ # Documentación de CLI
|
||||||
|
│ ├── gateway/ # Documentación de gateway
|
||||||
|
│ ├── platforms/ # Guías específicas de plataforma
|
||||||
|
│ ├── providers/ # Documentación de proveedores
|
||||||
|
│ ├── reference/ # Documentación de referencia
|
||||||
|
│ └── ...
|
||||||
|
│
|
||||||
|
├── skills/ # Paquetes de skills de workspace
|
||||||
|
│ └── workspace1/ # Ejemplo de workspace
|
||||||
|
│
|
||||||
|
├── packages/ # Paquetes monorepo
|
||||||
|
│ └── ...
|
||||||
|
│
|
||||||
|
├── scripts/ # Scripts de utilidad
|
||||||
|
│ ├── build-*.ts # Scripts de build
|
||||||
|
│ ├── test-*.sh # Scripts de test
|
||||||
|
│ ├── package-*.sh # Scripts de empaquetado
|
||||||
|
│ └── ...
|
||||||
|
│
|
||||||
|
├── test/ # Fixtures de test y helpers
|
||||||
|
│ ├── fixtures/ # Datos de prueba
|
||||||
|
│ └── helpers/ # Utilidades de test
|
||||||
|
│
|
||||||
|
├── ui/ # UI web (Control UI)
|
||||||
|
│ └── ...
|
||||||
|
│
|
||||||
|
├── vendor/ # Dependencias vendorizadas
|
||||||
|
│ └── ...
|
||||||
|
│
|
||||||
|
├── .github/ # Workflows de GitHub Actions
|
||||||
|
│ ├── workflows/ # Definiciones de workflow CI/CD
|
||||||
|
│ └── labeler.yml # Configuración de auto-etiquetado
|
||||||
|
│
|
||||||
|
├── dist/ # Salida compilada (generada)
|
||||||
|
│ └── ...
|
||||||
|
│
|
||||||
|
├── package.json # Configuración de paquete npm
|
||||||
|
├── pnpm-workspace.yaml # Configuración de workspace pnpm
|
||||||
|
├── tsconfig.json # Configuración de TypeScript
|
||||||
|
├── vitest.config.ts # Configuración de Vitest
|
||||||
|
├── docker-compose.yml # Configuración de Docker Compose
|
||||||
|
├── Dockerfile # Dockerfile principal
|
||||||
|
├── README.md # README principal (inglés)
|
||||||
|
├── CHANGELOG.md # Registro de cambios
|
||||||
|
├── LICENSE # Licencia MIT
|
||||||
|
└── ...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Directorios Clave
|
||||||
|
|
||||||
|
#### `/src/`
|
||||||
|
Código fuente principal de TypeScript. Organizado por dominio:
|
||||||
|
- **Agentes & Runtime**: `agents/`, `memory/`, `sessions/`
|
||||||
|
- **Comunicación**: `gateway/`, `channels/`, `routing/`
|
||||||
|
- **Canales Integrados**: `whatsapp/`, `telegram/`, `discord/`, etc.
|
||||||
|
- **Herramientas**: `browser/`, `canvas-host/`, `media/`, `tts/`
|
||||||
|
- **Sistema**: `cli/`, `config/`, `plugins/`, `daemon/`
|
||||||
|
- **Seguridad**: `security/`, `pairing/`
|
||||||
|
- **UI**: `web/`, `wizard/`, `tui/`
|
||||||
|
|
||||||
|
#### `/extensions/`
|
||||||
|
Plugins de extensión (20+ canales). Cada extensión es un paquete npm auto-contenido:
|
||||||
|
- Tiene su propio `package.json`
|
||||||
|
- Define `plugin.manifest.json`
|
||||||
|
- Implementa hooks de plugin
|
||||||
|
- Puede tener dependencias propias
|
||||||
|
|
||||||
|
#### `/apps/`
|
||||||
|
Aplicaciones nativas para múltiples plataformas:
|
||||||
|
- **macOS**: App SwiftUI con integración de menubar
|
||||||
|
- **iOS**: App SwiftUI con soporte de voz
|
||||||
|
- **Android**: App Kotlin con soporte de voz
|
||||||
|
|
||||||
|
#### `/docs/`
|
||||||
|
Documentación completa (Mintlify):
|
||||||
|
- Guías de inicio rápido
|
||||||
|
- Tutoriales de instalación
|
||||||
|
- Documentación de conceptos
|
||||||
|
- Referencia de API
|
||||||
|
- Guías específicas de plataforma
|
||||||
|
- Documentación de desarrollo de plugins
|
||||||
|
|
||||||
|
#### `/skills/`
|
||||||
|
Skills de workspace. Cada workspace puede tener:
|
||||||
|
- Prompts personalizados
|
||||||
|
- Herramientas bash personalizadas
|
||||||
|
- Integraciones personalizadas
|
||||||
|
- Configuración específica de workspace
|
||||||
|
|
||||||
|
#### `/scripts/`
|
||||||
|
Scripts de utilidad para:
|
||||||
|
- Construcción y empaquetado
|
||||||
|
- Testing (unit, E2E, Docker)
|
||||||
|
- Generación de código (protocol, Swift)
|
||||||
|
- Gestión de releases
|
||||||
|
- Automatización de desarrollo
|
||||||
|
|
||||||
|
#### `/test/`
|
||||||
|
Fixtures de test y helpers:
|
||||||
|
- Datos de prueba
|
||||||
|
- Mocks y stubs
|
||||||
|
- Utilidades de test
|
||||||
|
- Configuraciones de test
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Recursos Adicionales
|
||||||
|
|
||||||
|
### Documentación Oficial
|
||||||
|
- **Sitio Web**: https://molt.bot
|
||||||
|
- **Documentación**: https://docs.molt.bot
|
||||||
|
- **Comenzar**: https://docs.molt.bot/start/getting-started
|
||||||
|
- **FAQ**: https://docs.molt.bot/start/faq
|
||||||
|
- **Showcase**: https://docs.molt.bot/start/showcase
|
||||||
|
|
||||||
|
### Comunidad
|
||||||
|
- **Discord**: https://discord.gg/clawd
|
||||||
|
- **GitHub**: https://github.com/moltbot/moltbot
|
||||||
|
- **Releases**: https://github.com/moltbot/moltbot/releases
|
||||||
|
|
||||||
|
### Guías de Desarrollo
|
||||||
|
- **Desarrollo de Plugins**: Ver `PLUGIN-DEVELOPMENT.md`
|
||||||
|
- **Referencia de API**: Ver `API-REFERENCE.md`
|
||||||
|
- **Guía de Arquitectura**: Ver `ARCHITECTURE.md`
|
||||||
|
- **Guía de Despliegue**: Ver `DEPLOYMENT.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Licencia
|
||||||
|
|
||||||
|
MIT License - Ver [LICENSE](../LICENSE) para detalles.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Contribuir
|
||||||
|
|
||||||
|
¡Las contribuciones son bienvenidas! Ver [CONTRIBUTING.md](../CONTRIBUTING.md) para guías.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**¡Feliz hacking con Moltbot! 🦞**
|
||||||
Loading…
Reference in New Issue
Block a user