Plugins 插件系统

什么是 Claude Code Plugins?

Plugins 是自定义开发工具集合,用于扩展 Claude Code 的能力。可以把它们想象成开发工作流的增强包 - 你可以通过一个命令安装所需的全部工具。

一个 Plugin 可以包含四个核心组件:

Slash Commands: 常用操作的快捷命令
Subagents: 针对特定任务的专业 AI 代理
MCP Servers: 连接外部工具和数据源
Hooks: 在特定工作流时刻的自定义行为

关键创新之处:所有这些组件打包在一起,使复杂的开发环境设置变得简单快速。

为什么使用 Plugins?

传统工具管理问题

没有 Plugins,开发团队面临:

🔄 工具分散: 每个团队成员配置工具的方式都不同
📚 学习曲线陡峭: 新成员花费数天时间设置环境
🔧 配置地狱: 每个人维护自己的脚本和配置
🐛 标准不一致: 没有统一的方式来执行最佳实践

Plugins 解决方案

Plugins 通过以下方式解决这些问题:

✅ 一键安装: 整个工具链即刻安装完成
🎯 标准化: 每个人使用相同的工具和工作流
🚀 快速上手: 新成员第一天就能开始工作
🔄 轻松管理: 根据需要启用/禁用插件

理解四大组件

1. Slash Commands

Slash Commands 是快速操作的入口点。它们将复杂任务封装成简单命令。

常见模式:

/test          # 运行测试套件
/deploy        # 部署到生产环境
/review        # 启动代码审查流程
/docs          # 生成文档
/build         # 执行优化构建

工作原理:

当你输入 /test 时,Claude Code:

从 .claude/commands/test.md 读取命令定义
执行定义的工作流
将结果返回给你

创建你的第一个 Slash Command:

<!-- .claude/commands/hello.md -->
向用户问好并展示当前项目结构。

现在输入 /hello 就会执行这个命令。

2. Subagents

Subagents 是具有深厚领域专业知识的专业 AI 代理。它们就像你团队中的专家顾问。

真实世界示例:

DevOps Agent:

自动化部署流程
监控系统健康
处理基础设施任务

> 使用 DevOps agent 为这个项目设置 CI/CD 流水线

Testing Agent:

生成智能测试用例
识别边界情况
优化测试覆盖率

> 使用 Testing agent 为认证模块创建全面的测试

Security Agent:

扫描代码漏洞
建议安全改进
验证安全模式

> 使用 Security agent 审计这个 API 端点

3. MCP Servers

MCP (Model Context Protocol) Servers 提供与外部工具和数据源的连接。

连接能力:

开发工具:

- Git: 版本控制操作
- Docker: 容器管理
- Kubernetes: 编排和部署

数据库:

- PostgreSQL: 关系型数据
- MongoDB: 文档存储
- Redis: 缓存和会话

云服务:

- AWS: 云基础设施
- Azure: 微软云
- GCP: 谷歌云平台

API 服务:

- 内部微服务
- 第三方 APIs
- Webhook 集成

MCP Server 配置示例:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION": "postgresql://localhost/mydb"
      }
    }
  }
}

4. Hooks

Hooks 在特定工作流时刻自定义 Claude Code 的行为。

可用的 Hook 类型:

Pre-commit Hook:

// .claude/hooks/pre-commit.js
// 在代码提交前运行
module.exports = async (context) => {
  // 运行 linters
  // 检查格式
  // 验证测试
  return { allow: true };
};

Post-analysis Hook:

// .claude/hooks/post-analysis.js
// 在代码分析后运行
module.exports = async (context) => {
  // 生成报告
  // 更新文档
  // 通知团队
};

Error Hook:

// .claude/hooks/error.js
// 发生错误时运行
module.exports = async (error, context) => {
  // 记录错误详情
  // 尝试恢复
  // 通知监控系统
};

安装和使用 Plugins

基础安装

安装插件的最简单方式:

/plugin install organization/plugin-name

示例:

/plugin install danavila/devops-toolkit

Claude 将:

