Agent Plugins 规范

规范版本：1.0.0

状态：工作草案

本文档定义规范的 Agent Plugins 规范 v1.0.0，用于把扩展 AI 智能体的可复用组件封装成可分发的插件。

目录

1. 状态与版本
2. 合规性用语
3. 术语
4. 插件包模型
5. 清单
6. 组件发现
7. 组件类型
8. 客户端扩展
9. 环境变量和占位符展开
10. 版本控制
11. 客户端合规性

非规范性材料

• 附录 A：合规性检查清单
• 设计决策

1. 状态与版本

本规范定义 Agent Plugins 格式的 1.0.0 版。

声称符合 Agent Plugins v1 的客户端和插件包 MUST 实现或遵循本文档中的要求。

1.1 治理模型

Agent Plugins 项目的治理方式独立于可移植包格式，并在技术章程中定义。

2. 合规性用语

在本文档的规范性章节中，关键词 MUST、MUST NOT、REQUIRED、SHOULD、SHOULD NOT、RECOMMENDED、MAY 和 OPTIONAL 仅在全部使用大写字母时，才按照 RFC 2119 和 RFC 8174 的说明解释。

附录 A 和“设计决策”不具规范性。其他所有章节均具规范性。

3. 术语

4. 插件包模型

4.1 一般要求

1. 插件是以单一文件系统位置为根的目录。
2. 插件 MUST 在插件根目录中包含位于 plugin.json 的清单。
3. 客户端发现、读取或执行插件包提供的文件或目录时，经过文件系统解析的路径 MUST 留在经过文件系统解析的插件根目录内。符号链接、目录联接、重解析点和同等文件系统机制 MAY 解析到插件根目录内的目标，但客户端 MUST 拒绝解析到该目录之外的包路径。
4. 本规范定义为插件相对路径的配置字段 MUST 以 ./ 开头，相对于插件根目录解析，并且在解析后留在经过文件系统解析的插件根目录内。
5. 未定义为路径的配置值（包括命令参数和环境变量值）是不透明字符串。为执行本节要求，客户端 MUST NOT 将这些值解释为包路径。

示例：有效和无效的相对路径

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "server": {
      "type": "stdio",
      "command": "./bin/server",
      "cwd": "./data"
    }
  }
}

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "server": {
      "type": "stdio",
      "command": "../bin/server",
      "cwd": "data"
    }
  }
}

第一个示例有效：两个路径都以 ./ 开头，并留在插件根目录内。第二个示例无效：../bin/server 逃逸插件根目录，而 data 不是插件相对路径。

这些包含规则管理对插件包所提供文件的访问。它们不会对插件子进程实施沙箱，也不限制运行时提供的路径。§7.2.1 另行定义了以客户端管理的 PLUGIN_DATA 目录为根的配置工作目录的包含规则。

路径不符合包含要求时，客户端 MUST 应用最窄的适用失败边界：

1. 如果 plugin.json 未解析到插件根目录内，客户端 MUST 拒绝插件。
2. 如果组件的固定位置未解析到插件根目录内，客户端 MUST 根据 §6.2 将该组件类型视为无效。
3. 如果已发现的 SKILL.md 未解析到插件根目录内，客户端 MUST 根据 §7.1 跳过该技能。
4. 如果 MCP 服务器的 command 或 cwd 不符合包含要求，客户端 MUST 根据 §7.2.2 将该服务器条目视为无效。
5. 任何其他包路径解析到插件根目录之外时，客户端 MUST 拒绝访问该路径。

4.2 标准布局

包含技能、MCP 服务器和客户端扩展的插件可以采用以下布局：

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       ├── SKILL.md
│       ├── scripts/
│       │   └── analyze.sh
│       └── references/
│           └── checklist.md
├── mcp.json
├── com.example.client/
│   └── hooks/
├── LICENSE
└── CHANGELOG.md

