Публікацыя плагіна — AiHummer Дакументацыя

Пабудавалі плагін з дапамогай Plugin SDK? Вы можаце апублікаваць яго ў двух рэжымах:

Прыватна (для сябе) — бакавая загрузка ў ваш інстанс. Артэфакт ніколі не пакідае яго.
Публічна (для ўсіх) — адправіць у курыраваны афіцыйны каталог AiHummer праз PR.

Аналогія: усталяванне .vsix уручную (прыватна) супраць публікацыі ў VS Code Marketplace (публічна); прыватны рэестр npm супраць публічнага.

Прыватны рэжым — бакавая загрузка ў ваш інстанс

Выкарыстоўвайце гэта, калі плагін патрэбны толькі вам: унутраны канектар, кастамная інтэграцыя, тэставая зборка.

Крокі

Упакуйце і падпішыце бандл:

aihummer plugin package ./my-plugin
aihummer plugin sign --key author.key --manifest ./my-plugin/manifest.json my-plugin-1.0.0.tar.gz

Загрузіце яго ў інстанс адным з двух спосабаў:
- Адмін-інтэрфейс → Plugins → «Upload plugin» — перацягніце бандл; або
- CLI:
```
aihummer plugin publish --private --instance https://your-instance \
  --token <admin-token> my-plugin-1.0.0.tar.gz
```
Пад капотам гэта POST /v1/admin/modules/upload (multipart, integrations:write): артэфакт трапляе ў blob-сховішча інстанса (AIHUMMER_BLOB_DIR) пад спасылкай blob:, і рэгіструецца радок каталога з origin = local-private, visibility = private.
Плагін з’яўляецца ў маркетплейсе з тэгам Private і ўсталёўваецца праз звычайны шлях — ізаляваны юніт systemd + кантроль спраўнасці.

Давер: замацаваны ключ і сховішча даверу

Прыватныя артэфакты павінны быць падпісаны. Калі вы загружаеце плагін, падпісаны невядомым ключом, адмін-інтэрфейс прапануе вам зацвердзіць ключ аўтара ў сховішча даверу інстанса (адзін клік). Пасля зацвярджэння подпіс правяраецца пры кожным усталяванні і абнаўленні.

Артэфакты з афіцыйнай крыніцы правяраюцца адносна ключа рэестра, замацаванага ў ядры — давераныя па змаўчанні, без дадатковых крокаў.
Прыватныя артэфакты правяраюцца адносна ключоў у сховішчы даверу інстанса.
Непадпісаныя бандлы адхіляюцца — акрамя рэжыму распрацоўкі для лакальных ітэрацый: AIHUMMER_PLUGIN_DEV_UNSIGNED=1.

[!WARNING] AIHUMMER_PLUGIN_DEV_UNSIGNED=1 адключае праверку подпісу і прызначаны толькі для лакальнай распрацоўкі. Ніколі не ўключайце яго на інстансе, даступным звонку.

Публічны рэжым — публічны рэестр

Каб зрабіць плагін даступным для кожнага інстанса, адправіце яго ў публічны рэестр AiHummer/marketplace-catalog праз PR: аўтаматызаваныя праверкі + агляд, і пасля зацвярджэння AiHummer сустрэчна падпісвае рэліз.

Крокі

Аднаразова — зарэгіструйце выдаўца. Згенеруйце ключ і зарэзервуйце прастору імён:
```
aihummer plugin keygen                # prints the public key (base64) and key id
```
Гэта рэзервуе прастору імён @you. Захоўвайце прыватны ключ пры сабе — ён падпісвае кожную адпраўку.
Размясціце артэфакт па стабільным URL HTTPS (артэфакт размяшчаецца аўтарам, а не AiHummer).

Адкрыйце PR у каталог:

aihummer plugin publish --public --dir ./my-plugin --key author.key \
  --artifact-url https://you.example.com/my-plugin-1.0.0.tar.gz \
  --publisher you --description "What the plugin does" --icon https://you.example.com/icon.svg \
  [--screenshot https://you.example.com/1.png ...] [--channel stable|beta] \
  [--register-key author.pub]

--register-key дадае publishers/<you>.json (патрэбны толькі пры вашай першай адпраўцы).

Гейты CI валідуюць адпраўку (гл. ніжэй), AI-агляд публікуе вердыкт рызыкі, і мэйнтэйнер AiHummer правярае і ўручную выконвае зліццё.
Пры зліцці рэліз сустрэчна падпісваецца замацаваным ключом рэестра і публікуецца ў асобны community-catalog.json на CDN. Кожны інстанс, які дадаў гэтую крыніцу, бачыць плагін; ядро давярае яму праз замацаваны ключ — ніякі крок даверу для кожнага аператара не патрэбны.

Кантракт адпраўкі

PR дадае два файлы (форма генеруецца publish --public і стабільная):

publishers/<publisher>.json — аднаразовая рэгістрацыя:

{
  "publisher": "acme",
  "public_key": "<base64 std ed25519 public key>",
  "key_id": "<sha256(public_key)[:16] in hex>",
  "contact": "you@example.com"
}

catalog/<publisher>/<slug>/plugin.json — адпраўка (адна на лінію версій):

{
  "publisher": "acme",
  "slug": "hello-tool",
  "namespaced_slug": "@acme/hello-tool",
  "version": "1.0.0",
  "channel": "stable",
  "artifact_url": "https://acme.example.com/hello-tool-1.0.0.tar.gz",
  "license": "MIT",
  "publisher_key_id": "bd68f2deedad25b1",
  "signature": "<base64 ed25519 over the release identity>",
  "manifest": { "...the full Manifest object..." }
}

namespaced_slug павінен раўняцца @<publisher>/<slug>.
channel ∈ stable | beta.
artifact_url — гэта .tar.gz, размешчаны аўтарам.
publisher_key_id павінен супадаць з key_id зарэгістраванага выдаўца.
Падпісаная ідэнтычнасць рэлізу = байты slug \x00 version \x00 artifact_url.
Для публічнай адпраўкі ўбудаваны manifest павінен несці description, icon (і опцыянальна screenshots) — гл. палі старонкі ў краме.

[!TIP] aihummer plugin publish --public збірае гэтыя файлы ў патрэбнай форме і адкрывае PR за вас — няма патрэбы рэдагаваць JSON уручную.

Мадэрацыя

Кожная адпраўка праходзіць аўтаматызаваную праверку (кантракт адпраўкі, подпіс і сканіраванне бяспекі), затым дарадчы AI-агляд рызыкі і нарэшце абавязковы агляд чалавекам камандай AiHummer. Ні аўтаматыка, ні AI ніколі не выконваюць зліццё самастойна — рашэнне заўсёды за мэйнтэйнерам, і нічога не трапляе ў каталог без яго зацвярджэння. Апублікаваны плагін, які пазней апынуўся шкоднасным або зламаным, можа быць адкліканы і выдалены з каталога пры наступнай сінхранізацыі.

Супольнасны каталог як дадатковая крыніца

Публічныя плагіны публікуюцца ў асобны community-catalog.json, які не перазапісвае курыраваны першапраўны каталог. Інстанс дадае яго як дадатковую крыніцу ў Plugins → Sources (або POST /v1/admin/modules/catalog/sources). Гл. Усталяванне і абнаўленні і Агляд і ўзроўні.

Куды далей

Plugin SDK — палі маніфеста і каманды aihummer plugin.
Усталяванне і абнаўленні — шматкрынічнасць, мадэль даверу, падпісаныя абнаўленні, ранжыраванне.
Маркетплейс: агляд і ўзроўні — афіцыйны супраць супольнаснага рэестра.