plugin-dependencies.md +0 −267 deleted
File Deleted View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Ограничение версий зависимостей плагина
6
7> Объявляйте ограничения версий для зависимостей плагина и объедините подобранный набор плагинов в одну установку.
8
9Плагин может зависеть от других плагинов, указав их в `plugin.json` или в записи на marketplace. По умолчанию зависимость отслеживает последнюю доступную версию, поэтому вышестоящий выпуск может изменить зависимость в вашем плагине без предупреждения. Ограничения версий позволяют удерживать зависимость на протестированном диапазоне версий до тех пор, пока вы не решите перейти на новую версию.
10
11Когда вы устанавливаете плагин, который объявляет зависимости, Claude Code автоматически разрешает и устанавливает их, за исключением зависимости, запись на marketplace которой имеет [`command` источник](/docs/ru/plugin-marketplaces#how-users-accept-the-command) или [`headersHelper`](/docs/ru/plugin-marketplaces#how-users-accept-a-headershelper-command), которую вы устанавливаете сами в первую очередь. Позже `/reload-plugins`, автоматическое обновление marketplace зависимого плагина, повторный запуск `claude plugin install` для зависимого плагина и `claude plugin marketplace add` каждый устанавливают любую объявленную зависимость, которая ещё не установлена, по тем же правилам; если одна остаётся неразрешённой, см. [Разрешение ошибок зависимостей](#resolve-dependency-errors).
12
13Это руководство предназначено для авторов плагинов, которые объявляют зависимости в `plugin.json`, и для администраторов marketplace, которые помечают выпуски. Зависимости здесь — это другие плагины; для пакетов npm и Bun, которые использует сам плагин, см. [Зависимости пакетов Node.js](/docs/ru/plugins-reference#node-js-package-dependencies). Чтобы установить плагины с зависимостями, см. [Обнаружение и установка плагинов](/docs/ru/discover-plugins). Полную схему манифеста см. в [справочнике плагинов](/docs/ru/plugins-reference).
14
15<h2 id="why-constrain-dependency-versions">
16 Почему нужно ограничивать версии зависимостей
17</h2>
18
19Рассмотрим внутренний marketplace, где две команды публикуют плагины. Команда платформы поддерживает `secrets-vault`, MCP-сервер, который оборачивает бэкенд секретов. Команда развертывания поддерживает `deploy-kit`, который вызывает `secrets-vault` для получения учетных данных во время развертывания.
20
21`deploy-kit` протестирован для работы с `secrets-vault` v2.1.0. Без ограничения версии при следующем выпуске платформенной команды, который переименовывает MCP-инструмент, автоматическое обновление переместит `secrets-vault` каждого инженера на новую версию, и `deploy-kit` сломается.
22
23С ограничением версии `deploy-kit` объявляет, что ему нужен `secrets-vault` в диапазоне `~2.1.0`. Инженеры с установленным `deploy-kit` остаются на самой высокой соответствующей версии `2.1.x`. Команда развертывания обновляется по собственному графику, публикуя новую версию `deploy-kit` с более широким ограничением.
24
25<h2 id="declare-a-dependency-with-a-version-constraint">
26 Объявление зависимости с ограничением версии
27</h2>
28
29Перечислите зависимости в массиве `dependencies` файла `.claude-plugin/plugin.json` вашего плагина.
30
31Следующий манифест объявляет одну зависимость без версии и одну зависимость с ограничением:
32
33```json .claude-plugin/plugin.json theme={null}
34{
35 "name": "deploy-kit",
36 "version": "3.1.0",
37 "dependencies": [
38 "audit-logger",
39 { "name": "secrets-vault", "version": "~2.1.0" }
40 ]
41}
42```
43
44Запись может быть простой строкой с только именем плагина, как `"audit-logger"` в манифесте `deploy-kit`, которая зависит от любой версии, которую предоставляет marketplace этого плагина. Для большего контроля используйте объект с этими полями:
45
46| Поле | Тип | Описание |
47| :------------ | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
48| `name` | string | Имя плагина. Разрешается в том же marketplace, что и объявляющий плагин. Обязательно. |
49| `version` | string | [Диапазон semver](https://github.com/npm/node-semver#ranges), такой как `~2.1.0`, `^2.0`, `>=1.4` или `=2.1.0`. Зависимость получается в самой высокой помеченной версии, которая удовлетворяет этому диапазону. |
50| `marketplace` | string | Другой marketplace для разрешения `name`. Кросс-marketplace зависимости блокируются, если целевой marketplace не указан в [`allowCrossMarketplaceDependenciesOn`](#depend-on-a-plugin-from-another-marketplace) в `marketplace.json` корневого marketplace. |
51
52Версии предварительного выпуска, такие как `2.0.0-beta.1`, исключаются, если ваш диапазон не выбирает их с суффиксом предварительного выпуска, например `^2.0.0-0`.
53
54<h2 id="bundle-plugins-for-a-team">
55 Объединение плагинов для команды
56</h2>
57
58Помимо обязательного поля `name`, манифест плагина может состоять только из массива `dependencies`. Его установка подтягивает все зависимости, что позволяет упаковать тщательно отобранный набор плагинов в один установочный пакет.
59
60Например, команда платформы может опубликовать специализированные наборы во внутреннем маркетплейсе, чтобы инженеры запустили одну команду `claude plugin install` вместо установки каждого инструмента отдельно:
61
62```json .claude-plugin/plugin.json theme={null}
63{
64 "name": "backend-standard",
65 "version": "1.0.0",
66 "description": "Standard plugin set for backend engineers",
67 "dependencies": [
68 "secrets-vault",
69 "deploy-kit",
70 { "name": "db-migrate", "version": "^3.0" },
71 "oncall-runbook"
72 ]
73}
74```
75
76Установка `backend-standard` разрешает и устанавливает все четыре зависимости.
77
78Чтобы позже добавить инструмент в стандартный набор, опубликуйте новую версию `backend-standard` с дополнительной зависимостью. Если маркетплейс не [автоматически обновляется](/docs/ru/discover-plugins#configure-auto-updates), инженеры получают новую версию одним из двух способов:
79
80* Включите автоматическое обновление для маркетплейса в `/plugin`. Следующее автоматическое обновление переместит пакет на новую версию и установит все добавленные им зависимости.
81* Запустите `claude plugin update backend-standard`, затем `/reload-plugins` для установки вновь добавленных зависимостей.
82
83Чтобы развернуть пакеты по всей организации, добавьте плагин пакета в `enabledPlugins` в [управляемых параметрах](/docs/ru/settings-reference#enabledplugins).
84
85<h2 id="depend-on-a-plugin-from-another-marketplace">
86 Зависимость от плагина из другого marketplace
87</h2>
88
89По умолчанию Claude Code отказывается автоматически устанавливать зависимость, которая находится в другом marketplace, чем плагин, который ее объявляет. Это предотвращает молчаливое извлечение плагинов из источника, который вы не проверили.
90
91Чтобы это разрешить, администратор корневого marketplace добавляет имя целевого marketplace в `allowCrossMarketplaceDependenciesOn` в `marketplace.json`. Корневой marketplace — это тот, который размещает плагин, который устанавливает пользователь; проверяется только его список разрешений, поэтому доверие не распространяется через промежуточные marketplace.
92
93Следующий `marketplace.json` позволяет `deploy-kit` зависеть от плагина из `acme-shared`:
94
95```json .claude-plugin/marketplace.json theme={null}
96{
97 "name": "acme-tools",
98 "owner": { "name": "Acme" },
99 "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
100 "plugins": [
101 {
102 "name": "deploy-kit",
103 "source": "./deploy-kit",
104 "dependencies": [
105 { "name": "audit-logger", "marketplace": "acme-shared" }
106 ]
107 }
108 ]
109}
110```
111
112Если поле отсутствует или не включает целевой marketplace, установка завершается с ошибкой `cross-marketplace`, указывающей на поле для установки. Пользователи все еще могут установить зависимость вручную в первую очередь, что удовлетворяет ограничению без изменения списка разрешений.
113
114<h2 id="test-a-plugin-and-its-dependency-locally">
115 Тестирование плагина и его зависимости локально
116</h2>
117
118Если вы разрабатываете плагин и одновременно разрабатываете плагин, от которого он зависит, загрузите оба с помощью `--plugin-dir`:
119
120```bash theme={null}
121claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin
122```
123
124Локальная копия зависимости удовлетворяет записи о зависимости вашего плагина, даже когда запись указывает на marketplace, поэтому вам не нужно устанавливать зависимость из её marketplace. Claude Code не проверяет [ограничение версии](#declare-a-dependency-with-a-version-constraint) для локальной копии, поэтому локальный `plugin.json` не требует `version`. До версии v2.1.242 запись о зависимости, которая указывала на marketplace, никогда не совпадала с локальной копией, и Claude Code отключал ваш плагин при загрузке.
125
126Когда оба плагина находятся в одной родительской папке, вы можете передать эту папку в `--plugin-dir` один раз. Если папка сама по себе не является плагином, Claude Code загружает каждую дочернюю папку, которая содержит `.claude-plugin/plugin.json`. Требуется Claude Code версии v2.1.265 или позже.
127
128Если вы не установили зависимость из её marketplace, ваш плагин перестанет загружаться, когда локальная копия исчезнет:
129
130* **Вы отключили локальную копию**: Claude Code отключает ваш плагин при следующей загрузке плагина. Для записи о зависимости, которая указывает на marketplace, Claude Code выводит сообщение `Dependency "<name>@inline" is disabled — enable it or remove the dependency`; для записи с простым именем выводит зависимость по её простому имени. `<name>@inline` — это способ, которым Claude Code идентифицирует каждый плагин `--plugin-dir` и `--plugin-url`.
131* **Вы начали сеанс без флага `--plugin-dir` зависимости**: Claude Code выводит сообщение, что зависимость не установлена. Передайте флаг снова или установите зависимость из её marketplace.
132
133<h2 id="tag-plugin-releases-for-version-resolution">
134 Выпуски тегов плагинов для разрешения версий
135</h2>
136
137Claude Code разрешает ограничения версий для git-тегов в репозитории, который размещает зависимость: собственный репозиторий плагина для [источников плагинов](/docs/ru/plugin-marketplaces#plugin-sources) `github`, `url` и `git-subdir`, или репозиторий маркетплейса для плагина, на который маркетплейс ссылается относительным путём. Чтобы Claude Code мог найти доступные версии зависимости, выпуски вышестоящего плагина должны быть помечены тегами с использованием определённого соглашения об именовании.
138
139Пометьте каждый выпуск как `{plugin-name}--v{version}`, где `{version}` соответствует полю `version` в `plugin.json` этого коммита. Из директории плагина выполните:
140
141```bash theme={null}
142claude plugin tag --push
143```
144
145Команда `claude plugin tag` выводит имя тега из манифеста плагина и записи маркетплейса, которая его содержит. Перед созданием тега она проверяет содержимое плагина, убеждается, что `plugin.json` и запись маркетплейса согласны по версии, требует чистого рабочего дерева в директории плагина и отказывает, если тег уже существует.
146
147* `--push` отправляет тег на удалённый репозиторий `origin`, поэтому репозиторий должен иметь настроенный удалённый репозиторий `origin`. Передайте `--remote` для отправки на другой.
148* Если отправка не удаётся, тег всё равно создаётся локально и команда завершается с ошибкой.
149* С `--push` успешный запуск заканчивается с `Created tag secrets-vault--v2.1.0` и `Pushed to origin`, где последняя строка называет удалённый репозиторий, на который была произведена отправка. Без `--push` команда выводит команду `git push` для запуска вместо этого.
150* `--dry-run` выводит то, что будет помечено тегом, без его создания.
151
152Запуск `git tag secrets-vault--v2.1.0` напрямую эквивалентен, если вы сами синхронизируете `plugin.json` и запись маркетплейса.
153
154Префикс имени плагина позволяет одному репозиторию маркетплейса размещать несколько плагинов с независимыми линиями версий. Разделитель `--v` анализируется как совпадение префикса на полное имя плагина, поэтому имена плагинов, содержащие дефисы, обрабатываются правильно.
155
156Когда вы устанавливаете плагин, который объявляет `{ "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 устанавливает текущую копию маркетплейса и проверяет ограничение при загрузке плагина.
157
158Для плагина, на который маркетплейс ссылается относительным путём, маркетплейс, добавленный как локальный путь папки, разрешает теги таким же образом, когда папка является git-репозиторием. Это требует Claude Code v2.1.196 или позже. В двух случаях Claude Code устанавливает зависимость из текущего содержимого папки вместо этого:
159
160* Более ранние версии не читают теги из маркетплейса локальной папки, поэтому ограниченная зависимость загружается только если эта копия удовлетворяет диапазону.
161* Локальная папка, которая не является git-репозиторием, не имеет тегов, независимо от версии.
162
163Semver разрешённого тега записывается отдельно от `version` в `plugin.json`, поэтому проверки ограничений используют тег, который был фактически получен, даже если `plugin.json` в этом коммите имеет устаревшее значение. Имя директории кэша для установки с разрешённым тегом включает суффикс SHA коммита из 12 символов, поэтому если разработчик принудительно переместит тег на другой коммит, следующая установка получит свежую директорию кэша вместо повторного использования устаревшего содержимого.
164
165<Note>
166 Для зависимостей с [источником плагина](/docs/ru/plugin-marketplaces#plugin-sources) `npm`, `archive` или `command`, ограничение не контролирует, какая версия получена, поскольку разрешение на основе тегов применяется только к источникам, поддерживаемым git. Ограничение всё равно проверяется во время загрузки, и зависимый плагин отключается с `dependency-version-unsatisfied`, если установленная версия не удовлетворяет ему. Для источника `command` Claude Code проверяет версию в `plugin.json` зависимости и игнорирует суффикс хэша содержимого; зависимость, чей `plugin.json` не устанавливает версию, не удовлетворяет никакому ограничению, поэтому установите её перед тем, как вы её ограничите.
167
168 Claude Code никогда не устанавливает зависимость с источником `command` сам, поэтому пользователи [устанавливают её первыми](/docs/ru/plugin-marketplaces#how-users-accept-the-command). Claude Code также никогда не запускает `headersHelper` на записи маркетплейса зависимости, поэтому пользователи [устанавливают этот плагин первыми](/docs/ru/plugin-marketplaces#how-users-accept-a-headershelper-command).
169</Note>
170
171<h2 id="how-constraints-interact">
172 Как ограничения взаимодействуют
173</h2>
174
175Когда несколько установленных плагинов ограничивают одну и ту же зависимость, Claude Code пересекает их диапазоны и разрешает зависимость на самую высокую версию, которая удовлетворяет всем из них. Таблица ниже показывает, как разрешаются общие комбинации.
176
177| Плагин A требует | Плагин B требует | Результат |
178| :--------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------ |
179| `^2.0` | `>=2.1` | Одна установка на самый высокий тег `2.x` на уровне или выше `2.1.0`. Оба плагина загружаются. |
180| `~2.1` | `~3.0` | Установка плагина B завершается с ошибкой `range-conflict`. Плагин A и зависимость остаются как они были. |
181| `=2.1.0` | none | Зависимость остается на `2.1.0`. Автоматическое обновление пропускает более новые версии, пока установлен плагин A. |
182
183Автоматическое обновление получает ограниченную зависимость на самом высоком теге git, который удовлетворяет диапазону каждого установленного плагина, а не на последней версии marketplace, поэтому зависимость продолжает получать обновления в пределах своего допустимого диапазона. Если ни один тег не удовлетворяет всем диапазонам, автоматическое обновление пропускает эту зависимость и указывает пропуск на вкладке Errors в `/plugin`, называя ограничивающий плагин.
184
185Когда вы удаляете последний плагин, который ограничивает зависимость, зависимость больше не удерживается и возобновляет отслеживание записи marketplace при следующем обновлении.
186
187<h2 id="enable-or-disable-a-plugin-with-dependencies">
188 Включение или отключение плагина с зависимостями
189</h2>
190
191Этот раздел охватывает плагины, установленные из маркетплейса. Для копии, которую вы загрузили с помощью `--plugin-dir`, см. [Локальное тестирование плагина и его зависимости](#test-a-plugin-and-its-dependency-locally).
192
193Включение плагина также включает плагины, от которых он зависит, и отключение плагина блокируется, если другой включенный плагин все еще нуждается в нем.
194
195Когда вы включаете плагин, Claude Code также включает его зависимости в той же области. Если зависимость имеет свои собственные зависимости, Claude Code включает и их. Сообщение об успехе выводит список того, что еще было включено вместе с плагином, который вы назвали. Если зависимость не может быть включена, команда отказывает и сообщает вам, что блокирует и как это исправить:
196
197| Условие | Результат |
198| :-------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |
199| Зависимость не установлена | Включение завершается с ошибкой и выводит команду `claude plugin install` для каждой отсутствующей зависимости. |
200| Зависимость заблокирована политикой плагинов вашей организации | Включение завершается с ошибкой и указывает на заблокированную зависимость. |
201| Зависимость установлена на `false` в области с более высоким приоритетом, чем целевая область | Включение завершается с ошибкой. Включите зависимость в этой области или передайте `--scope` для записи там. |
202| Все зависимости установлены и разрешены | Включение успешно и записывает `true` для плагина и каждой зависимости, которая еще не была включена в целевой области. |
203
204Это справедливо даже когда зависимость устанавливает [`defaultEnabled: false`](/docs/ru/plugins-reference#default-enablement) в своем манифесте, потому что Claude Code записывает явное `true` для нее. То же самое применяется при установке: зависимость, подключенная для удовлетворения активного плагина, устанавливается с `true` независимо от своего собственного значения по умолчанию.
205
206Когда вы отключаете плагин, Claude Code отказывает, если другой включенный плагин все еще зависит от него. Ошибка указывает на плагины, которые зависят от него, и дает вам цепную команду, которая отключает их в правильном порядке, заканчивая тем, который вы запросили.
207
208Например, если `deploy-kit` зависит от `secrets-vault`, отключение только `secrets-vault` завершается с ошибкой с выводом, похожим на следующий:
209
210```text theme={null}
211secrets-vault is still required by deploy-kit. Disable that plugin first, or
212disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools
213```
214
215Скопируйте цепную команду из ошибки, чтобы отключить полный набор за один шаг.
216
217<h2 id="remove-orphaned-auto-installed-dependencies">
218 Удаление осиротевших автоматически установленных зависимостей
219</h2>
220
221Автоматически установленные зависимости остаются на диске после удаления плагинов, которые их установили, на случай, если вы переустановите зависимый плагин или захотите продолжить использование зависимости напрямую. Чтобы очистить их, запустите `claude plugin prune` для вывода списка автоматически установленных зависимостей, которые больше не требуются ни одним установленным плагином, и удалите их после подтверждения.
222
223```bash theme={null}
224claude plugin prune
225```
226
227Если ничего не подлежит удалению, команда выводит `Nothing to prune` с указанием причины и завершает работу. Это ожидаемый результат при свежей установке, а не ошибка.
228
229По умолчанию prune работает в области пользователя и запрашивает подтверждение перед удалением чего-либо:
230
231* `--scope project` или `--scope local` выбирает другую область.
232* `--dry-run` выводит список того, что будет удалено, без внесения изменений.
233* `-y` пропускает подтверждение. Когда stdin или stdout не является терминалом, prune выводит список осиротевших зависимостей и завершает работу без их удаления, если не передана `-y`.
234
235Чтобы выполнить prune как часть удаления, передайте `--prune` в `claude plugin uninstall`. После удаления названного плагина Claude Code сканирует и удаляет любые автоматически установленные зависимости, которые теперь осиротели. Плагины, которые вы установили сами, никогда не удаляются, только те, которые были установлены автоматически через массив `dependencies` другого плагина.
236
237Поведение подтверждения остаётся прежним. Когда stdin или stdout не является терминалом, удаление всё ещё завершается, но шаг prune выводит список осиротевших зависимостей и ничего не удаляет, если не передана `-y`.
238
239Например, чтобы удалить `deploy-kit` и очистить зависимости, которые он оставляет:
240
241```bash theme={null}
242claude plugin uninstall deploy-kit --prune
243```
244
245<h2 id="resolve-dependency-errors">
246 Разрешение ошибок зависимостей
247</h2>
248
249Проблемы с зависимостями появляются в `claude plugin list` и в интерфейсе `/plugin` в виде описательных сообщений об ошибках вместо буквальных кодов в этой таблице. Claude Code отключает затронутый плагин до тех пор, пока вы не разрешите ошибку. Таблица ниже содержит список наиболее распространенных ошибок и способы их разрешения.
250
251| Ошибка | Значение | Как разрешить |
252| :------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
253| `dependency-unsatisfied` | Объявленная зависимость не установлена, или она установлена, но отключена. | Запустите команду `claude plugin install`, показанную в сообщении об ошибке. Если marketplace зависимости еще не настроен, добавьте его с помощью `claude plugin marketplace add`, и Claude Code разрешит зависимость автоматически. Если зависимость отключена, включите её. |
254| `range-conflict` | Требования к версии для зависимости не могут быть объединены. Сообщение об ошибке указывает причину: ни одна версия не удовлетворяет всем диапазонам, диапазон не является действительным синтаксисом semver, или объединенные диапазоны слишком сложны для пересечения. | Удалите или обновите один из конфликтующих плагинов, исправьте любую неправильную строку `version`, упростите длинные цепочки `\|\|` или попросите вышестоящего автора расширить его ограничение. |
255| `dependency-version-unsatisfied` | Версия установленной зависимости находится вне объявленного диапазона этого плагина. | Запустите `claude plugin install <dependency>@<marketplace>` для повторного разрешения зависимости относительно всех текущих ограничений. |
256| `no-matching-tag` | Репозиторий зависимости не имеет тега `{name}--v*`, удовлетворяющего диапазону. | Проверьте, что вышестоящий помечен выпусками, используя соглашение выше, или ослабьте ваш диапазон. |
257
258Чтобы проверить эти ошибки программно, запустите `claude plugin list --json`. Плагины с проблемами включают поле `errors`, в котором они перечислены. Плагины, которые загрузились без ошибок, опускают это поле.
259
260<h2 id="see-also">
261 См. также
262</h2>
263
264* [Создание плагинов](/docs/ru/plugins): создавайте плагины с skills, agents и hooks
265* [Создание и распространение marketplace плагинов](/docs/ru/plugin-marketplaces): размещайте плагины для вашей команды
266* [Справочник плагинов](/docs/ru/plugins-reference#plugin-manifest-schema): полная схема `plugin.json`
267* [Управление версиями](/docs/ru/plugins-reference#version-management): как разрешается версия самого плагина и используется в качестве ключа кэша