# 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` 完整链路

## 当前状态

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