Ограничение версий зависимостей плагина

Объявляйте ограничения версий для зависимостей плагина и объедините подобранный набор плагинов в одну установку.

Плагин может зависеть от других плагинов, указав их в plugin.json или в записи на marketplace. По умолчанию зависимость отслеживает последнюю доступную версию, поэтому вышестоящий выпуск может изменить зависимость в вашем плагине без предупреждения. Ограничения версий позволяют удерживать зависимость на протестированном диапазоне версий до тех пор, пока вы не решите перейти на новую версию.

Когда вы устанавливаете плагин, который объявляет зависимости, Claude Code автоматически разрешает и устанавливает их, за исключением зависимости, запись на marketplace которой имеет command источник или headersHelper, которую вы устанавливаете сами в первую очередь. Позже /reload-plugins, автоматическое обновление marketplace зависимого плагина, повторный запуск claude plugin install для зависимого плагина и claude plugin marketplace add каждый устанавливают любую объявленную зависимость, которая ещё не установлена, по тем же правилам; если одна остаётся неразрешённой, см. Разрешение ошибок зависимостей.

Это руководство предназначено для авторов плагинов, которые объявляют зависимости в plugin.json, и для администраторов marketplace, которые помечают выпуски. Зависимости здесь — это другие плагины; для пакетов npm и Bun, которые использует сам плагин, см. Зависимости пакетов Node.js. Чтобы установить плагины с зависимостями, см. Обнаружение и установка плагинов. Полную схему манифеста см. в справочнике плагинов.

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

Рассмотрим внутренний 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 вашего плагина.

Следующий манифест объявляет одну зависимость без версии и одну зависимость с ограничением:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Запись может быть простой строкой с только именем плагина, как "audit-logger" в манифесте deploy-kit, которая зависит от любой версии, которую предоставляет marketplace этого плагина. Для большего контроля используйте объект с этими полями:

Версии предварительного выпуска, такие как 2.0.0-beta.1, исключаются, если ваш диапазон не выбирает их с суффиксом предварительного выпуска, например ^2.0.0-0.

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

Помимо обязательного поля name, манифест плагина может состоять только из массива dependencies. Его установка подтягивает все зависимости, что позволяет упаковать тщательно отобранный набор плагинов в один установочный пакет.

Например, команда платформы может опубликовать специализированные наборы во внутреннем маркетплейсе, чтобы инженеры запустили одну команду claude plugin install вместо установки каждого инструмента отдельно:

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

Установка backend-standard разрешает и устанавливает все четыре зависимости.

Чтобы позже добавить инструмент в стандартный набор, опубликуйте новую версию backend-standard с дополнительной зависимостью. Если маркетплейс не автоматически обновляется, инженеры получают новую версию одним из двух способов:

• Включите автоматическое обновление для маркетплейса в /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:

