AiHummer
Polski▾
Zaloguj sięKonto
v1.0.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Rynek i wtyczki/SDK wtyczki

SDK wtyczki

v1.0.x · zaktualizowany 2026-06-27

Wtyczka jest opisana przez jeden manifest.json. Umowa, która weryfikuje manifest w trakcie developmentu, jest tą samą, którą platforma egzekwuje w czasie instalacji, więc manifest, który przechodzi validate jest manifestem, który rynek zaakceptuje. aihummer plugin CLI obejmuje cały cykl życia: od szkieletu po podpisywanie i publikowanie.

Jeden manifest, jedna umowa

Wtyczka ma dokładnie jedno źródło prawdy — swoje manifest.json. Deklaruje rodzaj wtyczki (kind), jak jest skonfigurowane (config[]), jego możliwości oraz — w przypadku usług natywnych dla hosta — install[] kroki i polecenie start SystemdDeployer Działa. Ponieważ rozwój i instalacja korzystają z tej samej umowy weryfikacyjnej, „ważny manifest” i „instalowalny plugin” oznaczają to samo.

[!NOTE] Manifest opisuje wtyczkę umowa, nie jego nazwa na stronie sklepu. maszyna slug pochodzi z nazwy katalogu/pakietu (prywatne przesyłanie boczne) lub z wniosek, który wypełniasz «Moje wtyczki» podczas publikowania wtyczki społecznościowej — widzieć Publikowanie wtyczki.

CLI

aihummer plugin łączy polecenia tworzenia, pakowania i publikowania:

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

Opublikować społeczność wtyczka dla wszystkich, ty robisz nie użyj polecenia CLI — przesyłasz spakowany, podpisany artefakt ze swojego Moje wtyczki w osobistym panelu (prześlij → przegląd AI → moderacja). Zobacz Prześlij wtyczkę.

Polecenie Co to robi
init <kind> [dir] Pisze start manifest.json dla wybranego rodzaju.
validate <m.json> Weryfikuje manifest zgodnie z tym samym kontraktem co instalacja.
keygen Generuje parę kluczy autora: .key (prywatne, trzymaj w tajemnicy) i .pub, drukuje key id.
package <dir> Buduje (opc.) --build) i pakuje się w <slug>-<version>.tar.gz z --strip-components=1 układ, pisze .sha256. Nigdy nie pakuje .env, *.key, node_modules, .git.
sign --key <priv> Podpisuje tożsamość zwolnienia; drukuje podpis i key id; z --manifest osadza podpis w manifeście.
publish --private Przesyła pakiet do twojej instancji POST /v1/admin/modules/upload.

Obie ścieżki publikowania — prywatne przesyłanie boczne i publikowanie w społeczności za pośrednictwem osobistej szafki — są szczegółowo opisane na Publikowanie wtyczki.

Pola manifestu

Czy pole jest wymagane, zależy od uprzejmy i od tego, czy wtyczka jest publiczna. Pola podstawowe i tożsamości:

Pole Typ Wymagane Cel
kind ciąg zawsze Rodzaj: connector | service | openapi | mcp.
version ciąg tak Wersja wtyczki (semver), np. 1.0.0.
contract ciąg dla kanałów ID kontraktu, np. aihummer.channel.v1.
scope ciąg nie Model dostępu: shared (domyślnie) lub personal.
capabilities string[] nie Deklarowane możliwości.
config obiekt[] nie Skonfiguruj pola formularza; każde potrzebuje key, plus label, secret, required.
oauth obiekt nie OAuth2 (authorize_url, token_url, scopes[]) aby połączyć konto użytkownika.
signature ciąg kiedy podpisano podpis ed25519 w formacie base64 nad tożsamością wydania (osadzony przez sign).

Pola specyficzne dla rodzaju — dokładnie jeden blok jest wypełniany w zależności od kind:

