36 lines
5.9 KiB
Markdown
36 lines
5.9 KiB
Markdown
# Каталог пакетов
|
||
|
||
Каталог — отдельный Go-сервис со своей PostgreSQL БД. Он владеет метаданными harness, plugin, skill и template. OCI-образы обслуживает registry, архивы — S3. Прямой доступ других сервисов к таблицам каталога запрещён; используется API.
|
||
|
||
## Пакет и версия
|
||
|
||
Package содержит id, tenantId, kind, name, description, visibility и ownerId. Имя уникально внутри tenant и kind. PackageVersion содержит version, manifest, artifactDigest, artifactRef, schemaDigest, createdAt и publisherId. Содержимое версии неизменяемо. Отдельная запись VersionPolicy хранит status, reason и changedAt: блокировка не переписывает исходный пакет.
|
||
|
||
Harness описывает поддерживаемый runtime, entrypoint и протокол ввода/вывода. Plugin описывает расширение и совместимость с harness. Skill содержит инструкции, ресурсы и при необходимости скрипты. Template объединяет точные или ограниченные версии зависимостей, инструкции и схему конфигурации. Skill с исполняемым кодом проходит те же проверки, что plugin.
|
||
|
||
## Публикация
|
||
|
||
Автор с ролью publisher создаёт draft, получает ограниченный upload grant и загружает артефакт. Для OCI он использует стандартный registry push. Publish проверяет размер, digest, формат манифеста, ссылки внутри архива, схему конфигурации, доступ к зависимостям и отсутствие циклов. Архив не может содержать выходящие за корень пути, абсолютные пути или небезопасные symlink.
|
||
|
||
Только после проверки артефакта транзакция публикует версию. Повтор Publish с тем же Idempotency-Key возвращает прежний результат. То же имя версии с другим digest даёт 409. Объекты без опубликованной версии очищаются после 24 часов — исходное значение, настраиваемое администратором.
|
||
|
||
## Resolve
|
||
|
||
Resolver принимает templateVersionId и профиль среды. Он строит ацикличный граф зависимостей, проверяет совместимость, выбирает конкретные версии и возвращает lock со всеми digest. Диапазоны версий разрешены на входе публикации шаблона, но не в ExecutionSpec. Конфликт версий возвращается с цепочками зависимостей; молчаливый выбор несовместимого пакета запрещён.
|
||
|
||
Доступ проверяется при resolve, выдаче download grant и назначении Attempt. Публичный шаблон не должен требовать недоступную аудитории приватную зависимость. Блокировка версии запрещает новые назначения; для уже работающих Attempt администратор выбирает policy cancel или allow_finish с аудитом.
|
||
|
||
## Обновления и хранение
|
||
|
||
Обновление шаблона не изменяет существующие AgentRevision. Пользователь получает preview изменений и ошибок валидации. Новая ревизия создаётся только после успешной проверки. В MVP миграция ручная через форму; исполняемые миграции автора не запускаются в браузере.
|
||
|
||
Deprecated версия доступна закреплённым агентам, но скрыта из стандартного выбора. Удаление referenced-версии возвращает 409. Физическая очистка допускается после retention запусков, проверки ссылок и grace period. Immutable артефакты адресуются по digest; signed URL не сохраняется в постоянном lock.
|
||
|
||
API: [catalog-api.md](api/catalog-api.md). Все диаграммы: [design.md](design.md).
|
||
|
||
## DSH и схемы ввода/вывода
|
||
|
||
Каталог хранит оригинальный DSH plugin artifact вместе с платформенным manifest envelope. Поля dshCompatibility фиксируют диапазон DSH, runtime, entry module и поддержанный профиль; tested versions и digest находятся в отчёте проверки каталога. Декларация автора не даёт badge совместимости. Плагины с зависимостью от API платформы явно объявляют endpoint и scopes; offline режим может не поддерживаться.
|
||
|
||
Template публикует inputSchemaRef и outputSchemaRef в том же архиве. Resolver включает архив по digest в lock, а API валидирует input до создания Run и output до success. UI схемы относятся к настройкам; дополнительные права не могут выдаваться значениями формы. См. [DSH foundation](dsh-foundation.md) и [плагины](plugins.md).
|