Cursor 插件规范架构解析：扩展点机制与跨平台兼容层设计

背景：AI 原生 IDE 的扩展困境

传统 IDE 插件系统（如 VS Code Extension API）围绕编辑器生命周期设计，核心关注点是 UI 组件注册、语言服务接入和命令面板扩展。当 IDE 进化为 AI 原生形态 —— 以 Agent 为中心、以对话为交互界面 —— 插件架构需要回答一个根本问题：如何让外部能力注入到 AI 工作流中？

Cursor 的插件规范提供了一种务实的解决方案。它既保持与 VS Code 生态的兼容性，又引入了面向 AI 工作流的全新扩展点。本文基于 Cursor 官方插件仓库的规范定义，解析其架构设计的关键决策。

清单驱动架构：Marketplace 与 Plugin 的双层契约

Cursor 插件系统采用双层清单结构，实现市场聚合与插件自治的分离：

1. 市场层：marketplace.json

位于仓库根目录 .cursor-plugin/marketplace.json，作为插件市场的聚合清单：

{
  "name": "cursor-plugins",
  "owner": { "name": "Cursor", "email": "plugins@cursor.com" },
  "metadata": {
    "description": "Official Cursor plugin marketplace: developer tools..."
  },
  "plugins": [
    { "name": "continual-learning", "source": "continual-learning", "description": "..." },
    { "name": "thermos", "source": "thermos", "description": "..." }
  ]
}

该清单仅包含插件的入口信息（name、source 目录、description），实际的插件元数据由各个插件自行维护。这种设计允许插件独立版本演进，市场层仅负责索引和发现。

2. 插件层：plugin.json

每个插件目录下的 .cursor-plugin/plugin.json 定义完整的插件契约：

{
  "name": "continual-learning",
  "displayName": "Continual Learning",
  "version": "1.0.0",
  "description": "Incrementally learns durable user preferences...",
  "author": { "name": "Cursor", "email": "plugins@cursor.com" },
  "category": "developer-tools",
  "tags": ["automation", "memory", "transcripts"],
  "skills": "./skills/",
  "agents": "./agents/",
  "hooks": "./hooks/hooks.json"
}

关键字段说明：

扩展点机制：四类能力注入接口

Cursor 插件规范定义了四类扩展点，覆盖 AI 工作流的不同阶段：

Skills：斜杠命令接口

Skills 对应用户主动发起的交互，通常以 /skill-name 形式调用。每个 Skill 是一个自包含的工作流定义，包含：

• 输入模式：参数解析和验证规则
• 执行逻辑：单步或多步任务编排
• 输出格式：文本、HTML 或结构化数据

以 Compound Engineering 插件为例，其定义了 38+ Skills，覆盖从策略制定（/ce-strategy）到代码审查（/ce-code-review）的完整开发周期。

Rules：系统提示注入

Rules 以 .mdc 文件形式存在，在对话上下文构建阶段被注入到系统提示中。与 Skills 的显式调用不同，Rules 是隐式生效的上下文修饰，常用于：

• 编码风格约束（如 "使用 DHH Rails 风格"）
• 项目特定知识（如 "AGENTS.md 中的架构决策"）
• 安全策略（如 "禁止生成 eval 调用"）

Agents：子代理编排

Agents 是 Cursor 插件规范中最具特色的扩展点。每个 Agent 是一个可独立调用的子工作单元，支持：

• 并行执行：一个 Skill 可同时触发多个 Agents
• 角色 specialization：如 ce-security-reviewer 专精安全审计
• 置信度校准：Agent 输出附带置信度评分，用于后续决策

Compound Engineering 插件包含 50+ Agents，形成完整的审查、研究、设计工作流网络。

Hooks：生命周期事件

Hooks 允许插件响应 IDE 内部事件，如：

• transcript-change：对话历史变更时触发
• file-save：文件保存时触发
• agent-completion：Agent 执行完成时触发

Continual Learning 插件利用 Hooks 实现增量式记忆更新：当对话 transcript 变更时，自动提取高信号信息并更新 AGENTS.md。

跨平台兼容层：多 IDE 部署策略

Cursor 插件规范的一个核心设计目标是跨编辑器兼容。Compound Engineering 插件的安装文档展示了这一能力的工程实现：

原生支持平台

转换层支持平台

对于未原生支持 Cursor 插件规范的平台，通过 Bun/TypeScript 转换器实现兼容：

# Codex 需要两步：原生插件安装 + Bun agent 安装
codex plugin marketplace add EveryInc/compound-engineering-plugin
bunx @every-env/compound-plugin install compound-engineering --to codex

转换层的核心任务：

1. 清单格式转换：将 plugin.json 映射为目标平台的插件清单
2. Agent 模拟：在缺乏原生 Agent 支持的平台（如 Codex）上，通过 CLI 封装模拟子代理行为
3. Skill 路由：统一斜杠命令的调用协议

兼容层设计启示

这种分层策略揭示了 AI IDE 插件生态的现实：不同平台的 Agent 能力参差不齐，但 Skills 和 Rules 可以相对容易地跨平台移植。插件作者应遵循以下优先级：

1. 核心逻辑放在 Skills：确保最大平台覆盖
2. Agent 作为可选增强：为支持平台提供深度能力
3. 提供转换脚本：降低非原生平台的接入成本

工程实践：开发一个 Cursor 插件

基于官方 create-plugin 插件的模板，一个最小化 Cursor 插件的目录结构如下：

my-plugin/
├── .cursor-plugin/
│   └── plugin.json          # 插件清单
├── skills/
│   └── my-skill/
│       └── SKILL.md         # Skill 定义（含 frontmatter）
├── rules/
│   └── my-rule.mdc          # 规则文件
├── agents/
│   └── my-agent/
│       └── AGENT.md         # Agent 定义
├── README.md
├── CHANGELOG.md
└── LICENSE

SKILL.md 结构示例

---
name: my-skill
description: Do something useful
---

## Purpose
简要说明 Skill 的用途。

## Workflow
1. 步骤一：分析输入
2. 步骤二：执行操作
3. 步骤三：输出结果

## Output Format
- 成功：返回结构化数据
- 失败：返回错误原因和修复建议

局限与未来方向

当前 Cursor 插件规范存在以下工程约束：

1. Agent 支持不一致：Codex 等平台对自定义 Agent 的支持仍在演进，需要转换层兜底
2. Hook 覆盖有限：生命周期事件主要集中在对话层面，缺乏编辑器状态（如光标位置、选中范围）的细粒度 Hook
3. 调试工具有限：跨平台开发时，缺乏统一的插件调试和日志追踪机制

尽管如此，Cursor 插件规范为 AI 原生 IDE 的扩展机制提供了一个务实的参考实现。其清单驱动架构、分层扩展点设计和跨平台兼容策略，值得同类工具借鉴。

资料来源

• cursor/plugins 官方仓库 — Cursor 插件规范定义与官方插件集
• EveryInc/compound-engineering-plugin — 跨平台 AI 工程插件示例，展示复杂 Agent 编排与多 IDE 部署策略

web