English · Русский · 中文 · Español · Deutsch · Français · Português (BR) · 日本語

Flock

Запустите команду AI-разработчиков на базе Claude Code на своём сервере и управляйте ею из чата. Опишите фичу в Telegram или VK; команда спланирует её, реализует в ветке, протестирует, проведёт ревью и откроет PR — каждый чат в собственном изолированном рабочем пространстве.

Работает на вашей подписке Claude Pro/Max (без потокенной оплаты) или на API-ключе Anthropic, поставляется в виде готовых Docker-образов (без этапа сборки) и держит каждый чат в собственном изолированном рабочем пространстве.

Быстрый старт (Docker)

git clone https://github.com/duckbugio/flock
cd flock/adapters/telegram
cp .env.example .env        # fill in the REQUIRED block (4 values)
docker compose up -d

Это подтянет готовый образ ghcr.io/duckbugio/flock-telegram — без сборки, без Ansible — после чего напишите своему боту. Минимальный .env:

У всего остального в .env.example есть разумные значения по умолчанию. Обновить позже можно командой docker compose pull && docker compose up -d.

Регион: размещайте в поддерживаемом Anthropic регионе (некоторые страны, например RU/CN, заблокированы по геолокации) — иначе вызовы Claude будут падать.

VK устроен по тому же принципу в adapters/vk/, построен на том же ядре и публикуется как ghcr.io/duckbugio/flock-vk. Он поставляется только с шаблоном env (без compose-файла): cp .env.example .env, затем docker run --env-file .env ghcr.io/duckbugio/flock-vk. Аутентификация Claude и настройки ядра совпадают с Telegram; меняются только три транспортные переменные:

Ключевые особенности

• Источник задач — сам разговор — опишите, что вам нужно, в чате и проверьте пришедший в ответ PR; оболочка и редактор агента изолированы внутри контейнера.
• Настоящий конвейер команды разработки, а не один промпт — критерии приёмки на основе спецификации, шлюзы сборки и регрессий, а также арбитр, который разрывает циклы.
• Несколько транспортов — сегодня Telegram и VK, оба на одном ядре; новая платформа — это тонкий адаптер, а не форк.
• Реакции на PR без входящих вебхуков — бот опрашивает ваш git-хост на предмет новых комментариев ревью и направляет каждый обратно в тот чат, где был открыт PR.
• Дружелюбен к подписке — аутентифицируйтесь токеном Claude Pro/Max (без потокенной оплаты) или API-ключом Anthropic.

Как это работает

You (in a chat): "implement X across the api + web services"
  → bot's Claude (Lead) → planner → confirm scope → coder ⇄ tester → PR per repo
                                                      → reviewer (inline comments) ⇄ coder → arbiter
                                                                                        ├ APPROVE → you merge
                                                                                        └ ESCALATE → asks you

Пять субагентов — planner → coder → tester → reviewer → arbiter — работают как нативные субагенты Claude Code в core/agents/. На обычный вопрос просто даётся ответ; запрос на сборку запускает команду. Арбитр — это размыкатель циклов, учитывающий риски и ограниченный числом итераций, благодаря чему агенты никогда не зацикливаются. Ветки именуются duck/<chatid>/<slug>, чтобы события вебхуков/опроса PR направлялись обратно в нужный чат.

Команда рассчитана на микросервисное рабочее пространство: фича может затрагивать несколько сервисов, и команда координирует ветки и по одному перекрёстно связанному PR на репозиторий. Полный конвейер, ограничители и таблица ролей описаны в core/README.md.

Структура репозитория (монорепо)

Платформенно-независимый «мозг» команды разработки находится в core/; каждая платформа — это тонкий адаптер в adapters/<name>/, использующий общее ядро.

Будущие платформы переиспользуют то же ядро — см. docs/multi-transport-plan.md.

Подключение git-хоста (опционально, но это ядро)

Задайте эти переменные в .env, чтобы команда могла клонировать репозитории и открывать PR (работает с Gitea/GitHub/GitLab):

GIT_HOST=git.example.com
GIT_USER=...
GIT_TOKEN=...                 # write-scoped PAT
GIT_AUTHOR_NAME=AI Team
GIT_AUTHOR_EMAIL=ai@example.com
# Poll the host for new PR comments (reliable; no inbound webhook needed):
GITEA_API_URL=https://git.example.com/api/v1
GITEA_POLL_INTERVAL=90

Для github.com также задайте GH_TOKEN (= вашему GIT_TOKEN), чтобы CLI gh мог открывать PR.

Поллер — рекомендуемый способ реагировать на комментарии ревью: он обращается наружу, поэтому работает даже тогда, когда ваш хост не может достучаться до бота. Он активен, когда установлены ENABLE_PR_REVIEW=true и GITEA_API_URL. Альтернатива с входящим вебхуком и TLS-прокси на Caddy доступна только через развёртывание Ansible (задайте webhook_domain).

Прочие опции

• Голосовые сообщения: ENABLE_VOICE_MESSAGES=true, VOICE_PROVIDER=mistral|openai|local, плюс MISTRAL_API_KEY (или OPENAI_API_KEY). Транскрибируются и выполняются как команды.
• Сайдкар dind: docker compose --profile dind up -d даёт команде линтеры/тесты в Docker (задайте DOCKER_HOST=tcp://dind:2375).
• Изоляция по чатам: каждый чат получает /workspace/chat_<id> (1:1 → приватное; группа → одно общее рабочее пространство); чаты полностью изолированы и выполняются параллельно с ограничением MAX_CONCURRENT_CHAT_RUNS. В группах задайте REQUIRE_GROUP_MENTION=true, чтобы отвечать только при @упоминании или в ответ на сообщение.
• Развёртывание через Ansible (Telegram): провижининг VPS одной командой из adapters/telegram/deploy — скопируйте inventories/example в собственный inventories/<name>/ (в gitignore), заполните inventory/vars/vault, затем ansible-playbook -i inventories/<name>/inventory.ini playbook.yml. Роль подтягивает готовый образ; задайте bot_image, чтобы зафиксировать тег.

Безопасность

• Белый список: пользоваться ботом могут только ALLOWED_USERS (Telegram) / VK_ALLOWED_USERS (VK) — никогда не оставляйте список пустым; он предоставляет доступ к оболочке/редактированию на вашем сервере.
• Изоляция по чатам: разные чаты получают отдельные рабочие пространства. Git-токен общий для всего развёртывания — выдавайте права соответственно.
• Секреты: держите их в .env (в gitignore) или, для Ansible, в vault.yml реального инстанса (в gitignore, шифруется через ansible-vault). Отслеживается только inventories/example/.
• Песочница: агент работает от имени не-root пользователя; его Bash/Edit ограничены контейнером, а не вашим хостом.

Сборка, линтинг, тесты

Репозиторий использует Task в качестве CI-раннера — та же точка входа, что и в CI:

task lint      # format + vet + linters (in the dev-tools image)
task tests     # Go test suite
task build     # compile the binaries

Лицензия

MIT © DuckBug.

Участие и безопасность

Руководства по участию и сообщению об уязвимостях: CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md.