AiHummer
Deutsch▾
AnmeldenKonto
v1.1.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Marktplatz und Plugins/Plugin-SDK

Plugin-SDK

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

Ein Plugin wird beschrieben durch eins manifest.json. Der Vertrag, der das Manifest während der Entwicklung validiert, ist derselbe, den die Plattform beim Installationszeitpunkt durchsetzt, sodass ein Manifest, das besteht validate ist ein Manifest, das der Marktplatz akzeptieren wird. Die aihummer plugin Die CLI deckt den gesamten Lebenszyklus ab: vom Scaffold bis zum Signieren und Veröffentlichen.

Ein Manifest, ein Vertrag

Ein Plugin hat genau eine Quelle der Wahrheit — seine manifest.json. Es deklariert die Art des Plugins (kind), wie es konfiguriert ist (config[]), seine Fähigkeiten und — für host-interne Dienste — die install[] Schritte und Startbefehl, die der Systemd-Einsetzer läuft. Da Entwicklung und Installation denselben Validierungsvertrag verwenden, bedeuten „gültiges Manifest“ und „installierbares Plugin“ dasselbe.

[!NOTE] Das Manifest beschreibt ein Plugin Vertrag, nicht seinem Shop-Seitennamen. Der Maschine slug kommt vom Verzeichnis-/Paketnamen (private Seitenladung) oder von die Einreichung, die Sie ausfüllen «Meine Plugins» beim Veröffentlichen eines Community-Plugins — sehen Ein Plugin veröffentlichen.

Kommandozeilenschnittstelle

aihummer plugin bündelt die Entwicklungs-, Verpackungs- und Veröffentlichungskommandos:

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

Zu veröffentlichen Gemeinschaft Plugin für jeden, machst du nicht Verwenden Sie einen CLI-Befehl — Sie laden das verpackte, signierte Artefakt von Ihrem hoch Meine Plugins im persönlichen Cabinet (hochladen → KI-Überprüfung → Moderation). Siehe Ein Plugin einreichen.

Befehl Was es tut
init <kind> [dir] Schreibt einen Starter manifest.json für die gewählte Art.
validate <m.json> Validiert das Manifest mit demselben Vertrag wie bei der Installation.
keygen Generiert das Schlüsselpaar des Autors: .key (privat, geheim halten) und .pub, druckt das key id.
package <dir> Builds (opt.) --build) und verpackt in <slug>-<version>.tar.gz mit einem --strip-components=1 Layout, schreibt .sha256. Packt nie .env, *.key, node_modules, .git.
sign --key <priv> Unterzeichnet die Freigabeidentität; druckt die Unterschrift und key id; mit --manifest betten die Signatur in das Manifest ein.
publish --private Lädt ein Bundle auf die Instanz hoch POST /v1/admin/modules/upload.

Beide Veröffentlichungswege – private Seitendownloads und Community-Veröffentlichungen über das persönliche Cabinet – sind auf … ausführlich beschrieben. Ein Plugin veröffentlichen.

Manifestfelder

Ob ein Feld erforderlich ist, hängt von dem ab Art und ob das Plugin öffentlich ist. Basis- und Identitätsfelder:

Feld Typ Erforderlich Zweck
kind Zeichenkette immer Kind: connector | service | openapi | mcp.
version Zeichenkette ja Plugin-Version (semver), z.B. 1.0.0.
contract Zeichenkette für Kanäle Vertrags-ID, z. B. aihummer.channel.v1.
scope Zeichenkette nein Zugriffsmodell: shared (Standard) oder personal.
capabilities string[] nein Erklärte Fähigkeiten.
config Objekt[] nein Konfigurationsformularfelder; jedes benötigt key, plus label, secret, required.
oauth Objekt nein OAuth2 (authorize_url, token_url, scopes[]) um das Konto eines Benutzers zu verbinden.
signature Zeichenkette bei Unterzeichnung Base64-ed25519-Signatur über die Release-Identität (eingebettet von sign).

Art-spezifische Felder — genau eins Block wird je nach gefüllt kind:

