toon-formatter

TOON v2.0 格式专家

TOON（Token-Oriented Object Notation）通过省去统一数组中的重复键，可为结构化数据节省 30-60% 的 Token。

适用场景

以下情况自动使用 TOON：

• 包含 5 个或更多相似对象的数组
• 结构重复的 API 响应
• 数据库查询结果
• 日志条目、事件、事务
• 指标、分析数据、基准测试
• 任何表格数据

以下情况保留为 JSON：

• 小型数组（少于 5 项）
• 深层嵌套且结构不统一的数据
• 单个对象
• 叙述性文本或说明

格式规范

表格格式（最常见）

适用于统一对象数组：

[count]{field1,field2,field3}:
  value1,value2,value3
  value1,value2,value3

示例 — JSON（120 个 Token）：

[
  {"id": 1, "name": "Alice", "role": "admin", "active": true},
  {"id": 2, "name": "Bob", "role": "user", "active": true},
  {"id": 3, "name": "Carol", "role": "user", "active": false}
]

TOON（70 个 Token，节省 42%）：

[3]{id,name,role,active}:
  1,Alice,admin,true
  2,Bob,user,true
  3,Carol,user,false

内联格式

适用于原始值数组（10 项或更少）：

fieldName[count]: value1,value2,value3

示例：

tags[4]: javascript,react,nodejs,api
ids[3]: 101,102,103

展开格式

适用于复杂的嵌套值（每行一个）：

items[3]|:
  | {"complex": "object1"}
  | {"complex": "object2"}
  | {"complex": "object3"}

分隔符

根据数据内容选择：

分隔符	语法	使用场景
逗号	[N]	默认选项，值中不含逗号
制表符	[N\t]	值中包含逗号
竖线	[N|]	值中包含逗号和制表符

制表符分隔示例：

[2\t]{name,description}:
  Product A	A great product, really
  Product B	Another one, even better

键折叠（嵌套对象）

扁平化嵌套结构：

server.host: localhost
server.port: 8080
server.ssl.enabled: true
database.url: postgres://localhost/db

特殊值

值	TOON 表示形式
null	~
空字符串	""
true	true
false	false

转换模式

API 响应

转换前（JSON）：

{
  "users": [
    {"id": 1, "email": "[email protected]", "plan": "pro"},
    {"id": 2, "email": "[email protected]", "plan": "free"},
    {"id": 3, "email": "[email protected]", "plan": "pro"}
  ],
  "total": 3
}

转换后（TOON）：

users[3]{id,email,plan}:
  1,[email protected],pro
  2,[email protected],free
  3,[email protected],pro
total: 3

日志条目

转换前（JSON）：

[
  {"ts": "2024-01-15T10:00:00Z", "level": "INFO", "msg": "Server started"},
  {"ts": "2024-01-15T10:00:01Z", "level": "DEBUG", "msg": "Connection pool ready"},
  {"ts": "2024-01-15T10:00:02Z", "level": "INFO", "msg": "Listening on :8080"}
]

转换后（TOON）：

[3]{ts,level,msg}:
  2024-01-15T10:00:00Z,INFO,Server started
  2024-01-15T10:00:01Z,DEBUG,Connection pool ready
  2024-01-15T10:00:02Z,INFO,Listening on :8080

数据库结果

转换前（JSON）：

[
  {"product_id": 101, "name": "Widget", "price": 29.99, "stock": 150},
  {"product_id": 102, "name": "Gadget", "price": 49.99, "stock": 75},
  {"product_id": 103, "name": "Gizmo", "price": 19.99, "stock": 200}
]

转换后（TOON）：

[3]{product_id,name,price,stock}:
  101,Widget,29.99,150
  102,Gadget,49.99,75
  103,Gizmo,19.99,200

混合内容

按需组合格式：

config.name: MyApp
config.version: 1.0.0
config.features[3]: auth,logging,metrics

endpoints[4]{method,path,auth}:
  GET,/api/users,required
  POST,/api/users,required
  GET,/api/health,none
  DELETE,/api/users/:id,admin

tags[5]: api,rest,json,http,web

决策流程图

Is it an array?
├─ No → Use standard JSON/key-value
└─ Yes → How many items?
    ├─ <5 → Keep as JSON (overhead not worth it)
    └─ ≥5 → Are objects uniform (≥60% same keys)?
        ├─ No → Use expanded format
        └─ Yes → Are values primitives?
            ├─ Yes, ≤10 items → Inline format
            └─ Otherwise → Tabular format

Token 节省参考

数据类型	典型节省比例
用户列表	40-50%
日志条目	35-45%
API 响应	30-50%
数据库行	45-55%
事件流	40-60%
配置数组	25-35%

二进制编码器

可使用已编译的 Zig 编码器（比 JS 快 20 倍）：

# Encode JSON to TOON
.claude/utils/toon/bin/toon encode data.json

# Decode TOON to JSON  
.claude/utils/toon/bin/toon decode data.toon

# Check if TOON recommended
.claude/utils/toon/bin/toon check data.json

# Analyze token savings
.claude/utils/toon/bin/toon analyze data.json

命令

命令	描述
/toon-encode <file>	将 JSON 转换为 TOON
/toon-decode <file>	将 TOON 转换为 JSON
/toon-validate <file>	验证 TOON 语法
/analyze-tokens <file>	对比 JSON 与 TOON 的大小
/convert-to-toon <file>	完整转换工作流

最佳实践

建议：

• 在 RAG 流程的数据载荷中使用 TOON
• 用于包含数组的工具调用响应
• 转换基准测试结果和指标
• 值中包含逗号时使用制表符分隔符

不建议：

• 转换小型数组（少于 5 项）
• 强行将结构不统一的数据转换为表格格式
• 用于深层嵌套结构
• 用于面向人类阅读的文档

资源

• 规范：https://github.com/toon-format/spec
• 网站：https://toonformat.dev
• 本地指南：.claude/utils/toon/toon-guide.md