tokentrust

安装

TokenTrust 提供两种互补且同等重要的发行版本：适用于 Node.js 工具链的 npm 包，以及适用于 Python 工具链的 PyPI 包。两者都会安装一个 tokentrust 命令，提供完全相同的 CLI 功能、TT01-TT05 验证类别和内置任务语料库，因此选择与你现有技术栈相匹配的版本即可。

npm（Node.js）：

npx tokentrust-cli verify --proxy rtk

无需克隆，也无需本地构建。npx 会获取已发布的包并直接运行。若要将其作为依赖项安装：npm install -g tokentrust-cli。

pip（Python）：

pip install tokentrust-cli
tokentrust verify --proxy rtk

Python 包的完整文档请参阅 python/README.md，其中还说明了两者之间唯一实际的行为差异：npm 包的 js-tiktoken 依赖项内置了分词器数据，可完全离线使用；而 Python 包的 tiktoken 依赖项会在首次使用时获取并缓存相同的公开数据。

使用该命令针对本仓库内置任务语料库运行后，得到的实际输出：

$ npx tokentrust-cli verify --proxy rtk

TokenTrust v0.1 -- Token/Context-Reduction Claims Verification
Proxy: rtk 0.43.0 | Repo: TokenTrust | Task corpus: 23 labeled tasks

[MEASURED] TT01 Compression Ratio
  Claimed (rtk README): up to 70% context reduction
  Measured (this repo, this corpus): 60.6% average reduction across 23 tasks
  Range: 0.0% ("verify-go-build-filter") to 95.4% ("verify-git-log-filter")

[MEASURED] TT02 Cost-Savings Delta
  Baseline (uncompressed): $0.02 across 23 tasks @ claude-5-sonnet pricing
  Compressed (rtk-proxied): $0.00 across 23 tasks
  Actual savings: 77.0% ($0.01) -- vs. claimed 70% ceiling

[FAIL]  TT03 Never-Worse Output Guard
  2/23 tasks regressed in task-completion diff vs. uncompressed baseline

[PASS]  TT05 Version-Drift Regression Check
  No prior verified baseline for rtk on this repo -- this run establishes the first baseline.

Summary: 77.0% measured cost savings (claimed: up to 70%) -- see full report

这是实际运行的输出，并非手动输入的示例——npx tokentrust-cli 会调用完全相同的 dist/cli.js 入口点（tokentrust 命令名称不变），因此无需克隆，即可在你的机器上复现。

测量内容

• TT01：压缩率。 使用本地分词器（js-tiktoken）测量语料库中每项任务的实际 Token 缩减量。
• TT02：成本节省差值。 根据已公布的模型定价，使用 TT01 测得的 Token 差值计算成本节省。可选的 --live 模式会通过真实的、由服务商计费的样本验证估算值（需主动选择、使用你自己的 API 密钥，并通过 --confirm-cost 确认；默认最多处理 5 项任务）。
• TT03：输出不劣化保护。 检查代理压缩后的输出是否删除了任务要求保留的内容。
• TT04：跨工具对比基准测试。 多次传入 --proxy，TokenTrust 就会将相同的任务语料库并行交给每个指定的代理运行。
• TT05：版本漂移回归检测。 将一次运行测得的节省量与相同代理和仓库组合的上次验证基线进行比较，从而自动发现版本升级时出现的隐性回归（例如 rtk#582）。

命令

tokentrust verify --proxy <name> [options]

标志	描述
--proxy <name>	要验证的代理。可重复传入多次，以运行 TT04 跨工具比较。支持：rtk、headroom。必填。
--repo <path>	用于测量的代码库。默认为当前目录。
--tasks <file>	任务语料库 YAML 文件。默认为捆绑的 23 项任务语料库。
--live	为第一个代理采样真实的、按服务商计费的 Token，而不是根据定价表估算。需要 --confirm-cost。
--confirm-cost	确认 --live 在进行任何真实 API 调用之前显示的预估费用。
--live-max-tasks <n>	在 --live 模式下采样的最大任务数。默认为 5。
--format <terminal|json>	报告输出格式。默认为 terminal。
-h、--help	显示帮助信息并退出。