{
  "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, указывающей на поле для установки. Пользователи все еще могут установить зависимость вручную в первую очередь, что удовлетворяет ограничению без изменения списка разрешений.

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

Если вы разрабатываете плагин и одновременно разрабатываете плагин, от которого он зависит, загрузите оба с помощью --plugin-dir:

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

Локальная копия зависимости удовлетворяет записи о зависимости вашего плагина, даже когда запись указывает на marketplace, поэтому вам не нужно устанавливать зависимость из её marketplace. Claude Code не проверяет ограничение версии для локальной копии, поэтому локальный plugin.json не требует version. До версии v2.1.242 запись о зависимости, которая указывала на marketplace, никогда не совпадала с локальной копией, и Claude Code отключал ваш плагин при загрузке.

Когда оба плагина находятся в одной родительской папке, вы можете передать эту папку в --plugin-dir один раз. Если папка сама по себе не является плагином, Claude Code загружает каждую дочернюю папку, которая содержит .claude-plugin/plugin.json. Требуется Claude Code версии v2.1.265 или позже.

Если вы не установили зависимость из её marketplace, ваш плагин перестанет загружаться, когда локальная копия исчезнет:

• Вы отключили локальную копию: Claude Code отключает ваш плагин при следующей загрузке плагина. Для записи о зависимости, которая указывает на marketplace, Claude Code выводит сообщение Dependency "<name>@inline" is disabled — enable it or remove the dependency; для записи с простым именем выводит зависимость по её простому имени. <name>@inline — это способ, которым Claude Code идентифицирует каждый плагин --plugin-dir и --plugin-url.
• Вы начали сеанс без флага --plugin-dir зависимости: Claude Code выводит сообщение, что зависимость не установлена. Передайте флаг снова или установите зависимость из её marketplace.

Выпуски тегов плагинов для разрешения версий

Claude Code разрешает ограничения версий для git-тегов в репозитории, который размещает зависимость: собственный репозиторий плагина для источников плагинов github, url и git-subdir, или репозиторий маркетплейса для плагина, на который маркетплейс ссылается относительным путём. Чтобы Claude Code мог найти доступные версии зависимости, выпуски вышестоящего плагина должны быть помечены тегами с использованием определённого соглашения об именовании.

Пометьте каждый выпуск как {plugin-name}--v{version}, где {version} соответствует полю version в plugin.json этого коммита. Из директории плагина выполните:

claude plugin tag --push

Команда claude plugin tag выводит имя тега из манифеста плагина и записи маркетплейса, которая его содержит. Перед созданием тега она проверяет содержимое плагина, убеждается, что plugin.json и запись маркетплейса согласны по версии, требует чистого рабочего дерева в директории плагина и отказывает, если тег уже существует.

• --push отправляет тег на удалённый репозиторий origin, поэтому репозиторий должен иметь настроенный удалённый репозиторий origin. Передайте --remote для отправки на другой.
• Если отправка не удаётся, тег всё равно создаётся локально и команда завершается с ошибкой.
• С --push успешный запуск заканчивается с Created tag secrets-vault--v2.1.0 и Pushed to origin, где последняя строка называет удалённый репозиторий, на который была произведена отправка. Без --push команда выводит команду git push для запуска вместо этого.
• --dry-run выводит то, что будет помечено тегом, без его создания.

Запуск git tag secrets-vault--v2.1.0 напрямую эквивалентен, если вы сами синхронизируете plugin.json и запись маркетплейса.

Префикс имени плагина позволяет одному репозиторию маркетплейса размещать несколько плагинов с независимыми линиями версий. Разделитель --v анализируется как совпадение префикса на полное имя плагина, поэтому имена плагинов, содержащие дефисы, обрабатываются правильно.

Когда вы устанавливаете плагин, который объявляет { "name": "secrets-vault", "version": "~2.1.0" }, Claude Code выводит список тегов в репозитории, который размещает secrets-vault, фильтрует те, которые начинаются с secrets-vault--v, и получает наивысшую версию, удовлетворяющую ~2.1.0. Если ни один тег в собственном репозитории плагина не удовлетворяет диапазону, установка завершается с ошибкой Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0, которая называет зависимость вместе с её маркетплейсом. Для плагина с относительным путём без соответствующего тега Claude Code устанавливает текущую копию маркетплейса и проверяет ограничение при загрузке плагина.

Для плагина, на который маркетплейс ссылается относительным путём, маркетплейс, добавленный как локальный путь папки, разрешает теги таким же образом, когда папка является git-репозиторием. Это требует Claude Code v2.1.196 или позже. В двух случаях Claude Code устанавливает зависимость из текущего содержимого папки вместо этого:

• Более ранние версии не читают теги из маркетплейса локальной папки, поэтому ограниченная зависимость загружается только если эта копия удовлетворяет диапазону.
• Локальная папка, которая не является git-репозиторием, не имеет тегов, независимо от версии.

Semver разрешённого тега записывается отдельно от version в plugin.json, поэтому проверки ограничений используют тег, который был фактически получен, даже если plugin.json в этом коммите имеет устаревшее значение. Имя директории кэша для установки с разрешённым тегом включает суффикс SHA коммита из 12 символов, поэтому если разработчик принудительно переместит тег на другой коммит, следующая установка получит свежую директорию кэша вместо повторного использования устаревшего содержимого.

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

Когда несколько установленных плагинов ограничивают одну и ту же зависимость, Claude Code пересекает их диапазоны и разрешает зависимость на самую высокую версию, которая удовлетворяет всем из них. Таблица ниже показывает, как разрешаются общие комбинации.

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

Когда вы удаляете последний плагин, который ограничивает зависимость, зависимость больше не удерживается и возобновляет отслеживание записи marketplace при следующем обновлении.

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

Этот раздел охватывает плагины, установленные из маркетплейса. Для копии, которую вы загрузили с помощью --plugin-dir, см. Локальное тестирование плагина и его зависимости.

Включение плагина также включает плагины, от которых он зависит, и отключение плагина блокируется, если другой включенный плагин все еще нуждается в нем.

Когда вы включаете плагин, Claude Code также включает его зависимости в той же области. Если зависимость имеет свои собственные зависимости, Claude Code включает и их. Сообщение об успехе выводит список того, что еще было включено вместе с плагином, который вы назвали. Если зависимость не может быть включена, команда отказывает и сообщает вам, что блокирует и как это исправить:

Это справедливо даже когда зависимость устанавливает 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 plugin prune

Если ничего не подлежит удалению, команда выводит Nothing to prune с указанием причины и завершает работу. Это ожидаемый результат при свежей установке, а не ошибка.

По умолчанию prune работает в области пользователя и запрашивает подтверждение перед удалением чего-либо:

• --scope project или --scope local выбирает другую область.
• --dry-run выводит список того, что будет удалено, без внесения изменений.
• -y пропускает подтверждение. Когда stdin или stdout не является терминалом, prune выводит список осиротевших зависимостей и завершает работу без их удаления, если не передана -y.

Чтобы выполнить prune как часть удаления, передайте --prune в claude plugin uninstall. После удаления названного плагина Claude Code сканирует и удаляет любые автоматически установленные зависимости, которые теперь осиротели. Плагины, которые вы установили сами, никогда не удаляются, только те, которые были установлены автоматически через массив dependencies другого плагина.

Поведение подтверждения остаётся прежним. Когда stdin или stdout не является терминалом, удаление всё ещё завершается, но шаг prune выводит список осиротевших зависимостей и ничего не удаляет, если не передана -y.

Например, чтобы удалить deploy-kit и очистить зависимости, которые он оставляет:

claude plugin uninstall deploy-kit --prune

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

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

Чтобы проверить эти ошибки программно, запустите claude plugin list --json. Плагины с проблемами включают поле errors, в котором они перечислены. Плагины, которые загрузились без ошибок, опускают это поле.

См. также

• Создание плагинов: создавайте плагины с skills, agents и hooks
• Создание и распространение marketplace плагинов: размещайте плагины для вашей команды
• Справочник плагинов: полная схема plugin.json
• Управление версиями: как разрешается версия самого плагина и используется в качестве ключа кэша