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) және --strip-components=1 орналасуымен <slug>-<version>.tar.gz-ке буады, .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) және екі режимнің бірінде жарияланады:

  • Жеке (өзіңіз үшін) — әкімші интерфейсі немесе publish --private арқылы данаңызға бүйірден жүктеу. Артефакт данадан ешқашан шықпайды.
  • Қоғамдық (барлығы үшін) — publish --public қоғамдық каталогқа PR ашады; шолудан кейін AiHummer релизге қарсы қол қояды және оны қауымдастық каталогына жариялайды.

Толық нұсқаулықты Плагинді жариялау бөлімінен қараңыз.

Әрі қарай қайда