AiHummer
Türkmençe▾
Gir
v1.0.x▾
v1.0.xstable
{ }Swagger
Marketpleýs we pluginler/Plugin SDK

Plugin SDK

v1.0.x · täzelendi 2026-06-27

Plugin bir manifest.json bilen suratlandyrylýar. Işläp düzme döwründe manifesti barlaýan şertnama platforma gurnama wagtynda berjaý edýäni bilen şol bir, şonuň üçin validate-den geçen manifest marketplace kabul etjek manifestdir. aihummer plugin CLI bütin ömri öz içine alýar: skafolddan gol çekmäge we çap etmäge çenli.

Bir manifest, bir şertnama

Pluginiň takyk bir hakykat çeşmesi bar — onuň manifest.json-i. Ol plugin görnüşini (kind), nähili sazlanýandygyny (config[]), onuň başarnyklaryny we — host-native hyzmatlar üçin — SystemdDeployer işledýän install[] ädimlerini we başlangyç buýrugyny yglan edýär. Işläp düzme we gurnama şol bir barlag şertnamasyny ulanýandygy üçin, “dogry manifest” we “gurnap boljak plugin” şol bir manyny aňladýar.

[!NOTE] Manifest pluginiň şertnamasyny suratlandyrýar, onuň dükan-sahypa adyny däl. Maşyn slug katalog/bukja adyndan (hususy side-load) ýa-da iberiş meýdanyndan (jemgyýetçilik) gelýär — serediň Plugin çap etmek.

CLI

aihummer plugin işläp düzme, gaplama we çap etmek buýruklaryny birleşdirýär:

# 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>]
Buýruk Näme edýär
init <kind> [dir] Saýlanan görnüş üçin başlangyç manifest.json ýazýar.
validate <m.json> Manifesti gurnama bilen şol bir şertnama bilen barlaýar.
keygen Awtor açar jübütini döredýär: .key (hususy, gizlin saklaň) we .pub, key id-i çap edýär.
package <dir> Gurýar (islege görä --build) we --strip-components=1 ýerleşişi bilen <slug>-<version>.tar.gz-a gaplaýar, .sha256 ýazýar. Hiç haçan .env, *.key, node_modules, .git gaplamaýar.
sign --key <priv> Reliz şahsyýetine gol çekýär; goly we key id-i çap edýär; --manifest bilen goly manifeste gömýär.
publish --private Bukjany gurnamaňyzyň POST /v1/admin/modules/upload-yna ýükleýär.
publish --public AiHummer/marketplace-catalog-a PR açýar.

Iki çap etmek rejesi-de Plugin çap etmek bölüminde jikme-jik berlendir.

Manifest meýdanlary

Meýdanyň gerekdigi kind-a we pluginiň jemgyýetçilik bolup-bolmazlygyna bagly. Esasy we şahsyýet meýdanlary:

Meýdan Görnüş Gerek Maksat
kind string elmydama Görnüş: connector | service | openapi | mcp.
version string hawa Plugin wersiýasy (semver), meselem 1.0.0.
contract string kanallar üçin Şertnama ID, meselem aihummer.channel.v1.
scope string ýok Giriş modeli: shared (deslapky) ýa-da personal.
capabilities string[] ýok Yglan edilen başarnyklar.
config object[] ýok Sazlama görnüş meýdanlary; her birine key, hem-de label, secret, required gerek.
oauth object ýok Ulanyjynyň hasabyny birikdirmek üçin OAuth2 (authorize_url, token_url, scopes[]).
signature string gol çekilende reliz şahsyýetine base64 ed25519 goly (sign tarapyndan gömülen).

Görnüşe mahsus meýdanlar — kind-a baglylykda takyk bir blok doldurylýar:

Meýdan Görnüş üçin Gerek Maksat
host_native.exec_start connector, service hawa Uzak ýaşaýan hyzmaty işledýän buýruk.
host_native.runtime connector, service, mcp ýok node | python | binary.
host_native.install connector, service, mcp ýok Gurnama ädimleri (shell buýruklarynyň massiwi), ekstraksiýadan soň host-da işledilýär.
host_native.port connector, service ýok Halanýan TCP porty (deployer $PORT arkaly täzeden belläp biler).
host_native.health_path connector, service ýok Saglyk-barlag ýoly (deslapky /healthz).
openapi.spec_url openapi hawa OpenAPI 3.x spek URL-i.
openapi.base_url openapi ýok servers[0].url-y üýtgetmek.
openapi.allowed_hosts openapi ýok Döredilen gurallar üçin egress rugsat sanawy.
openapi.auth openapi ýok securityScheme → secret adyny düzmek.
openapi.tool_prefix openapi ýok Gural-ady prefiksi.
mcp.transport mcp hawa stdio ýa-da http.
mcp.command / mcp.args mcp (stdio) stdio üçin hawa Serwer ýerine ýetiriji we argumentler.
mcp.url mcp (http) http üçin hawa MCP ahyrky nokat URL-i.
mcp.auth_header / mcp.secret_token_key mcp (http) ýok Bearer token üçin header we secret açary.

Dükan-sahypa we şahsyýet meýdanlary (jemgyýetçilik pluginleri üçin)

Jemgyýetçilik kataloguna girmek üçin manifest çap ediji şahsyýetini we dükan-sahypa meýdanlaryny götermeli. Hususy side-load bularyň hiç birine mätäç däl — beýle plugin gurama derejesinde ynamlydyr.

Meýdan Görnüş Gerek Maksat
visibility string ýok public | private | unlisted. Boş = miras/birinji tarap (şahsyýet talaby ýok).
publisher string jemgyýetçilik üçin Çap ediji ady, ^[a-z0-9][a-z0-9-]{1,38}$. Jemgyýetçilik slug-lar @publisher/slug diýlip atlandyrylýar.
publisher_key_id string jemgyýetçilik üçin Artefaktyň gol çekilen açarynyň key id-i.
description string jemgyýetçilik üçin Katalogda dükan-sahypa beýany.
icon string jemgyýetçilik üçin Plugin nyşany: https:// URL ýa-da data: URI.
screenshots string[] ýok Dükan-sahypa skrinşotlary (https:// URL-leriň massiwi; her biri boş däl).

[!TIP] Her çap etmekden öň aihummer plugin validate işlediň. Gurnama we barlag şertnamasy birmeňzeş, şonuň üçin ýerli geçen manifest hem marketplace deployer hem-de jemgyýetçilik katalog walidatory tarapyndan kabul ediler.

Minimal manifestler

service skafold (aihummer plugin init service ýazýan zat):

{
  "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 }
  ]
}

Kodsuz openapi manifesti has-da gysga — ol diňe speke ugrukdyrýar:

{
  "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 manifesti (stdio transport):

{
  "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"] }
}

Manifestden marketplace-e

Barlagdan soň, plugin gaplanýar (package), gol çekilýär (sign) we iki rejäniň birinde çap edilýär:

  • Hususy (özüňiz üçin) — Admin UI ýa-da publish --private arkaly gurnamaňyza side-load. Artefakt gurnamany hiç haçan terk etmeýär.
  • Jemgyýetçilik (hemmeler üçin) — publish --public jemgyýetçilik kataloguna PR açýar; synanyşykdan soň AiHummer relizi garşy-gol çekýär we ony jemgyýet katalogyna çap edýär.

Doly gezelenç üçin Plugin çap etmek bölümine serediň.

Indiki ädim