⚡

TOON格式Skill toon-format

TOON是一种为LLM（大型语言模型）提示设计的紧凑、人类可读的JSON编码格式，旨在减少令牌数量，提高数据传输效率。

NLP 0 次安装 5 次浏览 更新于 3/3/2026

TOON格式技能 TOON是为LLM提示设计的紧凑、人类可读的JSON编码。

变量

变量 默认 描述
VALIDATION_MODE strict strict（需要CLI验证）或lenient（解析器宽容）
AUTO_FIX true 在验证失败时自动运行修复脚本

指令

强制性 - 遵循此技能中的格式规则和reference/format-rules.md。

  • 总是包括明确的[count]用于数组
  • 使用2个空格缩进用于表格行
  • 在表格数组后添加空白行以终止它们
  • 在单元格中使用分号用于嵌套数组（而不是逗号）

红旗 - 停止并重新考虑

如果你即将：

  • 在表格单元格中在引号内放置逗号
  • 从数组声明中省略[count]
  • 忘记在表格数组后添加空白行
  • 使用YAML风格的- item列表语法
  • 添加带有#的注释

停止 -> 检查reference/format-rules.md -> 然后继续

工作流程

  1. [ ] 确定是否适用TOON（见下面的"何时使用TOON"）
  2. [ ] 为表格表示设计数据结构
  3. [ ] 检查点：验证格式是否符合规则
  4. [ ] 用适当的缩进编写TOON
  5. [ ] 使用npx @toon-format/cli --decode进行验证
  6. [ ] 如果有错误，运行reference/validation-tools.md中的自动修复脚本

食谱

格式规则

  • IF：编写或编辑TOON文件
  • THEN：阅读reference/format-rules.md
  • COVERS：语法规则、约束、正确模式

验证与修复

  • IF：TOON文件验证失败
  • THEN：阅读reference/validation-tools.md
  • COVERS：CLI验证，自动修复脚本

何时使用TOON

好候选：

  • 统一的表格数据（类似对象的列表）
  • 文档索引和清单
  • 重复的键值结构
  • 任何被馈送到LLMs的结构化数据

使用JSON代替：

  • 深层嵌套结构
  • 非统一数据（混合模式）
  • 需要频繁程序操作的数据
  • 由工具读取的配置文件

TOON语法

键值（YAML风格）

name: 约翰
age: 30
active: true

带有显式长度的数组

tags[3]: 红色，绿色，蓝色

表格数据（主要用例）

# 语法：name[count]{col1,col2,col3}:
# 后跟2个空格缩进的CSV风格行

users[3]{id,name,email}:
  1,约翰，john@example.com
  2,简，jane@example.com
  3,鲍勃，bob@example.com

重要：行必须用2个空格缩进。总是在最后一行后添加一个空白行。

单元格中的嵌套数组

使用分号或引号包含多个项目的值：

pages[2]{path,keywords,priority}:
/intro,"概览；基础；开始",核心
/api,"参考；方法；类型",核心

多行字符串

使用引号字符串和 进行换行：

description: "这是一个多行
字符串值，保留
换行。"

嵌套对象

config:
  database:
    host: 本地主机
    port: 5432
  cache:
    enabled: true

编码模式用于文档

索引文件

meta:
  category: 库
  generated: 2025-01-15T10:30:00Z
  count: 5

items[5]{id,name,description,path,keywords}:
baml,BAML,结构化LLM输出，ai-docs/libraries/baml/_index.toon,"llm；类型；结构化"
mcp,MCP,工具集成协议，ai-docs/libraries/mcp/_index.toon,"工具；上下文；服务器"
prisma,Prisma,类型安全数据库ORM，ai-docs/libraries/prisma/_index.toon,"数据库；ORM；SQL"

页面摘要

meta:
  library: baml
  page: 错误处理
  source_url: https://docs.boundaryml.com/guide/error-handling
  content_hash: a3f2c1d4e5

summary:
  purpose: "配置重试策略和回退策略，以实现弹性LLM调用。"

  key_concepts[4]: 重试策略，回退客户端，超时，指数退避

  gotchas[2]: 默认超时60秒可能太短，重试次数计入速率限制

code_patterns[1]:
  - lang: baml
    desc: 重试策略配置
    code: "retry_policy 弹性 {
  max_retries 3
  strategy 指数
}"

令牌比较

JSON（约280个令牌）：

{"pages":[{"path":"/intro","section":"guide","title":"介绍","priority":"核心"},{"path":"/setup","section":"guide","title":"设置","priority":"核心"}]}

TOON（约100个令牌）：

pages[2]{path,section,title,priority}:
/intro,guide,介绍,核心
/setup,guide,设置,核心

节省：~64%

工具和库

最佳实践

  1. 尽可能为表格表示设计数据结构
  2. 使用显式的[count]用于数组 - 有助于LLM解析
  3. 保持JSON作为规范源，TOON用于LLM传输
  4. 使用分号用于嵌套数组（例如，“val1;val2;val3”）
  5. 截断长字符串（代码片段<200字符）
  6. 总是在表格数组后添加一个空白行以终止它们

格式约束

由官方@toon-format/cli强制执行（使用--decode进行验证）：

规则 ❌ 不正确 ✅ 正确
无注释 # comment （完全删除注释）
无YAML风格列表 - item key[N]{col}: + 缩进行
行必须缩进 row,data row,data（2个空格）
数组需要计数+列 items{a,b}: items[3]{a,b}:
无多行字符串 key: | `key: "line1
line2"`
无管道分隔符 val|val val,val 或 "val;val"
表格单元格中无逗号 "a,b" "a;b"
数组后空白行 缺少终止符 在最后一行后添加空白行

验证工具：

# 使用官方CLI进行验证（使用--decode，而不是validate！）
npx @toon-format/cli --decode file.toon > /dev/null

# 自动修复常见问题（按此顺序运行）
python3 .claude/ai-dev-kit/dev-tools/scripts/fix_toon_comments.py path/
python3 .claude/ai-dev-kit/dev-tools/scripts/fix_toon_yaml_lists.py path/
python3 .claude/ai-dev-kit/dev-tools/scripts/fix_toon_nested_lists.py path/
python3 .claude/ai-dev-kit/dev-tools/scripts/fix_toon_commas.py path/
python3 .claude/ai-dev-kit/dev-tools/scripts/fix_toon_pipes.py path/
python3 .claude/ai-dev-kit/dev-tools/scripts/fix_toon_multiline.py path/
python3 .claude/ai-dev-kit/dev-tools/scripts/fix_toon_blank_lines.py path/