agent-ledger
by zs6755413
README.md
# agent-ledger
> 前阵子想算一笔账:手上那几个每天定点跑的脚本,一个月到底省了我多少时间、又烧了多少钱。算了半天没算出来。
>
> 日志里有步骤,账单里有 token,权限配置在另一个文件里,三样东西对不上。这个仓库就是拿来把它们拼成一张账的。
零依赖。一份 JSONL 事件流进去,出来是终端报告、一个 HTML,或者一个能让 agent 自己查账的 MCP server。
## 先说为什么要算这个
起因不是看了什么趋势报告,是想算账算不出来。
我平时在给一个内容站做运维,站上跑着几个自动化:sitemap 对账、链接图、索引推送,还有一两个改稿用的脚本。这些东西平时不出声,出了事才响。问题就在这儿——**它们只在失败的时候才被人看见,成功的时候花了多少、值不值,没人记。**
后来我去翻公开讨论,想看看别人怎么处理这件事。翻到三类数字,都在说同一件事:
一类是关于复合错误的。单步成功率 95%,十步的任务只剩六成左右。误差会乘起来,所以任务越长越脆。
一类是关于成本口径的。"每百万 token 多少钱"这个说法正在被换掉,换成"每个完成的任务多少钱"。理由是如果一半任务最后失败,token 单价便宜没有任何意义。
一类是关于权限的。有安全调研说八成以上的 CISO 担心 AI 被过度授权,但能说清环境里到底有几种 agent 的不到一半。
(这三条是我从 2026 年 11 月的公开报道和厂商公告里读到的,属于二手转述。原始调研报告我没有逐份去核,它们在这里只是用来说明"为什么值得算",不当结论用。)
三条放在一起看,缺口很明显:**大家都在说要按任务算钱、要管权限、要盯住复合错误,但没有一个工具把这三件事算进同一张表。**
日志平台管 trace,计费平台管 token,权限系统管 grant,各自都挺专业,就是彼此不说话。
## 这张账算三件事
### 一、单步成功率推不出任务成功率
这是复合错误的核心,也是我最想验证的一件事。
工具会先算单步成功率。这里有条规定要说清楚:同一个 step 如果有多条事件,只按**最后一条**算。所以"失败一次、重试成功"记成成功,"连着失败两次"才算失败。这条规则决定了后面所有数字,是整个分析的地基。
然后按独立假设推一个理论任务成功率,就是把单步成功率按平均步数乘方。再和实测的对比。
最后给实测值一个 Wilson 95% 置信区间。
**第四步是我加得最不情愿、但最有用的一步。** 八个任务跑出 62.5%,置信区间是 30.6% 到 86.3%——区间比结论本身还宽。把区间打出来这件事犹豫过,不打的话,这个数字迟早会被人拿去汇报,然后被现实打脸。
差值本身也有用。实测比理论好,说明重试和自我纠正在起作用;实测比理论差,说明错误会聚集,某一步走歪后面全歪。
### 二、钱花在哪,得按任务算
按 token 算的钱是没有意义的,至少对做决策没有意义。
工具输出这几个数:
- 失败任务吃掉了多少比例的成本
- 有效成本倍数:把失败成本摊进去后,每个成功任务的真实成本是名义成本的几倍
- 模型维度的成本占比,和调用占比并排放
- 最贵的两成任务占多少成本
样例数据跑出来是这样:
```text
失败任务消耗 $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` 里——这种配置在改过几轮策略文件的项目里太常见了,没人记得哪条还有效。工具会直接把它标出来。
过度授权真正的意义不在"整洁"。那四个授予了但一次没用过的工具,就是注入攻击得手之后可以直接调用的现成入口。收窄权限换来的不是好看,是"出事的时候坏得少一点"。
## 怎么用
```bash
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
```
样例数据是八个任务、六十二条事件,里面有重试、有越权被拒、有上下文超限、有测试失败。跑出来:
```text
任务成功率 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` 必填:
```json
{"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 用
```bash
node bin/ledger.js --mcp
```
在 Cursor、Claude Code 这类客户端里注册:
```json
{
"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` 只说明那一步没报错,不代表产出是对的。质量评估是另一件事,别混在一起。
这些限制里,有一部分是因为我只有一个站、几个脚本的数据量,做不出更细的东西。数据量上去了,判断哪些假设该松、哪些该紧,会更有依据。
## 关于
代码是从日常运维里长出来的。
说个题外话,这个项目最初的动机跟证书有关。之前换过一次证书,面板上说换好了,监控是绿的,浏览器小锁也是绿的,只有从公网握手才知道用户拿到的还是那张快过期的旧证。当时的教训是"局部正常不等于整体正常",我专门记了一篇:[换证书:面板说换好了,公网说没换](https://www.kan112.com/post/p_092215f8)。
后来做这个账本,发现是同一个毛病。日志说这一步成功了,计费说这次花了多少钱,权限系统说这个工具是允许的,三个局部都正常,合起来看却是一笔糊涂账。局部正常不等于整体正常,这句话在运维里能用很多年。
这些东西都放在 [Kan112 AI 网址导航](https://www.kan112.com/) 上,那是个 AI 工具与建站资源的收录站,也顺手记建站过程中的排查过程。类似的记录还有[改了没生效?先看缓存和预压缩副本](https://www.kan112.com/post/p_0a1b2c11)这种,都是踩完之后写的。
## 使用许可
不是开源项目,是源码可见。保留所有权利。
- 可以直接用:读源码、抄片段学习、个人非商业自用;
- 需要事先取得书面授权:任何商业用途、再分发、去掉版权声明、基于它做竞争产品。
完整条款见 [LICENSE](LICENSE)。商业授权走[站点联系页](https://www.kan112.com/contact.html)。
这么定的原因跟前面那些工具一样:这东西会读到你的运行数据,商用出了问题不好溯源。个人拿去算自己的账,不用打招呼。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues