引言：为什么编程 Agent 的 Token 成本越来越值得关注
当 AI 编程工具从“问答助手”变成能连续读代码、规划、修改、测试和复盘的编程 Agent 后，Token 成本就不再只是单次 API 调用价格的问题。长任务会反复携带系统提示、工具定义、项目规则、代码片段、历史对话和工具结果；如果上下文组织不当，模型不仅会消耗更多输入 Token，还可能被无关信息干扰，导致更多重试。
DeepSeek-Reasonix 的重构版值得关注，原因并不在于它“神奇地少发 Token”，而在于它把编程 Agent 的上下文组织问题放到了工程架构层面：尽量让稳定内容形成可复用前缀，让动态内容留在后缀，并通过项目记忆、文件引用、上下文压缩和会话分离降低无效上下文。
需要先说清楚一个边界：Reasonix 不应被理解成本地实现了模型 KV Cache。更准确的说法是，它是一个面向 DeepSeek 的终端编程 Agent / 编排层，围绕 DeepSeek 服务端 Context Cache 的 prefix cache 特性做缓存友好的上下文工程。
Reasonix 是什么：DeepSeek-native 的终端编程 Agent
根据项目公开资料和本次报告整理，DeepSeek-Reasonix 当前重构版更偏向一个 DeepSeek-native 的终端编程 Agent：它强调单一静态 Go binary、配置驱动、插件边界、OpenAI-compatible provider 形态，以及围绕 DeepSeek prefix cache 稳定性设计的长会话体验。
从工程视角看，Reasonix 的重点不是“让所有 Token 消失”，而是把长任务中高频复用的内容放到稳定位置，把真正会变化的任务输入、工具输出和临时代码片段放到后面。这样做的收益主要有两类：
- 缓存型省钱：输入内容仍然在请求中，但命中 provider 的 prompt/context cache 后，缓存命中部分可能以更低成本计费，并降低首 Token 延迟。
- 真实 Token 减少：通过文件引用、上下文裁剪、摘要、repo map、CodeGraph 或 lazy loading，让无关内容根本不进入 prompt。
这两类优化经常被混在一起讨论，但它们不是一回事。缓存命中更像“重复内容更便宜、更快”；真实 Token 减少才是“重复或无关内容不再发送”。
DeepSeek Context Cache 的核心机制
DeepSeek Context Caching 是服务端缓存能力。官方文档提供了 prompt_cache_hit_tokens 和 prompt_cache_miss_tokens 两个 usage 字段，用来观察本次输入中有多少 Token 命中缓存、有多少没有命中。换句话说，Agent 侧应把这两个字段视为一级观测指标，而不是只看总输入 Token。
这里最容易误解的是：缓存命中并不等于客户端没有发送 Token，也不等于模型不需要上下文。对于 API 调用者来说，请求仍然包含输入内容；区别在于 provider 端如果识别到重复前缀，就可以复用已处理过的上下文，从而降低部分输入计费和首 Token 延迟。
因此，Reasonix 这类 Agent 的关键设计目标不是“在本地保存模型内部 KV 张量”，而是尽量稳定请求前缀，减少前缀抖动。对编程 Agent 来说，常见的前缀抖动包括：把时间戳放进系统提示、每轮重排工具 schema、中途切换模型或 effort、频繁启停 MCP 插件、把临时工具输出插到稳定规则之前。
Reasonix 如何提高缓存命中
1. 稳定 Prompt 前缀 + 动态后缀
最核心的思路可以概括为一套 Prompt 拓扑：
[System / Provider 固定说明]
[Agent Profile / 配置派生说明]
[Tool Schema / 插件清单]
[Project Memory / AGENTS.md 或项目规则]
[Repo Map / Symbol Map 摘要]
[Long-term Summary]
[Recent Conversation]
[Current Task]
[Temporary Tool Results]越稳定、越大、越会跨多轮复用的内容，越应该靠前；越动态、越临时、越任务相关的内容，越应该靠后。这样做并不能保证每一次都命中缓存，因为 provider 缓存通常有 TTL、容量和路由条件，但从工程设计上看，这是提高 prefix cache 命中率的基本方向。
2. Planner / Executor 分离会话
Reasonix 的 Planner / Executor 分离不应被简单理解为“多模型协作更省钱”。真正有价值的点在于：规划、探索和执行阶段的上下文形态不同，如果混在同一个会话里，日志、失败路径、工具输出和模型切换都可能污染稳定前缀。
更合理的设计是：Planner 保持只读、少工具输出、偏长稳定会话；Executor 处理编辑、测试和 patch；Reviewer 只关注 diff、规则和验收条件。会话 key 可以从 provider、model、agent role、tool schema hash、project memory hash、项目分支等字段派生。这样即使某个阶段需要更多动态上下文，也不至于破坏所有角色的缓存形态。
3. 工具 schema 稳定和插件边界
编程 Agent 的工具定义通常会进入系统提示或工具层级。工具数量、顺序、描述和 JSON schema 的变化，都可能改变请求前缀。Reasonix 使用配置和插件边界来管理工具，给开发者一个很重要的启发：工具 schema 应该稳定、排序、版本化，而不是每轮动态拼装。
实践中可以维护一个 tool_schema_hash，将工具名称、版本、规范化后的 schema 一起计算。如果长任务中这个 hash 频繁变化，就应该追查是否存在 MCP server reload、插件启停、权限策略改写或工具描述随机化。
4. AGENTS.md / 项目记忆
项目记忆的价值在于把“每次都要告诉 Agent 的事实”沉淀成稳定、短小、可复用的上下文，例如构建命令、测试命令、目录结构、代码风格、安全约束和常见陷阱。
但项目记忆不是越长越好。如果把 README、开发手册、接口文档全文塞进 AGENTS.md 或类似文件，它会扩大稳定前缀，增加 miss 面积，也可能降低模型遵循度。更好的做法是：root memory 只保留每轮必须知道的规则；路径级规则按目录或文件类型懒加载；大型规范只放引用，任务需要时再读取。
5. @ 文件引用与文件大小控制
@path/to/file、@dir 或类似文件引用机制，是编程 Agent 真实减少 Token 的关键入口。它让上下文注入从“把整个仓库丢给模型”变成“按任务选择必要文件”。
这类机制还应该配合文件 size cap、目录噪音过滤和范围读取。比如默认跳过 .git、node_modules、构建产物和大日志；大文件只注入符号摘要或相关函数片段；编辑阶段再提供可 patch 的原始代码片段。
6. Compaction：减少长度，但也是缓存重建点
上下文压缩可以减少后续 prompt 长度，把老历史变成摘要。但它也会改变 conversation prefix，因此不应该被描述成“天然提高缓存命中”。更谨慎的说法是：Compaction 能减少真实输入长度和无效上下文，但会在压缩点之后形成新的前缀，需要重新建立缓存。
较好的触发时机包括：完成一个子任务、从探索转入实现、接近上下文窗口阈值、日志明显膨胀但关键信息可摘要、或准备进入 review 阶段。过早或过频繁 compact，可能让模型丢失细节，也可能让 cache miss 增加。
Reasonix 如何真正减少无效 Token
如果目标是“真实减少输入 Token”，仅靠 provider cache 不够。Reasonix 体现或适合借鉴的做法包括：
- Repo/Symbol Map：用文件树、符号、导入导出和调用关系摘要替代仓库全文。
- Context Router：根据当前任务、错误堆栈、git diff、用户提到的文件和依赖关系选择上下文。
- Lazy Loading：规则、文档和工具只在相关任务中加载，不在启动时全量注入。
- 失败路径清理：探索失败后优先 rewind 或摘要，而不是让大量失败日志继续污染后续请求。
- 阶段化上下文：分析阶段可以摘要，编辑阶段必须提供可修改代码原文，审核&查验阶段重点放 diff 和约束。
这也是本文最重要的区分：缓存命中主要降低重复输入的成本和延迟；真实 Token 减少要靠上下文治理、文件选择和摘要裁剪。
需要避免的几个误区
- 误区一：缓存命中等于不发送 Token。更准确地说，Token 仍在请求里，只是 provider 端可能以缓存读的方式处理重复前缀。
- 误区二：Reasonix 本地实现了模型 KV Cache。从公开资料和工程定位看，Reasonix 更像 Agent 编排层，不是 vLLM、SGLang 或 LMCache 这类推理层 KV Cache 系统。
- 误区三：Prompt 越短越好。编程任务需要足够上下文。过度裁剪代码片段可能降低修改正确率。
- 误区四：频繁 compact 一定省钱。Compaction 会减少长度，但也可能重建 conversation layer，适合放在自然阶段边界。
- 误区五：把整个仓库塞进上下文更保险。这会增加成本和噪音。更好的方式是 repo map + 相关文件切片 + 按需读取。
对编程 Agent 开发者的启发
把 Reasonix 抽象成工程方法论，可以得到几条可落地原则：
- 稳定内容放前面，动态内容放后面。
- 系统提示、工具 schema、项目记忆和 repo map 要有固定顺序。
- 不要在稳定前缀里放时间戳、随机 ID、临时路径和工具结果。
- 长任务中尽量不要频繁切模型、切 effort 或启停插件。
- Planner、Executor、Reviewer 等角色分离 session，避免互相污染。
- Compaction 放在阶段边界，压缩前保留关键约束、修改文件和失败路径。
- 成本评估看
cost_per_successful_task，而不是只看单次请求价格。
小结：从 Reasonix 走向通用 Token 优化方案
Reasonix 的价值，不在于把 Token 成本问题包装成某个神秘功能，而在于提示我们：编程 Agent 的成本优化本质上是上下文工程。稳定前缀、分离会话、工具 schema 稳定、项目记忆控长、文件引用、repo map、低频 compaction 和可观测账本，应该共同工作。
如果说 Reasonix 是一个具体案例，那么更通用的问题是：Codex、Claude Code、Cursor、OpenCode 这类编程 Agent 应该如何系统性地提高缓存命中率、减少 Token 浪费？我在 下一篇文章《编程 Agent 如何节省 Token 成本？一套适用于 Codex、Claude Code、Cursor、OpenCode 的通用方案》 中继续拆解一套通用方案。
评论