Codex Agent
150 lines
11 KiB
Markdown
150 lines
11 KiB
Markdown
# Codex Subagent Router
|
||
|
||
当前版本：**2.2.0**。GPT-6 三档路由、积极 Luna 舰队与任务连续性适配；保留 2.1 的 Astra 前置介入、滚动调度及证据裁决。见 [2.2 发行说明](docs/releases/2.2.0.md)、[舰队调度](skills/codex-subagent-router/references/fleet.md) 和 [专家介入与裁决](skills/codex-subagent-router/references/escalation.md)。
|
||
|
||
面向 **GPT-6 Luna / Sol / Astra** 的 Codex 路由技能与工程提示词。把可独立完成的工作交给合适的模型，并让触发、运行状态、证据与最终责任保持清楚。Terra 已退出推荐与自动回退路线；旧宿主按实际能力显式兼容。
|
||
|
||
这是供 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 检查当前模型继承、触发规则和生命周期工具，
|
||
仅报告发现，不创建子任务、不修改设置。
|
||
```
|
||
|
||
技能单独安装时，仍需用户或适用指令授权委派。可选全局提示词现在明确提供普通开发、检索、诊断、审查和验证的持续并行授权；审查仍只读，用户禁止、仅审计并行配置及更高优先级宿主限制优先。模板文件只有被作为适用指令加载时才生效，放在仓库或压缩包里不改变当前会话权限。
|
||
|
||
有授权和独立工作时默认积极并行：尽早派发 Luna 收集、比对、验证、局部审查和已定方案修改，主线程继续关键路径。并发随真实槽位和验收能力扩展，不固定只开一两个；结果返回即验收并补充队列，不等整批结束。四个总槽位最多容纳主线程加三个子智能体，提示词不会突破宿主限制。
|
||
|
||
任务太小、存在立即依赖、共享所有权冲突或验收积压时缩小并行。单条命令优先直接用工具；复杂判断直接选 Sol/Astra，不让 Luna 重试堆数量。配置示例的数值不是并行策略上限，安装不自动修改运行配置。
|
||
|
||
## 模型策略
|
||
|
||
| 工作 | 起点 |
|
||
| --- | --- |
|
||
| 固定来源收集、枚举和检查 | GPT-6 Luna low，多步任务 medium |
|
||
| 有界转换、分类、已定方案补丁 | GPT-6 Luna medium，必要时 high |
|
||
| 常规实现、调试和跨文件调查 | GPT-6 Sol medium |
|
||
| 复杂分析、设计和关键语义证据 | GPT-6 Sol medium/high |
|
||
| 最困难的独立综合任务 | GPT-6 Astra medium/high |
|
||
| 共享决定、最终整合与验收 | 当前主线程 |
|
||
|
||
优先考虑 Luna 的四个条件：输入有界、合同已定、正确性易检查、失败影响可控。需要调查、设计取舍或跨文件因果推理时直接用 Sol；最困难的独立综合可直接用 Astra，不要求从便宜模型逐级尝试。主线程保持用户选择，负责判断与整合。
|
||
|
||
Terra 原先承担的常规开发、调试和调查统一交给 Sol。新版 Sol 的价格使单独维护 Terra 中间档的收益不足以支撑本技能继续推荐它；这是工程策略，仍需真实任务校准。缺少 GPT-6 的宿主可显式选用足够胜任的 GPT-5.6 Sol/Luna 或本地执行，不自动回退到 Terra，也不改写用户已有配置。
|
||
|
||
2026-09-23 核实的 API Standard 短上下文单价（美元/百万 token）：Luna 输入 0.10、输出 0.50；Sol 输入 2、输出 10；Astra 输入 10、输出 50。相同 token 用量与计费条件下，Luna 为 Sol 的 1/20，Sol 为 Astra 的 1/5。此比例不等于实际任务节省或 Codex 套餐消耗；核算须包含主线程、重试与验收。[价格来源及成本校准](skills/codex-subagent-router/references/model-economics.md)。低价不增加并行权限，也不意味着应开启更多子任务。
|
||
|
||
按实时工具 schema 检查模型、effort、fork、并发槽位和工作区。API 模型目录不证明当前子智能体支持。可选配置示例见 [运行时参考](skills/codex-subagent-router/references/platforms.md)，安装工具不会应用它。
|
||
|
||
新通用工程会话建议 GPT-6 Sol / medium，复杂推理按需 high，保留用户已选主模型。Astra 可前置处理影响多个后续任务的困难决策、跨系统证据及独立高影响反例，不必先失败。专家按问题、产物和退出条件设界；新增证据或可测试进展支持续轮，没有进展则暂停专题。
|
||
|
||
同类验收失败两次暂停切片并重新分类，严重反例立即处理；问题计数跨 agent 保留。证据统一基线后裁决，主线程必须理解并验证关键结论。证据 schema 1/2 与决策 schema 1 保持兼容，累计咨询次数不得倒退；示例见 [决策记录](examples/decisions/resolved.json)。
|
||
|
||
## GPT-6 工作方式适配
|
||
|
||
技能与全局提示词保留目标、权限、所有权与验收要求，减少固定步骤和重复规则。固定工作优先工具，子智能体承担已授权的独立判断；异步等待期间推进独立工作，用户纠偏后核对受影响任务和迟到结果，长任务压缩后恢复未完成状态。
|
||
|
||
GPT-6 新增的异步工具、执行中纠偏与动态推理强度都有 API 或宿主限制。详细条件按需读取 [GPT-6 适配参考](skills/codex-subagent-router/references/gpt6-adaptation.md)，不会因安装提示词就自动开启这些功能。计算机操作、结构化输出、程序化工具调用、缓存与压缩属于延续能力，不统一宣传为 GPT-6 新功能。
|
||
|
||
## 验证
|
||
|
||
```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 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 要求可能仍影响任务。需要时把这些规则纳入明确的联合迁移范围；不能由本技能假装旧门槛已经满足。
|
||
|
||
## 官方参考
|
||
|
||
- [OpenAI 模型目录](https://developers.openai.com/api/docs/models)
|
||
- [GPT-6 家族指南](https://developers.openai.com/api/docs/guides/latest-model)
|
||
- [GPT-6 Sol](https://developers.openai.com/api/docs/models/gpt-6-sol)
|
||
- [GPT-6 Luna](https://developers.openai.com/api/docs/models/gpt-6-luna)
|
||
- [API 价格](https://developers.openai.com/api/docs/pricing)
|
||
- [Codex 子智能体](https://learn.chatgpt.com/zh-Hans/docs/agent-configuration/subagents)
|
||
|
||
模型与价格依据核对日期：2026-09-23；原有宿主配置示例的核对日期见运行时参考。模型分工属于工程策略；宿主真实能力与实际任务证据优先。
|