Skip to main content
Зависимость плагина — это другой плагин, на который полагается ваш плагин, например плагин, чей MCP-сервер или skill вы вызываете. Каждая зависимость отслеживает последнюю версию, которую предоставляет её маркетплейс, если вы не объявите ограничение версии — диапазон семантических версий, такой как ^2.0 или ~2.1.0, который вы протестировали. Эта страница предназначена для авторов плагинов, которые объявляют зависимости в plugin.json, и для администраторов маркетплейсов, которые помечают релизы.
Эти случаи рассмотрены на других страницах:
Чтобы добавить ограничение, начните с раздела Объявить зависимость с ограничением версии. Если вы поддерживаете плагин, от которого зависят другие, помечайте ваши релизы, чтобы их ограничения могли разрешиться.

​
Объявить зависимости

Без ограничения версии зависимость переходит на каждый новый релиз, который её маркетплейс публикует, в следующий раз, когда пользователи обновляют. Если этот релиз переименует MCP-инструмент, который вызывает ваш плагин, ваш плагин сломается для всех, кто обновляет. С ограничением, таким как ~2.1.0, на зависимость из источника на основе git, пользователи, у которых установлен ваш плагин, продолжают получать патчи 2.1.x зависимости и никогда не переходят на 2.2. Чтобы обновить по собственному расписанию, протестируйте более новый релиз, а затем опубликуйте новую версию вашего плагина с более широким ограничением.

​
Объявить зависимость с ограничением версии

Перечислите зависимости в массиве dependencies файла .claude-plugin/plugin.json вашего плагина. Следующий манифест объявляет одну зависимость без версии и одну зависимость с ограничением:
.claude-plugin/plugin.json
Запись может быть строкой: только имя плагина, такое как "audit-logger" в этом манифесте, или "name@marketplace" для разрешения в другом маркетплейсе. С простой строкой ваш плагин зависит от любой версии, которую предоставляет маркетплейс этого плагина. Чтобы установить ограничение версии, используйте объект с этими полями, каждое из которых является строкой: Диапазон не совпадает с версиями предварительного выпуска, такими как 2.0.0-beta.1, если вы не согласитесь с суффиксом предварительного выпуска, таким как ^2.0.0-0.

​
Объединить плагины для команды

Чтобы позволить инженерам установить тщательно отобранный набор плагинов одной командой, опубликуйте плагин, чей манифест содержит name и массив dependencies. Манифест плагина нужен только name, поэтому это действительный плагин, и его установка устанавливает каждую зависимость. Например, команда платформы может опубликовать пакеты, специфичные для ролей, во внутреннем маркетплейсе, чтобы инженеры запустили одну команду claude plugin install вместо установки каждого плагина отдельно:
.claude-plugin/plugin.json
Чтобы добавить плагин в стандартный набор позже, опубликуйте новую версию backend-standard с дополнительной зависимостью. Когда маркетплейс не автоматически обновляется по умолчанию, инженеры либо включают автоматическое обновление для маркетплейса, либо обновляют вручную:
  • Включить автоматическое обновление для маркетплейса: следующее автоматическое обновление переместит пакет на новую версию и установит любые зависимости, которые он добавляет.
  • Обновить вручную: запустите claude plugin update backend-standard в оболочке, затем /reload-plugins в открытой сессии, чтобы установить вновь добавленные зависимости.
Для шагов со стороны инженера см. Держите плагины в актуальном состоянии. Чтобы развернуть пакет для всех в организации, администратор добавляет его в enabledPlugins в управляемых параметрах. См. Предварительная установка и требование плагинов.

​
Зависимость от плагина из другого маркетплейса

