datoon

datoon

智能结构化数据→TOON 网关 — 仅在确实能节省令牌时才进行转换

转换前/后 • 安装 • 功能一览 • 工作原理 • 基准测试 • 完整安装指南

原始结构化数据在大模型提示词中往往冗长。TOON 可以节省令牌，但盲目转换也可能让负载更糟。datoon 增加了一层决策逻辑：当结构和节省效果值得转换时就转换，不值得时就跳过，并始终说明原因。

支持 JSON、CSV、JSONL、YAML、XML、Parquet、Avro、ORC、Excel 和 Apple Numbers，并根据文件扩展名自动检测格式。

转换前 / 后

{"users":[
  {"id":1,"name":"Ada","role":"admin"},
  {"id":2,"name":"Lin","role":"analyst"},
  {"id":3,"name":"Grace","role":"viewer"}
]}

users[3]{id,name,role}:
  1,Ada,admin
  2,Lin,analyst
  3,Grace,viewer

{"decision":"convert","reason":"Estimated savings 44.19% (threshold 15.00%)."}

id,name,role
1,Ada,admin
2,Lin,analyst
3,Grace,viewer

datoon data.csv --report-stdout

{"config":{"debug":true},"tags":["a","b"]}

{"decision":"skip","reason":"No uniform object arrays found with at least 3 rows."}

数据相同。格式恰当。始终说明原因。

┌──────────────────────────────────────────────────┐
│  PAYLOAD SAVINGS (auto avg)    ████░░░░░░   28%  │
│  PAYLOAD SAVINGS (agent skill) ████████░░   62%  │
│  DECISION ACCURACY             ██████████  100%  │
│  HARMFUL CONVERSIONS BLOCKED   ██████████  100%  │
└──────────────────────────────────────────────────┘

重要

datoon 节省的是负载令牌，即提示词中结构化数据部分所占用的令牌。令牌节省效果取决于负载形态：均匀的表格数据适合转换；深度嵌套或非均匀结构则会跳过。每项决策都会附带原因，方便工作流记录日志、调试并信任结果。

安装

# core (JSON, CSV, JSONL, XML — no extra deps)
uv add datoon
pip install datoon

# with YAML support
pip install "datoon[yaml]"

# with Excel support
pip install "datoon[excel]"

# with Parquet / ORC / Avro support
pip install "datoon[columnar]"

# with Apple Numbers support
pip install "datoon[numbers]"

# with tiktoken-based token counting
pip install "datoon[tokens]"

# with MCP server
pip install "datoon[mcp]"

# everything
pip install "datoon[all]"

需要 Python 3.12+。转换 TOON 需要安装 Node.js，且 npx 位于 PATH 中；无需 Node.js 也能进行分析和读取格式。

Claude Code 插件、Codex 和 MCP 配置 → INSTALL.md。

功能一览

支持的输入格式

工作原理

1. 检测格式 — 根据 --format 标志、文件扩展名，或在读取 stdin 时默认使用 JSON
2. 读取并规范化 — 将源数据解析为行字典列表；序列化为紧凑 JSON
3. 分析结构 — 是否为统一的对象数组？深度是否可接受？行数是否达到最低要求？
4. 提前筛选 — 非候选数据会在任何 CLI 调用前跳过；不会产生 Node.js 开销
5. 转换并估算 — 运行 TOON CLI，计算 Token 节省量
6. 按节省量筛选 — 低于阈值 → 返回 JSON；高于阈值 → 返回 TOON 和报告

每种情况下都会返回一个包含 decision、reason 和 Token 估算值的 ConversionReport。流水线不会出现意外的静默行为。

快速开始

JSON（stdin）：

echo '{"users":[{"id":1,"name":"Ada"},{"id":2,"name":"Lin"},{"id":3,"name":"Grace"}]}' | datoon --report-stdout

CSV（根据扩展名自动检测）：

datoon data.csv --report-stdout

JSONL：

datoon data.jsonl -o output.toon

YAML（需要 datoon[yaml]）：

datoon data.yaml --report-stdout

Parquet（需要 datoon[columnar]）：

datoon data.parquet --report ./report.json

显式指定格式：

datoon --format csv < data.csv --report-stdout

强制转换（绕过筛选 — 用于实验）：

