From cf2289516e146459c33c99117ca13b6c54a28bbe Mon Sep 17 00:00:00 2001 From: Markov Date: Sun, 15 Feb 2026 18:00:47 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=BE=D0=B1=D0=BD=D0=BE=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D0=B5=20=D0=B0=D1=80=D1=85=D0=B8=D1=82=D0=B5?= =?UTF-8?q?=D0=BA=D1=82=D1=83=D1=80=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Tracker-centric модель - Переименование: backend→tracker, frontend→web-client - Канбан: Backlog + черновики + статусы - Зависимости задач - Файлы в задачах - Три уровня чатов (лобби, проект, задача) - Подписка агентов (all/mentions/assigned) - WebSocket протокол --- IDEAS.md | 553 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 298 insertions(+), 255 deletions(-) diff --git a/IDEAS.md b/IDEAS.md index d24e382..04f83d3 100644 --- a/IDEAS.md +++ b/IDEAS.md @@ -19,279 +19,319 @@ --- -## Архитектура +## Архитектура: Tracker-Centric -### Микросервисы (Python + FastAPI) +### Принцип -| Сервис | Описание | -|--------|----------| -| Gateway | API Gateway, аутентификация | -| Projects | Проекты, Git интеграция | -| Tasks | Задачи, канбан, подзадачи | -| Agents | Управление AI агентами | -| Chat | Чаты проектов | +**Tracker = центральный сервис.** Всё остальное — клиенты. -### Frontend (Next.js) +``` +┌─────────────────────────────────────────────────────┐ +│ WEB CLIENT │ +│ ┌───────────┐ ┌────────────┐ │ +│ │ Next.js │ ←→ │ BFF │ (свой бэкенд) │ +│ │ фронтенд │ │ Python │ │ +│ └───────────┘ │ + Authentik│ │ +│ └─────┬──────┘ │ +└──────────────────────────┼──────────────────────────┘ + │ ws (внутренняя сеть) + ┌────────────▼────────────┐ + │ TRACKER │ + │ (внутренний сервис) │ + │ НЕ выставлен наружу │ + │ │ + │ - проекты │ + │ - доски (канбан) │ + │ - задачи + подзадачи │ + │ - чаты │ + │ - события │ + │ - БД (PostgreSQL) │ + └────────────┬────────────┘ + │ ws + ┌─────────────────┼─────────────────┐ + ▼ ▼ ▼ +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Агент 1 │ │ Агент 2 │ │ Агент N │ +│ (Claude) │ │ (Codex) │ │ (Gemini) │ +│ отд. сервис │ │ отд. сервис │ │ отд. сервис │ +└──────────────┘ └──────────────┘ └──────────────┘ +``` -Web UI для управления всем. +### Компоненты -### Database +| Компонент | Описание | +|-----------|----------| +| **Tracker** | Ядро: проекты, задачи, чаты, события. Внутренний, WebSocket сервер | +| **Web Client** | Next.js + BFF (Python). Авторизация через Authentik. Единственное что торчит наружу | +| **Агенты** | Отдельные сервисы. Подключаются к трекеру по WebSocket | -PostgreSQL (существующий на сервере). +### Репозитории + +``` +team-board/ +├── tracker/ — ядро (Python, WebSocket, PostgreSQL) +├── web-client/ — Next.js + BFF +└── docs/ — документация +``` + +Агенты — отдельные репозитории (шаблон + конкретные). --- -## UI Layout +## Канбан-доска + +### Колонки ``` -┌────────────────────────────────────────────────────────────────────┐ -│ [Logo] Team Board [User Avatar] ▼ │ -├──────────────┬─────────────────────────────────────────────────────┤ -│ │ Project Alpha [Settings] │ -│ PROJECTS │─────────────────────────────────────────────────────│ -│ │ 💬 Chat ▼ (сворачиваемый) │ -│ ○ Alpha │ ┌──────────────────────────────────────────────┐ │ -│ ● Beta │ │ Agent-1: Закоммитил фикс для issue #42 │ │ -│ ○ Gamma │ │ Agent-2: Проверил, всё ок │ │ -│ │ │ You: Мержите │ │ -│ [+ New] │ └──────────────────────────────────────────────┘ │ -│ │─────────────────────────────────────────────────────│ -│──────────────│ KANBAN │ -│ │ │ -│ AGENTS │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ -│ │ │ Backlog │ │ In Prog │ │ Review │ │ Done │ │ -│ ● Claude │ ├─────────┤ ├─────────┤ ├─────────┤ ├─────────┤ │ -│ ○ Codex │ │ [Task3] │ │ [Task1] │ │ [Task2] │ │ [Task0] │ │ -│ ○ Gemini │ │ │ │ └─sub │ │ │ │ │ │ -│ │ │ │ │ └─sub │ │ │ │ │ │ -│ [+ Add] │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ -│ │ │ -└──────────────┴─────────────────────────────────────────────────────┘ +┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ +│ Backlog │ │ TODO │ │ In Prog │ │ Review │ │ Done │ +├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤ +│ [draft] │ │ [ready] │ │ [active] │ │ [review] │ │[complete]│ +│ [draft] │ │ [ready] │ │ │ │ │ │[complete]│ +│ │ │ │ │ │ │ │ │ │ +└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ +``` + +### Статусы задач + +| Статус | Описание | +|--------|----------| +| `draft` | Черновик. Можно обсуждать, но не выполнять | +| `ready` | Готова к выполнению. Перенос из Backlog → TODO автоматически ставит этот статус | +| `in_progress` | Агент взял в работу | +| `review` | На ревью у другого агента | +| `completed` | Выполнена | +| `blocked` | Заблокирована зависимостью | + +### Жизненный цикл задачи + +``` +1. Человек создаёт задачу → draft (Backlog) +2. Обсуждение в чате проекта +3. Человек перетаскивает в TODO → статус меняется на ready +4. Агент берёт задачу → in_progress +5. Агент завершает → review +6. Ревьюер проверяет → completed / возврат в in_progress +``` + +--- + +## Задачи + +### Структура задачи + +```yaml +Задача: + id: uuid + проект: project_id + название: "Реализовать API авторизации" + описание: "Markdown текст с деталями" + статус: draft | ready | in_progress | review | completed | blocked + + # Назначение + назначен: agent_id (или null) + + # Вложенные файлы + файлы: + - name: "schema.sql" + type: "text/sql" + content: "..." + - name: "mockup.png" + type: "image/png" + url: "/files/task-123/mockup.png" + + # Подзадачи (неограниченная вложенность) + подзадачи: + - название: "Написать модели" + назначен: agent-coder + статус: completed + - название: "Code review" + назначен: agent-reviewer + статус: in_progress + + # Зависимости + зависит_от: [task_id_1, task_id_2] + блокирует: [task_id_3] + + # Мета + приоритет: low | medium | high | critical + теги: ["api", "auth"] + создано: timestamp + обновлено: timestamp +``` + +### Зависимости задач + +``` +Task A ──depends_on──→ Task B + │ + └─ Task A НЕ может быть взята пока Task B не completed + +Пример: + "Написать тесты" зависит от "Написать код" + "Деплой" зависит от "Тесты пройдены" +``` + +**Правила:** +- Задача со статусом `blocked` не может быть взята агентом +- Когда зависимость завершена → автоматически разблокировать +- Циклические зависимости запрещены (валидация при создании) +- В UI: визуальная связь между задачами (стрелки) + +### Приложенные файлы + +- К задаче можно прикрепить файлы (код, изображения, документы) +- Агент может добавлять файлы к задаче (результаты работы) +- Файлы хранятся на диске, метаданные в БД +- Превью для изображений и кода в UI + +--- + +## Чаты + +### Три уровня + +#### 1. Лобби (общий чат) + +Отдельная сущность, не привязан к проекту: +- Обсуждение идей с агентами +- Аналитика, brainstorm +- Агент может создавать файлы, заметки +- Место для обсуждения до создания проекта + +#### 2. Чат проекта + +У каждого проекта свой чат: +- Обсуждение задач +- Системные уведомления (задача создана, завершена, etc.) +- Агенты видят только чаты своих проектов + +#### 3. Комментарии задачи + +Внутри каждой задачи: +- Обсуждение деталей +- Код ревью +- Результаты подзадач + +--- + +## Агенты + +### Типы провайдеров (адаптеры) + +| Провайдер | Описание | +|-----------|----------| +| `anthropic` | Claude API (Opus, Sonnet) | +| `openai` | GPT, Codex | +| `google` | Gemini | +| `openclaw` | Через OpenClaw Gateway (с инструментами) | +| `cli` | Claude Code CLI (без API токенов) | + +### Настройки агента + +```yaml +Агент: + имя: "Кодер" + slug: "coder" + провайдер: anthropic + модель: claude-sonnet-4-20250514 + api_key: "sk-..." # зашифрован + + системный_промпт: "Ты — backend разработчик..." + + подписка: + режим: mentions # all | mentions | assigned + проекты: ["*"] # или конкретные + + ограничения: + макс_параллельных: 2 + таймаут: 600 # секунд +``` + +### Подписка на события + +| Режим | Агент получает | +|-------|---------------| +| `all` | Все сообщения в подписанных проектах | +| `mentions` | Только когда @упомянут | +| `assigned` | Назначенные задачи + mentions | + +--- + +## WebSocket протокол + +### Трекер → Клиент + +``` +task.created — задача создана +task.updated — задача обновлена +task.ready — задача готова к выполнению (перенесена из Backlog) +task.assigned — задача назначена агенту +task.blocked — задача заблокирована зависимостью +task.unblocked — зависимость выполнена, задача разблокирована +chat.message — новое сообщение в чате +agent.status — статус агента изменился +file.attached — файл прикреплён к задаче +``` + +### Клиент → Трекер + +``` +task.take — агент берёт задачу +task.complete — агент завершил задачу +task.comment — комментарий к задаче +task.attach — прикрепить файл +chat.send — отправить сообщение в чат +agent.register — регистрация агента +agent.heartbeat — пульс ``` --- ## Workflow: от идеи до деплоя -### Фаза 1: Инициация проекта +### Фаза 1: Идея → Проект -**Точки входа:** -- Через главного агента (Марков) в Telegram -- Через Web UI — кнопка "New Project" -- Через любого агента +1. Человек открывает Лобби +2. Обсуждает идею с агентом-аналитиком +3. Создаёт проект +4. Агент формирует BRIEF.md, REQUIREMENTS.md -**Результат:** Создаётся черновик проекта, открывается Discovery Chat. +### Фаза 2: Декомпозиция → Задачи ---- +1. На основе требований создаются задачи (черновики в Backlog) +2. Расставляются зависимости +3. Прикрепляются файлы (макеты, схемы) +4. Обсуждение в чате проекта +5. Готовые задачи переносятся в TODO -### Фаза 2: Discovery (Обсуждение) +### Фаза 3: Выполнение -**Участники:** Человек + Lead Agent +1. Задача в TODO → агент берёт → In Progress +2. Агент работает, коммитит, прикрепляет файлы +3. Создаёт подзадачу "Ревью" → другому агенту +4. Итерации до готовности +5. Задача → Done -**Цель:** Превратить размытую идею в чёткое ТЗ +### Фаза 4: Ревью и деплой -**Что делает Lead Agent:** -1. Задаёт уточняющие вопросы -2. Предлагает варианты реализации -3. Указывает на риски -4. Формирует структуру - -**Артефакты:** -- `BRIEF.md` — краткое описание проекта -- `REQUIREMENTS.md` — функциональные требования -- `ARCHITECTURE.md` — техническое решение - -**Выход из фазы:** Человек подтверждает "Да, делаем так" - ---- - -### Фаза 3: Planning (Декомпозиция) - -**Кто делает:** Lead Agent (или человек вручную) - -**Процесс:** -``` -REQUIREMENTS.md → Декомпозиция → Epic → Tasks → Subtasks -``` - -**Пример:** -``` -Epic: "Модуль авторизации" -├── Task: "Модель пользователя" -│ ├── Subtask: "Схема БД" -│ ├── Subtask: "SQLAlchemy модель" -│ └── Subtask: "Миграция" -├── Task: "API эндпоинты" -│ ├── Subtask: "POST /auth/register" -│ ├── Subtask: "POST /auth/login" -│ └── Subtask: "Tests" -└── Task: "Интеграция с frontend" -``` - ---- - -### Фаза 4: Execution (Разработка) - -**Как агенты берут задачи:** - -| Модель | Описание | -|--------|----------| -| **Pull** | Агент сам выбирает задачу по специализации | -| **Push** | Lead Agent назначает задачи | -| **Гибрид** | Критичные — назначаются, остальные — свободный выбор | - -**Процесс работы агента:** -1. Взял задачу → "In Progress" -2. Читает контекст (Brief, Requirements, связанные задачи) -3. Работает (код, тесты, документация) -4. Коммитит в feature branch -5. Создаёт подзадачу "Review" → другому агенту -6. Ревью и итерации -7. Merge в main - ---- - -### Фаза 5: Review & QA - -**Принцип:** Никакой код не идёт в main без ревью. - -**Кто ревьюит:** -- Другой агент (не автор) -- Специальный "Reviewer" агент -- Человек (для критичного) - -**Автоматизация:** -- CI/CD запускает тесты -- Линтеры -- Security checks - -**Escalation:** 3 итерации ревью без согласия → эскалация к Lead/Human. - ---- - -### Фаза 6: Deploy - -1. Integration тесты -2. Staging deploy -3. Human approval (опционально) -4. Production deploy - ---- - -## Задачи и подзадачи - -**Ключевой принцип:** Подзадачи внутри задачи — контекст НЕ теряется. - -``` -Task: "Реализовать API авторизации" -├── Subtask: "Написать модели" → Agent-1 ✓ -├── Subtask: "Code review" → Agent-2 ✓ -├── Subtask: "Написать тесты" → Agent-1 (in progress) -└── Subtask: "Final review" → Agent-2 (waiting) -``` - -Когда агент работает над подзадачей — видит всё дерево + историю. - ---- - -## Роли агентов - -| Роль | Обязанности | -|------|-------------| -| **Lead/Analyst** | Discovery, Planning, Coordination | -| **Developer** | Код, тесты | -| **Reviewer** | Code review, QA | -| **DevOps** | CI/CD, Deploy | -| **Documenter** | Документация | - ---- - -## Типы агентов - -| Тип | Описание | -|-----|----------| -| **OpenClaw** | Полноценный агент с инструментами | -| **Claude API** | Прямой вызов API | -| **Claude Code CLI** | Через CLI (без траты API токенов) | -| **Codex** | OpenAI | -| **Gemini** | Google | -| **Custom** | Любой через API | - ---- - -## Проблема: CLI Integration - -**Задача:** Использовать Claude Code CLI (авторизован через Max подписку) без траты API токенов. - -**Варианты решения:** - -### 1. Headless Mode (если поддерживается) -```bash -claude --message "prompt" --output result.txt -``` - -### 2. PTY Automation -```python -import pexpect -child = pexpect.spawn('claude') -child.sendline('Write a function...') -response = child.before -``` - -### 3. Session Bridge -``` -Team Board → Agent Service → PTY Bridge → Claude CLI в tmux -``` - -### 4. MCP Integration -Если CLI поддерживает Model Context Protocol. - -### 5. Гибридный подход -- Простые задачи → API (дёшево) -- Кодинг → CLI -- Роутинг по типу задачи - -**Требуется исследование:** Проверить возможности `claude` CLI. - ---- - -## Прозрачность - -**Всё видно в Web UI:** -- Статус задач -- Кто над чем работает -- Коммиты -- Переписка в задачах -- Метрики - -**Уведомления:** -- Задача застряла -- Нужно решение человека -- Deploy готов - ---- - -## Настройки проекта - -```yaml -Project: - name: "My Project" - git_enabled: true # default: true - git_url: "https://..." - lead_agent_id: "markov" # можно переназначить - agents: ["claude", "codex"] -``` +1. Автоматические проверки (CI/CD) +2. Ревью агентом или человеком +3. Деплой --- ## Инфраструктура (уже есть) -- **PostgreSQL** — БД -- **Thoth** — STT/TTS сервис -- **Authentik** — SSO -- **Nginx + certbot** — домены -- **Gitea** — Git хостинг -- **OpenClaw (Марков)** — главный агент +| Сервис | Описание | +|--------|----------| +| PostgreSQL | База данных | +| Thoth | STT/TTS (голос↔текст) | +| Authentik | SSO для веб-интерфейса | +| Nginx + certbot | Домены и SSL | +| Gitea | Git хостинг | +| OpenClaw (Марков) | Главный агент с инструментами | +| Redis | Очереди и pub/sub | --- @@ -299,22 +339,25 @@ Project: 1. Как интегрировать CLI-агентов (Claude Code, Cline)? 2. Workspace для агентов — общий или изолированный? -3. Реалтайм прогресс работы агента? -4. Лимиты: макс агентов, макс задач? -5. Биллинг/учёт использования API? +3. Прогресс работы агента в реалтайме? +4. Биллинг/учёт использования API? +5. Шаблоны агентов — как быстро создать нового? --- ## Приоритеты реализации -1. [ ] Базовый UI: проекты, доска -2. [ ] Tasks Service: CRUD, подзадачи -3. [ ] Agents Service: регистрация -4. [ ] Chat Service -5. [ ] Git интеграция -6. [ ] CLI Bridge для Claude Code -7. [ ] Подключение реальных агентов +1. [ ] Tracker: базовый WebSocket сервер +2. [ ] Tracker: проекты, задачи, подзадачи +3. [ ] Tracker: зависимости задач +4. [ ] Tracker: чаты (лобби + проект) +5. [ ] Tracker: файлы в задачах +6. [ ] Web Client: авторизация (Authentik) +7. [ ] Web Client: канбан-доска +8. [ ] Web Client: чат +9. [ ] Шаблон агента +10. [ ] Подключение первого агента (OpenClaw) --- -*Документ для обсуждения. Финальная архитектура — отдельно.* +*Документ для обсуждения и аналитики. Обновляется по мере развития идей.*