Пакеты каталога¶

Справочник видов пакета каталога: как каждый вид отображается на API сервиса, который его хранит, в каком порядке виды применяются, что из них версионируется и выводится из оборота, как ядро помнит, каким пакетом поставлен объект. Страница для администратора инсталляции и тех, кто читает каталог через API. Как писать, тестировать и ставить пакет — в разделе Пакеты. Обоснование — TAI-ADR-0044, TAI-ADR-0062.

Формат объекта¶

Каждый файл пакета — один объект в общей обёртке, spec — ровно тело запроса API сервиса, который хранит объект, в camelCase и без поля идентичности:

apiVersion: taimen.ai/v1
kind: TaskType
key: document-review
spec:
  displayName: Document review
  fieldSchema: { ... }
  lifecycleSchema: { ... }

Правила ключей, манифест и переменные — в Анатомии пакета.

Виды и API¶

`kind`	Папка	Идентичность в API	Как применяется
`KnowledgePack`	`knowledge-packs/`	`name`	онтология памяти: регистрация версии `POST /api/v1/knowledge/packs`; другое содержимое при той же версии — ошибка. Включение для пространств работы — секция `knowledge` установки, `PUT /api/v1/workspaces/{id}/knowledge-packs`
`WorkspaceType`	`workspace-types/`	`key`	создать или `PATCH` (с `If-Match`) при расхождении; архивный тип пакет не восстановит — это ошибка
`Capability`	`capabilities/`	`name`	только создание; расхождение описания — предупреждение (API описание не меняет)
`Role`	`roles/`	`slug`	роли уровня tenant'а; создать или `PATCH`
`Skill`	`skills/`	`name` + `spec.version`	создать версию; расхождение в `protocol`, `sideEffects`, `riskLevel` или `contract` — ошибка «поднимите `spec.version`»; у опубликованной версии меняются только `description` и статус
`ArtifactType`	`artifact-types/`	`key`	новая неизменяемая версия, только если файл отличается от новейшей (см. ниже)
`TaskType`	`task-types/`	`key`	при расхождении с новейшей активной версией публикуется новая, остальные активные → `deprecated`. `acceptance` — критерии приёмки по умолчанию у всех задач типа (Приёмка типа)
`Agent`	`agents/`	`key`	сначала `POST /api/v1/agents:validate`; если не меняются ни ревизия, ни желаемое состояние — «без изменений», иначе `POST /api/v1/agents` (см. ниже)
`ProjectTemplate`	`project-templates/`	`key`	так же, как `TaskType`
`Calendar`	`calendars/`	`key`	производственный календарь; применяется только планом ядра (см. ниже)
`Process`	`processes/`	`key` + `spec.version`	процесс; применяется только планом ядра (см. ниже)
`WorkRule`	`rules/`	`key`	правило вывода работы (Правила вывода работы): создать или `PATCH` (с `If-Match`) изменённых `description`, `trigger`, `condition`, `interpretation`, `action`, `identity`; `status` — через `:enable`/`:disable`. `workspaceId` задаётся только переменной установки и после создания не меняется. С `identity: {agent: <key>}` правило действует полномочиями этого агента
`NotificationRule`	`notification-rules/`	`key`	применяется к сервису уведомлений, а не к ядру; версию считает сервис по хэшу спецификации (см. ниже)

Удаления нет ни у одного вида.

Порядок применения¶

Единый план установки (см. Установку и выпуск) применяется секциями: catalog → core → knowledge → notification-rules → retire.