另请参阅： §5 清单中的清单规则、§6 组件发现中的固定组件位置和位置缺失时的行为，以及§8 客户端扩展中的客户端扩展约定。

5. 清单

5.1 位置与加载

客户端 MUST 检查插件根目录中位于 plugin.json 的清单。

Agent Plugins 核心规范为每个插件只定义一个可移植清单。其他文件不能替代、补充或覆盖根目录 plugin.json 中的核心字段。

客户端先加载并验证根目录 plugin.json，然后才能发现组件或应用客户端专属行为。

另请参阅： §11 客户端合规性中有关支持 plugin.json 的要求。

5.2 清单对象

清单 MUST 是 JSON，且 MUST 包含顶层对象。其 Schema 是封闭的：允许的顶层字段仅有 $schema、name、version、description、author、homepage、repository、license、keywords 和 extensions。

如果 plugin.json 包含任何其他顶层字段，它就不符合 Schema。客户端 MUST 报告并忽略每个未知字段；如果清单在其他方面符合本节要求，客户端 MUST 继续加载插件。客户端 MUST NOT 为未知字段赋予语义。客户端专属清单数据应按照 §8 的定义放在 extensions 下。

不是对象的 extensions 字段按 §8.1 处理。除此之外，每个允许字段都 MUST 符合下文定义的类型和限制。除未知顶层字段或不是对象的 extensions 字段外，任何 Schema 违规都是致命错误：客户端 MUST 拒绝插件，并且 MUST NOT 发现或执行其中的任何组件。

正式的机器可读 Schema 是 schemas/1.0.0/plugin.schema.json。如果它与规范文本冲突，以规范文本为准。

必需的 $schema 字段标识插件所面向的 Agent Plugins 规范版本及其对应的清单 Schema。对于 Agent Plugins 1.0.0，其值 MUST 是规范标识符 https://agent-plugins.org/schemas/1.0.0/plugin.schema.json。

客户端 MUST 使用识别的 $schema 值来选择本地支持的清单验证和解释规则。只有当客户端明确认定多个 Agent Plugins 版本相互兼容时，才 MAY 将多个规范标识符映射到同一实现。客户端在加载插件时 MUST NOT 获取 Schema。如果客户端不支持声明的 Agent Plugins 版本或明确认定兼容的版本，它 MUST 拒绝插件，并且 SHOULD 报告不支持的版本。

示例：最小清单

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "minimal-plugin"
}

示例：完整清单

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/example/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "extensions": {
    "com.example.client": {
      "setting": true
    }
  }
}

5.3 必填字段

如果必填字段缺失、类型错误、为空或以其他方式违反其要求，清单无效。客户端 MUST 拒绝插件，并且 MUST NOT 发现或执行其中的任何组件。客户端 SHOULD 报告哪个必填字段无效。

5.4 元数据字段

author 对象 MAY 只包含 name、email 和 url 字段，且每个字段的值均为字符串。任何其他字段或值类型都会使清单无效。

除非本规范明确规定限制，否则仅按 JSON 类型验证元数据字段。客户端 MUST NOT 仅因以下情况拒绝清单：version 不是有效的语义化版本；homepage、repository 或 author.url 不是可识别的 URL；author.email 不是可识别的电子邮件地址；或者 license 不是 SPDX 标识符。

5.5 插件名称限制

清单的 name 值 MUST 满足以下所有条件：

插件名称中允许使用句点。

有效名称：my-plugin、acme.tools、lint3r、a

无效名称：My-Plugin（大写字母）、-start（前导连字符）、has--double（连续连字符）、too.many..dots（连续句点）、``（空）

5.6 Extensions 字段

可选的 extensions 字段包含以扩展命名空间为键的客户端专属清单数据。处理规则见 §8。

6. 组件发现

另请参阅： §4 插件包模型中的目录布局约定。

6.1 固定位置

客户端 MUST 从固定位置发现客户端支持的每种组件类型。plugin.json 不能覆盖这些位置，也不能包含内联组件配置。

