第 07 章

Plugins

把多个能力组合成可安装、可分发的一体化方案

一条命令安装 = 命令 + 角色 + MCP + Hooks 全部就绪

碎片化配置

你有没有发现，让新同事把 Claude Code 环境配好，要折腾一整个下午？

复制一堆文件

先复制 Skill 文件，再配 MCP server，再创建 subagent 角色，再装 Hook 脚本。六七个步骤，少一步就出问题。

配置不一致

A 同事配了安全审查 Hook，B 同事没配。A 审查出来的问题，B 根本看不到。团队标准全靠口头传达。

升级靠手动

PR 审查流程改了。你在 Slack 里通知全组"把 review 命令更新到 v2"。然后？三天了还有人在用 v1。

Plugin 就是为这个设计的：把命令、角色、MCP server、Hook、模板打包成一个整体。一条命令安装，所有组件就绪。升级时一条命令更新，全组同步。

开始之前

适合谁

  • 想把个人最佳实践变成团队标准的人
  • 需要在多个仓库/团队复用同一套流程的人
  • 已经理解前面章节的命令、Skill、Subagent、Hook、MCP

读完后你应该已经能

  • 说清 Plugin 的定位和组成
  • 判断"什么时候该升级到 Plugin 层"
  • 创建一个最小 Plugin 结构
  • 理解版本化和分发策略

什么是 Plugin

一句话：把多个能力打包成一套可安装的工作流

Plugin是把 slash commands、subagents、MCP servers 和 hooks 组合在一起的功能集合，可以通过一条命令安装和分发。

说白了，Plugin 就是一个"开箱即用的工作流套餐"——你不需要逐个配置每个组件，装完就能用。这个比喻只是为了帮你建立直观感受。在技术上，Plugin 是一个符合特定目录规范的文件夹，包含清单文件和各组件的定义文件。

图：插件组成架构——一个 Plugin 包含哪些组件

Commands

以 Markdown 形式存放的命令

Agents

自定义 agent 角色定义

Skills

带 SKILL.md 的技能

Hooks

事件处理器

MCP Servers

外部工具配置

Configuration

默认设置

插件类型

按范围和共享对象，插件分为四类

类型范围共享对象维护者示例
官方全局所有用户AnthropicPR 审查、安全指导
社区公开所有用户社区DevOps、数据科学
组织内部团队成员公司内部规范、工具
个人个人单个用户开发者自定义工作流

官方 vs 社区

官方插件由 Anthropic 审核维护，质量有保障；社区插件由开源贡献者提交，生态更丰富。两者都通过市场分发。

组织 vs 个人

组织插件放在企业私有仓库，通过 strictKnownMarketplaces 白名单管控。个人插件适合开发调试，不对外共享。

目录结构

一个插件文件夹里该有什么

my-plugin/
├── .claude-plugin/
│   └── plugin.json        [清单 — 必需]
├── commands/              [命令]
│   └── review-pr.md
├── agents/                [角色]
│   └── security-reviewer.md
├── skills/                [技能]
│   └── pr-review/
│       └── SKILL.md
├── hooks/                 [事件处理]
│   └── hooks.json
├── .mcp.json              [MCP 配置]
├── settings.json          [默认设置]
└── templates/             [模板]
# 文件：.claude-plugin/plugin.json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "一个示例插件",
  "author": { "name": "Your Name" },
  "license": "MIT",
  "userConfig": {
    "apiKey": {
      "description": "API 密钥",
      "sensitive": true
    },
    "region": {
      "description": "部署区域",
      "default": "us-east-1"
    }
  }
}
唯一必需的文件：plugin.json。其他都是可选的——你的插件可以只包含命令，也可以包含所有组件。userConfig 声明用户可配置的选项，sensitive: true 的值会存入系统密钥链而非明文文件。
插件中的角色安全限制：插件里的 subagent 不能注册自己的 hooks、不能配置 MCP servers、不能覆盖权限模式。这些限制确保插件不会在用户不知情的情况下扩展权限。

本仓示例

三个不同场景的插件

DevOps Automation

部署自动化、回滚、事件响应。包含 deploy、rollback、status、incident 四个命令和 deployment-specialist、incident-commander 两个角色。

DevOps

Documentation

文档生成、校验和同步。包含 generate-api-docs、generate-readme、sync-docs 三个命令和 api-documenter、code-commentator 两个角色。

