Аҿартҟәал SDK — AiHummer Адокументациа

Аҿартҟәал зныкатәи manifest.json ала иарбоуп. Аус ауразы manifest ишьоуа аконтракт убри ауп аплатформа аҭагалараан изныҟәо, убри аҟнытә validate зхызгало manifest — маркетплейс иадикыло manifest. aihummer plugin CLI аԥсҭазаара аамҭа зегьы иаҵанакуеит: ашаблон аҟынтә анышьҭ агалареи акьыԥхьреи рҟынӡа.

Зныкатәи manifest, зныкатәи аконтракт

Аҿартҟәал зныкатәи аиашатә ахыҵхырҭа амоуп — иара manifest.json. Уи аҿартҟәал ашьаҟа (kind), ишԥазырхиоу (config[]), иалшарақәа, насгьы — host-зныҟәоу аусурақәа рзы — install[] ашьаҿақәеи аусаԥшьыргара адҵеи SystemdDeployer инанагӡо иарбоит. Аус ауреи аҭагалареи убри ашьоуратә контракт хадырхәо аҟнытә, “иашоу manifest” насгьы “иҭагалатәу аҿартҟәал” акоуп иаҳәо.

[!NOTE] Manifest аҿартҟәал аконтракт иарбоит, иара store-page ахьыӡ акәымкәа. Амашьына slug адиректориа/абандл ахьыӡ аҟынтә иаауеит (шәахатә side-load) ма аишьҭратә аҭакыга аҟынтә (ауаажәларратә) — иаҳәшьа Аҿартҟәал акьыԥхьра.

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>

# Open a PR to the public AiHummer/marketplace-catalog
aihummer plugin publish --public --dir <dir> --key <priv> \
  --artifact-url <url> --publisher <name> \
  --description <text> --icon <url> [--screenshot <url> ...] \
  [--channel stable|beta] [--register-key <pub>]

Адҵа	Изуа
`init <kind> [dir]`	Иалху ашьаҟа азы алагара `manifest.json` иҩуеит.
`validate <m.json>`	Manifest аҭагалара еиԥш убри аконтракт ала ишьоуеит.
`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` ала анышьҭ manifest аҩныҵҟа иалаирԥхьоит.
`publish --private`	Абандл шәинстанциа `POST /v1/admin/modules/upload` ахь иршьҭуеит.
`publish --public`	`AiHummer/marketplace-catalog` ахь PR иаанартуеит.

Аҩбагьы акьыԥхьратә режим иҵаулала иарбоуп Аҿартҟәал акьыԥхьра аҟны.

Manifest аҭакыгақәа

Аҭакыга иаҭахузар ма иаҭахмузар уи аӡбоит ашьаҟа (kind) насгьы аҿартҟәал ауаажәларратәу ала. Абазеи аидентификациеи аҭакыгақәа:

Аҭакыга	Атип	Иаҭахуп	Ахықәкы
`kind`	string	есыҟа	Ашьаҟа: `connector` \| `service` \| `openapi` \| `mcp`.
`version`	string	ааи	Аҿартҟәал аверсиа (semver), аӡбахә ала `1.0.0`.
`contract`	string	аканалқәа рзы	Аконтракт ID, аӡбахә ала `aihummer.channel.v1`.
`scope`	string	мап	Анаплаҟазшьамҭа амодель: `shared` (бжьаратә) ма `personal`.
`capabilities`	string[]	мап	Иарбоу алшарақәа.
`config`	object[]	мап	Аконфиг аформа аҭакыгақәа; дарбанзаалак `key` иаҭахуп, насгьы `label`, `secret`, `required`.
`oauth`	object	мап	OAuth2 (`authorize_url`, `token_url`, `scopes[]`) ауаҩ иаккаунт аиԥшьразы.
`signature`	string	анышьҭ аналоу	арелиз идентификациа азы base64 ed25519 анышьҭ (`sign` ала иалаԥхьоу).

Ашьаҟа-зхадоу аҭакыгақәа — зныкатәи аблок мацара kind инахьыԥшны иҭәуп:

