kongdeqiang
2026-10-09 f55d84f8479f35f780c535d2d4f4836727363255
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
/**
 * SSE 客户端封装。
 *
 * ## 为什么用 fetch 而不是浏览器原生 EventSource
 *
 * 文档最初设想用 EventSource,但 EventSource 有两个无法绕开的限制:
 *
 * 1. **不能自定义请求头**。它无法携带 `Authorization: Bearer`,
 *    只能靠 URL query 传 token,而 URL 会进入 nginx access log、
 *    浏览器历史与 Referer,是实打实的凭据泄露面。
 * 2. **无法主动中断**。只有 `close()`,无法区分「用户点了停止」和
 *    「网络断开」,也拿不到 HTTP 状态码与错误响应体 —— 后端返回的
 *    「Ollama 未启动」这类有价值提示会被静默吞掉。
 *
 * `fetch` + `ReadableStream` 手动解析 SSE 能同时解决这两点,
 * 且服务端协议完全不变(依然是 `text/event-stream` + `event:`/`data:` 帧),
 * 后端不需要为前端实现方式做任何妥协。
 *
 * 若你确实需要用原生 EventSource,见文件末尾的 `streamChatViaEventSource`。
 */
 
const SSE_DATA_PREFIX = 'data:'
const SSE_EVENT_PREFIX = 'event:'
 
/**
 * 建立 SSE 连接并流式消费事件。
 *
 * @param {object} options
 * @param {string} options.url           请求地址(相对 /api 路径)
 * @param {string} options.token         JWT,放入 Authorization 头
 * @param {(event: string, data: object) => void} options.onEvent 事件回调
 * @param {(error: Error) => void} [options.onError]   错误回调
 * @param {() => void} [options.onClose] 流正常结束回调
 * @returns {{ abort: () => void }} 控制器,调用 abort() 中断连接
 */
export function streamChat({ url, token, onEvent, onError, onClose }) {
  const controller = new AbortController()
  // 用户主动中断的标志:用于在 catch 里区分「主动停止」与「真的出错」
  let abortedByUser = false
 
  /**
   * 终止回调只允许触发一次。
   *
   * 这是修一个真实 bug 的关键:`abort()` 主动中断时,`reader.read()` 是否
   * 会 reject 一个 AbortError 在不同浏览器/不同时刻表现并不一致 ——
   * 有时它只是安静地返回 { done: true },于是 onClose 永远不触发,
   * 调用方的 `streaming` 标志就卡在 true:发送按钮**永久变灰**,
   * 必须刷新页面才能恢复。
   *
   * 因此不再依赖「异常是否抛出」来决定收尾,而是显式收口:
   * abort() 立即结算,流自然结束也结算,谁先到算谁,只结算一次。
   */
  let settled = false
 
  const settle = (fn) => {
    if (settled) return
    settled = true
    fn?.()
  }
 
  const run = async () => {
    let response
    try {
      response = await fetch(url, {
        method: 'GET',
        headers: {
          Accept: 'text/event-stream',
          Authorization: `Bearer ${token}`
        },
        signal: controller.signal,
        // 不使用 Cookie 认证,避免 CSRF 面
        credentials: 'omit'
      })
    } catch (err) {
      // 主动中断由 abort() 负责结算,这里直接返回,避免重复回调
      if (abortedByUser || err.name === 'AbortError') {
        return
      }
      settle(() => onError?.(new Error('无法建立连接,请确认后端服务已启动')))
      return
    }
 
    // 后端在流开始前返回错误(如 401、404、400),此时是普通 JSON 响应
    if (!response.ok) {
      let message = `请求失败 (HTTP ${response.status})`
      try {
        const body = await response.json()
        if (body?.msg) message = body.msg
      } catch {
        // 响应体不是 JSON,沿用默认提示
      }
      settle(() => onError?.(new Error(message)))
      return
    }
 
    if (!response.body) {
      settle(() => onError?.(new Error('当前浏览器不支持流式响应(ReadableStream 不可用)')))
      return
    }
 
    const reader = response.body.getReader()
    const decoder = new TextDecoder('utf-8')
    // 跨 chunk 的残留数据:一个 SSE 帧可能被 TCP 分片切开
    let buffer = ''
 
    try {
      while (true) {
        const { done, value } = await reader.read()
        if (done) break
 
        buffer += decoder.decode(value, { stream: true })
 
        // SSE 帧以空行分隔。把完整帧逐个取出来处理,剩余部分留回 buffer。
        let separatorIndex
        while ((separatorIndex = findFrameEnd(buffer)) !== -1) {
          const rawFrame = buffer.slice(0, separatorIndex)
          buffer = buffer.slice(separatorIndex).replace(/^(\r?\n){2}/, '')
          handleFrame(rawFrame, onEvent)
        }
      }
 
      // 处理最后一个可能没有以空行结尾的帧
      if (buffer.trim()) {
        handleFrame(buffer, onEvent)
      }
 
      settle(onClose)
    } catch (err) {
      // 主动中断已由 abort() 结算,这里静默返回
      if (abortedByUser || err.name === 'AbortError') {
        return
      }
      settle(() => onError?.(new Error(`读取流数据失败: ${err.message}`)))
    } finally {
      try {
        reader.releaseLock()
      } catch {
        // 流已关闭,忽略
      }
    }
  }
 
  run()
 
  return {
    abort() {
      abortedByUser = true
      // 先中断网络请求,再立即结算 —— 不等待 reader.read() 抛错,
      // 否则异常语义在浏览器间不一致时会漏掉收尾,导致 loading 卡死
      controller.abort()
      settle(onClose)
    }
  }
}
 
