AiHummer
Lietuvių▾
PrisijungtiPaskyra
v1.0.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Turgavietė ir įskiepiai/Įskiepio SDK

Įskiepio SDK

v1.0.x · atnaujinta 2026-06-27

Įskiepis apibūdinamas vienas manifest.json. Sutartis, kuri patvirtina manifestą kūrimo metu, yra ta pati, kurią platforma taiko įdiegimo metu, todėl manifestas, kuris praeina validate tai yra manifestas, kurį rinka priims. aihummer plugin CLI apima visą gyvavimo ciklą: nuo karkaso kūrimo iki pasirašymo ir publikavimo.

Viena deklaracija, viena sutartis

Papildinys turi tik vieną tiesos šaltinį – savo manifest.json. Jis nurodo įskiepio tipą (kind), kaip tai sukonfigūruota (config[]), jo galimybes ir — vietinių pagrindinių paslaugų atveju — install[] žingsniai ir starto komanda, kuri SystemdDiegėjas veikia. Kadangi kūrimas ir diegimas naudoja tą patį patikrinimo susitarimą, „galiojantis manifestas“ ir „įdiegiamas įskiepis“ reiškia tą patį.

[!NOTE] Manifestas aprašo įskiepio sutartis, o ne jo parduotuvės puslapio pavadinimas. mašina slug atsiranda iš katalogo/paketo pavadinimo (privatus perkėlimas) arba iš pateikimas, kurį užpildote «Mano įskiepiai» kai skelbiama bendruomenės įskiepiai — žiūrėti Įskiepio publikavimas.

CLI

aihummer plugin surenka vystymo, pakavimo ir publikavimo komandas:

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

Paskelbti bendruomenė įskiepis visiems, tu darai ne naudokite CLI komandą — jūs įkeliat supakuotą, pasirašytą artefaktą iš savo Mano įskiepiai asmeniniame kabinete (įkelti → AI peržiūra → moderavimas). Žr. Pateikti papildinį.

Komanda Ką tai daro
init <kind> [dir] Rašo pradžią manifest.json pasirinktai rūšiai.
validate <m.json> Tvirtina manifestą pagal tą patį sutartį kaip diegimas.
keygen Sugeneruoja autoriaus raktų porą: .key (privatu, laikyti paslaptyje) ir .pub, spausdina key id.
package <dir> Statyba (pasir.) --build) ir pakuoja į <slug>-<version>.tar.gz su --strip-components=1 išdėstymas, rašo .sha256. Niekada nepakuoja .env, *.key, node_modules, .git.
sign --key <priv> Pasirašo išleidimo tapatybę; atspausdina parašą ir key id; su --manifest įterpia parašą į manifestą.
publish --private Įkelia paketą į jūsų egzempliorių POST /v1/admin/modules/upload.

Abi leidybos kryptys – privatus papildomas diegimas ir bendruomenės leidyba per asmeninę kabinetą – išsamiai aptariamos Įskiepio publikavimas.

Manifesto laukai

Ar laukas yra privalomas, priklauso nuo geras ir ar įskiepis yra viešas. Baziniai ir tapatybės laukai:

Laukas Tipas Privalomas Tikslas
kind eilutė visada Rūšis: connector | service | openapi | mcp.
version eilutė taip Įskiepio versija (semver), pvz. 1.0.0.
contract eilutė kanalams Sutarties ID, pvz. aihummer.channel.v1.
scope eilutė ne Prieigos modelis: shared (numatytasis) arba personal.
capabilities eilutė[] ne Deklaruotos galimybės.
config objektas[] ne Konfigūracijos formos laukai; kiekvienas reikia key, plius label, secret, required.
oauth objektas ne OAuth2 (authorize_url, token_url, scopes[]) prisijungti prie vartotojo paskyros.
signature eilutė kai pasirašyta base64 ed25519 parašas ant leidimo tapatybės (įterptas pagal sign).

Laimės specifiniai laukeliai — būtent vienas blokas užpildomas priklausomai nuo kind:

