{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 从您的 CLI 推荐插件

> 从您的 CLI 发出一行标记，以便 Claude Code 提示用户安装您的官方插件。

如果您维护一个 CLI 或 SDK，并且在官方 Anthropic 市场中有一个插件，您的工具可以提示 Claude Code 用户安装该插件。当您的 CLI 检测到它正在 Claude Code 内部运行时，会将一行标记写入 stderr。Claude Code 读取该标记，将其从输出中剥离，并向用户显示一次性安装提示。

Claude Code 在将命令输出发送给模型之前会剥离提示行，因此标记永远不会出现在对话中，也不会计入 token 使用量。该协议不需要额外的命令，也不会更改您的 CLI 为 Claude Code 外部用户打印的内容。

本页面面向 CLI 和 SDK 维护者。如果您想安装插件，请参阅[发现和安装插件](/en/discover-plugins)。

## 工作原理

Claude Code 为通过 Bash 和 PowerShell 工具运行的每个命令以及[钩子](/en/hooks)命令设置 [`CLAUDECODE`](/en/env-vars) 环境变量为 `1`。当您的 CLI 看到该变量时，它会将自关闭的 `<claude-code-hint />` 标签写入 stderr。在钩子命令中，提示标签会被剥离和忽略。只有 Bash 和 PowerShell 工具输出会触发安装提示。

当 Claude Code 接收到命令输出时，它会：

1. 扫描提示行并在输出到达模型之前将其移除
2. 检查提示是否指向官方 Anthropic 市场中的插件
3. 检查插件是否尚未安装且之前未被提示过
4. 向用户显示安装提示，其中包含发出提示的命令名称

Claude Code 永远不会自动安装插件。用户始终需要确认。

## 发出提示

在 `CLAUDECODE` 环境变量上设置门控，使标记永远不会出现在人类用户的终端中。然后在单独的行上将标签写入 stderr。

以下示例为官方市场中名为 `example-cli` 的插件发出提示：

<CodeGroup>
  ```javascript Node.js theme={null}
  if (process.env.CLAUDECODE) {
    process.stderr.write(
      '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
    )
  }
  ```

  ```python Python theme={null}
  import os, sys

  if os.environ.get("CLAUDECODE"):
      print(
          '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',
          file=sys.stderr,
      )
  ```

  ```go Go theme={null}
  if os.Getenv("CLAUDECODE") != "" {
      fmt.Fprintln(os.Stderr,
          `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)
  }
  ```

  ```shell Shell theme={null}
  [ -n "$CLAUDECODE" ] &&
    printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2
  ```
</CodeGroup>

将 `example-cli` 替换为您在官方市场中的插件名称。

## 选择发出位置

您控制哪些代码路径发出提示。Claude Code 按插件去重，因此每次调用时发出都没有负面影响。效果良好的触点包括：

| 放置位置                 | 为什么有效                                               |
| :------------------------ | :--------------------------------------------------------- |
| `--help` 输出           | Claude 在探索不熟悉的 CLI 时经常运行帮助命令    |
| 未知子命令错误 | 在 Claude 对您的界面感到困惑时触达 |
| 登录或身份验证成功     | 用户已经处于设置心态                     |
| 首次运行欢迎消息 | 自然的引导时刻                                |

## 用户看到的内容

当提示通过所有检查时，Claude Code 会显示如下提示：

```text theme={null}
─────────────────────────────────────────────────────────────
  Plugin Recommendation

    The example-cli command suggests installing a plugin.

    Plugin: example-cli
    Marketplace: claude-plugins-official
    Official integration for example-cli deployments

    Would you like to install it?
    ❯ 1. Yes, install example-cli
      2. No
      3. No, and don't show plugin installation hints again

─────────────────────────────────────────────────────────────
```

提示中包含产生提示的命令名称，以便用户可以发现工具与其推荐的插件之间的不匹配。如果用户在 30 秒内未响应，提示将以 **No** 关闭。

提示频率有上限：

* **每个插件一次**：提示显示后，Claude Code 记录该插件，无论用户的回答如何，都不会再提示它。
* **每个会话一次**：在机器上的所有 CLI 中，每个 Claude Code 会话最多显示一个提示。

选择 **Yes** 会将插件安装到用户作用域。选择 **No, and don't show plugin installation hints again** 会为用户禁用所有未来的提示。

## 提示格式

提示是一个带有三个必需属性的自关闭标签。

```text theme={null}
<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
```

| 属性 | 必需 | 描述                                       |
| :-------- | :------- | :------------------------------------------------ |
| `v`       | 是      | 协议版本。`1` 是唯一受支持的值 |
| `type`    | 是      | 提示类型。`plugin` 是唯一受支持的值   |
| `value`   | 是      | `name@marketplace` 形式的插件标识符      |

属性值可以用双引号引起来，也可以不加引号。不加引号的值不能包含空白字符。不支持转义序列。

## 要求

Claude Code 在对提示执行操作之前强制执行两个条件。未通过任一检查的提示将被丢弃：

* **独占一行**：标签必须独占一行。嵌入在行中的标签（例如在日志语句内）会被忽略。行首和行尾的空白是允许的。
* **官方市场**：`value` 必须引用 Anthropic 控制的市场（如 `claude-plugins-official`）中的插件。指向其他市场的提示会被静默丢弃。

即使版本或类型未被识别，提示行也会在到达模型之前从输出中移除，因此标记永远不会计入 token 使用量。

其余指导是推荐的但不强制执行。Claude Code 无法观察您的 CLI 是否遵循它：

* **写入 stderr**：stderr 将标签排除在 shell 管道（如 `example-cli deploy | jq`）之外。Claude Code 扫描两个流，因此 stdout 也可以工作。
* **在 `CLAUDECODE` 上设置门控**：仅在 `CLAUDECODE` 环境变量被设置时发出。这可以防止标记出现在直接运行您的 CLI 的用户面前。

## 将您的插件放入官方市场

提示协议仅对 Anthropic 官方市场 `claude-plugins-official` 中列出的插件生效。Anthropic 自行决定该市场的策展，应用内提交表单会将插件添加到[社区市场](/en/plugins#submit-your-plugin-to-the-community-marketplace)，提示协议不会检查该市场。如果您正在与 Anthropic 合作伙伴联系人合作，请与他们联系以协调官方市场列表。

## 另请参阅

* [创建插件](/en/plugins)：构建您的 CLI 推荐的插件
* [创建和分发插件市场](/en/plugin-marketplaces)：在官方市场之外托管插件
* [环境变量](/en/env-vars)：`CLAUDECODE` 和相关变量的完整参考