AiHummer
Azərbaycanca▾
Daxil ol
v1.0.x▾
v1.0.xstable
{ }Swagger
Marketplace və plaginlər/Plagin SDK

Plagin SDK

v1.0.x · yeniləndi 2026-06-27

Plagin bir manifest.json ilə təsvir edilir. Manifesti inkişaf zamanı yoxlayan müqavilə platformanın quraşdırma zamanı tətbiq etdiyi ilə eynidir, beləliklə validate-dən keçən manifest marketplace-in qəbul edəcəyi manifestdir. aihummer plugin CLI bütün həyat dövrünü əhatə edir: skeletdən imzalama və nəşrə qədər.

Bir manifest, bir müqavilə

Plaginin tam olaraq bir həqiqət mənbəyi var — onun manifest.json-u. O, plagin növünü (kind), necə konfiqurasiya edildiyini (config[]), onun qabiliyyətlərini və — host-native xidmətlər üçün — SystemdDeployer-in işə saldığı install[] addımlarını və başlatma əmrini bəyan edir. İnkişaf və quraşdırma eyni yoxlama müqaviləsindən istifadə etdiyi üçün “etibarlı manifest” və “quraşdırıla bilən plagin” eyni mənanı verir.

[!NOTE] Manifest plaginin müqaviləsini təsvir edir, store səhifəsi adını yox. Maşın slug-ı qovluq/bundle adından (şəxsi yan yükləmə) və ya təqdimat sahəsindən (ictimai) gəlir — baxın: Plagin nəşri.

CLI

aihummer plugin inkişaf, paketləmə və nəşr əmrlərini birləşdirir:

# 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>]
Əmr Nə edir
init <kind> [dir] Seçilmiş növ üçün başlanğıc manifest.json yazır.
validate <m.json> Manifesti quraşdırma ilə eyni müqavilə ilə yoxlayır.
keygen Müəllif açar cütünü yaradır: .key (şəxsi, gizli saxlayın) və .pub, key id-i çap edir.
package <dir> Build edir (istəyə bağlı --build) və --strip-components=1 quruluşu ilə <slug>-<version>.tar.gz-ə paketləyir, .sha256 yazır. Heç vaxt .env, *.key, node_modules, .git paketləmir.
sign --key <priv> Release identity-ni imzalayır; imzanı və key id-i çap edir; --manifest ilə imzanı manifestə daxil edir.
publish --private Bundle-ı instance-inizin POST /v1/admin/modules/upload-una yükləyir.
publish --public AiHummer/marketplace-catalog-a PR açır.

Hər iki nəşr rejimi Plagin nəşri səhifəsində ətraflı izah olunur.

Manifest sahələri

Sahənin tələb olunub-olunmadığı növdən (kind) və plaginin ictimai olub-olmadığından asılıdır. Baza və identifikasiya sahələri:

Sahə Tip Tələb olunur Məqsəd
kind string həmişə Növ: connector | service | openapi | mcp.
version string bəli Plagin versiyası (semver), məs. 1.0.0.
contract string kanallar üçün Müqavilə ID-si, məs. aihummer.channel.v1.
scope string xeyr Giriş modeli: shared (standart) və ya personal.
capabilities string[] xeyr Bəyan edilmiş qabiliyyətlər.
config object[] xeyr Konfiqurasiya forma sahələri; hər biri key, üstəlik label, secret, required tələb edir.
oauth object xeyr İstifadəçinin hesabını qoşmaq üçün OAuth2 (authorize_url, token_url, scopes[]).
signature string imzalananda Release identity üzərində base64 ed25519 imzası (sign tərəfindən daxil edilir).

Növə xas sahələr — kind-dən asılı olaraq dəqiq bir blok doldurulur:

Sahə Növ üçün Tələb olunur Məqsəd
host_native.exec_start connector, service bəli Uzunömürlü xidməti işə salan əmr.
host_native.runtime connector, service, mcp xeyr node | python | binary.
host_native.install connector, service, mcp xeyr Quraşdırma addımları (shell əmrləri massivi), çıxarışdan sonra host-da işə salınır.
host_native.port connector, service xeyr Üstünlük verilən TCP portu (deployer $PORT vasitəsilə yenidən təyin edə bilər).
host_native.health_path connector, service xeyr Sağlamlıq yoxlaması yolu (standart /healthz).
openapi.spec_url openapi bəli OpenAPI 3.x spesifikasiyasının URL-i.
openapi.base_url openapi xeyr servers[0].url-i əvəz et.
openapi.allowed_hosts openapi xeyr Sintez edilmiş alətlər üçün çıxış allowlist-i.
openapi.auth openapi xeyr securityScheme → secret adı xəritələ.
openapi.tool_prefix openapi xeyr Alət adı prefiksi.
mcp.transport mcp bəli stdio və ya http.
mcp.command / mcp.args mcp (stdio) stdio üçün bəli Server icra faylı və arqumentləri.
mcp.url mcp (http) http üçün bəli MCP endpoint URL-i.
mcp.auth_header / mcp.secret_token_key mcp (http) xeyr Bearer token üçün header və secret açar.

Store səhifəsi və identifikasiya sahələri (ictimai plaginlər üçün)

İctimai kataloqa daxil olmaq üçün manifest nəşr edən identifikasiyasını və store səhifəsi sahələrini daşımalıdır. Şəxsi yan yükləməyə bunların heç biri lazım deyil — belə plaginə instance səviyyəsində etibar olunur.

Sahə Tip Tələb olunur Məqsəd
visibility string xeyr public | private | unlisted. Boş = köhnə/birinci tərəf (identifikasiya tələbi yoxdur).
publisher string ictimai üçün Nəşr edən namespace, ^[a-z0-9][a-z0-9-]{1,38}$. İctimai slug-lar @publisher/slug adlanır.
publisher_key_id string ictimai üçün Artefaktın imzalandığı açarın key id-i.
description string ictimai üçün Kataloqda store səhifəsi təsviri.
icon string ictimai üçün Plagin ikonu: https:// URL və ya data: URI.
screenshots string[] xeyr Store səhifəsi skrinşotları (https:// URL massivi; hər biri boş olmayan).

[!TIP] Hər nəşrdən əvvəl aihummer plugin validate işə salın. Quraşdırma və yoxlama müqaviləsi eynidir, beləliklə lokal olaraq keçən manifest həm marketplace deployer-i, həm də ictimai kataloq validator-u tərəfindən qəbul ediləcək.

Minimal manifestlər

service skeleti (aihummer plugin init service nə yazır):

{
  "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 daha da qısadır — o sadəcə spesifikasiyaya işarə edir:

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

Manifestdən marketplace-ə

Yoxlamadan sonra plagin paketlənir (package), imzalanır (sign) və iki rejimdən birində nəşr edilir:

  • Şəxsi (özünüz üçün) — Admin UI və ya publish --private vasitəsilə instance-inizə yan yükləyin. Artefakt heç vaxt instance-dən çıxmır.
  • İctimai (hər kəs üçün) — publish --public ictimai kataloqa PR açır; baxışdan sonra AiHummer release-i əks imzalayır və icma kataloquna nəşr edir.

Tam izahat üçün baxın: Plagin nəşri.

Sonra haraya