组件位置：

示例：插件 reports-plugin 采用以下布局：

reports-plugin/
├── plugin.json
├── skills/summarize/SKILL.md
└── mcp.json

客户端从 skills/ 发现技能 summarize，并从 mcp.json 发现 MCP 服务器。

6.2 位置缺失

如果组件的固定位置不存在，客户端 MUST NOT 将其视为错误。

如果组件的固定位置存在，但未解析为预期的文件系统类型（例如 skills 未解析为目录，或 mcp.json 未解析为普通文件），客户端 MUST 将该组件类型视为无效，并继续加载其他支持的组件类型。

7. 组件类型

另请参阅： §6 组件发现中有关查找组件文件的说明。

Agent Plugins v1 只定义两种组件类型：技能和 MCP 服务器。其他组件类型不属于 v1 格式，也不影响合规性。

客户端 MUST 忽略不支持的组件类型。

7.1 技能

Agent Skills MUST 符合 Agent Skills 规范。该规范是 SKILL.md 格式、frontmatter 字段和目录布局（scripts/、references/、assets/）的权威依据。

本规范定义如何在插件中发现 Agent Skills，而不定义技能格式本身，也不定义客户端如何向用户或模型提供技能。

固定发现位置是 skills/。如果直接子目录中名称恰为 SKILL.md 的路径解析为普通文件，则该子目录被视为一项技能。客户端 MUST NOT 递归搜索更深层的后代目录来寻找其他技能。

如果已发现的技能不符合 Agent Skills 规范，客户端 MUST 跳过该技能并继续加载其他技能和组件类型。客户端 SHOULD 报告无效技能。

示例：skills/ 内名为 deploy 的技能目录：

skills/
└── deploy/
    ├── SKILL.md          # name: deploy
    ├── scripts/
    │   └── rollback.sh
    └── references/
        └── runbook.md

7.2 MCP 服务器

Model Context Protocol 规范定义 MCP 线路行为和生命周期语义。Agent Plugins 定义 mcp.json 配置格式，用于在插件中定位和连接 MCP 服务器。客户端将此可移植格式映射到自身配置；其字段名和值不必与客户端原生格式一致。

7.2.1 发现与配置

MCP 配置路径是插件根目录中的 mcp.json。MCP 配置 MUST NOT 在 plugin.json 中内联声明，也不得从其他核心路径加载。

mcp.json MUST 是 JSON 对象，其中包含必需的 $schema 和 mcpServers 字段，且没有其他顶层字段。mcpServers MUST 是对象，其成员名称标识服务器，成员值是服务器配置对象。空的 mcpServers 对象有效。

正式的机器可读 Schema 是 schemas/1.0.0/mcp.schema.json。如果它与规范文本冲突，以规范文本为准。Schema 提供 #/$defs/server，使客户端可以分别验证每个服务器，并保留 §7.2.2 中的失败边界。

必需的 $schema 字段标识 MCP 配置所面向的 Agent Plugins 规范版本及其对应的 MCP Schema。对于 Agent Plugins 1.0.0，其值 MUST 是规范标识符 https://agent-plugins.org/schemas/1.0.0/mcp.schema.json。

客户端 MUST 使用识别的 $schema 值来选择本地支持的 MCP 配置验证和解释规则。只有当客户端明确认定多个 Agent Plugins 版本相互兼容时，才 MAY 将多个规范标识符映射到同一实现。客户端在加载插件时 MUST NOT 获取 Schema。

每项服务器配置 MUST 包含 type 字段，并且只匹配下列一个封闭变体。未知字段、未知 type 值或属于其他变体的字段都会使该服务器条目无效。

stdio

command 字段 MUST 包含单个可执行文件标记，而不是 shell 命令字符串。它 MUST 是纯可执行文件名，或以 ./ 开头的插件相对路径。客户端 MUST 使用平台的可执行文件搜索规则解析纯名称，并且 MUST 相对于插件根目录解析插件相对路径。客户端 MUST NOT 在 command 中展开占位符。

