AiHummer
Latviešu▾
PierakstītiesKonts
v1.0.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Tirgus un spraudņi/Spraudņa SDK

Spraudņa SDK

v1.0.x · atjaunināts 2026-06-27

Spraudnis tiek aprakstīts ar viens manifest.json. Līgums, kas pārbauda manifestu izstrādes laikā, ir tas pats, ko platforma piemēro uzstādīšanas laikā, tāpēc manifests, kas iziet pārbaudi validate ir manifestu, ko tirgus pieņems. aihummer plugin CLI aptver visu dzīves ciklu: no karkasa līdz parakstīšanai un publicēšanai.

Viens kravas saraksts, viens līgums

Spraudnim ir tieši viens patiesības avots — tā manifest.json. Tas deklarē spraudņa veidu (kind), kā tas ir konfigurēts (config[]), tā iespējas, un — attiecībā uz resursdatora vietējajiem pakalpojumiem — install[] soļi un sākuma komanda, ka SystemdIzvietotājs darbojas. Tā kā izstrāde un instalēšana izmanto to pašu pārbaudes līgumu, “derīgs manifests” un “uzstādāms spraudnis” nozīmē vienu un to pašu.

[!NOTE] Manifestā aprakstīts spraudņa līgums, nevis tās veikala lapas nosaukumu. mašīna slug nāk no direktorijas/iepakojuma nosaukuma (privāta sānu ielāde) vai no iesniegums, ko jūs aizpildāt «Mani spraudņi» publicējot kopienas spraudni — redzēt Spraudņa publicēšana.

CLI

aihummer plugin apvieno izstrādes, iesaiņošanas un publicēšanas komandas:

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

Publicēt kopiena spraudnis visiem, tu dari ne izmantojiet CLI komandu — jūs augšupielādējat iepakoto, parakstīto artefaktu no sava Mani spraudņi personīgajā kabinetā (augšupielāde → AI pārskats → moderēšana). Skatīt Iesniegt spraudni.

Komanda Ko tas dara
init <kind> [dir] Uzraksta starteri manifest.json izvēlētajai sugai.
validate <m.json> Pārbauda manifestu ar to pašu līgumu kā instalācija.
keygen Ģenerē autora atslēgu pāri: .key (privāts, turēt noslēpumā) un .pub, drukā key id.
package <dir> Versijas (pēc izvēles) --build) un iesaiņo <slug>-<version>.tar.gz ar --strip-components=1 izkārtojums, raksta .sha256. Nekad nesaiet .env, *.key, node_modules, .git.
sign --key <priv> Paraksta atbrīvošanas identitāti; izdrukā parakstu un key id; ar --manifest iegulda parakstu manifestā.
publish --private Augšupielādē pakotni jūsu instances POST /v1/admin/modules/upload.

Abi publicēšanas ceļi — privātā sānu ielāde un kopienas publicēšana caur personīgo kabinetu — ir sīki aprakstīti Spraudņa publicēšana.

Manifestācijas lauki

Vai lauks ir obligāts, ir atkarīgs no laipns un vai spraudnis ir publisks. Pamata un identitātes lauki:

Lauks Veids Nepieciešams Mērķis
kind virkne vienmēr Draudzīgs connector | service | openapi | mcp.
version virkne jā Spraudņa versija (semver), piem. 1.0.0.
contract virkne kanāliem Līguma ID, piemēram aihummer.channel.v1.
scope virkne no Piekļuves modelis: shared (noklusējums) vai personal.
capabilities virkne[] no Deklarētās spējas.
config objekts[] no Konfigurācijas formas lauki; katram nepieciešams key, plus label, secret, required.
oauth objekts no OAuth2 (authorize_url, token_url, scopes[]) lai savienotu lietotāja kontu.
signature virkne kad parakstīts base64 ed25519 paraksts pār izlaišanas identitāti (iebūvēts ar sign).

Tipspecifiski lauki — tieši viens bloks tiek aizpildīts atkarībā no kind:

