446 lines
13 KiB
Markdown
446 lines
13 KiB
Markdown
# Team Board — AI агентная система
|
||
|
||
## Назначение
|
||
|
||
**Picogent** — система для запуска ИИ-агентов, интегрированных с Team Board Tracker. Агенты могут автономно работать с задачами, участвовать в проектных чатах и использовать специальные MCP инструменты для взаимодействия с системой.
|
||
|
||
**Основа:** Pi Agent Core v0.52.12
|
||
**Технологии:** TypeScript, Node.js, WebSocket
|
||
|
||
---
|
||
|
||
## Архитектура системы
|
||
|
||
```
|
||
AI Model (Claude/GPT) ↔ Pi Agent Core ↔ MCP Tools ↔ Tracker API/WebSocket
|
||
↓
|
||
Agent Bootstrap & Memory
|
||
```
|
||
|
||
### Компоненты:
|
||
|
||
1. **Agent Core** — базовая логика агента на Pi Agent Core
|
||
2. **MCP Tools** — набор инструментов для работы с Team Board
|
||
3. **Transport Layer** — WebSocket/HTTP связь с Tracker
|
||
4. **Bootstrap Context** — начальное состояние и память агента
|
||
5. **Memory System** — персистентная память сессий
|
||
|
||
---
|
||
|
||
## Конфигурация агента
|
||
|
||
### Файлы конфигурации:
|
||
|
||
#### `agent.json` — основная конфигурация:
|
||
```json
|
||
{
|
||
"name": "Coder Agent",
|
||
"slug": "coder",
|
||
"tracker_url": "http://localhost:8100",
|
||
"ws_url": "ws://localhost:8100/ws",
|
||
"token": "tb-agent-token-here",
|
||
"transport": "ws",
|
||
"listen_port": 3200,
|
||
"work_dir": "/workspace",
|
||
"capabilities": ["coding", "testing"],
|
||
"max_concurrent_tasks": 2,
|
||
"heartbeat_interval_sec": 30,
|
||
"allowed_paths": ["/workspace", "/tmp"],
|
||
"session_id": "550e8400-e29b-41d4-a716-446655440000"
|
||
}
|
||
```
|
||
|
||
#### `config.json` — LLM конфигурация (переопределяет agent.json):
|
||
```json
|
||
{
|
||
"model": "claude-3-5-sonnet-20241022",
|
||
"provider": "anthropic",
|
||
"api_key": "sk-ant-...",
|
||
"prompt": "Системный промпт агента...",
|
||
"max_concurrent_tasks": 3
|
||
}
|
||
```
|
||
|
||
### Environment переменные:
|
||
```bash
|
||
# Tracker подключение
|
||
TRACKER_URL=http://localhost:8100
|
||
AGENT_TOKEN=tb-agent-token
|
||
AGENT_WS_URL=ws://localhost:8100/ws
|
||
|
||
# LLM настройки
|
||
PICOGENT_MODEL=claude-3-5-sonnet-20241022
|
||
PICOGENT_PROVIDER=anthropic
|
||
ANTHROPIC_API_KEY=sk-ant-...
|
||
PICOGENT_API_KEY=sk-ant-...
|
||
|
||
# Рабочая среда
|
||
PICOGENT_WORK_DIR=/workspace
|
||
AGENT_TRANSPORT=ws
|
||
AGENT_PORT=3200
|
||
|
||
# Логи
|
||
LOG_LEVEL=info
|
||
```
|
||
|
||
---
|
||
|
||
## Режимы запуска
|
||
|
||
### Agent Mode (рекомендуемый):
|
||
```bash
|
||
# Директория агента (agent.json + config.json)
|
||
node dist/index.js ./agents/coder/
|
||
|
||
# Файл конфигурации
|
||
node dist/index.js ./agent.json
|
||
|
||
# Environment переменные
|
||
TRACKER_URL=... AGENT_TOKEN=... node dist/index.js
|
||
```
|
||
|
||
### WebSocket Server Mode:
|
||
```bash
|
||
# Общий режим сервера
|
||
node dist/index.js
|
||
```
|
||
|
||
**WebSocket Server** принимает подключения на порту 3100, **Agent Mode** подключается к Tracker как member.
|
||
|
||
---
|
||
|
||
## MCP Tools — Инструменты агента
|
||
|
||
**Файлы:** `src/tools/`
|
||
|
||
### Task Tools:
|
||
- **`list_tasks`** — список задач с фильтрами (project_id, status, assignee_id)
|
||
- **`get_task`** — детали задачи по UUID
|
||
- **`create_task`** — создание задачи в проекте
|
||
- **`update_task`** — обновление полей задачи
|
||
- **`take_task`** — взять задачу в работу (атомарно)
|
||
- **`reject_task`** — отклонить назначенную задачу с причиной
|
||
- **`watch_task`** — подписаться на уведомления по задаче
|
||
- **`unwatch_task`** — отписаться от уведомлений
|
||
|
||
### Step Tools (чеклисты):
|
||
- **`list_steps`** — этапы задачи
|
||
- **`create_step`** — создать этап
|
||
- **`update_step`** — обновить этап (название, статус выполнения)
|
||
- **`delete_step`** — удалить этап
|
||
|
||
### Message Tools:
|
||
- **`list_messages`** — сообщения чата/задачи
|
||
- **`send_message`** — отправить сообщение в чат проекта
|
||
- **`send_task_comment`** — комментарий к задаче
|
||
- **`upload_file`** — загрузить файл как вложение
|
||
|
||
### Project Tools:
|
||
- **`list_projects`** — список доступных проектов
|
||
- **`get_project`** — информация о проекте
|
||
- **`list_project_files`** — файлы проекта
|
||
- **`upload_project_file`** — загрузить файл в проект
|
||
- **`download_project_file`** — скачать файл проекта
|
||
|
||
### Member Tools:
|
||
- **`list_members`** — участники системы
|
||
- **`get_member`** — информация об участнике
|
||
- **`list_project_members`** — участники конкретного проекта
|
||
|
||
### File Tools:
|
||
- **`read_file`** — чтение файлов из файловой системы
|
||
- **`write_file`** — запись файлов (с проверкой allowed_paths)
|
||
- **`list_directory`** — содержимое директории
|
||
- **`file_exists`** — проверка существования файла
|
||
|
||
### Task Links (зависимости):
|
||
- **`create_task_link`** — создать зависимость между задачами
|
||
- **`list_task_links`** — зависимости задачи
|
||
|
||
---
|
||
|
||
## Bootstrap Context
|
||
|
||
Агент получает стартовую информацию при подключении к Tracker через WebSocket auth.ok:
|
||
|
||
```json
|
||
{
|
||
"member_id": "agent-uuid",
|
||
"slug": "coder",
|
||
"name": "Coder Agent",
|
||
"projects": [
|
||
{
|
||
"id": "project-uuid",
|
||
"slug": "team-board",
|
||
"name": "Team Board",
|
||
"chat_id": "chat-uuid"
|
||
}
|
||
],
|
||
"assigned_tasks": [
|
||
{
|
||
"id": "task-uuid",
|
||
"title": "Fix bug in login",
|
||
"status": "todo",
|
||
"project_id": "project-uuid"
|
||
}
|
||
],
|
||
"agent_config": {
|
||
"model": "claude-3-5-sonnet-20241022",
|
||
"provider": "anthropic",
|
||
"prompt": "Системный промпт...",
|
||
"chat_listen": "mentions",
|
||
"task_listen": "assigned",
|
||
"max_concurrent_tasks": 2,
|
||
"capabilities": ["coding", "testing"],
|
||
"labels": ["bug", "feature"]
|
||
},
|
||
"online": [
|
||
{"id": "member-uuid", "slug": "john"}
|
||
]
|
||
}
|
||
```
|
||
|
||
**Автоматические подписки:** агент подписывается на все доступные проекты
|
||
|
||
---
|
||
|
||
## Memory система
|
||
|
||
### Session ID:
|
||
```json
|
||
"session_id": "550e8400-e29b-41d4-a716-446655440000"
|
||
```
|
||
|
||
- Генерируется при первом запуске
|
||
- Сохраняется в `agent.json`
|
||
- Обеспечивает преемственность памяти между перезапусками
|
||
|
||
### Директории:
|
||
```
|
||
~/.picogent/sessions/
|
||
├── 550e8400-e29b-41d4-a716-446655440000/
|
||
│ ├── conversation.json # История диалогов
|
||
│ ├── memory.json # Ключевые факты
|
||
│ └── context.json # Рабочий контекст
|
||
```
|
||
|
||
### Рабочая директория:
|
||
- **`workDir`** — основная директория работы агента
|
||
- **`agentHome`** — домашняя директория агента (для config/logs)
|
||
- **`allowedPaths`** — ограничения доступа к файловой системе
|
||
|
||
---
|
||
|
||
## Transport уровни
|
||
|
||
### WebSocket Transport (рекомендуемый):
|
||
**Файл:** `src/transport/ws-client.ts`
|
||
|
||
**Особенности:**
|
||
- Реальное время получение событий
|
||
- Автоматическое переподключение
|
||
- Heartbeat поддержание соединения
|
||
- Фильтрация событий по подпискам
|
||
|
||
**Процесс подключения:**
|
||
1. WebSocket соединение с токеном агента
|
||
2. Аутентификация и получение bootstrap данных
|
||
3. Автоподписка на проекты
|
||
4. Обработка входящих событий через EventRouter
|
||
|
||
### HTTP Transport:
|
||
**Файл:** `src/transport/http.ts`
|
||
|
||
**Особенности:**
|
||
- HTTP сервер для получения webhook'ов
|
||
- Регистрация callback URL в Tracker
|
||
- Периодический heartbeat через HTTP
|
||
- Подходит для firewall окружений
|
||
|
||
---
|
||
|
||
## Event Router
|
||
|
||
**Файл:** `src/router.ts`
|
||
|
||
### Обработка событий:
|
||
- **`message.new`** — новые сообщения в чатах/задачах
|
||
- **`task.created`** — созданные задачи
|
||
- **`task.updated`** — изменения задач
|
||
- **`task.assigned`** — назначение задач
|
||
- **`config.updated`** — обновление конфигурации агента
|
||
|
||
### Фильтрация:
|
||
- По подпискам проектов
|
||
- По `chat_listen` режиму (all/mentions/none)
|
||
- По `task_listen` режиму (all/mentions/assigned/none)
|
||
- По типу участника (humans получают всё, агенты фильтруются)
|
||
|
||
---
|
||
|
||
## Безопасность
|
||
|
||
### Аутентификация:
|
||
- Bearer токен агента (tb-xxxxx формат)
|
||
- Проверка токена на каждое API обращение
|
||
- WebSocket аутентификация при подключении
|
||
|
||
### Файловая система:
|
||
```json
|
||
"allowed_paths": ["/workspace", "/tmp"]
|
||
```
|
||
|
||
**Ограничения:**
|
||
- Чтение/запись только в разрешённых директориях
|
||
- Валидация путей на каждую операцию
|
||
- Защита от path traversal атак
|
||
|
||
### Сетевые ограничения:
|
||
- Доступ только к Tracker API
|
||
- Валидация URLs в file operations
|
||
- Логирование всех внешних запросов
|
||
|
||
---
|
||
|
||
## Логирование
|
||
|
||
**Библиотека:** Pino
|
||
**Формат:** JSON structured logging
|
||
|
||
### Уровни логов:
|
||
```json
|
||
{
|
||
"level": "info",
|
||
"time": 1640995200000,
|
||
"msg": "Processing message",
|
||
"messageId": "msg-123",
|
||
"clientId": "agent-456",
|
||
"workDir": "/workspace",
|
||
"sessionId": "550e8400-..."
|
||
}
|
||
```
|
||
|
||
### Ключевые события:
|
||
- Agent startup с конфигурацией
|
||
- WebSocket подключение/отключение
|
||
- Обработка сообщений и вызовы tools
|
||
- Ошибки API и network issues
|
||
- Memory операции и session management
|
||
|
||
---
|
||
|
||
## Capabilities система
|
||
|
||
### Базовые capabilities:
|
||
- **`coding`** — разработка и рефакторинг кода
|
||
- **`testing`** — написание и запуск тестов
|
||
- **`debugging`** — анализ и исправление багов
|
||
- **`documentation`** — создание документации
|
||
- **`review`** — code review и анализ
|
||
|
||
### Label matching:
|
||
```json
|
||
{
|
||
"capabilities": ["coding", "testing"],
|
||
"labels": ["bug", "feature", "typescript"]
|
||
}
|
||
```
|
||
|
||
**Auto-assign логика:** если в проекте включён auto_assign, задачи с соответствующими лейблами автоматически назначаются на агентов с matching capabilities.
|
||
|
||
---
|
||
|
||
## Развёртывание
|
||
|
||
### Docker:
|
||
```dockerfile
|
||
FROM node:22-alpine
|
||
WORKDIR /app
|
||
COPY package*.json ./
|
||
RUN npm ci --only=production
|
||
COPY dist/ ./dist/
|
||
CMD ["node", "dist/index.js"]
|
||
```
|
||
|
||
### Systemd Service:
|
||
```ini
|
||
[Unit]
|
||
Description=Picogent Agent
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=agent
|
||
WorkingDirectory=/opt/picogent
|
||
Environment=NODE_ENV=production
|
||
ExecStart=/usr/bin/node dist/index.js ./agents/coder/
|
||
Restart=always
|
||
RestartSec=10
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
### Process Management:
|
||
```bash
|
||
# Development
|
||
npm run dev
|
||
|
||
# Production build
|
||
npm run build
|
||
npm start
|
||
|
||
# Agent mode
|
||
node dist/index.js ./agents/coder/
|
||
```
|
||
|
||
---
|
||
|
||
## Мониторинг и отладка
|
||
|
||
### Health Check:
|
||
- Heartbeat каждые 30 секунд в Tracker
|
||
- WebSocket connection status monitoring
|
||
- API response time tracking
|
||
|
||
### Debug режим:
|
||
```bash
|
||
LOG_LEVEL=debug node dist/index.js
|
||
```
|
||
|
||
### Metrics:
|
||
- Количество обработанных сообщений
|
||
- Время ответа AI модели
|
||
- Успешность выполнения tools
|
||
- Memory usage и session persistence
|
||
|
||
---
|
||
|
||
## Расширение системы
|
||
|
||
### Создание новых tools:
|
||
```typescript
|
||
export function createCustomTools(ctx: ToolContext): ToolDefinition[] {
|
||
return [{
|
||
name: 'custom_action',
|
||
description: 'Custom action description',
|
||
parameters: ActionParams,
|
||
async execute(id: string, params: any) {
|
||
// Implementation
|
||
return { content: [{ type: 'text', text: 'Result' }], details: {} };
|
||
}
|
||
}];
|
||
}
|
||
```
|
||
|
||
### Новые transport типы:
|
||
- Implement transport interface
|
||
- Register в router system
|
||
- Add configuration options
|
||
|
||
### Custom AI providers:
|
||
- Extend Pi Agent Core provider system
|
||
- Configure в `config.json`
|
||
- Test с existing MCP tools
|
||
|
||
Этот документ описывает AI агентную систему на основе исходного кода в `/root/projects/team-board/picogent/` на дату создания спецификации. |