跳到主要内容
Ed. notes

搭建 AI 助手前端 · 从零实现流式对话界面

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

  • 前端架构
  • AI助手
  • 产品设计
第 1 / 10 篇 · 查看全部章节 → 当前:搭建 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。