Аҭакыга	Ашьаҟа азы	Иаҭахуп	Ахықәкы
`host_native.exec_start`	connector, service	ааи	Иҭагӡоу аусура изырго адҵа.
`host_native.runtime`	connector, service, mcp	мап	`node` \| `python` \| `binary`.
`host_native.install`	connector, service, mcp	мап	Аҭагалара ашьаҿақәа (шелл адҵақәа рмассив), аибыхырҭ ашьҭахь host аҟны изыргылоу.
`host_native.port`	connector, service	мап	Иаԥсыхоу TCP порт (адеплоер `$PORT` ала еиҭеиҿнакаар алшоит).
`host_native.health_path`	connector, service	мап	Агәабзиара аԥшаара амҩа (бжьаратә `/healthz`).
`openapi.spec_url`	openapi	ааи	OpenAPI 3.x спецификациа URL.
`openapi.base_url`	openapi	мап	`servers[0].url` аиҭагара.
`openapi.allowed_hosts`	openapi	мап	Исинтезу аусхәамаа рзы адәылҵра аужәуыргалатә сиа.
`openapi.auth`	openapi	мап	`securityScheme` → анышьҭ ахьыӡ амап.
`openapi.tool_prefix`	openapi	мап	Аусхәамаа-ахьыӡ апрефикс.
`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)	мап	Bearer токен азы ахы насгьы анышьҭ акьыс.

Store-page насгьы аидентификациа аҭакыгақәа (ауаажәларратә аҿартҟәалақәа рзы)

Ауаажәларратә каталогахь ианалало, manifest акьыԥхьҩы аидентификациеи store-page аҭакыгақәеи аныҟәгароуп. Шәахатә side-load абарҭ акгьы рҭахӡам — абас еиԥшу аҿартҟәал инстанциа аҩаӡара аҟны иуадгылоуп.

Аҭакыга	Атип	Иаҭахуп	Ахықәкы
`visibility`	string	мап	`public` \| `private` \| `unlisted`. Иҭәамкәа = легаси/актәи-напала (аидентификациа аҭахымкәа).
`publisher`	string	ауаажәларратә азы	Акьыԥхьҩы аиԥш, `^[a-z0-9][a-z0-9-]{1,38}$`. Ауаажәларратә slug-қәа `@publisher/slug` рыхьӡуп.
`publisher_key_id`	string	ауаажәларратә азы	Аартефакт зала анышьҭ зуоу акьыс `key id`.
`description`	string	ауаажәларратә азы	Каталог аҟны store-page аҵыхә.
`icon`	string	ауаажәларратә азы	Аҿартҟәал аиконка: `https://` URL ма `data:` URI.
`screenshots`	string[]	мап	Store-page аскриншотқәа (`https://` URL-қәа рмассив; дарбанзаалак иҭәоуп).

[!TIP] Акьыԥхьра зегьы раԥхьа aihummer plugin validate иныҟәга. Аҭагалареи ашьоуреи аконтракт еиԥшуп, убри аҟнытә ахьыҟа изхызгало manifest маркетплейс адеплоер ала, ауаажәларратә каталог авалидатор ала акгьы иадыркылоит.

Иминималу аманифестқәа

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

Manifest аҟынтә маркетплейс ахь

Ашьоура ашьҭахь, аҿартҟәал иеиҿкаауп (package), анышьҭ агалоуп (sign) насгьы ҩба арежим ала икьыԥхьуп:

Шәахатә (шәара шәзы) — Admin UI ма publish --private ала шәинстанциахь side-load. Аартефакт инстанциа ддәылҵӡом.
Ауаажәларратә (зегьы рзы) — publish --public ауаажәларратә каталогахь PR иаанартуеит; ахцәажәара ашьҭахь AiHummer арелиз контр-анышьҭ агалоит насгьы уи community catalog ахь икьыԥхьуеит.

Иҵаулоу аоԥшра аиура азы иаҳәшьа Аҿартҟәал акьыԥхьра.

Уаҩ узаауеи

Аҿартҟәал акьыԥхьра — шәахатә side-load насгьы ауаажәларратә регистр, аишьҭратә контракт, амодерациа.
Кодыда аинтеграциақәа — openapi насгьы mcp ашьаҟақәа ҵаулала.
Аҭагалара & арҿыцрақәа — install[] изырго, агәабзиаратә гейт, атрести анышьҭ зуоу арҿыцрақәеи.
Маркетплейс: аиҿкаашьа & аҵыхәтәиқәа — ашьаҟа зегьы ахьынхо насгьы официалтә каталог community ала ишеиԥшым.