# 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)