Основные понятия

В CherryPi намеренно небольшой словарь. Одни и те же термины используются в дашборде, API и документации.

Agency

Центральное веб-приложение. Оно обслуживает дашборд, Connect API, tunnel hub, планировщик и прокси объектного хранилища. Это единственная часть, которую вы публикуете в интернет.

Agency владеет:

• людьми — пользователи, приглашения, сессии, personal access tokens;
• агентами — зарегистрированные воркеры и их владельцы;
• командами и проектами — контроль доступа;
• задачами — работа, промпты, история и артефакты;
• конфигурацией — провайдеры аутентификации, SMTP, хранилище, брендинг.

Агент

Долгоживущий процесс-воркер на машине, которая должна выполнять работу. У него нет HTTP-слушателя и локального входа. Он подключается исходящим соединением к agency по туннелю и отдаёт свой API только через него.

Агент:

• запускает один дочерний pi --mode rpc на каждую выполняющуюся задачу;
• хранит рабочее пространство каждой задачи на диске;
• обслуживает root PTY-терминалы;
• может показать браузеру уже запущенный X-дисплей;
• сообщает версию, версию протокола, здоровье и использование.

Агент тоже актор: им можно владеть, делиться с командой и задавать ему лимиты параллельных задач.

Туннель

Постоянное соединение между агентом и agency. Оно предпочитает двунаправленный Connect-поток поверх HTTP/2 и откатывается на WebSocket /api/tunnel/ws поверх HTTP/1.1. Именно fallback делает обычный TLS reverse proxy достаточным без cleartext HTTP/2.

Если туннель падает, агент переподключается с backoff. Запущенные задачи восстанавливаются, когда агент возвращается.

Проект

Группа задач со своим описанием, системным промптом и правилами доступа. Каждая задача принадлежит ровно одному проекту.

Доступ выдаётся командам (роль owner, member или viewer) или отдельным акторам как исключение. Пользователь или агент может запускать задачи только в том проекте, где у него есть роль.

Задача

Одна единица работы. У задачи есть:

• имя и промпт;
• проект и назначенный агент;
• состояние — draft, queued, running, input, settled, failed, completed или cancelled;
• транскрипт из сообщений пользователя и записей сессии Pi;
• вложения, ссылки и артефакты;
• опциональные теги, приоритет и ссылки на другие задачи.

Задача выполняется в workspace на агенте. Agency хранит не-header записи сессии Pi, поэтому задачу, перенесённую на другого агента, можно продолжить там из истории.

Промпт

Текст, который вы отправляете задаче, плюс системный промпт, собранный из версий organization, agent, project и agent × project. Agency фиксирует версии промптов на момент старта задачи, поэтому задача остаётся воспроизводимой после редактирования промпта.

Вложение и артефакт

Вложения — файлы, которые вы добавляете в сообщение или задачу: скриншоты, логи, документы. Они лежат в S3-совместимом бакете, а agency проксирует доступ.

Артефакты — файлы, которые агент публикует как результат задачи. Они появляются во вкладке Artifacts с именем, описанием и, если возможно, превью.

Сайт

Статический сайт, который задача публикует zip-архивом. Agency хранит архив, отдаёт его по /sites/<id> и добавляет вкладку Site рядом с чатом задачи. Сайт сохраняет исходную задачу и создателя, может отображаться agency-wide в боковой панели и может запросить у посетителя привязанный к сайту personal access token через модалку согласия agency. См. Сайты.

Команда

Группа акторов (пользователей и агентов). Команды — основная единица доступа: привяжите команду к проекту с ролью. Команды также могут владеть агентами и делают информацию о своём составе доступной участникам.

Personal access token

Креденшел pat_… для SDK, CLI и инструментов агента. Браузер использует HTTP-only cookie сессии. Токены можно ограничивать, ротировать и отзывать в Account → Personal access tokens.

Pi

Harness кодирующего агента, который выполняет фактическую работу с моделью. CherryPi не включает провайдера моделей: агент запускает pi, а Pi использует свою конфигурацию в $PI_CODING_AGENT_DIR (по умолчанию ~/.pi/agent). CherryPi добавляет промпт задачи, workspace, вложения и набор встроенных инструментов.

Использование

Учёт токенов и стоимости, который сообщает Pi и агрегирует agency. Использование привязывается к задаче, проекту и агенту и сохраняется при простое агента.