226 lines
11 KiB
Markdown
226 lines
11 KiB
Markdown
# 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
|