AiHummer
Suomi▾
Kirjaudu sisäänTili
v1.2.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Markkinapaikka ja lisäosat/Liitännäisen SDK

Liitännäisen SDK

v1.2.x · päivitetty 2026-06-27

Laajennus kuvataan yksi manifest.json. Sopimus, joka vahvistaa manifestin kehitysvaiheessa, on sama kuin se, jota alusta noudattaa asennusvaiheessa, joten manifesti, joka läpäisee validate on luettelo, jonka markkinapaikka hyväksyy. Se aihummer plugin CLI kattaa koko elinkaaren: rungon luomisesta allekirjoittamiseen ja julkaisemiseen.

Yksi manifesti, yksi sopimus

Laajennuksella on tarkalleen yksi totuuden lähde — sen manifest.json. Se määrittelee lisäosan tyypin (kind), miten se on määritetty (config[]), sen kyvykkyydet, ja — isäntäkohtaisille palveluille — install[] vaiheet ja käynnistä komento joka SystemdAsentaja toimii. Koska kehitys ja asennus käyttävät samaa validointisopimusta, ‘kelvollinen manifesti’ ja ‘asennettavissa oleva laajennus’ tarkoittavat samaa asiaa.

[!NOTE] Manifesti kuvaa lisäosan sopimus, ei sen kauppasivun nimeä. Se kone slug tulee hakemiston/paketin nimestä (yksityinen sivulataus) tai jostain lähetys, jonka täytät »Omat lisäosani« julkaistaessa yhteisölaajennusta — nähdä Laajennuksen julkaiseminen.

Komentoriviliittymä

aihummer plugin pakkaa kehitys-, paketointi- ja julkaisu-komennot:

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

Julkaistaksesi yhteisö laajennus kaikille, sinä teet ei käytä CLI-komentoa — lataat pakatun, allekirjoitetun artefaktin omasta Lisäosani henkilökohtaisessa kaapissa (lähetä → tekoälyn tarkistus → moderointi). Katso Lähetä lisäosa.

Komento Mitä se tekee
init <kind> [dir] Kirjoittaa aloituksen manifest.json valitulle lajille.
validate <m.json> Varmistaa manifestin samalla sopimuksella kuin asennus.
keygen Luo tekijän avainparin: .key (yksityinen, pidä salassa) ja .pub, tulostaa key id.
package <dir> Kokoonpanot (valinn.) --build) ja pakkaa <slug>-<version>.tar.gz kanssa --strip-components=1 asettelu, kirjoittaa .sha256. Ei koskaan pakkauksia .env, *.key, node_modules, .git.
sign --key <priv> Allekirjoittaa vapautusasiakirjan; tulostaa allekirjoituksen ja key id; kanssa --manifest upottaa allekirjoituksen manifestiin.
publish --private Lataa paketin instanssiisi POST /v1/admin/modules/upload.

Molemmat julkaisutavat — yksityinen sivulataus ja yhteisöjulkaisu henkilökohtaisen hallintapaneelin kautta — on kuvattu yksityiskohtaisesti osoitteessa Laajennuksen julkaiseminen.

Manifestikentät

Se, onko kenttä pakollinen, riippuu siitä ystävällinen ja siitä, onko liitännäinen julkinen. Perus- ja tunnistuskentät:

Kenttä Tyyppi Vaadittu Tarkoitus
kind merkkijono aina Laji: connector | service | openapi | mcp.
version merkkijono kyllä Laajennuksen versio (semver), esim. 1.0.0.
contract merkkijono kanaville Sopimuksen tunnus, esim. aihummer.channel.v1.
scope merkkijono ei Käyttömalli: shared (oletus) tai personal.
capabilities merkkijono[] ei Ilmoitetut ominaisuudet.
config objekti[] ei Määritä lomakkeen kentät; jokainen tarvitsee key, plus label, secret, required.
oauth esine ei OAuth2 (authorize_url, token_url, scopes[]) yhdistää käyttäjän tilin.
signature merkkijono kun allekirjoitettu base64 ed25519 -allekirjoitus julkaisun identiteetistä (upotettu by sign).

Lajikohtaiset kentät — täsmälleen yksi lohko täytetään riippuen siitä kind:

