Kun 在途生成图片放置机制:从工具时间线行内联渲染到回合级生成文件汇总的交接

原创2026-10-09 14:52:372,132 阅读
文章标签:AI 应用人工智能AI Agent代码智能体交互助手桌面应用多智能体Agent 编排Agent 工作流工具调用Agent 记忆本地部署LLM 网关MCP Clients前端CLI

Kun 在途生成图片放置机制:从工具时间线行内联渲染到回合级生成文件汇总的交接

本文基于 Kun 仓库的 OpenSpec 变更 fix-inflight-generated-image-placement 展开,讲解其"在途生成媒体"(inflight generated media)的放置机制:当图像生成工具在回合(turn)尚未结束时产出结果,预览应锚定在产生它的那个工具时间线上;回合结束后再交接给回合级"Generated files"汇总面板。读完本文,你能理解 Kun 聊天时间线的分组边界策略、GeneratedFilesPanel 的 placement 双模式设计,以及 isProcessing 状态驱动的去重交接逻辑,并可结合源码与单元测试验证每一处行为。

背景问题:中间产物与产出步骤脱节

在修复之前,Kun 的对话时间线存在一个 UI 语义问题(见 proposal.md 的 Why 一节):

生成图片目前会在图像工具一完成时,就渲染在回合级的"Generated files"区域——即使整个回合仍在运行中。这让中间结果看起来脱离了产生它的工具步骤,并错误地暗示整个响应已经到了最终输出阶段。

具体而言,ConversationTurn 组件此前会从回合的所有成功生成的文件工具块中汇总出媒体,并在 assistant 内容之后渲染一个 GeneratedFilesPanel,且无论回合是否仍在进行。与此同时,这些工具块在按时间顺序排列的过程时间线(process timeline)中同样存在,但该时间线原本只渲染工具摘要行,并且会把相邻的工具事件折叠进同一个分区——也就是说,即使预览被提前渲染出来,其"归属位置"在时间线上也是模糊的。

这个变更引入一个全新的能力规范(proposal 的 Capabilities 一节):

  • New Capability:inflight-generated-media-placement —— 定义生成媒体如何从"进行中的工具时间线位置"移动到"已完成的回合汇总"(规格文件见 spec.md);
  • Modified Capabilities:无,不改动任何既有能力契约。

变更目标与非目标

proposal 的 What Changes 给出了四条变更点,design.md 的 Goals / Non-Goals 进一步收窄了范围:

变更内容(What Changes)

  1. 回合仍在处理时,将生成媒体按时间顺序内联渲染在产生它的工具位置;
  2. 让生成媒体的工具结果保持为独立的时间线位置,避免其预览被折叠进不相干的多工具批处理(collapsed tool batch)中;
  3. 仅在回合结束后,才把生成媒体移入既有的回合级"Generated files"汇总;
  4. 为"进行中"与"已完成"两种回合状态下的放置行为增加渲染端(renderer)覆盖,且不允许出现预览重复。

Goals:进行中的生成媒体预览锚定在产出它的工具结果上;即使相邻工具事件按常规应被分组,也保持其时间线位置;进行中的回合内恰好只渲染一份预览;完成后复用既有的回合级生成文件汇总。

Non-Goals(明确不做的事,划定实现边界):不改动图像生成 provider、runtime 载荷、附件存储或 SSE 顺序;不在成功工具结果出现之前引入"部分图像流式";不重新设计生成媒体磁贴(tile)的视觉外观与操作;不改动已完成回合的过程展开行为。

核心设计一:生成媒体工具结果成为时间线分组边界

design.md 的第一个决策是:携带生成媒体的工具结果在过程时间线中作为分组边界(grouping boundary)——这样的工具块将独占一个执行分区,从而提供稳定的时间线锚点。设计中明确记录了一个被否决的替代方案:把相邻工具保持分组、把预览放在整批工具之后——但该方案会丢失"精确定位到产出步骤"这一 UI 行为诉求。

从源码结构看,这一决策落在 message-timeline-process-grouping.ts 中。判定谓词 processBlockHasGeneratedMedia 要求工具块同时满足 kind === 'tool'、status === 'success',并且 meta.attachments 或 meta.generatedFiles 至少有一个非空数组(L30-L37):

export function processBlockHasGeneratedMedia(block: ChatBlock): block is ToolBlock {
  if (block.kind !== 'tool' || block.status !== 'success') return false
  return (
    Array.isArray(block.meta?.attachments) && block.meta.attachments.length > 0
  ) || (
    Array.isArray(block.meta?.generatedFiles) && block.meta.generatedFiles.length > 0
  )
}

分组函数 groupProcessSections 在主循环中对该谓词命中块直接 push 一个独立 section(L84-L87),并用 followsGeneratedMedia 标志阻断后续 reasoning/execution 块向该 section 的合并(L99、L111-L130)。换言之,生成媒体块不仅自己独占一行,其后的普通工具也不会被折叠进它,双方向上都保证了时间线位置的稳定性。

