Claude-Code插件市场设计

# 14. Claude Code 插件市场设计

适用场景：为 Claude Code CLI 设计一个完整的插件市场系统，包括插件发现、安装、更新、卸载等全生命周期管理。

关键词：Plugin Marketplace, CLI Extension, Semantic Versioning, Git-based Registry

# 一、为什么需要插件市场？

Claude Code 作为 AI 编程助手，核心能力有限。用户需求千奇百怪：

有人要连接企业内部 API
有人要集成特定框架（React、Spring、Django）
有人要定制代码风格检查
有人要接入私有知识库

核心问题：不能把所有功能塞进主程序，否则：

包体积爆炸
启动速度变慢
维护成本失控

解决方案：插件市场——让生态自己生长。

# 二、整体架构设计

┌─────────────────────────────────────────────────────────┐
│                    Claude Code CLI                       │
├─────────────────────────────────────────────────────────┤
│  /plugin  │  /market  │  /config  │  /doctor  │  ...   │
└─────┬─────┴─────┬─────┴─────┬─────┴─────┬─────┴────────┘
      │           │           │           │
      ▼           ▼           ▼           ▼
┌─────────────────────────────────────────────────────────┐
│                   Plugin Manager                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │ Registry │  │ Resolver │  │ Sandbox  │  │ Cache   │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
└─────┬─────────────┬─────────────┬─────────────┬────────┘
      │             │             │             │
      ▼             ▼             ▼             ▼
┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│ Official │  │ GitHub   │  │ Private  │  │ Local    │
│ Registry │  │ Registry │  │ Registry │  │ Plugins  │
└──────────┘  └──────────┘  └──────────┘  └──────────┘

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

核心组件：

组件	职责
Registry	插件注册表，存储元数据
Resolver	依赖解析，版本冲突处理
Sandbox	隔离执行，权限控制
Cache	本地缓存，离线支持

# 三、Marketplace 配置规范

# 3.1 marketplace.json 结构

每个插件市场（Registry）需要一个 marketplace.json 声明基本信息：

