英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

面向令牌的对象表示法（TOON）

面向令牌的对象表示法是一种紧凑、可人类阅读的 JSON 数据模型编码方式，它能够最小化令牌数量，并使结构易于模型理解。

TOON 将 YAML 基于缩进的嵌套对象结构与类似 CSV 的表格形式结合起来，用于统一数据。它的最佳应用场景是统一对象——无论在数组中还是通过 ID 键控——各项字段相同，从而达到类似 CSV 的紧凑性，同时增加了显式结构，帮助大语言模型可靠地解析和验证数据。对于深度嵌套或非统一的数据，JSON 可能更高效。

可以将其视为一个翻译层：以编程方式使用 JSON，并将其编码为 TOON 以供 LLM 输入——这是对你已有 JSON 的无损替代表示。

[!提示]
TOON 格式是稳定的，但同时也是一个正在发展的概念。没有任何事情是固定不变的——你可以通过贡献到 规范 或分享反馈来影响其发展方向。

为什么选择 TOON？

大语言模型的令牌是需要付费的——而 JSON 在结构上消耗了大量令牌。用 TOON 表示的天气预报示例：

location:
  city: Berlin
  country: DE
  units: metric
alerts[2]: frost,wind
forecast[3]{day,temp{min,max},condition,rainChance}:
  Mon,-2,4,snow,80
  Tue,1,7,cloudy,20
  Wed,3,11,sunny,5

相同的数据以 JSON 格式 – 大约 117 个标记，而 TOON 的大约 66 个：

{
  "location": {
    "city": "Berlin",
    "country": "DE",
    "units": "metric"
  },
  "alerts": [
    "frost",
    "wind"
  ],
  "forecast": [
    {
      "day": "Mon",
      "temp": {
        "min": -2,
        "max": 4
      },
      "condition": "snow",
      "rainChance": 80
    },
    {
      "day": "Tue",
      "temp": {
        "min": 1,
        "max": 7
      },
      "condition": "cloudy",
      "rainChance": 20
    },
    {
      "day": "Wed",
      "temp": {
        "min": 3,
        "max": 11
      },
      "condition": "sunny",
      "rainChance": 5
    }
  ]
}

在上面的 TOON 中，同时发生了三件事。其中两个是 表单 —— 一个是值的呈现，从数据的形状中自动选择 —— 第三个是标题功能：

• alerts[2]: frost,wind 是 内联表单：在其标题行上的原始数组。
• forecast[3]{day,…}: 是 表格表单：字段列表在标题中声明一次，然后每个元素一行。
• 该标题内的 temp{min,max} 是 嵌套字段组：统一的嵌套 temp 对象折叠到标题中，而行保持扁平。

第三种表单是 键控表格，用于值为统一对象的对象 —— 配置映射、功能标志、按 ID 的记录。长度后的冒号（[2:]）标记它，每行带有自己的键：

JSON

卡通

{
  "environments": {
    "production": { "region": "eu-central-1", "replicas": 6, "debug": false },
    "staging": { "region": "eu-central-1", "replicas": 2, "debug": true }
  }
}

environments[2:]{region,replicas,debug}:
  production: eu-central-1,6,false
  staging: eu-central-1,2,true

任何不符合上述任何一种情况的内容——混合类型、非统一对象——都会退回到第四种形式，列表形式：每个元素一个 - 项，或者空对象用单独的 -。这四种形式涵盖了结构；其余内容请参见 格式概览。

[!提示]
在你自己的数据上尝试——无需安装：

cat data.json | npx @toon-format/cli --stats

它会打印出 TOON 以及转换所节省的内容——在上面的天气预报中，那是：

ℹ 令牌估算：~117（JSON）→ ~66（TOON）
✔ 节省约51个令牌（-43.6%）

主要特点

