Agent Plugins：可移植插件标准全解析

摘要 — Agent Plugins（agent-plugins.org）是一个厂商中立的开放标准，为 AI agent 插件定义了统一的可移植包格式。你不再需要为 Cursor、VS Code、ChatGPT、Kiro 等每个客户端分别打包——只需一个 plugin.json 清单、一个 skills/ 目录和可选的 mcp.json，兼容客户端即可自动识别和运行。1.0.0 Working Draft 由 Amazon、Cursor、Microsoft、OpenAI 和 Vercel 组成的技术指导委员会（TSC）治理。

同一个插件，我打包了五次

Agent Plugins 官网首页 agent-plugins.org — Amazon、Cursor、Microsoft、OpenAI、Vercel 联合发起的开放标准。

上个季度，我开发了一个代码审查插件：分析 diff、标记安全问题、内联建议修复方案。功能本身并不复杂——但发布过程让人崩溃。

先给 Cursor 打包。自定义清单格式、Cursor 专属的生命周期钩子、特定的目录结构。花了一周。接着同事需要在 VS Code 里用，不同的 manifest schema、不同的激活事件、不同的 API 接口。又花了四天。后来团队开始用 Kiro 做基础设施开发，又移植了一次。当产品经理说想在 ChatGPT 桌面端也能用时，我几乎想放弃了。

核心逻辑完全一样。底层 MCP server 完全一样。但我需要维护五种完全不同的打包格式、五份文档、五条 CI 流水线。插件本身大约 400 行有意义的代码，而围绕打包和客户端适配的胶水代码？三倍于此。

我相信 AI 工具生态里的每个插件开发者都经历过类似的痛苦：写一次有用的东西，然后花大量时间让它适配各个各自为政的平台。

这就是 Agent Plugins 要解决的问题——一次打包，所有客户端通用。

什么是 Agent Plugins？

Agent Plugins 是一个开放标准——截至 2026 年 8 月已发布 1.0.0 Working Draft——为 AI agent 插件定义了可移植的包格式。规范托管在 agent-plugins.org，源码在 GitHub 上，采用 CC BY 4.0 协议。

治理机构是技术指导委员会（TSC），初始成员来自 Amazon、Cursor、Microsoft、OpenAI 和 Vercel。关键词是厂商中立：没有任何单一公司控制这个标准。

核心设计哲学分为两个原则：

共享部分追求可移植性 — 包格式、manifest schema、skill 定义、MCP server 声明都是标准化的，插件作者只需编写一次。
客户端保留自治权 — 每个客户端自行控制分发机制、安装流程、UX 呈现、权限模型和沙箱策略。标准不会规定 Cursor 如何渲染 skill，也不会规定 ChatGPT 如何管理权限。

这种拆分使得标准的落地具有现实可行性。客户端不需要放弃对用户体验的控制——只需就插件包的格式达成一致，让作者不必反复重建同一个东西。

Agent Plugins 兼容客户端列表 兼容 Agent Plugins v1 格式的客户端 — VS Code、Cursor、GitHub Copilot、ChatGPT/Codex、Kiro 等。

包结构

一个 Agent Plugins 包是一个目录（或归档文件），结构如下：

my-plugin/
├── plugin.json          # 必需：清单文件
├── skills/
│   ├── review-diff/
│   │   └── SKILL.md    # Agent Skill 定义
│   └── suggest-fix/
│       └── SKILL.md
├── mcp.json             # 可选：MCP server 声明
└── com.cursor.ide/      # 可选：客户端扩展（反向域名命名空间）
    └── extension.json

plugin.json — 清单文件

plugin.json 是唯一严格要求的文件。它声明插件的身份、版本、组件和元数据：

{
  "name": "security-review",
  "version": "1.2.0",
  "description": "Automated security review for code diffs",
  "author": "Daniel Russo",
  "license": "MIT",
  "skills": ["skills/review-diff", "skills/suggest-fix"],
  "mcp": "mcp.json"
}

skills/ — Agent Skills

Skills 是自然语言驱动的组件类型。每个 skill 位于独立的子目录中，由一个 SKILL.md 文件定义——这是一份 Markdown 文档，告诉 agent 何时使用该技能、需要什么输入、以及如何执行。

这是刻意的低技术门槛设计。SKILL.md 文件对人类和机器都可读。Agent 解析它来理解意图和调用模式；开发者阅读它来了解功能。不需要编译步骤，没有二进制格式。

mcp.json — MCP Server 声明

如果插件通过 Model Context Protocol 暴露工具，需要在 mcp.json 中声明。规范支持三种传输类型：

stdio — MCP server 作为子进程运行，通过 stdin/stdout 通信。
Streamable HTTP — server 暴露支持流式的 HTTP 端点。
Legacy SSE — Server-Sent Events 传输方式，用于向后兼容。

