托管和维护一个 marketplace

​

托管你的 marketplace

​

为仓库中的每个人注册 marketplace

​

避免在 URL 托管的 marketplace 中使用相对路径条目

​

在共享目录上就地编辑插件

​

将插件文件保留在 Git LFS 之外

​

使用符号链接在 marketplace 内共享文件

• 在插件自己的目录内：符号链接在缓存中被保留为相对符号链接，因此它在运行时继续解析到复制的目标。
• 在同一 marketplace 内的其他地方：符号链接被解引用。目标的内容被复制到缓存中以代替它。这允许元插件的 skills/ 目录链接到 marketplace 中其他插件定义的技能。
• 在 marketplace 外：符号链接因安全原因被跳过。

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

通过组织设置分发

• Marketplace 仓库：在 github.com 和 gitlab.com 上，它必须是私有或内部的
• 插件源：每个插件源必须是 github、url 或 git-subdir 类型，或以 ./ 开头的 相对路径
• 顶级 bin/ 目录：claude.ai 拒绝具有一个的插件并同步 marketplace 的其余部分。错误消息以 Plugin contains a top-level bin/ directory 开头。将可执行文件保留在另一个目录中，如 scripts/，并从你的 hooks 或 MCP 服务器配置中将它们引用为 ${CLAUDE_PLUGIN_ROOT}/scripts/<name>

​

授予对私有 marketplace 的访问权限

• GitHub owner/repo：Claude Code 探测 ssh -T git@github.com，当探测成功时通过 SSH 克隆。如果探测失败，或 SSH 克隆本身失败，它通过 HTTPS 克隆。没有 GitHub SSH 密钥的机器上的用户可以设置 CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 来跳过探测并通过 HTTPS 克隆。
• git@host:path.git：SSH。
• https://example.com/repo.git：HTTPS。

• SSH：密钥必须在没有密码提示的情况下工作，例如因为它被加载到 ssh-agent 中。主机必须已经在 known_hosts 中。
• HTTPS：Claude Code 保持用户的 git 凭证助手启用，但禁止它提示。助手已经存储的凭证有效；它必须要求的凭证失败。在 GitHub 上，gh auth login 后跟 gh auth setup-git 存储一个。

​

为没有 git 主机账户的用户提供服务

• archive：通过 HTTPS 下载的 zip。用户既不需要 git 也不需要账户，只需要对 URL 的网络访问。需要 Claude Code v2.1.224 或更高版本。用 sha256 固定每个存档，以便 Claude Code 拒绝更改的下载。要随下载发送凭证，请参阅 认证存档下载。
• 公共 git 仓库：当条目给出 https:// URL 时，Claude Code 通过 HTTPS 克隆公共 url 或 git-subdir 源，无需凭证。对于 github 源或写成 owner/repo 的 git-subdir 源，没有 GitHub SSH 密钥的用户设置 CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1。

​

后台自动更新对凭证的处理

• SSH 远程：加载到 ssh-agent 中的密钥认证检查。
• 具有存储凭证的 HTTPS 远程：可以在不提示的情况下提供存储凭证的助手认证检查。Git Credential Manager、macOS Keychain 助手和 git-credential-store 一旦为主机持有凭证就以这种方式工作。
• 具有需要提示的助手的 HTTPS 远程：助手无法在后台回答。更新失静地失败，现有检出保持原位，因此用户的插件继续从最后同步的状态工作。

• 检出是最新的：Claude Code 保持原样。
• 检查找到新提交，或因为无法到达或认证到远程而失败：Claude Code 再次克隆 marketplace 并用新克隆替换现有检出。如果该克隆失败，现有检出保持原位。重新克隆可以 在大型仓库上超时。

• 存储凭证：首先登录凭证助手，以便它为主机持有凭证。对于 GitHub，运行 gh auth login，然后 gh auth setup-git。
• 在失败时保持检出：如果用户设置 CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1，当后台检查无法到达或认证到远程时，Claude Code 保持现有检出而不尝试重新克隆。插件继续从最后同步的状态工作。

​

向整个公司推出

• 不需要 git 账户的条目源：为没有 git 主机账户的用户提供服务
• 预填充的插件目录：为容器和 CI 播种，也为没有 git 主机账户的用户提供服务
• claude.ai 组织设置：通过组织设置分发，你的用户的 git 凭证不涉及

