TokenScope：可视化AI Agent的Token消耗分布

你能看到你的云账单，能看到 CI 分钟数一点点消耗。但 AI Agent 应用中增长最快的支出项，恰恰是你在每次模型调用中看不到的：你的 Agent 上下文究竟价值多少 token。

它之所以看不见，是因为从来不会以一笔大额账单的形式出现。它是几千个 token，在一天内被重复发送数百次，在悄然叠加。等到它在账单上变成一个具体的数字时，它已经融入你发出的每一个请求之中。

下面教你如何在十秒内看清这个数字——无需账号、无需日志、无需配置：

npx @wartzar-bee/tokenscope scan .

将它指向存放 Agent 的 prompt、工具和配置的目录。它会打印出 token 占用量以及相关文件：

tokenscope scan — src
Estimated token footprint: 8,454 tokens across 6 files
(estimate ≈ 4 chars/token — a tokenizer-free proxy for relative comparison, not a billing figure)

Top files by estimated tokens:
      2991  share.mjs
      2134  scan.mjs
      1092  core.mjs
       835  report.mjs
       718  pricing.mjs
       684  benchmark.mjs

这才是关键所在：排名第一的文件通常是系统 prompt、工具 schema，或者是某人"以防万一"塞进去的大量 few-shot 示例。现在你可以看清是哪一个、重量几何，而不是等它已经成为每次调用的一部分之后才追悔莫及。

为什么这个数字会咬人

大多数 Agent 框架在每一步都会重新发送累计的上下文——记忆、历史、工具定义，一股脑儿全带上。所以一个重 2,000 token 的 prompt，不是单次成本，而是 2,000 token × 每次调用 × 每个用户。单次调用的日志看起来很正常，月度账单就不是那么回事了。（我曾亲眼看到一个跑在定时器上的 Agent 一夜之间烧掉 136M token，几乎什么都没做——根本原因如出一辙。）

tokenscope 给你一个单一、可复现的占用量数字，让"我们就往 prompt 里加这个"的 PR 不再是不可见的黑洞。

1. 临时急用，立刻上手——在发布 prompt 变更前，测量任意仓库：

npx @wartzar-bee/tokenscope scan ./agent

2. 作为本地成本门禁——如果占用量超过预算就让提交失败，这样失控的 prompt 永远不会离开你的机器：

# .git/hooks/pre-push  (chmod +x)
npx @wartzar-bee/tokenscope scan . --max-total 50000 || {
  echo "Context footprint over budget — trim it before pushing."; exit 1;
}

用的是 pre-commit 框架？四行配置就搞定——无需写 hook 脚本。

3. 在每个 PR 中、CI 层面——同样的检查，作为 GitHub Action 运行，在相关文件上评论 token 成本增量，并（可选地）阻止合并：

- uses: wartzar-bee/ci-guardrail@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    mode: warn   # report-only until you trust it; switch to block later

这就是 ci-guardrail——将 tokenscope 接入你的流水线。

运行它：npx @wartzar-bee/tokenscope scan .

npm：@wartzar-bee/tokenscope

源码（Apache-2.0）：github.com/wartzar-bee/tokenscope

它是免费、开源、无需 tokenizer 的——提供的是用于相对比较的估算值，而非计费权威，所以你可以在任何代码库上运行它，无需接入任何 provider SDK。如果它能帮你省下一个"为什么账单涨了 40%？"的下午，它就完成了自己的使命。