AiHummer
Беларуская▾
Увайсці
v1.0.x▾
v1.0.xstable
{ }Swagger
Маркетплэйс і плагіны/SDK плагінаў

SDK плагінаў

v1.0.x · абноўлена 2026-06-27

Плагін апісваецца адным manifest.json. Кантракт, які правярае маніфест падчас распрацоўкі, той самы, які платформа прымушае выконваць падчас усталёўкі, таму маніфест, што праходзіць validate, — гэта маніфест, які маркетплэйс прыме. CLI aihummer plugin ахоплівае ўвесь жыццёвы цыкл: ад каркаса да подпісу і публікацыі.

Адзін маніфест, адзін кантракт

Плагін мае роўна адну крыніцу праўды — свой manifest.json. Ён аб’яўляе від плагіна (kind), як ён наладжваецца (config[]), яго магчымасці і — для host-native сэрвісаў — крокі install[] і каманду запуску, якія выконвае SystemdDeployer. Паколькі распрацоўка і ўсталёўка выкарыстоўваюць адзін і той жа кантракт валідацыі, «правільны маніфест» і «усталёўны плагін» азначаюць адно і тое ж.

[!NOTE] Маніфест апісвае кантракт плагіна, а не яго назву на старонцы крамы. Машынны slug паходзіць ад назвы дырэкторыі/пакета (прыватная side-load) ці ад поля заяўкі (публічны) — глядзіце Публікацыя плагіна.

CLI

aihummer plugin аб’ядноўвае каманды распрацоўкі, пакавання і публікацыі:

# Scaffold a manifest (kind: connector | service | openapi | mcp)
aihummer plugin init <kind> [dir]

# Validate a manifest against the install contract
aihummer plugin validate <manifest.json>

# Generate an ed25519 author key (writes <prefix>.key and <prefix>.pub)
aihummer plugin keygen [--out <prefix>]

# Build and package the plugin into a release tarball + .sha256
aihummer plugin package <dir> [--out <file>] [--slug <slug>] [--build "<cmd>"]

# Sign the release identity (slug\0version\0source_ref); with --manifest the
# signature is embedded into the manifest.signature field
aihummer plugin sign --key <priv> [--manifest <m.json>] <bundle|dir>

# Upload a private plugin into your own instance (side-load)
aihummer plugin publish --private --instance <url> --token <admin> <bundle.tar.gz>

# Open a PR to the public AiHummer/marketplace-catalog
aihummer plugin publish --public --dir <dir> --key <priv> \
  --artifact-url <url> --publisher <name> \
  --description <text> --icon <url> [--screenshot <url> ...] \
  [--channel stable|beta] [--register-key <pub>]
Каманда Што яна робіць
init <kind> [dir] Запісвае стартавы manifest.json для выбранага віду.
validate <m.json> Правярае маніфест тым жа кантрактам, што і ўсталёўка.
keygen Генеруе пару ключоў аўтара: .key (прыватны, трымаць у сакрэце) і .pub, друкуе key id.
package <dir> Будуе (апцыянальна --build) і пакуе ў <slug>-<version>.tar.gz з раскладкай --strip-components=1, запісвае .sha256. Ніколі не пакуе .env, *.key, node_modules, .git.
sign --key <priv> Падпісвае ідэнтычнасць рэлізу; друкуе подпіс і key id; з --manifest убудоўвае подпіс у маніфест.
publish --private Загружае пакет у POST /v1/admin/modules/upload вашага экзэмпляра.
publish --public Адкрывае PR у AiHummer/marketplace-catalog.

Абодва рэжымы публікацыі апісаны падрабязна на Публікацыя плагіна.

Палі маніфеста

Ці з’яўляецца поле абавязковым, залежыць ад віду і ад таго, ці з’яўляецца плагін публічным. Базавыя палі і палі ідэнтычнасці:

Поле Тып Абавязковае Прызначэнне
kind string заўсёды Від: connector | service | openapi | mcp.
version string так Версія плагіна (semver), напр. 1.0.0.
contract string для каналаў ID кантракту, напр. aihummer.channel.v1.
scope string не Мадэль доступу: shared (па змаўчанні) ці personal.
capabilities string[] не Аб’яўленыя магчымасці.
config object[] не Палі формы канфігурацыі; кожнаму патрэбен key, плюс label, secret, required.
oauth object не OAuth2 (authorize_url, token_url, scopes[]) для падключэння ўліковага запісу карыстальніка.
signature string калі падпісана base64 ed25519 подпіс над ідэнтычнасцю рэлізу (убудоўваецца sign).

Палі, спецыфічныя для віду — роўна адзін блок запаўняецца ў залежнасці ад kind:

