plugin-relevance.md +0 −186 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# Recomende plugins para sua organização
6
7> Adicione um bloco de relevância às entradas de plugins do marketplace para que Claude Code os sugira quando o trabalho de um usuário corresponder.
8
9Se você opera um marketplace de plugins para sua organização, pode fazer com que Claude Code sugira plugins específicos aos usuários com base no que estão trabalhando. Adicione um bloco `relevance` à entrada de um plugin em `marketplace.json`, depois coloque o marketplace na lista de permissões nas configurações gerenciadas. Quando a sessão de um usuário corresponder a um dos sinais declarados, Claude Code exibe uma sugestão de instalação para esse plugin.
10
11As sugestões declaradas pelo marketplace são opcionais por marketplace através das [configurações gerenciadas](/docs/pt/managed-settings). Nenhuma declaração de `relevance` de um marketplace produz sugestões até que um administrador a adicione à lista de permissões, incluindo o marketplace oficial da Anthropic. Claude Code também inclui uma sugestão integrada que é independente dessa lista de permissões; essa dica e todas as dicas declaradas pelo marketplace são desabilitadas quando [`spinnerTipsEnabled`](/docs/pt/settings-reference#spinnertipsenabled) é definido como `false`.
12
13Esta página é para operadores de marketplace e administradores corporativos. Se você está procurando instalar plugins, consulte [Descobrir e instalar plugins](/docs/pt/discover-plugins).
14
15<h2 id="how-it-works">
16 Como funciona
17</h2>
18
19Cada entrada de plugin em `marketplace.json` pode conter um objeto `relevance`. O objeto nomeia um tópico e um ou mais sinais. Um sinal é um padrão que Claude Code testa contra a sessão atual, como o diretório de trabalho ou arquivos que Claude leu.
20
21A correspondência de sinais acontece localmente na máquina do usuário. A correspondência não adiciona tráfego de rede e não relata quais sinais corresponderam, ou seus valores, à Anthropic ou ao operador do marketplace.
22
23Quando um sinal corresponde e o plugin ainda não está instalado, Claude Code mostra o plugin em três lugares:
24
25* **Dica do spinner**: uma mensagem "Trabalhando com *tópico*? Instale o plugin *plugin*" com o comando `/plugin install` aparece abaixo do spinner enquanto Claude está respondendo.
26* **Sugestão de início de sessão**: se o sinal `cwd` corresponder ao diretório de trabalho, uma notificação de uma linha `plugin suggestion: <name>@<marketplace> · /plugin` aparece antes do primeiro turno.
27* **Aba Discover do `/plugin`**: o plugin é fixado no topo da lista Discover com uma anotação como "sugerido para este diretório" ou "sugerido para comandos stripe".
28
29A dica do spinner e a notificação de início de sessão fazem parte do sistema de dicas do spinner. Claude Code desabilita ambas quando `spinnerTipsEnabled` é resolvido como `false` em seus arquivos de configuração, ou quando `excludeDefault` é resolvido como `true` em todas as chaves [`spinnerTipsOverride`](/docs/pt/settings-reference#spinnertipsoverride) em configurações de usuário, `--settings` e gerenciadas, e essas chaves configuram pelo menos uma dica ou um `tipsFile`.
30
31O pino da aba Discover é independente das configurações de dicas.
32
33Claude Code nunca instala um plugin automaticamente. O usuário sempre confirma.
34
35<h2 id="add-relevance-to-a-plugin-entry">
36 Adicione relevância a uma entrada de plugin
37</h2>
38
39Adicione um objeto `relevance` à entrada do plugin em seu `marketplace.json`. O exemplo a seguir declara que o plugin `terraform-helpers` é relevante quando Claude lê um arquivo `.tf` ou quando Claude executa `terraform`:
40
41```json theme={null}
42{
43 "name": "acme-corp-plugins",
44 "owner": { "name": "Acme Platform Team" },
45 "plugins": [
46 {
47 "name": "terraform-helpers",
48 "source": "./plugins/terraform-helpers",
49 "description": "Acme conventions and helpers for Terraform",
50 "relevance": {
51 "topic": "Terraform",
52 "signals": {
53 "cli": ["terraform"],
54 "filesRead": ["**/*.tf"]
55 }
56 }
57 }
58 ]
59}
60```
61
62Um plugin com um bloco `relevance` mas sem sinal correspondente se comporta como qualquer outra entrada do marketplace. Ele aparece na lista Discover em sua posição normal e nunca aparece como uma dica do spinner.
63
64<h2 id="field-reference">
65 Referência de campos
66</h2>
67
68<h3 id="relevance">
69 `relevance`
70</h3>
71
72| Campo | Tipo | Descrição |
73| :-------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
74| `topic` | string | Opcional. A frase que preenche "Trabalhando com *tópico*?" na dica do spinner. Geralmente o nome do produto, por exemplo `Stripe`. Use um domínio como `design` quando o nome do plugin não se lê naturalmente como um tópico. Padrão é o nome do plugin com cada segmento de hífen capitalizado. A notificação de início de sessão não usa este valor. Máximo 64 caracteres. |
75| `signals` | object | Correspondentes que determinam quando o plugin é relevante. Pelo menos um sinal é necessário para que o plugin seja sugerível. Veja a tabela abaixo. |
76
77<h3 id="relevance-signals">
78 `relevance.signals`
79</h3>
80
81| Campo | Tipo | Descrição |
82| :------------- | :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
83| `cwd` | array of strings | Padrões Glob correspondidos contra o diretório de trabalho da sessão. Correspondido como um caminho absoluto e, quando dentro de um repositório git, como um caminho relativo à raiz do repositório. Normalizado com barra invertida e insensível a maiúsculas/minúsculas. Cada padrão corresponde ao diretório em si e a tudo sob ele, então `infra`, `infra/`, e `infra/**` se comportam de forma idêntica. Este é o único sinal que pode corresponder no início da sessão, antes do primeiro turno. Máximo 10 padrões de 256 caracteres cada. |
84| `cli` | array of strings | Nomes de comando de comandos shell que Claude executou nesta sessão, por exemplo `["stripe"]`. Aplica-se em todas as plataformas: comandos executados no Windows através do PowerShell ou Git Bash são registrados da mesma forma. Claude Code registra um nome de comando por invocação de ferramenta shell: o primeiro token após qualquer atribuição de variável de ambiente inicial e `sudo`. Comandos compostos contribuem apenas com seu comando inicial, então `cd infra && terraform plan` registra `cd`, não `terraform`. Correspondência exata. Máximo 10 entradas de 64 caracteres cada. |
85| `hosts` | array of strings | Nomes de host vistos em URLs `http://` ou `https://` em comandos Bash nesta sessão, por exemplo `["api.stripe.com"]`. Apenas nome de host em minúsculas: sem esquema, porta ou caminho. Correspondência exata insensível a maiúsculas/minúsculas. Máximo 20 entradas de 128 caracteres cada. |
86| `filesRead` | array of strings | Padrões Glob correspondidos contra os caminhos de arquivos que Claude leu nesta sessão, por exemplo `["**/*.tf"]`. Normalizado com barra invertida e insensível a maiúsculas/minúsculas. Máximo 10 padrões de 256 caracteres cada. |
87| `manifestDeps` | array of objects | Dependências declaradas em manifestos de pacote que Claude leu nesta sessão. Cada entrada é `{ "file": "...", "pattern": "..." }`, onde `file` é uma expressão regular correspondida contra o caminho do arquivo de manifesto conforme registrado no estado da sessão, normalmente um caminho absoluto, e `pattern` é uma expressão regular correspondida contra o conteúdo desse arquivo. Âncora `file` no final, por exemplo `[/\\\\]package\\.json$` em forma com escape JSON, porque um padrão ancorado no início nunca corresponde a um caminho absoluto. Os caminhos não são normalizados por separador para este sinal, então os caminhos do Windows usam barras invertidas. Arquivos de manifesto maiores que 512 KB são ignorados. Ambos os valores são strings de origem `RegExp` do JavaScript de no máximo 256 caracteres. `file` corresponde insensível a maiúsculas/minúsculas. `pattern` é sensível a maiúsculas/minúsculas. Máximo 10 entradas. |
88
89Os sinais `cli`, `hosts`, `filesRead` e `manifestDeps` precisam de histórico de sessão, então eles só podem corresponder na dica do spinner e na aba Discover. O `cwd` é o único sinal que pode corresponder no início da sessão. Os sinais `filesRead` e `manifestDeps` testam o estado de arquivo registrado da sessão, que também inclui arquivos que Claude escreveu ou editou e arquivos de memória `CLAUDE.md` carregados automaticamente.
90
91O exemplo a seguir usa `manifestDeps` para sugerir um plugin Stripe uma vez que Claude leu um `package.json` que depende de `stripe`. O padrão `file` usa `[/\\\\]` para que corresponda tanto a separadores de caminho com barra invertida quanto com barra invertida, e `\\.` para que o ponto seja literal. Em JSON, cada barra invertida na expressão regular é escrita duas vezes.
92
93```json theme={null}
94{
95 "name": "stripe-helpers",
96 "source": "./plugins/stripe-helpers",
97 "relevance": {
98 "topic": "Stripe",
99 "signals": {
100 "manifestDeps": [
101 {
102 "file": "[/\\\\]package\\.json$",
103 "pattern": "\"stripe\"\\s*:"
104 }
105 ]
106 }
107 }
108}
109```
110
111<Note>
112 Claude Code ignora campos desconhecidos sob `relevance` e `relevance.signals` no tempo de carregamento, então clientes mais antigos continuam carregando seu marketplace.
113</Note>
114
115<h2 id="enable-suggestions-in-managed-settings">
116 Ative sugestões nas configurações gerenciadas
117</h2>
118
119Declarar `relevance` em `marketplace.json` não é suficiente por si só. Um administrador deve colocar o marketplace na lista de permissões nas [configurações gerenciadas](/docs/pt/managed-settings) antes que suas sugestões apareçam aos usuários.
120
121Adicione o nome do marketplace a `pluginSuggestionMarketplaces`. Para qualquer marketplace que não seja o marketplace oficial da Anthropic, também declare a fonte do marketplace nas mesmas configurações gerenciadas, seja como entrada desse nome em `extraKnownMarketplaces` ou como entrada em `strictKnownMarketplaces`. O nome colocado na lista de permissões é ignorado se o marketplace registrado na máquina veio de uma fonte diferente. Isso impede que uma fonte não relacionada se registre sob um nome colocado na lista de permissões para ter seus plugins sugeridos em toda sua organização.
122
123O `managed-settings.json` a seguir registra um marketplace de organização de um repositório GitHub e ativa suas sugestões:
124
125```json theme={null}
126{
127 "extraKnownMarketplaces": {
128 "acme-corp-plugins": {
129 "source": {
130 "source": "github",
131 "repo": "acme-corp/claude-plugins"
132 }
133 }
134 },
135 "pluginSuggestionMarketplaces": ["acme-corp-plugins"]
136}
137```
138
139O marketplace oficial está isento do requisito de declaração de fonte porque seu nome só pode ser registrado da fonte oficial da Anthropic. Colocar apenas o nome na lista de permissões é suficiente:
140
141```json theme={null}
142{
143 "pluginSuggestionMarketplaces": ["claude-plugins-official"]
144}
145```
146
147<h2 id="what-the-user-sees">
148 O que o usuário vê
149</h2>
150
151Quando um sinal corresponde durante uma sessão, a dica do spinner lê:
152
153```text theme={null}
154Working with Terraform? Install the terraform-helpers plugin:
155/plugin install terraform-helpers@acme-corp-plugins
156```
157
158No início da sessão, um sinal `cwd` correspondente exibe a notificação de uma linha:
159
160```text theme={null}
161plugin suggestion: terraform-helpers@acme-corp-plugins · /plugin
162```
163
164A sugestão de um determinado plugin aparece no máximo uma vez a cada três sessões entre a dica do spinner e a notificação de início de sessão combinadas, e nenhuma se repete uma vez que o plugin está instalado. A notificação de início de sessão também para de aparecer após a sugestão ter sido mostrada duas vezes.
165
166Na aba Discover do `/plugin`, o plugin é fixado acima dos outros resultados com uma anotação que nomeia o sinal correspondente, como `suggested for this directory` ou `suggested for terraform commands`. A aba Discover fixa um determinado plugin uma vez; visitas posteriores o listam em ordem normal.
167
168<h2 id="validate-your-marketplace">
169 Valide seu marketplace
170</h2>
171
172Execute `claude plugin validate` contra seu diretório de marketplace para verificar o bloco `relevance` antes de publicar:
173
174```
175claude plugin validate ./my-marketplace
176```
177
178O validador relata chaves desconhecidas sob `relevance` e `relevance.signals` como avisos, sinaliza um valor `relevance` que não é um objeto, e rejeita uma entrada `signals.hosts` que inclui um esquema, porta ou caminho.
179
180<h2 id="see-also">
181 Veja também
182</h2>
183
184* [Crie e distribua um marketplace de plugins](/docs/pt/plugin-marketplaces): construa o marketplace que hospeda seus plugins
185* [Recomende seu plugin a partir de sua CLI](/docs/pt/plugin-hints): solicite aos usuários a partir de sua própria CLI em vez de dos sinais de sessão do Claude Code
186* [Todas as configurações](/docs/pt/settings-reference#pluginsuggestionmarketplaces): `pluginSuggestionMarketplaces` e `extraKnownMarketplaces`