claude-bot
e2cf883603
Единый операторский CLI scripts/setup_lite.py — исполняемый инструмент Lite-тиража поверх документа-канона docs/deployment/LITE_SETUP.md (ORCH-102). Автоматизирует маршрут §2–§12: скан предусловий хоста с офером доустановки → discovery docker-инсталляций Plane/Gitea → интерактивный сбор обязательных ключей с немедленной верификацией → автодетект хост-параметров и когерентность портов → сборка .env/.env.watchdog от канонов → webhook Plane → guard-ы Gitea → подъём ровно orchestrator+orchestrator-watchdog → регистрация проекта строго кирпичом onboard_project.py → итоговый отчёт PASS/FAIL/MANUAL. Scripts+docs+tests (паттерн ORCH-009/103): рантайм src/**, корневой docker-compose.yml, Dockerfile, .env.example/.env.watchdog.example, STAGE_TRANSITIONS/QG_CHECKS/check_*/machine-verdict/схема БД — байт-в-байт. kill-switch не нужен (активация — только явный запуск CLI человеком на целевом хосте; в нашем контуре артефакт инертен). - D1/D2: stdlib-only, один файл; режимы plan/apply/verify (closed choices), дефолт apply (бизнес-цель «одна команда»); безопасность структурно — фаза 0 ≡ plan, ранний guard чужого .env, per-action consent, non-TTY без --yes → exit 2 ДО мутаций. Exit 0/2/1; resume = повторный запуск (check→ensure по реальности, без state-файла). - D3: 10 нормативных шагов, инвариант APPLY_STEPS == build_plan(). - D4–D11: решающая логика — чистые функции (вердикты предусловий, classifier discovery строго по image-префиксам, port_overrides когерентной тройкой, staging==prod fail-closed, рендер env с маркером managed-файла, C-1 ORCH-100 машинно, §6.4 branch protection без удаления, webhook Plane Path A/Б, build_onboard_args). - NFR-1/3: src.* не импортируется; секреты скрыты и не печатаются; delete-операций нет; никаких операций с main; рестарт — только собственного контура. - D12: LITE_SETUP.md §1.1 + footer-норматив; tests/test_setup_lite_script.py (47 unit/structural); аддитивный TC-27 в test_lite_setup_doc.py; витрина docs/overview + docs/architecture/README дополнены; CHANGELOG + CLAUDE.md (паспорт) обновлены. Refs: ORCH-104 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
91 lines
7.2 KiB
Markdown
91 lines
7.2 KiB
Markdown
# Витрина системы — Orchestrator
|
||
|
||
**Что это за система.** Orchestrator — автономная фабрика разработки: конвейер из шести
|
||
ИИ-агентов (аналитик → архитектор → разработчик → ревьюер → тестировщик → деплойер), который
|
||
проводит задачу от бизнес-постановки до выкладки на прод. Человек ставит задачу и принимает
|
||
результат; всё между — автономно, под защитой машинных гейтов качества. Платформа ведёт
|
||
несколько проектов из одного инстанса, дорабатывает сама себя (self-hosting) и тиражируется
|
||
на новые хосты.
|
||
|
||
**Зачем эта витрина.** Это единая точка входа в документацию системы: связное описание на двух
|
||
уровнях — бизнес (для нетехнического читателя) и технический (7 блоков), с маршрутами чтения
|
||
для трёх аудиторий и слайдо-готовой основой для презентации. Витрина — обзор; за деталями она
|
||
ведёт ссылками в инженерные golden sources, не подменяя их.
|
||
|
||
---
|
||
|
||
## Состав витрины
|
||
|
||
| Файл | О чём |
|
||
|------|-------|
|
||
| [business.md](business.md) | Бизнес-уровень: проблема, решение, что умеет, ценность, сценарии |
|
||
| [tech-architecture.md](tech-architecture.md) | Блок 1: компоненты и связи, схема потока |
|
||
| [tech-pipeline.md](tech-pipeline.md) | Блок 2: конвейер, стадии, гейты, откаты, человеческие гейты |
|
||
| [tech-agents.md](tech-agents.md) | Блок 3: 6 ролей агентов, артефакты, модель/эффорт |
|
||
| [tech-data-model.md](tech-data-model.md) | Блок 4: каноническая модель объектов, словарь терминов |
|
||
| [tech-integrations.md](tech-integrations.md) | Блок 5: Plane, Gitea, LLM, Telegram |
|
||
| [tech-quality-security.md](tech-quality-security.md) | Блок 6: гейты качества, безопасность, секреты |
|
||
| [tech-observability.md](tech-observability.md) | Блок 7: наблюдаемость, аналитика, журнал уроков |
|
||
| [presentation.md](presentation.md) | Слайдо-источник презентации + сборка `.pptx` |
|
||
|
||
---
|
||
|
||
## Маршруты чтения
|
||
|
||
### Я заказчик
|
||
1. [business.md](business.md) — проблема, решение, ценность.
|
||
2. [business.md → Сценарии использования](business.md#сценарии-использования) — как это выглядит в работе.
|
||
3. [presentation.md](presentation.md) — слайдовая версия рассказа (собирается в PowerPoint).
|
||
4. Развернуть у себя: [LITE_SETUP](../deployment/LITE_SETUP.md) (своя инфраструктура;
|
||
быстрый путь — интерактивный installer `scripts/setup_lite.py`, ORCH-104) или
|
||
[BUNDLED_SETUP](../deployment/BUNDLED_SETUP.md) (весь стек одним комплектом).
|
||
|
||
### Я менеджер проекта
|
||
1. [business.md](business.md) — что платформа делает и где в процессе человек.
|
||
2. [tech-pipeline.md](tech-pipeline.md) — конвейер, статусная модель Plane, человеческие гейты
|
||
(одобрение постановки, подтверждение прод-деплоя).
|
||
3. [tech-observability.md](tech-observability.md) — как следить за ходом: живая Telegram-карточка,
|
||
статусы, стоимость.
|
||
|
||
### Я разработчик
|
||
1. Тех-блоки 1→7: [архитектура](tech-architecture.md) → [конвейер](tech-pipeline.md) →
|
||
[агенты](tech-agents.md) → [модель объектов](tech-data-model.md) →
|
||
[интеграции](tech-integrations.md) → [качество/безопасность](tech-quality-security.md) →
|
||
[наблюдаемость](tech-observability.md).
|
||
2. [Инженерный справочник архитектуры](../architecture/README.md) и
|
||
[internals](../architecture/internals.md) — детали реализации.
|
||
3. [Стандарты](../_standards/PIPELINE_DOCS.md) (структура доков конвейера),
|
||
[HANDOFF_PROTOCOL](../_standards/HANDOFF_PROTOCOL.md) (машинный контракт стадий),
|
||
[TRACEABILITY](../_standards/TRACEABILITY.md) (маркеры решений).
|
||
4. [Реестр сквозных ADR](../architecture/adr/) — история архитектурных решений.
|
||
5. [CLAUDE.md](../../CLAUDE.md) — паспорт проекта и правила для агентов.
|
||
|
||
---
|
||
|
||
## Норматив сопровождения
|
||
|
||
> **Изменил функциональность платформы → обнови витрину `docs/overview/` в том же PR.**
|
||
|
||
Какой файл правится при каком классе изменений:
|
||
|
||
| Класс изменения | Файл витрины |
|
||
|-----------------|--------------|
|
||
| Новый компонент / демон / поток данных | [tech-architecture.md](tech-architecture.md) |
|
||
| Стадии, гейты, под-гейты, маршруты задач | [tech-pipeline.md](tech-pipeline.md) |
|
||
| Роли агентов, промпты, модель/эффорт | [tech-agents.md](tech-agents.md) |
|
||
| Таблицы БД, объекты, термины | [tech-data-model.md](tech-data-model.md) |
|
||
| Plane / Gitea / LLM / Telegram | [tech-integrations.md](tech-integrations.md) |
|
||
| Гейты качества, секреты, self-hosting-страховки | [tech-quality-security.md](tech-quality-security.md) |
|
||
| Эндпоинты наблюдаемости, метрики, уроки | [tech-observability.md](tech-observability.md) |
|
||
| Новая способность уровня продукта | [business.md](business.md) + при необходимости [presentation.md](presentation.md) |
|
||
|
||
Каркас и машинно-проверяемые факты витрины (перечень стадий, имена гейтов, полнота агентов,
|
||
валидность ссылок) защищены структурными тестами `tests/test_system_docs.py` — дрейф рвёт CI.
|
||
Прозу проверяет reviewer: необновлённая витрина при изменении описанной в ней функциональности —
|
||
finding ≥ P1 (расширение оси обзорных доков).
|
||
|
||
---
|
||
|
||
*Витрина — обзорный слой документации. Текущее состояние и реестр доработок — [CLAUDE.md](../../CLAUDE.md);
|
||
концепция развития — [Product Vision](../PRODUCT_VISION.md).*
|