从仓库下载插件
安装所有依赖
配置所有组件
立即可用

管理 Plugins

Plugins 被设计为轻量且可切换:

# 启用插件
/plugin enable plugin-name

# 禁用插件
/plugin disable plugin-name

# 列出所有已安装插件
/plugin list

# 查看插件详情
/plugin info plugin-name

# 卸载插件
/plugin uninstall plugin-name

Plugin 生命周期

安装 → 配置 → 启用 → 使用 → 禁用/卸载

安装: 下载并设置插件 配置: 为你的项目自定义插件设置 启用: 激活插件功能 使用: 访问 slash commands、subagents 和 hooks 禁用: 临时关闭但不卸载 卸载: 完全移除插件

Plugin 市场

什么是市场?

市场是开发者分享插件的仓库。任何人都可以创建和托管自己的市场。

创建市场

步骤 1: 创建配置文件

// .claude-plugin/marketplace.json
{
  "name": "我的市场",
  "description": "我们团队的自定义插件",
  "plugins": [
    {
      "name": "team-standards",
      "description": "执行团队编码标准",
      "version": "1.0.0",
      "repository": "github.com/myteam/team-standards"
    }
  ]
}

步骤 2: 托管在 GitHub

git init
git add .claude-plugin/
git commit -m "Initialize plugin marketplace"
git push origin main

步骤 3: 与团队分享

/plugin marketplace add myteam/plugin-marketplace

社区市场

Dan Ávila 的市场:

/plugin marketplace add danavila/plugins

包含:

DevOps 自动化工具
文档生成器
项目管理集成

Seth Hobson 的仓库:

/plugin marketplace add sethhobson/agents

提供 80+ 专业 subagents:

前端开发 (React, Vue, Angular)
后端开发 (Node.js, Python, Java)
数据科学和机器学习
移动开发 (iOS, Android)

真实世界的 Plugin 工作流

场景 1: 前端团队标准化

问题: 团队成员使用不同的 lint 规则和格式化标准

解决方案: 创建团队标准 Plugin

# 安装团队标准插件
/plugin install company/frontend-standards

Plugin 包含:

/lint - 使用团队配置运行 ESLint
/format - 应用团队 Prettier 规则
/test - 运行 Jest 并要求覆盖率
React Agent - 强制执行组件模式
Accessibility Agent - 确保 WCAG 合规

结果:

团队代码风格一致
自动化质量检查
减少代码审查时间

场景 2: 全栈生产力提升

问题: 重复的样板代码降低开发速度

解决方案: 安装生产力 Plugin

/plugin install awesome-dev/fullstack-boost

Plugin 提供:

/api - 使用最佳实践生成 REST API
/component - 创建带测试的 UI 组件
/db-migrate - 数据库迁移助手
Backend Agent - API 优化建议
Database Agent - 查询性能提示

结果:

功能开发速度提升 3 倍
一致的架构模式
内置优化指导

场景 3: 企业安全合规

问题: 部署前必须满足安全标准

解决方案: 安全合规 Plugin

/plugin install enterprise/security-compliance

Plugin 强制执行:

/security-scan - 自动化安全检查
/compliance-check - 法规合规验证
/audit-log - 生成审计跟踪
Security Agent - 漏洞检测和修复
Compliance Hook - 提交前安全验证

结果:

自动化安全执行
自动生成合规文档
减少安全事件

创建你的第一个 Plugin

Plugin 结构

my-plugin/
├── .claude-plugin/
│   ├── manifest.json          # Plugin 元数据
│   ├── commands/               # Slash commands
│   │   ├── test.md
│   │   └── deploy.md
│   ├── agents/                 # Subagents
│   │   ├── testing-agent.md
│   │   └── deploy-agent.md
│   ├── mcp-servers/            # MCP server 配置
│   │   └── custom-tools.json
│   └── hooks/                  # Hooks 配置
│       ├── pre-commit.js
│       └── post-analysis.js
└── README.md

