AiHummer
Svenska▾
Logga inKonto
v1.2.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Marknadsplats och tillägg/Plugin-SDK

Plugin-SDK

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

Ett tillägg beskrivs av en manifest.json. Kontraktet som validerar manifestet under utveckling är samma som plattformen upprätthåller vid installation, så ett manifest som passerar validate är ett manifest som marknadsplatsen kommer att acceptera. Den aihummer plugin CLI täcker hela livscykeln: från scaffold till signering och publicering.

Ett manifest, ett kontrakt

Ett plugin har exakt en källa till sanning — dess manifest.json. Det deklarerar plugin-typen (kind), hur det är konfigurerat (config[]), dess kapabiliteter, och — för tjänster som är inhemska på värddatorn — install[] steg och startkommando som SystemdDistribuerare kör. Eftersom utveckling och installation använder samma valideringskontrakt betyder “giltigt manifest” och “installerbart plugin” samma sak.

[!NOTE] Manifestet beskriver ett plugins kontrakt, inte dess butiks-sidans namn. maskin slug kommer från katalog-/paketnamnet (privat sidoladdning) eller från inlämningen du fyller i «Mina tillägg» när man publicerar ett community-plugin — se Publicera ett plugin.

CLI

aihummer plugin paketerar utvecklings-, paketerings- och publiceringskommandon:

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

Att publicera en gemenskap plugin för alla, du gör inte använd ett CLI-kommando — du laddar upp den paketerade, signerade artefakten från din Mina tillägg i det personliga skåpet (ladda upp → AI-granskning → moderation). Se Skicka in ett tillägg.

Kommando Vad det gör
init <kind> [dir] Skriver en start manifest.json för den utvalda sorten.
validate <m.json> Validerar manifestet med samma kontrakt som install.
keygen Genererar författarens nyckelpar: .key (privat, håll hemligt) och .pub, skriver ut key id.
package <dir> Bygger (valfritt) --build) och packar i <slug>-<version>.tar.gz med en --strip-components=1 layout, skriver .sha256. Packar aldrig .env, *.key, node_modules, .git.
sign --key <priv> Signer te utsläppsidentiteten; skriver ut signaturen och key id; med --manifest bäddar in signaturen i manifestet.
publish --private Laddar upp ett paket till din instans POST /v1/admin/modules/upload.

Båda publiceringsvägarna — privat sidoladdning och communitypublicering via det personliga skåpet — beskrivs i detalj på Publicera ett plugin.

Manifestfält

Om ett fält är obligatoriskt beror på snäll och om plugin-programmet är offentligt. Bas- och identitetsfält:

Fält Typ Obligatorisk Syfte
kind sträng alltid Typ: connector | service | openapi | mcp.
version sträng ja Plugin-version (semver), t.ex. 1.0.0.
contract sträng för kanaler Kontrakt-ID, t.ex. aihummer.channel.v1.
scope sträng nej Åtkomstmodell: shared (standard) eller personal.
capabilities sträng[] nej Deklarerade kapaciteter.
config objekt[] nej Konfigurera formulärfält; varje behöver key, plus label, secret, required.
oauth objekt nej OAuth2 (authorize_url, token_url, scopes[]) för att ansluta en användares konto.
signature sträng när undertecknad base64 ed25519-signatur över utgåvans identitet (inbäddad av sign).

Artypsspecifika fält — exakt en blocket fylls beroende på kind:

Fält För snäll Obligatorisk Syfte
host_native.exec_start kontakt, tjänst ja Kommando som kör den långlivade tjänsten.
host_native.runtime kontakt, tjänst, mcp nej node | python | binary.
host_native.install kontakt, tjänst, mcp nej Installationssteg (array av shell-kommandon), kör på värddatorn efter extraktion.
host_native.port kontakt, tjänst nej Föredragen TCP-port (installatören kan tilldela om via $PORT).
host_native.health_path kontakt, tjänst nej Hälsokontrollväg (standard /healthz).
openapi.spec_url openapi ja URL för OpenAPI 3.x-specifikationen.
openapi.base_url openapi nej Åsidosätta servers[0].url.
openapi.allowed_hosts openapi nej Tillträdeslista för utgående trafik för de syntetiserade verktygen.
openapi.auth openapi nej Karta securityScheme → hemligt namn.
openapi.tool_prefix openapi nej Verktygsnamnsprefix.
mcp.transport mcp ja stdio eller http.
mcp.command / mcp.args mcp (stdio) ja för stdio Serverkörbar fil och argument.
mcp.url mcp (http) ja för http MCP-slutpunktens URL.
mcp.auth_header / mcp.secret_token_key mcp (http) nej Header och hemlig nyckel för bearer-token.

Store-sida och identitetsfält (för community-tillägg)

Manifestet kan också innehålla utgivaridentitet och fält för butikssida. För en gemenskap plugin dessa är vad katalogen visar, men du brukar normalt skriva in dem i «Mina tillägg» butikssida i ditt personliga konto vid inskickningstillfället (namn, beskrivningar, ikon, skärmdumpar, kategori, donationslänk) istället för för hand i manifestet. En privat sidoladdning behöver ingen av dem — ett sådant plugin är betrott på instansnivå.

Fält Typ Obligatorisk Syfte
visibility sträng nej public | private | unlisted. Tom = legacy/förstapart (inga identitetskrav).
publisher sträng för allmänheten Publicerarrollsnamn, ^[a-z0-9][a-z0-9-]{1,38}$. Offentliga sniglar är namngivna @publisher/slug.
publisher_key_id sträng för allmänheten key id med vilken nyckeln artefakten är signerad.
description sträng för allmänheten Kort beskrivning på butiksidan i katalogen.
icon sträng för allmänheten Plugin-ikon: ett https:// URL eller en data: URI.
screenshots sträng[] nej Skärmdumpar från butikssidan (fält av https:// URL:er; varje icke-tom).

[!TIP] Spring aihummer plugin validate innan du skickar in. Installationen och valideringen kontrakt är identiska, så ett manifest som passerar lokalt kommer att accepteras båda av marknadsplatsens utplacerare och av marknadsplatsens granskning i ditt personliga kabinett.

Minimala manifester

A service ställning (vad 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 nollkod openapi manifest är ännu kortare — det pekar bara 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"] }
}

Från manifest till marknadsplats

Efter validering paketeras ett plugin (package), undertecknad (sign) och publicerad på ett av två sätt:

  • Privat (för dig själv) — sidoladda in i din instans via Admin UI eller publish --private. Artefakten lämnar aldrig instansen.
  • Gemenskap (för alla) — ladda upp det paketerade, signerade artefaktet från Mina tillägg i ditt personliga skåp; efter AI-granskning och mänsklig moderation signeras det och publiceras till gemenskapen katalog.

Se Publicera ett plugin för den fullständiga genomgången.

Vart härnäst