team-board/docs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2bab3cf60a
docs/specs/AGENTS.md

13 KiB
Raw Blame History

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 — основная конфигурация:

{
  "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):

{
  "model": "claude-3-5-sonnet-20241022",
  "provider": "anthropic", 
  "api_key": "sk-ant-...",
  "prompt": "Системный промпт агента...",
  "max_concurrent_tasks": 3
}

Environment переменные:

# 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 (рекомендуемый):

# Директория агента (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:

# Общий режим сервера
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:

{
  "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:

"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 аутентификация при подключении

Файловая система:

"allowed_paths": ["/workspace", "/tmp"]

Ограничения:

  • Чтение/запись только в разрешённых директориях
  • Валидация путей на каждую операцию
  • Защита от path traversal атак

Сетевые ограничения:

  • Доступ только к Tracker API
  • Валидация URLs в file operations
  • Логирование всех внешних запросов

Логирование

Библиотека: Pino
Формат: JSON structured logging

Уровни логов:

{
  "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:

{
  "capabilities": ["coding", "testing"],
  "labels": ["bug", "feature", "typescript"]
}

Auto-assign логика: если в проекте включён auto_assign, задачи с соответствующими лейблами автоматически назначаются на агентов с matching capabilities.

Развёртывание

Docker:

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
CMD ["node", "dist/index.js"]

Systemd Service:

[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:

# 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 режим:

LOG_LEVEL=debug node dist/index.js

Metrics:

  • Количество обработанных сообщений
  • Время ответа AI модели
  • Успешность выполнения tools
  • Memory usage и session persistence

Расширение системы

Создание новых tools:

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/ на дату создания спецификации.