> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Marketplace 参考

> marketplace.json 字段、插件条目和插件及 marketplace 源对象的完整参考，包括每个字段的有效位置。

`marketplace.json` 是定义插件 marketplace 的文件。它包含 marketplace 的名称、所有者和每个插件的一个条目。每个条目的插件源说明 Claude Code 从哪里获取该插件。

marketplace 源是一个单独的对象，说明 Claude Code 从哪里获取 marketplace 文件本身。你在设置中编写一个，或者当你运行 `claude plugin marketplace add` 时 Claude Code 会构建一个。

本参考适用于需要确切字段名称或值的 marketplace 维护者，以及需要了解哪些 `source` 值在 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces)、[`strictKnownMarketplaces`](/docs/zh-CN/settings-reference#strictknownmarketplaces) 和 [`blockedMarketplaces`](/docs/zh-CN/plugins/org#restrict-what-users-can-install) 中有效的管理员。

<Note>
  这些情况在其他页面上有介绍：

  * **构建或托管 marketplace**：请参阅 [创建 marketplace](/docs/zh-CN/plugins/create-marketplace) 和 [托管和维护 marketplace](/docs/zh-CN/plugins/host-marketplace)
  * **允许列表和阻止列表配方**：请参阅 [为你的组织管理插件](/docs/zh-CN/plugins/org)
</Note>

查找你正在编写或读取的内容的部分：

* **marketplace 文件**：[顶级字段](#top-level-fields) 和 [插件条目](#plugin-entries)
* **条目的 `source`**：[插件源](#plugin-sources)
* **设置中的 `source` 对象**：[Marketplace 源](#marketplace-sources)
* **来自 [`claude plugin validate <path>`](/docs/zh-CN/plugins/cli-reference) 的输出**：[验证消息](#validation-messages)，它将每条消息映射到它命名的字段

<h2 id="marketplace-file">
  Marketplace 文件
</h2>

将 marketplace 文件保存在 marketplace 目录中的 `.claude-plugin/marketplace.json`。如果你将文件保存在存储库中的其他位置，用户必须在 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 中声明 marketplace，并在其源上设置 `path`，因为 `claude plugin marketplace add` 没有该选项。

包含 `.claude-plugin/` 的目录称为 marketplace 根目录，每个相对插件源都从它解析，而不是从 `.claude-plugin/`。

每个用户为每个 `name` 注册一个 marketplace，因此用户不能同时注册两个同名的 marketplace。

Claude Code 忽略未知的顶级键或插件条目键，而不是拒绝它，因此拼写错误会静默加载。`claude plugin validate` 将每个未知键报告为警告。

<h3 id="reserved-names">
  保留名称
</h3>

你不能给你的 marketplace 以下任何名称：

* **官方 marketplace 名称**：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`life-sciences`、`knowledge-work-plugins`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins` 和 `claude-tag-plugins`。除非 marketplace 来自 `github.com/anthropics/` 下的 `github` 或 `git` [marketplace 源](#marketplace-sources)，否则保留。
* **社区 marketplace 名称**：`claude-community`、`claude-plugins-community` 和 `healthcare`。保留规则与官方名称相同。
* **插件目录名称**：`anthropic-plugin-directory` 和 `claude-plugin-directory`。保留规则与官方名称相同。
* **冒充官方 marketplace 的名称**：名称如 `official-claude-plugins` 或 `claude-plugins-v2`，以及任何包含非 ASCII 字符的名称。错误是 `Marketplace name impersonates an official Anthropic/Claude marketplace`。名称中的控制或双向格式化字符也会报告 `Marketplace name cannot contain control or bidirectional-formatting characters`。
* <span id="reserved-name-spellings" />**保留名称的另一种拼写**：与保留名称仅在尾部点或用除下划线以外的符号代替连字符的名称，因此 `claude.code.plugins` 计为 `claude-code-plugins`。`claude plugin validate` 接受这样的名称；添加 marketplace 失败，错误为 [`is another spelling of "<reserved>", a reserved marketplace name`](/docs/zh-CN/errors#marketplace-name-is-another-spelling-of-a-reserved-name)，已在一个下注册的 marketplace 停止加载。此检查需要 Claude Code v2.1.280 或更高版本。
* **Claude Code 用于不来自 marketplace 的插件的名称**：`inline` 用于使用 [`--plugin-dir`](/docs/zh-CN/cli-reference) 加载的插件，`builtin` 用于内置插件，`skills-dir` 用于从 [`.claude/skills/`](/docs/zh-CN/skills) 自动加载的插件，`synced` 用于从你的 claude.ai 账户同步的插件。`claude-plugin-test` 也被保留。`skills-dir` 也显示为 `{"source": "skills-dir"}`，在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中，如 [仅在策略列表中有效的源值](#source-values-valid-only-in-policy-lists) 下所述。
* **`npm`、`pip`、`uv`、`cargo`、`github` 和 `gh`**：以任何大小写保留。此检查需要 Claude Code v2.1.275 或更高版本。
* **以 `claudeai-` 开头的名称**：为托管在 claude.ai 上的 marketplace 保留。`claude plugin marketplace add` 拒绝任何其他使用一个的 marketplace，错误为 `Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai`。

<h2 id="top-level-fields">
  顶级字段
</h2>

该表列出 Claude Code 从 `marketplace.json` 读取的每个键。`name`、`owner` 和 `plugins` 是必需的。

| 字段                                        | 类型               | 描述                                                                                                                              |
| :---------------------------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| `name`                                    | string           | Marketplace 标识符。没有空格、控制字符或双向格式化字符，没有 `/` 或 `\`，没有 `..`，不是 `.`。请参阅 [保留名称](#reserved-names)。用户在安装插件时在 `@` 后键入它                    |
| `owner`                                   | object           | 维护者信息。`name` 是必需的；`email` 和 `url` 是可选的                                                                                          |
| `plugins`                                 | array            | [插件条目](#plugin-entries)。每个条目单独验证，因此一个无效条目不会导致 marketplace 失败                                                                    |
| `$schema`                                 | string           | JSON Schema URL 用于编辑器自动完成。在加载时忽略                                                                                                |
| `description`                             | string           | 向用户显示的 marketplace 描述。`claude plugin validate` 在缺少时警告                                                                           |
| `version`                                 | string           | Marketplace 清单版本                                                                                                                |
| `metadata.description`、`metadata.version` | string           | `description` 和 `version` 的备用位置                                                                                                 |
| `metadata.pluginRoot`                     | string           | 裸插件源名称解析的目录。请参阅 [相对路径插件源](#relative-path-plugin-source)。需要 Claude Code v2.1.239 或更高版本                                           |
| `forceRemoveDeletedPlugins`               | boolean          | 当为 `true` 时，从 `plugins` 中删除的插件会在用户的机器上卸载。请参阅 [托管和维护 marketplace](/docs/zh-CN/plugins/host-marketplace)                               |
| `allowCrossMarketplaceDependenciesOn`     | array of strings | 其插件可作为此 marketplace 插件的依赖项安装的 marketplace 名称。安装插件时，仅适用该插件自己的 marketplace 中的列表，用于其整个依赖链。请参阅 [插件依赖项](/docs/zh-CN/plugins/dependencies) |
| `renames`                                 | object           | 从前一个插件 `name` 映射到其当前名称，或映射到 `null` 以删除插件。需要 Claude Code v2.1.193 或更高版本。请参阅 [托管和维护 marketplace](/docs/zh-CN/plugins/host-marketplace) |

<h2 id="plugin-entries">
  插件条目
</h2>

`marketplace.json` 的顶级 `plugins` 数组中的每个对象命名一个插件并说明从哪里获取它。`name` 和 `source` 是必需的。

条目也接受每个 [`plugin.json` 字段](/docs/zh-CN/plugins/manifest-reference)，如 `description`、`version`、`author`、`commands` 和 `hooks`。有关这些字段何时适用，请参阅 [条目如何与 plugin.json 结合](#entry-and-plugin-json)。

该表列出条目自己的字段和清单字段，其含义在条目中改变。

| 字段               | 类型               | 描述                                                                                                                                                                                                      |
| :--------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`           | string           | 插件标识符，没有空格、控制字符或双向格式化字符。用户在安装时在 `@` 前键入它，即使插件自己的 `plugin.json` 设置了不同的 `name`                                                                                                                            |
| `source`         | string or object | 从哪里获取插件。请参阅 [插件源](#plugin-sources)                                                                                                                                                                      |
| `description`    | string           | 在 [`/plugin`](/docs/zh-CN/plugins/install) 列表和详情中显示                                                                                                                                                          |
| `version`        | string           | 插件的版本字符串。当 `plugin.json` 也设置 `version` 时，`plugin.json` 优先，`claude plugin validate` 警告。请参阅 [插件加载参考](/docs/zh-CN/plugins/loading)                                                                              |
| `category`       | string           | 用于组织目录的自由格式类别                                                                                                                                                                                           |
| `tags`           | array of strings | 用于搜索的自由格式标签                                                                                                                                                                                             |
| `strict`         | boolean          | 默认 `true`。`plugin.json` 是否是插件组件的权威来源。请参阅 [严格模式](#strict-mode)                                                                                                                                           |
| `relevance`      | object           | 告诉 Claude Code 何时建议插件的信号。请参阅 [为你的组织推荐插件](/docs/zh-CN/plugins/relevance)                                                                                                                                      |
| `dependencies`   | array            | 必须为此插件启用的插件。每个项是 `"name"`、`"name@marketplace"` 或对象。请参阅 [插件依赖项](/docs/zh-CN/plugins/dependencies)                                                                                                             |
| `defaultEnabled` | boolean          | 默认 `true`。当用户未在 [`enabledPlugins`](/docs/zh-CN/settings-reference#enabledplugins) 中设置时，插件是否启动时启用。条目值优先于 `plugin.json`                                                                                        |
| `displayName`    | string           | 在 UI 中显示的人类可读名称。当条目和插件的 `plugin.json` 都未设置时，用户看到插件的 `name`                                                                                                                                              |
| `metadata`       | object           | 用于你自己字段的自由格式对象。Claude Code 不读取它。需要 Claude Code v2.1.222 或更高版本                                                                                                                                           |
| `headers`        | object           | Claude Code 在下载此条目的 [archive](#archive-plugin-source) 时发送的 HTTP 标头。此处设置的标头替换 marketplace 源的 [`headers`](#fields-by-type) 中同名的标头。需要 Claude Code v2.1.238 或更高版本                                           |
| `headersHelper`  | string           | 打印此条目的 archive 下载标头的命令，作为一个 JSON 对象，用于过期的凭证。条目还必须设置 [`"strict": false`](#strict-mode)。需要 Claude Code v2.1.238 或更高版本。请参阅 [验证 archive 下载](/docs/zh-CN/plugins/host-marketplace#authenticate-archive-downloads) |

<h3 id="entry-and-plugin-json">
  条目如何与 plugin.json 结合
</h3>

条目的字段对获取的具有自己的 `.claude-plugin/plugin.json` 的插件和没有的插件的应用方式不同：

* **没有 `plugin.json`**：条目是清单，无论 `strict` 如何。条目中的每个清单字段都适用，包括 [`mcpServers`、`lspServers`、`userConfig` 和 `channels`](/docs/zh-CN/plugins/manifest-reference)。
* **`plugin.json` 存在**：`plugin.json` 是清单。[严格模式](#strict-mode) 决定条目的六个组件字段 `commands`、`agents`、`skills`、`hooks`、`outputStyles` 和 `themes` 是与其结合还是作为冲突被拒绝。条目 `mcpServers`、`lspServers`、`userConfig` 和 `channels` 不适用。在 `plugin.json` 中声明它们。

<h4 id="hooks-in-an-entry">
  条目中的 Hooks
</h4>

将条目 `hooks` 写成内联对象，将 hook 事件名称映射到匹配器数组。如果你写文件路径或数组，`claude plugin validate` 会通过。这些 hooks 永远不会运行，Claude Code 为插件报告 `not yet supported in a marketplace entry` 错误。将基于文件的 hooks 放在插件自己的 [`hooks/hooks.json`](/docs/zh-CN/plugins/components) 或 `plugin.json` 中。

<h4 id="display-fields">
  显示字段
</h4>

条目和插件自己的 `plugin.json` 都可以设置显示字段 `displayName`、`description`、`author`、`homepage`、`repository`、`license` 和 `keywords`。用户在插件列表和详情中看到这些值，在安装前后：

* 对于你在条目上设置的字段，用户看到条目的值，即使 `plugin.json` 设置了不同的值。
* 对于条目未设置的字段，用户看到 `plugin.json` 值。

在安装前，Claude Code 只能为具有 [相对路径源](#relative-path-plugin-source) 的条目读取 `plugin.json`，其插件文件在 marketplace 内。对于具有任何其他源类型的条目，用户在安装插件之前只看到条目自己的字段。

<h3 id="strict-mode">
  严格模式
</h3>

`strict` 决定当获取的插件具有自己的 `plugin.json` 且条目也声明任何 [组件字段](#entry-and-plugin-json) 时会发生什么：`commands`、`agents`、`skills`、`hooks`、`outputStyles` 或 `themes`。使用 `strict: true`（默认值），Claude Code 将条目的组件字段附加到 `plugin.json`，除了 `hooks`，其匹配器替换清单的每个事件。使用 `strict: false`，声明任何组件字段的条目是冲突，插件加载失败。该表显示 `strict`、`plugin.json` 和条目的组件字段的每个组合。

| `strict`   | `plugin.json` | 条目组件字段      | 结果                                                                                                                                                  |
| :--------- | :------------ | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| any        | absent        | any         | 条目是清单                                                                                                                                               |
| `true`，默认值 | present       | any         | `plugin.json` 是权威。Claude Code 将条目的组件字段附加到它，除了 `hooks`，其匹配器 [替换清单的每个事件](/docs/zh-CN/plugins/manifest-reference#how-entry-fields-combine-with-plugin-json) |
| `false`    | present       | none        | `plugin.json` 是清单，与 `true` 相同                                                                                                                       |
| `false`    | present       | one or more | 冲突。插件加载失败，错误为 `Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components`                                  |

<h2 id="plugin-sources">
  Plugin sources
</h2>

一个插件条目的 `source` 说明 Claude Code 从哪里获取该插件。它要么是一个相对路径字符串，要么是一个对象，其自身的 `source` 键命名类型，所以一个条目看起来像 `"source": { "source": "github", "repo": "your-org/formatter" }`。

该表列出了每种插件源类型及其字段。

| 类型           | 字段                               | 说明                                                                                                                                                                 |
| :----------- | :------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 相对路径         | 字符串本身                            | marketplace 内的一个目录，从 marketplace 根目录解析。必须以 `./` 开头，除非你在 [`metadata.pluginRoot`](#bare-names-under-pluginroot) 下写一个[裸名](#bare-names-under-pluginroot)。`"."` 本身表示根目录 |
| `github`     | `repo`, `ref`, `sha`             | GitHub 仓库，格式为 `owner/repo`                                                                                                                                         |
| `url`        | `url`, `ref`, `sha`              | 任何 git 仓库的 URL                                                                                                                                                     |
| `git-subdir` | `url`, `path`, `ref`, `sha`      | git 仓库的一个子目录，使用稀疏部分克隆获取                                                                                                                                            |
| `npm`        | `package`, `version`, `registry` | npm 包，使用你的 npm 客户端获取并解包，不运行安装脚本                                                                                                                                    |
| `archive`    | `url`, `sha256`                  | HTTPS 上的 Zip 存档。需要 Claude Code v2.1.224 或更高版本                                                                                                                      |
| `command`    | `command`, `timeout`, `mode`     | 由 Claude Code 在用户机器上运行的命令打印的目录。需要 Claude Code v2.1.229 或更高版本                                                                                                       |

名称 `url` 和 `github` 也是[marketplace 源](#marketplace-sources)类型，其中 `url` 表示直接链接到 `marketplace.json` 文件而不是 git 仓库。`git` 仅作为 marketplace 源存在，`npm` 既作为 marketplace 源也作为插件源存在。`git-subdir`、`archive` 和 `command` 仅作为插件源存在。

对于 marketplace 仓库本身的子目录中的插件，使用相对路径。对于其他仓库的子目录，使用 `git-subdir`。

`github`、`url` 和 `git-subdir` 源共享 `ref` 和 `sha` 字段：

* **`ref`**：一个分支或标签。默认为仓库的默认分支。
* **`sha`**：一个完整的 40 字符小写提交 SHA。当你同时设置 `ref` 和 `sha` 时，Claude Code 检出 `sha`。在大多数 git 主机上，包括 GitHub、GitLab 和 Bitbucket，这意味着即使上游的分支或标签已被删除，只要提交仍然可从仓库到达，安装就会成功。某些服务器（如 AWS CodeCommit）不支持按 SHA 获取提交。在这些服务器上，`ref` 必须仍然存在，固定的提交必须可从它到达。

有关每种类型如何获取、缓存和版本化的信息，请参阅 [Plugin loading reference](/docs/zh-CN/plugins/loading)。

<h3 id="relative-path-plugin-source">
  Relative path plugin source
</h3>

路径从 marketplace 根目录解析。`./plugins/formatter` 是 `<root>/plugins/formatter`，即使 marketplace 文件在 `<root>/.claude-plugin/` 中。

包含 `..` 的路径会验证失败。在 macOS 和 Linux 上，Claude Code 拒绝条目路径在前导 `./` 之后的任何地方包含反斜杠，所以用正斜杠写路径。

```json theme={null}
{ "name": "formatter", "source": "./plugins/formatter" }
```

相对路径仅在 Claude Code 拥有 marketplace 文件时才能解析，所以检查 [marketplace 源](#marketplace-sources)类型：

* **`github`、`git`、`file` 和 `directory`**：Claude Code 拥有 marketplace 的文件。
* **`url`**：Claude Code 仅获取 `marketplace.json`，所以相对路径无法解析。给每个插件一个对象源，如 `github` 或 `git-subdir`。
* **`settings`**：相对路径被直接拒绝。

<h4 id="bare-names-under-pluginroot">
  Bare names under pluginRoot
</h4>

裸名是一个没有 `/` 的单个目录名，如 `"formatter"`。要写裸名而不是 `./` 路径，设置 [`metadata.pluginRoot`](#top-level-fields) 为它们解析的目录。使用 `"pluginRoot": "./plugins"`，`"source": "formatter"` 解析为 `./plugins/formatter`。需要 Claude Code v2.1.239 或更高版本。

`metadata.pluginRoot` 有这些限制：

* 它本身必须是 marketplace 内的相对路径。
* 它对已经以 `./` 开头的源没有影响。
* 包含 `/` 的源，如 `team-a/formatter`，不是裸名，即使设置了 `metadata.pluginRoot` 也仍然需要 `./` 前缀。

<h3 id="github-plugin-source">
  github plugin source
</h3>

`repo` 采用 `owner/repo` 格式。`ref` 和 `sha` 是可选的。

```json theme={null}
{
  "name": "formatter",
  "source": {
    "source": "github",
    "repo": "your-org/formatter",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}
```

<h3 id="url-plugin-source">
  url plugin source
</h3>

`url` 是一个完整的 git URL：`https://`、`http://`、`file://` 或 `git@`。不需要 `.git` 后缀，所以 Azure DevOps 和 AWS CodeCommit URL 可以按原样工作。此类型不采用 `owner/repo` 简写。

```json theme={null}
{
  "name": "formatter",
  "source": {
    "source": "url",
    "url": "https://gitlab.example.com/your-group/formatter.git",
    "ref": "main"
  }
}
```

<h3 id="git-subdir-plugin-source">
  git-subdir plugin source
</h3>

`url` 接受完整的 git URL 或 GitHub `owner/repo` 简写。`path` 是保存插件的子目录，Claude Code 仅下载该子目录。

```json theme={null}
{
  "name": "formatter",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/your-org/monorepo.git",
    "path": "tools/formatter"
  }
}
```

<h3 id="npm-plugin-source">
  npm plugin source
</h3>

一个 `npm` 源采用这些字段：

* `package`：一个包名，或一个作用域名，如 `@your-org/formatter`
* `version`：一个版本或范围
* `registry`：一个不在默认 registry 上的包的 registry URL

Claude Code 使用你的 npm 客户端获取包。包的安装脚本，如 `preinstall` 或 `postinstall`，永远不会运行，其依赖项在获取期间不会被安装。如果包在其 `package.json` 旁边有一个支持的 lockfile，Claude Code 在单独的步骤中安装这些 [Node.js 包依赖项](/docs/zh-CN/plugins/loading#node-js-package-dependencies)，也禁用脚本。

```json theme={null}
{
  "name": "formatter",
  "source": {
    "source": "npm",
    "package": "@your-org/formatter",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}
```

<h3 id="archive-plugin-source">
  archive plugin source
</h3>

`url` 必须使用 `https://`，不能指向环回、链接本地或云元数据主机。

插件根可能在 zip 的顶部或下一个目录。

`sha256` 是存档的摘要，为 64 个十六进制字符，大写或小写。当你设置它时，Claude Code 拒绝不匹配的下载。

```json theme={null}
{
  "name": "formatter",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/formatter-2.0.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}
```

<h3 id="command-plugin-source">
  command plugin source
</h3>

当安装在用户机器上的工具生成插件目录时，使用 `command` 源，如一个为用户选择的工具链呈现其插件的 IDE。Claude Code 在用户安装或更新插件时运行该命令，并[每个会话再运行一次](/docs/zh-CN/plugins/loading#when-a-command-source-re-runs)，所以用户无需重新安装就能获得工具的更改输出。

一个 `command` 源采用这些字段：

* `command`：一个 shell 命令，打印插件目录的绝对路径作为一行并退出 0。Claude Code 在运行前向用户显示整个字符串以供审查。将其写为可打印的 ASCII，最多 500 个字符，没有四个或更多空格的连续。
* `timeout`：从 1 到 600 的整数秒数。默认为 60。
* `mode`：`copy`（默认）或 `link`。参见 [Copy mode and link mode](#copy-mode-and-link-mode)。

```json theme={null}
{
  "name": "formatter",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path",
    "timeout": 120
  }
}
```

有关用户如何接受命令的信息，请参阅 [Install from your shell](/docs/zh-CN/plugins/install#install-from-your-shell)。有关你更改它后用户看到的内容，请参阅 [Change the command of a command source](/docs/zh-CN/plugins/host-marketplace#change-the-command-of-a-command-source)。管理员使用 [`disableCommandPluginSources`](/docs/zh-CN/settings-reference#disablecommandpluginsources) 关闭命令源。

<h4 id="what-the-command-must-do">
  What the command must do
</h4>

编写命令以满足这些要求：

* **Shell 和工作目录**：Claude Code 通过 `sh` 运行命令，或在 Windows 上通过 `cmd.exe`，从用户的主目录。给出绝对路径或 `PATH` 上的命令。
* **输出**：在 stdout 上打印恰好一行，插件目录的绝对路径，并在 `timeout` 秒内退出 0。
* **目录内容**：该目录在命令退出时保存完整的插件。路径可能因运行而异。

<h4 id="output-that-fails-the-install-or-update">
  Output that fails the install or update
</h4>

当命令退出非零、运行时间超过 `timeout` 或打印除一个绝对路径之外的任何内容时，安装或更新失败。当打印的目录是以下之一时，它也会失败：

* **没有插件内容**：打印的目录在其顶级没有插件内容，如 `.claude-plugin/` 目录或 `skills/`、`commands/`、`agents/` 或 `hooks/` 目录。
* **会话自己的目录**：打印的目录是 Claude Code 启动的目录，或其父目录之一。
* **网络路径**：在 Windows 上，打印的路径是 UNC 路径。
* **太大而无法复制**：在复制模式下，目录大于 256 MiB 或有超过 20,000 个条目。

<h4 id="copy-mode-and-link-mode">
  Copy mode and link mode
</h4>

`mode` 决定 Claude Code 是复制打印的目录还是就地使用它：

* **`copy`**：Claude Code 将目录复制到插件缓存中，并从复制文件的哈希值派生[插件版本](/docs/zh-CN/plugins/loading#how-claude-code-computes-the-version)。你的工具可以在命令退出后删除或重写目录。产生相同文件的重新运行计为最新。
* **`link`**：Claude Code 用指向打印目录的每个顶级条目的链接填充插件的缓存条目，并就地加载文件。不复制任何内容，文件内容不被哈希，大小限制不适用。对于太大而无法复制的目录（如呈现的 SDK 导出），使用它。

链接模式插件有这些要求：

* **保持目录就位**：Claude Code 在每次启动时通过链接加载插件，所以打印的目录必须保持在原位，只要插件保持安装。
* **打印不同的路径以表示新内容**：版本来自打印目录的真实路径及其顶级条目，而不是其中的文件。
* **保持顶级符号链接在目录内**：如果顶级条目是指向打印目录外的符号链接，安装失败。
* **包含 `node_modules`**：Claude Code 跳过链接模式插件的 [Node.js 包依赖项安装](/docs/zh-CN/plugins/loading#node-js-package-dependencies)，所以打印一个已经包含插件需要的包的目录。
* **在目录内启动的会话**：在打印目录或其下方任何地方启动的会话不加载插件。
* **不在 Windows 上**：Claude Code 拒绝在 Windows 上安装链接模式插件。在那里声明 `"mode": "copy"`。

<h2 id="marketplace-sources">
  Marketplace 源
</h2>

marketplace 源说明 Claude Code 从哪里获取 `marketplace.json`。CLI 在你添加 marketplace 时为你构建一个，你在设置中自己编写一个：

* **[`claude plugin marketplace add`](/docs/zh-CN/plugins/cli-reference)**：Claude Code 从你传递的字符串构建源。
* **[`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces)**：你自己将源写成 `source` 对象。
* **[`strictKnownMarketplaces`](/docs/zh-CN/settings-reference#strictknownmarketplaces) 和 [`blockedMarketplaces`](/docs/zh-CN/plugins/org#restrict-what-users-can-install)**：管理员在这两个策略列表中编写源。`strictKnownMarketplaces` 是允许列表，`blockedMarketplaces` 是阻止列表。

类型名称 `url`、`git` 和 `github` 在 marketplace 源中的含义与在 [插件源](#plugin-sources) 中不同：

| 类型名称     | 作为 marketplace 源                                                  | 作为插件源                                         |
| :------- | :---------------------------------------------------------------- | :-------------------------------------------- |
| `url`    | 直接链接到 `marketplace.json` 文件，字段为 `url`、`headers` 和 `headersHelper` | 要克隆的 git 存储库，字段为 `url`、`ref` 和 `sha`          |
| `git`    | 要克隆的 git 存储库，字段为 `url`、`ref`、`path` 和 `sparsePaths`               | 不存在                                           |
| `github` | GitHub 存储库，字段为 `repo`、`ref`、`path` 和 `sparsePaths`                | GitHub 存储库，字段为 `repo`、`ref` 和 `sha`，没有 `path` |

该表列出每个 marketplace 源类型及其字段、产生它的 `claude plugin marketplace add` 输入，以及它在三个设置键中的作用。

| 类型            | 字段                                | `marketplace add` 输入                                                                                        | `extraKnownMarketplaces`                           | `strictKnownMarketplaces`                                                                                                                                   | `blockedMarketplaces`          |
| :------------ | :-------------------------------- | :---------------------------------------------------------------------------------------------------------- | :------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------- |
| `url`         | `url`、`headers`、`headersHelper`   | 不匹配 git 形式的 `http://` 或 `https://` URL                                                                      | 加载                                                 | 允许相同的 URL                                                                                                                                                   | 阻止相同的 URL                      |
| `github`      | `repo`、`ref`、`path`、`sparsePaths` | `owner/repo`、`owner/repo@ref` 或 `owner/repo#ref`                                                            | 加载                                                 | 允许相同的 `repo`、`ref` 和 `path`。`repo` 可能是 `owner/*`                                                                                                            | 阻止相同的，以及到相同存储库的 `git` URL      |
| `git`         | `url`、`ref`、`path`、`sparsePaths`  | `user@host:path` URL，或以 `.git` 结尾、包含 `/_git/` 或命名 github.com 或 gitlab.com 存储库的 `https://` URL。`#ref` 固定 ref | 加载                                                 | 允许相同的 URL、`ref` 和 `path`                                                                                                                                    | 阻止相同的，以及相同 github.com 存储库的其他拼写 |
| `npm`         | `package`                         | 未产生                                                                                                         | 加载失败：`NPM marketplace sources not yet implemented` | 解析但不匹配任何内容，因为没有任何内容注册 `npm` marketplace                                                                                                                     | 解析但不匹配任何内容                     |
| `file`        | `path`                            | `.json` 文件的路径                                                                                               | 加载                                                 | 允许相同的路径                                                                                                                                                     | 阻止相同的路径                        |
| `directory`   | `path`                            | 目录的路径                                                                                                       | 加载                                                 | 允许相同的路径                                                                                                                                                     | 阻止相同的路径                        |
| `settings`    | `name`、`plugins`、`owner`          | 未产生                                                                                                         | 加载                                                 | 允许具有相同 `name` 和相同 `plugins` 的条目                                                                                                                             | 阻止相同的 `name`                   |
| `skills-dir`  | none                              | 未产生                                                                                                         | 加载失败：`Unsupported marketplace source type`         | 保持 [skills-directory 插件](/docs/zh-CN/plugins/org#keep-skills-directory-plugins-loading) 在设置允许列表时加载。请参阅 [仅在策略列表中有效的源值](#source-values-valid-only-in-policy-lists) | 停止 skills-directory 插件加载       |
| `hostPattern` | `hostPattern`                     | 未产生                                                                                                         | 加载失败：`Unsupported marketplace source type`         | 允许主机匹配的 `github`、`git` 和 `url` 源                                                                                                                            | 阻止这些源                          |
| `pathPattern` | `pathPattern`                     | 未产生                                                                                                         | 加载失败：`Unsupported marketplace source type`         | 允许 `path` 匹配的 `file` 和 `directory` 源                                                                                                                        | 阻止这些源                          |

<h3 id="fields-by-type">
  按类型的字段
</h3>

该表列出每个具有默认值、约束或特定于其类型的含义的 marketplace 源字段。

| 字段              | 类型             | 描述                                                                                                                                                                           |
| :-------------- | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`           | `url`          | 指向 `marketplace.json` 文件的链接。Claude Code 仅下载该文件，因此 marketplace 的插件不能使用 [相对路径源](#relative-path-plugin-source)                                                                  |
| `url`           | `git`          | 要克隆的 git 存储库                                                                                                                                                                 |
| `headers`       | `url`          | Claude Code 随获取发送的 HTTP 标头映射，用于经过身份验证的主机                                                                                                                                     |
| `headersHelper` | `url`          | 打印标头的命令，其值太短暂而无法在 `headers` 中列出。需要 Claude Code v2.1.238 或更高版本。请参阅 [验证 archive 下载](/docs/zh-CN/plugins/host-marketplace#authenticate-archive-downloads)                            |
| `repo`          | `github`       | 在 `marketplace add` 和 `extraKnownMarketplaces` 中，`repo` 必须命名一个存储库。`marketplace add` 拒绝 `owner/*` 作为无效的 `owner/repo` 简写；在 `extraKnownMarketplaces` 中 Claude Code 按字面意思取它，克隆失败 |
| `ref`           | `github`、`git` | 分支或标签。默认为存储库的默认分支                                                                                                                                                            |
| `path`          | `github`、`git` | marketplace 文件在存储库内的路径。默认为 `.claude-plugin/marketplace.json`                                                                                                                 |
| `path`          | `file`         | marketplace 文件本身。Claude Code 就地读取它，并将上两级的目录作为 marketplace 根目录，因此将文件保持在 `<root>/.claude-plugin/marketplace.json`                                                              |
| `path`          | `directory`    | marketplace 根目录，包含 `.claude-plugin/marketplace.json` 的目录                                                                                                                     |
| `sparsePaths`   | `github`、`git` | 用于稀疏检出的目录数组，如 `[".claude-plugin", "plugins"]`。`claude plugin marketplace add --sparse` 设置它                                                                                   |
| `skipLfs`       | `github`、`git` | 接受且无效果。请参阅 [保持插件文件不在 Git LFS 中](/docs/zh-CN/plugins/host-marketplace#keep-plugin-files-out-of-git-lfs)                                                                            |
| `name`          | `settings`     | 必须等于 `extraKnownMarketplaces` 键，不能是 [保留名称](#reserved-names)                                                                                                                  |
| `plugins`       | `settings`     | 内联目录，没有托管文件。每个项采用 `name`、`source`、`description`、`version`、`strict`、`headers` 和 `headersHelper`。将每个项的 `source` 写成对象类型，因为相对路径没有存储库来解析                                          |

<h3 id="source-values-valid-only-in-policy-lists">
  仅在策略列表中有效的源值
</h3>

`hostPattern`、`pathPattern`、`skills-dir` 和 `repo` 的 `owner/*` 形式仅在两个策略列表中有效，`strictKnownMarketplaces` 和 `blockedMarketplaces`：

* **`hostPattern` 和 `pathPattern`**：Claude Code 在获取前针对源测试的正则表达式。
* **`skills-dir`**：不是源。如果你设置 `strictKnownMarketplaces`，[skills-directory 插件](/docs/zh-CN/plugins/org#keep-skills-directory-plugins-loading) 停止加载，直到你将 `{"source": "skills-dir"}` 添加到该列表。
* **`owner/*`**：作为 `github` `repo` 值，匹配恰好该 GitHub 所有者下的每个存储库。需要 Claude Code v2.1.223 或更高版本。

有关匹配顺序、精确 `ref` 语义和配方，请参阅 [为你的组织管理插件](/docs/zh-CN/plugins/org)。

<h3 id="source-objects-in-settings">
  设置中的源对象
</h3>

`extraKnownMarketplaces` 值是从 marketplace 名称到具有 `source` 的对象的映射。此条目从其 `main` 分支的 git 存储库注册 marketplace：

```json theme={null}
{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/your-org/your-marketplace.git",
        "ref": "main"
      }
    }
  }
}
```

`strictKnownMarketplaces` 和 `blockedMarketplaces` 是源对象的数组。此允许列表允许一个 GitHub 所有者和一个内部主机：

```json theme={null}
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "your-org/*" },
    { "source": "hostPattern", "hostPattern": "^git\\.example\\.com$" }
  ]
}
```

<h2 id="validation-messages">
  验证消息
</h2>

`claude plugin validate <path>` 接受 marketplace 根目录或 marketplace 文件本身。它打印错误和警告。有关退出代码和 `--strict`，请参阅 [plugin validate](/docs/zh-CN/plugins/cli-reference#plugin-validate)。

消息通过索引命名插件条目，写作 `plugins.1.source` 或 `plugins[1].source`。

以条目索引和 `plugin.json →` 为前缀的消息，例如 `plugins[2] plugin.json →`，涉及该插件自己的文件。[`claude plugin validate` 报告错误](/docs/zh-CN/plugins/troubleshooting#claude-plugin-validate-reports-errors) 列出这些消息及其修复。

提及 Claude Desktop 标志名称的警告，这些名称 Claude Code 接受但 Claude Desktop 拒绝，因为 Claude Desktop 的名称规则更严格。

该表将 marketplace 级别的消息映射到每个消息所涉及的字段。

| 消息                                                                                                                                                                                                  | 级别 | 字段                                                                                  |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :- | :---------------------------------------------------------------------------------- |
| `Marketplace must have a name`                                                                                                                                                                      | 错误 | `name` 为空                                                                           |
| `Marketplace name cannot contain spaces. Use kebab-case (e.g., "my-marketplace")`                                                                                                                   | 错误 | `name`                                                                              |
| `Marketplace name cannot contain path separators (/ or \), ".." sequences, or be "."`                                                                                                               | 错误 | `name`                                                                              |
| `Marketplace name impersonates an official Anthropic/Claude marketplace`                                                                                                                            | 错误 | `name`。请参阅 [Reserved names](#reserved-names)                                        |
| `Marketplace name cannot contain control or bidirectional-formatting characters`                                                                                                                    | 错误 | `name` 包含控制字符，例如转义或换行符，或 Unicode 双向格式化字符                                            |
| `Marketplace name "inline" is reserved for --plugin-dir session plugins`, and the `builtin`, `skills-dir`, `synced`, `claude-plugin-test`, `npm`, `pip`, `uv`, `cargo`, `github`, and `gh` variants | 错误 | `name`                                                                              |
| `Author name cannot be empty`                                                                                                                                                                       | 错误 | `owner.name`                                                                        |
| `Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin")`                                                                                                                             | 错误 | `plugins[i].name`                                                                   |
| `Plugin name cannot contain control or bidirectional-formatting characters`                                                                                                                         | 错误 | `plugins[i].name`                                                                   |
| `Duplicate plugin name "x" found in marketplace`                                                                                                                                                    | 错误 | 两个条目共享一个 `name`                                                                     |
| `plugins.i.source: Invalid input`                                                                                                                                                                   | 错误 | 该条目的 `source` 与任何类型都不匹配。请参阅 [Invalid input on a source](#invalid-input-on-a-source) |
| `plugins[i].source: Path contains "..": <path>`                                                                                                                                                     | 错误 | 转义 marketplace 根目录的相对 `source`                                                      |
| `source.source: 'unsupported' is a parse-time placeholder and cannot be authored`                                                                                                                   | 错误 | `plugins[i].source`                                                                 |
| `Plugin "x" sets headersHelper but is not "strict": false`                                                                                                                                          | 错误 | `plugins[i].headersHelper`，在 `archive` 条目上                                          |
| `chain does not resolve (<reason>) — target must be a name in plugins[], a key in renames, or null`                                                                                                 | 错误 | `renames.<old>`                                                                     |
| `target "x" is not a valid plugin name (PluginIdSchema)`                                                                                                                                            | 错误 | `renames.<old>`                                                                     |
| `Unknown field 'x'. Claude Code ignores it at load time.`                                                                                                                                           | 警告 | 顶级、`metadata` 下、条目中或条目的 `relevance` 下的命名键                                           |
| `Marketplace has no plugins defined`                                                                                                                                                                | 警告 | `plugins` 为空                                                                        |
| `Plugin "x" sets headers/headersHelper, which only apply to "archive" sources; they have no effect on this entry.`                                                                                  | 警告 | `plugins[i].headers` 或 `plugins[i].headersHelper`，在 `source` 不是 `archive` 的条目上      |
| `Plugin "x" fetches its archive with a headersHelper but sets no sha256 pin`                                                                                                                        | 警告 | `plugins[i].source.sha256`                                                          |
| `Header "x" is a request-routing/identity header that catalog entries may not set; Claude Code drops it at download time.`                                                                          | 警告 | `plugins[i].headers.<name>`                                                         |
| `Local source "x" is or traverses a symlink, so <path> was not read`                                                                                                                                | 警告 | `plugins[i].source`                                                                 |
| `No marketplace description provided. Adding a description helps users understand what this marketplace offers`                                                                                     | 警告 | `description`                                                                       |
| `Entry declares version "x" but <path>/plugin.json says "y". At install time, plugin.json wins`                                                                                                     | 警告 | `plugins[i].version`，在相对路径条目上                                                       |
| `'relevance' must be an object containing topic and signals; got <type>. It will be ignored at load time.`                                                                                          | 警告 | `plugins[i].relevance`                                                              |
| `'metadata' must be a free-form object; got <type>. It will be ignored at load time.`                                                                                                               | 警告 | `plugins[i].metadata`                                                               |
| `'experimental' must be an object containing component declarations; got <type>. It will be ignored at load time.`                                                                                  | 警告 | `plugins[i].experimental`                                                           |
| `Marketplace name "x" is reserved in Claude Desktop`                                                                                                                                                | 警告 | `name` 是 `org`、`org-provisioned` 或 `unknown`。Claude Desktop 拒绝该 marketplace         |
| `Marketplace name "x" is not accepted by Claude Desktop (letters, digits, ".", "_", "-"; must start alphanumeric; max 128 chars)`                                                                   | 警告 | `name`。Claude Desktop 拒绝该 marketplace                                               |
| `Plugin name "x" is not accepted by Claude Desktop (letters, digits, ".", "_", "-"; must start alphanumeric; max 128 chars)`                                                                        | 警告 | `plugins[i].name`。Claude Desktop 删除该条目                                              |

<h3 id="invalid-input-on-a-source">
  Invalid input on a source
</h3>

`source` 上的 `Invalid input` 意味着该对象与任何源类型都不匹配。检查这些原因：

* 不以 `./` 开头的相对路径，除了 `"."` 或 `metadata.pluginRoot` 下的裸名称
* 包含 `..` 的 `npm` `package`
* 不是 [plugin sources](#plugin-sources) 之一的 `source` 类型
* 已知类型缺少必需字段或字段类型错误，例如没有 `repo` 的 `github`

<h3 id="failures-that-validation-doesn’t-catch">
  验证未捕获的失败
</h3>

`claude plugin validate` 不会报告每个失败。写作文件路径或数组的条目 `hooks` 通过验证，错误仅在插件加载时出现，如 [Hooks in an entry](#hooks-in-an-entry) 所述。获取 `source` 的错误也仅在安装后出现，不在验证中出现。

[`claude plugin list`](/docs/zh-CN/plugins/cli-reference) 显示加载失败的插件及其错误，[Troubleshoot plugins](/docs/zh-CN/plugins/troubleshooting) 涵盖加载时字符串。

<h2 id="next-steps">
  后续步骤
</h2>

* [创建 marketplace](/docs/zh-CN/plugins/create-marketplace)：从这些字段构建 marketplace 并在本地安装
* [托管和维护 marketplace](/docs/zh-CN/plugins/host-marketplace)：放置文件的位置以及用户如何接收更改
* [插件清单参考](/docs/zh-CN/plugins/manifest-reference)：条目可以覆盖的 `plugin.json` 字段
* [为你的组织管理插件](/docs/zh-CN/plugins/org)：使用这些源值的允许列表和阻止列表配方