codex-quota-optimizer

Codex 配额优化器

优化目标是单位 Codex 配额所完成的有效工作量，而不是答案最短。

0. 操作原则

使用能满足验收标准的最低成本执行路径。只有证据表明较低成本的路径无法满足要求时，才升级。

除非当前 Codex 客户端或账户能显示确切剩余配额，否则绝不要声称知道确切剩余配额。如果配额状态很重要，请告知用户查看 /status 或使用情况仪表板，然后继续采用现有条件下的最佳策略。

零摩擦不变量

优化器不得成为额外负担。

• 不要仅为任务分类或预算再发起一次模型调用。
• 不要为 CQO 分类、记录日志或审计添加网络请求。
• 不要在常规 Codex 执行前设置阻塞式预算门槛。
• 不要仅因超过软性预算就要求用户确认。
• 不要代替 CQO 启动子 Agent。
• 即使从未安装或运行可选的 cqo CLI，Skill 仍必须完全实用。

参见 references/zero-friction.md。

1. 只读取所需内容

在广泛探索之前：

1. 检查任务请求、当前差异和仓库说明（AGENTS.md）。
2. 优先使用定向搜索（rg、针对具体文件的读取、清单、已更改文件），而不是递归读取。
3. 如果不熟悉该仓库，请先运行一次 scripts/repo_snapshot.py --compact，再打开大量文件。
4. 除非出现矛盾，否则不要在当前任务中重新读取已理解且未更改的文件。
5. 仅在与任务直接相关时，才读取生成文件、供应商文件或构建目录。

详细规则请参见 references/context-policy.md。

2. 执行前对任务分类

在现有推理轮次中进行内部分类。不要仅为分类而调用另一个模型。

• XS — 单文件、机械式操作，验收标准明确。
• S — 范围较小的功能或修复，涉及 1–3 个文件，已有已知模式。
• M — 涉及多个文件，需要适度的设计判断或集成工作。
• L — 跨领域改动、架构不明确、迁移或复杂调试。
• XL — 高风险重设计、多系统工作、与安全密切相关，或端到端任务不明确。

然后选择满足要求的最低等级模型或推理路径：

• **XS/S：**优先选择 Luna 或最快、成本最低的可用设置，使用低推理强度。
• **M：**优先选择 Terra，使用低或中等推理强度。
• **L：**先使用中等推理强度的 Terra；仅在设计或调试复杂性仍未解决时才升级到 Sol。
• **XL：**使用中等或高推理强度的 Sol；仅当任务确实需要最强的多步骤或工具推理能力，且账户提供该能力时，才使用 Astra。

可用性因套餐或客户端而异。如果指定模型不可用，请选择承担相同角色、成本更低或速度更快的最接近模型。

默认情况下不要使用 Max/Ultra。不要仅仅因为可以启动子 Agent 就启动它们。

参见 references/model-routing.md。

3. 使用执行预算

对于所有非简单任务，都在内部维持以下预算：

• **探索预算：**足以通过读取和搜索定位改动范围。
• **编辑预算：**满足验收标准所需的最少文件数。
• **验证预算：**优先进行有针对性的检查；仅在最终关卡或证据需要时进行全面检查。

这些都是软性预算，绝不能成为执行门槛：

• 理解相关依赖路径后，就停止探索。
• 满足验收标准后，就停止编辑；避免顺手重构。
• 相关测试、类型检查或 lint 检查通过后，就停止验证，除非改动风险较高。
• 如果正确性需要检查其他文件、测试或推理步骤，就继续进行，不要打断用户。
• 如果任务范围扩大，请在内部重新分类并继续推进；不要仅因初始预算不足而请求许可。

4. 经济地规划

对于 S/M/L/XL 任务，请说明或维护一份精简计划，包含：

1. 目标行为，
2. 可能涉及的文件，
3. 最小化验证，
4. 升级触发条件。

阅读最少量的仓库证据之前，不要制定冗长且推测性的计划。

优先一次完成连贯的实现，避免反复进行每次都要重新加载上下文的微小操作。

5. 尽量少改

• 只修改最小且连贯的范围。
• 复用现有辅助函数、模式、组件和测试。
• 避免格式化无关文件。
• 除非确有需要，否则不要升级依赖。
• 除非任务本身需要生成文件，否则避免产生生成文件变更。
• 将逻辑相关的编辑合并处理，避免反复打开和编辑同一文件。

如果可以通过配置或小范围本地补丁解决问题，就不要引入框架或抽象层。

