# Codex Subagent Router

面向 **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/SKILL.md) | 可安装技能入口 |
| [skills/codex-subagent-router/references](skills/codex-subagent-router/references) | 路由边界、运行时、生命周期和证据合同 |
| [prompts/AGENTS.md](prompts/AGENTS.md) | 可选全局工程提示词 |
| [AGENTS.md](AGENTS.md) | 本仓库开发约定，不是安装模板 |
| [scripts/install.py](scripts/install.py) | 默认预览、按文件备份的安装工具 |
| [examples](examples) | 明确标记的合成证据样例 |
| [tests](tests) | 校验器与安装安全行为测试 |
| [docs/behavior-scenarios.md](docs/behavior-scenarios.md) | 触发与管理的行为验收场景 |
| [docs/development.md](docs/development.md) | 维护、兼容与后续验证约定 |

## 安装

需要 Python 3.9+。仓库工具只使用标准库。

```sh
git clone https://git.wun.im/kakan/codex-subagent-router.git
cd codex-subagent-router
python3 scripts/install.py
```

最后一条命令仅预览差异。确认目标后安装技能：

```sh
python3 scripts/install.py --apply
```

默认使用环境变量 `CODEX_HOME`，未设置时使用 `~/.codex`；也可以通过 `--codex-home /path/to/codex-home` 指定。默认只同步技能，不改全局提示词。

若要同时使用本仓库的全局工程提示词，先审阅模板和本机已有规则，再运行：

```sh
python3 scripts/install.py --include-prompt
python3 scripts/install.py --include-prompt --apply
```

`--include-prompt --apply` 会替换目标 `AGENTS.md`，不是智能合并；原文件先备份。安装不会修改 `config.toml`、其他技能或本地额外文件，不清理未收录文件，遇到目标路径中的符号链接会拒绝安装。

安装后按所用客户端的规则重新加载或开始新会话，并检查技能是否可见。写入文件不证明已启动会话采纳了新规则。

## 使用与触发

技能可以自动被选中帮助做路由判断，但自动发现不授予委派权限。明确要求执行委派的示例：

```text
使用 $codex-subagent-router，把这个任务中可独立完成的部分交给子智能体；
主线程继续关键路径，显式选择合适模型，完成后检查证据与残留任务。
```

只读审查示例：

```text
使用 $codex-subagent-router 检查当前模型继承、触发规则和生命周期工具，
仅报告发现，不创建子任务、不修改设置。
```

获得明确授权后，同一范围内无需逐次询问是否创建子任务；有独立产物和并行收益才分工。更高优先级宿主限制始终有效。修改这份技能、任务复杂、模型可用或选择 Ultra 本身不能覆盖这些限制。

## 模型策略

| 工作 | 起点 |
| --- | --- |
| 固定来源收集、枚举和检查 | Luna low/medium |
| 有界转换、分类、已定方案补丁 | Luna high |
| 常规实现、调试和跨文件调查 | Terra medium，必要时 high |
| 复杂分析、设计和关键语义证据 | Sol medium，必要时 high |
| 最困难的独立综合任务 | Astra medium，必要时 high |
| 共享决定、最终整合与验收 | 当前主线程 |

对于以复杂工程和长任务为主的工作，可从 Astra / medium 主线程开始；这是待实际工作校准的建议，不会改变用户已选模型，也不是效果或价格保证。主线程自己还要承担判断与整合，不能仅因可以委派就视为消息转发器。

按实时工具 schema 检查模型、effort、fork、并发槽位和工作区。API 模型目录不证明当前子智能体支持。可选配置示例见 [运行时参考](skills/codex-subagent-router/references/platforms.md)，安装工具不会应用它。

## 验证

```sh
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 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 要求可能仍影响任务。需要时把这些规则纳入明确的联合迁移范围；不能由本技能假装旧门槛已经满足。

## 官方参考

- [OpenAI 模型目录](https://developers.openai.com/api/docs/models)
- [GPT-6 Astra 使用与提示指南](https://developers.openai.com/api/docs/guides/latest-model)
- [Codex 子智能体](https://learn.chatgpt.com/zh-Hans/docs/agent-configuration/subagents)

本轮依据核对日期：2026-09-14。模型分工属于工程策略；宿主真实能力与实际任务证据优先。