此表（以及下文的 tokentrust mcp 参考内容）已根据已发布的 tokentrust-cli 软件包的实际 --help 输出进行验证，而非依据旧版本副本。实际 --help 文本与上表之间已知的一处差异会在 FAQ 中直接说明， 而不是悄悄重复。

--format json 会以结构化数据提供每个类别的声称值与实测值，因此脚本或 Agent 可以使用 jq 直接提取比较结果，无需解析终端文本：

运行完成且没有触发阻断失败时，退出代码为 0，否则为非零。捆绑的 GitHub Action 中的 --fail-on-regression 会直接将其映射为失败的 CI 步骤，因此版本漂移导致的回归会中断构建，而不会悄然发布。

使用捆绑的 GitHub Action（action/action.yml）将其添加到 CI，这样每当代理版本升级时都会自动重新运行验证：

- uses: RudrenduPaul/TokenTrust-CLI@main
  with:
    proxy: rtk
    fail-on-regression: 'true'
    cli-version: '<pin to the exact tokentrust-cli version you have verified against>'

请显式固定 cli-version，不要依赖 Action 的默认值。此 Action 刻意不支持将 latest 用于此输入：固定版本是供应链防护措施，因此 npm 发布遭到入侵时，攻击者无法在下一次运行时触及所有使用此 Action 的工作流，除非你主动升级版本。此输入在 Action 中的默认值是早期的、尚未包含 TT04/TT05/MCP 的版本—— 省略 cli-version 会运行这个旧版本，而非本文档所述的版本。

面向 Agent / MCP

TokenTrust 与 Semgrep、Trivy、Snyk 和 SonarQube 一样，以 CLI + MCP 服务双模式提供：一个二进制文件、一个底层验证引擎，以及一个面向使用 MCP（模型上下文协议） 而非 Shell 的 Agent 的轻量级入口。tokentrust mcp 会通过 stdio 启动 MCP 服务，暴露一个名为 verify_proxy_savings 的工具，该工具直接调用 tokentrust verify 使用的同一个 runVerify() 引擎——不会重复实现验证逻辑，且该工具返回的正是 --format json 已生成的结构化 JSON 报告。

npx tokentrust-cli mcp

在 MCP 客户端中注册

在客户端的服务配置中，将此二进制文件指定为参数 mcp。适用于 Claude Code、 Claude Desktop，以及任何读取 mcpServers 块的其他客户端：

{
  "mcpServers": {
    "tokentrust": {
      "command": "npx",
      "args": ["tokentrust-cli", "mcp"]
    }
  }
}

工具

字段	描述
verify_proxy_savings	工具名称。与 verify 的标志一一对应，但不包括 --format——MCP 调用始终面向机器，因此该工具始终返回结构化 JSON 报告。
proxy（必填）	单个代理名称（"rtk"）或数组（["rtk", "headroom"]），用于在一次调用中运行 TT04 跨工具比较。支持：rtk、headroom。
repo	与 --repo 相同。默认为 MCP 服务进程的当前工作目录。
tasks	与 --tasks 相同。默认为捆绑的任务语料库。
live / confirmCost	与 CLI 相同的 --live/--confirm-cost 安全门：除非在同一次调用中明确将两者都设为 true，否则不会发起会产生费用的实时 API 调用。两者的默认值都不是 true。
liveMaxTasks	与 --live-max-tasks 相同。默认为 5。

这是工具实际的、未经编辑的 tools/list 架构，抓取自正在运行的 tokentrust mcp 服务（为节省篇幅，此处删去了 inputSchema 中各字段的描述；运行中的服务会完整返回这些描述）：

{
  "name": "verify_proxy_savings",
  "title": "Verify proxy token/cost savings",
  "inputSchema": {
    "type": "object",
    "properties": {
      "proxy": { "anyOf": [{ "type": "string", "enum": ["rtk", "headroom"] }, { "type": "array", "items": { "type": "string", "enum": ["rtk", "headroom"] }, "minItems": 1 }] },
      "repo": { "type": "string" },
      "tasks": { "type": "string" },
      "live": { "type": "boolean" },
      "confirmCost": { "type": "boolean" },
      "liveMaxTasks": { "type": "integer", "exclusiveMinimum": 0 }
    },
    "required": ["proxy"]
  }
}

