social-app/docs/bugs/2026-03-24-events-not-rendering.md

Bug: 前端未渲染 events 接口事件

日期

• 2026-03-24

现象

• 用户反馈：改动后前端无法获取/渲染 /api/v1/agent/runs/{threadId}/events 的事件。
• 页面表现为消息流无事件增量或工具执行状态未更新。

本次背景

• 本次清理了前端死链路：
  • ToolRegistry
  • RouteNavigationTool
  • AiDecisionEngine
• 当前主链路仍为 AG-UI SSE：AgUiService -> AgUiEvent -> ChatBloc -> HomeChatItemRenderer。

影响范围

• Chat 事件流渲染（运行状态、工具调用状态、文本完成事件）
• 可能影响 Home 聊天视图实时反馈

初步判断

• 已清理的死链路不在当前主流程中，理论上不应直接导致 SSE 事件无法渲染。
• 更可能的问题点：
  1. runId 绑定过滤导致事件被丢弃（shouldDispatch 为 false）
  2. onEvent 回调异常导致流提前停止
  3. SSE data 结构变化，AgUiEvent.fromJson 解析失败

关键代码位置

• apps/lib/features/chat/data/services/ag_ui_service.dart
• apps/lib/features/chat/data/models/ag_ui_event.dart
• apps/lib/features/chat/presentation/bloc/chat_bloc.dart
• apps/lib/features/home/ui/widgets/home_chat_item_renderer.dart

待执行排查

1. 在 _streamEventsFromApi 增加临时诊断日志：eventType、eventRunId、expectedRunId、shouldDispatch
2. 捕获并输出 onEvent 抛错栈，确认是否由 UI/Bloc 处理异常中断
3. 抓取真实 SSE 帧，核对 runId/threadId/type/data 与解析模型一致性
4. 复测 RUN_STARTED -> TOOL_* -> TEXT_MESSAGE_END -> RUN_FINISHED/RUN_ERROR 完整链路

当前状态

• 状态：待定位
• 优先级：高