476 lines
14 KiB
Markdown
476 lines
14 KiB
Markdown
# Fase 4: OpenClaw Embutido — Plano de Implementação
|
|
|
|
**Fase:** 4
|
|
**Data Início:** 2026-03-26
|
|
**Prazo:** 2026-04-08 (Semanas 7-8)
|
|
**Status:** 🔄 Sprint 3 Pendente (Sprint 1 e 2 concluídos)
|
|
|
|
---
|
|
|
|
## 1. OBJETIVO DA FASE
|
|
|
|
Implementar **detecção proativa de padrões** e **sugestão emergente de skills**, transformando comportamentos repetitivos do usuário em automações reutilizáveis através de um widget conversacional flutuante.
|
|
|
|
### Entregável Final
|
|
✅ Skills emergentes funcionando end-to-end:
|
|
- Usuário executa ação repetida → PatternDetector detecta → OpenClawWidget sugere → Blackboard gera DRAFT → Dev Center aprova → Skill disponível
|
|
|
|
---
|
|
|
|
## 2. ARQUITETURA
|
|
|
|
```
|
|
FLUXO OPENCCLAW:
|
|
|
|
1. USER INTERACTION
|
|
└─ Usuário usa Arcádia
|
|
└─ Learning API registra evento (já existe)
|
|
└─ Neo4j armazena interação
|
|
|
|
2. PATTERN DETECTION (NOVO)
|
|
└─ PatternDetector analisa Learning API
|
|
└─ Identifica: 3+ ocorrências em 30 dias
|
|
└─ Calcula confiança (threshold 0.8+)
|
|
└─ Dispara evento no Socket.IO
|
|
|
|
3. WIDGET SUGGESTION (NOVO)
|
|
└─ OpenClawWidget fica "ouvindo"
|
|
└─ Recebe evento de padrão detectado
|
|
└─ Exibe notificação flutuante
|
|
└─ Modal SkillSuggestion mostra preview
|
|
|
|
4. SKILL GENERATION (NOVO)
|
|
└─ Usuário confirma
|
|
└─ OpenClawEngine chama Blackboard
|
|
└─ Blackboard gera código (DRAFT)
|
|
└─ Armazena em database
|
|
|
|
5. APPROVAL FLOW (EXISTENTE - Dev Center)
|
|
└─ Skill DRAFT aparece em Dev Center
|
|
└─ Admin/Lead revisa e aprova
|
|
└─ Publica no tenant
|
|
└─ Skill fica disponível para reutilização
|
|
```
|
|
|
|
### Componentes para Implementar
|
|
|
|
```
|
|
BACKEND:
|
|
server/modules/openclaw/
|
|
├── PatternDetector.ts ← [NOVO] Detecta padrões
|
|
├── SkillEmergence.ts ← [NOVO] Coordena criação
|
|
├── OpenClawEngine.ts ← [NOVO] Lógica central
|
|
├── config/
|
|
│ └── arcadia.config.yaml ← [NOVO] Configuração
|
|
|
|
FRONTEND:
|
|
client/src/components/openclaw/
|
|
├── OpenClawWidget.tsx ← [NOVO] Widget flutuante
|
|
├── PatternDetector.ts ← [NOVO] Hook de detecção
|
|
├── SkillSuggestion.tsx ← [NOVO] Modal de sugestão
|
|
└── useAgentEmergence.ts ← [NOVO] Lógica de emergência
|
|
```
|
|
|
|
---
|
|
|
|
## 3. DEPENDÊNCIAS VERIFICADAS
|
|
|
|
| Componente | Status | Localização |
|
|
|-----------|--------|-----------|
|
|
| **Skills Engine** | ✅ Pronto | `server/skills/engine.ts` |
|
|
| **Blackboard** | ✅ Pronto | `server/blackboard/service.ts` |
|
|
| **Dev Center** | ✅ Pronto | `client/src/pages/DevCenter.tsx` |
|
|
| **Learning API** | ✅ Existe | `/api/learning/*` |
|
|
| **Neo4j (KG)** | ✅ Running | Docker |
|
|
| **Socket.IO** | ✅ Configurado | `server/socket-io.ts` |
|
|
| **PostgreSQL** | ✅ Rodando | Docker |
|
|
| **Scientist (MiroFlow)** | ✅ Existe | `/api/manus/scientist/*` |
|
|
|
|
**Conclusão:** Todas as dependências estão prontas ✅
|
|
|
|
---
|
|
|
|
## 4. TASKS DETALHADAS
|
|
|
|
### SPRINT 1 (26-27/03): PatternDetector Backend — ✅ COMPLETO
|
|
|
|
#### Task 1.1: Criar PatternDetector.ts ✅
|
|
**Arquivo:** `server/modules/openclaw/PatternDetector.ts`
|
|
**Objetivo:** Analisar eventos de usuário e detectar padrões
|
|
|
|
```typescript
|
|
// Pseudocódigo da estrutura
|
|
export class PatternDetector {
|
|
// Config
|
|
min_occurrences: 3;
|
|
time_window_days: 30;
|
|
confidence_threshold: 0.8;
|
|
|
|
// Métodos
|
|
detectPattern(userId: string, action: string): Pattern | null
|
|
calculateConfidence(interactions: Interaction[]): number
|
|
storePattern(pattern: Pattern): Promise<void>
|
|
emitEvent(pattern: Pattern): void
|
|
}
|
|
```
|
|
|
|
**Entrada:** Eventos do Learning API (`/api/learning/interactions`)
|
|
**Saída:** Pattern objects armazenados em Neo4j + Socket.IO event
|
|
**Dependência:** Learning API funcionando ✅
|
|
|
|
#### Task 1.2: Criar OpenClawEngine.ts ✅
|
|
**Arquivo:** `server/modules/openclaw/OpenClawEngine.ts`
|
|
**Objetivo:** Orquestração central de OpenClaw
|
|
|
|
```typescript
|
|
export class OpenClawEngine {
|
|
patternDetector: PatternDetector;
|
|
skillEmergence: SkillEmergence;
|
|
|
|
// Métodos
|
|
async suggestSkill(pattern: Pattern): Promise<SkillSuggestion>
|
|
async onUserConfirmation(suggestion: SkillSuggestion): Promise<Skill>
|
|
async checkPatternsPeriodicly(): Promise<void>
|
|
}
|
|
```
|
|
|
|
**Entrada:** Padrões detectados
|
|
**Saída:** Sugestões + Skills gerados
|
|
**Evento:** Socket.IO broadcast `/openclaw/pattern-detected`
|
|
|
|
#### Task 1.3: Criar SkillEmergence.ts ✅
|
|
**Arquivo:** `server/modules/openclaw/SkillEmergence.ts`
|
|
**Objetivo:** Integração com Blackboard para codegen
|
|
|
|
```typescript
|
|
export class SkillEmergence {
|
|
async generateSkillDraft(pattern: Pattern): Promise<SkillDraft> {
|
|
// 1. Montar prompt baseado no padrão
|
|
// 2. Chamar POST /api/blackboard/generate-skill
|
|
// 3. Receber código gerado
|
|
// 4. Salvar como DRAFT no database
|
|
// 5. Notificar Dev Center
|
|
// 6. Retornar skill DRAFT
|
|
}
|
|
}
|
|
```
|
|
|
|
**Integração:** POST `/api/blackboard/generate-skill`
|
|
**Database:** skills table (com status: 'draft')
|
|
|
|
#### Task 1.4: Criar rotas OpenClaw ✅
|
|
**Arquivo:** `server/modules/openclaw/routes.ts`
|
|
**Rotas:**
|
|
```
|
|
POST /api/openclaw/detect-patterns ← Trigger manual de análise
|
|
GET /api/openclaw/patterns ← Listar padrões detectados
|
|
POST /api/openclaw/confirm-skill ← Usuário confirma sugestão
|
|
GET /api/openclaw/suggestions ← Histórico de sugestões
|
|
```
|
|
|
|
#### Task 1.5: Integrar em server/index.ts ✅
|
|
**Arquivo:** `server/index.ts`
|
|
**Ação:** Importar rotas OpenClaw e carregá-las
|
|
|
|
```typescript
|
|
import openclawRoutes from "./modules/openclaw/routes";
|
|
app.use("/api/openclaw", openclawRoutes);
|
|
```
|
|
|
|
### SPRINT 2 (28-29/03): Frontend Widgets — ✅ COMPLETO (commit 5231166)
|
|
|
|
#### Task 2.1: Criar OpenClawWidget.tsx ✅
|
|
**Arquivo:** `client/src/components/openclaw/OpenClawWidget.tsx`
|
|
**Objetivo:** Widget flutuante que recebe notificações de padrões
|
|
|
|
```typescript
|
|
export function OpenClawWidget() {
|
|
// Escutar Socket.IO event: /openclaw/pattern-detected
|
|
// Exibir notificação flutuante (canto inferior direito)
|
|
// Mostrar padrão detectado
|
|
// Botão "Ver Sugestão" abre modal
|
|
// Botão "Ignorar" descarta
|
|
|
|
return (
|
|
<div className="fixed bottom-4 right-4">
|
|
{/* Widget flutuante */}
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
**Socket.IO:** Escuta evento `/openclaw/pattern-detected`
|
|
**Trigger:** Modal SkillSuggestion
|
|
|
|
#### Task 2.2: Criar SkillSuggestion.tsx ✅
|
|
**Arquivo:** `client/src/components/openclaw/SkillSuggestion.tsx`
|
|
**Objetivo:** Modal com preview da skill sugerida
|
|
|
|
```typescript
|
|
export function SkillSuggestion({ pattern, suggestion }) {
|
|
// Modal mostra:
|
|
// 1. "Detectamos um padrão na sua utilização:"
|
|
// 2. Preview do padrão (ações repetidas)
|
|
// 3. Preview da automação gerada
|
|
// 4. Campo de nome (auto-preenchido)
|
|
// 5. Descrição (auto-gerada)
|
|
// 6. Botão "Criar Skill" ou "Cancelar"
|
|
|
|
const handleCreate = async () => {
|
|
// POST /api/openclaw/confirm-skill
|
|
// Esperar resposta (skill DRAFT)
|
|
// Toast: "Skill criada! Vá para Dev Center para publicar"
|
|
};
|
|
}
|
|
```
|
|
|
|
**Integração:** Chama `POST /api/openclaw/confirm-skill`
|
|
**Feedback:** Toast notification
|
|
|
|
#### Task 2.3: Hook useAgentEmergence.ts ✅
|
|
**Arquivo:** `client/src/hooks/useAgentEmergence.ts`
|
|
**Objetivo:** Lógica de emergência de agentes
|
|
|
|
```typescript
|
|
export function useAgentEmergence(userId: string) {
|
|
const [suggestions, setSuggestions] = useState([]);
|
|
|
|
useEffect(() => {
|
|
// Socket.IO listener
|
|
socket.on("openclaw:pattern-detected", (pattern) => {
|
|
// Filtrar por tenant, user prefs
|
|
// Atualizar suggestions state
|
|
setSuggestions([...suggestions, pattern]);
|
|
});
|
|
}, []);
|
|
|
|
return { suggestions, dismiss, confirm };
|
|
}
|
|
```
|
|
|
|
#### Task 2.4: Integrar Widget em layout principal ✅
|
|
**Arquivo:** `client/src/App.tsx` ou `client/src/layouts/MainLayout.tsx`
|
|
**Ação:** Adicionar OpenClawWidget ao layout persistente
|
|
|
|
```typescript
|
|
import { OpenClawWidget } from "@/components/openclaw/OpenClawWidget";
|
|
|
|
export default function App() {
|
|
return (
|
|
<>
|
|
{/* Conteúdo existente */}
|
|
<OpenClawWidget /> {/* ← Adicionar aqui */}
|
|
</>
|
|
);
|
|
}
|
|
```
|
|
|
|
### SPRINT 3 (30-31/03): Configuração e Integração — ⏳ PRÓXIMO
|
|
|
|
#### Task 3.1: Criar arcadia.config.yaml
|
|
**Arquivo:** `server/modules/openclaw/config/arcadia.config.yaml`
|
|
|
|
```yaml
|
|
openclaw:
|
|
enabled: true
|
|
|
|
# Endpoints
|
|
arcadia_api_url: http://localhost:3000/api
|
|
arcadia_kg_url: http://localhost:7474
|
|
blackboard_url: http://localhost:3000/api/blackboard
|
|
|
|
# Tenant awareness
|
|
tenant_aware: true
|
|
|
|
# Detecção de padrões
|
|
pattern_detection:
|
|
enabled: true
|
|
min_occurrences: 3
|
|
time_window_days: 30
|
|
confidence_threshold: 0.8
|
|
scheduled_check_interval_minutes: 60
|
|
|
|
# Sugestões
|
|
suggestions:
|
|
enabled: true
|
|
auto_suggest: false # Sempre pedir confirmação do usuário
|
|
channels: ['widget', 'chat']
|
|
priority_threshold: 0.85
|
|
|
|
# Skills emergentes
|
|
emergence:
|
|
create_as_draft: true # Sempre requer aprovação
|
|
auto_publish: false
|
|
notify_admins: true
|
|
skill_prefix: "emergent_" # Prefixo para skills auto-geradas
|
|
|
|
# Logging
|
|
logging:
|
|
enabled: true
|
|
store_patterns: true
|
|
store_in_kg: true
|
|
audit_trail: true
|
|
```
|
|
|
|
#### Task 3.2: Integrar Socket.IO events
|
|
**Arquivo:** `server/socket-io.ts`
|
|
**Ação:** Adicionar listeners e emitters para OpenClaw
|
|
|
|
```typescript
|
|
socket.on("openclaw:confirm-skill", async (data) => {
|
|
// Receber confirmação do usuário
|
|
// Chamar SkillEmergence.generateSkillDraft()
|
|
// Emitir "openclaw:skill-created"
|
|
});
|
|
|
|
// Emitter no PatternDetector
|
|
io.emit("openclaw:pattern-detected", pattern);
|
|
```
|
|
|
|
#### Task 3.3: Database schema para OpenClaw
|
|
**Arquivo:** `shared/schema.ts` (Drizzle ORM)
|
|
**Adicionar tabelas:**
|
|
|
|
```typescript
|
|
// Padrões detectados
|
|
export const detectedPatterns = pgTable("detected_patterns", {
|
|
id: serial().primaryKey(),
|
|
tenant_id: uuid().notNull(),
|
|
user_id: uuid().notNull(),
|
|
action_type: varchar(255).notNull(),
|
|
occurrences: integer().notNull(),
|
|
confidence: numeric(3, 2).notNull(),
|
|
time_window_days: integer().notNull(),
|
|
created_at: timestamp().defaultNow(),
|
|
metadata: jsonb(),
|
|
});
|
|
|
|
// Sugestões geradas
|
|
export const skillSuggestions = pgTable("skill_suggestions", {
|
|
id: serial().primaryKey(),
|
|
pattern_id: integer().references(() => detectedPatterns.id),
|
|
skill_draft_id: uuid().references(() => skills.id),
|
|
status: varchar(50).notNull(), // 'suggested', 'accepted', 'rejected'
|
|
created_at: timestamp().defaultNow(),
|
|
});
|
|
```
|
|
|
|
#### Task 3.4: Migration SQL
|
|
**Arquivo:** `migrations/0004_openclaw_tables.sql`
|
|
|
|
```sql
|
|
CREATE TABLE detected_patterns (
|
|
id SERIAL PRIMARY KEY,
|
|
tenant_id UUID NOT NULL,
|
|
user_id UUID NOT NULL,
|
|
action_type VARCHAR(255) NOT NULL,
|
|
occurrences INTEGER NOT NULL,
|
|
confidence NUMERIC(3,2) NOT NULL,
|
|
time_window_days INTEGER NOT NULL,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
metadata JSONB
|
|
);
|
|
|
|
CREATE TABLE skill_suggestions (
|
|
id SERIAL PRIMARY KEY,
|
|
pattern_id INTEGER REFERENCES detected_patterns(id),
|
|
skill_draft_id UUID REFERENCES skills(id),
|
|
status VARCHAR(50) NOT NULL,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
|
);
|
|
|
|
CREATE INDEX idx_detected_patterns_user_tenant
|
|
ON detected_patterns(user_id, tenant_id);
|
|
```
|
|
|
|
#### Task 3.5: Testes unitários
|
|
**Arquivo:** `tests/openclaw.test.ts`
|
|
- PatternDetector detecta padrão corretamente
|
|
- OpenClawEngine orquestra fluxo correto
|
|
- SkillEmergence integra com Blackboard
|
|
- Socket.IO emite eventos corretamente
|
|
|
|
#### Task 3.6: Documentação
|
|
**Arquivo:** `DOCUMENTATION.md` (adicionar seção)
|
|
- Como OpenClaw funciona
|
|
- Configuração por tenant
|
|
- Troubleshooting
|
|
|
|
---
|
|
|
|
## 5. TIMELINE
|
|
|
|
| Data | Sprint | Tasks | Status |
|
|
|------|--------|-------|--------|
|
|
| 26-27/03 | 1 | PatternDetector backend | ✅ Completo |
|
|
| 26/03 | 2 | OpenClawWidget frontend | ✅ Completo (commit 5231166) |
|
|
| 26/03 | 3 | Migration DB + testes | ⏳ Próximo |
|
|
| 01-08/04 | Buffer | Refinamento, testes E2E | ⏳ Próximo |
|
|
|
|
**Nota:** Trabalho em `/opt/arcadia_merged/` (diretório canônico do projeto).
|
|
|
|
---
|
|
|
|
## 6. CRITÉRIOS DE SUCESSO
|
|
|
|
✅ **PatternDetector funciona:**
|
|
- Detecta padrão após 3 ocorrências em 30 dias
|
|
- Confiança calculada corretamente
|
|
- Eventos emitidos para Socket.IO
|
|
|
|
✅ **OpenClawWidget funciona:**
|
|
- Widget aparece quando padrão é detectado
|
|
- Modal mostra sugestão corretamente
|
|
- Usuário pode confirmar ou rejeitar
|
|
|
|
✅ **SkillEmergence funciona:**
|
|
- Integra com Blackboard
|
|
- Gera skill como DRAFT
|
|
- Aparece em Dev Center para aprovação
|
|
|
|
✅ **E2E funciona:**
|
|
- User faz ação 3x
|
|
- Widget sugere
|
|
- Approva
|
|
- Skill publicada
|
|
- Skill disponível para reutilização
|
|
|
|
---
|
|
|
|
## 7. RISCOS E MITIGAÇÕES
|
|
|
|
| Risco | Probabilidade | Mitigação |
|
|
|-------|--------------|-----------|
|
|
| Blackboard não retorna código correto | Média | Testar integração antes, ter fallback |
|
|
| Padrões detectados incorretamente | Média | Validar threshold, testes no KG |
|
|
| Socket.IO não emite em tempo real | Baixa | Já funciona em outras partes |
|
|
| Performance com muitos eventos | Média | Usar índices em PG, cache em Redis |
|
|
|
|
---
|
|
|
|
## 8. BRANCH E COMMITS
|
|
|
|
**Branch:** `Servidor` (deploy branch, conforme feedback anterior)
|
|
**Commit pattern:**
|
|
```
|
|
feat(openclaw): PatternDetector backend
|
|
feat(openclaw): OpenClawWidget frontend
|
|
feat(openclaw): Integração Blackboard + esquema DB
|
|
docs(openclaw): Documentação e testes
|
|
```
|
|
|
|
---
|
|
|
|
## 9. PRÓXIMAS AÇÕES
|
|
|
|
1. ✅ **26/03:** Sprint 1 concluído (PatternDetector, OpenClawEngine, SkillEmergence, routes, config)
|
|
2. ✅ **26/03:** Sprint 2 concluído (OpenClawWidget, SkillSuggestion, useAgentEmergence, App.tsx — commit 5231166)
|
|
3. ⏳ **Agora:** Sprint 3 — migration SQL + vitest + testes unitários em `/opt/arcadia_merged/`
|
|
4. ⏳ **01-08/04:** Refinamento e testes E2E
|
|
|
|
---
|
|
|
|
*Fase 4: OpenClaw Embutido — Plano Executável*
|
|
*Data: 2026-03-26*
|
|
*Pronto para implementação ✅*
|