Plugin SDK — AiHummer დოკუმენტაცია

პლაგინი აღწერილია ერთი manifest.json-ით. კონტრაქტი, რომელიც ამოწმებს მანიფესტს განვითარების დროს, იგივეა, რასაც პლატფორმა აღასრულებს ინსტალაციის დროს, ასე რომ მანიფესტი, რომელიც გადის validate-ს, არის მანიფესტი, რომელსაც marketplace მიიღებს. aihummer plugin CLI მოიცავს მთელ სასიცოცხლო ციკლს: ჩონჩხიდან ხელმოწერამდე და გამოქვეყნებამდე.

ერთი მანიფესტი, ერთი კონტრაქტი

პლაგინს აქვს ზუსტად ერთი ჭეშმარიტების წყარო — მისი manifest.json. ის აცხადებს პლაგინის სახეობას (kind), თუ როგორ კონფიგურირდება ის (config[]), მის შესაძლებლობებს და — ჰოსტზე-მშობლიური სერვისებისთვის — install[] ნაბიჯებსა და გაშვების ბრძანებას, რომელსაც SystemdDeployer აწარმოებს. ვინაიდან განვითარება და ინსტალაცია იყენებენ იმავე ვალიდაციის კონტრაქტს, “ვალიდური მანიფესტი” და “ინსტალირებადი პლაგინი” ერთსა და იმავეს ნიშნავს.

[!NOTE] მანიფესტი აღწერს პლაგინის კონტრაქტს, და არა მის store-გვერდის სახელს. მანქანური slug მოდის დირექტორიის/bundle-ის სახელიდან (პირადი 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>`	ამოწმებს მანიფესტს იმავე კონტრაქტით, რასაც ინსტალაცია.
`keygen`	აგენერირებს ავტორის გასაღების წყვილს: `.key` (პირადი, შეინახეთ საიდუმლოდ) და `.pub`, ბეჭდავს `key id`-ს.
`package <dir>`	აგებს (სურვ. `--build`) და აფუთავს `<slug>-<version>.tar.gz`-ში `--strip-components=1` განლაგებით, წერს `.sha256`-ს. არასოდეს აფუთავს `.env`, `*.key`, `node_modules`, `.git`.
`sign --key <priv>`	ხელს აწერს release-ის იდენტობას; ბეჭდავს ხელმოწერასა და `key id`-ს; `--manifest`-ით ჩაშენებს ხელმოწერას მანიფესტში.
`publish --private`	ტვირთავს bundle-ს თქვენი ინსტანციის `POST /v1/admin/modules/upload`-ში.
`publish --public`	ხსნის PR-ს `AiHummer/marketplace-catalog`-ში.

ორივე გამოქვეყნების რეჟიმი დეტალურადაა აღწერილი გვერდზე პლაგინის გამოქვეყნება.

მანიფესტის ველები

ველის სავალდებულობა დამოკიდებულია სახეობაზე (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 ხელმოწერა release-ის იდენტობაზე (ჩაშენებული `sign`-ით).

სახეობა-სპეციფიკური ველები — ზუსტად ერთი ბლოკი ივსება kind-ის მიხედვით:

ველი	სახეობისთვის	სავალდებულო	დანიშნულება
`host_native.exec_start`	connector, service	კი	ბრძანება, რომელიც აწარმოებს ხანგრძლივ სერვისს.
`host_native.runtime`	connector, service, mcp	არა	`node` \| `python` \| `binary`.
`host_native.install`	connector, service, mcp	არა	ინსტალაციის ნაბიჯები (shell ბრძანებების მასივი), ეშვება ჰოსტზე ამოღების შემდეგ.
`host_native.port`	connector, service	არა	სასურველი TCP პორტი (deployer-მა შეიძლება ხელახლა მიანიჭოს `$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` → secret-ის სახელის რუკა.
`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)	არა	header და secret გასაღები bearer token-ისთვის.

Store-გვერდისა და იდენტობის ველები (საჯარო პლაგინებისთვის)

საჯარო კატალოგში მოსახვედრად მანიფესტს უნდა ჰქონდეს გამომქვეყნებლის იდენტობა და store-გვერდის ველები. პირად side-load-ს არცერთი ეს არ სჭირდება — ასეთი პლაგინი სანდოა ინსტანციის დონეზე.

ველი	ტიპი	სავალდებულო	დანიშნულება
`visibility`	string	არა	`public` \| `private` \| `unlisted`. ცარიელი = legacy/პირველი მხარის (იდენტობის მოთხოვნის გარეშე).
`publisher`	string	საჯაროსთვის	გამომქვეყნებლის namespace, `^[a-z0-9][a-z0-9-]{1,38}$`. საჯარო slug-ები იწოდება `@publisher/slug`.
`publisher_key_id`	string	საჯაროსთვის	`key id` იმ გასაღებისა, რომლითაც არტეფაქტი ხელმოწერილია.
`description`	string	საჯაროსთვის	store-გვერდის აღწერა კატალოგში.
`icon`	string	საჯაროსთვის	პლაგინის ხატულა: `https://` URL ან `data:` URI.
`screenshots`	string[]	არა	store-გვერდის ეკრანის სურათები (`https://` URL-ების მასივი; თითოეული არაცარიელი).

[!TIP] გაუშვით aihummer plugin validate ყოველი გამოქვეყნების წინ. ინსტალაციისა და ვალიდაციის კონტრაქტი იდენტურია, ასე რომ მანიფესტი, რომელიც ლოკალურად გადის, მიიღება როგორც marketplace-ის deployer-ის, ისე საჯარო კატალოგის ვალიდატორის მიერ.

მინიმალური მანიფესტები

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 მანიფესტი კიდევ უფრო მოკლეა — ის უბრალოდ უთითებს სპეციფიკაციაზე:

{
  "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 მანიფესტი (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"] }
}

მანიფესტიდან marketplace-მდე

ვალიდაციის შემდეგ პლაგინი იფუთება (package), ხელმოწერილია (sign) და ქვეყნდება ორი რეჟიმიდან ერთით:

პირადი (საკუთარი თავისთვის) — side-load თქვენს ინსტანციაში ადმინ-UI-ით ან publish --private-ით. არტეფაქტი არასოდეს ტოვებს ინსტანციას.
საჯარო (ყველასთვის) — publish --public ხსნის PR-ს საჯარო კატალოგში; განხილვის შემდეგ AiHummer თანახელს აწერს release-ს და აქვეყნებს მას საზოგადოების კატალოგში.

სრული მიმოხილვისთვის იხილეთ პლაგინის გამოქვეყნება.

სად შემდეგ

პლაგინის გამოქვეყნება — პირადი side-load და საჯარო registry, წარდგენის კონტრაქტი, მოდერაცია.
უკოდო ინტეგრაციები — openapi და mcp სახეობები დეტალურად.
ინსტალაცია და განახლებები — რა მართავს install[]-ს, ჯანმრთელობის ბარიერი, ნდობა და ხელმოწერილი განახლებები.
Marketplace: მიმოხილვა და დონეები — სად ცხოვრობს თითოეული სახეობა და როგორ განსხვავდება ოფიციალური კატალოგი საზოგადოებისგან.