配置的 PATH 环境值是否参与解析纯 command 由客户端定义。声称合规的插件 MUST NOT 依赖该行为。在包中捆绑可执行文件的插件 MUST 使用插件相对 command。

客户端 MAY 在启动解析后的可执行文件需要时使用平台专属命令解释器，例如 Windows 上的 .bat 或 .cmd 脚本，但 MUST 将 command 保持为单个标记，并单独传递 args。

省略 cwd 时，客户端 MUST 使用插件根目录作为子进程工作目录。提供 cwd 时，它 MUST 采用以下形式之一：

1. 以 ./ 开头的插件相对路径。
2. 恰好是 ${PLUGIN_ROOT}，或以 ${PLUGIN_ROOT}/ 开头的路径。
3. 恰好是 ${PLUGIN_DATA}，或以 ${PLUGIN_DATA}/ 开头的路径。

客户端 MUST 先展开占位符，再解析 cwd。插件相对值或以 ${PLUGIN_ROOT} 为根的值 MUST 留在经过文件系统解析的插件根目录内。以 ${PLUGIN_DATA} 为根的值 MUST 留在经过文件系统解析的插件数据目录内。任何其他形式或解析后的逃逸都会使该服务器条目根据 §7.2.2 无效。

stdio 服务器配置中的 args、env 和 cwd 字段 MUST 支持 ${PLUGIN_ROOT} 和 ${PLUGIN_DATA} 展开。

Streamable HTTP 和旧版 HTTP+SSE

streamable-http 选择当前的 MCP Streamable HTTP 传输。sse 选择 MCP 2024-11-05 规范定义的已弃用 HTTP+SSE 传输；它不指 Streamable HTTP 内使用的 SSE 响应或流。

url 值 MUST 是绝对 HTTP 或 HTTPS URL，且 MUST NOT 包含用户信息或片段。非环回端点 MUST 使用 HTTPS。当 URL 主机恰好为 localhost 或环回范围内的 IP 字面量时 MAY 使用 HTTP。

标头名称和值 MUST 是有效的 HTTP 标头字段。标头名称不区分大小写；如果条目以不同大小写多次包含同一标头名称，则该条目无效。客户端 MUST NOT 在 url、标头名称或标头值中展开占位符或环境变量。

标头值是包中可见的数据，不是可移植的密钥机制。插件 MUST NOT 在 headers 中嵌入凭据或其他密钥。客户端为实现 HTTP、MCP 或授权而生成的标头优先于名称不区分大小写且相同的配置标头。未经用户明确授权，客户端 MUST NOT 通过重定向或旧版 SSE 端点事件将配置的标头转发到其他来源。

Agent Plugins v1 不定义 OAuth 配置或可移植凭据引用字段。授权发现、用户交互和凭据存储由客户端管理。授权失败是该服务器的连接失败，不代表插件配置无效。

传输支持

支持 Agent Plugins MCP 服务器的客户端 MUST 至少支持 stdio 和 streamable-http 中的一种，并且 SHOULD 支持两者。对 sse 的支持是 OPTIONAL。客户端 MUST 在首次尝试连接时使用 type 声明的传输方式。如果该尝试失败，Agent Plugins 不定义回退行为。

示例：mcp.json

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "local-validator": {
      "type": "stdio",
      "command": "./bin/validator",
      "args": ["--data", "${PLUGIN_DATA}/validator"],
      "env": {
        "CONFIG": "${PLUGIN_ROOT}/config.json"
      },
      "cwd": "${PLUGIN_ROOT}"
    },
    "deployment-api": {
      "type": "streamable-http",
      "url": "https://deploy.example.com/mcp",
      "headers": {
        "X-Tenant": "public-tenant"
      }
    },
    "legacy-events": {
      "type": "sse",
      "url": "https://legacy.example.com/sse"
    }
  }
}

7.2.2 加载规则