По умолчанию Claude Code не устанавливает зависимость из другого маркетплейса, чем собственный маркетплейс объявляющего плагина, если пользователь уже не установил эту зависимость и не включил её в той же области. Это значение по умолчанию предотвращает молчаливую установку плагинов из источника, который пользователь не проверил, одним маркетплейсом. Чтобы разрешить установку, добавьте имя целевого маркетплейса в allowCrossMarketplaceDependenciesOn в marketplace.json корневого маркетплейса. Корневой маркетплейс — это тот, который размещает плагин, который устанавливает пользователь. Применяется только список разрешений корневого маркетплейса. Следующий marketplace.json позволяет deploy-kit зависеть от плагина из your-shared-marketplace:
.claude-plugin/marketplace.json
Если allowCrossMarketplaceDependenciesOn отсутствует или не включает целевой маркетплейс, Claude Code не устанавливает зависимость. Когда зависимость объявлена в записи маркетплейса, сама установка отклоняется с сообщением, которое начинается с Dependency "audit-logger@your-shared-marketplace" (required by deploy-kit@your-marketplace) is in marketplace "your-shared-marketplace", which is not in the allowlist и называет поле для установки. Когда она объявлена в plugin.json, установка завершается без зависимости, и ваш плагин затем не загружается. Проверка списка разрешений не применяется к зависимости, которая уже включена. Если пользователь сначала сам установит audit-logger из your-shared-marketplace в той же области, deploy-kit затем устанавливается без каких-либо изменений в списке разрешений.

​
Протестировать плагин и его зависимость локально

Если вы разрабатываете плагин и плагин, от которого он зависит, одновременно, запустите Claude Code из вашей оболочки и загрузите оба с помощью --plugin-dir:
Локальная копия зависимости удовлетворяет записи зависимости вашего плагина, поэтому вам не нужно устанавливать зависимость из её маркетплейса.
  • Не требуется version: локальный plugin.json также не нуждается в version, потому что ограничение версии не проверяется против локальной копии.
  • Записи, которые называют маркетплейс: запись, которая называет маркетплейс, также совпадает с локальной копией на Claude Code v2.1.242 или позже.
Пока вы не установите зависимость из её маркетплейса, ваш плагин перестаёт загружаться всякий раз, когда локальная копия отключена или отсутствует:
  • Вы отключили локальную копию: ваш плагин отключается при следующей загрузке плагина с ошибкой, которая заканчивается на is disabled — enable it or remove the dependency. Когда ошибка называет зависимость как <name>@inline, этот идентификатор относится к копии --plugin-dir.
  • Вы запустили сессию без флага --plugin-dir зависимости: ошибка сообщает, что зависимость не установлена. Передайте флаг снова или установите зависимость из её маркетплейса.
Когда оба плагина находятся в одной родительской папке, вы можете передать эту папку в --plugin-dir один раз. Если папка сама по себе не является плагином, Claude Code загружает каждую дочернюю папку, которая имеет .claude-plugin/plugin.json. Требуется Claude Code v2.1.265 или позже.

​
Выпустить плагин, от которого зависят другие

Если вы поддерживаете плагин, от которого другие плагины зависят с ограничением версии, помечайте его релизы, чтобы эти ограничения могли разрешиться. Ограничение разрешается против git-меток в репозитории, который размещает плагин. Помечайте репозиторий, на который указывает источник плагина плагина в marketplace.json:
  • Источник github, url или git-subdir: собственный репозиторий плагина, поэтому автор плагина создаёт метки
  • Относительный путь, такой как ./plugins/secrets-vault: репозиторий маркетплейса, поэтому администратор маркетплейса создаёт метки

​
Создать метку релиза

Помечайте каждый релиз как <plugin-name>--v<version>, где <version> совпадает с полем version в plugin.json этого коммита. Префикс plugin-name позволяет одному репозиторию маркетплейса размещать несколько плагинов с независимыми историями версий. Создайте метку из директории плагина с настроенным удалённым origin для получения отправленной метки, используя claude plugin tag:
Команда строит имя метки из манифеста плагина. Перед созданием метки она запускает эти проверки:
  • Проверяет плагин
  • Проверяет, что plugin.json и запись маркетплейса согласны по версии, когда директория плагина находится внутри проверки маркетплейса
  • Требует чистое рабочее дерево под директорией плагина
  • Отказывает, если метка уже существует
Успешный запуск выводит Created tag secrets-vault--v2.1.0. С --push он также выводит Pushed to origin. Без --push он выводит команду git push для запуска самостоятельно. Передайте --dry-run, чтобы увидеть план без создания чего-либо. Справочник claude plugin tag перечисляет оставшиеся флаги. Вы также можете запустить git tag secrets-vault--v2.1.0 напрямую, если вы сохраняете version в plugin.json и в записи маркетплейса в синхронизации самостоятельно.

​
Ограничить зависимость, которая имеет источник, не основанный на git

