需求与边界:先定义对话体验
结论
前端要交付的不是“把请求发出去”,而是一条完整的对话体验:用户提问后,先看到参考来源,再看到回答逐字出现;可以中途停止;失败后能重试;两个入口都不打断站点其他区域;键盘和读屏也能走完这条路。
这些能力不能等到页面写完再补。它们决定了协议、状态和组件边界。
问题与设计
先看后端已经提供了什么:POST /api/chat 返回 text/event-stream,事件依次是 sources、若干 token、done,异常时用 error 结束。浏览器不能像处理普通 JSON 一样等响应结束再渲染,因为回答本身就是一个持续打开的过程。
把需求拆成六项:
| 能力 | 用户看到什么 | 前端要负责什么 |
|---|---|---|
| 提问 | 输入框、发送按钮、Enter 发送 | 本地校验、空输入不发送、请求期间禁用重复提交 |
| 流式回答 | 回答逐步出现,而不是长时间空白 | 增量解析、把 token 追加到当前消息 |
| 来源 | 回答下方出现可点击的原文链接 | 在 sources 事件到达时保存并展示 |
| 停止 | 生成中显示“停止生成” | 中止请求,把消息标记为已取消而不是失败 |
| 失败恢复 | 错误提示与“重试” | 区分连接失败、流中途失败和用户主动取消 |
| 两个入口 | /chat 独立页;全站右下角浮窗 |
复用同一套状态与视图,不复制聊天逻辑 |
架构上只保留三层:
入口层:/chat 页面、ChatLauncher 浮窗
视图层:ChatConversation、MessageItem、Sources、Composer
状态层:useChat + readChatEvents
入口只决定“在哪儿聊”,视图只负责“怎么显示”,状态层负责“消息现在是什么状态、请求是否还活着”。这样 /chat 和浮窗可以共享 ChatConversation,但各自持有独立会话,不会在切换页面时把两段对话混在一起。
几个有意不做的选择:
- 不引入全局聊天 store。 当前没有跨页面恢复会话的需求,局部的
useChat()更简单。以后要做会话列表,再把持久化层抽出来。 - 不直接渲染 Markdown。 流式过程中 Markdown 语法经常只到达一半,直接交给
v-html既有 XSS 风险,也会让未闭合的代码块闪烁。当前按纯文本渲染,保留换行。 - 不做本地消息持久化。 刷新即清空,避免把“临时会话”误认为“账号历史”。
- 不把功能开关当成权限。 前端开关只决定是否显示入口;生产环境的代理另有 fail-closed 逻辑。
关键代码
页面和浮窗都只做一件事:把 useChat() 的输出交给 ChatConversation。
<ChatConversation
:messages="messages"
:busy="isStreaming"
:error="error"
@send="ask"
@stop="stop"
@retry="retry"
/>
ChatConversation 不知道请求发往哪里,也不知道 SSE 怎样解析;它只接收消息、忙碌状态和错误文案,向上发出 send、stop、retry。这条边界让组件可以被页面和浮窗同时复用,也让测试可以只替换 fetch,不依赖真实模型。
验证
第一版按下面几条验收,不依赖模型质量:
- 发送后立即出现用户消息和一条空的助手消息,而不是等完整回答。
- 第一段 token 到达时,回答区域已经能看到文字。
- 生成中再次按发送不会产生第二个请求。
- 点“停止生成”后,消息显示“回答已停止”,而不是错误。
- 后端不可达时显示可读错误,并且还能继续发送下一条。
- 来源链接能在新回答下方出现,指向站内笔记详情。
这些行为分别对应解析器、状态机和组件测试,后续文章会逐层展开。
边界
当前版本没有登录、配额、限流和会话持久化;/api/chat 会产生真实模型成本,不能因为界面上有入口就公开暴露。也没有实现消息自动跟随滚动、输入法组词时的 Enter 保护和 Markdown 渲染,这些是发布前要继续补的体验细节。
下一篇先把事件协议定下来。协议稳定后,解析、状态和 UI 才有共同的依据。