59 · 对话里的工具调用可见性
性质:实现真源(2026-11-01 立项并落地)。 状态:✅ 已落地(2026-11-01,A1–A2)。对话页把每一次工具调用画成一张工具卡(帧与 runlog 两条路径),不再按工具名筛。 代码落点:
yk-tako-eino/web/src/{chat.ts,App.vue,api.ts}(后端零改动)。 验收:浏览器打开历史会话(21 次工具调用全上屏、2 张失败卡、刷新后仍在)+ 活体一轮echo hello(运行中即出卡、回执到后同卡合并)+npm run typecheck/npm run build绿。 上游:doc/52 C5(技能三件的工具卡)——本篇翻掉它的窄口:卡片机制保留,筛选去掉。 2026-11-03 补记:等人工具边界开始把正文切段(§5.4),问答块可按真实先后排开;普通工具仍不分段(§6 第 2 条)。 台账:tmp/59-工具调用可见性/(不入库)。
0. 一句话结论
工具调用一直在数据里:帧(tool_call / tool_result)和 runlog 账本行都带 name / args / output / toolCallId / agent。 丢的是前端:chat.ts 里有一张「只认技能三件」的名字白名单,其余工具帧和账本行被静默返回 null。 本篇把白名单换成通用映射——所有工具进气泡,一行摘要、点开看参数与回执,失败标「失败」,刷新与翻页都不丢。
1. 病灶:一场 21 次工具调用的 run,界面上一次都看不到
故事(2026-11-01 用户实测):问 「What writer is quoted by Merriam-Webster for the Word of the Day from June 27, 2022?」。 模型 web_search 找了 5 轮、web_fetch 抓了 2 次 Merriam-Webster(都被站点挡回 404)、bash 自己 curl 与 grep 了 6 次、read_file 读了 5 个落盘文件——共 21 次工具调用,run 跑了 303 秒。
用户在页面上看到的:一个气泡,先空着,最后只落一行答案。中间那 21 次调用、两处 404、沙箱拒绝 /dev/null 的报错,一个都看不见。 用户换到 CozeLoop 的 trace 树才看到那一长串 chat ↔︎ execute_tool,于是问:「为什么前端看不到里面这么多的工具调用?」
丢在哪一步:链路本来是全的。
worker 每轮模型调用完成
→ 写 tool_call 帧(name/args/toolCallId/agent) ← Redis runlive
→ 执行工具
→ 写 tool_result 帧(name/output/toolCallId/agent)
→ 定稿时同一份 payload 进 runlog 账本行 ← PG
→ 前端 pollFrames / getLog 拉回来
→ chat.ts 过滤:不是 read_skill / use_skill / read_skill_file 就 return null ← ★断在这里
断点的来历是 doc/52 C5:当时只做技能三件的卡,注释顺手写了「页面不演终端」。技能之外的调用(bash / web_search / web_fetch / read_file / 子代理)从此在界面上不存在。
不做的后果:用户没法判断 agent 在干什么、卡在哪一步、是哪一次抓取失败了。一场 5 分钟的 run 看起来像「模型在发呆」。
2. 数据面:两条路径,同一个事件形状
工具调用有两个来源,字段同形,前端收敛成一个 ToolEvent:
| 来源 | 什么时候读 | 一条记录长什么样 |
|---|---|---|
| 帧 | run 活着时每 400ms 轮询 GET /api/runs/:runId/frames |
{"kind":"tool_call","name":"web_fetch","args":"{\"url\":\"…\"}","toolCallId":"call_00_…","agent":""};回执行是 kind:"tool_result",把 args 换成 output |
| runlog 行 | 打开历史会话 / 翻页 GET /api/sessions/:id/log |
{"role":"tool_call","agent":"","payload":"{\"name\":\"bash\",\"args\":\"{\\\"command\\\":\\\"ls\\\"}\",\"toolCallId\":\"call_00_…\"}"};回执行 role:"tool_result"、payload 里是 output |
映射代码在 web/src/chat.ts:toolFrameEvent(:244)与 toolRowEvent(:258)各自把来源解成同一个形状:
type ToolEvent = { callId: string; name: string; args?: string; output?: string; agent?: string }mergeTool(:292)按 toolCallId 把 call 和 result 叠到同一张卡上:先到的建卡,后到的补另一半。 一个工具调用允许一帧到得比另一半早(同一轮多个调用并行时回执顺序可以交错),所以配对键必须是 toolCallId,不能按行号或数组下标。
agent 是产出这条记录的代理:空串 = 主代理,非空 = 子代理名字(types.go 与 runlog 一直带着这两列,只是之前前端 Row 类型没声明)。
3. 画成什么样:一行摘要,点开看详情
web/src/App.vue 的 toolCardLabel(:276)把一次调用压成一行:
| 工具 | 摘要 |
|---|---|
web_search |
搜索:<query> |
web_fetch |
抓取:<url> |
read_file |
读取:<path>(分页读时带「(从第 N 行)」) |
bash |
执行:<命令首行> |
write_file / edit_file |
写文件:<path> |
use_skill / read_skill / read_skill_file |
沿用 doc/52 C5 的中文措辞(使用技能:… 等) |
| 其余 | <工具名>:<参数 JSON 前 90 字> |
摘要里所有文本压成单行(oneLine:折叠空白、超 90 字加省略号),过长的摘要用 CSS 省略号截断,不换行撑破气泡。
卡片是 <details>:默认收起,展开依次是
- 失败原因(回执判为失败时,
<p class="tool-fail">); - 参数原文(
<pre class="tool-args">,参数是{}时不画); - 回执原文(
<pre class="tool-out">;还没有回执时写「还没有回执。」)。
失败 / 执行中是摘要行右侧的 chip:toolCardState(:315)先看有没有失败,再看有没有回执——没有回执且气泡在跑 = 执行中。 回执不设内部滚动条:整段直接撑开(用户明确不要嵌套滚动条),代价是超长回执会把页面拉长,因此有截断上限(§4)。
4. 失败判定与截断
失败判定统一走工具错误文本的契约:所有工具的错误结果都由 tools.go 的 toolErrorText 包一次,恒以「错误:」开头。 所以 toolCardFail(:297)对通用工具只看前缀;只有技能三件保留结构化信封判据(code≠0 时取 message,成功回执以 <skill 开头)。
这替代了旧判据「不是 <skill 开头就是失败」——那个判据对 web_search(回执以「来源:」开头)会把 21 次里的每一次成功搜索都标成失败。
截断(clipped,:271):参数 2,000 字符、回执 8,000 字符。超出时保留前一段,末尾换行写「…(后面还有 N 字符,已截断)」。 保留原文而不是摘要,是因为展开卡片的用途就是看模型到底收到了什么;截断只防一场 34 次调用 × 50KB 把页面拖死。
5. 两条路径各自的坑
5.1 账本行可能先于气泡到达
runlog 里工具行排在它那场的 assistant 终稿行之前。打开历史会话时,气泡还不存在,卡片无处可挂。 attachToolRow 因此先按 runId 把事件排进 pendingTools(:322),assistant 气泡一出现就 flushPendingTools 补齐。
5.2 初始窗口可能切在一次调用与它的回执之间
GET /api/sessions/:id/log 的游标是排他的(返回 offset > N 的行),初始窗口是 高水位 - 10。 高水位 44 时从 34 拉,拿到 35–44:如果一次 bash 的调用行在 34、回执行在 37,调用行落在窗口外,卡片只剩回执——摘要显示成 执行:(没有命令)、点开也没有参数。
修法在取数侧:hasUnpairedToolResult(:278)检查一批行里有没有「回执找不到同批的调用行」,有就把起点再往前挪一页重拉,直到配对完整或到达会话开头(0)。 翻页 loadOlder 用同一判据。这条规则不引入新的 API 语义,只改前端取窗口的起点。
5.3 实时路径的「执行中」
帧路径里 tool_call 帧先到、tool_result 帧后到,所以卡片会先以「执行中」出现,回执到后同一张卡合并结果并翻成完成。 这是可见性修复真正要给的东西:run 跑到一半就能看出它正在做什么,不用等定稿。
5.4 正文与卡片谁在上(按行序,不按模板)
一段普通的 run(get_time 那种)在账本里的行序是 user → tool_call → tool_result → assistant: 卡片对应的事先发生,答案后到。但气泡模板里正文块写在卡片块前面,第一版就一律画成「答案在上、卡片在下」—— 与行序相反,读起来像先回答了再补查。
判据放在数据侧(web/src/chat.ts):气泡上带一个 toolsFirst,凡是「第一张卡到达时这个气泡还没有任何正文」就置真—— 历史面走 flushPendingTools(排队的工具行先于气泡创建)与 attachToolRow(翻页时按 logOffset 比先后), 实时面走 mergeTool(工具帧早于第一个 delta)。渲染侧 bubbleBlocks(web/src/App.vue)据此决定两块谁在上。
普通工具调用仍只分两块:runlog 把整场 root 正文 Σ 成一行(store.go 的 writeTurnRows), 模型中途说的「我先搜一下」和最后的答案在库里是同一行字,拆不开(见 §6 第 2 条)。
2026-11-03 补记(等人工具边界开始分段):writeTurnRows 在 ask_user / submit_plan / skill_install 之前记下 root 正文的 rune 偏移,写进那条 assistant 行 payload 的 segments([{end,toolCallId}],行数仍是一条)。 前端按偏移把同一行切成多段气泡,问题卡挂到切点前那段;已答的自由文本问题紧跟一个右对齐答案气泡。 于是「段 1 → 问题卡 → 答案气泡 → 段 2」可以按真实先后排开,刷新与实时走同一套切法。 代价是工具卡仍统一挂在第一段(toolsFirst 不变),回答后才发生的工具在收口/刷新后会随第一段上移。
6. 已知缺口(明确不做 / 未验)
- 没有耗时:帧与账本行都不带开始/结束时间戳,卡片无法显示「这条跑了 12 秒」。要显示得先加字段(属于帧契约变更,不在本篇)。
- 正文只在等人工具边界分段,普通工具仍不逐段交错:一场 run 的正文在库里仍是一条 Σ 行,普通工具调用前后的话拆不开,界面只能排「卡片全部在上 / 全部在下」。2026-11-03 起
ask_user/submit_plan/skill_install的边界会把正文切成多段(segments偏移,见 §5.4 补记),问答块因此能按真实先后排开;要让每个普通工具调用也交错,得改 runlog 的行形状(按轮次写多行 assistant),牵到 19v6 的定稿锚与折叠输入,仍未做。 - 子代理前缀未活体验证:
agent非空时摘要前画一个代理名字 chip(.tool-agent),代码路径已通,但最近 12 场会话里没有带agent的工具行,没有活体样本。 - 只读展示:卡片不提供重试、复制参数、跳转到工作区文件等操作。
7. 验收记录(2026-11-01)
- 历史会话(同一场 Merriam-Webster run):21 次工具调用按序全上屏,
web_search/read_file/web_fetch/bash都有;两张失败的web_fetch显示「失败」与错误:HTTP 404;展开可见参数、回执原文与截断提示(5 条超 8,000 字符的回执带「已截断」标注)。 - 活体:新发「用 bash 执行 echo hello,只回复 ok」→ 工具卡在运行中以「执行:echo hello / 执行中」出现,回执到后同一张卡合并输出并翻成完成;刷新后答案、卡片仍在(runlog 路径)。
cd yk-tako-eino/web && npm run typecheck && npm run build绿。- 窗口边界修正前,同一会话首屏出现过一张参数为空的
执行:卡;修正后消失(hasUnpairedToolResult)。 - 2026-11-01 补拍(正文/卡片顺序):用户按
GET /api/sessions/:id/log的原始行序(user→tool_call→tool_result→assistant)指出页面把答案画在了卡片上方。改为按toolsFirst排两块(§5.4)后浏览器复核:get_time会话(s_01M6BNXHHGQ74DJ2FDG6PCJGKZ)与echo hello会话的.bubble-main子节点顺序均为tool-cards→bubble-text,答案在卡片下方;npm run typecheck/build绿、npm test14 件全过。 - 2026-11-03 分段补记验收:活体一轮「先确认一下 → ask_user 选 A/B → 答 A → 只回复 ok」,页面节点顺序为
user→assistant(卡+「我先确认一下,再问你。」)→问题卡→答案气泡「A」→assistant「ok」;刷新后 6 个节点顺序与文本逐项一致(docScrollWidth == innerWidth,无横向溢出)。runlog 仍是一条 assistant 行,payloadsegments:[{"end":7,"toolCallId":"call_…"}];没有提问的 run 不出现segments。
8. 与 doc/52 C5 的关系
doc/52 C5 的卡片机制(toolCallId 配对、失败显示结构化 message、展开看回执原文)是本篇的地基,原样保留。 本篇翻掉的是它的范围:C5 只对技能三件建卡,其余工具帧与账本行被白名单丢掉。现在所有工具都建卡,技能三件只是多了中文摘要措辞。