პლაგინების განვითარების ნაკრები

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

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

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

[!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`.

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

მ_manifestის ველები

აუცილებელი ველი დამოკიდებულია კარგი და იმაზე, whether დანამატი საჯაროა. ბაზის და იდენტობის ველები:

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

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

ხელი	კარგისთვის	საჭიროა	მიზანი
`host_native.exec_start`	რთოვნება, მომსახურება	კი	კომანდა, რომელიც იწყებს ხანგრძლივ სერვისს.
`host_native.runtime`	კონექტორი, სერვისი, mcp	არა	`node` \| `python` \| `binary`.
`host_native.install`	კონექტორი, სერვისი, mcp	არა	გადადგმული ნაბიჯები (შელშის ბრძანებების მასივი), შეასრულეთ მასზე ჰოსტზე გამოხსნის შემდეგ.
`host_native.port`	რთოვნება, მომსახურება	არა	პროფილური TCP პორტი (დეპლოიერი შეუძლია გადაამოტვირთოს საშუალებით `$PORT`).
`host_native.health_path`	რთოვნება, მომსახურება	არა	მოვლის მდგომარეობის შემოწმების გზა (სტანდარტულად) `/healthz`).
`openapi.spec_url`	ოპენაპი	კი	OpenAPI 3.x-ის სპეციფიკაციის URL.
`openapi.base_url`	ოპენაპი	არა	გადამიზნვა `servers[0].url`.
`openapi.allowed_hosts`	ოპენაპი	არა	გამავალი ტრაფიკის თეთრი სია სინთეზირებული ინსტრუმენტებისთვის.
`openapi.auth`	ოპენაპი	არა	ბარათი `securityScheme` → საიდუმლო სახელი.
`openapi.tool_prefix`	ოპენაპი	არა	ინსტრუმენტის სახელის პრეფიქსი.
`mcp.transport`	მსრ	კი	`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 განცხადება კიდევ უფრო მოკლეა — ის უბრალოდ მიუთითებს სპეციფიკაციაზე:

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

მანიფესტიდან ბაზრამდე

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

პირადი (თვითისთვის) — ატვირთეთ თქვენს ეგზემპლარზე ადმინისტრაციული ინტერფეისის საშუალებით ან publish --private. არტეფაქტი არასდროს ტოვებს ინსტანსს.
სამეგობრო (ყველასთვის) — ატვირთეთ შეფუთული, ხელმოწერილი არტეფაქტი ჩემები პლაგინები თქვენს პირად კაბინეტში; AI-ის განხილვისა და ადამიანის მოდერაციის შემდეგ იგი ხელმოწერილია და საზოგადოებაში გამოქვეყნებულია კატალოგი.

ხედვა პლაგინის გამოქვეყნება სრული ნაბიჯ-ნაბიჯ სახელმძღვანელოსთვის.

სად შემდეგ

პლაგინის გამოქვეყნება — კერძო გვერდითი ჩატვირთვა და საზოგადოებრივი გამოქვეყნება პირადი კაბინეტის საშუალებით, შემოწმება და მოდერაცია.
კოდის გარეშე ინტეგრაციები — ეს openapi და mcp ობიექტები დეტალურად.
ინსტალაცია და განახლებები — რა წყვეტს install[], ჯანმრთელობის კარიბჭე, ნდობა და მოწონებული განახლებები.
მარკეტპლეისი: მიმოხილვა და დონეები — სად ყოველი სახეობა ცხოვრობს და როგორ განსხვავდება ოფიციალური კატალოგი საზოგადოებისგან.