对此仓库执行实际的 tools/call，即 {"name": "verify_proxy_savings", "arguments": {"proxy": "rtk"}}，会返回与 CLI 的 --format json 输出相同的结构（此处已精简；运行中的调用会返回包含 TT01/TT02/TT05 条目的完整 records 数组）：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"run_id\": \"tt_2026-07-18_f88644\",\n  \"repo\": \"...\",\n  \"task_corpus_size\": 23,\n  \"proxies\": [\"rtk\"],\n  \"records\": [ /* TT01, TT02, TT05 -- same shape as `verify --format json` */ ],\n  \"tt03\": { \"rtk\": { \"pass\": false, \"regressed_count\": 2, \"task_corpus_size\": 23 } },\n  \"tt05\": { \"rtk\": { \"pass\": true, \"message\": \"No regression vs. last-verified rtk 0.43.0 baseline (stored 2026-07-18).\", \"prior_run_id\": \"tt_2026-07-18_608b74\", \"degraded\": false } }\n}"
    }
  ],
  "isError": false
}

只要底层的 runVerify() 调用本身在 CLI 中会以非零状态码退出，isError 就会为 true（且不附带报告）；例如代理二进制文件缺失、任务语料库无效，或 --live 安全门拒绝确认不足的调用。在 MCP 模式下，进度输出以及 tokentrust verify 通常打印到 stdout 的跟踪日志会改为输出到 stderr，因为连接 stdio 传输后，stdout 就是实时 JSON-RPC 通道。

代理支持

代理	状态
rtk	完全支持：基于真实子进程的验证（对 stdin 形式的任务使用 rtk pipe --filter <name>，对基于文件的任务使用 rtk read -l aggressive <files>）。
headroom	可识别（--proxy headroom 是有效的标志值），但尚不支持。headroom 是 HTTP 代理服务，而不是一次性压缩 CLI，因此当前基于子进程的测试框架无法驱动它。tokentrust verify --proxy headroom 会打印一条消息并跳过它，而不是静默失败。

对比

	作用	持续运行／自行使用	验证特定主张
TokenTrust	使用带标签的任务语料库运行指定代理，测量实际压缩率、成本和输出质量回退，并显示声称值与实测值	是，可在你自己的 CI 和代码仓库中运行，每次代理版本升级时都能运行	是，这正是它的全部意义
tokbench	对 rtk、headroom 和 lean-ctx 在真实 Agentic SDLC 任务上的独立试点基准测试，提供原始记录和预注册协议	否，是针对单个代码仓库的试点报告，复现工作正在进行	是，而且严谨：该肯定的地方就肯定
Langfuse、Vantage、Finout、Amnic、Revenium	LLM／AI 成本可观测性和 FinOps。跟踪你在不同模型和提供商上的实际 API 支出，并将其分摊到各团队	是，提供托管或可自托管方案，可持续运行	否，这些工具跟踪的是你的支出；它们不会核查某个特定代理声称的具体节省是否成立

tokbench 是最接近的先行项目，值得真正肯定。它严谨且公开透明，但其试点范围比初读时看起来更窄：一个代码仓库、一个任务、每组 N=1，复现工作正在进行。值得直接阅读它在该试点中的原始数据。以 2.28M token 的原生基准为参照，提供商计费的输入 token 数分别为：rtk 2.89M（+27%），headroom 3.24M（+43%；尽管 headroom 确实将线上传输的 token 压缩了 342K）。这是因为即使每轮的负载变小，Agent 的轮数仍然增加。这是一个真实且独立有用的数据点，也正是 TokenTrust 要在你自己的代码仓库中持续捕捉的“已压缩”与“更便宜”之间的差距，而不只是在单次公开试点中捕捉。

为什么要做这个项目

上下文缩减代理（rtk、headroom 等）会在自己的 README 中发布压缩率和成本节省数据。这些数据来自维护者自己的基准测试，针对维护者自己的工作负载，而且没有项目之外的人核查计算过程。这并非指责，只是这个领域的代理目前都以这种方式报告自己的数据；维护者对自己的工具进行基准测试，并不等于进行了对抗性测试。

这些代理自己的 issue 跟踪器中就能看到这一差距：

