ai-agent-cost-optimizer

AI Agent 成本优化器

在不降低交付质量的前提下降低 AI Agent 开支。优化每项正确完成任务的成本，而非原始令牌数。

何时启用

• AI 编码账单、令牌用量、API 推理成本或模型开支过高
• 检查 Agent 工作流中的上下文浪费、重试循环或缓存未命中
• 为规划、实现、审查或清理任务选择模型等级
• 评估有关提示词缓存、低成本模型或令牌节省的说法
• 记录重复工作流，避免未来的 Agent 重新探索相同上下文

核心原则

根据失败成本选择模型和上下文。

如果错误答案可能导致高昂的返工、安全风险、数据丢失或架构负担，就使用能力更强的模型。如果任务范围明确、可逆、有测试覆盖或属于机械性操作，就使用更便宜的模型和更小的上下文。

不要为了节省令牌而增加重试、掩盖重要证据或降低代码质量。

成本审计工作流

1. 明确支出构成

在提出改进建议前，先找出实际的成本驱动因素：

• API 支出与订阅支出
• 正在使用的提供商和模型
• 运行最频繁的工作流
• 可获取时，平均输入、输出、缓存输入、推理和工具调用令牌数
• 重试次数、失败运行次数和人工纠正时间
• 成本来自少数大型工作流，还是许多小型调用

如果无法获取用量数据，请标记为未知；只有在能够访问时，才检查本地配置、日志、脚本或提供商仪表板。

2. 区分已核实的事实与说法

价格、模型可用性、缓存行为和基准排名都可能随时间变化。引用具体价格或建议将某个模型设为默认模型之前，请核实提供商的最新文档。

将社交帖子、基准测试截图和供应商营销内容视为假设。在更改默认路由之前，先将其转化为本地测试。

3. 找出令牌浪费

留意以下常见浪费模式：

• 尚未明确任务范围，就加载大型文件或目录
• “以防万一”而包含文件
• 已提取有用信息后，仍保留原始日志、构建输出、搜索结果或测试输出
• 每次重试都重新发送相同上下文的工具循环
• 可缓存的重复工具定义或提供商指令
• 本可通过简洁摘要保留足够状态，却仍继续冗长对话
• 用高级模型处理格式整理、重命名、Lint 修复、提取或样板代码
• 针对相同前缀，将许多小问题拆成单独调用
• 反复探索环境，而这些信息本应记录为技能、参考资料或脚本

4. 切换模型前先精简上下文

先优化上下文结构：

• 在打开文件前搜索符号、路径和错误
• 只读取足以回答问题的最小相关片段
• 将稳定规则、架构和工作流指令保存在持久化技能或参考资料中
• 工具输出完成用途后进行摘要
• 阶段切换后丢弃过时上下文
• 对共享相同上下文的只读探索进行批处理
• 对关键调试、安全、计费或数据丢失场景保留精确证据

5. 提高缓存命中概率

设计稳定前缀：

• 将稳定指令、工具定义、架构和示例放在可变任务数据之前
• 不要将时间戳、会话 ID、用户特定详情和检索到的片段放入可复用前缀
• 避免在不同调用间改写稳定指令
• 如果提供商响应中包含缓存读写用量，请进行监控
• 在假定缓存有效之前，先检查提供商特定的阈值、TTL 和失效规则

不要笼统地认为流式传输会破坏缓存。缓存未命中通常源于前缀不稳定、提供商或模型不受支持、阈值、TTL 过期，或工具／消息结构发生变化。

6. 根据任务风险路由

将此评估标准作为起点：

任务	默认层级	提升层级的条件
架构、安全关键审查、不可逆操作、影响范围大的重构	高级	已是高级层级；增加审查或测试
功能实现、调试、编写测试、常规重构	主力	反复失败、测试薄弱或存在隐藏的架构风险
Lint、格式化、重命名、简单提取、样板代码、分类	实用或本地	输出需要细致判断，或会影响生产行为
长时间的 Agent 循环	严格限制上下文预算的主力	循环遇到不明确的设计决策或持续失败
探索未知代码库	初步梳理使用主力或高级层级，之后将范围明确的后续工作交给更低成本的层级	架构不明确或风险较高

以本地评估为准，不要盲信泛泛的排行榜结论。较便宜的模型如果导致重试次数翻倍，成本可能反而高于高级模型。

7. 有计划地批处理和拆分任务

如果几个相关的小问题共享上下文，就将它们合并到一次调用中。如果每个子任务都能在隔离的上下文中运行并返回简洁结果，就将较大的任务拆分为独立子任务。

不要只是为了并行处理琐碎工作而额外启动 Agent。除非上下文隔离或节省时间足以证明额外开销合理，否则多 Agent 系统可能会增加 Token 消耗。

8. 固化重复工作流

当工作流反复使用且稳定时，将其固化下来，避免 Agent 一再重新探索：

• 为多步骤的流程性知识编写有针对性的技能
• 将冗长的背景材料移至仅在需要时加载的参考资料
• 为脆弱或重复的转换编写确定性脚本
• 将环境信息记录在仓库记忆或项目文档中，并注明验证日期

固化最终可用的工作流，而不是发现它时的探索过程。

9. 衡量结果

使用任务级指标比较优化前后的表现：

• 每个已完成任务的成本
• 输入、输出、缓存输入和工具调用 Token 数
• 缓存命中率
• 重试次数
• 耗时
• 测试通过率或审查缺陷率
• 人工修正时间

以实际测得的范围报告节省情况。除非已知优化前后的基准数据，否则避免声称“减少 80%”等缺乏依据的结论。

输出格式

审计工作流时，请按以下格式返回：

1. 主要成本漏洞 - 按可能产生的支出影响排序
2. 低风险修复 - 降低成本且不影响质量的改动
3. 路由变更 - 模型层级变更及提升层级的条件
4. 缓存计划 - 稳定前缀、可变后缀，以及需要关注的指标
5. 固化候选项 - 值得转化为技能、参考资料或脚本的工作流
6. 未经验证的说法 - 需要通过当前来源核实的定价或模型质量说法

防护原则

• 未核实当前定价且缺乏本地质量证据时，不要推荐特定提供商或模型作为默认选择
• 不要移除正确性、安全性、合规性或可审计性所需的上下文
• 如果机械地减少 Token 数会增加重试或审查负担，就不要这样优化
• 不要把提示词缓存当作万能方案；应通过用量数据验证缓存命中情况
• 不要将易变的价格表写入长期使用的技能内容
• 不要使用违反仓库既定工作流的编辑捷径

集成

相关技能：

• context-optimization（references/fundamentals.md）- 了解哪些内容会消耗上下文
• context-optimization - 应用压缩、遮蔽、缓存和拆分
• multi-agent-patterns - 评估子 Agent 上下文隔离是否值得其开销
• tool-design - 减少工具歧义和响应冗长问题
• skill-capture - 将重复工作流保存为可复用技能