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

От нуля до работающего плагина примерно за 30 минут.

Это руководство проведёт вас от пустой директории до подписанного плагина, работающего в sandbox-тенанте.

Что вы соберёте

Минимальный плагин, который:

Регистрирует один MCP-инструмент (hello_learner) в Plugin Gateway.
Потребляет enrollment.completed.v1 из Kafka.
Логирует использование LLM-токенов в телеметрию.

Что нужно заранее

docker и pnpm (или uv для Python-плагинов)
Аккаунт publisher с Cosign signing key
adapstory CLI: curl -fsSL https://adapstory.com/cli/install | sh

Если у вас ещё нет publisher-аккаунта, запросите его в #adapstory-plugins или через админ-портал. Получите signing key и sandbox-тенант для тестов.

Шаги

Scaffold проекта

adapstory plugin new hello-learner --runtime python
cd hello-learner

Получите:

hello-learner/
├── plugin.yaml          # манифест
├── pyproject.toml       # uv-managed зависимости
├── src/
│   └── hello_learner/
│       ├── __init__.py
│       ├── main.py      # FastAPI app
│       └── tools.py     # @mcp_tool handlers
├── tests/
└── Dockerfile

Декларируйте манифест

Откройте plugin.yaml и заполните точки интеграции:

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 with an AI-generated message.
      endpoint: /mcp/hello
      schema: mcp/hello-learner.schema.json
  events:
    consumes: [enrollment.completed.v1]
  llm:
    gatewayBudget: 100000
    defaultModel: claude-haiku-4-5-20251001
  guardrails:
    content: [no-pii, education-safe]

Полный справочник полей здесь.

Реализуйте MCP-инструмент

# src/hello_learner/tools.py
from adapstory_plugin_sdk import mcp_tool, LlmGateway

@mcp_tool(name="hello_learner")
async def hello_learner(
    learner_name: str,
    gateway: LlmGateway,
) -> dict:
    """Возвращает дружелюбное, education-safe приветствие."""
    response = await gateway.chat(
        model="claude-haiku-4-5-20251001",
        messages=[
            {"role": "system", "content": "You are an encouraging tutor."},
            {"role": "user",   "content": f"Say hi to {learner_name} in one short sentence."},
        ],
    )
    return {"message": response.text}

// src/tools.ts
import { mcpTool, type LlmGateway } from '@adapstory/plugin-sdk';

export const helloLearner = mcpTool({
  name: 'hello_learner',
  async handler({ learnerName }: { learnerName: string }, ctx: { gateway: LlmGateway }) {
    const response = await ctx.gateway.chat({
      model: 'claude-haiku-4-5-20251001',
      messages: [
        { role: 'system', content: 'You are an encouraging tutor.' },
        { role: 'user',   content: `Say hi to ${learnerName} in one short sentence.` },
      ],
    });
    return { message: response.text };
  },
});

SDK инжектирует LlmGateway — никогда не вызывайте провайдеров моделей напрямую.

Запустите локально

adapstory plugin dev

Это поднимает dockerised sandbox с mock Plugin Gateway и mock тенантом. Вызовите инструмент:

curl -XPOST http://localhost:8787/mcp/invoke \
  -H 'content-type: application/json' \
  -d '{"tool":"hello_learner","args":{"learnerName":"Alex"}}'

Увидите приветствие — и строку телеметрии с фиктивным расходом токенов.

Подпишите и опубликуйте

adapstory plugin build              # → registry.adapstory.com/your-org/hello-learner:0.1.0
adapstory plugin sign               # → Cosign-подпись + SBOM + SLSA provenance
adapstory plugin publish            # → BC-02 забирает, верифицирует подпись, делает установочным

Последний шаг fail-closed: неподписанные образы отклоняются на admission.

Установите в тенант

adapstory plugin install hello-learner --tenant sandbox-tenant-1

Мониторьте статус до ACTIVE:

adapstory plugin status hello-learner --tenant sandbox-tenant-1 --watch

Что у вас теперь есть

Подписанный образ плагина в реестре.
Активная установка в sandbox-тенанте, видимая в ArgoCD под plugin-sandbox-tenant-1-hello-learner.
Телеметрия: трейсы в Tempo, CPU-профиль в Pyroscope, логи в Loki.

Дальше

Справочник манифеста — каждое поле и его смысл.
MCP-инструменты — подробно про схемы, стриминг и cancellation.
Жизненный цикл — как работают upgrade'ы, откаты и multi-tenant раскатка.
Observability — сделайте плагин отлаживаемым в проде.

Quickstart по плагину