Поле Для віду Абавязковае Прызначэнне
host_native.exec_start connector, service так Каманда, што запускае доўгажывучы сэрвіс.
host_native.runtime connector, service, mcp не node | python | binary.
host_native.install connector, service, mcp не Крокі ўсталёўкі (масіў каманд shell), выконваюцца на хасце пасля распакоўкі.
host_native.port connector, service не Пажаданы TCP-порт (deployer можа пераназначыць праз $PORT).
host_native.health_path connector, service не Шлях праверкі здароўя (па змаўчанні /healthz).
openapi.spec_url openapi так URL спецыфікацыі OpenAPI 3.x.
openapi.base_url openapi не Перавызначыць servers[0].url.
openapi.allowed_hosts openapi не Спіс дазволеных для выхаду для сінтэзаваных інструментаў.
openapi.auth openapi не Супастаўленне securityScheme → назва сакрэту.
openapi.tool_prefix openapi не Прэфікс назвы інструмента.
mcp.transport mcp так stdio ці http.
mcp.command / mcp.args mcp (stdio) так для stdio Выканальны файл сервера і аргументы.
mcp.url mcp (http) так для http URL канчатковага пункта MCP.
mcp.auth_header / mcp.secret_token_key mcp (http) не Загаловак і ключ сакрэту для bearer-токена.

Палі старонкі крамы і ідэнтычнасці (для публічных плагінаў)

Каб трапіць у публічны каталог, маніфест павінен несці ідэнтычнасць выдаўца і палі старонкі крамы. Прыватнай side-load нічога з гэтага не патрэбна — такі плагін давераны на ўзроўні экзэмпляра.

Поле Тып Абавязковае Прызначэнне
visibility string не public | private | unlisted. Пуста = legacy/першакрыніцовы (без патрабавання ідэнтычнасці).
publisher string для публічных Прастора імёнаў выдаўца, ^[a-z0-9][a-z0-9-]{1,38}$. Публічныя slug’і называюцца @publisher/slug.
publisher_key_id string для публічных key id ключа, якім падпісаны артэфакт.
description string для публічных Анатацыя старонкі крамы ў каталогу.
icon string для публічных Іконка плагіна: URL https:// ці URI data:.
screenshots string[] не Скрыншоты старонкі крамы (масіў URL https://; кожны непусты).

[!TIP] Запускайце aihummer plugin validate перад кожнай публікацыяй. Кантракт усталёўкі і валідацыі ідэнтычныя, таму маніфест, што праходзіць лакальна, будзе прыняты як deployer’ам маркетплэйса, так і валідатарам публічнага каталога.

Мінімальныя маніфесты

Каркас service (тое, што запісвае aihummer plugin init service):

{
  "version": "1.0.0",
  "kind": "service",
  "scope": "shared",
  "contract": "aihummer.channel.v1",
  "host_native": {
    "runtime": "node",
    "install": ["npm ci --omit=dev"],
    "exec_start": "node dist/main.js",
    "port": 8800,
    "health_path": "/healthz"
  },
  "config": [
    { "key": "api_token", "label": "API token", "secret": true, "required": true }
  ]
}

Маніфест openapi без кода яшчэ карацейшы — ён проста паказвае на спецыфікацыю:

{
  "version": "1.0.0",
  "kind": "openapi",
  "scope": "shared",
  "openapi": {
    "spec_url": "https://api.example.com/openapi.json",
    "tool_prefix": "example_",
    "allowed_hosts": ["api.example.com"],
    "auth": { "bearerAuth": "api_token" }
  },
  "config": [
    { "key": "api_token", "label": "API token", "secret": true, "required": true }
  ]
}

Маніфест mcp (транспарт stdio):

{
  "version": "1.0.0",
  "kind": "mcp",
  "scope": "shared",
  "host_native": { "runtime": "node", "install": ["npm ci --omit=dev"] },
  "mcp": { "transport": "stdio", "command": "node", "args": ["server.js"] }
}

Ад маніфеста да маркетплэйса

Пасля валідацыі плагін пакуецца (package), падпісваецца (sign) і публікуецца ў адным з двух рэжымаў:

  • Прыватны (для сябе) — side-load у ваш экзэмпляр праз адмінскі UI ці publish --private. Артэфакт ніколі не пакідае экзэмпляр.
  • Публічны (для ўсіх) — publish --public адкрывае PR у публічны каталог; пасля агляду AiHummer контр-падпісвае рэліз і публікуе яго ў каталог супольнасці.

Глядзіце Публікацыя плагіна для поўнага пакрокавага кіраўніцтва.

Куды далей