步骤 1: 创建清单文件

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "我的自定义开发工具",
  "author": "你的名字",
  "components": {
    "commands": ["test", "deploy"],
    "agents": ["testing-agent"],
    "hooks": ["pre-commit"]
  }
}

步骤 2: 添加 Slash Command

<!-- .claude-plugin/commands/test.md -->
# 测试命令

运行项目测试套件并生成覆盖率报告。

## 步骤:
1. 检查测试文件
2. 运行 Jest 并生成覆盖率
3. 生成 HTML 报告
4. 在浏览器中打开报告

步骤 3: 创建 Subagent

<!-- .claude-plugin/agents/testing-agent.md -->
# 测试代理

你是一个专注于全面测试覆盖的测试专家。

## 能力:
- 为函数和类生成单元测试
- 为 APIs 创建集成测试
- 设计端到端测试场景
- 识别边界情况和测试覆盖缺口
- 建议测试数据和模拟策略

## 指南:
- 遵循 AAA 模式 (Arrange, Act, Assert)
- 目标代码覆盖率 80% 以上
- 包含正面和负面测试用例
- 适当模拟外部依赖

步骤 4: 添加 Hook

// .claude-plugin/hooks/pre-commit.js
module.exports = async (context) => {
  console.log('运行提交前检查...');

  // 运行 linter
  const lintResult = await context.exec('npm run lint');
  if (lintResult.exitCode !== 0) {
    return {
      allow: false,
      message: 'Lint 失败。请在提交前修复错误。'
    };
  }

  // 运行测试
  const testResult = await context.exec('npm test');
  if (testResult.exitCode !== 0) {
    return {
      allow: false,
      message: '测试失败。请在提交前修复失败的测试。'
    };
  }

  return { allow: true };
};

步骤 5: 测试你的 Plugin

# 本地加载插件
/plugin install ./my-plugin

# 测试 slash command
/test

# 使用 subagent
> 使用 Testing agent 为 UserService 创建测试

# 验证 hook (尝试提交)
git add .
git commit -m "test commit"

最佳实践

1. 单一职责

每个插件应专注于一个领域:

✅ 好:

- authentication-plugin (仅处理认证)
- testing-plugin (仅处理测试)
- deployment-plugin (仅处理部署)

❌ 不好:

- everything-plugin (尝试做所有事)

2. 可组合性

设计插件以便它们能很好地协同工作:

# 插件应该互补
/plugin enable testing-plugin
/plugin enable quality-plugin
/plugin enable deployment-plugin

# 它们不应该冲突

3. 清晰的文档

每个插件需要:

# 插件名称

## 描述
清楚说明它的作用

## 安装
分步安装指南

## 使用
所有命令和功能的示例

## 配置
可用选项和设置

## 故障排除
常见问题和解决方案

4. 版本管理

使用语义化版本:

{
  "version": "1.2.3"
  // 1 = 主版本 (破坏性更改)
  // 2 = 次版本 (新功能)
  // 3 = 补丁 (bug 修复)
}

5. 性能优化

懒加载:

// 仅在需要时加载
if (command === '/heavy-operation') {
  const module = await import('./heavy-module');
  module.execute();
}

缓存:

// 缓存昂贵的操作
const cache = new Map();
if (cache.has(key)) {
  return cache.get(key);
}
const result = await expensiveOperation();
cache.set(key, result);

故障排除

Plugin 无法安装

问题: 插件安装失败

解决方案:

# 检查网络连接
ping github.com

# 验证插件仓库存在
git ls-remote https://github.com/org/plugin-name

# 尝试详细日志模式
/plugin install org/plugin-name --verbose

# 检查冲突的插件
/plugin list

Slash Command 未找到

问题: /mycommand 提示 "command not found"

解决方案:

# 验证插件已启用
/plugin list

# 如果禁用则启用
/plugin enable plugin-name

# 重新加载插件
/plugin reload

# 检查命令定义是否存在
ls .claude-plugin/commands/

Hook 未触发

问题: Pre-commit hook 不运行

解决方案:

// 检查 hook 是否已注册
/plugin info plugin-name

// 验证 hook 文件存在且名称正确
ls .claude-plugin/hooks/