1. 支持 MCP 服务器的客户端 MUST 仅从插件根目录的 mcp.json 加载配置。
2. 如果 mcp.json 不是有效 JSON，面向的 Agent Plugins 版本不受客户端支持或未被明确认定兼容，与 plugin.json 面向的 Agent Plugins 版本不同，或不符合 §7.2.1 的其他顶层要求，则客户端 MUST 为该插件禁用 MCP，并继续加载其他组件类型。客户端 SHOULD 报告无效、不受支持或版本不匹配的配置。
3. 如果单个服务器条目不符合 §7.2.1 的要求，客户端 MUST 跳过该服务器，并继续加载其他服务器和组件类型。客户端 SHOULD 报告无效条目。
4. 如果客户端不支持其他方面有效的服务器条目所声明的传输方式，它 MUST 跳过该服务器，并继续加载其他服务器和组件类型。客户端 SHOULD 报告不支持的传输方式。
5. 如果服务器无法启动、连接、通过身份验证或完成 MCP 握手，客户端 MUST 继续加载其他服务器和组件类型。客户端 SHOULD 报告连接失败。

8. 客户端扩展

客户端专属清单数据 MUST 在 extensions 下用反向域名命名空间表示。客户端专属文件 MUST 放在以该命名空间命名的顶层目录中。客户端 MAY 使用其中一种表示，也可以同时使用两者。

客户端 SHOULD 根据其控制的域名设置命名空间，并且 SHOULD 保持命名空间稳定。例如，控制 example.com 的客户端可以使用 com.example.client。

Agent Plugins 不为客户端扩展数据或文件指定任何可移植的发现、验证、加载或失败语义。每个客户端定义自己命名空间的内容和行为，包括其清单数据与目录内容之间的关系。

8.1 清单扩展数据

plugin.json 中可选的 extensions 字段 MUST 是对象，其成员名称是客户端扩展命名空间，成员值是对象。

示例：

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "example-plugin",
  "extensions": {
    "com.example.client": {
      "setting": true
    }
  }
}

如果 extensions 不是对象，客户端 MUST 报告并忽略该字段，然后继续加载组件。客户端 MUST 忽略未实现命名空间的清单条目，且不得验证其值的内容。已实现命名空间内的验证和失败处理由该客户端定义。

8.2 扩展目录

命名空间的扩展目录是以该命名空间命名的顶层目录。例如，com.example.client 的文件属于 com.example.client/。

示例：仅包含文件的客户端扩展

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       └── SKILL.md
└── com.example.client/
    └── hooks/
        └── hooks.json

为命名空间实现基于文件行为的客户端 MUST 在对应的顶层目录中查找这些文件。

9. 环境变量和占位符展开

另请参阅： §7.2 MCP 服务器中适用插件变量展开的字段，以及§4.1 一般要求中的路径安全规则。

9.1 子进程环境

启动插件子进程（即 stdio MCP 服务器）的客户端 MUST 在每个子进程环境中提供 PLUGIN_ROOT 和 PLUGIN_DATA。PLUGIN_ROOT 是经过文件系统解析的插件根目录绝对路径。PLUGIN_DATA 是客户端管理的持久数据目录绝对路径，专供该已安装插件实例使用。

客户端选择 PLUGIN_DATA 的位置。它 MUST 在启动插件子进程前创建该目录，MUST 使子进程可以写入该目录，并且 MUST 在插件更新时保留其内容。卸载插件时，客户端 MAY 删除该目录。

以下内容使用 PLUGIN_DATA：已安装的依赖项（node_modules、虚拟环境）、生成的代码、缓存，以及更新后需要保留的其他插件状态。PLUGIN_ROOT 用于引用随插件提供的捆绑脚本、二进制文件和配置文件。

