AiHummer
Türkmençe▾
GirmekŞahsy kabinet
v1.0.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Marketpleýs we pluginler/Plugin SDK

Plugin SDK

v1.0.x · täzelendi 2026-06-27

Plugin bir manifest.json faýly bilen beýan edilýär. Ösüş döwründe manifesti barlaýan şertnama platformanyň gurnama wagtynda ulanýan şertnamasy bilen birdir, şonuň üçin validate barlagyndan geçen manifesti bazar hem kabul eder. aihummer plugin CLI ähli ýaşaýyş siklini öz içine alýar: karkas döretmekden gol çekmek we neşir etmeklige çenli.

Bir manifest, bir şertnama

Bir pluginiň tak bir hakykatyň çeşmesi bar — onuň manifest.json. Ol plagin görnüşini yglan edýär (kind), ol nädip sazlanandygy (config[]), onuň mümkinçiligi, we — myhmanlyk-özüw hyzmatlary üçin — install[] ädimler we başlamak buýrugy SystemdÝerleşdiriji işleýär. Sebäbi ösüş we gurmak birmeňzeş tassyklama şertnama ulanar, “tassyklanan manifest” we “gurup boljak goşundy” şol bir manyy aňladýar.

[!NOTE] Manifest pluginiň dükan sahypasyndaky adyny däl-de, onuň mümkinçilikleriniň şertnamasyny beýan edýär. maşyn slug folder/baglajyk adyndan (şahsy tölegli ýükleme) ýa-da sen dolduran tabyşlama «Meniň goşundylarym» jemgyýetçilik pluginini çap edende — seretmek Plugin-i neşir etmek.

CLI

aihummer plugin ösüşi, gaplamak we neşir buýruklaryny birleşdirýär:

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

Neşir etmäge jemagat herkese plugin, sen edýärsiň däk CLI buýrugyny ulanyň — gaplanan, gol bilen tassyklanan artefaktyňyzy ýükläň Meniň Pluginlerim şahsy kabinetde (ýükle → AI syn → redaksiýa). Göz aýla Plugin-i tabşyrmak.

Buýruk Ol näme edýär
init <kind> [dir] Başlaýan ýazýar manifest.json saýlanan görnüş üçin.
validate <m.json> Manifesti install bilen şol bir şertnama boýunça barlaýar.
keygen Awtor açar juwetini döredýär: .key (hususy, gizlin sakla) we .pub, çap edýär key id.
package <dir> Düzgünleýär (saýlap bolýar) --build) we gaplaýar <slug>-<version>.tar.gz bilen --strip-components=1 daşky görnüş, ýazýar .sha256. Asla gaplanmaýar .env, *.key, node_modules, .git.
sign --key <priv> Bellikleriň çykarylyş beýanyny görkezýär; golyny we çap edýär key id; bilen --manifest gol goýmasyny manifestde ýerleşdirýär.
publish --private Siziň instansiňize bir toplumy ýüklýär POST /v1/admin/modules/upload.

Iki neşir ýoly — hususy tarapdan ýüklemek we şahsy kabinet arkaly jemgyýetçilik neşir — jikme-jik beýan edilýär Plugin-i neşir etmek.

Manifest meýdanlary

Bir meýdançanyň zerur bolup-bolmazlygy şundan baglydyr meýil we plugin-iň jemgyýetçilige elýeterli bolmagyna baglylykda. Esasy we şahsyýet meýdanlary:

Merkez Görnüş Talap edilýän Maksat
kind setir hemişe Gatyş connector | service | openapi | mcp.
version setir hawa Plugin wersiýasy (semver), mysal üçin 1.0.0.
contract setir kanallar üçin Şertnama ID-si, meselem aihummer.channel.v1.
scope setir ýok Elýeterlilik modeli: shared (standart) ýa-da personal.
capabilities setir[] ýok Yglan edilen mümkinçilikler.
config obýekt[] ýok Konfigurasiýa formasynyň meýdançalarynyň hersi gerek key, goşmaça label, secret, required.
oauth obýekt ýok OAuth2 (authorize_url, token_url, scopes[]) ulanyjynyň hasabyny birikdirmek üçin.
signature setir gol çekilende base64 ed25519 gol çekmesi çykarmanyň şahsylygy boýunça (göni ýerleşdirilen) sign).

Hususy görnüşlere degişli meýdanlar — takyk biri blok doldurylyşy görä kind:

Merkez Mähirli üçin Talap edilýän Maksat
host_native.exec_start birikdiriji, hyzmat hawa Uzun ömürli hyzmaty işleýän buýruk.
host_native.runtime baglaýjy, hyzmat, mcp ýok node | python | binary.
host_native.install baglaýjy, hyzmat, mcp ýok Gurnama ädimleri (shell buýruklarynyň ýygyndy), çykarylandan soň hostda işledilýär.
host_native.port birikdiriji, hyzmat ýok Halaýan TCP porty (ýerlestiriji onuň üýtgemegini ýerine ýetirip biler $PORT).
host_native.health_path birikdiriji, hyzmat ýok Saglyk barlag ýoly (öňünden kesgitlän) /healthz).
openapi.spec_url açykAPI hawa OpenAPI 3.x spesifikasiýasynyň URL-i.
openapi.base_url açykAPI ýok Üstesinden gelmek servers[0].url.
openapi.allowed_hosts açykAPI ýok Sintezlenen enjamlar üçin çykýan giriş sanawyny rugsat beriň.
openapi.auth açykAPI ýok Kart securityScheme → gizlin ad.
openapi.tool_prefix açykAPI ýok Gurnama adynyň öňtölegi.
mcp.transport mcp hawa stdio ýa-da http.
mcp.command / mcp.args mcp (stdio) hawa, stdio üçin Serweriň ýerine ýetiriji faýly we argumentleri.
mcp.url mcp (http) hawa, http üçin MCP uç nokadynyň URL-iniň.
mcp.auth_header / mcp.secret_token_key mcp (http) ýok Daşary çykaryjy tokeni üçin öňbap we gizlin açar.

Dükanyň sahypasy we şahsyýet meýdançalary ( jemgyýetçilik goşundylary üçin )

Manifest-de neşirçi şahsyýeti we sahypa saklaýyş meýdançalary hem bolup biler. Üçin jemagat plugin, bular katalogyň görkezýän zady, ýöne adatça olary girizýäňiz «Meniň goşundylarym» tabşyryş wagtynda şahsy kabinetiňizde dükanyň sahypasy (ady, düşündirişleri, ikonka, skrinşotlar, kategoriýa, baýrak baglanyşygy) manifeşte el bilen däl. Şahsy_SIDE-y ýüklän ýagdaýynda olaryň hiç birine gerek däl — şeýle plagin wersiýa derejesinde ynamdar hasaplanýar.

Merkez Görnüş Talap edilýän Maksat
visibility setir ýok public | private | unlisted. Bos = miras/ilki öňki tarap (şahsyýet talaby ýok).
publisher setir jemgyýet üçin Neşirçi ad giňişligi, ^[a-z0-9][a-z0-9-]{1,38}$. Jemgyýetdeki salyangozlara at goýulýar @publisher/slug.
publisher_key_id setir jemgyýet üçin key id açar bilen artefakt gol goýlan.
description setir jemgyýet üçin Katalogdaky sahypanyň mazmun beýany.
icon setir jemgyýet üçin Plagin nyşany: açyk https:// URL ýa-da a data: URI.
screenshots setir[] ýok Dükanyň sahypasynyň skrinşotlary (massiw) https:// URL-ler; her boş bolmadyk).

[!TIP] Gaç aihummer plugin validate tabşyrmazdan öň. Gurmak we tassyklaýyş şertnama özara meňzeş, şonuň üçin ýeriňizde geçen manifesta hem ikisini hem kabul ediler bazaryň bölüşdirijisi tarapyndan we şahsy kabinetiňizde bazaryň gözden geçirişi tarapyndan.

Minimal görkezmeler

A service skafold (näme aihummer plugin init service ýazýar):

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

Kodsyz openapi manifest has-da gysga — ol diňe spesifikasiýany görkezýär:

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

Bir mcp manifest (stdio transporty):

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

Manifestden bazara

Tassyklamadan soň, bir plagin paketlenýär (package), gol çekildi (sign) we iki görnüşde neşir edilýär:

  • Şahsy (özüň üçin) — Admin UI arkaly öz nusgaňyza töwekgelçilikli ýükle publish --private. Artefakt hiç wagt instansyýadan çykmaýar.
  • Jemgyýet (herkim üçin) — gaplanan, gol çekilen artefakty ýükläň Meniň Pluginlerim şahsy kabinetiňizde; AI barlagyndan we adam tarapyndan seljermeden soň ol gol çekilýär we jemgyýetçilige çap edilýär katalog.

Gör Plugin-i neşir etmek täzeden doly görkezme üçin.

Indiki nirede