• rtk#839，一个公开的实证基准测试讨论串，涵盖 5 个代码仓库、2,100 次测量，探讨 rtk 的实际节省与其声称值相比如何。
• rtk#1935，“rtk gain 幻觉出大量 token 使用量和节省”（公开）。
• rtk#582，“RTK Hook 使 Claude Code 成本增加 18%”，这是维护者自己的测试套件未能发现的成本回退。TT05 的存在，就是为了在用户发现之前捕捉这类回退。

TokenTrust 不与这些代理竞争，而是对它们进行验证。无论代理声称的数据是否经得起检验，TokenTrust 都没有利益关系；每次运行类别测试时，都会将声称值与实测值并列显示，因此比较结果绝不会被隐藏或平均掉。

我们还发现并修复了自己测量中的一个错误：某个测试夹具的基准值意外地使用了 git log --oneline 捕获，而不是真正的原始 git log，导致该任务低估了 rtk 约 42 个百分点的实际压缩率。诚实地重新捕获后，verify-git-log-filter 现在测得 95.4%，是语料库中最高的缩减率，而且是真实的。提交 e42246c 修复了这个问题——每个测量数据在发布前都有对应的测试夹具运行记录。同一提交还将语料库从 15 个任务扩展到当前的 23 个任务，这就是为什么上方的实际运行输出写着“23 个带标签的任务”，尽管仍有一处遗留的帮助字符串提到了旧数量（参见常见问题）。

什么是 TokenTrust？它为何存在？

TokenTrust 是一款命令行工具，用于衡量 AI 编码 Agent 上下文缩减代理所宣称的 token 和成本节省，在使用本地分词器而非电子表格估算的情况下，能否经得起真实标注任务语料的检验。它之所以存在，是因为压缩代理目前会自行报告节省数据，而在采用某个代理之前，缺乏独立、可重复且原生支持 CI 的验证方式。TokenTrust 本身不是代理，也不会压缩任何内容。它负责验证那些会进行压缩的代理。

真实场景验证

TokenTrust 自身的验证工作已经反馈到一个真实、由独立方跟踪的 GitHub issue：rtk-ai/rtk#1313（由 @ChrisEdwards 提交，要求 rtk 提供仅无损模式，并如实说明截断在 Agent 上下文中造成的静默失败）。最初的验证结果显示，rtk 现有机制只部分解决了该问题，因为 TokenTrust 自身的测试样例当时还没有足以证明问题是否解决的质量标记。为 TokenTrust 的三个 pipe --filter 测试样例补充真实且经过验证的质量标记，弥补的是 TokenTrust 自身测试能力的缺口，而不是 rtk 的缺口；这也让该工具能够通过真实的 rtk 0.43.0 二进制文件，而非仅凭声明，确认 rtk 现有的“绝不变差”保护机制已经实现了 issue 的要求。由此，该 issue 的结论从部分解决转为真正经过重新验证的通过。TokenTrust 从未触及 rtk 自身的代码库；它只是变得足够精确，能够证明 rtk 中早已成立的事实。

Python 软件包

pip install tokentrust-cli 安装的是作为真正 Python 移植版的同一款 tokentrust CLI，而不是 Node 二进制文件的封装：真实的 Python 源代码位于 python/src/tokentrust/，拥有自己的 pytest 测试套件，并将完全相同的 23 个任务语料原样复制到 wheel 中。两个发行版本都运行相同的 cl100k_base 分词器编码，并已通过真实样本文本验证，确保生成的 token 数量完全一致；今后也会共同维护，包括 tokentrust mcp：Python 移植版提供与 npm 软件包相同的 verify_proxy_savings MCP 工具，且线上 schema 逐字节一致（参见 python/README.md 中的“Agent-native / MCP”部分）。安装说明请参见 python/README.md，操作指南请参见 python/docs/getting-started.md，两款软件包共用的验证方法请参见 python/docs/concepts.md。

常见问题

什么是 TokenTrust？它与 rtk 或 headroom 这类上下文缩减代理有何不同？ TokenTrust 本身不是代理，也不会压缩任何内容。它是一个独立于厂商的验证层：它会将 rtk 或 headroom 这类代理作为真实子进程，在固定且经过标注的 23 个任务语料上运行；使用本地分词器测量实际节省的 token 和金额，并将测量结果与代理自身 README 中宣称的数据并列输出。其区别在于独立性：TokenTrust 不会因代理宣称的数据是否经得起检验而获利，因此绝不会通过平均差值来掩盖差异。