Kenttä Ystävälliselle Vaadittu Tarkoitus
host_native.exec_start liitin, palvelu kyllä Komentorivi, joka käynnistää pitkäikäisen palvelun.
host_native.runtime liitin, palvelu, mcp ei node | python | binary.
host_native.install liitin, palvelu, mcp ei Asennusvaiheet (taulukko shel-komentoja), suorita isäntäkoneella purkamisen jälkeen.
host_native.port liitin, palvelu ei Suositeltu TCP-portti (asentaja voi uudelleen määrittää sen kautta $PORT).
host_native.health_path liitin, palvelu ei Terveystarkastuksen polku (oletus /healthz).
openapi.spec_url openapi kyllä OpenAPI 3.x -määritelmän URL-osoite.
openapi.base_url openapi ei Ohittaa servers[0].url.
openapi.allowed_hosts openapi ei Lähtevien yhteyksien sallittu luettelo syntetisoiduille työkaluista.
openapi.auth openapi ei Kartta securityScheme → salainen nimi.
openapi.tool_prefix openapi ei Työkalun nimen etuliite.
mcp.transport mcp kyllä stdio tai http.
mcp.command / mcp.args mcp (stdio) kyllä stdioa varten Palvelimen suoritettava tiedosto ja argumentit.
mcp.url mcp (http) kyllä http:lle MCP-päätepisteen URL-osoite.
mcp.auth_header / mcp.secret_token_key mcp (http) ei Otsikko ja salainen avain kantajalle tokenille.

Kauppa-sivu ja tunnistetiedot (yhteisölaajennuksille)

Manifestissa voi myös olla julkaisijan tunnistetiedot ja kaupan sivun kentät. Yhdelle yhteisö liitännäinen nämä ovat mitä luettelo näyttää, mutta normaalisti syötät ne »Omat lisäosani« tallennussivu henkilökohtaisessa hallintapaneelissasi lähetyksen yhteydessä (nimi, kuvaukset, kuvake, kuvakaappaukset, kategoria, lahjoituslinkki) sen sijaan, että täyttäisit ne käsin manifestissa. Yksityinen sivulataus ei tarvitse mitään näistä — tällainen lisäosa on luotettu instanssitasolla.

Kenttä Tyyppi Vaadittu Tarkoitus
visibility merkkijono ei public | private | unlisted. Tyhjä = perinteinen/ensimmäisen osapuolen (ei henkilöllisyysvaatimusta).
publisher merkkijono julkiseen käyttöön Julkaisijan nimiavaruus, ^[a-z0-9][a-z0-9-]{1,38}$. Julkiset etanat nimetään @publisher/slug.
publisher_key_id merkkijono julkiseen käyttöön key id avaimella, jolla artefakti on allekirjoitettu.
description merkkijono julkiseen käyttöön Kaupan sivun kuvaus luettelossa.
icon merkkijono julkiseen käyttöön Laajennuksen kuvake: an https:// URL tai a data: URI.
screenshots merkkijono[] ei Kauppasivun kuvakaappaukset (taulukko https:// URL-osoitteet; jokainen ei-tyhjä).

[!TIP] Juosta aihummer plugin validate ennen kuin lähetät. Asennus ja vahvistus sopimukset ovat identtisiä, joten paikallisesti hyväksytty manifesti hyväksytään molemmissa markkinapaikan julkaisejan ja markkinapaikan arvostelun kautta henkilökohtaisessa kaapissasi.

Minimaaliset ilmaukset

A service teline (mikä aihummer plugin init service kirjoittaa):

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

Nollakoodia openapi manifesti on vielä lyhyempi — se vain osoittaa spesifikaatioon:

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

Yksi mcp manifesti (stdio-siirto):

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

Manifesteista markkinapaikalle

Vahvistuksen jälkeen liitännäinen pakataan (package), allekirjoitettu (sign) ja julkaistu kahdella tavalla:

  • Yksityinen (itsellesi) — asenna sivuttaisesti instanssiisi hallintakäyttöliittymän kautta tai publish --private. Artefakti ei koskaan poistu instanssista.
  • Yhteisö (kaikille) — lataa pakattu, allekirjoitettu artefakti osoitteesta Lisäosani henkilökohtaisessa kaapissasi; AI-arvion ja ihmisen moderoinnin jälkeen se allekirjoitetaan ja julkaistaan yhteisölle luettelo.

Katsoa Laajennuksen julkaiseminen täydellistä läpikäyntiä varten.

Minne seuraavaksi