文档

PR Review

完整的 PR 审查工作流。包含 review-pr、check-security、check-tests 三个命令和 security-reviewer、performance-analyzer 两个角色，还集成了 GitHub MCP。

审查

安装与更新

一条命令完成安装、启用、更新、卸载

图：插件生命周期——从发现到卸载的完整流程 
# 从 GitHub 安装
$ /plugin install github:acme/pr-review-plugin

# 从本地路径安装
$ /plugin install ./my-plugin

# 列出已安装
$ /plugin list --installed

# 启用 / 禁用 / 更新 / 卸载
$ /plugin enable pr-review
$ /plugin disable pr-review
$ /plugin update pr-review
$ /plugin uninstall pr-review
安装

所有组件
自动就位

使用

命令、角色
直接可用

更新

一条命令
全组同步

卸载

干净移除
不留残余

命令命名空间

独立命令用 /review，插件命令用 /pr-review:review-pr——自动加上插件名前缀，避免不同插件的命令冲突。

开发时热重载

开发插件时，用 /reload-plugins 重新加载所有插件配置，不用重启会话。也支持 claude --plugin-dir ./my-plugin 从本地目录临时加载。

持久化数据目录

每个插件有专属的 ${CLAUDE_PLUGIN_DATA} 目录，用于缓存、统计等跨会话持久状态。安装时自动创建，卸载时自动清理。

// hooks.json — 在 Hook 中使用持久化目录
{
  "hooks": {
    "PostToolUse": [
      {
        "command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js"
      }
    ]
  }
}

完整 CLI 命令

# 所有插件操作都可通过 CLI 完成
claude plugin install name@marketplace
claude plugin uninstall name
claude plugin list
claude plugin enable name
claude plugin disable name
claude plugin validate  # 验证结构

测试插件

发布前用 --plugin-dir 在本地充分验证

# 加载单个插件进行测试
$ claude --plugin-dir ./my-plugin

# 同时加载多个插件测试兼容性
$ claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin

六项验证清单

  • 所有 slash commands 是否可用
  • subagents 和 agents 是否正常工作
  • MCP servers 能正确连接
  • hooks 的执行符合预期
  • LSP server 配置正确加载
  • 没有配置错误或路径问题

热重载加速开发

修改插件文件后，用 /reload-plugins 重新加载所有配置（清单、命令、角色、技能、Hook、MCP/LSP），无需重启会话。

/reload-plugins
# 重新读取所有插件，会话不中断

分发渠道

插件可以从多个来源安装

来源语法适合
GitHub/plugin install github:owner/repo开源插件、团队内部仓库
本地路径/plugin install ./my-plugin开发调试、私有项目
npm/plugin install @acme/claude-plugin公开发布的插件
Git URL/plugin install https://git.internal/plugin.git企业内网
Git 子目录{ "source": "git-subdir", "url": "...", "path": "packages/plugin" }Monorepo 中的插件
pip{ "source": "pip", "package": "claude-data-plugin" }Python 生态插件

版本锁定

GitHub 和 Git 来源支持可选的 ref（分支/标签）和 sha（提交哈希）字段，用于锁定到特定版本，确保可复现的环境。

企业管控

通过 strictKnownMarketplaces 和 deniedPlugins 控制团队可安装的插件范围，防止安装来源不明的插件。

插件市场

官方目录 + 企业私有市场 + 内联定义

# 添加市场源
/plugin marketplace add owner/repo-name
/plugin marketplace add https://gitlab.com/org/marketplace-repo.git

# 内联定义（在 settings.json 中直接嵌入插件）
{
  "pluginMarketplaces": [
    {
      "name": "inline-tools",
      "source": "settings",
      "plugins": [
        { "name": "quick-lint", "source": "./local-plugins/quick-lint" }
      ]
    }
  ]
}

marketplace.json 字段

字段必填说明
name是kebab-case 市场名
owner是组织或用户
plugins是插件条目数组
plugins[].source是路径字符串或来源对象

组织管控设置

设置说明
enabledPlugins默认启用的白名单
deniedPlugins禁止安装的黑名单
strictKnownMarketplaces限制允许的市场
allowedChannelPlugins每渠道允许的插件
严格模式：strict: true（默认）下本地 plugin.json 为权威来源；strict: false 下市场条目即完整定义。配合 strictKnownMarketplaces 白名单模式，只允许匹配的市场被添加。

