obsidian-vault/personal/projects/archive/balda-reference-before-2026-10-14.md

Balda — историческая карточка и шаблоны до 2026-10-14

[!WARNING] Архив Эти сведения и инструкции относятся к прежним версиям. Они не описывают текущий запуск и не применяются автоматически. Актуальные карточки: personal/projects/balda/balda, personal/projects/balda/setup, personal/projects/balda/execution-broker. Старые PR #8 и #12 уже merged. Литералы старых credentials заменены ссылкой на приватное хранилище.

Карточка Balda до актуализации

Актуальный статус — 2026-10-03. Mattermost-интеграция PR #8 уже в upstream. PR #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, OPEN, 8/8 CI, MERGEABLE)

🔴 Два репозитория — не путать

Репо	Что там	PR
baldaworks/balda	сам бот, транспорты (Mattermost, Zulip)	#8 Mattermost, OPEN · #1 Zulip, merged
normahq/runtime	библиотека рантайма (agentfactory, hostedagent)	#5 фикс MCP-тулинга, OPEN · CHANGES_REQUESTED (3 дефекта, план — personal/plans/runtime-pr5-toolset-dedup-review-fixes) · #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 — soul (global_instruction) — редактировать здесь, синхронизировать в config.yaml
• balda/workspace-context.md — per-provider system_instructions (рабочий проект/стек)
• ~/Developer/balda/.config/balda/config.yaml — основной конфиг (runtime + balda)
• ~/Developer/balda/.env — секреты (Zulip API key, webhook token)

Запуск

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.

Если нужны особые флаги модели:

runtime:
  providers:
    claude_code:
      type: claude_code_acp
      system_instructions: |
        <вставить сюда содержимое этого файла>
      claude_code_acp:
        model: claude-sonnet-4-6