Pole Dla miłego Wymagane Cel
host_native.exec_start złącze, usługa tak Polecenie, które uruchamia usługę działającą przez długi czas.
host_native.runtime złącze, usługa, mcp nie node | python | binary.
host_native.install złącze, usługa, mcp nie Kroki instalacji (tablica poleceń shell), uruchom na hoście po rozpakowaniu.
host_native.port złącze, usługa nie Preferowany port TCP (wdrażający może przypisać ponownie przez $PORT).
host_native.health_path złącze, usługa nie Ścieżka kontroli stanu zdrowia (domyślna /healthz).
openapi.spec_url openapi tak Adres URL specyfikacji OpenAPI 3.x.
openapi.base_url openapi nie Nadpisz servers[0].url.
openapi.allowed_hosts openapi nie Lista dozwolonego ruchu wychodzącego dla zsyntetyzowanych narzędzi.
openapi.auth openapi nie Mapa securityScheme → tajna nazwa.
openapi.tool_prefix openapi nie Prefiks nazwy narzędzia.
mcp.transport mcp tak stdio lub http.
mcp.command / mcp.args mcp (stdio) tak dla stdio Plik wykonywalny serwera i argumenty.
mcp.url mcp (http) tak dla http Adres URL punktu końcowego MCP.
mcp.auth_header / mcp.secret_token_key mcp (http) nie Nagłówek i tajny klucz dla tokena dostępu.

Strona sklepu i pola tożsamości (dla wtyczek społecznościowych)

Manifest może również zawierać identyfikator wydawcy oraz pola strony sklepu. Dla społeczność wtyczki, to jest to, co pokazuje katalog, ale zazwyczaj wprowadza się je w «Moje wtyczki» stronę sklepu w twoim osobistym panelu w momencie przesyłania (nazwa, opisy, ikona, zrzuty ekranu, kategoria, link do darowizn), zamiast ręcznie w manifeście. Prywatne instalowanie boczne nie wymaga żadnego z nich — taki plugin jest zaufany na poziomie instancji.

Pole Typ Wymagane Cel
visibility ciąg nie public | private | unlisted. Puste = starsza/pierwotna (bez wymogu tożsamości).
publisher ciąg dla publiczności Przestrzeń nazw wydawcy, ^[a-z0-9][a-z0-9-]{1,38}$. Publiczne ślimaki są nazywane @publisher/slug.
publisher_key_id ciąg dla publiczności key id klucza, którym podpisany jest artefakt.
description ciąg dla publiczności Krótki opis strony sklepu w katalogu.
icon ciąg dla publiczności Ikona wtyczki: an https:// URL lub a data: URI.
screenshots string[] nie Zrzuty ekranu strony sklepu (tablica https:// Adresy URL; każdy niepusty).

[!TIP] Biegać aihummer plugin validate przed wysłaniem. Instalacja i walidacja umowy są identyczne, więc manifest, który zostanie zaakceptowany lokalnie, zostanie zaakceptowany w obu przypadkach przez wdrażającego rynek i przez przegląd rynku w Twojej personalnej szafce.

Minimalne manifesty

A service rusztowanie (co aihummer plugin init service pisze):

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

Zero-kod openapi manifest jest jeszcze krótszy — po prostu wskazuje na specyfikację:

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

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

Od manifestu do rynku

Po weryfikacji, wtyczka jest pakowana (package), podpisany (sign) i opublikowane na jeden z dwóch sposobów:

  • Prywatne (dla siebie) — załaduj bocznie do swojej instancji przez interfejs administracyjny lub publish --private. Artefakt nigdy nie opuszcza instancji.
  • Społeczność (dla wszystkich) — prześlij spakowany, podpisany artefakt z Moje wtyczki w twojej osobistej szafce; po przeglądzie przez AI i moderacji ludzkiej jest podpisywane i publikowane w społeczności katalog.

Zobacz Publikowanie wtyczki dla pełnego przewodnika.

Gdzie dalej