Claude Code 生态与安全

为组织推荐插件

2 分钟阅读

为组织推荐插件

在插件市场的插件条目中添加 relevance 块，让 Claude Code 在用户的工作内容与插件匹配时主动推荐。

如果你为组织运营插件市场，可以让 Claude Code 根据用户正在处理的工作向他们推荐特定插件。在 marketplace.json 的插件条目中添加 relevance 块，再通过托管设置将该插件市场加入允许列表。当用户会话与声明的某项信号匹配时，Claude Code 就会显示相应插件的安装建议。

是否启用插件市场声明的推荐，需要通过托管设置按插件市场选择加入。管理员将插件市场加入允许列表前，该市场的 relevance 声明不会产生任何推荐，Anthropic 官方插件市场也不例外。Claude Code 还内置了一条不受此允许列表控制的推荐；当 spinnerTipsEnabled 设为 false 时，这条内置提示和所有插件市场声明的提示都会被禁用。

此功能需要 Claude Code v2.1.152 或更高版本。较早的客户端会忽略 relevance 字段。

本页面面向插件市场运营者和企业管理员。如果你希望安装插件，请参阅发现并安装插件。

工作原理

marketplace.json 中的每个插件条目都可以包含 relevance 对象。该对象指定一个主题以及一个或多个信号。信号是 Claude Code 用来匹配当前会话的模式，例如工作目录或 Claude 已读取的文件。

信号匹配在用户计算机本地进行。匹配过程不会增加任何网络流量，也不会向 Anthropic 或插件市场运营者报告哪些信号匹配成功或信号的具体值。

当某项信号匹配且插件尚未安装时，Claude Code 会在三个位置显示该插件：

spinner 提示：Claude 响应期间，spinner 下方会显示一条“正在使用 topic？请安装 plugin 插件”消息，其中附有 /plugin install 命令。
会话启动推荐：如果 cwd 信号与工作目录匹配，首次交互前会显示单行通知 plugin suggestion: <name>@<marketplace> · /plugin。此显示位置需要 Claude Code v2.1.153 或更高版本。
/plugin 的 Discover 标签页：插件会置顶到 Discover 列表，并附有“suggested for this directory”或“suggested for stripe commands”之类的注释。此显示位置需要 Claude Code v2.1.154 或更高版本。

spinner 提示和会话启动通知都属于 spinner-tips 系统。当用户或项目将 spinnerTipsEnabled 设为 false，或配置了带 excludeDefault 的自定义 spinnerTipsOverride 时，二者都会被禁用。Discover 标签页的置顶推荐不受提示设置影响。

Claude Code 绝不会自动安装插件，始终由用户确认。

向插件条目添加 relevance

在 marketplace.json 的插件条目中添加 relevance 对象。以下示例声明：Claude 读取 .tf 文件或运行 terraform 时，terraform-helpers 插件与当前工作相关：

{
  "name": "acme-corp-plugins",
  "owner": { "name": "Acme Platform Team" },
  "plugins": [
    {
      "name": "terraform-helpers",
      "source": "./plugins/terraform-helpers",
      "description": "Acme conventions and helpers for Terraform",
      "relevance": {
        "topic": "Terraform",
        "signals": {
          "cli": ["terraform"],
          "filesRead": ["**/*.tf"]
        }
      }
    }
  ]
}

如果插件包含 relevance 块，但没有任何信号匹配，其行为与普通插件市场条目相同：它会显示在 Discover 列表中的正常位置，绝不会作为 spinner 提示出现。

字段参考

`relevance`

字段	类型	说明
`topic`	string	可选。用于填充 spinner 提示中“正在使用 topic？”的短语，通常为产品名称，例如 `Stripe`。如果插件名称作为主题读起来不自然，可以使用 `design` 等领域名称。默认值为插件名称，其中以连字符分隔的各段首字母大写。会话启动通知不使用此值。最多 64 个字符。
`signals`	object	用于判断插件何时相关的 matcher。插件至少要有一项信号，才能作为推荐显示。请参阅下表。

`relevance.signals`

字段	类型	说明
`cwd`	字符串数组	用于匹配会话工作目录的 glob 模式。系统会按绝对路径进行匹配；如果目录位于 git 仓库内，还会按相对于仓库根目录的路径进行匹配。路径统一使用正斜杠，且匹配不区分大小写。每个模式都会匹配目录本身及其下所有内容，因此 `infra`、`infra/` 和 `infra/**` 的行为相同。这是唯一能在会话启动时、首次交互前进行匹配的信号。最多 10 个模式，每个不超过 256 个字符。
`cli`	字符串数组	Claude 在当前会话中运行过的 shell 命令名称，例如 `["stripe"]`。适用于所有平台：在 Windows 上通过 PowerShell 或 Git Bash 运行的命令会以相同方式记录。Claude Code 每次调用 shell 工具只记录一个命令名称：跳过开头的环境变量赋值和 `sudo` 后的第一个 Token。对于复合命令，只记录最开头的命令，因此，`cd infra && terraform plan` 记录的是 `cd`，而不是 `terraform`。精确匹配。最多 10 个条目，每个不超过 64 个字符。
`hosts`	字符串数组	当前会话的 Bash 命令中，`http://` 或 `https://` URL 里出现过的主机名，例如 `["api.stripe.com"]`。只能是小写主机名本身，不能包含 scheme、端口或路径。精确匹配，不区分大小写。最多 20 个条目，每个不超过 128 个字符。
`filesRead`	字符串数组	用于匹配 Claude 在当前会话中读取过的文件路径的 glob 模式，例如 `["*/.tf"]`。路径统一使用正斜杠，且匹配不区分大小写。最多 10 个模式，每个不超过 256 个字符。
`manifestDeps`	对象数组	Claude 在当前会话中读取过的 package manifest 所声明的依赖。每个条目为 `{ "file": "...", "pattern": "..." }`；其中，`file` 是用于匹配会话状态中所记录 manifest 文件路径的正则表达式（通常为绝对路径），`pattern` 是用于匹配该文件内容的正则表达式。请在 `file` 末尾设置锚点，例如 JSON 转义形式的 `[/\\\\]package\\.json$`，因为以起始位置为锚点的模式永远无法匹配绝对路径。此信号不会统一路径分隔符，因此 Windows 路径使用反斜杠。大于 512 KB 的 manifest 文件会被跳过。两个值均为 JavaScript `RegExp` 源字符串，长度不超过 256 个字符。`file` 匹配不区分大小写，`pattern` 匹配区分大小写。最多 10 个条目。

