Tokenleak 发布：审计编码智能体的 token 泄漏并给出修复规则

找出并堵住你的编码代理的 token 泄漏。
不是泄露的 API 密钥：而是你的 AI 代理消耗在它并不需要的上下文上的 token。

网站 · 安装 · 审计 · 基准测试 · 规则 · Français

在 Sonnet 5 上使用规则进行 80 次 A/B 运行，成本降低 32%，通过率相同（40/40）。在 Haiku 4.5 上使用读取守卫，成本降低 20% 到 28%（两批，120 次运行）。 详情。

先试用，无需安装：十秒内查看你自己的 token 去了哪里（Python 3.8+，读取你的本地记录，不发送任何内容）。

curl -fsSL https://raw.githubusercontent.com/Pazificateur69/tokenleak/main/skills/tokenleak/scripts/tokenleak.py | python3 - --since 7d

为什么

在代理循环中，你放进上下文的每一个工具结果都会在之后的每次调用中重新发送，直到上下文被压缩。一个 6k token 的测试日志在 60 次调用会话的第 5 次调用时被读取，会被再付费约 55 次。每一次额外的往返都会重新发送整个上下文。

所以账单不是由代理有多啰嗦决定的。它是由它让什么进入上下文，以及多早进入决定的。在基准测试中不使用 tokenleak 的运行里，模型写下的所有内容（回复、工具调用、思考）在 Sonnet 上占一次运行成本的 7%，在 Haiku 上占 10% 到 11%（中位数）；其余都是上下文。更短的回复只能省下那一小部分。审计会显示你自己会话中的这种拆分。

tokenleak 做两件事：

1. 规则（一个技能，约 770 个 token），让任何编码代理只让下一个决策所需的内容进入：先定位再读取，计算而不是读取数据，限制每条命令的输出，绝不重复读取，批量处理独立调用，用差异而非文件，编辑而不是重写。带有护栏，因此它绝不会通过猜测或跳过验证来节省 token。
2. 一项审计，读取你自己的 Claude Code 和 Codex 记录，显示 token 实际去了哪里：每一次过大的读取、嘈杂的日志、浪费的调用和串行往返，按其造成的上下文税定价，并给出修复它的规则。本地、只读、零依赖。

安装

Claude Code（插件，推荐）。规则在会话开始时、压缩之后以及注入每个子代理，外加一个读取守卫：对大文本文件（超过约 24 KB）的整文件读取会被阻止，对于代码和 Markdown，代理会得到文件的大纲（带行号的定义或标题），以便它只读取所需的部分；传递 limit 总是可以通过。添加 /tokenleak 技能。用 TOKENLEAK_GUARD=0 关闭守卫，或用 TOKENLEAK_GUARD_BYTES 移动其阈值。

/plugin marketplace add Pazificateur69/tokenleak
/plugin install tokenleak@tokenleak

Codex（插件）。会话开始时使用相同规则（以及在你的 Codex 版本触发该钩子的子代理中），外加该技能：

codex plugin marketplace add Pazificateur69/tokenleak
codex plugin add tokenleak@tokenleak

然后在 Codex 中打开 /hooks 以查看并信任其生命周期钩子，并启动一个新线程。

任何支持 Agent Skills 的代理（Codex、Cursor、Gemini CLI、GitHub Copilot、Windsurf、Cline、OpenCode 以及另外 50 多个）：

npx skills add Pazificateur69/tokenleak -g

始终开启，任何代理，无需安装。将规则追加到你的指令文件中（AGENTS.md、CLAUDE.md、GEMINI.md、.cursorrules…）：

curl -fsSL https://raw.githubusercontent.com/Pazificateur69/tokenleak/main/skills/tokenleak/SKILL.md | awk '/^## Audit/{exit} f>=2; /^---$/{f++}' >> AGENTS.md

审计

# no install: Python 3.8+, stdlib only, reads ~/.claude/projects and ~/.codex/sessions
curl -fsSL https://raw.githubusercontent.com/Pazificateur69/tokenleak/main/skills/tokenleak/scripts/tokenleak.py | python3 - --since 30d

报告首先显示钱去了哪里（cost split：上下文，从缓存读取或写入缓存，与输出对比），然后按估计的上下文税为每个泄漏定价。

或者安装 CLI：uvx --from git+https://github.com/Pazificateur69/tokenleak tokenleak（或 pipx install git+https://github.com/Pazificateur69/tokenleak），或从克隆运行：python3 skills/tokenleak/scripts/tokenleak.py。或者直接问你的代理：“审计我的 token 泄漏”。

来自你自己泄漏的项目规则

cd your-project && tokenleak suggest   # or: python3 /path/to/tokenleak.py suggest

