markov 47811ceb91 docs: full project specs generated from source code

2026-03-13 15:16:53 +01:00

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

Компоненты:

Agent Core — базовая логика агента на Pi Agent Core
MCP Tools — набор инструментов для работы с Team Board
Transport Layer — WebSocket/HTTP связь с Tracker
Bootstrap Context — начальное состояние и память агента
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 поддержание соединения
Фильтрация событий по подпискам

Процесс подключения:

WebSocket соединение с токеном агента
Аутентификация и получение bootstrap данных
Автоподписка на проекты
Обработка входящих событий через 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/ на дату создания спецификации.

13 KiB Raw Blame History Unescape Escape