何时升级

不是什么都需要做成插件——先判断再行动

适合用插件

  • 团队入职：新同事一条命令装好所有配置
  • 框架初始化：打包框架专属命令和模板
  • 企业规范：集中分发，版本控制，统一升级
  • 多组件协作：命令 + 角色 + Hook + MCP 协同工作

不需要插件

  • 快速自动化 → 用 Command 就够
  • 单一领域能力 → 用 Skill 就够
  • 专门化分析 → 用 Subagent 就够
  • 实时数据访问 → 用 MCP 就够
判断标准：当你的配置涉及多个组件协同，且需要团队共享和版本管理时，才该升级到 Plugin。

能力对比

Slash Command / Skill / Subagent / Plugin 九维度横评

维度Slash CommandSkillSubagentPlugin
安装手动复制手动复制手动配置一条命令
设置时间5 分钟10 分钟15 分钟2 分钟
打包单文件单文件单文件多文件
版本管理手动手动手动自动
团队共享复制文件复制文件复制文件安装 ID
更新手动手动手动自动可用
依赖无无无可能包含
市场否否否是
分发仓库仓库仓库市场
选择依据：单一场景用独立功能（Command/Skill/Subagent），多组件协作 + 团队分发用 Plugin。Plugin 是唯一支持市场分发和版本管理的扩展方式。

LSP 支持

插件可以内置代码智能——实时诊断、跳转定义、类型提示

通过在插件中配置 .lsp.json，你可以让 Claude Code 获得 Language Server Protocol 的能力。这意味着 Claude 在编辑代码时能获得和 IDE 一样的实时反馈。

字段必填说明
command是LSP server 可执行文件（须在 PATH 中）
extensionToLanguage是文件扩展名 → 语言 ID 映射
args否server 命令行参数
transport否通信方式：stdio（默认）或 socket
env否server 进程的环境变量
initializationOptions否LSP 初始化期间发送的选项
settings否传递给 server 的工作区配置
workspaceFolder否覆盖工作区文件夹路径
startupTimeout否等待 server 启动最长时间（毫秒）
shutdownTimeout否优雅关闭最长时间（毫秒）
restartOnCrash否server 崩溃时自动重启
maxRestarts否放弃前最大重启次数

LSP 多语言

Python / Go / TypeScript 三种语言的配置示例

Python（pyright）

{
  "python": {
    "command": "pyright-langserver",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".py": "python",
      ".pyi": "python"
    }
  }
}

Go（gopls）

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

TypeScript

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".ts": "typescript",
      ".tsx": "typescriptreact",
      ".js": "javascript",
      ".jsx": "javascriptreact"
    }
  }
}

预置 LSP 插件

语言安装
Pythonpip install pyright
TypeScriptnpm i -g typescript-language-server typescript
Rustrustup component add rust-analyzer
LSP 提供的能力：即时诊断（错误/警告）、代码导航（跳转到定义、查找引用）、悬浮信息（类型签名和文档）、符号列表（文件或工作区范围）。

完整工作流

PR Review 插件：从安装到审查的端到端流程

Step 1：用户执行  /review-pr

Step 2：插件自动编排
├── pre-review.js hook    → 验证 git repo 状态
├── GitHub MCP            → 获取 PR diff 和元数据
├── security-reviewer     → 分析安全漏洞
├── test-checker          → 验证测试覆盖率
└── performance-analyzer  → 检查性能影响

Step 3：汇总并展示结果
    ✅ 安全：没有发现关键问题
    ⚠️  测试：覆盖率 65%（建议 80%+）
    ✅ 性能：没有明显影响
    📝 提供了 12 条改进建议
端到端体验：用户只输入一条命令，插件自动调度 Hook、MCP、多个 Subagent 协同工作，最终汇总成结构化报告。这就是 Plugin 的核心价值——把复杂的多步工作流封装成一键操作。

发布插件

从本地开发到市场上架的 8 步流程

1. 创建结构

组织所有组件文件

2. 编写清单

.claude-plugin/plugin.json

3. 写 README

完整文档和使用说明

4. 本地测试

claude --plugin-dir

5. 提交市场

PR 到市场仓库

6. 审核批准

官方/组织审核

7. 正式发布

上架到市场

8. 用户安装

一条命令即可

