Документация Adapstory

Плагин описывается одним plugin.yaml. Эта страница перечисляет каждое поле. Обязательные помечены R.

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

apiVersion: adapstory.com/v1        # R — версия схемы
kind: Plugin                        # R — всегда Plugin
metadata: { ... }                   # R
spec:     { ... }                   # R

`metadata`

Поле	Тип	Обязат.	Заметки
`name`	string	R	kebab-case, глобально уникальное в пределах publisher
`version`	semver	R	Строгий SemVer 2.0. Никаких `latest`
`publisher`	string	R	Совпадает со slug вашего publisher-аккаунта
`displayName`	string		Имя в админке (fallback на `name`)
`description`	string		Короткое резюме, до 140 символов
`tags`	string[]		Для поиска в каталоге плагинов

`spec.runtime`

Контролирует, как BC-19 планирует ваш workload.

spec:
  runtime:
    image: registry.adapstory.com/your-org/hello-learner:0.1.0   # R
    imagePullSecret: your-org-pull                               # optional
    resources:
      requests: { cpu: 100m, memory: 256Mi }                     # R
      limits:   { cpu: 500m, memory: 512Mi }                     # R
    replicas:
      min: 1
      max: 3
      targetCPUUtilization: 70
    startupProbe:
      path: /health
      port: 8080
      periodSeconds: 5
      failureThreshold: 12

image обязан быть pinned по тегу. Admission-контроллер отклоняет :latest и любые mutable-паттерны тегов.

`spec.mcpTools`

Каждый элемент регистрирует MCP-инструмент в BC-01.

spec:
  mcpTools:
    - name: hello_learner                # R — kebab_case
      description: One-line purpose.     # R — LLM читают это, решая когда вызвать
      endpoint: /mcp/hello               # R — путь в вашем контейнере (порт из startupProbe)
      schema: mcp/hello-learner.schema.json   # R — JSON-Schema аргументов
      streaming: false                   # optional, default false
      timeout: 10s                       # optional, default 15s
      rateLimit:
        perTenant: 60/minute
        perUser:   10/minute

JSON-Schema аргументов должна быть JSON-Schema draft 2020-12. Держите её компактной — LLM токенизируют схему на каждом вызове.

`spec.events`

Интеграция с Kafka. События в формате CloudEvents 1.0.

spec:
  events:
    consumes:
      - enrollment.completed.v1
      - course.published.v1
    produces:
      - course.recommended.v1
    dlqStrategy: retry-5-then-dlq        # default

Ваш сервис подписывается на топики consumes в consumer group plugin.<name>.<tenant>. At-least-once delivery — будьте идемпотентны.

`spec.dataModels`

Расширения схемы обрабатывает BC-15.

spec:
  dataModels:
    extends:
      - name: bc15.course
        attributes:
          - name: recommender_score
            type: float
            range: [0.0, 1.0]
      - name: bc15.enrollment
        attributes:
          - name: nudge_last_sent_at
            type: timestamp

Правила:

Только additive. Нельзя удалить атрибут, который декларировал другой плагин (или ядро).
Non-nullable атрибуты требуют default.
Удаление атрибута между версиями требует двухшаговой миграции.

`spec.llm`

Настройки LLM Gateway.

spec:
  llm:
    gatewayBudget: 500000                # R — токенов/день на тенант
    defaultModel: claude-sonnet-4-6      # R — alias модели по умолчанию
    allowedModels:                       # optional — whitelist; default все tenant-enabled
      - claude-sonnet-4-6
      - claude-haiku-4-5-20251001
    maxCostUsdPerCall: 0.50              # optional — circuit breaker
    guardrails:
      content: [no-pii, education-safe]
      prompt-injection: strict
      output-filter: profanity-mild
    caching:
      enabled: true
      ttlSeconds: 3600

`spec.secrets`

Секреты резолвятся через External Secrets Operator.

spec:
  secrets:
    - name: STRIPE_API_KEY
      vaultPath: adapstory/plugins/hello-learner/{tenant}/stripe
      key: api_key

{tenant} подставляется runtime. Секрет приходит в контейнер как env var.

`spec.permissions`

Scopes, которые плагин может запросить на install-time. Админ тенанта должен выдать каждый.

spec:
  permissions:
    - read:learners
    - write:courses
    - call:bc-15.migrate

Недекларированные scopes → отказ, даже если ваш код каким-то образом получил токен.

Минимальный валидный пример

apiVersion: adapstory.com/v1
kind: Plugin
metadata:
  name: hello-learner
  version: 0.1.0
  publisher: your-org
spec:
  runtime:
    image: registry.adapstory.com/your-org/hello-learner:0.1.0
    resources:
      requests: { cpu: 100m, memory: 256Mi }
      limits:   { cpu: 500m, memory: 512Mi }
  mcpTools:
    - name: hello_learner
      description: Greet a learner by name.
      endpoint: /mcp/hello
      schema: mcp/hello-learner.schema.json
  llm:
    gatewayBudget: 50000
    defaultModel: claude-haiku-4-5-20251001

JSON Schema

Полная схема опубликована по адресу https://docs.adapstory.com/schemas/plugin.v1.json — подключите к IDE для автокомплита и валидации.

Далее: MCP-инструменты.

Справочник манифеста