​

保持用户最新

​

打开自动更新

• 告诉用户打开它：每个用户进入 /plugin 中的 Marketplaces，选择你的 marketplace，并选择 启用自动更新。
• 要求管理员设置它：如果管理员在托管设置中的你的 marketplace 的 extraKnownMarketplaces 条目上设置 "autoUpdate": true，它对接收这些设置的每个人都打开。请参阅 设置更新策略。

​

发布新版本

• 在每次发布时提升 version：用户停留在他们的缓存副本上，直到字符串改变。如果你设置 "version": "1.0.0" 并推送新提交而不改变它，用户不会接收它们。
• 省略 version：用户改为跟踪你的提交。将 version 保留在 plugin.json 和 marketplace 条目之外。

​

将用户保持在一个版本上

• 插件条目上的 ref 和 sha：ref 命名分支或标签，sha 为 github、url 或 git-subdir 源命名提交。请参阅 插件源。
• 添加命令上的 #<ref>：添加 your-org/your-marketplace#stable 的用户获得该目录的分支或标签。对于两条发布线同时进行，请参阅 运行发布渠道。
• <plugin>--v<version> 标签：依赖的版本范围针对这些标签解析。请参阅 发布其他人依赖的插件。

​

更改命令源的命令

• 不再有后台运行：该用户的命令的 每会话一次运行 停止，因此工具的新输出不会到达他们。
• /plugin 错误选项卡中的条目：条目显示新命令和要运行的 claude plugin update 命令。

​

运行发布渠道

{
  "name": "stable-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "stable" } }
  ]
}

{
  "name": "latest-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "latest" } }
  ]
}

​

重命名或删除插件

​

使用重命名映射迁移用户

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

• 重命名的条目：插件在其新名称下加载。claude plugin list 和 /plugin 下的插件详情显示 Renamed to "code-formatter" in the "your-marketplace" marketplace 一次，Claude Code 在用户、项目和本地设置范围中将旧键重写为 enabledPlugins 和 pluginConfigs 中的新键。
• null 条目：旧键从这些范围中删除，用户看到 Removed from the "your-marketplace" marketplace。
• 在托管设置中启用：插件仍然在其新名称下加载，但 Claude Code 无法重写托管设置，所以通知重复出现，直到管理员在那里更新 enabledPlugins。

​

从用户机器卸载已删除的插件

1. 比较用户从你的 marketplace 安装的内容与条目和 renames 映射，并将既不列出也不重命名的任何插件视为已删除。
2. 从用户、项目和本地范围卸载每个已删除的插件。仅托管设置安装的插件保持原位。
3. 在 /plugin 中的 Flagged 标题下列出每个已删除的插件，状态为 Removed from marketplace。

​

认证存档下载

• Marketplace 的 url 源：你注册 marketplace 的 url 源，如 extraKnownMarketplaces 条目。
• 插件的条目：在 Claude Code v2.1.238 或更高版本上，你可以改为在插件的 marketplace.json 条目上设置它，在 source 旁边。

​

向插件条目添加 headersHelper

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

​

编写 headersHelper 命令

• 命令文本：最多 500 个可打印 ASCII 字符，没有四个或更多空格的运行。
• 输出：在 stdout 上打印一个标头名称和字符串值的 JSON 对象，然后在 10 秒内退出 0。
• Shell 和工作目录：Claude Code 通过 sh 运行命令，或在 Windows 上通过 cmd.exe。工作目录是配置目录，即 ~/.claude 或 CLAUDE_CONFIG_DIR。给出绝对路径或 PATH 上的命令，因为相对路径针对该目录解析，而不是用户的项目。
• Claude Code 删除的变量：当命令在 marketplace.json 条目中设置，或在项目的 .claude/settings.json 或 .claude/settings.local.json 中设置时，Claude Code 从环境中删除每个名称看起来像凭证的变量，通过 它应用于 MCP headersHelper 的相同规则。ANTHROPIC_API_KEY 和 MY_REGISTRY_TOKEN 都被删除，所以让命令从文件或凭证存储读取其凭证。此删除不适用于在用户设置、--settings 文件或托管设置中设置的命令。
• Claude Code 设置的变量：对于 url 源的命令为 CLAUDE_CODE_MARKETPLACE_URL 和 CLAUDE_CODE_MARKETPLACE_NAME，对于条目的命令为 CLAUDE_CODE_PLUGIN_NAME 和 CLAUDE_CODE_PLUGIN_ARCHIVE_URL。CLAUDE_CODE_MARKETPLACE_NAME 在用户通过 URL 添加 marketplace 后的第一次获取时未设置，因为该获取是提供名称的。

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

