AiHummer
Oʻzbekcha▾
Kirish
v1.0.x▾
v1.0.xstable
{ }Swagger
Marketplace va plaginlar/Plagin SDK

Plagin SDK

v1.0.x · yangilandi 2026-06-27

Plagin bitta manifest.json bilan tasvirlanadi. Ishlab chiqish paytida manifestni tekshiradigan shartnoma platforma oʻrnatish paytida amal qiladigan shartnoma bilan bir xil, shuning uchun validate’dan o‘tgan manifest — marketplace qabul qiladigan manifestdir. aihummer plugin CLI butun hayot tsiklini qamrab oladi: skeletdan imzolash va nashr qilishgacha.

Bitta manifest, bitta shartnoma

Plaginda aniq bitta haqiqat manbasi bor — uning manifest.json’i. U plagin turini (kind), uning qanday sozlanishini (config[]), uning imkoniyatlarini va — host-native xizmatlar uchun — SystemdDeployer ishga tushiradigan install[] bosqichlari va ishga tushirish buyrug‘ini e’lon qiladi. Ishlab chiqish va oʻrnatish xuddi shu tekshiruv shartnomasidan foydalangani uchun, “to‘g‘ri manifest” va “oʻrnatiladigan plagin” bir xil narsani anglatadi.

[!NOTE] Manifest plaginning shartnomasini tasvirlaydi, uning store sahifasidagi nomini emas. Mashina slug’i katalog/to‘plam nomidan (maxfiy side-load) yoki topshiriq maydonidan (ommaviy) keladi — qarang Plaginni nashr qilish.

CLI

aihummer plugin ishlab chiqish, paketlash va nashr buyruqlarini to‘playdi:

# 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>]
Buyruq U nima qiladi
init <kind> [dir] Tanlangan tur uchun boshlang‘ich manifest.json yozadi.
validate <m.json> Manifestni oʻrnatish bilan bir xil shartnoma yordamida tekshiradi.
keygen Muallif kalit juftligini yaratadi: .key (maxfiy, sir saqlang) va .pub, key id’ni chop etadi.
package <dir> Quradi (ixt. --build) va --strip-components=1 joylashuvi bilan <slug>-<version>.tar.gz’ga paketlaydi, .sha256 yozadi. Hech qachon .env, *.key, node_modules, .git paketlamaydi.
sign --key <priv> Release identifikatorini imzolaydi; imzo va key id’ni chop etadi; --manifest bilan imzoni manifestga joylaydi.
publish --private To‘plamni oʻrnatmangizning POST /v1/admin/modules/upload’iga yuklaydi.
publish --public AiHummer/marketplace-catalog’ga PR ochadi.

Ikkala nashr rejimi ham Plaginni nashr qilish sahifasida batafsil bayon qilingan.

Manifest maydonlari

Maydonning majburiyligi kind’ga va plaginning ommaviy yoki yo‘qligiga bog‘liq. Asosiy va identifikatsiya maydonlari:

Maydon Tur Majburiy Maqsad
kind string doimo Tur: connector | service | openapi | mcp.
version string ha Plagin versiyasi (semver), masalan 1.0.0.
contract string kanallar uchun Shartnoma ID, masalan aihummer.channel.v1.
scope string yo‘q Kirish modeli: shared (sukut) yoki personal.
capabilities string[] yo‘q E’lon qilingan imkoniyatlar.
config object[] yo‘q Konfiguratsiya forma maydonlari; har biriga key, plus label, secret, required kerak.
oauth object yo‘q Foydalanuvchi hisobini ulash uchun OAuth2 (authorize_url, token_url, scopes[]).
signature string imzolanganda Release identifikatori ustidan base64 ed25519 imzo (sign tomonidan joylanadi).

Tur uchun maxsus maydonlar — kind’ga qarab aniq bitta blok to‘ldiriladi:

