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

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

Рассмотрим внутренний 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
{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
Запись может быть простой строкой с только именем плагина, как "audit-logger" в примере выше, которая зависит от любой версии, которую предоставляет marketplace этого плагина. Для большего контроля используйте объект с этими полями:
ПолеТипОписание
namestringИмя плагина. Разрешается в том же marketplace, что и объявляющий плагин. Обязательно.
versionstringДиапазон semver, такой как ~2.1.0, ^2.0, >=1.4 или =2.1.0. Зависимость получается в самой высокой помеченной версии, которая удовлетворяет этому диапазону.
marketplacestringДругой marketplace для разрешения name. Кросс-marketplace зависимости блокируются, если целевой marketplace не указан в allowCrossMarketplaceDependenciesOn в marketplace.json корневого marketplace.
Поле version принимает любое выражение, поддерживаемое пакетом semver Node, включая диапазоны с каретой, тильдой, дефисом и компаратором. Версии предварительного выпуска, такие как 2.0.0-beta.1, исключаются, если ваш диапазон не выбирает их с суффиксом предварительного выпуска, например ^2.0.0-0.

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

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

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

Ограничения версий разрешаются относительно git-тегов в репозитории marketplace. Чтобы Claude Code мог найти доступные версии зависимости, выпуски вышестоящего плагина должны быть помечены с использованием определенного соглашения об именовании. Помечайте каждый выпуск как {plugin-name}--v{version}, где {version} соответствует полю version в plugin.json этого коммита. Из директории плагина выполните: 
claude plugin tag --push
Команда 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. Если соответствующий тег не существует, зависимый плагин отключается с ошибкой, в которой перечислены доступные версии. Разрешенный тег semver записывается отдельно от version в plugin.json, поэтому проверки ограничений используют тег, который был фактически получен, даже если plugin.json в этом коммите имеет устаревшее значение. Имя директории кэша для установки с разрешением тега включает суффикс commit-SHA из 12 символов, поэтому если разработчик принудительно переместит тег на другой коммит, следующая установка получит свежую директорию кэша вместо повторного использования устаревшего содержимого.
Для источников marketplace npm ограничение не контролирует, какая версия получается, так как разрешение на основе тегов применяется только к источникам, поддерживаемым git. Ограничение все еще проверяется во время загрузки, и зависимый плагин отключается с dependency-version-unsatisfied, если установленная версия не удовлетворяет ему.

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

Когда несколько установленных плагинов ограничивают одну и ту же зависимость, Claude Code пересекает их диапазоны и разрешает зависимость на самую высокую версию, которая удовлетворяет всем из них. Таблица ниже показывает, как разрешаются общие комбинации.
Плагин A требуетПлагин B требуетРезультат
^2.0>=2.1Одна установка на самый высокий тег 2.x на уровне или выше 2.1.0. Оба плагина загружаются.
~2.1~3.0Установка плагина B завершается с ошибкой range-conflict. Плагин A и зависимость остаются как они были.
=2.1.0noneЗависимость остается на 2.1.0. Автоматическое обновление пропускает более новые версии, пока установлен плагин A.
Автоматическое обновление получает ограниченную зависимость на самом высоком теге git, который удовлетворяет диапазону каждого установленного плагина, а не на последней версии marketplace, поэтому зависимость продолжает получать обновления в пределах своего допустимого диапазона. Если ни один тег не удовлетворяет всем диапазонам, обновление пропускается и пропуск отображается в /doctor и на вкладке Errors в /plugin, указывая на ограничивающий плагин. Когда вы удаляете последний плагин, который ограничивает зависимость, зависимость больше не удерживается и возобновляет отслеживание записи marketplace при следующем обновлении.

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

Включение плагина также включает плагины, от которых он зависит, и отключение плагина блокируется, если другой включенный плагин все еще нуждается в нем. Оба поведения требуют Claude Code v2.1.143 или более поздней версии. Более ранние версии включают или отключают только названный плагин и выводят ошибку dependency-unsatisfied при следующей загрузке. Когда вы включаете плагин, Claude Code также включает его зависимости в той же области. Если зависимость имеет свои собственные зависимости, Claude Code включает и их. Сообщение об успехе выводит список того, что еще было включено вместе с плагином, который вы назвали. Если зависимость не может быть включена, команда отказывает и сообщает вам, что блокирует и как это исправить:
УсловиеРезультат
Зависимость не установленаВключение завершается с ошибкой и выводит команду claude plugin install для каждой отсутствующей зависимости.
Зависимость заблокирована политикой плагинов вашей организацииВключение завершается с ошибкой и указывает на заблокированную зависимость.
Зависимость установлена на false в области с более высоким приоритетом, чем целевая областьВключение завершается с ошибкой. Включите зависимость в этой области или передайте --scope для записи там.
Все зависимости установлены и разрешеныВключение успешно и записывает true для плагина и каждой зависимости, которая еще не была включена в целевой области.
Это справедливо даже когда зависимость устанавливает defaultEnabled: false в своем манифесте, потому что Claude Code записывает явное true для нее. То же самое применяется при установке: зависимость, подключенная для удовлетворения активного плагина, устанавливается с true независимо от своего собственного значения по умолчанию. Когда вы отключаете плагин, Claude Code отказывает, если другой включенный плагин все еще зависит от него. Ошибка указывает на плагины, которые зависят от него, и дает вам цепную команду, которая отключает их в правильном порядке, заканчивая тем, который вы запросили. Например, если deploy-kit зависит от secrets-vault, отключение только secrets-vault завершается с ошибкой с выводом, похожим на следующий: 
secrets-vault is still required by deploy-kit. Disable that plugin first, or
disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools
Скопируйте цепную команду из ошибки, чтобы отключить полный набор за один шаг.

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

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

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

Проблемы с зависимостями появляются в claude plugin list, в интерфейсе /plugin и в /doctor. Затронутый плагин отключается до тех пор, пока вы не разрешите ошибку. Наиболее распространенные ошибки и их исправления перечислены ниже.
ОшибкаЗначениеКак разрешить
dependency-unsatisfiedОбъявленная зависимость не установлена, или она установлена, но отключена.Запустите команду claude plugin install, показанную в сообщении об ошибке. Если marketplace зависимости еще не настроен, добавьте его с помощью claude plugin marketplace add, и Claude Code разрешит зависимость автоматически. Если зависимость отключена, включите её.
range-conflictТребования к версии для зависимости не могут быть объединены. Сообщение об ошибке указывает причину: ни одна версия не удовлетворяет всем диапазонам, диапазон не является действительным синтаксисом semver, или объединенные диапазоны слишком сложны для пересечения.Удалите или обновите один из конфликтующих плагинов, исправьте любую неправильную строку version, упростите длинные цепочки || или попросите вышестоящего автора расширить его ограничение.
dependency-version-unsatisfiedВерсия установленной зависимости находится вне объявленного диапазона этого плагина.Запустите claude plugin install <dependency>@<marketplace> для повторного разрешения зависимости относительно всех текущих ограничений.
no-matching-tagРепозиторий зависимости не имеет тега {name}--v*, удовлетворяющего диапазону.Проверьте, что вышестоящий помечен выпусками, используя соглашение выше, или ослабьте ваш диапазон.
Чтобы проверить эти ошибки программно, запустите claude plugin list --json и прочитайте поле errors для каждого плагина.

​
См. также