/**
 * 找到第一个完整 SSE 帧的结束位置。
 *
 * 兼容 `\n\n` 与 `\r\n\r\n` 两种换行风格 ——
 * 不同代理(nginx / 某些网关)会改写换行符。
 */
function findFrameEnd(text) {
  const lf = text.indexOf('\n\n')
  const crlf = text.indexOf('\r\n\r\n')
  if (lf === -1) return crlf
  if (crlf === -1) return lf
  return Math.min(lf, crlf)
}
 
/**
 * 解析单个 SSE 帧并触发回调。
 *
 * 帧格式:
 *   event: delta
 *   data: {"type":"delta","delta":"你"}
 *
 * 以 `:` 开头的行是注释(常用于心跳),直接忽略。
 */
function handleFrame(rawFrame, onEvent) {
  let eventName = 'message'
  const dataLines = []
 
  for (const line of rawFrame.split(/\r?\n/)) {
    if (!line || line.startsWith(':')) continue
 
    if (line.startsWith(SSE_EVENT_PREFIX)) {
      eventName = line.slice(SSE_EVENT_PREFIX.length).trim()
    } else if (line.startsWith(SSE_DATA_PREFIX)) {
      // 去掉前缀后的一个空格(规范允许 `data:foo` 与 `data: foo`)
      dataLines.push(line.slice(SSE_DATA_PREFIX.length).replace(/^ /, ''))
    }
  }
 
  if (dataLines.length === 0) return
 
  const payload = dataLines.join('\n')
  let parsed
  try {
    parsed = JSON.parse(payload)
  } catch {
    // 非 JSON 载荷(理论上本项目的后端不会这样发)按纯文本处理
    parsed = { type: eventName, delta: payload }
  }
 
  onEvent?.(eventName, parsed)
}
 
/**
 * 原生 EventSource 备用实现。
 *
 * **仅在你愿意接受 token 出现在 URL 中时使用。**
 * 服务端已支持 `?token=` 认证(见 JwtAuthenticationFilter),
 * 因此这个实现在功能上可用,但请务必:
 *   - 生产环境通过 nginx 关闭该路径 query 的日志记录
 *   - 强制 HTTPS,避免 token 明文传输
 *
 * @param {object} options
 * @param {string} options.baseUrl  后端地址,如 'http://localhost:8080'
 * @param {number} options.chatId
 * @param {string} options.token
 * @param {object} options.params   query 参数:content/parentId/model/useRag
 * @param {(event: string, data: object) => void} options.onEvent
 * @param {(error: Error) => void} [options.onError]
 */
export function streamChatViaEventSource({
  baseUrl = '',
  chatId,
  token,
  params,
  onEvent,
  onError
}) {
  const query = new URLSearchParams({
    ...params,
    token
  })
  const url = `${baseUrl}/api/chats/${chatId}/stream?${query.toString()}`
 
  const source = new EventSource(url)
 
  // 逐个注册后端约定的事件类型。
  // EventSource 不提供「监听所有事件」的能力,必须显式列出。
  for (const eventName of ['start', 'delta', 'title', 'done', 'error']) {
    source.addEventListener(eventName, (event) => {
      try {
        onEvent?.(eventName, JSON.parse(event.data))
      } catch (err) {
        onError?.(new Error(`解析 ${eventName} 事件失败: ${err.message}`))
      }
      // done / error 之后流已结束,主动关闭以释放后端 SseEmitter
      if (eventName === 'done' || eventName === 'error') {
        source.close()
      }
    })
  }
 
  source.onerror = () => {
    // EventSource 会自动重连,但对话流不该重连(会重复生成)。
    // 因此这里直接关闭并把控制权交给上层。
    source.close()
    onError?.(new Error('SSE 连接中断'))
  }
 
  return {
    abort() {
      source.close()
    }
  }
}