构建自己的插件

你是 Codex 插件开发顾问，帮我规划构建一个小而可用的插件，从设计到发布前检查。

【角色】
你理解插件的三个核心概念、什么时候该做插件、为什么第一版要尽量小、marketplace 怎么放、发布前要检查什么。

【输入】
- 我想做的插件要解决什么：___
- 目标用户（自己 / 团队 / 公开）：___
- 它要访问的资源和权限：___
- 我的开发经验：___

【工作流程】
1. 判断这个需求是否值得做成插件
2. 设计第一版的最小功能范围
3. 给核心结构和权限边界
4. 给发布前的功能 / 权限 / 安全检查清单

【输出规范】
▌一、是否值得做插件的判断
▌二、第一版最小功能设计
▌三、核心结构 + 权限边界
▌四、发布前检查清单

【硬约束】
- 第一版尽量小，先解决一个明确问题
- 权限按最小必要，不索取多余权限
- 公开发布前过安全和隐私检查
- 不确定的插件 API 标注需查官方文档
- 不替我假设用途，需求不清先问

Codex plugin 是分发单元，用来把 skills、MCP 配置、app integration 或其他能力打包给别人安装。它不是“把一段 prompt 包起来”。

新手最常见的错误，是本来只需要本地 skill，却一上来做 plugin、marketplace 和发布目录。

三个概念

flowchart LR
    Skill["Skill<br/>工作方法"]
    Plugin["Plugin<br/>分发包"]
    Marketplace["Marketplace<br/>发现和安装目录"]

    Skill --> Plugin
    Plugin --> Marketplace

Skill 解决：

• Codex 在某类任务上应该怎么做。
• 触发条件、步骤、输出和验证。

Plugin 解决：

• 把一组能力打包给别人安装。
• 可以包含 skills、MCP、hooks、app mappings 等。

Marketplace 解决：

• Codex 从哪里发现 plugin。
• 团队或个人如何维护可安装清单。

什么时候该做 plugin

适合：

• 能力已经被反复使用。
• 有清楚名称、说明、输入边界和使用场景。
• 安装后别人能直接在 Codex 里发现。
• 需要一起分发 skill、MCP 或其他配置。
• 愿意维护版本、兼容性和变更记录。

不适合：

• 只是一次性 prompt。
• skill 还没跑稳。
• 只服务当前仓库的临时任务。
• 还没想清楚权限和外部依赖。
• 只是为了目录看起来更工程化。

第一版应该尽量小

第一版 plugin 建议只包含一个稳定 skill。

最小结构：

my-plugin/
  .codex-plugin/
    plugin.json
  skills/
    my-skill/
      SKILL.md

说明必须写清：

• 插件解决什么任务。
• 什么时候应该调用。
• 什么时候不应该调用。
• 是否需要 token、MCP、外部网络或账号。
• 安装后如何确认生效。

不要第一版就塞多个 skills、多个 MCP servers 和复杂 hooks。包越大，排错越难。

最小 manifest 放在 .codex-plugin/plugin.json：

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable workflow for one stable Codex task.",
  "skills": "./skills/"
}

name 使用稳定 kebab-case。Codex 会把它当成 plugin identifier 和 component namespace。

Marketplace 怎么放

Marketplace 是 JSON catalog，不是 plugin 本身。常用位置：

本地 repo marketplace 的最小条目：

{
  "name": "local-repo",
  "interface": {
    "displayName": "Local Repo Plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

source.path 必须相对 marketplace root，并以 ./ 开头。修改 marketplace 或 plugin 后要重启 Codex；local plugin 会被安装到 Codex cache 中，Codex 读取的是安装后的副本，而不是你刚编辑的源目录。

也可以用 CLI 添加 marketplace：

codex plugin marketplace add ./local-marketplace-root
codex plugin marketplace upgrade
codex plugin marketplace remove marketplace-name

发布前检查

发布前确认：

• plugin name 稳定。
• version 清楚。
• description 能触发正确任务。
• 不包含密钥、token、私有 URL。
• 外部依赖写明。
• 禁止事项写明。
• 关闭 plugin 后不会留下全局副作用。

如果插件会调用外部系统，还要说明权限、数据流和审计方式。

安装后怎么验证

本地验证不要只看文件存在，要在 Codex 里确认：

• /plugins 能看到对应 marketplace。
• plugin details 能展示名称、说明和 category。
• 安装后 bundled skills 能被调用。
• 需要认证的 app 或 MCP 会在 install 或首次使用时提示。
• 禁用 plugin 后，相关能力不再触发。

如果插件包含外部 app、MCP server 或 hooks，还要单独确认权限提示和失败路径。安装 plugin 只是让 workflow 可用，Codex 现有 approval settings 仍然生效，外部服务仍受自己的认证和隐私策略约束。

推荐流程

1. 先写本地 skill。
2. 在真实任务中跑多次。
3. 记录误触发、缺上下文和失败点。
4. 用 plugin creator scaffold plugin。
5. 本地 marketplace 安装测试。
6. 换干净环境复验。
7. 再放进团队 repo marketplace。

每一步都要可回滚。不要把未稳定能力分发给团队。

常见坑

• marketplace 路径写错。
• 修改后忘记重启或刷新 Codex。
• description 太泛，导致误触发。
• 把敏感配置打进插件。
• 缺少版本和变更记录。
• 安装说明只适用于作者机器。
• skill 和 plugin 职责混在一起。

Plugin 的目标是分发稳定能力，而不是提前包装不稳定流程。

官方资料

• Plugins
• Build plugins
• Agent Skills
• Agent approvals and security