{
  "$schema": "https://claudecode.dev/schemas/marketplace.json",
  "name": "claude-code-official",
  "displayName": "Claude Code Official Marketplace",
  "description": "官方插件市场，由 Anthropic 维护",
  "version": "1.0.0",
  "maintainer": {
    "name": "Anthropic",
    "email": "plugins@anthropic.com",
    "url": "https://anthropic.com"
  },
  "plugins": [
    {
      "name": "kit",
      "version": "2.3.1",
      "path": "plugins/kit",
      "manifest": "plugin.json"
    },
    {
      "name": "react-helper",
      "version": "1.0.0",
      "path": "plugins/react-helper",
      "manifest": "plugin.json"
    }
  ],
  "signature": "sha256:abc123...",
  "updatedAt": "2026-06-17T00:00:00Z"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# 3.2 字段说明

字段	必填	说明
`name`	✅	市场唯一标识（小写字母、数字、连字符）
`displayName`	✅	显示名称
`description`	❌	市场描述
`version`	✅	市场配置版本（SemVer）
`maintainer`	✅	维护者信息
`plugins`	✅	插件列表
`signature`	❌	数字签名（用于验证完整性）
`updatedAt`	❌	最后更新时间（ISO 8601）

# 四、插件清单：plugin.json

每个插件需要一个 plugin.json 声明元数据和能力：

{
  "$schema": "https://claudecode.dev/schemas/plugin.json",
  "name": "kit",
  "version": "2.3.1",
  "displayName": "Claude Code Kit",
  "description": "官方工具集，包含代码生成、重构、测试等增强功能",
  "author": {
    "name": "Anthropic",
    "email": "support@anthropic.com"
  },
  "license": "MIT",
  "repository": "https://github.com/anthropics/claude-code-kit",
  "keywords": ["tools", "refactor", "test", "official"],
  "engines": {
    "claude-code": ">=1.0.0 <2.0.0",
    "node": ">=18.0.0"
  },
  "dependencies": {
    "common-utils": "^1.2.0"
  },
  "entry": "./dist/index.js",
  "commands": [
    {
      "command": "kit:refactor",
      "description": "智能重构代码"
    },
    {
      "command": "kit:test",
      "description": "生成单元测试"
    }
  ],
  "permissions": [
    "fs.read",
    "fs.write",
    "http.request",
    "shell.execute"
  ],
  "config": {
    "apiKey": {
      "type": "string",
      "description": "API 密钥（可选）",
      "required": false,
      "secret": true
    },
    "maxWorkers": {
      "type": "number",
      "description": "最大并发数",
      "default": 4
    }
  },
  "hooks": {
    "preInstall": "./scripts/pre-install.js",
    "postInstall": "./scripts/post-install.js",
    "preUninstall": "./scripts/pre-uninstall.js"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

# 4.1 关键字段解析

字段	说明
`engines`	运行环境要求，CLI 版本、Node 版本等
`dependencies`	插件间依赖，支持版本范围
`entry`	入口文件，ES Module 格式
`commands`	注册的 CLI 命令
`permissions`	申请的权限（安装时需用户确认）
`config`	可配置项（运行时可通过 `/config` 修改）
`hooks`	生命周期钩子脚本

# 五、CLI 命令设计

# 5.1 市场管理

# 添加市场（支持 Git URL、本地路径、HTTP URL）
/plugin marketplace add https://github.com/anthropics/claude-plugins.git#main
/plugin marketplace add https://plugins.mycompany.com/registry.json
/plugin marketplace add ./local-plugins

# 列出所有市场
/plugin marketplace list

# 更新市场索引
/plugin marketplace update claude-code-official
/plugin marketplace update --all

# 移除市场
/plugin marketplace remove claude-code-official

# 显示市场详情
/plugin marketplace info claude-code-official

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 5.2 插件管理

# 搜索插件
/plugin search react
/plugin search --author anthropic
/plugin search --tag testing

# 查看插件详情
/plugin info kit
/plugin info kit@2.3.0  # 指定版本

# 安装插件
/plugin install kit
/plugin install kit@2.3.0
/plugin install https://github.com/user/my-plugin.git#v1.0.0

# 更新插件
/plugin update kit
/plugin update kit@latest
/plugin update --all

# 卸载插件
/plugin uninstall kit

# 列出已安装插件
/plugin list
/plugin list --outdated  # 显示可更新的

# 启用/禁用插件
/plugin enable kit
/plugin disable kit

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 5.3 调试与诊断

# 检查插件健康状态
/plugin doctor
/plugin doctor kit

# 查看插件日志
/plugin logs kit
/plugin logs kit --follow

# 清理缓存
/plugin cache clean
/plugin cache clean kit

# 验证插件签名
/plugin verify kit

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 六、插件生命周期

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Search  │───▶│  Install │───▶│  Enable  │───▶│  Active  │
└──────────┘    └──────────┘    └──────────┘    └────┬─────┘
                     │                │             │
                     │                │             ▼
                     │                │        ┌──────────┐
                     │                │        │ Disable  │
                     │                │        └────┬─────┘
                     │                │             │
                     │                ▼             ▼
                     │          ┌──────────┐  ┌──────────┐
                     │          │ Update   │  │Uninstall │
                     │          └──────────┘  └──────────┘
                     │
                     ▼
                ┌──────────┐
                │ Rollback │
                └──────────┘

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 6.1 安装流程

/plugin install kit@2.3.0

内部执行：

解析依赖 → 构建依赖树
检查权限 → 展示权限列表，请求用户确认
下载插件 → 从 Registry 下载到本地缓存
验证签名 → 校验 SHA256 或 GPG 签名
执行钩子 → 运行 preInstall 脚本
安装依赖 → 递归安装 dependencies
注册命令 → 将插件命令注册到 CLI
执行钩子 → 运行 postInstall 脚本
更新索引 → 写入 installed.json

# 6.2 更新流程

/plugin update kit

内部执行：

检查版本 → 对比本地与 Registry 版本
下载新版本 → 缓存旧版本以便回滚
迁移配置 → 保留用户配置
更新依赖 → 重新解析依赖树
重启服务 → 热加载新版本

# 6.3 回滚机制

# 安装失败自动回滚
/plugin install kit --rollback-on-failure

# 手动回滚到上一版本
/plugin rollback kit
/plugin rollback kit --to 2.2.0

1
2
3
4
5
6

# 七、安全与审核机制

# 7.1 权限模型

{
  "permissions": [
    "fs.read",           // 读取文件
    "fs.write",          // 写入文件
    "fs.delete",         // 删除文件
    "http.request",      // 发送 HTTP 请求
    "http.request.*",    // 发送到任意域名
    "shell.execute",     // 执行 Shell 命令
    "shell.execute.safe", // 只允许白名单命令
    "env.read",          // 读取环境变量
    "env.write",         // 写入环境变量
    "clipboard.read",    // 读取剪贴板
    "clipboard.write"    // 写入剪贴板
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

权限分级：

级别	说明	示例
`safe`	无需用户确认	`fs.read`（当前项目目录内）
`moderate`	首次确认后记住	`http.request`（指定域名白名单）
`dangerous`	每次操作都确认	`shell.execute`、`fs.delete`

# 7.2 沙箱隔离

// 插件运行在隔离的 VM Context 中
const vm = require('vm');
const context = vm.createContext({
  // 只暴露白名单 API
  console: safeConsole,
  fetch: sandboxedFetch,
  fs: sandboxedFs,
  // 禁止访问 process、require 等
});
vm.runInContext(pluginCode, context, { timeout: 30000 });

1
2
3
4
5
6
7
8
9
10

# 7.3 签名验证

# 生成签名
/plugin sign kit --key ~/.ssh/plugin-signing-key.pem

# 验证签名
/plugin verify kit --key https://anthropic.com/pubkey.pem

1
2
3
4
5

签名流程：

开发者用私钥对 plugin.json + dist/ 签名
签名写入 plugin.json.signature
CLI 下载后用公钥验证

# 八、版本管理

# 8.1 语义化版本

遵循 SemVer 2.0 (opens new window)：

MAJOR.MINOR.PATCH

MAJOR: 不兼容的 API 变更
MINOR: 向后兼容的功能新增
PATCH: 向后兼容的问题修复

1
2
3
4
5

# 8.2 版本范围语法

{
  "dependencies": {
    "common-utils": "^1.2.0",    // >=1.2.0 <2.0.0
    "logger": "~2.1.0",          // >=2.1.0 <2.2.0
    "validator": ">=3.0.0",      // >=3.0.0
    "cache": "1.0.0 - 1.5.0",    // >=1.0.0 <=1.5.0
    "core": "*"                  // 任意版本
  }
}

1
2
3
4
5
6
7
8
9

# 8.3 锁文件

生成 plugin-lock.json 锁定具体版本：

{
  "lockfileVersion": 1,
  "plugins": {
    "kit": {
      "version": "2.3.1",
      "resolved": "https://github.com/anthropics/kit/archive/v2.3.1.tar.gz",
      "integrity": "sha256-abc123...",
      "dependencies": {
        "common-utils": "1.2.5"
      }
    },
    "common-utils": {
      "version": "1.2.5",
      "resolved": "https://registry.npmjs.org/common-utils/-/1.2.5.tgz",
      "integrity": "sha256-def456..."
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 九、缓存与离线支持

# 9.1 缓存目录结构

~/.claude-code/
├── cache/
│   ├── plugins/
│   │   ├── kit@2.3.1/
│   │   │   ├── plugin.json
│   │   │   ├── dist/
│   │   │   └── integrity.json
│   │   └── kit@2.3.0/
│   └── registries/
│       ├── claude-code-official.json
│       └── my-company.json
├── installed.json
└── plugin-lock.json

1
2
3
4
5
6
7
8
9
10
11
12
13

# 9.2 离线模式

# 优先使用缓存
/plugin install kit --offline

# 预下载所有依赖（部署前执行）
/plugin prefetch --all
/plugin prefetch kit react-helper

1
2
3
4
5
6

# 十、示例：从零发布一个插件

# 10.1 创建项目

mkdir my-awesome-plugin
cd my-awesome-plugin
npm init -y

1
2
3

# 10.2 编写 plugin.json

{
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "displayName": "My Awesome Plugin",
  "description": "一个示例插件",
  "entry": "./src/index.js",
  "commands": [
    {
      "command": "awesome:greet",
      "description": "打招呼"
    }
  ],
  "permissions": ["fs.read"]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 10.3 编写代码

// src/index.js
export function activate(context) {
  context.registerCommand('awesome:greet', async (args) => {
    const name = args[0] || 'World';
    return `Hello, ${name}!`;
  });
}

export function deactivate() {
  console.log('Plugin deactivated');
}

1
2
3
4
5
6
7
8
9
10
11

# 10.4 本地测试

# 在插件目录执行
ln -s $(pwd) ~/.claude-code/plugins/my-awesome-plugin

# 重启 CLI 测试
claude-code
> /awesome:greet Claude
Hello, Claude!

1
2
3
4
5
6
7

# 10.5 发布到 Registry

# 打包
npm pack

# 发布到 GitHub Registry
git tag v1.0.0
git push origin v1.0.0

# 更新 marketplace.json
# 添加：
# {
#   "name": "my-awesome-plugin",
#   "version": "1.0.0",
#   "path": "plugins/my-awesome-plugin"
# }

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 10.6 用户安装

/plugin marketplace add https://github.com/your-org/claude-plugins.git
/plugin install my-awesome-plugin

1
2

# 十一、高级特性

# 11.1 插件配置

# 查看配置
/plugin config kit

# 设置配置
/plugin config kit apiKey sk-xxx
/plugin config kit maxWorkers 8

# 导出/导入配置
/plugin config kit --export > kit-config.json
/plugin config kit --import kit-config.json

1
2
3
4
5
6
7
8
9
10

# 11.2 插件组合（Presets）

// presets/react.json
{
  "name": "react-preset",
  "plugins": [
    "react-helper@^1.0.0",
    "eslint-integration@^2.0.0",
    "testing-utils@^1.5.0"
  ]
}

1
2
3
4
5
6
7
8
9

/plugin preset install react-preset

# 11.3 插件依赖注入

// 插件 A 提供服务
export function activate(context) {
  context.provide('logger', {
    info: (msg) => console.log(`[INFO] ${msg}`),
    error: (msg) => console.error(`[ERROR] ${msg}`)
  });
}

// 插件 B 使用服务
export function activate(context) {
  const logger = context.consume('logger');
  logger.info('Plugin B activated');
}

1
2
3
4
5
6
7
8
9
10
11
12
13

# 十二、最佳实践

# 12.1 插件开发

单一职责：一个插件只做一件事
最小权限：只申请必要的权限
优雅降级：依赖缺失时提供 fallback
完善文档：README 包含使用示例和 API 说明
版本兼容：遵循 SemVer，破坏性变更升级大版本

# 12.2 市场运维

定期审核：检查插件安全性和活跃度
自动测试：CI 流水线运行插件测试
版本归档：保留历史版本，支持回滚
镜像备份：多地部署 Registry，避免单点故障

# 12.3 安全建议

信任来源：只添加可信的 Registry
验证签名：启用签名验证
定期更新：及时修复漏洞
最小化安装：只安装必要的插件

# 十三、常见问题

# Q1: 插件安装失败如何排查？

# 查看详细日志
/plugin install kit --verbose

# 检查网络连接
/plugin doctor --network

# 清理缓存重试
/plugin cache clean kit
/plugin install kit

1
2
3
4
5
6
7
8
9

# Q2: 如何解决版本冲突？

# 查看依赖树
/plugin deps kit --tree

# 强制指定版本
/plugin install kit@2.3.0 --force

1
2
3
4
5

# Q3: 插件导致 CLI 崩溃怎么办？

# 安全模式启动（禁用所有插件）
claude-code --safe

# 卸载问题插件
/plugin uninstall kit

1
2
3
4
5

# 十四、总结

一个完善的插件市场需要解决四个核心问题：

问题	解决方案
发现	Registry + marketplace.json + 搜索命令
安装	依赖解析 + 权限确认 + 签名验证
管理	版本控制 + 配置持久化 + 生命周期钩子
安全	权限模型 + 沙箱隔离 + 代码审计

设计 CLI 插件市场，本质上是在能力扩展与安全可控之间寻找平衡。

# 参考资料

最后更新：2026-06-17 作者：墨隐

上次更新: 2026/6/17 17:04:02

← XXL-JOB 分布式任务调度平台部署 MCP与Skill选择指南→