Laukas Už malonę Privalomas Tikslas
host_native.exec_start jungtis, paslauga taip Komanda, kuri paleidžia ilgai veikiančią paslaugą.
host_native.runtime jungtis, paslauga, mcp ne node | python | binary.
host_native.install jungtis, paslauga, mcp ne Įdiegimo žingsniai (šeimininko komandas masyve), vykdykite pasirodžiusiame išskleidę faile.
host_native.port jungtis, paslauga ne Pageidaujamas TCP prievadas (diegėjas gali perskirstyti per $PORT).
host_native.health_path jungtis, paslauga ne Sveikatos patikros kelias (numatytasis /healthz).
openapi.spec_url openapi taip OpenAPI 3.x specifikacijos URL.
openapi.base_url openapi ne Perrašyti servers[0].url.
openapi.allowed_hosts openapi ne Išėjimo leidimų sąrašas sintetizuotoms priemonėms.
openapi.auth openapi ne Žemėlapis securityScheme → slaptas vardas.
openapi.tool_prefix openapi ne Įrankio pavadinimo prefiksas.
mcp.transport mcp taip stdio arba http.
mcp.command / mcp.args mcp (stdio) taip stdio Serverio vykdomoji byla ir argumentai.
mcp.url mcp (http) taip http MCP galinio taško URL.
mcp.auth_header / mcp.secret_token_key mcp (http) ne Antraštė ir slaptasis raktas nešėjo žetone.

Parduotuvės puslapio ir identifikacijos laukai (bendruomenės papildiniams)

Manifestas taip pat gali turėti leidėjo tapatybės ir parduotuvės puslapio laukus. Dėl bendruomenė įskiepiai, tai yra tai, ką rodo katalogas, bet paprastai juos įvedate į «Mano įskiepiai» parduotuvės puslapis jūsų asmeniniame kabinete pateikimo metu (pavadinimas, aprašymai, piktograma, ekrano kopijos, kategorija, aukojimo nuoroda), o ne rankiniu būdu manifeste. Privatus šoninis įkėlimas jų nereikalauja — toks papildinys yra patikimas instancijos lygiu.

Laukas Tipas Privalomas Tikslas
visibility eilutė ne public | private | unlisted. Tuščia = senoji/pirminė (nereikalaujama tapatybės).
publisher eilutė viešam Leidėjo vardų sritis, ^[a-z0-9][a-z0-9-]{1,38}$. Viešieji šliužai pavadinti @publisher/slug.
publisher_key_id eilutė viešam key id tai, kuriuo raktu pasirašytas artefaktas.
description eilutė viešam Parduotuvės puslapio aprašymas kataloge.
icon eilutė viešam Priedo piktograma: an https:// URL arba a data: URI.
screenshots eilutė[] ne Parduotuvės puslapio ekrano kopijos (masyvas iš https:// URL; kiekvienas ne tuščias).

[!TIP] Bėgti aihummer plugin validate prieš pateikdami. Diegimas ir patikrinimas sutartis yra identiška, todėl manifestas, kuris praeina vietoje, bus priimtas abiejose turgavietės diegėjas ir turgavietės peržiūra jūsų asmeniniame kabinete.

Minimalūs manifestai

A service pastoliai (kas aihummer plugin init service rašo):

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

Nulinis kodas openapi manifestas yra dar trumpesnis — jis tiesiog nurodo į specifikaciją:

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

Vienas mcp manifestas (stdio transportas):

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

Nuo manifesto iki rinkos

Po patikrinimo, papildinys yra supakuojamas (package), pasirašyta (sign) ir paskelbta vienu iš dviejų būdų:

  • Privatus (sau) — šoniniu įkėlimu į savo instanciją per Administratoriaus sąsają arba publish --private. Šis artefaktas niekada nepalieka instancijos.
  • Bendruomenė (visiems) — įkelkite supakuotą, pasirašytą artefaktą iš Mano įskiepiai jūsų asmeniniame kabinete; po DI peržiūros ir žmogaus moderavimo jis pasirašomas ir paskelbtas bendruomenei katalogas.

Matyti Įskiepio publikavimas pilnam vadovui.

Kur toliau