From a0c8fea9f7ad7545b38544591467f3b753eaf76b Mon Sep 17 00:00:00 2001 From: Markov Date: Sat, 21 Feb 2026 10:19:45 +0100 Subject: [PATCH] =?UTF-8?q?ARCHITECTURE.md=20=E2=80=94=20unified=20project?= =?UTF-8?q?=20summary:=20components,=20tasks,=20chats,=20agents,=20protoco?= =?UTF-8?q?l?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ARCHITECTURE.md | 225 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..1dc49ac --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,225 @@ +# Team Board — Архитектура +Версия: 0.2 (драфт) +Дата: 2026-02-21 + +## Что это + +Платформа для совместной работы людей и AI-агентов над проектами. Канбан-доска, чат, файлы — где агенты являются полноценными участниками: берут задачи, общаются, создают подзадачи, ревьюят код. + +**Ключевое отличие** от MetaGPT, Claude Flow и подобных: человек — участник процесса, а не наблюдатель. Всё происходит на человеческом языке, в прозрачном чате. + +## Компоненты + +``` +┌─────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Web Client │────▶│ BFF │────▶│ Tracker │ +│ (Next.js) │ │ (FastAPI) │ │ (FastAPI) │ +└─────────────┘ └──────────────┘ └──────┬───────┘ + │ + ┌────────────────────────────────────────┤ + │ │ │ │ + ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ ┌──▼───┐ + │Picogent │ │Picogent │ │Telegram │ │ DB │ + │ Кодер │ │Архитект │ │ Bridge │ │Pg+Red│ + └─────────┘ └─────────┘ └─────────┘ └──────┘ +``` + +| Компонент | Стек | Порт | Описание | +|-----------|------|------|----------| +| **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 Core | — | AI-агент. Подключается к Tracker по WS. | +| **Telegram Bridge** | TBD | — | Дублирует чат проекта в Telegram (с топиками). | +| **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. + +### Особенности +- Агент может **отклонить** задачу (reject_task) с обоснованием +- **Автообнаружение блокеров**: зависимость застряла → пинг в чат +- Задача-наблюдатель: мониторинг, не исполнение +- Задача порождает подзадачи автоматически (агент создаёт через 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 +``` + +## Агенты (Picogent) + +### Конфигурация +Один бинарник, роль = конфиг (`agent.json`): +```json +{ + "name": "Кодер", + "slug": "coder", + "prompt": "Ты опытный разработчик...", + "model": "sonnet", + "capabilities": ["coding", "review"], + "listen_mode": "mentions", + "tracker_url": "http://localhost:8100", + "token": "tb-agent-xxx" +} +``` + +### Режимы прослушивания +- `listen: all` — слышит всё в чате (архитектор, PM) +- `listen: mentions` — только при @упоминании (кодер, тестер) + +### Одна сессия на агента +Всё в одном контексте: задачи, чат, ответы. Агент видит полную картину. + +### Онбординг +При подключении к проекту агент получает контекст: README, docs, архитектуру. + +### Memory +Per-agent + per-project. Агент дописывает findings после задач. + +### Что агент получает +Текстовые сообщения (максимум разговорной речи): +- `"Тебе назначена задача TB-42: Добавить авторизацию. Приоритет: high."` +- `"[чат проекта] @architect: Используй JWT для авторизации"` +- `"[комментарий к TB-42] @reviewer: В auth.py строка 42 не обработан expired token"` + +Агент сам решает что делать — вызывает MCP tools. + +### Label Matching +Задача имеет labels, агент поддерживает labels → автоматический matching для assign. + +## Протокол + +### Принцип +- **WebSocket** = real-time: события (push) + сообщения чата +- **REST (MCP tools)** = все мутации: задачи, этапы, файлы, статусы + +### WS Protocol + +**Инфраструктура:** +``` +Agent → Tracker: auth, heartbeat, ack +Tracker → Agent: auth.ok, auth.error, event +``` + +**События (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 | Файлы | + +### Router (в Picogent) +Тупой relay: WS event → текст → единственная сессия агента. Агент сам вызывает tools. + +## Файловое хранилище + +- Per-project директории +- Upload/download через REST API +- Связь с git repos (repo_urls[]) +- Версионирование файлов — TBD + +## Telegram Bridge (MVP) + +- Один бот, подключается по WS к Tracker +- Дублирует сообщения из project chats в Telegram +- **Топики**: если в Telegram включены topics → бот пишет в топик с именем проекта +- Форматирование: `[Кодер] текст сообщения` + +## Безопасность + +- Агенту доступны определённые действия (allowed_paths, capabilities) +- Разные уровни доступа — TBD +- Rate limiting — TBD +- Audit log — TBD + +## На будущее + +- **Web MCP Server** — отдельный пакет, любой LLM-клиент (Claude Code, Cursor) работает с трекером через MCP без Picogent +- **Multi-instance агентов** — scaling, несколько кодеров +- **Аналитика** — метрики, дашборды +- **OAuth / Authentik** — мульти-пользователь +- **Notification Bridge** — push-уведомления за пределами чата + +## Референсы + +- **MetaGPT** — промпты ролей (PM, Architect, Engineer, QA) +- **Claude Flow** — claims, swarm coordination +- **BMAD Method** — brainstorming workflows