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# Рекомендуйте ваш плагин из вашего CLI
6
7> Выведите однострочный маркер из вашего CLI, чтобы Claude Code предложил пользователям установить ваш официальный плагин.
8
9Если вы поддерживаете CLI или SDK и у вас есть плагин в официальном маркетплейсе Anthropic, ваш инструмент может предложить пользователям Claude Code установить этот плагин. Ваш CLI выводит однострочный маркер в stderr, когда обнаруживает, что работает внутри Claude Code. Claude Code читает маркер, удаляет его из вывода и показывает пользователю одноразовое предложение об установке.
10
11Протокол не требует дополнительных команд и не изменяет то, что ваш CLI выводит для пользователей вне Claude Code.
12
13Эта страница предназначена для разработчиков CLI и SDK. Если вы ищете информацию об установке плагинов, см. [Обнаружение и установка плагинов](/docs/ru/discover-plugins).
14
15<h2 id="how-it-works">
16 Как это работает
17</h2>
18
19Claude Code устанавливает переменную окружения [`CLAUDECODE`](/docs/ru/env-vars) в значение `1` для каждой команды, которую он запускает через инструменты Bash и PowerShell, а также для команд [hook](/docs/ru/hooks). Начиная с версии 2.1.172, он также устанавливает [`CLAUDE_CODE_CHILD_SESSION`](/docs/ru/env-vars) в значение `1` в этих же подпроцессах. Когда ваш CLI видит одну из этих переменных, он выводит самозакрывающийся тег `<claude-code-hint />` в stderr. В командах hook тег подсказки удаляется и игнорируется. Только вывод инструментов Bash и PowerShell запускает приглашение установки.
20
21Когда Claude Code получает вывод команды, он:
22
231. Сканирует строки подсказок и удаляет их перед тем, как вывод достигнет модели
242. Проверяет, что подсказка указывает на плагин в официальном маркетплейсе Anthropic
253. Проверяет, что плагин ещё не установлен и на него не было предложения ранее
264. Показывает пользователю предложение об установке, в котором указана команда, выведшая подсказку
27
28Claude Code никогда не устанавливает плагин автоматически. Пользователь всегда подтверждает.
29
30<h2 id="emit-the-hint">
31 Выведите подсказку
32</h2>
33
34Подсказки срабатывают только для плагинов, указанных в официальном маркетплейсе Anthropic. Смотрите [Добавьте ваш плагин в официальный маркетплейс](#get-your-plugin-into-the-official-marketplace) перед тем, как вы развернёте интеграцию.
35
36Обусловьте вывод переменной окружения, чтобы маркер был маловероятен при прямом запуске вашего CLI пользователем, затем выведите тег в stderr на отдельной строке. Выберите, какую переменную проверять:
37
38* `CLAUDECODE`: устанавливается в каждой версии Claude Code, поэтому достигает большинства сеансов. Она также устанавливается в tmux сеансах и подпроцессах stdio MCP сервера, которые запускает Claude Code. Расширения IDE также устанавливают её в своих интегрированных терминалах, где пользователь может запускать ваш CLI напрямую.
39* `CLAUDE_CODE_CHILD_SESSION`: устанавливается только в подпроцессах, которые сам Claude Code порождает, таких как вызовы инструментов, команды hook и команды [строки состояния](/docs/ru/statusline), поэтому тег обычно не достигает терминала пользователя. Долгоживущий процесс, запущенный внутри сеанса, такой как tmux сервер, захватывает переменную, поэтому оболочки, позже запущенные из этого процесса, всё ещё показывают необработанный тег.
40
41Следующие примеры обусловливают `CLAUDECODE` для максимального охвата и выводят подсказку для плагина с именем `example-cli` в официальном маркетплейсе:
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
76Замените `example-cli` на имя вашего плагина в официальном маркетплейсе.
77
78<h2 id="choose-where-to-emit">
79 Выберите место для вывода
80</h2>
81
82Вы контролируете, какие пути кода выводят подсказку. Claude Code дедублицирует по плагину, поэтому вывод при каждом вызове не имеет никаких недостатков. Хорошо работают следующие точки:
83
84| Размещение | Почему это работает |
85| :------------------------------------------ | :----------------------------------------------------------- |
86| Вывод `--help` | Claude часто запускает справку при изучении незнакомого CLI |
87| Ошибки неизвестной подкоманды | Достигает момента, когда Claude запутался в вашем интерфейсе |
88| Успешный вход или аутентификация | Пользователь уже находится в режиме настройки |
89| Приветственное сообщение при первом запуске | Естественный момент адаптации |
90
91<h2 id="what-the-user-sees">
92 Что видит пользователь
93</h2>
94
95Когда подсказка проходит все проверки, Claude Code показывает приглашение, подобное следующему:
96
97```text theme={null}
98─────────────────────────────────────────────────────────────
99 Рекомендация плагина
100
101 Команда example-cli предлагает установить плагин.
102
103 Плагин: example-cli
104 Маркетплейс: claude-plugins-official
105 Официальная интеграция для развёртываний example-cli
106
107 Хотите ли вы установить его?
108 ❯ 1. Да, установить example-cli
109 2. Нет
110 3. Нет, и больше не показывать предложения об установке плагинов
111
112─────────────────────────────────────────────────────────────
113```
114
115Приглашение указывает команду, которая произвела подсказку, чтобы пользователи могли заметить несоответствие между инструментом и плагином, который он рекомендует. Если пользователь не ответит в течение 30 секунд, Claude Code закрывает приглашение как **Нет**.
116
117Частота приглашений ограничена, и некоторые сеансы никогда не показывают приглашения:
118
119* **Один раз на плагин**: после того как приглашение показано, Claude Code записывает плагин и никогда больше не предлагает его, независимо от ответа пользователя.
120* **Один раз за сеанс**: на всех CLI на машине одновременно может появиться максимум одно приглашение подсказки за сеанс Claude Code.
121* **Только в основном интерактивном сеансе**: Claude Code показывает приглашение только в сеансе терминала, в который пользователь вводит текст. Claude Code никогда не предлагает команду, которую запускает [подагент](/docs/ru/sub-agents), и никогда не предлагает, когда пользователь запускает Claude Code в [неинтерактивном режиме](/docs/ru/headless) с флагом `-p` или через [Agent SDK](/docs/ru/agent-sdk/overview). Claude Code по-прежнему удаляет строку подсказки из выходных данных команды во всех этих случаях.
122* **Отказ от телеметрии**: сеансы, в которых аналитика отключена, никогда не показывают приглашения подсказок. Это включает сеансы с установленными `DISABLE_TELEMETRY` или `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, а также сеансы у сторонних поставщиков, таких как Amazon Bedrock или Google Cloud's Agent Platform, где применяется [автоматический отказ от телеметрии](/docs/ru/data-usage#default-behaviors-by-api-provider).
123
124Выбор **Да** устанавливает плагин в область пользователя. Выбор **Нет, и больше не показывать предложения об установке плагинов** отключает все будущие приглашения подсказок для пользователя.
125
126<h2 id="hint-format">
127 Формат подсказки
128</h2>
129
130Подсказка — это самозакрывающийся тег с тремя обязательными атрибутами.
131
132```text theme={null}
133<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
134```
135
136| Атрибут | Обязательный | Описание |
137| :------ | :----------- | :------------------------------------------------------------- |
138| `v` | Да | Версия протокола. `1` — единственное поддерживаемое значение |
139| `type` | Да | Тип подсказки. `plugin` — единственное поддерживаемое значение |
140| `value` | Да | Идентификатор плагина в форме `name@marketplace` |
141
142Значения атрибутов могут быть заключены в двойные кавычки или оставлены без кавычек. Значения без кавычек не могут содержать пробелы. Последовательности экранирования не поддерживаются.
143
144<h2 id="requirements">
145 Требования
146</h2>
147
148Claude Code применяет два условия перед действием на основе подсказки. Подсказки, которые не проходят ни одну из проверок, отбрасываются:
149
150* **Отдельная строка**: тег должен занимать отдельную строку. Тег, встроенный в середину строки, например внутри оператора логирования, игнорируется. Пробелы в начале и конце строки допускаются.
151* **Официальный маркетплейс**: `value` должен ссылаться на плагин в контролируемом Anthropic маркетплейсе, таком как `claude-plugins-official`. Подсказки, указывающие на другие маркетплейсы, молча отбрасываются.
152
153Строка подсказки всегда удаляется из вывода перед тем, как она достигнет модели, даже если версия или тип не распознаны, поэтому маркер никогда не учитывается при подсчёте использованных токенов.
154
155Остальные рекомендации рекомендуются, но не обязательны. Claude Code не может наблюдать, следует ли ваш CLI им:
156
157* **Выводите в stderr**: stderr держит тег вне конвейеров оболочки, таких как `example-cli deploy | jq`. Claude Code сканирует оба потока, поэтому stdout также работает.
158* **Обусловьте на переменной окружения**: выводите только когда установлена переменная окружения `CLAUDECODE` или `CLAUDE_CODE_CHILD_SESSION`. Смотрите [Выведите подсказку](#emit-the-hint), чтобы узнать, чем отличаются эти две переменные.
159
160<h2 id="get-your-plugin-into-the-official-marketplace">
161 Добавьте ваш плагин в официальный маркетплейс
162</h2>
163
164Протокол подсказок вступает в силу только для плагинов, которые указаны в официальном маркетплейсе Anthropic, `claude-plugins-official`. Anthropic курирует этот маркетплейс по своему усмотрению, а встроенные формы отправки добавляют плагины в [маркетплейс сообщества](/docs/ru/plugins#submit-your-plugin-to-the-community-marketplace), который протокол подсказок не проверяет. Если вы работаете с контактом партнёра Anthropic, свяжитесь с ним для координации листинга в официальном маркетплейсе.
165
166<h2 id="see-also">
167 См. также
168</h2>
169
170* [Создание плагинов](/docs/ru/plugins): создайте плагин, который рекомендует ваш CLI
171* [Создание и распространение маркетплейса плагинов](/docs/ru/plugin-marketplaces): размещайте плагины вне официального маркетплейса
172* [Переменные окружения](/docs/ru/env-vars): полный справочник по `CLAUDECODE` и связанным переменным