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# Restringir versões de dependências de plugins
6
7> Declare restrições de versão em dependências de plugins e agrupe um conjunto de plugins curado atrás de uma única instalação.
8
9Um plugin pode depender de outros plugins listando-os em `plugin.json` ou em sua entrada de marketplace. Por padrão, uma dependência rastreia a versão mais recente disponível, portanto um lançamento upstream pode alterar a dependência sob seu plugin sem aviso. Restrições de versão permitem que você mantenha uma dependência em um intervalo de versão testado até que você escolha se mover.
10
11Quando você instala um plugin que declara dependências, Claude Code resolve e instala automaticamente, exceto por uma dependência cuja entrada de marketplace tem uma [`command` source](/docs/pt/plugin-marketplaces#how-users-accept-the-command) ou um [`headersHelper`](/docs/pt/plugin-marketplaces#how-users-accept-a-headershelper-command), que você instala primeiro. Posteriormente, `/reload-plugins`, atualização automática do marketplace do plugin dependente, executar novamente `claude plugin install` no plugin dependente e `claude plugin marketplace add` cada um instala qualquer dependência declarada que ainda não esteja instalada, sob as mesmas regras; se uma permanecer não resolvida, consulte [Resolver erros de dependência](#resolve-dependency-errors).
12
13Este guia é para autores de plugins que declaram dependências em `plugin.json` e para mantenedores de marketplace que marcam lançamentos. As dependências aqui são outros plugins; para os pacotes npm e Bun que um plugin usa, consulte [Dependências de pacotes Node.js](/docs/pt/plugins-reference#node-js-package-dependencies). Para instalar plugins que têm dependências, consulte [Descobrir e instalar plugins](/docs/pt/discover-plugins). Para o esquema de manifesto completo, consulte a [referência de Plugins](/docs/pt/plugins-reference).
14
15<h2 id="why-constrain-dependency-versions">
16 Por que restringir versões de dependências
17</h2>
18
19Considere um marketplace interno onde dois times publicam plugins. O time de plataforma mantém `secrets-vault`, um servidor MCP que envolve um backend de segredos. O time de deploy mantém `deploy-kit`, que chama `secrets-vault` para buscar credenciais durante deploys.
20
21`deploy-kit` é testado contra `secrets-vault` v2.1.0. Sem uma restrição de versão, na próxima vez que o time de plataforma marcar um lançamento que renomeia uma ferramenta MCP, a atualização automática move `secrets-vault` de cada engenheiro para a nova versão e `deploy-kit` quebra.
22
23Com uma restrição de versão, `deploy-kit` declara que precisa de `secrets-vault` no intervalo `~2.1.0`. Engenheiros com `deploy-kit` instalado permanecem na versão patch `2.1.x` mais alta correspondente. O time de deploy faz upgrade em seu próprio cronograma publicando uma nova versão de `deploy-kit` com uma restrição mais ampla.
24
25<h2 id="declare-a-dependency-with-a-version-constraint">
26 Declare uma dependência com uma restrição de versão
27</h2>
28
29Liste dependências no array `dependencies` do `plugin.json` do seu plugin.
30
31O manifesto a seguir declara uma dependência sem versão e uma dependência restrita:
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
44Uma entrada pode ser uma string simples com apenas o nome do plugin, como `"audit-logger"` no manifesto `deploy-kit`, que depende de qualquer versão que o marketplace desse plugin forneça. Para mais controle, use um objeto com estes campos:
45
46| Campo | Tipo | Descrição |
47| :------------ | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
48| `name` | string | Nome do plugin. Resolve dentro do mesmo marketplace que o plugin declarante. Obrigatório. |
49| `version` | string | Um [intervalo semver](https://github.com/npm/node-semver#ranges) como `~2.1.0`, `^2.0`, `>=1.4`, ou `=2.1.0`. A dependência é buscada na versão marcada mais alta que satisfaz este intervalo. |
50| `marketplace` | string | Um marketplace diferente para resolver `name`. Dependências entre marketplaces são bloqueadas a menos que o marketplace de destino esteja listado em [`allowCrossMarketplaceDependenciesOn`](#depend-on-a-plugin-from-another-marketplace) no `marketplace.json` do marketplace raiz. |
51
52Versões pré-lançamento como `2.0.0-beta.1` são excluídas a menos que seu intervalo opte por um sufixo pré-lançamento como `^2.0.0-0`.
53
54<h2 id="bundle-plugins-for-a-team">
55 Agrupar plugins para uma equipe
56</h2>
57
58Além do `name` obrigatório, um manifesto de plugin pode consistir apenas em um array `dependencies`. Instalá-lo puxa todas as dependências, o que o torna uma forma de empacotar um conjunto de plugins curado atrás de uma única instalação.
59
60Por exemplo, uma equipe de plataforma pode publicar bundles específicos de função em um marketplace interno para que os engenheiros executem um único `claude plugin install` em vez de instalar cada ferramenta separadamente:
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
76Instalar `backend-standard` resolve e instala todas as quatro dependências.
77
78Para adicionar uma ferramenta ao conjunto padrão posteriormente, publique uma nova versão de `backend-standard` com a dependência extra. A menos que o marketplace [atualize automaticamente](/docs/pt/discover-plugins#configure-auto-updates), os engenheiros pegam a nova versão de uma de duas formas:
79
80* Ative a atualização automática para o marketplace em `/plugin`. A próxima atualização automática move o bundle para a nova versão e instala quaisquer dependências que ele adiciona.
81* Execute `claude plugin update backend-standard`, depois `/reload-plugins` para instalar as dependências recém-adicionadas.
82
83Para distribuir bundles em toda uma organização, adicione o plugin bundle a `enabledPlugins` nas [configurações gerenciadas](/docs/pt/settings-reference#enabledplugins).
84
85<h2 id="depend-on-a-plugin-from-another-marketplace">
86 Dependa de um plugin de outro marketplace
87</h2>
88
89Por padrão, Claude Code recusa auto-instalar uma dependência que vive em um marketplace diferente do plugin que a declara. Isso evita que um marketplace puxe silenciosamente plugins de uma fonte que você não revisou.
90
91Para permitir, o mantenedor do marketplace raiz adiciona o nome do marketplace de destino a `allowCrossMarketplaceDependenciesOn` em `marketplace.json`. O marketplace raiz é aquele que hospeda o plugin que o usuário está instalando; apenas sua lista de permissões é consultada, portanto a confiança não se encadeia através de marketplaces intermediários.
92
93O seguinte `marketplace.json` permite que `deploy-kit` dependa de um plugin de `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
112Se o campo estiver faltando ou não incluir o marketplace de destino, a instalação falha com um erro `cross-marketplace` nomeando o campo a ser definido. Os usuários ainda podem instalar a dependência manualmente primeiro, o que satisfaz a restrição sem alterar a lista de permissões.
113
114<h2 id="test-a-plugin-and-its-dependency-locally">
115 Teste um plugin e sua dependência localmente
116</h2>
117
118Se você está desenvolvendo um plugin e o plugin do qual ele depende ao mesmo tempo, carregue ambos com `--plugin-dir`:
119
120```bash theme={null}
121claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin
122```
123
124A cópia local da dependência satisfaz a entrada de dependência do seu plugin, mesmo quando a entrada nomeia um marketplace, portanto você não precisa instalar a dependência do seu marketplace. Claude Code não verifica uma [restrição de versão](#declare-a-dependency-with-a-version-constraint) contra uma cópia local, portanto o `plugin.json` local não precisa de uma `version`. Antes da v2.1.242, uma entrada de dependência que nomeava um marketplace nunca correspondia à cópia local, e Claude Code desabilitava seu plugin no carregamento.
125
126Quando ambos os plugins estão em uma pasta pai, você pode passar essa pasta para `--plugin-dir` uma vez. Se a pasta não for ela mesma um plugin, Claude Code carrega cada pasta filha que tem um `.claude-plugin/plugin.json`. Requer Claude Code v2.1.265 ou posterior.
127
128Se você não instalou a dependência do seu marketplace, seu plugin para de carregar quando a cópia local desaparece:
129
130* **Você desabilitou a cópia local**: Claude Code desabilita seu plugin no próximo carregamento de plugin. Para uma entrada de dependência que nomeia um marketplace, Claude Code relata `Dependency "<name>@inline" is disabled — enable it or remove the dependency`; para uma entrada de nome simples, ele relata a dependência pelo seu nome simples. `<name>@inline` é como Claude Code identifica cada plugin `--plugin-dir` e `--plugin-url`.
131* **Você iniciou uma sessão sem o sinalizador `--plugin-dir` da dependência**: Claude Code relata a dependência como não instalada. Passe o sinalizador novamente ou instale a dependência do seu marketplace.
132
133<h2 id="tag-plugin-releases-for-version-resolution">
134 Lançamentos de tag de plugin para resolução de versão
135</h2>
136
137Claude Code resolve restrições de versão contra tags git no repositório que hospeda a dependência: o repositório próprio do plugin para [fontes de plugin](/docs/pt/plugin-marketplaces#plugin-sources) `github`, `url` e `git-subdir`, ou o repositório do marketplace para um plugin que o marketplace referencia por um caminho relativo. Para que Claude Code encontre as versões disponíveis de uma dependência, os lançamentos do plugin upstream devem ser marcados usando uma convenção de nomenclatura específica.
138
139Marque cada lançamento como `{plugin-name}--v{version}`, onde `{version}` corresponde ao campo `version` no `plugin.json` daquele commit. Do diretório do plugin, execute:
140
141```bash theme={null}
142claude plugin tag --push
143```
144
145O comando `claude plugin tag` deriva o nome da tag do manifesto do plugin e da entrada do marketplace envolvente. Antes de criar a tag, ele valida o conteúdo do plugin, verifica se `plugin.json` e a entrada do marketplace concordam sobre a versão, requer uma árvore de trabalho limpa sob o diretório do plugin e recusa se a tag já existe.
146
147* `--push` envia a tag para o remote `origin`, portanto o repositório precisa de um remote `origin` configurado. Passe `--remote` para enviar para um diferente.
148* Se o envio falhar, a tag ainda será criada localmente e o comando sairá com um erro.
149* Com `--push`, uma execução bem-sucedida termina com `Created tag secrets-vault--v2.1.0` e `Pushed to origin`, onde a última linha nomeia o remote para o qual foi enviado. Sem `--push`, o comando imprime o comando `git push` a ser executado.
150* `--dry-run` imprime o que seria marcado sem criá-lo.
151
152Executar `git tag secrets-vault--v2.1.0` diretamente é equivalente se você manter `plugin.json` e a entrada do marketplace sincronizados você mesmo.
153
154O prefixo do nome do plugin permite que um repositório do marketplace hospede múltiplos plugins com linhas de versão independentes. O separador `--v` é analisado como uma correspondência de prefixo no nome completo do plugin, portanto nomes de plugin que contêm hífens são tratados corretamente.
155
156Quando você instala um plugin que declara `{ "name": "secrets-vault", "version": "~2.1.0" }`, Claude Code lista as tags no repositório que hospeda `secrets-vault`, filtra aquelas que começam com `secrets-vault--v` e busca a versão mais alta que satisfaz `~2.1.0`. Se nenhuma tag no repositório próprio do plugin satisfizer o intervalo, a instalação falha com `Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0`, que nomeia a dependência junto com seu marketplace. Para um plugin de caminho relativo sem tag correspondente, Claude Code instala a cópia atual do marketplace em vez disso e verifica a restrição quando o plugin é carregado.
157
158Para um plugin que o marketplace referencia por um caminho relativo, um marketplace adicionado como um caminho de pasta local resolve tags da mesma forma quando a pasta é um repositório git. Isso requer Claude Code v2.1.196 ou posterior. Em dois casos Claude Code instala a dependência do conteúdo atual da pasta em vez disso:
159
160* Versões anteriores não leem tags de um marketplace de pasta local, portanto uma dependência restrita é carregada apenas se essa cópia satisfizer o intervalo.
161* Uma pasta local que não é um repositório git não tem tags, independentemente da versão.
162
163O semver da tag resolvida é registrado separadamente do `version` do `plugin.json`, portanto verificações de restrição usam a tag que foi realmente buscada mesmo se `plugin.json` naquele commit tiver um valor obsoleto. O nome do diretório de cache para uma instalação resolvida por tag inclui um sufixo de commit-SHA de 12 caracteres, portanto se um mantenedor mover uma tag para um commit diferente, a próxima instalação obtém um diretório de cache fresco em vez de reutilizar conteúdo obsoleto.
164
165<Note>
166 Para dependências com uma [fonte de plugin](/docs/pt/plugin-marketplaces#plugin-sources) `npm`, `archive` ou `command`, a restrição não controla qual versão é buscada, já que a resolução baseada em tag se aplica apenas a fontes com suporte git. A restrição ainda é verificada no tempo de carregamento, e o plugin dependente é desabilitado com `dependency-version-unsatisfied` se a versão instalada não a satisfizer. Para uma fonte `command`, Claude Code verifica a versão no `plugin.json` da dependência e ignora o sufixo de hash de conteúdo; uma dependência cujo `plugin.json` não define versão satisfaz nenhuma restrição, portanto defina uma antes de restringi-la.
167
168 Claude Code nunca instala uma dependência com uma fonte `command` em si, portanto os usuários [a instalam primeiro](/docs/pt/plugin-marketplaces#how-users-accept-the-command). Claude Code nunca executa o `headersHelper` em uma entrada de marketplace de dependência também, portanto os usuários [instalam esse plugin primeiro](/docs/pt/plugin-marketplaces#how-users-accept-a-headershelper-command).
169</Note>
170
171<h2 id="how-constraints-interact">
172 Como restrições interagem
173</h2>
174
175Quando vários plugins instalados restringem a mesma dependência, Claude Code intersecciona seus intervalos e resolve a dependência para a versão mais alta que satisfaz todos eles. A tabela abaixo mostra como combinações comuns resolvem.
176
177| Plugin A requer | Plugin B requer | Resultado |
178| :-------------- | :-------------- | :----------------------------------------------------------------------------------------------------------- |
179| `^2.0` | `>=2.1` | Uma instalação na tag `2.x` mais alta em ou acima de `2.1.0`. Ambos os plugins carregam. |
180| `~2.1` | `~3.0` | Instalação do plugin B falha com `range-conflict`. Plugin A e a dependência permanecem como estavam. |
181| `=2.1.0` | nenhum | A dependência permanece em `2.1.0`. Auto-update pula versões mais recentes enquanto plugin A está instalado. |
182
183Auto-update busca uma dependência restrita na tag git mais alta que satisfaz o intervalo de cada plugin instalado, em vez de na versão mais recente do marketplace, portanto a dependência continua a receber atualizações dentro de seu intervalo permitido. Se nenhuma tag satisfizer todos os intervalos, auto-update pula essa dependência e lista o pulo na aba Errors do `/plugin`, nomeando o plugin restringidor.
184
185Quando você desinstala o último plugin que restringe uma dependência, a dependência não é mais mantida e retoma o rastreamento de sua entrada de marketplace na próxima atualização.
186
187<h2 id="enable-or-disable-a-plugin-with-dependencies">
188 Ativar ou desativar um plugin com dependências
189</h2>
190
191Esta seção aborda plugins instalados a partir de um marketplace. Para uma cópia que você carregou com `--plugin-dir`, consulte [Testar um plugin e sua dependência localmente](#test-a-plugin-and-its-dependency-locally).
192
193Ativar um plugin também ativa os plugins dos quais ele depende, e desativar um plugin é bloqueado se outro plugin ativado ainda precisar dele.
194
195Quando você ativa um plugin, Claude Code também ativa suas dependências no mesmo escopo. Se uma dependência tiver suas próprias dependências, Claude Code ativa aquelas também. A mensagem de sucesso lista o que mais foi ativado junto com o plugin que você nomeou. Se uma dependência não puder ser ativada, o comando recusa e diz o que está bloqueando e como corrigir:
196
197| Condição | Resultado |
198| :-------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
199| Uma dependência não está instalada | Ativar falha e imprime o comando `claude plugin install` para cada dependência ausente. |
200| Uma dependência é bloqueada pela política de plugins da sua organização | Ativar falha e nomeia a dependência bloqueada. |
201| Uma dependência está definida como `false` em um escopo com precedência mais alta que o escopo de destino | Ativar falha. Ative a dependência naquele escopo, ou passe `--scope` para escrever lá. |
202| Todas as dependências estão instaladas e permitidas | Ativar sucede e escreve `true` para o plugin e cada dependência que não estava já ativada no escopo de destino. |
203
204Isto se aplica mesmo quando uma dependência define [`defaultEnabled: false`](/docs/pt/plugins-reference#default-enablement) em seu manifesto, porque Claude Code escreve um `true` explícito para ela. O mesmo se aplica na instalação: uma dependência trazida para satisfazer um plugin ativo instala com `true` independentemente de seu próprio padrão.
205
206Quando você desativa um plugin, Claude Code recusa se outro plugin ativado ainda depender dele. O erro nomeia os plugins que dependem dele e dá a você um comando encadeado que os desativa na ordem correta, terminando com o que você pediu.
207
208Por exemplo, se `deploy-kit` depende de `secrets-vault`, desativar `secrets-vault` sozinho falha com saída similar à seguinte:
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
215Copie o comando encadeado do erro para desativar o conjunto completo em uma etapa.
216
217<h2 id="remove-orphaned-auto-installed-dependencies">
218 Remova dependências auto-instaladas órfãs
219</h2>
220
221Dependências auto-instaladas permanecem no disco após os plugins que as instalaram serem desinstalados, no caso de você reinstalar um plugin dependente ou querer continuar usando a dependência diretamente. Para limpá-las, execute `claude plugin prune` para listar as dependências auto-instaladas que não têm mais nenhum plugin instalado exigindo-as e removê-las após um prompt de confirmação.
222
223```bash theme={null}
224claude plugin prune
225```
226
227Se nada se qualificar para remoção, o comando imprime `Nothing to prune` com o motivo e sai. Esta é a saída esperada em uma instalação nova, não um erro.
228
229Por padrão, prune opera no escopo do usuário e pede confirmação antes de remover qualquer coisa:
230
231* `--scope project` ou `--scope local` direciona um escopo diferente.
232* `--dry-run` lista o que seria removido sem alterar nada.
233* `-y` pula o prompt de confirmação. Quando stdin ou stdout não é um terminal, prune lista os órfãos e sai sem removê-los a menos que você passe `-y`.
234
235Para prune como parte de uma desinstalação, passe `--prune` para `claude plugin uninstall`. Após remover o plugin nomeado, Claude Code verifica e remove quaisquer dependências auto-instaladas que agora estão órfãs. Plugins que você instalou você mesmo nunca são podados, apenas aqueles instalados automaticamente através do array `dependencies` de outro plugin.
236
237O mesmo comportamento de confirmação se aplica. Quando stdin ou stdout não é um terminal, a desinstalação ainda é concluída, mas a etapa prune lista os órfãos e não remove nada a menos que você passe `-y`.
238
239Por exemplo, para desinstalar `deploy-kit` e limpar as dependências que deixa para trás:
240
241```bash theme={null}
242claude plugin uninstall deploy-kit --prune
243```
244
245<h2 id="resolve-dependency-errors">
246 Resolva erros de dependência
247</h2>
248
249Problemas de dependência aparecem em `claude plugin list` e na interface `/plugin`, como mensagens de erro descritivas em vez dos códigos literais nesta tabela. Claude Code desabilita o plugin afetado até que você resolva o erro. A tabela abaixo lista os erros mais comuns e como resolvê-los.
250
251| Erro | Significado | Como resolver |
252| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
253| `dependency-unsatisfied` | Uma dependência declarada não está instalada, ou está instalada mas desabilitada. | Execute o comando `claude plugin install` mostrado na mensagem de erro. Se o marketplace da dependência ainda não está configurado, adicione-o com `claude plugin marketplace add` e Claude Code resolve a dependência automaticamente. Se a dependência está desabilitada, ative-a. |
254| `range-conflict` | Os requisitos de versão para uma dependência não podem ser combinados. A mensagem de erro nomeia a causa: nenhuma versão satisfaz todos os intervalos, um intervalo não é sintaxe semver válida, ou os intervalos combinados são muito complexos para interseccionar. | Desinstale ou atualize um dos plugins conflitantes, corrija qualquer string `version` inválida, simplifique cadeias `\|\|` longas, ou peça ao autor upstream para ampliar sua restrição. |
255| `dependency-version-unsatisfied` | A versão da dependência instalada está fora do intervalo declarado deste plugin. | Execute `claude plugin install <dependency>@<marketplace>` para re-resolver a dependência contra todas as restrições atuais. |
256| `no-matching-tag` | O repositório da dependência não tem uma tag `{name}--v*` satisfazendo o intervalo. | Verifique se o upstream marcou lançamentos usando a convenção acima, ou relaxe seu intervalo. |
257
258Para verificar esses erros programaticamente, execute `claude plugin list --json`. Plugins com problemas incluem um campo `errors` listando-os. Plugins que carregaram corretamente omitem o campo.
259
260<h2 id="see-also">
261 Veja também
262</h2>
263
264* [Criar plugins](/docs/pt/plugins): construa plugins com skills, agents e hooks
265* [Criar e distribuir um marketplace de plugins](/docs/pt/plugin-marketplaces): hospede plugins para seu time
266* [Referência de Plugins](/docs/pt/plugins-reference#plugin-manifest-schema): o esquema completo de `plugin.json`
267* [Gerenciamento de versão](/docs/pt/plugins-reference#version-management): como a versão própria de um plugin é resolvida e usada como a chave de cache