ZealBot：约 85 个 slash command 的多服务器 Discord 机器人

Bot Discord multi-server (ZealBot) con ~85 slash command, moduli attivabili per guild, dashboard web e un Commander centrale (cervello: gate, timeout, circuit-breaker, Guardian).

Self-hostabile · MIT · Dashboard stile MEE6 · Commander + sistema immunitario

Perché è diverso

Commander (cervello) — unico ingresso: toggle per server, esecuzione isolata, un modulo rotto non spegne gli altri
Guardian (immunità) — score salute per modulo/guild, quarantena consigliata, recovery; niente LLM nel hot path
AI plug-and-play — una chiave (Groq, Gemini, OpenAI, …) oppure endpoint free; brain/skill per guild
Ticket professionali — claim, transcript, priorità, SLA, rating
Moderazione seria — warn con escalation, lockdown con snapshot permessi, registro casi
Dashboard web — OAuth2 Discord, griglia server, moduli configurabili, overview attività

Supporta il progetto

Se il bot ti è utile, una donazione aiuta hosting, tempo di sviluppo e nuove feature.


Donazione libera (Stripe)	Apri Payment Link →
Importo a scelta (EUR)	minimo 1 € · preset 5 €

Nota: il link attuale è sul Stripe Sandbox (livemode: false) collegato a questo account. Per donazioni reali crea lo stesso prodotto/Payment Link in Live mode dalla Dashboard Stripe e sostituisci l’URL qui e in .github/FUNDING.yml.

Altri modi di aiutare: ★ star al repo · issue e PR · feedback sulla dashboard.

Sponsor

Aziende o community che vogliono sponsorizzare hosting / feature prioritarie: aprite una issue con titolo Sponsor oppure usate il link Stripe sopra.

Grazie a chi supporta già il progetto 💚

Avvio rapido

git clone https://github.com/zema-tech/zealbot-discord.git
cd zealbot-discord
npm install
cp .env.example .env   # DISCORD_TOKEN + CLIENT_ID
node deploy-commands.js
npm start

Bot + dashboard Express (src/dashboard): usa npm come sopra. La dashboard Next.js in apps/dashboard usa dipendenze workspace:* (Bun/pnpm): non fare solo npm install in root se stai sviluppando quel path — vedi docs/HOSTING.md.

npm test   # smoke senza token: comandi, eventi, commander, DB

Indice

Sezione	Contenuto
Supporta	Donazioni Stripe · sponsor
Architettura	Cervello → muscoli → Guardian
Funzionalità	Panoramica per area
Requisiti	Node, intents
Variabili	Env minime
Dashboard	OAuth2 e avvio
Hosting	Render, Docker, VPS
Docs	CONFIG · COMMANDS · HOSTING · PLAN

Architettura

        Dashboard / Discord / MCP   (nervi)
                    │
                    ▼
            ┌───────────────┐
            │   COMMANDER   │  cervello: gate, dispatch, config
            │  + Guardian   │  immunità: score, quarantine hint
            └───────┬───────┘
                    │
     ┌──────────────┼──────────────┐
     ▼              ▼              ▼
  moduli        dashboard        eventi
  (muscoli)     (muscoli)        (muscoli)

I moduli non si chiamano tra loro: solo tramite Commander
Toggle on/off per server (default ON)
Config dashboard: la UI valida, il Commander esegue
Guardian osserva ok/fail/timeout e espone guardianSummary(guildId)
Core tipizzato: packages/commander (TypeScript) + bridge in src/modules/commander.js

Funzionalità (sintesi)

Area	Esempi
Moderazione	ban, kick, timeout, warn, clear, lockdown, casi
Economia	balance, daily, bank, shop, lotteria, rob, slots
Livelli	XP chat/vocale, rank, top, ruoli premio
Ticket	pannello, claim, transcript, priorità, SLA, rating
AI	/chiedi, riassumi, brain/skill, provider auto
Agenti	/jarvis + specialisti in sandbox, control-room live (docs/AGENTS.md)
Utility	welcome, automod, starboard, reaction roles, giveaway…
Musica	/musica (play, coda, skip, loop…)

Dettaglio comandi → docs/COMMANDS.md.

Requisiti

Node.js 22+ (richiesto da package.json; consigliato Node 24 per @discordjs/voice e DB_BACKEND=sqlite)
Intents: Guilds, GuildMessages, Message Content, Server Members, GuildModeration
App Discord: token + Client ID

Variabili essenziali

Variabile	Ruolo
`DISCORD_TOKEN`	Token bot
`CLIENT_ID`	Deploy comandi
`GUILD_ID`	Opzionale: un solo server di test
`DB_BACKEND`	`json` (default) o `sqlite`
`CLIENT_SECRET` · `SESSION_SECRET` · `BASE_URL`	Dashboard OAuth2
`DASHBOARD_AUDIT_LOG`	Opzionale: path audit log dashboard
`GROQ_API_KEY` / `GEMINI_API_KEY` / …	AI (opzionale)

Completo → docs/CONFIG.md · .env.example.

Dashboard web

Developer Portal → OAuth2 → redirect <BASE_URL>/callback (scope identify guilds)
Env: DASHBOARD_PORT, SESSION_SECRET, CLIENT_SECRET, BASE_URL
Avvio:

npm start            # bot
npm run dashboard    # pannello Express (stesso .env / DB)

Serve Gestisci Server + bot presente nella guild.

Griglia server (Entra / Invita) · moduli a categorie · Welcome a sezioni · overview 7/14/30.

Hosting

docs/HOSTING.md — Docker, PM2, Render, Railway, VPS.

Health: GET /healthz → ok, guilds, commands, backend.

Struttura

src/commands/          slash per categoria
src/events/            listener Discord
src/modules/           descrittori + commander bridge
src/database/          json / sqlite
src/dashboard/         Express + UI (produzione tipica)
apps/dashboard/        Next.js opzionale (Bun/pnpm, workspace:*)
packages/commander/    core TS (gate, breaker, guardian)
docs/                  CONFIG, COMMANDS, HOSTING
.github/FUNDING.yml    link donazioni (Sponsor button)

npm run dev
npm run build:commander   # dopo modifiche a packages/commander
npm test

Licenza

MIT — contributi e issue benvenuti.