From 123771c9967343dc261836811d13b76a6ce63c13 Mon Sep 17 00:00:00 2001 From: "Rodrigo Rodriguez (Pragmatismo)" Date: Sun, 5 Apr 2026 12:49:15 -0300 Subject: [PATCH] Update AGENTS.md: add data directory structure and testing tools section --- AGENTS.md | 187 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 137 insertions(+), 50 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4a31ed6..21bd1d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,71 @@ - **Bot data:** `/opt/gbo/data` (primary) - **Test web:** `http://localhost:3000` — Login: `http://localhost:3000/suite/auth/login.html` +### 📦 Data Directory Structure + +``` +/opt/gbo/data/ # Fonte original dos bots (production) +├── system/ +│ └── work/ +│ └── {botname}.gbai/ # Código fonte .bas +│ └── {botname}.gbdialog/ +│ └── *.bas # Scripts BASIC originais +│ +./botserver-stack/data/system/work/ # Dev local (symlink ou cópia) +├── {botname}.gbai/ +│ ├── seplagse.gbdialog/ # .bas original +│ └── seplagse/ # .gbkb (KB compilado) +``` + +**Importante:** O botserver_compila `.bas` → `.ast` em tempo de execução. Arquivos `.ast` são gerados automaticamente. + +--- + +## 🧪 Debugging & Testing Tools + +### 🔍 Ver Erros de Execução +```bash +tail -f botserver.log | grep -i "error\|tool" +``` + +### 🧪 Testar Ferramenta Específica + +1. **Identificar o erro no log:** + ```bash + grep -A5 "Tool error" botserver.log + ``` + +2. **Corrigir o arquivo `.bas` na fonte:** + - **Production:** `/opt/gbo/data/system/work/{bot}.gbai/{bot}.gbdialog/{tool}.bas` + - **Dev:** `./botserver-stack/data/system/work/{bot}.gbai/{bot}.gbdialog/{tool}.bas` + +3. **Forçar recompilação (se necessário):** + ```bash + rm ./botserver-stack/data/system/work/{bot}.gbai/{bot}.gbdialog/{tool}.ast + ``` + +4. **Testar novamente no browser:** + ``` + http://localhost:3000/{botname} + ``` + +### ⚠️ Erros Comuns em Scripts BASIC + +| Erro | Causa | Solução | +|------|-------|---------| +| `=== is not a valid operator` | BASIC usa `==`, não `===` | Substituir `===` por `--` em strings | +| `Syntax error` | Erro de sintaxe BASIC | Verificar parênteses, vírgulas | +| `Tool execution failed` | Erro no script | Ver logs para stack trace | + +### 📝 Exemplo: Corrigir Operador Inválido +```bas +# ERRADO (JavaScript syntax): +PRINT "=== RESULTADO ===" + +# CORRETO (BASIC syntax): +PRINT "-- RESULTADO --" +``` + --- ## 🧭 LLM Navigation Guide @@ -167,22 +232,86 @@ CARGO_BUILD_JOBS=1 cargo check -p botserver 2>&1 | tail -200 --- -## 🔄 Reset & Service Management +## 🔄 Modos de Execução -### reset.sh -- Cleans and restarts dev env (3-5 min bootstrap: Vault, PostgreSQL, Valkey, MinIO, Zitadel, LLM) -- May timeout waiting for Zitadel — check `botserver.log` for "Bootstrap process completed!" +O botserver suporta **dois modos** de execução: -### Verify After Reset -✅ PostgreSQL (5432), ✅ Valkey (6379), ✅ BotServer (8080), ✅ BotUI (3000), ✅ No errors in logs +### Modo 1: Local Standalone (sem Docker/Incus) + +O botserver sobe **tudo localmente** (PostgreSQL, Valkey, MinIO, Vault, LLM). + +```bash +cd /home/rodriguez/src/gb/botserver +cargo run -- --install # Instala dependências (PostgreSQL, Valkey, MinIO, etc.) +cargo run # Sobe tudo e inicia o servidor +``` + +**O que acontece:** +- `PackageManager` baixa e extrai binários para `botserver-stack/bin/` +- Cria `botserver-stack/data/pgdata/` com PostgreSQL +- Inicia PostgreSQL na porta 5432 +- Inicia Valkey na porta 6379 +- Inicia MinIO na porta 9100 +- Configura Vault para secrets +- Baixa modelo LLM (llama.cpp) para detecção de anomalias +- Ao final: `http://localhost:8080` + +**Verificar se está rodando:** +```bash +curl http://localhost:8080/health +curl http://localhost:5432 # PostgreSQL +curl http://localhost:6379 # Valkey +``` + +**Testar com Playwright:** +```bash +# Navegar para bot de teste +npx playwright open http://localhost:3000/salesianos +# Ou diretamente +npx playwright open http://localhost:3000/detecta +``` + +### Modo 2: Container (Incus) — Produção + +Os serviços rodam em containers Incus separados. + +```bash +# Subir todos os containers +sudo incus start system tables vault directory drive cache llm vector_db + +# Verificar status +sudo incus list + +# Acessar container system (onde roda botserver) +sudo incus exec system -- bash + +# Ver logs do botserver +sudo incus exec system -- journalctl -u botserver -f +``` + +**Arquitetura de Containers:** + +| Container | Services | Portas | +|-----------|----------|--------| +| system | BotServer, Valkey | 8080, 6379 | +| tables | PostgreSQL | 5432 | +| vault | Vault | 8200 | +| directory | Zitadel | 9000 | +| drive | MinIO | 9100 | +| cache | Valkey (backup) | 6379 | +| llm | llama.cpp | 8081 | +| vector_db | Qdrant | 6333 | + +### reset.sh (Ambiente Local) +```bash +./reset.sh # Limpa e reinicia tudo localmente +``` ### Service Commands ```bash ps aux | grep -E "(botserver|botui)" | grep -v grep curl http://localhost:8080/health ./restart.sh # Restart services -systemctl status|start|stop|restart botserver # systemd management -journalctl -u botserver -f # Follow logs ``` --- @@ -244,28 +373,6 @@ cd .. && git add botserver && git commit -m "Update botserver: " && git pu --- -## 🐛 Debugging - -### Critical Rule -**STOP on ANY error** — identify → fix root cause → verify → then continue. Never restart to "fix" errors. - -### Log Locations -| Component | Log | Prefix | -|-----------|-----|--------| -| botserver | `botserver.log` | — | -| botui | `botui.log` | — | -| drive_monitor | botserver logs | `[drive_monitor]` | -| client errors | botserver logs | `CLIENT:` | - -### Bug Fix Flow -1. Reproduce: `grep -E " E | W " botserver.log | tail -20` -2. Trace data flow backwards through call chain -3. Fix minimal change, search for similar occurrences -4. `cargo check -p botserver` → `./restart.sh` → test → check logs -5. Commit with clear root cause description - ---- - ## 🧪 Testing - **Unit:** per-crate `tests/` or `#[cfg(test)]` modules — `cargo test -p ` @@ -288,26 +395,6 @@ cd .. && git add botserver && git commit -m "Update botserver: " && git pu | system | BotServer + Valkey | 8080/6379 | | tables | PostgreSQL | 5432 | | vault | Vault | 8200 | -| directory | Zitadel | 9000 | -| drive | MinIO | 9100 | -| cache | Valkey | 6379 | -| llm | llama.cpp | 8081 | -| vectordb | Qdrant | 6333 | -| meet | LiveKit | 7880 | -| email | Stalwart | 25/587 | -| alm | Forgejo | **4747** (NOT 3000!) | -| alm-ci | Forgejo Runner | — | -| proxy | Caddy | 80/443 | - -### Container Management (Incus) -```bash -sudo incus list # List all -sudo incus start|stop|restart # Lifecycle -sudo incus exec -- bash # Shell access -sudo incus exec -- systemctl restart -sudo incus snapshot create pre-change-$(date +%Y%m%d%H%M%S) -``` - --- ## 🔑 Core Directives Summary