AiHummer
Eesti▾
SisselogimineKonto
v1.2.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Turg ja lisandmoodulid/Plugina SDK

Plugina SDK

v1.2.x · uuendatud 2026-06-27

Plugin kirjeldatakse kui üks manifest.json. Leping, mis kinnitab manifesteerimist arendamise ajal, on sama, mida platvorm rakendab installimisel, seega manifesteerimine, mis läbib validate on manifest, mida turg aktsepteerib. aihummer plugin CLI katab kogu elutsükli: alates raamistikust kuni allkirjastamise ja avaldamiseni.

Üks manifeest, üks leping

Laiendil on täpselt üks tõeallikas — selle manifest.json. See deklareerib pistikprogrammi tüübi (kind), kuidas see on seadistatud (config[]), selle võimekuse ja — hosti-põhiste teenuste puhul — install[] sammud ja käivituskäsk, mis SystemdDeployer töötab. Kuna arendamine ja paigaldamine kasutavad sama valideerimislepingut, tähendavad „kehtiv manifest“ ja „paigaldatav plugin“ sama asja.

[!NOTE] Manifest kirjeldab pistikprogrammi leping, mitte selle poe lehe nimi. masin slug tuleb kataloogi/paki nimest (privaatne külglaadimine) või sellest täidetav esitamine «Minu pistikprogrammid» kogukonna pistikprogrammi avaldamisel — see Plugina avaldamine.

Käsklusrida

aihummer plugin koondab arenduse, pakendamise ja avaldamise käsud:

# 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>

Avaldada kogukond plugin kõigile, sina teed ei kasutage CLI käsku — laadite üles pakitud, allkirjastatud artefakti oma Minu pluginad isiklikus kabinetis (laadi üles → tehisintellekti ülevaatus → modereerimine). Vaata Esita pistikprogramm.

Käsk Mida see teeb
init <kind> [dir] Kirjutab algaja manifest.json valitud tüübi jaoks.
validate <m.json> Kontrollib manifesti sama lepingu alusel nagu install.
keygen Genereerib autori võtme paari: .key (privaatne, hoia saladuses) ja .pub, prindib key id.
package <dir> Versioonid (valikuline) --build) ja pakib sisse <slug>-<version>.tar.gz koos --strip-components=1 paigutus, kirjutab .sha256. Ei paki kunagi .env, *.key, node_modules, .git.
sign --key <priv> Allkirjastab vabastuse identiteedi; trükib allkirja ja key id; koos --manifest manustab allkirja manifesti sisse.
publish --private Laadib teie eksemplari jaoks paketi üles POST /v1/admin/modules/upload.

Mõlemad avaldamise teed — privaatne külglaadimine ja kogukonna avaldamine isikliku kontori kaudu — on üksikasjalikult kirjeldatud Plugina avaldamine.

Manifesti väljad

Kas väli on nõutav, sõltub sellest lahke ja kas pistikprogramm on avalik. Baasi- ja identiteediväljad:

Väli Tüüp Nõutav Eesmärk
kind string alati Sõbralik connector | service | openapi | mcp.
version string jah Pistikprogrammi versioon (semver), nt. 1.0.0.
contract string kanalite jaoks Lepingu ID, nt aihummer.channel.v1.
scope string ei Juurdepääsumudel: shared (vaikimisi) või personal.
capabilities string[] ei Deklareeritud võimed.
config objekt[] ei Seadista vormiväljad; igaüht on vaja key, pluss label, secret, required.
oauth ese ei OAuth2 (authorize_url, token_url, scopes[]) kasutaja konto ühendamiseks.
signature string allkirjastamisel base64 ed25519 allkiri väljalaske identiteedi üle (manustatud poolt sign).

Tüübispetsiifilised väljad — täpselt üks plokk täidetakse sõltuvalt kind:

