{"id":47275382,"url":"https://github.com/zvenoai/coder","last_synced_at":"2026-04-01T18:25:44.457Z","repository":{"id":344233000,"uuid":"1181059083","full_name":"zvenoai/coder","owner":"zvenoai","description":"Async AI coding orchestrator: turns Yandex Tracker tasks into Claude Agent SDK workflows and GitHub PRs, with code review, deployment checks, and supervised auto-merge.","archived":false,"fork":false,"pushed_at":"2026-03-16T14:15:18.000Z","size":752,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-18T06:00:31.764Z","etag":null,"topics":["agentic-coding","ai-agent","ai-orchestrator","auto-merge","autonomous-coding","claude","claude-agent-sdk","code-review","coding-agent","fastapi","llm","multi-agent","python","yandex-tracker"],"latest_commit_sha":null,"homepage":"https://zveno.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zvenoai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-13T17:49:37.000Z","updated_at":"2026-03-17T09:42:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zvenoai/coder","commit_stats":null,"previous_names":["zvenoai/coder"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zvenoai/coder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvenoai%2Fcoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvenoai%2Fcoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvenoai%2Fcoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvenoai%2Fcoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zvenoai","download_url":"https://codeload.github.com/zvenoai/coder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zvenoai%2Fcoder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31018559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-27T03:51:26.850Z","status":"ssl_error","status_checked_at":"2026-03-27T03:51:09.693Z","response_time":164,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-coding","ai-agent","ai-orchestrator","auto-merge","autonomous-coding","claude","claude-agent-sdk","code-review","coding-agent","fastapi","llm","multi-agent","python","yandex-tracker"],"created_at":"2026-03-15T16:58:31.723Z","updated_at":"2026-03-27T04:17:12.633Z","avatar_url":"https://github.com/zvenoai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZvenoAI Coder\n\n[English version](README_EN.md)\n\nМы активно используем Coder больше месяца в продакшне — сейчас он пишет ~90% всего кода в [ZvenoAI](https://zveno.ai).\n\n![ZvenoAI Coder Dashboard](docs/dashboard.jpg)\n\nАсинхронный оркестратор на Python: опрашивает Yandex Tracker на задачи с тегом `ai-task`, запускает агентов Claude для их выполнения, координирует подзадачи эпиков по зависимостям (с автодекомпозицией), мониторит PR на ревью-комментарии, автоматически мёржит PR (с human gate и pre-merge code review), верифицирует деплой после merge, принимает алерты из Alertmanager и стримит вывод в веб-дашборд реального времени. Supervisor проактивно мониторит здоровье агентов через heartbeat и может эскалировать на человека.\n\n## Доступ к Claude API из России\n\nClaude API недоступен напрямую из РФ, а оплата зарубежных API-сервисов затруднена. [ZvenoAI](https://zveno.ai) решает обе проблемы:\n\n- **Единый API** (`api.zveno.ai/v1`) — полностью совместим с OpenAI SDK и Claude Agent SDK\n- **Оплата в рублях** — карты, СБП, безнал для юрлиц\n- **200+ моделей** — OpenAI, Anthropic, Google, xAI и другие через один ключ\n- **Автоматический failover** между провайдерами\n\nДля работы Coder достаточно получить API-ключ на [zveno.ai](https://zveno.ai) и указать его в `.env`:\n\n```bash\nANTHROPIC_API_KEY=sk-zveno-...   # ключ ZvenoAI\n```\n\nAPI ZvenoAI совместим с Anthropic SDK — никаких изменений в коде не требуется.\n\n## Как это работает\n\n**Жизненный цикл:** опрос трекера → если задача — эпик: регистрация и координация подзадач через OrchestratorAgent → иначе: разрешение репозиториев → создание worktree → запуск агента (opus) → **планирование (opus sub-agent, read-only)** → если есть блокеры: запрос информации и остановка, иначе: TDD (сначала тесты, потом реализация) → push и создание PR (если нужен) → мониторинг ревью → агент правит комментарии → **human gate** (блокировка больших/чувствительных PR) → **pre-merge code review** (Sonnet sub-agent) → auto-merge → **post-merge verification** (проверка деплоя) → закрытие задачи в трекере. При рестарте оркестратора сессии агентов возобновляются с полным контекстом через `session_id` + `fork_session`.\n\nАгент сам решает, когда задача завершена. PR создаётся только при наличии изменений кода — исследовательские и документационные задачи завершаются без PR.\n\n## Архитектура\n\n```mermaid\nflowchart TB\n    tracker[\"Yandex Tracker\"]\n    github[\"GitHub\"]\n    claude[\"Claude API\"]\n\n    alertmanager[\"Alertmanager\"]\n\n    subgraph core[\"Оркестратор\"]\n        dispatcher[\"Dispatcher\u003cbr/\u003eопрос задач\"]\n        agents[\"Worker Agents\u003cbr/\u003eвыполнение задач\"]\n        monitors[\"Мониторы\u003cbr/\u003ePR / needs-info\"]\n        heartbeat[\"HeartbeatMonitor\u003cbr/\u003eздоровье агентов\"]\n        supervisor[\"Supervisor\u003cbr/\u003eчат + память\"]\n        mailbox[\"Mailbox\u003cbr/\u003eмежагентное общение\"]\n        epics[\"Epic Coordinator\u003cbr/\u003eкоординация подзадач\"]\n        gate[\"Human Gate\u003cbr/\u003eблокировка больших PR\"]\n        verifier[\"Post-Merge Verifier\u003cbr/\u003eпроверка деплоя\"]\n        escalation[\"Escalation\u003cbr/\u003eэскалация на человека\"]\n    end\n\n    subgraph infra[\"Инфраструктура\"]\n        eventbus[\"EventBus\"]\n        storage[\"SQLite Storage\"]\n    end\n\n    dashboard[\"Веб-дашборд\u003cbr/\u003eReact + xterm.js\"]\n\n    tracker -- \"задачи\" --\u003e dispatcher\n    dispatcher -- \"запуск\" --\u003e agents\n    agents -- \"код, PR\" --\u003e github\n    agents -- \"SDK\" --\u003e claude\n    agents \u003c-- \"сообщения\" --\u003e mailbox\n    agents -- \"результат\" --\u003e monitors\n    github -- \"ревью, CI\" --\u003e monitors\n    monitors -- \"промпт\" --\u003e agents\n    monitors -- \"human gate\" --\u003e gate\n    gate -- \"OK\" --\u003e monitors\n    monitors -- \"auto-merge\" --\u003e github\n    monitors -- \"после merge\" --\u003e verifier\n    verifier -- \"hotfix task\" --\u003e tracker\n    tracker -- \"ответы\" --\u003e monitors\n    epics -- \"активация\u003cbr/\u003eподзадач\" --\u003e dispatcher\n    heartbeat -- \"алерты\" --\u003e supervisor\n    supervisor -- \"управление\" --\u003e tracker\n    supervisor -- \"эскалация\" --\u003e escalation --\u003e tracker\n    alertmanager -- \"webhook\u003cbr/\u003e(auto-create task)\" --\u003e tracker\n    alertmanager -- \"webhook\u003cbr/\u003e(prompt)\" --\u003e supervisor\n    core --\u003e eventbus\n    eventbus --\u003e dashboard\n    eventbus --\u003e storage\n\n    classDef ext fill:#4a90d9,stroke:#2c5ea0,color:#fff\n    classDef core_s fill:#e8a838,stroke:#b8842c,color:#000\n    classDef infra_s fill:#6bbf6b,stroke:#4a9a4a,color:#000\n    classDef dash fill:#f87171,stroke:#c25050,color:#fff\n\n    class tracker,github,claude,alertmanager ext\n    class dispatcher,agents,monitors,heartbeat,supervisor,mailbox,epics,gate,verifier,escalation core_s\n    class eventbus,storage infra_s\n    class dashboard dash\n```\n\n## Архитектура (компоненты)\n\n| Компонент | Назначение |\n|---|---|\n| `orchestrator/main.py` | Асинхронный цикл оркестратора, диспетчеризация задач, мониторинг ревью/needs-info, веб-сервер |\n| `orchestrator/config.py` | Конфигурация из переменных окружения с полями SDK |\n| `orchestrator/constants.py` | Общие перечисления и типы (EventType, PRState, MAX_COMPACTION_CYCLES) |\n| `orchestrator/orchestrator_agent.py` | Обработка результатов — track_pr / retry / escalate / fail / complete, координация эпиков |\n| `orchestrator/orchestrator_tools.py` | Реализация терминальных действий (track_pr, retry, escalate, fail, complete) |\n| `orchestrator/epic_coordinator.py` | Хранилище состояния подзадач эпика, автодекомпозиция, управление готовностью, активация с учётом зависимостей |\n| `orchestrator/agent_runner.py` | Обёртка над Claude Agent SDK, долгоживущие сессии для циклов ревью, захват и возобновление `session_id` после рестарта |\n| `orchestrator/compaction.py` | Авто-компактификация контекста: `should_compact()`, `summarize_output()`, `build_continuation_prompt()` |\n| `orchestrator/task_dispatcher.py` | Опрос Tracker, запуск агентов с контролем параллелизма через семафор, возобновление сессий после рестарта (`resume` + `fork_session`) |\n| `orchestrator/tracker_client.py` | REST-клиент для Yandex Tracker API |\n| `orchestrator/tracker_enums.py` | Перечисления и хелперы для сопоставления статусов Tracker |\n| `orchestrator/tracker_types.py` | TypedDict-определения типов для ответов Tracker API |\n| `orchestrator/tracker_tools.py` | In-process MCP-инструменты, scoped по задаче (без sidecar-процессов) |\n| `orchestrator/heartbeat.py` | Периодический мониторинг здоровья агентов (stuck, long-running, stale review), алертинг supervisor с cooldown |\n| `orchestrator/github_client.py` | GitHub GraphQL-клиент для ревью-тредов, CI, auto-merge (enablePullRequestAutoMerge), проверки готовности к мёржу |\n| `orchestrator/pr_monitor.py` | Цикл мониторинга PR ревью/CI + human gate + pre-merge review + auto-merge + post-merge verification trigger |\n| `orchestrator/pre_merge_reviewer.py` | One-shot sub-agent (Sonnet) для code review перед auto-merge: OWASP checklist, fail-close по умолчанию |\n| `orchestrator/post_merge_verifier.py` | Верификация деплоя после merge: ожидание CI на merge SHA, K8s rollout, sub-agent проверки, авто-создание hotfix |\n| `orchestrator/alertmanager_webhook.py` | Парсинг Alertmanager webhook, дедупликация, маппинг компонентов, авто-создание задач в Tracker |\n| `orchestrator/adr.py` | Architecture Decision Records: создание/список/чтение markdown-файлов в `docs/decisions/` |\n| `orchestrator/escalation.py` | Эскалация supervisor → человек: тег `needs-human-review` + структурированный комментарий в Tracker |\n| `orchestrator/dependency_manager.py` | Автодефер задач с неразрешёнными зависимостями (Tracker links + LLM-экстракция блокеров), рекурентная перепроверка |\n| `orchestrator/k8s_client.py` | Kubernetes client: pod logs/status через in-cluster ServiceAccount, feature-gated (`K8S_LOGS_ENABLED`) |\n| `orchestrator/metrics.py` | Prometheus-метрики (Counter, Gauge, Histogram) для VictoriaMetrics, endpoint `/metrics` |\n| `orchestrator/preflight_checker.py` | Preflight-проверки задач перед запуском агента |\n| `orchestrator/llm_utils.py` | Общие утилиты для LLM-вызовов (Haiku) |\n| `orchestrator/needs_info_monitor.py` | Мониторинг статуса needs-info — ожидание ответов от людей |\n| `orchestrator/agent_mailbox.py` | Межагентный почтовый ящик — маршрутизация сообщений, управление inbox, interrupt-доставка |\n| `orchestrator/comm_tools.py` | MCP-инструменты для общения worker-агентов (list peers, send/reply/check messages) |\n| `orchestrator/supervisor.py` | Инициализация SupervisorRunner (memory index, embedder) |\n| `orchestrator/supervisor_chat.py` | Интерактивный стриминг-чат с supervisor-агентом |\n| `orchestrator/supervisor_tools.py` | Supervisor MCP-инструменты — Tracker, GitHub, статистика, память, управление агентами, ADR, env config |\n| `orchestrator/supervisor_prompt_builder.py` | Построение системного промпта для supervisor |\n| `orchestrator/supervisor_memory.py` | SQLite + FTS5 гибридный поиск по markdown-файлам (`data/memory/`) |\n| `orchestrator/prompt_builder.py` | Построение промптов задач для worker-агентов |\n| `orchestrator/repo_resolver.py` | Клонирование/pull git-репозиториев из `repos.yaml`, блокировки по репо |\n| `orchestrator/workspace.py` | Создание/очистка git worktree на задачу, блокировки по репо |\n| `orchestrator/workspace_tools.py` | MCP-инструменты для workspace (ленивое создание worktree) |\n| `orchestrator/recovery.py` | Персистенция состояния восстановления, классификация ошибок, отслеживание backoff |\n| `orchestrator/proposal_manager.py` | Жизненный цикл предложений по улучшению |\n| `orchestrator/event_bus.py` | Async pub/sub с кольцевым буфером истории на задачу |\n| `orchestrator/stats_collector.py` | Подписчик EventBus, записывающий статистику в хранилище |\n| `orchestrator/stats_models.py` | Модели данных для персистентной статистики (TaskRun, SupervisorRun и т.д.) |\n| `orchestrator/storage.py` | Абстрактный Storage Protocol для бекендов персистенции |\n| `orchestrator/sqlite_storage.py` | Реализация хранилища на SQLite |\n| `orchestrator/_persistence.py` | Mixin для фоновой персистенции через asyncio-задачи |\n| `orchestrator/web.py` | FastAPI REST + WebSocket + Alertmanager webhook + Prometheus /metrics, раздача React-фронтенда |\n| `frontend/` | React 19 + Vite + TypeScript + xterm.js терминал |\n\n## Быстрый старт\n\n```bash\ncp .env.example .env\n# Заполнить: YANDEX_TRACKER_TOKEN, YANDEX_TRACKER_ORG_ID, CLAUDE_CODE_OAUTH_TOKEN или ANTHROPIC_API_KEY, GITHUB_TOKEN\n\ndocker compose up -d\n# Дашборд: http://localhost:8080\n```\n\n## Деплой\n\n### Требования\n\n- **Yandex Tracker** — организация с очередью задач\n- **GitHub** — токен с правами на целевые репозитории (`repo` scope)\n- **Claude API** — OAuth-токен Claude Code или API-ключ (Anthropic / ZvenoAI)\n- **Docker** — для локального деплоя через Docker Compose\n- **Kubernetes** — для production-деплоя через Helm\n\n### Docker Compose (локальный / dev)\n\n```bash\ncp .env.example .env\n# Заполнить обязательные переменные (см. раздел Аутентификация)\n\ndocker compose up -d          # запуск\ndocker compose logs -f        # логи\ndocker compose up -d --build  # пересборка после изменений\n```\n\n**Что внутри:**\n\n| Volume | Путь в контейнере | Назначение |\n|---|---|---|\n| `workspace` | `/workspace` | Клонированные репозитории и git worktree агентов |\n| `stats-data` | `/app/data` | SQLite БД (статистика, состояние задач, PR lifecycle) |\n| `./prompts` | `/app/prompts` (ro) | Промпты агентов — монтируются read-only для быстрой правки без пересборки |\n| Docker socket | `/var/run/docker.sock` | Агенты используют Docker CLI внутри worktree (`make gen`, `docker compose up`, testcontainers) |\n\n\u003e **Docker socket** монтируется потому что агенты запускают команды сборки и тесты в целевых репозиториях. Если целевые проекты не используют Docker — можно убрать из `docker-compose.yaml`.\n\n**Порты:**\n- `8080` — веб-дашборд (REST API + WebSocket + Prometheus `/metrics`)\n\n### Kubernetes (production)\n\nВ каталоге [`helm/`](https://github.com/zvenoai/coder) лежит Helm chart. Пример деплоя:\n\n```bash\nhelm install coder ./helm/charts/coder \\\n  -f helm/values/dev/coder.yaml \\\n  --set externalSecrets.enabled=true\n```\n\n**Ключевые особенности chart'а:**\n\n- **ExternalSecrets** — секреты (Tracker token, GitHub token, API key) загружаются из Vault через `ExternalSecret` CRD. Fallback на Kubernetes Secret если `externalSecrets.enabled=false`.\n- **Persistent storage** — два PVC: `workspace` (20Gi, для репозиториев) и `stats-data` (1Gi, SQLite).\n- **RBAC** — `rbac.create=true` создаёт Role/RoleBinding для чтения pod logs (нужно для `K8S_LOGS_ENABLED=true`).\n- **Docker-in-Docker** — опциональный sidecar (`dind.enabled=true`) для агентов, использующих Docker CLI внутри worktree.\n- **HTTPRoute** — опциональный Gateway API route (`route.enabled=true`) для доступа к дашборду.\n- **Recreate strategy** — один реплика, Recreate (не Rolling) из-за SQLite и git worktree.\n- **Graceful shutdown** — `terminationGracePeriodSeconds: 120` для завершения активных агентов.\n- **Reloader** — аннотация `reloader.stakater.com/auto: \"true\"` для авто-рестарта при изменении ConfigMap/Secret.\n\n**Структура values:**\n\n```\nhelm/\n  charts/coder/          # chart и шаблоны\n    values.yaml          # дефолты (пустые секреты, минимальные ресурсы)\n  values/\n    dev/coder.yaml       # dev-окружение (ваши значения)\n    prod/coder.yaml      # production\n```\n\n**Минимальные ресурсы:**\n\n| Контейнер | Requests | Limits |\n|---|---|---|\n| coder | 400m CPU, 4Gi RAM | 2000m CPU, 8Gi RAM |\n| dind (опционально) | 400m CPU, 2Gi RAM | 2000m CPU, 4Gi RAM |\n\n\u003e RAM зависит от `MAX_CONCURRENT_AGENTS`. Каждый агент — это процесс Claude Code CLI (~500MB-1GB RAM). Для 10 параллельных агентов рекомендуется 8-16Gi.\n\n## Аутентификация\n\nОркестратор передаёт учётные данные в Claude Agent SDK. Три варианта (по приоритету):\n\n| Переменная окружения | Описание | Приоритет |\n|---|---|---|\n| `CLAUDE_CODE_OAUTH_TOKEN` | Квота подписки Claude Code | 1 (предпочтительный) |\n| `ANTHROPIC_API_KEY` | API-ключ Anthropic или [ZvenoAI](https://zveno.ai) | 2 |\n\n### Вариант 1 — через ZvenoAI (рекомендуется для РФ)\n\nЗарегистрируйтесь на [zveno.ai](https://zveno.ai), получите API-ключ и укажите в `.env`:\n\n```bash\nANTHROPIC_API_KEY=sk-zveno-...\n```\n\nОплата в рублях, без VPN и зарубежных карт.\n\n### Вариант 2 — через OAuth-токен Claude Code\n\nClaude Code CLI сохраняет OAuth-токены в системное хранилище ключей после авторизации.\n\n**Авторизация через CLI** (токен сохраняется автоматически):\n```bash\nclaude\n# в REPL ввести: /login\n# завершить OAuth в браузере\n```\n\n**Извлечение существующего токена из macOS Keychain:**\n```bash\nsecurity find-generic-password -s \"Claude Code-credentials\" -w \\\n  | python3 -c \"import sys,json; print(json.load(sys.stdin)['claudeAiOauth']['accessToken'])\"\n```\n\nФормат токена: `sk-ant-oat01-...`. Задаётся в `.env` или Vault.\n\n### Вариант 3 — напрямую через Anthropic API\n\nЕсли у вас есть прямой доступ к Anthropic API:\n\n```bash\nANTHROPIC_API_KEY=sk-ant-...\n```\n\n## Конфигурация\n\nВсе параметры через переменные окружения (см. `.env.example`):\n\n| Переменная | Значение по умолчанию | Описание |\n|---|---|---|\n| `TRACKER_QUEUE` | `QR` | Ключ очереди в Yandex Tracker |\n| `TRACKER_TAG` | `ai-task` | Тег, запускающий диспетчеризацию агента |\n| `AGENT_MODEL` | `claude-opus-4-6` | Модель Claude для worker-агентов |\n| `AGENT_MAX_BUDGET_USD` | _(нет)_ | Лимит расходов на задачу (опционально) |\n| `MAX_CONCURRENT_AGENTS` | `2` | Лимит параллельных агентов |\n| `AGENT_PERMISSION_MODE` | `acceptEdits` | Режим прав SDK |\n| `REVIEW_CHECK_DELAY_SECONDS` | `120` | Интервал опроса PR-ревью |\n| `SUPERVISOR_MODEL` | `claude-opus-4-6` | Модель для supervisor-чата |\n| `COMPACTION_ENABLED` | `true` | Включить авто-компактификацию контекста |\n| `COMPACTION_BUFFER_TOKENS` | `20000` | Буфер до лимита контекста для срабатывания компактификации |\n| `COMPACTION_MODEL` | `claude-haiku-4-5-20251001` | Модель для суммаризации при компактификации |\n| `AUTO_MERGE_ENABLED` | `false` | Включить авто-мёрж PR (opt-in) |\n| `AUTO_MERGE_METHOD` | `squash` | Метод мёржа (squash, merge, rebase) |\n| `AUTO_MERGE_REQUIRE_APPROVAL` | `true` | Требовать approval перед авто-мёржем |\n| `PRE_MERGE_REVIEW_ENABLED` | `false` | Включить code review sub-agent перед merge |\n| `PRE_MERGE_REVIEW_FAIL_OPEN` | `false` | При ошибке/таймауте: `false` = reject, `true` = approve |\n| `HUMAN_GATE_MAX_DIFF_LINES` | `0` | Порог diff для блокировки auto-merge (0 = выключен) |\n| `HUMAN_GATE_SENSITIVE_PATHS` | _(пусто)_ | Comma-separated glob-паттерны чувствительных файлов |\n| `POST_MERGE_VERIFICATION_ENABLED` | `false` | Включить верификацию деплоя после merge |\n| `POST_MERGE_VERIFICATION_ENVIRONMENT` | `dev` | Окружение для верификации |\n| `ALERTMANAGER_WEBHOOK_ENABLED` | `false` | Включить приём алертов из Alertmanager |\n| `ALERTMANAGER_AUTO_CREATE_TASK` | `false` | Авто-создание задач из critical/error алертов |\n| `HEARTBEAT_INTERVAL_SECONDS` | `300` | Интервал проверки здоровья агентов |\n\n## Маппинг репозиториев\n\n`repos.yaml` перечисляет git-репозитории, клонируемые в workspace:\n\n```yaml\nall_repos:\n  - url: https://github.com/org/api.git\n    path: /workspace/api\n    description: \"Go API backend\"\n  - url: https://github.com/org/frontend.git\n    path: /workspace/frontend\n    description: \"Next.js frontend\"\n```\n\n## Разработка\n\n```bash\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[dev]\"\npytest tests/ -v\n```\n\nПроверка качества (Docker, синхронизировано с CI):\n```bash\ntask quality          # все проверки (Python + Frontend параллельно)\ntask python:quality   # lint → format:check → typecheck → test\ntask frontend:quality # typecheck → lint → test → build\n```\n\nФронтенд:\n```bash\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run dev\n```\n\n## Контейнерный тулчейн\n\nDocker-образ содержит: Python 3.12, Node.js 22, Go 1.24, Docker CLI, docker-compose, gh CLI, Claude Code CLI. Docker-сокет монтируется для `make gen`, `docker compose up` (тестовая инфра) и testcontainers внутри worktree агентов.\n\n---\n\n## Детальные схемы по модулям\n\n### Диспетчеризация и выполнение задач\n\n```mermaid\nflowchart LR\n    tracker[\"Yandex Tracker\u003cbr/\u003eai-task, non-resolved\"]\n    dispatcher[\"TaskDispatcher\u003cbr/\u003eопрос каждые 60с\"]\n    resolver[\"RepoResolver\u003cbr/\u003eкомпонент → репозиторий\u003cbr/\u003e(repos.yaml)\"]\n    workspace[\"WorkspaceManager\u003cbr/\u003egit worktree\u003cbr/\u003eветка: ai/{key}\"]\n    runner[\"AgentRunner\u003cbr/\u003eClaudeSDKClient\"]\n    worker[\"Worker Agent\u003cbr/\u003e(opus)\"]\n    plan[\"Planning Sub-Agent\u003cbr/\u003e(opus, read-only)\"]\n    compaction[\"Compaction\u003cbr/\u003eсуммаризация через Haiku\"]\n    orch_agent[\"OrchestratorAgent\u003cbr/\u003etrack_pr / retry /\u003cbr/\u003eescalate / complete\"]\n\n    tracker --\u003e dispatcher\n    dispatcher --\u003e resolver --\u003e workspace\n    dispatcher --\u003e runner --\u003e worker\n    worker -- \"Task tool\" --\u003e plan\n    plan -- \"план / блокеры\" --\u003e worker\n    worker -. \"лимит токенов\" .-\u003e compaction\n    compaction -. \"новая сессия\" .-\u003e worker\n    worker -- \"результат\" --\u003e orch_agent\n    orch_agent -- \"решение\" --\u003e dispatcher\n\n    classDef ext fill:#4a90d9,stroke:#2c5ea0,color:#fff\n    classDef core fill:#e8a838,stroke:#b8842c,color:#000\n    classDef agent fill:#c084fc,stroke:#9061c2,color:#000\n    classDef infra fill:#6bbf6b,stroke:#4a9a4a,color:#000\n\n    class tracker ext\n    class dispatcher,orch_agent core\n    class runner,worker,plan agent\n    class resolver,workspace,compaction infra\n```\n\n### Мониторинг PR и needs-info\n\n```mermaid\nflowchart LR\n    github[\"GitHub\u003cbr/\u003eGraphQL API\"]\n    tracker[\"Yandex Tracker\"]\n    pr_mon[\"PRMonitor\u003cbr/\u003eопрос каждые 120с\"]\n    ni_mon[\"NeedsInfoMonitor\u003cbr/\u003eопрос каждые 120с\"]\n    session[\"Agent Session\u003cbr/\u003e(долгоживущая)\"]\n    recovery[\"RecoveryManager\u003cbr/\u003ebackoff + retry\"]\n    gate[\"Human Gate\"]\n    reviewer[\"Pre-merge Review\u003cbr/\u003e(Sonnet)\"]\n    verifier[\"Post-merge\u003cbr/\u003eVerification\"]\n\n    github -- \"статус PR,\u003cbr/\u003eревью-треды, CI\" --\u003e pr_mon\n    pr_mon -- \"промпт ревью\" --\u003e session\n    session -- \"push fix\" --\u003e github\n    pr_mon -- \"gate check\" --\u003e gate\n    gate -- \"OK\" --\u003e reviewer\n    reviewer -- \"approve\" --\u003e pr_mon\n    pr_mon -- \"auto-merge\" --\u003e github\n    pr_mon -- \"вмёрджен\" --\u003e verifier\n    verifier -. \"hotfix\" .-\u003e tracker\n    pr_mon -- \"закрытие\" --\u003e tracker\n\n    tracker -- \"новые комментарии\" --\u003e ni_mon\n    ni_mon -- \"промпт ответа\" --\u003e session\n    session -- \"продолжение\u003cbr/\u003eработы\" --\u003e github\n\n    recovery -. \"retry / skip\" .-\u003e pr_mon\n    recovery -. \"retry / skip\" .-\u003e ni_mon\n\n    classDef ext fill:#4a90d9,stroke:#2c5ea0,color:#fff\n    classDef core fill:#e8a838,stroke:#b8842c,color:#000\n    classDef agent fill:#c084fc,stroke:#9061c2,color:#000\n    classDef infra fill:#6bbf6b,stroke:#4a9a4a,color:#000\n\n    class github,tracker ext\n    class pr_mon,ni_mon,gate core\n    class session,reviewer,verifier agent\n    class recovery infra\n```\n\n### Координация эпиков\n\n```mermaid\nflowchart LR\n    epic[\"Эпик в Tracker\u003cbr/\u003e(тип: Epic)\"]\n    coordinator[\"EpicCoordinator\u003cbr/\u003eобнаружение подзадач\u003cbr/\u003eавтодекомпозиция\u003cbr/\u003eграф зависимостей\"]\n    supervisor[\"Supervisor Chat\u003cbr/\u003eпланирование\u003cbr/\u003eустановка зависимостей\"]\n    children[\"Подзадачи\u003cbr/\u003eawaiting_plan → executing\"]\n    dispatcher[\"Dispatcher\"]\n\n    epic --\u003e coordinator\n    coordinator -- \"EPIC_AWAITING_PLAN\" --\u003e supervisor\n    coordinator -- \"EPIC_NEEDS_DECOMPOSITION\u003cbr/\u003e(нет подзадач)\" --\u003e supervisor\n    supervisor -- \"epic_create_child\u003cbr/\u003eset_child_dependencies\u003cbr/\u003eactivate_child\" --\u003e coordinator\n    coordinator -- \"тег ai-task\u003cbr/\u003eна готовую подзадачу\" --\u003e children\n    children --\u003e dispatcher\n\n    classDef ext fill:#4a90d9,stroke:#2c5ea0,color:#fff\n    classDef core fill:#e8a838,stroke:#b8842c,color:#000\n    classDef agent fill:#c084fc,stroke:#9061c2,color:#000\n\n    class epic ext\n    class coordinator,dispatcher core\n    class supervisor,children agent\n```\n\n### Supervisor\n\nSupervisor — один агент (Opus, `bypassPermissions`), работающий через **три независимых канала** (каждый со своей сессией и историей):\n\n| Канал | Назначение | Триггер |\n|---|---|---|\n| `chat` | Интерактивный чат с оператором через дашборд | Оператор пишет сообщение |\n| `tasks` | Автономные уведомления (эпики, деферы, декомпозиция, алерты) | Системные события (fire-and-forget через `auto_send`) |\n| `heartbeat` | Диагностика (застрявшие агенты, долгие задачи, stale ревью) | `HeartbeatMonitor` каждые 5 мин |\n\nСессия в каждом канале — долгоживущая (не пересоздаётся на каждое сообщение), история накапливается.\n\n#### Инструменты supervisor vs worker\n\nWorker-агенты получают **узкий набор** инструментов, ограниченных контекстом своей задачи. Supervisor — **глобальный доступ** ко всей системе.\n\n| Категория | Worker (4 + 5 comm) | Supervisor (~100 инструментов) |\n|---|---|---|\n| **Tracker** | Только свой issue (get, comment, checklist) | Поиск, создание, обновление любых задач |\n| **GitHub** | Нет | PR diff, reviews, checks, mergeability |\n| **Статистика** | Нет | Summary, costs, errors, произвольные SQL |\n| **Память** | Нет | CRUD + гибридный поиск (BM25 + vector) |\n| **Эпики** | Нет | Планирование зависимостей, активация/ресет детей |\n| **Агенты** | Нет | List/abort/cancel агентов, отправка сообщений |\n| **Зависимости** | Нет | Approve/defer задач |\n| **Межагентное** | send/reply/check/list (свой скоуп) | view_agent_messages, get_comm_stats (read-only) |\n| **K8s** | Нет | Pod logs/status (опционально) |\n| **ADR** | Нет | Создание/список/чтение Architecture Decision Records |\n| **Env config** | Нет | Чтение/запись per-env connection details (API URLs, credentials) |\n| **Эскалация** | Нет | Тег `needs-human-review` + комментарий в Tracker |\n| **Файловая система** | Workspace (свой worktree) | Bash, Write, Edit (без ограничений) |\n\n#### Взаимодействие с воркерами\n\n- **Supervisor → Worker**: `send_message_to_task()` (interrupt текущей сессии), `abort_task()`, `cancel_task()`\n- **Worker → Supervisor**: напрямую невозможно; supervisor видит всё через EventBus и `view_agent_messages`\n\n```mermaid\nflowchart LR\n    user[\"Пользователь\u003cbr/\u003e(дашборд)\"]\n    events[\"Системные события\u003cbr/\u003e(epic plan, defer,\u003cbr/\u003eheartbeat, alertmanager)\"]\n\n    subgraph supervisor[\"Supervisor Agent (Opus)\"]\n        chat_ch[\"chat канал\u003cbr/\u003eинтерактивный\"]\n        tasks_ch[\"tasks канал\u003cbr/\u003eавтономный\"]\n        hb_ch[\"heartbeat канал\u003cbr/\u003eдиагностика\"]\n    end\n\n    tools[\"~100 MCP-инструментов\u003cbr/\u003eTracker, GitHub, stats,\u003cbr/\u003ememory, epic mgmt, K8s,\u003cbr/\u003eADR, env, escalation,\u003cbr/\u003eBash, Write, Edit\"]\n    memory[\"SupervisorMemory\u003cbr/\u003eSQLite + FTS5\u003cbr/\u003eBM25 + cosine\"]\n    files[\"data/memory/*.md\"]\n    workers[\"Worker Agents\"]\n\n    user -- \"сообщение\" --\u003e chat_ch\n    events -- \"auto_send\" --\u003e tasks_ch\n    events -- \"алерты\" --\u003e hb_ch\n    chat_ch \u0026 tasks_ch \u0026 hb_ch --\u003e tools\n    tools -. \"поиск / запись\" .-\u003e memory --\u003e files\n    tools -- \"interrupt / abort\" --\u003e workers\n\n    classDef user_s fill:#f87171,stroke:#c25050,color:#fff\n    classDef core fill:#e8a838,stroke:#b8842c,color:#000\n    classDef agent fill:#c084fc,stroke:#9061c2,color:#000\n    classDef infra fill:#6bbf6b,stroke:#4a9a4a,color:#000\n\n    class user,events user_s\n    class chat_ch,tasks_ch,hb_ch core\n    class tools agent\n    class memory,files,workers infra\n```\n\n### Межагентное общение\n\n```mermaid\nflowchart LR\n    agentA[\"Worker Agent A\u003cbr/\u003e(QR-10)\"]\n    agentB[\"Worker Agent B\u003cbr/\u003e(QR-11)\"]\n    mailbox[\"AgentMailbox\u003cbr/\u003eинбоксы, статусы сообщений\u003cbr/\u003eMAX_INBOX_SIZE = 50\"]\n    interrupt[\"interrupt_with_message\u003cbr/\u003e(доставка через прерывание)\"]\n\n    agentA -- \"1. list_running_agents\" --\u003e mailbox\n    agentA -- \"2. send_message_to_agent\" --\u003e mailbox\n    mailbox -- \"3. interrupt\" --\u003e interrupt --\u003e agentB\n    agentB -- \"4. reply_to_message\" --\u003e mailbox\n    mailbox -- \"5. interrupt\" --\u003e agentA\n\n    classDef agent fill:#c084fc,stroke:#9061c2,color:#000\n    classDef infra fill:#6bbf6b,stroke:#4a9a4a,color:#000\n\n    class agentA,agentB agent\n    class mailbox,interrupt infra\n```\n\n### Веб-дашборд и события\n\n```mermaid\nflowchart LR\n    components[\"Все компоненты\u003cbr/\u003e(dispatcher, monitors,\u003cbr/\u003eagents, mailbox)\"]\n    eventbus[\"EventBus\u003cbr/\u003easync pub/sub\u003cbr/\u003eкольцевой буфер (500)\"]\n    collector[\"StatsCollector\"]\n    storage[\"SQLite Storage\"]\n    fastapi[\"FastAPI :8080\"]\n    ws[\"WebSocket\u003cbr/\u003e/ws/tasks/{key}/stream\u003cbr/\u003e/ws/events\"]\n    rest[\"REST API\u003cbr/\u003e/api/status, /tasks, /events,\u003cbr/\u003e/proposals, /stats, /config,\u003cbr/\u003e/webhook/alertmanager, /metrics\"]\n    frontend[\"React 19 + Vite\u003cbr/\u003eTailwindCSS\u003cbr/\u003exterm.js\"]\n\n    components --\u003e eventbus\n    eventbus --\u003e ws\n    eventbus --\u003e collector --\u003e storage\n    fastapi --- ws\n    fastapi --- rest\n    ws --\u003e frontend\n    rest --\u003e frontend\n\n    classDef core fill:#e8a838,stroke:#b8842c,color:#000\n    classDef infra fill:#6bbf6b,stroke:#4a9a4a,color:#000\n    classDef dash fill:#f87171,stroke:#c25050,color:#fff\n\n    class components core\n    class eventbus,collector,storage infra\n    class fastapi,ws,rest,frontend dash\n```\n\n### Auto-merge pipeline\n\n```mermaid\nflowchart LR\n    pr[\"PR готов к merge\"]\n    gate[\"Human Gate\u003cbr/\u003ediff \u003e N строк?\u003cbr/\u003eчувствительные пути?\"]\n    block[\"BLOCK\u003cbr/\u003eкомментарий в PR\u003cbr/\u003eHUMAN_GATE_TRIGGERED\"]\n    review[\"Pre-merge Review\u003cbr/\u003eSonnet sub-agent\u003cbr/\u003eOWASP checklist\"]\n    reject[\"REJECT\u003cbr/\u003eREQUEST_CHANGES\u003cbr/\u003e→ worker исправляет\"]\n    readiness[\"Merge Readiness\u003cbr/\u003eCI ✓, approved,\u003cbr/\u003eno conflicts\"]\n    merge[\"Auto-merge\u003cbr/\u003esquash/merge/rebase\"]\n    verify[\"Post-merge Verification\"]\n    ci_wait[\"Ожидание CI\u003cbr/\u003eна merge SHA\"]\n    k8s_wait[\"Ожидание K8s\u003cbr/\u003epod rollout\"]\n    agent[\"Verification Agent\u003cbr/\u003e(Sonnet)\"]\n    pass_ev[\"TASK_VERIFIED\"]\n    fail_ev[\"Hotfix Bug task\u003cbr/\u003eв Tracker\"]\n\n    pr --\u003e gate\n    gate -- \"blocked\" --\u003e block\n    gate -- \"OK\" --\u003e review\n    review -- \"reject\" --\u003e reject\n    reject -. \"fix + new commit\" .-\u003e pr\n    review -- \"approve\" --\u003e readiness\n    readiness --\u003e merge\n    merge --\u003e verify\n    verify --\u003e ci_wait --\u003e k8s_wait --\u003e agent\n    agent -- \"pass\" --\u003e pass_ev\n    agent -- \"fail\" --\u003e fail_ev\n\n    classDef ext fill:#4a90d9,stroke:#2c5ea0,color:#fff\n    classDef core fill:#e8a838,stroke:#b8842c,color:#000\n    classDef agent_s fill:#c084fc,stroke:#9061c2,color:#000\n    classDef danger fill:#f87171,stroke:#c25050,color:#fff\n\n    class pr ext\n    class gate,readiness,merge,verify,ci_wait,k8s_wait core\n    class review,agent agent_s\n    class block,reject,fail_ev danger\n    class pass_ev ext\n```\n\n### Alertmanager webhook\n\n```mermaid\nflowchart LR\n    am[\"Alertmanager\"]\n    webhook[\"POST /alertmanager/webhook\"]\n    filter[\"Фильтр:\u003cbr/\u003estatus = firing\"]\n    severity{\"severity\u003cbr/\u003ecritical/error?\"}\n    dedup[\"Dedup: query Tracker\u003cbr/\u003eсанитизированный alertname\"]\n    exists{\"дубликат?\"}\n    create[\"Создать задачу\u003cbr/\u003e+ компонент\"]\n    prompt[\"Форматировать\u003cbr/\u003e→ Supervisor\"]\n    skip[\"Пропустить\"]\n    component[\"Маппинг компонента:\u003cbr/\u003enamespace/service →\u003cbr/\u003eБекенд / Фронтенд / DevOps\"]\n\n    am --\u003e webhook --\u003e filter --\u003e severity\n    severity -- \"да\" --\u003e dedup --\u003e exists\n    exists -- \"нет\" --\u003e component --\u003e create\n    exists -- \"да\" --\u003e skip\n    severity -- \"нет\" --\u003e prompt\n\n    classDef ext fill:#4a90d9,stroke:#2c5ea0,color:#fff\n    classDef core fill:#e8a838,stroke:#b8842c,color:#000\n    classDef danger fill:#f87171,stroke:#c25050,color:#fff\n\n    class am ext\n    class webhook,filter,severity,dedup,exists,component core\n    class create,prompt ext\n    class skip danger\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzvenoai%2Fcoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzvenoai%2Fcoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzvenoai%2Fcoder/lists"}