Перейти к основному содержанию
Плагин может зависеть от других плагинов, указав их в plugin.json или в записи на marketplace. По умолчанию зависимость отслеживает последнюю доступную версию, поэтому вышестоящий выпуск может изменить зависимость в вашем плагине без предупреждения. Ограничения версий позволяют удерживать зависимость на протестированном диапазоне версий до тех пор, пока вы не решите перейти на новую версию. Когда вы устанавливаете плагин, который объявляет зависимости, Claude Code автоматически разрешает и устанавливает их, а также выводит список добавленных зависимостей в конце вывода установки. Если зависимость позже исчезнет, /reload-plugins и фоновое автоматическое обновление плагина переустановят её при условии, что её marketplace уже находится в ваших настроенных marketplaces. Повторный запуск claude plugin install для зависимого плагина или добавление marketplace с помощью claude plugin marketplace add также разрешит любые оставшиеся отсутствующие зависимости. Зависимости из marketplace, который вы не добавили, остаются неразрешёнными. Это руководство предназначено для авторов плагинов, которые объявляют зависимости в plugin.json, и для администраторов marketplace, которые помечают выпуски. Чтобы установить плагины с зависимостями, см. Обнаружение и установка плагинов. Полную схему манифеста см. в справочнике плагинов.

​
Почему нужно ограничивать версии зависимостей

Рассмотрим внутренний marketplace, где две команды публикуют плагины. Команда платформы поддерживает secrets-vault, MCP-сервер, который оборачивает бэкенд секретов. Команда развертывания поддерживает deploy-kit, который вызывает secrets-vault для получения учетных данных во время развертывания. deploy-kit протестирован для работы с secrets-vault v2.1.0. Без ограничения версии при следующем выпуске платформенной команды, который переименовывает MCP-инструмент, автоматическое обновление переместит secrets-vault каждого инженера на новую версию, и deploy-kit сломается. С ограничением версии deploy-kit объявляет, что ему нужен secrets-vault в диапазоне ~2.1.0. Инженеры с установленным deploy-kit остаются на самой высокой соответствующей версии 2.1.x. Команда развертывания обновляется по собственному графику, публикуя новую версию deploy-kit с более широким ограничением.

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

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

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

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

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

По умолчанию Claude Code отказывается автоматически устанавливать зависимость, которая находится в другом marketplace, чем плагин, который ее объявляет. Это предотвращает молчаливое извлечение плагинов из источника, который вы не проверили. Чтобы это разрешить, администратор корневого marketplace добавляет имя целевого marketplace в allowCrossMarketplaceDependenciesOn в marketplace.json. Корневой marketplace — это тот, который размещает плагин, который устанавливает пользователь; проверяется только его список разрешений, поэтому доверие не распространяется через промежуточные marketplace. Следующий marketplace.json позволяет deploy-kit зависеть от плагина из acme-shared:
.claude-plugin/marketplace.json
Если поле отсутствует или не включает целевой marketplace, установка завершается с ошибкой cross-marketplace, указывающей на поле для установки. Пользователи все еще могут установить зависимость вручную в первую очередь, что удовлетворяет ограничению без изменения списка разрешений.

​
Помечание выпусков плагинов для разрешения версий

Ограничения версий разрешаются относительно git-тегов в репозитории marketplace. Чтобы Claude Code мог найти доступные версии зависимости, выпуски вышестоящего плагина должны быть помечены с использованием определенного соглашения об именовании. Помечайте каждый выпуск как {plugin-name}--v{version}, где {version} соответствует полю version в plugin.json этого коммита. Из директории плагина выполните:
Команда claude plugin tag выводит имя тега из манифеста плагина и записи marketplace, которая его содержит. Перед созданием тега она проверяет содержимое плагина, убеждается, что plugin.json и запись marketplace согласны по версии, требует чистого рабочего дерева в директории плагина и отказывает, если тег уже существует. Добавьте --dry-run, чтобы увидеть, что будет помечено, без его создания. Прямое выполнение git tag secrets-vault--v2.1.0 эквивалентно, если вы сами поддерживаете синхронизацию plugin.json и записи marketplace. Префикс имени плагина позволяет одному репозиторию marketplace размещать несколько плагинов с независимыми линиями версий. Разделитель --v анализируется как совпадение префикса на полное имя плагина, поэтому имена плагинов, содержащие дефисы, обрабатываются правильно. Когда вы устанавливаете плагин, который объявляет { "name": "secrets-vault", "version": "~2.1.0" }, Claude Code выводит список тегов marketplace, фильтрует те, которые начинаются с secrets-vault--v, и получает самую высокую версию, удовлетворяющую ~2.1.0. Если соответствующий тег не существует, зависимый плагин отключается с ошибкой, в которой перечислены доступные версии. Marketplace, добавленный как путь локальной папки, разрешает теги таким же образом, когда папка является git-репозиторием. Это требует Claude Code v2.1.196 или более поздней версии. В двух случаях Claude Code устанавливает зависимость из текущего содержимого папки:
  • Более ранние версии не читают теги из marketplace локальной папки, поэтому зависимость с ограничением загружается только если эта копия удовлетворяет диапазону.
  • Локальная папка, которая не является git-репозиторием, не имеет тегов, независимо от версии.
