agent-aide/docs/04-插件市场指南.md

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