Open Plugins：AI 编程助手的插件标准

2026年7月18日 · 阅读需 19 分钟

Booker Zhao

AI Full-Stack Engineer / CloudBase AI ToolKit Author

一个插件标准，七个工具共用

图：Open Plugins 标准——装一个就能在七个工具里用

最近 AI 编程工具越来越多：Cursor、Claude Code、Codex、Grok Build……每个一套插件格式。然后冒出了个 Open Plugins。

它是 Vercel Labs 维护的一个开放标准。装一个插件，就能在七个工具里跑。

现状：AI 编程工具的"插件战国"

先说问题。

图：各工具各说各话，夹不到一起

假设你有一组很好用的 AI 编程辅助工具：

一个代码审查 skill，每次提交前自动审查变更
一个 MCP 服务器，连接到公司的 API 文档
一个钩子脚本，保存文件时自动格式化

在 Claude Code 里配一遍，换到 Cursor 又得重新配，换到 Codex 格式可能还不一样。这就像 npm 出现之前的 JavaScript——每个库有自己的模块格式，想复用就得手动折腾。

Open Plugins 的目的就是终结这种割裂：定一套标准，所有工具共用。

npx plugins：怎么装

怎么用？一条命令：

# 从 GitHub 安装插件（短格式）
npx plugins add vercel/vercel-plugin

# 完整 HTTPS URL
npx plugins add https://github.com/vercel/vercel-plugin

# 从本地目录安装
npx plugins add ./my-plugin

# 先看看有哪些组件，不实际安装
npx plugins discover owner/repo

# 查看本地已检测到的工具
npx plugins targets

这个 plugins 包（v1.3.4）就是 Open Plugins 生态的"安装器"。安装后的存储路径统一走 .agents/plugins/。

它的工作流程可以看作一条流水线：

支持的安装 scope 分为三档：

npx plugins add repo --scope user     # 用户级（~/.agents/plugins/）
npx plugins add repo --scope project  # 项目级（./.agents/plugins/）
npx plugins add repo --scope local    # 仅本地开发测试

还可以指定安装到某个特定工具：

npx plugins add owner/repo -t grok     # 只装到 Grok Build
npx plugins add owner/repo -t vscode   # 只装到 VS Code

支持七种 AI 编程工具

npx plugins targets 会检测你机器上安装了哪些工具，然后自动安装到所有检测到的目标。

图：七种 AI 编程工具，一个插件标准全支持

不过，装完不等于每个组件都在所有工具里能用。这里有个关键认知——Open Plugin Spec v1 保证的只有两类组件：Skills 和 MCP。其他组件（Hooks、Commands、Agents）不在 v1 规范里，支不支持完全看宿主工具。

Spec v1 保证 → Skills + MCP（装完就能用）
Spec v1 不保证 → Hooks / Commands / Agents（宿主不认识就忽略，不报错）

来看看各工具的实际情况：

工具	Skills	MCP	Hooks	Agents	Commands	备注
Claude Code	⭐ v1	⭐ v1	✅ 原生	✅ 原生	✅ 原生	最全面的宿主
Cursor	⭐ v1	⭐ v1	✅	❌	❌
Codex	⭐ v1	⭐ v1	✅	✅	✅
Grok Build	⭐ v1	⭐ v1	✅	❌	❌
Kimi Code	⭐ v1	⭐ v1	❌	❌	❌
GitHub Copilot CLI	⭐ v1	⭐ v1	✅	✅	✅
VS Code	⭐ v1	⭐ v1	❌	❌	❌	Preview

⭐ v1 = Spec v1 标准保证；✅ = 宿主额外支持；❌ = 不支持（宿主会静默忽略）

关键要点：

Skills + MCP 是跨 IDE 通用协议，装到哪个工具都能用——这是我们推荐 npx plugins add 的根本原因
Hooks 不是全员标配。Claude Code 和 Copilot CLI 支持最完整，VS Code 和 Kimi Code 就不认
Claude Code 通过原生 marketplace 机制支持最全（hooks + commands + agents），但那是宿主能力，不是 v1 标准
不支持 Hooks 的工具会静默忽略，不会报错，插件仍然能正常工作

协议拆解

一个插件其实就是按约定结构放了一堆文件的目录。

标准目录结构

安装后的存储路径分两个 scope：

