Hotdry.

Article

跨IDE AI工程插件架构：Compound Engineering的技能定义与MCP兼容层设计

解析Compound Engineering插件如何实现Claude Code、Codex、Cursor跨平台兼容，聚焦技能定义格式标准化、MCP工具注册机制与编辑器上下文同步的工程实践。

2026-05-31developer-tools

跨 IDE 的 AI 工程插件开发面临一个核心矛盾：如何在保持统一抽象的同时适配各平台的原生能力差异。Compound Engineering 插件提供了一个值得研究的实现样本 —— 它同时支持 Claude Code、Codex、Cursor 等主流 AI 编码工具，却采用了截然不同的底层适配策略。

统一抽象与平台适配的架构分层

Compound Engineering 的设计哲学是 "80% 规划审查，20% 执行编码"。这一理念通过一套标准化的技能工作流实现：从/ce-strategy制定产品策略，到/ce-brainstorm交互式需求梳理，再到/ce-plan生成实现方案，/ce-work执行任务，/ce-code-review多代理代码审查，最后通过/ce-compound沉淀知识。整个插件包含 37 个 skills 和 51 个 agents，却能在多个 IDE 中以不同形态运行。

这种跨平台能力的核心在于三层架构分离。技能定义层采用 Claude Code 原生格式，以 JSON 描述技能元数据、触发条件和参数契约；MCP 连接层负责与外部工具和服务建立通信，处理认证、传输和错误恢复；平台适配层则针对各 IDE 的插件规范进行格式转换和功能映射。MCP 在此扮演 "连接层" 角色，而 Skills 则是 "行为层"—— 前者解决 "如何调用工具"，后者解决 "何时调用以及调用后如何处理"。

技能定义格式的标准化实践

Compound Engineering 的技能定义遵循 Claude Code 插件规范，目录结构标准化为：

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # 插件元数据
├── commands/                # 斜杠命令
├── agents/                  # 专用代理
├── skills/                  # 技能定义
├── hooks/                   # 事件钩子
├── .mcp.json               # 外部工具配置
└── README.md

其中plugin.json是跨 IDE 识别的关键，它声明插件名称、版本、兼容的 IDE 版本范围以及入口点配置。Skills 目录下的每个技能文件定义了技能的触发模式、参数 Schema、上下文要求以及关联的 agents 列表。这种结构使得 Claude Code 能够直接识别加载，而其他 IDE 则通过转换层进行适配。

值得注意的是，技能定义中引入了上下文锚点机制。例如/ce-strategy生成的STRATEGY.md文件会被后续所有技能读取作为 grounding，确保策略选择能自然流入需求构思和规格定义阶段。这种基于文件系统的上下文传递方式，相比内存中的状态共享更具持久性和可观测性。

三大 IDE 的安装差异与兼容层

Compound Engineering 在 Claude Code、Codex、Cursor 三大平台的安装流程呈现出显著差异，这直接反映了各平台插件架构的不同成熟度。

Claude Code采用最简洁的两步安装：先通过/plugin marketplace add注册市场源，再执行/plugin install完成安装。这种方式依赖 Claude Code 成熟的插件系统，原生支持 skills、agents、hooks 和 MCP 服务器的完整能力集。

Cursor通过/add-plugin命令或插件市场搜索安装，流程与 Claude Code 类似但内部实现不同。Cursor 的 Agent chat 界面将 Compound Engineering 作为插件集成，命令触发后由 Cursor 的 Agent 调度系统处理。

Codex的安装最为复杂，需要三步配合：首先注册市场源，然后通过 Bun 安装 agent 集合，最后在 TUI 中完成插件安装。这种复杂性源于 Codex 原生插件规范目前不支持自定义 agents，仅支持 skills。因此 Compound Engineering 的 reviewer、researcher 等工作流 agents 必须通过独立的 Bun 安装步骤注入。官方文档明确指出："一旦 Codex 原生插件规范支持自定义 agents，Bun 安装步骤将被移除"。

这种差异揭示了一个关键工程决策：在目标平台能力不完整时，是等待还是通过额外适配层先行交付？Compound Engineering 选择了后者，通过 Bun/TypeScript 转换器为 Codex、OpenCode、Pi、Gemini CLI、Kiro CLI 等平台生成兼容格式，同时保持 Claude Code 原生格式的权威性。

MCP 工具注册与上下文同步机制

MCP（Model Context Protocol）在 Compound Engineering 中承担工具注册和跨服务通信的职责。.mcp.json配置文件声明了插件依赖的外部 MCP 服务器，包括代码搜索、文档生成、测试执行等工具。当技能执行需要调用外部能力时，MCP 层负责建立连接、序列化请求、处理流式响应和错误重试。

编辑器上下文同步是跨 IDE 插件的另一大挑战。Compound Engineering 采用文件系统优先的同步策略：策略文档、需求规格、代码审查记录都以 Markdown 形式持久化到docs/目录，而非依赖 IDE 特定的内存状态 API。这种设计使得同一项目在不同 IDE 间切换时，上下文能够通过 Git 仓库自然同步。

对于实时上下文（如当前编辑文件、光标位置、选区范围），Compound Engineering 通过各 IDE 提供的 API 抽象获取。Claude Code 提供终端集成和文件系统监听，Cursor 提供编辑器事件流，Codex 则通过其 Agent 系统暴露上下文快照。插件内部通过统一的上下文适配器屏蔽这些差异，向上层 skills 提供一致的上下文视图。

可落地的跨 IDE 插件开发参数清单

基于 Compound Engineering 的实现经验，跨 IDE AI 插件开发可遵循以下工程参数：

技能定义参数

  • 技能 Schema 采用 JSON Schema 2020-12 标准，确保类型安全
  • 命令命名统一使用/{plugin-prefix}-{action}格式，避免冲突
  • 上下文依赖显式声明在技能元数据中，便于 IDE 预加载

MCP 集成参数

  • 外部工具调用超时默认 30 秒，可配置范围为 5-300 秒
  • 流式响应采用 SSE 传输，单条消息大小限制 1MB
  • 工具错误分类为可重试 / 不可重试，后者立即中断工作流

平台适配参数

  • 优先实现 Claude Code 原生格式，其他平台通过转换层适配
  • 转换层使用确定性缓存目录，支持分支级隔离开发
  • 版本兼容性声明采用语义化版本范围，如>=0.2.0 <1.0.0

上下文同步参数

  • 持久化上下文优先使用 Git 跟踪的 Markdown 文件
  • 实时上下文获取采用轮询 + 事件监听混合策略，轮询间隔 500ms
  • 跨 IDE 状态不一致时以文件系统版本为准

跨 IDE 插件架构的本质是在标准化与灵活性之间寻找平衡点。Compound Engineering 通过清晰的分层设计 ——Claude Code 原生格式为源、MCP 为连接层、Bun 转换器为适配层 —— 实现了在 9 个不同平台上的功能交付。这种架构选择意味着短期维护成本的增加（需要维护多套转换逻辑），但换来了更广泛的生态覆盖和用户触达。对于正在设计类似系统的开发者而言，关键决策在于：你的核心平台是什么？哪些平台值得投入转换成本？以及，当目标平台能力演进时，如何优雅地退役适配代码？

资料来源

  • EveryInc/compound-engineering-plugin GitHub 仓库
  • Anthropic Claude Code 官方插件文档及 plugins 目录示例

developer-tools

内容声明：本文无广告投放、无付费植入。

如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。