AiHummer
Հայերեն▾
Մուտք
v1.0.x▾
v1.0.xstable
{ }Swagger
Marketplace և փլագիններ/Փլագինի SDK

Փլագինի SDK

v1.0.x · թարմացվել է 2026-06-27

Փլագինը նկարագրվում է մեկ manifest.json-ով։ Պայմանագիրը, որը վավերացնում է manifest-ը մշակման ընթացքում, նույնն է, ինչ հարթակը պարտադրում է տեղադրման ժամանակ, այնպես որ manifest-ը, որն անցնում է validate-ը, marketplace-ի կողմից ընդունվող manifest է։ aihummer plugin CLI-ն ընդգրկում է ողջ կենսացիկլը. scaffold-ից մինչև ստորագրում և հրապարակում։

Մեկ manifest, մեկ պայմանագիր

Փլագինն ունի ճշգրիտ մեկ ճշմարտության աղբյուր — իր manifest.json-ը։ Այն հայտարարում է փլագինի տիպը (kind), ինչպես է այն կարգավորվում (config[]), իր կարողությունները, և — host-native ծառայությունների համար — install[] քայլերը և գործարկման հրամանը, որ SystemdDeployer-ն աշխատեցնում է։ Քանի որ մշակումը և տեղադրումն օգտագործում են նույն վավերացման պայմանագիրը, «վավեր manifest» և «տեղադրելի փլագին» նշանակում են նույն բանը։

[!NOTE] Manifest-ը նկարագրում է փլագինի պայմանագիրը, ոչ թե store-page-ի անունը։ Մեքենայական slug-ը գալիս է գրացուցակի/փաթեթի անունից (մասնավոր side-load) կամ ներկայացման դաշտից (հանրային) — տես Փլագինի հրապարակում։

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 ընտրված kind-ի համար։
validate <m.json> Վավերացնում է manifest-ը նույն պայմանագրով, ինչ տեղադրումը։
keygen Գեներացնում է հեղինակի բանալիների զույգը. .key (մասնավոր, գաղտնի պահեք) և .pub, տպում է key id-ը։
package <dir> Build է անում (ընտրովի՝ --build) և փաթեթավորում <slug>-<version>.tar.gz-ի մեջ --strip-components=1 դասավորությամբ, գրում .sha256։ Երբեք չի փաթեթավորում .env, *.key, node_modules, .git։
sign --key <priv> Ստորագրում է թողարկման ինքնությունը. տպում է ստորագրությունը և key id-ը. --manifest-ով ներդնում է ստորագրությունը manifest-ի մեջ։
publish --private Վերբեռնում է փաթեթը ձեր instance-ի POST /v1/admin/modules/upload-ին։
publish --public Բացում է PR AiHummer/marketplace-catalog-ի համար։

Հրապարակման երկու ռեժիմներն էլ մանրամասն նկարագրված են Փլագինի հրապարակում էջում։

Manifest-ի դաշտերը

Թե արդյոք դաշտը պարտադիր է, կախված է kind-ից և նրանից, թե արդյոք փլագինը հանրային է։ Բազային և ինքնության դաշտեր.

Դաշտ Տիպ Պարտադիր Նպատակ
kind string միշտ Kind: connector | service | openapi | mcp։
version string այո Փլագինի տարբերակ (semver), օր.՝ 1.0.0։
contract string ալիքների համար Contract ID, օր.՝ aihummer.channel.v1։
scope string ոչ Մուտքի մոդել. shared (լռելյայն) կամ personal։
capabilities string[] ոչ Հայտարարված կարողություններ։
config object[] ոչ Config ձևի դաշտեր. յուրաքանչյուրին պետք է key, գումարած label, secret, required։
oauth object ոչ OAuth2 (authorize_url, token_url, scopes[])՝ օգտատիրոջ հաշիվը միացնելու համար։
signature string երբ ստորագրված է base64 ed25519 ստորագրություն թողարկման ինքնության վրա (ներդրված sign-ով)։

Kind-ի համար յուրահատուկ դաշտեր — ճշգրիտ մեկ բլոկ է լրացվում՝ կախված kind-ից.

Դաշտ 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 այո OpenAPI 3.x spec-ի URL։
openapi.base_url openapi ոչ Վերագրել servers[0].url։
openapi.allowed_hosts openapi ոչ Egress allowlist սինթեզված գործիքների համար։
openapi.auth openapi ոչ Map securityScheme → secret-ի անուն։
openapi.tool_prefix openapi ոչ Գործիքի անվան prefix։
mcp.transport mcp այո stdio կամ http։
mcp.command / mcp.args mcp (stdio) այո stdio-ի համար Սերվերի executable և արգումենտներ։
mcp.url mcp (http) այո http-ի համար MCP վերջակետի URL։
mcp.auth_header / mcp.secret_token_key mcp (http) ոչ Header և secret-ի բանալի bearer token-ի համար։

Store-page և ինքնության դաշտեր (հանրային փլագինների համար)

Հանրային կատալոգ մտնելու համար manifest-ը պետք է կրի հրապարակողի ինքնությունը և store-page դաշտերը։ Մասնավոր side-load-ին դրանցից ոչ մեկը պետք չէ — այդպիսի փլագինը վստահելի է instance-ի մակարդակում։

Դաշտ Տիպ Պարտադիր Նպատակ
visibility string ոչ public | private | unlisted։ Դատարկ = legacy/առաջին-կողմի (ինքնության պահանջ չկա)։
publisher string հանրայինի համար Հրապարակողի namespace, ^[a-z0-9][a-z0-9-]{1,38}$։ Հանրային slug-երը կոչվում են @publisher/slug։
publisher_key_id string հանրայինի համար Արտեֆակտի ստորագրման բանալու key id-ն։
description string հանրայինի համար Store-page-ի նկարագրությունը կատալոգում։
icon string հանրայինի համար Փլագինի պատկերակ. https:// URL կամ data: URI։
screenshots string[] ոչ Store-page-ի սքրինշոթներ (https:// URL-ների զանգված. յուրաքանչյուրը՝ ոչ դատարկ)։

[!TIP] Աշխատեցրեք aihummer plugin validate ամեն հրապարակումից առաջ։ Տեղադրման և վավերացման պայմանագիրը նույնական են, այնպես որ manifest-ը, որն անցնում է լոկալ, կընդունվի և՛ marketplace-ի deployer-ի, և՛ հանրային կատալոգի validator-ի կողմից։

Նվազագույն manifest-ներ

service scaffold (ինչ որ 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 }
  ]
}

Zero-code openapi manifest-ն ավելի կարճ է — այն պարզապես ուղղորդում է spec-ին.

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

Manifest-ից մինչև marketplace

Վավերացումից հետո փլագինը փաթեթավորվում է (package), ստորագրվում (sign) և հրապարակվում երկու ռեժիմներից մեկով.

  • Մասնավոր (ձեզ համար) — side-load ձեր instance-ի մեջ Ադմին UI-ի կամ publish --private-ի միջոցով։ Արտեֆակտը երբեք չի լքում instance-ը։
  • Հանրային (բոլորի համար) — publish --public-ը բացում է PR հանրային կատալոգի համար. վերանայումից հետո AiHummer-ը հակա-ստորագրում է թողարկումը և հրապարակում այն համայնքային կատալոգում։

Տես Փլագինի հրապարակում՝ ամբողջական ուղեցույցի համար։

Ո՞ւր հաջորդիվ