客户端选择子进程基础环境，并 MAY 继承、省略或清理环境中的变量。占位符展开后，stdio 服务器 env 对象中的条目 MUST 叠加到基础环境上，并按平台的环境变量名称语义替换同名条目。然后，客户端 MUST 将 PLUGIN_ROOT 和 PLUGIN_DATA 设置为上述值，并按平台的环境变量名称语义替换等效名称的任何条目。

除解析纯 command 所用的平台可执行文件搜索外，声称合规的插件 MUST NOT 依赖基础环境变量，除非本规范要求该变量或服务器配置明确提供该变量。

示例：客户端从 /home/alex/.agents/plugins/devtools 加载插件 devtools 时设置：

PLUGIN_ROOT=/home/alex/.agents/plugins/devtools
PLUGIN_DATA=/home/alex/.agents/plugins/data/devtools

9.2 占位符展开

启动插件子进程的客户端 MUST 在支持的配置字段中展开 ${PLUGIN_ROOT} 和 ${PLUGIN_DATA}。展开是单次、非递归的文本替换，替换两个占位符的每个完全匹配项。替换所引入的文本 MUST NOT 再次扫描占位符。

展开适用于 args 的每个字符串元素、env 中的每个字符串值和 cwd 字符串。它不适用于 env 键、command 或固定组件位置。

无法识别的占位符状文本 MUST 保留为字面量。客户端 MUST NOT 执行任何其他占位符或环境变量展开。

配置的 env 值是包中可见的数据，不是可移植的密钥机制。插件 MUST NOT 在 env 中嵌入凭据或其他密钥。

MCP 服务器的 env 对象 MUST NOT 包含名为 PLUGIN_ROOT 或 PLUGIN_DATA 的条目。此类条目会使服务器配置根据 §7.2.2 无效。客户端 MUST 自行提供保留环境变量。

示例：在 MCP 中展开插件变量

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["--config", "${PLUGIN_ROOT}/config/db.json"],
      "cwd": "${PLUGIN_ROOT}",
      "env": {
        "DATA_DIR": "${PLUGIN_DATA}/database"
      }
    }
  }
}

10. 版本控制

10.1 规范和 Schema 版本

§1 中的版本标识完整的 Agent Plugins 规范发行版，包括其规范性文本、插件清单 Schema 和 MCP 配置 Schema。每个规范发行版 MUST 发布与规范版本相同的两个 Schema，即使某个 Schema 的验证规则与上一发行版相同。

插件所必需的 plugin.json $schema 值声明包所面向的 Agent Plugins 版本。存在 mcp.json 时，其 $schema 值中的版本 MUST 与 plugin.json 声明的版本一致。版本不匹配会使 MCP 配置根据 §7.2.2 无效，但不会使其他组件类型无效。

任一 Schema 发生变化都需要发布新的规范版本。已发布的规范 Schema 标识符 MUST NOT 重新分配给不同的 Schema 内容。现有插件 MAY 继续面向较旧的 Agent Plugins 版本；客户端使用声明的规范标识符和任何明确的兼容性映射来确定支持情况。

10.2 插件版本

插件 SHOULD 为 version 使用语义化版本。

客户端 MAY 使用 version 来确定是否有更新，以及缓存是否过期。

11. 客户端合规性

11.1 客户端最低要求

合规客户端 MUST 满足第 1 至 10 节中所有适用的要求。它至少需要：

1. 能从目录路径加载插件。
2. 根据 $schema 选择本地支持的插件清单 Schema，然后使用 §5.2 和 §8.1 中的非致命例外来解析和验证封闭的 plugin.json Schema。
3. 忽略 extensions 中未实现的成员，且不验证其值的内容。
4. 对支持的每种组件类型，从固定位置发现组件。
5. 如果支持 MCP 服务器，根据 $schema 选择本地支持的 MCP 配置 Schema，并支持 mcp.json 中 stdio 或 streamable-http 变体的至少一种。
6. 如果客户端启动插件子进程（即 stdio MCP 服务器），提供 PLUGIN_ROOT 和 PLUGIN_DATA，并在运行时配置值（args、env、cwd）中展开两个变量。
7. 对于 stdio MCP 服务器，将 command 解析为单个可执行文件标记，并使用插件根目录作为子进程默认工作目录。
8. 支持至少一种组件类型（技能或 MCP 服务器）。