design.md 的 Risks / Trade-offs 一节还指出一个一致性要点:生成的非图像文件(如视频、文档)同样会成为分组边界——为此刻意复用了与回合级生成文件汇总相同的元数据谓词,使行为在所有媒体类型上保持一致;而"呈现类产物"(presentation artifacts,例如生成的文档)则仍由其专属面板过滤,不进入媒体预览流。这一过滤在 GeneratedFilesPanel 内部通过 isGeneratedDocumentArtifactPath(mediaPath(file)) 实现(见下文)。

核心设计二:复用 GeneratedFilesPanel,以 placement 标记区分生命周期

第二个决策是不新增预览实现,而是复用既有的 GeneratedFilesPanel,并为其增加显式的 placement 标记('timeline' | 'turn')。这样做的好处是:媒体去重、懒加载预览、轮播行为与文件操作(reveal/download 等动作)在两种位置间保持一致,同时 placement 属性让"进行中 vs 最终"的行为可以直接被单元测试断言,无需维护两套组件。

message-timeline-media-views.tsx 中该组件的实现(L507-L541)展示了复用与标记的具体形态:

export function GeneratedFilesPanel({
  blocks,
  placement = 'turn'
}: {
  blocks: ToolBlock[]
  placement?: 'timeline' | 'turn'
}): ReactElement | null {
  const { t } = useTranslation('common')
  const media = useMemo(() => {
    const attachments: AttachmentReference[] = []
    const generatedFiles: GeneratedFileReference[] = []
    for (const block of blocks) {
      attachments.push(...metaAttachmentReferences(block.meta as RuntimeDisclosureMetadata | undefined))
      generatedFiles.push(...metaGeneratedFileReferences(block.meta))
    }
    return mergeMediaReferences(attachments, generatedFiles).filter(
      (file) => !isGeneratedDocumentArtifactPath(mediaPath(file))
    )
  }, [blocks])

  if (media.length === 0) return null

  return (
    <div
      className="flex min-w-0 flex-col gap-2"
      data-generated-files-placement={placement}
    >
      ...
      <MediaAttachmentGallery media={media} variant="conversation" />
    </div>
  )
}

两个值得注意的实现细节:

  1. data-generated-files-placement 属性(L532)把 placement 输出到 DOM 上,使"同一回合内 timeline 版与 turn 版不应同时出现"这类不变量可以在渲染输出上直接断言——这正是 spec 中"预览不重复"场景可测的关键;
  2. 媒体合并与去重集中在 mergeMediaReferences。message-timeline-media-logic.ts 中的该函数(L140-L166)先按 mediaKey(id → absolutePath → relativePath → path → previewUrl → name 的优先级链)索引,再对 attachments 允许按规范化文件名(lowercased)做二次合并;命中已有条目时以 {...existing, ...entry} 方式合并字段而不是重复推入。design.md 的第三个风险项("一个工具载荷可能同时包含普通 attachments 和生成媒体")正是通过复用这套既有合并/去重逻辑来化解的——载荷只被解释一次。

在时间线侧,message-timeline-process.tsx 的工具行组件用一行条件决定内联预览是否出现(L580):

const showInlineGeneratedMedia = processing && processBlockHasGeneratedMedia(block)

只有当该回合仍在处理中(processing 为真)且该块携带生成媒体时,才在工具详情之后渲染内联面板(L686-L690):

{showInlineGeneratedMedia ? (
  <div className="ml-2 mt-2">
    <GeneratedFilesPanel blocks={[block]} placement="timeline" />
  </div>
) : null}

注意这里传入的 blocks={[block]} 只包含当前工具块本身——内联预览严格对应"产出它的那一步",而不是整个回合的媒体集合。

核心设计三:turn 级面板由 isProcessing 门控,状态驱动交接

第三个决策是回合级面板由回合完成状态门控。ConversationTurn 在 isProcessing 为真时完全省略底部的聚合面板,此时唯一的预览属于时间线中那条隔离出来的过程行;当 isProcessing 变为假,过程行的内联预览随之禁用(上面 showInlineGeneratedMedia 中的 processing 项自然为假),聚合面板则在最终 assistant 内容之后出现。message-timeline-conversation-turn.tsx 中的对应渲染(L484-L485):

{!isProcessing ? (
  <GeneratedFilesPanel blocks={generatedFileBlocks} placement="turn" />
) : ...}

这是一个纯状态驱动的交接(handoff):两个面板的可见性由同一个布尔量(回合处理状态)互补控制,任何时刻至多一个可见,因此不引入任何新的持久化状态也不会出现双份预览。这与 spec 的第二个 Requirement 一一对应——回合从 processing 转为 completed 后,"内联过程时间线预览不再渲染,且生成图像在最终 assistant 内容之后的回合级生成文件汇总中恰好渲染一次"。

行为规范:spec 中的 Requirements 与 Scenarios

spec.md 以两个 Requirement 固化了该能力的契约:

