AiHummer
Қазақша▾
КіруЖеке кабинет
v1.1.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Маркетплейс және плагиндер/Плагин SDK

Плагин SDK

v1.1.x · жаңартылды 2026-06-27

Плагин бір manifest.json файлымен сипатталады. Әзірлеу кезінде манифестті тексеретін келісімшарт платформаның орнату кезінде қолданатын келісімшартымен бірдей, сондықтан validate тексеруінен өткен манифестті нарық та қабылдайды. aihummer plugin CLI бүкіл өмірлік циклді қамтиды: қаңқа жасаудан қол қою мен жариялауға дейін.

Бір манифест, бір келісімшарт

Плагиннің дәл бір ғана шынайы дереккөзі бар — оның manifest.json. Ол плагин түрін жариялайды (kind), оны қалай баптауға болады (config[]), оның мүмкіндіктері және — хостқа тән қызметтер үшін — install[] қадамдар және бастау командасы ол SystemdЖүктеуші жүреді. Өйткені әзірлеу және орнату бірдей тексеру келісімін пайдаланады, «жарамды манифест» және «орнатылатын плагин» бірдей нәрсені білдіреді.

[!NOTE] Манифест плагиннің дүкен бетіндегі атауын емес, оның мүмкіндіктер келісімшартын сипаттайды. машина slug директория/пакет атауынан (жеке бүйірлік жүктеу) немесе … сіз толтырған өтініш «Менің плагиндерім» қоғамдық плагинді жариялағанда — көр Плагинді жариялау.

CLI

aihummer plugin даму, орау және жариялау командаларын біріктіреді:

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

Жариялау үшін қауымдастық барлығы үшін плагин, сіз жасайсыз емес CLI пәрменін қолданыңыз — сіз пакеттелген, қол қойылған артефактіңізді жүктейсіз Менің плагиндерім жеке кабинетте (жүктеу → AI шолу → модерация). Қараңыз Плагинді жіберу.

Бұйрық Не істейді
init <kind> [dir] Бастауышты жазады manifest.json таңдалған түр үшін.
validate <m.json> Манифесті орнату сияқты келісімшартпен тексереді.
keygen Автор кілт жұбын жасайды: .key (жеке, құпия ұстап) және .pub, басып шығарады key id.
package <dir> Құрылыстар (қосымша) --build) және оралады <slug>-<version>.tar.gz мен --strip-components=1 жоспар, жазады .sha256. Ешқашан қаптамайды .env, *.key, node_modules, .git.
sign --key <priv> Шығару тұлғасын көрсететін белгілер; қолтаңбаны басып шығарады және key id; бірге --manifest қолтаңбаны манифестке енгізеді.
publish --private Сіздің инстанцияңызға буманы жүктейді POST /v1/admin/modules/upload.

Екі жариялау жолы — жеке жүктеу және жеке кабинет арқылы қауымдастыққа жариялау — мына жерде толық сипатталған Плагинді жариялау.

Манифест өрістері

Ерікті алаң болу-болмауы тәуелді болады жақсы және плагиннің жалпыға қолжетімділігіне байланысты. Негізгі және жеке деректер өрістері:

Дала Тип Керек Мақсат
kind жол әрқашан Түрі: connector | service | openapi | mcp.
version жол иә Плагин нұсқасы (semver), мысалы 1.0.0.
contract жол арналар үшін Шарттың идентификаторы, мысалы aihummer.channel.v1.
scope жол жоқ Қол жеткізу моделі: shared (әдепкі) немесе personal.
capabilities жол[] жоқ Анықталған мүмкіндіктер.
config объект[] жоқ Конфигурация формасының өрістері; әрқайсысы қажет key, қосыңыз label, secret, required.
oauth зат жоқ OAuth2 (authorize_url, token_url, scopes[]) пайдаланушының аккаунтын қосу үшін.
signature жол қол қойылғанда base64 ed25519 қолтаңбасы шығарылым идентификаторы бойынша (енгізілген) sign).

Түрге тән өрістер — дәл бір блок толтырылады байланысты kind:

