Каталог плагинов

Каталог плагинов — это отобранный вручную справочник расширений Hermes. Каждую запись читал живой человек, а поставить любое из них можно по имени, одной командой:

hermes plugins install <name>

Полистать каталог глазами удобнее на странице каталога плагинов: записи разложены по полкам-категориям (Memory, Desktop, Platforms, Web & Browser, Tools, Voice, Automation, Models), есть поиск, фильтр по уровню (официальные и от сообщества), плашки с возможностями плагина, а у каждой записи — готовая команда установки, которую можно скопировать.

У каждой записи есть и собственная страница /docs/plugins/<name> (клик по карточке): полное описание и раскрытие рисков, если оно есть, закреплённый коммит, инструменты, хуки и переменные окружения, кнопка установки в десктоп и команда CLI, необязательные скриншоты и README из проверенного коммита, а также полка More by this author. У авторов есть страница /docs/plugins/by/<maintainer> со всем, что они поддерживают в каталоге. Обе страницы генерируются при сборке из тех же файлов каталога, так что изменить страницу можно только влитым PR.

Каталог не заменяет систему плагинов, а достраивается над ней. Всё, что вы ставите из каталога, внутри остаётся обычным плагином — каталог добавляет к этому только удобный поиск и слой проверки.

Во время онбординга в десктопе мастер настройки тоже может предложить плагины и навыки из каталога — через карточку подтверждения. Каждая строка ставится в профиль default только после нажатия Install и ровно на том проверенном коммите, о котором говорит эта страница.

Из чего состоит запись

Одна запись каталога — небольшой YAML-файл в папке plugin-catalog/ репозитория hermes-agent. В нём объявлено:

Модель доверия

Каталог собран так, чтобы вы точно знали, что именно ставите:

• Заявки вливает человек. Каждая запись и каждое обновление пина проходят через pull request, который смотрит мейнтейнер. Автоматически в каталог не попадает ничего.
• Пин на конкретный SHA. Запись закреплена за коммитом, а не за ветками. Автор плагина может залить в свой репозиторий что угодно — на то, что установит каталог, это не повлияет: сдвинуть пин можно только новым проверенным PR.
• Сканируется при приёме, доверяется при установке. CI приёма гоняет тот же сканер безопасности, что и установщик (hermes plugins validate включает проверку security scan): вердикт dangerous проваливает запись, находки уровня caution перечисляются для проверяющего. Раз проверяющий их видел, установка из каталога ровно на закреплённом SHA не останавливается, чтобы спросить про caution ещё раз; dangerous по-прежнему блокирует, а всё, что ставится по сырому URL или на другой ревизии, получает обычный запрос.
• Десктопные плагины работают с полномочиями приложения — граница здесь в проверке. desktop/plugin.js плагина исполняется внутри самого десктопного приложения, в той же среде, что и собственный код приложения: песочницы нет, и он может всё, что может приложение (RPC к шлюзу, весь мост window.hermesDesktop, хранилище других плагинов). Защищает вас описанная выше модель доверия — человек прочитал ровно закреплённый коммит, и ставится именно он, — плюс две растяжки: линт desktop surface при приёме отказывает в очевидных действиях за пределами SDK плагинов (патчинг встроенных прототипов, eval, импорт чего-либо кроме @hermes/plugin-sdk/react, подключение удалённых скриптов), а загрузчик приложения ещё раз отклоняет любой импорт не из SDK при загрузке. Регулярку <script — литерал или строку шаблона new RegExp(...), переданную прямо в .replace()/.split()/.match() или использованную как .test()/.exec(), — линт понимает как санитайзер, которым она и является, а не как инъекцию; строка <script, записанная в DOM, в том числе собранная из new RegExp(...).source, по-прежнему не проходит. Считайте линт подспорьем для проверки, а не гарантией: десктопную часть проверяйте так же придирчиво, как Python-часть.
• Никаких подмен Hermes в рантайме. Плагины из каталога расширяют Hermes через его публичные поверхности (хуки, middleware, профили провайдеров, слоты SDK десктопа) и никогда не заменяют на месте функции, методы ядра или интерфейс десктопа: два плагина, патчащие один и тот же шов, сломали бы друг друга, а релиз ядра мог бы сломать оба. Проверка приёма no core override отклоняет Python, который в рантайме переопределяет модули, классы Hermes или их таблицы, а линт desktop surface отклоняет код desktop/plugin.js, который опрашивает собственную разметку приложения, чтобы перекрасить, скрыть, нажать или переписать интерфейс ядра.
• Объявленные возможности. Запись заранее говорит, какие инструменты, хуки и middleware даёт плагин и какие переменные окружения (ключи API и прочее) ему нужны. Так масштаб возможных последствий видно до установки.
• Список отозванных. Плагины, убранные из каталога — скажем, после инцидента безопасности, — попадают в plugin-catalog/removed.yaml с причиной и датой. Совпадение ищется по имени или идентичности репозитория — написания git@, ssh://, http:// и www. одного и того же репозитория считаются совпадающими. Установщик отказывается ставить то, что в этом списке, а плагин, попавший в список после установки, перестаёт обновляться, не включается и отклоняется при загрузке (hermes plugins remove <name> или переустановка с --allow-removed, чтобы оставить его осознанно).
• Установлен — не значит включён. Установка кладёт плагин на диск; как и любой другой, перед загрузкой он должен быть включён. См. Плагины → Включение и отключение.

