内容
<p align="center">
<img src="assets/datoon-banner.svg" width="720" />
</p>
<h1 align="center">datoon</h1>
<p align="center">
<strong>智能结构化数据→TOON网关 — 仅在实际节省令牌时转换</strong>
</p>
<p align="center">
<a href="https://github.com/andrii-su/datoon/actions/workflows/tests.yml"><img src="https://github.com/andrii-su/datoon/actions/workflows/tests.yml/badge.svg" alt="测试"></a>
<a href="https://github.com/andrii-su/datoon/actions/workflows/pre-commit.yml"><img src="https://github.com/andrii-su/datoon/actions/workflows/pre-commit.yml/badge.svg" alt="预提交"></a>
<a href="https://github.com/andrii-su/datoon/actions/workflows/release.yml"><img src="https://github.com/andrii-su/datoon/actions/workflows/release.yml/badge.svg" alt="发布"></a>
<a href="https://pypi.org/project/datoon/"><img src="https://img.shields.io/pypi/v/datoon?color=0EA5E9" alt="PyPI"></a>
<a href="https://img.shields.io/badge/python-3.12%2B-3776AB"><img src="https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white" alt="Python"></a>
<a href="./LICENSE"><img src="https://img.shields.io/github/license/andrii-su/datoon" alt="许可证：MIT"></a>
</p>
<p align="center">
<a href="#前后对比">前后对比</a> •
<a href="#安装">安装</a> •
<a href="#您将获得什么">您将获得什么</a> •
<a href="#工作原理">工作原理</a> •
<a href="#基准测试">基准测试</a> •
<a href="./INSTALL.md">完整安装指南</a>
</p>
______________________________________________________________________
原始结构化数据通常在LLM提示中冗长。 [TOON](https://github.com/toon-format/toon) 可以节省令牌 — 但盲目转换也会使有效载荷 *变差*。 `datoon` 添加了一个决策层：转换时结构和节省有道理时才转换，否则跳过，并始终解释原因。
支持 **JSON、CSV、JSONL、YAML、XML、Parquet、Avro、ORC、Excel 和 Apple Numbers** — 从文件扩展名自动检测。
## 前后对比
<table>
<tr>
<td width="50%">
### JSON 在提示中（43 个令牌）
```json
{"users":[
{"id":1,"name":"Ada","role":"admin"},
{"id":2,"name":"Lin","role":"analyst"},
{"id":3,"name":"Grace","role":"viewer"}
]}
```
</td>
<td width="50%">
### datoon 转换 → TOON（24 个令牌）
```toon
users[3]{id,name,role}:
1,Ada,admin
2,Lin,analyst
3,Grace,viewer
```
```json
{"decision":"convert","reason":"Estimated savings 44.19% (threshold 15.00%)."}
```
</td>
</tr>
<tr>
<td>
### 来自数据管道的 CSV（111 个令牌作为 JSON）
```csv
id,name,role
1,Ada,admin
2,Lin,analyst
3,Grace,viewer
```
</td>
<td>
### datoon 自动转换 → TOON（24 个令牌）
```bash
datoon data.csv --report-stdout
```
相同结果。代码中零 JSON 序列化。
</td>
</tr>
<tr>
<td>
### 非均匀有效载荷（26 个令牌）
```json
{"config":{"debug":true},"tags":["a","b"]}
```
</td>
<td>
### datoon 跳过 → 保留 JSON
```json
{"decision":"skip","reason":"No uniform object arrays found with at least 3 rows."}
```
无需 Node.js 调用。无需静默损坏。
</td>
</tr>
</table>
**相同数据。正确格式。始终解释。**
```
┌──────────────────────────────────────────────────┐
│ 有效载荷节省（自动平均值） ████░░░░░░ 28% │
│ 有效载荷节省（代理技能） ████████░░ 62% │
│ 决策准确性 ██████████ 100% │
│ 有害转换阻止 ██████████ 100% │
└──────────────────────────────────────────────────┘
```
> [!IMPORTANT]
> datoon 节省 **有效载荷令牌** — 结构化数据部分的提示。令牌节省取决于有效载荷形状：统一表格数据转换良好；深度嵌套或非统一结构被跳过。每个决策都包含一个原因，以便管道可以记录、调试和信任结果。
## 安装
```bash
# 核心（JSON、CSV、JSONL、XML — 无额外依赖）
uv add datoon
pip install datoon
# 支持 YAML
pip install "datoon[yaml]"
# 支持 Excel
pip install "datoon[excel]"
# 支持 Parquet / ORC / Avro
pip install "datoon[columnar]"
# 支持 Apple Numbers
pip install "datoon[numbers]"
# 支持 tiktoken-based 令牌计数
pip install "datoon[tokens]"
# 支持 MCP 服务器
pip install "datoon[mcp]"
# 所有功能
pip install "datoon[all]"
```
需要 Python 3.12+。 TOON 转换需要带有 `npx` 的 Node.js 在 PATH 中 — 分析和格式读取无需它。
对于 Claude Code 插件、Codex 和 MCP 配置 → [**INSTALL.md**](./INSTALL.md)。
## 您将获得什么
| | 功能 |
|---|---|
| `datoon` **命令行界面** | 自动门控任意支持格式 → TOON 从终端或脚本 |
| **Python API** | `convert_json_for_llm()` + `read_tabular()` 用于任意 LLM 管道 |
| **MCP 服务器** | `convert_json`, `convert_text`, `analyze_json` 工具用于 Claude Desktop, Cursor, Windsurf |
| **Claude Code 插件** | `/datoon` 会话触发器，从 GitHub 安装只需一个命令 |
| **Codex 插件** | 市场插件 — 结构化数据模式用于 Codex |
### 支持的输入格式
| 格式 | 扩展名 | 需要额外功能 |
|---|---|---|
| JSON | `.json` | — |
| JSONL | `.jsonl`, `.ndjson` | — |
| CSV | `.csv` | — |
| XML | `.xml` | — |
| YAML | `.yaml`, `.yml` | `datoon[yaml]` |
| Excel | `.xlsx`, `.xls` | `datoon[excel]` |
| Parquet | `.parquet` | `datoon[columnar]` |
| Avro | `.avro` | `datoon[columnar]` |
| ORC | `.orc` | `datoon[columnar]` |
| Apple Numbers | `.numbers` | `datoon[numbers]` |
## 工作原理
1. **检测格式** — 从 `--format` 标志、文件扩展名或 stdin 默认 JSON
1. **读取 + 规范化** — 解析源为行字典列表；序列化为紧凑 JSON
1. **分析结构** — 统一对象数组？可接受的深度？最小行数？
1. **早期门控** — 非候选者跳过任何 CLI 调用前；无需 Node.js 开销
1. **转换 + 估计** — TOON CLI 运行，计算令牌节省
1. **门控节省** — 低于阈值 → 返回 JSON；高于 → 返回 TOON 并报告
每条路径返回一个 `ConversionReport`，包含 `decision`、`reason` 和令牌估计。管道永远不会收到静默惊喜。
______________________________________________________________________
## 快速开始
**JSON（标准输入）：**
```bash
echo '{"users":[{"id":1,"name":"Ada"},{"id":2,"name":"Lin"},{"id":3,"name":"Grace"}]}' | datoon --report-stdout
```
**CSV（从扩展名自动检测）：**
```bash
datoon data.csv --report-stdout
```
**JSONL：**
```bash
datoon data.jsonl -o output.toon
```
**YAML（需要 `datoon[yaml]`）：**
```bash
datoon data.yaml --report-stdout
```
**Parquet（需要 `datoon[columnar]`）：**
```bash
datoon data.parquet --report ./report.json
```
**显式格式覆盖：**
```bash
datoon --format csv < data.csv --report-stdout
```
**强制转换（绕过门控 — 用于实验）：**
```bash
datoon data.json --force --report-stdout
```
______________________________________________________________________
## Python API
**JSON 转换：**
```python
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 或原始 JSON
# outcome.report.decision — "convert" | "skip"
# outcome.report.reason — 人类可读的解释
send_to_model(outcome.payload_text)
```
**通过 `read_tabular` 读取任意格式：**
```python
import json
from pathlib import Path
from datoon import read_tabular, convert_json_for_llm, ConversionConfig
# 文本格式：csv, jsonl, yaml, xml
rows = read_tabular("csv", text=csv_string)
# 二进制格式：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）：**
```python
from datoon.analyzer import analyze_payload
from datoon.models import ConversionConfig
analysis = analyze_payload(parsed_data, ConversionConfig())
print(analysis.is_candidate, analysis.reason)
```
______________________________________________________________________
## MCP 服务器
<!-- mcp-name: io.github.andrii-su/datoon -->
`datoon` 随附一个 [MCP](https://modelcontextprotocol.io) 服务器，具有三个工具：
| 工具 | 描述 |
|---|---|
| `convert_json` | 具有策略门控的完整 JSON 转换 |
| `convert_text` | 使用策略门控转换 CSV、YAML、XML 或 JSONL 文本 |
| `analyze_json` | 仅结构分析 — 无需 Node.js |
**Claude Desktop / Cursor / Windsurf 配置：
```json
{
"mcpServers": {
"datoon": {
"command": "uvx",
"args": ["--from", "datoon[mcp]", "datoon", "mcp"]
}
}
}
```
**本地运行：
```bash
datoon mcp # 或独立脚本：datoon-mcp
```
列在 [MCP 注册表](https://registry.modelcontextprotocol.io)、 [Smithery](https://smithery.ai) 和 [Glama](https://glama.ai) 上。参见 [MARKETPLACES.md](./MARKETPLACES.md)。
______________________________________________________________________
## Claude Code 插件
直接从 GitHub 安装：
```bash
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
```
______________________________________________________________________
## 命令行界面参考
| 标志 | 默认值 | 描述 |
|---|---|---|
| `--format` | 自动 | 输入格式：`json`, `csv`, `jsonl`, `yaml`, `xml`, `excel`, `parquet`, `avro`, `orc`, `numbers` |
| `--force` | `false` | 绕过门控和最低节省阈值 |
| `--min-savings` | `0.15` | 要求的最低相对令牌节省 |
| `--max-depth` | `6` | 自动转换的最大嵌套深度 |
| `--min-uniform-rows` | `3` | 统一对象数组的最小行数 |
| `--timeout` | `30` | TOON CLI 调用中止前的秒数 |
| `--report <path>` | — | 将 JSON 转换报告写入文件 |
| `--report-stdout` | — | 将 JSON 转换报告打印到 stderr |
| `-o <path>` | stdout | 输出文件路径 |
| `--version` | — | 打印版本并退出 |
格式从文件扩展名自动检测。使用 `--format` 覆盖或从 stdin 读取时。
______________________________________________________________________
## 基准测试
```bash
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`），同时匹配强制 TOON 的平均令牌数。每个决策都附带原因报告。
| 场景 | JSON 基线 | 强制 TOON | `datoon` 自动 |
|---|---:|---:|---:|
| 平均令牌 | 77 | 50 | 50 |
| 平均节省令牌 | 0.0% | 26.8% | **28.1%** |
| 决策质量 | n/a | 转换所有 | 转换 `3/5`，跳过有害情况 |
<!-- BENCHMARK-TABLE-START -->
| 数据集 | JSON | TOON（强制） | 原始节省 | 自动 | 自动令牌 | 自动节省 |
|---|---:|---:|---:|---|---:|---:|
| users-small | 56 | 31 | 44.6% | convert | 31 | 44.6% |
| events-medium | 198 | 111 | 43.9% | convert | 111 | 43.9% |
| orders-nested | 93 | 91 | 2.2% | skip | 93 | 0.0% |
| mixed-non-uniform | 35 | 37 | -5.7% | skip | 35 | 0.0% |
| metrics-wide | 133 | 63 | 52.6% | convert | 63 | 52.6% |
| **平均值** | **103** | **67** | **27.5%** | **3/5 转换** | **67** | **28.2%** |
*强制转换适用于 5/5 个有效载荷。*
<!-- BENCHMARK-TABLE-END -->
### 格式转换基准
从常见结构化格式（CSV、JSONL、XML、YAML）转换令牌节省。基线是相同数据的 JSON 表示 — 没有 datoon 的 LLM 将收到的数据。
<!-- FORMAT-BENCHMARK-TABLE-START -->
| 数据集 | 格式 | JSON 令牌 | TOON（强制） | 原始节省 | 自动 | 自动令牌 | 自动节省 |
|---|---|---:|---:|---|---:|---:|
| users-csv | csv | 53 | 29 | 45.3% | convert | 29 | 45.3% |
| events-jsonl | jsonl | 194 | 109 | 43.8% | convert | 109 | 43.8% |
| catalog-xml | xml | 96 | 50 | 47.9% | convert | 50 | 47.9% |
| metrics-yaml | yaml | 129 | 61 | 52.7% | convert | 61 | 52.7% |
| **平均值** | — | **118** | **62** | **27.5%** | **4/4 转换** | **62** | **47.4%** |
*强制转换适用于 4/4 个有效载荷。*
<!-- FORMAT-BENCHMARK-TABLE-END -->
### 代理技能评估
基于工件的子代理比较 — 相同的分析任务，两种模式：
- `with_skill`: 代理接收 `datoon` 技能并遵循转换工作流。
- `without_skill`: 代理直接使用 JSON，无 TOON 或 `datoon`。
3 个有效载荷大小 × 3 次迭代 = 18 次总代理运行。两种模式：100% 正确答案。
| 场景 | 平均 JSON 令牌 | 平均 TOON 令牌 | 平均节省令牌 |
|---|---:|---:|---:|
| small | 225 | 118 | 47.6% |
| medium | 2,972 | 1,138 | 61.7% |
| large | 17,757 | 6,673 | 62.4% |
完整报告和原始输出： [`benchmarks/agent_skill_eval/`](benchmarks/agent_skill_eval/). 节省的令牌估计不是完整的端到端模型令牌使用情况。
______________________________________________________________________
## 开发
贡献者工作流： [CONTRIBUTING.md](./CONTRIBUTING.md)。维护者/代理说明： [CLAUDE.md](./CLAUDE.md)。
**设置：
```bash
uv sync --extra dev
uvx pre-commit install
```
**测试：
```bash
pytest -m "not integration" # 仅单元测试（102 个测试）
pytest # 集成测试（需要 Node.js + npx）
```
**技能同步 + 插件元数据：
```bash
python scripts/validate_skill_sync.py
python scripts/validate_plugin_metadata.py
```
______________________________________________________________________
## 链接
- [INSTALL.md](./INSTALL.md) — 完整安装矩阵，所有目标，每个代理的详细说明
- [CONTRIBUTING.md](./CONTRIBUTING.md) — 贡献者工作流
- [CLAUDE.md](./CLAUDE.md) — 维护者指南
- [CHANGELOG.md](./CHANGELOG.md) — 发布历史
- [SECURITY.md](./SECURITY.md) — 漏洞报告
- [Live docs](https://andrii-su.github.io/datoon/) — `docs/`
- [Issues](https://github.com/andrii-su/datoon/issues) — 错误、功能、问题
______________________________________________________________________
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器