OpenAI Plugins：包示例、便携格式与连接边界
OpenAI 插件架构：便携身份与 OpenAI 专属配置覆盖层
理解固定的便携组件位置、不合并的覆盖规则，以及应用映射和 MCP 配置之间的不同职责。
你将学会
- 便携身份负责定义包边界
- 内联 OpenAI 对象整体替代覆盖层
- 工作流指令和连接布线不同
开始前需要
- 了解基本 JSON 和目录路径
- 理解技能及外部服务权限
区分仓库示例与当前格式指导，检查插件包时不把元数据当作运行证明。
先看结论
- 便携身份和组件位置仍以根规范为准。
- 内联 OpenAI 对象会整体替代兼容覆盖层。
- 连接配置不证明运行时已经认证成功。
便携身份负责定义包边界
当前官方指导把声明 Agent Plugins schema 的根目录 plugin.json 作为便携入口，技能从 skills 发现，随包 MCP 配置从 mcp.json 发现。这些固定位置不会被 Codex 覆盖层中的 skills 或 mcpServers 声明替换或扩展。
没有被识别为便携根清单的历史示例，使用兼容清单自己的声明。因此，仅把旧文件移动到根目录并不等于完成迁移。需要一起审阅 schema、组件发现方式和 OpenAI 元数据位置，同时保留原本想提供的工作流。
内联 OpenAI 对象整体替代覆盖层
当便携清单中的 extensions.com.openai 是对象时，官方页面说明它会代替整个 .codex-plugin/plugin.json，提供 OpenAI 专属设置，两者不会合并。如果该内联对象缺失，兼容覆盖层可以提供这些设置，但便携身份仍以根清单为准。
这对分步迁移很重要：只含 interface 的内联对象，不会自动继承旧覆盖层的 apps 或 hooks。应检查最终被选中的完整设置对象，并测试预期能力。JSON 语法有效的文档，也可能缺少工作流所需连接。
工作流指令和连接布线不同
Figma 兼容示例中，skills 指向工作流目录，apps 指向 .app.json，后者将具名集成映射到注册连接标识。独立 .mcp.json 描述端点和 OAuth 资源。这些只是配置观察，并不证明某个宿主同时打开两种连接或自动去重。
配套教学模型演示便携身份、固定组件位置和整对象覆盖选择，不包含真实宿主加载、认证、策略执行及工具运行。它用于理解迁移错误，之后仍须在准备使用的受支持宿主中验证真实插件包。
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
先判断便携还是纯兼容布局。
- 2
确定唯一被选中的 OpenAI 设置对象。
- 3
把固定组件发现与覆盖字段分开核对。
- 4
在目标宿主中测试最终插件包。
可复制示例
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "synthetic-notes",
"version": "0.1.0",
"description": "合成会议记录练习",
"extensions": {
"com.openai": {
"interface": {
"displayName": "合成会议记录"
}
}
}
}常见问题
内联设置与兼容设置会合并吗？
不会。官方页面说明内联对象整体替代旧覆盖层。
覆盖层可以改写便携技能发现路径吗？
不能。已识别的便携包使用固定 skills 和 mcp.json 位置。
资料来源
- OpenAI Plugins / plugins/figma/.codex-plugin/plugin.json来源核查 2026-09-14
- OpenAI Plugins / plugins/figma/.app.json来源核查 2026-09-14
- OpenAI Plugins / plugins/figma/.mcp.json来源核查 2026-09-14
- OpenAI — Package your plugin (checked 2026-09-14)来源核查 2026-09-14