Evandro Fonseca Junior
77c57c3d45
- Check process_running and ready state before making inference request
- Emit descriptive error messages for each failure scenario
- Handle local vs remote connection modes appropriately
- Validation score: 100 (was 0)
Result: {"status":"keep","validation_score":100,"response_time_ms":500}
493 lines
17 KiB
Markdown
493 lines
17 KiB
Markdown
# System Design Document (SDD)
|
|
## ForgeAgent - Modo Agentic para ForgeLM
|
|
|
|
**Versão:** 1.0
|
|
**Data:** 2025-04-02
|
|
**Status:** Draft
|
|
|
|
---
|
|
|
|
## 1. Visão Geral
|
|
|
|
### 1.1 Objetivo
|
|
Transformar respostas do modelo LLM de simples "bolhas de texto" em uma **experiência agentic visível**, onde o usuário acompanha em tempo real:
|
|
- O plano estruturado de execução
|
|
- Progresso passo a passo com checkmarks
|
|
- Sub-tarefas detalhadas
|
|
- Artefatos gerados (arquivos Markdown)
|
|
|
|
### 1.2 Motivação
|
|
Modelos pequenos (0.8B-4B) têm excelente capacidade de planejamento quando estruturados corretamente. O ForgeAgent expõe essa capacidade visualmente, criando valor percebido maior e experiência similar ao Manus 1.6 Lite.
|
|
|
|
### 1.3 Escopo
|
|
- **Incluído:** Frontend React/Tauri, backend Rust (structured output), prompts para modelo
|
|
- **Excluído (futuro):** Suporte a ZIP, visão/áudio, execução real de código
|
|
|
|
---
|
|
|
|
## 2. Arquitetura
|
|
|
|
### 2.1 High-Level Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Frontend (React/Tauri) │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ ChatView │ │ ForgeAgent │ │ Artifact │ │
|
|
│ │ │ │ Plan Card │ │ Viewer │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└────────────────────┬────────────────────────────────────────┘
|
|
│ Tauri Events
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Backend (Rust/Tauri) │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Trigger │ │ Plan │ │ Streaming │ │
|
|
│ │ Detector │ │ Generator │ │ Emitter │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└────────────────────┬────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ LLM (llama.cpp) │
|
|
│ ForgeSteel 4B / ForgeIron 2B │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 2.2 Fluxo de Dados
|
|
|
|
```
|
|
1. Usuário envia mensagem
|
|
↓
|
|
2. Trigger Detector analisa: modo agentic necessário?
|
|
↓ Sim
|
|
3. Plan Generator envia prompt estruturado ao LLM
|
|
↓
|
|
4. LLM retorna JSON (AgentPlan)
|
|
↓
|
|
5. Streaming Emitter envia eventos Tauri progressivamente
|
|
↓
|
|
6. Frontend renderiza: Plano → Execução → Artefatos
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Componentes
|
|
|
|
### 3.1 Trigger Detector
|
|
**Responsabilidade:** Decidir quando ativar o modo agentic.
|
|
|
|
**Critérios Automáticos:**
|
|
- Palavras-chave: "como fazer", "guia", "passo a passo", "tutorial", "exemplo completo", "projeto"
|
|
- Padrões regex: `/\b(como|guia|tutorial|passo a passo|exemplo completo|projeto)\b/i`
|
|
|
|
**Critérios Manuais:**
|
|
- Toggle "🛠️ Modo Agentic" ao lado do input de chat
|
|
|
|
**Saída:** Boolean (`shouldUseAgentic`)
|
|
|
|
### 3.2 Plan Generator
|
|
**Responsabilidade:** Gerar estrutura JSON do plano usando structured output.
|
|
|
|
**Schema (Rust):**
|
|
```rust
|
|
#[derive(Serialize, Deserialize, Debug, Clone)]
|
|
pub struct AgentPlan {
|
|
pub title: String,
|
|
pub overview: String,
|
|
pub steps: Vec<Step>,
|
|
}
|
|
|
|
#[derive(Serialize, Deserialize, Debug, Clone)]
|
|
pub struct Step {
|
|
pub id: u32,
|
|
pub title: String,
|
|
pub description: String,
|
|
pub status: StepStatus,
|
|
pub sub_steps: Vec<SubStep>,
|
|
}
|
|
|
|
#[derive(Serialize, Deserialize, Debug, Clone)]
|
|
pub struct SubStep {
|
|
pub id: String, // formato: "{step_id}.{sub_id}"
|
|
pub description: String,
|
|
pub status: StepStatus,
|
|
}
|
|
|
|
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
|
|
#[serde(rename_all = "lowercase")]
|
|
pub enum StepStatus {
|
|
Pending,
|
|
Running,
|
|
Completed,
|
|
Error,
|
|
}
|
|
|
|
#[derive(Serialize, Deserialize, Debug, Clone)]
|
|
pub struct Artifact {
|
|
pub filename: String,
|
|
pub content: String,
|
|
pub language: Option<String>, // "markdown", "javascript", etc.
|
|
}
|
|
```
|
|
|
|
### 3.3 Streaming Emitter
|
|
**Responsabilidade:** Enviar progresso para o frontend via Tauri events.
|
|
|
|
**Eventos:**
|
|
- `forgeagent:plan-started` - Início do plano
|
|
- `forgeagent:step-started` - Step N iniciado
|
|
- `forgeagent:step-completed` - Step N completado
|
|
- `forgeagent:step-error` - Step N falhou
|
|
- `forgeagent:artifact-ready` - Artefato disponível
|
|
- `forgeagent:plan-completed` - Plano finalizado
|
|
|
|
### 3.4 Frontend Components
|
|
|
|
#### 3.4.1 ForgeAgentBubble
|
|
Container especial para mensagens agentic. Diferente da bolha normal por:
|
|
- Avatar distinto (badge "ForgeAgent")
|
|
- Background sutilmente diferente
|
|
- Badge "Modo Agentic"
|
|
|
|
#### 3.4.2 PlanCard
|
|
Card expansível mostrando o plano completo:
|
|
- Header: Título + progresso (X de Y passos)
|
|
- Body: Lista de steps com checkmarks
|
|
- Accordion: Steps podem expandir para mostrar sub-steps
|
|
- Progress bar: Visualização linear do progresso
|
|
|
|
#### 3.4.3 StepItem
|
|
Item individual de uma tarefa:
|
|
- Ícone de status (⏳ pending, ⏯️ running, ✅ completed, ❌ error)
|
|
- Título da tarefa
|
|
- Descrição curta
|
|
- Sub-steps (se houver)
|
|
|
|
#### 3.4.4 SystemMessage
|
|
Mensagens intermediárias do sistema:
|
|
- Sem avatar
|
|
- Background cinza escuro
|
|
- Texto de status (ex: "✅ Diretório criado. Próximo passo...")
|
|
|
|
#### 3.4.5 ArtifactViewer
|
|
Visualizador de artefatos Markdown:
|
|
- Preview do conteúdo
|
|
- Botão "Download"
|
|
- Syntax highlight para blocos de código
|
|
|
|
---
|
|
|
|
## 4. Interface do Usuário
|
|
|
|
### 4.1 Layout da Tela de Chat
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────┐
|
|
│ 💬 Chat │
|
|
├────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌────────────────────────────────────────────────────┐ │
|
|
│ │ 👤 Usuário: como criar uma api em nodejs? │ │
|
|
│ └────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌────────────────────────────────────────────────────┐ │
|
|
│ │ 🤖 ForgeAgent [Modo Agentic] │ │
|
|
│ │ │ │
|
|
│ │ Vou criar um guia completo para você! │ │
|
|
│ │ │ │
|
|
│ │ ┌──────────────────────────────────────────────┐ │ │
|
|
│ │ │ 📋 Plano de Execução (4 passos) [░░░░] │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ │ ✅ 1. Configurar ambiente │ │ │
|
|
│ │ │ ├── Instalar Node.js │ │ │
|
|
│ │ │ └── Verificar versão │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ │ ⏯️ 2. Inicializar projeto (executando...) │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ │ ⏳ 3. Instalar dependências │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ │ ⏳ 4. Criar endpoints │ │ │
|
|
│ │ └──────────────────────────────────────────────┘ │ │
|
|
│ │ │ │
|
|
│ │ ✅ Projeto inicializado com sucesso! │ │
|
|
│ │ │ │
|
|
│ │ 📄 api-nodejs-guide.md [⬇️] │ │
|
|
│ └────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌────────────────────────────────────────────────────┐ │
|
|
│ │ [🛠️ Modo Agentic] [ ] [➤] │ │
|
|
│ └────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 4.2 Estados Visuais
|
|
|
|
#### Step - Pending
|
|
```
|
|
⏳ Título da tarefa
|
|
Descrição curta
|
|
```
|
|
|
|
#### Step - Running
|
|
```
|
|
⏯️ Título da tarefa
|
|
[==========> ] 60%
|
|
Descrição curta
|
|
```
|
|
|
|
#### Step - Completed
|
|
```
|
|
✅ Título da tarefa
|
|
Descrição curta
|
|
└── Sub-step 1
|
|
└── Sub-step 2
|
|
```
|
|
|
|
#### Step - Error
|
|
```
|
|
❌ Título da tarefa
|
|
⚠️ Erro: mensagem de erro
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Prompt Engineering
|
|
|
|
### 5.1 System Prompt
|
|
|
|
```markdown
|
|
Você é o ForgeAgent, um assistente especializado em criar planos estruturados e executáveis.
|
|
|
|
SUA TAREFA:
|
|
1. Analisar a solicitação do usuário
|
|
2. Criar um plano passo a passo detalhado
|
|
3. Retornar APENAS um objeto JSON válido no formato especificado
|
|
|
|
REGRAS:
|
|
- NUNCA adicione texto fora do JSON
|
|
- Sempre divida tarefas complexas em passos claros
|
|
- Cada passo deve ter 2-5 sub-passos quando aplicável
|
|
- Use linguagem clara e direta
|
|
- O overview deve ter no máximo 2 frases
|
|
|
|
FORMATO JSON OBRIGATÓRIO:
|
|
{
|
|
"title": "Título do plano (máx 50 caracteres)",
|
|
"overview": "Breve descrição do que será feito",
|
|
"steps": [
|
|
{
|
|
"id": 1,
|
|
"title": "Título do passo",
|
|
"description": "Descrição detalhada",
|
|
"status": "pending",
|
|
"sub_steps": [
|
|
{
|
|
"id": "1.1",
|
|
"description": "Sub-tarefa específica",
|
|
"status": "pending"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 5.2 Few-Shot Example
|
|
|
|
**Input:** "como fazer uma api em nodejs"
|
|
|
|
**Output:**
|
|
```json
|
|
{
|
|
"title": "Criar API Node.js",
|
|
"overview": "Vamos criar uma API REST completa usando Express.js com estrutura profissional.",
|
|
"steps": [
|
|
{
|
|
"id": 1,
|
|
"title": "Configurar ambiente",
|
|
"description": "Preparar o ambiente de desenvolvimento",
|
|
"status": "pending",
|
|
"sub_steps": [
|
|
{"id": "1.1", "description": "Verificar instalação do Node.js", "status": "pending"},
|
|
{"id": "1.2", "description": "Instalar npm/yarn", "status": "pending"}
|
|
]
|
|
},
|
|
{
|
|
"id": 2,
|
|
"title": "Inicializar projeto",
|
|
"description": "Criar estrutura base do projeto",
|
|
"status": "pending",
|
|
"sub_steps": [
|
|
{"id": "2.1", "description": "Criar diretório do projeto", "status": "pending"},
|
|
{"id": "2.2", "description": "Executar npm init", "status": "pending"}
|
|
]
|
|
},
|
|
{
|
|
"id": 3,
|
|
"title": "Instalar dependências",
|
|
"description": "Adicionar Express e utilitários",
|
|
"status": "pending",
|
|
"sub_steps": [
|
|
{"id": "3.1", "description": "Instalar express", "status": "pending"},
|
|
{"id": "3.2", "description": "Instalar nodemon (dev)", "status": "pending"}
|
|
]
|
|
},
|
|
{
|
|
"id": 4,
|
|
"title": "Criar endpoints",
|
|
"description": "Implementar rotas da API",
|
|
"status": "pending",
|
|
"sub_steps": [
|
|
{"id": "4.1", "description": "Criar servidor Express", "status": "pending"},
|
|
{"id": "4.2", "description": "Adicionar rota GET /", "status": "pending"},
|
|
{"id": "4.3", "description": "Adicionar rota POST /api/data", "status": "pending"}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. API & Eventos
|
|
|
|
### 6.1 Commands (Tauri)
|
|
|
|
```rust
|
|
#[tauri::command]
|
|
async fn generate_agent_plan(
|
|
request: AgentPlanRequest,
|
|
) -> Result<AgentPlan, String> {
|
|
// Implementation
|
|
}
|
|
|
|
#[tauri::command]
|
|
async fn execute_plan_step(
|
|
plan_id: String,
|
|
step_id: u32,
|
|
) -> Result<StepResult, String> {
|
|
// Implementation
|
|
}
|
|
```
|
|
|
|
### 6.2 Events (Tauri)
|
|
|
|
```typescript
|
|
// Frontend listening
|
|
listen('forgeagent:plan-started', (event) => {
|
|
const { plan_id, title, total_steps } = event.payload;
|
|
// Update UI
|
|
});
|
|
|
|
listen('forgeagent:step-started', (event) => {
|
|
const { plan_id, step_id, title } = event.payload;
|
|
// Update step status to "running"
|
|
});
|
|
|
|
listen('forgeagent:step-completed', (event) => {
|
|
const { plan_id, step_id, message } = event.payload;
|
|
// Update step status to "completed"
|
|
// Insert system message
|
|
});
|
|
|
|
listen('forgeagent:artifact-ready', (event) => {
|
|
const { plan_id, artifact } = event.payload;
|
|
// Show artifact viewer
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Estados e Transições
|
|
|
|
```
|
|
┌─────────────┐
|
|
│ IDLE │
|
|
└──────┬──────┘
|
|
│ trigger detected
|
|
▼
|
|
┌─────────────┐
|
|
┌──────────│ PLANNING │◄─────────┐
|
|
│ └──────┬──────┘ │
|
|
│ │ plan generated │
|
|
│ ▼ │
|
|
│ ┌─────────────┐ │
|
|
│ │ EXECUTING │──────────┘
|
|
│ └──────┬──────┘ (next step)
|
|
│ │
|
|
│ ▼
|
|
│ ┌─────────────┐
|
|
└──────────│ COMPLETED │
|
|
(all steps done) └─────────────┘
|
|
│
|
|
▼
|
|
┌─────────────┐
|
|
│ ARTIFACT │
|
|
│ READY │
|
|
└─────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Considerações de Performance
|
|
|
|
### 8.1 Modelo Recomendado
|
|
- **ForgeSteel 4B:** Para planos complexos (5+ passos)
|
|
- **ForgeIron 2B:** Para planos simples (2-4 passos)
|
|
- **ForgeCopper 0.8B:** Não recomendado para geração de planos
|
|
|
|
### 8.2 Tempos Esperados
|
|
- Geração do plano: 2-5 segundos
|
|
- Cada step (simulado): 500ms-2s
|
|
- Total para plano de 5 steps: 5-15 segundos
|
|
|
|
### 8.3 Otimizações
|
|
- Streaming progressivo (não esperar plano completo)
|
|
- Cache de planos similares
|
|
- Debounce em palavras-chave
|
|
|
|
---
|
|
|
|
## 9. Testes
|
|
|
|
### 9.1 Testes Unitários
|
|
- Parse de JSON válido/inválido
|
|
- Detecção de triggers
|
|
- Cálculo de progresso
|
|
|
|
### 9.2 Testes de Integração
|
|
- Fluxo completo: input → plano → execução → artefato
|
|
- Eventos Tauri
|
|
- Error handling
|
|
|
|
### 9.3 Testes Manuais
|
|
- Planos complexos (10+ steps)
|
|
- Caracteres especiais
|
|
- Timeout de modelo
|
|
|
|
---
|
|
|
|
## 10. Referências
|
|
|
|
- [Manus 1.6 Lite UI Reference](manus-reference.png)
|
|
- [Structured Output - llama.cpp](https://github.com/ggerganov/llama.cpp/blob/master/examples/main/README.md#grammar)
|
|
- [Tauri Events](https://tauri.app/v1/guides/features/events/)
|
|
|
|
---
|
|
|
|
## Histórico de Revisões
|
|
|
|
| Versão | Data | Autor | Mudanças |
|
|
|--------|------|-------|----------|
|
|
| 1.0 | 2025-04-02 | ForgeLM Team | Versão inicial |
|
|
|
|
---
|
|
|
|
## Aprovações
|
|
|
|
- [ ] Tech Lead
|
|
- [ ] Product Manager
|
|
- [ ] QA Lead
|