cli、hosts、filesRead 和 manifestDeps 信号需要会话历史，因此只能在 spinner 提示和 Discover 标签页中匹配。只有 cwd 能在会话启动时匹配。filesRead 和 manifestDeps 信号会检查会话中记录的文件状态，其中也包括 Claude 写入或编辑过的文件，以及自动加载的 CLAUDE.md 记忆文件。

以下示例使用 manifestDeps：Claude 读取依赖 stripe 的 package.json 后，推荐一个 Stripe 插件。file 模式使用 [/\\\\]，以同时匹配正斜杠和反斜杠路径分隔符；使用 \\.，让句点按字面值匹配。在 JSON 中，正则表达式里的每个反斜杠都要写两次。

{
  "name": "stripe-helpers",
  "source": "./plugins/stripe-helpers",
  "relevance": {
    "topic": "Stripe",
    "signals": {
      "manifestDeps": [
        {
          "file": "[/\\\\]package\\.json$",
          "pattern": "\"stripe\"\\s*:"
        }
      ]
    }
  }
}

加载时会忽略 relevance 和 relevance.signals 下的未知字段，确保较早的 Claude Code 客户端仍能加载你的插件市场。运行 claude plugin validate 可以将它们作为警告显示出来。

在托管设置中启用推荐

仅在 marketplace.json 中声明 relevance 并不足以启用推荐。管理员必须先通过托管设置将插件市场加入允许列表，用户才能看到它的推荐。

将插件市场名称添加到 pluginSuggestionMarketplaces。对于 Anthropic 官方插件市场以外的所有插件市场，还要在同一份托管设置中声明插件市场来源：可以将其作为相应名称的条目添加到 extraKnownMarketplaces，也可以添加为 strictKnownMarketplaces 中的条目。如果计算机上注册的插件市场来自另一个来源，系统会忽略已加入允许列表的名称。这样可以防止无关来源使用已获准的名称进行注册，进而向整个组织推荐自己的插件。

以下 managed-settings.json 从 GitHub 仓库注册组织插件市场，并启用其推荐：

{
  "extraKnownMarketplaces": {
    "acme-corp-plugins": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  },
  "pluginSuggestionMarketplaces": ["acme-corp-plugins"]
}

官方插件市场无需满足来源声明要求，因为它的名称只能由 Anthropic 官方来源注册。只需把名称加入允许列表即可：

{
  "pluginSuggestionMarketplaces": ["claude-plugins-official"]
}

完整配置详情请参阅 pluginSuggestionMarketplaces 的设置参考，以及 extraKnownMarketplaces。

用户看到的内容

会话期间有信号匹配时，spinner 提示如下：

Working with Terraform? Install the terraform-helpers plugin:
/plugin install terraform-helpers@acme-corp-plugins

会话启动时，如果 cwd 信号匹配，则显示以下单行通知：

plugin suggestion: terraform-helpers@acme-corp-plugins · /plugin

对于同一个插件，spinner 提示和会话启动通知合计每三个会话最多出现一次；插件安装后，二者都不再重复显示。此外，会话启动通知显示两次后也会停止出现。

在 /plugin 的 Discover 标签页中，插件会置顶到其他结果上方，并附上指出匹配信号的注释，例如 suggested for this directory 或 suggested for terraform commands。Discover 标签页只会将特定插件置顶一次；之后再打开该标签页时，插件会按正常顺序显示。Discover 标签页置顶需要 Claude Code v2.1.154 或更高版本。在 v2.1.152 中仅显示 spinner 提示；v2.1.153 新增会话启动通知。

验证插件市场

发布前，请对插件市场目录运行 claude plugin validate，检查 relevance 块：

claude plugin validate ./my-marketplace

验证器会把 relevance 和 relevance.signals 下的未知键报告为警告；如果 relevance 的值不是对象，会将其标记为错误；如果 signals.hosts 条目包含 scheme、端口或路径，则会拒绝该条目。

另请参阅

创建并分发插件市场：构建用于托管插件的插件市场
通过 CLI 推荐你的插件：通过你自己的 CLI 提示用户，而不是使用 Claude Code 的会话信号
设置：pluginSuggestionMarketplaces 和 extraKnownMarketplaces 的完整参考

上一页从 CLI 推荐插件下一页安全性说明