# 插件系统

Claude Code 插件系统允许你扩展 Claude 的功能，创建自定义斜杠命令、专门的代理、可复用的技能，以及自动化钩子。通过插件，你可以将团队的最佳实践和工作流程编码化。

## 什么是插件？

### 基本概念

Claude Code 插件是一个包含特定文件结构的目录，可以添加以下组件：

| 组件 | 说明 | 文件格式 |
|------|------|----------|
| **Commands（命令）** | 自定义斜杠命令 | `.md` 文件 |
| **Agents（代理）** | 专门任务的子代理 | `.md` 文件 |
| **Skills（技能）** | 可复用的知识和能力 | 目录 + `SKILL.md` |
| **Hooks（钩子）** | 事件触发的自动化 | `hooks.json` |

### 为什么需要插件？

- **团队规范化**：将编码规范、审查标准编码为可执行命令

- **工作流自动化**：自动化重复性任务，如提交、部署、审查

- **知识共享**：团队成员共享最佳实践和专业知识

- **定制体验**：根据项目需求定制 Claude 的行为

## 插件目录结构

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 必需：插件配置清单
├── commands/                 # 斜杠命令（.md 文件）
│   ├── review.md
│   └── deploy.md
├── agents/                   # 子代理定义（.md 文件）
│   └── code-reviewer.md
├── skills/                   # 代理技能（子目录）
│   └── coding-standards/
│       └── SKILL.md
├── hooks/
│   └── hooks.json           # 事件处理配置
├── .mcp.json                # MCP 服务器定义（可选）
└── scripts/                 # 辅助脚本（可选）
```

## 快速开始

### 安装插件

```bash
# 从市场安装
/plugin install plugin-name@claude-code-marketplace

# 从本地目录安装
claude --plugin-dir /path/to/my-plugin
```

### 使用插件创建向导

```bash
/plugin-dev:create-plugin
```

这个命令会引导你完成 8 个阶段来创建一个完整的插件。

## 创建自定义命令

### 基本命令格式

在 `commands/` 目录创建 `.md` 文件：

```markdown
---
description: 执行代码审查
argument-hint: [file-path]
allowed-tools: Read, Bash(git:*)
---

请审查以下文件的代码质量：@$1

重点检查：
1. 代码可读性
2. 潜在的 bug
3. 性能问题
4. 安全漏洞
```

### YAML 前置配置

| 字段 | 说明 | 示例 |
|------|------|------|
| `description` | 命令描述（显示在 /help） | `执行代码审查` |
| `argument-hint` | 参数提示 | `[file-path] [options]` |
| `allowed-tools` | 允许使用的工具 | `Read, Bash(git:*)` |
| `model` | 指定模型 | `opus` 或 `sonnet` |

### 使用动态参数

- `$1`, `$2`, `$3`... - 位置参数

- `$ARGUMENTS` - 所有参数

- `@path/to/file` - 文件引用

- `!`command`` - 执行 Bash 命令

### 命令示例

**代码审查命令** (`commands/review.md`)：

```markdown
---
description: 全面的代码审查
argument-hint: [file-or-directory]
allowed-tools: Read, Grep, Glob
model: opus
---

对 @$1 进行全面的代码审查。

检查清单：
- [ ] 代码风格是否符合项目规范
- [ ] 是否有潜在的安全问题
- [ ] 错误处理是否完善
- [ ] 是否需要添加测试

如果是目录，先用 Glob 工具找到所有相关文件。
```

**智能提交命令** (`commands/commit.md`)：

```markdown
---
description: 智能生成 commit 并提交
allowed-tools: Bash(git:*)
---

1. 运行 `git status` 查看更改
2. 运行 `git diff --staged` 分析已暂存的更改
3. 根据更改内容生成规范的 commit message
4. 执行 `git commit`

Commit message 格式：
- feat: 新功能
- fix: Bug 修复
- docs: 文档更新
- refactor: 重构
- test: 测试相关
```

## 创建自定义代理

### 代理定义格式

在 `agents/` 目录创建 `.md` 文件：

```markdown
---
description: 专门的代码审查代理
model: opus
tools: Read, Grep, Glob
---

你是一个专业的代码审查代理。你的任务是：

