172 lines
6.7 KiB
Markdown
172 lines
6.7 KiB
Markdown
# Документация: Orchestrator Multi-Agent Pipeline
|
||
|
||
## Статус: 2026-06-01 (актуально)
|
||
|
||
---
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
Plane (Work Items) → Webhook → Orchestrator → Claude CLI agents → Gitea → Deploy
|
||
```
|
||
|
||
**Orchestrator** — Python FastAPI приложение в Docker на mva154 (port 8500).
|
||
Слушает webhooks от Plane и Gitea, управляет жизненным циклом задач.
|
||
|
||
---
|
||
|
||
## Конвейер (Pipeline)
|
||
|
||
```
|
||
created → analysis → architecture → development → review → testing → deploy → done
|
||
```
|
||
|
||
| Stage | Agent | QG (вход) | Что делает |
|
||
|-------|-------|-----------|------------|
|
||
| analysis | analyst | — | BRD, ТЗ, AC, Test Plan |
|
||
| architecture | architect | check_analysis_approved (`:approved:` от Славы) | ADR, архитектурные решения |
|
||
| development | developer | check_architecture_done (файлы ADR есть) | Код + тесты + PR |
|
||
| review | reviewer | check_ci_green (Gitea CI status) | Code review → 12-review.md |
|
||
| testing | tester | check_reviewer_verdict (APPROVED в 12-review.md) | Прогон тестов → 13-test-report.md |
|
||
| deploy | deployer | check_tests_passed (PASS в 13-test-report.md) | Merge PR → tag → deploy → smoke |
|
||
| done | — | — | Задача завершена |
|
||
|
||
---
|
||
|
||
## Агенты
|
||
|
||
### Конфигурация (AGENT_CONFIGS)
|
||
|
||
| Agent | Task file | System prompt | Model |
|
||
|-------|-----------|---------------|-------|
|
||
| analyst | `.task.md` | `.openclaw/agents/analyst.md` | claude-sonnet-4-6 |
|
||
| architect | `.task-arch.md` | `.openclaw/agents/architect.md` | claude-sonnet-4-6 |
|
||
| developer | `.task-dev.md` | `.openclaw/agents/developer.md` | claude-sonnet-4-6 |
|
||
| reviewer | `.task-review.md` | `.openclaw/agents/reviewer.md` | claude-sonnet-4-6 |
|
||
| tester | `.task-test.md` | `.openclaw/agents/tester.md` | claude-sonnet-4-6 |
|
||
| deployer | `.task-deploy.md` | `.openclaw/agents/deployer.md` | claude-sonnet-4-6 |
|
||
|
||
### Deployer (добавлен 2026-06-01)
|
||
|
||
**Функции:**
|
||
1. Merge PR через Gitea API
|
||
2. Создать semver tag (patch increment)
|
||
3. Deploy (git pull main на сервере)
|
||
4. Healthcheck (до 60 сек, 12 попыток)
|
||
5. Smoke test (ключевые endpoints)
|
||
6. Rollback к предыдущему тегу при fail
|
||
7. Записать `14-deploy-log.md` + обновить `CHANGELOG.md`
|
||
|
||
**Запрещено:** менять код, force push, деплоить без merge.
|
||
|
||
---
|
||
|
||
## Quality Gates
|
||
|
||
| QG | Функция | Что проверяет |
|
||
|----|---------|---------------|
|
||
| check_analysis_approved | `:approved:` в комментарии Plane от стейкхолдера | Человеческое подтверждение ТЗ |
|
||
| check_architecture_done | Наличие ADR файлов в `docs/work-items/<id>/06-adr/` | Архитектура задокументирована |
|
||
| check_ci_green | Gitea commit status API | CI pipeline зелёный |
|
||
| check_reviewer_verdict | Парсинг `12-review.md` → APPROVED/REQUEST_CHANGES | Код прошёл ревью |
|
||
| check_tests_passed | Парсинг `13-test-report.md` → PASS/FAIL | Тесты пройдены |
|
||
|
||
---
|
||
|
||
## Механизмы автономности
|
||
|
||
### Auto-advance
|
||
После завершения агента (exit 0), `_monitor_agent` вызывает `_try_advance_stage`:
|
||
1. Определяет текущий stage задачи
|
||
2. Проверяет QG следующего stage
|
||
3. Если QG green → advance stage → launch next agent
|
||
4. Если QG red → stop (ждёт внешнего события)
|
||
|
||
### Auto-PR
|
||
После developer push, `_ensure_pr()` автоматически создаёт PR в Gitea.
|
||
|
||
### Retry (developer)
|
||
При `REQUEST_CHANGES` от reviewer'а — developer перезапускается (до 3 раз).
|
||
|
||
### Notifications
|
||
Telegram уведомления на каждом переходе stage + при ошибках.
|
||
|
||
---
|
||
|
||
## Файловая структура
|
||
|
||
```
|
||
/home/slin/repos/orchestrator/
|
||
├── src/
|
||
│ ├── main.py # FastAPI app
|
||
│ ├── config.py # Settings (env vars)
|
||
│ ├── db.py # SQLite (tasks, agent_runs)
|
||
│ ├── stages.py # STAGE_TRANSITIONS
|
||
│ ├── notifications.py # Telegram + Plane comments
|
||
│ ├── plane_sync.py # Plane API integration
|
||
│ ├── agents/
|
||
│ │ ├── launcher.py # AgentLauncher (AGENT_CONFIGS, launch, monitor)
|
||
│ │ └── __init__.py
|
||
│ ├── webhooks/
|
||
│ │ ├── gitea.py # Push, PR, CI status handlers
|
||
│ │ ├── plane.py # Comment handlers (:approved:)
|
||
│ │ └── __init__.py
|
||
│ └── qg/
|
||
│ ├── checks.py # QG check functions
|
||
│ └── __init__.py
|
||
├── docker-compose.yml
|
||
├── Dockerfile
|
||
└── requirements.txt
|
||
```
|
||
|
||
---
|
||
|
||
## Инфраструктура
|
||
|
||
- **Host:** mva154 (82.22.50.71)
|
||
- **Container:** `orchestrator` (port 8500)
|
||
- **Gitea:** localhost:3000 (в docker network)
|
||
- **Repos:** `/home/slin/repos/orchestrator`, `/repos/enduro-trails` (в контейнере)
|
||
- **DB:** SQLite (`/app/data/orchestrator.db`)
|
||
- **Logs:** `/app/data/logs/` (per-agent run logs)
|
||
|
||
---
|
||
|
||
## Единственная точка ручного вмешательства
|
||
|
||
**`:approved:` после analyst'а** — Слава подтверждает ТЗ в Plane.
|
||
|
||
Всё остальное — полностью автономно:
|
||
- architect запускается автоматически после approve
|
||
- developer → после architecture done
|
||
- reviewer → после CI green
|
||
- tester → после review approved
|
||
- deployer → после tests passed
|
||
- done → после deploy success
|
||
|
||
---
|
||
|
||
## Расхождения с Proposal v1
|
||
|
||
Полная таблица: `tasks/multi-agent/PROPOSAL_VS_REALITY.md`
|
||
|
||
Ключевые отличия от идеала:
|
||
- Designer не реализован (skip для не-UI задач)
|
||
- QG упрощены (проверка файлов, не lint-скрипты)
|
||
- Один environment (test), нет prod
|
||
- Нет budget tracking
|
||
- Все агенты на Sonnet (proposal: Architect/Reviewer на Opus)
|
||
|
||
---
|
||
|
||
## Changelog
|
||
|
||
| Дата | Изменение |
|
||
|------|-----------|
|
||
| 2026-05-31 | Fix: `_monitor_agent` PIPE streaming (race condition) |
|
||
| 2026-05-31 | Fix: `check_reviewer_verdict` вместо `check_review_approved` |
|
||
| 2026-05-31 | Add: `_ensure_pr` (auto-PR after developer push) |
|
||
| 2026-05-31 | Add: REQUEST_CHANGES retry logic (3 attempts) |
|
||
| 2026-06-01 | Add: **deployer agent** (merge → tag → deploy → smoke → rollback) |
|
||
| 2026-06-01 | Remove: `_auto_merge_pr` hardcode from `_try_advance_stage` |
|