Справочник

Манифест команды

Команда агентов как один JSON-документ cradle.team/v1: экспорт, импорт с dry-run, пакеты скиллов и политики по id@version.

Команда агентов описывается одним JSON-документом — манифестом cradle.team/v1. Манифест — источник правды о структуре команды: канвас в консоли его отрисовывает, cradle-server его экспортирует и импортирует, git его хранит. Скиллы и политики приезжают отдельными пакетами, манифест ссылается на них по id@version.

Схема: /schemas/team.v1.json (JSON Schema draft 2020-12). Этой страницы и схемы достаточно, чтобы написать валидный манифест — руками или моделью.

Форма команды

Ровно три уровня, без условий и циклов (маршрутизация остаётся за triage и лидами):

  • captain — один, принимает входящее и распределяет (роль triage);
  • checker — один, хранится в структуре команды (как агент в версии 0.9.2 не вызывается); onReject в v1 только return-to-lead;
  • leads — 1–5 лидов, у каждого members — 0–5 исполнителей;
  • shared — 0–5 общих исполнителей: любой лид может поручить им задачу, напрямую сообщения они не получают.

Неизвестное поле — ошибка валидации (additionalProperties: false), чтобы опечатка не прошла молча.

Верхний уровень

ПолеПравило
schemaОбязательно, строго cradle.team/v1
nameSlug команды [a-z0-9-]{1,64}, уникален на колыбели
titleНазвание, 1–120 символов
descriptionДо 2000 символов, необязательно
captain, checkerПо одному агенту (поля ниже)
leads1–5 агентов-лидов с members, sources, triggers
shared0–5 агентов с triggers
requiresВнешние зависимости по именам: channels, mcpServers, knowledgeBases, ontologies. Никаких токенов и адресов

Поля агента

ПолеПравило
idSlug, уникален в манифесте. Стабильный ключ агента: при повторном импорте агент с тем же id обновляется на месте
titleНазвание, 1–120 символов
badge1–3 символа для канваса, необязательно (в v1 не хранится)
promptОбязательно. Системный промпт, 1–32 000 символов
categorycoding · business · marketing · seo · general · other; по умолчанию general
modelАлиас модели (идентификатор модели в каталоге колыбели). Нет поля — модель даёт посадка по requirement
requirementgeneral · coding · reasoning; по умолчанию general
temperature0–1.5, по умолчанию 0.7
tagsТеги маршрутизации из справочника (faq, escalation, …). Неизвестный тег создаётся
skillsПакеты скиллов id@semver. Отсутствующий пакет блокирует импорт
policiesПолитики id@semver. Отсутствующая блокирует импорт
toolsВстроенные инструменты: web.search, web.fetch, doc.read, doc.create, tts.speak, image.generate. Неизвестный блокирует
knowledgeBasesИмена баз знаний команды. Отсутствующие не блокируют: агент помечается needsBinding
mcpServersИмена MCP-серверов колыбели. То же
groundingoff · soft · strict; по умолчанию soft. Политика со strict побеждает
enabledПо умолчанию true
executionТолько у исполнителя (members лида и shared): { "kind": "external", "repository": "owner/name", "baseBranch": "main" }. Задача уходит внешнему кодовому агенту (workflow GitHub Actions), модель колыбели для него не вызывается. Репозиторий должен быть в списке репозиториев команды, иначе при импорте будет предупреждение repository_not_allowed. Нет поля — исполнитель работает на модели колыбели. Подробно — Внешний кодовый агент
sourcesТолько у лида: из каких источников он принимает сообщения — telegram, telegram:private, telegram:group, widget, api, mcp-server. Нет поля — любой; [] — только по задачам и триггерам
triggersУ лида и общего исполнителя, до 5: { id, cron (5 полей), tz (IANA, по умолчанию UTC), instruction }. В v1 хранятся и показываются, по расписанию пока не запускаются

Полный пример