• 📊 高效令牌 & 精准: 在使用比 JSON 少 42.6% 的令牌的同时，匹配 JSON 的检索准确率 – 查看 基准测试。
• 🔁 JSON 数据模型: 使用与 JSON 相同的对象、数组和原始类型进行编码，实现确定性、无损的往返操作。
• 🛤️ 对 LLM 友好的护栏: [N] 声明行数，{fields} 声明宽度 – 因此截断或格式错误的输出无法漏过。
• 📐 最小语法: 使用缩进代替大括号，并尽量减少引用，实现类似 YAML 的可读性，同时具有 CSV 风格的紧凑性。
• 🧺 表格形式: 统一对象 – 在数组中或在键下 – 只需声明一次字段列表，然后逐行流式输出。
• 🌐 多语言生态系统: 官方实现，以及数十个社区移植版本，都针对同一规范并共享符合性测试套件。

何时不使用 TOON

TOON 在统一对象数组中表现出色。当出现以下情况时，请使用其他方案:

• 结构深度嵌套或不统一（表格适用性 ≈ 0%）– 压缩 JSON 通常直接胜出。
• 数组半统一（~40–60% 适用性）– 节省效果减小；如果你的管道已经支持 JSON，继续使用 JSON。
• 数据纯粹为表格型 – CSV 更小。TOON 约 5–10% 的开销换来了声明长度、字段列表和定界符作用域，这是一种可靠性权衡，而非大小权衡。
• 延迟占主导 – 某些部署（尤其是本地或量化模型）虽然令牌数更多，但处理压缩 JSON 更快。在自己的环境中测量 TTFT 和总时间。

基准测试 下方量化了令牌和准确性权衡；延迟需要你自行测量。

基准测试

两个赛道，因此每个比较都是同类对比：

• 混合结构赛道：嵌套和半统一数据集（TOON 与 JSON、YAML、XML）。排除 CSV —— 它无法在不损失信息的情况下表示这些结构。
• 仅平面赛道：平面、完全适合表格的数据集，CSV 是一个公平的竞争者。

检索准确性

基准测试通过使用4个模型的244个数据检索问题来测试大型语言模型在不同输入格式下的理解能力。

效率排名（每千个标记的准确率）

按效率对每种格式进行排名（每 1,000 个标记的准确率百分比）

TOON           ████████████████████   29.2 acc%/1K tok  │  72.2%  ±2.8 acc  │  2,474 tokens
JSON compact   ████████████████░░░░   23.8 acc%/1K tok  │  69.0%  ±2.9 acc  │  2,892 tokens
YAML           ██████████████░░░░░░   20.1 acc%/1K tok  │  70.1%  ±2.9 acc  │  3,487 tokens
JSON           ███████████░░░░░░░░░   16.6 acc%/1K tok  │  71.4%  ±2.8 acc  │  4,308 tokens
XML            ██████████░░░░░░░░░░   14.4 acc%/1K tok  │  70.7%  ±2.9 acc  │  4,909 tokens

效率评分 = (准确率 % ÷ 令牌) × 1,000。数值越高越好。

[!提示]
TOON 达到 72.2% 的准确率（相比 JSON 的 71.4%），同时使用的令牌 少 42.6%。

[!注意]
CSV 被排除在排名之外，因为它仅支持 244 个问题中的 109 个（仅平面表格数据）。虽然 CSV 对简单表格数据的令牌使用效率很高，但它无法表示其他格式可以处理的嵌套结构。

平面数据集的准确率

每种格式都对每个模型回答相同的 109 个平面数据集问题，因此可以在这里将 CSV 公平地进行比较。

按模型准确率

在 244 个数据检索问题上的 4 个大型语言模型的准确率：

claude-haiku-4-5-20251001
→ TOON           █████████████░░░░░░░    65.6% ±5.9 (160/244)
  JSON           █████████████░░░░░░░    63.5% ±6.0 (155/244)
  XML            ████████████░░░░░░░░    62.3% ±6.0 (152/244)
  YAML           ████████████░░░░░░░░    62.3% ±6.0 (152/244)
  JSON compact   ████████████░░░░░░░░    61.9% ±6.0 (151/244)
  CSV            ██████████░░░░░░░░░░    49.5% ±9.2 (54/109)