Requirement 1:活动回合中的生成媒体停留在其产出的时间线位置——当回合仍在处理时,来自已完成工具结果的生成媒体 SHALL 按该工具结果的时间顺序位置渲染。覆盖两个场景:

  • 图像生成先于回合结束完成:图像工具结果包含生成图像且回合仍进行中 → 预览与该工具结果内联渲染于过程时间线中,且不同时出现在回合级生成文件汇总中;
  • 生成媒体发生在其他过程事件之间:该结果 SHALL 保留一个位于前后事件之间的独立时间线位置,且不被折叠进不相干的工具批处理。

Requirement 2:已完成的生成媒体移入回合汇总——当回合不再处理时,生成媒体 SHALL 渲染在回合级生成文件汇总中。场景:含成功生成图像结果的回合从 processing 转为 completed → 内联预览不再渲染,图像在最终 assistant 内容之后的回合汇总中恰好渲染一次。

这两个 Requirement 恰好分别由"设计一 + 设计二"(分组边界 + timeline placement)与"设计三"(isProcessing 门控)满足,构成 需求 → 决策 → 实现 的完整闭环。

预览加载:为什么"只改放置"也足够稳健

proposal 强调本次改动"复用既有的生成媒体预览与文件操作,不需要任何 runtime、IPC、持久化或 provider 契约变更"。从源码看,这依托于 message-timeline-media-logic.ts 中已经成熟的预览解析链路:

  • 引用规范化:normalizeGeneratedFileReference(L29-L69)对工具载荷中的 generatedFiles 条目做防御性解析,兼容多种字段别名(如 previewUrl/dataUrl/url、relativePath/relative_path),并提取 byteSize、width、height、availability 等元信息;
  • 懒加载与双数据源兜底:useMediaPreviews(L213 起)按 (threadId, workspaceRoot) 作用域缓存解析结果,仅对尚未解析且无 previewUrl 的媒体发起请求;每个请求先尝试 provider 的 getAttachmentContent(附件存储),失败后回退到工作区路径读取(window.kunGui.readWorkspaceImage),只有全部来源耗尽才标记该磁贴失败。代码中的注释明确写道:"Generated images also carry a workspace path. Continue to that safe, workspace-bounded source before declaring the tile failed."
  • 类型识别:mediaIsImage/mediaIsVideo 优先使用 MIME 前缀,MIME 缺失时按扩展名(png|jpe?g|webp|gif|bmp|svg、mp4|webm|mov|m4v|ogg)兜底判断。

正因为预览加载、去重、轮播(carousel)与磁贴自适应缩放(mediaTileFitConstraints 按 user/tool/conversation 三种变体给出不同的宽高约束)此前就已完成,本次变更才能把全部改动收敛到"放置与生命周期"这一层,而不触碰媒体管线本身。

验证:任务清单与测试覆盖

tasks.md 记录了该变更的工作项,且全部处于完成状态:

  1. Timeline Placement:生成媒体工具结果成为独立的时间线过程分区;仅当回合活动时由产出的过程行渲染生成媒体;聚合的回合级面板直到回合完成才出现——三项均勾选完成;
  2. Verification:为"生成媒体分区隔离 + 活动态内联放置且不重复"添加测试;为"完成后置于最终 assistant 内容之后"添加测试;运行聚焦的 renderer 测试与相关类型检查。

对应的测试证据可以在 MessageTimeline.media-metadata.test.ts 中找到,例如用例 keeps generated media tool results as distinct chronological process sections(L357)直接验证分组边界行为,其余用例通过 renderToStaticMarkup 断言 data-generated-media-carousel、data-generated-media-strip 等输出特征;derive-turn-sections.test.ts、MessageTimeline.tool-process.test.ts 等则覆盖回合分节与工具过程渲染的周边行为。design.md 最后一条风险——"未来时间线分组逻辑变化时放置行为可能回归"——正是通过这批聚焦单元测试来兜底的:它同时覆盖分组边界与活动/完成两种渲染顺序。

影响面总结

回到 proposal 的 Impact 一节,可以把本次变更的影响面归纳为:

  • 影响范围:src/renderer/src/components/chat 下的聊天时间线分区分组与渲染(process grouping、process row 内联面板、ConversationTurn 底部面板三处);
  • 不产生契约变更:无 runtime、IPC、持久化或 provider 契约改动,纯渲染端(renderer)变更;
  • 质量保障:以聚焦的 renderer 单元测试覆盖时间顺序放置与回合完成后的落位。

对维护者的实际启示在于:当一个"看起来是布局 bug"的问题背后其实是渲染生命周期的时序语义问题(中间产物 vs 最终产物),Kun 的解法是引入一个显式的 placement 维度(timeline/turn)加一个共享状态门(isProcessing),复用单一组件表达两个阶段,而不是复制组件或新增数据流。这套"分组边界 + placement 标记 + 状态门控"的组合,对任何流式对话 UI 中"在途产物展示"的设计都有参考意义。

登录后查看全文
Kun