BatchTicket（CLI：adt）是一款面向 Agent 工作流的确定性结构化数据转换器（deterministic structured-data transducer）。就像随生产或运输批次一起流转的小票一样，每次运行都携带一份带版本号的计划（plan）和执行所变更内容的显式说明。该说明并不声称映射在语义上是正确的。
它不是又一个 jq 或 SQL 方言。DuckDB、JSON Schema、PyYAML 和标准解析器已经承担了既有的执行工作。本项目拥有的是围绕它们的 Agent 契约（Agent contract）。
版本 0.2.0 是未发布源码的候选版本（source release candidate）。本项目采用
Apache License 2.0 许可。稳定的技术标识符仍为
agent-data-transformer、data-transformer、adt 以及四个 data_* MCP 工具。
在不返回完整载荷的情况下检查 JSON、JSONL、CSV、TSV、YAML 和 Parquet。
发现 JSON/YAML 封装中的有界嵌套记录集（bounded nested record sets），并对其逻辑字段进行概要分析。
将源记录形状与目标 JSON Schema 进行比较，仅呈现结构性映射候选，并且只有在明确兼容的映射之后才生成可执行的草案计划。
安全的 Transformation Plan v1，不包含任何原始代码、SQL、shell、jq、正则表达式或模板执行。
支持过滤（filter）、投影（project）、删除（drop）、重命名（rename）、排序（sort）、限制（limit）、去重（deduplicate）、类型转换（cast）、派生（derive）、展开（explode）、连接（join）、分组（group）、透视（pivot）、逆透视（unpivot）、扁平化（flatten）、反扁平化（unflatten）以及树形变更（tree mutation）。
JSON Schema 以及非空、唯一、行数、字段和类型断言。
支持模式感知的有键或无键差异比较（diff）。
干跑（Dry-run）附带真实目标预检、分阶段原子发布和覆盖保护。
全调用级工作进程隔离，带有累计的源/字节/行/项/深度/时间/RSS/临时文件限制。
针对完整个序列化响应的字节上限，包括样本、形状、执行效果、差异、验证失败和错误。
一个严格的类型化 Plan v1 模型统一生成运行时验证、已发布的 JSON Schema 和实时 MCP 模式。
一个共享核心，附带 CLI 和四个任务级 MCP 工具。
Related MCP server: MCP Data Integration Server
开发环境检出：
git clone https://github.com/tetracoralla/BatchTicket.git
cd BatchTicket
uv sync --frozen --extra dev
uv run adt inspect examples/users.json --select 'data.users[*]'
uv run adt inspect examples/users.json --select 'data.users[*]' \
--target-schema target.schema.json --mappings mappings.json
uv run adt transform examples/adults.plan.yaml
uv run adt transform examples/adults.plan.yaml --dry-run
uv run adt validate examples/users.json --select 'data.users[*]' \
--assertions examples/users.assertions.json
ADT_WORKSPACE_ROOT=/absolute/granted/workspace uv run adt mcp构建一个无需仓库、uv、Python 安装或运行时网络连接的平台特定插件：
uv run python scripts/build_plugin.py
uv run python scripts/probe_plugin.py \
dist/plugin/data-transformer-0.2.0-darwin-arm64
codex plugin marketplace add dist/plugin
codex plugin add data-transformer@data-transformer-local构建产物会生成一个插件目录、一个 .tar.gz 归档文件以及 dist/plugin/ 中的 SHA-256 校验和。请安装或复制完整的生成目录；仓库根目录下的 .mcp.json 是开发配置，而生成的插件内的 .mcp.json 会直接调用其打包的可执行文件。生成的本地 marketplace 会让 Codex 指向该自包含目录。使用 --replace 重新构建时，会拒绝符号链接的输出根目录或已生成的输出目标，然后才删除或覆盖任何内容。
生成的独立捆绑包目前是本地验证工件，而非公开发布资产。它包含 Python 运行时、Python 包和原生库，其第三方许可材料尚未整合进归档文件中。请勿将插件目录、归档文件或校验和上传到 GitHub Release。这不限制发布或使用 Apache-2.0 源码仓库；请参阅发布检查清单。
示例转换以内联方式返回两条记录，并通过 execution_effects 报告有一行输入被移除。文件输出通过 output.path 选择性启用；除非 output.overwrite 显式为 true，否则不会覆盖已有文件。
CLI 路径是显式用户路径，可以是绝对路径。MCP 路径是一项更窄的能力：服务器首先使用通过 MCP roots 协议授予的工作区。当授予多个 roots 时，会自动选择一个；当授予多个 roots 时，请在工具的可选 workspace 字段中传入其确切的 root name。不支持 roots 协议的主机可以传入显式的 ADT_WORKSPACE_ROOT 作为兼容性授权。工具路径保持相对于所选 root，并且会拒绝绝对路径、父目录、URI 和符号链接逃逸。纯内联的 MCP 调用不需要工作区授权。
Codex CLI 0.148 目前不会将 MCP roots 传递给本地插件服务器。要进行冷启动 CLI 主机测试，请将 ADT_WORKSPACE_ROOT 设置为确切的测试工作区来启动 Codex。只读工具可以在 approval=never 下运行；data_transform 具有条件性文件输出能力，因此即使某次特定调用内联返回数据，也需要具备批准能力的主机策略。被阻止的调用属于授权结果，而不是回退到 shell 或模型侧数据重写的许可。
data_inspect 接受可选的 target_schema 和 mappings 对象。它可以基于结构性证据选择唯一的嵌套记录集，建议精确或规范化名称匹配，并展示不兼容、缺失、重复、省略或丢弃的字段。它不使用模糊同义词、类型转换或默认值。v1 适配器映射顶层记录字段，并支持对象模式或 items 为单一对象模式的数组。组合/引用模式以及不明确的记录集将保持显式未解析状态。
当每个必填字段都有显式的兼容映射时，adaptation.status 为 ready，且 adaptation.draft_plan 是一个常规的 Transformation Plan v1。请通过 data_transform 运行该计划；适配器不会创建单独的执行路径或第五个公共工具。
from data_transformer import DataTransformer
result = DataTransformer().transform(
{
"version": "1",
"sources": {"rows": {"inline": [{"x": 2}, {"x": 4}]}},
"steps": [
{
"op": "derive",
"field": "doubled",
"expr": {"multiply": [{"field": "x"}, {"value": 2}]},
}
],
}
)公共调用返回 status: ok、status: dry_run 或 status: error，并带有稳定的错误码。公共调用不会泄露堆栈跟踪或 DuckDB 内部信息；运行时观察到的变更会通过 execution_effects 报告。
请参阅产品模型、Transformation Plan v1 和评审契约。贡献方式见 CONTRIBUTING.md，安全报告见 SECURITY.md，重要变更见 CHANGELOG.md。
Compare two structured datasets by schema and rows, optionally using stable key fields. Returns compact added, removed, and changed counts and samples.
| Name | Required | Description | Default |
|---|---|---|---|
| left | Yes | ||
| right | Yes | ||
| limits | No | ||
| workspace | No | ||
| key_fields | No | ||
| sample_rows | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about the output being 'compact' and that it 'returns added, removed, and changed counts and samples', which goes beyond annotations. There is no contradiction, and the description adds value by clarifying the behavioral output characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the purpose and includes the key optional parameter (key fields) and the output nature. Every phrase earns its place, with no redundancy or fluff. This is ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters including complex source objects (PathSource/InlineSource) and a limits model, but the description does not mention that sources can be paths or inline, nor the limits concept. However, the schema provides rich detail on these, and the output is described. Given no output schema, the description covers the return format adequately. The main gap is not explaining how sources are specified, but the schema covers that, so a moderate score is fair.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description explicitly mentions 'stable key fields' matching the key_fields parameter and 'compact counts and samples' relating to sample_rows. However, it does not explain the left/right source objects, limits, or workspace parameters. The description adds some meaning but not enough to fully compensate for low coverage; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Compare two structured datasets by schema and rows' with 'optional stable key fields', and specifies the output as 'compact added, removed, and changed counts and samples'. This is a specific verb+resource combination that distinguishes it from siblings like data_transform (transforms), data_inspect (inspects), and data_validate (validates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when two datasets need comparison, but it does not explicitly mention when not to use it or name alternatives. Sibling tools are obvious from their names, but the description could have added context about when to choose this over data_inspect or data_validate. Still, the purpose is clear enough that a moderate score is warranted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect JSON, JSONL, CSV, TSV, YAML, or Parquet shape, types, counts, and a small sample without returning the full payload. Use for 'what fields are in this data?' or unknown tool output. Optionally compare record fields with target_schema and return deterministic mapping candidates; a draft plan is returned only after explicit mappings are supplied. One successful call is sufficient for its recorded observations; never repeat the same arguments to confirm it.
| Name | Required | Description | Default |
|---|---|---|---|
| limits | No | ||
| source | Yes | ||
| mappings | No | ||
| workspace | No | ||
| sample_rows | No | ||
| target_schema | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the read-only/idempotent annotations by adding key behavioral details: no full payload returned, deterministic mapping candidates, draft plans only after explicit mappings, and a note that one successful call is sufficient for observations. These are meaningful traits not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the core purpose, and every sentence adds valuable context: formats, outputs, use cases, optional mapping behavior, and idempotence caution. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's main purpose, use cases, and special behaviors well. It lacks detail on certain parameters (limits, workspace) and the two source variants, but for a read-only inspection tool with clear annotations, the provided context is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It meaningfully explains target_schema and mappings, and implies sample behavior via 'small sample,' but it leaves limits, workspace, and source structure (path vs inline) undocumented. This is a partial but not full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool inspects multiple data formats (JSON, JSONL, CSV, TSV, YAML, Parquet) and returns shape, types, counts, and a small sample without returning the full payload. It also clearly distinguishes itself from sibling tools by specifying its use case: 'what fields are in this data?' or unknown tool output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance ('Use for...') and a strong behavioral instruction ('never repeat the same arguments to confirm it'). While it doesn't explicitly name alternative sibling tools as exclusions, the use case framing makes it clear when inspection is appropriate versus transform/validate/diff.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transform or rewrite records: reshape, filter, join, aggregate, cast, flatten, or convert structured data with Transformation Plan v1. Do not use this tool for a validation-only request such as checking non-null or unique fields; use data_validate. Known transformation shape: {"version":"1","sources":{"input":{"path":"users.json","select":"data.users[*]"}},"steps":[{"id":"filtered","op":"filter","source":"input","where":{"field":"age","gte":18}},{"op":"select","source":"filtered","fields":[{"field":"userId","as":"id"}]}],"return":{"mode":"auto"}}. Omit workspace with ADT_WORKSPACE_ROOT; otherwise it is an exact granted root name, never a path. Returns a compact sample and explicit execution effects; large results require output.path.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | Yes | ||
| dry_run | No | ||
| workspace | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the description's job is to add value beyond them. It does: it discloses that the tool 'Returns a compact sample and explicit execution effects,' warns that 'large results require output.path,' and explains workspace variable behavior (ADT_WORKSPACE_ROOT). Crucially, the description is consistent with the annotations—the described rewrite/transform behavior aligns with destructiveHint=true, so there's no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but justifiably so given the tool's complexity—a full transformation DSL. It front-loads the purpose, uses a crisp exclusion, and packs workspace semantics and return behavior into tight sentences. The embedded JSON example is bulky but earns its place. It loses one point for the dense JSON blob being potentially hard to scan, but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 top-level params, a huge nested schema (19 step types, multiple assertion types), and no output schema, the description covers the most critical gaps: workspace pathing rules, large-result handling (output.path), the full plan shape, and the validation sibling's boundary. It's slightly shy of a 5 because the 'compact sample and explicit execution effects' return semantics are never detailed, and error/limit behaviors aren't addressed—leaving some burden on the agent despite the otherwise strong guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate, and it does extensively: it embeds a complete Transformation Plan v1 JSON example showing versions, sources with path/select, steps (filter with condition, select with aliases), and return mode. It also explicitly documents the workspace parameter semantics and the output.path behavior for large results. This is exactly the burden-shifting the rubric requires when the schema provides no narrative.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb phrase — 'Transform or rewrite records: reshape, filter, join, aggregate, cast, flatten, or convert structured data with Transformation Plan v1' — clearly naming the resource (Transformation Plan v1) and listing concrete operations. It differentiates from siblings by explicitly excluding validation tasks ('Do not use this tool for a validation-only request'). This is a strong purpose statement for a tool whose name alone would be ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit when-not-to-use directive with a named alternative: 'Do not use this tool for a validation-only request such as checking non-null or unique fields; use data_validate.' It also provides workspace usage guidance ('Omit workspace with ADT_WORKSPACE_ROOT; otherwise it is an exact granted root name, never a path') and large-result handling. This matches the exemplar behavior in the rubric—clear exclusion plus named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate or check requirements on existing structured data (校验/检查非空、唯一、类型、字段或行数); choose data_validate, not data_transform, for validation-only requests. It accepts JSON Schema and deterministic assertions and returns valid true or false without rewriting the source. Known validation shape: {"source":{"path":"users.json","select":"data.users[*]"},"assertions":[{"type":"not_null","field":"userId"},{"type":"unique","field":"userId"}]}.
| Name | Required | Description | Default |
|---|---|---|---|
| limits | No | ||
| schema | No | ||
| source | Yes | ||
| workspace | No | ||
| assertions | No | ||
| sample_rows | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful context by stating it 'returns valid true or false without rewriting the source' and that assertions are deterministic, reinforcing that validation has no side effects. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and usage guidance, and the three sentences are efficient. The JSON shape example is practical and earns its place, though it slightly lengthens the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 6-parameter tool with no output schema, the description covers the main purpose, sibling differentiation, side-effect-free behavior, and return type. Yet optional parameters like limits, workspace, and sample_rows are not addressed, so the description is not fully complete despite the rich input schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It provides a concrete validation shape for source and assertions, and enumerates assertion type names, giving real semantic value for the core parameters. However, other parameters such as limits, workspace, and sample_rows are not described, leaving clear gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Validate or check requirements') and clearly identifies the resource ('existing structured data'). It enumerates supported check types (non-null, unique, type, field, row count) and explicitly distinguishes from a sibling tool ('choose data_validate, not data_transform'), which is strong differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit usage rule: 'choose data_validate, not data_transform, for validation-only requests.' This named alternative and clear when/when-not guidance meets the highest bar, even though it does not mention data_inspect or data_diff.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0data_diffdata_inspectdata_transformdata_validateScored across 4 tools
Each tool occupies a cleanly separated role: observe (inspect), modify (transform), check (validate), and compare (diff). The overlap risk between transform and validate is explicitly addressed with cross-references steering agents to the right tool. No ambiguity remains after reading the descriptions.
All tools follow the exact data_<verb> pattern in snake_case with uniform imperative verbs: transform, inspect, validate, diff. The convention is fully predictable with zero deviation.
At 4 tools, the surface is tightly scoped with no bloat, comfortably within the ideal range for a focused data utility. Every tool earns its place within the read/validate/write/compare lifecycle.
Core workflows are fully covered: reading, transforming/writing output, validating, and diffing data, with output paths already handled by the transform tool. Minor gaps like an explicit export/delete or data source listing tool prevent a perfect score, but agents can accomplish all primary tasks.
Remote MCP: JSON repair, JSON Schema validation, JSON to TypeScript, CSV to JSON and JSON to CSV.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
JSON Schema validator for API payloads via MCP: bounded checks and structured pass/fail errors.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