gemini-3.6-flash
→ TOON           ██████████████░░░░░░    69.3% ±5.8 (169/244)
  JSON           ██████████████░░░░░░    68.4% ±5.8 (167/244)
  YAML           ██████████████░░░░░░    67.6% ±5.8 (165/244)
  XML            █████████████░░░░░░░    65.2% ±5.9 (159/244)
  JSON compact   █████████████░░░░░░░    63.5% ±6.0 (155/244)
  CSV            ████████████░░░░░░░░    57.8% ±9.1 (63/109)

gpt-5.4-nano
  XML            ████████████░░░░░░░░    59.4% ±6.1 (145/244)
  JSON           ███████████░░░░░░░░░    57.4% ±6.2 (140/244)
→ TOON           ███████████░░░░░░░░░    57.0% ±6.2 (139/244)
  JSON compact   ███████████░░░░░░░░░    54.9% ±6.2 (134/244)
  YAML           ███████████░░░░░░░░░    54.5% ±6.2 (133/244)
  CSV            █████████░░░░░░░░░░░    46.8% ±9.2 (51/109)

grok-4.5
→ TOON           ███████████████████░    97.1% ±2.2 (237/244)
  JSON           ███████████████████░    96.3% ±2.5 (235/244)
  XML            ███████████████████░    95.9% ±2.6 (234/244)
  YAML           ███████████████████░    95.9% ±2.6 (234/244)
  JSON compact   ███████████████████░    95.5% ±2.7 (233/244)
  CSV            ███████████████████░    94.5% ±4.5 (103/109)

[!注意]
准确性数据包括威尔逊95%置信区间（±）；当两种格式的区间重叠时，它们之间的差异在统计上没有意义。CSV仅回答109个平面数据集的问题，因此其每个模型的单元格涵盖的人群比其他格式的更小、更简单。

运行配置

• 测试模型：claude-haiku-4-5-20251001、gemini-3.6-flash、gpt-5.4-nano、grok-4.5
• 比较格式：TOON、JSON、XML、YAML、紧凑JSON、CSV
• 令牌计数：使用 gpt-tokenizer 的 o200k_base 编码（GPT-5 分词器）。其他提供商的分词方式不同，因此绝对计数取决于分词器；格式之间的相对差异方向一致。
• 推理：通过 AI SDK 的通用 reasoning: 'none' 禁用（Gemini 3 以最小思考运行，grok-4.5 设置为 low）
• 温度：未设置（模型使用默认值）
• 总评估：244 个问题 × 6 种格式 × 4 个模型 = 5,856 次 LLM 调用

数据集包含的内容、问题生成方式以及答案验证方式已在基准测试 README中记录。

令牌效率

令牌计数是使用 GPT-5 o200k_base 分词器通过 gpt-tokenizer 测量的。节省量是以格式化的 JSON（2 空格缩进）为主要基准计算的，同时也与紧凑 JSON（最小化）、YAML 和 XML 进行了额外比较。实际节省量因模型和分词器而异。

基准测试的数据集涵盖不同结构模式（均匀、半均匀、嵌套、深度嵌套），以显示 TOON 的优势所在以及其他格式可能更好的场景。

混合结构跟踪

具有嵌套或半统一结构的数据集。排除 CSV，因为它无法正确表示这些结构。

🛒 E-commerce orders with nested structures  ┊  Tabular: 33%
   │
   TOON                █████████████░░░░░░░    72,832 tokens
   ├─ vs JSON          (−32.9%)               108,611 tokens
   ├─ vs JSON compact  (+5.6%)                 68,944 tokens
   ├─ vs YAML          (−14.0%)                84,701 tokens
   └─ vs XML           (−40.4%)               122,119 tokens

🧾 Semi-uniform event logs  ┊  Tabular: 50%
   │
   TOON                █████████████████░░░   154,084 tokens
   ├─ vs JSON          (−15.0%)               181,201 tokens
   ├─ vs JSON compact  (+19.9%)               128,529 tokens
   ├─ vs YAML          (−0.8%)                155,397 tokens
   └─ vs XML           (−25.2%)               205,859 tokens

