Skip to main content
Glama

agent-ledger

前阵子想算一笔账:手上那几个每天定点跑的脚本,一个月到底省了我多少时间、又烧了多少钱。算了半天没算出来。

日志里有步骤,账单里有 token,权限配置在另一个文件里,三样东西对不上。这个仓库就是拿来把它们拼成一张账的。

零依赖。一份 JSONL 事件流进去,出来是终端报告、一个 HTML,或者一个能让 agent 自己查账的 MCP server。

先说为什么要算这个

起因不是看了什么趋势报告,是想算账算不出来。

我平时在给一个内容站做运维,站上跑着几个自动化:sitemap 对账、链接图、索引推送,还有一两个改稿用的脚本。这些东西平时不出声,出了事才响。问题就在这儿——它们只在失败的时候才被人看见,成功的时候花了多少、值不值,没人记。

后来我去翻公开讨论,想看看别人怎么处理这件事。翻到三类数字,都在说同一件事:

一类是关于复合错误的。单步成功率 95%,十步的任务只剩六成左右。误差会乘起来,所以任务越长越脆。

一类是关于成本口径的。"每百万 token 多少钱"这个说法正在被换掉,换成"每个完成的任务多少钱"。理由是如果一半任务最后失败,token 单价便宜没有任何意义。

一类是关于权限的。有安全调研说八成以上的 CISO 担心 AI 被过度授权,但能说清环境里到底有几种 agent 的不到一半。

(这三条是我从 2026 年 11 月的公开报道和厂商公告里读到的,属于二手转述。原始调研报告我没有逐份去核,它们在这里只是用来说明"为什么值得算",不当结论用。)

三条放在一起看,缺口很明显:大家都在说要按任务算钱、要管权限、要盯住复合错误,但没有一个工具把这三件事算进同一张表。

日志平台管 trace,计费平台管 token,权限系统管 grant,各自都挺专业,就是彼此不说话。

Related MCP server: agent-activity

这张账算三件事

一、单步成功率推不出任务成功率

这是复合错误的核心,也是我最想验证的一件事。

工具会先算单步成功率。这里有条规定要说清楚:同一个 step 如果有多条事件,只按最后一条算。所以"失败一次、重试成功"记成成功,"连着失败两次"才算失败。这条规则决定了后面所有数字,是整个分析的地基。

然后按独立假设推一个理论任务成功率,就是把单步成功率按平均步数乘方。再和实测的对比。

最后给实测值一个 Wilson 95% 置信区间。

第四步是我加得最不情愿、但最有用的一步。 八个任务跑出 62.5%,置信区间是 30.6% 到 86.3%——区间比结论本身还宽。把区间打出来这件事犹豫过,不打的话,这个数字迟早会被人拿去汇报,然后被现实打脸。

差值本身也有用。实测比理论好,说明重试和自我纠正在起作用;实测比理论差,说明错误会聚集,某一步走歪后面全歪。

二、钱花在哪,得按任务算

按 token 算的钱是没有意义的,至少对做决策没有意义。

工具输出这几个数:

  • 失败任务吃掉了多少比例的成本

  • 有效成本倍数:把失败成本摊进去后,每个成功任务的真实成本是名义成本的几倍

  • 模型维度的成本占比,和调用占比并排放

  • 最贵的两成任务占多少成本

样例数据跑出来是这样:

失败任务消耗      $0.6325    48.6% 的钱花在最终没成的任务上
名义单任务成本    $0.2604    总成本 / 成功任务数
有效成本倍数      x1.94      把失败成本摊进去之后

模型                 调用        成本      占比  调用占比
claude-opus-5.5        11     $1.0056     77.3%  40.7%
gpt-6.1-terra          16     $0.2962     22.8%  59.3%

最后两列要并排看。一个模型吃掉七成七的成本,调用次数只占四成——这时候去优化便宜模型的调用次数,纯属浪费时间,该问的是贵模型那十一次到底值不值。

三、权限给多了,多在哪

给一份 policy 文件,对照实际调用,能算出四样东西:过度授权率、从未用过的工具清单、被 policy 拦下的越权尝试次数、以及配置矛盾。

最后一项不是凑数。样例里 delete_file 同时写在 allow 和 deny 里——这种配置在改过几轮策略文件的项目里太常见了,没人记得哪条还有效。工具会直接把它标出来。

过度授权真正的意义不在"整洁"。那四个授予了但一次没用过的工具,就是注入攻击得手之后可以直接调用的现成入口。收窄权限换来的不是好看,是"出事的时候坏得少一点"。

怎么用

node bin/ledger.js data/sample-runs.jsonl --policy policy.json
node bin/ledger.js data/sample-runs.jsonl --json > out.json
node bin/ledger.js data/sample-runs.jsonl --policy policy.json --html report.html

样例数据是八个任务、六十二条事件,里面有重试、有越权被拒、有上下文超限、有测试失败。跑出来:

任务成功率            62.5%             5 成功 / 3 失败
单步成功率            93.2%             55 / 59 步
总成本                $1.3018           27 次模型调用 / 35 次工具调用

理论任务成功率        59.6%             假设每步独立:p^k
实测任务成功率        62.5%             95% 置信区间 30.6% – 86.3%
偏差                  +2.9pt            实测优于独立假设,重试在起作用

事件流的格式

