mcpField
M
media-transformation

media-transformation

github.com/qodex-ai数据与数据库47125 次安装42 周前更新
代码仓库

关于 media-transformation

指导 Agent 将适合的结构化数据编码为 TOON v2.0，以减少提示词中的 Token 用量，并涵盖格式选择、分隔符、键折叠和 Zig 编码器流程。

主要功能

  1. 01TOON 与 JSON 的选择条件
  2. 02表格、内联和展开数组格式
  3. 03逗号、制表符和竖线分隔符
  4. 04嵌套键折叠
  5. 05Zig 编码器及转换命令

适用场景

  1. 01压缩提示词中的规则化 API 响应
  2. 02格式化大型数据库查询结果
  3. 03为 RAG 流程和工具调用准备结构化数据
  4. 04比较 JSON 与 TOON 的 Token 用量估算

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/qodex-ai/ai-agent-skills --skill media-transformation

安装后在 Claude Code 中输入/media-transformation确认已加载。

详细介绍

TOON v2.0 格式化技能（激进模式）

目的

激进地应用 TOON v2.0 格式，以节省 30–60% 的结构化数据令牌。对于较大且规则的数据，默认使用 TOON。使用原生 Zig 编码器可获得 20 倍性能。

何时使用（激进模式）

全天候使用 TOON——自动用于：

  • ✅ 包含 ≥ 5 个相似项的数组
  • ✅ 表格、日志、事件、交易、分析数据
  • ✅ 结构统一的 API 响应（字段重合度 ≥ 60%）
  • ✅ 数据库查询结果
  • ✅ 在提示词中反复使用的结构化数据
  • ✅ RAG 管道、工具调用、Agent 之间传递的数据
  • ✅ 提示词大小直接影响成本的基准测试／评估
  • ✅ 形状比标签更重要的情况
  • ✅ 清楚每列含义的情况
  • ✅ 可以只声明一次表头，然后逐行列出数据的情况

可以考虑，但不自动使用——酌情选择：

  • ⚠️ 人类协作者需要经常阅读或编辑数据
  • ⚠️ API／工具要求使用 JSON（线上传输用 JSON，提示词中用 TOON）
  • ⚠️ 结构不规则（有许多可选键或奇怪的嵌套）

不要使用——坚持使用 JSON／文本：

  • ❌ 短数组（< 5 个项）
  • ❌ 文档中的一次性示例
  • ❌ 叙述文本、说明、文章
  • ❌ 层级关系很重要的深层不规则树结构

什么是 TOON v2.0？

TOON（面向令牌的对象表示法）v2.0 可将结构化数据的令牌消耗降低 30–60%：

三种数组类型

1. 表格型（≥5 个统一对象）：

[2]{id,name,balance}:
  1,Alice,5420.50
  2,Bob,3210.75

2. 内联型（≤10 个基本类型值）：

tags[5]: javascript,react,node,express,api

3. 展开型（不统一）：

- name: Alice
  role: admin
- name: Bob
  level: 5
三种分隔符

逗号（默认，最紧凑）：

[2]{name,city}: Alice,NYC Bob,LA

制表符（用于包含逗号的数据）：

[2\t]{name,address}: Alice	123 Main St, NYC

竖线（类似 Markdown）：

[2|]{method,path}: GET|/api/users
键折叠

展平嵌套对象（额外节省 25–35%）：

server.host: localhost
server.port: 8080
database.host: db.example.com

流程

1. 检测适用的数据

遇到数组数据时，检查它是否符合 TOON 条件：

  • ✅ 数组包含 ≥5 个项
  • ✅ 对象的字段统一度 ≥60%（大多数对象具有相同字段）
  • ✅ 结构扁平或只有中等程度的嵌套

检查统一度的方法：

  1. 提取所有对象中的全部字段名
  2. 统计具有最常见字段集的对象数量
  3. 计算：(具有常见字段的对象数 / 对象总数) × 100
  4. 如果 ≥60%，则统一度适合使用 TOON
2. 估算令牌节省量

快速估算方法：

  • JSON 令牌数 ≈ (项数 × 字段数 × 4) + 额外开销
    • 示例：10 项 × 5 个字段 × 4 = 约 200 个令牌
  • TOON 令牌数 ≈ 20（表头）+（项数 × 字段数 × 2）
    • 示例：20 + (10 × 5 × 2) = 约 120 个令牌
  • 节省比例 ≈ (JSON - TOON) / JSON × 100%
    • 示例：(200 - 120) / 200 = 节省 40%
3. 激进地应用 TOON v2.0

激进模式：使用 Zig 编码器以获得最佳效果

如果数据符合条件：

方法 1：使用 Zig 编码器（推荐——速度快 20 倍）：

.claude/utils/toon/zig-out/bin/toon encode data.json \
  --delimiter tab \
  --key-folding \
  > data.toon

方法 2：手动使用 TOON（用于内联生成）：

  1. 检测数组类型（内联型／表格型／展开型）
  2. 选择分隔符（逗号／制表符／竖线）
  3. 如果对象存在嵌套，则应用键折叠
  4. 构建 TOON 表头：[N]{fields}: 或 key[N]: values
  5. 输出格式化后的 TOON

显示简短摘要：

📊 Using TOON v2.0 (estimated 42% savings, 10 items)
Format: Tabular with tab delimiter
Key folding: enabled