1. 仔细阅读提供的代码
2. 识别潜在问题
3. 提供具体的改进建议
4. 关注安全性和性能

始终保持建设性和具体性。
```

### 代理类型

| 类型 | 用途 | 示例 |
|------|------|------|
| 审查代理 | 代码审查、PR 审查 | `code-reviewer` |
| 测试代理 | 生成和运行测试 | `test-generator` |
| 文档代理 | 生成文档 | `doc-writer` |
| 重构代理 | 代码重构 | `refactorer` |

## 创建技能

### 技能目录结构

```
skills/
└── coding-standards/
    ├── SKILL.md              # 必需：技能定义
    ├── references/           # 参考资料
    │   └── style-guide.md
    └── examples/             # 示例代码
        └── good-practices.md
```

### SKILL.md 格式

```markdown
# 编码规范技能

## 概述
这个技能包含团队的编码规范和最佳实践。

## 知识内容

### 命名规范
- 变量：camelCase
- 常量：UPPER_SNAKE_CASE
- 类：PascalCase
- 文件：kebab-case

### 代码风格
- 使用 2 空格缩进
- 最大行宽 100 字符
- 使用分号

### 错误处理
- 始终使用 try-catch
- 记录错误日志
- 提供有意义的错误消息
```

## 创建钩子

### hooks.json 格式

```json
{
  "hooks": [
    {
      "event": "on_commit",
      "command": "npm run lint",
      "description": "提交前运行 lint 检查"
    },
    {
      "event": "on_file_change",
      "pattern": "*.ts",
      "command": "npm run typecheck",
      "description": "TypeScript 文件变更时检查类型"
    }
  ]
}
```

### 支持的事件

| 事件 | 触发时机 |
|------|----------|
| `on_commit` | 提交代码时 |
| `on_file_change` | 文件变更时 |
| `on_session_start` | 会话开始时 |
| `on_command` | 执行命令时 |

## 插件配置清单

### plugin.json 格式

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "我的自定义插件",
  "author": "Your Name",
  "components": {
    "commands": ["commands/*.md"],
    "agents": ["agents/*.md"],
    "skills": ["skills/*/SKILL.md"],
    "hooks": "hooks/hooks.json"
  },
  "mcpServers": ".mcp.json"
}
```

## 实际应用示例

### 示例 1：团队代码审查插件

```
team-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── review-pr.md          # PR 审查命令
│   ├── security-check.md     # 安全检查命令
│   └── perf-audit.md         # 性能审计命令
├── agents/
│   ├── security-reviewer.md  # 安全审查代理
│   └── perf-analyzer.md      # 性能分析代理
└── skills/
    └── team-standards/
        └── SKILL.md          # 团队规范技能
```

### 示例 2：部署自动化插件

```
deploy-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── deploy-staging.md     # 部署到测试环境
│   ├── deploy-prod.md        # 部署到生产环境
│   └── rollback.md           # 回滚命令
├── hooks/
│   └── hooks.json            # 部署前检查钩子
└── .mcp.json                 # Kubernetes MCP 配置
```

## 最佳实践

### 命令设计

1. **单一职责**：每个命令只做一件事

2. **清晰描述**：description 要简洁明了

3. **参数文档**：使用 argument-hint 说明参数

4. **最小权限**：allowed-tools 只包含必要工具

5. **错误处理**：考虑失败场景

### 插件组织

1. **模块化**：相关功能组织在一起

2. **可复用**：技能应该可以被多个命令使用

3. **文档化**：添加 README 和使用说明

4. **版本管理**：使用语义化版本号

### 安全考虑

1. **不硬编码密钥**：使用环境变量

2. **限制文件访问**：只访问必要的路径

3. **验证输入**：对参数进行验证

4. **审计日志**：记录敏感操作

## 调试插件

```bash
# 查看插件加载状态
/plugin list

# 查看命令详情
/help my-command

# 测试命令
/my-command test-argument
```

## 下一步

- 学习 [MCP 服务器](/docs/advanced/mcp) 扩展外部集成

- 查看 [CLI 技巧](/docs/usage/cli-tips) 提升使用效率

- 探索 [工作流技巧](/docs/usage/workflow-tips) 优化开发流程