datoon data.json --force --report-stdout

Python API

JSON 转换：

from datoon import convert_json_for_llm, ConversionConfig, DatoonError

config = ConversionConfig(min_savings_ratio=0.15, max_depth=6, min_uniform_rows=3)

try:
    outcome = convert_json_for_llm(raw_json, config)
except DatoonError as exc:
    raise

# outcome.payload_text  — TOON or original JSON
# outcome.report.decision  — "convert" | "skip"
# outcome.report.reason    — human-readable explanation
send_to_model(outcome.payload_text)

通过 read_tabular 读取任意格式：

import json
from pathlib import Path
from datoon import read_tabular, convert_json_for_llm, ConversionConfig

# text formats: csv, jsonl, yaml, xml
rows = read_tabular("csv", text=csv_string)

# binary formats: excel, parquet, orc, avro, numbers
rows = read_tabular("parquet", path=Path("data.parquet"))

json_text = json.dumps(rows, separators=(",", ":"))
outcome = convert_json_for_llm(json_text, ConversionConfig())
send_to_model(outcome.payload_text)

仅分析结构（无需 Node.js）：

from datoon.analyzer import analyze_payload
from datoon.models import ConversionConfig

analysis = analyze_payload(parsed_data, ConversionConfig())
print(analysis.is_candidate, analysis.reason)

MCP 服务

datoon 提供了一个 MCP 服务，包含三个工具：

Claude Desktop / Cursor / Windsurf 配置：

{
  "mcpServers": {
    "datoon": {
      "command": "uvx",
      "args": ["--from", "datoon[mcp]", "datoon", "mcp"]
    }
  }
}

本地运行：

datoon mcp     # or the standalone script: datoon-mcp

已列入 MCP Registry、Smithery 和 Glama。参见 MARKETPLACES.md。

Claude Code 插件

直接从 GitHub 安装：

claude plugin marketplace add andrii-su/datoon
claude plugin install datoon@datoon

在会话中触发：

/datoon
convert this JSON to TOON if it saves tokens
use datoon mode for structured data

CLI 参考

根据文件扩展名自动检测格式。从 stdin 读取时，或需要覆盖自动检测结果时，请使用 --format。

基准测试

PYTHONPATH=src python benchmarks/run.py --dry-run
PYTHONPATH=src python benchmarks/run.py
PYTHONPATH=src python benchmarks/run.py --update-readme

为什么自动模式优于强制转换

自动模式会跳过收益较低、风险较高的负载（orders-nested、mixed-non-uniform），同时在适合转换的负载上，其平均 token 数与强制 TOON 转换相当。每项决策都会附带有据可循的报告。

5/5 个负载均成功强制转换。

格式转换基准测试

从常见结构化格式（CSV、JSONL、XML、YAML）转换时的 token 节省情况。 基准是相同数据的 JSON 表示，也就是不使用 datoon 时大模型会收到的内容。

4/4 个负载均成功强制转换。

Agent 技能评估

基于产物的子 Agent 对比——分析任务相同，模式不同：

• with_skill：Agent 获得了 datoon 技能，并遵循转换工作流。
• without_skill：Agent 直接使用 JSON，不使用 TOON 或 datoon。

3 种负载大小 × 3 次迭代 = 共运行 18 次 Agent。两种模式的回答正确率均为 100%。

完整报告和原始输出：benchmarks/agent_skill_eval/。节省数据是负载 token 的估算值，并非端到端模型 token 使用量。

开发

贡献者工作流：CONTRIBUTING.md。维护者/Agent 说明：CLAUDE.md。

设置：

uv sync --extra dev
uvx pre-commit install

测试：

pytest -m "not integration"   # unit only (102 tests)
pytest                        # with integration (requires Node.js + npx)

技能同步 + 插件元数据：

python scripts/validate_skill_sync.py
python scripts/validate_plugin_metadata.py

链接

• INSTALL.md — 完整安装矩阵、所有目标及各 Agent 的详细说明
• CONTRIBUTING.md — 贡献者工作流
• CLAUDE.md — 面向 Agent 的维护者指南
• CHANGELOG.md — 发布历史
• SECURITY.md — 漏洞报告
• 在线文档 — docs/
• 问题 — Bug、功能需求、问题

许可证

MIT