CodePilot 工具调用 UX 深度解析:Thinking 展示、上下文归组与流式渲染优化实践
CodePilot 工具调用 UX 深度解析:Thinking 展示、上下文归组与流式渲染优化实践
本文围绕 CodePilot 仓库中 工具调用 UX 产品思考 展开,结合 技术交接文档 与 竞品调研报告,并对照
src/components/ai-elements/tool-actions-group.tsx、src/lib/stream-session-manager.ts、src/hooks/useSSEStream.ts、src/components/chat/StreamingMessage.tsx等核心源码,系统讲解 CodePilot 在多模型 Agent 桌面客户端中如何重构工具调用展示层。读者将掌握:thinking 推理内容如何全链路展示、工具渲染注册表如何设计、连续信息收集工具如何自动归组、is_error如何穿透 SSE 链路、以及"缓冲 + 节流"如何解决流式文本闪烁问题。
一、背景:四个真实的用户问题
CodePilot 是一款基于 Electron + Next.js 的多模型 AI Agent 桌面客户端,工具调用是 Agent 与工作区交互的核心通道。但在一段时间的使用与反馈中,产品团队发现了四个影响体验的关键问题,它们构成了本次工具调用 UX 优化的全部动机:
| 用户痛点 | 现象 | 根因 |
|---|---|---|
| "AI 在干嘛我不知道" | 工具调用期间只有闪烁的 "Thinking..." 文字,长工具调用链(30s+)期间用户无法判断模型是走在正确方向还是已经跑偏 | 模型的 extended thinking 内容没有进入 UI |
| "满屏都是 Read Read Read" | 模型连续读 5-10 个文件时,工具列表变成一堆重复的 Read 行,有效信息密度极低 | 无连续信息收集工具的归组能力 |
| "工具出错了我看不出来" | 工具失败和成功看起来完全一样,用户只能翻工具输出文本找线索 | is_error 字段在 SSE 链路中被静默丢弃 |
| "文字一个一个蹦出来" | 流式输出前几个字符时 DOM 高频更新,文字"抽搐",中文回复(每字一个 delta)尤其明显 | 无智能缓冲,也无后端文本节流 |
这四个问题分别对应四项核心改造:thinking 全链路展示、上下文工具归组、is_error 全链路修复、缓冲 + 节流双轨流式优化。
二、Thinking 展示:让模型的"思考"可见、可折叠、可追溯
2.1 方案:thinking 作为工具调用列表的第一行
针对"AI 在干嘛我不知道",方案是把 Claude 的 extended thinking 内容以可折叠行的形式嵌入工具调用列表:
- 流式过程中默认展开,让用户实时看到模型的推理过程;
- 完成后自动折叠,让历史消息保持紧凑;
- 摘要提取:从 thinking 内容中提取第一个粗体(
**bold**)或标题(# heading)行作为折叠态摘要。
这里有一个关键设计决策:thinking 作为工具调用列表的第一行(同级),而不是独立的推理区域。原因在于避免双层嵌套——Turn 折叠 + 工具折叠叠加会让用户"要点两次才能看到内容",而把 thinking 并进工具列表后,用户一次展开就能看到全部内容,结构扁平、交互统一。
2.2 源码实现:ThinkingRow 组件
ThinkingRow 是这一方案的落地组件,其实现要点:
function ThinkingRow({ content, isStreaming }: { content: string; isStreaming?: boolean }) {
// 流式中默认展开,历史消息中折叠
const [expanded, setExpanded] = useState(!!isStreaming);
const { stopScroll } = useStickToBottomContext();
// 从第一个 **bold** 或 # heading 提取摘要
const summary = (() => {
const boldMatch = content.match(/\*\*(.+?)\*\*/);
if (boldMatch) return boldMatch[1];
const headingMatch = content.match(/^#{1,4}\s+(.+)$/m);
if (headingMatch) return headingMatch[1];
return isStreaming ? 'Thinking...' : 'Thought';
})();
// ...
}
- 图标交互:默认显示 Brain 图标(流式中为
ThinkingOrb的 solving 态),hover 时变为CaretRight箭头,点击展开/折叠——这一交互模式参考了用户提供的 ChatGPT 截图中"思考"行的设计。 - 防跳动:展开时调用
useStickToBottomContext().stopScroll()脱离自动滚动模式,避免内容展开触发 use-stick-to-bottom 的 resize 自动滚动导致视觉跳动。 - 富渲染:展开内容用
Streamdown渲染,并启用了cjk、math、mermaid三个插件(见 tool-actions-group.tsx),使 thinking 中的中文排版、公式和 mermaid 图都能正确呈现。
2.3 全链路数据流与持久化
thinking 的展示并非只在 UI 层,而是打通了一条完整的数据链路(见 handover 文档):
claude-client.ts (thinking delta → SSE 'thinking')
→ useSSEStream.ts (onThinking callback)
→ stream-session-manager.ts (accumulatedThinking + phase separation)
→ ChatView.tsx → MessageList.tsx → StreamingMessage.tsx
→ ToolActionsGroup.tsx (ThinkingRow 组件)
各环节职责如下:
| 环节 | 文件 | 职责 |
|---|---|---|
| SSE 事件分发 | src/hooks/useSSEStream.ts | handleSSEEvent 新增 case 'thinking',把 delta 转发给 callbacks.onThinking |
| 三层累积 | src/lib/stream-session-manager.ts | accumulatedThinking(当前 phase)/ fullThinking(全部 phase)/ thinkingPhaseEnded(phase 标记) |
| 客户端持久化 | finalMessageContent |
序列化时包含 { type: 'thinking', thinking: allThinking } block |
| 服务端累积 | /api/chat/route.ts |
collectStreamResponse 累积 thinkingText 并 unshift 到 contentBlocks |
| 历史渲染 | MessageItem.tsx 的 parseToolBlocks |
提取 thinking 传给 ToolActionsGroup.thinkingContent |
| 归一化 | message-normalizer.ts |
识别 thinking block,生成 (reasoning: summary) 摘要 |
2.4 Phase 分隔机制:多轮工具调用的 thinking 处理
多轮工具调用场景中,SDK 会在每一轮产生新的 thinking block。如果简单累加,多轮 thinking 会混成一团。stream-session-manager.ts 采用如下机制:
onText与onToolUse回调中把thinkingPhaseEnded置为true(stream-session-manager.ts);- 新的 thinking delta 到来时,若
thinkingPhaseEnded为 true,则把当前accumulatedThinking追加到fullThinking(用---分隔),再重置当前累积(stream-session-manager.ts); - UI 只显示当前 phase(流式中用户看到的是"当前这轮在想什么"),持久化保存全部 phases(历史消息可完整回溯)。
三、上下文归组:把"满屏 Read"折叠成一条摘要
3.1 方案与阈值选择
针对"满屏都是 Read Read Read",方案是:3 个以上连续的信息收集工具自动归组为 "Gathering context (N)"。
阈值选 3 而非 2 是一个刻意的产品决策:刻意的双文件对比(如对比两个实现)不应被折叠。若阈值设为 2,用户想同时看两个文件时也会被折叠,损失关键信息。参考对象是 Opencode 的 ContextToolGroup 与 Codex 的 "Exploring" 模式。
3.2 源码实现:computeSegments
computeSegments 用一次线性扫描完成归组:
const CONTEXT_TOOLS = new Set([
'read', 'readfile', 'read_file',
'glob', 'grep',
'ls', 'list', 'list_files',
'search', 'find_files', 'search_files',
]);
function computeSegments(tools: ToolAction[]): Segment[] {
// 连续 CONTEXT_TOOLS 缓冲,>=3 归组为 context,否则逐个展开为 single
}
ContextGroup 组件负责渲染归组结果:
- 独立展开/折叠(
AnimatePresence+ height 动画); - 标题文案按状态切换:
Gathering context (N)(有 running 中工具)/Gathered context (N files)(全部完成); - 右侧
StatusDot聚合组状态:任一 running → running,任一 error → error,否则 success; - 展开后子工具行沿用统一的左侧竖线(border-l-2)视觉语言,与整体工具列表一致。
从源码结构看,归组只基于工具名匹配,不区分 MCP 工具与内置工具(这一点记录在已知局限中)。
四、is_error 全链路修复:失败必须看得见
4.1 问题根因
is_error 字段在 SSE 链路中被静默丢弃,导致工具失败与成功在 UI 上完全无法区分。用户遇到问题时不知道哪个步骤出了错,只能翻工具输出文本找线索。
4.2 修复链路
修复贯穿整条 SSE 链路(见 handover 文档 第 4 节):
claude-client.ts (tool_result SSE 包含 is_error)
→ useSSEStream.ts (提取 is_error)
→ stream-session-manager.ts (透传到 snapshot + finalMessageContent)
→ ToolActionsGroup (StatusDot 显示红色 XCircle)
关键实现点:
- useSSEStream.ts 的 tool_result 分支:解析结果时条件展开
...(resultData.is_error ? { is_error: true } : {}),保证只有真实失败才携带该字段; - 同步修复了
page.tsx和route.ts中的本地ToolResultInfo类型,避免类型层面再次丢弃; - ToolActionsGroup 的 getStatus:
result === undefined→ running;isError→ error;否则 success。
4.3 StatusDot:三态动画
StatusDot 用 AnimatePresence mode="wait" 包裹三种状态,状态切换时旧图标先淡出、新图标再入场:
- running:opacity fade,
SpinnerGap+animate-spin灰色旋转; - success:spring scale 弹入(
stiffness: 400, damping: 20),绿色CheckCircle; - error:同样 spring 弹入,红色
XCircle。
Header 中的运行描述用 Shimmer 包裹闪烁,让"正在做什么"在长工具链中始终可见。此外,工具行渲染还包含一个内联提示:当模型调用了当前 Runtime 不支持的 codepilot_* 内置工具时,通过 isToolUnsupportedError 判定并显示"切换 Runtime"提示(tool-actions-group.tsx),该判定只对 "tool not found / unknown tool / not registered" 类错误生效,不会误伤 API key、网络等真实运行错误。
五、流式优化:缓冲 + 节流,而不是纯节流
5.1 为什么"纯节流"不够
纯节流只解决 DOM 更新频率问题,解决不了"前几个字闪烁":流式输出的前几个字符仍然逐字出现,中文回复(每个字都是一次 delta)时尤其明显。缓冲的核心价值是让首屏从"逐字出现"变为"一段话出现",体感差异明显。
但缓冲对结构化块是危险的:show-widget、batch-plan、image-gen-request 这类块的半成品预览和确认卡都依赖增量检测,缓冲会阻塞它们的即时反馈,所以必须有旁路直通。
5.2 前端:useBufferedContent(40 词 / 2.5s)
useBufferedContent 实现了前端智能缓冲:
const BUFFER_WORD_THRESHOLD = 40; // 词数阈值
const BUFFER_MAX_MS = 2500; // 最大等待时长
const STRUCTURED_BLOCK_RE = /```(show-widget|batch-plan|image-gen-request)/;
实现细节:
- 双阈值释放:累积 40 词后立即释放,或 2.5s 超时强制释放;
- 结构化块旁路:内容中出现结构化块标记即 bypass,直通渲染;
- Timer 锚定到首次内容到达:用
hasContentboolean gate 保证 timer 只创建一次,不随 delta 重建(StreamingMessage.tsx); - 渲染路径纯计算:所有 bypass 决策通过
useEffect同步状态,render 阶段零副作用(if (!isStreaming) return rawContent; if (shouldBypass) return rawContent; return '')。
5.3 后端:stream-session-manager 的 100ms 文本节流
与前端缓冲配套,stream-session-manager.ts 实现了自适应快照节流:
const TEXT_THROTTLE_MS = 100;
const throttledTextEmit = () => {
textDirty = true;
if (!textEmitTimer) {
textEmitTimer = setTimeout(() => {
textEmitTimer = null;
if (textDirty) emitTextUpdate();
}, TEXT_THROTTLE_MS);
}
};
关键设计:
- 100ms 节流合并快速 delta,减少 React 重渲染次数;
- 高频率的非 text 事件(
onThinking、onToolOutput、onToolProgress)也复用同一节流器,四个回调统一调度合并后的snapshot-updated(stream-session-manager.ts); - 合并不丢帧:
buildSnapshot总是读取最新累加器,丢弃的只是中间帧,最终快照不受影响; - 终点强制 flush:
onToolUse与 completion/error/stop 等终态转换前调用flushTextThrottle(),保证 tool block 与最终内容出现前没有滞留帧(stream-session-manager.ts); - 节流器定义在
try/catch外层,error path 也能访问。
对比竞品,文本节流参考 Opencode 的 createThrottledValue(100ms),但 CodePilot 把实现放在 stream-session-manager 层而非组件层,使节流对所有订阅快照的消费者统一生效。
5.4 附带:等待期文案的诚实设计
流式等待区还有一个细节:ThinkingPhaseLabel 的文案刻意避免使用 "thinking",因为用户会把它误读为"模型正在努力推理",而实际上只是首个字节尚未到达。它按时间推进:0-5s "生成中..."、5-15s "回复中..."、15s+ "组织回复中..."(StreamingMessage.tsx),真实推理内容由 ThinkingRow 单独渲染,两者职责分离。
六、设计演进:为什么放弃独立 Reasoning 面板
最初实现的是独立的 Reasoning 面板(位于工具列表上方),但实际使用时暴露两个问题:
- 双层折叠:Turn 折叠和工具折叠嵌套,用户要点两次才能看到内容;
- 展开跳动:展开 thinking 时触发对话自动滚动,视觉跳动明显。
改为 thinking 作为工具列表第一行后,结构扁平化、交互统一。Brain 图标 → hover 变箭头的交互参考了用户提供的 ChatGPT 截图中"思考"行的模式。这一演进过程完整记录在 insights 文档 与 handover 文档 中。
七、注册表模式:取代 if/else 工具分类
7.1 动机
原实现中的 getToolCategory / getToolIcon / getToolSummary 是硬编码的 if/else 链,每新增一种工具类型需要同时修改三个函数,极易遗漏且难以扩展。
7.2 ToolRegistry 设计
ToolActionsGroup 的注册表 让每种工具自描述:
interface ToolRendererDef {
match: (name: string) => boolean;
iconName: CodePilotIconName;
label: string;
getSummary: (input: unknown, name?: string) => string;
renderDetail?: (tool: ToolAction, streamingOutput?: string) => React.ReactNode;
}
内置 5 种渲染器,按 match 顺序匹配:
| 渲染器 | 匹配工具 | 摘要逻辑 | 特殊能力 |
|---|---|---|---|
| bash | bash / execute / run / shell / execute_command |
命令文本,>60 字符截断 | renderDetail:运行中显示末 5 行滚动窗口,完成后显示前 20 行 + 省略提示 |
| edit | write / edit / writefile / write_file / create_file / notebookedit 等 |
文件 basename | — |
| read | read / readfile / read_file |
文件 basename | — |
| search | search / glob / grep / find_files / websearch / xai.x_search 等 |
搜索 pattern(截断 50 字符) | — |
| agent | agent |
agentType: prompt 前 50 字符 |
renderDetail:解析进度行,> 活动 / [+] 完成 / [x] 错误 / [subagent:] 头,只显示末 8 行 |
| fallback(兜底) | 任意(must be last) | 原始工具名 + input JSON(截断) | 保证未注册工具(TodoWrite、MCP 工具、插件工具)仍可识别 |
扩展方式:registerToolRenderer() 把新渲染器 unshift 到注册表头部,新工具类型优先于内置渲染器(tool-actions-group.tsx)。这一模式参考了 Opencode 的 ToolRegistry.register({ name, render }),但比它更轻——不需要独立文件,一个数组即可。
7.3 Bash 实时输出窗口
renderDetail 在 running 时显示 streamingToolOutput 的最后 5 行滚动窗口(保证实时看到最新输出且不遮挡界面),完成后显示 tool.result 的前 20 行并标注省略行数(tool-actions-group.tsx)。streamingToolOutput prop 去掉了原来的 _ 前缀正式启用,且只附加到最后一个 running 工具行(lastRunningId 匹配),避免所有工具行同时刷新造成闪烁。
7.4 Header 布局与 Flat 模式
- Header 布局:内容(数量 badge + 摘要 + 运行描述)在左,CaretRight 箭头在右(
ml-auto),保证箭头位置稳定可点击; - 数量 badge:
tools.length + (thinkingContent ? 1 : 0),thinking 行计入总数; - Flat 模式:
flatprop 跳过 header 和折叠动画直接渲染工具列表,目前虽未启用但保留为扩展点(如嵌入其他面板时复用)。
八、Diff Summary:写完文件要让人知道
DiffSummary 在 MessageItem.tsx 中消费:从 pairedTools 提取 edit/write 工具的文件路径,去重后显示 "Modified N files" 折叠行。
当前实现比纯文件名列表更进一步:
- 可预览文件(
.md/.mdx/.html/.htm/.jsx/.tsx/.csv/.tsv)渲染为独立 Artifact 卡片,带 "Open preview" 按钮(PREVIEWABLE集合,DiffSummary.tsx); - Created / Modified 标签:
operation字段区分新建与修改,绿色 / 琥珀色徽章; - 其他文件折叠为一行 "Also modified: foo.ts, bar.json",避免无操作卡片刷屏(DiffSummary.tsx);
- 长截图导出:仅
.html支持 "Export long shot"(LONGSHOT集合),因为导出管线走隐藏 BrowserWindow → PNG 路径,把 TSX 源码当页面导出会得到源码截图而非预览(DiffSummary.tsx)。
设计上刻意不做列表级折叠头:预览入口要在第一眼可见。
九、测试覆盖
本次改造的单元测试集中在两条链路(见 handover 文档 测试覆盖表):
| 测试文件 | 覆盖点 |
|---|---|
__tests__/unit/sse-stream.test.ts |
thinking 事件分发、不混入 text、is_error 提取、media 透传 |
__tests__/unit/message-normalizer.test.ts |
thinking-only 摘要、heading 提取、组合消息、长文本截断 |
同时 __tests__/unit/emit-throttle.test.ts 覆盖了节流合并逻辑,验证 throttledTextEmit / flushTextThrottle 在快速 delta 与终态 flush 下的行为。
十、竞品参考与取舍
| 功能 | 主要参考 | 取舍 |
|---|---|---|
| Thinking 摘要提取 | Opencode(提取 **bold**/# heading)、Codex(reasoning 驱动状态栏) |
采用 Opencode 方案,Codex 的状态栏模式不适合 GUI |
| 上下文归组 | Opencode(ContextToolGroup)、Codex(Exploring 模式) | 采用 Opencode 方案,阈值从 2 改为 3 |
| 工具注册表 | Opencode(ToolRegistry) | 简化为数组 + match 函数,不需要独立文件 |
| 状态动画 | CraftAgent(Framer Motion crossfade) | 采用,spring scale 弹入效果 |
| 智能缓冲 | CraftAgent(BUFFER_CONFIG) | 简化配置(只留 word count + max ms),加结构化块旁路 |
| 文本节流 | Opencode(createThrottledValue 100ms) | 在 stream-session-manager 层实现,而非组件层 |
十一、未来方向
- Intermediate text:CraftAgent 的工具调用间推理文本展示。需要先重构
useSSEStream的文本累积为分段感知(当前单一字符串无法区分 tool 前后的文本),改动量较大; - Diff viewer:当前只有文件名列表,没有行级 diff 预览。项目内暂无 diff 组件(Git 页面也是
<pre>裸文本),需要引入 diff 渲染库; - 工具审批 UI:CodePilot 目前没有工具审批流程,如未来需要可参考 Opencode 的三选按钮(Deny / Allow Always / Allow Once)。
十二、已知局限
- 滚动脱离:Thinking 展开时调用
stopScroll()会脱离自动滚动,流式过程中展开后新内容不会自动追到底部,需用户手动点滚动按钮(tool-actions-group.tsx); - 历史消息 Bash 长输出:
showDetail条件含tool.result,导致历史消息中 bash renderDetail 始终展开,长输出占空间,可能需要加折叠; - 归组仅基于工具名:不区分 MCP 与内置工具,同名不同源的上下文工具也会被归组;
- Phase 分隔硬编码:thinking phase 用
---分隔,若 thinking 内容本身包含---会产生混淆(概率极低)。
十三、总结
CodePilot 的工具调用 UX 优化是一次典型的"从产品痛点出发、以竞品调研为参考、以源码级实现收尾"的完整改造:thinking 展示从无到有并打通全链路持久化,工具渲染从 if/else 硬编码演进为可扩展注册表,连续 Read 通过归组把信息密度提回来,is_error 让失败一目了然,缓冲 + 节流的双轨方案同时解决"逐字闪烁"与"结构化块即时性"两个看似矛盾的需求。相关实现细节可继续深入阅读 产品思考文档、技术交接文档、竞品调研文档 以及 Thinking 展示专项调研,核心代码集中在 tool-actions-group.tsx、stream-session-manager.ts 与 useSSEStream.ts 三个文件中。