上一篇文章中，我们以 DeepSeek-Reasonix 重构版 为例，分析了一个编程 Agent 如何围绕 DeepSeek Context Cache 做上下文工程。本文继续把这个思路抽象成一套适用于主流编程 Agent 的通用 Token 优化方案。
引言：AI 编程工具的真正成本不是模型单价，而是任务完成成本
讨论 AI 编程工具成本时，很多人第一反应是比较模型单价。但在真实开发任务里，更关键的指标通常不是“单次请求多少钱”，而是“完成一个可接受 patch 要花多少钱”。一个看起来便宜的模型，如果需要更多重试、更长上下文和更多人工修正，端到端成本可能并不低。
因此，编程 Agent 的 Token 优化应该从单轮请求优化升级为任务级成本治理。核心目标包括：提高稳定前缀的缓存命中率，减少 cache miss tokens，避免把无关仓库内容塞进 prompt，控制工具输出膨胀，并用指标衡量每个成功任务的真实成本。
编程 Agent 为什么容易浪费 Token
编程 Agent 的上下文比普通聊天复杂得多。一次任务可能同时携带系统提示、工具 schema、项目规则、repo map、用户需求、历史对话、文件内容、diff、测试日志、错误堆栈和外部文档。Token 浪费通常来自以下几类问题：
- 稳定内容不稳定：系统提示、工具 schema、规则文件顺序每轮变化，导致 prefix cache 难以命中。
- 动态内容放太前：时间戳、trace id、临时日志、当前任务被插到系统提示或项目规则之前。
- 仓库上下文过量：为了“保险”读取太多文件，甚至把大目录全文注入模型。
- 工具输出失控：测试日志、构建输出和 grep 结果反复进入历史，形成无效膨胀。
- 会话边界不清：规划、执行、调试、审核&查验混在同一个会话里，失败路径长期污染上下文。
解决这些问题不能只靠“压缩 prompt”。更合适的方向是建立一层上下文与成本治理层，也就是本文提出的 Agent Token Gateway。
主流平台的缓存机制差异
| 平台 / Agent | 可借鉴机制 | 注意点 |
|---|---|---|
| DeepSeek / Reasonix | 围绕 Context Cache、稳定前缀、分会话、低频 compaction 设计 | 不要误解成本地 KV Cache；仍要区分缓存命中和真实 Token 减少 |
| OpenAI API / Codex 类 Agent | 自动 Prompt Caching、静态内容前置、prompt_cache_key | cache key 粒度要稳定，避免把当前任务或随机值放入 key |
| Anthropic / Claude | Prompt caching、cache_control、tools/system/messages 层级 | cache breakpoint 应放在稳定 block 末尾，不应落在动态内容上 |
| Claude Code | CLAUDE.md、项目记忆、prompt cache 失效规则、/compact 与 /rewind | 切模型、改 effort、MCP 或 plugin 变化都可能造成缓存重建 |
| OpenCode | Build / Plan / Explore / Scout 多 Agent、AGENTS.md、rules lazy loading、compaction | 规则文件过多或全量加载会放大上下文 |
| Aider | Repo Map、prompt cache-friendly message ordering、只添加必要文件 | Repo map 应控制预算和相关性，不能替代关键代码原文 |
| Cursor 类 IDE Agent | 规则文件、项目索引、当前文件 / selection / diff 工作流 | 内部缓存不可见，适合在外部做上下文和成本观测 |
| Gemini | implicit / explicit context caching、cachedContent、TTL | cached content 仍要纳入上下文窗口和预算治理 |
一套通用 Prompt 拓扑
无论底层使用 DeepSeek、OpenAI、Anthropic 还是 Gemini，编程 Agent 都可以先把 prompt 拆成稳定 block 和动态 block。推荐拓扑如下：
[System]
[Agent Profile]
[Tool Schema]
[Project Memory]
[Repo Map]
[Long-term Summary]
[Recent Conversation]
[Current Task]
[Temporary Tool Results]这套顺序的关键是：静态内容优先，动态内容靠后；大而稳定的内容尽量保持 byte-stable；临时工具结果、日志和当前任务不要插入稳定前缀。对于支持显式缓存边界的 provider，可以在稳定 block 末尾设置缓存控制；对于自动 prefix cache，则至少要保证前缀内容和顺序不抖动。
Agent Token Gateway 架构
Agent Token Gateway 可以理解为位于 Coding Agent 和 LLM Provider 之间的一层上下文治理与成本账本。它不替代 Agent 的产品体验，也不替代模型能力，而是统一处理 prompt 拓扑、provider 缓存适配、项目记忆、工具 schema、repo map、上下文预算、压缩时机和 telemetry。
Coding Agent / IDE / CLI
→ Agent Token Gateway
→ Prompt Canonicalizer
→ Context Router
→ Repo Map / Symbol Map
→ Project Memory Loader
→ Tool Schema Registry
→ Provider Cache Adapter
→ Session Manager
→ Compaction Manager
→ Budget Governor
→ Telemetry / Cost Ledger
→ LLM Provider关键模块设计
1. Prompt Canonicalizer：固定 block 顺序
Canonicalizer 负责把不同 Agent 拼出来的上下文标准化。工具 schema 按名称和版本排序；项目规则按层级加载；动态内容放末尾；不在稳定前缀中插入时间戳、随机 ID 或临时路径。它还应输出 stable_prefix_hash，帮助判断为什么本轮 cache miss。
2. Context Router：只加载任务相关代码
Context Router 决定本轮应该读哪些文件、哪些片段和哪些日志。输入信号可以包括用户提到的文件、当前 selection、git diff、测试失败堆栈、import/call graph 邻近文件、最近修改文件和 path-scoped rules。它的目标不是让上下文最短，而是让上下文足够精确。
3. Repo Map / Symbol Map：用结构摘要替代全仓库输入
借鉴 Aider Repo Map 和 Reasonix CodeGraph 的思路，Gateway 应维护本地结构索引：文件树摘要、类和函数签名、导入导出关系、调用关系、公共 API 面、测试关联文件、生成文件过滤规则等。模型先看到结构摘要，再按需读取关键代码片段。
4. Project Memory Loader：统一 AGENTS.md、CLAUDE.md 和 Cursor rules
项目记忆可以统一兼容 AGENTS.md、CLAUDE.md、.cursorrules、.cursor/rules/*.md、.claude/rules/*.md 和 opencode.json instructions。建议分成 root memory、path memory、task memory、skill memory 和 cold memory。root memory 应短而稳定，路径级规则只在处理匹配文件时加载。
5. Tool Schema Registry：工具 schema 稳定和版本化
工具 schema 是缓存命中率的高风险变量。Registry 应规范化 JSON schema、固定排序、记录版本，并输出 tool_schema_hash。同一任务中尽量不要频繁启停 MCP server，也不要把所有工具全量加载给所有角色。Plan / Explore 角色可以只拥有只读工具，Executor 才加载写工具。
6. Provider Cache Adapter：适配不同厂商缓存机制
不同 provider 的缓存语义不同。DeepSeek 侧重点是 Context Cache usage 字段；OpenAI API 可使用自动 Prompt Caching 和 prompt_cache_key；Anthropic API 支持显式 cache breakpoint；Gemini 可以使用 explicit cachedContent。Gateway 应提供统一接口：构建请求、提取 usage、计算 stable prefix hash、解释 cache invalidation。
7. Session Manager：Planner / Executor / Reviewer 分离
会话分离可以降低上下文污染。Planner 负责只读探索，Executor 负责编辑和测试，Reviewer 负责 diff 审核&查验，Debugger 负责长日志与失败路径。不同角色可以使用不同工具权限和缓存策略，但不应在同一长历史里反复切换模型、effort 和工具集合。
8. Compaction Manager：控制压缩时机
Compaction 应在自然阶段边界发生，而不是一接近阈值就机械触发。摘要需要保留用户目标、已确认约束、修改文件、关键设计决策、失败路径、待验证事项和可恢复引用。对代码编辑任务，摘要不能替代可 patch 的原始代码片段。
9. Budget Governor：按任务控制成本
预算不应只限制单次请求，而要按任务类型设置。例如 bugfix 可以限制最大请求数、最大 input tokens、最大 cache miss tokens、最大 output tokens、最大工具调用数和最大成本。接近预算时，优先压缩工具输出、缩小检索范围、切换只读 subagent 定位，或在阶段边界 compact。
10. Telemetry / Cost Ledger：让成本可观测
没有 telemetry，Token 优化只能靠感觉。每次请求至少应记录 provider、model、agent role、input_tokens、cache_hit_tokens、cache_miss_tokens、output_tokens、stable_prefix_hash、tool_schema_hash、project_memory_hash、compaction_count、latency、TTFT 和 cost。
成本观测与 Benchmark 指标
建议把以下指标纳入 dashboard：
cache_hit_token_ratio：缓存命中 Token 占比。cache_miss_tokens：本轮需要重新处理的输入规模。input_tokens/output_tokens：输入和输出总量。tool_schema_hash：工具定义是否变化。stable_prefix_hash：稳定前缀是否变化。compaction_count：一次任务中压缩发生次数。cost_per_successful_task：每个成功任务的真实成本。accepted_patch_rate：生成 patch 被接受的比例。
Benchmark 不应只比较单轮 latency。更合理的对照组包括：原始 Agent、仅依赖 provider 自动缓存、加入稳定 prompt topology、加入 repo/symbol map、加入会话分离、加入 budget governor 和 telemetry、再加入 provider-specific cache adapter。
面向不同 Agent 的落地建议
Codex / OpenAI API
固定 system、tools、project memory 的顺序；把动态任务内容放末尾；对共享长前缀的任务使用稳定的 prompt_cache_key；不要把当前用户请求、时间戳或随机 trace id 放进 cache key。
Claude Code / Claude API
任务开始前确定 model 和 effort；让 CLAUDE.md 保持短、具体、结构化；MCP/plugin 状态尽量在 session 开始前稳定；/compact 放在自然断点；显式 API 场景把 cache breakpoint 放在最后一个稳定 block 上。
OpenCode
利用 Plan、Build、Explore、Scout 的角色分工减少上下文污染；保持 AGENTS.md 简洁；外部规则通过 instructions、skills 或 @ 引用按需加载；为高成本 Agent 配置 max steps。
Aider
使用 Repo Map 保留仓库级结构感，但不要把所有文件都加入 chat；编辑阶段只添加真正需要修改的文件；read-only 文件和 repo map 可以保持在更稳定的位置，减少重复上下文成本。
Cursor 类 IDE Agent
由于内部缓存不可见，更适合做外部治理：规则文件模块化，以当前文件、selection、diff 和错误堆栈为 primary context；通过本地 symbol map 控制上下文；记录每次任务的文件选择、上下文大小和成功率。
Gemini
对大而稳定的资料、文档或仓库摘要，可以考虑 explicit context caching；短期多轮任务则保持共同内容靠前，提高 implicit cache 命中概率。需要注意 cached content 仍要纳入窗口、TTL 和成本策略。
MVP / Pro / Enterprise 三阶段落地路线
| 阶段 | 目标 | 核心能力 |
|---|---|---|
| MVP | 先让成本可见、prompt 稳定 | 规则统一、固定 Prompt block、简单 repo map、文件 size cap、成本日志、stable_prefix_hash |
| Pro | 多 Provider 缓存适配和智能上下文路由 | Provider Cache Adapter、Tool Schema Registry、Session Manager、Compaction Manager、rules lint |
| Enterprise | 团队级成本治理和审计 | 团队策略、CI 规则检查、成本审计、MCP 工具治理、多项目缓存治理、Benchmark CI |
小结：Token 优化本质是上下文工程
编程 Agent 的 Token 成本优化，不是简单把 prompt 压短，也不是盲目依赖某个 provider 的缓存折扣。更可靠的方向是上下文工程：把稳定内容稳定化，把动态内容后置，把仓库知识结构化，把项目规则分层，把工具 schema 版本化，把 compaction 放在正确时机，并把 cache hit、cache miss、成本和成功率一起纳入观测。
从 Reasonix 到 Claude Code、Codex、OpenCode、Aider、Cursor 和 Gemini，平台差异确实存在，但通用原则相同：不要让无关信息进入模型，不要让稳定前缀无意义抖动，不要只看单轮价格，要看每个成功任务的真实成本。
评论