82 lines
2.9 KiB
Markdown
82 lines
2.9 KiB
Markdown
# 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` — техническая спецификация
|