Claude Code 使用手册 · 第 8 章 插件 Plugins

Claude Code 使用手册 · 第 8 章 插件 Plugins

章节摘要:插件是把多个扩展能力打包成"一键安装"分发单元的最高级扩展机制——捆绑斜杠命令、子代理、MCP 服务器、Hooks 四要素,安装一条命令,团队可精确复现同一套配置。清单在 .claude-plugin/plugin.json;分发经市场(marketplace),插件来源支持六种类型(相对路径/GitHub/Git URL/Git 子目录/npm/pip);官方市场 anthropics/claude-plugins-official 自动注册,社区市场需手动添加。沙箱限制:插件子代理禁止 hooks、mcpServers、permissionMode,防止权限升级。官方提供三个示例插件:PR Review、DevOps Automation、Documentation。本章共 4 节。

解剖坐标

一句话主线:理解"为什么需要插件" → 掌握目录结构与四要素 → 学会市场分发与安装 → 按安全与发布规范上线自己的插件。

学习目标

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

1. 说出插件四要素与目录结构,解释插件与单个命令/技能/子代理的取舍。
2. 写出 plugin.json 清单与 marketplace.json 市场定义,说出六种来源语法。
3. 用 /plugin 界面与 CLI 完成安装、启用、禁用、卸载、更新、打标签。
4. 复述三个示例插件的组件构成与协作模式。
5. 背出插件沙箱三禁令与发布八步流程。

子章节导航

01 四要素与目录结构

插件本质(捆绑+一键安装+精确复现);目录结构全览;manifest 字段;LSP 配置与 bin/ PATH;userConfig 敏感项存钥匙串;${CLAUDE_PLUGIN_DATA} 持久目录;背景监视器;inline 插件;插件 vs 独立功能的决策矩阵。

02 市场与分发

四种插件类型(官方/社区/组织/个人);marketplace.json 定义与字段;六种来源语法(GitHub/npm/pip/git-subdir 等);/plugin 与 claude plugin 命令族;生命周期(发现→安装→更新→禁用→卸载);自动更新与三个环境变量;版本锁定与 claude plugin tag。

03 三个示例插件精读

PR Review(3 命令+3 代理+GitHub MCP+审查钩子,完整协作流程);DevOps Automation(部署/回滚/状态/事故 4 命令+3 代理+脚本+前后置钩子);Documentation(4 命令+3 代理+模板+GitHub MCP)。规律:命令是入口、代理是分工、钩子是守门、模板是标准。

04 安全与发布最佳实践

沙箱三禁令(hooks/mcpServers/permissionMode);组织级受管设置;发布八步流程;本地测试(--plugin-dir/--plugin-url)与热重载;Do's/Don'ts;插件 vs 手工配置的成本对比。

前置知识与后续延伸

前置知识:第 2、4、6、7 章——插件就是把命令、子代理、MCP、Hooks 打包。

后续延伸:第 9 章检查点与高级特性(插件可分发命令/代理,与高级特性组合使用)。