{
  "schema": "cradle.team/v1",
  "name": "stoic-sage",
  "title": "Стоик",
  "description": "Собеседник-стоик для Telegram-группы: беседа, редактура подборок, библиотека и поиск в общем пуле",
  "captain": {
    "id": "triage",
    "title": "Triage",
    "prompt": "Ты — диспетчер. Определяешь, кому адресовано сообщение: беседа — Собеседнику, запрос на подборку или текст — Редактору.",
    "requirement": "general",
    "tags": ["greeting", "faq", "escalation"]
  },
  "checker": {
    "id": "checker",
    "title": "Checker",
    "prompt": "Ты — Checker. Проверяешь, что цитаты приписаны верному автору и тексту, а совет не выдаёт себя за медицинскую или юридическую помощь.",
    "requirement": "reasoning",
    "grounding": "strict",
    "onReject": "return-to-lead"
  },
  "leads": [
    {
      "id": "companion",
      "title": "Собеседник",
      "badge": "СБ",
      "prompt": "Ты — собеседник-стоик в духе Марка Аврелия, Эпиктета и Сенеки. Отвечаешь коротко, задаёшь встречный вопрос, опираешься на первоисточники из библиотеки. Для цитат проси библиотекаря, для фактов о мире — поисковика.",
      "requirement": "general",
      "temperature": 0.8,
      "tags": ["tone-support"],
      "knowledgeBases": ["stoic-canon"],
      "sources": ["telegram:group"]
    },
    {
      "id": "editor",
      "title": "Редактор",
      "badge": "РД",
      "prompt": "Ты — редактор подборок. Собираешь тематические подборки цитат с комментарием, готовишь утренний текст и недельный обзор обсуждений группы. Входящие сообщения не принимаешь — работаешь по расписанию и задачам.",
      "requirement": "reasoning",
      "temperature": 0.5,
      "tags": ["copy"],
      "knowledgeBases": ["stoic-canon", "stoic-community"],
      "sources": [],
      "triggers": [
        { "id": "morning", "cron": "0 7 * * *", "tz": "Europe/Moscow", "instruction": "Подготовь утреннюю цитату с комментарием на 3–4 предложения." },
        { "id": "weekly", "cron": "0 18 * * 0", "tz": "Europe/Moscow", "instruction": "Собери обзор обсуждений недели из базы stoic-community: темы, лучшие вопросы, цитаты, которые помогли." }
      ]
    }
  ],
  "shared": [
    {
      "id": "librarian",
      "title": "Библиотекарь",
      "badge": "Б",
      "prompt": "Ты — библиотекарь. По запросу находишь точные цитаты в первоисточниках и возвращаешь их с указанием автора, труда, книги и фрагмента. Не пересказываешь — цитируешь.",
      "requirement": "general",
      "temperature": 0.1,
      "grounding": "strict",
      "knowledgeBases": ["stoic-canon", "stoic-community"]
    },
    {
      "id": "searcher",
      "title": "Поисковик",
      "badge": "П",
      "prompt": "Ты — поисковик. По запросу находишь факты в сети и возвращаешь краткую выжимку со ссылками на источники.",
      "requirement": "general",
      "temperature": 0.2,
      "tools": ["web.search", "web.fetch"]
    },
    {
      "id": "observer",
      "title": "Наблюдатель",
      "badge": "Н",
      "prompt": "Ты — наблюдатель группы. Ночью просматриваешь обсуждения дня и формируешь краткий конспект: темы, вопросы без ответа, повторяющиеся трудности.",
      "requirement": "general",
      "temperature": 0.3,
      "knowledgeBases": ["stoic-community"],
      "triggers": [
        { "id": "nightly-digest", "cron": "30 2 * * *", "tz": "Europe/Moscow", "instruction": "Составь конспект обсуждений за прошедшие сутки для базы stoic-community." }
      ]
    }
  ],
  "requires": {
    "channels": ["telegram"],
    "knowledgeBases": ["stoic-canon", "stoic-community"]
  }
}

Ещё примеры — папка examples/team-manifest: манифест с одним лидом, ссылками на скилл и политики; две политики; пакет скилла.

Экспорт и импорт

