最近在折腾 Codex 的 subagent 机制时，我发现了一个很有意思的问题：
Codex 是支持 subagent 的，但它永远不会主动提用 subagent。
也就是说，哪怕你给它一个非常适合拆分的任务，比如代码审查、复杂 bug 排查、代码路径分析、文档核对、多方案调研，它也会默认在主会话里自己硬啃。
这个设定有点反人类。
因为用过 agent 的都知道，主会话的上下文窗口其实很宝贵。任务越复杂，中间过程越多，主上下文就越容易被搜索记录、代码片段、文档信息、推理过程塞满。等会话越来越长，agent 就更容易开始忘事、跑偏，或者被前面的无关信息干扰。
所以我做了一个轻量级 Codex Skill：
cast-subagents
它的作用很简单：
让 Codex 在开始干活之前，主动判断当前任务是否值得拆给 subagent，并给出推荐的子代理阵容。
项目地址：
https://github.com/917Dhj/cast-subagents
为什么需要这个东西？
subagent 的价值在于，它可以把一些相对独立的任务拆出去处理。
比如：
- 一个 agent 负责代码路径梳理
- 一个 agent 负责文档或 API 行为核对
- 一个 agent 负责代码审查
- 一个 agent 负责测试风险分析
这些子 agent 执行完后，只需要把最终结论返回给主会话。中间大量搜索、阅读、遍历、验证的过程，都不会污染主上下文。
这样主会话会轻很多，也更适合处理长任务。
但问题在于，Codex 不会主动帮你判断：
- 这个任务该不该拆给 subagent
- 应该拆成几个子任务
- 每个子 agent 应该是什么角色
- 哪些只读，哪些允许改代码
- 是否需要先征求用户确认
这些都需要用户自己想清楚，然后主动告诉 Codex。
这就导致一个很现实的问题：
Codex 有能力使用 subagent，但用户经常忘了让它用。
cast-subagents 解决的就是这个问题。
cast-subagents 做了什么？
它不是一个自动派生 subagent 的调度系统。
它做的是一件更轻量、更安全的事：
在 Codex 执行任务前，先做一次任务判断。
-
如果当前任务很简单，比如改一个 typo、解释一个报错、修改单文件小 bug，它会保持安静，让 Codex 正常执行。
-
如果当前任务明显适合拆分，比如多角度代码审查、复杂代码库阅读、代码路径加文档验证、多方案技术调研，它会先停下来，给出一个推荐方案。
大概形式是这样：
只有在你确认之后，Codex 才会继续进行后续的 subagent 分工。
换句话说，它不是替你做决定，而是帮你把该不该拆、怎么拆这件事提前想好。
它是怎么实现的？
cast-subagents 主要由两部分组成：
AGENTS.md gate + SKILL.md advisor
可以简单理解成：
AGENTS.md gate负责常驻触发，让 Codex 在开始非简单任务前先检查是否值得拆分SKILL.md负责具体判断任务类型、选择角色阵容、决定工作模式，并生成建议内容
它的执行流程大概是这样：
用户发出任务
↓
AGENTS.md gate 先判断任务形态
↓
如果是简单任务，保持安静，Codex 正常执行
↓
如果是可拆分任务，调用 cast-subagents skill
↓
skill 判断任务类型
↓
推荐 1-4 个 subagent 角色
↓
说明 work mode
↓
停止，等待用户确认
这个设计我觉得比较克制。
因为 subagent 会增加 token 消耗，不适合所有任务。如果一上来就自动派生，反而可能带来额外成本。
所以 cast-subagents 选择的是建议优先，而不是自动执行。
内置了哪些角色？
项目里打包了一组常用的 subagent 角色，可以直接安装使用：
| 角色 | 作用 |
|---|---|
code-mapper | 梳理代码路径、模块边界和文件归属 |
reviewer | 检查正确性、安全性、测试风险和可维护性 |
docs-researcher | 核对官方文档、API 行为和框架约定 |
search-specialist | 快速搜索代码或外部资料中的高价值信息 |
knowledge-synthesizer | 汇总多个研究结果，生成可执行结论 |
task-distributor | 把宽泛任务拆成清晰的子任务 |
test-automator | 为风险点补充最小回归测试 |
常见组合比如：
| 任务类型 | 推荐阵容 | 模式 |
|---|---|---|
| 多角度 PR Review | reviewer + code-mapper + docs-researcher | read-only |
| 代码路径加文档验证 | code-mapper + docs-researcher | read-only |
| 多方案技术调研 | search-specialist + knowledge-synthesizer | read-only |
| 大型代码库探索 | code-mapper + search-specialist | read-only |
| 先探索再修改 | code-mapper + reviewer + worker | mixed |
| 测试补全 | reviewer + test-automator | write-capable |
三种工作模式
cast-subagents 会在建议中明确标注工作模式。
read-only
只读模式。
适合代码审查、代码路径分析、文档核对、调研总结。
这种模式下 subagent 只负责阅读、分析、汇报，不修改文件。
mixed
混合模式。
适合先调研再动手的任务。
一般是先让 subagent 做只读分析，等范围明确后，再决定是否进入修改阶段。
write-capable
可写模式。
适合测试补全、局部修复等明确需要改代码的任务。
这个模式会明确告诉你 subagent 可能修改文件，避免不知情的代码变更。
适合什么场景？
我觉得它最适合下面几类任务：
1. 复杂代码审查
比如：
Review this branch against main for bugs, security issues, missing tests, and maintainability risks.
这种任务天然有多个审查角度，很适合拆给不同角色并行处理。
2. 大型代码库阅读
比如：
先帮我梳理一下登录模块的完整调用路径，再判断这里能不能安全重构。
这类任务通常需要先看很多文件。如果都放在主会话里做，很容易把上下文撑大。
3. 代码路径加文档核对
比如：
先查清楚这段 checkout 逻辑的代码路径，再核对框架文档里相关 API 的行为。
代码阅读和文档核对可以并行，所以适合拆分。
4. 多方案技术调研
比如：
帮我调研三种后台任务重试方案，并比较它们的优缺点。
不同方案之间相对独立，可以让 subagent 分头查，最后再统一汇总。
安装方式
推荐直接让 Codex 读取安装说明：
Fetch and follow instructions from https://raw.githubusercontent.com/917Dhj/cast-subagents/refs/heads/main/.codex/INSTALL.md
Codex 会根据安装说明完成：
- 安装 skill
- 安装 AGENTS gate
- 根据当前环境推荐是否安装内置角色
- 提醒你重启 Codex
也可以手动安装：
npx skills add 917Dhj/cast-subagents -a codex
CAST_SUBAGENTS_HOME="${AGENTS_HOME:-$HOME/.agents}/skills/cast-subagents"
然后安装全局 AGENTS gate：
python3 "$CAST_SUBAGENTS_HOME/scripts/install-agents-gate.py" --scope global
推荐再安装内置角色：
python3 "$CAST_SUBAGENTS_HOME/scripts/install-agent-roles.py" --scope global
最后重启 Codex，让新的 skill 和 AGENTS 规则生效。
这个项目适合谁？
如果你平时只是让 Codex 写小函数、改小 bug，那可能没必要装。
但如果你经常让 Codex 做这些事：
- 阅读大型代码库
- 做复杂 PR Review
- 分析框架源码
- 核对文档和实现
- 调研多个技术方案
- 在长会话里持续处理复杂任务
那 cast-subagents 会很有用。
它解决的不是“Codex 能不能用 subagent”的问题，而是：
让 Codex 在该提醒你用 subagent 的时候，主动提醒你。
总结
Codex 支持 subagent，但它永远不会主动提 subagent。
这就导致很多适合拆分的任务，最后都被主会话自己硬吞了。上下文越来越重，任务越做越乱。
cast-subagents 的思路很简单：
不强制自动派生，不打乱原有工作流，只在合适的时候主动给出 subagent 分工建议。
你仍然保留最终决定权。
Codex 负责判断任务是否值得拆。
cast-subagents 负责推荐阵容和模式。
你负责点头或拒绝。
这可能是我目前觉得比较舒服的一种 subagent 使用方式。
项目地址：
https://github.com/917Dhj/cast-subagents
感兴趣可以试一下。如果你本来就经常用 Codex 处理复杂代码任务，这个 Skill 应该能明显改善你的工作流。
