131 lines
4.4 KiB
Markdown
131 lines
4.4 KiB
Markdown
# ABE — AI Bug Report Enrichment Specification
|
|
|
|
## Concepto
|
|
Este es el diferenciador más importante de ABE frente a cualquier competidor.
|
|
Después de detectar una anomalía, ABE puede usar una LLM para enriquecer
|
|
el bug report con un análisis inteligente: causa probable, impacto,
|
|
sugerencia de fix, y prompt listo para usar con Claude/GPT.
|
|
|
|
## IMPORTANTE: esto es una capa OPCIONAL sobre el core determinista.
|
|
El core engine nunca llama a LLMs. El enriquecimiento es post-procesado,
|
|
ejecutado solo si el usuario lo configura.
|
|
|
|
## Qué genera la IA
|
|
|
|
### 1. Root Cause Analysis
|
|
A partir del action trace, HTTP log, console errors y DOM snapshot,
|
|
la IA propone la causa más probable del bug.
|
|
Ejemplo: "The 500 error is likely caused by missing server-side validation
|
|
of the email field. The server crashes when receiving an empty string
|
|
where a valid email is expected."
|
|
|
|
### 2. User Impact Assessment
|
|
La IA evalúa el impacto del bug en términos de negocio:
|
|
"This bug blocks users from completing registration. Any user who
|
|
submits an empty email will encounter an unhandled server error,
|
|
preventing account creation."
|
|
|
|
### 3. Suggested Fix
|
|
La IA propone un fix concreto:
|
|
"Add server-side validation: check if email is present and valid
|
|
before processing. Return a 422 with a descriptive error message
|
|
instead of propagating the exception."
|
|
|
|
### 4. AI-Ready Debug Prompt
|
|
Un prompt completo listo para copiar y pegar en Claude/ChatGPT:
|
|
```
|
|
Bug Report Context:
|
|
- Type: HTTP 500 on form submission
|
|
- Steps to reproduce: [exact action trace]
|
|
- Error: [exact error message]
|
|
- Request: POST /api/register with body {"email": ""}
|
|
- Response: 500 Internal Server Error
|
|
|
|
Please analyze this bug and provide:
|
|
1. Root cause
|
|
2. Code fix
|
|
3. Test case to prevent regression
|
|
```
|
|
|
|
## Implementación
|
|
|
|
### Provider abstraction
|
|
```typescript
|
|
interface IAIProvider {
|
|
name: string;
|
|
enrich(anomaly: IAnomaly, context: IEnrichmentContext): Promise<IAIEnrichment>;
|
|
}
|
|
|
|
interface IEnrichmentContext {
|
|
domSnapshot: string;
|
|
httpLog: IHttpResponse[];
|
|
consoleErrors: string[];
|
|
actionTrace: IAction[];
|
|
pageTitle: string;
|
|
url: string;
|
|
}
|
|
|
|
interface IAIEnrichment {
|
|
rootCause: string;
|
|
userImpact: string;
|
|
suggestedFix: string;
|
|
debugPrompt: string;
|
|
confidence: 'low' | 'medium' | 'high';
|
|
generatedAt: number;
|
|
provider: string;
|
|
model: string;
|
|
}
|
|
```
|
|
|
|
### Providers implementados
|
|
- `ClaudeProvider` — usa Anthropic API (claude-3-5-haiku — rápido y barato)
|
|
- `OpenAIProvider` — usa OpenAI API (gpt-4o-mini)
|
|
- `OllamaProvider` — usa Ollama local (llama3.2 — sin API key, offline)
|
|
|
|
### Cuándo se ejecuta
|
|
- Automático: si `aiEnrichment.autoEnrich: true`, se ejecuta tras cada anomalía high/critical
|
|
- Manual: botón "Enrich with AI" en AnomalyDetail page
|
|
- No bloquea: el bug report se guarda sin enriquecimiento, la IA lo añade async
|
|
|
|
## Configuración en .env
|
|
```
|
|
ABE_AI_PROVIDER=claude # claude | openai | ollama | none
|
|
ABE_AI_API_KEY=sk-ant-xxx # Anthropic key (si provider=claude)
|
|
ABE_OPENAI_API_KEY=sk-xxx # OpenAI key (si provider=openai)
|
|
ABE_OLLAMA_URL=http://localhost:11434 # (si provider=ollama)
|
|
ABE_AI_MODEL=claude-haiku-4-5 # modelo específico (opcional)
|
|
ABE_AI_AUTO_ENRICH=false # default false para no incurrir en costes
|
|
ABE_AI_MIN_SEVERITY=high # solo enriquecer high/critical automáticamente
|
|
```
|
|
|
|
## Modelo de datos — añadir a SQLite
|
|
|
|
### Añadir columna a anomalies
|
|
```sql
|
|
ALTER TABLE anomalies ADD COLUMN ai_enrichment_json TEXT;
|
|
ALTER TABLE anomalies ADD COLUMN ai_enriched_at INTEGER;
|
|
```
|
|
|
|
## Frontend — AI panel en AnomalyDetail
|
|
|
|
Si la anomalía tiene ai_enrichment_json, mostrar panel "AI Analysis" con:
|
|
- 🔍 Root Cause (texto con ícono)
|
|
- 👥 User Impact (texto con ícono)
|
|
- 🔧 Suggested Fix (bloque de código si contiene código)
|
|
- 📋 "Copy debug prompt" button (copia el debugPrompt al clipboard)
|
|
- Badge: "Analyzed by Claude" / "Analyzed by GPT-4o-mini" / "Analyzed by Llama 3.2"
|
|
- Timestamp de cuándo se generó
|
|
|
|
Si no tiene enriquecimiento, mostrar botón "✨ Analyze with AI" que llama a:
|
|
POST /api/anomalies/:id/enrich
|
|
|
|
## Endpoint nuevo
|
|
|
|
### POST /api/anomalies/:anomalyId/enrich
|
|
Dispara el enriquecimiento de una anomalía concreta (async).
|
|
Response inmediata: { status: 'enriching' }
|
|
Cuando termina, emite WebSocket event: anomaly:enriched { anomalyId, enrichment }
|
|
|
|
### GET /api/anomalies/:anomalyId — actualizado
|
|
Incluye ai_enrichment si está disponible.
|