用更好的工具输出削减编码代理 Token 消耗：JSON 不总是答案

团队通常把 AI 编码成本的控制重心放在模型选择、提示词长度和请求限制上。这些杠杆都值得关注，但一个更隐蔽的消耗点藏在代理与开发工具之间的接口里：返回给模型的数据格式。「Token 成本不仅取决于编码代理读了什么，还取决于开发工具如何打包这些信息。」当工具返回一长串形状相似的记录时，发送冗长的 JSON 会让代理为字段名、引号和结构语法反复付费。内容是有用的，但大部分表示形式不是。对 agentic 开发工作流来说，输出格式是一个工程决策，而不是装饰问题。

1. 问题：重复的结构化开销

考虑一个 issue 列表。每条记录可能包含标识符、规则、严重级别、文件、行号、消息、状态和预估修复工作量。在传统 JSON 中，这些标签会在每条记录里重复出现：{"key": "AZ1002fQ9x", "severity": "BLOCKER", "component": "src/main/java/com/acme/UserRepo.java", "line": 29, "status": "OPEN"}。这对许多系统来说可读且有用。但一个代理要检查 25、100 甚至 500 条发现时，不需要被告知 severity 或 component 的含义几百次。重复这些标签消耗的上下文，本可以装下更多相关证据、指令或源代码。

// The problem: a long list of similarly shaped records
// in verbose JSON. Each finding repeats field names,
// quotation marks, and structural syntax the model has
// already seen 24 times before this one.
[
  { "key": "AZ1002fQ9x", "severity": "BLOCKER",
    "component": "src/main/java/com/acme/UserRepo.java",
    "line": 29, "status": "OPEN" },
  { "key": "AZ1002fQ9y", "severity": "CRITICAL",
    "component": "src/main/java/com/acme/AuthService.java",
    "line": 41, "status": "OPEN" }
  // ... 23 more records, repeating the same labels
]

2. TOON：Token 导向对象记法

Token-Oriented Object Notation（TOON）是解决这个问题的一种思路。它为统一数组保留一个 schema 风格的头，然后把每条记录作为一行发送。字段名只出现一次，值保持完整。对于它针对的数据形状，它是 JSON 数据模型的无损编码。「规则的结构给模型一组明确的字段去预期，这会让审查和验证更可预测。」结果不只是更小的文本：代理收到同样的发现，但周围重复的脚手架更少。

// Token-Oriented Object Notation (TOON): a schema-like
// header once, then each record as a row. Lossless for
// uniform arrays, dramatically less scaffolding.
#schema
key,severity,component,line,status
AZ1002fQ9x,BLOCKER,src/main/java/com/acme/UserRepo.java,29,OPEN
AZ1002fQ9y,CRITICAL,src/main/java/com/acme/AuthService.java,41,OPEN
// The agent gets the SAME findings with less repeated
// structure around them. Field names appear once, values
// stay intact, and validation becomes more predictable.

3. 真实数字：49% 和 33%

作者用 25 条 issue 的代表性样本做过对比：TOON 比美化后的 JSON 少 49% 字符，比压缩后的 JSON 少 33%。TOON 项目公开的基准也报告了统一表格数据的更低 token 用量，同时测试集上的检索精度相当。但这些结果应视为方向性证据，而不是替代方案：分析单位是团队实际的工具输出和实际模型。字符数是有用的第一信号，但不同模型的 tokenization 不同。正确做法是抓取代表性响应，用相关工作流相关的 tokenizer 跑一遍，再与当前默认格式比较。

// Real-world CLI comparison from the article: the Sonar
// CLI can return an issue list as JSON or TOON. The
// first command preserves a baseline, the second reports
// savings for the actual payload, the third applies the
// compact format only where the consumer is an agent.
# 1. Default JSON output (baseline)
sonar list issues -p my-org_my-app --severities BLOCKER,CRITICAL --format json > issues.json

# 2. Evaluate the same data with the TOON CLI
npx @toon-format/cli issues.json --stats

# 3. Return compact, lossless output directly to an agent
sonar list issues -p my-org_my-app --severities BLOCKER,CRITICAL --format toon

4. 在循环调用中复利

最后一种情况很关键，因为编码代理越来越多地在循环中调用工具。代理可能列出发现、检查受影响文件、做出修改、再分析、再列出剩余发现。一次响应的适度缩减，会在同一工作流跨仓库、跨迭代运行时不断复利。但紧凑不是唯一要求：格式必须保留代理做出正确决策所需的字段，必须被工具链接受，还应该针对关键任务验证——识别最高优先级发现、定位受影响代码、判断修复是否完成。更便宜的上下文如果导致更弱的决策，就不是成本改进。

5. 代码实战：格式、测量与规则

本文的代码块把模式拆开：代码块一是问题本身——一长串形状相似记录的冗长 JSON；代码块二是 TOON 格式——schema 头加逐行记录；代码块三是 Sonar CLI 的真实对比命令——保留基线、报告实际节省、只对代理消费者应用紧凑格式；代码块四是测量脚本——用你自己的 tokenizer 对比两种格式，而不是假设一个通用百分比；代码块五是选择规则——按消费者和数据形状决定格式，并记住循环调用中的复利效应。

// Measure, don't assume. Character counts are a first
// signal, but tokenization differs across models. Capture
// a representative response and run it through the
// tokenizer relevant to YOUR workflow.
async function compareFormats(payload, tokenizer) {
  const json = JSON.stringify(payload);
  const toon = toToon(payload);            // header + rows
  const jTokens = tokenizer.count(json);
  const tTokens = tokenizer.count(toon);
  return {
    jsonChars: json.length,
    toonChars: toon.length,
    jsonTokens: jTokens,
    toonTokens: tTokens,
    savingsPct: Math.round((1 - tTokens / jTokens) * 100),
  };
}
// Published TOON benchmarks report lower token usage for
// uniform tabular datasets with comparable retrieval
// accuracy -- treat them as directional evidence, then
// measure your own production payload.

6. 更广的教训：代理成本是上下文设计问题

代理成本在一定程度上是上下文设计问题。团队可以通过几种互补方式减少不必要的上下文：只检索相关文件、以合适的详细程度返回工具结果、避免反复传输结构开销。这些改变都不需要降低代码或安全发现的质量门槛。从 agent 工作流中最高频的结构化调用开始，测量基线，改变一个格式设置，然后一起评估 token 消耗、响应质量和任务完成度。这个方法刻意保持适度：避免平台重写，让权衡可见。随着 AI 辅助开发越来越成为工程日常，关于代理看到什么、如何看到的纪律性选择，将和模型本身一样重要。

// The durable rule: choose the format by consumer and
// data shape. JSON stays the right choice for nested or
// irregular data; TOON wins for large uniform collections.
const FORMAT_RULE = {
  "nested_or_irregular": "json",          // keep JSON
  "large_uniform_array": "toon",          // header + rows
  "human_reading": "pretty-json",         // readability
  "agent_consuming_loop": "toon",         // compounds across
};                                        // iterations
// Coding agents call tools in loops: list findings,
// inspect files, make a change, list remaining findings.
// A modest reduction in one response compounds when the
// same workflow runs across repositories and iterations.
// But: a cheaper context that causes a weaker decision is
// not a cost improvement -- preserve the fields the agent
// needs, validate against real tasks, then ship.