🎉 init: 初始存档
This commit is contained in:
382
guide/04-插件市场指南.md
Executable file
382
guide/04-插件市场指南.md
Executable file
@@ -0,0 +1,382 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user