[10\t]{id,name,address,status}:
  1	Alice	123 Main St, NYC	active
  2	Bob	456 Oak Ave, LA	inactive
  ...

否则，使用 JSON 并说明原因：

Using JSON because:
- Only 3 items (too small)
- Or: Low uniformity (only 45% have same fields)
- Or: Deeply nested structure
4. 显示格式化后的输出

立即以 TOON 格式显示，并附上简短说明：

📊 API Endpoints (15 items, TOON format - saved 40.1% tokens):

[15]{method,path,description,auth,rateLimit}:
  GET,/api/users,List all users,required,100/min
  POST,/api/users,Create new user,required,50/min
  ...

不需要长篇解释——直接使用即可！

最佳实践

始终说明格式选择

处理数据时，始终说明使用哪种格式以及原因：

📊 Using TOON (estimated 42% token savings)
[count]{fields}:...

或

ℹ️ Using JSON (deeply nested structure, TOON not suitable)
{...}
不使用 TOON 的情况

说明何时 JSON 更合适：

  • 深度嵌套的数据：TOON 擅长处理扁平／表格型结构
  • 统一度低（<70%）：对象字段各不相同会降低 TOON 的优势
  • 小数组（<10 个项）：额外开销不值得
  • 单条记录：使用 JSON 更清晰
性能提示
  1. 批处理：一次转换大型数据集，并重复使用 TOON 格式
  2. 统一度很重要：字段重合度越高，节省越多
  3. 嵌套数组：TOON 支持嵌套结构，但节省效果会减弱
  4. 类型转换：TOON 会保留类型（数字、布尔值、日期）

示例

示例 1：API 响应

输入：

const apiResponse = await fetch('/api/users').then(r => r.json());
// 150 users returned

输出：

API Response (150 users):
Format: TOON (saves 41.2%, 1,847 tokens saved)

[150]{id,name,email,role,lastLogin}:
  1,Alice Smith,[email protected],admin,2024-01-15T10:30:00Z
  2,Bob Jones,[email protected],user,2024-01-15T09:15:00Z
  ...
示例 2：数据库查询

输入：

SELECT * FROM transactions WHERE date > '2024-01-01' LIMIT 500;

输出：

Query Results (500 transactions):
Format: TOON (saves 38.9%, 3,421 tokens saved)

[500]{id,date,amount,merchant,category,status}:
  1,2024-01-15,42.50,Starbucks,Food & Drink,completed
  2,2024-01-15,125.00,Shell Gas,Transportation,completed
  ...
示例 3：指标仪表板

输入：

const metrics = analyzePerformance();
// Returns array of route performance metrics

输出：

Performance Metrics (45 routes):
Format: TOON (saves 44.1%, 892 tokens saved)

[45]{route,avgTime,p95,requests,errors}:
  /api/users,125,340,15420,3
  /api/products,89,210,8932,0
  /api/orders,450,1250,3421,12
  ...
示例 4：混合数据（JSON 更合适）

输入：

const complexData = {
  metadata: { version: '1.0', timestamp: '...' },
  results: [
    { id: 1, data: { nested: { deep: 'value' } } },
    // Highly nested, non-uniform
  ]
};

输出：

ℹ️ Using JSON format (TOON not recommended):
- Deeply nested structure
- Low uniformity (45%)
- Small array (only 5 items)

{
  "metadata": { "version": "1.0", ... },
  "results": [ ... ]
}

与其他技能集成

财务分析

分析交易或财务数据时，大型结果集请使用 TOON：

  • 交易历史记录（100 项以上）
  • 多个账户的余额
  • 支付日志和审计跟踪
数据导出

导出数据时，请检查 TOON 是否适用：

  • 如果有 ≥5 项且其中 ≥60% 格式统一 → 使用 TOON
  • 否则 → 使用 JSON
API 文档

使用 TOON 格式编写 API 端点文档，以便简洁查阅：

# API Endpoints

[15]{method,path,auth,rateLimit,description}:
  GET,/api/users,required,100/min,List all users
  POST,/api/users,required,50/min,Create new user
  ...

命令

使用以下 TOON v2.0 命令：

  • /toon-encode <file> [--delimiter tab] [--key-folding] - JSON → TOON v2.0
  • /toon-validate <file> [--strict] - 验证 TOON 文件
  • /analyze-tokens <file> - 比较 JSON 与 TOON 的节省量
  • /convert-to-toon <file> - 旧版命令（请使用 toon-encode）

资源

  • Zig 编码器：.claude/utils/toon/toon.zig（601 行，速度快 20 倍）
  • 用户指南：.claude/docs/toon-guide.md
  • 示例：.claude/utils/toon/examples/（9 个文件）
  • 指南：.claude/utils/toon/guides/（4 个文件）
  • 常见问题：.claude/docs/FAQ.md
  • TOON 规范：https://github.com/toon-format/spec
  • 官方网站：https://toonformat.dev

成功指标

跟踪 TOON 的使用效果：

  • 平均 token 节省量：30-60%
  • 准确率提升：+3-5%（依据官方基准测试）
  • 释放的上下文窗口：大型数据集可释放 15K+ tokens
  • 用户满意度：响应更快，可用上下文更多

评论

支持 Markdown