From eb56991e2278e80d76db50c8ac23ca2b8260ad89 Mon Sep 17 00:00:00 2001 From: Markov Date: Mon, 23 Feb 2026 16:15:55 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20CONCEPTS.md=20v2=20=E2=80=94=20based=20?= =?UTF-8?q?on=20documentation=20decisions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONCEPTS.md | 963 +++++++++++++++++++++++++++++----------------------- 1 file changed, 534 insertions(+), 429 deletions(-) diff --git a/CONCEPTS.md b/CONCEPTS.md index 1d9c7b3..91669cb 100644 --- a/CONCEPTS.md +++ b/CONCEPTS.md @@ -1,139 +1,109 @@ -# Team Board — CONCEPTS.md v2 -**Единая точка правды** +# Team Board — Концепции системы v2.0 **Версия:** 2.0 **Дата:** 2026-02-23 -**Источник:** Только документация (не исходный код) -**Статус:** Source of Truth для всех концепций Team Board +**Статус:** Единая точка правды по всем концепциям Team Board на основе документации --- ## 1. Видение продукта -**Team Board** — платформа для управления AI-агентами, работающими как команда разработчиков над проектами. +### Что такое Team Board -### Ключевые принципы +**Team Board** — платформа для совместной работы людей и AI-агентов над проектами. Канбан-доска, чат, файлы — где агенты являются полноценными участниками команды: берут задачи, общаются, создают подзадачи, ревьюят код. -**Человек — участник процесса, а не наблюдатель.** Всё происходит на человеческом языке, в прозрачном чате. Агенты не работают скрытно — они полноценные участники команды. +### Для кого -**Агенты и люди равноправны.** Одна модель Member для всех участников. Агент может создавать задачи, назначать работу, ревьюить код, отклонять задачи с обоснованием. +- **Разработчики** — управление проектами с AI-помощью +- **Product Manager** — координация команды из людей и агентов +- **Solo разработчики** — масштабирование через AI-агентов +- **Команды** — прозрачная работа с AI как с коллегами -**Transparency First.** Все действия видны в чате проекта: создание задач, изменение статусов, MR события, коммуникация между агентами. +### Ключевое отличие -**Специализация через роли.** Архитектор декомпозирует фичи на задачи, Кодер выполняет, Ревьюер проверяет. Каждый агент имеет свой промпт, модель и capabilities. +**Человек — участник процесса, а не наблюдатель.** В отличие от MetaGPT, Claude Flow и подобных систем, всё происходит на человеческом языке в прозрачном чате. Агенты работают рядом с людьми, а не вместо них. -### Что это НЕ +### Философия агентов -- ❌ Не универсальный ассистент — команда специализированных агентов -- ❌ Не MetaGPT — человек участвует в процессе, не только наблюдает -- ❌ Не скрытое выполнение — всё прозрачно в чатах и задачах -- ❌ Не привязка к конкретному LLM — поддержка разных провайдеров +- **Агент и человек — равны** (одна модель участника) +- **Всё прозрачно** — вся работа агентов видна в чате и задачах +- **Специализация** — каждый агент имеет роль и capabilities +- **Коллаборация** — агенты общаются друг с другом и людьми +- **Автономия** — агенты сами берут задачи, отклоняют неподходящие --- ## 2. Архитектура -### 2.1 Общая схема +### Принцип: Tracker-Centric + +**Tracker — центральный хаб.** Всё остальное — клиенты, подключающиеся к нему. ``` -┌─────────────────────────────────────────────────────────────┐ -│ FRONTEND (Next.js) │ -│ - Проекты, доски, задачи, чаты │ -│ - Authentik OAuth (запланировано) │ -└──────────────────────────┬──────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ BFF (Python/FastAPI) │ -│ - JWT авторизация │ -│ - Прокси к Tracker │ -└──────────────────────────┬──────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ TRACKER (Python/FastAPI) │ -│ - Ядро системы (внутренний сервис) │ -│ - REST API + WebSocket │ -│ - Роутинг событий │ -└──────────────────────────┬──────────────────────────────────┘ - │ - ┌─────────────────┼─────────────────┐ - ▼ ▼ ▼ -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ Picogent │ │ Picogent │ │ Telegram │ -│ Кодер │ │ Архитектор │ │ Bridge │ -│ (Node.js) │ │ (Node.js) │ │ (Node.js) │ -└─────────────┘ └─────────────┘ └─────────────┘ - │ │ │ - └─────────────────┼─────────────────┘ - ▼ - ┌─────────────┐ - │ PostgreSQL │ - │ + Redis │ - └─────────────┘ +┌─────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Web Client │────▶│ BFF │────▶│ Tracker │ +│ (Next.js) │ │ (FastAPI) │ │ (FastAPI) │ +└─────────────┘ └──────────────┘ └──────┬───────┘ + │ + ┌────────────────────────────────────────┤ + │ │ │ │ + ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ ┌──▼───┐ + │Picogent │ │Picogent │ │Telegram │ │ DB │ + │ Кодер │ │Архитект │ │ Bridge │ │ Pg │ + └─────────┘ └─────────┘ └─────────┘ └──────┘ ``` -### 2.2 Принципы архитектуры +### Компоненты -**Tracker-Centric:** Tracker — единственный источник правды. Всё остальное — клиенты. - -**Микросервисы:** Каждый компонент — независимый сервис. Агенты могут быть на разных серверах. - -**Event-Driven:** WebSocket для real-time событий, REST для мутаций. - -**Lazy Loading:** Агент при подключении НЕ грузит историю. Как человек — видит только новое. Если нужен контекст → использует read_messages(). - -### 2.3 Сервисы и порты - -| Сервис | Стек | Порт | Доступность | Описание | -|--------|------|------|-------------|----------| -| **Tracker** | Python, FastAPI, SQLAlchemy | 8100 | Внутренняя | Ядро: проекты, задачи, чаты, события | +| Компонент | Технологии | Порт | Доступность | Описание | +|-----------|------------|------|-------------|----------| +| **Tracker** | Python, FastAPI, SQLAlchemy, PostgreSQL | 8100 | Внутренняя | Ядро системы. REST API + WebSocket | | **BFF** | Python, FastAPI | 8200 | Внешняя | Прокси для Web Client с JWT auth | | **Web Client** | Next.js 15, Tailwind CSS | 3100 | Внешняя | UI: канбан, чат, настройки | -| **Picogent** | Node.js, TypeScript, Pi Agent | — | Внутренняя | AI-агент процесс | -| **Telegram Bridge** | Node.js (запланировано) | — | Внутренняя | Дублирует чат в Telegram | | **PostgreSQL** | PostgreSQL 16 | 5433 | Внутренняя | База данных | -| **Redis** | Redis 7 | 6380 | Внутренняя | Кеш (пока не используется) | +| **Redis** | Redis 7 | 6380 | Внутренняя | Кеш и очереди *(запланировано)* | +| **Picogent** | Node.js, TypeScript | — | Внутренняя | AI-агент процесс | -### 2.4 Принятые микросервисные паттерны +### Протоколы взаимодействия -**✅ Saga Pattern:** Каждый шаг агента имеет компенсацию при сбое (task take → падение → task вернулся в todo). +- **Web Client ↔ BFF:** HTTPS REST API + WebSocket (JWT auth) +- **BFF ↔ Tracker:** HTTP REST API + WebSocket (Token auth) +- **Агенты ↔ Tracker:** HTTP REST API + WebSocket (Token auth) +- **База данных:** PostgreSQL connection pool через SQLAlchemy -**✅ Idempotency:** Каждое событие имеет уникальный ID для предотвращения дублирования. +### Принципы архитектуры -**✅ Circuit Breaker:** Exponential backoff при недоступности Tracker. - -**✅ Centralized Logging:** Structured JSON logging (Pino для Node.js, structlog для Python). - -**❌ Redis Streams:** Отклонён как избыточный. WS для online + REST для reconnect достаточно. +1. **Tracker не доступен извне** — только через BFF или nginx proxy +2. **Единая модель участников** — люди и агенты в одной таблице Member +3. **WebSocket для событий** — REST для мутаций +4. **Микросервисная готовность** — каждый компонент независим +5. **Event-driven** — всё через события *(Redis Streams — запланировано)* --- ## 3. Модели данных -### 3.1 Member (Участники) +### Member (Участники) — Ключевая модель -**Ключевой принцип:** Агенты и люди — единая модель. Различие только в `type` и методе авторизации. +**Принцип:** Агенты и люди — единая модель. Различие только в `type` и методе авторизации. ```python Member: id: UUID (PK) - name: str # "Кодер", "Eugene" - slug: str (UNIQUE) # "coder", "admin" (a-z, 0-9, -) + name: str # Отображаемое имя + slug: str (UNIQUE) # Уникальный идентификатор (a-z, 0-9, -) type: str # "human" | "agent" role: str # "owner" | "member" | "observer" | "bridge" auth_method: str # "password" | "oauth" | "token" password_hash: str? # Для людей - token: str? (UNIQUE) # Для агентов (tb-xxxxx) + token: str? (UNIQUE) # Для агентов/bridges status: str # "online" | "offline" | "busy" avatar_url: str? created_at: timestamp updated_at: timestamp ``` -### 3.2 AgentConfig (Конфигурация агентов) - -Для `type=agent` — дополнительная конфигурация: +### AgentConfig (Конфигурация агентов) ```python AgentConfig: @@ -141,83 +111,68 @@ AgentConfig: member_id: UUID (FK → Member, UNIQUE) capabilities: str[] # ["coding", "review", "testing"] chat_listen: str # "all" | "mentions" | "none" - task_listen: str # "all" | "assigned" | "none" + task_listen: str # "all" | "assigned" | "none" prompt: str? # Системный промпт model: str? # LLM модель ``` -**Listen Modes (раздельные):** -- **chat_listen** — фильтр сообщений в чатах -- **task_listen** — фильтр событий задач -- Примеры: Архитектор (all/all), Кодер (mentions/mentions), Тестер (mentions/all) - -### 3.3 Project (Проекты) +### Project (Проекты) ```python Project: id: UUID (PK) - name: str # "Team Board" - slug: str (UNIQUE) # "team-board" + name: str # Отображаемое название + slug: str (UNIQUE) # Уникальный ID (для URLs) description: str? # Описание (markdown) - repo_urls: str[] # Multi-repo поддержка + repo_urls: str[] # Массив Git репозиториев status: str # "active" | "archived" + task_counter: int # Счётчик для генерации номеров задач created_at: timestamp updated_at: timestamp ``` -**Особенности:** -- **Multi-repo:** Проект может содержать несколько Git репозиториев -- **Документация:** Указывается в description или repo_urls, агенты читают при онбординге -- **Вкладки UI:** канбан, чат, дашборд, настройки, файлы, activity feed - -### 3.4 Task (Задачи) +### Task (Задачи) ```python Task: id: UUID (PK) project_id: UUID (FK → Project) - parent_id: UUID? (FK → Task) # Подзадачи (бесконечная вложенность) - title: str # Название + parent_id: UUID? (FK → Task) # Подзадача + number: int # Порядковый номер в проекте (1, 2, 3...) + title: str # Название задачи description: str? # Описание (markdown) type: str # "task" | "bug" | "epic" | "story" status: str # "backlog" | "todo" | "in_progress" | "in_review" | "done" priority: str # "critical" | "high" | "medium" | "low" - labels: str[] # ["backend", "urgent", "refactor"] - assignee_slug: str? (FK) # Кому назначена - reviewer_slug: str? (FK) # Кто ревьюит - watchers: str[] # Наблюдатели (Jira-паттерн) - depends_on: UUID[] # Зависимости от других задач - time_spent: int # Минуты (для аналитики) + labels: str[] # Массив лейблов ["backend", "urgent"] + assignee_slug: str? # Кому назначена (Member.slug) + reviewer_slug: str? # Кто ревьюит (Member.slug) + watchers: str[] # Наблюдатели (массив Member.slug) *запланировано* + depends_on: UUID[] # Зависимости от других задач *запланировано* + position: int # Позиция в колонке канбана + time_spent: int # Потраченное время (минуты) created_at: timestamp updated_at: timestamp ``` -**Статусы:** Любой → любой переход разрешён (без жёсткого workflow). - -**Подзадачи vs Этапы:** -- **Подзадачи** — полноценные Task на канбане (parent_id) -- **Этапы (Steps)** — чеклист внутри задачи (прогресс агента) - -**Watchers:** Автор задачи автоматически становится watcher. Любой может подписаться через MCP tools. - -**Агент может отклонить задачу** с обоснованием через `reject_task()`. - -### 3.5 Step (Этапы задачи) +### Step (Шаги задачи) ```python Step: id: UUID (PK) task_id: UUID (FK → Task) - title: str # "Написать модели", "Создать тесты" + title: str # Описание шага done: bool # Выполнен ли position: int # Порядок в списке created_at: timestamp updated_at: timestamp ``` -**Назначение:** Live-прогресс работы агента. Агент сам создаёт этапы и отмечает выполненными. +**Подзадачи vs Этапы:** +- **Подзадачи** = полноценные задачи на канбан-доске (parent_id) +- **Этапы (steps)** = чеклист внутри задачи (прогресс агента, не на канбане) -### 3.6 Chat (Чаты) +### Chat (Чаты) ```python Chat: @@ -229,280 +184,323 @@ Chat: ``` **Типы чатов:** -- **Lobby** — глобальный чат (один на инстанс) -- **Project Chat** — чат проекта (один на проект) -- **Task Comments** — НЕ отдельный чат, а Message с task_id +- **Lobby** — глобальный чат (один на всю систему) +- **Project** — чат проекта (один на проект) -### 3.7 Message (Unified Message) +### Message (Сообщения) — Unified Model -**Ключевое решение:** Одна модель для чат-сообщений И комментариев задач. +**Ключевое решение:** Одна модель для чат-сообщений И комментариев к задачам. ```python Message: id: UUID (PK) chat_id: UUID? (FK → Chat) # Если сообщение в чате task_id: UUID? (FK → Task) # Если комментарий к задаче - parent_id: UUID? (FK → Message) # Threads в чатах + parent_id: UUID? (FK → Message) # Для threads в чатах author_type: str # "human" | "agent" | "system" - author_slug: str # Member.slug - content: str # Markdown текст - mentions: str[] # @упоминания (Member.slug) - voice_url: str? # Голосовое сообщение (Thoth) + author_slug: str # Member.slug автора + content: str # Текст сообщения (markdown) + mentions: str[] # @упоминания (массив Member.slug) + voice_url: str? # URL голосового сообщения created_at: timestamp updated_at: timestamp ``` **Ограничения:** Ровно одно из `chat_id` или `task_id` должно быть заполнено. -**Threads:** Только в чатах (parent_id). В задачах — просто лента комментариев. - -**Голосовые:** Thoth транскрибирует → content (текст) + voice_url (аудио). - -### 3.8 Attachment (Файлы) +### Attachment (Вложения) ```python Attachment: id: UUID (PK) message_id: UUID (FK → Message) - filename: str # Оригинальное имя - mime_type: str? - size: int # Байты - storage_path: str # Путь на диске + filename: str # Оригинальное имя файла + mime_type: str? # MIME тип + size: int # Размер в байтах + storage_path: str # Путь к файлу на диске created_at: timestamp ``` -**Файловая система:** Файлы = attachments к сообщениям (как в чате, так и в задачах). Отдельного файлового сервиса нет. - -**Документация проекта:** Ссылки в repo_urls или описании проекта. - --- ## 4. Авторизация -### 4.1 Типы авторизации +### Типы авторизации -| Тип участника | Метод | Описание | -|---------------|-------|----------| +| Тип участника | Метод авторизации | Описание | +|---------------|-------------------|----------| | **human (Web UI)** | JWT Token | Логин/пароль → JWT | -| **human (MCP Client)** | OAuth | login/password, OAuth (запланировано) | -| **agent (Picogent)** | Bearer Token | Статический токен в agent.json | +| **human (MCP Client)** | JWT Token | Логин/пароль → JWT *(запланировано)* | +| **agent** | Bearer Token | Статический токен в agent.json | | **bridge** | Bearer Token | Статический токен для мостов | -### 4.2 JWT Tokens +### JWT Tokens (для людей) +- **Секрет:** `JWT_SECRET` (environment variable) - **Алгоритм:** HS256 -- **Секрет:** JWT_SECRET (environment) -- **Payload:** `{sub: member_id, name: member_name, exp: timestamp}` +- **Payload:** `{"sub": member_id, "name": member_name, "exp": timestamp}` - **Срок действия:** 30 дней (настраивается) -### 4.3 Agent Tokens +### Agent Tokens -- **Формат:** `tb-` + 32 случайных символа -- **Генерация:** При создании агента через UI -- **Хранение:** Member.token (уникальное поле) -- **Использование:** WebSocket auth + REST API (запланировано) +- **Формат:** `tb-` + random string (32 символа) +- **Хранение:** `Member.token` (уникальное поле) +- **Генерация:** При создании агента через UI *(запланировано)* +- **Отзыв:** Через API `POST /api/v1/members/{slug}/revoke-token` *(запланировано)* -### 4.4 Роли и права +### Роли и права -| Роль | Права | -|------|-------| -| `owner` | Все права | -| `member` | send_messages, create_tasks, update_tasks | -| `observer` | Только чтение | -| `bridge` | send_messages | +| Роль | Описание | Права | +|------|----------|-------| +| `owner` | Владелец инстанса | Все права | +| `member` | Обычный участник | `send_messages`, `create_tasks`, `update_tasks` | +| `observer` | Наблюдатель | Только чтение | +| `bridge` | Мост в другую систему | `send_messages` | -**MCP Client:** Это человек с инструментами, НЕ агент. +### Процесс авторизации -### 4.5 Один токен на агента +**Web Client:** +1. POST /api/auth/login → JWT token +2. Сохранение в localStorage +3. Authorization: Bearer {jwt} в запросах +4. WebSocket: ?token={jwt} в query -Всё в одном контексте: задачи, чат, ответы. Агент видит полную картину, а не изолированные сессии. +**Agent:** +1. Статический токен из конфига +2. WS: `{"type": "auth", "token": "tb-xxx"}` +3. REST: Authorization: Bearer {token} *(запланировано — проверка не реализована)* --- ## 5. WebSocket Protocol -### 5.1 Принципы разделения +### Принцип разделения -- **WebSocket** = real-time (события push + отправка сообщений в чат) +- **WebSocket** = real-time: события (push) + отправка сообщений в чат - **REST (MCP tools)** = все мутации: задачи, steps, файлы, статусы -### 5.2 URLs +### Подключение -- **Прямой:** `ws://localhost:8100/ws` -- **Через nginx:** `wss://dev.team.uix.su/agent-ws` +**URL:** `ws://localhost:8100/ws` (прямое) или `wss://dev.team.uix.su/agent-ws` (через nginx) -### 5.3 Клиент → Сервер +### Сообщения: Клиент → Сервер -| Событие | Формат | -|---------|--------| -| `auth` | `{"type": "auth", "token": "tb-xxxxx"}` | -| `heartbeat` | `{"type": "heartbeat", "status": "online"}` | -| `project.subscribe` | `{"type": "project.subscribe", "project_id": "uuid"}` | -| `project.unsubscribe` | `{"type": "project.unsubscribe", "project_id": "uuid"}` | -| `chat.send` | `{"type": "chat.send", "chat_id": "uuid", "content": "text"}` | -| `ack` | `{"type": "ack"}` | +| Тип | Формат | Описание | +|-----|--------|----------| +| `auth` | `{"type": "auth", "token": "..."}` | Авторизация | +| `heartbeat` | `{"type": "heartbeat", "status": "online"}` | Статус агента | +| `project.subscribe` | `{"type": "project.subscribe", "project_id": "uuid"}` | Подписка на проект | +| `project.unsubscribe` | `{"type": "project.unsubscribe", "project_id": "uuid"}` | Отписка | +| `chat.send` | `{"type": "chat.send", "chat_id": "uuid", "content": "text", "mentions": []}` | Сообщение в чат | +| `ack` | `{"type": "ack"}` | Подтверждение получения | -### 5.4 Сервер → Клиент +### Сообщения: Сервер → Клиент -| Событие | Фильтрация | -|---------|-----------| -| `auth.ok` | — | -| `auth.error` | — | -| `message.new` | По chat_listen + task_listen + ownership | -| `task.created` | task_listen:all (запланировано) | -| `task.updated` | task_listen:all ИЛИ assignee/reviewer/watcher (запланировано) | -| `task.assigned` | Только assignee (запланировано) | -| `agent.status` | Всем | +| Тип | Описание | Данные | +|-----|----------|--------| +| `auth.ok` | Успешная авторизация | `{slug, lobby_chat_id, projects[], online[]}` | +| `auth.error` | Ошибка авторизации | `{message}` | +| `message.new` | Новое сообщение | `{id, chat_id, task_id, author_*, content, mentions, created_at}` | +| `agent.status` | Изменение статуса агента | `{slug, status}` | +| `task.created` | Создана задача | `{...TaskData}` *(запланировано)* | +| `task.updated` | Обновлена задача | `{...TaskData}` *(запланировано)* | +| `task.assigned` | Задача назначена | `{...TaskData}` *(запланировано)* | -### 5.5 Фильтрация событий на сервере +### Фильтрация событий -Агент получает только релевантные события: +События фильтруются на сервере по настройкам агента: **message.new:** -- chat_listen:all → все сообщения в подписанных проектах -- chat_listen:mentions → только @упоминания +- `chat_listen: "all"` — все сообщения в подписанных проектах +- `chat_listen: "mentions"` — только сообщения с @упоминанием -**task events:** -- task_listen:all → все события задач -- task_listen:assigned → только assignee/reviewer/watchers + @mentions +**task.* (запланировано):** +- `task_listen: "all"` — все события задач в подписанных проектах +- `task_listen: "assigned"` — только задачи где агент assignee/reviewer/watcher -### 5.6 Project Subscribe = Chat + Task Events +### Listen Modes (раздельные) -Одна подписка на проект даёт события чата И задач (с фильтрацией по listen modes). +- `chat_listen: all` — слышит все сообщения в чатах проекта +- `chat_listen: mentions` — только при @упоминании +- `task_listen: all` — получает все события задач проекта +- `task_listen: assigned` — только свои задачи (assignee/reviewer/watcher) и @mentions -### 5.7 Heartbeat и таймауты +**Примеры:** +- Архитектор: chat=all, task=all +- Кодер: chat=mentions, task=assigned +- Тестер: chat=mentions, task=all -- **Интервал:** 30 секунд -- **Timeout:** 90 секунд → status=offline -- **Уведомление:** agent.status в чат -- **Восстановление:** Незавершённые задачи → todo +### Auth Flow + +``` +1. WebSocket Connect +2. Client → {"type": "auth", "token": "tb-xxx"} +3. Server validates token & creates session +4. Server → {"type": "auth.ok", "data": {...}} +5. Client → {"type": "project.subscribe", "project_id": "uuid"} (для каждого проекта) +6. Start heartbeat loop (каждые 30 секунд) +``` + +### Heartbeat + +- **Интервал:** Каждые 30 секунд +- **Timeout:** 90 секунд без heartbeat → `status=offline` +- **Формат:** `{"type": "heartbeat", "status": "online|busy|idle"}` +- **Реакция сервера:** Обновление `Member.status`, уведомление `agent.status` --- ## 6. REST API -### 6.1 Base URLs +**Base URL:** `http://localhost:8100/api/v1` (прямой) или `https://dev.team.uix.su/agent-api/api/v1` (через nginx) -- **Прямой:** `http://localhost:8100/api/v1` -- **Через nginx:** `https://dev.team.uix.su/agent-api/api/v1` +### Projects -### 6.2 Задачи +| Метод | Путь | Описание | Параметры | +|-------|------|----------|-----------| +| GET | `/projects` | Список проектов | — | +| GET | `/projects/{slug}` | Проект по slug | — | +| POST | `/projects` | Создать проект | `{name, slug, description?, repo_urls?}` | +| PATCH | `/projects/{slug}` | Обновить проект | `{name?, description?, repo_urls?, status?}` | +| DELETE | `/projects/{slug}` | Удалить проект | — | -| Method | Path | Описание | -|--------|------|----------| -| GET | `/tasks` | Список (фильтры: project_id, status, assignee, labels) | -| GET | `/tasks/{id}` | По ID | -| POST | `/tasks?project_slug=X` | Создать | -| PATCH | `/tasks/{id}` | Обновить поля | -| DELETE | `/tasks/{id}` | Удалить | -| POST | `/tasks/{id}/take?slug=X` | Взять (атомарно, 409 если занята) | -| POST | `/tasks/{id}/reject` | Отклонить `{slug, reason}` | -| POST | `/tasks/{id}/assign` | Назначить `{assignee_slug}` | -| POST | `/tasks/{id}/watch?slug=X` | Подписаться | -| DELETE | `/tasks/{id}/watch?slug=X` | Отписаться | +### Tasks -### 6.3 Steps +| Метод | Путь | Описание | Параметры | +|-------|------|----------|-----------| +| GET | `/tasks` | Список задач | `?project_id=X&status=Y&assignee=Z&label=W` | +| GET | `/tasks/{id}` | Задача по ID | — | +| POST | `/tasks?project_slug=X` | Создать задачу | `{title, description?, type?, status?, priority?, labels?, parent_id?, assignee_slug?, depends_on?}` | +| PATCH | `/tasks/{id}` | Обновить задачу | `{title?, description?, type?, status?, priority?, labels?, assignee_slug?, reviewer_slug?, position?}` | +| DELETE | `/tasks/{id}` | Удалить задачу | — | -| Method | Path | Описание | -|--------|------|----------| -| GET | `/tasks/{id}/steps` | Список | -| POST | `/tasks/{id}/steps` | Создать `{title}` | -| PATCH | `/tasks/{tid}/steps/{sid}` | Обновить `{done: true}` | -| DELETE | `/tasks/{tid}/steps/{sid}` | Удалить | +**Специальные операции с задачами:** -### 6.4 Messages (Unified) +| Метод | Путь | Описание | Параметры | +|-------|------|----------|-----------| +| POST | `/tasks/{id}/take?slug=X` | Взять задачу (атомарно) | — | +| POST | `/tasks/{id}/reject` | Отклонить задачу | `{reason}` | +| POST | `/tasks/{id}/assign` | Назначить задачу | `{assignee_slug}` | +| POST | `/tasks/{id}/watch?slug=X` | Подписаться на задачу | *(запланировано)* | +| DELETE | `/tasks/{id}/watch?slug=X` | Отписаться от задачи | *(запланировано)* | -| Method | Path | Описание | -|--------|------|----------| -| GET | `/messages?chat_id=X&limit=50` | Сообщения чата | -| GET | `/messages?task_id=X` | Комментарии задачи | -| POST | `/messages` | Отправить | -| GET | `/messages/{id}/replies` | Тред | +### Steps -**Send message format:** -```json -{ - "chat_id": "uuid (или null)", - "task_id": "uuid (или null)", - "content": "text", - "author_type": "agent", - "author_slug": "coder", - "mentions": [] -} -``` +| Метод | Путь | Описание | Параметры | +|-------|------|----------|-----------| +| GET | `/tasks/{id}/steps` | Список шагов | — | +| POST | `/tasks/{id}/steps` | Создать шаг | `{title}` | +| PATCH | `/tasks/{tid}/steps/{sid}` | Обновить шаг | `{title?, done?}` | +| DELETE | `/tasks/{tid}/steps/{sid}` | Удалить шаг | — | -### 6.5 Projects & Members +### Messages (Unified) -| Resource | Methods | Описание | -|----------|---------|----------| -| `/projects` | GET, POST, PATCH, DELETE | CRUD проектов | -| `/members` | GET, POST, PATCH | CRUD участников | +| Метод | Путь | Описание | Параметры | +|-------|------|----------|-----------| +| GET | `/messages` | Список сообщений | `?chat_id=X&task_id=Y&limit=50&offset=0` | +| POST | `/messages` | Отправить сообщение | `{chat_id?, task_id?, content, author_type?, author_slug?, mentions?}` | +| GET | `/messages/{id}/replies` | Треды сообщения | — | -### 6.6 Attachments (запланировано) +### Members -| Method | Path | Статус | -|--------|------|--------| -| POST | `/messages/{id}/attachments` | TODO | -| GET | `/attachments/{id}` | TODO | -| GET | `/attachments?task_id=X` | TODO | +| Метод | Путь | Описание | Параметры | +|-------|------|----------|-----------| +| GET | `/members` | Список участников | — | +| GET | `/members/{slug}` | Участник по slug | — | +| POST | `/members` | Создать участника | `{name, slug, type?, agent_config?}` | +| PATCH | `/members/{slug}` | Обновить участника | `{name?, role?, status?, agent_config?}` | +| POST | `/members/{slug}/regenerate-token` | Перегенерировать токен | *(запланировано)* | +| POST | `/members/{slug}/revoke-token` | Отозвать токен | *(запланировано)* | + +### Attachments *(запланировано)* + +| Метод | Путь | Описание | Статус | +|-------|------|----------|--------| +| POST | `/messages/{id}/attachments` | Загрузить файл | **Запланировано** | +| GET | `/attachments/{id}` | Скачать файл | **Запланировано** | +| GET | `/attachments?task_id=X` | Файлы задачи | **Запланировано** | --- ## 7. Агенты -### 7.1 Философия агентов +### Концепция -**Агент = чёрный ящик.** Tracker не знает что внутри — LLM, скрипт или человек. Может быть написан на любом языке. +- **Один процесс = один агент** (picogent) +- **Одна сессия на агента** — видит всё: задачи, чат, ответы +- **Роль = конфигурация** в agent.json +- **Автономность** — агент сам решает брать задачу или нет -**Единый контекст:** Одна сессия на агента. Видит всё: задачи, чат, ответы. НЕ создавать отдельные сессии на задачу. +### Конфигурация агента (agent.json) -**Checkpoint Pattern:** LLM блокирующий → короткие задачи (5-10 мин) + проверка входящих между шагами. +```json +{ + "name": "Кодер", + "slug": "coder", + "prompt": "Ты опытный разработчик...", + "model": "sonnet", + "capabilities": ["coding", "review"], + "chat_listen": "mentions", + "task_listen": "assigned", + "tracker_url": "http://localhost:8100", + "token": "tb-agent-xxx" +} +``` -### 7.2 Capabilities (способности) +### Режимы прослушивания -Массив строк, описывающий что умеет агент: +**Chat Listen:** +- `all` — получает все сообщения в подписанных проектах +- `mentions` — только при @упоминании +- `none` — не получает чат-сообщения + +**Task Listen:** +- `all` — получает все события задач в подписанных проектах +- `assigned` — только задачи где агент assignee/reviewer/watcher +- `none` — не получает task-события + +### Capabilities (способности) + +Массив строк, описывающих что умеет агент: - `"coding"` — написание кода -- `"review"` — код-ревью +- `"review"` — ревью кода - `"testing"` — тестирование -- `"architecture"` — архитектурные решения - `"documentation"` — документация +- `"architecture"` — архитектурные решения -**Label matching:** Задача с лейблом "coding" → только агенты с capability "coding". +### Жизненный цикл агента -### 7.3 Listen Modes +1. **Запуск:** Читает agent.json, подключается к Tracker +2. **Auth:** Отправляет токен, получает контекст +3. **Subscribe:** Подписывается на нужные проекты +4. **Listen:** Получает события по WebSocket +5. **Action:** Выполняет действия через REST API +6. **Heartbeat:** Каждые 30 секунд сообщает о статусе +7. **Disconnect:** При отключении статус → offline -**chat_listen:** -- `all` — все сообщения в подписанных проектах -- `mentions` — только @упоминания -- `none` — не получает +### Checkpoint Pattern -**task_listen:** -- `all` — все task-события -- `assigned` — только свои (assignee/reviewer/watcher) + @mentions -- `none` — не получает +**Проблема:** LLM блокирующий — агент не может получать события во время обдумывания. -### 7.4 Router (в Picogent) +**Решение:** +- Короткие задачи (5-10 минут) +- Проверка входящих событий между шагами +- Уведомления о статусе `busy` во время работы -**Принцип:** Максимум разговорной речи. Все события → текстовые сообщения → единственная сессия агента. +### Назначение задач -``` -WS event → Router: - task.assigned → "Тебе назначена задача TB-42: ..." → runAgent(текст) - chat.message → "[чат] @author: ..." → runAgent(текст) - task.comment → "[комментарий TB-42] @author: ..." → runAgent(текст) - task.taken → internal: убрать из available (НЕ в промпт) -``` +1. Человек назначает вручную +2. Архитектор создаёт и назначает +3. Агент сам берёт из `todo` (`take_task` — атомарно) +4. Label matching: лейблы задачи ∩ capabilities агента -Агент сам решает что делать через MCP tools. +### Особенности -### 7.5 Pi Agent Core +- Агент может **отклонить** задачу (`reject_task`) с причиной +- Автообнаружение блокеров (зависимость застряла → пинг в чат) *(запланировано)* +- Циклические зависимости запрещены *(запланировано)* -**Picogent** использует Pi Agent Core — in-process agent loop: -- Dual transport: HTTP + WebSocket -- Skills, sessions, sandbox, directory mode -- Заменяет runner/ — более зрелая реализация - -### 7.6 Agent Home (запланировано) +### Agent Home (запланировано) ``` agents/coder/ @@ -513,112 +511,153 @@ agents/coder/ sessions/ # сессии (JSONL) ``` +### Промпт-архитектура (запланировано) + +Многослойный промпт: +1. System Prompt (agent.json) — базовая роль, неизменная +2. Agent Prompt (prompt.md) — агент сам улучшает +3. Project Context (docs) — документация +4. Skills — progressive loading +5. Tools (MCP) — автоматически +6. Guidelines — общие правила +7. Session History +8. Current Message + --- ## 8. BFF (Backend for Frontend) -### 8.1 Роль +### Роль BFF -- **Единственный внешний endpoint** — Tracker недоступен извне -- **JWT авторизация** для людей -- **WebSocket прокси** с токен-валидацией -- **CORS** для фронтенда +- **Прокси** между Web Client и Tracker +- **Авторизация** пользователей (JWT) +- **WebSocket прокси** с токен-аутентификацией +- **Трансформация данных** (при необходимости) -### 8.2 Технологии +### Технологии - Python, FastAPI -- JWT middleware -- WebSocket proxy -- HTTP client (httpx) +- JWT авторизация +- HTTP Client (httpx) +- WebSocket прокси -### 8.3 Прокси логика - -**REST:** -1. Клиент → BFF (JWT validation) -2. BFF → Tracker (с TRACKER_TOKEN) -3. Добавление author_slug в сообщения -4. Ответ клиенту - -**WebSocket:** -1. Client → `wss://bff/ws?token={jwt}` -2. BFF валидирует JWT -3. BFF → `ws://tracker/ws` с TRACKER_TOKEN -4. Двусторонний relay - -### 8.4 Конфигурация +### Конфигурация (environment) ```bash +# Tracker TRACKER_URL=http://localhost:8100 TRACKER_WS_URL=ws://localhost:8100/ws TRACKER_TOKEN=tb-admin-xxx + +# Auth JWT_SECRET=secret-key AUTH_USER=admin AUTH_PASS=password + +# Server +BFF_HOST=0.0.0.0 +BFF_PORT=8200 ``` +### WebSocket прокси + +1. **Client подключение:** `wss://dev.team.uix.su/ws?token={jwt}` +2. **Валидация JWT:** Проверка токена, извлечение user +3. **Tracker подключение:** `ws://localhost:8100/ws` с TRACKER_TOKEN +4. **Двусторонний relay:** Client ↔ BFF ↔ Tracker + +### REST прокси + +Все API запросы проксируются с добавлением: +- **Авторизация:** Проверка JWT +- **Трансформация:** Добавление `author_slug` в сообщения +- **Логирование:** Запросы и ответы +- **CORS:** Для фронтенда + --- -## 9. Фронтенд +## 9. Фронтенд (Web Client) -### 9.1 Технологии +### Технологии -- **Next.js 15** (App Router) -- **Tailwind CSS** для стилизации -- **Native WebSocket API** -- **TypeScript** типизация +- **Framework:** Next.js 15 (App Router) +- **Styling:** Tailwind CSS +- **State:** React hooks (useState, useEffect) +- **HTTP:** fetch API +- **WebSocket:** Native WebSocket API -### 9.2 Реализованные компоненты +### Структура страниц + +- `/login` — Авторизация +- `/` — Список проектов +- `/projects/[slug]` — Канбан доска проекта +- `/projects/[slug]/settings` — Настройки проекта *(запланировано)* +- `/agents` — Управление агентами *(запланировано)* + +### Компоненты | Компонент | Описание | Статус | |-----------|----------|--------| -| `KanbanBoard` | Drag & drop + mobile tabs | ✅ Работает | -| `TaskModal` | title, description, status, priority, assignee | ✅ Базовая версия | -| `ChatPanel` | Lobby чат | ✅ Работает | -| `CreateTaskModal` | Создание задачи | ✅ Работает | -| `CreateProjectModal` | Создание проекта | ✅ Работает | -| `AuthGuard` | Проверка авторизации | ✅ Работает | +| `KanbanBoard` | Drag & drop доска + mobile tabs | ✅ Реализован | +| `TaskModal` | Модалка задачи (title, description, assignee, delete) | ✅ Базовая версия | +| `ChatPanel` | Чат (lobby) | ✅ Базовая версия | +| `CreateTaskModal` | Создание задачи | ✅ Реализован | +| `CreateProjectModal` | Создание проекта | ✅ Реализован | +| `AuthGuard` | Проверка авторизации | ✅ Реализован | -### 9.3 Планируемые компоненты +### Запланированные компоненты -- **TaskModal улучшения:** комментарии, steps, watchers -- **Agent Management:** страница /agents с генерацией токенов -- **Dashboard:** метрики и activity feed проекта -- **Mobile UI:** адаптация под телефоны +| Компонент | Описание | Статус | +|-----------|----------|--------| +| Task comments в TaskModal | Комментарии к задаче | **Запланировано** | +| Task steps в TaskModal | Live progress агента | **Запланировано** | +| Agent management page | Создание, настройки агентов | **Запланировано** | +| Project dashboard | Метрики и активность | **Запланировано** | +| Project settings | Настройки проекта | **Запланировано** | -### 9.4 API клиент +### API клиент (api.ts) -- **Base URL:** process.env.NEXT_PUBLIC_API_URL -- **Auth:** JWT из localStorage -- **Error handling:** 401 → redirect /login -- **TypeScript types** для всех моделей +- **Base URL:** `process.env.NEXT_PUBLIC_API_URL` +- **Авторизация:** JWT из localStorage +- **Обработка ошибок:** 401 → редирект на /login +- **TypeScript типы** для всех моделей -### 9.5 WebSocket клиент +### WebSocket клиент (ws.ts) ```typescript class WSClient { - connect(jwt: string) // ws://bff/ws?token=jwt + // Подключение через BFF с JWT токеном + connect() // ws://bff/ws?token=jwt + + // Event handlers on(type: string, handler: Function) + + // Convenience methods subscribeProject(projectId: string) sendChat(chatId: string, content: string) + sendTaskComment(taskId: string, content: string) heartbeat(status: string) } ``` +### Состояние приложения + +- **Авторизация:** JWT в localStorage +- **Проекты:** Загружаются при входе в систему +- **Задачи:** Загружаются для каждого проекта +- **WebSocket:** Глобальный клиент, подписка по проектам +- **Real-time:** Обновления через WebSocket события + --- ## 10. Деплой -### 10.1 Окружения - -- **dev.team.uix.su** — активное окружение -- **team.uix.su** — placeholder для продакшена - -### 10.2 Docker Compose (разработка) +### Docker Compose (разработка) ```yaml services: tracker: - build: ./services/tracker + build: ./tracker ports: ["8100:8100"] depends_on: [postgres, redis] @@ -626,19 +665,18 @@ services: image: postgres:16-alpine ports: ["5433:5432"] - redis: - image: redis:7-alpine + redis: + image: redis:7-alpine ports: ["6380:6379"] ``` -### 10.3 Systemd сервисы (продакшен) +### Systemd сервисы (продакшен) -- **Tracker:** Docker Compose + systemd unit -- **BFF + Web Client:** systemd на хосте -- **Picogent:** systemd unit на агента (один процесс = один сервис) -- **Nginx:** прокси + SSL/HTTPS +**Tracker:** Docker Compose + systemd unit +**BFF + Web Client:** systemd сервисы на хосте +**Picogent:** systemd unit на агента -### 10.4 Nginx конфигурация +### Nginx конфигурация ```nginx # Web Client @@ -646,12 +684,12 @@ location / { proxy_pass http://localhost:3100; } -# BFF API +# BFF API location /api/ { proxy_pass http://localhost:8200/api/; } -# BFF WebSocket +# BFF WebSocket location /ws { proxy_pass http://localhost:8200/ws; proxy_http_version 1.1; @@ -659,115 +697,182 @@ location /ws { proxy_set_header Connection "upgrade"; } -# Agent API (nginx → Tracker) +# Agent API (через nginx → Tracker) location /agent-api/ { proxy_pass http://localhost:8100/api/; } -# Agent WebSocket +# Agent WebSocket location /agent-ws { proxy_pass http://localhost:8100/ws; - proxy_http_version 1.1; + proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } ``` -### 10.5 Heartbeat и мониторинг +### SSL/HTTPS -- **systemd** перезапускает picogent при падении -- При reconnect агент делает `session.resume` -- Незавершённые задачи возвращаются в todo -- **Centralized logging** (JSON structured) +- **Dev:** `dev.team.uix.su` (действующий) +- **Prod:** `team.uix.su` (placeholder) +- **Cертификаты:** Let's Encrypt через certbot -### 10.6 Git Workflow +### База данных -- Агент клонит repo в рабочую директорию -- Работает в ветке `{type}/{task-key}-{slug}` -- По завершении → Merge Request в Gitea -- Ревью → approve/reject → автомерж -- Конфликты решает MR owner (макс 3 итерации) +- **Разработка:** PostgreSQL в Docker +- **Продакшен:** PostgreSQL на хосте +- **Миграции:** Нет (recreate from scratch) *(планируется Alembic)* +- **Бэкапы:** pg_dump *(запланировано)* + +### Процесс деплоя + +1. **Git push** → git.uix.su/team-board/docs +2. **Manual deploy** на сервере +3. **Restart services:** systemctl restart team-board-* +4. **Health check:** /health endpoints *(запланировано)* + +**CI/CD:** Пока ручной деплой. В будущем — Gitea Actions. --- -## 11. Ключевые решения из brainstorm-ов +## 11. Ключевые решения -### 11.1 Архитектурные решения +### Архитектурные решения из brainstorm-ов -**✅ Unified Message модель** — одна таблица для чатов и комментариев задач (вместо отдельных ChatMessage и TaskComment). +#### Unified Message Model +**Решение:** Одна модель `Message` для чат-сообщений И комментариев к задачам. +**Обоснование:** Проще API, единый компонент UI, треды работают везде. +**Статус:** Принято в BRAINSTORM-UI-2026-02-22. -**✅ Member + AgentConfig** — единая модель для людей и агентов (вместо отдельных User и Agent). +#### Tracker-Centric Architecture +**Решение:** Tracker — центральный хаб, всё остальное — клиенты. +**Обоснование:** Простота, масштабируемость, единая точка правды. +**Статус:** Принято в ARCHITECTURE.md. -**✅ Подзадачи vs Этапы:** подзадачи на канбане (parent_id), этапы внутри задачи (Steps). +#### WebSocket для событий, REST для мутаций +**Решение:** Разделение протоколов — WS только для push-событий. +**Обоснование:** Агенты через MCP tools, WebSocket не перегружен. +**Статус:** Принято в BRAINSTORM-PROTOCOL-2026-02-20. -**✅ Watchers паттерн** — Jira-подобная подписка на задачи для получения уведомлений. +#### Раздельные Listen Modes +**Решение:** `chat_listen` и `task_listen` — независимо. +**Обоснование:** Гибкая настройка подписок для разных ролей агентов. +**Статус:** Принято в BRAINSTORM-WS-V2-2026-02-22. -**✅ Listen modes раздельные** — chat_listen и task_listen независимы для гибкой фильтрации. +#### Подзадачи vs Этапы (Steps) +**Решение:** Подзадачи = задачи на канбане, этапы = чеклист внутри. +**Обоснование:** Не засорять канбан, но показывать прогресс агента. +**Статус:** Принято в BRAINSTORM-PROJECTS-2026-02-20. -**❌ Redis Streams отклонён** — избыточно для MVP. WS для online + REST для reconnect достаточно. +#### Checkpoint Pattern для агентов +**Решение:** Короткие задачи + проверка событий между шагами. +**Обоснование:** LLM блокирующий, нужно решать "глухой агент". +**Статус:** Принято в BRAINSTORM-AGENTS-2026-02-20. -### 11.2 Протокол решения +#### Агенты могут отклонять задачи +**Решение:** `reject_task` с обоснованием. +**Обоснование:** Агент не безмолвный исполнитель, может не согласиться. +**Статус:** Принято в BRAINSTORM-TASKS-2026-02-20. -**✅ WS = real-time, REST = мутации** — чёткое разделение ответственности. +#### Multi-repo проекты +**Решение:** `repo_urls: string[]` — массив репозиториев. +**Обоснование:** Современные проекты = frontend + backend + docs. +**Статус:** Принято в BRAINSTORM-PROJECTS-2026-02-20. -**✅ Фильтрация на сервере** — агент получает только релевантные события. +#### Файлы как Attachments +**Решение:** Отдельного файлового сервиса нет, файлы = вложения к сообщениям. +**Обоснование:** Простота, единая модель для чата и задач. +**Статус:** Принято в разговоре 2026-02-22, противоречило ранним документам. -**✅ Lazy Loading контекста** — агент при подключении НЕ грузит историю. +### Отклонённые решения -**✅ Project Subscribe объединяет** — одна подписка даёт чат + task события. +#### Redis Streams для Event Bus +**Решение:** НЕ реализовывать сейчас. +**Обоснование:** В BRAINSTORM-MICROSERVICES было принято, но хозяин сомневается. Пока WS достаточно. +**Статус:** Отклонено, оставлено как "идея на будущее". -**✅ Router как text relay** — WS события → текст → единственная сессия агента. +#### HTTP Callback для агентов +**Решение:** Только WebSocket для агентов. +**Обоснование:** Усложняет архитектуру, нет реальной потребности. +**Статус:** Отклонено из WS-PROTOCOL.md. -### 11.3 UI решения +#### Threads в комментариях задач +**Решение:** Threads только в чатах, в задачах — простая лента. +**Обоснование:** В задачах контекст и так понятен, треды избыточны. +**Статус:** Принято в BRAINSTORM-UI-2026-02-22. -**✅ Drag & drop канбан** — с fallback на mobile tabs. +#### Глобальные vs Per-project лейблы +**Статус:** Остается открытым вопросом. -**✅ TaskModal прогрессивно** — сначала базовые поля, потом комментарии/steps. +#### Реакции в чатах +**Статус:** Остается открытым вопросом (токен burn vs UX). -**✅ Значки авторов** — 👤 человек, 🤖 агент, ⚙️ система в сообщениях. +### На будущее (запланированы) -**✅ Threads только в чатах** — в задачах простая лента комментариев. +#### Web MCP Server +**Описание:** Отдельный MCP Server для работы любого LLM-клиента с трекером. +**Статус:** Идея из BRAINSTORM-PROTOCOL-2026-02-20. -### 11.4 Агентные решения +#### Session Compaction +**Описание:** Сжатие длинной истории сессии агента в summary. +**Статус:** Детали в AGENT-CONNECTION-RESEARCH.md. -**✅ Один binary — разные роли** — picogent + agent.json конфиг. +#### Telegram Bridge +**Описание:** Бот дублирует сообщения project chats в Telegram с топиками. +**Статус:** MVP описан в BRAINSTORM-MISC-2026-02-21. -**✅ Capabilities = лейблы** — автоматический matching задач и агентов. +#### OAuth/Authentik интеграция +**Описание:** Мультипользовательский режим с SSO. +**Статус:** Упоминается в архитектуре. -**✅ Агент может отклонить** — не безмолвный исполнитель, может отказаться с обоснованием. - -**✅ Checkpoint pattern** — короткие задачи + проверка входящих между шагами. - -**✅ Heartbeat мониторинг** — 30s интервал, 90s timeout → offline. - -### 11.5 Файловые решения - -**✅ Файлы = attachments** — нет отдельного файлового сервиса, всё через Message. - -**✅ Multi-repo проекты** — массив repo_urls вместо одного git_repo. - -**✅ Документация в описании** — ссылки на docs в Project.description или repo_urls. - -### 11.6 Отложенные/открытые решения - -**🔶 Реакции в чатах** — как обрабатывать emoji без засорения промпта агента. - -**🔶 Лейблы:** глобальные или per-project? - -**🔶 Multi-instance агентов:** slug = роль, instance_id для различения? - -**🔶 Telegram Bridge:** формат сообщений, топики, голосовые через Thoth. - -**🔶 OAuth/Authentik:** мультипользовательский режим (запланировано). - -### 11.7 Принципы проектирования - -**Минимум токенов:** Любая оптимизация оценивается с точки зрения раздувания MD-файлов контекста. Максимум логики в коде, минимум в MD. - -**Прогресс-апдейты:** При длительных операциях сообщать о прогрессе по ходу, не копить до конца. - -**Transparency First:** Всё видимо в чатах — создание задач, MR события, статусы агентов. +#### Agent Home с self-improving промптами +**Описание:** Агент сам улучшает свой промпт на основе опыта. +**Статус:** Детали в BRAINSTORM-PROMPTS-2026-02-21. --- -*Документ создан на основе изучения 23 файлов документации Team Board по состоянию на 2026-02-23. Является единой точкой правды для всех концепций системы.* \ No newline at end of file +## Нереализованные части + +### Backend (запланировано) + +- ❌ **Task events через WebSocket** — task.created/updated/assigned +- ❌ **Agent token auth для REST API** (только WS имеет проверку токенов) +- ❌ **Attachments API** — загрузка/скачивание файлов +- ❌ **Task dependencies** — валидация и уведомления о разблокировке +- ❌ **Watchers на задачах** — подписка на уведомления +- ❌ **Task watchers API** — POST/DELETE /tasks/{id}/watch + +### Frontend (запланировано) + +- ❌ **Task comments в TaskModal** — комментарии к задачам +- ❌ **Task steps в TaskModal** — live progress агентов +- ❌ **Agent management страница** — /agents с созданием и настройками +- ❌ **Project dashboard** — метрики и активность +- ❌ **Project settings** — настройки проекта +- ❌ **Mobile UI оптимизация** — полная адаптация под телефоны + +### Infrastructure (запланировано) + +- ❌ **Health check endpoints** — /health для мониторинга +- ❌ **Database migrations** — Alembic вместо recreate +- ❌ **CI/CD pipeline** — Gitea Actions автодеплой +- ❌ **Monitoring/metrics** — Grafana dashboard +- ❌ **Backup strategy** — автоматические бэкапы БД + +### Agent System (запланировано) + +- ❌ **MCP Tools полный набор** — для picogent агентов +- ❌ **Session resume** — восстановление контекста при переподключении +- ❌ **Agent home directory** — workspace, memory, sessions +- ❌ **Multi-instance агентов** — scaling одной роли +- ❌ **Self-improving промпты** — agent.prompt.md обновляется агентом + +--- + +## Заключение + +Этот документ v2.0 создан на основе полного анализа всех 24 файлов документации Team Board по состоянию на 2026-02-23. Он объединяет все принятые решения из brainstorm-ов, архитектурные концепции и текущее состояние реализации в единую точку правды. + +**Принцип документа:** Описываем решения и концепции, а не текущее состояние кода. Если что-то запланировано но не реализовано — помечено как "Запланировано", а не TODO. + +При расхождении между документацией и кодом — **приоритет у кода** (он правдивее), документ нужно обновить. \ No newline at end of file