{
  "servers": {
    "security-scanner": {
      "transport": "stdio",
      "command": "node",
      "args": ["./servers/scanner.js"],
      "env": {
        "API_KEY": "${SECURITY_API_KEY}"
      }
    }
  }
}

注意 ${SECURITY_API_KEY} 占位符。规范支持环境变量占位符展开，因此密钥永远不会被硬编码到包中。

客户端扩展（反向域名命名空间）

需要超出可移植规范覆盖范围的额外配置的客户端，可以使用反向域名命名法定义自己的命名空间（如 com.cursor.ide/、com.microsoft.vscode/）。客户端专属的 UX 钩子、快捷键绑定或激活规则就放在这里。

关键约束：这些是附加性的。插件在没有任何客户端扩展目录的情况下必须能正常工作。客户端扩展增强特定客户端中的体验，但不是插件运行的必要条件。

安全隔离

规范强制执行一条关键安全规则：插件相对路径必须保持在插件根目录内。插件不能引用 ../../etc/passwd 或逃逸出自身目录边界。客户端应在安装时和运行时强制执行此规则。

路径隔离加上客户端自行控制的权限和沙箱机制，意味着标准不会引入新的攻击面——它继承客户端已有的安全模型。

兼容客户端

截至 1.0.0 Working Draft，以下客户端已承诺兼容 Agent Plugins：

客户端	类型
VS Code	IDE
Cursor	IDE
GitHub Copilot	IDE 扩展 / 独立应用
ChatGPT / Codex	云端 agent
Kiro	IDE
Hermes Agent	自主 agent
OpenClaw	CLI agent

这不是一个等待采纳的理论规范。AI 编程和 agent 领域的主要参与者要么在 TSC 中，要么已承诺客户端支持。

Agent Plugins vs. MCP vs. 自定义插件格式

常见问题：这和 MCP 是什么关系？MCP 不是已经解决了互操作性问题吗？

MCP 和 Agent Plugins 在不同层面运作，是互补而非竞争关系：

维度	Agent Plugins	MCP	自定义插件格式
定义了什么	包格式 + manifest	工具调用的通信协议	因客户端而异
范围	打包、分发、发现	客户端与工具 server 间的运行时通信	端到端但私有
可移植性	一个包适用于所有兼容客户端	一个 server 适用于任何 MCP 客户端	锁定在单一客户端
Skill 支持	是——基于 SKILL.md	否——MCP 仅限工具	因客户端而异
MCP 集成	将 MCP servers 作为组件包含	不适用——本身就是协议	部分客户端原生支持 MCP
客户端专属 UX	通过反向域名扩展支持	未涉及	内建
治理	多厂商 TSC（Amazon、Cursor、Microsoft、OpenAI、Vercel）	Anthropic 主导	单一厂商
安全模型	路径隔离 + 客户端执行权限	传输层 + 客户端执行	因客户端而异

简单来说：MCP 定义 agent 如何与工具 server 通信。Agent Plugins 定义你如何打包和发布所有东西——skills、MCP servers、元数据和客户端扩展——让任何客户端都能安装。

如果你已经构建了 MCP server，采用 Agent Plugins 意味着用一个 plugin.json 清单把它包裹起来，并可选地添加 skills。你的 MCP server 代码不需要修改。

实际工作流程

让我们走一遍用户在兼容客户端中安装 Agent Plugins 包时发生的事情：

发现 — 用户通过客户端的市场、注册中心或直接链接找到插件。分发由客户端控制。
安装 — 客户端下载包，验证 plugin.json，检查路径隔离，将插件放入其插件目录。
权限授予 — 客户端向用户展示插件声明的能力并请求授权。此步骤完全由客户端定义。
Skill 注册 — 客户端读取每个 SKILL.md 文件并在其 agent 上下文中注册 skills。当 agent 遇到匹配 skill 触发条件的任务时，可以调用该 skill。
MCP server 启动 — 如果存在 mcp.json，客户端使用指定的传输方式启动声明的 MCP servers（或连接远程端点）。
运行时 — Agent 在工作流中使用 skills 和 MCP 工具。环境变量在启动时从用户环境中展开。

插件作者不需要知道第 1、2、3 步在任何特定客户端中如何工作。只需产出一个符合标准的包即可。

对生态系统的意义

2026 年的 AI agent 生态系统面临的碎片化，类似于 WebExtensions 出现之前的浏览器扩展，或跨平台框架成熟之前的移动应用开发。每个客户端有自己的格式、自己的分发方式、自己的开发者文档。

这种碎片化带来了真实的成本：

对插件作者：N 倍的打包工作、N 倍的维护负担、N 条 CI/CD 流水线。许多有用的插件永远不会被移植到第一个客户端之外。
对用户：最好的插件只在一个平台上可用。切换客户端意味着失去你的工具集。
对客户端开发者：从零构建插件生态系统代价高昂。共享标准意味着第一天就有更多可用插件。