Установка из каталога

# Поставить проверенную запись каталога по имени (забирает закреплённый SHA)
hermes plugins install <name>

# Затем включить, как любой другой плагин
hermes plugins enable <name>

Перед тем как что-то будет склонировано, приглашение установки покажет сводку возможностей записи: объявленные инструменты, хуки и требуемые переменные окружения. В терминале затем следует вопрос «Enable now?», так что при ответе «да» две команды выше сводятся к одному шагу (для скриптов на него отвечают флаги --enable / --no-enable).

Имя в каталоге и имя из собственного манифеста плагина могут различаться. Любая последующая команда (enable, disable, show, capabilities, update, remove) принимает любое из них: имя из каталога разрешается через запись об установке, которую Hermes сделал при клонировании записи, а не через файл в репозитории самого плагина. Например, запись touchdesigner (переносимый пакет Agent Plugins v1, в котором MCP-сервер twozero идёт вместе с навыком touchdesigner-mcp) устанавливается как td — имя специально короткое, чтобы сгенерированные имена его MCP-инструментов укладывались в лимиты провайдеров на длину имени функции:

hermes plugins install touchdesigner
hermes plugins enable touchdesigner   # то же, что: hermes plugins enable td

В десктопном приложении пакет, у которого есть и агентская, и десктопная половина (desktop/plugin.js), — это одна строка с отдельным переключателем на каждую половину. Включение пакета (флажок Enable agent plugin after install в диалоге установки или переключатель Agent в строке) включает и его десктопную половину, если только вы сами её не выключили. Выключение действует отдельно по половинам, потому что десктопная половина общая для всех профилей.

Переносимые пакеты могут нести и stdio-сервер MCP. Запись snyk закрепляет Snyk CLI (npx -y snyk@<version> mcp) и включает навык snyk-security-scan, так что одна установка даёт Hermes сканирование кода, зависимостей, контейнеров и IaC плюс рабочий процесс для этого; имя в каталоге и имя в манифесте здесь совпадают:

hermes plugins install snyk
hermes plugins enable snyk

Обновление того, что поставлено из каталога

Для установок из каталога hermes plugins update <name> никогда не выполняет git pull. Вместо этого команда сравнивает ваш пин с текущим пином каталога и, если каталог сдвинулся (через проверенный PR), готовит новый SHA и проверяет его зависимости, прежде чем опубликовать. Состояние «включён / отключён» при этом сохраняется, как и файлы, которые репозиторий плагина не отслеживает (config.yaml, созданный из его .example, файлы данных, .env). Симлинки среди этих неотслеживаемых файлов никогда не переносятся в новый код: обновление останавливается до публикации и называет их, так что замените каждый обычным файлом. Каталоги зависимостей и кэшей (.venv/, venv/, node_modules/, кэши инструментов) не переносятся вовсе, включая ссылки; обновлённый плагин заново собирает свои зависимости. Установки из монорепозиториев и подкаталогов, у которых нет локального чекаута Git, при обновлении сохраняют файлы пользовательского состояния, которых нет в новой ревизии. Код плагина и управляющие поверхности остаются за ревизией и из старой установки не воскрешаются: исходные файлы (Python, JavaScript/TypeScript, включая .mjs/.cjs/.jsx/.tsx, shell, Ruby, Perl, PHP), каталоги верхнего уровня dashboard/, desktop/, skills/, sidecar/ и node_modules/, манифест плагина, mcp.json и метаданные зависимостей (pyproject.toml, package.json, lock-файлы). Если путь с пользовательским состоянием конфликтует с раскладкой файлов и каталогов нового дерева, обновление останавливается до публикации, так что установленная копия и данные пользователя остаются нетронутыми. Ваши правки в отслеживаемых файлах на новый код не переносятся: их копии сохраняются в ~/.hermes/plugins-backup/<name>-<sha>/, а обновление об этом предупреждает. Если новый пин переименовывает манифест плагина, старый каталог удаляется, а флаг включения переезжает на новое имя. В выводе hermes plugins list такие установки помечены как catalog:<tier>@<sha> — происхождение видно сразу.

