27 · 用量可见化(doc/16 #4c 的「可见/可决策」半边)
性质:施工真源。方案经 Yk 点头(2026-10-16),A1–A3 三拍已全部施工并活体验收完(2026-10-17,未含pi 任何外推项)。 分工:doc/24 做的是引擎内的半边——计数(
usageEstimate)和折叠触发,用户看不见。 本篇做引擎外的半边——把用量送进帧、API 和页面,让用户看得见、据此做决定。 doc/24 §8 写的「不把 Usage 写入四个 API / 帧 / 表」是那一拍的不做,不是永久禁令;本篇就是来开这道门的。施工状态(2026-10-17):
- A1(帧契约)✅:worker.go
usageBill/usageFrame(提取负路径三件:无 ResponseMeta / 无 Usage / 三数全 0 不发帧)+ 发帧点在每枪 drain 合并后(root 与子代理同点,帧 agent 区分)。curl 验收:usage 帧在 delta 与 terminal 之间,promptTokens 3311 与 doc/24 基线 ~3.4k 同量级。- A2(前端渲染)✅:api.ts Frame 扩 usage;chat.ts Bubble.usage/usageUnknown(多枪取最后一帧、子代理帧跳过、亲历收尾无帧标「用量 ?」);App.vue pi 式小字
↑3.3k ↓32 · 3.3k/256k (1%)+ >70% 橙 / >90% 红。浏览器验收:金路径、多枪、刷新 reconcile、橙色阈值(-compact-window 4400 实测 75% 变橙)全过;>90% 红与「用量 ?」未活体(同分支/负路径,单测盖)。- A3(落库 + 历史行)✅:
UsageBill共形状(帧与 payload 列);TurnEntry.Usage 随 assistant 条目进 turn,EndRun 两处定稿行(root 取最后一枪 / 子代理本枪)落 payload 列,账单缺失不写列;ReadLog assistant 行解出注入usage、原文不透出,tool 行 payload 照旧;前端 rowBubble/loadOlder/closeOut 三路带 usage。curl 验收:assistant 行带 usage、user/tool 行无、assistant 行无 payload 原文;工具 run 的 promptTokens 3398 = 第二枪账单(「最后一枪」真值对);浏览器刷新历史小字在。stopped/error 分支零改动(无 assistant 行 = 无账单行)。- 单测:TestUsageFrame(负三件+正形+字节面)、TestEndRunLandsUsagePayload(root 末枪/子代理含 reasoning/无账单 payload NULL)。go test runengine 全量绿 + vet 干净;vue-tsc + build 过。
1. 背景与病灶(故事先行)
tako 的会话会越聊越长。今天用户对「上下文还剩多少」零可见,后果是一场真实的失败戏:
用户跟 tako 聊了一下午,读了几个大文件、跑了几次 bash。上下文悄悄逼近窗口上限。 折叠层按 doc/24 在 200k 附近自动压了一轮——用户什么都没看到,只觉得 tako 突然 「忘了」前半小时讨论过的文件路径,又花几轮重新铺垫。最后用户发一个大文件, POST /api/runs 返回 413 message_too_large——这是今天唯一一个把 token 数透给用户的时刻, 而且只在死后说话:墙已经撞上了才告诉用户墙在哪。用户既不能提前开新会话, 也不知道 413 之前的会话已经压过几轮、还剩多少余量。
「可决策」指的是:用户看到用量,自己决定继续聊 / 停下来 / 开新会话。 不自动做任何事——压缩照旧由引擎按 doc/24 的线自动判,决定权在人这边只多不少。
2. 现状盘点(代码事实,2026-10-16 核对)
| 事实 | 位置 |
|---|---|
账单真身 schema.TokenUsage(PromptTokens / CompletionTokens / ReasoningTokens 等),粘在 state assistant 消息的 ResponseMeta.Usage 上,内存态、不落库、跨场读不回 |
eino v0.9.21 schema/message.go L448/L535;读取点 midfold.go L310–344(doc/24 落地) |
usageEstimate 四读数(baseline/visible/delta/total)今天只喂折叠触发判定和 stdout 日志行 compact usage … |
midfold.go L298–405 |
帧五种 kind(start/delta/tool_call/tool_result/terminal),只进 Redis tk:runlive:<runID>,随 lease TTL 消亡;没有任何帧带 token 信息 |
types.go L31–42、redisstore.go |
定稿历史 = PG runlog_entries(user / assistant / tool_call / tool_result 行),payload 列已存在(今天只有工具扩展行用) |
pgstore.go L82–96 |
窗口 = CLI 旗标 compact-window(默认 256000),limit = window − min(window/5, 16384) |
cmd/yktako/main.go L47/L93、compact.go L138–143 |
| 前端只认 start/delta/terminal 三种帧,零用量展示 | web/src/chat.ts L186–187、web/src/api.ts |
token 进 HTTP 的唯一先例:413 响应体 {error:"message_too_large", limit, tokens} |
server.go L104、worker.go L622–634 |
3. 参考形态与取舍(抄谁、不抄谁)
- pi(footer 状态行):
↑输入 ↓输出 R缓存读 CH命中率% 34.5%/200k,>70% 变警告色、>90% 变错误色; 压缩后无新响应前显示?/200k。数据 = provider 真实 usage。抄这个形态——轻量、每轮更新、阈值变色。 - Octop(
context_usage.py+ REST breakdown):按 system_prompt/tool_definitions/conversation 等 7 段估算, 挂内存快照 + 盖章消息,弹层画环形图。segments 明细本篇不抄——tako 的countInput基数拆分 是 doc/24 §8 明令不动的东西,且第一版用户要的是一个数,不是一张饼图。 - codex / hermes:同为「provider 真值 + 状态行
used/max (percent%)+ 阈值」,佐证 pi 形态是业界惯用法。
4. 契约(先写 API/帧,curl 手打,不从 UI 起手)
4a. 新帧 kind=usage
每枪模型回执处理完(doc/24 读 ResponseMeta.Usage 的同一点)后发一帧,进 runlive 帧流:
{"eventOffset":7,"kind":"usage","agent":"","model":"deepseek/deepseek-flash",
"promptTokens":2910,"completionTokens":63,"reasoningTokens":61,"totalTokens":3034,
"window":256000}- 字段蛇形改驼峰,与 Frame 既有
eventOffset同风格;reasoningTokens缺省省略(厂商明细可有可无,doc/24 同款)。 promptTokens就是上下文占用真值:它是「这一枪实际发出去的输入大小」,天然含 system、工具声明、 全部历史。不另设contextUsed字段重复它——语义在文档钉死,不在字段上叠床架屋。- window 是配置值不是模型真值(来自
compact-window旗标)。模型级窗口真值校准仍归溢出层 (extractWindow),本篇不碰。percent 由前端promptTokens/window现算,不传冗余字段。 - 账单缺失(厂商不报 Usage)→ 不发 usage 帧。不发 0、不发假数;前端对「没有 usage 帧」显示
?,与 pi 压缩后无新响应前的?/200k同款。 - 子代理同款:帧
agent字段非空即子代理枪,形状不变。前端第一版只渲染 root 帧(agent===""), 子代理用量在场内可见(frames 里翻得到)、历史归置跟 doc/17 §6 子代理折叠的行投影一起裁,本篇不展开。 - 一场 run 工具循环多枪 → 多帧 usage,前端每条 assistant 回复取最后一帧显示(= 下一枪的基线)。
4b. 历史行扩展(阶段二)
assistant 定稿行在 runlog_entries 复用 payload 列存同款 JSON。GET /api/sessions/:id/log 的 assistant 行随之多一个 usage 字段(后端从 payload 解出注入,无 payload 则不写该字段):
{"runlogOffset":5,"runId":"r_2","role":"assistant","agent":"","model":"deepseek/deepseek-flash",
"text":"……","usage":{"promptTokens":2910,"completionTokens":63,"reasoningTokens":61,"totalTokens":3034,"window":256000}}payload 列注释「只有工具扩展行有」随之放宽为「扩展行与 assistant 行(usage)有」——同一列, 语义按 role 分派,与既有读侧按 role 分派的惯例一致。
4c. 验收命令(契约拍期望字节)
# 阶段一:发一条消息,等流结束
curl -s -XPOST localhost:8080/api/runs -d '{"sessionId":"s_01","text":"你好"}'
curl -s "localhost:8080/api/runs/<runId>/frames?offset=0"
# 期望帧序列里 terminal 之前出现一帧:
# {"eventOffset":N,"kind":"usage","agent":"","model":"deepseek/...","promptTokens":<正整数>,
# "completionTokens":<正整数>,"totalTokens":<两数之和或更多>,"window":256000}
# 阶段二:同一会话事后拉历史
curl -s "localhost:8080/api/sessions/s_01/log?runlogOffset=0"
# 期望 assistant 行多 "usage":{...},user 行 / tool 行无此字段5. 数据链路(谁 → 谁 → 谁,机制挂在哪一环)
用户发消息 → 引擎发枪 → provider 回执(ResponseMeta.Usage,doc/24 既有读取点)
→ [新增] 同点压 kind=usage 帧进 runlive → SSE / GET frames → 前端气泡小字(阈值变色)
→ run 收尾 → [阶段二新增] assistant 定稿行 payload 带同款 JSON → GET log → 前端历史渲染
- 上游:doc/24 的读取点触发它(无它则账单根本拿不到);溢出层在极端偏差时兜底,不改本篇形状。
- 下游:前端消费帧;未来的「手动压缩」按钮(若做)也读同一份数字,本篇不预埋。
每个新件没它会怎样:不压 usage 帧 → 场内永久黑箱,用户只剩 413 死后报数;不落 payload → run 结束 TTL 一到,历史轮的用量全部蒸发,「这会话聊了多少」无法回看,可见半边只活一场; 不显示 percent → 用户还得自己拿 promptTokens 除以 window,决策成本回升,等于没做可决策。
6. 分阶段与 todos 草案(点头后建 tmp 台账开拍)
| Action | 改什么 | 怎么验收(第一行打跑着的东西) | 预估 diff |
|---|---|---|---|
| A1(契约拍) | worker 回执点压 usage 帧进 runlive;frames 端点零改动自然透出;无账单不发帧 |
4c 的 curl 两条:frames 期望含 usage 帧;伪造无账单厂商路径见帧缺席 | ~40 行 |
| A2 | web/src/api.ts Frame 类型扩 usage;chat.ts 渲染气泡小字 ↑2.9k ↓63 · 2910/256k (1%),>70% 橙、>90% 红 |
两个窗口:发消息看小字,深聊到高占比看变色 | ~60 行 |
| A3(阶段二) | EndRun 定稿时 assistant 行 payload 带 usage JSON;log 端点解出注入;前端历史行同款渲染 | 4c 阶段二 curl + 两个窗口回看历史 | ~60 行 |
阶段二启动条件 = 阶段一两拍验收过。A3 动 payload 列语义,属存储面,单独一拍交审。
7. 本篇不做
- segments 分段明细(Octop 式 breakdown)——countInput 基数是 doc/24 §8 不动项
- 费用估算(pi 的
$0.412)——无单价配置面,等真需要再说 - 缓存命中/缓存读写展示——
PromptTokenDetails今天没被消费,不为其扩帧 - 模型级窗口配置——window 保持 CLI 旗标;真值校准归溢出层
- 自动动作(自动压缩按钮、自动开新会话建议)——压缩线仍由 doc/24 引擎侧独裁
- 图表化(环形图/饼图)——一行小字是 pi 验证过的形态,先到先停
- 不动
run_model_messages(模型投影,历史展示永不读它——真源划分不变)
8. 闭环
所以这解决了什么:用户第一次在撞墙之前知道墙在哪——上下文占用、每枪花销变成 气泡旁的一行小字和历史里的一条记录;doc/16 #4c 的「可见/可决策」半边闭环, tako 与 Octop/pi 在这项能力上对齐(轻量形态、真值来源、阈值变色三处业界惯例全部落到)。