AiHummer доки
v1.0.x ▾
v1.0.x stable
RU EN
Маркетплейс и плагины /Публикация плагина

Публикация плагина

v1.0.x · обновлено 2026-06-27

Собрали плагин с Plugin SDK? Опубликовать его можно в двух режимах:

  • Приватно (для себя) — side-load в свой инстанс. Артефакт никогда его не покидает.
  • Публично (для всех) — сабмишн в курируемый публичный каталог AiHummer через PR.

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

Приватный режим — side-load в свой инстанс

Подходит, когда плагин нужен только вам: внутренний коннектор, кастомная интеграция, тестовая сборка.

Шаги

  1. Упакуйте и подпишите бандл: 
    aihummer plugin package ./my-plugin
aihummer plugin sign --key author.key --manifest ./my-plugin/manifest.json my-plugin-1.0.0.tar.gz
  2. Загрузите его в инстанс одним из способов:
    • Admin UI → Plugins → «Загрузить плагин» — перетащите бандл; или
    • CLI: 
      aihummer plugin publish --private --instance https://your-instance \
  --token <admin-token> my-plugin-1.0.0.tar.gz
  3. Под капотом это POST /v1/admin/modules/upload (multipart, право integrations:write): артефакт кладётся в blob-хранилище инстанса (AIHUMMER_BLOB_DIR) под ссылкой blob:, и регистрируется запись каталога с origin = local-private, visibility = private.
  4. Плагин появляется в маркетплейсе с меткой Private и ставится обычным путём — sandbox-юнит systemd + health-гейт.

Доверие: запиненный ключ и trust-store

Приватные артефакты должны быть подписаны. При загрузке плагина, подписанного незнакомым ключом, Admin UI предложит одобрить ключ автора в trust-store инстанса (один клик). После одобрения подпись проверяется на каждой установке и обновлении.

  • Артефакты из официального источника проверяются против запиненного в ядре ключа реестра — доверяются по умолчанию, отдельный шаг не нужен.
  • Приватные артефакты проверяются против ключей в trust-store инстанса.
  • Неподписанные бандлы отклоняются — кроме dev-режима для локальной итерации: AIHUMMER_PLUGIN_DEV_UNSIGNED=1.

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

Публичный режим — публичный реестр

Чтобы плагин стал доступен всем инстансам, он сабмитится в публичный реестр AiHummer/marketplace-catalog через PR: автоматические проверки + ревью, а при одобрении AiHummer контрподписывает релиз.

Шаги

  1. Один раз — регистрация издателя. Сгенерируйте ключ и зарегистрируйте namespace: 
    aihummer plugin keygen                # печатает public key (base64) и key id
    Это резервирует namespace @you. Приватный ключ держите при себе — им подписывается каждый сабмишн.
  2. Опубликуйте артефакт на стабильном HTTPS-URL (артефакт хостит автор, не AiHummer).
  3. Откройте 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 "Что делает плагин" --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 (нужно только при первом сабмишне).
  4. CI-гейты проверяют сабмишн (см. ниже), AI-ревью постит вердикт о рисках, мейнтейнер AiHummer вручную ревьюит и мёржит.
  5. На merge релиз контрподписывается запиненным ключом реестра и публикуется в отдельный 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] в 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 над релизной идентичностью>",
  "manifest": { "...полный объект Manifest..." }
}
  • 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 не выполняют merge сами — решение всегда за мейнтейнером, и ничто не попадает в каталог без его одобрения. Уже опубликованный плагин, оказавшийся вредоносным или сломанным, может быть отозван и исключён из каталога при следующей синхронизации.

Community-каталог как дополнительный источник

Публичные плагины публикуются в отдельный community-catalog.json, который не перезаписывает курируемый первопартийный каталог. Инстанс подключает его как доп-источник в Plugins → Sources (или POST /v1/admin/modules/catalog/sources). Подробнее — в Установке и обновлениях и Обзоре и тирах.

Куда дальше