🧩 Deeply nested configuration  ┊  Tabular: 0%
   │
   TOON                █████████████░░░░░░░       589 tokens
   ├─ vs JSON          (−34.9%)                   905 tokens
   ├─ vs JSON compact  (+6.7%)                    552 tokens
   ├─ vs YAML          (−11.0%)                   662 tokens
   └─ vs XML           (−40.9%)                   997 tokens

📊 Feature flags keyed by name  ┊  Tabular: 100%
   │
   TOON                █████████░░░░░░░░░░░    10,503 tokens
   ├─ vs JSON          (−54.6%)                23,141 tokens
   ├─ vs JSON compact  (−32.8%)                15,635 tokens
   ├─ vs YAML          (−41.3%)                17,905 tokens
   └─ vs XML           (−63.3%)                28,655 tokens

📊 Contacts with nested address and plan groups  ┊  Tabular: 100%
   │
   TOON                ███████░░░░░░░░░░░░░    26,726 tokens
   ├─ vs JSON          (−66.5%)                79,779 tokens
   ├─ vs JSON compact  (−42.9%)                46,791 tokens
   ├─ vs YAML          (−51.8%)                55,475 tokens
   └─ vs XML           (−70.4%)                90,306 tokens

──────────────────────────────────── Total ────────────────────────────────────
   TOON                █████████████░░░░░░░   264,734 tokens
   ├─ vs JSON          (−32.7%)               393,637 tokens
   ├─ vs JSON compact  (+1.6%)                260,451 tokens
   ├─ vs YAML          (−15.7%)               314,140 tokens
   └─ vs XML           (−40.9%)               447,936 tokens

仅平面轨道

具有平面、完全可用于表格的数据集，适用于 CSV。

👥 Uniform employee records  ┊  Tabular: 100%
   │
   CSV                 ███████████████████░    47,153 tokens
   TOON                ████████████████████    49,978 tokens   (+6.0% vs CSV)
   ├─ vs JSON          (−60.7%)               127,061 tokens
   ├─ vs JSON compact  (−36.8%)                79,057 tokens
   ├─ vs YAML          (−50.0%)               100,054 tokens
   └─ vs XML           (−65.9%)               146,605 tokens

📈 Time-series analytics data  ┊  Tabular: 100%
   │
   CSV                 ██████████████████░░     8,383 tokens
   TOON                ████████████████████     9,115 tokens   (+8.7% vs CSV)
   ├─ vs JSON          (−59.0%)                22,245 tokens
   ├─ vs JSON compact  (−35.9%)                14,211 tokens
   ├─ vs YAML          (−49.0%)                17,858 tokens
   └─ vs XML           (−65.8%)                26,616 tokens

⭐ Top 100 GitHub repositories  ┊  Tabular: 100%
   │
   CSV                 ███████████████████░     8,711 tokens
   TOON                ████████████████████     8,937 tokens   (+2.6% vs CSV)
   ├─ vs JSON          (−41.7%)                15,337 tokens
   ├─ vs JSON compact  (−23.2%)                11,640 tokens
   ├─ vs YAML          (−33.0%)                13,337 tokens
   └─ vs XML           (−48.3%)                17,294 tokens

──────────────────────────────────── Total ────────────────────────────────────
   CSV                 ███████████████████░    64,247 tokens
   TOON                ████████████████████    68,030 tokens   (+5.9% vs CSV)
   ├─ vs JSON          (−58.7%)               164,643 tokens
   ├─ vs JSON compact  (−35.2%)               104,908 tokens
   ├─ vs YAML          (−48.2%)               131,249 tokens
   └─ vs XML           (−64.3%)               190,515 tokens

令牌计数使用 gpt-tokenizer 并采用 o200k_base 编码（GPT-5 分词器）。其他提供商的分词方式不同，因此绝对计数取决于分词器；不同格式之间的相对差异方向保持不变。