Väli Hea jaoks Nõutav Eesmärk
host_native.exec_start liides, teenus jah Käsk, mis käivitab pikaajaliselt töötava teenuse.
host_native.runtime liides, teenus, mcp ei node | python | binary.
host_native.install liides, teenus, mcp ei Paigaldusetapid (shell-käskude massiiv), käivitage hostil pärast pakkimist lahtipakkimist.
host_native.port liides, teenus ei Eelistatud TCP-port (paigaldaja võib vajadusel määrata uuesti kaudu $PORT).
host_native.health_path liides, teenus ei Tervisekontrolli tee (vaikimisi /healthz).
openapi.spec_url avatudliides jah OpenAPI 3.x spetsifikatsiooni URL.
openapi.base_url avatudliides ei Ülekirjutamine servers[0].url.
openapi.allowed_hosts avatudliides ei Väljuva liikluse lubatud nimekiri sünteesitud tööriistade jaoks.
openapi.auth avatudliides ei Kaart securityScheme → salanimi.
openapi.tool_prefix avatudliides ei Tööriista nime eesliide.
mcp.transport mcp jah stdio või http.
mcp.command / mcp.args mcp (stdio) jah stdio jaoks Serveri käivitatav fail ja argumendid.
mcp.url mcp (http) jah http jaoks MCP lõpp-punkti URL.
mcp.auth_header / mcp.secret_token_key mcp (http) ei Päis ja salavõti kandjatokeni jaoks.

Pood-lehekülje ja identiteedi väljad (kogukonna pistikprogrammide jaoks)

Manifest võib samuti kanda kirjastaja identiteedi ja poe-lehe välju. Selleks kogukond pluginid, need on need, mida kataloog näitab, kuid tavaliselt sisestate need «Minu pistikprogrammid» poodi lehekülg teie isiklikus kabinetis esitamise ajal (nimi, kirjeldused, ikoon, ekraanipildid, kategooria, annetuse link) mitte käsitsi manifesti kaudu. Eravastupuu laadimine ei vaja neist ühtegi — selline plugin on usaldusväärne instantsi tasemel.

Väli Tüüp Nõutav Eesmärk
visibility string ei public | private | unlisted. Tühi = pärand/esmase osapoole (identiteedi nõuet ei ole).
publisher string avalikuks Väljaandja nimetüüp ^[a-z0-9][a-z0-9-]{1,38}$. Avalikke limuseid nimetatakse @publisher/slug.
publisher_key_id string avalikuks key id võtme all, millega artifakt on allkirjastatud.
description string avalikuks Poe lehe kirjeldus kataloogis.
icon string avalikuks Pistikprogrammi ikoon: an https:// URL või a data: URI.
screenshots string[] ei Poe lehe kuvatõmmised (järjend https:// URL-id; iga mitte-tühi).

[!TIP] Jookse aihummer plugin validate enne kui esitate. Paigaldamine ja valideerimine leping on identsed, nii et manifes, mis läbib kohalikult, aktsepteeritakse mõlemal turuväljaandja poolt ja turu ülevaatuse poolt teie isiklikus kabinetis.

Minimaalne avaldus

A service telling aihummer plugin init service kirjutab):

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

Nullkood openapi manifest on veelgi lühem — see viitab lihtsalt spetsifikatsioonile:

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

Üks 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"] }
}

Manifetist turule

Pärast valideerimist pakitakse pistikprogramm (package), allkirjastatud (sign) ja avaldatud ühel kahest viisil:

  • Privaatne (enda jaoks) — paigalda oma eksemplari kaudu Admin UI või publish --private. Artefakt ei lahku kunagi eksemplarist.
  • Kogukond (kõigile) — laadige üles pakitud, allkirjastatud artefakt aadressilt Minu pluginad teie isiklikus kabinetis; pärast tehisintellekti ülevaatust ja inimese modereerimist see allkirjastatakse ja avaldatakse kogukonnale kataloog.

See Plugina avaldamine täieliku juhendi jaoks.

Kuhu edasi