~/.agents/plugins/          # 用户级
<project>/.agents/plugins/  # 项目级

plugin.json 清单文件

清单文件是可选的。如果省略，插件名称从目录名派生，组件只在默认位置发现。

如果提供，name 是唯一必填字段：

{
  "name": "my-plugin",
  "version": "1.2.0",
  "description": "插件描述",
  "author": {
    "name": "Author",
    "email": "author@example.com"
  },
  "homepage": "https://example.com",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["code-review", "automation"]
}

name 的命名约束：1-64 字符，小写字母/数字/连字符/点号，字母数字开头结尾，禁止 -- 或 ..。✅ deployment-tools、code-reviewer、prompts.chat ❌ My-Plugin、-tools、my--plugin

组件发现算法

这是协议最核心的部分。工具扫描插件的完整流程：

插件的四步生命周期——从安装到激活：

图：插件的安装、发现、命名空间和激活流程

`${PLUGIN_ROOT}` 路径展开

插件内的所有配置文件中都可以使用 ${PLUGIN_ROOT}，工具加载时自动替换为插件根目录的绝对路径。这个机制让插件可以自包含——所有路径引用都相对于自身，装到任何位置都能工作。

{
  "mcpServers": {
    "db-server": {
      "command": "${PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${PLUGIN_ROOT}/data"
      }
    }
  }
}

扩展规则：递归展开，嵌套引用也会被替换；逃逸检查保证路径不超出插件目录。

实战：把 CloudBase MCP 改成 Open Plugins 插件

前面讲了一堆理论，来点真实的。

我们最近在维护一个叫 CloudBase MCP 的开源项目，给 AI 编程工具提供云接入能力——AI 模型调用、NoSQL/PostgreSQL 数据库、云函数、云托管、云存储、微信小程序对接等等。以前手动配 .claude-plugin/、.codex-plugin/、.mcp.json，每个工具一个配置，维护起来头大。这次正好借 Open Plugins 标准的东风，做了一次改造。

完整改造 PR：TencentCloudBase/CloudBase-MCP#808（+818 / -34）

图：PR #808 改造前后对比——从 vendor 专属格式到通用插件标准

改造前后对比

plugin.json

按照 Open Plugins 规范 v1.0.0 的 closed schema，只保留规范允许的元数据字段：

{
  "$schema": "https://open-plugins.com/schemas/1.0.0/plugin.schema.json",
  "name": "cloudbase",
  "version": "0.2.0",
  "description": "Tencent CloudBase — AI models, authentication, NoSQL/PostgreSQL databases, cloud functions, cloud storage, CloudRun backend services, and WeChat Mini Program integration.",
  "author": {
    "name": "Tencent CloudBase",
    "url": "https://cloudbase.net"
  },
  "homepage": "https://github.com/TencentCloudBase/cloudbase-mcp",
  "license": "MIT",
  "keywords": [
    "cloudbase", "tencent-cloud", "baas",
    "ai-model", "database", "cloud-function",
    "authentication", "storage", "cloudrun"
  ]
}

mcp.json

MCP 服务器配置从 .mcp.json 复制到规范路径 mcp.json：

{
  "mcpServers": {
    "cloudbase-mcp": {
      "command": "npx",
      "args": ["-y", "@cloudbase/cloudbase-mcp@latest"],
      "env": {}
    }
  }
}

自动化构建

写了 build-open-plugin-spec.mjs 构建脚本，从 .claude-plugin/plugin.json 自动生成产物。还加了 --check 模式跑在 CI 里——每次 PR 自动校验，防止改源码忘了更新。

# 生成产物
node scripts/build-open-plugin-spec.mjs

# CI 模式：只检查不写入
node scripts/build-open-plugin-spec.mjs --check

配了 GitHub Actions workflow（.github/workflows/open-plugin-spec-check.yml），PR 自动跑检查。

验收结果

最大的成就感是一行命令装到所有工具：

npx plugins add TencentCloudBase/cloudbase-plugin

而且因为之前就已经在 skills/ 目录下放了 4 个 Skill，npx plugins discover 自动把它们注册为命名空间下的命令：

组件	用户调用方式
`skills/ai-model/`	`/cloudbase:ai-model`
`skills/cloudbase-data/`	`/cloudbase:cloudbase-data`
`skills/cloud-functions/`	`/cloudbase:cloud-functions`
`skills/mini-program/`	`/cloudbase:mini-program`

