Update AGENTS.md: add data directory structure and testing tools section
This commit is contained in:
parent
f767337ed8
commit
123771c996
1 changed files with 137 additions and 50 deletions
187
AGENTS.md
187
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: <desc>" && 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 <crate>`
|
||||
|
|
@ -288,26 +395,6 @@ cd .. && git add botserver && git commit -m "Update botserver: <desc>" && 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 <container> # Lifecycle
|
||||
sudo incus exec <container> -- bash # Shell access
|
||||
sudo incus exec <container> -- systemctl restart <service>
|
||||
sudo incus snapshot create <container> pre-change-$(date +%Y%m%d%H%M%S)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Core Directives Summary
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue