免费 AI IDE
Codex 插件是一个可安装的扩展包：它用 manifest 声明身份，再按需组合技能、应用连接器、MCP 服务、命令、Agent 和 Hook。你不必把所有能力都塞进一个插件；正确做法是先确定用户任务，再选择最小的能力面。
本文依据 2026 年 9 月 20 日核验的 OpenAI 官方插件仓库，解释当前目录结构与职责边界。看完后，你应能读懂一个插件、判断功能该放在哪层，并在安装前检查权限。今天这篇文章，编程狮不讨论抽象“生态”，而是直接拆一个最小目录。
一、先看结论：各能力面负责什么
| 能力面 | 职责 | 适合放什么 | 不适合放什么 |
|---|---|---|---|
| manifest | 插件身份证 | 名称、版本、描述 | 业务逻辑、长篇教程 |
| skill | 任务方法与规范 | 步骤、模板、脚本 | 长期密钥、远端会话 |
| app | 授权入口与产品连接 | 用户授权、账号连接 | 大段写作规范 |
| MCP | 结构化工具 | 查询、创建、更新 | 仅供人阅读的教程 |
| command | 显式可复用入口 | 用户主动触发的操作 | 隐蔽副作用 |
| hook | 生命周期检查与自动动作 | 提交前检查、通知 | 未告知的外部写入 |
| assets | 辅助资源 | 示例图、模板、词典 | 运行时代码 |
一句话：先确定用户任务，再选择最小的能力面；目录越多不代表质量越高。
二、Codex 插件先从最小 manifest 开始
官方仓库把每个示例放在 plugins/<name>/，必需文件是 .codex-plugin/plugin.json。这份 manifest 是插件的身份证，而不是业务实现。站内的 Codex 插件参考 可以搭配本文查字段。
my-plugin/
├─ .codex-plugin/
│ └─ plugin.json # 插件身份证：名称、版本、描述
├─ skills/ # 技能：任务说明、规范、模板、脚本
├─ .app.json # 应用连接器：授权入口与产品连接
├─ .mcp.json # MCP 服务：结构化工具配置
├─ agents/ # Agent：可复用的代理配置
├─ commands/ # 命令：用户显式触发的入口
├─ hooks.json # Hook：生命周期事件与自动动作
└─ assets/ # 辅助资源：图片、模板、词典
除 plugin.json 外，其余目录都应按需出现。一个只提供写作规范的插件可能只有技能；连接外部服务的插件才需要应用或 MCP。空目录不会让插件更完整，只会让维护者误判能力范围。
| 目录/文件 | 是否必需 | 说明 |
|---|---|---|
.codex-plugin/plugin.json |
必需 | 插件身份声明 |
skills/ |
可选 | 固定流程与规范 |
.app.json |
可选 | 产品授权与连接 |
.mcp.json |
可选 | 外部工具配置 |
agents/ |
可选 | 代理配置 |
commands/ |
可选 | 显式操作入口 |
hooks.json |
可选 | 生命周期钩子 |
assets/ |
可选 | 静态资源 |
三、技能、应用与 MCP 分别解决什么
Codex 技能是一组任务说明和本地资源，适合固定流程、格式规范和脚本调用。应用连接器负责受控访问某个产品或账号。MCP 则提供结构化工具，让模型调用外部服务。三者关系可以理解为“做事方法、授权入口、可调用动作”。
| 能力面 | 适合放什么 | 不适合放什么 |
|---|---|---|
| skill | 步骤、规范、模板、脚本 | 长期密钥、远端账号会话 |
| app | 用户授权、产品连接 | 大段写作规范 |
| MCP | 查询、创建、更新等工具 | 仅供人阅读的教程 |
| command | 可复用的显式入口 | 隐蔽的副作用 |
| hook | 生命周期检查和自动动作 | 未告知用户的外部写入 |
如果你还没装好客户端，应先完成 Codex 安装说明，再研究扩展。基础运行环境都不稳定时，插件报错很难区分是安装、权限还是插件自身问题。
四、用任务边界决定插件目录
假设要做一个“审查 Markdown 并输出报告”的插件，可以按下面顺序判断：
- 规则是否固定？若固定，写入
skill； - 是否需要访问外部文档库？需要时再加入
app或MCP； - 是否要让用户显式运行某个动作？可以提供
command； - 是否必须在提交前自动检查？确认副作用后再考虑
hook； - 是否需要示例图、模板或词典？放进
assets。
// plugin.json 示例：只声明身份，不包含业务逻辑
{
"name": "markdown-review",
"version": "0.1.0",
"description": "Review Markdown structure and produce a local report"
}上面只是说明 manifest 的职责，并非保证与未来版本字段完全一致。创建插件时必须以仓库内最新示例为准。想理解技能如何承载稳定流程，可以继续阅读 AI 编程技能教程。
| 任务需求 | 推荐能力面 | 原因 |
|---|---|---|
| 固定写作规范 | skill | 方法与模板 |
| 访问 Notion、Figma | app 或 MCP | 需要授权与外部工具 |
| 用户主动运行检查 | command | 显式入口 |
| 提交前自动检查 | hook | 生命周期事件 |
| 提供示例图 | assets | 静态资源 |
| 组合多个步骤 | agent | 代理流程 |
五、安装前先检查权限和副作用
插件能组合外部连接和自动动作，审查时不能只看名称。至少检查四处：manifest 声明、MCP 工具、应用权限、Hook 触发条件。
# 只列出关键配置文件，不执行插件
Get-ChildItem -Recurse -File .\my-plugin |
Where-Object { $_.Name -match 'plugin\.json|\.mcp\.json|\.app\.json|hooks\.json' } |
Select-Object FullName这条命令只列出关键配置，不会执行插件。随后逐项回答：工具是只读还是写入？会访问哪些域名？密钥从哪里取得？Hook 何时触发？失败后是否能回滚？如果答案不清楚，先不要安装。
插件权限审查最好形成一张表，而不是凭文件名做判断：
| 检查项 | 可接受证据 | 需要暂停的信号 |
|---|---|---|
| 外部访问 | 域名与用途明确 | 任意域名或用途不明 |
| 写入动作 | 目标、确认与回滚清楚 | 后台静默写入 |
| 凭据 | 系统授权或环境注入 | 密钥写进仓库 |
| Hook | 触发时机和失败策略可见 | 每次运行都产生副作用 |
| MCP 工具 | 只读/写入范围明确 | 工具名称模糊、权限过大 |
| 应用授权 | 用户可撤销、范围最小 | 请求无关账号权限 |
官方 OpenAI 插件仓库 展示了 Figma、Notion、Web、iOS 等较完整示例。仓库只能证明官方示例在核验日采用这些结构，不代表第三方插件天然可信。
六、常见设计错误与修正
| 常见错误 | 问题 | 修正方向 |
|---|---|---|
| 把教程全文写进 manifest | manifest 应短小稳定 | 任务细节放 skill |
| 为了“功能齐全”同时加 app 与 MCP | 重复授权、排错困难 | 确认职责不重复 |
| Hook 默认执行外部写入 | 用户无法预期副作用 | 改为显式 command 或增加确认 |
| 空目录占位 | 误判能力范围 | 按需出现，不建空目录 |
| 权限说明模糊 | 安装后才发现越权 | 安装前逐项审查 |
| 版本升级不复查 | 能力面悄悄扩大 | 对比 manifest、MCP、app、hooks |
调试时先退回最小插件：保留 manifest 和一个 skill，确认能被识别；再逐个恢复 MCP、应用和 Hook。每恢复一层就记录新增权限和实际结果。这样出现失败时，变更范围只有一层。
七、用最小验收确认目录与行为一致
验收不能停在“插件被识别”。按以下顺序逐步验证：
| 步骤 | 操作 | 验证目标 |
|---|---|---|
| 1 | 执行纯本地、只读的技能任务 | 说明与资源路径可用 |
| 2 | 单独调用一个 MCP 查询工具 | 工具配置正确、只读 |
| 3 | 测试需要授权的应用写入 | 授权范围与回滚明确 |
| 4 | 测试 Hook 触发 | 时机、副作用、失败策略可见 |
| 5 | 记录输入、调用、输出、外部变化 | 目录与行为一致 |
若插件声称只做 Markdown 审查，却在首次运行请求日历、邮箱或代码仓库写权限，目录设计与任务边界已经不一致。此时应删掉无关能力，或拆成另一个由用户显式安装的插件，而不是在说明里用一句“可能需要”掩盖权限扩张。
版本升级也按同样方法复查：对比 manifest、MCP 配置、应用权限和 hooks.json 的变化，再运行最小任务。不能只看版本号或更新日志，因为真正影响用户风险的是能力面与副作用是否改变。
| 升级检查项 | 对比内容 |
|---|---|
| manifest | 名称、版本、描述是否变化 |
| MCP 配置 | 工具、域名、权限是否扩大 |
| 应用权限 | 授权范围是否增加 |
| hooks | 触发时机、写入动作是否改变 |
| 最小任务 | 实际行为是否与说明一致 |
总结
Codex 插件不是单个提示词，而是一个带 manifest 的能力包。Codex 技能负责方法，应用负责授权入口，MCP 提供工具，命令提供显式操作，Hook 处理生命周期事件。目录越多不代表质量越高；能通过插件权限审查、目录与行为一致、每层都可单独验证的最小组合，才更容易维护。
延伸学习
- AI Coding 新范式解析 可补充 AI 编程工具的整体背景；
- Agentic Coding 入门 解释 Agent 式任务与普通补全的差异。
- 职场提效：小白 AI 办公实战课程
- 零基础AI编程：7天做出第一个真正能用的小工具
- 零基础AI手绘配图：从选画风到完成一组作品
- 不会Python也能写脚本：7天用AI自动化5件重复工作
常见问题
Q：一个 Codex 插件必须同时有技能和 MCP 吗？
A：不必须。官方结构把它们列为可选能力面。只需本地流程规范时，一个 manifest 加 skill 就可能足够。
Q：应用连接器和 MCP 能不能同时存在？
A：可以，但要确认职责不重复。应用偏向授权和产品连接，MCP 偏向结构化工具；重复能力会增加权限与排错成本。
Q：从 GitHub 下载的插件可以直接信任吗？
A：不能。先检查 manifest、外部服务、写入工具和 Hook，再决定安装。仓库热度和作者名称都不能替代权限审查。
Q：Hook 和 command 有什么区别？
A：command 是用户显式触发的入口，hook 是生命周期事件自动触发。需要用户主动运行时用 command；需要在提交前自动检查时再考虑 hook，并确保副作用可预期。
