383 lines
8.6 KiB
Markdown
Executable File
383 lines
8.6 KiB
Markdown
Executable File
# Claude Code 插件市场（Plugin Marketplaces）指南
|
||
|
||
## 概述
|
||
|
||
插件市场是基于 JSON 的目录，用于集中发现、版本管理和团队分发 Claude Code 扩展。它支持来自多种来源（Git 仓库、GitHub、本地路径、包管理器）的插件。
|
||
|
||
### 核心功能
|
||
|
||
- **集中发现**：在一个地方浏览来自多个来源的插件
|
||
- **版本管理**：自动跟踪和更新插件版本
|
||
- **团队分发**：跨组织共享所需插件
|
||
- **灵活来源**：支持 Git 仓库、GitHub、本地路径等多种来源
|
||
- **环境变量**：使用 `${CLAUDE_PLUGIN_ROOT}` 引用插件安装目录
|
||
|
||
## 快速命令参考
|
||
|
||
```bash
|
||
# 添加 GitHub 市场
|
||
/plugin marketplace add owner/repo
|
||
|
||
# 添加 Git 仓库
|
||
/plugin marketplace add https://gitlab.com/company/plugins.git
|
||
|
||
# 添加本地市场
|
||
/plugin marketplace add ./my-marketplace
|
||
/plugin marketplace add ./path/to/marketplace.json
|
||
|
||
# 添加远程 URL
|
||
/plugin marketplace add https://url.of/marketplace.json
|
||
|
||
# 从市场安装插件
|
||
/plugin install plugin-name@marketplace-name
|
||
|
||
# 列出已配置市场
|
||
/plugin marketplace list
|
||
|
||
# 更新市场
|
||
/plugin marketplace update marketplace-name
|
||
|
||
# 删除市场
|
||
/plugin marketplace remove marketplace-name
|
||
```
|
||
|
||
## 市场结构
|
||
|
||
### 基本目录结构
|
||
|
||
在仓库根目录创建 `.claude-plugin/marketplace.json`：
|
||
|
||
```
|
||
my-marketplace/
|
||
├── .claude-plugin/
|
||
│ └── marketplace.json # 必需：市场索引文件
|
||
├── plugin-a/ # 本地插件 A
|
||
│ └── .claude-plugin/
|
||
│ └── plugin.json
|
||
├── plugin-b/ # 本地插件 B
|
||
│ └── .claude-plugin/
|
||
│ └── plugin.json
|
||
└── README.md # 可选：市场说明
|
||
```
|
||
|
||
### marketplace.json 基本格式
|
||
|
||
```json
|
||
{
|
||
"name": "company-tools",
|
||
"owner": {
|
||
"name": "DevTools Team",
|
||
"email": "team@example.com"
|
||
},
|
||
"plugins": [
|
||
{
|
||
"name": "code-formatter",
|
||
"source": "./plugins/formatter",
|
||
"description": "自动代码格式化"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 市场索引字段说明
|
||
|
||
### 必需字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `name` | string | 市场标识符（kebab-case，无空格） |
|
||
| `owner` | object | 市场维护者信息 |
|
||
| `plugins` | array | 可用插件列表 |
|
||
|
||
### 可选元数据字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `metadata.description` | string | 市场简介 |
|
||
| `metadata.version` | string | 市场版本 |
|
||
| `metadata.pluginRoot` | string | 相对插件来源的基础路径 |
|
||
|
||
## 插件条目配置
|
||
|
||
### 必需字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `name` | string | 插件标识符（kebab-case，无空格） |
|
||
| `source` | string\|object | 插件来源位置 |
|
||
|
||
### 可选元数据字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `description` | string | 插件功能描述 |
|
||
| `version` | string | 插件版本 |
|
||
| `author` | object | 插件作者信息 |
|
||
| `homepage` | string | 插件主页或文档 URL |
|
||
| `repository` | string | 源代码仓库 URL |
|
||
| `license` | string | SPDX 许可证标识符（MIT、Apache-2.0 等） |
|
||
| `keywords` | array | 发现和分类标签 |
|
||
| `category` | string | 插件分类 |
|
||
| `tags` | array | 搜索标签 |
|
||
| `strict` | boolean | 是否要求文件夹中有 plugin.json（默认：true） |
|
||
|
||
### 组件配置字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `commands` | string\|array | 命令文件或目录的自定义路径 |
|
||
| `agents` | string\|array | 代理文件的自定义路径 |
|
||
| `hooks` | string\|object | 钩子配置或钩子文件路径 |
|
||
| `mcpServers` | string\|object | MCP 服务器配置或 MCP 配置文件路径 |
|
||
|
||
## 插件来源配置
|
||
|
||
### 相对路径（同一仓库内）
|
||
|
||
```json
|
||
{
|
||
"name": "my-plugin",
|
||
"source": "./plugins/my-plugin"
|
||
}
|
||
```
|
||
|
||
### GitHub 仓库
|
||
|
||
```json
|
||
{
|
||
"name": "github-plugin",
|
||
"source": {
|
||
"source": "github",
|
||
"repo": "owner/plugin-repo"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Git 仓库（任意服务）
|
||
|
||
```json
|
||
{
|
||
"name": "git-plugin",
|
||
"source": {
|
||
"source": "url",
|
||
"url": "https://gitlab.com/team/plugin.git"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 完整配置示例
|
||
|
||
### 市场配置
|
||
|
||
```json
|
||
{
|
||
"name": "enterprise-marketplace",
|
||
"owner": {
|
||
"name": "Enterprise Team",
|
||
"email": "enterprise@company.com"
|
||
},
|
||
"metadata": {
|
||
"description": "企业级 Claude Code 插件集合",
|
||
"version": "2.0.0"
|
||
},
|
||
"plugins": [
|
||
{
|
||
"name": "code-formatter",
|
||
"source": "./plugins/formatter",
|
||
"description": "自动代码格式化",
|
||
"version": "2.1.0"
|
||
},
|
||
{
|
||
"name": "security-scanner",
|
||
"source": {
|
||
"source": "github",
|
||
"repo": "company/security-plugin"
|
||
},
|
||
"description": "代码安全扫描"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 高级插件条目
|
||
|
||
```json
|
||
{
|
||
"name": "enterprise-tools",
|
||
"source": {
|
||
"source": "github",
|
||
"repo": "company/enterprise-plugin"
|
||
},
|
||
"description": "企业工作流自动化工具",
|
||
"version": "2.1.0",
|
||
"author": {
|
||
"name": "Enterprise Team",
|
||
"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"],
|
||
"category": "productivity",
|
||
"commands": [
|
||
"./commands/core/",
|
||
"./commands/enterprise/",
|
||
"./commands/experimental/preview.md"
|
||
],
|
||
"agents": [
|
||
"./agents/security-reviewer.md",
|
||
"./agents/compliance-checker.md"
|
||
],
|
||
"hooks": {
|
||
"PostToolUse": [
|
||
{
|
||
"matcher": "Write|Edit",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
},
|
||
"mcpServers": {
|
||
"enterprise-db": {
|
||
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
|
||
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
|
||
}
|
||
},
|
||
"strict": false
|
||
}
|
||
```
|
||
|
||
## 创建和使用市场
|
||
|
||
### 创建本地市场
|
||
|
||
```bash
|
||
# 1. 创建市场目录
|
||
mkdir -p my-marketplace/.claude-plugin
|
||
|
||
# 2. 创建市场索引
|
||
cat > my-marketplace/.claude-plugin/marketplace.json << 'EOF'
|
||
{
|
||
"name": "my-marketplace",
|
||
"owner": {
|
||
"name": "Your Name"
|
||
},
|
||
"plugins": []
|
||
}
|
||
EOF
|
||
|
||
# 3. 添加插件到市场
|
||
mkdir -p my-marketplace/hello-plugin/.claude-plugin
|
||
# ... 创建插件文件 ...
|
||
|
||
# 4. 更新市场索引添加插件条目
|
||
```
|
||
|
||
### 从市场安装插件
|
||
|
||
```bash
|
||
# 从已知市场安装
|
||
/plugin install plugin-name@marketplace-name
|
||
|
||
# 交互式浏览
|
||
/plugin
|
||
```
|
||
|
||
## 团队市场配置
|
||
|
||
在项目的 `.claude/settings.json` 中配置自动安装：
|
||
|
||
```json
|
||
{
|
||
"extraKnownMarketplaces": {
|
||
"team-tools": {
|
||
"source": {
|
||
"source": "github",
|
||
"repo": "your-org/claude-plugins"
|
||
}
|
||
},
|
||
"project-specific": {
|
||
"source": {
|
||
"source": "git",
|
||
"url": "https://git.company.com/project-plugins.git"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
当团队成员信任该仓库文件夹后，Claude Code 会自动安装这些市场，以及通过 `enabledPlugins` 字段指定的任何插件。
|
||
|
||
## 托管和分发
|
||
|
||
### GitHub 托管（推荐）
|
||
|
||
1. 创建 GitHub 仓库
|
||
2. 添加 `.claude-plugin/marketplace.json`
|
||
3. 添加插件目录
|
||
4. 用户通过以下命令添加：
|
||
```bash
|
||
/plugin marketplace add owner/repo
|
||
```
|
||
|
||
### 其他 Git 服务
|
||
|
||
```bash
|
||
/plugin marketplace add https://gitlab.com/company/plugins.git
|
||
```
|
||
|
||
### 本地开发测试
|
||
|
||
```bash
|
||
/plugin marketplace add ./my-local-marketplace
|
||
/plugin install test-plugin@my-local-marketplace
|
||
```
|
||
|
||
## 验证和测试
|
||
|
||
```bash
|
||
# 验证市场 JSON 语法和结构
|
||
claude plugin validate .
|
||
|
||
# 添加本地市场测试
|
||
/plugin marketplace add ./path/to/marketplace
|
||
|
||
# 测试插件安装
|
||
/plugin install test-plugin@marketplace-name
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 市场无法加载
|
||
|
||
- 验证市场 URL 可访问
|
||
- 检查 `.claude-plugin/marketplace.json` 存在
|
||
- 验证 JSON 语法有效
|
||
- 私有仓库需确保有访问权限
|
||
|
||
### 插件安装失败
|
||
|
||
- 验证插件源 URL 可访问
|
||
- 检查插件目录包含必需文件
|
||
- GitHub 源需确保仓库公开或有权限
|
||
- 验证插件来源可手动下载
|
||
|
||
## 最佳实践
|
||
|
||
1. **清晰命名**：使用有意义的市场和插件名称
|
||
2. **完整描述**：为每个插件提供清晰的功能描述
|
||
3. **版本管理**：使用语义化版本号
|
||
4. **文档齐全**：提供 README 和使用说明
|
||
5. **定期更新**：保持插件和市场元数据最新
|
||
|
||
## 相关资源
|
||
|
||
- [自定义斜杠命令指南](./01-自定义斜杠命令指南.md)
|
||
- [Skills 技能指南](./02-技能指南.md)
|
||
- [Plugins 插件指南](./03-插件指南.md)
|
||
- [官方文档：插件市场](https://code.claude.com/docs/en/plugin-marketplaces)
|