需要给 LLM 传入 JSON 数据并降低 prompt…

将结构化 JSON 数据编码为 TOON 格式后注入 LLM prompt，以减少 token 并保持可读性；也可将 TOON 解码回 JSON/JS 对象。

适用场景

解决思路

1. 安装包：使用 npm install @toon-format/toon，或 pnpm add @toon-format/toon，或 yarn add @toon-format/toon。
2. 全局安装 CLI：npm install -g @toon-format/toon。
3. 用 CLI 将 JSON 文件编码为 TOON：toon encode input.json；指定输出文件用 toon encode input.json -o output.toon。
4. 用 CLI 将 TOON 解码回 JSON：toon decode input.toon；指定输出文件用 toon decode input.toon -o output.json。
5. 使用管道处理：cat data.json | toon encode，cat data.toon | toon decode。
6. 美化 JSON 输出：toon decode input.toon --pretty。
7. 查看 token 数对比：toon encode input.json --stats。
8. 核心 API 导入：import { encode, decode } from '@toon-format/toon';。
9. 编码数据：调用 encode(data)，把 JSON/JS 对象转为 TOON 字符串。
10. 解码数据：调用 decode(toonString)，把 TOON 字符串还原为 JavaScript 对象。
11. 设置 encode 选项 tabular：tabular: 'always' 强制所有数组使用 tabular 格式，tabular: 'never' 从不使用；默认自动检测 uniform arrays。
12. 设置 encode 选项 indent：indent: 2 控制嵌套对象缩进大小，默认 2。
13. 设置 encode 选项 quoting：quoting: 'auto' 自动给含特殊字符的字符串加引号。
14. 编码标量：按 YAML 方式编码，无歧义时不加引号，例如 name: Alice、age: 30、active: true、score: 98.6、nothing: null。
15. 编码嵌套对象：使用 YAML 风格缩进，例如 user: 下一行缩进 name: Alice，再下一层缩进 address:。
16. 编码扁平数组：用方括号声明长度并以逗号分隔值，例如 tags[3]: typescript,llm,serialization。
17. 编码均匀对象数组：用 tabular 格式，例如 employees[3]{id,name,department,salary}:，后续每行缩进写一行逗号分隔值。
18. 引号规则：值中包含逗号、冒号或换行时，用双引号包裹，例如 notes[2]: "hello, world","line1\nline2"。
19. 混合嵌套：按缩进组合嵌套对象、扁平数组和 tabular 对象数组。
20. LLM 直接提示词注入：先用 encode(data) 生成 TOON，再放入 user content 的代码块；同时在 system prompt 中说明 TOON 规则：缩进表示嵌套对象，key[N]: v1,v2 表示标量数组，key[N]{fields}: 加缩进行表示对象数组。
21. OpenAI 用法：new OpenAI({ apiKey: process.env.OPENAI_API_KEY })，调用 client.chat.completions.create，选择 model: 'gpt-4o-mini'，在 messages 中放入 system 格式说明与包含 TOON 数据的 user 内容。
22. Anthropic/Claude 用法：new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })，调用 client.messages.create，选择 model: 'claude-haiku-4-5-20251001'，设置 max_tokens: 1024，system 说明 TOON 格式，messages 的 user 内容用 ```toon 包裹 TOON。
23. Token 数对比工具：用 JSON.stringify(data) 得到 JSON 字符串，用 encode(data) 得到 TOON 字符串；用 gpt-tokenizer 的 encode 分别计算长度；按 (jsonTokens - toonTokens) / jsonTokens * 100 计算节省百分比并打印或返回。
24. 批量 API 调用模式：逐条编码用 records.map((r) => encode(r))；批量编码为一个 TOON 文档用 encode({ [key]: records })，其中 key 可为 records。
25. RAG/检索上下文注入：对 SearchResult 数组调用 encode({ results })，让均匀对象结果折叠成紧凑表格后放入上下文。
26. 大型数据集文件转换：读取 inputPath 的 UTF-8 内容，JSON.parse 后调用 encode，写入 outputPath；再用 Buffer.byteLength 比较 JSON 与 TOON 字节数并计算减少百分比。
27. Schema-aware TypeScript：定义接口如 Employee、EmployeeReport，构造 report 后 encode(report)；解码时用 decode(toon) as EmployeeReport，再按类型访问字段。
28. Express 中间件解析 TOON 请求体：检查 content-type 是否以 text/toon 开头，累积 body，decode 后挂到 req.toonBody；解析失败返回 400。
29. Express 中间件返回 TOON：检查 Accept 是否包含 text/toon，设置 Content-Type: text/toon; charset=utf-8，并用 res.send(encode({ employees })) 返回 TOON，否则用 res.json。
30. 不确定收益时做基准：用 compareTokens 或 toon encode input.json --stats 对真实数据比较 JSON 与 TOON 的 token 数，再决定是否替换。
31. 处理含逗号值：encode() 会自动给含逗号的值加双引号；手写 TOON 时也要用双引号包裹含逗号的值。
32. 避免类型往返丢失：编码前确保数字和布尔值使用正确 JS 类型，不要用 '95000'、'true' 这类字符串代替 95000、true。
33. LLM 误读表格行时：在 system prompt 中补充 TOON 格式规则，说明缩进、key[N]: 标量数组、key[N]{fields}: 对象数组的读法。
34. CLI 全局安装后找不到命令：运行 npm bin -g 或 npm root -g 检查全局 bin 路径是否在 PATH，或改用 npx @toon-format/toon encode input.json。
35. 手写 TOON 解码失败时检查：必须写长度声明，如 items[2]{id,name}:；不要混用制表符和空格；不要使用未加引号且以冒号开头的值。
36. 需要规范时查阅：官方 Specification SPEC v3.0、npm 包 @toon-format/toon、在线 Playground 和 GitHub Repository。

适用边界 · 注意事项

• 程序化 API 调用或机器间传输不要用 TOON 替代 JSON；JSON 更适合程序处理，只在 LLM 输入时编码为 TOON。
• 深层嵌套、非均匀对象数组或半均匀数据不一定节省 token；先 benchmark JSON 与 TOON，并关注延迟关键场景的 TTFT 和 tokens/sec。
• 纯扁平表格数据优先考虑 CSV，除非你需要保留结构化对象语义；约 40–60% tabular 的半均匀数据收益递减，也应先比较。