AiHummer
Тоҷикӣ▾
Даромадан
v1.0.x▾
v1.0.xstable
{ }Swagger
Маркетплейс ва плагинҳо/SDK-и плагин

SDK-и плагин

v1.0.x · навсозӣ шуд 2026-06-27

Як плагин бо як manifest.json тавсиф мешавад. Қарордоде, ки манифестро ҳангоми рушд тасдиқ мекунад, ҳамонест, ки платформа ҳангоми насб иҷро мекунад, бинобар ин манифесте, ки validate-ро мегузаронад, манифестест, ки бозор қабул хоҳад кард. CLI-и aihummer plugin тамоми давраи зиндагиро фаро мегирад: аз сохтори ибтидоӣ то имзо ва нашр.

Як манифест, як қарордод

Як плагин маҳз як манбаи ҳақиқат дорад — manifest.json-и он. Он навъи плагин (kind)-ро, тарзи танзим (config[]), тавоноиҳои он ва — барои хидматҳои ба host бунёдшуда — қадамҳои install[] ва фармони оғозро эълом мекунад, ки SystemdDeployer онро иҷро мекунад. Азбаски рушд ва насб ҳамон қарордоди тасдиқро истифода мебаранд, “манифести дуруст” ва “плагини насбшаванда” як маъно доранд.

[!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 PR-ро ба AiHummer/marketplace-catalog мекушояд.

Ҳардуи реҷаҳои нашр дар Нашри плагин ба тафсил шарҳ дода шудаанд.

Майдонҳои манифест

Талаботнокии майдон аз 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 иҷро мешаванд.
host_native.port connector, service не Порти TCP-и афзалиятнок (deployer метавонад тавассути $PORT аз нав таъин кунад).
host_native.health_path connector, service не Роҳи санҷиши саломатӣ (пешфарз /healthz).
openapi.spec_url openapi бале URL-и спетсификатсияи OpenAPI 3.x.
openapi.base_url openapi не Бекоркунии servers[0].url.
openapi.allowed_hosts openapi не Рӯйхати иҷозати egress барои абзорҳои синтезшуда.
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 URL-и нуқтаи интиҳоии MCP.
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 барои ҷамъиятӣ Нишони плагин: як URL-и https:// ё як URI-и data:.
screenshots string[] не Скриншотҳои саҳифаи мағоза (массиви URL-ҳои https://; ҳар яке холӣ набошад).

[!TIP] Пеш аз ҳар нашр aihummer plugin validate-ро иҷро кунед. Қарордоди насб ва тасдиқ якхела ҳастанд, бинобар ин манифесте, ки маҳаллӣ мегузарад, ҳам аз ҷониби deployer-и бозор ва ҳам аз ҷониби валидатори каталоги ҷамъиятӣ қабул хоҳад шуд.

Манифестҳои минималӣ

Як сохтори ибтидоии 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) ва дар яке аз ду реҷа нашр мешавад:

  • Хусусӣ (барои худатон) — бори паҳлӯӣ ба инстанси шумо тавассути Admin UI ё publish --private. Артефакт ҳеҷ гоҳ инстансро тарк намекунад.
  • Ҷамъиятӣ (барои ҳама) — publish --public PR-ро ба каталоги ҷамъиятӣ мекушояд; пас аз баррасӣ AiHummer нашрро имзои муқобил мекунад ва онро ба каталоги ҷамъиятӣ нашр менамояд.

Барои роҳбалади пурра нигаред ба Нашри плагин.

Қадами оянда