Պլագինների զարգացման բազա — AiHummer Փաստաթղթեր

Պլագինը նկարագրվում է մեկ manifest.json ֆայլով։ Մշակման ընթացքում մանիֆեստը ստուգող պայմանագիրը նույնն է, ինչ հարթակն օգտագործում է տեղադրման ժամանակ, ուստի validate-ն անցած մանիֆեստը շուկան կընդունի։ aihummer plugin CLI-ն ընդգրկում է ամբողջ կյանքի ցիկլը՝ սկզբնական կառուցվածքից մինչև ստորագրում և հրապարակում։

Մեկ մանիֆեստ, մեկ պայմանագիր

Պլագինն ունի ընդամենը մեկ ճշմարտության աղբյուր՝ այն manifest.json. Նա հայտարարում է պլագինի տիպը (kind), ինչպես սա կարգավորված է (config[]), նրա հնարավորությունները և՝ հոստի վրա գործող ծառայությունների համար — 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>

Հրապարակել համայնք պլագին բոլորի համար, դուք անում եք ոչ օգտագործեք CLI հրամանը — դուք բեռնում եք փաթեթավորված, ստորագրված արհեստանյութը ձեր Իմ պլագինները անձնական կաբինետում (բեռնավորում → ԱՅ հասկացում → մոդերացիա): Տեսեք Ներկայացնել պլագին.

Թիմ	Ի՞նչ է սա անում
`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`	Բեռնավորում է փաթեթը ձեր օրինակ onto `POST /v1/admin/modules/upload`.

Երկու հրապարակման ուղիներն էլ՝ անձնական կողմնակի բեռնաթափում և համայնքի համար անձնական գրասենյակից հրապարակումը՝ մանրամասն նկարագրված են Պլագինի հրապարակում.

Մանիֆեստի դաշտեր

Պարտադիր դաշտը կախված է լավ և թե արդյոք պլագինը հանրային է: Հիմնական և ճանաչողական դաշտերը՝

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

Տիպին հատուկ դաշտեր — համաչափ մեկ բլոկը լրացված է կախված kind:

Արտ	Լավի համար	Պահանջվում է	Նպատակ
`host_native.exec_start`	կապիչ, սպասարկում	այո	Կոմանդա, որը սկսում է երկարաժամկետ ծառայություն։
`host_native.runtime`	կապիչ, ծառայություն, mcp	ոչ	`node` \| `python` \| `binary`.
`host_native.install`	կապիչ, ծառայություն, mcp	ոչ	Ներբեռման քայլերը (շելլի հրամանների զանգված), կատարեք հոստի վրա հանելուց հետո:
`host_native.port`	կապիչ, սպասարկում	ոչ	Ընտրյալ TCP պորտ (ծրագրավորողը կարող է փոխվել միջոցով `$PORT`).
`host_native.health_path`	կապիչ, սպասարկում	ոչ	Ստուգման վիճակի ուղի (ստանդարտ ըստ լռության) `/healthz`).
`openapi.spec_url`	օփենապի	այո	OpenAPI 3.x-ի սպեցիֆիկացիայի URL
`openapi.base_url`	օփենապի	ոչ	Վերահռչակել `servers[0].url`.
`openapi.allowed_hosts`	օփենապի	ոչ	Սպիտակ ցուցակ՝ արտահանվող տրաֆիկի համար արտադրված գործիքների համար։
`openapi.auth`	օփենապի	ոչ	Քարտ `securityScheme` → գաղտնի անուն.
`openapi.tool_prefix`	օփենապի	ոչ	Գործիքի անունի նախածանցը։
`mcp.transport`	մսր	այո	`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)	ոչ	Վերնագիր և գաղտնի բանալի կրիչի նշանի համար։

Խանութի և նույնացման էջի դաշտեր (համայնքային հավելումների համար)

Մանիֆեստում կարող են ընդգրկվել նաև հրատարակչի նույնացման տվյալները և խանութի էջի դաշտերը: համայնք պլագին, դա այն է, ինչ ցույց է տալիս կատալոգը, բայց սովորաբար դուք դրանք ներմուծում եք «Իմ պլագինները» խանութի էջը ձեր անձնական ֆոլիայում՝ ներկայացման ժամանակ (անուն, նկարագրություններ, պատկերակ, էկրանային լուսանկարներ, կատեգորիա, նվիրատվության հղում), այլ ոչ թե ձեռքով մանիֆեստում: Անձնական տեղադրումը ոչինչ այս ամենից չի պահանջում — նման պլագին է վստահված օբյեկտի մակարդակով։

Արտ	Տիպ	Պահանջվում է	Նպատակ
`visibility`	տող	ոչ	`public` \| `private` \| `unlisted`. Դատարկ = ժառանգական/առաջին կողմ (ոչ մի անձնվարչության պահանջ չկա)
`publisher`	տող	հասարակության համար	Տեղեկատվության հրատարակչի անվանակոչման տարածք, `^[a-z0-9][a-z0-9-]{1,38}$`. Հանրային սլագերը կոչվում են `@publisher/slug`.
`publisher_key_id`	տող	հասարակության համար	`key id` բանալով, որով ստորագրված է արդիականը.
`description`	տող	հասարակության համար	Խանութի էջի նկարագրություն կատալոգում։
`icon`	տող	հասարակության համար	Պլագինի պատկերակ: an `https://` URL կամ a `data:` URI.
`screenshots`	տող[]	ոչ	Խանութի էջի սքրինշոթներ (մասիվ `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 մանIFEST (տրանսպորտ 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. Արտեֆակտը երբեք չի լքում ինստանսը.
Համայնք (բոլորի համար) — ներբեռնեք հավաքած, ստորագրված արհեստը Իմ պլագինները ձեր անձնական հաշվի մեջ; ԱՏ-ի վերանայման և մարդկային moderation-ից հետո այն ստորագրվում և հրապարակվում է համայնքին կատալոգ

տեսնել Պլագինի հրապարակում մի ամբողջական քայլ առ քայլ ուղեցույցի համար:

Որտեղից հետո

Պլագինի հրապարակում — մասնավոր կողմնակի բեռնավորում և հասարակական հրապարակում անձնական գրասենյակից, ստուգում և մոդերացիա։
Անկոդ ինտեգրացիաներ — սա openapi և mcp տեսակները մանրամասն.
Տեղադրում և թարմացումներ — ինչ է շարժում install[], առողջության դարպասներ, վստահություն և ստորագրված թարմացումներ։
Մարկետփլեյս՝ ակնարկ և մակարդակներ — որտեղ յուրաքանչյուր տեսակ ապրում է և ինչպես պաշտոնական կատալոգն է տարբերվում համայնքից։