feat(gestao): adiciona plugin gestao (agents, skills, knowledge e metadados do projeto)

2026-10-28 16:08:53 +00:00
parent 7b2162ff29
commit de2d6f2fb5
91 changed files with 13525 additions and 0 deletions
@@ -0,0 +1,186 @@
+---
+name: clip-health
+description: Diagnóstico rápido Paperclip — serviço, BD, heartbeats falhados, budget, disco. Usar quando "clip health", "saúde clip", "diagnóstico paperclip", "clip problemas".
+context: fork
+layer: wiki
+---
+
+# /clip-health — Diagnostico Paperclip
+
+Verificacao rapida da saude do sistema Clip.
+
+## Constantes
+
+```
+BD: PGPASSWORD="paperclip" psql -h localhost -p 54329 -U paperclip -d paperclip
+PAPERCLIP_DIR: /home/ealmeida/paperclip
+INSTANCE_DIR: /home/ealmeida/.paperclip/instances/default
+```
+
+## Procedimento
+
+Executar todas as verificacoes em paralelo, depois apresentar relatorio.
+
+### Check 1: Serviço
+
+```bash
+ps aux | grep -E "paperclip.*src/index|pnpm.*paperclipai" | grep -v grep | head -5
+```
+
+- Processos encontrados = OK
+- Nenhum processo = CRITICO (iniciar com: `cd /home/ealmeida/paperclip && pnpm --filter @paperclipai/server dev`)
+
+Verificar também memória partilhada PostgreSQL (causa do bug POSIX shared memory):
+```bash
+ls /dev/shm/PostgreSQL.* 2>/dev/null && echo "POSIX OK" || echo "POSIX em falta — BD pode falhar ao ligar"
+```
+
+- POSIX OK = OK
+- POSIX em falta + processos activos = AVISO (PostgreSQL perdeu shared memory — reiniciar Paperclip)
+- POSIX em falta + sem processos = CRITICO
+
+### Check 2: Base de dados
+
+Conexao:
+```sql
+SELECT 1 as connected;
+```
+
+Tamanho:
+```sql
+SELECT pg_size_pretty(pg_database_size('paperclip')) as db_size;
+```
+
+Contagens:
+```sql
+SELECT
+  (SELECT COUNT(*) FROM agents WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f') as agentes,
+  (SELECT COUNT(*) FROM issues WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f') as issues,
+  (SELECT COUNT(*) FROM heartbeat_runs hr JOIN agents a ON hr.agent_id = a.id WHERE a.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f') as heartbeats;
+```
+
+- Conexao OK = OK
+- Conexao falha = CRITICO
+
+### Check 3: Heartbeats falhados (24h)
+
+```sql
+SELECT a.name, hr.status, LEFT(hr.error, 70) as erro, hr.started_at::timestamp(0)
+FROM heartbeat_runs hr JOIN agents a ON hr.agent_id = a.id
+WHERE a.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+AND hr.status IN ('failed','error')
+AND hr.started_at > NOW() - INTERVAL '24 hours'
+ORDER BY hr.started_at DESC
+LIMIT 20;
+```
+
+- 0 falhas = OK
+- 1-2 falhas = AVISO
+- 3+ falhas = CRITICO
+
+### Check 4: Budget
+
+```sql
+SELECT name, budget_monthly_cents, spent_monthly_cents,
+  CASE WHEN budget_monthly_cents > 0
+    THEN ROUND(spent_monthly_cents::numeric / budget_monthly_cents * 100, 1)
+    ELSE 0 END as pct
+FROM agents
+WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
+AND budget_monthly_cents > 0
+AND spent_monthly_cents > 0
+ORDER BY pct DESC;
+```
+
+- <80% = OK
+- 80-95% = AVISO
+- >95% = CRITICO
+
+### Check 5: Disco
+
+```bash
+df -h /home/ealmeida/.paperclip/ | tail -1
+```
+
+```bash
+du -sh /home/ealmeida/.paperclip/instances/default/db/ 2>/dev/null
+du -sh /home/ealmeida/.paperclip/instances/default/logs/ 2>/dev/null
+du -sh /home/ealmeida/.paperclip/instances/default/data/ 2>/dev/null
+```
+
+- >30% livre = OK
+- 15-30% livre = AVISO
+- <15% livre = CRITICO
+
+### Check 6: API Health
+
+```bash
+curl -s --max-time 5 http://localhost:3100/health 2>/dev/null || echo "FALHA"
+```
+
+Esperado: `{"status":"ok","version":"...","deploymentMode":"authenticated","bootstrapStatus":"ready"}`
+
+- `status: ok` = OK
+- `{"error":"Board access required"}` = AVISO (API responde mas sem auth — BD operacional)
+- FALHA/timeout = CRITICO (servidor não responde)
+
+### Check 7: Gateway MCPs
+
+```bash
+curl -s --max-time 5 https://gateway.descomplicar.pt/health 2>/dev/null || echo "FALHA"
+```
+
+- Responde = OK
+- Timeout/falha = AVISO
+
+### Check 8: Referencias orfas na BD
+
+Budget policies e incidents a referenciar entidades inexistentes:
+
+Invocar tool MCP: `mcp__paperclip__diag_budget_orphans`
+
+- 0 orfaos = OK
+- 1+ orfaos = CRITICO (causa "Agent not found" no dashboard, apagar com DELETE)
+
+### Check 9: Instancias duplicadas
+
+```bash
+ss -tlnp | grep -E "310[0-9]" | wc -l
+```
+
+- 1 instancia = OK
+- 2+ instancias = CRITICO (processos orfaos do pnpm, matar com `kill -9` os PIDs com PPID=1)
+
+Detalhe dos processos:
+```bash
+ss -tlnp | grep -E "310[0-9]"
+```
+
+### Check 10: Porta vs Cloudflare Tunnel
+
+```bash
+TUNNEL_PORT=$(grep -A1 "clip.descomplicar.pt" ~/.cloudflared/config.yml | grep service | grep -oP ':\K[0-9]+')
+ACTUAL_PORT=$(ss -tlnp | grep -E "310[0-9]" | head -1 | grep -oP ':310[0-9]' | tr -d ':')
+echo "Tunnel: $TUNNEL_PORT | Servidor: $ACTUAL_PORT"
+```
+
+- Iguais = OK
+- Diferentes = CRITICO (tunnel a apontar para porta errada, dashboard inacessivel)
+
+### Check 11: Agentes sem permissoes bash
+
+Invocar tool MCP: `mcp__paperclip__diag_agents_without_skip_permissions`
+
+- 0 = OK
+- 1+ = CRITICO (agentes vao ficar bloqueados ao executar bash — corrigir com `/clip-agent`)
+
+### Check 12: Agentes sem heartbeat
+
+Invocar tool MCP: `mcp__paperclip__diag_agents_missing_heartbeat`
+
+- 0 = OK
+- 1+ = AVISO (agentes nao acordam — podem nao processar issues)
+
+### Check 13: Routine triggers com kind errado ou next_run_at NULL
+
+Invocar tool MCP: `mcp__pap