​

当 Claude Code 跳过 headersHelper 命令或删除其输出时

• 命令失败：如果命令退出非零、运行超过 10 秒或打印除 JSON 对象的字符串值以外的任何内容，命令运行的获取或下载不会发生。
• Marketplace URL 不以 https:// 开头：该 url 源的命令不运行，请求仅携带其 headers 字段中列出的标头。
• 重定向离开源：当下载被重定向离开存档 URL 的源时，重定向的请求不携带来自 marketplace url 源或插件条目的 headers 值或命令输出。
• 条目设置路由或身份标头：Claude Code 从条目的 headers 和命令输出中删除请求路由和客户端身份名称，如 Host、Cookie 和 X-Forwarded-*，并保持认证名称，如 Authorization。每个 marketplace.json 条目都以这种方式过滤。对于设置中的内联插件条目，请参阅 extraKnownMarketplaces。
• 命令在 --add-dir 目录的设置中设置：命令被忽略，在 url 源和 内联插件条目 上，仅该文件的 headers 被发送。
• 托管设置阻止命令：将 disableCommandPluginSources 设置为 true 阻止 headersHelper 命令，allowManagedHooksOnly 也阻止它们，除非 disableCommandPluginSources 明确为 false。在任一块下，Claude Code 仍然为托管设置本身声明的 marketplace 运行命令。

​

用户如何接受 headersHelper 命令

​

拒绝命令而不是询问的安装和更新

• 一次安装多个插件、来自插件建议或作为另一个插件的依赖：Claude Code 拒绝具有命令的插件并将用户指向 /plugin 中的该插件自己的视图。批量安装中的其他插件仍然安装。依赖于被拒绝插件的插件无法安装，直到用户自己安装被拒绝的插件。
• 后台自动更新，或会话启动以获取其存档从未下载的插件：Claude Code 在 /plugin 错误选项卡中列出插件，以便用户知道自己安装或更新它。

​

当 marketplace url 源的命令运行时

​

依赖和推荐其他插件

• 版本范围：依赖可以携带 semver 范围。
• 跨 marketplace 依赖：来自另一个 marketplace 的依赖仅在你的 marketplace 在 allowCrossMarketplaceDependenciesOn 中列出该 marketplace 时安装。

​

解决 marketplace 无法做的事情

• 限制用户安装的其他内容：marketplace 允许列表是托管设置 strictKnownMarketplaces。请参阅 限制用户可以安装的内容。
• 在用户询问之前安装或启用插件：没有条目字段安装插件。托管 enabledPlugins 为一个舰队执行此操作；请参阅 预安装和要求插件。
• 向不同用户显示不同的条目：条目不携带受众字段，添加 marketplace 的每个用户看到整个目录。为不同的受众托管单独的 marketplace。
• 标记插件已弃用：没有弃用状态。选项是删除条目，在 renames 中将其名称映射到 null，并可选地设置 forceRemoveDeletedPlugins。
• 为你的用户打开自动更新：每个用户在 /plugin 中的 Marketplaces 下打开它，或管理员在托管设置中设置 autoUpdate。请参阅 打开自动更新。
• 携带 git 凭证：没有 marketplace 字段持有 git 令牌。对 git 托管的 marketplace 或插件的访问遵循用户的 git 设置，根据 授予对私有 marketplace 的访问权限。对于 archive 源，条目可以改为设置 headers 或 headersHelper。

​

后续步骤

• Marketplace 参考：marketplace.json 字段、源类型和验证消息
• 为你的组织管理插件：在你的组织的机器上要求、限制或播种你的 marketplace
• 插件依赖：标记发布，以便依赖你的插件的插件可以解析版本
• 排查插件问题：你的用户在从你的 marketplace 添加或更新时看到的错误