Lauks Lai laipns Nepieciešams Mērķis
host_native.exec_start savienotājs, serviss jā Komanda, kas palaidina ilgi darbojošos pakalpojumu.
host_native.runtime savienotājs, pakalpojums, mcp no node | python | binary.
host_native.install savienotājs, pakalpojums, mcp no Instalēšanas soļi (komandu virkne), palaist uz hosta pēc izsaiņošanas.
host_native.port savienotājs, serviss no Vēlamais TCP ports (izvietotājs var piešķirt citu, izmantojot $PORT).
host_native.health_path savienotājs, serviss no Veselības pārbaudes ceļš (noklusējums /healthz).
openapi.spec_url openapi jā OpenAPI 3.x specifikācijas URL.
openapi.base_url openapi no Pārrakstīt servers[0].url.
openapi.allowed_hosts openapi no Ērģesu atļauto saraksts sintētiskajiem rīkiem.
openapi.auth openapi no Kartele securityScheme → slepenais vārds.
openapi.tool_prefix openapi no Rīka nosaukuma priekšvārds.
mcp.transport mcp jā stdio vai http.
mcp.command / mcp.args mcp (stdio) jā priekš stdio Servera izpildāmā programma un argumenti.
mcp.url mcp (http) jā, par http MCP galapunkta URL.
mcp.auth_header / mcp.secret_token_key mcp (http) no Virsraksts un slepenais atslēga nesēja tokenam.

Veikala lapa un identitātes lauki (kopienas spraudņiem)

Manifestā var būt arī izdevēja identitātes un veikala lapas lauki. Lai kopiena spraudnis tas ir tas, ko rāda katalogs, bet parasti jūs tos ievadāt tajā «Mani spraudņi» veikala lapa jūsu personīgajā kabinetā iesniegšanas brīdī (nosaukums, apraksti, ikona, ekrānuzņēmumi, kategorija, ziedojumu saite), nevis manuāli manifestā. Privāta sānu ielāde nevienu no tiem neprasa — šāds spraudnis tiek uzticēts instanču līmenī.

Lauks Veids Nepieciešams Mērķis
visibility virkne no public | private | unlisted. Tukša = mantojums/pirmās puses (nav nepieciešama identitāte).
publisher virkne publikai Izdevēja nosaukumu telpa, ^[a-z0-9][a-z0-9-]{1,38}$. Publiskās gliemenes tiek nosauktas @publisher/slug.
publisher_key_id virkne publikai key id ar kura atslēgu artefakts ir parakstīts.
description virkne publikai Veikala lapas apraksts katalogā.
icon virkne publikai Spraudņa ikona: an https:// URL vai a data: URI.
screenshots virkne[] no Veikala lapas ekrānuzņēmumi (masīvs no https:// URL; katrs neaizpildīts).

[!TIP] Skriet aihummer plugin validate pirms iesniegšanas. Instalēšana un validācija līgumi ir identiski, tāpēc lokāli veiksmīgi izpildīts manifests tiks pieņemts abos tirdzniecības vietas izvietotāja un tirdzniecības vietas pārskatīšanas jūsu personīgajā kabinetā.

Minimāls manifests

A service celtniecības skatuve (kas aihummer plugin init service raksta):

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

Nulles kods openapi manifestācija ir vēl īsāka — tā vienkārši norāda uz specifikāciju:

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

Neviens mcp manifestācija (stdio transports):

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

No manifestācijas līdz tirgum

Pēc validācijas spraudnis tiek iepakots (package), parakstīts (sign) un publicēts vienā no diviem veidiem:

  • Privāts (tev pašam) — ielādēt sānu režīmā savā instancē, izmantojot administrācijas lietotāja saskarni vai publish --private. Artefakts nekad neatstāj instanci.
  • Kopiena (visiem) — augšupielādēt iepakoto, parakstīto artefaktu no Mani spraudņi jūsu personīgajā kabinetā; pēc AI pārskatīšanas un cilvēka moderēšanas tas tiek parakstīts un publicēts kopienai katalogs.

Redzēt Spraudņa publicēšana pilnīgai soli pa solim instrukcijai.

Kur tālāk