减少编码 Agent Token 消耗：优化工具输出是关键

我们在等你。你可以通过邮件收到 The New Stack 的每日精选内容，工作日不停歇，让你随时掌握行业动态。

检查你的收件箱，收到确认邮件后可以调整偏好设置，甚至加入其他订阅组。

在你喜欢的社交媒体平台上关注 The New Stack。

在 LinkedIn 上成为 The New Stack 的关注者。

在等待第一封 TNS 通讯时，看看有哪些精选和热门文章。

在 AI 编程 Agent 写出第一行代码之前，它就已经消耗了大量 token。比如源码文件、工单描述、构建日志、质量问题报告、依赖告警等。你支付的费用大部分并不在那个 Pull Request 上，而是在 Agent 为此阅读的所有内容上。

团队通常会把成本控制重点放在模型选择、提示词长度和请求限流上。这些都是有效的杠杆，但还有一个更隐蔽的因素藏在 Agent 与开发工具之间的接口层：返回给模型的数据格式。

"Token 成本不仅取决于编程 Agent 读取了什么，还取决于开发工具如何打包这些信息。"

当一个工具返回大量结构相似的记录时，发送冗长的 JSON 会让 Agent 反复为字段名、引号和结构语法付费。内容是有用的，但其中的大部分表示形式并非必需。对于 Agent 开发工作流来说，输出格式是一个工程决策，而非美观与否的问题。

这并不意味着所有集成都要抛弃 JSON。JSON 仍然是广泛支持的 interchange 格式，对于嵌套或不规则数据来说可能是更紧凑的选择。真正的问题更具体：当模型需要消费一个大型、uniform 的集合时，工具能否以针对该形状优化的表示形式返回相同的信息？

为什么数据结构会成为 token 账单的一部分

以问题列表为例。每条记录可能包含标识符、规则、严重程度、文件、行号、消息、状态和预估修复工作量。在传统 JSON 中，这些标签每条记录都会重复：

{
  "key": "AZ1002fQ9x",
  "severity": "BLOCKER",
  "component": "src/main/java/com/acme/UserRepo.java",
  "line": 29,
  "status": "OPEN"
}

这对于许多系统来说既可读又有用。但当 Agent 检查 25 条、100 条或 500 条问题时，并不需要数百次被告知 severity 或 component 的含义。重复这些标签消耗的是本可以容纳更多相关证据、指令或源代码的上下文。

TOON（Token-Oriented Object Notation）是一种解决这个问题的方案。它为 uniform 数组保留一个类 schema 的头部，然后每条记录作为一行发送。字段名只出现一次，而值保持完整。这是针对目标数据形状的 JSON 数据模型的无损编码。

"规律的结构让模型能够预期明确的字段集，这可以使审查和验证更加可预测。"

结果不仅仅是文本更小。规律的结构让模型能够预期明确的字段集，这可以使审查和验证更加可预测。Agent 收到的是相同的问题列表，但周围的重复脚手架更少。

用真实工作流衡量，而非空洞的承诺

有用的分析单位是团队实际的工具输出和实际的模型。字符数是很好的第一步信号，但不同模型的 token 化方式不同。不要假设一个通用的百分比，而是捕获一个有代表性的响应，用与工作流相关的 tokenizer 或格式化工具处理它，并与当前的默认格式比较。

例如，Sonar CLI 可以将问题列表以 JSON 或 TOON 格式返回：

# 默认 JSON 输出
sonar list issues -p my-org_my-app --severities BLOCKER,CRITICAL --format json > issues.json

# 用 TOON CLI 评估相同数据
npx @toon-format/cli issues.json --stats

# 直接向 Agent 返回紧凑的无损输出
sonar list issues -p my-org_my-app --severities BLOCKER,CRITICAL --format toon

第一条命令保留基准。第二条报告实际 payload 的节省。第三条仅在消费者是 Agent 时应用替代格式。

我自己测试时生成了一组有代表性的 25 条问题对比：TOON 比美化输出的 JSON 少用 49% 的字符，比压缩后的 JSON 少用 33%。TOON 项目发布的基准测试也报告了对于 uniform 表格数据集更低的 token 使用量，同时在其测试集上检索准确率相当。这些结果应被视为方向性证据，而非用团队所选模型测量生产 payload 的替代品。

选择适合读者的格式

一个持久有效的规则是根据消费者和数据形状选择格式：

当人需要在终端中扫描短结果时，使用表格。

当脚本、API 客户端或深层嵌套的 payload 从 JSON 的熟悉结构中受益时，使用标准 JSON。

当 LLM 读取具有相同字段的多条记录时，考虑使用紧凑的、schema-first 的表示形式（如 TOON）。

最后一种情况很重要，因为编程 Agent 越来越多地在循环中调用工具。Agent 可能会列出问题、检查受影响的文件、做修改、运行分析，然后列出剩余的问题。当相同的工作流跨仓库和迭代运行时，一次响应中适度的减少会产生复合效果。

"更便宜的上下文如果导致更弱的决策，那不是成本改进。"

尽管如此，紧凑性不是唯一的要求。格式必须保留 Agent 做正确决策所需的字段。它必须被工具链接受。而且应该针对重要的任务进行验证：识别最高优先级的问题、定位受影响的代码、确定修复是否完成。更便宜的上下文如果导致更弱的决策，那不是成本改进。

把工具响应视为 Agent 设计的一部分

更广泛的教训是，Agent 成本部分是一个上下文设计问题。团队可以通过几种互补的方式减少不必要的上下文：只检索相关文件、在适当的细节层级返回工具结果、避免重复传输结构开销。这些改动都不需要降低代码或安全问题的质量标准。

从 Agent 工作流中最高吞吐量的结构化调用开始。测量基准。更改一个格式设置。然后综合评估 token 消耗、响应质量和任务完成情况。

这个方法刻意保持谨慎。它避免了平台重写，并使权衡变得透明。随着 AI 辅助开发越来越成为工程工作的常规部分，对 Agent 看到什么以及如何看到它们的严格选择，将与它们使用的模型一样重要。