[2026-06-05] add balda project note

2026-06-05 13:21:03 +06:00
parent 7a0e00cd14
commit 3301e2a994
1 changed files with 81 additions and 0 deletions
@@ -0,0 +1,81 @@
+# Balda (Валера) — AI Worker Bot
+
+Аналог Hermes. Go-сервис: берёт задачи из чата (Telegram или Zulip), запускает AI CLI и отвечает.
+
+## Репо
+
+- Upstream: https://github.com/normahq/balda
+- Fork: https://github.com/mallexxx/balda
+- Local: ~/Developer/balda
+- Ветка: `feat/zulip-transport`
+
+## Архитектура
+
+- NATS JetStream — event bus (embedded)
+- SQLite — состояние (owner, sessions, tasks)
+- Telegram — через polling или webhook
+- Zulip — через outgoing webhook bot
+- Providers: codex, opencode, copilot, gemini, claude (ACP protocol)
+
+## Zulip Integration
+
+Полностью реализована. Webhook-based (не polling).  
+Тип бота: **Outgoing webhook** (не Generic bot).
+
+### Credentials (zulip.qentra.top)
+
+- Bot email: `balda-bot@zulip.qentra.top`
+- API key: `AtC9FypdIl6F0hNICW0lcOzehrVrWhPr`
+- Server URL: `https://zulip.qentra.top`
+- Webhook token: берётся из Settings → Bots → balda-bot → Edit → Token
+
+### Config (env vars)
+
+```
+BALDA_ZULIP_BOT_EMAIL=balda-bot@zulip.qentra.top
+BALDA_ZULIP_API_KEY=AtC9FypdIl6F0hNICW0lcOzehrVrWhPr
+BALDA_ZULIP_SERVER_URL=https://zulip.qentra.top
+BALDA_ZULIP_WEBHOOK_TOKEN=<из настроек бота>
+BALDA_ZULIP_WEBHOOK_ENABLED=true
+```
+
+### Webhook setup в Zulip
+
+1. Settings → Bots → balda-bot → Edit
+2. Bot type: Outgoing webhook
+3. Endpoint URL: `http://<host>:8090/zulip/webhook`
+4. Скопировать token → `BALDA_ZULIP_WEBHOOK_TOKEN`
+
+### Авторизация
+
+После запуска написать боту в DM:
+```
+/start owner=<BALDA_AUTH_TOKEN>
+```
+
+## Реализованные команды (Telegram parity)
+
+| Команда | Статус |
+|---------|--------|
+| `/start owner=<token>` | ✅ |
+| `/start invite=<token>` | ✅ |
+| `/goal <objective>` / `/goal clear` | ✅ |
+| `/topic` | ✅ (создаёт сессию для нового топика) |
+| `/user add <email>` | ✅ |
+| `/user list` | ✅ (с инвайтами + expiry) |
+| Typing indicator | ✅ (isDM-aware: true в DM, false в стримах) |
+| plan_updates / SendDraftPlain | ➖ no-op (нет аналога в Zulip) |
+
+## Upcoming: mention-based thread takeover
+
+Когда `@balda-bot` упоминается в топике без активной сессии — бот автоматически берёт топик под контроль.
+
+Механизм (аналог whale-thread-guard в Hermes):
+- Webhook payload поле `trigger == "mention"` → auto-create session
+- `allowed_owners` список в конфиге: Zulip email без токена
+- После захвата топик отвечает на все сообщения (обычная сессия)
+
+## Docs
+
+- `docs/zulip-webhook.md` — полное руководство по настройке
+- `docs/balda.md` — техническая спецификация