不用多写一行配置，按规范放目录就行。

第一个坑：marketplace.json 冲突

PR #808 合进去之后，兴冲冲跑 npx plugins add TencentCloudBase/CloudBase-MCP，结果：

No plugins found. 2 remote plugin(s) not shown.

插件就在仓库里，但 CLI 说找不到。

查了半天发现原因：主仓库根目录有一个 marketplace.json，这是给 Claude Code 和 Codex 的 marketplace add 用的索引文件。npx plugins CLI 检测到它后，把整个仓库识别为 marketplace（多插件集合），拒绝安装其中的子目录插件。

解决方案：创建专门插件仓库

参考 Vercel（vercel/vercel-plugin）和 Supabase（supabase-community/supabase-plugin）的做法——建专门的插件仓库，根目录只有 .plugin/plugin.json，没有 marketplace.json，让 CLI 识别为单插件。

创建了两个仓库：

仓库	安装命令	内容
`TencentCloudBase/cloudbase-plugin`	`npx plugins add TencentCloudBase/cloudbase-plugin`	28 skills + MCP + 5 commands + 2 agents + hooks
`TencentCloudBase/cloudbase-sites-plugin`	`npx plugins add TencentCloudBase/cloudbase-sites-plugin`	1 skill + MCP + hooks

内容从主仓库 plugin/cloudbase/ 和 plugin/cloudbase-sites/ 自动同步，同步时排除 marketplace.json——这是关键。

自动化同步机制

新增了这些文件：

文件	作用
`scripts/push-plugin-repos.mjs`	构建插件仓库产物到 `.plugin-repo-output/`
`.github/workflows/push-plugin-repos.yaml`	CI 自动同步 workflow
`scripts/build-open-plugin-spec.mjs`（扩展）	同时处理 cloudbase + cloudbase-sites
`plugin/cloudbase-sites/.plugin/plugin.json`	cloudbase-sites 的 Open Plugin Spec manifest
`plugin/cloudbase-sites/mcp.json`	cloudbase-sites 的 MCP 配置

验证全部通过：

npx plugins discover TencentCloudBase/cloudbase-plugin --remote
# → ✅ Found 1 local plugin(s), 28 skills, 5 cmds, 2 agents, hooks

npx plugins add TencentCloudBase/cloudbase-plugin --target cursor --scope local
# → ✅ Installed

npx plugins discover TencentCloudBase/cloudbase-sites-plugin --remote
# → ✅ Found 1 local plugin(s), 1 skill, hooks

现在的安装命令统一指向专门仓库：

# 主插件
npx plugins add TencentCloudBase/cloudbase-plugin

# Sites 插件
npx plugins add TencentCloudBase/cloudbase-sites-plugin

这个坑的核心教训是：Open Plugins 会把根目录有 marketplace.json 的仓库当作插件集合，而非单插件。 如果你的仓库本身就有多个发布物（像 CloudBase-MCP 既有 MCP 服务器又有插件），需要建专门的插件仓库。Vercel 和 Supabase 也是这样做的。

Hook 系统

我看规范时觉得最值钱的部分是这个——Hook 能在 agent 工作流的各个生命周期点插一脚。不过注意：Hook 不在 Spec v1 标准里，支不支持全看宿主工具。Claude Code 和 Copilot CLI 支持最全，VS Code 和 Kimi Code 就不认（静默忽略，不报错）。

下面讲的事件模型来自 Open Plugin Spec 的 Hooks 组件规范——如果你的宿主工具支持 Hooks，这就是它的工作方式。

图：Hook 系统——从 SessionStart 到 SessionEnd 的完整事件链

事件全景

事件	触发时机	匹配器作用域
`PreToolUse`	agent 调用工具前	工具名
`PostToolUse`	工具调用成功后	工具名
`PostToolUseFailure`	工具调用出错时	工具名
`BeforeReadFile`	读取文件前	文件路径
`AfterFileEdit`	文件写入后	文件路径
`BeforeShellExecution`	执行 shell 命令前	命令字符串
`AfterShellExecution`	shell 命令完成后	命令字符串
`SessionStart`	会话开始时	—
`SessionEnd`	会话结束时	—
`UserPromptSubmit`	用户提交提示词	—
`Stop`	agent 尝试停止	—
`SubagentStart`	子 agent 启动	—
`SubagentStop`	子 agent 结束	—