6. 分层验证

按以下顺序运行检查：

1. 对已修改文件进行语法／格式检查，
2. 对已修改行为进行针对性的单元／组件测试，
3. 针对性的类型／lint 检查，
4. 仅在必要时运行范围更广的软件包／应用测试，
5. 仅在涉及多个模块／高风险变更，或发布前检查时运行完整测试套件。

参见 references/test-policy.md。

对于微小修改，不要反复运行同一项耗时的完整测试套件。如果广泛测试因无关的既有问题而失败，请记录下来，并继续进行针对性验证。

7. 控制上下文增长

在自然的检查点，将工作状态压缩成简短的交接说明，包含：

• 目标，
• 决策，
• 已修改文件，
• 已运行的测试／结果，
• 尚未解决的问题。

使用检查点内容，而不是重述整个对话或仓库历史。

对于长任务，仅在能避免重复探索时才创建／更新简短的本地临时记录。除非项目希望提交该记录，否则在最终完成前将其删除。

8. 避免耗费资源的反模式

默认情况下，绝不要：

• 在定向搜索即可找到功能时扫描整个仓库，
• 无需时打开大型锁文件、压缩包、生成产物或供应商目录，
• 尚未确定变更范围就运行完整测试套件，
• 对常规编辑使用 high/xhigh/max/ultra 推理，
• 对单个 Agent 可低成本完成的任务使用多个子 Agent，
• 在补丁足以解决问题时要求 Codex 重写整个文件，
• 反复总结当前上下文中已有的信息，
• 为了顺手处理而在附近代码中进行重构，却无法给用户带来价值，
• 仓库／本地文档已经足够时浏览网页，
• 使用含义相同的查询重复搜索。

参见 references/anti-patterns.md。

9. 有计划地升级

仅在至少满足以下一项条件时，才升级模型／推理／工具范围：

• 两次针对性尝试均失败，且本地证据无法解释原因，
• 架构存在歧义，错误选择会导致大范围返工，
• 故障涉及多个子系统，
• 存在显著的安全／数据丢失／迁移风险，
• 验收标准彼此冲突，
• 针对性验证发现了隐性耦合。

升级前，请总结已知情况，避免更强的模型重新探索一遍。

10. Plus 与 Pro 的行为差异

不要将套餐配额硬编码到决策中。两种套餐采用相同的效率策略，但默认激进程度不同：

• **Plus：**默认采用 economy 行为——优先使用 Luna/Terra，进行针对性检查，严格控制范围。
• **Pro：**默认采用 balanced 行为——优先使用 Terra，在复杂度足以支撑时使用 Sol；仍应避免浪费，因为 Pro 配额有限，且可能与其他 Agent 功能共享。

如果用户表示配额即将耗尽，则进入紧急模式：

• 不进行广泛探索，
• 不做可选重构，
• 不使用子 Agent，
• 使用满足需求的最低成本模型，
• 仅采用一条实现路径，
• 只进行针对性验证，
• 如果当前轮次无法完成，则提供简短的后续处理说明。

11. 面向用户的输出

适用时，可在结尾添加简短的 使用建议，仅包含可执行的事项，例如：

• “这是一个 S 级任务；Luna/low 就够了。”
• “实现时使用 Terra/medium；将 Sol 留给迁移边界情况。”
• “现在运行针对性测试；完整测试套件留到最终审查时再运行。”

如果技能在后台正常运行，不要在每条回复中都加入配额说明。

12. 可选的本地可观测性

cqo CLI 是可选的。它提供任务级分类、软预算、本地日志和本地审计：

• cqo start <task>
• cqo status
• cqo audit
• cqo history

日志仅保存在本地的 ~/.cqo 下（或 CQO_HOME 中）。它不会检查私人账户页面，也不会估算隐藏配额。

切勿仅为收集分析数据而自动运行 cqo。 该 CLI 是检查层，而非运行时依赖。如果用户未选择加入 CQO 会话，则正常的技能行为不变，不会产生任何 CLI 开销。

13. 可选的辅助脚本

• scripts/repo_snapshot.py --compact — 生成精简的项目概览，无需读取整个代码库。
• scripts/change_scope.py — 总结当前 Git 变更范围，并建议验证范围。
• scripts/cqo.py — 可选的零网络本地 CLI，用于任务级预算管理和审计。

仅在脚本能节省模型上下文／工具调用，或用户明确要求可观测性时使用；不要为了走流程而运行。