AiHummer
Norsk▾
Logg påKonto
v1.2.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Markedsplass og plugins/Plugin SDK

Plugin SDK

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

Et tillegg beskrives av en manifest.json. Kontrakten som validerer manifestet under utvikling er den samme som plattformen håndhever ved installasjon, så et manifest som godkjennes validate er et manifest markedet vil akseptere. aihummer plugin CLI dekker hele livssyklusen: fra stillas til signering og publisering.

Én manifest, én kontrakt

En plugin har nøyaktig én kilde til sannhet — sin manifest.json. Det erklærer plugin-typen (kind), hvordan det er konfigurert (config[]), dets kapasiteter, og — for vert-native tjenester — install[] trinn og startkommandoen som SystemdDistribusjon kjører. Fordi utvikling og installasjon bruker den samme valideringskontrakten, betyr “gyldig manifest” og “installerbart plugin” det samme.

[!NOTE] Manifestet beskriver en plugins kontrakt, ikke dens butikk-side navn. Den maskin slug kommer fra katalog-/pakkenavnet (privat side-last) eller fra innleveringen du fyller ut «Mine tillegg» når man publiserer en fellesskapsplugin — se Publisering av en plugin.

CLI

aihummer plugin pakker sammen kommandoene for utvikling, pakking og publisering:

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

Å utgi en samfunn plugin for alle, du gjør ikke bruk en CLI-kommando — du laster opp den pakkede, signerte artefakten fra din Mine plugins i det personlige kabinettet (last opp → AI-gjennomgang → moderasjon). Se Send inn et tillegg.

Kommando Hva det gjør
init <kind> [dir] Skriver en starter manifest.json for den utvalgte typen.
validate <m.json> Validerer manifestet med samme kontrakt som installasjon.
keygen Genererer forfatterens nøkkelpar: .key (privat, hold hemmelig) og .pub, skriver ut key id.
package <dir> Bygger (valgfritt) --build) og pakker inn i <slug>-<version>.tar.gz med en --strip-components=1 oppsett, skriver .sha256. Aldri pakker .env, *.key, node_modules, .git.
sign --key <priv> Tegn utslippsidentiteten; skriv ut signaturen og key id; med --manifest innebygger signaturen i manifestet.
publish --private Laster opp en pakke til instansen din POST /v1/admin/modules/upload.

Begge publiseringsveier — privat side-lasting og fellesskapspublisering via det personlige kabinettet — er detaljert på Publisering av en plugin.

Manifestfelt

Om et felt er påkrevd avhenger av snill og om pluginen er offentlig. Base- og identitetsfelt:

Felt Type Påkrevd Formål
kind streng alltid Type: connector | service | openapi | mcp.
version streng ja Plugin-versjon (semver), f.eks. 1.0.0.
contract streng for kanaler Kontrakt-ID, f.eks. aihummer.channel.v1.
scope streng nei Tilgangsmodell: shared (standard) eller personal.
capabilities streng[] nei Erklærte kapasiteter.
config objekt[] nei Konfigurer skjema felt; hvert trenger key, pluss label, secret, required.
oauth objekt nei OAuth2 (authorize_url, token_url, scopes[]) for å koble til en brukers konto.
signature streng når signert base64 ed25519-signatur over utgivelsesidentiteten (innlemmet av sign).

Arvespesifikke felt — nøyaktig én blokken fylles avhengig av kind:

Felt For snill Påkrevd Formål
host_native.exec_start kontakt, tjeneste ja Kommando som kjører den langvarige tjenesten.
host_native.runtime kobler, tjeneste, mcp nei node | python | binary.
host_native.install kobler, tjeneste, mcp nei Installasjonstrinn (rekkefølge av shell-kommandoer), kjør på verten etter utpakking.
host_native.port kontakt, tjeneste nei Foretrukket TCP-port (installatøren kan tildele en annen via $PORT).
host_native.health_path kontakt, tjeneste nei Helsetilsyn-sti (standard /healthz).
openapi.spec_url openapi ja URL til OpenAPI 3.x-spesifikasjonen.
openapi.base_url openapi nei Overstyre servers[0].url.
openapi.allowed_hosts openapi nei Tillatelsesliste for utgående trafikk for de syntetiserte verktøyene.
openapi.auth openapi nei Kart securityScheme → hemmelig navn.
openapi.tool_prefix openapi nei Verktøynavn-prefiks.
mcp.transport mcp ja stdio eller http.
mcp.command / mcp.args mcp (stdio) ja for stdio Serverkjørbar fil og argumenter.
mcp.url mcp (http) ja for http MCP-endepunkt-URL.
mcp.auth_header / mcp.secret_token_key mcp (http) nei Header og hemmelig nøkkel for bærertokenet.

Store-side og identitetsfelt (for fellesskapsplugins)

Manifestet kan også inneholde utgiveridentitet og butikksidefelt. For en samfunn plugin disse er det katalogen viser, men du skriver dem vanligvis inn i «Mine tillegg» store siden på din personlige konto ved innsending (navn, beskrivelser, ikon, skjermbilder, kategori, donasjonslenke) i stedet for manuelt i manifestet. En privat side-load trenger ingen av dem — en slik plugin er pålitelig på instansnivå.

Felt Type Påkrevd Formål
visibility streng nei public | private | unlisted. Tom = eldre/egenutviklet (ingen identitetskrav).
publisher streng for offentligheten Utgiver-navnerom, ^[a-z0-9][a-z0-9-]{1,38}$. Offentlige sneakere heter @publisher/slug.
publisher_key_id streng for offentligheten key id av nøkkelen artefakten er signert med.
description streng for offentligheten Kort beskrivelse på butikkens side i katalogen.
icon streng for offentligheten Plugin-ikon: en https:// URL eller en data: URI.
screenshots streng[] nei Store-side skjermbilder (array av https:// URL-er; hver ikke-tom).

[!TIP] Løp aihummer plugin validate før du sender inn. Installeringen og valideringen kontrakten er identisk, så et manifest som passer lokalt vil bli akseptert begge steder av markedsplassutplasseringen og av markedsplassvurderingen i ditt personlige skap.

Minimale manifester

A service stillas (hva aihummer plugin init service skriver):

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

En null-kode openapi manifestet er enda kortere — det peker bare på spesifikasjonen:

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

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

Fra manifest til marked

Etter validering pakkes en plugin (package), signert (sign) og publisert på en av to måter:

  • Privat (for deg selv) — last inn på siden i din instans via Admin UI eller publish --private. Artefakten forlater aldri instansen.
  • Samfunn (for alle) — last opp den pakkede, signerte artefakten fra Mine plugins i ditt personlige skap; etter AI-gjennomgang og menneskelig moderering blir det signert og publisert til samfunnet katalog.

Se Publisering av en plugin for den fullstendige gjennomgangen.

Hvor neste