Agent Plugins 通过标准化应该共享的部分来解决这三个问题，同时在重要的地方保留客户端的自由度。

构建你的第一个 Agent Plugin

以下是一个最小但完整的插件，提供生成 commit message 的技能：

commit-message-plugin/
├── plugin.json
└── skills/
    └── generate-commit-msg/
        └── SKILL.md

plugin.json：

{
  "name": "commit-message-generator",
  "version": "0.1.0",
  "description": "Generates conventional commit messages from staged diffs",
  "author": "Your Name",
  "license": "MIT",
  "skills": ["skills/generate-commit-msg"]
}

skills/generate-commit-msg/SKILL.md：

# Generate Commit Message

## When to use
The user has staged changes and wants a commit message, or explicitly asks
for help writing a commit message.

## Inputs
- The current git diff (staged changes)
- Optional: project's commit convention (conventional commits, etc.)

## Steps
1. Read the staged diff using `git diff --cached`
2. Analyze the changes: what files changed, what was added/removed/modified
3. Determine the commit type (feat, fix, refactor, docs, chore, etc.)
4. Write a concise subject line (≤72 chars) following the project's convention
5. If the change is complex, add a body explaining the "why"

## Output
A ready-to-use commit message in the project's preferred format.

这就是一个完整的、可安装的 Agent Plugin。无需构建步骤，无需客户端专属代码。任何兼容客户端都可以安装它并将该 skill 提供给其 agent。

添加 MCP 工具

如果想在 skills 之外添加程序化工具，加入 mcp.json：

{
  "servers": {
    "git-tools": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

现在你的插件同时提供高层次的 agent skills（SKILL.md 指令）和底层的程序化工具（MCP server）。Agent 可以根据任务需要选择使用哪个。

Agent Plugins GitHub 规范仓库 agent-plugins-spec 仓库 — 开放开发，包含提案、JSON Schema 和治理文档。

常见问题

Agent Plugins 会取代 MCP 吗？

不会。Agent Plugins 包含 MCP 作为组件类型。MCP 定义运行时协议；Agent Plugins 定义打包格式。两者协同工作。如果你已经投入了 MCP servers 的开发，Agent Plugins 让它们更易分发——而非过时。

我需要重写现有的 VS Code 扩展吗？

不需要。Agent Plugins 是附加性的。你可以创建一个 Agent Plugins 包来封装现有逻辑，并添加 com.microsoft.vscode/ 客户端扩展目录用于 VS Code 专属的钩子。现有的扩展代码可以与可移植包共存。

插件如何分发？

分发被刻意留给客户端决定。有些客户端可能运营集中式市场。其他客户端可能支持从 GitHub URL 或 npm 包直接安装。标准规范化的是格式，而非交付机制。

安全性如何？恶意插件能逃逸沙箱吗？

规范要求路径隔离——所有插件相对路径必须解析在插件根目录内。除此之外，客户端执行其自有的安全模型。插件无法做客户端权限系统不允许的任何事情。标准不会削弱现有的安全边界。

可以只针对一个客户端吗？

可以。你可以创建一个最小的 plugin.json 加上仅一个客户端扩展目录。但标准的价值来自可移植性——你的插件越可移植，受众就越大。

这只适用于编程 agent 吗？

不是。规范是领域无关的。虽然初始 TSC 成员主要来自编程工具领域，但该格式适用于任何 AI agent 客户端：研究 agent、数据分析 agent、创意工具等。

在哪里可以贡献？

规范在 GitHub 上开源，采用 CC BY 4.0 协议。欢迎提交 Issues 和 Pull Requests。TSC 公开运作。

未来展望

1.0.0 Working Draft 只是起点。可能演进的方向包括：

注册中心标准 — 通用的注册协议，让客户端无需各自构建私有基础设施即可发现插件。
版本管理和更新 — 标准化的更新通知和兼容性范围。
能力声明 — 更丰富的权限清单，让客户端做出知情的信任决策。
测试与认证 — 插件包的自动化合规测试。

这里的演进轨迹与其他成功标准类似：从最小可行规范开始，获得主要参与者的采纳，然后根据实际反馈迭代。

开始使用

如果你今天正在构建 agent 工具或扩展，以下是可执行的路径：

阅读规范——简洁且结构清晰。
用一个 plugin.json 清单封装你现有的工具。
将你的文档转换为 SKILL.md 文件，对应你已有的技能。
如果你有 MCP server，添加 mcp.json 声明。
至少在两个兼容客户端中测试以验证可移植性。

AI agent 框架的生态正在快速成熟。Agent Plugins 和 MCP 这样的标准是防止碎片化拖垮整个领域的连接组织。一次打包，所有客户端——这是目标，有 TSC 阵容的支撑，它看起来可以实现。

Agent Plugins 规范可在 agent-plugins.org 和 github.com/agentplugins/agent-plugins-spec 获取。采用 CC BY 4.0 协议。