11.2 渐进采用

客户端不必支持每种组件类型。例如，仅支持技能的客户端可以在不支持 MCP 服务器的情况下合规，前提是它满足所有适用要求。

11.3 不支持的组件和失败

1. 客户端 MUST 忽略不支持的组件类型。
2. 根据 §5.2 和 §8.1，未知顶层字段或不是对象的 extensions 字段属于非致命问题。任何其他 plugin.json Schema 违规对插件都是致命的：客户端 MUST 拒绝插件，并且 MUST NOT 发现或执行其中的任何组件。
3. 只影响某个组件类型、组件条目或组件进程的失败 MUST NOT 阻止客户端加载独立有效的组件。客户端 MUST 应用 §6 和 §7 中为该组件定义的失败行为。
4. 客户端 SHOULD 报告无效配置和组件失败。客户端 MAY 报告部分不受支持的插件，但不支持某个组件类型、MCP 传输或客户端扩展本身并不是错误。

附录 A：合规性检查清单

此检查清单只为方便使用。如果与上面的规范文本冲突，以规范为准。

插件加载器

• 解析并验证 plugin.json（§5.1、§5.2）
• 验证必需的 $schema 和 name 字段（§5.3）
• 根据命名限制验证插件名称（§5.5）
• 报告并忽略未知的 plugin.json 字段（§5.2）
• 忽略 extensions 中未实现的命名空间，且不验证其值的内容（§8.1）
• 拒绝解析到插件根目录之外的包路径（§4.1）
• 从顶层命名空间目录发现已实现的基于文件的扩展（§8.2）

组件发现

• 扫描支持的每种组件类型的固定位置（§6.1）
• 忽略缺失的固定位置，不视为错误（§6.2）

MCP 配置

• 选择支持的 $schema，然后验证封闭的 mcp.json Schema 和每种服务器变体（§7.2.1）
• 如果支持 MCP，至少实现 stdio 或 Streamable HTTP 中的一种（§7.2.1）
• 首次尝试连接时使用各服务器条目声明的传输方式（§7.2.1）
• 强制执行远程 URL 和字面量标头要求（§7.2.1）

环境与展开

• 如果客户端启动插件子进程，提供 PLUGIN_ROOT 和专用的可写 PLUGIN_DATA 目录（§9.1）
• 将 MCP 服务器 command 解析为单个纯可执行文件标记或插件相对可执行文件标记（§7.2.1）
• 使用插件根目录作为 MCP 服务器默认工作目录（§7.2.1）
• 验证明示 cwd 形式和解析后的包含关系（§7.2.1）
• 将配置的 env 条目叠加到客户端选择的基础环境中（§9.1）
• 应用配置的 env 后设置客户端提供的 PLUGIN_ROOT 和 PLUGIN_DATA，并按平台环境变量名称语义替换等效名称（§9.1）
• 不要求配置的 PATH 影响纯命令解析（§7.2.1）
• 仅在 MCP 服务器的 args、env 和 cwd 字段中展开 ${PLUGIN_ROOT} 和 ${PLUGIN_DATA}（§9.2）

恢复能力

• 忽略不支持的组件类型（§11.3）
• 跳过声明了不支持的传输方式的服务器条目，而不影响其他服务器或组件（§7.2.2）
• 独立组件失败时继续加载（§11.3）
• 支持至少一种组件类型（§11.1）

设计决策

本节说明主要设计选择的原因，仅供参考。具有约束力的规则见上文的规范性章节。

为什么基于目录发现？

插件使用文件系统目录作为包单元，而不是归档格式（.zip、.tar.gz）或从注册表获取的包。这样可以用标准工具（ls、cat、git）检查插件，在开发期间原地编辑插件，也可以直接使用版本控制。skills/ 和 mcp.json 等固定根级位置省去了发现间接层、备用来源的优先级，以及原本每个客户端都要实现的清单配置。

