AiHummer
Dansk▾
Log indKonto
v1.1.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Markedsplads og plugins/Plugin SDK

Plugin SDK

v1.1.x · opdateret 2026-06-27

Et plugin beskrives af en manifest.json. Kontrakten, der validerer manifestet under udvikling, er den samme, som platformen håndhæver ved installation, så et manifest, der består validate er et manifest, som markedet vil acceptere. Den aihummer plugin CLI dækker hele livscyklussen: fra stillads til underskrift og udgivelse.

Én manifest, én kontrakt

Et plugin har præcis én sandhedskilde — dens manifest.json. Det erklærer plugin-typen (kind), hvordan det er konfigureret (config[]), dets kapaciteter, og — for vært-native tjenester — install[] trin og startkommandoen, der SystemdDeployer kører. Fordi udvikling og installation bruger den samme valideringskontrakt, betyder “gyldig manifest” og “installerbar plugin” det samme.

[!NOTE] Manifestet beskriver en plugins kontrakt, ikke dens butiks-sidenavn. Den maskine slug kommer fra mappen/bundtet navnet (privat sideindlæsning) eller fra den indsendelse, du udfylder «Mine plugins» når man udgiver et fællesskabsplugin — se Publicering af en plugin.

CLI

aihummer plugin samler udviklings-, pakke- og udgivelseskommandoerne:

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

At udgive en samfund plugin til alle, du gør ikke brug en CLI-kommando — du uploader den pakkede, signerede artefakt fra din Mine plugins i det personlige kabinet (upload → AI-gennemgang → moderation). Se Indsend et plugin.

Kommando Hvad det gør
init <kind> [dir] Skriver en starter manifest.json for den valgte slags.
validate <m.json> Validerer manifestet med samme kontrakt som install.
keygen Genererer forfatterens nøglepar: .key (privat, hold hemmeligt) og .pub, udskriver key id.
package <dir> Bygger (valgfri) --build) og pakker i <slug>-<version>.tar.gz med en --strip-components=1 layout, skriver .sha256. Pakker aldrig .env, *.key, node_modules, .git.
sign --key <priv> Tegn frigivelsesidentiteten; udskriver signaturen og key id; med --manifest indlejrer signaturen i manifestet.
publish --private Uploader en pakke til din instances POST /v1/admin/modules/upload.

Begge udgivelsesveje — privat side-indlæsning og fællesskabsudgivelse via det personlige kabinet — er beskrevet på Publicering af en plugin.

Manifestfelter

Om et felt er påkrævet afhænger af venlig og om plugin’et er offentligt. Base- og identitetsfelter:

Mark Type Påkrævet Formål
kind streng altid Venlig: connector | service | openapi | mcp.
version streng ja Plugin-version (semver), f.eks. 1.0.0.
contract streng for kanaler Kontrakt-ID, f.eks. aihummer.channel.v1.
scope streng nej Adgangsmodel: shared (standard) eller personal.
capabilities streng[] nej Deklarerede kapaciteter.
config objekt[] nej Konfigurer formularfelter; hver har brug for key, plus label, secret, required.
oauth objekt nej OAuth2 (authorize_url, token_url, scopes[]) for at tilslutte en brugers konto.
signature streng når underskrevet base64 ed25519-signatur over udgivelsesidentiteten (indlejret af sign).

Arts-specifikke felter — præcis én blokken bliver fyldt afhængigt af kind:

Mark For venlig Påkrævet Formål
host_native.exec_start forbinder, tjeneste ja Kommando, der kører den langvarige tjeneste.
host_native.runtime forbinder, service, mcp nej node | python | binary.
host_native.install forbinder, tjeneste, mcp nej Installationstrin (array af shell-kommandoer), kør på værten efter udpakning.
host_native.port forbinder, tjeneste nej Foretrukken TCP-port (udruleren kan tildele en anden via $PORT).
host_native.health_path forbinder, tjeneste nej Health-check-sti (standard /healthz).
openapi.spec_url openapi ja URL’en på OpenAPI 3.x-specifikationen.
openapi.base_url openapi nej Overskriv servers[0].url.
openapi.allowed_hosts openapi nej Tilladelsesliste for udgående trafik for de syntetiserede værktøjer.
openapi.auth openapi nej Kort securityScheme → hemmeligt navn.
openapi.tool_prefix openapi nej Værktøjsnavn præfiks.
mcp.transport mcp ja stdio eller http.
mcp.command / mcp.args mcp (stdio) ja for stdio Server eksekverbar fil og argumenter.
mcp.url mcp (http) ja for http MCP-endepunkt URL.
mcp.auth_header / mcp.secret_token_key mcp (http) nej Header og hemmelig nøgle til bærer-tokenet.

Store-side og identitetsfelter (for fællesskabsplugins)

Manifestet kan også indeholde udgiveridentitet og butikssidefelter. For en samfund plugin disse er, hvad kataloget viser, men du indtaster dem normalt i «Mine plugins» store side i dit personlige kabinet på indsendelsestidspunktet (navn, beskrivelser, ikon, skærmbilleder, kategori, donationslink) i stedet for manuelt i manifestet. En privat side-indlæsning har ingen af dem brug for — sådan en plugin er betroet på instansniveau.

Mark Type Påkrævet Formål
visibility streng nej public | private | unlisted. Tom = ældre/first-party (ingen identitetskrav).
publisher streng for offentligheden Udgiver-namespace, ^[a-z0-9][a-z0-9-]{1,38}$. Offentlige sneakere er navngivet @publisher/slug.
publisher_key_id streng for offentligheden key id af nøglen artefakten er underskrevet med.
description streng for offentligheden Stor-sides tekst i katalogen.
icon streng for offentligheden Plugin-ikon: en https:// URL eller en data: URI.
screenshots streng[] nej Store-side screenshots (array af https:// URL’er; hver ikke-tomme).

[!TIP] Løb aihummer plugin validate før du indsender. Installationen og valideringen kontrakterne er identiske, så et manifest, der passer lokalt, vil blive accepteret begge steder af markedspladsudstederen og af markedspladsanmeldelsen i dit personlige kabinet.

Minimal manifester

A service stillads (hvad 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 nul-kode openapi manifestet er endnu kortere — det peger bare på specifikationen:

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

Efter validering pakkes et plugin (package), underskrevet (sign) og offentliggjort på en af to måder:

  • Privat (for dig selv) — sidelæs ind i din instans via Admin UI eller publish --private. Artefakten forlader aldrig instansen.
  • Fællesskab (for alle) — upload den pakkede, signerede artefakt fra Mine plugins i dit personlige kabinet; efter AI-gennemgang og menneskelig moderation bliver det underskrevet og offentliggjort for fællesskabet katalog.

Se Publicering af en plugin for den fulde gennemgang.

Hvorhen næste