{
  "指标": ["
    {
      "date": "2025-01-01",
      "views": 6138,
      "clicks": 174,
      "conversions": 12,
      "revenue": 2712.49,
      "bounceRate": 0.35
    },
    {
      "date": "2025-01-02",
      "views": 4616,
      "clicks": 274,
      "conversions": 34,
      "revenue": 9156.29,
      "bounceRate": 0.56
    },
    {
      "date": "2025-01-03",
      "views": 4460,
      "clicks": 143,
      "conversions": 8,
      "revenue": 1317.98,
      "bounceRate": 0.59
    },
    {
      "date": "2025-01-04",
      "views": 4740,
      "clicks": 125,
      "conversions": 13,
      "revenue": 2934.77,
      "bounceRate": 0.37
    },
    {
      "date": "2025-01-05",
      "views": 6428,
      "clicks": 369,
      "conversions": 19,
      "revenue": 1317.24,
      "bounceRate": 0.3
    }
  ]
}

metrics[5]{日期,浏览量,点击量,转化,收入,跳出率}:
  2025-01-01,6138,174,12,2712.49,0.35
  2025-01-02,4616,274,34,9156.29,0.56
  2025-01-03,4460,143,8,1317.98,0.59
  2025-01-04,4740,125,13,2934.77,0.37
  2025-01-05,6428,369,19,1317.24,0.3

{
  "repositories": ["
    {
      "id": 132750724,
      "name": "build-your-own-x",
      "repo": "codecrafters-io/build-your-own-x",
      "description": "Master programming by recreating your favorite technologies from scratch.",
      "createdAt": "2018-05-09T12:03:18Z",
      "updatedAt": "2026-07-23T18:57:15Z",
      "pushedAt": "2026-07-14T19:25:58Z",
      "stars": 530712,
      "watchers": 6778,
      "forks": 50205,
      "defaultBranch": "master"
    },
    {
      "id": 21737465,
      "name": "awesome",
      "repo": "sindresorhus/awesome",
      "description": "😎 Awesome lists about all kinds of interesting topics",
      "createdAt": "2014-07-11T13:42:37Z",
      "updatedAt": "2026-07-23T18:57:24Z",
      "pushedAt": "2026-06-30T18:21:16Z",
      "stars": 488074,
      "watchers": 8292,
      "forks": 36010,
      "defaultBranch": "main"
    },
    {
      "id": 28457823,
      "name": "freeCodeCamp",
      "repo": "freeCodeCamp/freeCodeCamp",
      "description": "freeCodeCamp.org's open-source codebase and curriculum. Learn math, programming,…",
      "createdAt": "2014-12-24T17:49:19Z",
      "updatedAt": "2026-07-22T07:01:33Z",
      "pushedAt": "2026-07-21T18:00:51Z",
      "stars": 452380,
      "watchers": 8590,
      "forks": 45624,
      "defaultBranch": "main"
    }
  ]
}

repositories[3]{id,名称,仓库,描述,创建时间,更新时间,推送时间,收藏数,关注者,分支数,默认分支}:
  132750724，build-your-own-x，codecrafters-io/build-your-own-x，通过从零开始重现你喜欢的技术来掌握编程。“2018-05-09T12：03：18Z”，“2026-07-23T18：57：15Z”，“2026-07-14T19：25：58Z”，530712,6778,50205，master。
  21737465，awesome，sindresorhus/awesome，😎关于各种有趣话题的精彩列表，“2014-07-11T13：42：37Z”，“2026-07-23T18：57：24Z”，“2026-06-30T18：21：16Z”，488074,8292,36010，主线
  28457823，freeCodeCamp，freeCodeCamp/freeCodeCamp，“freeCodeCamp.org的开源代码库和课程。学习数学，编程,...”，“2014-12-24T17：49：19Z”，“2026-07-22T07：01：33Z”，“2026-07-21T18：00：51Z”，452380,8590,45624，main”

安装与快速入门

# npm
npm install @toon-format/toon

# pnpm
pnpm add @toon-format/toon

# yarn
yarn add @toon-format/toon

如果想保留 CLI 而不是通过 npx 调用它，请全局安装它：

npm install -g @toon-format/cli

示例用法：

import { encode } from '@toon-format/toon'

