搭建 AI 助手前端 · 从零实现流式对话界面
这个系列只做一件事:把“后端能回答”变成“用户能顺畅地问、看、停、重试”。从事件协议开始,逐层写出一个可测试的流式对话前端。
读者与范围
默认你了解 Vue 3、TypeScript、fetch 和 HTTP 的基本概念。这里不解释组件语法、ref / computed 的用法,也不从 SSE 是什么讲起;重点放在为什么这样拆分、状态放在哪里、异常怎样收束。
后端如何切片、检索和生成,已经写在 AI助手后端实现。本系列从浏览器拿到一条 SSE 响应之后开始,沿着“解析 → 状态 → 组件 → 入口 → 代理 → 测试”往上走。
一条主线
/chat 页面 或 全站浮窗
↓
ChatConversation(只负责展示与交互)
↓
useChat(消息状态机、历史、取消)
↓
readChatEvents(把字节流拆成事件)
↓
POST /api/assistant/chat(同源)
↓
Nitro 代理
↓
FastAPI /api/chat
前端不直接访问模型,也不保存 API Key。浏览器只认识自己的域名,后端地址留在服务端配置里。
系列地图
| 编号 | 文章 | 核心问题 |
|---|---|---|
| 01 | 需求与边界:先定义对话体验 | 一个聊天界面到底要拆成哪些能力 |
| 02 | 协议先行:用四种事件描述一次回答 | 为什么先定 sources / token / done / error |
| 03 | 解析 SSE:不要假设一次 read 就是一条事件 | 任意分块、CRLF、异常与结束怎样处理 |
| 04 | 会话状态:useChat 的消息状态机 | 消息状态、历史裁剪、取消与错误恢复 |
| 05 | 对话界面:组件边界与流式渲染 | 怎样让流式内容稳定地渲染,而不把状态散在组件里 |
| 06 | 两种入口:独立页面与全站浮窗 | 同一套对话怎样服务深链接与随手提问 |
| 07 | 同源代理:Nitro 转发与 fail-closed | 浏览器怎样只认识一个地址,生产入口怎样默认关闭 |
| 08 | 可访问性与测试:让流式界面可用可验证 | 焦点、读屏、键盘路径和假流测试怎样落地 |
| 09 | 联调与边界:从本地可用到可以公开 | 本地怎样跑通,公开上线还缺什么 |
阅读路线可以按目标选:
- 想复刻聊天主流程:01 → 02 → 03 → 04 → 05。
- 想接入现有站点:01 → 06 → 07 → 09。
- 想补质量和测试:02 → 03 → 04 → 08。
- 完整通读:01 → 09。
代码地图
frontend/
app/
pages/chat.vue 独立聊天页
components/chat/
AssistantFeature.vue 功能开关入口
ChatLauncher.vue 全站浮窗与对话框
ChatConversation.vue 共享对话视图
ChatComposer.vue 输入与发送
ChatMessageItem.vue 单条消息
ChatSources.vue 参考来源
composables/useChat.ts 会话状态机
utils/chat-stream.ts SSE 增量解析
types/chat.ts 协议与消息类型
server/api/assistant/chat.post.ts 同源代理
tests/nuxt/ 解析、状态、浮窗、代理测试
e2e/ 键盘路径、响应式与 axe 检查
当前实现边界
已经实现:/chat 页面、全站浮窗、流式回答、来源展示、停止生成、失败重试、同源代理、键盘与读屏基础、单元与端到端测试。
尚未实现:登录鉴权、用户配额、按 IP / 用户限流、跨刷新会话持久化、回答质量评测、生产部署。生产模式下代理会直接返回 404,功能开关不是安全边界。第 09 篇会把这张表展开。
阅读约定
每篇按“结论 → 问题与设计 → 关键代码 → 验证 → 边界”组织。代码以当前仓库为准;没实现的能力写成边界,不用“能跑”代替“可以公开”。所有文章当前都是 draft: true。系列就是所在文件夹 03-搭建AI助手前端,00-目录.md 是系列第一篇,也是普通长文。文章 slug 规则是 <英文系列>-<两位序号>-<英文主题词>,本系列以 ai-frontend- 开头,例如 ai-frontend-01-requirements、ai-frontend-05-chat-ui。