81e0e383e0
- stages.py: QG renamed to check_analysis_approved (requires :approved: comment) - qg/checks.py: new check_analysis_approved verifies files + Plane :approved: comment - launcher.py: skip auto-advance for analysis stage (requires human approval) - plane.py: route check_analysis_approved in _try_advance_stage - docs/ARCHITECTURE.md: updated QG table and flow description
201 lines
8.0 KiB
Markdown
201 lines
8.0 KiB
Markdown
# Архитектура Orchestrator
|
||
|
||
## Обзор
|
||
|
||
Orchestrator — event-driven FastAPI сервис, который управляет жизненным циклом задач разработки через мульти-агентный пайплайн. Каждая задача проходит через фиксированные стадии, на каждой из которых работает специализированный Claude CLI агент.
|
||
|
||
## Компоненты
|
||
|
||
### 1. Webhook Receivers
|
||
|
||
#### Plane Webhook (`src/webhooks/plane.py`)
|
||
- Принимает `work_item.created` — создаёт задачу в DB, запускает analyst
|
||
- Принимает `work_item.updated` — синхронизация статусов
|
||
|
||
#### Gitea Webhook (`src/webhooks/gitea.py`)
|
||
- **push** — проверяет наличие артефактов (docs/, src/), продвигает стадию
|
||
- **pull_request\*** (wildcard) — обрабатывает review approved/rejected, PR merge
|
||
- **status** — CI green/failure, продвигает development → review
|
||
|
||
### 2. State Machine (`src/stages.py`)
|
||
|
||
Линейный пайплайн с одним возможным откатом (review → development):
|
||
|
||
```
|
||
STAGE_TRANSITIONS = {
|
||
created: → analysis (agent: None)
|
||
analysis: → architecture (agent: architect, QG: check_analysis_approved)
|
||
architecture: → development (agent: developer, QG: check_architecture_done)
|
||
development: → review (agent: reviewer, QG: check_ci_green)
|
||
review: → testing (agent: tester, QG: check_review_approved)
|
||
testing: → deploy (agent: None, QG: check_tests_passed)
|
||
deploy: → done (agent: None, QG: None)
|
||
}
|
||
```
|
||
|
||
### 3. Quality Gates (`src/qg/checks.py`)
|
||
|
||
| Check | Метод проверки |
|
||
|-------|---------------|
|
||
| check_analysis_approved | Filesystem: 4 файла + :approved: comment в Plane |
|
||
| check_architecture_done | Filesystem: ADR dir или infra-requirements.md |
|
||
| check_ci_green | Gitea API: GET /commits/{branch}/status |
|
||
| check_review_approved | Gitea API: GET /pulls/{n}/reviews (skip stale) |
|
||
| check_tests_passed | Filesystem: test-report.md содержит "PASS" |
|
||
|
||
### 4. Agent Launcher (`src/agents/launcher.py`)
|
||
|
||
Запускает Claude CLI как subprocess:
|
||
|
||
```bash
|
||
claude.exe --print --system-prompt --allowedTools Read,Write,Edit,Bash
|
||
```
|
||
|
||
Каждый запуск:
|
||
1. Записывает run в DB (agent_runs)
|
||
2. Запускает subprocess с stdout → `/app/data/runs/{id}.log`
|
||
3. Стартует **watchdog thread** (timeout 30 мин → SIGKILL)
|
||
4. Стартует **monitor thread** (ждёт завершения → git commit/push → auto-advance)
|
||
|
||
### 5. Auto-advance (`launcher._try_advance_stage`)
|
||
|
||
После успешного завершения агента:
|
||
1. Определяет текущую стадию задачи
|
||
2. Проверяет QG для выхода из стадии
|
||
3. Если QG пройден — продвигает стадию
|
||
4. Запускает следующего агента (если определён)
|
||
|
||
Исключение: `check_review_approved` — обрабатывается через PR webhook, не через auto-advance.
|
||
|
||
### 6. Review Bounce
|
||
|
||
При REQUEST_CHANGES:
|
||
1. Считает количество developer runs для задачи
|
||
2. Если < MAX_DEV_RETRIES (3) — откатывает в development, перезапускает developer
|
||
3. Если >= MAX_DEV_RETRIES — эскалация (логирование + уведомление)
|
||
|
||
## Database Schema
|
||
|
||
```sql
|
||
-- Задачи
|
||
CREATE TABLE tasks (
|
||
id INTEGER PRIMARY KEY,
|
||
work_item_id TEXT, -- Plane issue identifier (e.g. "ET-006")
|
||
plane_issue_id TEXT, -- Plane UUID
|
||
repo TEXT,
|
||
branch TEXT,
|
||
stage TEXT DEFAULT 'created',
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
|
||
-- Запуски агентов
|
||
CREATE TABLE agent_runs (
|
||
id INTEGER PRIMARY KEY,
|
||
task_id INTEGER REFERENCES tasks(id),
|
||
agent TEXT, -- analyst/architect/developer/reviewer/tester
|
||
started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
finished_at TIMESTAMP,
|
||
exit_code INTEGER,
|
||
output_path TEXT -- /app/data/runs/{id}.log
|
||
);
|
||
|
||
-- Сырые события
|
||
CREATE TABLE events (
|
||
id INTEGER PRIMARY KEY,
|
||
source TEXT, -- plane/gitea
|
||
event_type TEXT,
|
||
payload TEXT,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
## Deployment
|
||
|
||
### Docker Compose
|
||
|
||
```yaml
|
||
services:
|
||
orchestrator:
|
||
build: .
|
||
container_name: orchestrator
|
||
restart: unless-stopped
|
||
network_mode: host
|
||
volumes:
|
||
- ./data:/app/data # SQLite + logs
|
||
- /home/slin/repos:/repos # Git repositories
|
||
- /var/run/docker.sock:/var/run/docker.sock # Docker CLI
|
||
- claude-code:/opt/claude-code:ro # Claude CLI binary
|
||
- /home/slin/.claude:/home/slin/.claude # Claude config
|
||
env_file: .env
|
||
group_add: ["999"] # docker group
|
||
```
|
||
|
||
### Dockerfile
|
||
|
||
- Base: python:3.12-slim
|
||
- Docker CLI (sibling containers)
|
||
- **tini** как PID 1 (proper zombie reaping)
|
||
- `git config --global safe.directory '*'`
|
||
- ENTRYPOINT: tini → uvicorn
|
||
|
||
## Потоки данных
|
||
|
||
### Happy path (ET-006 пример)
|
||
|
||
```
|
||
1. Plane webhook: work_item.created → task created, analyst launched
|
||
2. Analyst: пишет BRD/TRZ/AC/TestPlan → git push docs/
|
||
3. Plane comment :approved: → QG check_analysis_approved → PASS
|
||
4. Auto-advance: analysis → architecture, architect launched
|
||
5. Architect: пишет ADR, infra-requirements → git push docs/
|
||
6. Gitea push webhook: ADR detected → QG check_architecture_done → PASS
|
||
7. Auto-advance: architecture → development, developer launched
|
||
8. Developer: пишет код src/ + tests/ → git push, creates PR
|
||
9. Gitea status webhook: CI green → QG check_ci_green → PASS
|
||
10. Auto-advance: development → review, reviewer launched
|
||
11. Reviewer: оставляет review (APPROVED или REQUEST_CHANGES)
|
||
12. Gitea PR webhook: review event → QG check_review_approved → PASS
|
||
13. Advance: review → testing, tester launched
|
||
14. Tester: прогоняет тесты, пишет test-report.md → git push
|
||
15. Auto-advance: testing → deploy (QG check_tests_passed → PASS)
|
||
16. PR merge → Gitea PR webhook: action=closed, merged=true → done
|
||
```
|
||
|
||
### Review bounce path
|
||
|
||
```
|
||
11. Reviewer: REQUEST_CHANGES
|
||
12. Gitea PR webhook: review_state=REQUEST_CHANGES, stage=review
|
||
13. Rollback: review → development, developer relaunched (attempt N/3)
|
||
14. Developer: фиксит замечания → git push
|
||
15. CI green → development → review, reviewer relaunched
|
||
16. Reviewer: APPROVED → continue happy path
|
||
```
|
||
|
||
## Resilience
|
||
|
||
| Механизм | Описание |
|
||
|----------|----------|
|
||
| Orphan recovery | При старте: runs без finished_at старше 35 мин → exit_code=-1 |
|
||
| Watchdog | Каждый агент: timeout 30 мин → SIGKILL + exit_code=-9 |
|
||
| tini | PID 1 reaper — zombie processes невозможны |
|
||
| safe.directory | git операции работают в любой директории |
|
||
| Stale review skip | check_review_approved игнорирует stale reviews |
|
||
| Max retries | Developer: max 3 попытки, затем эскалация |
|
||
|
||
## Агенты
|
||
|
||
Каждый агент — Claude CLI с:
|
||
- **System prompt**: `.openclaw/agents/{role}.md` (в репозитории)
|
||
- **Task file**: `.task-{suffix}.md` (генерируется orchestrator)
|
||
- **Tools**: Read, Write, Edit, Bash
|
||
- **Output**: `--print` mode (весь вывод в stdout после завершения)
|
||
|
||
| Агент | Артефакты | Время (типичное) |
|
||
|-------|-----------|-------------------|
|
||
| analyst | BRD, TRZ, AC, TestPlan | 5-10 мин |
|
||
| architect | ADR, infra-requirements, tech-risks | 5-10 мин |
|
||
| developer | src/, tests/, PR | 15-30 мин |
|
||
| reviewer | review report, PR review | 3-5 мин |
|
||
| tester | test-report.md, e2e results | 10-25 мин |
|