AiHummer
Română▾
AutentificareCont personal
v1.2.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Marketplace și pluginuri/SDK pentru plugin

SDK pentru plugin

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

Un plugin este descris de unu manifest.json. Contractul care validează manifestul în timpul dezvoltării este același pe care platforma îl aplică la momentul instalării, astfel încât un manifest care trece validate este un manifest pe care piața îl va accepta. aihummer plugin CLI acoperă întregul ciclu de viață: de la schelet până la semnare și publicare.

Un manifest, un contract

Un plugin are exact o singură sursă de adevăr — a sa manifest.json. Declară tipul pluginului (kind), cum este configurat (config[]), capacitățile sale și — pentru serviciile native găzduite — install[] pași și comanda de pornire care DeploratorSystemd rulează. Deoarece dezvoltarea și instalarea folosesc același contract de validare, „manifest valid” și „plugin instalabil” înseamnă același lucru.

[!NOTE] Manifestul descrie un plugin contract, nu numele său de pe pagina magazinului. mașină slug provine din numele directorului/pachetului (încărcare laterală privată) sau din formularul pe care îl completați «Pluginurile mele» când publici un plugin pentru comunitate — vede Publicarea unui plugin.

CLI

aihummer plugin împachetează comenzile de dezvoltare, ambalare și publicare:

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

A publica un comunitate plugin pentru toată lumea, tu faci nu folosește o comandă CLI — încarci artefactul ambalat și semnat de la tine Pluginurile mele în cabinetul personal (încărcare → revizuire AI → moderare). Vezi Trimite un plugin.

Comandă Ce face
init <kind> [dir] Scrie un început manifest.json pentru specia aleasă.
validate <m.json> Validează manifestul cu același contract ca instalarea.
keygen Generează perechea de chei a autorului: .key (privat, păstrează secret) și .pub, tipărește key id.
package <dir> Construcții (opțional) --build) și se împachetează în <slug>-<version>.tar.gz cu un --strip-components=1 aspect, scrie .sha256. Niciodată pachete .env, *.key, node_modules, .git.
sign --key <priv> Semnează identitatea eliberării; tipărește semnătura și key id; cu --manifest încorporează semnătura în manifest.
publish --private Încarcă un pachet în instanța ta POST /v1/admin/modules/upload.

Ambele căi de publicare — încărcarea privată laterală și publicarea în comunitate prin intermediul cabinetului personal — sunt detaliate pe Publicarea unui plugin.

Câmpuri de manifest

Dacă un câmp este obligatoriu depinde de amabil și dacă pluginul este public. Câmpurile de bază și de identitate:

Câmp Tip Necesar Scop
kind șir întotdeauna Încântat connector | service | openapi | mcp.
version șir da Versiunea pluginului (semver), de exemplu 1.0.0.
contract șir pentru canale ID contract, de exemplu aihummer.channel.v1.
scope șir nu Model de acces: shared (implicit) sau personal.
capabilities șir[] nu Capabilități declarate.
config obiect[] nu Configurați câmpurile formularului; fiecare are nevoie key, plus label, secret, required.
oauth obiect nu OAuth2 (authorize_url, token_url, scopes[]) pentru a conecta contul unui utilizator.
signature șir când este semnat semnătură base64 ed25519 asupra identității versiunii (încorporată de sign).

Câmpuri specifice tipului — exact unul blocul este umplut în funcție de kind:

Câmp Pentru amabil Necesar Scop
host_native.exec_start conector, serviciu da Comandă care rulează serviciul cu durată lungă de viață.
host_native.runtime conector, serviciu, mcp nu node | python | binary.
host_native.install conector, serviciu, mcp nu Pași de instalare (șir de comenzi shell), rulați pe gazdă după extragere.
host_native.port conector, serviciu nu Port TCP preferat (deployantul poate reasigna prin $PORT).
host_native.health_path conector, serviciu nu Cale de verificare a stării de sănătate (implicit /healthz).
openapi.spec_url openapi da URL-ul specificației OpenAPI 3.x.
openapi.base_url openapi nu Suprascriere servers[0].url.
openapi.allowed_hosts openapi nu Lista de permisiuni de ieșire pentru instrumentele sintetizate.
openapi.auth openapi nu Harta securityScheme → nume secret.
openapi.tool_prefix openapi nu Prefixul numelui instrumentului.
mcp.transport mcp da stdio sau http.
mcp.command / mcp.args mcp (stdio) da pentru stdio Executabilul serverului și argumentele.
mcp.url mcp (http) da pentru http URL-ul endpoint MCP.
mcp.auth_header / mcp.secret_token_key mcp (http) nu Antet și cheie secretă pentru tokenul de tip bearer.

Pagina magazin și câmpuri de identitate (pentru pluginuri comunitare)

Manifestul poate de asemenea să conțină identitatea editorului și câmpurile paginii de magazin. Pentru un comunitate plugin acestea sunt ceea ce arată catalogul, dar de obicei le introduci în «Pluginurile mele» pagina magazinului în cabinetul tău personal la momentul trimiterii (nume, descrieri, pictogramă, capturi de ecran, categorie, link de donație) mai degrabă decât manual în manifest. Un side-load privat nu are nevoie de niciunul dintre ele — un astfel de plugin este de încredere la nivel de instanță.

Câmp Tip Necesar Scop
visibility șir nu public | private | unlisted. Gol = moștenire/prima parte (fără cerință de identitate).
publisher șir pentru public Spațiu de nume al editorului, ^[a-z0-9][a-z0-9-]{1,38}$. Melcii publici sunt numiți @publisher/slug.
publisher_key_id șir pentru public key id cu cheia cu care este semnat artefactul.
description șir pentru public Descrierea paginii magazinului în catalog.
icon șir pentru public Pictogramă plugin: un https:// URL sau un data: URI.
screenshots șir[] nu Capturi de ecran ale paginii magazinului (șir de https:// URL-uri; fiecare nenulă).

[!TIP] Aleargă aihummer plugin validate înainte de a trimite. Instalarea și validarea contractul este identic, astfel încât un manifest care trece local va fi acceptat în ambele de către distribuitorul pieței și de către recenzia pieței în cabinetul tău personal.

Manifestări minimale

A service schelă (ce aihummer plugin init service scrie):

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

Fără cod openapi manifestul este și mai scurt — el doar indică spre specificație:

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

Un mcp manifest (transport 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"] }
}

De la manifest la piață

După validare, un plugin este ambalat (package), semnat (sign) și publicat în unul dintre două moduri:

  • Privat (pentru tine) — încărcați lateral în instanța dvs. prin interfața de administrare sau publish --private. Artefactul nu părăsește niciodată instanța.
  • Comunitate (pentru toată lumea) — încarcă artefactul ambalat, semnat de la Pluginurile mele în cabinetul tău personal; după revizuirea AI și moderarea umană, este semnat și publicat în comunitate catalog.

Vede Publicarea unui plugin pentru ghidul complet.

Unde următor