BatchTicket

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: Trace MCP

安装与运行

开发环境检出：

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 运行该计划；适配器不会创建单独的执行路径或第五个公共工具。

库 API

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。