Maydon Qaysi kind uchun Majburiy Maqsad
host_native.exec_start connector, service ha Uzoq muddatli xizmatni ishga tushiradigan buyruq.
host_native.runtime connector, service, mcp yo‘q node | python | binary.
host_native.install connector, service, mcp yo‘q Oʻrnatish bosqichlari (shell buyruqlari massivi), ajratib olgandan keyin xostda ishga tushadi.
host_native.port connector, service yo‘q Afzal ko‘rilgan TCP porti (deployer $PORT orqali qayta tayinlashi mumkin).
host_native.health_path connector, service yo‘q Salomatlik tekshiruvi yo‘li (sukut /healthz).
openapi.spec_url openapi ha OpenAPI 3.x spetsifikatsiyasi URL’i.
openapi.base_url openapi yo‘q servers[0].url’ni bekor qiladi.
openapi.allowed_hosts openapi yo‘q Sintez qilingan vositalar uchun chiqish ruxsat ro‘yxati.
openapi.auth openapi yo‘q securityScheme → sir nomi xaritasi.
openapi.tool_prefix openapi yo‘q Vosita nomi prefiksi.
mcp.transport mcp ha stdio yoki http.
mcp.command / mcp.args mcp (stdio) stdio uchun ha Server bajariladigani va argumentlar.
mcp.url mcp (http) http uchun ha MCP so‘nggi nuqta URL’i.
mcp.auth_header / mcp.secret_token_key mcp (http) yo‘q Bearer token uchun sarlavha va sir kaliti.

Store sahifasi va identifikatsiya maydonlari (ommaviy plaginlar uchun)

Ommaviy katalogga kirish uchun manifest nashriyotchi identifikatsiyasi va store sahifasi maydonlarini olib yurishi kerak. Maxfiy side-load bularning hech biriga muhtoj emas — bunday plaginga oʻrnatma darajasida ishoniladi.

Maydon Tur Majburiy Maqsad
visibility string yo‘q public | private | unlisted. Bo‘sh = eski/birinchi tomon (identifikatsiya talabisiz).
publisher string ommaviy uchun Nashriyotchi nom maydoni, ^[a-z0-9][a-z0-9-]{1,38}$. Ommaviy slug’lar @publisher/slug deb nomlanadi.
publisher_key_id string ommaviy uchun Artefakt imzolangan kalitning key id’si.
description string ommaviy uchun Katalogdagi store sahifasi tavsifi.
icon string ommaviy uchun Plagin ikonkasi: https:// URL yoki data: URI.
screenshots string[] yo‘q Store sahifasi skrinshotlari (https:// URL’lar massivi; har biri bo‘sh emas).

[!TIP] Har bir nashrdan oldin aihummer plugin validate ishga tushiring. Oʻrnatish va tekshiruv shartnomasi bir xil, shuning uchun lokal o‘tgan manifest marketplace deployer tomonidan ham, ommaviy katalog tekshiruvchisi tomonidan ham qabul qilinadi.

Minimal manifestlar

service skeleti (aihummer plugin init service nima yozadi):

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

Kodsiz openapi manifesti yanada qisqaroq — u shunchaki spetsifikatsiyaga ko‘rsatadi:

{
  "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 transporti):

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

Manifestdan marketplace’gacha

Tekshiruvdan keyin plagin paketlanadi (package), imzolanadi (sign) va ikki rejimdan birida nashr etiladi:

  • Maxfiy (o‘zingiz uchun) — Admin UI yoki publish --private orqali oʻrnatmangizga side-load. Artefakt oʻrnatmadan hech qachon chiqmaydi.
  • Ommaviy (hamma uchun) — publish --public ommaviy katalogga PR ochadi; ko‘rikdan keyin AiHummer release’ni qarama-qarshi imzolaydi va uni community katalogiga nashr etadi.

To‘liq qadamlar uchun Plaginni nashr qilish sahifasiga qarang.

Keyin qayerga