plugin-marketplaces.md +0 −1687 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# 创建和分发 plugin marketplace
6
7> 构建和托管 plugin marketplace，以在团队和社区中分发 Claude Code 扩展。
8
9**plugin marketplace** 是一个目录，让你能够将 plugins 分发给他人。Marketplace 提供集中式发现、版本跟踪、自动更新以及对多种源类型（包括 git 存储库和本地路径）的支持。本指南展示了如何创建自己的 marketplace，与你的团队或社区共享 plugins。
10
11想要从现有 marketplace 安装 plugins？请参阅[发现和安装预构建的 plugins](/docs/zh-CN/discover-plugins)。
12
13<h2 id="overview">
14 概述
15</h2>
16
17创建和分发 marketplace 涉及：
18
191. **创建 plugins**：使用 skills、agents、hooks、MCP servers 或 LSP servers 构建一个或多个 plugins。本指南假设你已经有要分发的 plugins；有关如何创建 plugins 的详细信息，请参阅[创建 plugins](/docs/zh-CN/plugins)。
202. **创建 marketplace 文件**：定义一个 `marketplace.json`，列出你的 plugins 及其位置。请参阅[创建 marketplace 文件](#create-the-marketplace-file)。
213. **托管 marketplace**：推送到 GitHub、GitLab 或其他 git 主机。请参阅[托管和分发 marketplaces](#host-and-distribute-marketplaces)。
224. **与用户共享**：用户使用 `/plugin marketplace add` 添加你的 marketplace 并安装单个 plugins。请参阅[发现和安装 plugins](/docs/zh-CN/discover-plugins)。
23
24一旦你的 marketplace 上线，你可以通过推送更改到你的存储库来更新它。用户使用 `/plugin marketplace update` 刷新他们的本地副本。
25
26<h2 id="walkthrough-create-a-local-marketplace">
27 演练：创建本地 marketplace
28</h2>
29
30此示例创建一个包含一个 plugin 的 marketplace：一个用于代码审查的 `quality-review` skill。你将创建目录结构、添加 skill、创建 plugin manifest 和 marketplace 目录，然后安装并测试它。
31
32<Steps>
33 <Step title="创建目录结构">
34 ```bash theme={null}
35 mkdir -p my-marketplace/.claude-plugin
36 mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
37 mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review
38 ```
39 </Step>
40
41 <Step title="创建 skill">
42 创建一个 `SKILL.md` 文件，定义 `quality-review` skill 的功能。
43
44 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}
45 ---
46 description: Review code for bugs, security, and performance
47 ---
48
49 Review the code I've selected or the recent changes for:
50 - Potential bugs or edge cases
51 - Security concerns
52 - Performance issues
53 - Readability improvements
54
55 Be concise and actionable.
56 ```
57 </Step>
58
59 <Step title="创建 plugin manifest">
60 创建一个 `plugin.json` 文件，描述该 plugin。manifest 位于 `.claude-plugin/` 目录中。
61
62 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}
63 {
64 "name": "quality-review-plugin",
65 "description": "Adds a quality-review skill for quick code reviews",
66 "version": "1.0.0",
67 "author": {
68 "name": "Your Name"
69 }
70 }
71 ```
72
73 <Note>
74 设置 `version` 意味着用户仅在你更改此字段时才会收到更新，因此在每次发布时都要提升版本号。具有 [`command` source](#command-sources) 的 plugin 不会被此字段固定。从本地目录添加的 marketplace 中 [就地加载](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution) 的 plugin 也不会被固定。如果你省略 `version`，版本来自 [版本管理](/docs/zh-CN/plugins-reference#version-management) 中的下一个来源。
75 </Note>
76 </Step>
77
78 <Step title="创建 marketplace 文件">
79 创建列出你的 plugin 的 marketplace 目录。
80
81 ```json my-marketplace/.claude-plugin/marketplace.json theme={null}
82 {
83 "name": "my-plugins",
84 "owner": {
85 "name": "Your Name"
86 },
87 "plugins": [
88 {
89 "name": "quality-review-plugin",
90 "source": "./plugins/quality-review-plugin",
91 "description": "Adds a quality-review skill for quick code reviews"
92 }
93 ]
94 }
95 ```
96 </Step>
97
98 <Step title="添加和安装">
99 从包含 `my-marketplace` 的目录启动 Claude Code 并运行以下命令。install 命令打开一个 plugin 详情视图，你可以在其中选择安装范围来确认安装。检查安装摘要：如果它报告 `Run /reload-plugins to activate.`，请参阅 [不重启应用而应用 plugin 更改](/docs/zh-CN/discover-plugins#apply-plugin-changes-without-restarting)。
100
101 ```shell theme={null}
102 /plugin marketplace add ./my-marketplace
103 /plugin install quality-review-plugin@my-plugins
104 ```
105 </Step>
106
107 <Step title="尝试一下">
108 在编辑器中选择一些代码并运行你的新 skill。Plugin skills 使用 plugin 名称进行命名空间划分。
109
110 ```shell theme={null}
111 /quality-review-plugin:quality-review
112 ```
113 </Step>
114</Steps>
115
116要了解更多关于 plugins 可以做什么的信息，包括 hooks、agents、MCP servers 和 LSP servers，请参阅 [Plugins](/docs/zh-CN/plugins)。
117
118<Note>
119 **plugins 如何安装**：当用户安装 plugin 时，Claude Code 将 plugin 目录复制到缓存位置，除非 plugin 就地加载。link mode 中的 [`command` source](#copy-mode-and-link-mode) 就地加载，从本地目录添加的 marketplace 中的 [相对路径 source](#relative-paths) 也是如此。复制的 plugins 无法使用 `../shared-utils` 之类的路径引用其目录外的文件，因为这些文件不会被复制。
120
121 如果你需要在 plugins 之间共享文件，请使用符号链接。有关详细信息，请参阅 [Plugin 缓存和文件解析](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)。
122</Note>
123
124<h2 id="create-the-marketplace-file">
125 创建 marketplace 文件
126</h2>
127
128在你的存储库根目录中创建 `.claude-plugin/marketplace.json`。此文件定义你的 marketplace 的名称、所有者信息以及包含其源的 plugins 列表。
129
130每个 plugin 条目至少需要一个 `name` 和 `source`（告诉 Claude Code 从哪里获取它）。有关所有可用字段，请参阅下面的[完整架构](#marketplace-schema)。
131
132```json theme={null}
133{
134 "name": "company-tools",
135 "owner": {
136 "name": "DevTools Team",
137 "email": "devtools@example.com"
138 },
139 "plugins": [
140 {
141 "name": "code-formatter",
142 "source": "./plugins/formatter",
143 "description": "Automatic code formatting on save",
144 "version": "2.1.0",
145 "author": {
146 "name": "DevTools Team"
147 }
148 },
149 {
150 "name": "deployment-tools",
151 "source": {
152 "source": "github",
153 "repo": "company/deploy-plugin"
154 },
155 "description": "Deployment automation tools"
156 }
157 ]
158}
159```
160
161<h2 id="marketplace-schema">
162 Marketplace 架构
163</h2>
164
165<h3 id="required-fields">
166 必需字段
167</h3>
168
169| 字段 | 类型 | 描述 | 示例 |
170| :-------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- |
171| `name` | string | Marketplace 标识符，采用 kebab-case 格式，不包含空格、控制字符或双向格式化字符。这是面向公众的：用户在安装 plugins 时会看到它（例如，`/plugin install my-tool@your-marketplace`）。每个用户只能为每个名称注册一个 marketplace：添加第二个同名 marketplace 时，Claude Code 会替换第一个。要在一个 marketplace 名称下发布多个 plugins，请在[单个 `marketplace.json`](#create-the-marketplace-file) 中列出它们。 | `"acme-tools"` |
172| `owner` | object | Marketplace 维护者信息。见[所有者字段](#owner-fields) | |
173| `plugins` | array | 可用 plugins 列表 | 见[Plugin 条目](#plugin-entries) |
174
175<Note>
176 **保留名称**：以下 marketplace 名称为 Anthropic 官方使用保留，第三方 marketplaces 无法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins`、`claude-tag-plugins`、`healthcare`。冒充官方 marketplaces 的名称（如 `official-claude-plugins` 或 `anthropic-plugins-v2`）也被阻止。保留这些名称可防止第三方 marketplace 将自己呈现为 Anthropic 发布的来源。
177
178 Claude Code 每次加载 marketplace 时都会重新检查保留名称，而不仅仅是在添加时。在该名称成为保留名称之前以其中一个名称注册的 marketplace 停止加载，并报告它是[从不受信任的来源注册的](/docs/zh-CN/errors#marketplace-is-registered-from-an-untrusted-source)。移除该 marketplace 并从官方 Anthropic 来源重新添加它。受新保留名称影响的第三方 marketplace 在你以不同名称重新添加它后立即再次加载。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 不是保留的，已在保留名称下注册的 marketplace 继续加载。在 v2.1.265 之前，`claude-tag-plugins` 不是保留的。
179
180 你也不能将 marketplace 命名为 `npm`、`pip`、`uv`、`cargo`、`github` 或 `gh`，无论大小写如何。此检查需要 Claude Code v2.1.275 或更高版本。
181</Note>
182
183<h3 id="owner-fields">
184 所有者字段
185</h3>
186
187| 字段 | 类型 | 必需 | 描述 |
188| :------ | :----- | :- | :-------------------- |
189| `name` | string | 是 | 维护者或团队的名称 |
190| `email` | string | 否 | 维护者的联系电子邮件 |
191| `url` | string | 否 | 网站、GitHub 个人资料或组织 URL |
192
193<h3 id="optional-fields">
194 可选字段
195</h3>
196
197| 字段 | 类型 | 描述 |
198| :------------------------------------ | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
199| `$schema` | string | 用于编辑器自动完成和验证的 JSON Schema URL。Claude Code 在加载时忽略此字段。 |
200| `description` | string | 简短的 marketplace 描述 |
201| `version` | string | Marketplace 清单版本 |
202| `metadata.pluginRoot` | string | Claude Code 解析裸 plugin 源名称的目录。见[相对路径](#relative-paths)。需要 Claude Code v2.1.239 或更高版本。 |
203| `allowCrossMarketplaceDependenciesOn` | array | 此 marketplace 中的 plugins 可能依赖的其他 marketplaces。来自此处未列出的 marketplace 的依赖项在安装时被阻止。见[依赖来自另一个 marketplace 的 plugin](/docs/zh-CN/plugin-dependencies#depend-on-a-plugin-from-another-marketplace)。 |
204| `renames` | object | 从前一个 plugin `name` 到其当前名称的映射，或如果 plugin 被移除则映射到 `null`。当你重命名或移除 `plugins` 中的条目时，让现有用户自动迁移。见[重命名或移除 plugin](#rename-or-remove-a-plugin)。需要 Claude Code v2.1.193 或更高版本。 |
205
206`description` 和 `version` 也可以在 `metadata` 下接受，以实现向后兼容性。
207
208<h2 id="plugin-entries">
209 Plugin 条目
210</h2>
211
212`plugins` 数组中的每个 plugin 条目描述一个 plugin 及其位置。你可以包含 [plugin manifest 架构](/docs/zh-CN/plugins-reference#plugin-manifest-schema)中的任何字段，如 `description`、`version`、`author`、`commands` 和 `hooks`，加上这些 marketplace 特定的字段：`source`、`category`、`tags`、`strict`、`relevance`、`headers` 和 `headersHelper`。
213
214<h3 id="required-fields-2">
215 必需字段
216</h3>
217
218| 字段 | 类型 | 描述 |
219| :------- | :------------- | :------------------------------------------------------------------------------------------------------ |
220| `name` | string | Plugin 标识符（kebab-case，无空格、控制字符或双向格式化字符）。这是面向公众的：用户在安装时会看到它（例如，`/plugin install my-plugin@marketplace`）。 |
221| `source` | string\|object | 从哪里获取 plugin（见下面的 [Plugin 源](#plugin-sources)） |
222
223<h3 id="optional-plugin-fields">
224 可选 plugin 字段
225</h3>
226
227**标准元数据字段：**
228
229| 字段 | 类型 | 描述 |
230| :--------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
231| `displayName` | string | 在 UI 界面中显示的人类可读名称。当条目和 plugin 的 `plugin.json` 都未设置时，用户会看到 plugin 的 `name`。可以包含空格和任何大小写。不用于命名空间或查找。 |
232| `description` | string | 简短的 plugin 描述 |
233| `version` | string | Plugin 版本。如果设置（在此处或在 `plugin.json` 中），plugin 将固定到此字符串，用户仅在其更改时才会收到更新。具有 [`command` 源](#command-sources)的 plugin 不会被任一字段固定。也不会从 marketplace 添加为本地目录的 [就地加载](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)的 plugin。如果在两个地方都未设置，版本来自 [版本管理](/docs/zh-CN/plugins-reference#version-management)中的下一个源。 |
234| `author` | object | Plugin 作者信息（`name` 必需；`email` 和 `url` 可选） |
235| `homepage` | string | Plugin 主页或文档 URL |
236| `repository` | string | 源代码存储库 URL |
237| `license` | string | SPDX 许可证标识符（例如，MIT、Apache-2.0） |
238| `keywords` | array | 用于 plugin 发现和分类的标签 |
239| `metadata` | object | 自由格式对象，用于你自己的字段，如权利或目录数据。Claude Code 不读取它。在 v2.1.222 之前，`claude plugin validate` 将该键报告为无法识别的字段。 |
240| `category` | string | Plugin 类别以供组织 |
241| `tags` | array | 用于可搜索性的标签 |
242| `strict` | boolean | 控制 `plugin.json` 是否是组件定义的权威（默认：true）。见下面的 [Strict 模式](#strict-mode)。 |
243| `relevance` | object | 告诉 Claude Code 何时向用户建议此 plugin 的信号。仅对管理员在托管设置中允许列表的 marketplace 生效。见 [为你的组织推荐 plugin](/docs/zh-CN/plugin-relevance)。 |
244| `defaultEnabled` | boolean | Plugin 安装后是否启用（默认：true）。设置为 `false` 以安装禁用的 plugin，直到用户选择启用。优先于 plugin 的 `plugin.json` 中的同一字段。见 [默认启用](/docs/zh-CN/plugins-reference#default-enablement)。 |
245
246条目和 plugin 自己的 `plugin.json` 都可以设置显示字段 `displayName`、`description`、`author`、`homepage`、`repository`、`license` 和 `keywords`。在 plugin 列表和详情中，安装前后：
247
248* 对于你在条目上设置的字段，用户会看到条目的值，即使 `plugin.json` 设置了不同的值。
249* 对于条目未设置的字段，用户会看到 `plugin.json` 的值。
250
251安装前，Claude Code 只能为具有 [相对路径源](#relative-paths)的条目读取 `plugin.json`，其 plugin 文件位于 marketplace 内部。对于具有任何其他源类型的条目，用户在安装 plugin 之前只会看到条目自己的字段。
252
253**组件配置字段：**
254
255| 字段 | 类型 | 描述 |
256| :----------- | :------------- | :------------------------------------ |
257| `skills` | string\|array | 包含 `<name>/SKILL.md` 的 skill 目录的自定义路径 |
258| `commands` | string\|array | 平面 `.md` skill 文件或目录的自定义路径 |
259| `agents` | string\|array | agent 文件的自定义路径 |
260| `hooks` | string\|object | 自定义 hooks 配置或 hooks 文件的路径 |
261| `mcpServers` | string\|object | MCP server 配置或 MCP 配置的路径 |
262| `lspServers` | string\|object | LSP server 配置或 LSP 配置的路径 |
263
264**存档身份验证字段：**
265
266当条目在需要凭证的服务器上具有 [`archive` 源](#zip-archives)时设置这些字段。
267
268| 字段 | 类型 | 描述 |
269| :-------------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
270| `headers` | object | Claude Code 在下载此条目的存档时发送的 HTTP 标头。覆盖 marketplace 中相同名称的标头。需要 Claude Code v2.1.238 或更高版本。 |
271| `headersHelper` | string | 命令，将此条目的存档下载的 HTTP 标头打印为一个 JSON 对象，用于过期的凭证。见 [验证存档下载](#authenticate-archive-downloads)。条目还必须设置 [`"strict": false`](#strict-mode)。需要 Claude Code v2.1.238 或更高版本。 |
272
273<h2 id="plugin-sources">
274 Plugin 源
275</h2>
276
277Plugin 源告诉 Claude Code 在你的 marketplace 中列出的每个单独 plugin 从哪里获取。这些在 `marketplace.json` 中每个 plugin 条目的 `source` 字段中设置。
278
279Claude Code 将每个已安装的 plugin 复制到本地版本化 plugin 缓存中，位置为 `~/.claude/plugins/cache`，除非 plugin 就地加载。链接模式中的 [`command` 源](#copy-mode-and-link-mode)就地加载，[相对路径源](#relative-paths)从本地目录添加的 marketplace 也是如此。Claude Code 还会[将 plugin 的符合条件的 Node.js 包依赖项安装](/docs/zh-CN/plugins-reference#node-js-package-dependencies)到缓存副本中。见[Plugin 缓存和文件解析](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)了解从本地目录 marketplace 就地加载的 plugin 如何获取你的编辑。
280
281| 源 | 类型 | 字段 | 注释 |
282| ------------ | ---------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
283| 相对路径 | `string`（例如 `"./my-plugin"`） | 无 | marketplace repo 中的本地目录。必须以 `./` 开头，除非你在 [`metadata.pluginRoot`](#relative-paths) 下写一个裸名。Claude Code 相对于 marketplace 根目录解析路径，而不是 `.claude-plugin/` 目录 |
284| `github` | object | `repo`、`ref?`、`sha?` | |
285| `url` | object | `url`、`ref?`、`sha?` | Git URL 源 |
286| `git-subdir` | object | `url`、`path`、`ref?`、`sha?` | git repo 中的子目录。稀疏克隆以最小化大型 monorepos 的带宽 |
287| `npm` | object | `package`、`version?`、`registry?` | npm 包，通过你的 npm 客户端获取并解包，不运行安装脚本 |
288| `archive` | object | `url`、`sha256?` | 通过 HTTPS 下载的 Zip 存档。在用户机器上无需 git 或 npm 即可工作。需要 Claude Code v2.1.224 或更高版本 |
289| `command` | object | `command`、`timeout?`、`mode?` | 通过运行本地命令生成的 plugin 目录，每个会话重新运行一次以获取更改。需要 Claude Code v2.1.229 或更高版本 |
290
291<Note>
292 **Marketplace 源与 plugin 源**：这些是控制不同事物的不同概念。
293
294 * **Marketplace 源**：从哪里获取 `marketplace.json` 目录本身。在用户运行 `/plugin marketplace add` 或在 `extraKnownMarketplaces` 设置中设置。基于 Git 的 marketplace 源支持 `ref`（分支/标签）但不支持 `sha`。
295 * **Plugin 源**：从哪里获取 marketplace 中列出的单个 plugin。在 `marketplace.json` 内每个 plugin 条目的 `source` 字段中设置。基于 Git 的 plugin 源支持 `ref`（分支/标签）和 `sha`（精确提交）。
296
297 例如，托管在 `acme-corp/plugin-catalog` 的 marketplace（marketplace 源）可以列出从 `acme-corp/code-formatter` 获取的 plugin（plugin 源）。marketplace 源和 plugin 源指向不同的存储库，并独立固定。
298</Note>
299
300下面的基于 git 的源类型是 `github`、`url` 和 `git-subdir`。当在其中任何一个上同时设置 `ref` 和 `sha` 时，`sha` 是有效的固定。Claude Code 直接获取并检出固定的提交。
301
302在大多数 git 主机上，包括 GitHub、GitLab 和 Bitbucket，这意味着即使上游的 `ref` 命名的分支或标签已被删除，只要提交仍然可从存储库到达，安装也会成功。某些服务器（如 AWS CodeCommit）不支持通过 SHA 获取提交。在这些服务器上，`ref` 必须仍然存在，固定的提交必须可从其到达。
303
304如果你通过**组织设置 > Plugins** 分发 plugins，只允许某些源类型。见[通过组织设置分发](#distribute-through-organization-settings)。
305
306<h3 id="relative-paths">
307 相对路径
308</h3>
309
310对于同一存储库中的 plugins，使用以 `./` 开头的路径：
311
312```json theme={null}
313{
314 "name": "my-plugin",
315 "source": "./plugins/my-plugin"
316}
317```
318
319路径相对于 marketplace 根目录解析，即包含 `.claude-plugin/` 的目录。源 `./plugins/my-plugin` 因此指向 `<repo>/plugins/my-plugin`，即使 `marketplace.json` 位于 `<repo>/.claude-plugin/marketplace.json`。不要使用 `../` 来引用 marketplace 根目录外的路径。在 macOS 和 Linux 上，Claude Code 拒绝在前导 `./` 之后任何地方包含反斜杠的条目路径，所以在每个平台上将分隔符写为 `/`。
320
321裸名是没有 `/` 的单个目录名，例如 `"formatter"`。要写裸名而不是 `./` 路径，请设置 [`metadata.pluginRoot`](#optional-fields) 为它们解析的目录。使用 `"pluginRoot": "./plugins"`，Claude Code 将 `"source": "formatter"` 解析为 `./plugins/formatter`。需要 Claude Code v2.1.239 或更高版本。
322
323`metadata.pluginRoot` 本身必须是 marketplace 内的相对路径。Claude Code 对已经以 `./` 开头的源忽略它。包含 `/` 的源，例如 `team-a/formatter`，不是裸名，即使设置了 `metadata.pluginRoot`，仍然需要 `./` 前缀。
324
325<Note>
326 Claude Code 相对于 marketplace 的本地副本解析相对路径，所以当用户从 git 源或本地目录添加你的 marketplace 时它们有效。如果用户通过直接 URL 添加你的 marketplace 到 `marketplace.json` 文件，相对路径将无法解析，因为 Claude Code 仅下载该文件。对于基于 URL 的分发，请改用任何其他[plugin 源](#plugin-sources)。见[故障排除](#plugins-with-relative-paths-fail-in-url-based-marketplaces)了解详情。
327</Note>
328
329<h3 id="github-repositories">
330 GitHub 存储库
331</h3>
332
333```json theme={null}
334{
335 "name": "github-plugin",
336 "source": {
337 "source": "github",
338 "repo": "owner/plugin-repo"
339 }
340}
341```
342
343你可以固定到特定的分支、标签或提交：
344
345```json theme={null}
346{
347 "name": "github-plugin",
348 "source": {
349 "source": "github",
350 "repo": "owner/plugin-repo",
351 "ref": "v2.0.0",
352 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
353 }
354}
355```
356
357| 字段 | 类型 | 描述 |
358| :----- | :----- | :------------------------------- |
359| `repo` | string | 必需。`owner/repo` 格式的 GitHub 存储库 |
360| `ref` | string | 可选。Git 分支或标签（默认为存储库默认分支） |
361| `sha` | string | 可选。完整的 40 字符 git 提交 SHA 以固定到精确版本 |
362
363<h3 id="git-repositories">
364 Git 存储库
365</h3>
366
367```json theme={null}
368{
369 "name": "git-plugin",
370 "source": {
371 "source": "url",
372 "url": "https://gitlab.com/team/plugin.git"
373 }
374}
375```
376
377你可以固定到特定的分支、标签或提交：
378
379```json theme={null}
380{
381 "name": "git-plugin",
382 "source": {
383 "source": "url",
384 "url": "https://gitlab.com/team/plugin.git",
385 "ref": "main",
386 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
387 }
388}
389```
390
391| 字段 | 类型 | 描述 |
392| :---- | :----- | :--------------------------------------------------------------------------------------------------- |
393| `url` | string | 必需。完整的 git 存储库 URL（`https://` 或 `git@`）。`.git` 后缀是可选的，所以 Azure DevOps 和 AWS CodeCommit URL 不带后缀也可以工作 |
394| `ref` | string | 可选。Git 分支或标签（默认为存储库默认分支） |
395| `sha` | string | 可选。完整的 40 字符 git 提交 SHA 以固定到精确版本 |
396
397<h3 id="git-subdirectories">
398 Git 子目录
399</h3>
400
401使用 `git-subdir` 指向位于 git 存储库子目录中的 plugin。Claude Code 使用稀疏的部分克隆来仅获取子目录，最小化大型 monorepos 的带宽。
402
403```json theme={null}
404{
405 "name": "my-plugin",
406 "source": {
407 "source": "git-subdir",
408 "url": "https://github.com/acme-corp/monorepo.git",
409 "path": "tools/claude-plugin"
410 }
411}
412```
413
414你可以固定到特定的分支、标签或提交：
415
416```json theme={null}
417{
418 "name": "my-plugin",
419 "source": {
420 "source": "git-subdir",
421 "url": "https://github.com/acme-corp/monorepo.git",
422 "path": "tools/claude-plugin",
423 "ref": "v2.0.0",
424 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
425 }
426}
427```
428
429`url` 字段也接受 GitHub 简写（`owner/repo`）或 SSH URL（`git@github.com:owner/repo.git`）。
430
431| 字段 | 类型 | 描述 |
432| :----- | :----- | :---------------------------------------------------- |
433| `url` | string | 必需。Git 存储库 URL、GitHub `owner/repo` 简写或 SSH URL |
434| `path` | string | 必需。repo 中包含 plugin 的子目录路径（例如，`"tools/claude-plugin"`） |
435| `ref` | string | 可选。Git 分支或标签（默认为存储库默认分支） |
436| `sha` | string | 可选。完整的 40 字符 git 提交 SHA 以固定到精确版本 |
437
438<h3 id="npm-packages">
439 npm 包
440</h3>
441
442npm 源可以命名公共 npm registry 上的任何包或你的团队托管的私有 registry 上的任何包。Claude Code 使用你的 npm 客户端解析包，下载 tarball，并将其解包到 plugin 缓存中。
443
444包的安装脚本（例如 `preinstall` 或 `postinstall`）永远不会运行，其依赖项在获取期间不会被安装。
445
446如果包在其 `package.json` 旁边附带支持的 lockfile，Claude Code 会在单独的步骤中安装那些[Node.js 包依赖项](/docs/zh-CN/plugins-reference#node-js-package-dependencies)，也禁用脚本。否则，发布已构建所需一切的 plugin。需要其他包的 MCP 服务器可以通过 `npx` 启动，它在首次运行时安装它们。
447
448```json theme={null}
449{
450 "name": "my-npm-plugin",
451 "source": {
452 "source": "npm",
453 "package": "@acme/claude-plugin"
454 }
455}
456```
457
458要固定到特定版本，请添加 `version` 字段：
459
460```json theme={null}
461{
462 "name": "my-npm-plugin",
463 "source": {
464 "source": "npm",
465 "package": "@acme/claude-plugin",
466 "version": "2.1.0"
467 }
468}
469```
470
471要从私有或内部 registry 安装，请添加 `registry` 字段：
472
473```json theme={null}
474{
475 "name": "my-npm-plugin",
476 "source": {
477 "source": "npm",
478 "package": "@acme/claude-plugin",
479 "version": "^2.0.0",
480 "registry": "https://npm.example.com"
481 }
482}
483```
484
485| 字段 | 类型 | 描述 |
486| :--------- | :----- | :-------------------------------------------------------- |
487| `package` | string | 必需。包名称或作用域包（例如，`@org/plugin`） |
488| `version` | string | 可选。版本或版本范围（例如，`2.1.0`、`^2.0.0`、`~1.5.0`） |
489| `registry` | string | 可选。自定义 npm registry URL。默认为系统 npm registry（通常为 npmjs.org） |
490
491<h3 id="zip-archives">
492 Zip 存档
493</h3>
494
495使用 `archive` 将 plugin 分发为 Claude Code 通过 HTTPS 下载的 zip 文件，这样安装在用户机器上无需 git 或 npm 即可工作。在任何静态文件服务器或工件存储库上托管文件，例如 S3 bucket、Artifactory 通用存储库或 nginx。需要 Claude Code v2.1.224 或更高版本。在 v2.1.120 到 v2.1.223 版本上，安装 plugin 失败并显示 `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`；在更早的版本上，包含 `archive` 条目的 marketplace 完全无法加载。
496
497此条目从工件服务器上的 zip 文件安装 plugin：
498
499```json theme={null}
500{
501 "name": "my-plugin",
502 "source": {
503 "source": "archive",
504 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
505 }
506}
507```
508
509构建 zip 时，你可以直接 zip plugin 的内容或 zip plugin 文件夹本身。Claude Code 在存档的顶部查找 `.claude-plugin/`，然后在单个顶级文件夹内查找，所以两种布局都可以安装：
510
511```text theme={null}
512my-plugin.zip my-plugin.zip
513├── .claude-plugin/ └── my-plugin/
514│ └── plugin.json ├── .claude-plugin/
515└── commands/ │ └── plugin.json
516 └── commands/
517```
518
519Claude Code 不会查找超过一个文件夹的深度，所以嵌套更深的 plugin 无法安装。Claude Code 拒绝大于 256 MiB 的存档。
520
521要固定精确文件，请添加 `sha256` 字段，其中包含存档的摘要：
522
523```json theme={null}
524{
525 "name": "my-plugin",
526 "source": {
527 "source": "archive",
528 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
529 "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
530 }
531}
532```
533
534如果下载的文件与固定不匹配，Claude Code 拒绝安装并报告 [`Plugin archive integrity check failed`](/docs/zh-CN/errors#plugin-archive-integrity-check-failed)。
535
536存档源接受这些字段：
537
538| 字段 | 类型 | 描述 |
539| :------- | :----- | :------------------------------------------------------------------------------------------------------ |
540| `url` | string | 必需。zip 存档的 HTTPS URL。Claude Code 拒绝 `http://` URL，以及环回、链接本地和云元数据主机。每个重定向跳转必须满足相同的规则，否则 Claude Code 拒绝下载 |
541| `sha256` | string | 可选。存档的 SHA-256 摘要，为 64 个十六进制字符，大写或小写。Claude Code 验证每次下载并在不匹配时拒绝安装 |
542
543`sha256` 摘要也用作 plugin 的版本，当 `plugin.json` 和 marketplace 条目都未声明版本时。见[版本管理](/docs/zh-CN/plugins-reference#version-management)。如果你声明 `version`，该版本字符串是更新信号，所以在更改 zip 及其摘要后，也要提升版本，否则用户保留缓存副本。
544
545<h4 id="authenticate-archive-downloads">
546 验证存档下载
547</h4>
548
549要验证存档下载，例如从私有 registry 下载，请设置 Claude Code 随之发送的 HTTP 标头。在你注册 marketplace 的 `url` 源上设置 `headers`，例如 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 条目。在 Claude Code v2.1.238 或更高版本上，你可以在 plugin 的条目上设置它，在 `source` 旁边。
550
551如果你要放在 `headers` 中的值是短期的，例如你的 registry 按需生成的令牌，请在同一位置设置 `headersHelper` 命令。Claude Code 运行命令并将其打印的 JSON 对象作为该位置的标头发送。需要 Claude Code v2.1.238 或更高版本。
552
553你选择的位置决定了哪些下载获得标头以及 Claude Code 何时运行命令：
554
555| 位置 | 获得标头的下载 | Claude Code 何时运行设置在那里的 `headersHelper` |
556| :------------------ | :---------------------------------------- | :------------------------------------------------------------------------------------ |
557| Marketplace `url` 源 | 在 marketplace URL 的源上的存档下载，意味着相同的方案、主机和端口 | 在每次获取 marketplace 的 `marketplace.json` 之前和在该源上的每次存档下载之前。Claude Code 将一次运行的输出重用最多 60 秒 |
558| Plugin 条目 | 仅该条目的下载 | 仅当用户自己安装或更新该单个 plugin 时，并[接受命令](#how-users-accept-a-headershelper-command) |
559
560当两个位置都设置相同名称的标头时，Claude Code 发送条目的值。在一个位置内，命令打印的标头覆盖相同名称的列出的标头。
561
562<h5 id="add-a-headershelper-to-a-plugin-entry">
563 向 plugin 条目添加 headersHelper
564</h5>
565
566此条目在 `source` 旁边设置 `headersHelper`。它还设置 `"strict": false`，这是 Claude Code 对设置 `headersHelper` 的 `marketplace.json` 条目所需的。使用 [`"strict": false`](#strict-mode)，marketplace 条目是 plugin 的完整定义，所以用户可以在接受命令之前查看 plugin 包含的内容：
567
568```json theme={null}
569{
570 "name": "my-plugin",
571 "description": "Formatting commands for internal services",
572 "strict": false,
573 "commands": "./commands",
574 "source": {
575 "source": "archive",
576 "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
577 },
578 "headersHelper": "/opt/bin/mint-registry-token.sh"
579}
580```
581
582要检查条目，运行 `claude plugin install my-plugin@your-marketplace`。Claude Code 显示你命令和存档 URL，并在你接受后下载 zip。
583
584在 v2.1.238 之前，Claude Code 下载条目的存档时不带其 `headers` 或 `headersHelper`，所以依赖它们的安装失败并显示 `HTTP 401 while downloading plugin archive from`，后跟 URL，registry 的状态代码代替 401。
585
586<h4 id="write-the-headershelper-command">
587 编写 headersHelper 命令
588</h4>
589
590无论你在 marketplace 的 `url` 源还是在 plugin 条目上设置 `headersHelper`，编写命令以满足这些要求：
591
592* **命令文本**：最多 500 个可打印 ASCII 字符，没有四个或更多空格的运行。
593* **输出**：在 stdout 上打印一个标头名称和字符串值的 JSON 对象，然后在 10 秒内以 0 退出。
594* **Shell 和工作目录**：Claude Code 通过 `sh` 运行命令，或在 Windows 上通过 `cmd.exe`，从配置目录 `~/.claude` 或 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars#variables)。给出绝对路径或 `PATH` 上的命令，因为相对路径相对于该目录解析，而不是用户的项目。
595* **Claude Code 移除的变量**：从 `marketplace.json` 条目或项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中设置的命令的环境中，Claude Code 移除每个名称包含 `TOKEN`、`SECRET`、`KEY` 或 `AUTH` 等词的变量，包括 `ANTHROPIC_API_KEY`。Claude Code 不对用户设置、`--settings` 文件或托管设置中设置的命令应用此移除。
596* **Claude Code 设置的变量**：`CLAUDE_CODE_MARKETPLACE_URL` 和 `CLAUDE_CODE_MARKETPLACE_NAME` 用于 `url` 源的命令，以及 `CLAUDE_CODE_PLUGIN_NAME` 和 `CLAUDE_CODE_PLUGIN_ARCHIVE_URL` 用于条目的命令。`CLAUDE_CODE_MARKETPLACE_NAME` 在用户通过 URL 添加 marketplace 后的第一次获取时未设置，因为该获取是提供名称的。
597
598生成持有者令牌的命令打印如下对象：
599
600```json theme={null}
601{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}
602```
603
604<h4 id="when-claude-code-skips-a-headershelper-command-or-drops-its-output">
605 Claude Code 何时跳过 headersHelper 命令或丢弃其输出
606</h4>
607
608Claude Code 不运行 `headersHelper` 命令，或在这些情况下丢弃来自 `headers` 或命令输出的标头：
609
610* **命令失败**：如果命令以非零退出、运行超过 10 秒或打印除 JSON 字符串值对象之外的任何内容，Claude Code 不进行它运行命令的获取或下载。
611* **Marketplace URL 不以 `https://` 开头**：Claude Code 不运行该 `url` 源的命令，仅发送其 `headers` 字段中列出的标头。
612* **重定向离开源**：当下载被重定向离开存档 URL 的源时，Claude Code 丢弃 marketplace `url` 源和 plugin 条目的 `headers` 值和命令输出。
613* **条目设置路由或身份标头**：Claude Code 从条目的 `headers` 和命令输出中丢弃请求路由和客户端身份名称，例如 `Host`、`Cookie` 和 `X-Forwarded-*`，并保留身份验证名称，例如 `Authorization`。Claude Code 以这种方式过滤每个 `marketplace.json` 条目，以及[内联设置条目](/docs/zh-CN/settings-reference#extraknownmarketplaces)取决于哪个文件声明它。
614* **命令在 `--add-dir` 目录的设置中设置**：Claude Code 忽略它，在 `url` 源和[内联 plugin 条目](/docs/zh-CN/settings-reference#extraknownmarketplaces)上都一样，仅发送该文件的 `headers`。
615* **托管设置阻止命令**：将 [`disableCommandPluginSources`](/docs/zh-CN/settings-reference#disablecommandpluginsources) 设置为 `true` 阻止 `headersHelper` 命令，[`allowManagedHooksOnly`](/docs/zh-CN/settings-reference#allowmanagedhooksonly) 也阻止它们，除非 `disableCommandPluginSources` 明确为 `false`。在任一阻止下，Claude Code 仍然为托管设置本身声明的 marketplace 运行命令。
616
617<h4 id="how-users-accept-a-headershelper-command">
618 用户如何接受 headersHelper 命令
619</h4>
620
621用户每次从 plugin 的自己的视图在 `/plugin` 或使用 `claude plugin install` 或 `claude plugin update` 自己安装或更新该单个 plugin 时接受 plugin 条目的命令。Claude Code 显示命令和存档 URL，并仅在用户接受后运行命令。
622
623在非交互式 shell 中，传递 [`--yes`](/docs/zh-CN/plugins-reference#plugin-install) 以接受命令。要接受仅前一个 `--json` 运行显示的命令，传递 [`--accept-command`](/docs/zh-CN/plugins-reference#plugin-install) 和运行报告的 `sha256`。
624
625Claude Code 仅运行它显示的命令，用于它显示的存档 URL。如果条目的命令或存档 URL 在此期间更改，Claude Code 拒绝安装或更新。仅查询字符串中的更改不计算。
626
627<h5 id="installs-and-updates-that-refuse-the-command-instead-of-asking">
628 拒绝命令而不是询问的安装和更新
629</h5>
630
631在任何其他操作上，而不是单个 plugin 安装或更新，Claude Code 既不运行条目的命令也不下载其存档，所以 plugin 保持其已安装版本或保持未安装。用户看到的取决于操作：
632
633* **一次安装多个 plugins、从 plugin 建议或作为另一个 plugin 的依赖项**：Claude Code 拒绝具有命令的 plugin 并将用户指向该 plugin 在 `/plugin` 中的自己的视图。批量安装中的其他 plugins 仍然安装。依赖被拒绝 plugin 的 plugin 无法安装，直到用户自己安装被拒绝的 plugin。
634* **后台自动更新，或会话启动用于从未下载其存档的 plugin**：Claude Code 在 `/plugin` 错误选项卡中列出 plugin，以便用户知道手动安装或更新它。找到条目的自动更新仍然宣传已安装版本列表无。
635
636<h5 id="when-a-marketplace-url-source’s-command-runs">
637 Marketplace `url` 源的命令何时运行
638</h5>
639
640Marketplace `url` 源的 `headersHelper` 在设置文件中声明，例如 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 条目，而不是在 marketplace 发布的目录中，所以 Claude Code 不会在每次安装或更新时要求用户接受它。声明它的设置文件决定了 Claude Code 何时运行它：
641
642| 设置文件 | Claude Code 何时运行命令 |
643| :---------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
644| 用户设置、`--settings` 文件或机器上的托管设置文件 | 无需询问，包括在后台 marketplace 刷新期间 |
645| 项目的 `.claude/settings.json` 或 `.claude/settings.local.json` | 仅在用户接受该文件夹本身的[工作区信任对话框](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)后。`-p` 或 SDK 会话不计为接受它，父文件夹的信任也不计 |
646| 服务器托管设置 | 仅在用户在[安全批准对话框](/docs/zh-CN/server-managed-settings#security-approval-dialogs)中批准交付的设置后 |
647
648在 `-p` 或 SDK 会话中，Claude Code 无法显示安全批准对话框。它应用其他交付的设置，但 marketplace 获取和任何需要命令的存档下载失败，直到用户在交互式会话中批准。
649
650对于这些文件之一中的[内联 plugin 条目](/docs/zh-CN/settings-reference#extraknownmarketplaces)，Claude Code 要求与该文件中 marketplace 级别命令相同的文件夹信任或设置批准，用户也在每次安装或更新时接受条目的命令。
651
652<h3 id="command-sources">
653 Command 源
654</h3>
655
656当本地安装的工具生成 plugin 目录时使用 `command`，例如为当前选定的工具链呈现其 plugin 的 IDE。Claude Code 在用户安装 plugin 时运行命令，并在后台每个会话重新运行一次，所以你的用户无需重新安装即可获取工具的更改输出。需要 Claude Code v2.1.229 或更高版本。在 v2.1.120 到 v2.1.228 上，安装 plugin 失败并显示 `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`，在更早的版本上整个 marketplace 无法加载。
657
658此条目从工具打印的任何目录安装 plugin：
659
660```json theme={null}
661{
662 "name": "my-plugin",
663 "source": {
664 "source": "command",
665 "command": "my-tool claude-plugin-path"
666 }
667}
668```
669
670Claude Code 通过平台 shell 运行命令，macOS 和 Linux 上的 `sh` 或 Windows 上的 `cmd.exe`，从用户的主目录。命令必须在 stdout 上打印恰好一行并以代码 0 退出。该行是包含完整 plugin 的目录的绝对路径，在命令退出时，路径可能在运行之间更改。
671
672Claude Code 停止运行超过 `timeout` 秒的命令，安装或更新失败。Claude Code 也在这些情况下拒绝打印的路径，安装或更新以相同方式失败：
673
674* 目录在其顶级没有 plugin 内容，例如 `.claude-plugin/` 目录或 `skills/`、`commands/`、`agents/` 或 `hooks/` 目录
675* 目录是 Claude Code 启动的目录，或其父目录之一
676* 在 Windows 上，路径是 UNC 路径
677
678Command 源接受这些字段：
679
680| 字段 | 类型 | 描述 |
681| :-------- | :----- | :---------------------------------------------------------------------------------------------------------- |
682| `command` | string | 必需。Shell 命令，在 stdout 上打印 plugin 目录的绝对路径作为单行并以 0 退出。必须是可打印 ASCII，最多 500 字符，没有四个或更多空格的运行，所以用户可以查看他们被要求接受的整个命令 |
683| `timeout` | number | 可选。等待命令的整数秒数，然后放弃（默认：60，最大：600） |
684| `mode` | string | 可选。`"copy"`（默认）将打印的目录复制到 plugin 缓存中。`"link"` 就地使用打印的目录。见[复制模式和链接模式](#copy-mode-and-link-mode) |
685
686<h4 id="copy-mode-and-link-mode">
687 复制模式和链接模式
688</h4>
689
690使用默认的 `"mode": "copy"`，Claude Code 将打印的目录复制到版本化 plugin 缓存中，并从目录内容的哈希派生[plugin 版本](/docs/zh-CN/plugins-reference#version-management)。你的工具可以在命令退出后删除或重写目录，产生相同内容的重新运行计为最新。Claude Code 拒绝安装大于 256 MiB 或包含超过 20,000 个条目的目录。
691
692为大型 plugin 目录设置 `"mode": "link"`，不应复制，例如呈现的 SDK 导出。Claude Code 用打印目录的每个顶级条目的链接填充 plugin 的缓存条目，并就地使用文件，所以没有复制、文件内容未哈希，大小限制不适用。如果顶级条目是指向打印目录外的符号链接，安装失败。Claude Code 也跳过链接模式 plugin 的[Node.js 包依赖项安装](/docs/zh-CN/plugins-reference#node-js-package-dependencies)，所以打印已包含 plugin 需要的任何 `node_modules` 的目录。
693
694保持打印的目录就位，只要 plugin 保持安装，因为 Claude Code 在每次启动时通过这些链接加载 plugin。Claude Code 从打印目录的真实路径及其顶级条目派生[plugin 版本](/docs/zh-CN/plugins-reference#version-management)，而不是文件内部，所以打印不同的路径以表示新内容。在打印目录中或其下方启动的会话中，Claude Code 根本不加载 plugin。
695
696Claude Code 不支持 Windows 上的链接模式，拒绝在那里安装链接模式 plugin。改为声明 `"mode": "copy"`。
697
698<h4 id="how-users-accept-the-command">
699 用户如何接受命令
700</h4>
701
702Claude Code 在用户的机器上运行你的命令，所以它将每次运行绑定到用户的明确接受：
703
704* 当用户从 `/plugin` 中的 plugin 详情屏幕安装 plugin，或在交互式终端中使用 `claude plugin install` 或 `claude plugin update` 安装或更新它时，Claude Code 首先向他们显示确切的命令字符串，并为该安装记录接受的命令。可以在接受相同命令的记录接受上进行的 `claude plugin update` 显示无。在非交互式 shell 中，例如配置脚本，传递 `--yes` 到 `claude plugin install` 或 `claude plugin update` 以接受它打印的命令。要接受仅前一个 `--json` 运行显示的命令，传递 [`--accept-command`](/docs/zh-CN/plugins-reference#plugin-install) 和运行报告的 `sha256`。
705* 每条其他路径仅运行用户已接受的命令。这包括从 `/plugin` 启动的更新和[何时 Claude Code 重新运行命令](#when-claude-code-re-runs-the-command)中描述的后台运行。当未接受任何内容时，Claude Code 拒绝运行命令并告诉用户如何查看它。Claude Code 从不将 command 源 plugin 安装为另一个 plugin 的依赖项，所以用户自己先安装它。
706* 如果你更改条目的 `command` 或切换其 `mode`，用户保留他们已有的版本，Claude Code 停止重新运行命令。在交互式会话中，`/plugin` 错误选项卡显示新命令，直到用户通过运行 `claude plugin update <plugin>@<marketplace>` 查看并接受它。
707
708管理员可以使用托管设置 [`disableCommandPluginSources`](/docs/zh-CN/settings-reference#disablecommandpluginsources) 在整个组织中阻止 command 源。如果组织设置 [`allowManagedHooksOnly`](/docs/zh-CN/settings-reference#allowmanagedhooksonly)，Claude Code 默认阻止 command 源。
709
710<h4 id="when-claude-code-re-runs-the-command">
711 Claude Code 何时重新运行命令
712</h4>
713
714打印的目录反映工具在命令运行时的状态，所以 Claude Code 在这些时间重新运行命令：
715
716* 每次用户安装或更新 plugin 时
717* 每个会话一次用于每个启用的 command 源 plugin，在后台，会话启动后不久。此运行不通过 marketplace 自动更新，所以它不依赖 marketplace 的[自动更新设置](/docs/zh-CN/discover-plugins#configure-auto-updates)
718* 在启动或 `/reload-plugins` 时，当启用的 plugin 的已安装版本从 plugin 缓存中丢失时
719
720当用户设置 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars) 时，Claude Code 跳过两个后台运行。显式安装和更新仍然使用该变量集运行命令。
721
722当命令的哈希输出已更改时，Claude Code 将结果安装为新版本并在运行的交互式会话中重新加载它，切换[`/reload-plugins` 切换的相同组件](/docs/zh-CN/plugins-reference#environment-variables)。用户看到 plugin 已重新加载的通知。如果就地重新加载会使会话的提示缓存失效，Claude Code 改为提示用户运行 `/reload-plugins`，它[警告缓存成本并在使用 `--force` 重新运行时应用](/docs/zh-CN/prompt-caching#enabling-or-disabling-a-plugin)。
723
724<h3 id="advanced-plugin-entries">
725 高级 plugin 条目
726</h3>
727
728此示例显示了使用许多可选字段的 plugin 条目，包括命令、agents、hooks 和 MCP servers 的自定义路径：
729
730```json theme={null}
731{
732 "name": "enterprise-tools",
733 "source": {
734 "source": "github",
735 "repo": "company/enterprise-plugin"
736 },
737 "description": "Enterprise workflow automation tools",
738 "version": "2.1.0",
739 "author": {
740 "name": "Enterprise Team",
741 "email": "enterprise@example.com"
742 },
743 "homepage": "https://docs.example.com/plugins/enterprise-tools",
744 "repository": "https://github.com/company/enterprise-plugin",
745 "license": "MIT",
746 "keywords": ["enterprise", "workflow", "automation"],
747 "category": "productivity",
748 "commands": [
749 "./commands/core/",
750 "./commands/enterprise/",
751 "./commands/experimental/preview.md"
752 ],
753 "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
754 "hooks": {
755 "PostToolUse": [
756 {
757 "matcher": "Write|Edit",
758 "hooks": [
759 {
760 "type": "command",
761 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
762 }
763 ]
764 }
765 ]
766 },
767 "mcpServers": {
768 "enterprise-db": {
769 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
770 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
771 }
772 },
773 "strict": false
774}
775```
776
777需要注意的关键事项：
778
779* **`commands` 和 `agents`**：你可以指定多个目录或单个文件。路径相对于 plugin 根目录，必须保持在其内部。
780 * Claude Code 拒绝解析到 plugin 目录外的路径，例如 `./../shared.md`，带有 [`path escapes plugin directory`](/docs/zh-CN/errors#path-escapes-plugin-directory) 错误，仍然加载 plugin 而不带该组件
781* **`${CLAUDE_PLUGIN_ROOT}`**：在 hook 命令和 MCP server 配置中使用此变量来引用 plugin 安装目录中的文件。
782 * 查看[替换表](/docs/zh-CN/plugins-reference#environment-variables)了解每个服务器类型在哪些配置字段中替换它
783 * 对于应该在 plugin 更新后保留的依赖项或状态，请改用 [`${CLAUDE_PLUGIN_DATA}`](/docs/zh-CN/plugins-reference#persistent-data-directory)
784* **`strict: false`**：由于这设置为 false，plugin 不需要自己的 `plugin.json`。marketplace 条目定义了一切。见下面的 [Strict 模式](#strict-mode)。
785
786默认情况下，plugin 的 skills 从其 `source` 下的 `skills/` 目录加载。`skills` 字段中列出的路径添加到该扫描中：
787
788```json theme={null}
789"skills": ["./skills/", "./extra-skills/"]
790```
791
792当多个 plugin 条目在 marketplace 根目录（`source: "./"`）共享一个 `skills/` 文件夹时，改为列出特定子目录，以便每个条目仅加载自己的 skills：
793
794```json theme={null}
795"source": "./",
796"skills": ["./skills/code-review", "./skills/docs"]
797```
798
799使用 marketplace 根源，列出的路径是该条目的完整集合，共享 `skills/` 文件夹中的其他目录不会加载。列出 `./skills/` 本身或 plugin 根目录会保持完整扫描。如果列出的路径都不存在，则改为运行默认扫描。
800
801<h3 id="strict-mode">
802 Strict 模式
803</h3>
804
805`strict` 字段控制 `plugin.json` 是否是组件定义（skills、agents、hooks、MCP servers、输出样式）的权威。
806
807| 值 | 行为 |
808| :--------- | :---------------------------------------------------------------------- |
809| `true`（默认） | `plugin.json` 是权威。marketplace 条目可以用额外的组件补充它，两个源都被合并。 |
810| `false` | marketplace 条目是完整的定义。如果 plugin 也有声明组件的 `plugin.json`，那就是冲突，plugin 无法加载。 |
811
812**何时使用每种模式：**
813
814* **`strict: true`**：plugin 有自己的 `plugin.json` 并管理自己的组件。marketplace 条目可以在顶部添加额外的 skills 或 hooks。这是默认值，适用于大多数 plugins。
815* **`strict: false`**：marketplace 操作员想要完全控制。plugin repo 提供原始文件，marketplace 条目定义这些文件中的哪些被公开为 skills、agents、hooks 等。当 marketplace 以不同于 plugin 作者意图的方式重组或策划 plugin 的组件时很有用。
816
817<h2 id="host-and-distribute-marketplaces">
818 托管和分发 marketplaces
819</h2>
820
821当用户添加托管在 git 存储库中的 marketplace，或安装其列出的基于 git 的 plugin 时，Claude Code 会将该 marketplace 或 plugin 存储库克隆到他们的机器上。克隆永远不会下载 [Git LFS](https://git-lfs.com) 内容，所以 LFS 跟踪的文件作为指针文件到达。将你的 plugins 需要的文件保留在 LFS 之外。
822
823<h3 id="host-on-github-recommended">
824 在 GitHub 上托管（推荐）
825</h3>
826
827GitHub 是托管和分发 marketplace 的推荐方式：
828
8291. **创建存储库**：为你的 marketplace 设置一个新存储库
8302. **添加 marketplace 文件**：使用你的 plugin 定义创建 `.claude-plugin/marketplace.json`
8313. **与团队共享**：用户使用 `/plugin marketplace add owner/repo` 添加你的 marketplace
832
833**优点**：内置版本控制、问题跟踪和团队协作功能。
834
835<h3 id="host-on-other-git-services">
836 在其他 git 服务上托管
837</h3>
838
839任何 git 托管服务都可以工作，例如 GitLab、Bitbucket 和自托管服务器。用户使用完整的存储库 URL 添加：
840
841```shell theme={null}
842/plugin marketplace add https://gitlab.com/company/plugins.git
843```
844
845<h3 id="private-repositories">
846 私有存储库
847</h3>
848
849Claude Code 支持从私有存储库安装 plugins。如果你通过[**组织设置 > Plugins**](https://claude.ai/admin-settings/plugins)分发你的 marketplace，你的 git 凭证不涉及：组织同步通过你的组织的 GitHub 或 GitLab 连接在 claude.ai 上读取 marketplace 存储库。有关哪些 plugin 源可以是私有的，请参阅[通过组织设置分发](#distribute-through-organization-settings)。
850
851<h4 id="commands-you-run">
852 你运行的命令
853</h4>
854
855当你运行 `/plugin marketplace add`、`/plugin install`、`/plugin update` 或 `/plugin marketplace update` 时，Claude Code 使用你现有的 git 凭证助手，所以通过 `gh auth login`、macOS Keychain 或 `git-credential-store` 的 HTTPS 访问工作方式与你的终端中相同。SSH 访问工作，只要主机已经在你的 `known_hosts` 文件中，并且密钥已加载到 `ssh-agent` 中，因为 Claude Code 会抑制主机指纹和密钥密码的交互式 SSH 提示。GitHub `owner/repo` 简写源默认通过 SSH 克隆；设置 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-CN/env-vars#variables) 以改为通过 HTTPS 克隆它们。
856
857<h4 id="background-auto-updates">
858 后台自动更新
859</h4>
860
861后台刷新会使用你配置的 git 凭证助手检查 marketplace 的远程以查找新提交，与你运行的命令相同。对于 SSH 远程，加载到 `ssh-agent` 中的密钥对检查进行身份验证。Claude Code 以非交互方式运行检查：它关闭 git 的终端提示和 askpass 程序，并告诉凭证助手不要提示。检查是否可以通过 HTTPS 对私有存储库进行身份验证取决于你的助手：
862
863* 可以在不提示的情况下提供存储凭证的助手对检查进行身份验证。Git Credential Manager、macOS Keychain 助手和 `git-credential-store` 一旦为主机保存凭证就以这种方式工作。
864* 需要提示你的助手无法在后台回答。更新会静默失败，现有检出保持就位，所以你的 plugins 继续从最后同步的状态工作。运行 `/plugin marketplace update <name>` 以使用你的凭证刷新 marketplace。
865
866当检查发现检出是最新的时，Claude Code 会保持原样。当检查发现新提交，或因为无法到达或对远程进行身份验证而失败时，Claude Code 会再次克隆 marketplace 并交换新克隆。如果该克隆失败，现有检出保持就位。重新克隆可能在大型存储库上[超时](#git-operations-time-out)。
867
868两个设置使私有 marketplaces 的行为可预测：
869
870* 设置 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在后台检查无法到达或对远程进行身份验证时保留现有检出，而不尝试重新克隆。你的 plugins 继续从最后同步的状态工作，使用 `/plugin marketplace update` 的手动更新仍然使用你的凭证进行身份验证。
871* 配置 git 凭证助手，例如使用 `gh auth setup-git` 用于 GitHub，以便后台检查和重新克隆可以在不提示的情况下进行身份验证。
872
873在你的环境中设置提供商令牌（如 `GITHUB_TOKEN`）本身不会启用后台身份验证。令牌仅通过配置的凭证助手（例如 `gh` CLI 的助手，它读取 `GH_TOKEN` 和 `GITHUB_TOKEN`）生效。
874
875<Note>
876 在 CI/CD 环境中，在从私有存储库安装 plugins 之前配置 git 凭证助手。在 GitHub Actions 上，导出对 marketplace 存储库具有读取访问权限的令牌作为 `GH_TOKEN`，然后运行 `gh auth setup-git`。默认工作流令牌只能访问工作流自己的存储库，所以另一个存储库中的私有 marketplace 需要个人访问令牌或应用令牌。
877</Note>
878
879<h3 id="distribute-through-organization-settings">
880 通过组织设置分发
881</h3>
882
883如果你在 Team 或 Enterprise 计划上通过[**组织设置 > Plugins**](https://claude.ai/admin-settings/plugins)分发 plugins，这些源规则适用：
884
885* 在 github.com 和 gitlab.com 上，marketplace 存储库必须是私有或内部的。组织同步通过与其主机匹配的连接读取存储库：
886 * **github.com**：Claude GitHub App
887 * **你的 GitHub Enterprise Server 主机**：你的组织的 [GitHub Enterprise App](/docs/zh-CN/github-enterprise-server#admin-setup)
888 * **gitlab.com 或你的自托管 GitLab 实例**：你的组织的 [GitLab 配置](#sync-a-gitlab-hosted-marketplace)中该主机的访问令牌
889* 每个 plugin 源必须是 `github`、`url` 或 `git-subdir` 类型，或[相对路径](#relative-paths)，以 `./` 开头。如果你在 `metadata.pluginRoot` 下按裸名称列出 plugin，组织同步会将其拒绝为不支持的源，所以写出路径，例如 `./plugins/deploy-tools`。
890* plugin 源可以在三种情况下是私有的：
891 * 与 marketplace 存储库的所有者共享的 github.com 源
892 * 在你的组织的 GitHub Enterprise 主机上安装了 GHE App 的源
893 * 与 marketplace 存储库在同一 GitLab 主机上的 `url` 或 `git-subdir` 源。在 gitlab.com 上，源也必须在与 marketplace 存储库相同的顶级组或用户命名空间下。
894* 任何其他 plugin 源必须是 github.com、gitlab.com 或 bitbucket.org 上的公开存储库，组织同步在没有凭证的情况下获取。组织同步拒绝这些规则不涵盖的主机上的 plugin 源。
895
896有关管理员工作流，请参阅[为你的组织管理 plugins](https://support.claude.com/en/articles/13837433)。
897
898要包含私有 plugins，请将 plugin 文件夹放在 marketplace 存储库内，并使用[相对路径](#relative-paths)引用它们。组织同步在分发期间打包每个 plugin，所以用户永远不需要访问单独的源存储库。
899
900例如，这个 `marketplace.json` plugin 条目引用你在 marketplace 存储库中的 `plugins/deploy-tools` 处提交的 plugin：
901
902```json theme={null}
903{
904 "name": "deploy-tools",
905 "source": "./plugins/deploy-tools"
906}
907```
908
909<h4 id="sync-a-gitlab-hosted-marketplace">
910 同步 GitLab 托管的 marketplace
911</h4>
912
913要从 gitlab.com 或自托管 GitLab 实例同步 marketplace，[所有者](/docs/zh-CN/server-managed-settings#access-control)首先在[**组织设置 > Claude Code**](https://claude.ai/admin-settings/claude-code)为该主机添加 GitLab 配置。GitLab 配置处于公开测试版，仅适用于 plugin marketplace 同步。添加一个不会使 GitLab 存储库在[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web#limitations) 中可用。有关设置步骤，请参阅[为你的组织管理 plugins](https://support.claude.com/en/articles/13837433)。
914
915当你添加 marketplace 时，输入项目的 HTTPS URL，例如 `https://gitlab.example.com/platform/claude-plugins`。嵌套子组中的项目有效。组织同步读取项目的默认分支。如果你打开**自动同步**，只有对默认分支的 pushes 才会启动同步。
916
917<h4 id="keep-executables-out-of-the-top-level-bin-directory">
918 将可执行文件保留在顶级 bin 目录之外
919</h4>
920
921不要在你通过组织设置分发的任何 plugin 中包含顶级 `bin/` 目录。claude.ai 拒绝具有该目录的 plugin，无论 plugin 是通过 marketplace 同步还是直接上传到达：
922
923* **Marketplace 同步**：组织同步拒绝该 plugin 并同步 marketplace 的其余部分。错误消息以 `Plugin contains a top-level bin/ directory` 开头。
924* **直接上传**：如果你改为在[**组织设置 > Plugins**](https://claude.ai/admin-settings/plugins)中上传 plugin，claude.ai 会以相同的消息拒绝上传。
925
926将可执行文件保留在另一个目录中，例如 `scripts/`，并从你的[skills、hooks 或 MCP server 配置](/docs/zh-CN/plugins-reference#environment-variables)中将它们引用为 `${CLAUDE_PLUGIN_ROOT}/scripts/<name>`。
927
928<h3 id="require-marketplaces-for-your-team">
929 为你的团队要求 marketplaces
930</h3>
931
932你可以配置你的存储库，以便当团队成员[信任项目文件夹](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)时，Claude Code 会为他们添加你的 marketplace，无需单独的提示。将你的 marketplace 添加到 `.claude/settings.json`：
933
934```json theme={null}
935{
936 "extraKnownMarketplaces": {
937 "company-tools": {
938 "source": {
939 "source": "github",
940 "repo": "your-org/claude-plugins"
941 }
942 }
943 }
944}
945```
946
947你也可以指定默认应启用哪些 plugins：
948
949```json theme={null}
950{
951 "enabledPlugins": {
952 "code-formatter@company-tools": true,
953 "deployment-tools@company-tools": true
954 }
955}
956```
957
958有关完整的配置选项，请参阅 [Plugin 设置](/docs/zh-CN/settings-reference#plugin-settings)。
959
960<Note>
961 如果你使用带有相对路径的本地 `directory` 或 `file` 源，路径将相对于你的存储库的主检出解析。当你从 git worktree 运行 Claude Code 时，路径仍然指向主检出，所以所有 worktrees 共享相同的 marketplace 位置。Marketplace 状态存储一次每个用户在 `~/.claude/plugins/known_marketplaces.json` 中，而不是每个项目。
962</Note>
963
964<h3 id="pre-populate-plugins-for-containers">
965 为容器预填充 plugins
966</h3>
967
968对于容器镜像和 CI 环境，你可以在构建时预填充 plugins 目录，以便 Claude Code 启动时已经有 marketplaces 和 plugins 可用，无需在运行时克隆任何内容。设置 `CLAUDE_CODE_PLUGIN_SEED_DIR` 环境变量以指向此目录。
969
970要分层多个种子目录，请在 Unix 上用 `:` 分隔路径，或在 Windows 上用 `;` 分隔。Claude Code 按顺序搜索每个目录，第一个包含给定 marketplace 或 plugin 缓存的种子获胜。
971
972种子目录镜像 `~/.claude/plugins` 的结构：
973
974```
975$CLAUDE_CODE_PLUGIN_SEED_DIR/
976 known_marketplaces.json
977 marketplaces/<name>/...
978 cache/<marketplace>/<plugin>/<version>/...
979```
980
981要构建种子目录，请在镜像构建期间运行 Claude Code 一次，安装你需要的 plugins，然后将生成的 `~/.claude/plugins` 目录复制到你的镜像中，并将 `CLAUDE_CODE_PLUGIN_SEED_DIR` 指向它。
982
983要跳过复制步骤，请在构建期间将 `CLAUDE_CODE_PLUGIN_CACHE_DIR` 设置为你的目标种子路径，以便 plugins 直接安装到那里：
984
985```bash theme={null}
986CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
987CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins
988```
989
990然后在你的容器的运行时环境中设置 `CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed`，以便 Claude Code 在启动时从种子读取。
991
992在启动时，Claude Code 将种子的 `known_marketplaces.json` 中找到的 marketplaces 注册到主配置中，并使用在 `cache/` 下找到的 plugin 缓存，而无需重新克隆。这在交互模式和使用 `-p` 标志的非交互模式中都有效。
993
994行为详情：
995
996* **只读**：Claude Code 永远不会写入种子目录。
997* **自动更新禁用**：种子 marketplaces 不会自动更新。
998* **种子条目优先**：在每次启动时，种子中声明的 marketplaces 会覆盖用户配置中的任何匹配条目。要选择退出种子 plugin，请使用 `/plugin disable` 而不是删除 marketplace。
999* **路径解析**：Claude Code 通过在运行时探测 `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/` 来定位 marketplace 内容，而不是信任存储在种子 JSON 内的路径。这意味着即使在与构建时不同的路径上挂载，种子也能正确工作。
1000* **变更被阻止**：针对种子管理的 marketplace 运行 `/plugin marketplace remove` 或 `/plugin marketplace update` 会失败，并提示你要求管理员更新种子镜像。
1001* **与设置组合**：如果 `extraKnownMarketplaces` 或 `enabledPlugins` 声明的 marketplace 已经存在于种子中，Claude Code 使用种子副本而不是克隆。
1002
1003<h3 id="managed-marketplace-restrictions">
1004 托管 marketplace 限制
1005</h3>
1006
1007对于需要严格控制 plugin 源的组织，管理员可以使用托管设置中的 [`strictKnownMarketplaces`](/docs/zh-CN/settings-reference#strictknownmarketplaces) 设置限制用户允许添加哪些 plugin marketplaces。要同时拒绝为单次运行 sideload plugins、agents 和 MCP servers 的 CLI 标志，请将其与 [`disableSideloadFlags`](/docs/zh-CN/settings-reference#disablesideloadflags) 配对。要允许列表哪些 marketplaces 的 plugins 可以作为上下文安装建议出现，请设置 [`pluginSuggestionMarketplaces`](/docs/zh-CN/settings-reference#pluginsuggestionmarketplaces)。
1008
1009`strictKnownMarketplaces` 匹配 plugin 来自的 marketplace，而不是其中的条目，所以用户仍然可以从允许的 marketplace 安装具有[`command` 源](#command-sources)的 plugin。要同时阻止 command 源，请设置 [`disableCommandPluginSources`](/docs/zh-CN/settings-reference#disablecommandpluginsources)。
1010
1011当在托管设置中配置 `strictKnownMarketplaces` 时，限制行为取决于值：
1012
1013| 值 | 行为 |
1014| -------- | -------------------------------------------------- |
1015| 未定义（默认） | 无限制。用户可以添加任何 marketplace |
1016| 空数组 `[]` | 完全锁定。阻止每个 marketplace 源，包括官方 Anthropic marketplace |
1017| 源列表 | 允许列表强制执行。用户只能添加与条目匹配的 marketplaces |
1018
1019<h4 id="common-configurations">
1020 常见配置
1021</h4>
1022
1023禁用所有 marketplace 添加，包括官方 Anthropic marketplace：
1024
1025```json theme={null}
1026{
1027 "strictKnownMarketplaces": []
1028}
1029```
1030
1031Claude Code 下载[从 claude.ai 同步的](/docs/zh-CN/plugins-reference#synced-plugins) plugins 来自你的账户而不是来自 marketplace，所以这个锁定不涵盖它们。要同时停止这些，请在托管设置中将 [`syncClaudeAiPlugins`](/docs/zh-CN/settings-reference#syncclaudeaiplugins) 设置为 `false`，或在 claude.ai 上为你的组织关闭 Skills。
1032
1033仅允许官方 Anthropic marketplace。单个存储库条目的匹配是精确的，所以此条目不涵盖同一存储库的 `ref` 或 `path` 变体：
1034
1035```json theme={null}
1036{
1037 "strictKnownMarketplaces": [
1038 {
1039 "source": "github",
1040 "repo": "anthropics/claude-plugins-official"
1041 }
1042 ]
1043}
1044```
1045
1046使用此条目，Claude Code 保持已注册的官方 marketplace 可用，在新机器上，在你首次以交互方式启动 Claude Code 时自动注册 marketplace。
1047
1048自动注册不涵盖每台机器。它最常遗漏：
1049
1050* 在机器首次交互启动之前运行的非交互环境。
1051* Claude Code 已在阻止 marketplace 的策略下以交互方式运行的机器，例如空数组锁定。Claude Code 记录被阻止的尝试，在策略更改后不重试。
1052
1053在这些机器上，将 marketplace 添加到同一 `managed-settings.json` 中的 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces)，以便 Claude Code 自动注册它，或运行 `claude plugin marketplace add anthropics/claude-plugins-official`。
1054
1055仅允许特定 marketplaces：
1056
1057```json theme={null}
1058{
1059 "strictKnownMarketplaces": [
1060 {
1061 "source": "github",
1062 "repo": "acme-corp/approved-plugins"
1063 },
1064 {
1065 "source": "github",
1066 "repo": "acme-corp/security-tools",
1067 "ref": "v2.0"
1068 },
1069 {
1070 "source": "url",
1071 "url": "https://plugins.example.com/marketplace.json"
1072 }
1073 ]
1074}
1075```
1076
1077使用[所有者通配符](/docs/zh-CN/settings-reference#owner-wildcards)条目允许 GitHub 组织下的每个 marketplace 存储库。所有者通配符需要 Claude Code v2.1.223 或更高版本。
1078
1079```json theme={null}
1080{
1081 "strictKnownMarketplaces": [
1082 {
1083 "source": "github",
1084 "repo": "acme-corp/*"
1085 }
1086 ]
1087}
1088```
1089
1090使用主机上的正则表达式模式匹配允许来自内部 git 服务器的所有 marketplaces。这是 [GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server#plugin-marketplaces-on-ghes) 或自托管 GitLab 实例的推荐方法：
1091
1092```json theme={null}
1093{
1094 "strictKnownMarketplaces": [
1095 {
1096 "source": "hostPattern",
1097 "hostPattern": "^github\\.example\\.com$"
1098 }
1099 ]
1100}
1101```
1102
1103使用路径上的正则表达式模式匹配允许来自特定目录的基于文件系统的 marketplaces：
1104
1105```json theme={null}
1106{
1107 "strictKnownMarketplaces": [
1108 {
1109 "source": "pathPattern",
1110 "pathPattern": "^/opt/approved/"
1111 }
1112 ]
1113}
1114```
1115
1116使用 `".*"` 作为 `pathPattern` 来允许任何文件系统路径，同时仍然使用 `hostPattern` 控制网络源。
1117
1118<Note>
1119 `strictKnownMarketplaces` 限制用户可以添加的内容，但不会自行注册 marketplaces。要为用户自动注册允许的 marketplace，请在同一 `managed-settings.json` 中将其添加到 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces)。
1120
1121 官方 Anthropic marketplace 是唯一 Claude Code 自行注册的，仅当允许列表允许时。自动注册也遗漏一些机器，例如非交互环境和早期策略阻止它的机器。要覆盖这些机器，也将官方 marketplace 添加到 `extraKnownMarketplaces`。有关两个设置并排，请参阅 [`strictKnownMarketplaces` 参考](/docs/zh-CN/settings-reference#strictknownmarketplaces)。
1122</Note>
1123
1124<h4 id="how-restrictions-work">
1125 限制如何工作
1126</h4>
1127
1128限制在任何网络或文件系统操作之前进行检查。检查在 marketplace 添加以及 plugin 安装、更新、刷新和自动更新时运行。如果 marketplace 在配置策略之前被添加，其源不再与允许列表匹配，Claude Code 会拒绝从中安装或更新 plugins。相同的强制执行也适用于 `blockedMarketplaces`。
1129
1130两个列表的强制执行位置取决于你在哪里设置它们：
1131
1132* **claude.ai 管理控制台**：Claude Code 在[读取服务器管理设置](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies)的会话中强制执行两个列表。claude.ai 还在你的组织中的任何人从 git 存储库在 claude.ai 上添加新 marketplace，或从 Claude Desktop 应用外部其 Code 选项卡的**自定义**添加新 marketplace 时检查它们。这涵盖成员为自己的账户添加的 marketplace 和在[**组织设置 > Plugins**](https://claude.ai/admin-settings/plugins)下为整个组织添加的 marketplace。claude.ai 拒绝允许列表不允许的存储库或阻止列表命名的存储库。它不重新检查在你设置列表之前在任一位置添加的 marketplace，也不检查上传的 plugins。
1133* **托管设置文件、OS 级别策略或其他托管源**：Claude Code 在读取该源的地方强制执行两个列表。claude.ai 不读取它。
1134
1135要阻止 GitHub 所有者下的每个 marketplace 存储库，请在 `blockedMarketplaces` 条目中使用所有者通配符形式：`{ "source": "github", "repo": "untrusted-org/*" }`。需要 Claude Code v2.1.223 或更高版本。有关匹配规则（在阻止列表和允许列表之间不同），请参阅[所有者通配符](/docs/zh-CN/settings-reference#owner-wildcards)。
1136
1137当用户添加 Claude Code [克隆而不是获取](/docs/zh-CN/discover-plugins#add-from-other-git-hosts)的 `https://` 存储库 URL（例如裸 `github.com` 或 `gitlab.com` 存储库 URL）时，Claude Code 也会根据 `blockedMarketplaces` 中的 `url` 条目检查它。如果条目命名相同的 URL，Claude Code 会阻止添加。在该比较中，Claude Code 忽略 `.git` 后缀和用户在 `#` 后附加的任何 ref。需要 Claude Code v2.1.232 或更高版本。在 v2.1.232 之前，Claude Code 仅针对它作为托管 `marketplace.json` 文件获取的 URL 匹配 `url` 条目。
1138
1139允许列表对大多数源类型使用精确匹配，除了所有者通配符 `github` 条目。要允许 marketplace，所有指定的字段必须匹配：
1140
1141* 对于 GitHub 源：`repo` 是必需的，要么命名一个存储库，要么使用所有者通配符形式 `owner/*` 来覆盖该所有者下的每个存储库。有关通配符条目如何匹配（包括大小写规则），请参阅[所有者通配符](/docs/zh-CN/settings-reference#owner-wildcards)。对于单个存储库条目，`ref` 必须完全匹配或在 marketplace 源和允许列表条目中都不存在，相同的规则适用于 `path`
1142* 对于 URL 源：完整 URL 必须完全匹配
1143* 对于 `hostPattern` 源：marketplace 主机与正则表达式模式匹配
1144* 对于 `pathPattern` 源：marketplace 的文件系统路径与正则表达式模式匹配
1145
1146允许列表的精确匹配将仅因尾部斜杠、`.git` 后缀或 `ssh://` 和 `https://` 方案不同的 URL 视为不同的值。如果你的组织的 marketplace 可以通过多个 URL 形式克隆，优先使用 `hostPattern` 条目而不是字面 URL，以便 `https://`、`ssh://` 和 `user@host:path` 形式都匹配。
1147
1148一个[托管在 claude.ai 上的 marketplace](/docs/zh-CN/discover-plugins#add-from-claude-ai) 通过主机匹配：一个与 `claude.ai` 匹配的 `hostPattern` 条目在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中管理它。在允许列表上，这样的条目不允许成员的个人 claude.ai 上传。需要 Claude Code v2.1.273 或更高版本。
1149
1150因为 `strictKnownMarketplaces` 在[托管设置](/docs/zh-CN/managed-settings)中设置，个别用户和项目配置无法覆盖这些限制。
1151
1152有关完整的配置详细信息，包括所有支持的源类型和与 `extraKnownMarketplaces` 的比较，请参阅 [strictKnownMarketplaces 参考](/docs/zh-CN/settings-reference#strictknownmarketplaces)。
1153
1154<h3 id="version-resolution-and-release-channels">
1155 版本解析和发布渠道
1156</h3>
1157
1158Plugin 版本确定缓存路径和更新检测：如果解析的版本与用户已有的版本匹配，`/plugin update` 和自动更新会跳过该 plugin。对于 git 源，如果你省略 `version`，Claude Code 使用源的解析提交 SHA，所以用户在该提交更改时获得更新；这是内部或积极开发的 plugins 的最简单设置。有关完整的解析顺序（包括 `archive` 源），请参阅[版本管理](/docs/zh-CN/plugins-reference#version-management)。
1159
1160<Warning>
1161 设置 `version` 为除了 [`command`](#command-sources) 之外的每个源类型固定 plugin，其版本始终包括命令生成内容的哈希。一个[从 marketplace 加载的 plugin](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)添加为本地目录也不会被固定。如果你在 `plugin.json` 中声明 `"version": "1.0.0"` 并推送新提交而不改变该字符串，这些源的现有用户保留缓存副本，因为 Claude Code 看到相同的版本。在每个发布时提升该字段，或省略它以回退到解析的版本。
1162
1163 避免在 `plugin.json` 和 marketplace 条目中都设置 `version`。Claude Code 总是无声地使用 `plugin.json` 值，所以陈旧的 manifest 版本可能会掩盖你在 `marketplace.json` 中设置的版本。
1164</Warning>
1165
1166<h4 id="set-up-release-channels">
1167 设置发布渠道
1168</h4>
1169
1170要为你的 plugins 支持"稳定"和"最新"发布渠道，你可以设置两个指向同一 repo 的不同 refs 或 SHAs 的 marketplaces。然后你可以通过托管设置以两种方式之一将每个用户组分配给其自己的 marketplace：
1171
1172* 部署单独的[端点管理设置](/docs/zh-CN/managed-settings#delivery-mechanisms)（例如托管设置文件或 MDM 配置文件）到每个组的设备。[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)说明每个组的文件或配置文件是否适用于也有组织范围源的设备。
1173* 为每个组定义一个 [Claude apps gateway 策略](/docs/zh-CN/claude-apps-gateway-config#managed)。网关应用第一个匹配规则适合用户的策略，所以对策略进行排序，以便每个用户到达其组的策略。组策略的 `extraKnownMarketplaces` 替换全局策略的映射而不是与其合并，所以在组的策略中列出组需要的每个 marketplace，而不仅仅是其渠道 marketplace。
1174
1175来自管理控制台的服务器管理设置[适用于你的组织中的每个用户](/docs/zh-CN/server-managed-settings#current-limitations)，所以它们无法进行每个组的分配。
1176
1177<Warning>
1178 每个渠道必须解析为不同的版本。如果你使用显式版本，`plugin.json` 必须在每个固定的 ref 处声明不同的 `version`。如果你省略 `version`，不同的提交 SHA 已经区分了渠道。如果两个 refs 解析为相同的版本字符串，Claude Code 会将它们视为相同并跳过更新。
1179</Warning>
1180
1181<h5 id="example">
1182 示例
1183</h5>
1184
1185```json theme={null}
1186{
1187 "name": "stable-tools",
1188 "plugins": [
1189 {
1190 "name": "code-formatter",
1191 "source": {
1192 "source": "github",
1193 "repo": "acme-corp/code-formatter",
1194 "ref": "stable"
1195 }
1196 }
1197 ]
1198}
1199```
1200
1201```json theme={null}
1202{
1203 "name": "latest-tools",
1204 "plugins": [
1205 {
1206 "name": "code-formatter",
1207 "source": {
1208 "source": "github",
1209 "repo": "acme-corp/code-formatter",
1210 "ref": "latest"
1211 }
1212 }
1213 ]
1214}
1215```
1216
1217<h5 id="assign-channels-to-user-groups">
1218 将渠道分配给用户组
1219</h5>
1220
1221通过上述[设置发布渠道](#set-up-release-channels)中描述的每个组端点管理设置或网关策略将每个 marketplace 分配给其用户组。例如，稳定组接收：
1222
1223```json theme={null}
1224{
1225 "extraKnownMarketplaces": {
1226 "stable-tools": {
1227 "source": {
1228 "source": "github",
1229 "repo": "acme-corp/stable-tools"
1230 }
1231 }
1232 }
1233}
1234```
1235
1236早期访问组改为接收 `latest-tools`：
1237
1238```json theme={null}
1239{
1240 "extraKnownMarketplaces": {
1241 "latest-tools": {
1242 "source": {
1243 "source": "github",
1244 "repo": "acme-corp/latest-tools"
1245 }
1246 }
1247 }
1248}
1249```
1250
1251<h4 id="pin-dependency-versions">
1252 固定依赖版本
1253</h4>
1254
1255Plugin 可以将其依赖约束到 semver 范围，以便对依赖的更新不会破坏依赖的 plugin。有关 `{plugin-name}--v{version}` git 标签约定、范围语法以及如何组合对同一依赖的多个约束，请参阅[约束 plugin 依赖版本](/docs/zh-CN/plugin-dependencies)。
1256
1257<h3 id="rename-or-remove-a-plugin">
1258 重命名或删除 plugin
1259</h3>
1260
1261Plugin 的 `name` 是其稳定标识符。用户在 `enabledPlugins`、`pluginConfigs` 和 `/plugin install` 命令中引用它，所以改变它会破坏每个现有的安装。要改变 UI 中显示的标签而不破坏安装，请设置 [`displayName`](#optional-plugin-fields) 并保持 `name` 不变。
1262
1263如果你必须改变 plugin 的 `name`，或者你从 `plugins` 数组中删除 plugin，请添加顶级 `renames` 条目，以便现有用户迁移而不是看到 `plugin-not-found` 错误。自动迁移需要 Claude Code v2.1.193 或更高版本。将每个前名称映射到其当前名称，或映射到 `null` 如果 plugin 不再存在。以下示例将 `formatter` 重命名为 `code-formatter` 并记录 `legacy-linter` 已被删除：
1264
1265```json theme={null}
1266{
1267 "name": "acme-tools",
1268 "owner": { "name": "Acme" },
1269 "plugins": [
1270 { "name": "code-formatter", "source": "./plugins/code-formatter" }
1271 ],
1272 "renames": {
1273 "formatter": "code-formatter",
1274 "legacy-linter": null
1275 }
1276}
1277```
1278
1279当用户启动 Claude Code 时旧名称仍在其设置中，Claude Code 遵循 `renames` 映射：
1280
1281* 如果条目指向新名称，Claude Code 在其新名称下加载 plugin 并显示一行通知，例如 `在"acme-tools" marketplace 中重命名为"code-formatter"`。然后它在用户、项目和本地设置范围中为 `enabledPlugins` 和 `pluginConfigs` 都将旧键重写为新键，所以通知只出现一次。
1282* 对于 `null` 条目，Claude Code 删除旧键，通知报告 plugin 已从 marketplace 中删除。
1283* 如果重命名的 plugin 使用远程源，例如 `github` 或 `npm`，Claude Code 在重命名后报告 `plugin-cache-miss`，用户必须运行 `/plugin install` 一次以在新名称下获取它。
1284
1285将 `renames` 视为仅追加历史：即使在你期望每个用户都已迁移后，也要保持旧条目就位。Claude Code 遵循链，所以如果你稍后将 `code-formatter` 重命名为 `formatter-pro`，请添加第二个条目而不是编辑第一个。仍然启用原始 `formatter` 的用户然后通过两个条目解析到 `formatter-pro`。
1286
1287在编辑映射后运行 `claude plugin validate .`；它拒绝任何链形成循环或不终止于 `null` 或 `plugins` 中列出的名称的条目。
1288
1289<Note>
1290 托管和策略设置对 Claude Code 是只读的，所以在那里启用的 plugins 无法自动重写。重命名的 plugin 仍然在每个会话中加载，但重命名通知会重复出现，直到管理员更新托管设置文件中的 `enabledPlugins` 以使用新名称。相同的情况适用于通过其他只读源（例如 `--add-dir`）启用的 plugins。
1291</Note>
1292
1293早期版本的 Claude Code 忽略 `renames` 字段并为旧名称报告 `plugin-not-found`。
1294
1295<h2 id="validation-and-testing">
1296 验证和测试
1297</h2>
1298
1299在共享前测试你的 marketplace。验证检查文件结构；要测试 plugin 是否改变了 Claude 在实际提示上的行为，请在发布新版本前使用 [`claude plugin eval`](/docs/zh-CN/plugin-evals) 运行其 eval 套件。
1300
1301从你的 marketplace 目录验证 JSON 语法：
1302
1303```bash theme={null}
1304claude plugin validate .
1305```
1306
1307或从 Claude Code 内：
1308
1309```shell theme={null}
1310/plugin validate .
1311```
1312
1313添加 marketplace 进行测试：
1314
1315```shell theme={null}
1316/plugin marketplace add ./path/to/marketplace
1317```
1318
1319安装测试 plugin 以验证一切正常：
1320
1321```shell theme={null}
1322/plugin install test-plugin@marketplace-name
1323```
1324
1325有关完整的 plugin 测试工作流，请参阅[本地测试你的 plugins](/docs/zh-CN/plugins#test-your-plugins-locally)。有关技术故障排除，请参阅[Plugins 参考](/docs/zh-CN/plugins-reference)。
1326
1327<h2 id="manage-marketplaces-from-the-cli">
1328 从 CLI 管理 marketplaces
1329</h2>
1330
1331Claude Code 提供非交互式 `claude plugin marketplace` 子命令用于脚本编写和自动化。这些等同于交互式会话中可用的 `/plugin marketplace` 命令。
1332
1333<h3 id="plugin-marketplace-add">
1334 Plugin marketplace add
1335</h3>
1336
1337从 GitHub 存储库、git URL、远程 URL 或本地路径添加 marketplace。
1338
1339```bash theme={null}
1340claude plugin marketplace add <source> [options]
1341```
1342
1343**参数：**
1344
1345* `<source>`：GitHub `owner/repo` 简写、git URL、指向 `marketplace.json` 文件的远程 URL 或本地目录路径。要固定到分支或标签，请将 `@ref` 附加到 GitHub 简写或 `#ref` 附加到 git URL
1346
1347URL 必须包含其方案。从 Claude Code v2.1.196 开始，没有方案的主机（如 `gitlab.example.com/team/plugins`）被拒绝为无效的 `owner/repo` 简写，错误会告诉你添加 `https://` 或为本地路径使用 `./`。早期版本会将其误读为 GitHub 存储库路径，并在克隆时失败，出现 GitHub 未找到错误。
1348
1349**选项：**
1350
1351| 选项 | 描述 | 默认值 |
1352| :-------------------- | :--------------------------------------------------------------------------------------------------------------------- | :----- |
1353| `--scope <scope>` | 声明 marketplace 的位置：`user`、`project` 或 `local`。见 [Plugin 安装范围](/docs/zh-CN/plugins-reference#plugin-installation-scopes) | `user` |
1354| `--sparse <paths...>` | 通过 git sparse-checkout 限制检出到特定目录。对 monorepos 有用 | |
1355| `--claudeai` | 将参数读取为 [claude.ai 上托管的 marketplace](/docs/zh-CN/discover-plugins#add-from-claude-ai) 的名称，而不是源。需要 Claude Code v2.1.273 或更高版本 | |
1356
1357从 GitHub 使用 `owner/repo` 简写添加 marketplace：
1358
1359```bash theme={null}
1360claude plugin marketplace add acme-corp/claude-plugins
1361```
1362
1363使用 `@ref` 固定到特定分支或标签：
1364
1365```bash theme={null}
1366claude plugin marketplace add acme-corp/claude-plugins@v2.0
1367```
1368
1369从非 GitHub 主机上的 git URL 添加：
1370
1371```bash theme={null}
1372claude plugin marketplace add https://gitlab.example.com/team/plugins.git
1373```
1374
1375从直接提供 `marketplace.json` 文件的远程 URL 添加：
1376
1377```bash theme={null}
1378claude plugin marketplace add https://example.com/marketplace.json
1379```
1380
1381从本地目录添加以进行测试：
1382
1383```bash theme={null}
1384claude plugin marketplace add ./my-marketplace
1385```
1386
1387在项目范围声明 marketplace，以便通过 `.claude/settings.json` 与你的团队共享：
1388
1389```bash theme={null}
1390claude plugin marketplace add acme-corp/claude-plugins --scope project
1391```
1392
1393对于 monorepo，限制检出到包含 plugin 内容的目录：
1394
1395```bash theme={null}
1396claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins
1397```
1398
1399添加 [claude.ai 上托管的 marketplace](/docs/zh-CN/discover-plugins#add-from-claude-ai)，使用 `claude plugin marketplace list` 的 `From claude.ai:` 部分中打印的名称：
1400
1401```bash theme={null}
1402claude plugin marketplace add --claudeai claudeai-organization-library
1403```
1404
1405使用 `--claudeai`，命令拒绝 `--scope` 和 `--sparse`。marketplace 为你的账户托管，不在设置文件中声明，所以你无法通过项目的 `.claude/settings.json` 共享它。
1406
1407<h3 id="plugin-marketplace-list">
1408 Plugin marketplace list
1409</h3>
1410
1411列出所有配置的 marketplaces。
1412
1413```bash theme={null}
1414claude plugin marketplace list [options]
1415```
1416
1417**选项：**
1418
1419| 选项 | 描述 |
1420| :------- | :------- |
1421| `--json` | 输出为 JSON |
1422
1423使用 `--json`，每个条目包括 `name`、`source`、一个包含 marketplace 存储的本地缓存路径的 `installLocation` 字段，以及源特定字段：GitHub 源的 `repo`、git 和 URL 源的 `url`，以及本地源的 `path`。当 marketplace 使用固定分支或标签添加时，GitHub 和 git 源也包括 `ref` 字段。
1424
1425添加的 [claude.ai marketplace](/docs/zh-CN/discover-plugins#add-from-claude-ai) 没有本地克隆，所以其条目使用其 claude.ai 标识符 `marketplaceId` 和 `organizationUuid` 代替 `installLocation`。
1426
1427在 [plugins 从你的 claude.ai 账户同步](/docs/zh-CN/plugins-reference#synced-plugins) 的终端会话中，文本列表以 `From claude.ai:` 部分结尾，命名 claude.ai 为你的账户列出的内容，超出你添加的 marketplaces。要添加其中之一，见 [从 claude.ai 添加](/docs/zh-CN/discover-plugins#add-from-claude-ai)。`--json` 输出仅涵盖配置的 marketplaces，并省略该部分。需要 Claude Code v2.1.273 或更高版本。
1428
1429<h3 id="plugin-marketplace-remove">
1430 Plugin marketplace remove
1431</h3>
1432
1433删除配置的 marketplace。别名 `rm` 也被接受。
1434
1435```bash theme={null}
1436claude plugin marketplace remove <name> [options]
1437```
1438
1439**参数：**
1440
1441* `<name>`：marketplace 名称要删除，如 `claude plugin marketplace list` 所示。这是来自 `marketplace.json` 的 `name`，而不是你传递给 `add` 的源
1442
1443**选项：**
1444
1445| 选项 | 描述 | 默认值 |
1446| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----- |
1447| `--scope <scope>` | 限制删除到单个设置范围：`user`、`project` 或 `local`。见 [Plugin 安装范围](/docs/zh-CN/plugins-reference#plugin-installation-scopes)。省略时，声明从每个可编辑的范围中删除。给定时，仅删除该范围的声明；当 marketplace 仍在另一个范围中声明时，共享状态、缓存和已安装的 plugin 数据将被保留 | （所有范围） |
1448
1449<Warning>
1450 从其最后剩余的范围中删除 marketplace 也会卸载你从它安装的任何 plugins。要刷新 marketplace 而不丢失已安装的 plugins，请改用 `claude plugin marketplace update`。
1451</Warning>
1452
1453<h3 id="plugin-marketplace-update">
1454 Plugin marketplace update
1455</h3>
1456
1457从其源刷新 marketplaces 以检索新 plugins 和版本更改。使用分支或标签 `ref` 添加的 marketplace 会更新到该 ref 的最新提交，而不是存储库的默认分支。
1458
1459```bash theme={null}
1460claude plugin marketplace update [name]
1461```
1462
1463**参数：**
1464
1465* `[name]`：marketplace 名称要更新，如 `claude plugin marketplace list` 所示。如果省略，更新所有 marketplaces
1466
1467`remove` 和 `update` 在针对种子管理的 marketplace 运行时都会失败，这是只读的。更新所有 marketplaces 时，种子管理的条目被跳过，其他 marketplaces 仍然更新。要更改种子提供的 plugins，请要求你的管理员更新种子镜像。见 [为容器预填充 plugins](#pre-populate-plugins-for-containers)。
1468
1469<h2 id="troubleshooting">
1470 故障排除
1471</h2>
1472
1473<h3 id="marketplace-not-loading">
1474 Marketplace 未加载
1475</h3>
1476
1477**症状**：无法添加 marketplace 或从中看到 plugins
1478
1479**解决方案**：
1480
1481* 验证 marketplace URL 是否可访问
1482* 检查 `.claude-plugin/marketplace.json` 是否存在于指定路径
1483* 使用 `claude plugin validate .` 或 `/plugin validate .` 确保 JSON 语法有效。要检查 skill、agent 和 command frontmatter，请参阅[验证没有 manifest 的 plugin 或目录](#validate-a-plugin-or-a-directory-without-a-manifest)
1484* 对于私有存储库，确认你有访问权限
1485
1486<h3 id="marketplace-validation-errors">
1487 Marketplace 验证错误
1488</h3>
1489
1490从你的 marketplace 目录运行 `claude plugin validate .` 或 `/plugin validate .` 来检查问题。当指向 marketplace 目录时，验证器检查 `marketplace.json` 是否存在 schema 错误、重复的 plugin 名称和源路径遍历。对于 `source` 是本地路径的每个条目，它还验证该 plugin 自己的 `plugin.json`，并在条目的 `version` 与 `plugin.json` 中的版本不匹配时发出警告。在 plugin 的 `plugin.json` 中发现的问题以条目索引为前缀，形式为 `plugins[2] plugin.json →`。
1491
1492从 Claude Code v2.1.196 开始，每个条目的检查还会：
1493
1494* 包括 `source` 为 `.` 的 plugins
1495* 在 `marketplace.json` 位于 `.claude-plugin` 目录外时运行，针对文件自己的目录解析源
1496* 即使文件的另一部分有 schema 错误，也报告每个条目的问题
1497
1498早期版本跳过 marketplace 根目录中的 plugins，仅从 `.claude-plugin/marketplace.json` 开始下降。
1499
1500从 marketplace 目录，Claude Code 不会打开 plugins 的 skill、agent、command 或 hook 文件。要查找这些文件中的错误，请参阅[验证没有 manifest 的 plugin 或目录](#validate-a-plugin-or-a-directory-without-a-manifest)。下表列出了从 marketplace 目录中最常见的错误，以及每个错误的原因和修复方法：
1501
1502| 错误 | 原因 | 解决方案 |
1503| :------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
1504| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | 你命名的目录没有 `.claude-plugin/marketplace.json` 或 `plugin.json`，也没有 skill、agent 或 command 文件可检查 | 从 marketplace 根目录运行，或使用必需字段创建 `.claude-plugin/marketplace.json` |
1505| `Invalid JSON syntax: Unexpected token...` | marketplace.json 中的 JSON 语法错误 | 检查缺少的逗号、多余的逗号或未引用的字符串 |
1506| `Duplicate plugin name "x" found in marketplace` | 两个 plugins 共享相同的名称 | 给每个 plugin 一个唯一的 `name` 值 |
1507| `plugins[0].source: Path contains ".."` | 源路径包含 `..` | 使用相对于 marketplace 根目录的路径，不包含 `..`。见[相对路径](#relative-paths) |
1508| `Marketplace name cannot contain control or bidirectional-formatting characters` | marketplace `name` 包含 Unicode 双向格式化字符或控制字符，如转义或换行符 | 从名称中删除该字符。在 v2.1.247 之前，这些字符产生 `Marketplace name impersonates an official Anthropic/Claude marketplace` 错误 |
1509| `Plugin name cannot contain control or bidirectional-formatting characters` | plugin `name` 包含 Unicode 双向格式化字符或控制字符，如转义或换行符 | 从名称中删除该字符。在 v2.1.247 之前，Claude Code 没有运行此检查 |
1510
1511**警告**（非阻止）：
1512
1513* `Marketplace has no plugins defined`：将至少一个 plugin 添加到 `plugins` 数组
1514* `No marketplace description provided`：添加顶级 `description` 以帮助用户理解你的 marketplace
1515* `Plugin name "x" is not kebab-case`：重命名为仅包含小写字母、数字和连字符（例如，`my-plugin`）。Claude Code 接受其他形式，但 claude.ai marketplace 同步会拒绝它们。
1516* `Marketplace name "x" is reserved in Claude Desktop`：marketplace 名称为 `org`、`org-provisioned` 或 `unknown`，任何大小写。Claude Code 接受这些名称，但 Claude Desktop 的托管 marketplace 同步会拒绝整个 marketplace。重命名 marketplace。在 v2.1.221 之前，`claude plugin validate` 没有运行此检查。
1517* `Marketplace name "x" is not accepted by Claude Desktop` 或 `Plugin name "x" is not accepted by Claude Desktop`：Claude Desktop 接受最多 128 个字符的名称，由字母、数字、`.`、`_` 和 `-` 组成，以字母或数字开头。Claude Code 接受其他形式，但 Claude Desktop 的托管 marketplace 同步会拒绝名称检查失败的 marketplace，并静默删除名称检查失败的 plugin 条目。重命名 marketplace 或 plugin。在 v2.1.221 之前，`claude plugin validate` 没有运行这些检查。
1518
1519<h4 id="validate-a-plugin-or-a-directory-without-a-manifest">
1520 验证没有 manifest 的 plugin 或目录
1521</h4>
1522
1523要查找 skill、agent 和 command 文件，其 frontmatter 无法解析，请运行 `claude plugin validate` 并命名包含它们的目录。Claude Code 不会查看你命名的目录之外。除了一次针对具有 `plugin.json` 的 plugin 的运行外，每次运行都需要 Claude Code v2.1.233 或更高版本。
1524
1525<h5 id="pick-the-directory-to-name">
1526 选择要命名的目录
1527</h5>
1528
1529Claude Code 根据你命名的目录检查不同的文件。在第一列中找到你想检查的内容，并运行该行的命令：
1530
1531| 要检查 | 运行 | Claude Code 检查 |
1532| :------------------------------------------------------ | :-------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ |
1533| 具有 `plugin.json` 的 plugin | `claude plugin validate ./plugins/my-plugin` | `plugin.json`、`hooks/hooks.json` 和 plugin 根目录下的 `skills`、`agents` 和 `commands` 目录 |
1534| 一个 skill、agent 或 command 目录，例如没有 `plugin.json` 的 plugin | `claude plugin validate .claude/skills`、`~/.claude/agents` 或 `./my-plugin/agents` | 该目录中的每个 skill、agent 或 command 文件 |
1535| 其 skill 是其根 `SKILL.md` 的文件夹 | `claude plugin validate ./skills`，命名包含该文件夹的 `skills` 目录 | 每个文件夹的根 `SKILL.md`。包含目录必须命名为 `skills`；位于另一个名称下的文件夹，如 `plugins/`，没有检查其根 `SKILL.md` 的运行 |
1536| 一个项目的三个目录一次 | `claude plugin validate .claude`，或当项目没有 `.claude-plugin/` manifest 时的项目根目录 | `.claude/skills`、`.claude/agents` 和 `.claude/commands` |
1537| 你的用户级目录 | `claude plugin validate ~/.claude` | `~/.claude/skills`、`~/.claude/agents` 和 `~/.claude/commands` |
1538
1539<h5 id="check-a-plugin-whose-skill-is-its-root-skill-md">
1540 检查其 skill 是其根 `SKILL.md` 的 plugin
1541</h5>
1542
1543当你针对 plugin 目录运行 `claude plugin validate` 时，Claude Code 不会检查 plugin 根目录下的 `SKILL.md`。当 plugin 位于名为 `skills` 的目录中时，运行该命令两次：
1544
1545* 命名该 `skills` 目录以检查 plugin 的根 `SKILL.md`。
1546* 命名 plugin 目录以检查其余部分。
1547
1548当 plugin 位于另一个名称下（如 `plugins/`）时，`skills` 目录运行不可用，没有运行检查其根 `SKILL.md`。
1549
1550<h5 id="check-files-behind-symlinks">
1551 检查符号链接后面的文件
1552</h5>
1553
1554当你运行 `claude plugin validate` 时，Claude Code 不会跟随你命名的目录内的符号链接。它所做的取决于链接的位置：
1555
1556* **plugin 或 `.claude` 根目录下的链接 `skills`、`agents` 或 `commands` 目录**：Claude Code 警告其中没有任何内容被读取。
1557* **`skills`、`agents` 或 `commands` 目录内的链接条目**：Claude Code 跳过它并警告，每个目录，它跳过了多少条目，会话会加载。
1558* **你命名的 `skills`、`agents` 或 `commands` 目录本身是符号链接，或其父 `.claude` 目录是**：Claude Code 报告错误，并且不检查其中的任何内容。改为命名真实目录。
1559
1560在两个 skills 情况下，运行通过警告。要检查链接的文件，再次运行并命名直接包含它们的目录：
1561
1562* **其 `skills` 目录[链接到同级 plugin 的 skills](/docs/zh-CN/plugins-reference#share-files-within-a-marketplace-with-symlinks) 的 plugin**：命名同级 plugin 的目录。
1563* **`~/.claude/skills` 或 `.claude/skills` 中的[符号链接 skill 条目](/docs/zh-CN/skills#where-skills-live)**：Claude Code 在会话中跟随该条目。要检查它，命名一个名为 `skills` 的目录，该目录包含真实文件夹。
1564
1565<h5 id="read-the-validation-results">
1566 读取验证结果
1567</h5>
1568
1569干净的运行以 `Validation passed` 结束。
1570
1571`No manifest found in directory` 意味着 Claude Code 在那里找不到 `plugin.json` 或 `marketplace.json`，也找不到它在其下探测的目录中的 skill、agent 或 command 文件。改为命名包含你的文件的 `skills`、`agents` 或 `commands` 目录。
1572
1573Claude Code 从这些运行中报告的两个错误，以及每个错误的修复：
1574
1575* `YAML frontmatter failed to parse: ...`：修复 skill、agent 或 command 文件的 frontmatter 块中的 YAML。在你这样做之前，会话从文件中读取不到 frontmatter 字段
1576* `Invalid JSON syntax: ...` 在 `hooks/hooks.json` 上：修复 JSON 语法。在你这样做之前，会话加载 plugin 时不带该文件中的 hooks。Claude Code 仅在 plugin 运行中报告此错误
1577
1578在 plugin 运行中，Claude Code 还会警告 plugin 根目录下的 `CLAUDE.md`。对于你通过 [component path fields](/docs/zh-CN/plugins-reference#component-path-fields) 在 `plugin.json` 中设置的路径，Claude Code 检查每个路径是否存在，但不读取那里的文件。
1579
1580<h3 id="plugin-installation-failures">
1581 Plugin 安装失败
1582</h3>
1583
1584**症状**：Marketplace 出现但 plugin 安装失败
1585
1586**解决方案**：
1587
1588* 验证 plugin 源 URL 是否可访问
1589* 检查 plugin 目录是否包含必需的文件
1590* 对于 GitHub 源，确保存储库是公开的或你有访问权限
1591* 通过手动克隆/下载来测试 plugin 源
1592* 如果源同时固定了 `ref` 和 `sha`，删除的上游分支或标签不会阻止大多数 git 主机（包括 GitHub、GitLab 和 Bitbucket）上的安装。在不支持通过 SHA 获取提交的服务器上（如 AWS CodeCommit），`ref` 必须仍然存在，固定的提交必须可从其到达。如果安装仍然失败，请确认固定的提交仍然存在于存储库中
1593
1594<h3 id="private-repository-authentication-fails">
1595 私有存储库身份验证失败
1596</h3>
1597
1598**症状**：从私有存储库安装 plugins 时出现身份验证错误
1599
1600**解决方案**：
1601
1602对于手动安装和更新：
1603
1604* 验证你已使用你的 git 提供商进行身份验证（例如，对于 GitHub 运行 `gh auth status`）
1605* 检查你的凭证助手是否配置正确：`git config --global credential.helper`
1606* 运行 `git ls-remote <marketplace-url>` 来测试 git 是否可以自行进行身份验证。如果 git 要求输入用户名或密码，请先存储凭证：对于 GitHub over HTTPS，运行 `gh auth setup-git`，对于 SSH 远程，将你的密钥加载到 `ssh-agent`
1607
1608对于后台自动更新：
1609
1610* 后台检查使用你配置的 git 凭证助手，但从不提示，因此你的助手必须能够使用存储的凭证进行应答。在 `ssh-agent` 中加载了密钥的 SSH 远程也可以进行身份验证
1611* 如果你的助手需要提示你，后台更新会静默失败，现有检出保持不变。首先登录你的助手，以便它为主机保存凭证。对于 GitHub，运行 `gh auth login`，然后 `gh auth setup-git`
1612* 当检查找到新提交，或无法到达或无法进行身份验证到远程时，Claude Code 使用相同的凭证重新克隆 marketplace。重新克隆可能在大型存储库上超时
1613* 设置 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在后台检查无法到达或无法进行身份验证到远程时保留现有检出，而不尝试重新克隆
1614* 如果重新克隆在大型存储库上超时，请使用 [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out) 增加限制
1615* 或使用 `/plugin marketplace update <name>` 手动更新私有 marketplaces，这使用你的凭证
1616
1617在 v2.1.280 之前，后台检查在没有你的凭证助手的情况下运行，无法进行身份验证到 HTTPS 上的私有存储库。
1618
1619<h3 id="marketplace-updates-fail-in-offline-environments">
1620 Marketplace 更新在离线环境中失败
1621</h3>
1622
1623**症状**：在离线或隔离的环境中，后台 marketplace 刷新无法到达远程，Claude Code 反复尝试无法成功的重新克隆。
1624
1625**原因**：后台刷新检查 marketplace 的远程以查找新提交，当检查无法到达远程时，Claude Code 尝试再次克隆 marketplace。离线时，克隆以相同的方式失败，现有检出保持不变。在 v2.1.274 之前，刷新在现有检出中运行 `git pull`，当拉取失败时将检出移到一边以重新克隆，并在事后尽力恢复它。
1626
1627刷新在启动后在后台运行，因此不会延迟启动。每个会话仍然重复失败的尝试，每个 git 操作可以等待 [120 秒超时](#git-operations-time-out)。
1628
1629**解决方案**：设置 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在检查无法到达远程时跳过重新克隆尝试并继续使用现有检出：
1630
1631```bash theme={null}
1632export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1
1633```
1634
1635对于存储库永远无法访问的完全离线部署，请改用 [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) 在构建时预填充 plugins 目录。
1636
1637<h3 id="git-operations-time-out">
1638 Git 操作超时
1639</h3>
1640
1641**症状**：Plugin 安装或 marketplace 更新失败，出现超时错误，如 `Git clone timed out after 120s`。
1642
1643**原因**：Claude Code 对所有 git 操作使用 120 秒超时，包括克隆 plugin 存储库和重新克隆 marketplace 以更新它。大型存储库或缓慢的网络连接可能超过此限制。
1644
1645**解决方案**：使用 `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` 环境变量增加超时。该值以毫秒为单位：
1646
1647```bash theme={null}
1648export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000 # 5 minutes
1649```
1650
1651<h3 id="plugins-with-relative-paths-fail-in-url-based-marketplaces">
1652 相对路径 Plugins 在基于 URL 的 Marketplaces 中失败
1653</h3>
1654
1655**症状**：通过 URL（如 `https://example.com/marketplace.json`）添加了 marketplace，但具有相对路径源（如 `"./plugins/my-plugin"`）的 plugins 无法安装，出现 `its marketplace entry path does not stay inside the marketplace directory` 错误。已安装的 plugins 无法加载，出现 `Plugin source path refused` 错误。两条消息都有一个[错误参考条目](/docs/zh-CN/errors#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory)。
1656
1657**原因**：添加基于 URL 的 marketplace 仅下载 `marketplace.json` 文件本身，Claude Code 不会从该服务器按相对路径获取 plugin 文件。marketplace 条目中的相对路径引用远程服务器上未下载的文件。
1658
1659**解决方案**：
1660
1661* **使用外部源**：将 plugin 条目更改为除相对路径外的任何 [plugin 源](#plugin-sources)：
1662 ```json theme={null}
1663 { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
1664 ```
1665* **使用基于 Git 的 Marketplace**：在 Git 存储库中托管你的 marketplace 并使用 git URL 添加它。基于 Git 的 marketplaces 克隆整个存储库，使相对路径有效。
1666
1667<h3 id="files-not-found-after-installation">
1668 安装后文件未找到
1669</h3>
1670
1671**症状**：Plugin 安装但对文件的引用失败，特别是 plugin 目录外的文件
1672
1673**原因**：Claude Code 将已安装的 plugins 复制到缓存目录，除非 plugin 就地加载。[链接模式中的 `command` 源](#copy-mode-and-link-mode)就地加载，[相对路径源](#relative-paths)在从本地目录添加的 marketplace 中也是如此。引用复制的 plugin 目录外文件的路径（如 `../shared-utils`）不会工作，因为这些文件不会被复制。
1674
1675**解决方案**：见 [Plugin 缓存和文件解析](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution) 了解解决方法，包括符号链接和目录重组。
1676
1677有关其他调试工具和常见问题，请参阅[调试和开发工具](/docs/zh-CN/plugins-reference#debugging-and-development-tools)。
1678
1679<h2 id="see-also">
1680 另见
1681</h2>
1682
1683* [发现和安装预构建的 plugins](/docs/zh-CN/discover-plugins) - 从现有 marketplaces 安装 plugins
1684* [Plugins](/docs/zh-CN/plugins) - 创建你自己的 plugins
1685* [Plugins 参考](/docs/zh-CN/plugins-reference) - 完整的技术规范和架构
1686* [Plugin 设置](/docs/zh-CN/settings-reference#plugin-settings) - Plugin 配置选项
1687* [strictKnownMarketplaces 参考](/docs/zh-CN/settings-reference#strictknownmarketplaces) - 托管 marketplace 限制