跳到主要内容
Ed. notes

会话状态:useChat 的消息状态机

长文 · 2026-11-12 · 合集第 5 / 10 篇

  • Vue
  • 状态管理
  • AI助手
第 5 / 10 篇 · 查看全部章节 → 当前:会话状态:useChat 的消息状态机

结论

useChat() 是前端的会话状态机:它持有消息数组、是否正在流式生成、当前错误和请求控制器。组件不直接调用 fetch,也不自己拼接 token。

一次发送产生两条消息:用户消息立即完成,助手消息以 streaming 状态占位,随后由事件推进到 complete、cancelled 或 error。

问题与设计

如果只在组件里放一个 loading 和一个 answer 字符串,很快就会遇到几个问题:

  • 多条消息时,无法知道哪一条正在生成、哪一条失败。
  • 用户点“停止”后,界面不能把已生成的部分保留下来并标记为取消。
  • 下一次请求需要带上历史,但失败或未完成的回答不能进入历史。
  • /chat 页面和浮窗各有一份状态,不能用一个模块级单例互相污染。

消息结构因此带上 status:

export interface ChatMessage {
  id: string
  role: 'user' | 'assistant'
  content: string
  sources: ChatSource[]
  status: 'streaming' | 'complete' | 'cancelled' | 'error'
}

助手消息的状态流转是单向的:

streaming → complete
streaming → cancelled
streaming → error

已完成的回答不会因为下一次请求失败而回退。用户消息创建时就是 complete,它没有流式阶段。

发送流程分四步:

  1. 清理首尾空白,空输入或正在生成时直接返回。
  2. 追加用户消息和空的助手消息,保存助手消息的响应式引用。
  3. 从“当前消息之前”的历史里挑出可用条目,裁剪后发给后端。
  4. 逐事件更新助手消息;网络错误、流内错误、用户取消分别落状态。

历史裁剪有三个约束:

  • 不发送当前这一轮的用户问题和空回答,所以用 slice(0, -2)。
  • 失败、取消、仍在生成的助手回答不进入历史;空内容也不进入。
  • 最多 6 条,单条最多 2000 字,和后端请求模型保持一致。

这样做不是“省略数据”,而是避免把无效上下文送给模型:一个失败的回答没有语义价值,一段未完成的回答还会让下一轮请求依赖不完整的信息。

关键代码

历史过滤集中在 toHistoryEntry():

function toHistoryEntry(message: ChatMessage) {
  const content = message.content.trim().slice(0, MAX_HISTORY_CONTENT)
  if (!content) return undefined
  if (message.role === 'assistant' && message.status !== 'complete') return undefined
  return { role: message.role, content }
}

发送时先占位,再消费事件:

messages.value.push({
  id: crypto.randomUUID(),
  role: 'assistant',
  content: '',
  sources: [],
  status: 'streaming',
})
// 必须修改数组中的响应式代理对象;保留 push 前的原始对象引用不会触发视图更新。
const answer = messages.value[messages.value.length - 1] as ChatMessage

const history = messages.value
  .slice(0, -2)
  .map(toHistoryEntry)
  .filter((entry): entry is NonNullable<typeof entry> => Boolean(entry))
  .slice(-MAX_HISTORY_MESSAGES)

controller = new AbortController()
isStreaming.value = true

for await (const event of readChatEvents(response.body, controller.signal)) {
  if (event.event === 'sources') answer.sources = event.data.sources
  if (event.event === 'token') answer.content += event.data.text
  if (event.event === 'done') answer.status = 'complete'
  if (event.event === 'error') throw new Error(event.data.message)
}

这里有一个真实的坑:messages.value.push(obj) 之后,数组里存的是 obj 的响应式代理版本。如果继续修改原始的 obj,视图不会更新。代码从数组末尾重新取出 answer,后续的 content += 和 status = 才作用在代理上。

取消和错误分开处理:

} catch (cause) {
  if (controller.signal.aborted) {
    answer.status = 'cancelled'
  } else {
    answer.status = 'error'
    error.value = cause instanceof Error ? cause.message : '暂时无法获取回答,请稍后重试。'
  }
} finally {
  isStreaming.value = false
  controller = undefined
}

用户点“停止”只调用 controller.abort()。fetch 和解析器都会收到同一个信号,服务端检测到断开后停止生成。前端把这种情况显示成“回答已停止”,不是“请求失败”,因为用户知道自己在做什么。

还有一个终态保护:如果流正常结束但没收到 done,说明连接被中途关闭,必须当成错误,不能把半截回答标成完成。

if (answer.status === 'streaming') throw new Error('回答流意外结束')

验证

测试不启动真实后端,用 vi.stubGlobal('fetch', ...) 返回手工构造的 ReadableStream:

  • 发送后消息顺序是 user → assistant,来源和 token 正确落到助手消息。
  • 流还开着时,页面文本会随 token 更新;收到 done 后状态变为 complete。
  • 两个 useChat() 实例互不影响,证明页面和浮窗的会话是隔离的。
  • 第一次请求失败后,第二次请求的历史里只有用户问题,没有失败回答。
  • 超长回答进入历史前被截断到 2000 字。
  • 停止后状态是 cancelled;网络错误后状态是 error;再次发送可以恢复。
cd frontend
npm run test -- tests/nuxt/chat.spec.ts

边界

  • 会话只在内存里,刷新页面即清空;没有会话 id、持久化或多标签页同步。
  • 历史只保留最近 6 条,且按“消息条数”截断,不按 token 数计算;长对话的上下文预算仍可能不准。
  • 用户主动取消后,对应的用户问题会保留在下一轮历史里,助手回答不会;这是当前选择,是否保留问题要结合产品语义再定。
  • 错误文案直接来自 Error.message,目前是本地可控的短句;如果以后展示后端错误码,需要先做映射,不能把内部信息直接透出。
  • useChat() 不做自动滚动、不做消息编辑,也不负责重试按钮的位置;这些属于入口或视图层。

下一篇看这些状态怎样落到组件上,尤其是流式文本和来源列表的渲染边界。