TokenTrust 可在哪些平台上运行？npm 和 PyPI 软件包是同一款工具吗？ 两者都是同一款工具的独立维护移植版，并非一方封装另一方。npm install -g tokentrust-cli（或 npx tokentrust-cli）安装 Node.js 版本；pip install tokentrust-cli 安装真正的 Python 移植版，代码位于 python/src/tokentrust/，并拥有自己的 pytest 测试套件。两者都提供相同的 tokentrust 命令、相同的 TT01-TT05 类别、相同的内置任务语料，以及相同的 cl100k_base 分词器编码。 TokenTrust 能否直接与 AI Agent 配合使用，而不只是从 shell 中使用？ 可以。tokentrust mcp（或 npx tokentrust-cli mcp）会通过 stdio 启动 MCP（Model Context Protocol）服务，并提供一个工具 verify_proxy_savings，该工具由 CLI 使用的同一 runVerify() 引擎提供支持。任何兼容 MCP 的客户端（包括 Claude Code 和 Claude Desktop）都可以调用该工具，并获得与命令行生成的 --format json 相同的结构化 JSON 报告。

TokenTrust 与另一个独立代理基准测试 tokbench 相比如何？ tokbench 是实实在在的先行工作，值得肯定：它开展了一项严谨且公开披露的试点，提供原始转录记录，并预先注册了测试协议。目前的范围比初看时更窄：只有一个代码库、一项任务，每个实验组 N=1，正在进行复现工作。相比之下，TokenTrust 会持续运行一个包含 23 项任务的语料库，每次代理版本更新时，都会在你自己的 CI 和代码库中运行，而不是只发布一份试点报告。

npm 包中的 tokentrust verify --help 文本称默认任务语料库有 15 项任务。哪个才是正确的，15 项还是 23 项？ 正确的是 23 项。提交 e42246c 将内置语料库从 15 项扩展到了 23 项。每次实际运行（npm 和 PyPI 均如此）都会在输出顶部报告“任务语料库：23 项已标注任务”，与实际的 fixtures/tasks.yml 文件一致。npm 包的 --tasks 标志帮助文本沿用了扩展前的旧字符串，尚未更新为 23；PyPI 包的帮助文本则已正确显示 23。这只影响 --help 文本的显示内容，不影响 CLI 实际运行的任务。

如果 pip install tokentrust-cli 在我的 Python 版本上安装失败，该怎么办？ PyPI 包在其 pyproject.toml 中声明了 requires-python = ">=3.10"，因此 pip 会拒绝在 Python 3.9 或更早版本上安装。请升级到 Python 3.10、3.11、3.12 或 3.13（该包经过这些版本的测试），或者改用 npm 包，它只要求 Node.js 18 或更高版本。

我可以将 TokenTrust 用于商业用途吗？需要注明出处吗？ 可以。TokenTrust 采用 Apache-2.0 许可证（见 LICENSE），允许商业使用、修改和分发，包括用于闭源产品；但你必须保留许可证和版权声明，并注明对源代码所做的任何更改。

TokenTrust 会修改我的代码或代理的压缩输出吗？ 不会。它会针对固定任务将代理作为真实子进程运行，捕获并测量输出。它不会更改你的代码库或代理配置。

TokenTrust 能否核验代理的实时供应商计费费用，而不是估算费用？ 可以，使用 --live --confirm-cost 即可。默认情况下，它通过 --live-max-tasks 将任务数上限设为 5 项。它会使用你自己的 API 密钥，并且绝不会在事先未显示预估费用的情况下产生实际费用。

TokenTrust 可以作为库导入吗，还是只能通过 CLI 使用？ 目前只能通过 CLI 使用。npm 包和 PyPI 包都没有提供有文档说明、可导入的公共 API：npm 的 package.json 列出了一个 main 条目，但它指向的文件实际上并未包含在已发布的包中；PyPI 包的顶层模块只导出了一个版本字符串。请使用 tokentrust 命令或 verify_proxy_savings MCP 工具；目前还没有受支持的方式可以直接 import/require 该包的核验逻辑。

贡献

请参阅 CONTRIBUTING.md，了解项目结构、如何添加核验类别或固定任务，以及 npm 和 PyPI 包中对每项类别变更的覆盖率要求。

许可证

Apache-2.0。见 LICENSE。