МетодПутьScopeЧто
GET/api/v1/teams/:slug/manifestteams:readКанонический JSON, заголовок X-Manifest-Sha256
POST/api/v1/teams/manifest/dry-runteams:readПроверка и план без записи
POST/api/v1/teams/manifest?mode=create|replaceagents:write (создание новой команды — admin:*)Применить. 409 — slug занят в create, 422 — ошибки схемы или блокирующие пропуски

Ответ dry-run:

{
  "valid": true,
  "errors": [],
  "plan": { "action": "create", "team": { "slug": "stoic-sage", "exists": false },
            "agents": { "create": ["triage", "checker", "companion", "editor", "librarian", "searcher", "observer"], "update": [], "remove": [] } },
  "missing": { "skills": [], "policies": [], "models": [], "tools": [],
               "channels": ["telegram"], "mcpServers": [], "knowledgeBases": ["stoic-canon", "stoic-community"], "ontologies": [] },
  "warnings": [{ "path": "/leads/1/triggers", "code": "trigger_inactive" }],
  "blocking": false
}

Блокируют skills, policies, models, tools. Остальное не блокирует: команда создаётся, агенты с непривязанными зависимостями помечаются на канвасе.

replace применяется одной транзакцией: агент с тем же id обновляется на месте и сохраняет историю, новые создаются, остальные удаляются. Ошибка посередине оставляет команду прежней. Экспорт → импорт в чистую команду → экспорт дают побайтно одинаковый JSON (ключи в порядке схемы, значения по умолчанию выписаны явно, без внутренних id и дат).

В консоли: экран команды → Экспорт / Импорт (проверка по схеме в браузере, план, загрузка недостающих пакетов прямо из плана, Применить).

Манифест через MCP

Ассистент, подключённый к MCP-эндпоинту колыбели (POST /mcp, ключ колыбели в заголовке Authorization или X-Api-Key), собирает и применяет манифест без консоли: cradle_catalog (что есть на колыбели), cradle_team_plan (проверка и план, ничего не пишет), cradle_team_apply (создать или заменить, только после согласия человека с планом) и cradle_team_export. Граница та же, что у остальных операций с командами: ключ команды видит свою команду, человек — команды своей организации, созданная им команда попадает в неё.

Пакеты скиллов

Скилл — папка с SKILL.md (frontmatter name, description, version — semver, необязательно tags) и любыми файлами. Тело SKILL.md дописывается в системный промпт агента, который ссылается на name@version.

---
name: grounding-check
description: Проверка, что каждое утверждение ответа подтверждено фрагментом источника
version: 1.0.0
tags: [compliance]
---

# Grounding check

Когда получаешь результат на проверку:

1. Разбей ответ на утверждения — по одному факту на строку.
2. Для каждого утверждения найди подтверждающий фрагмент в источниках `[n]`. Нет фрагмента — утверждение «не подтверждено».
3. Числа, даты, имена и коды сверяй посимвольно.
4. Вердикт: `accept`, если неподтверждённых утверждений нет; иначе `reject` со списком неподтверждённых утверждений и тем, что нужно исправить.

Не исправляй ответ сам — верни его лиду.

Экспорт — zip папки <id>-<version>.skill.zip: GET /api/v1/skills/:id/:version/export. Импорт — POST /api/v1/skills/import (multipart/form-data, поле file). Ограничения: ≤ 10 МБ, без симлинков, без абсолютных путей и ... Повтор той же версии с другим содержимым — 409.

Политики

Политика — документ cradle.policy/v1 (схема /schemas/policy.v1.json):

{
  "schema": "cradle.policy/v1",
  "id": "strict-grounding",
  "version": "1.0.0",
  "title": "Строгое заземление",
  "description": "Каждое утверждение подтверждено источником; инструменты не используются.",
  "grounding": "strict",
  "tools": { "allow": [] }
}

grounding перекрывает режим агента (строже побеждает), tools.allow только сужает инструменты, risk.holdOn в v1 хранится и показывается. GET /api/v1/policies/:id/:version/export, POST /api/v1/policies/import (JSON).