AiHummer
Кыргызча▾
Кирүү
v1.0.x▾
v1.0.xstable
{ }Swagger
Маркетплейс жана плагиндер/Плагин SDK

Плагин SDK

v1.0.x · жаңыланды 2026-06-27

Плагин бир manifest.json менен сүрөттөлөт. Иштеп чыгуу учурунда манифестти текшерген келишим — платформа орнотуу учурунда мажбурлаган келишим менен ошол эле, ошондуктан validateтен өткөн манифест — маркетплейс кабыл ала турган манифест. aihummer plugin CLIи бүт жашоо циклин камтыйт: каркастан кол коюуга жана жарыялоого чейин.

Бир манифест, бир келишим

Плагиндин так бир чындык булагы бар — анын manifest.json. Ал плагиндин түрүн (kind), кантип конфигурацияланарын (config[]), анын мүмкүнчүлүктөрүн жана — хост-нативдик кызматтар үчүн — SystemdDeployer иштеткен install[] кадамдарын жана баштоо буйругун жарыялайт. Иштеп чыгуу жана орнотуу ошол эле текшерүү келишимин колдонгондуктан, “жарактуу манифест” жана “орнотула турган плагин” бирдей нерсени билдирет.

[!NOTE] Манифест плагиндин дүкөн-барак атын эмес, анын келишимин сүрөттөйт. Машина slugи каталог/топтом атынан (жеке каптал-жүктөө) же жөнөтүү талаасынан (коомдук) келет — Плагинди жарыялоо бөлүмүн караңыз.

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 AiHummer/marketplace-catalogго PR ачат.

Эки жарыялоо режими тең Плагинди жарыялоо бөлүмүндө деталдуу.

Манифест талаалары

Талаа талап кылынабы — бул kindден жана плагин коомдукпу же жокпу андан көз каранды. Негизги жана идентификация талаалары:

Талаа Түр Талап кылынат Максаты
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 порту (деплоер $PORT аркылуу кайра дайындашы мүмкүн).
host_native.health_path connector, service жок Ден соолук текшерүү жолу (демейки /healthz).
openapi.spec_url openapi ооба OpenAPI 3.x спецификациясынын URLи.
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 үчүн ооба MCP акырынын URLи.
mcp.auth_header / mcp.secret_token_key mcp (http) жок Bearer токени үчүн аталыш жана сыр ачкыч.

Дүкөн-барак жана идентификация талаалары (коомдук плагиндер үчүн)

Коомдук каталогго кирүү үчүн манифест жарыялоочунун идентификациясын жана дүкөн-барак талааларын алып жүрүшү керек. Жеке каптал-жүктөөгө булардын бири да керек эмес — мындай плагин инстанция деңгээлинде ишеничтүү.

Талаа Түр Талап кылынат Максаты
visibility string жок public | private | unlisted. Бош = эски/биринчи тарап (идентификация талабы жок).
publisher string коомдук үчүн Жарыялоочу мейкиндиги, ^[a-z0-9][a-z0-9-]{1,38}$. Коомдук slugдар @publisher/slug деп аталат.
publisher_key_id string коомдук үчүн Артефакт кол коюлган ачкычтын key idси.
description string коомдук үчүн Каталогдогу дүкөн-барак сүрөттөмөсү.
icon string коомдук үчүн Плагин иконкасы: https:// URLи же data: URIи.
screenshots string[] жок Дүкөн-барак скриншоттору (https:// URLдеринин массиви; ар бири бош эмес).

[!TIP] Ар бир жарыялоодон мурда aihummer plugin validateти иштетиңиз. Орнотуу жана текшерүү келишими бирдей, ошондуктан жергиликтүү өткөн манифест маркетплейс деплоери да, коомдук каталог валидатору да тарабынан кабыл алынат.

Минималдуу манифесттер

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) жана эки режимдин биринде жарыяланат:

  • Жеке (өзүңүз үчүн) — Админ UI же publish --private аркылуу инстанцияңызга каптал-жүктөө. Артефакт инстанциядан эч качан чыкпайт.
  • Коомдук (баары үчүн) — publish --public коомдук каталогго PR ачат; карап чыккандан кийин AiHummer релизге каршы кол коюп, аны коомдук каталогго жарыялайт.

Толук кадамдар үчүн Плагинди жарыялоо бөлүмүн караңыз.

Эми кайда