sayurinana/agent-aide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
agent-aide/docs/reference/04-插件市场指南.md
sayurinana(vm) 0079bd5cd4 📃 docs: 暂存
2025-12-18 22:52:53 +08:00

8.6 KiB
Executable File
Raw Permalink Blame History

Claude Code 插件市场（Plugin Marketplaces）指南

概述

插件市场是基于 JSON 的目录，用于集中发现、版本管理和团队分发 Claude Code 扩展。它支持来自多种来源（Git 仓库、GitHub、本地路径、包管理器）的插件。

核心功能

  • 集中发现：在一个地方浏览来自多个来源的插件
  • 版本管理：自动跟踪和更新插件版本
  • 团队分发：跨组织共享所需插件
  • 灵活来源：支持 Git 仓库、GitHub、本地路径等多种来源
  • 环境变量：使用 ${CLAUDE_PLUGIN_ROOT} 引用插件安装目录

快速命令参考

# 添加 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 基本格式

{
  "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 配置文件路径

插件来源配置

相对路径（同一仓库内）

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

GitHub 仓库

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

Git 仓库（任意服务）

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

完整配置示例

市场配置

{
  "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": "代码安全扫描"
    }
  ]
}

高级插件条目

{
  "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
}

创建和使用市场

创建本地市场

# 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. 更新市场索引添加插件条目

从市场安装插件

# 从已知市场安装
/plugin install plugin-name@marketplace-name

# 交互式浏览
/plugin

团队市场配置

在项目的 .claude/settings.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. 用户通过以下命令添加： 
    /plugin marketplace add owner/repo

其他 Git 服务

/plugin marketplace add https://gitlab.com/company/plugins.git

本地开发测试

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

验证和测试

# 验证市场 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. 定期更新：保持插件和市场元数据最新

相关资源