三种 Action 类型

command — 执行外部脚本，事件上下文通过 stdin JSON 传入：

{ "type": "command", "command": "${PLUGIN_ROOT}/scripts/lint.sh" }

prompt — 向 LLM 发送提示词，$ARGUMENTS 替换为事件上下文：

{ "type": "prompt", "prompt": "Review the change: $ARGUMENTS" }

agent — 类似 prompt 但带工具访问权限，可以做多步验证：

{ "type": "agent", "prompt": "Verify style guide compliance: $ARGUMENTS" }

执行模型

多个规则可以匹配同一个事件，全部执行
同一规则内的 hooks 按数组顺序串行执行
实现端应该设置超时
失败不能 crash 宿主工具

给你的工具加上 Open Plugins 支持

如果你自己做 AI 编程工具、想让插件生态兼容 Open Plugins，需要实现五条：

五大核心能力

不同工具的集成方式

每个工具现有的插件机制不同，npx plugins 在安装时做了一层翻译——把通用 .plugin/ 格式转成各工具自己的原生格式：

工具	安装目标	集成机制
Claude Code	`.claude/plugins/`	Skills 和配置直接兼容
Cursor	`.cursor/plugins/`	通过 Rules + MCP 机制注册
Codex	市场入口 `vercel@openai-curated`	通过内置 Vercel 集成
Grok Build	`grok plugin install`	原生插件命令 + Claude Code 兼容层
Kimi Code	Kimi 插件存储	`/plugins` TUI 重载后可见
GitHub Copilot CLI	`copilot plugin marketplace add`	注册源后 `plugin add plugin@marketplace`
VS Code	`chat.pluginLocations` 设置	需开启 `chat.plugins.enabled`（Preview）

安全防护模型

一些感受

Open Plugins 让我想起十年前 npm 刚流行的时候。JavaScript 的包管理也是一团乱麻：AMD、CommonJS、UMD、IIFE……每个项目有自己的一套。后来 npm + ES Modules 统一了标准，整个生态起飞了。AI 编程工具的插件生态，现在就处在那"前 npm"时代。

这次给 CloudBase MCP 做改造是个挺有意思的过程。从 npx plugins discover 识别出插件，到一行命令装到所有工具，那种"写一次到处用"的感觉，恰好就是这个标准想解决的问题。

图：npx plugins add TencentCloudBase/cloudbase-plugin——一行命令装到所有工具

如果你也在做 AI 编程工具的扩展，推荐看看 Open Plugins 规范。好消息是不用搞多复杂——项目里加个 .plugin/plugin.json，你的插件就能被 7 种工具识别。我们的改造也就四百来行代码，两天不到搞完。

CloudBase-MCP 对应的插件在这两个仓库，供参考：

npx plugins add TencentCloudBase/cloudbase-plugin
npx plugins add TencentCloudBase/cloudbase-sites-plugin

Open Plugins 还没到"成熟"那一步，但方向是对的。能让同一份插件在不同工具之间跑，这个问题本身值得被认真解决。剩下的就看社区怎么长出来了。

参考链接

Open Plugins 官网
plugins npm 包 — npx plugins add 的安装器
Agent Skills 规范
Model Context Protocol
CloudBase Plugin — Open Plugins 标准插件仓库
CloudBase Sites Plugin — Sites 插件仓库
CloudBase MCP — 腾讯云开发 MCP 插件
PR #808: CloudBase MCP 集成 Open Plugin 规范

现状：AI 编程工具的"插件战国"​

npx plugins：怎么装​

支持七种 AI 编程工具​

协议拆解​

标准目录结构​

plugin.json 清单文件​

组件发现算法​

${PLUGIN_ROOT} 路径展开​

实战：把 CloudBase MCP 改成 Open Plugins 插件​

改造前后对比​

plugin.json​

mcp.json​

自动化构建​

验收结果​

第一个坑：marketplace.json 冲突​

Hook 系统​

事件全景​

三种 Action 类型​

执行模型​

给你的工具加上 Open Plugins 支持​

五大核心能力​

不同工具的集成方式​

安全防护模型​

一些感受​

参考链接​