第 8 章 · 02 市场与分发

第 8 章 · 02 市场与分发

本节摘要:插件靠市场(marketplace)分发——市场是一个插件目录(manifest 定义在 .claude-plugin/marketplace.json),每个插件条目声明名称与来源(六种:相对路径、GitHub、Git URL、Git 子目录、npm、pip)。官方市场自动注册,社区市场手动添加。安装、更新、禁用、卸载全部有 /plugin 界面与 CLI 双通道;自动更新默认只对官方市场开启。版本锁定靠 ref/sha 字段,发布靠 claude plugin tag 打带校验的 git 标签。

学习目标

阅读完本节,你应当能够:

1. 说出四种插件类型(官方/社区/组织/个人)与各自权威来源。
2. 写出 marketplace.json 并说出六种 source 语法与版本锁定方式。
3. 说出 /plugin 与 claude plugin 命令族,以及安装生命周期各环节。
4. 说出自动更新的默认行为与三个相关环境变量。

一、插件类型与市场生态

官方市场 anthropics/claude-plugins-official 首次交互启动时自动注册;社区市场 anthropics/claude-plugins-community 托管通过自动化验证与安全筛查的第三方插件,手动添加:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install <plugin-name>@claude-community
​

二、marketplace.json:市场定义

市场本身也是配置文件,放在 .claude-plugin/marketplace.json:

{
  "name": "my-team-plugins",
  "owner": "my-org",
  "plugins": [
    {
      "name": "code-standards",
      "source": "./plugins/code-standards",
      "description": "Enforce team coding standards",
      "version": "1.2.0",
      "author": "platform-team"
    },
    {
      "name": "deploy-helper",
      "source": { "source": "github", "repo": "my-org/deploy-helper", "ref": "v2.0.0" },
      "description": "Deployment automation workflows"
    }
  ]
}
​

必填:市场 name(kebab-case)、owner、plugins 数组;插件条目必填 name 与 source(路径字符串或来源对象),可选 description/version/author;另有 renames(旧名→新名映射,用户自动迁移,v2.1.193+)、displayName(仅展示,v2.1.143+)、defaultEnabled: false(装好后默认禁用需用户开启,v2.1.154+)。

六种来源语法

GitHub 与 Git 来源支持 ref(分支/标签)与 sha(提交哈希)做版本锁定。注意保留名:first-party-plugins 与 healthcare 不可被自定义市场占用(v2.1.205+)。

三、生命周期:发现到卸载

发现 → 浏览市场 → 查看组件 → /plugin install → 使用 → 更新 → 禁用/启用 → 卸载
​

安装途径:

/plugin install plugin-name              # 会话内
claude plugin install plugin-name@marketplace-name   # CLI
/plugin install github:username/repo     # 直接 GitHub 仓库
/plugin install ./path/to/plugin         # 本地目录
claude --plugin-dir ./my-plugin          # 本地开发测试(可重复,支持 .zip,v2.1.128+)
claude --plugin-url https://example.com/releases/my-plugin-0.3.0.zip   # URL 拉取,当前会话有效
​

CLI 命令族:

claude plugin install/uninstall/update/list/enable/disable <name>
claude plugin validate                   # 校验结构
claude plugin tag v0.3.0                 # 校验版本号并打 git 标签(发布推荐方式)
claude plugin prune                      # 清理孤儿自动安装的依赖插件
claude plugin uninstall <name> --prune   # 卸载并级联清理
claude plugin details <name>             # 组件清单 + 预估每回合 token 成本(v2.1.139+)
​

details 很有用——安装前先看"这插件每回合吃多少上下文",示例输出:3 skills / 2 hooks / 1 mcp,projected ctx +1,420 tokens per turn、+9,800 per /review 调用。市场浏览面板同样显示 CTX/TURN 列(v2.1.143+),按上下文成本挑选插件。

依赖管理(v2.1.143+):plugin disable 在仍有其他启用插件依赖它时会拒绝执行(防止依赖图断裂);plugin enable 会在一次确认后级联启用传递依赖;plugin prune 清理父插件已删除的孤儿依赖。plugin list 支持 --enabled/--disabled 过滤(v2.1.163+),/plugin 界面会标出未使用插件方便清理(v2.1.187+)。

市场管理:

claude plugin marketplace add <source>
claude plugin marketplace update [name]   # 只刷新目录,不更新已装插件
claude plugin marketplace remove <name>
claude plugin marketplace list
​

严格模式:strict: true(默认)时本地 plugin.json 优先,市场条目补充;false 时市场条目即全部定义。组织可用 strictKnownMarketplaces 限制可添加的市场(空数组 = 全部禁止;模式数组 = 白名单)。

四、自动更新与版本控制

官方市场默认自动更新(启动时刷新目录+更新已装插件+提示 /reload-plugins);第三方/本地市场默认关闭,在 /plugin → Marketplaces 界面切换。

注意:marketplace update 只刷新目录,不更新已装插件——更新要用 plugin update <name>。市场级设置还有 extraKnownMarketplaces(加来源)、blockedMarketplaces(黑名单,支持 hostPattern/pathPattern 正则,v2.1.119+,并在每次生命周期事件强制生效 v2.1.117+)、deniedPlugins(禁装名单);/plugin 市场浏览器带搜索栏(v2.1.172+)。

五、热重载与调试

开发期改插件文件可自动检测;或手动 /reload-plugins 重读全部 manifest 与组件,无需重启会话。出问题时按序排查:版本兼容性(/version)→ plugin.json 语法 → 路径与目录结构一致性 → 脚本权限(chmod +x)→ /plugin debug plugin-name 看日志。

小结

分发链路:插件 → 市场目录(marketplace.json)→ 来源(六种)→ 用户一键安装。官方市场自动注册、社区市场手动加,组织用严格模式白名单管控。生命周期命令齐全:install/uninstall/update/list/enable/disable/validate/tag/prune/details;自动更新默认仅官方市场,环境变量可整体关闭。claude plugin tag 是官方推荐的发布打标方式。下一节精读三个示例插件,看打包的具体长什么样。

下一节预告:第 3 节精读 PR Review、DevOps Automation、Documentation 三个示例插件。