From 49a9c7dc50c803dae04da3074840deaa71b09a52 Mon Sep 17 00:00:00 2001 From: Markov Date: Sun, 22 Feb 2026 17:02:22 +0100 Subject: [PATCH] =?UTF-8?q?ARCHITECTURE.md=20v0.4=20=E2=80=94=20unified=20?= =?UTF-8?q?source=20of=20truth,=20all=20contradictions=20resolved?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ARCHITECTURE.md | 611 ++++++++++++++++++++++-------------------------- 1 file changed, 285 insertions(+), 326 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index e9b47a2..b54578e 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,6 +1,6 @@ # Team Board — Архитектура -Версия: 0.3 (драфт) -Дата: 2026-02-21 +Версия: 0.4 +Дата: 2026-02-22 ## Что это @@ -19,8 +19,8 @@ ┌────────────────────────────────────────┤ │ │ │ │ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ ┌──▼───┐ - │Picogent │ │Picogent │ │Telegram │ │ DB │ - │ Кодер │ │Архитект │ │ Bridge │ │Pg+Red│ + │Picogent │ │Picogent │ │Telegram │ │ DB │ + │ Кодер │ │Архитект │ │ Bridge │ │ Pg │ └─────────┘ └─────────┘ └─────────┘ └──────┘ ``` @@ -31,110 +31,11 @@ | **Web Client** | Next.js 15, Tailwind CSS | 3100 | UI: канбан, чат, настройки. | | **Picogent** | Node.js, TypeScript, Pi Agent Core | — | AI-агент. Подключается к Tracker по WS. | | **Telegram Bridge** | TBD | — | Дублирует чат проекта в Telegram (с топиками). | -| **OpenClaw Bridge** | TBD | — | Фильтрует @markov mentions → webhook в OpenClaw. | -| **PostgreSQL** | 16 | 5433 | БД Tracker. | -| **Redis** | 7 | 6380 | Пока не используется. | - -## Проекты - -Проект = workspace для команды (людей + агентов). - -**Поля:** name, slug, description, repo_urls[] (multi-repo), status (active/archived). - -**Вкладки UI:** канбан, чат, дашборд, настройки, файлы, activity feed. - -**Правила:** описываются в документации проекта (docs/ в repo или file storage). Агенты читают при онбординге. - -**Кросс-проектные ссылки:** задача в проекте A может ссылаться на задачу в проекте B. - -## Задачи - -### Модель -| Поле | Тип | Описание | -|------|-----|----------| -| id | UUID | | -| title | string | Название | -| description | text | Markdown | -| type | enum | task, bug, epic, story | -| status | enum | backlog, todo, in_progress, in_review, done | -| priority | enum | critical, high, medium, low | -| labels | string[] | bug, feature, refactor, docs... | -| parent_id | UUID? | Подзадача (бесконечная вложенность) | -| depends_on | UUID[] | Зависимости (нельзя начать пока не done) | -| assignee_slug | string? | Исполнитель | -| reviewer_slug | string? | Ревьюер | -| steps | Step[] | Этапы (прогресс агента, не видны на канбане) | -| time_spent | int | Минуты (для аналитики) | -| project_id | UUID | | - -### Статусы -Любой → любой. Без жёсткого flow. `todo → done` — нормально, если задача простая. - -### Подзадачи vs Этапы -- **Подзадачи** = полноценные задачи на канбан-доске (parent_id) -- **Этапы (steps)** = чеклист внутри задачи. Агент обновляет по ходу работы. Не засоряют доску. - -### Комментарии -``` -TaskComment: id, task_id, author_type (human|agent|system), - content, mentions[], voice_url?, attachments[], - parent_comment_id? (threads), created_at -``` -Mentions (@slug) → уведомление агенту через WS. - -### Связи между задачами (Task Links) -Помимо parent/child и depends_on, задачи поддерживают дополнительные связи: -- **relates_to** — связанные задачи (информационно) -- **duplicates** — дубликат другой задачи -- **blocks / blocked_by** — блокировка (аналог depends_on, но для человеческого UI) - -Агенты используют `depends_on` для автоматики, остальные связи — для людей в UI. - -### Назначение задач -1. Человек назначает вручную -2. Архитектор создаёт и назначает -3. Агент сам берёт из `todo` по capabilities (`task.take` — атомарная операция) -4. Через чат с @mention: "ребята, новая задача" -5. Auto-assign: Tracker предлагает задачу по capabilities + загрузке (HYBRID модель) - -### Приоритизация очереди -- По приоритету задачи (critical → high → medium → low) -- Если задача назначена на конкретного агента → он берёт первым -- Label matching: лейблы задачи ∩ capabilities агента - -### Особенности -- Агент может **отклонить** задачу (reject_task) с обоснованием -- **Автообнаружение блокеров**: зависимость застряла → пинг в чат -- **Задача-наблюдатель**: не на выполнение, а мониторинг ("следи за CI", "проверяй X раз в час"). Периодическая/фоновая задача. -- Задача порождает подзадачи автоматически (агент создаёт через create_task) -- Циклические зависимости запрещены (валидация при создании) - -## Чаты - -### Типы -| Тип | Описание | Файлы | -|-----|----------|-------| -| **Lobby** | Глобальный чат для всех | Нет хранилища | -| **Project Chat** | Per-project, координация | Да | -| **Task Comments** | Per-task, обсуждение задачи | Да | - -### Фичи -- **Threads** (как в Slack) — ответ на сообщение создаёт ветку -- **Голосовые** — запись → Thoth транскрибирует → текст + аудио -- **Файлы в чат** — документы, изображения -- **Реакции** — TBD (не попадают в промпт агента, чисто UI) - -### Модель сообщения -``` -ChatMessage: id, chat_id, author_type, author_slug, - content (markdown), thread_id?, mentions[], - voice_url?, attachments[], reactions[], created_at -``` ## Участники (Members) ### Ключевой принцип: все равны -Агент и человек — **одна модель**. Различие только в type и методе авторизации. +Агент и человек — **одна модель (Member)**. Различие только в type и методе авторизации. ``` Member: @@ -144,45 +45,41 @@ Member: type: human | agent role: owner | member | observer | bridge auth_method: password | oauth | token - capabilities: string[] # для агентов: coding, review... - listen_mode: all | mentions # для агентов (human сам решает) - prompt: string? # system prompt (только для агентов) - model: string? # LLM модель (только для агентов) status: online | offline | busy avatar_url: string? ``` -### Авторизация -| Тип | Метод | Пример | -|-----|-------|--------| -| human (Web UI) | login/password, OAuth (Authentik) | Человек в браузере | -| human (MCP Client) | login/password, OAuth | Claude Code CLI, Cursor | -| agent (Picogent) | token (сгенерирован в UI) | Автономный AI-агент | -| agent (Марков/OpenClaw) | token (REST API) | AI через скилл | -| bridge | token | Telegram Bridge | +Для `type=agent` — дополнительные поля (или связанная таблица `AgentConfig`): +``` +AgentConfig: + member_id: UUID (FK → Member) + capabilities: string[] # coding, review, testing... + chat_listen: all | mentions + task_listen: all | mentions + prompt: text # system prompt + model: string # LLM модель +``` -MCP Client (Claude Code, Cursor) — это **человек с инструментами**, не агент. Авторизация как у человека. +### Авторизация +| Тип | Метод | +|-----|-------| +| human (Web UI) | login/password, OAuth | +| human (MCP Client) | login/password, OAuth | +| agent (Picogent) | token | +| bridge | token | + +MCP Client (Claude Code, Cursor) — это **человек с инструментами**, не агент. ### Роли -| Роль | Описание | Права по умолчанию | -|------|----------|-------------------| -| `owner` | Владелец доски. Полные права. | Все | -| `member` | Участник. Выполняет задачи, пишет в чат. | send_messages, create_tasks, update_tasks | -| `observer` | Только чтение. | — | -| `bridge` | Мост (Telegram). Пересылает сообщения, не берёт задачи. | send_messages | +| Роль | Права | +|------|-------| +| `owner` | Все | +| `member` | send_messages, create_tasks, update_tasks | +| `observer` | Только чтение | +| `bridge` | send_messages | -### Права (permissions) -| Право | Описание | -|-------|----------| -| `send_messages` | Отправка сообщений в чаты | -| `create_tasks` | Создание новых задач | -| `assign_tasks` | Назначение задач другим агентам | -| `update_tasks` | Изменение статуса/описания задач | -| `manage_agents` | Управление другими агентами | -| `manage_projects` | Создание/изменение проектов | - -### Конфигурация -Один бинарник, роль = конфиг (`agent.json`): +### Конфигурация агента +Один бинарник (picogent), роль = конфиг (`agent.json`): ```json { "name": "Кодер", @@ -190,236 +87,298 @@ MCP Client (Claude Code, Cursor) — это **человек с инструме "prompt": "Ты опытный разработчик...", "model": "sonnet", "capabilities": ["coding", "review"], - "listen_mode": "mentions", + "chat_listen": "mentions", + "task_listen": "mentions", "tracker_url": "http://localhost:8100", "token": "tb-agent-xxx" } ``` -### Режимы прослушивания -- `listen: all` — слышит всё в чате (архитектор, PM) -- `listen: mentions` — только при @упоминании (кодер, тестер) +### Listen Modes (раздельные) +- `chat_listen: all` — слышит все сообщения в чатах проекта +- `chat_listen: mentions` — только при @упоминании +- `task_listen: all` — получает все события задач проекта +- `task_listen: mentions` — только свои задачи (assignee/reviewer/watcher) и @mentions + +Примеры: +- Архитектор: chat=all, task=all +- Кодер: chat=mentions, task=mentions +- Тестер: chat=mentions, task=all ### Одна сессия на агента Всё в одном контексте: задачи, чат, ответы. Агент видит полную картину. -### Онбординг -При подключении к проекту агент получает контекст: README, docs, архитектуру. +### Checkpoint Pattern (глухой агент) +LLM блокирующий — агент не слышит пока думает. +Решения: короткие задачи (5-10 мин) + проверка входящих между шагами. -### Memory -Per-agent + per-project. Агент дописывает findings после задач. +### Heartbeat и таймауты +- Агент шлёт `heartbeat` каждые 30 сек +- Нет heartbeat 90 сек → `status=offline`, уведомление в чат +- Незавершённые задачи → возвращаются в `todo` +- systemd перезапускает picogent, агент делает `session.resume` -### Что агент получает -Текстовые сообщения (максимум разговорной речи): -- `"Тебе назначена задача TB-42: Добавить авторизацию. Приоритет: high."` -- `"[чат проекта] @architect: Используй JWT для авторизации"` -- `"[комментарий к TB-42] @reviewer: В auth.py строка 42 не обработан expired token"` +## Проекты -Агент сам решает что делать — вызывает MCP tools. - -### Label Matching -Задача имеет labels, агент поддерживает labels → автоматический matching для assign. - -### Проблема "глухого агента" (Checkpoint Pattern) -LLM `query()` блокирующий — агент не слышит новых сообщений пока думает. - -**Решения:** -- **Короткие задачи** — декомпозиция на шаги по 5-10 минут -- **Checkpoint pattern** — агент проверяет входящие между шагами работы -- **session.checkpoint** — агент сохраняет своё понимание контекста в Tracker, чтобы при сбое продолжить с того же места - -### Зависший агент / Таймауты -- **Heartbeat** — агент шлёт `agent.heartbeat` каждые 30 секунд -- Если heartbeat не пришёл 90 секунд → `agent.status = offline` -- Уведомление в чат: "Агент X перестал отвечать" -- **Grace period**: при дисконнекте статус сначала `away` (60 сек), потом `offline` -- Незавершённые задачи: возвращаются в `todo` или ждут (зависит от политики) -- **Рестарт**: systemd перезапускает picogent, агент делает session.resume - -### Reconnect и восстановление сессии -При реконнекте агент отправляет `session.resume` с `last_seq` (последнее известное сообщение). Tracker возвращает `context_summary` + пропущенные сообщения. Агент продолжает работу. - -### Контракт агента (contract) -Описывает capabilities, лимиты и разрешённые tools: -```json -{ - "capabilities": ["coding", "review"], - "max_concurrent_tasks": 2, - "timeout_seconds": 600, - "tools": {"file_read": true, "git_commit": true, "shell_exec": false}, - "limits": {"max_file_size_mb": 10, "max_files_per_task": 20} -} ``` +Project: + id: UUID + name: string + slug: string + description: text + repo_urls: string[] # multi-repo + status: active | archived +``` + +**Вкладки UI:** канбан, чат, дашборд, настройки, файлы, activity feed. + +**Документация проекта:** указывается в description / repo_urls. Агенты читают при онбординге. + +## Задачи + +### Модель +``` +Task: + id: UUID + title: string + description: text (markdown) + type: task | bug | epic | story + status: backlog | todo | in_progress | in_review | done + priority: critical | high | medium | low + labels: string[] + parent_id: UUID? # подзадача + depends_on: UUID[] # зависимости + assignee_slug: string? + reviewer_slug: string? + watchers: string[] # slugs наблюдателей + time_spent: int # минуты + project_id: UUID +``` + +### Статусы +Любой → любой. Без жёсткого flow. + +### Подзадачи vs Этапы (Steps) +- **Подзадачи** = полноценные задачи на канбан-доске (parent_id) +- **Этапы (steps)** = чеклист внутри задачи (прогресс агента, не на канбане) + +### Watchers (наблюдатели) +Jira-паттерн. Любой может подписаться на задачу и получать уведомления. +- Assignee, reviewer, watchers — получают все события задачи +- Автор задачи = автоматически watcher +- MCP tools: `watch_task`, `unwatch_task` + +### Назначение +1. Человек назначает вручную +2. Архитектор создаёт и назначает +3. Агент сам берёт из `todo` (`take_task` — атомарно) +4. Label matching: лейблы задачи ∩ capabilities агента + +### Особенности +- Агент может **отклонить** задачу (`reject_task`) с причиной +- Автообнаружение блокеров (зависимость застряла → пинг в чат) +- Циклические зависимости запрещены + +## Сообщения (Unified Message) + +**Одна модель** для чата и комментариев задач: +``` +Message: + id: UUID + content: text (markdown) + author_type: human | agent | system + author_slug: string + chat_id: UUID? # если в чате (lobby / project) + task_id: UUID? # если комментарий к задаче + parent_id: UUID? # thread (ответ на сообщение) + mentions: string[] + attachments: Attachment[] + voice_url: string? + created_at: timestamp +``` + +### Типы чатов +| Тип | Описание | +|-----|----------| +| **Lobby** | Глобальный чат | +| **Project Chat** | Per-project | +| **Task Comments** | Per-task (через task_id в Message) | + +### Фичи +- **Threads** — только в чатах (parent_id). В задачах — просто лента. +- **Голосовые** — Thoth транскрибирует → текст + аудио +- **Файлы** — attachments в сообщениях + +### Значки авторов в UI +👤 человек, 🤖 агент, ⚙️ система + +## Файлы + +**Отдельного файлового сервиса нет.** Файлы = attachments в Message (к сообщениям, комментариям задач). + +``` +Attachment: + id: UUID + message_id: UUID + filename: string + mime_type: string + size: int + storage_path: string # путь на диске +``` + +**Конфигурация:** путь к директории хранилища в конфиге Tracker. + +Документация проекта — ссылка в `repo_urls[]` или описании проекта. ## Протокол ### Принцип -- **WebSocket** = real-time: события (push) + сообщения чата -- **REST (MCP tools)** = все мутации: задачи, этапы, файлы, статусы +- **WebSocket** = real-time: события (push) + отправка сообщений в чат +- **REST (MCP tools)** = все мутации: задачи, steps, файлы, статусы -### WS Protocol +### WS: Клиент → Сервер +| Событие | Описание | +|---------|----------| +| `auth` | Токен + инфо агента | +| `heartbeat` | Статус (idle/busy) | +| `ack` | Подтверждение события | +| `chat.send` | Сообщение в чат | +| `project.subscribe` | Подписка на проект (чат + task events) | +| `project.unsubscribe` | Отписка | -**Инфраструктура:** -``` -Agent → Tracker: auth, heartbeat, ack -Tracker → Agent: auth.ok, auth.error, event -``` +### WS: Сервер → Клиент +| Событие | Фильтрация | +|---------|-----------| +| `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` | Всем | -**События (push):** -| Событие | В промпт? | | -|---------|-----------|--| -| task.assigned | ✅ | Текстом | -| chat.message | ✅/❌ | По listen_mode | -| task.comment (mention) | ✅ | Текстом | -| task.taken | ❌ | Internal | -| task.status_changed | ❌ | Internal (кроме разблокировки зависимости) | - -### MCP Tools (REST) -| Tool | Описание | -|------|----------| -| get_task, list_tasks | Чтение задач | -| create_task | Создать задачу/подзадачу | -| update_task | Обновить поля | -| take_task | Взять себе (атомарно) | -| reject_task | Отклонить с причиной | -| add_step, complete_step | Управление этапами | -| add_comment | Комментарий (с mentions) | -| send_message | Сообщение в чат | -| upload_file, list_files | Файлы | +### Фильтрация событий на сервере +Агент получает только релевантное: +- **task events** → assignee + reviewer + watchers + task_listen:all +- **chat events** → chat_listen:all ИЛИ @mention +- Агенты с `task_listen:mentions` НЕ получают чужие task.created/updated ### Router (в Picogent) -Тупой relay: WS event → текст → единственная сессия агента. Агент сам вызывает tools. +Тупой text relay: WS event → текстовое сообщение → единственная сессия агента. +Агент сам решает что делать — вызывает MCP tools. -### Межагентная коммуникация -Агенты общаются через чат (send_message с @mention). Для структурированных запросов — протокол `agent.request` / `agent.response`: -``` -Кодер → Tracker: agent.request {target: "reviewer", type: "code_review", payload: {pr_url}} -Tracker → Ревьюер: agent.request {from: "coder", request_id, payload} -Ревьюер → Tracker: agent.response {request_id, result: {approved, comments}} -``` +## MCP Tools (REST API) -## Файловое хранилище +### Задачи +| Tool | Описание | +|------|----------| +| `list_tasks` | Список (фильтры: project, status, assignee, labels) | +| `get_task` | Получить задачу по ID/key | +| `create_task` | Создать | +| `update_task` | Обновить поля | +| `take_task` | Взять себе (атомарно) | +| `reject_task` | Отклонить с причиной | +| `assign_task` | Назначить другому | +| `delete_task` | Удалить | -- Per-project директории -- Upload/download через REST API -- Связь с git repos (repo_urls[]) -- Версионирование файлов — TBD +### Steps +| Tool | Описание | +|------|----------| +| `add_step` | Добавить этап | +| `complete_step` | Завершить этап | +| `update_step` | Обновить текст | + +### Сообщения +| Tool | Описание | +|------|----------| +| `send_message` | В чат (chat_id) или к задаче (task_id) | +| `reply_message` | Ответ в thread (parent_id) | +| `list_messages` | Список (по chat_id / task_id) | + +### Файлы +| Tool | Описание | +|------|----------| +| `upload_file` | Загрузить | +| `list_files` | Список по задаче/проекту | +| `download_file` | Скачать | + +### Проекты и участники +| Tool | Описание | +|------|----------| +| `list_projects` | Список проектов | +| `get_project` | Информация о проекте | +| `list_members` | Кто в проекте | +| `update_status` | Обновить свой статус | +| `watch_task` | Подписаться на задачу | +| `unwatch_task` | Отписаться | ## Git Workflow -### Принцип -- Агент клонирует repo в свою рабочую директорию -- Работает в отдельной ветке: `{type}/{task-id}-{slug}` (feat/fix/refactor/docs) -- По завершении → **Merge Request** в Gitea -- Ревью (агент/человек) → approve/reject -- **Автомерж** после approve +- Агент клонирует repo, работает в ветке `{type}/{task-key}-{slug}` +- По завершении → Merge Request в Gitea +- Ревью → approve/reject → автомерж +- Конфликты решает MR owner. Макс 3 итерации, потом эскалация +- Git tools НЕ в MCP — агент работает через git CLI -### Конфликты -- Решает тот, чей MR. После разрешения — повторный review. -- Lock на файлы — **не нужен** -- Максимум 3 итерации ревью, потом эскалация к человеку +## Промпты агентов -### Gitea интеграция -- Webhooks от Gitea → Tracker: push, PR opened/reviewed/merged -- Tracker → Gitea API: создание веток, PR, комментирование -- PR merged → задача автоматически в Done -- CI/CD через Gitea Actions — автотесты на MR +Многослойный промпт: +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 -### Ревью -- Автор ≠ ревьюер (всегда) -- Не каждая задача требует PR (определяется лейблами: `coding` → PR, `analytics` → нет) -- Все комментарии ревью в задаче (единый контекст) +Agent Home: +``` +agents/coder/ + agent.json # конфиг + prompt.md # само-улучшаемый промпт + memory/ # per-project память + workspace/ # рабочие файлы + sessions/ # сессии (JSONL) +``` -## Telegram Bridge (MVP) +## Web UI (текущее состояние) -- Один бот, подключается по WS к Tracker как `client_type=bridge` -- Дублирует сообщения из project chats в Telegram -- **Топики**: если в Telegram включены topics → бот пишет в топик с именем проекта (каждый проект = отдельный топик) -- Форматирование: `👤 Eugene: текст` / `🤖 Кодер: текст` / `⚙️ Задача #42 → in_progress` -- **Telegram → Tracker**: сообщение из группы → `chat.send` с `sender_type=bridge` -- **Упоминания**: парсит `@slug` из Telegram → `mentions` в `chat.send` -- Системные события (task.created, task.updated) → уведомления в группу -- ⚠️ Ограничение Telegram: боты НЕ видят сообщения других ботов → один бот = bridge для всех +### Реализовано +- KanbanBoard (колонки, drag & drop) +- TaskModal (title, description, status, priority, assignee, delete) +- ChatPanel (lobby) +- Sidebar, CreateProjectModal, AuthGuard, Login -## Безопасность +### Следующие шаги +1. Комментарии в TaskModal (Message с task_id) +2. Steps в TaskModal (live-прогресс агента) +3. Agent management (генерация токенов) +4. Dashboard проекта -- **Аутентификация**: токены (прописываются при регистрации агента). Каждый агент = уникальный токен. -- **Роли и permissions**: owner / agent / bridge / observer (см. раздел Агенты) -- **Capabilities enforcement**: агент с capabilities=["code"] не получит задачи на review -- **Rate limiting** — планируется: chat.send 30/min, task.progress 10/min и т.д. -- **Audit log** — планируется: логирование всех действий -- **Token rotation** — планируется: ротация каждые 30 дней - -## Версионирование API - -- REST API: `/api/v1/`, `/api/v2/` -- Обратная совместимость при обновлении -- WS Protocol: версия в auth handshake +## Telegram Bridge (будущее) +- Один бот, WS к tracker как bridge +- Топики в Telegram = проекты +- Формат: `👤 Eugene: текст` / `🤖 Кодер: текст` ## Деплой - -- **Tracker + BFF + Web Client**: Docker Compose -- **Picogent**: systemd сервис (один процесс на агента) -- Автоматический restart при падении (systemd) -- CI/CD: Gitea Actions auto-deploy -- Агент-DevOps возможен для CI/CD задач +- Tracker: Docker Compose (+ PostgreSQL) +- BFF + Web Client: systemd на хосте +- Picogent: systemd (один процесс на агента) +- CI/CD: Gitea Actions ## На будущее - -- **Web MCP Server** — отдельный пакет (`team-board/mcp-server`), любой LLM-клиент (Claude Code, Cursor, Windsurf, Cline, OpenClaw) работает с трекером через MCP без WebSocket и без Picogent. Использует тот же REST API. Не автономный (нет push-событий), но полностью функциональный. -- **Multi-instance агентов** — scaling, несколько кодеров одного типа. Вопрос: slug = роль, instance_id = отдельно? Требует продумывания. -- **Аналитика** — метрики, дашборды (tasks/hour, avg task duration, agent utilization) +- **Web MCP Server** — любой LLM-клиент работает с трекером через MCP +- **Redis Streams** — event bus для масштабирования (если понадобится) +- **Multi-instance агентов** — scaling - **OAuth / Authentik** — мульти-пользователь -- **Notification Bridge** — отдельный bridge-агент, подключается по WS, пушит уведомления за пределы чата (email, push, webhooks) -- **Agent SDK** — Python-пакет (`team-board-sdk`) с базовым классом Agent, обработчиками on_task/on_chat/on_reconnect, интеграцией с git -- **Session Compaction** — при превышении контекста (50K токенов) сжатие истории в summary + recent window -- **Event Sourcing** — вся работа агента как поток событий для воспроизведения и восстановления состояния +- **Session Compaction** — сжатие контекста при превышении лимита -## Конкурентный анализ (референсы) +## Открытые вопросы +- Лейблы: глобальные или per-project? +- Реакции в чатах: как обрабатывать? +- Multi-instance: slug = роль, instance_id? +- Rollback файлов (attachments не версионированы) -| Система | Ключевые идеи | Что забираем | -|---------|---------------|-------------| -| **MetaGPT** | Промпты ролей (PM, Architect, Engineer, QA), pub/sub между ролями, SOP | Промпты для назначения ролей агентам | -| **Claude Flow / Ruflo** | Claims (атомарное взятие задач), swarm топологии, multi-provider | Паттерн claims для task.take | -| **BMAD Method** | Brainstorming workflow, party mode (мульти-ролевой prompt) | Workflow для планирования | -| **OpenHands** | Event sourcing, Docker sandbox, event log replay | Воспроизводимость сессий | -| **LangGraph** | State machine + persistent checkpointing | Checkpoint pattern | -| **CrewAI** | Role-based delegation, task routing по ролям | Capabilities matching | -| **Devin** | VM-sandbox, persistent sessions (часы), полный git цикл | Долгие сессии с checkpoints | - -### Picogent vs Runner -Picogent (Node.js, TypeScript, Pi Agent Core) **заменяет** runner/ — более зрелая реализация. In-process agent loop, dual transport (HTTP + WebSocket), skills, sessions, sandbox, directory mode. - -## Идеи на подумать - -### ⚠️ Требуют отдельного обсуждения -- **Rollback файлов**: git revert очевиден, но файлы в хранилище **не версионированы**. Нужно ли версионирование файлов или хотя бы бэкап перед изменением? -- **Реакции в чатах**: выглядит круто, но жрёт токены. Варианты: (a) не попадают в промпт агента, (b) агент ставит через MCP tool, (c) попадают только @mention-reactions. Решение TBD. -- **Лейблы глобальные или per-project?** — не решено -- **Формат скилла для Runner'ов** — как описать взаимодействие агента с Tracker -- **Как агент определяет релевантность задачи для себя?** — auto-assign vs manual -- **Workspace агентов: общий или изолированный?** -- **Прогресс работы агента в реалтайме** (streaming в UI) - -### 💡 Идеи на будущее -- **Agent SDK v1.0** — Python-пакет с базовым классом, git-хелперами, LLM-интерфейсом -- **Redis Streams** для event bus (горизонтальное масштабирование Tracker) -- **Structured inter-agent requests** (agent.request/response) для code review, delegation -- **task.offer / task.accept / task.decline** — Tracker предлагает задачу, агент может отклонить (HYBRID модель) -- **Compaction сессий** — server-side или agent-side сжатие контекста -- **Grafana dashboard**: WS connections, task flow, agent utilization -- **Token rotation** (30 дней) + per-agent capability enforcement -- **Docker containers per agent** для sandbox isolation -- **Gitea webhook handler** в Tracker для автоматизации git-событий -- **HTTP Callback** как альтернативный транспорт (Tracker POST'ит события на URL агента) -- **Агент создаёт проект** — Архитектор может создать проект через API -- **Subscription modes**: `all` / `mentions` / `assigned` (разные уровни вовлечения) - -### ❌ Отклонено (из брейншторма) -- Шаблоны задач / проектов — не нужны -- Forking проектов — не нужен -- Автостатус задач — не нужен -- Оценка сложности / дедлайны — не нужны -- Lock на файлы — не нужен -- Бюджет в токенах — нет -- Приватность проектов — агент не трогает чужое +## Устаревшие документы +- `WS-PROTOCOL.md` — заменён BRAINSTORM-WS-V2-2026-02-22.md +- `AGENTS-INTEGRATION.md` — заменён ARCHITECTURE.md