Codex
9.9 KiB
Codex Subagent Router
当前版本：2.1.0。Sol 常态指挥，Astra 前置处理关键疑难，按就绪状态滚动并行；见 2.1 版本说明、舰队调度 和 专家介入与裁决。
面向 GPT-6 Astra / GPT-5.6 Sol / Terra / Luna 的 Codex 路由技能与工程提示词。把可独立完成的工作交给合适的模型，并让触发、运行状态、证据与最终责任保持清楚。
这是供 Codex 读取的技能和可选提示词，附带证据校验、安装与测试工具。它不包含常驻调度器，也不会自行调用模型、修改模型配置或开启并行权限。
做什么
- 区分只读审查、已授权委派和普通本地工作，避免“选中了技能就自动启动 agent”。
- 按任务形状分配模型与 effort，创建任务时显式选择，避免所有子任务继承昂贵的主模型。
- 区分文件写集与语义写集、共享目录与真实隔离、合同约束与宿主强制能力。
- 管理运行中补充、空闲复用、等待、中断与收口；没有 close 工具时不要求虚构关闭。
- 分开记录请求的模型、宿主确认的运行身份、子任务完成和主线程验收；缺失身份使用 unknown。
目录
| 路径 | 用途 |
|---|---|
| skills/codex-subagent-router/SKILL.md | 可安装技能入口 |
| skills/codex-subagent-router/references | 路由边界、运行时、生命周期和证据合同 |
| prompts/AGENTS.md | 可选全局工程提示词 |
| AGENTS.md | 本仓库开发约定，不是安装模板 |
| scripts/install.py | 默认预览、按文件备份的安装工具 |
| examples | 明确标记的合成证据样例 |
| tests | 校验器与安装安全行为测试 |
| docs/behavior-scenarios.md | 触发与管理的行为验收场景 |
| docs/development.md | 维护、兼容与后续验证约定 |
安装
需要 Python 3.9+。仓库工具只使用标准库。
git clone https://git.wun.im/kakan/codex-subagent-router.git
cd codex-subagent-router
python3 scripts/install.py
最后一条命令仅预览差异。确认目标后安装技能：
python3 scripts/install.py --apply
默认使用环境变量 CODEX_HOME，未设置时使用 ~/.codex；也可以通过 --codex-home /path/to/codex-home 指定。默认只同步技能，不改全局提示词。
若要同时使用本仓库的全局工程提示词，先审阅模板和本机已有规则，再运行：
python3 scripts/install.py --include-prompt
python3 scripts/install.py --include-prompt --apply
--include-prompt --apply 会替换目标 AGENTS.md，不是智能合并；原文件先备份。安装不会修改 config.toml、其他技能或本地额外文件，不清理未收录文件，遇到目标路径中的符号链接会拒绝安装。
安装后按所用客户端的规则重新加载或开始新会话，并检查技能是否可见。写入文件不证明已启动会话采纳了新规则。
使用与触发
技能可以自动被选中帮助做路由判断，但自动发现不授予委派权限。明确要求执行委派的示例：
使用 $codex-subagent-router，把这个任务中可独立完成的部分交给子智能体；
主线程继续关键路径，显式选择合适模型，完成后检查证据与残留任务。
只读审查示例：
使用 $codex-subagent-router 检查当前模型继承、触发规则和生命周期工具，
仅报告发现，不创建子任务、不修改设置。
获得明确授权后，同一范围内无需逐次询问是否创建子任务；有独立产物和并行收益才分工。更高优先级宿主限制始终有效。修改这份技能、任务复杂、模型可用或选择 Ultra 本身不能覆盖这些限制。
模型策略
| 工作 | 起点 |
|---|---|
| 固定来源收集、枚举和检查 | Luna low/medium |
| 有界转换、分类、已定方案补丁 | Luna high |
| 常规实现、调试和跨文件调查 | Terra medium，必要时 high |
| 复杂分析、设计和关键语义证据 | Sol medium，必要时 high |
| 高影响困难方案、跨系统综合、独立深度反例审查 | Astra medium，必要时 high |
| 共享决定、最终整合与验收 | 当前主线程 |
通用工程会话默认建议 Sol / medium；复杂推理按需 high。Sol 承担规划、复杂实现、整合和验收，Terra/Luna 承担适合的执行。Astra 可在影响多个后续任务的困难决策前介入，综合跨系统证据或独立寻找高影响改动的反例，也处理残余疑难；不必先失败。保留用户已选模型，最终责任属于实际主线程。技能不能自动切换当前主模型，也不保证成本或速度收益。
同类验收失败两次暂停该切片并重新分类；严重反例立即触发。缺数据、权限或工具先修复条件。裁决先统一基线，再用可证伪假设与检查解决冲突，不能按模型贵贱投票。主线程无法理解或验证关键结论时不得验收；问题解决后恢复较便宜的执行路径。
专家任务以问题、产物和退出条件为界，不设置统一的一次咨询配额。新增证据、可测试的细化或明确遗漏可支持持续多轮；没有可区分的进展时暂停该专题，而不是反复询问直到模型同意。决策记录保留累计咨询次数和每轮推进依据。
2.1 保持证据 schema 1/2 和决策记录 schema 1。新增连续记录中的咨询次数不可倒退检查；例子见 resolved.json。固定安装可检出已发布标签；2.1 合并后也可从最新 main 安装，版本号不代表标签或 Release 已创建。
更积极的并行
获得委派授权后，在任务开始、依赖解除和子任务返回时主动寻找就绪工作。先派发独立调查；某个模块合同稳定后即可开始实现，不等全局调查结束。有真实空闲容量就滚动补位，不等整批结束。
队形随任务调整：可用多个同模型调查者、多个独立实现者，或 Astra 专题分析与其他执行者并行；不固定审查员席位或模型比例。主线程持续推进独立关键工作，统一共享合同与最终验收。
文件和语义写集都必须有 owner。整合积压、过期基线、反复返工或共享资源争用时，减少派发并优先整合，解决后再扩展。审查和最终测试针对固定提交或稳定产物。所有后代纳入宿主真实容量；没有 close 工具不能虚构释放槽位。
并行上限读取实际工具 schema，不在技能中写死数量，也不通过额外任务或嵌套进程绕过限制。更细拆分会增加上下文、重试和整合成本；先比较相同任务在串行及不同受支持宽度下的质量、耗时和总成本，再调整策略。Astra 前置分析可能减少返工，尚不能据此声称整体更便宜或更快。
按实时工具 schema 检查模型、effort、fork、并发槽位和工作区。API 模型目录不证明当前子智能体支持。可选配置示例见 运行时参考，安装工具不会应用它。
验证
python3 -m unittest discover -s tests -v
python3 scripts/check_repository.py
python3 skills/codex-subagent-router/scripts/validate_evidence_packet.py --self-test
python3 skills/codex-subagent-router/scripts/validate_evidence_packet.py examples/completed-unknown.json
python3 skills/codex-subagent-router/scripts/validate_decision_record.py examples/decisions/resolved.json
python3 scripts/install.py --include-prompt --check
最后一条命令只检查本机安装差异：一致返回 0，有差异返回 1；不会写入。单元测试和 examples 使用合成数据，不能证明任何模型已运行。
新证据使用 v2；未带版本的旧格式按 v1 读取并提示迁移。校验成功只证明结构可接受，不能证明 child ID、身份或业务结论真实。真实环境的前向测试应在获授权的有界任务中进行，并保留实际工具回执。
若本机有 skill-creator，还应运行其 scripts/quick_validate.py 检查技能；它依赖 PyYAML。缺少该工具或依赖时如实报告，不把仓库检查冒充为上游校验。
更新与回退
正常开发使用功能分支与 PR，测试通过后由仓库所有者按流程合并。更新本机前先确认工作树并拉取已审阅版本，再运行安装预览。
每次实际变更会在 CODEX_HOME/backups/codex-subagent-router/<时间-随机标识>/ 保留原文件和 manifest.json。清单记录路径、原先是否存在及前后 SHA-256。
回退时先比对当前文件与清单中的安装后哈希，保留安装后的用户修改；再把备份中的指定文件恢复到同一相对路径。原先不存在的文件不会有备份，只有确认它仍是本次新建版本时才按清单逐个移除。不要递归清空整个技能目录。安装按文件原子替换，不承诺整个目录的事务性；中断后依据清单检查实际状态。
与其他技能协作
本仓库不会自动修改 StockAgent 或其他编排技能。旧技能中的 Sol 主线程要求、严格身份探针、独立工作区假设或 close 要求可能仍影响任务。需要时把这些规则纳入明确的联合迁移范围；不能由本技能假装旧门槛已经满足。
官方参考
本轮依据核对日期：2026-09-14。模型分工属于工程策略；宿主真实能力与实际任务证据优先。