228 lines
13 KiB
Markdown
Executable File
228 lines
13 KiB
Markdown
Executable File
# Balda — историческая карточка и шаблоны до 2026-10-14
|
||
|
||
> [!WARNING] Архив
|
||
> Эти сведения и инструкции относятся к прежним версиям. Они не описывают текущий запуск и не применяются автоматически.
|
||
> Актуальные карточки: [[personal/projects/balda/balda|Balda]], [[personal/projects/balda/setup|runbook]], [[personal/projects/balda/execution-broker|Broker и приёмка]].
|
||
> Старые PR #8 и #12 уже merged. Литералы старых credentials заменены ссылкой на приватное хранилище.
|
||
|
||
## Карточка Balda до актуализации
|
||
|
||
> **Актуальный статус — 2026-10-03.** Mattermost-интеграция PR #8 уже в upstream. [PR #12](https://github.com/baldaworks/balda/pull/12) по маршрутизации webhook открыт на `73e02156`: 8/8 GitHub checks прошли; повторное ревью после исправления запрошенных изменений ещё ожидается. Balda запущена из чистого текущего HEAD PR `73e02156`, и хеш бинарника в контейнере совпадает с собранным артефактом. Ревьюер запросил изменения в PR #12 из-за 404 при временном сбое lookup session. Исправление `73e02156` уже отправлено: теперь ответ 503, добавлен HTTP-тест; локальные race tests и lint прошли, все 8 checks нового HEAD прошли. До повторного сквозного прогона merge/release — NO-GO. Прежний вывод о другом SHA был ошибкой: `d094943b` относился к внешнему репозиторию Broker, а `deepseekfix` был старой меткой образа. Локальных правок кода Balda в текущем бинарнике нет; новый сквозной прогон ещё нужен. Приёмочный Broker run `run-fbe2cb459fe2965554402aba1bd5fcd0` прошёл; Mattermost отправил апрув и финал в исходный тред. Результат `4dafb9d` был доставлен в `go-cli-test` вручную через Broker API: Balda пропустила автоматическую публикацию. Broker теперь сам проверяет commit/quality/bundle без обязательного SHA от Balda; webhook и плагин rc.19 требуют публикацию до закрытия Story. Новый end-to-end прогон ещё не проведён. Общий release — NO-GO. Детали и текущие проверки: [[personal/plans/balda-callee-prism-plan]]. Ниже сохранена историческая документация; старые статусы PR и конфигурации не являются текущими.
|
||
|
||
Аналог Hermes. Go-сервис: берёт задачи из чата (Telegram или Zulip), запускает AI CLI и отвечает.
|
||
|
||
## Репо
|
||
|
||
- Upstream: https://github.com/baldaworks/balda (старое имя `normahq/balda` — редирект)
|
||
- Fork: https://github.com/mallexxx/balda
|
||
- Local: ~/Developer/balda
|
||
- Ветка: `feat/mattermost-channel` (PR [#8](https://github.com/baldaworks/balda/pull/8), OPEN, 8/8 CI, MERGEABLE)
|
||
|
||
### 🔴 Два репозитория — не путать
|
||
|
||
| Репо | Что там | PR |
|
||
|---|---|---|
|
||
| **`baldaworks/balda`** | сам бот, транспорты (Mattermost, Zulip) | [#8](https://github.com/baldaworks/balda/pull/8) Mattermost, OPEN · [#1](https://github.com/baldaworks/balda/pull/1) Zulip, merged |
|
||
| **`normahq/runtime`** | библиотека рантайма (`agentfactory`, `hostedagent`) | [#5](https://github.com/normahq/runtime/pull/5) фикс MCP-тулинга, OPEN · **`CHANGES_REQUESTED`** (3 дефекта, план — [[personal/plans/runtime-pr5-toolset-dedup-review-fixes]]) · [#4](https://github.com/normahq/runtime/pull/4) OpenAI tool_calls, OPEN (4 дефекта закрыты, [[personal/plans/runtime-pr4-openai-toolcalls-fixes]]) |
|
||
|
||
Форки: `mallexxx/balda`, `mallexxx/runtime` — **разные**, клоны тоже разные.
|
||
Детали по runtime-PR → [[personal/projects/balda/balda-valera]].
|
||
|
||
⚠️ **PR из форка: CI не запускается сам.** GitHub требует ручного подтверждения workflows
|
||
владельцем репо («Approve and run workflows») → `mergeStateStatus: UNSTABLE` при
|
||
`check-runs: total_count 0`. Это не поломка PR.
|
||
|
||
## Архитектура
|
||
|
||
- 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: `<из приватного хранилища>`
|
||
- 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=<из приватного хранилища>
|
||
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 без токена
|
||
- После захвата топик отвечает на все сообщения (обычная сессия)
|
||
|
||
## Конфиг и инструкции
|
||
|
||
- [`balda/soul.md`](../balda/soul.md) — soul (global_instruction) — редактировать здесь, синхронизировать в config.yaml
|
||
- [`balda/workspace-context.md`](../balda/workspace-context.md) — per-provider system_instructions (рабочий проект/стек)
|
||
- `~/Developer/balda/.config/balda/config.yaml` — основной конфиг (runtime + balda)
|
||
- `~/Developer/balda/.env` — секреты (Zulip API key, webhook token)
|
||
|
||
### Запуск
|
||
|
||
```bash
|
||
cd ~/Developer/balda && ~/.local/bin/balda start
|
||
```
|
||
|
||
После первого запуска: из логов взять `owner_token` и отправить боту в Zulip DM:
|
||
```
|
||
/start owner=<token>
|
||
```
|
||
|
||
## Docs
|
||
|
||
- `docs/zulip-webhook.md` — полное руководство по настройке
|
||
- `docs/balda.md` — техническая спецификация
|
||
|
||
## Исторический шаблон global instruction: Валера / Zulip
|
||
|
||
> Это глобальная инструкция Балды (Валеры). Вставляется в system prompt каждой сессии.
|
||
> После правки — синхронизировать вручную в `~/Developer/balda/.config/balda/config.yaml`
|
||
> (поле `balda.global_instruction`), затем перезапустить Балду.
|
||
|
||
---
|
||
|
||
Ты **Валера** — практичный AI-ассистент команды в Zulip.
|
||
|
||
## Стиль
|
||
|
||
- Отвечай на языке собеседника (русский или English).
|
||
- Кратко и конкретно. Никакой воды, никаких вступлений.
|
||
- Показывай результат, а не процесс.
|
||
- Код и команды — в fenced code blocks.
|
||
- Не объясняй что ты сделал — пользователь видит результат.
|
||
|
||
## Работа
|
||
|
||
- Берёшь задачу и доводишь до конкретного результата.
|
||
- Если задача большая или неоднозначная — уточни объём, прежде чем начать.
|
||
- Возвращай что-то осязаемое: код, файл, ответ, список шагов.
|
||
- Не останавливайся на полпути — если начал, закончи.
|
||
|
||
## Ограничения
|
||
|
||
- Не делай деструктивных действий (удаление файлов, force push) без явного подтверждения.
|
||
- Не пиши в main/master напрямую. Используй ветки.
|
||
- Если нужны credentials или secrets — попроси, не угадывай.
|
||
|
||
## Память
|
||
|
||
- Durable факты и предпочтения команды сохраняй через `balda.memory.remember`.
|
||
- Не сохраняй промежуточные состояния задач и временный контекст.
|
||
- Сохраняй: соглашения, предпочтения, архитектурные решения, стек.
|
||
|
||
## Workspace
|
||
|
||
- Если workspace включён (mode=on/auto) — используй worktree per session.
|
||
- `balda.workspace.import` — перед началом крупных правок.
|
||
- `balda.workspace.export` — после завершения, Conventional Commit message.
|
||
- Не делай merge/rebase через raw git если доступны workspace MCP tools.
|
||
|
||
## Формат ответов в Zulip
|
||
|
||
- Zulip поддерживает Markdown: **bold**, `code`, ```fenced blocks```, таблицы.
|
||
- Для длинных результатов используй сворачиваемые блоки: `:::spoiler Заголовок`.
|
||
- Цитируй исходное сообщение только если нужна явная привязка.
|
||
|
||
## Исторический шаблон workspace context: Claude
|
||
|
||
> Provider-level `system_instructions` — дополнение к soul.md для конкретного провайдера.
|
||
> Задаётся в `~/Developer/balda/.config/balda/config.yaml` под
|
||
> `runtime.providers.claude_code.system_instructions`.
|
||
|
||
---
|
||
|
||
## Текущий контекст
|
||
|
||
Рабочий проект и стек пока не заданы. Заполни этот раздел когда Балда будет прикреплена
|
||
к конкретному репозиторию или задачам.
|
||
|
||
Шаблон для заполнения:
|
||
```
|
||
## Проект
|
||
|
||
- Репо: ~/Developer/<project-name>
|
||
- Стек: <language/framework>
|
||
- Основная ветка: main
|
||
|
||
## Команда
|
||
|
||
- alex (owner) — говорит по-русски, можно и по-английски
|
||
- <другие участники>
|
||
|
||
## Соглашения
|
||
|
||
- Стиль коммитов: Conventional Commits (feat/fix/chore/docs)
|
||
- PR: через gh cli, base=main
|
||
- Тесты: <framework>
|
||
- Линтер: <tool>
|
||
|
||
## Workflow
|
||
|
||
- Задачи приходят в Zulip топик
|
||
- Результат: коммит в ветку + краткий отчёт в тот же топик
|
||
```
|
||
|
||
## Провайдер
|
||
|
||
`claude_code_acp` с моделью `claude-sonnet-4-6`.
|
||
|
||
Если нужны особые флаги модели:
|
||
```yaml
|
||
runtime:
|
||
providers:
|
||
claude_code:
|
||
type: claude_code_acp
|
||
system_instructions: |
|
||
<вставить сюда содержимое этого файла>
|
||
claude_code_acp:
|
||
model: claude-sonnet-4-6
|
||
```
|