代码语言

知识点思维导图

24 个知识节点

参考资料

Codex（10） - 插件化实战

读完后，你应能完成以下任务：

绘制“Codex（10） - 插件化实战 / 插件设计原则”的关键对象与数据流，解释“用户应该调用 Skill，而不是直接理解一堆 agent。”，并用源码位置、日志或 Trace 标注证据。

为“Codex（10） - 插件化实战 / Agent 单一职责”设计正常与异常输入，验证“一个 agent 只负责一个维度。”，输出首个偏差位置与回归测试结果。

实现“Codex（10） - 插件化实战 / marketplace 只做索引”的最小代码或配置，检验“marketplace 不应该塞业务逻辑，只登记插件名称、来源、描述等元数据。”，输出命令、结果与 Diff，并说明不适用边界。

当 Skill、Subagent、脚本、配置开始变多，就需要更高层的组织方式：插件。

插件可以把一组能力打包起来，例如：

一组 Skill。
一组 Subagent。
一些脚本或资源。
插件清单。
marketplace 索引。

你当前的 imber-plugins 就是一个 Codex 插件市场的例子。它把 review、dev、feishu、docs、git 等能力拆成插件，再通过 marketplace 管理。

一、概念解释

一个简化插件结构：

plugins/
└── docs/
    ├── .Codex-plugin/
    │   └── plugin.json
    ├── skills/
    │   └── md-polish/
    │       └── SKILL.md
    └── agents/
        └── markdown-reviewer.md

marketplace 索引：

.Codex-plugin/
└── marketplace.json

核心文件职责：

文件	作用
`marketplace.json`	注册有哪些插件
`plugin.json`	描述单个插件
`SKILL.md`	面向用户的工作流入口
`agents/*.md`	面向内部编排的专用代理
`scripts/`	可执行辅助脚本
`references/`	参考资料

二、插件设计原则

2.1 Skill 面向用户，Agent 面向编排

用户应该调用 Skill，而不是直接理解一堆 agent。

比如 review 插件：

/review-all 是用户入口。
bug/security/test/maintainability agent 是内部执行单元。

2.2 Agent 单一职责

一个 agent 只负责一个维度。这样输出更稳定，也方便组合。

2.3 marketplace 只做索引

marketplace 不应该塞业务逻辑，只登记插件名称、来源、描述等元数据。

三、使用示例

新增一个 notes 插件的思路：

1. 在 plugins/notes/.Codex-plugin/plugin.json 写插件信息。
2. 在 plugins/notes/skills/md-polish/SKILL.md 写用户入口。
3. 如有需要，在 plugins/notes/agents/ 里写专用 agent。
4. 在 .Codex-plugin/marketplace.json 注册 notes。
5. 用一个真实 Markdown 文件跑一遍验证。

plugin.json 示例：

{
  "name": "notes",
  "description": "学习笔记整理、润色和目录维护插件。",
  "version": "0.1.0"
}

marketplace 条目示例：

{
  "name": "notes",
  "source": "plugins/notes",
  "description": "学习笔记整理、润色和目录维护。"
}

四、常见错误

4.1 错误 1：新增插件忘记注册 marketplace

插件目录建好了，但市场索引没登记，后续就找不到。

4.2 错误 2：Skill 和 Agent 边界混乱

如果用户必须知道调用哪个 agent，说明插件抽象还不够清晰。Skill 应该承担编排入口。

4.3 错误 3：插件名和能力不匹配

utils、tools 这类名字太泛。插件名最好能表达领域：

review
docs
git
feishu
dev

五、最佳实践

先从一个 Skill 开始，不急着设计完整插件。
当 Skill 数量变多或需要共享 agent，再抽成插件。
每个插件都有清楚的 README 或说明。
修改插件后，用真实任务跑一遍。
新增插件必须同步更新 marketplace。

六、本章小结

插件化不是为了显得高级，而是为了让能力可安装、可组合、可维护。先把一个重复工作流做成 Skill，再把相关 Skill 和 Agent 收拢成插件，是最自然的演进路径。

七、动手实践：10 plugin workflow

这个 demo 是一个迷你 Codex 插件市场结构，用来理解 plugin、skill、agent、marketplace 的关系。

7.1 目录内容

.Codex-plugin/marketplace.json
plugins/notes/.Codex-plugin/plugin.json
plugins/notes/skills/md-polish/SKILL.md
plugins/notes/agents/markdown-structure-reviewer.md

7.2 使用方式

让 Codex 审查插件结构：

codex exec --sandbox read-only --ask-for-approval never "请检查这个插件 demo 的结构是否合理，并说明 marketplace、plugin、skill、agent 的职责"

也可以让 Codex 基于这个结构新增一个 skill：

codex "请在 notes 插件里新增一个 md-outline skill，用于根据 Markdown 文件生成目录摘要，并同步更新必要说明"

7.3 练习目标

理解插件市场的索引关系。
理解 Skill 面向用户、Agent 面向内部编排。
练习新增插件能力时同步更新元数据。

7.4 配套实践材料

以下材料已并入正文，便于阅读时直接对照和练习。

plugins/notes/agents/markdown-structure-reviewer.md

# markdown-structure-reviewer

## 职责

只审查 Markdown 文档结构，不负责润色句子。

## 关注点

- 标题层级是否跳跃。
- 是否缺少导读。
- 段落是否过长。
- 清单是否可以提高可读性。
- 是否需要同步目录或进度表。

## 输出格式

```text
发现：
- ...

建议：
- ...
```text

plugins/notes/skills/md-polish/SKILL.md

---
name: "md-polish"
description: "当用户要求优化 Markdown 学习笔记、补充示例、调整结构时使用。"
---

# Markdown Polish

## 工作流

1. 阅读目标 Markdown 文件。
2. 判断主题、读者和当前结构。
3. 调用 markdown-structure-reviewer 思路检查标题层级。
4. 保留原始观点，优化表达。
5. 输出修改摘要和剩余风险。

## 风格

- 中文。
- 通俗。
- 示例驱动。
- 不新增无法确认的外部事实。

八、总结

插件设计原则：用户应该调用 Skill，而不是直接理解一堆 agent。
常见错误：如果用户必须知道调用哪个 agent，说明插件抽象还不够清晰。
最佳实践：新增插件必须同步更新 marketplace。
Agent 单一职责：一个 agent 只负责一个维度。