读取该项目最近 30 天的会话，并打印一段可粘贴到其 CLAUDE.md 或 AGENTS.md 中的内容，内容基于那里实际泄漏的情况撰写。示例输出（你的输出取决于你的会话）：

<!-- tokenleak suggest: 23 sessions in shop-api since 2026-09-12, leak score 11.2% -->
## Token hygiene for this repo

Keep tool output out of the context; these are this repo's biggest repeat offenders:

- `npm test` printed ~9.1k tokens per run (23x). Run it as `npm test --silent 2>&1 | tail -n 40` (iterate on the one failing test).
- `git diff` printed ~3.0k tokens per run (5x). Run it as `git diff --stat` first, then `git diff -- <path>` for the files you need.
- Large files: `src/data/catalog.ts` (~18.2k tokens, read 14x). `grep -n` them, then read only the lines you need.

只有真实存在的项目命令（测试、构建、安装、linter、git、docker）和项目中存在的文件才会进入列表。该技能会主动提出为你添加，并会先询问。

完整报告还会按泄漏评分（by project）对你的项目进行排名。

实时泄漏计量器（Claude Code 状态栏）

工作时查看当前会话的泄漏评分。添加到 ~/.claude/settings.json：

"statusLine": {
  "type": "command",
  "command": "python3 ~/.claude/plugins/marketplaces/tokenleak/skills/tokenleak/scripts/tokenleak.py statusline"
}

它会打印 leak 3.1% A · ctx 84.2k · top big-read（如果你没有安装该插件，请将路径指向 tokenleak.py 所在的位置）。

它发现了什么

它还会显示始终加载的内容：你的 CLAUDE.md / AGENTS.md / 记忆文件以及基础上下文（系统提示、工具、MCP 服务器）在每次调用时都会重新发送，并显示它们在你成本中的占比。这些不计为泄漏，但往往是最划算的优化点。

如何计算

对每个工具结果：上下文税 = 可避免的 token 数 ×（缓存写入 + 同一上下文中之后每次调用 × 缓存读取），使用各提供商的相对价格（Claude：缓存读取 0.1×，缓存写入 1.25–2×，输出 5×；Codex/GPT-5：缓存 0.1×，输出 8×）。可避免是一个估计值：只有超出合理预算的部分才计入（例如一次 6k token 的读取计为 4k 可避免），只有完全重复时才按完整大小计算。审计无法知道一次大读取是否真的必要，因此请将每条发现视为嫌疑，而非定论，并用 --compare 判断趋势。泄漏评分是此估计认定为可避免的部分占你总 token 成本的比例。金额来自 Claude Code 自身的每会话成本（如果会话在 --since 窗口之前开始，则按比例折算），绝不来自我们维护的价格表。

一切都留在你的机器上：无网络、无遥测，约 1,500 行标准库 Python，你十分钟就能读完。

基准测试

Claude Code 中的 A/B 测试（claude -p）：相同提示词，每次运行都使用同一小型仓库的全新副本。唯一的区别是 tokenleak 添加的内容：系统提示中的规则（插件注入的内容），以及在 guard 组中还有插件的读取防护。每次运行都由脚本检查：测试通过、构建通过、答案准确、功能正常。

Sonnet 5，每个任务和每组 10 次运行（两批，共 80 次运行）：

Haiku 4.5，每个任务和分支 5 次运行，两批（120 次运行）：

每次运行的 API 等效成本中位数，由 Claude Code 报告。在 Sonnet 上，上下文 token 减少 17%，输出 token 减少 11%。审计下的截图是对 20 次无规则运行的审计。

如实解读。

