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

Собрали плагин с [Plugin SDK](/v1.0/marketplace/sdk)? Опубликовать его можно **двумя способами**: - **Приватно (для себя)** — частная загрузка (side-load) в *свой* инстанс. Артефакт никогда его не покидает. - **Для сообщества (для всех)** — публикация через ваш [личный кабинет](/v1.0/portal/overview) на **my.aihummer.ru**, как в App Store: загружаете сборку, заполняете витрину, проходите проверку — и плагин попадает в подписанный community-каталог, откуда его может установить любой инстанс. Аналогия: установка `.vsix` вручную (приватно) против публикации в магазине приложений (для сообщества). > [!WARNING] > **Плагины сообщества сейчас установить нельзя — и это не сбой связи.** > Ключ, которым подписывался каталог сообщества, отозван; до выпуска нового > ключа проверка подписи такие записи отклоняет. Отдельно от этого сторонний > код пока не запускается службой на вашем сервере: до появления изолированной > среды выполнения разрешены только интеграции, которые работают на своей > стороне и подключаются по сети. > > **Что вы увидите:** после нажатия «установить» появится обычное сообщение > «устанавливается», но плагин **не появится** в списке установленных. Причина > отказа записывается в журнал шлюза — откройте **Логи** в панели управления. > > **Что работает прямо сейчас:** > > - **плагины от AiHummer** из официального каталога — ставятся как обычно, у > них другая, действующая подпись; > - **MCP-сервер по HTTP** — подключается как источник инструментов без > разработки, код остаётся на вашей стороне; > - **интеграция по спецификации OpenAPI** — то же самое, без установки службы. > > Частная загрузка (side-load) собственного плагина проходит проверку подписи, > но запустится только в виде **удалённого MCP по HTTP** или интеграции > OpenAPI; сборка, которую нужно запустить службой на этом же сервере, будет > отклонена. ## Приватный режим — частная загрузка в свой инстанс Подходит, когда плагин нужен только вам: внутренний коннектор, кастомная интеграция, тестовая сборка. ### Шаги 1. Упакуйте и подпишите бандл: ```bash aihummer plugin package ./my-plugin aihummer plugin sign --key author.key --manifest ./my-plugin/manifest.json my-plugin-1.0.0.tar.gz ``` 2. Загрузите его в инстанс одним из способов: - **Админ-панель → Плагины → «Загрузить плагин»** — перетащите пакет; или - CLI: ```bash 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 + проверка `/healthz`](/v1.0/marketplace/install-updates). ### Доверие: закреплённый ключ и trust-store Приватные артефакты **должны быть подписаны**. При загрузке плагина, подписанного незнакомым ключом, админ-панель предложит **одобрить ключ автора** в trust-store инстанса (один клик). После одобрения подпись проверяется на каждой установке и обновлении. - Артефакты из **официального** источника проверяются против **закреплённого в ядре ключа реестра** — доверяются по умолчанию, отдельный шаг не нужен. - **Приватные** артефакты проверяются против ключей в trust-store инстанса. - **Неподписанные** пакеты отклоняются — кроме dev-режима для локальной итерации: `AIHUMMER_PLUGIN_DEV_UNSIGNED=1`. > [!WARNING] > **Что произойдёт:** инстанс начнёт принимать неподписанные плагины, включая > потенциально вредоносные. **При каком условии:** если включить > `AIHUMMER_PLUGIN_DEV_UNSIGNED=1` на доступном извне инстансе — флаг > предназначен только для локальной разработки. **Как исправить:** уберите флаг > и перезапустите шлюз; проверку подписи нельзя отключать в промышленной > эксплуатации. ## Режим для сообщества — публикация через личный кабинет Чтобы плагин стал доступен **всем** инстансам, опубликуйте его из **личного кабинета** на **my.aihummer.ru** — так же, как вы публикуете приложение в магазине приложений. Вы загружаете сборку, заполняете витрину и отправляете на проверку: сначала прогоняется автоматическая проверка с помощью ИИ, затем финальное решение принимает модератор-человек, и при одобрении артефакт подписывается и публикуется в community-каталог. Полный пошаговый разбор — на странице [Публикация через личный кабинет](/v1.0/marketplace/submit-plugin). Кратко: 1. **Соберите и упакуйте** плагин через SDK ([`aihummer plugin package`](/v1.0/marketplace/sdk)) — артефакт это подписанный `.tar.gz` со своим `manifest.json`. 2. **Откройте «Мои плагины»** в кабинете и создайте заявку: **загрузите артефакт**, заполните **метаданные витрины** (название и описания на RU + EN, версия, иконка, скриншоты, категория, необязательная ссылка на донат, changelog) и задекларируйте [capability-манифест](/v1.0/marketplace/submit-plugin#шаг-3--задекларируйте-capability-манифест). 3. **Отправьте на проверку.** Автоматическая **проверка с помощью ИИ** проверяет заявку по [политике проверки](/v1.0/marketplace/review-policy) (безопасность, корректность манифеста, полнота, контент), затем **модератор-человек** читает отчёт и принимает решение. Автоматика ничего не публикует сама. 4. **При одобрении** артефакт **подписывается** и публикуется в **отдельный `community-catalog.json`** на CDN. Каждый инстанс, подключивший источник сообщества, видит плагин; ядро доверяет ему через **закреплённый ключ реестра** — отдельного шага доверия оператору не требуется. > [!NOTE] > **Прежний публичный поток публикации выведен из эксплуатации**; единственный > путь публикации для сообщества — описанный выше поток через личный кабинет, > раздел «Мои плагины». Плагины сообщества **бесплатны**; > можно добавить необязательную ссылку на донат. > [!NOTE] > **Первопартийные плагины** (Einstein, SIP, Bitrix24, pocket-agent, os-client) > так не публикуются — они выходят по собственному CI AiHummer и попадают в > закреплённый официальный каталог. Поток через личный кабинет — для **плагинов > сообщества (сторонних)**. ## Модерация Каждая заявка сообщества проходит три отдельных этапа: (1) **автоматическую проверку** (полнота, capability-манифест, **авторская подпись** артефакта и скан безопасности), (2) **автоматическую проверку с помощью ИИ** — оценку рисков по политике, и (3) **обязательную ручную проверку человеком** из команды AiHummer. Ни автоматика, ни ИИ не публикуют сами — решение всегда за модератором, и ничто не попадает в каталог без его одобрения. Только после одобрения происходит **контрподпись AiHummer**: артефакт подписывается ключом реестра и публикуется — это три разные операции, а не одна. Уже опубликованный плагин, оказавшийся вредоносным или сломанным, может быть **отозван** и исключён из каталога при следующей синхронизации. ## Community-каталог как дополнительный источник Плагины сообщества публикуются в **отдельный** `community-catalog.json`, который **не** перезаписывает курируемый первопартийный каталог. Инстанс подключает его как дополнительный источник в **Плагины → Источники** (или `POST /v1/admin/modules/catalog/sources`). Подробнее — в [Установке и обновлениях](/v1.0/marketplace/install-updates#мульти-источник-каталога) и [Обзоре и уровнях](/v1.0/marketplace/overview-tiers#official-и-community). ## Жизненный цикл плагина (App Store) Маркетплейс работает как полноценный App Store — у каждого плагина есть **постоянная учётная запись** (постоянный `slug` + автор), под которой выходят **версии**. ### Версии и обновления Обновление выпускается **новой версией** уже опубликованного плагина: тот же slug, свой changelog, отдельная проверка и модерация. В работе одновременно может быть **только одна** версия — новую можно отправить после решения по текущей. Когда новая версия публикуется, предыдущая помечается как заменённая (`superseded`), а в каталоге и на инстансах становится актуальной новая. ### Публикация по расписанию После одобрения модератором **публикацию контролирует автор**: опубликовать сразу или запланировать на конкретное время — плагин станет доступен в назначенный момент. ### Снятие с публикации - **Пауза** — временно скрыть плагин: он пропадает из публичного каталога и с инстансов (при следующей синхронизации), но сохраняется и может быть **возвращён** в любой момент. - **Снятие навсегда** — плагин удаляется из маркетплейса окончательно. Как только плагин снят (пауза или навсегда), запись убирается из `community-catalog.json`, и на следующей синхронизации инстансы перестают его показывать. ### Авторство Плагин публикуется под **вашим отображаемым именем** (например, названием студии) — или **анонимно**. В публичном каталоге и в веб-интерфейсе инстанса показывается выбранное имя либо «Аноним»; настоящий адрес электронной почты/идентификатор никогда не раскрывается. ### Статистика разработчика По каждому плагину доступна **агрегированная статистика**: скачивания, установки, активные инстансы и удаления, плюс дневной график. Только сводные цифры — данные по отдельным инстансам разработчику не раскрываются. ### Награда за публикацию За **каждый впервые опубликованный** плагин к вашей подписке AiHummer добавляется **один бесплатный месяц** (начисляется один раз на плагин). ## Куда дальше - [Публикация через личный кабинет](/v1.0/marketplace/submit-plugin) — полный пошаговый разбор: метаданные, capability-манифест, ИИ-проверка и модерация. - [Plugin SDK](/v1.0/marketplace/sdk) — поля манифеста и команды `aihummer plugin`. - [Установка и обновления](/v1.0/marketplace/install-updates) — мульти-источник, модель доверия, подписанные обновления, ранжирование. - [Политика проверки и чек-лист](/v1.0/marketplace/review-policy) — критерии, по которым проверяют плагин перед публикацией. - [Маркетплейс: обзор и уровни](/v1.0/marketplace/overview-tiers) — official и реестр сообщества.