Feld Für freundlich Erforderlich Zweck
host_native.exec_start Anschluss, Dienst ja Befehl, der den langlebigen Dienst ausführt.
host_native.runtime Stecker, Dienst, MCP nein node | python | binary.
host_native.install Stecker, Dienst, MCP nein Installationsschritte (Array von Shell-Befehlen), auf dem Host nach der Extraktion ausführen.
host_native.port Anschluss, Dienst nein Bevorzugter TCP-Port (der Bereitsteller kann ihn neu zuweisen über $PORT).
host_native.health_path Anschluss, Dienst nein Gesundheitsprüfpfad (Standard /healthz).
openapi.spec_url OpenAPI ja URL der OpenAPI 3.x-Spezifikation.
openapi.base_url OpenAPI nein Überschreiben servers[0].url.
openapi.allowed_hosts OpenAPI nein Ausgehende Zulassungsliste für die synthetisierten Werkzeuge.
openapi.auth OpenAPI nein Karte securityScheme → geheimer Name.
openapi.tool_prefix OpenAPI nein Tool-Name Präfix.
mcp.transport MCP ja stdio oder http.
mcp.command / mcp.args mcp (stdio) ja für stdio Server ausführbare Datei und Argumente.
mcp.url mcp (http) ja für http MCP-Endpunkt-URL.
mcp.auth_header / mcp.secret_token_key mcp (http) nein Header und geheimer Schlüssel für das Bearer-Token.

Store-Seite und Identitätsfelder (für Community-Plugins)

Das Manifest kann auch die Identität des Herausgebers und Felder für die Store-Seite enthalten. Für einen Gemeinschaft Plugin, dies sind, was der Katalog zeigt, aber normalerweise gibst du sie ein in die «Meine Plugins» Speicherseite in Ihrem persönlichen Cabinet zum Zeitpunkt der Einreichung (Name, Beschreibungen, Symbol, Screenshots, Kategorie, Spendenlink) anstatt von Hand im Manifest. Ein privates Side-Load benötigt keines davon — ein solches Plugin wird auf Instanzebene vertraut.

Feld Typ Erforderlich Zweck
visibility Zeichenkette nein public | private | unlisted. Leer = veraltet/erstanbieter (keine Identitätsanforderung).
publisher Zeichenkette für die Öffentlichkeit Publisher-Namespace, ^[a-z0-9][a-z0-9-]{1,38}$. Öffentliche Slugs werden benannt @publisher/slug.
publisher_key_id Zeichenkette für die Öffentlichkeit key id des Schlüssels, mit dem das Artefakt signiert ist.
description Zeichenkette für die Öffentlichkeit Kurzbeschreibung der Store-Seite im Katalog.
icon Zeichenkette für die Öffentlichkeit Plugin-Symbol: ein https:// URL oder ein data: URI.
screenshots string[] nein Store-Seiten-Screenshots (Array von https:// URLs; jede nicht-leere).

[!TIP] Laufen aihummer plugin validate bevor Sie einreichen. Die Installation und Validierung Verträge sind identisch, daher wird ein Manifest, das lokal bestanden wird, überall akzeptiert. durch den Marktplatz-Deployeur und durch die Marktplatzbewertung in Ihrem persönlichen Cabinet.

Minimale Manifeste

A service Gerüst (was aihummer plugin init service schreibt):

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

Ein Null-Code openapi Das Manifest ist sogar noch kürzer — es verweist einfach auf die Spezifikation:

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

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

Vom Manifest zum Marktplatz

Nach der Validierung wird ein Plugin verpackt (package), unterzeichnet (sign) und auf eine von zwei Arten veröffentlicht:

  • Privat (für dich selbst) — über die Admin-Benutzeroberfläche in Ihre Instanz seitlich laden oder publish --private. Das Artefakt verlässt niemals die Instanz.
  • Gemeinschaft (für alle) — laden Sie das verpackte, signierte Artefakt von der Meine Plugins in Ihrem persönlichen Schrank; Nach der KI-Überprüfung und menschlichen Moderation wird es unterzeichnet und der Gemeinschaft veröffentlicht. Katalog.

sehen Ein Plugin veröffentlichen für die vollständige Schritt-für-Schritt-Anleitung.

Wo als Nächstes