200 lines
22 KiB
Markdown
200 lines
22 KiB
Markdown
---
|
||
work_item: ORCH-011
|
||
stage: analysis
|
||
author_agent: analyst
|
||
status: ready-for-review
|
||
created_at: 2026-06-11
|
||
model_used: claude-opus-4-8
|
||
---
|
||
|
||
# 01 — BRD: ORCH-011 — Полная документация системы мультиагентов оркестратора (бизнес + тех, для людей и презентаций)
|
||
|
||
Work Item: **ORCH-011** · Repo: **orchestrator** (self-hosting) · Стадия: analysis
|
||
Заказчик: Владелец (Слава)
|
||
Тип: docs+tests (паттерн ORCH-102/103 — golden-source-документ + структурные анти-дрейф тесты; рантайм не трогается)
|
||
|
||
---
|
||
|
||
## 1. Бизнес-контекст и проблема
|
||
|
||
### 1.1. Цель
|
||
Описать работу **всей** мультиагентной системы оркестратора в **одном месте** — от бизнес-смысла
|
||
(зачем, какую проблему решает, что умеет) до технического устройства (архитектура, конвейер,
|
||
агенты, модель объектов, интеграции, качество, наблюдаемость). Документация нужна, чтобы:
|
||
1. **другие люди** (разработчики, заказчики, менеджеры проектов) могли разобраться, как работает
|
||
оркестратор, не раскапывая 60+ work-item пакетов и 40 ADR;
|
||
2. на её основе **генерировать презентационные материалы** по использованию и возможностям
|
||
(решение Владельца: слайды PowerPoint, стильный тёмный дизайн, точный рендеринг).
|
||
|
||
### 1.2. Корневая проблема — документация богатая, но фрагментированная
|
||
Установленные факты (проверено по дереву репо, не изобретать):
|
||
|
||
| Что есть | Где | Ограничение как «единого места» |
|
||
|----------|-----|---------------------------------|
|
||
| Паспорт проекта | `CLAUDE.md` | для агентов/разработчиков; плотный реестр доработок, не вводный текст |
|
||
| Тех-витрина | `README.md` | только технический уровень; обзор без бизнес-слоя |
|
||
| Бизнес-видение | `docs/PRODUCT_VISION.md` (v1.0, 2026-06-04) | «концепция развития» (vision), не описание текущего состояния; не покрывает тех-уровень |
|
||
| Детальная архитектура | `docs/architecture/README.md` (~1246 строк), `internals.md` | глубокий справочник для инженеров; нечитаем «с нуля» нетехническим читателем |
|
||
| Решения | `docs/architecture/adr/` (40 сквозных ADR) + per-work-item ADR | точечные решения, не цельная картина |
|
||
| Стандарты | `docs/_standards/` (PIPELINE_DOCS, HANDOFF_PROTOCOL, TRACEABILITY) | нормативы для агентов |
|
||
| Эксплуатация/тираж | `docs/operations/` (8 runbook'ов), `docs/deployment/` (LITE_SETUP, BUNDLED_SETUP) | операторские инструкции |
|
||
| История/уроки | `docs/history/`, `docs/epics/self-evolution.md` | сырьё, не витрина |
|
||
|
||
**Ни один** из этих документов не является единой точкой входа «бизнес + тех» для трёх целевых
|
||
аудиторий. Новому человеку (заказчику, менеджеру, новому разработчику) сегодня нужно собирать
|
||
картину из 5–8 разных мест с разной степенью детализации и разным языком. Презентацию о
|
||
возможностях системы собирать не из чего — нет слайдо-готового источника.
|
||
|
||
### 1.3. Почему сейчас
|
||
- Платформа достигла тиражируемости (ORCH-101/102/103: Lite- и Bundled-развёртывание у заказчика)
|
||
— появился **внешний читатель** (заказчики-тестеры), которому нужно объяснять систему.
|
||
- Самовоспроизводящийся темп доработок (self-hosting) без единой витрины делает порог входа всё
|
||
выше с каждой задачей.
|
||
|
||
### 1.4. Решения Владельца (из бизнес-запроса) — приняты как требования
|
||
| # | Решение |
|
||
|---|---------|
|
||
| D-1 | Формат презентационных материалов — **слайды PowerPoint**, стильный **тёмный дизайн**, точный рендеринг. |
|
||
| D-2 | Аудитория документации — **разработчики, заказчики, менеджеры проектов** (три явных маршрута чтения). |
|
||
| D-3 | Единое место — репозиторий orchestrator: `docs/` (+ возможно compiled-wiki — как опция, см. §2.2). |
|
||
| D-4 | Поддерживать в актуальном состоянии: документация обновляется **сразу после изменения функционала** (правило CLAUDE.md §2 распространяется на новую витрину). |
|
||
|
||
---
|
||
|
||
## 2. Объём (scope)
|
||
|
||
### 2.1. В объёме
|
||
- **Единая витрина системы** — новый связный раздел в `docs/` с одной точкой входа (индексом),
|
||
покрывающий **два уровня**:
|
||
- **Бизнес-уровень** (для нетехнических читателей и презентаций): зачем нужен оркестратор и
|
||
какую проблему решает; что умеет (автономный конвейер «задача → прод», мультипроектность,
|
||
самовосстановление, пакетный авто-режим, багфикс-трек, тиражируемость); ценность и
|
||
возможности простым языком; сценарии использования.
|
||
- **Технический уровень** (7 блоков, контент-карта — TRZ §3):
|
||
1) архитектура — компоненты и их связи; 2) конвейер/стадии и гейты на переходах;
|
||
3) агенты — 6 ролей, входы/выходы, артефакты, шаблоны; 4) структура объектов —
|
||
Project/Work-Item, реестр проектов, jobs-очередь, события/дедуп, каноническая модель БД;
|
||
5) интеграции — Plane, Gitea, LLM-модели, Telegram; 6) качество/безопасность;
|
||
7) аналитика/наблюдаемость.
|
||
- **Маршруты чтения** для трёх аудиторий (D-2): «я заказчик / я менеджер / я разработчик —
|
||
с чего начать и что читать дальше».
|
||
- **Презентационная основа** (D-1): слайдо-структурированный источник (последовательность
|
||
слайдов: заголовок/тезисы/визуальный мотив) + воспроизводимый путь получения `.pptx` в тёмном
|
||
дизайне. Выбор инструмента генерации — за архитектором (TRZ §3.4, OQ-2).
|
||
- **Норматив сопровождения**: правило «изменил функционал → обнови витрину в том же PR»
|
||
зафиксировано в витрине и в правилах агентов (D-4; ось reviewer'а по обзорным докам уже
|
||
существует — ORCH-079).
|
||
- **Анти-дрейф**: структурные pytest-тесты каркаса витрины (по образцу
|
||
`tests/test_lite_setup_doc.py` / `test_bundled_setup_doc.py`): обязательные разделы, сверка
|
||
карты стадий импортом `src/stages.py::STAGE_TRANSITIONS`, полнота 6 агентов, валидность
|
||
внутренних ссылок, запрет секретов/хост-хардкодов.
|
||
- Обновление указателей: `README.md`, `CLAUDE.md` (ссылка на витрину), `CHANGELOG.md`.
|
||
|
||
### 2.2. Вне объёма (явно, не делать)
|
||
- **Любые изменения рантайма:** `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`,
|
||
machine-verdict ключи, схема БД, compose/Dockerfile — байт-в-байт.
|
||
- **Compiled-wiki / внешняя вики-платформа** — вне объёма v1: репозиторий остаётся единственным
|
||
источником истины («канон не форкается», паттерн ORCH-009 BR-2); экспорт в wiki — возможное
|
||
развитие, фиксируется как открытый вопрос (TRZ §9 OQ-4), не реализуется.
|
||
- **Перенос вне-репозиторных источников в репо**: `tasks/orchestrator/STATUS.md`, `BACKLOG.md`,
|
||
PROGRESS-журналы, дневники `memory/` физически в репозитории отсутствуют — они служат лишь
|
||
затравками для содержания; сами файлы в гит не переносятся (внутренняя кухня, риск утечки
|
||
контекста/секретов).
|
||
- **Переписывание/замена существующих golden sources** (`docs/architecture/README.md`,
|
||
`internals.md`, стандарты `docs/_standards/`, deployment-доки): витрина ссылается на них,
|
||
а не дублирует и не подменяет (анти-«второй источник истины», BR-4).
|
||
- **Автогенерация документации из кода** (doc-from-code, autodoc) — вне объёма.
|
||
- **Маркетинговые материалы за пределами PPTX-основы** (видео, лендинги, демо-стенды).
|
||
- Новые runtime-зависимости прод-образа (включая библиотеки генерации презентаций) — запрещено
|
||
(NFR-2).
|
||
|
||
---
|
||
|
||
## 3. Заинтересованные стороны
|
||
- **Владелец/оператор (Слава)** — заказчик задачи; принимает витрину и презентационную основу;
|
||
использует слайды для показа возможностей платформы.
|
||
- **Заказчики платформы** (внешние, включая тестеров Lite/Bundled-тиража ORCH-102/103) — читают
|
||
бизнес-уровень и сценарии; смотрят презентацию.
|
||
- **Менеджеры проектов** — читают бизнес-уровень + конвейер/статусную модель (что видно в Plane,
|
||
какие человеческие гейты есть).
|
||
- **Разработчики** (люди и агенты самого оркестратора) — входят через витрину в технический
|
||
уровень и далее по ссылкам в golden sources.
|
||
- **Reviewer-агент конвейера** — контролирует соблюдение норматива сопровождения витрины
|
||
(расширение оси «обзорные доки» ORCH-079).
|
||
|
||
---
|
||
|
||
## 4. Бизнес-требования (BR)
|
||
|
||
| ID | Требование | Связь |
|
||
|----|------------|-------|
|
||
| BR-1 | В `docs/` существует **единая точка входа** (индекс витрины), из которой достижимы оба уровня (бизнес/тех) и все 7 тех-блоков; любой из трёх читателей начинает с одного места. | D-3, AC-1 |
|
||
| BR-2 | **Бизнес-уровень** читается нетехническим человеком: проблема → решение → ценность → возможности → сценарии использования; термины конвейера объяснены по-человечески; без необъяснённого жаргона и кодовых идентификаторов в основном тексте. | D-2, AC-2 |
|
||
| BR-3 | **Технический уровень** покрывает все 7 заявленных блоков (§2.1) и соответствует фактическому коду/канону репо: карта стадий = `STAGE_TRANSITIONS`, реестр гейтов = `QG_CHECKS` + под-гейты, агенты = 6 промптов `.openclaw/agents/` + таблица модель/эффорт (ORCH-41), модель данных = фактические таблицы `src/db.py`. | AC-3, AC-4, AC-5 |
|
||
| BR-4 | **Link-first / не форкается канон:** витрина даёт цельную картину и ссылается на golden sources за деталями (architecture/README, internals, стандарты, ADR, deployment-доки); не создаёт второй источник истины и не противоречит коду. | §2.2, AC-6 |
|
||
| BR-5 | **Презентационная основа:** в репо есть слайдо-структурированный источник (бизнес-нарратив → слайды) и воспроизводимый, документированный путь получения `.pptx` в тёмном дизайне (D-1). Инструмент — выбор архитектора; запуск — вне рантайма конвейера. | D-1, AC-7 |
|
||
| BR-6 | **Маршруты аудиторий:** витрина содержит явные маршруты чтения для заказчика / менеджера / разработчика (D-2). | D-2, AC-8 |
|
||
| BR-7 | **Норматив сопровождения:** правило «изменил функционал → обнови витрину в том же PR» зафиксировано в витрине и видимо агентам (CLAUDE.md-указатель); reviewer-ось обзорных доков покрывает витрину. | D-4, AC-9 |
|
||
| BR-8 | **Анти-дрейф:** каркас витрины и её ключевые машинно-проверяемые факты (стадии, агенты, ссылки, отсутствие секретов) защищены структурными pytest-тестами; их падение ловит расхождение витрины с кодом. | AC-10 |
|
||
| BR-9 | Существующие указатели актуализированы: `README.md` и `CLAUDE.md` ссылаются на витрину; `CHANGELOG.md` несёт запись. | AC-11 |
|
||
|
||
---
|
||
|
||
## 5. Нефункциональные требования (NFR)
|
||
|
||
| ID | Требование |
|
||
|----|------------|
|
||
| NFR-1 | **docs+tests only:** `src/**` байт-в-байт; `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict ключи / схема БД / compose / Dockerfile — не тронуты. Kill-switch не нужен: документация не исполняется (паттерн ORCH-102/103). |
|
||
| NFR-2 | **Прод-образ без новых зависимостей:** генерация презентации (если скриптом) исполняется вне рантайма (host/dev-окружение, явный запуск человеком — паттерн ORCH-009); зависимости генерации НЕ попадают в `requirements`/образ оркестратора. |
|
||
| NFR-3 | **Без секретов и хост-специфики** в новых доках/источниках презентации: токены, внутренние URL/имена хостов — только плейсхолдерами (паттерн `tests/test_no_host_hardcodes.py` / fenced-скан `test_lite_setup_doc.py`). |
|
||
| NFR-4 | **Язык:** русский (канон репо; языковое исключение deployer.md не затрагивается). Терминология единая со статусной моделью Plane (ORCH-066) и PIPELINE_DOCS. |
|
||
| NFR-5 | **Self-hosting safety:** задача не рестартит/не роняет прод-контейнер; прод-деплой — только штатным маршрутом конвейера (staging-гейт + Confirm Deploy). |
|
||
| NFR-6 | **Поддерживаемость:** витрина модульная (отдельные файлы по блокам, связанные индексом), чтобы будущие правки были точечными; объём основного текста разумен за счёт link-first (BR-4). |
|
||
|
||
---
|
||
|
||
## 6. Допущения и ограничения
|
||
- **Вне-репозиторные затравки** (`tasks/orchestrator/STATUS.md`, `BACKLOG.md`, PROGRESS-журналы,
|
||
`memory/`) в worktree недоступны — содержание витрины строится из **внутрирепозиторных** golden
|
||
sources (CLAUDE.md, README, PRODUCT_VISION, architecture/, _standards/, ADR, deployment/,
|
||
history/). Этого достаточно: репо самодостаточен по фактам (проверено §1.2).
|
||
- `docs/PRODUCT_VISION.md` остаётся самостоятельным vision-документом; витрина переиспользует его
|
||
бизнес-нарратив со сверкой с фактическим состоянием (что из vision уже реализовано — например,
|
||
тираж ORCH-101/102/103) и ссылается на него.
|
||
- Точное имя/структура каталога витрины — решение архитектора (рекомендация TRZ §2: новый каталог
|
||
в `docs/`, например `docs/overview/`); анти-дрейф тесты пишутся под выбранные пути.
|
||
- Бинарный артефакт `.pptx`: коммит бинаря в git спорен — решает архитектор (OQ-3); требование
|
||
BR-5 — воспроизводимость пути генерации, не обязательность бинаря в репо.
|
||
- Задача объёмная по контенту: допускается реализация витрины «вглубь по блокам» в одном PR
|
||
(один прогон developer); если объём не помещается — эскалация на уровне задач (разбиение)
|
||
по штатному маршруту, не молчаливое сокращение объёма.
|
||
|
||
---
|
||
|
||
## 7. Критерии успеха (резюме; детали — 03-acceptance-criteria.md)
|
||
- AC-1 единая точка входа существует и связывает оба уровня и маршруты аудиторий.
|
||
- AC-2 бизнес-уровень самодостаточен для нетехнического читателя.
|
||
- AC-3…AC-5 тех-уровень покрывает 7 блоков и сходится с кодом (стадии/гейты/агенты/модель данных).
|
||
- AC-6 link-first: ссылки на golden sources валидны, дублирования-противоречий нет.
|
||
- AC-7 презентационная основа есть; путь к `.pptx` (тёмный дизайн) воспроизводим и документирован.
|
||
- AC-8 маршруты трёх аудиторий присутствуют.
|
||
- AC-9 норматив сопровождения зафиксирован.
|
||
- AC-10 структурные анти-дрейф тесты существуют и зелёные; полный pytest зелёный.
|
||
- AC-11 README/CLAUDE.md/CHANGELOG обновлены; `src/**` не тронут.
|
||
|
||
---
|
||
|
||
## 8. Риски (кратко; детали — 10-tech-risks.md, заполняет архитектор)
|
||
- **R-1 — гниение витрины.** Self-hosting темп (несколько задач в неделю) быстро устаревает любой
|
||
снапшот. Митигция: link-first (BR-4) + норматив сопровождения (BR-7) + структурные тесты на
|
||
машинно-проверяемые факты (BR-8) — дрейф ловится CI, а не глазами.
|
||
- **R-2 — второй источник истины.** Дублирование деталей architecture/README в витрине приведёт к
|
||
противоречиям. Митигция: витрина = картина + ссылки; детали живут в существующих golden sources.
|
||
- **R-3 — объём одного прогона.** Полная витрина + презентация + тесты могут не поместиться в один
|
||
PR разумного размера. Митигция: модульность (NFR-6), приоритет блоков, при необходимости —
|
||
эскалация/разбиение (допущение §6).
|
||
- **R-4 — зависимость генерации презентации.** Библиотека генерации PPTX в прод-образе — лишний
|
||
attack-surface/вес. Митигция: NFR-2 (вне рантайма), решение по инструменту — ADR архитектора.
|
||
- **R-5 — расползание скопа в маркетинг.** Слайды → «а давайте ещё видео/лендинг». Митигция:
|
||
жёсткая граница §2.2.
|