tako 文档 GitHub

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>:默认收起,展开依次是

  1. 失败原因(回执判为失败时,<p class="tool-fail">);
  2. 参数原文(<pre class="tool-args">,参数是 {} 时不画);
  3. 回执原文(<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. 已知缺口(明确不做 / 未验)

  1. 没有耗时:帧与账本行都不带开始/结束时间戳,卡片无法显示「这条跑了 12 秒」。要显示得先加字段(属于帧契约变更,不在本篇)。
  2. 正文只在等人工具边界分段,普通工具仍不逐段交错:一场 run 的正文在库里仍是一条 Σ 行,普通工具调用前后的话拆不开,界面只能排「卡片全部在上 / 全部在下」。2026-11-03 起 ask_user / submit_plan / skill_install 的边界会把正文切成多段(segments 偏移,见 §5.4 补记),问答块因此能按真实先后排开;要让每个普通工具调用也交错,得改 runlog 的行形状(按轮次写多行 assistant),牵到 19v6 的定稿锚与折叠输入,仍未做。
  3. 子代理前缀未活体验证:agent 非空时摘要前画一个代理名字 chip(.tool-agent),代码路径已通,但最近 12 场会话里没有带 agent 的工具行,没有活体样本。
  4. 只读展示:卡片不提供重试、复制参数、跳转到工作区文件等操作。

7. 验收记录(2026-11-01)

8. 与 doc/52 C5 的关系

doc/52 C5 的卡片机制(toolCallId 配对、失败显示结构化 message、展开看回执原文)是本篇的地基,原样保留。 本篇翻掉的是它的范围:C5 只对技能三件建卡,其余工具帧与账本行被白名单丢掉。现在所有工具都建卡,技能三件只是多了中文摘要措辞。