Перейти к основному содержанию
Плагин может зависеть от других плагинов, указав их в plugin.json или в записи на marketplace. По умолчанию зависимость отслеживает последнюю доступную версию, поэтому вышестоящий выпуск может изменить зависимость в вашем плагине без предупреждения. Ограничения версий позволяют удерживать зависимость на протестированном диапазоне версий до тех пор, пока вы не решите перейти на новую версию. Когда вы устанавливаете плагин, который объявляет зависимости, Claude Code автоматически разрешает и устанавливает их, а также выводит список добавленных зависимостей в конце вывода установки. Это руководство предназначено для авторов плагинов, которые объявляют зависимости в 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 этого коммита. 
git tag secrets-vault--v2.1.0
git push origin secrets-vault--v2.1.0
Префикс имени плагина позволяет одному репозиторию marketplace размещать несколько плагинов с независимыми линиями версий. Разделитель --v анализируется как совпадение префикса на полное имя плагина, поэтому имена плагинов, содержащие дефисы, обрабатываются правильно. Когда вы устанавливаете плагин, который объявляет { "name": "secrets-vault", "version": "~2.1.0" }, Claude Code выводит список тегов marketplace, фильтрует те, которые начинаются с secrets-vault--v, и получает самую высокую версию, удовлетворяющую ~2.1.0. Если соответствующий тег не существует, зависимый плагин отключается с ошибкой, в которой перечислены доступные версии.
Для источников 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.
Автоматическое обновление проверяет каждую ограниченную зависимость относительно диапазона каждого установленного плагина перед применением обновления. Если marketplace перемещает зависимость на версию вне любого диапазона, обновление пропускается и сообщение о пропуске указывает на ограничивающий плагин. Когда вы удаляете последний плагин, который ограничивает зависимость, зависимость больше не удерживается и возобновляет отслеживание записи marketplace при следующем обновлении.

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

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

​
См. также