# Agent 对话总览与 SSE 流式交互 **本文引用的文件** - [chatApi.ts](file://ai-electron/frontend/src/ai/api/chatApi.ts) - [sse.ts](file://ai-electron/frontend/src/ai/api/sse.ts) - [chatStream.ts](file://ai-electron/frontend/src/ai/store/chatStream.ts) - [types.ts](file://ai-electron/frontend/src/ai/api/types.ts) - [constants.ts](file://ai-electron/frontend/src/ai/utils/constants.ts) - [AgentChatController.java](file://ai-server/src/main/java/com/zsjz/ai/module/agent/controller/AgentChatController.java) - [AgentChatService.java](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/AgentChatService.java) - [AgentChatServiceImpl.java](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/impl/AgentChatServiceImpl.java) - [AgentChatSession.java](file://ai-server/src/main/java/com/zsjz/ai/module/agent/entity/AgentChatSession.java) - [AgentMessage.java](file://ai-server/src/main/java/com/zsjz/ai/module/agent/entity/AgentMessage.java) ## 目录 1. [引言](#引言) 2. [项目结构定位](#项目结构定位) 3. [核心组件与职责分工](#核心组件与职责分工) 4. [架构总览](#架构总览) 5. [SSE 流式消息链路](#sse-流式消息链路) 6. [会话与消息数据模型](#会话与消息数据模型) 7. [典型调用示例](#典型调用示例) 8. [依赖关系分析](#依赖关系分析) 9. [性能与内存特性](#性能与内存特性) 10. [常见问题排查](#常见问题排查) 11. [结论](#结论) ## 引言 本文面向 Agent 对话模块的开发者与维护者,说明前端如何发起对话、后端 `AgentChatController` 与 `AgentChatService` 的职责边界,以及从前端到后端的完整 SSE(Server-Sent Events)流式交互链路。重点包括: - 前端通过 `chatApi.ts` 暴露接口,由 `sse.ts` 使用 `fetch` + `ReadableStream` 处理事件流。 - `chatStream.ts` 作为 Pinia store,负责会话生命周期、乐观插入用户消息、增量聚合助手回复、工具调用时序和 UI 渲染。 - 后端控制器仅做请求路由,真正逻辑在 `AgentChatServiceImpl`:校验工作空间、建立会话级互斥、驱动 Agent 流事件、按事件类型生成 SSE 帧、持久化消息并发送心跳。 - 解释 `AgentChatSession`、`AgentMessage`、Insight 会话在对话生命周期中的关系,并给出“选择模型后发送文本”“查看工具调用日志”“中断或重连 SSE”等典型流程。 ## 项目结构定位 本功能横跨前后端两个子工程: | 层级 | 关键路径 | 职责 | |---|---|---| | 前端 API 层 | `ai-electron/frontend/src/ai/api/chatApi.ts` | 封装会话、消息、图谱复原及流式对话入口;将解析器转发给 `sse.ts` | | 前端 SSE 实现 | `ai-electron/frontend/src/ai/api/sse.ts` | 通用 SSE 帧解析器、`fetch` 流读取、未登录/非 SSE 响应处理、中止信号透传 | | 前端状态管理 | `ai-electron/frontend/src/ai/store/chatStream.ts` | 会话列表、消息列表、流式对话状态机、工具步骤与思考过程累积、UI 富内容块增量扫描 | | 前端类型与常量 | `ai-electron/frontend/src/ai/api/types.ts`、`ai-electron/frontend/src/ai/utils/constants.ts` | 会话/消息/工具/Insight 契约、`getChatStreamUrl()` 地址拼接 | | 后端控制器 | `ai-server/.../controller/AgentChatController.java` | `/chat` 下 REST 路由;`/chat/stream` 返回 `Flux>` | | 后端服务接口 | `ai-server/.../service/AgentChatService.java` | 会话 CRUD、消息 CRUD、流式对话抽象 | | 后端服务实现 | `ai-server/.../service/impl/AgentChatServiceImpl.java` | 工作空间校验、会话锁、Agent 流事件映射、SSE 帧组装、心跳、落库 | | 后端实体 | `AgentChatSession.java`、`AgentMessage.java` | 数据库表 `agent_chat_session`、`agent_message` 的字段映射 | ```mermaid graph TB subgraph "前端" CA["chatApi.ts
API 入口"] ST["sse.ts
SSE 解析与 fetch 流"] CS["chatStream.ts
Pinia 状态与流式状态机"] TP["types.ts / constants.ts
类型与地址"] end subgraph "后端" AC["AgentChatController.java
/chat 路由"] AS["AgentChatService.java
服务接口"] ASI["AgentChatServiceImpl.java
流式逻辑实现"] DB["agent_chat_session / agent_message
PostgreSQL JSONB"] end CA --> ST CA --> CS CS --> CA ST --> TP AC --> AS AS --> ASI ASI --> DB ST --> AC ``` **图表来源** - [chatApi.ts:1-80](file://ai-electron/frontend/src/ai/api/chatApi.ts#L1-L80) - [sse.ts:1-222](file://ai-electron/frontend/src/ai/api/sse.ts#L1-L222) - [chatStream.ts:1-598](file://ai-electron/frontend/src/ai/store/chatStream.ts#L1-L598) - [AgentChatController.java:1-170](file://ai-server/src/main/java/com/zsjz/ai/module/agent/controller/AgentChatController.java#L1-L170) - [AgentChatService.java:1-83](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/AgentChatService.java#L1-L83) - [AgentChatServiceImpl.java:345-599](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/impl/AgentChatServiceImpl.java#L345-L599) **章节来源** - [chatApi.ts:1-80](file://ai-electron/frontend/src/ai/api/chatApi.ts#L1-L80) - [sse.ts:1-222](file://ai-electron/frontend/src/ai/api/sse.ts#L1-L222) - [chatStream.ts:1-598](file://ai-electron/frontend/src/ai/store/chatStream.ts#L1-L598) - [AgentChatController.java:1-170](file://ai-server/src/main/java/com/zsjz/ai/module/agent/controller/AgentChatController.java#L1-L170) - [AgentChatService.java:1-83](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/AgentChatService.java#L1-L83) ## 核心组件与职责分工 ### 前端:`chatApi.ts` `chatApi.ts` 是聊天相关 HTTP 接口的统一入口。它不直接实现 SSE 细节,而是把流式能力转发给 `sse.ts`: - 会话操作:创建、列表、详情、重命名、删除、置顶。 - 消息操作:查询、发送、删除、收藏。 - 图谱复原:根据历史工具入参中的查询条件重新拉取全量关系图,避免数据库存大 JSON。 - 流式对话:导出 `createParser`、`streamSse`、`streamChat`,保持调用方 `chatStream.ts` 零改动。 关键设计点: - 非流式接口走 `defHttp`(即 `aiHttp`)。 - 流式对话不走 axios,因为 axios 无法逐帧读取 `ReadableStream`。 - 注释明确区分“普通发送消息”和“流式对话”。 **章节来源** - [chatApi.ts:1-80](file://ai-electron/frontend/src/ai/api/chatApi.ts#L1-L80) ### 前端:`sse.ts` `sse.ts` 是通用 SSE 基础设施,同时供 AI 数据分析与 Insight 研判复用。其职责包括: 1. **帧解析器 `createParser`** - 维护缓冲区,支持 `\n\n` 与 `\r\n\r\n` 分隔。 - 忽略注释行(以 `:` 开头)。 - 合并多行 `data:` 字段。 - 对 JSON 载荷按 `event` 分发到 `onIntent`、`onThinking`、`onToolCall`、`onToolInput`、`onToolResult`、`onHeartbeat`、`onGraphData`、`onInsight`、`onToken`、`onDone`、`onError`。 - 非 JSON 载荷兜底为 token,避免丢字。 - 提供 `flush()`,防止最后一帧没有结尾空行时丢失末事件。 2. **`streamSse` 连接层** - 使用 `fetch` 发起 POST,携带 `x-token`、`Accept: text/event-stream`。 - 若后端返回非 SSE(例如 200 + code=401 的 JSON),先尝试解析错误消息并触发未登录跳转。 - 若 HTTP 非 ok,尽量解析 body 中错误信息。 - 使用 `response.body.getReader()` 逐块解码并喂给解析器。 - 捕获 `AbortError` 透传给调用方;其他异常转 `transportError`。 3. **`streamChat` 适配器** - 统一调用 `getChatStreamUrl()`,即 `/chat/stream`。 - 保留旧调用方式,内部委托 `streamSse`。 **章节来源** - [sse.ts:1-222](file://ai-electron/frontend/src/ai/api/sse.ts#L1-L222) - [constants.ts:20-28](file://ai-electron/frontend/src/ai/utils/constants.ts#L20-L28) ### 前端:`chatStream.ts` `chatStream.ts` 是整个对话 UI 的核心状态机。它不是简单的网络回调包装,而是承担了: - 初始化工作空间、加载会话列表。 - 新建会话、选中会话、加载历史消息。 - 历史消息中缺失的关系图按需复原。 - 后端消息反序列化为前端渲染态:工具步骤、思考过程、附件徽标、富内容块。 - 流式对话生命周期:乐观插入用户消息 → 占位助手消息 → 增量 token → 工具调用时序 → done/error → 收尾刷新会话元信息。 - 节流富内容块增量扫描,避免长回答 O(n²) 卡顿。 - 单进程内只允许一路流式请求,使用模块作用域的 `abortController`。 重要状态字段: | 字段 | 含义 | |---|---| | `workspaceId` | 当前案件/工作空间 | | `sessions` | 会话列表 | | `activeSessionId` | 当前选中会话 | | `messages` | 当前会话消息数组 | | `streaming` | 是否正在流式输出 | | `pendingExpert` | 来自 Insight 页面的预选研判方案 | | `thinking` | 模型思考正文 | | `trace` | 思考与工具的真实到达顺序链 | | `toolSteps` | 工具调用步骤列表 | | `intent` / `suggestions` | 意图识别与下一步引导 | | `lastActivityAt` / `lastHeartbeatAt` | 用于区分“模型在输出”和“连接断掉” | **章节来源** - [chatStream.ts:1-598](file://ai-electron/frontend/src/ai/store/chatStream.ts#L1-L598) ### 后端:`AgentChatController.java` 控制器只承担路由和参数绑定职责,不包含业务编排逻辑: - 会话 CRUD:`/chat/sessions`、标题更新、删除、置顶。 - 消息 CRUD:`/chat/messages`、收藏。 - 图谱复原:`/chat/graph/restore`。 - 附件上传:`/chat/attachments`。 - 流式对话:`POST /chat/stream`,返回 `Flux>`。 控制器注释明确描述了 SSE 事件顺序: 1. `tool_call` 2. `tool_input` 3. `tool_result` 4. `token` 5. `done` 6. `error` **章节来源** - [AgentChatController.java:1-170](file://ai-server/src/main/java/com/zsjz/ai/module/agent/controller/AgentChatController.java#L1-L170) ### 后端:`AgentChatService.java` 该接口定义了聊天域的所有对外方法,包括: - 会话:创建、列表、详情、标题、删除、置顶。 - 消息:查询、发送、删除、收藏。 - 图谱复原。 - 流式对话:`stream(ChatRequestDTO req)`。 它不关心具体事件如何映射,只声明契约。 **章节来源** - [AgentChatService.java:1-83](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/AgentChatService.java#L1-L83) ### 后端:`AgentChatServiceImpl.java` 这是流式对话的实际实现。核心行为: - 校验消息是否为空。 - 延迟解析会话 ID 与上下文,异常转为 error 帧。 - 会话级互斥:同一会话同一时刻只允许一条流,抢占失败返回“正在回复中”。 - 获取工作空间并校验访问权限。 - 构建 Agent 与 RuntimeContext。 - 订阅 `HarnessAgent.streamEvents`,将 Agent 事件映射为 SSE 帧。 - 独立心跳流:每 10 秒发送一次 `heartbeat`。 - done 时持久化完整助手消息;中断时持久化部分消息。 - 错误时持久化错误消息。 **章节来源** - [AgentChatServiceImpl.java:345-599](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/impl/AgentChatServiceImpl.java#L345-L599) ## 架构总览 下图展示一次完整的 Agent 对话请求从前端到后端的控制流和数据流: ```mermaid sequenceDiagram participant UI as "聊天页面" participant Store as "chatStream.ts" participant Api as "chatApi.ts" participant Sse as "sse.ts" participant Ctrl as "AgentChatController.java" participant Svc as "AgentChatServiceImpl.java" participant Db as "agent_chat_session / agent_message" UI->>Store: "选择模型并发送文本" Store->>Store: "乐观插入用户消息与占位助手消息" Store->>Api: "streamChat(params)" Api->>Sse: "streamSse(getChatStreamUrl(), params, handlers)" Sse->>Ctrl: "POST /chat/stream" Ctrl->>Svc: "stream(req)" Svc->>Db: "校验会话与工作空间" Svc->>Svc: "会话级互斥检查" Svc->>Svc: "启动 Agent 流事件" loop "SSE 事件流" Svc-->>Sse: "tool_call / tool_input / tool_result / token / thinking / heartbeat" Sse-->>Store: "对应 on* 回调" Store->>Store: "累积 content / toolSteps / trace / thinking" end alt "正常完成" Svc-->>Sse: "done" Svc->>Db: "持久化助手消息" else "错误或中断" Svc-->>Sse: "error / 连接关闭" Svc->>Db: "持久化错误或部分消息" end Sse-->>Store: "finally 清理流状态" Store->>Store: "结束 streaming、刷新会话元信息" ``` **图表来源** - [chatStream.ts:400-598](file://ai-electron/frontend/src/ai/store/chatStream.ts#L400-L598) - [chatApi.ts:57-80](file://ai-electron/frontend/src/ai/api/chatApi.ts#L57-L80) - [sse.ts:140-222](file://ai-electron/frontend/src/ai/api/sse.ts#L140-L222) - [AgentChatController.java:140-170](file://ai-server/src/main/java/com/zsjz/ai/module/agent/controller/AgentChatController.java#L140-L170) - [AgentChatServiceImpl.java:345-599](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/impl/AgentChatServiceImpl.java#L345-L599) ## SSE 流式消息链路 ### 前端发起连接 前端调用链如下: 1. 用户在聊天界面输入消息并点击发送。 2. `chatStream.ts` 的 `send` 方法判断是否需要新建会话。 3. 乐观插入本地用户消息和占位助手消息。 4. 调用 `chatApi.streamChat`。 5. `chatApi.ts` 转发到 `sse.ts` 的 `streamChat`。 6. `sse.ts` 拼接 `/chat/stream` 地址并发起 `fetch`。 7. 使用 `TextDecoder` + `SseFrameParser` 逐帧解析。 8. 将事件分发给 `chatStream.ts` 注册的 `handlers`。 ```mermaid flowchart TD Start["用户发送消息"] --> Draft{"是否存在有效会话?"} Draft -->|否| Create["创建会话"] Draft -->|是| UseExisting["复用现有会话"] Create --> InsertUser["乐观插入用户消息"] UseExisting --> InsertUser InsertUser --> InsertAssistant["插入占位助手消息"] InsertAssistant --> StreamApi["chatApi.streamChat"] StreamApi --> SseCore["sse.ts streamSse"] SseCore --> Fetch["fetch POST /chat/stream"] Fetch --> Parse["SseFrameParser 解析帧"] Parse --> Handlers["chatStream handlers 更新状态"] Handlers --> Render["UI 增量渲染"] ``` **图表来源** - [chatStream.ts:400-598](file://ai-electron/frontend/src/ai/store/chatStream.ts#L400-L598) - [chatApi.ts:57-80](file://ai-electron/frontend/src/ai/api/chatApi.ts#L57-L80) - [sse.ts:140-222](file://ai-electron/frontend/src/ai/api/sse.ts#L140-L222) **章节来源** - [chatStream.ts:400-598](file://ai-electron/frontend/src/ai/store/chatStream.ts#L400-L598) - [chatApi.ts:57-80](file://ai-electron/frontend/src/ai/api/chatApi.ts#L57-L80) - [sse.ts:140-222](file://ai-electron/frontend/src/ai/api/sse.ts#L140-L222) ### 后端事件生产 后端 `AgentChatServiceImpl` 将 AgentScope 的 `AgentEvent` 转换为 SSE 帧: | Agent 阶段 | SSE event | 前端处理器 | 状态变化 | |---|---|---|---| | 工具开始 | `tool_call` | `onToolCall` | 新增 `ToolStep{status:'running'}` | | 工具入参完成 | `tool_input` | `onToolInput` | 写入 step.input | | 工具结果完成 | `tool_result` | `onToolResult` | 写入 step.result、status='done' | | 模型 token | `token` | `onToken` | 追加 assistant.content | | 思考开始 | `thinking.start` | `onThinking` | 开启 thinkingActive,创建 trace think 节点 | | 思考增量 | `thinking.delta` | `onThinking` | 追加 thinking 与 trace.text | | 思考结束 | `thinking.end` | `onThinking` | 关闭 thinkingActive | | 完成 | `done` | `onDone` | 结束 streaming,持久化消息 | | 错误 | `error` | `onError` | 标记 messageType='error' | | 心跳 | `heartbeat` | `onHeartbeat` | 更新 lastHeartbeatAt | 心跳流与业务事件流是独立的:心跳通过 `Flux.interval(10s)` 生成,并在连接结束时停止。 **章节来源** - [AgentChatServiceImpl.java:461-599](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/impl/AgentChatServiceImpl.java#L461-L599) ### 前端增量聚合与渲染 `chatStream.ts` 对每个事件的处理策略: - `onIntent`:保存意图识别结果。 - `onSuggestions`:保存扁平建议与方向分组。 - `onThinking`:分段累积思考,维护 `thinkingActive` 与 trace。 - `onToolCall`:新增工具步骤,记录 trace tool 节点。 - `onToolInput`:归一化工具入参文本。 - `onToolResult`:写入结果并标记完成。 - `onToken`:追加正文,并按 100ms 节流执行富内容块增量扫描。 - `onHeartbeat`:仅更新时间戳,不影响 content。 - `onGraphData`:回填 get_case_graph 的全量图谱。 - `onDone`:结束消息 streaming,但整体 finally 仍会清理流状态。 - `onError` / `onTransportError`:设置 messageType 为 error 或 interrupted。 - finally:若收到连接关闭但未收到 done,标记为“连接已结束但未收到完成信号”。 **章节来源** - [chatStream.ts:426-598](file://ai-electron/frontend/src/ai/store/chatStream.ts#L426-L598) ## 会话与消息数据模型 ### 会话实体:`AgentChatSession` | 字段 | 类型 | 含义 | |---|---|---| | `id` | Long | 主键 | | `agent_id` | Long | 绑定的研判方案 | | `model_id` | Long | 会话默认模型 | | `case_id` | Long | 工作空间/案件 | | `title` | String | 会话标题 | | `context` | JSONB | 上下文 | | `message_count` | Integer | 消息数 | | `total_tokens` | Long | 累计 token | | `last_message_at` | LocalDateTime | 最后消息时间 | | `pinned` | Boolean | 是否置顶 | | `attachments` | JSONB | 附件摘要 | | `create_at` | LocalDateTime | 创建时间 | | `update_at` | LocalDateTime | 更新时间 | ### 消息实体:`AgentMessage` | 字段 | 类型 | 含义 | |---|---|---| | `id` | Long | 主键 | | `session_id` | Long | 所属会话 | | `role` | String | user / assistant / system | | `content` | String | 正文 | | `content_type` | String | 内容类型 | | `token_count` | Integer | token 计数 | | `metadata` | JSONB | 思考过程、附件摘要、错误标记等 | | `tool_events` | JSONB | 工具调用事件序列 | | `parent_id` | Long | 父消息 | | `message_type` | String | text / error / interrupted | | `reply_to_message_id` | Long | 回复目标 | | `starred` | Boolean | 是否收藏 | | `create_at` | LocalDateTime | 创建时间 | ### 三者关系 ```mermaid erDiagram AGENT_CHAT_SESSION { long id PK long agent_id long model_id long case_id string title jsonb context int message_count long total_tokens datetime last_message_at boolean pinned jsonb attachments datetime create_at datetime update_at } AGENT_MESSAGE { long id PK long session_id FK string role string content string content_type int token_count jsonb metadata jsonb tool_events long parent_id string message_type long reply_to_message_id boolean starred datetime create_at } INSIGHT_SESSION { long id PK string name jsonb context datetime create_at datetime update_at } AGENT_CHAT_SESSION ||--o{ AGENT_MESSAGE : "包含" ``` **图表来源** - [AgentChatSession.java:1-58](file://ai-server/src/main/java/com/zsjz/ai/module/agent/entity/AgentChatSession.java#L1-L58) - [AgentMessage.java:1-55](file://ai-server/src/main/java/com/zsjz/ai/module/agent/entity/AgentMessage.java#L1-L55) 在对话生命周期中: - `AgentChatSession` 表示一次 Agent 对话会话,绑定工作空间、研判方案和模型。 - `AgentMessage` 表示会话中的一条消息,可以是用户提问、助手回答、错误提示或中断结果。 - Insight 会话是“持续联系 AI 研判”的业务会话,它与 Agent 对话共享同一套 SSE 事件协议,但额外支持 `insight` 帧;前端在 `chatStream.ts` 中通过 `onInsight` 处理。 - 两者并非父子实体,而是不同业务场景下的会话载体:Agent 对话侧重交互式问答,Insight 侧重结构化研判任务。 **章节来源** - [AgentChatSession.java:1-58](file://ai-server/src/main/java/com/zsjz/ai/module/agent/entity/AgentChatSession.java#L1-L58) - [AgentMessage.java:1-55](file://ai-server/src/main/java/com/zsjz/ai/module/agent/entity/AgentMessage.java#L1-L55) ## 典型调用示例 ### 示例一:选择模型后发送文本消息 1. 用户在聊天面板选择某个模型。 2. 输入文本消息。 3. `chatStream.ts` 的 `send(text, modelId)` 被调用。 4. 若当前会话绑定的研判方案与预选不一致,则新建会话。 5. 乐观插入用户消息和助手占位消息。 6. 调用 `streamChat({ sessionKey, message, modelId })`。 7. 后端解析 `sessionKey` 为会话 ID,校验工作空间,建立 Agent 流。 8. 前端逐步累积 token 并渲染。 9. 收到 `done` 后结束流式态,刷新会话标题、消息数和最后消息时间。 注意:`modelId` 在前端类型中要求按字符串传递,避免雪花 ID 精度丢失。 **章节来源** - [chatStream.ts:400-598](file://ai-electron/frontend/src/ai/store/chatStream.ts#L400-L598) - [types.ts:247-260](file://ai-electron/frontend/src/ai/api/types.ts#L247-L260) - [AgentChatServiceImpl.java:345-400](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/impl/AgentChatServiceImpl.java#L345-L400) ### 示例二:查看工具调用日志 工具调用日志保存在 `AgentMessage.tool_events`,前端将其反序列化为 `ToolStep[]`: | 阶段 | 事件 | ToolStep 变化 | |---|---|---| | 开始 | `tool_call` | 新增步骤,状态 running | | 入参 | `tool_input` | 填充 input | | 结果 | `tool_result` | 填充 result,状态 done | | 图谱 | `graph_data` | 回填 graphPayload | 前端还会对历史消息中的 `get_case_graph` 调用进行图谱复原:如果数据库中只存了查询条件,则调用 `/chat/graph/restore` 拉取全量图。 **章节来源** - [chatStream.ts:240-360](file://ai-electron/frontend/src/ai/store/chatStream.ts#L240-L360) - [chatApi.ts:40-46](file://ai-electron/frontend/src/ai/api/chatApi.ts#L40-L46) - [sse.ts:30-120](file://ai-electron/frontend/src/ai/api/sse.ts#L30-L120) ### 示例三:中断或重连 SSE 中断: 1. 用户点击“停止生成”。 2. `chatStream.ts` 调用 `stop()`。 3. `stop()` 清除定时器并调用 `abortController.abort()`。 4. `sse.ts` 捕获 `AbortError` 并向上抛出。 5. `chatStream.ts` catch 分支忽略 `AbortError`,进入 finally。 6. finally 中若未收到 done,且消息仍在 streaming,则标记为 interrupted。 7. 后端可能已持久化部分消息,也可能尚未持久化,因此前端需要提示“以上为已接收内容,请重试”。 重连: - 前端当前实现不会自动重连 SSE。 - 常见做法是让用户重新发送消息,从而重建 `AbortController` 和新的 fetch 连接。 - 如果希望支持重连,应在 `onTransportError` 中暴露重连策略,而不是无限重试同一个 reader。 **章节来源** - [chatStream.ts:550-598](file://ai-electron/frontend/src/ai/store/chatStream.ts#L550-L598) - [sse.ts:201-222](file://ai-electron/frontend/src/ai/api/sse.ts#L201-L222) ## 依赖关系分析 ### 前端模块依赖 ```mermaid graph LR ChatPage["聊天页面组件"] --> ChatStream["chatStream.ts"] ChatStream --> ChatApi["chatApi.ts"] ChatApi --> Sse["sse.ts"] Sse --> Constants["constants.ts"] ChatStream --> Types["types.ts"] Sse --> Types ``` **图表来源** - [chatStream.ts:1-50](file://ai-electron/frontend/src/ai/store/chatStream.ts#L1-L50) - [chatApi.ts:1-80](file://ai-electron/frontend/src/ai/api/chatApi.ts#L1-L80) - [sse.ts:1-20](file://ai-electron/frontend/src/ai/api/sse.ts#L1-L20) - [types.ts:240-260](file://ai-electron/frontend/src/ai/api/types.ts#L240-L260) - [constants.ts:20-28](file://ai-electron/frontend/src/ai/utils/constants.ts#L20-L28) ### 后端模块依赖 ```mermaid graph LR Controller["AgentChatController"] --> Service["AgentChatService"] Service --> Impl["AgentChatServiceImpl"] Impl --> SessionMapper["AgentChatSessionMapper"] Impl --> MessageMapper["AgentMessageMapper"] Impl --> AgentService["AgentService"] Impl --> ModelService["AgentModelService"] Impl --> UsageStore["UsageStore"] Impl --> GraphService["GraphService"] Impl --> CaseAccessGuard["CaseAccessGuard"] ``` **图表来源** - [AgentChatController.java:1-170](file://ai-server/src/main/java/com/zsjz/ai/module/agent/controller/AgentChatController.java#L1-L170) - [AgentChatService.java:1-83](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/AgentChatService.java#L1-L83) - [AgentChatServiceImpl.java:1-120](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/impl/AgentChatServiceImpl.java#L1-L120) **章节来源** - [AgentChatController.java:1-170](file://ai-server/src/main/java/com/zsjz/ai/module/agent/controller/AgentChatController.java#L1-L170) - [AgentChatService.java:1-83](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/AgentChatService.java#L1-L83) - [AgentChatServiceImpl.java:1-120](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/impl/AgentChatServiceImpl.java#L1-L120) ## 性能与内存特性 ### 富内容块增量扫描 `chatStream.ts` 对每次 token 追加并不立即重新扫描全文,而是通过 `RESAN_THROTTLE_MS` 节流,默认约 100ms。这避免了长回答中反复扫描 Markdown/代码/ECharts/Insight 围栏导致的 O(n²) 成本。 已完成块会被冻结复用,进一步降低重复解析压力。 **章节来源** - [chatStream.ts:1-30](file://ai-electron/frontend/src/ai/store/chatStream.ts#L1-L30) - [chatStream.ts:450-520](file://ai-electron/frontend/src/ai/store/chatStream.ts#L450-L520) ### SSE 缓冲区与解码器 `sse.ts` 维护一个字符串缓冲区,逐块拼接后再按 `\n\n` 切分。对于超大响应: - 缓冲区和消息 content 都会持续增长。 - 浏览器侧 `TextDecoder` 以流模式解码,减少一次性转换开销。 - 若后端一次推送 chunk 过大,可能造成单次解析耗时增加。 优化建议: - 控制后端单次 SSE data payload 大小。 - 前端可对过长 response 做上限保护,避免极端情况导致内存暴涨。 **章节来源** - [sse.ts:20-120](file://ai-electron/frontend/src/ai/api/sse.ts#L20-L120) - [sse.ts:160-222](file://ai-electron/frontend/src/ai/api/sse.ts#L160-L222) ### 会话级互斥 `AgentChatServiceImpl` 使用 `ConcurrentHashMap` 保证同一会话只有一条流。这避免: - 双标签页并发写 Agent 记忆槽。 - 多条流交错写 transcript。 - 第一条对话完成后后续消息误报“正在回复中”。 注意:这是进程内锁,多实例部署时需要扩展为分布式锁。 **章节来源** - [AgentChatServiceImpl.java:80-120](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/impl/AgentChatServiceImpl.java#L80-L120) - [AgentChatServiceImpl.java:380-400](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/impl/AgentChatServiceImpl.java#L380-L400) ## 常见问题排查 ### SSE 断连与心跳 现象: - 模型长时间无输出,前端显示“正在输出”,但实际没有新 token。 - 用户看到“连接已结束但未收到完成信号”。 原因: - 服务端模型推理慢,但 SSE 连接未断。 - 中间代理、网关或防火墙提前关闭空闲连接。 - 后端服务进程异常退出。 排查要点: 1. 检查 `lastHeartbeatAt` 是否持续更新。 2. 若心跳停止但 `lastActivityAt` 也很久没变,大概率是连接断了。 3. 若心跳正常但无 token,可能是模型卡住或工具调用阻塞。 4. 后端心跳间隔为 10 秒,前端不应仅凭“长时间无活动”就判定断连。 **章节来源** - [AgentChatServiceImpl.java:593-599](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/impl/AgentChatServiceImpl.java#L593-L599) - [chatStream.ts:460-598](file://ai-electron/frontend/src/ai/store/chatStream.ts#L460-L598) ### token 过期或未登录 现象: - 前端收到 HTTP 200,但 Content-Type 不是 `text/event-stream`。 - 出现“请求失败:服务端未返回事件流”或跳转到登录页。 原因: - 后端 sa-token 校验失败,返回普通 Result JSON,而非 SSE。 - 前端先检测 `Content-Type`,再尝试解析 JSON 中的 code=401。 处理: - 前端会调用 `handleUnauthorizedRedirect` 跳转。 - 用户重新登录后应重新发起对话。 - 不要静默吞掉未登录错误。 **章节来源** - [sse.ts:140-190](file://ai-electron/frontend/src/ai/api/sse.ts#L140-L190) ### 服务端 503 或其他非 SSE 响应 现象: - 前端显示“请求失败(HTTP 503)”或类似错误。 - 工具日志不完整,助手消息可能被标记为 error。 原因: - 网关、负载均衡或后端服务不可用。 - 上游 LLM 提供商返回异常。 - 后端抛出未捕获异常。 处理: - `sse.ts` 会尝试读取响应体并提取 message 或 error。 - 前端 store 将消息标记为 error,并保留已收到的内容。 - 建议添加“重试”按钮,而不是自动无限重试。 **章节来源** - [sse.ts:170-200](file://ai-electron/frontend/src/ai/api/sse.ts#L170-L200) - [chatStream.ts:520-598](file://ai-electron/frontend/src/ai/store/chatStream.ts#L520-L598) ### 大响应导致内存增长 现象: - 长时间对话后,浏览器内存明显上升。 - 超长工具结果或图谱导致渲染卡顿。 原因: - `chatStream.ts` 中 `target.content` 不断拼接 token。 - `sse.ts` 的 buffer 累积未解析文本。 - `tool_steps` 中 result 可能包含大量文本。 - 历史消息恢复图谱时,全量 graph 可能很大。 缓解措施: - 前端限制单条消息最大长度,超出部分截断或折叠。 - 对工具结果采用分页或懒加载。 - 图谱数据优先展示元信息,全量图按需拉取。 - 后端对工具结果长度做合理限制。 **章节来源** - [chatStream.ts:450-520](file://ai-electron/frontend/src/ai/store/chatStream.ts#L450-L520) - [sse.ts:20-120](file://ai-electron/frontend/src/ai/api/sse.ts#L20-L120) ### 中断后刷新看不到消息 现象: - 用户停止生成后刷新页面,助手消息消失。 - 或者只看到半截内容。 原因: - 中断发生在后端持久化之前。 - 前端只做了本地 optimistic 写入,未落库。 - 后端在中断时尝试持久化部分消息,但可能失败或尚未完成。 处理: - 前端在 interrupted 状态下提示“请重试”。 - 后端 `persistPartialMessage` 会写入 messageType=interrupted。 - 若刷新后确实没有消息,属于后端落库失败或服务异常,应记录日志并提示用户。 **章节来源** - [AgentChatServiceImpl.java:781-804](file://ai-server/src/main/java/com/zsjz/ai/module/agent/service/impl/AgentChatServiceImpl.java#L781-L804) - [chatStream.ts:560-598](file://ai-electron/frontend/src/ai/store/chatStream.ts#L560-L598) ## 结论 Agent 对话与 SSE 流式交互是一个典型的前后端实时协作场景: - 前端 `chatApi.ts` 暴露稳定接口,`sse.ts` 处理低层流协议,`chatStream.ts` 承载业务状态机。 - 后端 `AgentChatController` 只做路由,`AgentChatServiceImpl` 负责会话互斥、Agent 事件映射、SSE 帧生产和消息持久化。 - SSE 事件不仅是 token 流,还承载工具调用、思考过程、意图识别、下一步建议和心跳。 - 正确理解 `AgentChatSession`、`AgentMessage` 与 Insight 会话的区别,有助于避免把不同业务会话混为一谈。 - 排障时应优先区分三类问题:认证问题、连接问题、后端业务问题。 - 性能和内存方面,应关注长消息拼接、SSE 缓冲区、工具结果体积和图谱全量数据。