一(yi)、TOON 是什么
官方定(ding)義要(yao)點摘錄（來源(yuan)：toon-format/toon 倉庫 README）：
- Token-efficient：通常比 JSON 少 30–60% 的 tokens（Key Features 列表）
- LLM-friendly guardrails：顯式長度與字段，便于驗證
- Minimal syntax：移除冗余標點（大括號、方括號、許多引號）
- Indentation-based structure：類似 YAML，以空白縮進代替大括號
- Tabular arrays：一次聲明列頭，數據按行流式書寫
官方基準與工具：
- README 的 Benchmarks 表格展示了多個數據集下的 token 節省比例；此外提供“Format Tokenization Playground”可交互比較不同格式的 token 用量
- 當前規范版本：v1.3（README 徽章與 SPEC.md 指向的專用倉庫）
規范入口與一致性：
- 規范遷移至獨立倉庫： 明確“moved to a dedicated repository”）
- 跨語言一致性依賴 conformance tests（README 的 Other Implementations 區塊提供說明）
二(er)、為什(shen)么 TOON 相比 JSON 更省 tokens
本質原因是“以(yi)結構換(huan)冗(rong)余(yu)”：在 LLM 語境下，重(zhong)復(fu)的鍵名和(he)標點(dian)都會占用(yong) tokens。TOON 通過以(yi)下策(ce)略顯著減少冗(rong)余(yu)（均(jun)可在 README 與語法速查中(zhong)找到實(shi)例(li)）：
- 表格數組：為均勻對象數組聲明一次列頭，如 users[2]{id,name}: 后續行直接寫 1,Alice
- 行內原子數組：tags[3]: a,b,c，避免多余方括號與引號
- 鍵名可不加引號：安全鍵裸寫，減少引號數量
- 縮進代替大括號：以空白表達層級
同時(shi)，官方 README 也(ye)清晰指出邊界(jie)：對于深(shen)度嵌套或非均勻結構的數據，JSON 可能更高效。這意(yi)味著在“樹深(shen)且(qie)分支(zhi)不(bu)規(gui)則(ze)”的任務上應優先評估 JSON。
三(san)、語法速查與(yu)對照示例
下列示例(li)與(yu)含義對應自 README 的 Syntax Cheatsheet 與(yu)“Why TOON”示例(li)（術語與(yu)格式(shi)請(qing)以規(gui)范 v1.3 為準）：
-
對象
{ id: 1, name: 'Ada' } → id: 1 換(huan)行 name: Ada -
嵌套對象
{ user: { id: 1 } } → user: 換行縮進 id: 1 -
行內原子數組
{ tags: ['foo', 'bar'] } → tags[2]: foo,bar -
表格數組（均勻對象）
{ items: [ { id: 1, qty: 5 }, { id: 2, qty: 3 } ] }
→ items[2]{id,qty}: 換(huan)行縮(suo)進 1,5 換(huan)行縮(suo)進 2,3 -
混合或非均勻數組
{ items: [ 1, { a: 1 }, 'x' ] } → items[3]: 換(huan)行(xing)縮(suo)進(jin)(jin)(jin) - 1 換(huan)行(xing)縮(suo)進(jin)(jin)(jin) - a: 1 換(huan)行(xing)縮(suo)進(jin)(jin)(jin) - x
四、AIDotNet.Toon：.NET 實現概(gai)覽
AIDotNet.Toon 對(dui)齊 upstream 規范與設計，面向 .NET 提供(gong)與 System.Text.Json 風(feng)格(ge)一致的 API。關鍵入口如下：
- 序列化： C#.ToonSerializer.Serialize() · C#.ToonSerializer.Serialize()
- 反序列化： C#.ToonSerializer.Deserialize() · C#.ToonSerializer.Deserialize()
- 編碼實現： C#.ToonEncoder.Encode()
- 解碼實現： C#.ToonDecoder.DecodeToJsonString()
- 選項模型： C#.ToonSerializerOptions · 分隔符枚舉 C#.ToonDelimiter · 默認實例 C#.ToonSerializerOptions.Default
- 錯誤模型： C#.ToonFormatException
實現思路（節(jie)選(xuan)自源(yuan)碼注釋與 README）：
- Encode 路徑：.NET 對象 → JsonElement → Encoders 結構化寫出（對象、行內原子數組、表格數組、列表回退等）
- Decode 路徑：TOON → 規范化 JSON 字符串 → System.Text.Json 反序列化為目標類型
- 數值與特殊值：允許命名浮點字面量，經編碼階段將 NaN 與 ±Infinity 規范化為 null，-0 規范化為 0（細節見編碼器與選項）
五、安裝與快速開始
通過(guo) NuGet（發布后）或源(yuan)碼引入本庫：
dotnet add package AIDotNet.Toon
using AIDotNet.Toon;
var options = new ToonSerializerOptions
{
Indent = 2,
Delimiter = ToonDelimiter.Comma,
Strict = true,
LengthMarker = null
};
var data = new
{
users = new[] { new { id = 1, name = "Alice" }, new { id = 2, name = "Bob" } },
tags = new[] { "a", "b", "c" },
numbers = new[] { 1, 2, 3 }
};
var text = ToonSerializer.Serialize(data, options);
// users[2]{id,name}:
// 1,Alice
// 2,Bob
// tags[3]: a,b,c
// numbers[3]: 1,2,3
讀取原子值：
var s = ToonSerializer.Deserialize<string>("hello", options); // "hello"
var n = ToonSerializer.Deserialize<double>("3.1415", options); // 3.1415
互操(cao)作(zuo)：TOON ? JSON ? .NET
// 將 TOON 文本轉為目標類型，內部先經 [C#.ToonDecoder.DecodeToJsonString()](src/AIDotNet.Toon/ToonDecoder.cs:15)
var user = ToonSerializer.Deserialize<Dictionary<string, object>>("id: 1", options);
// 將 .NET 對象經 JSON DOM 編碼為 TOON
var t = ToonSerializer.Serialize(new { id = 1, name = "Ada" }, options);
六、選項與行為
統一選項入口 C#.ToonSerializerOptions 與默認預設 C#.ToonSerializerOptions.Default：
- Indent：每級縮進空格數，默認 2
- Delimiter：分隔符，枚舉 C#.ToonDelimiter，用于行內與表格；底層轉換為具體字符見 C#.ToonSerializerOptions.GetDelimiterChar()
- Strict：嚴格模式，校驗縮進、空行、計數一致性等
- LengthMarker：數組長度標記，僅支持 # 或 null
- JsonOptions：直通 System.Text.Json；默認啟用 AllowNamedFloatingPointLiterals，并注冊轉換器以將 NaN 與 ±Infinity 寫出為 null
七、錯誤模型與定位
解碼錯誤統一拋出 C#.ToonFormatException 并包(bao)含錯誤分類與位置信息：
- 工廠方法：Syntax C#.ToonFormatException.Syntax() · Range C#.ToonFormatException.Range() · Validation C#.ToonFormatException.Validation() · Indentation C#.ToonFormatException.Indentation() · Delimiter C#.ToonFormatException.Delimiter()
八、進階示例
- 表格數組寫出
var rows = new[] { new { id = 1, name = "alice" }, new { id = 2, name = "bob" } };
var toon = ToonSerializer.Serialize(rows, options);
// [2]{id,name}:
// 1,alice
// 2,bob
- 行內原子數組
var arr = new[] { 1, 2, 3 };
var t2 = ToonSerializer.Serialize(arr, options); // "[3]: 1,2,3"
- 混合數組回退為列表
var mixed = new object[] { 1, new { a = 1 }, "x" };
var t3 = ToonSerializer.Serialize(mixed, options);
// [3]:
// - 1
// - a: 1
// - x
九、何時(shi)使用 TOON，何時(shi)選 JSON
基于(yu)官方 README 的(de)定(ding)位：當你(ni)的(de)數(shu)據是“均(jun)(jun)勻對象(xiang)數(shu)組、字(zi)段重復較多、需要給 LLM 更大(da)輸入(ru)上下(xia)文”時(shi)，TOON 通(tong)常更省 tokens 且(qie)更易校(xiao)驗(yan)驗(yan)證；當數(shu)據“深(shen)度嵌套、非均(jun)(jun)勻或樹(shu)形變化大(da)”時(shi)，JSON 可能(neng)更高效更直接。
十(shi)、數據流與實現(xian)關(guan)系圖
十一、來源與參考
- 官方倉庫與 README：
- 規范倉庫 v1.3：
- README“Key Features”“Benchmarks”“Syntax Cheatsheet”“Other Implementations”板塊提供了本文引用的特性描述、節省比例與示例
- 本文 .NET 實現地址：
十二、結語
TOON 讓(rang) LLM 輸入(ru)里(li)的結(jie)構化數(shu)據更加緊(jin)湊(cou)、可校(xiao)驗(yan)、可讀；AIDotNet.Toon 則在 .NET 世界(jie)提供熟悉的 API 體(ti)驗(yan)與(yu)選項模型。建議從表格數(shu)組與(yu)行(xing)內原(yuan)子數(shu)組的典型場景開(kai)始落(luo)地，并結(jie)合規范(fan) v1.3 與(yu)測試數(shu)據持續驗(yan)證。
Special thanks to the upstream project toon-format.
附：官方 Benchmarks 數據集(ji)節(jie)選
以下數(shu)(shu)字直接摘錄(lu)自官方 README 的 Benchmarks「Token Efficiency」小(xiao)節，原文與上下文見： TOON 的優(you)勢場景：均勻表格(ge)化數(shu)(shu)據，真實(shi)效果取(qu)決于數(shu)(shu)據結構）。交互式對(dui)比工具(ju)：
Token 效率
? GitHub Repositories ██████████████??????????? 8,745 tokens
vs JSON (-42.3%) 15,145
vs JSON compact (-23.7%) 11,455
vs YAML (-33.4%) 13,129
vs XML (-48.8%) 17,095
?? Daily Analytics ██████████??????????????? 4,507 tokens
vs JSON (-58.9%) 10,977
vs JSON compact (-35.7%) 7,013
vs YAML (-48.8%) 8,810
vs XML (-65.7%) 13,128
?? E-Commerce Order ████████████████????????? 166 tokens
vs JSON (-35.4%) 257
vs JSON compact (-2.9%) 171
vs YAML (-15.7%) 197
vs XML (-38.7%) 271
─────────────────────────────────────────────────────────────────────
Total ██████████████??????????? 13,418 tokens
vs JSON (-49.1%) 26,379
vs JSON compact (-28.0%) 18,639
vs YAML (-39.4%) 22,136
vs XML (-56.0%) 30,494
檢索準確率
4 種大型語言模型在 154 個(ge)數據檢索問(wen)題上的準確率：
gpt-5-nano
→ TOON ███████████████████? 96.1% (148/154)
CSV ██████████████████?? 91.6% (141/154)
YAML ██████████████████?? 91.6% (141/154)
JSON compact ██████████████████?? 91.6% (141/154)
XML █████████████████??? 87.0% (134/154)
JSON █████████████████??? 86.4% (133/154)
claude-haiku-4-5-20251001
JSON ██████████?????????? 50.0% (77/154)
YAML ██████████?????????? 49.4% (76/154)
→ TOON ██████████?????????? 48.7% (75/154)
XML ██████████?????????? 48.1% (74/154)
CSV █████████??????????? 47.4% (73/154)
JSON compact █████████??????????? 44.2% (68/154)
gemini-2.5-flash
CSV ██████████████████?? 87.7% (135/154)
XML ██████████████████?? 87.7% (135/154)
→ TOON █████████████████??? 86.4% (133/154)
YAML ████████████████???? 79.9% (123/154)
JSON compact ████████████████???? 79.9% (123/154)
JSON ███████████████????? 76.6% (118/154)
grok-4-fast-non-reasoning
→ TOON ██████████?????????? 49.4% (76/154)
JSON ██████████?????????? 48.7% (75/154)
XML █████████??????????? 46.1% (71/154)
YAML █████████??????????? 46.1% (71/154)
JSON compact █████████??????????? 45.5% (70/154)
CSV █████████??????????? 44.2% (68/154)
注(zhu)意(yi)：上述(shu)樣本強(qiang)調 TOON 在“均勻對象(xiang)數(shu)組/表格化數(shu)據”場(chang)景的節(jie)省效果；對于深度(du)嵌套或非均勻數(shu)據，官方(fang) README 指出(chu) JSON 可能更高效。建議在落地前結合自身數(shu)據結構評估與小規模驗證。