Дала Жақсылық үшін Керек Мақсат
host_native.exec_start коннектор, сервис иә Ұзақ мерзімді қызметті іске қосатын команда.
host_native.runtime коннектор, қызмет, mcp жоқ node | python | binary.
host_native.install коннектор, қызмет, mcp жоқ Орнату қадамдары (шелл командаларының массиві), шығарып алғаннан кейін хостта орындаңыз.
host_native.port коннектор, сервис жоқ Артық көретін TCP порты (орнатушы қайта тағайындай алады via $PORT).
host_native.health_path коннектор, сервис жоқ Денсаулықты тексеру жолы (әдепкі) /healthz).
openapi.spec_url ашық API иә OpenAPI 3.x спецификациясының URL мекенжайы.
openapi.base_url ашық API жоқ Жоғары басу servers[0].url.
openapi.allowed_hosts ашық API жоқ Синтезделген құралдар үшін шығу рұқсат тізімі.
openapi.auth ашық API жоқ Карта securityScheme → құпия атау.
openapi.tool_prefix ашық API жоқ Құрал атауының префиксі.
mcp.transport mcp иә stdio немесе http.
mcp.command / mcp.args mcp (stdio) иә, stdio үшін Сервер орындалатын файлы және аргументтері.
mcp.url mcp (http) иә http үшін MCP соңғы нүктесінің URL мекенжайы.
mcp.auth_header / mcp.secret_token_key mcp (http) жоқ Тасушы токен үшін тақырып және құпия кілт.

Дүкен-бет және сәйкестендіру өрістері (қауымдастық плагиндері үшін)

Манифестте сондай-ақ баспагердің сәйкестендігі және дүкен-бет өрістері болуы мүмкін. Үшін қауымдастық плагиндер бұл каталог көрсететін нәрселер, бірақ сіз әдетте оларды енгізесіз «Менің плагиндерім» жүктеу кезінде жеке кабинетіңіздегі дүкен парағында (аты, сипаттамалары, белгішесі, скриншоттар, категориясы, қайырымдылық сілтемесі) енгізу, манифест арқылы қолмен емес. Жеке бүйірлік жүктеу олардың ешқайсысын қажет етпейді — мұндай плагин инстанс деңгейінде сенімді болып есептеледі.

Дала Тип Керек Мақсат
visibility жол жоқ public | private | unlisted. Бос = мұра/бірінші тарап (оны пайдалану үшін жеке басын растау қажет емес).
publisher жол қоғамдық пайдалануға Баспа атау кеңістігі, ^[a-z0-9][a-z0-9-]{1,38}$. Қоғамдық қоңыздар аталады @publisher/slug.
publisher_key_id жол қоғамдық пайдалануға key id ключтің қолтаңбасымен жасалған артефакт.
description жол қоғамдық пайдалануға Каталогтағы дүкен бетіндегі қысқаша сипаттама.
icon жол қоғамдық пайдалануға Плагин белгішесі: an https:// URL немесе a data: URI.
screenshots жол[] жоқ Дүкен-бет скриншоттары (массиві https:// URL-мекенжайлары; әрбір бос емес).

[!TIP] Жүгіру aihummer plugin validate жібермес бұрын. Орнату және тексеру келісімшарттар бірдей, сондықтан жергілікті жерде өтетін манифест екеуінде де қабылданады нарық орналастырушысы және жеке кабинетіңіздегі нарық шолуы арқылы.

Минималды манифесттер

А service көрме құрылысы (не aihummer plugin init service жазады):

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

Нөлдік код openapi manifest тіпті қысқа — ол тек спецификацияға нұсқайды:

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

Бір mcp manifest (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"] }
}

Манифесттен нарыққа

Тексеруден кейін плагин оралады (package), қол қойылды (sign) және екі жолдың бірінде жарияланады:

  • Жеке (өз үшін) — әкімші UI арқылы немесе өз тіркелгіңізге бүйірден жүктеңіз publish --private. Артефакт ешқашан инстанциядан шықпайды.
  • Қауымдастық (бәріне) — орауышқа салынған, қол қойылған артефактіні жүктеңіз Менің плагиндерім жеке кабинетіңізде; Жасанды интеллектпен шолу және адам модерациясынан кейін ол қол қойылып, қауымдастыққа жарияланады каталог.

Көріңіз Плагинді жариялау толық нұсқаулық үшін.

Келесі қайда