[2026-06-15] move balda-valera doc to personal/projects/balda/

2026-06-15 20:39:20 +06:00
parent 936246da1b
commit c57ca86d27
1 changed files with 0 additions and 0 deletions
@@ -0,0 +1,62 @@
+# Балда / Валера — эксплуатация
+
+## Расположение
+- Repo: `~/Developer/balda/`
+- **Рабочий compose**: `~/Docker/balda-agent/docker-compose.yaml` → контейнер `balda-agent-valera-1`
+- Config (persistent): `~/Docker/balda-agent/.config/balda/config.yaml`
+- Env: `~/Docker/balda-agent/.env`
+- Дублирующий compose `~/Developer/balda/compose.valera.yaml` — НЕ использовать (сеть `balda_default` без DNS)
+
+## Запуск / рестарт
+```bash
+cd ~/Docker/balda-agent
+docker-compose restart
+
+# Rebuild после изменений в коде:
+docker-compose build && docker-compose up -d
+```
+
+## Архитектура получения сообщений
+Валера — **outgoing webhook bot** (bot_type=3). Zulip отправляет webhook только для @mention и DM.
+
+Для получения всех сообщений в теме — Events API polling (горутина в коде):
+- `events_polling.enabled: true` в config.yaml
+- Очередь регистрируется с `all_public_streams=true`
+- Бот подписывается на все публичные стримы при старте (`SubscribeToPublicStreams`)
+- После @mention создаётся сессия; последующие сообщения без @mention обрабатываются
+
+**После перезапуска**: нужно один раз написать `@Валера <текст>` чтобы создать сессию в теме.
+
+## Диагностика молчания
+1. Проверить логи: `docker logs balda-agent-valera-1 --tail 50`
+2. Проверить что Events API polling запустился: `zulip events queue registered` в логах
+3. Стухший NATS-таск (симптом: логов нет после @mention)  
+   Фикс: `docker-compose restart` (NATS embedded, состояние в памяти)
+4. Бот не подписан на стримы (симптом: `processing zulip message trigger=stream` не появляется):
+   ```bash
+   curl -u "<bot_email>:<api_key>" https://zulip.qentra.top/api/v1/users/me/subscriptions
+   ```
+   Если пустой — должен подписаться при следующем старте. Или вручную через API.
+
+## Патчи в коде (общие с Клавдием)
+
+В `zulip_handler.go` добавлены:
+1. `botName` — извлекается из bot_email (часть до @). Используется чтобы отличить свой @mention от чужого.
+2. `extractOtherMention()` — проверяет текст на @**Name**, где Name не равен botName и не @**all**/@**everyone**. Если найден чужой @mention — сообщение игнорируется.
+3. Детальное логирование в `handleAutoClaimMention` — видны все шаги от входа до ошибки.
+
+## Конфигурация провайдера
+В `config.yaml` обязательно:
+```yaml
+balda:
+  provider: deepseek
+  zulip:
+    events_polling:
+      enabled: true
+    stream_only_with_session: true
+runtime:
+  providers:
+    deepseek:
+      openai:
+        base_url: https://api.deepseek.com/v1
+```