Skip to main content
Glama
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)。

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