From 3353e2ea53b01266bbd4103aa4ebff7671530bc4 Mon Sep 17 00:00:00 2001 From: Markov Date: Sat, 21 Feb 2026 10:54:16 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=BF=D0=BE=D0=BB=D0=BD?= =?UTF-8?q?=D0=B8=D1=82=D1=8C=20ARCHITECTURE.md=20=D0=B8=D0=B7=20=D0=B2?= =?UTF-8?q?=D1=81=D0=B5=D1=85=20=D0=B1=D1=80=D0=B5=D0=B9=D0=BD=D1=88=D1=82?= =?UTF-8?q?=D0=BE=D1=80=D0=BC-=D1=84=D0=B0=D0=B9=D0=BB=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Добавлено: роли/permissions, git workflow, checkpoint pattern, таймауты, связи задач, межагентная коммуникация, Telegram Bridge детали, версионирование API, деплой, конкурентный анализ, раздел 'Идеи на подумать' --- ARCHITECTURE.md | 203 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 186 insertions(+), 17 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 1dc49ac..277538a 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,5 +1,5 @@ # Team Board — Архитектура -Версия: 0.2 (драфт) +Версия: 0.3 (драфт) Дата: 2026-02-21 ## Что это @@ -81,11 +81,32 @@ TaskComment: id, task_id, author_type (human|agent|system), ``` 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) +- Циклические зависимости запрещены (валидация при создании) ## Чаты @@ -111,6 +132,24 @@ ChatMessage: id, chat_id, author_type, author_slug, ## Агенты (Picogent) +### Роли +| Роль | Описание | Права по умолчанию | +|------|----------|-------------------| +| `owner` | Владелец доски. Полные права. Один на инстанс. | Все | +| `agent` | AI-агент. Выполняет задачи, пишет в чат. | send_messages, update_tasks | +| `bridge` | Мост (Telegram, Slack). Пересылает сообщения, не берёт задачи. | send_messages | +| `observer` | Только чтение. Получает события, но не может действовать. | — | + +### Права (permissions) +| Право | Описание | +|-------|----------| +| `send_messages` | Отправка сообщений в чаты | +| `create_tasks` | Создание новых задач | +| `assign_tasks` | Назначение задач другим агентам | +| `update_tasks` | Изменение статуса/описания задач | +| `manage_agents` | Управление другими агентами | +| `manage_projects` | Создание/изменение проектов | + ### Конфигурация Один бинарник, роль = конфиг (`agent.json`): ```json @@ -150,6 +189,37 @@ Per-agent + per-project. Агент дописывает findings после з ### 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} +} +``` + ## Протокол ### Принцип @@ -189,6 +259,14 @@ Tracker → Agent: auth.ok, auth.error, event ### Router (в Picogent) Тупой relay: WS event → текст → единственная сессия агента. Агент сам вызывает 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}} +``` + ## Файловое хранилище - Per-project директории @@ -196,30 +274,121 @@ Tracker → Agent: auth.ok, auth.error, event - Связь с git repos (repo_urls[]) - Версионирование файлов — TBD +## Git Workflow + +### Принцип +- Агент клонирует repo в свою рабочую директорию +- Работает в отдельной ветке: `{type}/{task-id}-{slug}` (feat/fix/refactor/docs) +- По завершении → **Merge Request** в Gitea +- Ревью (агент/человек) → approve/reject +- **Автомерж** после approve + +### Конфликты +- Решает тот, чей 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 + +### Ревью +- Автор ≠ ревьюер (всегда) +- Не каждая задача требует PR (определяется лейблами: `coding` → PR, `analytics` → нет) +- Все комментарии ревью в задаче (единый контекст) + ## Telegram Bridge (MVP) -- Один бот, подключается по WS к Tracker +- Один бот, подключается по WS к Tracker как `client_type=bridge` - Дублирует сообщения из project chats в Telegram -- **Топики**: если в Telegram включены topics → бот пишет в топик с именем проекта -- Форматирование: `[Кодер] текст сообщения` +- **Топики**: если в Telegram включены topics → бот пишет в топик с именем проекта (каждый проект = отдельный топик) +- Форматирование: `👤 Eugene: текст` / `🤖 Кодер: текст` / `⚙️ Задача #42 → in_progress` +- **Telegram → Tracker**: сообщение из группы → `chat.send` с `sender_type=bridge` +- **Упоминания**: парсит `@slug` из Telegram → `mentions` в `chat.send` +- Системные события (task.created, task.updated) → уведомления в группу +- ⚠️ Ограничение Telegram: боты НЕ видят сообщения других ботов → один бот = bridge для всех ## Безопасность -- Агенту доступны определённые действия (allowed_paths, capabilities) -- Разные уровни доступа — TBD -- Rate limiting — TBD -- Audit log — TBD +- **Аутентификация**: токены (прописываются при регистрации агента). Каждый агент = уникальный токен. +- **Роли и 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 + +## Деплой + +- **Tracker + BFF + Web Client**: Docker Compose +- **Picogent**: systemd сервис (один процесс на агента) +- Автоматический restart при падении (systemd) +- CI/CD: Gitea Actions auto-deploy +- Агент-DevOps возможен для CI/CD задач ## На будущее -- **Web MCP Server** — отдельный пакет, любой LLM-клиент (Claude Code, Cursor) работает с трекером через MCP без Picogent -- **Multi-instance агентов** — scaling, несколько кодеров -- **Аналитика** — метрики, дашборды +- **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) - **OAuth / Authentik** — мульти-пользователь -- **Notification Bridge** — push-уведомления за пределами чата +- **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** — вся работа агента как поток событий для воспроизведения и восстановления состояния -## Референсы +## Конкурентный анализ (референсы) -- **MetaGPT** — промпты ролей (PM, Architect, Engineer, QA) -- **Claude Flow** — claims, swarm coordination -- **BMAD Method** — brainstorming workflows +| Система | Ключевые идеи | Что забираем | +|---------|---------------|-------------| +| **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 на файлы — не нужен +- Бюджет в токенах — нет +- Приватность проектов — агент не трогает чужое