为什么 v1 只包含 Agent Skills 和 MCP？

Agent Plugins v1 聚焦 Agent Skills 和 MCP，因为两者都有在本项目之外制定的成熟规范，也已得到多个客户端实际采用。命令、钩子、智能体、规则和 LSP 服务器等其他拟议组件类型仍过于依赖具体客户端。它们在格式趋于一致之前不属于 v1 格式，也没有稳定的可移植约定。

为什么根目录 plugin.json 是合规性基线？

每个合规客户端 MUST 检查插件根目录中的 plugin.json（§5.1）。因此，插件作者只需提供一份保证适用于所有客户端的清单，无需了解客户端专属路径。

为什么使用封闭的可移植清单？

将根目录 plugin.json 限制为已知字段，可以进行严格验证、发现拼写错误，并由 Schema 驱动键名补全。客户端实验不能声称任意顶层字段有效；这些数据应放在 extensions 下的反向域名键中。未知顶层字段仍违反 Schema，但客户端会报告并忽略它们，而不是拒绝其他部分有效的插件。

为什么使用反向域名客户端扩展？

反向域名标识符提供了一种无需中央客户端名称注册表即可避免冲突的分散约定。同一标识符可用于清单数据和客户端专属目录，且任一表示都可以独立存在。扩展目录保留在顶层，使插件布局保持扁平并遵循约定。

为什么要有显式 MCP 配置格式？

现有客户端采用互不兼容的 MCP 配置结构，推断传输方式的方法也不同。因此，Agent Plugins 定义一个明确的封闭联合，其含义独立于任何客户端原生格式。区分 Streamable HTTP 与旧版 HTTP+SSE，使每个条目的首次传输方式不存在歧义；连接失败后的回退行为则不属于可移植格式。

为什么客户端可以只支持一种标准 MCP 传输？

Stdio 和 Streamable HTTP 适用于不同的部署和安全模型。如果要求每个支持 MCP 的客户端同时支持本地进程执行和远程 HTTP 连接，会扩大实现范围和信任边界，却不会改变可移植配置格式。由于每个服务器条目都会声明传输方式，客户端可以跳过不支持的条目，同时继续加载其他独立的服务器和组件。

为什么 Schema 与规范共用版本？

plugin.json 和 mcp.json Schema 使用 Agent Plugins 规范版本，而不是各自独立的版本序列。这样，插件作者和客户端只需理解一个可移植格式版本，可以避免包中混用版本，并让 $schema 选择完整的验证和解释约定，其中也包括 JSON Schema 无法表达的要求。在新的规范发行版中重新发布未更改的 Schema 会增加少量维护成本，但比公开三条独立的兼容性时间线简单。

为什么在配置中使用插件变量而不是相对路径？

MCP 服务器参数在运行时经常需要绝对路径。${PLUGIN_ROOT} 为捆绑文件提供明确且由客户端解析的锚点，${PLUGIN_DATA} 则标识客户端管理的可写状态，该状态在更新期间替换包内容时仍会保留。command 字段不使用插值：./ 路径直接相对于插件根目录解析，纯名称使用平台的可执行文件搜索规则。将 command 视为单个标记，客户端就不必解析和转义用户编写的 shell 命令字符串。客户端继承的环境和 PATH 行为各不相同，因此 Agent Plugins 标准化配置的环境覆盖值，但将纯命令搜索留给客户端定义；插件相对命令可以确定性地执行捆绑文件。

为什么组件失败不是致命错误？

MCP 服务器无法启动或连接时，客户端继续加载插件的其余组件（§11.3）。同时提供技能和 MCP 服务器的插件不应因一个服务器不可用而完全无法使用。规范在允许非致命组件失败的同时要求诊断，使失败保持可见，而不是静默发生。