Разрешенный тег semver записывается отдельно от version в plugin.json, поэтому проверки ограничений используют тег, который был фактически получен, даже если plugin.json в этом коммите имеет устаревшее значение. Имя директории кэша для установки с разрешением тега включает суффикс commit-SHA из 12 символов, поэтому если разработчик принудительно переместит тег на другой коммит, следующая установка получит свежую директорию кэша вместо повторного использования устаревшего содержимого.
Для источников marketplace npm ограничение не контролирует, какая версия получается, так как разрешение на основе тегов применяется только к источникам, поддерживаемым git. Ограничение все еще проверяется во время загрузки, и зависимый плагин отключается с dependency-version-unsatisfied, если установленная версия не удовлетворяет ему.

​
Как ограничения взаимодействуют

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

​
Включение или отключение плагина с зависимостями

Включение плагина также включает плагины, от которых он зависит, и отключение плагина блокируется, если другой включенный плагин все еще нуждается в нем. Оба поведения требуют Claude Code v2.1.143 или более поздней версии. Более ранние версии включают или отключают только названный плагин и выводят ошибку dependency-unsatisfied при следующей загрузке. Когда вы включаете плагин, Claude Code также включает его зависимости в той же области. Если зависимость имеет свои собственные зависимости, Claude Code включает и их. Сообщение об успехе выводит список того, что еще было включено вместе с плагином, который вы назвали. Если зависимость не может быть включена, команда отказывает и сообщает вам, что блокирует и как это исправить: Это справедливо даже когда зависимость устанавливает defaultEnabled: false в своем манифесте, потому что Claude Code записывает явное true для нее. То же самое применяется при установке: зависимость, подключенная для удовлетворения активного плагина, устанавливается с true независимо от своего собственного значения по умолчанию. Когда вы отключаете плагин, Claude Code отказывает, если другой включенный плагин все еще зависит от него. Ошибка указывает на плагины, которые зависят от него, и дает вам цепную команду, которая отключает их в правильном порядке, заканчивая тем, который вы запросили. Например, если deploy-kit зависит от secrets-vault, отключение только secrets-vault завершается с ошибкой с выводом, похожим на следующий:
Скопируйте цепную команду из ошибки, чтобы отключить полный набор за один шаг.

​
Удаление осиротевших автоматически установленных зависимостей

Автоматически установленные зависимости остаются на диске после удаления плагинов, которые их установили, на случай, если вы переустановите зависимый плагин или захотите продолжить использование зависимости напрямую. Чтобы очистить их, запустите claude plugin prune для вывода списка автоматически установленных зависимостей, которые больше не требуются ни одним установленным плагином, и удалите их после подтверждения. Это требует Claude Code v2.1.121 или более поздней версии.
По умолчанию prune работает в области пользователя. Используйте --scope project или --scope local для выбора другой области. Передайте --dry-run для вывода списка того, что будет удалено, без внесения изменений. Передайте -y для пропуска подтверждения. Когда stdin или stdout не является терминалом, prune выводит список осиротевших зависимостей и выходит без их удаления, если не передана -y. Чтобы выполнить prune как часть удаления, передайте --prune в claude plugin uninstall. После удаления названного плагина Claude Code сканирует и удаляет любые автоматически установленные зависимости, которые теперь осиротели. Плагины, которые вы установили сами, никогда не удаляются, только те, которые были установлены автоматически через массив dependencies другого плагина. Например, чтобы удалить deploy-kit и очистить зависимости, которые он оставляет:

​
Разрешение ошибок зависимостей

Проблемы с зависимостями появляются в claude plugin list и в интерфейсе /plugin. Claude Code отключает затронутый плагин до тех пор, пока вы не разрешите ошибку. Таблица ниже содержит список наиболее распространенных ошибок и способы их разрешения. Чтобы проверить эти ошибки программно, запустите claude plugin list --json и прочитайте поле errors для каждого плагина.

​
См. также