161 lines
7.0 KiB
Markdown
161 lines
7.0 KiB
Markdown
# Брейншторм: Протокол Picogent ↔ Tracker
|
||
Дата: 2026-02-20
|
||
|
||
## Принцип
|
||
|
||
Два слоя, чётко разделены:
|
||
|
||
1. **WebSocket** — real-time: события (push от трекера) + сообщения чата
|
||
2. **REST (через MCP tools)** — все мутации: задачи, этапы, файлы, статусы
|
||
|
||
Агент (LLM) не знает про WS-протокол. Он вызывает MCP tools.
|
||
Router (picogent) получает WS-события и решает: показать агенту или обработать внутренне.
|
||
|
||
## WebSocket Protocol
|
||
|
||
### Инфраструктура (Agent ↔ Tracker)
|
||
|
||
```
|
||
Agent → Tracker:
|
||
{type: "auth", token: "...", agent: {name, slug, capabilities}}
|
||
{type: "heartbeat", status: "idle|busy", current_tasks: [...]}
|
||
{type: "ack", id: "event-uuid"}
|
||
|
||
Tracker → Agent:
|
||
{type: "auth.ok", agent_id: "uuid"}
|
||
{type: "auth.error", message: "..."}
|
||
```
|
||
|
||
### События (Tracker → Agent, push)
|
||
|
||
```
|
||
{type: "event", id: "uuid", event: "<event_type>", data: {...}}
|
||
```
|
||
|
||
| Событие | В промпт LLM? | Описание |
|
||
|---------|---------------|----------|
|
||
| task.assigned | ✅ Да | Тебе назначена задача → начать работу |
|
||
| task.taken | ❌ Нет | Кто-то взял задачу → убрать из доступных (internal) |
|
||
| task.status_changed | ⚠️ Иногда | Только если зависимость разблокировалась |
|
||
| task.comment_added | ✅ Если mention | Новый комментарий → ответить/исправить |
|
||
| chat.message | ✅ По режиму | listen:all → всё, listen:mentions → только с @mention |
|
||
| agent.status_changed | ❌ Нет | Internal state |
|
||
|
||
### Сообщения чата (Agent → Tracker, через WS)
|
||
|
||
```
|
||
Agent → Tracker:
|
||
{type: "chat.send", chat_id: "uuid", content: "текст", mentions: ["slug"]}
|
||
|
||
Tracker → Agent:
|
||
{type: "event", event: "chat.message", data: {chat_id, author_slug, content, mentions}}
|
||
```
|
||
|
||
## MCP Tools (Agent → Tracker REST API)
|
||
|
||
Все мутации — только REST. MCP tools вызывает LLM по своему усмотрению.
|
||
|
||
### Задачи
|
||
| Tool | Method | Endpoint | Описание |
|
||
|------|--------|----------|----------|
|
||
| get_task | GET | /tasks/{id} | Получить задачу |
|
||
| list_tasks | GET | /tasks?project_id=&status=&assignee= | Список с фильтрами |
|
||
| create_task | POST | /tasks | Создать задачу/подзадачу |
|
||
| update_task | PATCH | /tasks/{id} | Обновить поля (status, priority...) |
|
||
| take_task | POST | /tasks/{id}/take | Взять себе (атомарно) |
|
||
| reject_task | POST | /tasks/{id}/reject | Отклонить с причиной |
|
||
|
||
### Этапы (Steps)
|
||
| Tool | Method | Endpoint | Описание |
|
||
|------|--------|----------|----------|
|
||
| add_step | POST | /tasks/{id}/steps | Добавить этап |
|
||
| complete_step | PATCH | /tasks/{id}/steps/{index} | Отметить выполненным |
|
||
| list_steps | GET | /tasks/{id}/steps | Текущие этапы |
|
||
|
||
### Комментарии
|
||
| Tool | Method | Endpoint | Описание |
|
||
|------|--------|----------|----------|
|
||
| add_comment | POST | /tasks/{id}/comments | Комментарий (с mentions) |
|
||
| list_comments | GET | /tasks/{id}/comments | Прочитать комментарии |
|
||
|
||
### Чат (альтернатива WS, fallback)
|
||
| Tool | Method | Endpoint | Описание |
|
||
|------|--------|----------|----------|
|
||
| send_message | POST | /chats/{id}/messages | Отправить сообщение |
|
||
| read_messages | GET | /chats/{id}/messages?limit= | Прочитать историю |
|
||
|
||
### Файлы
|
||
| Tool | Method | Endpoint | Описание |
|
||
|------|--------|----------|----------|
|
||
| upload_file | POST | /tasks/{id}/files | Прикрепить файл |
|
||
| list_files | GET | /tasks/{id}/files | Список файлов |
|
||
|
||
## Prompt Guidelines (заметки для промпта агента)
|
||
|
||
```
|
||
## Работа с задачами
|
||
|
||
- Получил задачу → прочитай описание через get_task()
|
||
- Если задача сложная → разбей на этапы через add_step()
|
||
- Обновляй этапы по мере работы через complete_step()
|
||
- Если нужно декомпозировать → создай подзадачи через create_task(parent_id=...)
|
||
- Если не можешь выполнить → отклони через reject_task() с объяснением
|
||
- После завершения → комментарий через add_comment() + update_task(status="review")
|
||
|
||
## Коммуникация
|
||
|
||
- Вопрос другому агенту → send_message() в чат с @mention
|
||
- Пришло сообщение с @mention → ответь
|
||
- Системные уведомления (task.taken, status changes) обрабатываются автоматически
|
||
```
|
||
|
||
## Архитектура в Picogent
|
||
|
||
### Router (обработка WS-событий)
|
||
```
|
||
WS event → Router:
|
||
task.assigned → buildPrompt() → runAgent(prompt, mcp_tools)
|
||
chat.message → если mention/listen:all → runAgent(message, mcp_tools)
|
||
task.comment → если mention → runAgent(comment, mcp_tools)
|
||
task.taken → internal: убрать из available (НЕ в промпт)
|
||
task.status → internal: проверить зависимости (НЕ в промпт)
|
||
```
|
||
|
||
### MCP Tools (регистрация)
|
||
```
|
||
MCP Server → tools:
|
||
get_task, list_tasks, create_task, update_task, take_task, reject_task
|
||
add_step, complete_step, list_steps
|
||
add_comment, list_comments
|
||
send_message, read_messages
|
||
upload_file, list_files
|
||
```
|
||
|
||
Каждый tool = HTTP request к Tracker REST API с Bearer token.
|
||
|
||
## Идея: Web MCP Server (на будущее)
|
||
|
||
Отдельный MCP Server (HTTP transport) для Tracker REST API.
|
||
Позволяет **любому LLM-клиенту** (Claude Code CLI, Cursor, Windsurf, Cline, OpenClaw)
|
||
работать с трекером через MCP без WebSocket и без Picogent.
|
||
|
||
- Отдельный пакет: `team-board/mcp-server`
|
||
- Человек говорит LLM: "возьми задачу #42" → LLM вызывает MCP tool → REST
|
||
- Не автономный (нет push-событий), но полностью функциональный
|
||
- Использует тот же REST API что и Picogent
|
||
|
||
Статус: **идея, не реализуем сейчас.**
|
||
|
||
## Что менять
|
||
|
||
### В Tracker:
|
||
1. WS handler: auth/auth.ok/event dispatch/ack
|
||
2. REST API: steps CRUD, reject_task, take_task (atomic)
|
||
3. Event dispatch: при assign/take/comment → WS push
|
||
|
||
### В Picogent:
|
||
1. MCP tools provider (обёртка над TrackerClient REST)
|
||
2. Router: разделить "в промпт" vs "internal"
|
||
3. WS протокол: согласовать с трекером
|
||
4. Listen modes: all vs mentions-only (из конфига)
|