plugin-hints.md +0 −172 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# Consiglia il tuo plugin dalla tua CLI
6
7> Emetti un marcatore su una riga dalla tua CLI in modo che Claude Code chieda agli utenti di installare il tuo plugin ufficiale.
8
9Se mantieni una CLI o SDK e hai un plugin nel marketplace ufficiale di Anthropic, il tuo strumento può chiedere agli utenti di Claude Code di installare quel plugin. La tua CLI scrive un marcatore su una riga in stderr quando rileva che è in esecuzione all'interno di Claude Code. Claude Code legge il marcatore, lo rimuove dall'output e mostra all'utente un prompt di installazione una sola volta.
10
11Il protocollo non richiede comandi extra e non cambia ciò che la tua CLI stampa per gli utenti al di fuori di Claude Code.
12
13Questa pagina è per i manutentori di CLI e SDK. Se stai cercando di installare plugin, vedi [Scopri e installa plugin](/docs/it/discover-plugins).
14
15<h2 id="how-it-works">
16 Come funziona
17</h2>
18
19Claude Code imposta la variabile di ambiente [`CLAUDECODE`](/docs/it/env-vars) a `1` per ogni comando che esegue attraverso gli strumenti Bash e PowerShell, e per i comandi [hook](/docs/it/hooks). A partire dalla versione 2.1.172 imposta anche [`CLAUDE_CODE_CHILD_SESSION`](/docs/it/env-vars) a `1` negli stessi sottoprocessi. Quando la tua CLI vede una di queste variabili, scrive un tag `<claude-code-hint />` auto-chiudente in stderr. Nei comandi hook il tag di suggerimento viene rimosso e ignorato. Solo l'output degli strumenti Bash e PowerShell attiva il prompt di installazione.
20
21Quando Claude Code riceve l'output del comando, esegue le seguenti operazioni:
22
231. Scansiona le righe di suggerimento e le rimuove prima che l'output raggiunga il modello
242. Verifica che il suggerimento sia destinato a un plugin in un marketplace ufficiale di Anthropic
253. Verifica che il plugin non sia già installato e che non sia stato suggerito in precedenza
264. Mostra all'utente un prompt di installazione che nomina il comando che ha emesso il suggerimento
27
28Claude Code non installa mai un plugin automaticamente. L'utente conferma sempre.
29
30<h2 id="emit-the-hint">
31 Emetti il suggerimento
32</h2>
33
34I suggerimenti hint vengono attivati solo per i plugin elencati nel marketplace ufficiale di Anthropic. Vedi [Inserisci il tuo plugin nel marketplace ufficiale](#get-your-plugin-into-the-official-marketplace) prima di distribuire l'integrazione.
35
36Condiziona l'emissione su una variabile di ambiente in modo che il marcatore sia improbabile che appaia quando un utente esegue direttamente la tua CLI, quindi scrivi il tag su stderr sulla sua propria riga. Scegli quale variabile controllare:
37
38* `CLAUDECODE`: impostata su ogni versione di Claude Code, quindi raggiunge il maggior numero di sessioni. È anche impostata nelle sessioni tmux e nei sottoprocessi del server MCP stdio che Claude Code avvia. Le estensioni IDE la impostano anche nei loro terminali integrati, dove un utente potrebbe eseguire direttamente la tua CLI.
39* `CLAUDE_CODE_CHILD_SESSION`: impostata solo nei sottoprocessi che Claude Code stesso genera, come le chiamate di strumenti, i comandi hook e i comandi della [riga di stato](/docs/it/statusline), quindi il tag normalmente non raggiunge un terminale umano. Un processo di lunga durata che è stato avviato all'interno di una sessione, come un server tmux, acquisisce la variabile, quindi le shell avviate successivamente da quel processo mostrano comunque il tag grezzo.
40
41I seguenti esempi condizionano su `CLAUDECODE` per la massima copertura e emettono un suggerimento per un plugin denominato `example-cli` nel marketplace ufficiale:
42
43<CodeGroup>
44 ```javascript Node.js theme={null}
45 if (process.env.CLAUDECODE) {
46 process.stderr.write(
47 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
48 )
49 }
50 ```
51
52 ```python Python theme={null}
53 import os, sys
54
55 if os.environ.get("CLAUDECODE"):
56 print(
57 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',
58 file=sys.stderr,
59 )
60 ```
61
62 ```go Go theme={null}
63 if os.Getenv("CLAUDECODE") != "" {
64 fmt.Fprintln(os.Stderr,
65 `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)
66 }
67 ```
68
69 ```shell Shell theme={null}
70 if [ -n "$CLAUDECODE" ]; then
71 printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2
72 fi
73 ```
74</CodeGroup>
75
76Sostituisci `example-cli` con il nome del tuo plugin nel marketplace ufficiale.
77
78<h2 id="choose-where-to-emit">
79 Scegli dove emettere
80</h2>
81
82Controlli quali percorsi di codice emettono il suggerimento. Claude Code deduplica per plugin, quindi emettere ad ogni invocazione non ha alcun aspetto negativo. I punti di contatto che funzionano bene includono:
83
84| Posizionamento | Perché funziona |
85| :------------------------------------- | :----------------------------------------------------------------- |
86| Output di `--help` | Claude spesso esegue help quando esplora una CLI sconosciuta |
87| Errori di sottocomando sconosciuto | Raggiunge il momento in cui Claude è confuso sulla tua interfaccia |
88| Accesso o successo dell'autenticazione | L'utente è già in uno stato mentale di configurazione |
89| Messaggio di benvenuto al primo avvio | Un momento di onboarding naturale |
90
91<h2 id="what-the-user-sees">
92 Cosa vede l'utente
93</h2>
94
95Quando il suggerimento supera tutti i controlli, Claude Code mostra un prompt come il seguente:
96
97```text theme={null}
98─────────────────────────────────────────────────────────────
99 Raccomandazione Plugin
100
101 Il comando example-cli suggerisce di installare un plugin.
102
103 Plugin: example-cli
104 Marketplace: claude-plugins-official
105 Integrazione ufficiale per distribuzioni example-cli
106
107 Desideri installarlo?
108 ❯ 1. Sì, installa example-cli
109 2. No
110 3. No, e non mostrare più suggerimenti di installazione plugin
111
112─────────────────────────────────────────────────────────────
113```
114
115Il prompt nomina il comando che ha prodotto il suggerimento in modo che gli utenti possano individuare una mancata corrispondenza tra lo strumento e il plugin che consiglia. Se l'utente non risponde entro 30 secondi, Claude Code chiude il prompt come **No**.
116
117La frequenza del prompt è limitata, e alcune sessioni non mostrano mai il prompt:
118
119* **Una volta per plugin**: dopo che il prompt viene mostrato, Claude Code registra il plugin e non lo suggerisce mai più, indipendentemente dalla risposta dell'utente.
120* **Una volta per sessione**: su tutte le CLI della macchina, al massimo un suggerimento di prompt appare per sessione di Claude Code.
121* **Solo sessione interattiva principale**: Claude Code mostra il prompt solo nella sessione del terminale in cui l'utente sta digitando. Claude Code non suggerisce mai un comando che un [subagent](/docs/it/sub-agents) esegue, e non suggerisce quando l'utente esegue Claude Code in [modalità non interattiva](/docs/it/headless) con il flag `-p` o tramite [Agent SDK](/docs/it/agent-sdk/overview). Claude Code comunque rimuove la riga del suggerimento dall'output del comando in tutti questi casi.
122* **Opt-out della telemetria**: le sessioni in cui l'analisi è disabilitata non mostrano mai i prompt di suggerimento. Questo include le sessioni con `DISABLE_TELEMETRY` o `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` impostati, e le sessioni su provider di terze parti come Amazon Bedrock o Google Cloud's Agent Platform dove si applica l'[opt-out automatico della telemetria](/docs/it/data-usage#default-behaviors-by-api-provider).
123
124Selezionando **Sì** installa il plugin nell'ambito dell'utente. Selezionando **No, e non mostrare più suggerimenti di installazione plugin** disabilita tutti i futuri suggerimenti di prompt per l'utente.
125
126<h2 id="hint-format">
127 Formato del suggerimento
128</h2>
129
130Il suggerimento è un tag auto-chiudente con tre attributi obbligatori.
131
132```text theme={null}
133<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
134```
135
136| Attributo | Obbligatorio | Descrizione |
137| :-------- | :----------- | :--------------------------------------------------------- |
138| `v` | Sì | Versione del protocollo. `1` è l'unico valore supportato |
139| `type` | Sì | Tipo di suggerimento. `plugin` è l'unico valore supportato |
140| `value` | Sì | Identificatore del plugin nella forma `name@marketplace` |
141
142I valori degli attributi possono essere racchiusi tra virgolette doppie o lasciati senza virgolette. I valori senza virgolette non possono contenere spazi. Le sequenze di escape non sono supportate.
143
144<h2 id="requirements">
145 Requisiti
146</h2>
147
148Claude Code applica due condizioni prima di agire su un suggerimento. I suggerimenti che non superano nessuno dei due controlli vengono scartati:
149
150* **Riga propria**: il tag deve occupare la sua propria riga. Un tag incorporato a metà riga, ad esempio all'interno di un'istruzione di log, viene ignorato. Gli spazi bianchi iniziali e finali sulla riga sono consentiti.
151* **Marketplace ufficiale**: il `value` deve fare riferimento a un plugin in un marketplace controllato da Anthropic come `claude-plugins-official`. I suggerimenti che puntano ad altri marketplace vengono silenziosamente scartati.
152
153La riga di suggerimento viene sempre rimossa dall'output prima che raggiunga il modello, anche quando la versione o il tipo non è riconosciuto, quindi il marcatore non viene mai conteggiato verso l'utilizzo dei token.
154
155Le linee guida rimanenti sono consigliate ma non applicate. Claude Code non può osservare se la tua CLI le segue:
156
157* **Scrivi in stderr**: stderr mantiene il tag fuori dalle pipeline di shell come `example-cli deploy | jq`. Claude Code scansiona entrambi i flussi, quindi anche stdout funziona.
158* **Condiziona su una variabile di ambiente**: emetti solo quando `CLAUDECODE` o `CLAUDE_CODE_CHILD_SESSION` è impostato. Vedi [Emetti il suggerimento](#emit-the-hint) per come i due variabili differiscono.
159
160<h2 id="get-your-plugin-into-the-official-marketplace">
161 Inserisci il tuo plugin nel marketplace ufficiale
162</h2>
163
164Il protocollo di suggerimento ha effetto solo per i plugin elencati nel marketplace ufficiale di Anthropic, `claude-plugins-official`. Anthropic cura quel marketplace a sua discrezione, e i moduli di invio in-app aggiungono plugin al [marketplace della comunità](/docs/it/plugins#submit-your-plugin-to-the-community-marketplace) invece, che il protocollo di suggerimento non controlla. Se stai lavorando con un contatto partner di Anthropic, contattalo per coordinare un elenco nel marketplace ufficiale.
165
166<h2 id="see-also">
167 Vedi anche
168</h2>
169
170* [Crea plugin](/docs/it/plugins): costruisci il plugin che la tua CLI consiglia
171* [Crea e distribuisci un marketplace di plugin](/docs/it/plugin-marketplaces): ospita plugin al di fuori del marketplace ufficiale
172* [Variabili di ambiente](/docs/it/env-vars): riferimento completo per `CLAUDECODE` e variabili correlate