Разрешение на основе меток применяется только к источникам на основе git. Для зависимости с источником npm, archive или command plugin source, ограничение не контролирует, какая версия будет получена. Оно всё ещё проверяется при загрузке плагина, и зависимый плагин отключается, если установленная версия не удовлетворяет ему. Для источников npm, archive и command, проверяемая версия — это version в plugin.json зависимости. Установите его там перед ограничением этой зависимости, потому что plugin.json, который не устанавливает версию, не удовлетворяет никакому ограничению. Claude Code никогда не устанавливает зависимость с источником command самостоятельно, поэтому пользователи устанавливают её первыми. Он также никогда не запускает headersHelper зависимости, поэтому пользователи также устанавливают зависимость, чья запись маркетплейса устанавливает её перед установкой вашего плагина. Помимо claude plugin install, эти операции также устанавливают любую отсутствующую объявленную зависимость, и ограничения command и headersHelper применяются к ним также:
  • /reload-plugins
  • Автоматическое обновление маркетплейса зависимого плагина
  • Повторный запуск claude plugin install на зависимом плагине
  • claude plugin marketplace add

​
Как зависимости ведут себя для ваших пользователей

Эти разделы описывают, как Claude Code разрешает, проверяет и объединяет ограничения, которые вы объявляете, когда ваш плагин установлен вместе с другими.

​
Как ограничение разрешается против меток

Когда пользователь устанавливает плагин, который объявляет { "name": "secrets-vault", "version": "~2.1.0" }, зависимость устанавливается из самой высокой метки secrets-vault--v, которая удовлетворяет ~2.1.0 в репозитории, который размещает secrets-vault. Когда никакая метка не удовлетворяет диапазону, установка либо не удаётся, либо использует текущую копию маркетплейса:
  • Плагин с собственным репозиторием: установка не удаётся с сообщением, содержащим Dependency "secrets-vault@your-marketplace" has no git tag satisfying.
  • Плагин, на который ссылается относительный путь: установка использует текущую копию маркетплейса вместо этого, и ограничение проверяется при загрузке плагина. Если эта копия находится вне диапазона, зависимый плагин остаётся отключённым и claude plugin list показывает Requires "secrets-vault@your-marketplace" ~2.1.0, installed 3.0.0.
Для плагина, на который маркетплейс ссылается относительным путём, маркетплейс, который вы добавили как путь локальной папки, также разрешает ограничения против git-меток этой папки, когда папка является git-репозиторием. Это требует Claude Code v2.1.196 или позже. Локальная папка, которая не является git-репозиторием, не имеет меток, поэтому Claude Code устанавливает зависимость из текущего содержимого папки вместо этого.

​
Подтвердить разрешённую версию

Чтобы подтвердить, какую версию разрешило ограничение, запустите claude plugin list в вашей оболочке. Зависимость, разрешённая меткой, показывает свою версию с суффиксом коммита из 12 символов, такой как 2.1.0-8713c5b11005. Проверки ограничений используют версию метки, а не version в plugin.json, даже если plugin.json в этом коммите отстаёт. Если вы принудительно переместите метку на другой коммит, следующая установка получит содержимое этого коммита вместо повторного использования устаревшей кэшированной копии. См. Версии и обновления для того, как версия плагина становится его ключом кэша.

​
Объединить ограничения из нескольких плагинов

Когда несколько установленных плагинов ограничивают одну и ту же зависимость, зависимость разрешается в самую высокую версию, которая удовлетворяет всем их диапазонам. Общие комбинации разрешаются так: Автоматическое обновление получает ограниченную зависимость в самую высокую git-метку, которая удовлетворяет диапазону каждого установленного плагина, а не в последнюю версию маркетплейса. Если диапазоны установленных плагинов не перекрываются, автоматическое обновление оставляет эту зависимость в её текущей версии, и вкладка Errors /plugin показывает запись, называющую ограничивающий плагин. Если они перекрываются, но никакая метка не попадает в диапазон, автоматическое обновление получает текущую копию маркетплейса и пропускает обновление, когда version этой копии выходит за пределы диапазона любого установленного плагина. Когда пользователь удаляет последний плагин, который ограничивает зависимость, зависимость больше не ограничивается диапазоном версий и возобновляет отслеживание записи маркетплейса при следующем обновлении.

​
См. также

  • claude plugin prune: удалить автоматически установленные зависимости, которые больше не нужны никакому плагину
  • Размещение маркетплейса: каналы выпуска и рекомендация других плагинов