会话状态: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,它没有流式阶段。
发送流程分四步:
- 清理首尾空白,空输入或正在生成时直接返回。
- 追加用户消息和空的助手消息,保存助手消息的响应式引用。
- 从“当前消息之前”的历史里挑出可用条目,裁剪后发给后端。
- 逐事件更新助手消息;网络错误、流内错误、用户取消分别落状态。
历史裁剪有三个约束:
- 不发送当前这一轮的用户问题和空回答,所以用
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()不做自动滚动、不做消息编辑,也不负责重试按钮的位置;这些属于入口或视图层。
下一篇看这些状态怎样落到组件上,尤其是流式文本和来源列表的渲染边界。