它省下什么¶
三件不同的事，第三件最容易被低估。
| 省的 | 靠什么 |
|---|---|
上下文——四千行的 job 日志变成 grep 加几行上下文；12 job 的矩阵变成 12 行名册 |
get_run、get_job、search_job_log，以及 tail/from_line/next_to_line 窗口 |
| 墙钟时间——等待变成一次有界调用；取消与去重省下本来会白烧的分钟 | wait_for_run、trigger_workflow(if_absent=true)、cancel_run、typical_duration_seconds |
| 错误结论——"第 1 次挂在容量抖动、第 2 次通过"而不是"这个后端不稳" | attempt/is_latest、has_log + reason、ci_status.health.alerts |
前两件没有它只是慢一点；第三件会让你写出一份看起来很有把握、实际是错的报告—— 而别人是照那份报告做事的。
一次会话的实测（使用者自述，非基准测试）¶
一位使用者记录了他一次会话的用量（他的估算，不是我们的基准）：
| 问题 | 不用本服务 | 用本服务 |
|---|---|---|
| Oracle 那个 job 为什么挂 | 一个 job 4369 行日志 | grep: "DPY-6005" → 19 个行号 + 上下文 |
| 12 job 的 run 哪个红了 | 12 份日志约 4.8 万行 | get_run 花名册 |
| 这十个仓库绿了吗 | 十次读取 | recent_runs 一次 |
他最锋利的一点不是比例：完整矩阵的日志根本装不进上下文窗口，所以这不是"便宜一点"，
而是"原本做不了"。他同一天还记录到：cancel_run + if_absent 粗估省下 50～60 分钟
runner 时间；另有三次，是某个字段让他避免了错误结论，而不是省下一点时间。
诚实的一半（他的记录 + 我们的）：
- 每次调用在内容之前就有 schema + JSON 的开销，约几百 token——"这个 run 绿了吗"并不免费；
- 自建服务必须能按构建辨识，否则所有评价都可能评错对象（
build.revision就是为此存在）； - 客户端缓存了工具目录时，"服务端改了"和"我能看见改了"之间差一次重连。
我们用在自己身上看到的¶
用本服务的工具写本服务：
- 77 个 job 的矩阵一次拿回名册；失败 step 的 443 行日志一次窗口读回；
- 对六天前的 run 调
get_job_log(step=N)，返回的是capture_closed而不是空文档—— 这才促使我们去拉原始归档，测出 step 分片在 56～70 分钟之间被压平； ci_status.health.alerts列出投递失败的 run id，修复从"排查"变成一遍get_run；- 在 24 个分支的仓库上查询，暴露了 workflow 显示名随分支漂移的问题—— 这个缺陷只读自己仓库是看不见的。