Прежде чем новый код активного плагина заменит установленную версию, PM проверяет его зависимости. Сбой на этапе версии, сканирования, зависимостей или публикации оставляет рабочий код и выбор зависимостей как были. Отключённые плагины остаются отключёнными. Происхождение установщик записывает в ~/.hermes/plugins/.install-metadata.json, за пределами дерева самого плагина, — репозиторий не может подложить файл, из-за которого он выглядел бы проверенной установкой из каталога. (.hermes-catalog.json внутри каталога плагина — лишь копия для удобства.) Установка записи каталога с --ref <sha> записывает тот SHA, который вы на самом деле взяли, поэтому list, вкладка Plugins в десктопе и update показывают, что установка ушла с проверенного пина. Плагины из собственных Git-источников сохраняют записанную политику обновления через Git/фид, но проходят ту же проверку и публикацию через PM.

Имена, которых в каталоге нет

Короткое имя, которому не соответствует запись каталога, приводит к ошибке: второго, непроверенного индекса имён не существует. Такие плагины ставьте через owner/repo или git-URL (свой источник, о нём ниже) — либо подайте заявку в каталог.

Обновление на лету

Сборка документации публикует каталог одним JSON-документом (https://hermes-agent.nousresearch.com/docs/api/plugin-catalog.json). Команды search, install и update тянут его не чаще раза в шесть часов и кэшируют в ~/.hermes/cache/, поэтому новые записи и отзывы доходят до установленных клиентов без обновления самого Hermes. Без сети до 24 часов используется закэшированная копия, после чего в дело вступает копия из вашего checkout (неудачная загрузка запоминается на минуту, так что plugins list и страница Plugins в дашборде упираются максимум в один таймаут соединения, а не в один на каждый установленный плагин). Если закэшированный документ и ваш checkout расходятся в пине записи, побеждает более новый из двух: git-checkout, чей каталог закоммичен позже публикации документа (свежий hermes update), ставит собственный пин, а не закэшированный старый. Отзывы соблюдаются всегда — и по списку из репозитория, и по «живому», — каким бы старым ни был кэш.

Свои git-URL — другая история

hermes plugins install <git-url> по-прежнему работает для любого репозитория, но каталог при этом не участвует вообще:

• Никакой проверки — вы получаете то, что лежит на верхушке ветки, а не проверенный пин.
• Показывается предупреждение, чтобы было понятно: код никто не смотрел.
• Список отозванных всё равно учитывается — заведомо плохой репозиторий установить по URL не дадут.

Путь через git-URL хорош для своих плагинов и репозиториев, которым вы и так доверяете. Для поиска нового берите каталог.

Как подать плагин в каталог

Заявка — это pull request, добавляющий один файл plugin-catalog/<name>.yaml. Полные правила изложены на странице Подача плагина в каталог плагинов: что проверить перед подачей, как устроены PR и ревью, все правила приёма, а также обновление пинов, снятие с публикации и удаление. Эта страница отражает канонические правила из README каталога.

Если коротко, плагин из каталога подаёт его владелец (или его добавляют по итогам проверенного обхода мейнтейнеров), он лежит в публичном репозитории, закрепляет точный коммит, проходит hermes plugins validate в CI каталога, никогда не обновляет себя сам и расширяет Hermes только через публичные хуки и SDK десктопа, а не патчит код ядра или интерфейс десктопа в рантайме.

Смотрите также

• Плагины — сама система плагинов: формат манифеста, включение, настройка
• Встроенные плагины — то, что идёт в комплекте с Hermes
• Как написать плагин для Hermes — свой собственный
• Страница каталога плагинов — каталог для просмотра
• Подача плагина в каталог плагинов — правила приёма и руководство по подаче