308 lines
10 KiB
Markdown
308 lines
10 KiB
Markdown
# PLAN: Captain Claude Mobile v2
|
|
|
|
## Objetivo
|
|
App móvil nativa de chat con Claude que ejecuta comandos en el servidor y muestra resultados formateados.
|
|
|
|
---
|
|
|
|
## 1. ARQUITECTURA
|
|
|
|
```
|
|
┌──────────────────┐ HTTPS/WSS ┌──────────────────┐
|
|
│ │ ◄────────────────► │ │
|
|
│ Flutter App │ │ FastAPI │
|
|
│ (Android/iOS) │ │ Backend │
|
|
│ │ │ │
|
|
└──────────────────┘ └────────┬─────────┘
|
|
│
|
|
│ subprocess
|
|
▼
|
|
┌──────────────────┐
|
|
│ │
|
|
│ Claude CLI │
|
|
│ (claude -p) │
|
|
│ │
|
|
└──────────────────┘
|
|
```
|
|
|
|
### Backend (FastAPI)
|
|
- Recibe mensajes del usuario via WebSocket
|
|
- Ejecuta `claude -p "mensaje" --output-format stream-json`
|
|
- Parsea el output JSON de Claude
|
|
- Envía respuesta formateada al frontend
|
|
- Guarda historial en PostgreSQL
|
|
|
|
### Frontend (Flutter)
|
|
- UI de chat nativa (burbujas, input, etc.)
|
|
- Renderiza Markdown en respuestas
|
|
- Syntax highlighting en code blocks
|
|
- Muestra progreso de ejecución
|
|
- Historial de conversaciones
|
|
|
|
---
|
|
|
|
## 2. DISEÑO UI/UX
|
|
|
|
### Pantalla Principal (Chat)
|
|
```
|
|
┌─────────────────────────────────┐
|
|
│ ☰ Captain Claude [●] Online│ ← AppBar con estado conexión
|
|
├─────────────────────────────────┤
|
|
│ │
|
|
│ ┌─ User ────────────────────┐ │
|
|
│ │ Muéstrame el uso de disco │ │ ← Burbuja usuario (derecha)
|
|
│ └───────────────────────────┘ │
|
|
│ │
|
|
│ ┌─ Claude ──────────────────┐ │ ← Burbuja Claude (izquierda)
|
|
│ │ Ejecutando `df -h`... │ │
|
|
│ │ │ │
|
|
│ │ ``` │ │ ← Code block con resultado
|
|
│ │ Filesystem Size Used │ │
|
|
│ │ /dev/sda1 100G 45G │ │
|
|
│ │ ``` │ │
|
|
│ │ │ │
|
|
│ │ El disco principal tiene │ │ ← Explicación en texto
|
|
│ │ 55% libre (55GB). │ │
|
|
│ └───────────────────────────┘ │
|
|
│ │
|
|
├─────────────────────────────────┤
|
|
│ ┌─────────────────────────┐ 📎│ ← Input con attach
|
|
│ │ Escribe un mensaje... │ ➤ │ ← Botón enviar
|
|
│ └─────────────────────────────┘│
|
|
└─────────────────────────────────┘
|
|
```
|
|
|
|
### Pantalla Historial
|
|
```
|
|
┌─────────────────────────────────┐
|
|
│ ← Conversaciones │
|
|
├─────────────────────────────────┤
|
|
│ ┌─────────────────────────────┐│
|
|
│ │ 📁 Backup de base de datos ││ ← Título auto-generado
|
|
│ │ Hace 2 horas • 5 mensajes ││
|
|
│ └─────────────────────────────┘│
|
|
│ ┌─────────────────────────────┐│
|
|
│ │ 🔧 Fix error en nginx ││
|
|
│ │ Ayer • 12 mensajes ││
|
|
│ └─────────────────────────────┘│
|
|
│ ┌─────────────────────────────┐│
|
|
│ │ 📊 Análisis de logs ││
|
|
│ │ 15 Ene • 8 mensajes ││
|
|
│ └─────────────────────────────┘│
|
|
└─────────────────────────────────┘
|
|
```
|
|
|
|
### Estados de Mensaje Claude
|
|
1. **Pensando**: Spinner + "Claude está pensando..."
|
|
2. **Ejecutando**: Muestra comando siendo ejecutado
|
|
3. **Streaming**: Texto aparece progresivamente
|
|
4. **Completado**: Mensaje completo con formato
|
|
5. **Error**: Mensaje rojo con opción de reintentar
|
|
|
|
---
|
|
|
|
## 3. API BACKEND
|
|
|
|
### Endpoints REST
|
|
|
|
| Método | Endpoint | Descripción |
|
|
|--------|----------|-------------|
|
|
| POST | /auth/login | Login, retorna JWT |
|
|
| GET | /conversations | Lista conversaciones |
|
|
| GET | /conversations/{id} | Mensajes de una conversación |
|
|
| DELETE | /conversations/{id} | Eliminar conversación |
|
|
| POST | /upload | Subir archivo para contexto |
|
|
|
|
### WebSocket /ws/chat
|
|
|
|
**Cliente → Servidor:**
|
|
```json
|
|
{
|
|
"type": "message",
|
|
"content": "Muéstrame el uso de disco",
|
|
"conversation_id": "uuid-opcional",
|
|
"files": ["/path/to/file"]
|
|
}
|
|
```
|
|
|
|
**Servidor → Cliente (streaming):**
|
|
```json
|
|
{"type": "thinking"}
|
|
{"type": "tool_use", "tool": "Bash", "input": "df -h"}
|
|
{"type": "tool_result", "output": "Filesystem Size..."}
|
|
{"type": "text", "content": "El disco principal..."}
|
|
{"type": "done", "conversation_id": "uuid"}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. MODELO DE DATOS
|
|
|
|
### PostgreSQL
|
|
|
|
```sql
|
|
-- Conversaciones
|
|
CREATE TABLE conversations (
|
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
user_id VARCHAR(255) NOT NULL,
|
|
title VARCHAR(500),
|
|
created_at TIMESTAMP DEFAULT NOW(),
|
|
updated_at TIMESTAMP DEFAULT NOW()
|
|
);
|
|
|
|
-- Mensajes
|
|
CREATE TABLE messages (
|
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
conversation_id UUID REFERENCES conversations(id),
|
|
role VARCHAR(50) NOT NULL, -- 'user' | 'assistant'
|
|
content TEXT NOT NULL,
|
|
tool_uses JSONB, -- [{tool, input, output}]
|
|
created_at TIMESTAMP DEFAULT NOW()
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
## 5. FLUTTER - ESTRUCTURA
|
|
|
|
```
|
|
lib/
|
|
├── main.dart
|
|
├── config/
|
|
│ └── api_config.dart
|
|
├── models/
|
|
│ ├── conversation.dart
|
|
│ ├── message.dart
|
|
│ └── tool_use.dart
|
|
├── services/
|
|
│ ├── api_service.dart
|
|
│ ├── chat_service.dart # WebSocket
|
|
│ └── auth_service.dart
|
|
├── providers/
|
|
│ ├── auth_provider.dart
|
|
│ └── chat_provider.dart
|
|
├── screens/
|
|
│ ├── login_screen.dart
|
|
│ ├── chat_screen.dart
|
|
│ └── history_screen.dart
|
|
└── widgets/
|
|
├── message_bubble.dart # Burbuja de mensaje
|
|
├── code_block.dart # Syntax highlighting
|
|
├── tool_use_card.dart # Muestra ejecución de tool
|
|
├── thinking_indicator.dart
|
|
└── chat_input.dart # Input con attach
|
|
```
|
|
|
|
---
|
|
|
|
## 6. COMPONENTES CLAVE
|
|
|
|
### MessageBubble (Flutter)
|
|
```dart
|
|
class MessageBubble extends StatelessWidget {
|
|
final Message message;
|
|
|
|
// Renderiza según tipo:
|
|
// - Texto normal → Markdown
|
|
// - Code blocks → Syntax highlighting
|
|
// - Tool uses → Cards expandibles
|
|
// - Errores → Estilo rojo
|
|
}
|
|
```
|
|
|
|
### ToolUseCard (Flutter)
|
|
```dart
|
|
// Muestra:
|
|
// ┌─ Bash ──────────────────────┐
|
|
// │ ▶ df -h │ ← Comando ejecutado
|
|
// ├─────────────────────────────┤
|
|
// │ Filesystem Size Used ... │ ← Output (colapsable)
|
|
// └─────────────────────────────┘
|
|
```
|
|
|
|
### ChatInput (Flutter)
|
|
```dart
|
|
// - TextField multilínea
|
|
// - Botón adjuntar archivo
|
|
// - Botón enviar (disabled si vacío o desconectado)
|
|
// - Indicador de conexión
|
|
```
|
|
|
|
---
|
|
|
|
## 7. PROCESO DE DESARROLLO
|
|
|
|
### Fase 1: Backend básico
|
|
1. FastAPI con WebSocket
|
|
2. Integración con Claude CLI
|
|
3. Parsing de output JSON
|
|
4. Base de datos PostgreSQL
|
|
|
|
### Fase 2: Frontend básico
|
|
1. Chat UI con burbujas
|
|
2. Conexión WebSocket
|
|
3. Streaming de mensajes
|
|
4. Markdown rendering
|
|
|
|
### Fase 3: Features completas
|
|
1. Historial de conversaciones
|
|
2. Syntax highlighting
|
|
3. Tool use cards
|
|
4. Upload de archivos
|
|
5. Estados de conexión
|
|
|
|
### Fase 4: Pulido
|
|
1. Animaciones
|
|
2. Error handling robusto
|
|
3. Offline mode básico
|
|
4. Notificaciones
|
|
|
|
---
|
|
|
|
## 8. PROCESO DE AUDITORÍA (post-código)
|
|
|
|
### Ronda 1: Agentes paralelos
|
|
- **Arquitecto**: Revisa estructura del código
|
|
- **QA**: Busca bugs y edge cases
|
|
- **UX**: Evalúa usabilidad
|
|
|
|
### Ronda 2: Tests reales
|
|
- Probar cada endpoint con curl
|
|
- Instalar APK y probar flujos
|
|
- Documentar problemas
|
|
|
|
### Ronda 3: Fixes + re-test
|
|
- Aplicar correcciones
|
|
- Verificar que funcionan
|
|
- Compilar versión final
|
|
|
|
---
|
|
|
|
## 9. DIFERENCIAS CON v1
|
|
|
|
| Aspecto | v1 (Terminal) | v2 (Chat) |
|
|
|---------|---------------|-----------|
|
|
| UI | Emulador xterm | Chat nativo |
|
|
| Input | Teclado terminal | Texto natural |
|
|
| Output | Raw ANSI | Markdown formateado |
|
|
| Comandos | Ctrl+C manual | Claude decide |
|
|
| UX | Técnico | Amigable |
|
|
|
|
---
|
|
|
|
## 10. CRITERIOS DE ÉXITO
|
|
|
|
1. ✅ Usuario puede chatear con Claude en lenguaje natural
|
|
2. ✅ Claude ejecuta comandos y muestra resultados formateados
|
|
3. ✅ Code blocks tienen syntax highlighting
|
|
4. ✅ Conversaciones se guardan y se pueden retomar
|
|
5. ✅ UI es responsiva y agradable en móvil
|
|
6. ✅ Errores se muestran claramente con opción de reintentar
|
|
7. ✅ Conexión se reconecta automáticamente
|
|
|
|
---
|
|
|
|
## PRÓXIMO PASO
|
|
|
|
¿Apruebas este plan para empezar a implementar?
|