437 lines
9.2 KiB
Markdown
Executable File
437 lines
9.2 KiB
Markdown
Executable File
# Claude Code 插件（Plugins）指南
|
||
|
||
## 概述
|
||
|
||
插件是 Claude Code 的扩展功能系统，允许用户通过自定义命令、代理、钩子、技能和 MCP 服务器来扩展平台功能。插件可以在项目和团队之间共享，是分发 Claude Code 扩展的标准方式。
|
||
|
||
## 插件目录结构
|
||
|
||
```
|
||
my-plugin/
|
||
├── .claude-plugin/
|
||
│ └── plugin.json # 必需：插件元数据
|
||
├── commands/ # 可选：自定义斜杠命令
|
||
│ └── hello.md
|
||
├── agents/ # 可选：自定义代理
|
||
│ └── helper.md
|
||
├── skills/ # 可选：Agent Skills
|
||
│ └── my-skill/
|
||
│ └── SKILL.md
|
||
├── hooks/ # 可选：事件处理器
|
||
│ └── hooks.json
|
||
└── .mcp.json # 可选：MCP 服务器配置
|
||
```
|
||
|
||
## 插件组件说明
|
||
|
||
| 组件 | 功能 | 位置 |
|
||
|------|------|------|
|
||
| **Commands** | 自定义斜杠命令 | `commands/*.md` |
|
||
| **Agents** | 专门的代理（显示在 `/agents`） | `agents/*.md` |
|
||
| **Skills** | 扩展 Claude 能力（模型自动调用） | `skills/skill-name/SKILL.md` |
|
||
| **Hooks** | 事件处理和自动化 | `hooks/hooks.json` |
|
||
| **MCP** | 外部工具集成 | `.mcp.json` |
|
||
|
||
## 快速开始：创建第一个插件
|
||
|
||
### 步骤1：创建目录结构
|
||
|
||
```bash
|
||
# 创建插件目录
|
||
mkdir -p my-first-plugin/.claude-plugin
|
||
mkdir -p my-first-plugin/commands
|
||
mkdir -p my-first-plugin/skills/greeting-skill
|
||
```
|
||
|
||
### 步骤2：创建插件清单
|
||
|
||
```bash
|
||
cat > my-first-plugin/.claude-plugin/plugin.json << 'EOF'
|
||
{
|
||
"name": "my-first-plugin",
|
||
"description": "一个简单的问候插件，用于学习基础知识",
|
||
"version": "1.0.0",
|
||
"author": {
|
||
"name": "你的名字"
|
||
}
|
||
}
|
||
EOF
|
||
```
|
||
|
||
### 步骤3：添加自定义命令
|
||
|
||
```bash
|
||
cat > my-first-plugin/commands/hello.md << 'EOF'
|
||
---
|
||
description: 用个性化消息问候用户
|
||
argument-hint: [用户名]
|
||
---
|
||
|
||
# 问候命令
|
||
|
||
热情地问候用户 $ARGUMENTS，并询问今天有什么可以帮助的。让问候变得个性化和鼓励性。
|
||
EOF
|
||
```
|
||
|
||
### 步骤4：添加技能
|
||
|
||
```bash
|
||
cat > my-first-plugin/skills/greeting-skill/SKILL.md << 'EOF'
|
||
---
|
||
name: greeting-skill
|
||
description: 生成友好的问候语。当用户需要问候模板或社交礼仪建议时使用。
|
||
---
|
||
|
||
# 问候技能
|
||
|
||
## 说明
|
||
|
||
根据场景生成合适的问候语：
|
||
- 正式场合
|
||
- 非正式场合
|
||
- 电子邮件开头
|
||
- 即时消息
|
||
EOF
|
||
```
|
||
|
||
## plugin.json 配置详解
|
||
|
||
### 基本配置
|
||
|
||
```json
|
||
{
|
||
"name": "plugin-name",
|
||
"description": "插件功能描述",
|
||
"version": "1.0.0",
|
||
"author": {
|
||
"name": "作者名称",
|
||
"email": "author@example.com"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 完整配置示例
|
||
|
||
```json
|
||
{
|
||
"name": "enterprise-tools",
|
||
"description": "企业级工作流自动化工具",
|
||
"version": "2.1.0",
|
||
"author": {
|
||
"name": "企业团队",
|
||
"email": "team@company.com"
|
||
},
|
||
"homepage": "https://docs.company.com/plugins/enterprise-tools",
|
||
"repository": "https://github.com/company/enterprise-plugin",
|
||
"license": "MIT",
|
||
"keywords": ["enterprise", "workflow", "automation"]
|
||
}
|
||
```
|
||
|
||
### 配置字段说明
|
||
|
||
| 字段 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `name` | 是 | 插件标识符（kebab-case 格式） |
|
||
| `description` | 否 | 插件功能简述 |
|
||
| `version` | 否 | 语义化版本号 |
|
||
| `author` | 否 | 作者信息对象（含 `name` 字段） |
|
||
| `homepage` | 否 | 文档或主页 URL |
|
||
| `repository` | 否 | 源代码仓库 URL |
|
||
| `license` | 否 | 许可证类型 |
|
||
| `keywords` | 否 | 关键词数组 |
|
||
|
||
## 安装和管理插件
|
||
|
||
### 安装插件
|
||
|
||
```bash
|
||
# 通过交互菜单浏览
|
||
/plugin
|
||
|
||
# 从市场直接安装
|
||
/plugin install formatter@your-org
|
||
|
||
# 从本地市场安装
|
||
/plugin install my-first-plugin@test-marketplace
|
||
```
|
||
|
||
### 管理已安装插件
|
||
|
||
```bash
|
||
# 启用插件
|
||
/plugin enable plugin-name@marketplace-name
|
||
|
||
# 禁用插件
|
||
/plugin disable plugin-name@marketplace-name
|
||
|
||
# 卸载插件
|
||
/plugin uninstall plugin-name@marketplace-name
|
||
```
|
||
|
||
### 验证安装
|
||
|
||
```bash
|
||
# 查看新命令是否出现
|
||
/help
|
||
|
||
# 管理插件
|
||
/plugin
|
||
```
|
||
|
||
## 本地开发和测试
|
||
|
||
### 开发工作流
|
||
|
||
```bash
|
||
# 1. 创建开发目录结构
|
||
mkdir dev-marketplace
|
||
cd dev-marketplace
|
||
mkdir my-plugin
|
||
|
||
# 2. 创建市场清单
|
||
mkdir .claude-plugin
|
||
cat > .claude-plugin/marketplace.json << 'EOF'
|
||
{
|
||
"name": "dev-marketplace",
|
||
"owner": {"name": "Developer"},
|
||
"plugins": [{
|
||
"name": "my-plugin",
|
||
"source": "./my-plugin",
|
||
"description": "开发中的插件"
|
||
}]
|
||
}
|
||
EOF
|
||
|
||
# 3. 从父目录启动 Claude Code
|
||
claude
|
||
|
||
# 4. 添加市场
|
||
/plugin marketplace add ./dev-marketplace
|
||
|
||
# 5. 安装插件
|
||
/plugin install my-plugin@dev-marketplace
|
||
```
|
||
|
||
### 迭代开发
|
||
|
||
```bash
|
||
# 修改插件代码后，重新安装
|
||
/plugin uninstall my-plugin@dev-marketplace
|
||
/plugin install my-plugin@dev-marketplace
|
||
```
|
||
|
||
## 高级功能
|
||
|
||
### 添加钩子（Hooks）
|
||
|
||
在 `hooks/hooks.json` 中定义事件处理器：
|
||
|
||
```json
|
||
{
|
||
"PostToolUse": [
|
||
{
|
||
"matcher": "Write|Edit",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
> **注意**：`${CLAUDE_PLUGIN_ROOT}` 环境变量指向插件安装目录。
|
||
|
||
### 添加 MCP 服务器
|
||
|
||
在插件根目录创建 `.mcp.json`：
|
||
|
||
```json
|
||
{
|
||
"servers": {
|
||
"my-server": {
|
||
"command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
|
||
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 添加自定义代理
|
||
|
||
在 `agents/` 目录创建代理定义：
|
||
|
||
```markdown
|
||
# agents/code-assistant.md
|
||
---
|
||
description: 专注于代码质量的智能助手
|
||
allowed-tools: Read, Grep, Glob, Edit
|
||
---
|
||
|
||
# 代码助手代理
|
||
|
||
你是一个专注于代码质量的助手。
|
||
|
||
## 职责
|
||
|
||
1. 代码审查
|
||
2. 重构建议
|
||
3. 最佳实践指导
|
||
```
|
||
|
||
## 完整插件示例
|
||
|
||
### 示例：代码格式化插件
|
||
|
||
**目录结构：**
|
||
```
|
||
code-formatter/
|
||
├── .claude-plugin/
|
||
│ └── plugin.json
|
||
├── commands/
|
||
│ ├── format.md
|
||
│ └── lint.md
|
||
├── skills/
|
||
│ └── formatting-rules/
|
||
│ └── SKILL.md
|
||
└── scripts/
|
||
└── prettier-wrapper.sh
|
||
```
|
||
|
||
**plugin.json：**
|
||
```json
|
||
{
|
||
"name": "code-formatter",
|
||
"description": "自动代码格式化和 lint 检查",
|
||
"version": "1.0.0",
|
||
"author": {
|
||
"name": "DevTools Team"
|
||
},
|
||
"keywords": ["format", "lint", "prettier", "eslint"]
|
||
}
|
||
```
|
||
|
||
**commands/format.md：**
|
||
```markdown
|
||
---
|
||
description: 格式化当前文件或目录
|
||
argument-hint: [文件或目录路径]
|
||
allowed-tools: Bash(npx prettier:*), Read, Write
|
||
---
|
||
|
||
# 格式化命令
|
||
|
||
格式化指定的文件或目录：$ARGUMENTS
|
||
|
||
使用项目的 Prettier 配置进行格式化。
|
||
```
|
||
|
||
**commands/lint.md：**
|
||
```markdown
|
||
---
|
||
description: 运行 ESLint 检查
|
||
argument-hint: [文件或目录路径]
|
||
allowed-tools: Bash(npx eslint:*)
|
||
---
|
||
|
||
# Lint 检查命令
|
||
|
||
对指定的文件或目录运行 ESLint：$ARGUMENTS
|
||
|
||
报告所有问题并提供修复建议。
|
||
```
|
||
|
||
**skills/formatting-rules/SKILL.md：**
|
||
```yaml
|
||
---
|
||
name: formatting-rules
|
||
description: 了解项目的代码格式化规则。当需要手动格式化代码或解释格式化规则时使用。
|
||
---
|
||
|
||
# 格式化规则
|
||
|
||
## 常用规则
|
||
|
||
- 缩进：2 空格
|
||
- 分号：必需
|
||
- 引号：单引号
|
||
- 尾随逗号：ES5 兼容
|
||
|
||
## 配置文件
|
||
|
||
检查以下文件了解项目规则：
|
||
- `.prettierrc`
|
||
- `.eslintrc`
|
||
- `package.json` 中的 `prettier` 和 `eslintConfig`
|
||
```
|
||
|
||
## 团队插件配置
|
||
|
||
在仓库的 `.claude/settings.json` 中配置自动安装：
|
||
|
||
```json
|
||
{
|
||
"extraKnownMarketplaces": {
|
||
"team-tools": {
|
||
"source": {
|
||
"source": "github",
|
||
"repo": "your-org/claude-plugins"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
当团队成员信任该仓库后：
|
||
- 市场会自动安装
|
||
- 通过 `enabledPlugins` 字段指定的插件会自动安装
|
||
|
||
## 调试和验证
|
||
|
||
### 调试技巧
|
||
|
||
1. **检查结构**：确保目录在插件根目录，而非 `.claude-plugin/` 内部
|
||
2. **单独测试**：分别检查每个命令、代理和钩子
|
||
3. **使用验证工具**：参见插件参考文档了解 CLI 调试命令
|
||
4. **验证安装**：运行 `/help` 查看新命令是否列出
|
||
|
||
### 检查清单
|
||
|
||
- [ ] `.claude-plugin/plugin.json` 存在且格式正确
|
||
- [ ] 组件目录（commands/、skills/ 等）在插件根目录
|
||
- [ ] 命令文件为 `.md` 格式
|
||
- [ ] 技能目录包含 `SKILL.md` 文件
|
||
- [ ] YAML frontmatter 语法正确
|
||
|
||
### 常见问题
|
||
|
||
**命令不显示：**
|
||
- 检查文件扩展名是否为 `.md`
|
||
- 验证 frontmatter 格式正确
|
||
- 重启 Claude Code
|
||
|
||
**技能不激活：**
|
||
- 检查 `description` 是否足够具体
|
||
- 验证 `SKILL.md` 路径正确
|
||
|
||
## 分享插件前的准备
|
||
|
||
在分发插件之前：
|
||
- 添加 `README.md` 包含安装和使用说明
|
||
- 在 `plugin.json` 中使用语义化版本号
|
||
- 创建或使用市场进行分发
|
||
- 在更广泛发布前与他人测试
|
||
|
||
## 相关资源
|
||
|
||
- [自定义斜杠命令指南](./01-自定义斜杠命令指南.md)
|
||
- [Skills 技能指南](./02-技能指南.md)
|
||
- [Plugin Marketplaces 插件市场指南](./04-插件市场指南.md)
|
||
- [官方文档：插件系统](https://code.claude.com/docs/en/plugins)
|
||
- [官方文档：子代理](https://code.claude.com/docs/en/sub-agents)
|
||
- [官方文档：钩子](https://code.claude.com/docs/en/hooks)
|
||
- [官方文档：MCP](https://code.claude.com/docs/en/mcp)
|