• 运行结果波动很大。第一批 Sonnet 给出 −40%，同一天的第二批为 −21%；表格将两批合并。单次运行波动可达 2 到 4 倍，因此请把这些当作范围来看，并在你自己的会话前后运行审计。
• Haiku 4.5 无法自行遵循规则（一个小模型，四个任务）。仅规则没有带来任何变化；读取守卫（阻止整份读取大文件）带来了 −20% 到 −28%。在 Sonnet 上，同一批次中规则 + 守卫与仅规则表现相当（−22% 对 −21%）。这就是该插件默认开启守卫的原因。
• 大纲带来的是小幅收益，而非大幅收益。在批次 2 中两个守卫并排运行：带大纲为 −28%，不带为 −25%，主要差异在数据问题上（9 次 API 调用而非 12 次，$0.077 对 $0.086）。在 5 次运行的噪声范围内；它之所以随附发布，是因为当 agent 知道自己要找什么时，它能省去一次搜索往返。
• 有一个任务被重新运行。在 Haiku 批次 2 中，fix-build 最初在所有分支中同样失败（各 3/5），因为沙箱阻止了 Apple 在 ~/Library 中的 Python 字节码缓存。测试框架现在将该缓存指向运行文件夹内，15 次 fix-build 运行已针对全部三个分支重做；表格使用的是重做后的运行。
• 速度表现不一。一次被拒绝的读取会耗费一次往返。每次运行的中位墙钟时间：在 Sonnet 上，无为 35 秒，仅规则为 31 秒，规则 + 守卫为 38 秒；在 Haiku 上，批次 1 从 27 秒变为带守卫的 37 秒，批次 2 从 32 秒变为 29 秒。
• 调优与测试保持分离。规则先经过试点（v1，30 次运行：−23%）并修改了一次：新增一条规则（计算，而非读取数据）和两处补充（先检查文件大小；串联 shell 步骤）。add-feature 任务在该修改之前就已写好，从未用于调优它们：它显示出最大的收益。
• 在一个合成仓库上的四个小任务，该仓库被构建为包含真实仓库中会泄漏的内容（一个大模块、啰嗦的日志、嘈杂的构建）。运行与你的设置、CLAUDE.md、插件和 MCP 服务器隔离（--setting-sources project --strict-mcp-config），并在沙箱中与你的个人文件夹隔离。

每次运行，连同所使用的确切规则及其按类型划分的 token 用量（以便重建成本拆分），都在 bench/results 中。2026 年 10 月，add-feature 检查器变得更严格（新增第二个类别，默认报告不变）；所有 55 次已发布的 add-feature 运行都对照它重新检查，仍然通过。复现：python3 bench/run.py --runs 5 --variants baseline,tokenleak,guard（60 次运行，在 Sonnet 上约 $13 的 API 等效用量）。

规则

完整技能见 skills/tokenleak/SKILL.md。简而言之：

1. 先定位，再读取。检查大小，grep -n，然后只读取该范围。
2. 计算，而非读取。关于数据的问题用一行命令打印答案，而不是打印数据。
3. 约束每条命令。使用安静标志；长任务写入日志文件，用 tail 读取，用 grep 挖掘。绝不要仅为看到更多而重新运行。
4. 绝不重读已在上下文中的内容。
5. 在一轮中批量执行独立调用，并在一条命令中串联 shell 步骤。
6. 用差异而非文件。git diff --stat 在 git diff 之前。
7. 编辑，而非重写。
8. 缩小搜索和获取范围。限定范围、上限、选择字段。
9. 将广泛探索委托给子代理；只返回其摘要。
10. 精简作答。先给结果，不做复述。

绝不要通过截断真实错误、猜测文件内容或跳过验证来节省 token。

常见问题

这会让代理变差吗？在基准测试中不会：每次运行都由脚本检查，各组的通过率相同（Sonnet 上 40/40，Haiku 上每批 60/60）。护栏是明确的：泄漏比错误修复代价更低。

我的代理已经做了其中一些。好的代理都会。例如 Claude Code 已经会阻止重新读取未更改的文件；审计将这些被阻止的尝试计为浪费的往返。审计告诉你的是你自己的会话中还剩多少，而不是演示中的。

ccusage 还是 tokenleak？两者读取相同的本地记录。ccusage 告诉你按天、会话或模型花了多少。tokenleak 告诉你哪些工具结果导致开销高昂并加以修补。两者配合使用效果很好。

那 rtk、caveman 及其他工具呢？互补。rtk 在 shell 层面压缩命令输出；输出风格技能缩短回复。tokenleak 改变代理请求的内容，并在你的真实记录上衡量结果。在你安装任何东西之前和之后都运行审计。

这些规则的成本是多少？约 770 个 token，每次调用都从缓存中重新发送：在一个 60 次调用的会话中，大约相当于 5.5k token 的新输入。在该会话第 5 次调用时将一份 6k token 的测试日志保持在 800 token，可节省约六倍于此的量。

局限性。单个结果的 token 大小是估算的（约 4 字符/token）；会话 token 总数来自记录中记录的用量，美元金额仅来自记录了成本的会话。“可避免”是估算，而非测量。serial-call 是一种启发式方法（它只标记目标已已知且未在上一个结果中提及的调用）。Codex 的记录格式在不同版本之间会变化；Claude Code 是测试最充分的路径。

收录于

Skills Directory（安全等级 A）。在 Claude Market 上找到更多类似工具。

贡献

欢迎提交 issue 和 PR，尤其是其他代理（Gemini CLI、Cursor、OpenCode）的记录格式以及新的泄漏检测器。测试：python3 -m unittest discover -s tests。基准测试：python3 bench/run.py --runs 5。

MIT 许可证。