// 检查 hook 语法
node .claude-plugin/hooks/pre-commit.js

// 启用 hook 调试
/plugin config plugin-name --debug-hooks

高级主题

条件 Plugin 加载

// 仅在特定环境加载
if (process.env.NODE_ENV === 'production') {
  await loadPlugin('production-monitoring');
}

Plugin 依赖

{
  "name": "advanced-plugin",
  "dependencies": {
    "base-plugin": "^1.0.0",
    "utils-plugin": "^2.1.0"
  }
}

自定义 Plugin 配置

{
  "plugins": {
    "my-plugin": {
      "enabled": true,
      "config": {
        "apiKey": "your-key",
        "timeout": 5000,
        "retries": 3
      }
    }
  }
}

Plugin 安全

最佳实践

1. 代码审查: 安装前始终审查插件代码 2. 可信来源: 仅从经过验证的市场安装 3. 权限: 了解插件请求的访问权限 4. 定期更新: 保持插件更新以获得安全补丁

危险信号

⚠️ 警告标志:

请求过多权限
包含混淆代码
没有源代码
未知开发者
没有文档

下一步

现在你理解了 Plugins,可以:

探索市场: 浏览可用插件

/plugin marketplace add danavila/plugins
/plugin browse

安装有用的 Plugins: 从社区热门开始
```
/plugin install danavila/devops-toolkit
```

创建你的 Plugin: 为你的工作流构建工具

mkdir my-plugin
cd my-plugin
# 按照上面的结构

与社区分享: 发布你的插件
```
git push origin main
# 分享仓库 URL
```

继续阅读: Dynamic Memory 了解 Claude Code 如何跨会话维护上下文。

什么是 Claude Code Plugins?​

为什么使用 Plugins?​

传统工具管理问题​

Plugins 解决方案​

理解四大组件​

1. Slash Commands​

2. Subagents​

3. MCP Servers​

4. Hooks​

安装和使用 Plugins​

基础安装​

管理 Plugins​

Plugin 生命周期​

Plugin 市场​

什么是市场?​

创建市场​

社区市场​

真实世界的 Plugin 工作流​

场景 1: 前端团队标准化​

场景 2: 全栈生产力提升​

场景 3: 企业安全合规​

创建你的第一个 Plugin​

Plugin 结构​

步骤 1: 创建清单文件​

步骤 2: 添加 Slash Command​

步骤 3: 创建 Subagent​

步骤 4: 添加 Hook​

步骤 5: 测试你的 Plugin​

最佳实践​

1. 单一职责​

2. 可组合性​

3. 清晰的文档​

4. 版本管理​

5. 性能优化​

故障排除​

Plugin 无法安装​

Slash Command 未找到​

Hook 未触发​

高级主题​

条件 Plugin 加载​

Plugin 依赖​

自定义 Plugin 配置​

Plugin 安全​

最佳实践​

危险信号​

下一步​

什么是 Claude Code Plugins?

为什么使用 Plugins?

传统工具管理问题

Plugins 解决方案

理解四大组件

1. Slash Commands

2. Subagents

3. MCP Servers

4. Hooks

安装和使用 Plugins

基础安装

管理 Plugins

Plugin 生命周期

Plugin 市场

什么是市场?

创建市场

社区市场

真实世界的 Plugin 工作流

场景 1: 前端团队标准化

场景 2: 全栈生产力提升

场景 3: 企业安全合规

创建你的第一个 Plugin

Plugin 结构

步骤 1: 创建清单文件

步骤 2: 添加 Slash Command

步骤 3: 创建 Subagent

步骤 4: 添加 Hook

步骤 5: 测试你的 Plugin

最佳实践

1. 单一职责

2. 可组合性

3. 清晰的文档

4. 版本管理

5. 性能优化

故障排除

Plugin 无法安装

Slash Command 未找到

Hook 未触发

高级主题

条件 Plugin 加载

Plugin 依赖

自定义 Plugin 配置

Plugin 安全

最佳实践

危险信号

下一步