每行一个 JSON,ts / run / step / type / ok 必填:

{"ts":"2026-11-17T09:12:03Z","run":"r1","task":"add-pagination","repo":"acme/api","step":1,"type":"model","model":"gpt-6.1-terra","in":11240,"out":780,"usd":0.01514,"ms":3120,"ok":true}
{"ts":"2026-11-17T09:12:11Z","run":"r1","task":"add-pagination","step":2,"type":"tool","tool":"read_file","ms":8,"ok":true}
{"ts":"2026-11-17T09:12:40Z","run":"r1","task":"add-pagination","step":3,"type":"model","model":"gpt-6.1-terra","in":12480,"out":0,"usd":0.01248,"ms":980,"ok":false,"error":"context_length_exceeded"}
{"ts":"2026-11-17T09:13:02Z","run":"r1","task":"add-pagination","step":3,"type":"model","model":"gpt-6.1-terra","in":9800,"out":640,"usd":0.013,"ms":2890,"ok":true,"retry":1}

字段

必填

说明

ts

是

ISO 8601 时间戳

run

是

一次运行的 id,同一 run 的事件归成一组

step

是

步序号,同一 run 内可以重复,表示重试

type

是

model / tool / plan / note

ok

是

这一步成不成

task

否

任务名,不给就用 run id

model / tool

看类型

model 事件填模型名,tool 事件填工具名

in / out

否

token 数

usd

否

这一步花了多少

ms

否

耗时

retry

否

填 1 表示这是重试,工具会单独算重试烧掉的钱

error

否

失败原因,用来归类

也能当 MCP server 用

node bin/ledger.js --mcp

在 Cursor、Claude Code 这类客户端里注册:

{
  "mcpServers": {
    "agent-ledger": {
      "command": "node",
      "args": ["/absolute/path/to/agent-ledger/bin/ledger.js", "--mcp"]
    }
  }
}

三个工具:ledger_summary 给概览,ledger_task 查单个任务的逐步明细,ledger_risks 出风险清单。

做这个的动机很直接:让 agent 在动手之前先查一眼自己在这个任务类型上历史成功率和成本。它不该等人告诉它"你上次这类活儿失败了三次",它自己该能查到。

实现的是 MCP 的核心子集——initialize、tools/list、tools/call、ping,stdio 传输,纯 JSON-RPC。protocolVersion 直接回显客户端请求的值,这样不同版本的客户端接上来都不会卡在握手上。

一些我做不了、或者做得不好的地方

它不采集数据。 事件流从哪来是你的事,自己埋点、从日志转、从计费记录拼都行。这个工具只负责算。

置信区间会经常很难看。 八个任务的区间跨度就是 55.7%。这不是 bug,是样本量的现实。我宁可让它难看,也不想给一个看起来确定、实际不成立的值。

按步数乘方那个假设很粗糙。 它假设每步独立同分布,可真实的 agent 步骤高度相关——前一步的输出就是后一步的输入。所以理论值只能当参照线,看差值的方向比看差值的绝对值更有意义。

成本完全依赖输入里的 usd。 工具不内置价格表。模型价格变得快,不同区域不同,缓存命中还有折扣,价格应该由你的采集端算清楚。

它不知道任务做得对不对。 事件流里 ok:true 只说明那一步没报错,不代表产出是对的。质量评估是另一件事,别混在一起。

这些限制里,有一部分是因为我只有一个站、几个脚本的数据量,做不出更细的东西。数据量上去了,判断哪些假设该松、哪些该紧,会更有依据。

关于

代码是从日常运维里长出来的。

说个题外话,这个项目最初的动机跟证书有关。之前换过一次证书,面板上说换好了,监控是绿的,浏览器小锁也是绿的,只有从公网握手才知道用户拿到的还是那张快过期的旧证。当时的教训是"局部正常不等于整体正常",我专门记了一篇:换证书:面板说换好了,公网说没换。

后来做这个账本,发现是同一个毛病。日志说这一步成功了,计费说这次花了多少钱,权限系统说这个工具是允许的,三个局部都正常,合起来看却是一笔糊涂账。局部正常不等于整体正常,这句话在运维里能用很多年。

这些东西都放在 Kan112 AI 网址导航 上,那是个 AI 工具与建站资源的收录站,也顺手记建站过程中的排查过程。类似的记录还有改了没生效?先看缓存和预压缩副本这种,都是踩完之后写的。

使用许可

不是开源项目,是源码可见。保留所有权利。

  • 可以直接用:读源码、抄片段学习、个人非商业自用;

  • 需要事先取得书面授权:任何商业用途、再分发、去掉版权声明、基于它做竞争产品。

完整条款见 LICENSE。商业授权走站点联系页。

这么定的原因跟前面那些工具一样:这东西会读到你的运行数据,商用出了问题不好溯源。个人拿去算自己的账,不用打招呼。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Exposes analytics from Claude Code transcripts as MCP tools, enabling cost, audit, safety, and efficiency queries through natural language.
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A read-only MCP server that exposes local coding-agent session logs as three tools for introspection of recent work, debugging tool failures, and tracking token usage and estimated cost without parsing log files.
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that records agent execution metrics and exposes a Context Window Explorer to visualize exactly what entered the model's context window across sessions, tokens, and tool calls.
      8
      3
      MIT