📃 docs: 暂存
This commit is contained in:
436
docs/reference/03-插件指南.md
Executable file
436
docs/reference/03-插件指南.md
Executable file
@@ -0,0 +1,436 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user