提交模板要点

  • 描述插件功能和使用场景
  • 列出包含的所有组件
  • 提供安装和使用命令
  • 标明依赖和环境要求

对比：手动 vs 插件

手动设置（2+ 小时）：逐个安装命令、创建角色、配置 MCP、设置 Hook、手动记录和分享。

使用插件（2 分钟）：/plugin install pr-review — 一切都已安装配置，团队可复现完全相同的设置。

最佳实践

应该做的

  • 使用清晰、描述性的插件名
  • 提供完整 README 和使用示例
  • 正确使用语义化版本（semver）
  • 一起测试所有组件
  • 清楚记录依赖和环境要求
  • 包含错误处理和完整测试
  • 为发现性添加合适标签
  • 保持向后兼容和聚焦一致
  • 记录所有外部依赖

不要做的

  • 不要打包无关功能
  • 不要硬编码凭据或密钥
  • 不要跳过测试就发布
  • 不要忘记文档
  • 不要创建功能重复的插件
  • 不要忽略版本管理
  • 不要把依赖搞得过于复杂
  • 不要忘记优雅处理错误

排错指南

安装失败

症状：/plugin install 报错。

修复：检查 Claude Code 版本（/version）。验证 plugin.json 语法。远程插件检查网络。用 claude plugin validate 验证插件结构。

组件未加载

症状：安装成功但命令/角色不可用。

修复：检查路径是否匹配实际目录结构。确认插件已启用（/plugin list --installed）。尝试 /reload-plugins 重新加载。

MCP 连接失败

症状：插件中的 MCP 工具调用报错。

修复：确认环境变量已设置（如 GITHUB_TOKEN）。检查 MCP server 是否已安装。用 /plugin debug plugin-name 查看详细日志。

命令冲突

症状：两个插件定义了同名命令。

修复：插件命令自动加前缀（/plugin-name:command）。如果前缀也冲突，禁用其中一个：/plugin disable plugin-name。

安装后命令不可用

症状：安装成功但找不到插件的命令。

修复：确认插件已安装且启用（/plugin list --installed + /plugin status plugin-name）。重启 Claude Code（exit 后重新打开）。检查是否与现有命令冲突。

Hook 执行问题

症状：插件的 Hook 没有按预期触发或报错。

修复：确认 Hook 文件有执行权限（chmod +x）。检查 Hook 语法和事件名是否正确。查看 Hook 日志中的错误细节。如有可能，手动测试 Hook 脚本。

动手练习

把 PR 审查流程打包成最小插件

任务：创建一个只包含清单 + 1 个命令 + 1 个角色的最小插件。
  • 创建 plugin.json 清单
  • 包含 1 个审查命令
  • 包含 1 个审查角色（只读权限）
  • 能通过 /plugin install 安装

参考答案

pr-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── review-pr.md
└── agents/
    └── security-reviewer.md
# .claude-plugin/plugin.json
{
  "name": "pr-review",
  "version": "1.0.0",
  "description": "包含安全检查的 PR 审查工作流"
}

# commands/review-pr.md
---
name: review-pr
description: 启动包含安全检查的完整 PR 审查
---
审查当前分支的所有改动，包含安全分析。

# agents/security-reviewer.md
---
name: security-reviewer
description: 安全代码审查
tools: Read, Grep, Glob
---
专注安全漏洞：注入攻击、数据暴露、权限问题。
最小够用：一个插件可以很简单——清单 + 命令 + 角色，三个文件就够了。别一开始就追求完美，先跑起来再迭代。

本章回顾

到这里，你已经能

  • 说清 Plugin 的定位和组成
  • 判断何时该升级到 Plugin 层
  • 创建最小 Plugin 结构
  • 理解版本化和分发策略

它和前后章节的关系

  • Commands — 插件中的命令
  • Skills — 插件中的技能
  • Subagents — 插件中的角色
  • MCP — 插件中的外部工具
  • Hooks — 插件中的事件处理
  • Plugins — 把以上全部打包
核心结论：Plugin 是 Claude Code 最高级别的扩展方式。当你的个人最佳实践需要变成团队标准时，就该创建插件了。一条命令安装，全团队配置一致。

延伸阅读

继续本课程

本章源文件 （点击查看完整内容）

  • README.md — Plugins 完整配置指南
  • 07-plugins/ 目录 — DevOps、Documentation、PR Review 三个示例插件

加载中…