const data = {
  users: [
    { id: 1, name: 'Ada', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' }
  ]
}

console.log(encode(data))
// users[2]{id,name,role}:
//   1,Ada,admin
//   2,Bob,user

流式传输大数据集：

import { encodeLines } from '@toon-format/toon'

const largeData = await fetchThousandsOfRecords()

// Memory-efficient streaming for large data
for (const line of encodeLines(largeData)) {
  process.stdout.write(`${line}\n`)
}

[!提示]
有关流解码 API，请参阅 decodeFromLines() 和 decodeStream()。

使用替换器转换值：

import { encode } from '@toon-format/toon'

// Remove sensitive fields
const user = { name: 'Ada', password: 'secret', email: 'ada@example.com' }
const safe = encode(user, {
  replacer: (key, value) => key === 'password' ? undefined : value
})
// name: Ada
// email: ada@example.com

[!提示]
replacer 函数提供了对编码的精细控制，类似于 JSON.stringify 的 replacer，但具有路径跟踪功能。请参阅 API 参考 获取更多示例，包括使用 rawString 的逐字输出。

命令行界面（CLI）

命令行工具，用于快速进行 JSON↔TOON 转换、令牌分析和管道集成。可从文件扩展名自动检测格式，支持 stdin/stdout 工作流，并提供分隔符选项（逗号、制表符、管道），在可读性和令牌数量之间进行权衡。

# Encode JSON to TOON (auto-detected)
npx @toon-format/cli input.json -o output.toon

# Decode TOON to JSON (auto-detected)
npx @toon-format/cli data.toon -o output.json

# Pipe from stdin (no argument needed)
cat data.json | npx @toon-format/cli
echo '{"name": "Ada"}' | npx @toon-format/cli

# Output to stdout
npx @toon-format/cli input.json

# Show token savings
npx @toon-format/cli data.json --stats

[!提示]
请参阅完整的CLI 文档以获取所有选项、示例和高级用法。

在大语言模型中使用 TOON

当你展示格式而不是描述它时，TOON 的效果最佳。一旦模型看到一个表格示例，标题 – [N] 长度加上 {fields} 字段列表 – 就会告诉它如何读取其余内容。将数据包裹在 ``` toon code blocks for input, and show the expected header template when asking models to generate TOON. Tab delimiters buy further token savings. Full-line 中 # 注释在解码时会被移除，因此手工标注的提示数据以及带有解释行的模型输出仍然可以干净地解码。

请遵循详细的LLM 集成指南以获取策略、示例和验证技巧。

生态系统

游乐场 – 官方游乐场 实时将 JSON 或 YAML 转换为 TOON，比较令牌数量，并通过 URL 分享实验。社区替代方案: 格式令牌化游乐场, TOON 工具。

编辑器 – TOON 语言支持 用于 VS Code (code --install-extension vishalraut.vscode-toon)，增加了高亮显示、验证和令牌分析。tree-sitter-toon 支持 Neovim、Helix、Emacs 以及 Zed；toon.nvim 是 Lua 本地替代方案。在其他地方，YAML 高亮显示是一个接近的替代。

工具 – Tooner 是一个 MCP 代理，将 JSON 工具响应转换为 TOON。

文档

入门指南

• 介绍与安装 – 什么是 TOON、何时使用以及第一步操作
• 格式概览 – 完整语法及示例
• 基准测试 – 准确性与令牌效率结果

工具与集成

• 命令行工具 – JSON↔TOON 转换的命令行工具
• 练习场 – 交互式工具
• 在 LLM 中使用 TOON – 提示策略与验证

参考资料

• API 参考 – TypeScript/JavaScript 编码/解码 API
• 语法速查表 – 格式快速查找
• 规范 – 实现者的规范规则
• 术语表 – 每个概念一个名称，供贡献者与工具使用

媒体类型及文件扩展名

TOON 文件使用 .toon 扩展名和临时媒体类型 text/toon。文档始终为 UTF-8；可能会给出 charset=utf-8 参数，但在缺失时默认假定为 UTF-8。规范性细节请参见 SPEC.md §17。

其他实现

TOON 在多个语言中都有官方和社区实现，包括 Python、Rust、Go、Java、Swift、.NET 等。

请在文档中查看完整的实现列表。

鸣谢

• 标志设计由 鈴木ックス(SZKX) 制作

许可

MIT 许可 © 2025-至今 Johann Schopplich