Plugin System

Плагин — это unitплатформы

Устанавливаешь один пакет — движок регистрирует CLI команды, REST роуты и страницу в Studio. Без ручных конфигов. Права объявлены в манифесте — видишь до установки.

terminal
$ kb marketplace install @kb-labs/review-entry
Resolving @kb-labs/review-entry@2.94.0
Installing via pnpm ...
CLI commands registered
kb review    kb review run    kb review:ci
REST routes mounted
POST /api/review    GET /api/review/runs
Studio page ready
/p/review
0+
сущностей маркетплейса
0
плагинов доступно
0
адаптеров доступно
0 день
типичная разработка плагина
task-create.tstypescript
import { defineCommand, type CLIInput, type PluginContextV3 } from '@kb-labs/sdk';
import { requireApiKey, createTask } from '@kb-labs/clickup-core';

export default defineCommand({
  id: 'clickup:task.create',

  handler: {
    // intent() — declare what the plugin will do before it does it
    async intent(_ctx, input: CLIInput<TaskCreateFlags>) {
      const { list, name } = input.flags;
      return {
        summary: `Create task "${name}" in list ${list}`,
        operations: [{ type: 'create', resource: 'task' }],
      };
    },

    async execute(ctx: PluginContextV3, input: CLIInput<TaskCreateFlags>) {
      const { list, name, desc, status, json } = input.flags;

      // business logic — the only thing the plugin author writes
      const task = await createTask(requireApiKey(), list, {
        name,
        markdown_content: desc,
        status,
      });

      // ctx.ui — same code, different surface: CLI, REST, Studio
      if (json) {
        ctx.ui.json({ id: task.id, name: task.name, url: task.url });
      } else {
        ctx.ui.success('Task created', {
          sections: [{ items: [`id: ${task.id}`, `url: ${task.url}`] }],
        });
      }

      return { exitCode: 0, result: task };
    },
  },
});
SDK

Только бизнес-логика

Плагин общается с абстракциями — ctx.ui, useLLM(). Какой провайдер стоит за ними, как роутится запрос, куда идут логи — всё это платформа.

ctx.ui.success() работает одинаково из CLI, Workflow вызова.

SDK документация
@kb-labs/review-entry
CLI
kb review --stagedkb review run
REST
POST /api/reviewGET /api/review/runs
Studio
/p/reviewfull page
Как это работает

Один манифест — три поверхности

Плагин объявляет CLI команды, REST роуты и Studio страницу в одном файле — manifest.ts. При установке движок регистрирует всё автоматически.

Не нужно настраивать роутер, регистрировать команды или писать конфиг Studio. Поставил пакет — всё работает.

Плагины изолированы: каждый получает только те ресурсы платформы, которые объявил. Полная OS-изоляция — с container/remote режимом исполнения.

Как работает

Жизненный цикл плагина

После установки платформа записывает пакет в .kb/marketplace.lock с SHA-256 чексуммой. При каждом старте discovery проверяет целостность и загружает манифест.

Из манифеста извлекаются entity kinds — семь типов сущностей: CLI команды, REST роуты, Studio страницы, workflow handlers, webhook handlers, WebSocket каналы, cron расписания. Один плагин может регистрировать любое их сочетание.

При вызове команды движок выбирает execution backend. In-process — дефолт, минимальный overhead. Subprocess и worker-pool — изоляция процесса. Remote — полная OS-изоляция на отдельной машине.

manifest.tsединый источник правды
schema: 'kb.plugin/3'permissionscapabilities
Installkb marketplace install @scope/plugin
pnpm install.kb/marketplace.locksha256 integrity
Discoverчитает lock при каждом старте
enabled checkintegrity verifyloadManifest()
RegisterextractEntityKinds() — 7 типов сущностей
cli-commandrest-routestudio-pageworkflowwebhookws-channelcron
Executebackend выбирается per-invocation
in-processsubprocessworker-poolremote · OS isolate
Permissions

Видишь права до установки

Каждый плагин декларирует в манифесте что ему нужно: читать git, вызывать LLM, писать в fs. Ты видишь это ещё до install.

Это не жёсткая гарантия — при in-process исполнении платформа проверяет запрошенные права, но полная OS-изоляция требует container или remote режима.

Как permissions в мобильных приложениях: ты знаешь что плагин хочет и принимаешь осознанное решение.

manifest.tstypescript
import { combinePermissions, kbPlatformPreset } from '@kb-labs/sdk';

export default {
  schema:      'kb.plugin/3',
  id:          '@kb-labs/review',
  version:     '2.94.0',
  permissions: combinePermissions()
    .with(kbPlatformPreset)
    .allow('git.read')     // can read git history
    .allow('llm.call')     // can call LLM
    .deny('fs.write')      // no filesystem writes
    .deny('shell.exec')    // no shell access
    .build(),
  cli: {
    commands: [
      { id: 'review',    handler: './commands/run.js#default' },
      { id: 'review:ci', handler: './commands/ci.js#default'  },
    ],
  },
} as const;
terminalbash
# 1. scaffold
kb scaffold run plugin my-plugin

# 2. build
pnpm build

# 3. publish to KB Labs Registry
kb marketplace publish

# --- anyone can now install ---
kb marketplace install @you/my-plugin

# or share privately
kb marketplace share --with user123
kb marketplace share --link
Экосистема

Создай и опубликуй свой плагин

1
Скаффолд
Запустите kb-create plugin my-plugin. Манифест, хэндлеры и tsconfig готовы.
2
Реализация
Напишите типизированные хэндлеры. Импорт только из @kb-labs/sdk.
3
Регистрация
Установите локально или опубликуйте в маркетплейс. kb plugins list покажет сразу.
Попробуйте прямо сейчас

Первый плагин — за 5 минут.

Установите KB Labs, запустите scaffold, добавьте логику. CLI, REST API и Studio готовы автоматически.

Plugin System — KB Labs