tako 文档 GitHub

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):

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. 参考形态与取舍(抄谁、不抄谁)

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}

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 → 前端历史渲染

每个新件没它会怎样:不压 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. 本篇不做

8. 闭环

所以这解决了什么:用户第一次在撞墙之前知道墙在哪——上下文占用、每枪花销变成 气泡旁的一行小字和历史里的一条记录;doc/16 #4c 的「可见/可决策」半边闭环, tako 与 Octop/pi 在这项能力上对齐(轻量形态、真值来源、阈值变色三处业界惯例全部落到)。