catalog — виды, которые установщик ставит ресурсами ядра, в порядке зависимостей: WorkspaceType → Capability → Role → Skill → ArtifactType → TaskType → Agent → ProjectTemplate → WorkRule. На что ссылаются, то создаётся раньше: artifactSchema типа задачи ссылается на типы артефактов, агент — на роли и типы задач, правило с identity — на агента.
core — пакет с процессами или календарями планирует и ставит само ядро (POST /api/v1/packages:plan, /packages:apply): у такого пакета это типы задач, агенты, календари, процессы и правила вывода работы. В секцию catalog они у него не входят.
knowledge — регистрация онтологий, затем включение наборов для пространств работы.
notification-rules — правила уведомлений ни на что в ядре не ссылаются, но исполняются сразу после применения, поэтому идут, когда ядро уже приведено.
retire — вывод из оборота.

Агент (`Agent`)¶

Файл в папке agents/ описывает агента целиком: личность и права, какую работу он берёт, вид исполнителя с параметрами и инструкциями, рабочую копию, скиллы и размещение (TAI-ADR-0052). Схема — $defs.agentSpec в sdk/package-sdk/schema/v1/object.schema.json, для автора — Агенты пакета.

check проверяет описание схемой формата и моделью AgentSpec ядра, требует, чтобы work.taskTypes были объявлены в пакете или его requires, и предупреждает о ролях из identity.roles, которых нет в пакетах (они должны уже быть в tenant'е);
топология — work.workspace, work.project — пишется переменной установки ${ИМЯ};
в описание не пишутся значения секретов — только имена в placement.secrets; ключи params, похожие на секрет, ядро отвергает 422 secret_material_rejected;
новая неизменяемая ревизия появляется, только если отличается хэш описания; state и placement.replicas меняют желаемое состояние без ревизии, и применение приводит к ним агента каждый раз;
права, которые описание выдаёт агенту, должны быть у применяющего: иначе 403 permission_escalation;
retire.Agent выводит агента из оборота: исполнитель останавливается, credential отзывается, история прогонов остаётся;
export выгружает spec текущей (или указанной --version) ревизии, а state и replicas — из желаемого состояния, опуская умолчания.

Разделы описания, жизненный цикл ревизий и события — в статье Агенты описанием, размещение на машинах — в Узлах и fleet.

Правило уведомления (`NotificationRule`)¶

Файл в папке notification-rules/ описывает, какое событие Control Plane становится уведомлением. Схема — $defs.notificationRuleSpec, полное описание — Правила уведомлений, для автора — Уведомления пакета.

Применяется к сервису уведомлений: адрес — переменная установки NOTIFICATION_SERVICE_URL, токен — NOTIFY_TOKEN (audience notification-service, scope notifications:admin) или обмен того же IAM credential, что у установщика.
plan вызывает :validate для всех правил установки: правило, которое сервис не примет, останавливает план целиком; в план попадают только изменившиеся.
Ключ on пишется в кавычках ("on":) — иначе YAML 1.1 прочтёт его как true.
retire.NotificationRule выводит правило из оборота, отправленные уведомления остаются. export --kind NotificationRule выгружает действующую версию из сервиса; --server не нужен, --version не поддерживается.

Тип артефакта (`ArtifactType`)¶

Тип артефакта — ключ, схема metadata, допустимые media types и потолок размера содержимого (модель — в Артефактах):

apiVersion: taimen.ai/v1
kind: ArtifactType
key: review-report
spec:
  displayName: Заключение проверки
  mediaTypes: [application/pdf]
  maxBytes: 10485760            # необязательно
  metadataSchema:
    type: object
    properties:
      reviewer: {type: string}

Поле `spec`	Умолчание в пакете	Как сравнивается с живой версией
`displayName`, `description`	`""`	всегда
`metadataSchema`	`{}`	всегда
`mediaTypes`	`["/"]`	всегда; перед сравнением приводятся к нижнему регистру, параметры и повторы отбрасываются — так их хранит ядро
`maxBytes`	не задан — ядро берёт `CP_ARTIFACT_MAX_BYTES` инсталляции на момент публикации	только если задан в файле

Версии неизменяемы, депрецирования у типов артефактов нет: старые версии не переводятся в deprecated, а retire для ArtifactType не поддерживается.
Артефакты всегда проверяются по новейшей версии: сужение mediaTypes или maxBytes сразу касается новых артефактов.
check проверяет metadataSchema, грамматику mediaTypes, положительный maxBytes, что каждый type в artifactSchema типа задачи объявлен в пакете или его requires и что mediaTypes слота сужает mediaTypes своего типа. Превышение CP_ARTIFACT_MAX_BYTES ловит ядро при применении (422 invalid_artifact_type).

Процессы и календари¶

Процесс (kind: Process) и производственный календарь (kind: Calendar) исполняет и проверяет само ядро (TAI-ADR-0054, CP-ADR-0074). Язык — в разделе Процессы, сценарии, replay и план ядра — в Сценариях и плане ядра, версии и живые дела — в Процессах в пакете.

<пакет>/
├── package.yaml               # renames — явные переименования объектов
├── processes/<ключ>.yaml      # kind: Process
├── calendars/<ключ>.yaml      # kind: Calendar
├── schemas/<имя>.schema.json  # схемы данных: data: {$ref: ../schemas/<имя>.schema.json}
├── tests/<имя>.test.yaml      # сценарии (schema/v1/test.schema.json)
└── .layout/<ключ>.json        # раскладка для визуального редактора; логики не несёт

Пакет с процессами или календарями ставится только планом ядра: секция core единого плана, запросы POST /api/v1/packages:plan и /packages:apply с файлами пакета (с tests/, без .layout/, с подставленными переменными).
data: {$ref: …} ссылается только на файл внутри пакета.
Если ядро не знает маршрутов пакетов процессов (404 или 501), check --server сообщает «ядро не поддерживает проверку процессов … — проверена только схема», а test --server и plan завершаются ошибкой.

Правка файлов: `package-sdk edit`¶

package-sdk edit выполняет мелкие правки процесса и пакета и меняет только затронутые строки: комментарии, порядок ключей, кавычки и flow/block-стиль остального файла остаются как были. Правка, которую не пропускает схема каталога или которая повторяет id элемента, не записывается.

Операция	Что делает
`add-step --in <стадия или шаг> --step <yaml> [--after/--before <id>]`	добавляет шаг в стадию или в блок `do` шага, ветви, таймера
`add-stage --stage <yaml> [--after/--before <id>]`	добавляет стадию
`add-decision-row --table <id> --row <yaml> [--index N]`	добавляет строку таблицы решений; столбцы проверяются по входам и выходам таблицы
`add-rule --table <id> --row <yaml>` или `add-rule --on-event <yaml>`	строка таблицы решений или реакция процесса на событие (`onEvent`)
`add-form-field --step <id> --name <поле> --schema <yaml> [--required] [--label]`	поле формы человеческого шага
`rename --file <процесс> --from <id> --to <id> [--no-migration]`	переименовывает элемент процесса, ссылки на него и тесты пакета; дописывает карту `migrations`
`rename --package <каталог> --kind <вид> --from <ключ> --to <ключ>`	переименовывает объект пакета и файл, дописывает `renames` в `package.yaml`; с историей план переносит `Process` и `Calendar`, у других видов — предупреждение `rename_not_planned` (Анатомия)
`set --path <путь> --value <yaml>`	записывает значение; в пути `[N]` — индекс, `[id]` — элемент списка по id

--json печатает результат или ошибку машиночитаемо, --dry-run — diff без записи. Язык пакетов — YAML 1.2: булевы значения только true/false.

Связь объектов с пакетом¶

Control Plane помнит, какой пакет поставил объект каталога: в ответах чтения у объекта есть поле package {key, version, installHash, installedAt}, а списки принимают фильтр ?package=<ключ пакета>. Связь принадлежит объекту (kind + ключ), а не версии: все версии типа задачи — один объект.

Процессы, календари и остальные виды пакета с процессами связывает само ядро при применении плана ядра.
Остальное установщик применяет своими маршрутами, а затем называет ядру, что поставил: один вызов POST /api/v1/packages:record на пакет, со всеми объектами пакета тех видов, которые ядро записывает, в том числе не изменившимися — при обновлении пакета их связь переходит на новую версию. Перечень видов установщик берёт из OpenAPI ядра (GET /openapi.json).
Агент, опубликованный из пакета, уходит в POST /api/v1/agents вместе с package {key, version}: новая ревизия запоминает пакет как свой источник.

installHash — sha256:<hex> содержимого файлов пакета: отсортированные относительные пути, на каждый файл — путь, длина и байты, как они лежат в git, до подстановки ${ПЕРЕМЕННЫХ}. Одинаковый пакет даёт одинаковый хэш на любой машине.

curl -s -H "Authorization: Bearer $CP_TOKEN" \
  "https://platform.example.com/api/v1/task-types?package=<пакет>" | jq '.items[] | {key, package}'

Так же фильтруются /artifact-types, /workspace-types, /project-templates, /roles, /capabilities, /skills, /rules и /agents. Запись связи требует права packages.plan и права записи каждого названного вида.

Выгрузка со стенда: `export`¶

Объект, который завели или поправили через API, выгружается в файл пакета:

package-sdk export --server https://platform.example.com \
  --kind TaskType --key document-review --package <каталог пакета>

export берёт новейшую активную версию (или ту, что указана в --version), отбрасывает пустые поля и значения по умолчанию, а у скилла с контрактом убирает поля, которые выводятся из контракта (inputSchema, outputSchema, protocol). Для Process и Calendar --env возвращает значения обратно ссылками ${ПЕРЕМЕННЫХ}, а --workspace учитывает поля консоли.

Что в пакет не входит¶

Топология: пространства работы, проекты, членство и назначения ролей людям. Principals и связки агентов в пакет тоже не пишутся: их выводит платформа из описания Agent.
Задачи-фикстуры.
Включение онтологий для деревьев workspace — секция knowledge установки; сама онтология — объект KnowledgePack пакета.
Вывод из оборота — список retire установки (см. Установку и выпуск).

Инициализация стенда¶

make bootstrap ставит каталог установки по умолчанию deploy/packages.yaml на шаге 5b (другой файл — флаг --packages); идентификаторы опубликованных объектов сохраняются в state bootstrap, в самих пакетах UUID не живут. Подробности — в статье Bootstrap.

Типичные проблемы¶

Сообщение	Причина	Что делать
`в опубликованной версии отличаются contract — контракт версии неизменяем`	правили контракт скилла без смены версии	поднять `spec.version` скилла
`artifactSchema.inputs '…': тип артефакта '…' не объявлен ни в пакете …, ни в его requires`	незамкнутая ссылка на тип артефакта	объявить `ArtifactType` или добавить пакет с ним в `requires`
`artifactSchema.outputs '…': mediaTypes [...] шире, чем у типа …`	выход расширяет, а не сужает media types типа	сузить `mediaTypes` выхода или расширить тип
`retire: вид ArtifactType не выводится из оборота`	`ArtifactType` в `retire`	убрать из списка
`retire: системный тип task вывести нельзя`	`task` в `retire`	убрать из списка
`422 non_canonical_value` при применении агента	дробное число в описании (например `resources.cpus`)	только целые
`403 permission_escalation`	у токена нет прав, которые описание выдаёт агенту	применять токеном с этими правами
`пакет …: объекты применены, но ядро не записало их связь с пакетом`	у токена нет `packages.plan` или права записи вида	выдать права и повторить применение: оно идемпотентно
`ядро не записывает связь объектов с пакетом (нет POST /api/v1/packages:record)`	Control Plane старше связей с пакетом	обновить Control Plane
`сервис уведомлений не принимает правило — …`	`:validate` вернул `422 invalid_notification_rule`	исправить правило по `details.errors`
`element_id_taken` от `package-sdk edit`	id элемента уже есть в процессе	выбрать другой id