AI 前端交互与流式体验（SSE / Vercel AI SDK / Tool UI / 引用）

课程目标（14 天）

读完本课你能：

给任意 LangGraph/FastAPI 后端配一个生产级流式前端（Next.js 15 App Router + React 19）。
讲清 SSE / WebSocket / HTTP Streaming / RSC 四种推送方式的取舍。
实现工具调用过程可视化（工具名、参数、中间结果、花费）。
做带引用/高亮的问答与图表报告页（ECharts）。
处理取消、重试、断线续传、乐观更新、错误边界。
具备"AI 前端差异化"能力——这是南京/杭州 50K+ 岗位的显著加分项。

技术选型总览

能力	推荐	备注
框架	Next.js 15 App Router + React 19	RSC + Server Actions 原生支持流
AI SDK	Vercel AI SDK v4	`streamText`、`useChat`、`useObject`
传输	SSE（首选）	单向、HTTP 友好、断线重连好做
可选	WebSocket	双向实时（语音/白板）
渲染	react-markdown + rehype	流式 Markdown + 代码高亮
图表	ECharts 6（或 Recharts）	配合后端 JSON spec
状态	Zustand / React Query	会话列表 + 断线恢复

推送方式四象限

                 服务端推                  双向实时
              ┌──────────────────┬──────────────────┐
 HTTP 友好    │  SSE (text/event) │    WebSocket     │
              │  首选，兼容 CDN    │  语音、协同白板   │
              ├──────────────────┼──────────────────┤
 特殊         │  Chunked HTTP     │  WebTransport    │
              │  (fetch + reader) │  (前沿)          │
              └──────────────────┴──────────────────┘

14 天带练路径

Day 1 — 最小 SSE Demo（Next.js 15）

后端（App Router Route Handler）：

// app/api/chat/route.ts
export async function POST(req: Request) {
  const { prompt } = await req.json();
  const stream = new ReadableStream({
    async start(ctrl) {
      for await (const token of callLLM(prompt)) {
        ctrl.enqueue(new TextEncoder().encode(`data: ${JSON.stringify({ t: token })}\n\n`));
      }
      ctrl.enqueue(new TextEncoder().encode("data: [DONE]\n\n"));
      ctrl.close();
    },
  });
  return new Response(stream, { headers: { "Content-Type": "text/event-stream" } });
}

前端：

"use client";
const [text, setText] = useState("");
const res = await fetch("/api/chat", { method: "POST", body });
const reader = res.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  // 解析 SSE event line
  decoder.decode(value, { stream: true }).split("\n\n").forEach(parseEvent);
}

Day 2 — Vercel AI SDK 封装

// 前端
const { messages, input, handleSubmit, isLoading, stop } = useChat({ api: "/api/chat" });
// 后端
return streamText({ model: openai("gpt-4o"), messages }).toDataStreamResponse();

自带：token 流、useChat 状态机、stop() 取消、错误边界。
验收：Markdown 表格、代码块流式渲染不闪烁。

Day 3 — 流式 Markdown 渲染（避免闪烁）

坑：ReactMarkdown 每 token 重解析造成卡顿。
方案：
- 增量解析 react-markdown + remark-gfm，用 memo。
- 代码块用 react-syntax-highlighter 的 light build，懒加载语言。
- 对话滚动用 scrollIntoView({block:"end"}) 节流 50ms。

Day 4 — 工具调用过程可视化

后端 emit 多种事件：

{"type":"tool_call","name":"search_docs","args":{"q":"..."}}
{"type":"tool_result","name":"search_docs","latency":820,"hits":5}
{"type":"token","delta":"根据检索..."}
{"type":"citation","docs":[{"id":"d12","title":"..."}]}

前端用一个 Timeline 组件分段展示：

⏳ search_docs(q="向量检索") ... 820ms · 5 条结果
🧠 生成中：根据检索，向量检索通常……
📎 引用：[向量数据库入门](/docs/d12)

Day 5 — 引用与高亮（Citation UI）

协议：后端给每段回答加 [[d12:para3]] 占位，前端解析成脚注。
点击引用 → 侧栏打开原文并高亮段落。
做"可追溯"是 RAG 产品的核心信任点，也是面试加分题。

Day 6 — 取消、重试、断线续传

取消：AbortController，同时服务端收到 req.signal.aborted 停 tool。
重试：失败保留上次 prompt，支持一键重发。
断线续传：SSE 事件带 id: <checkpoint>，重连时带 Last-Event-ID 让后端从 checkpoint 继续（需要 agent-state-persistence-hitl 支持）。

Day 7 — 加载骨架与 Suspense

首屏用 RSC + loading.tsx 骨架屏。
工具时延超 300ms 显示 spinner + 预计用时。
对"超过 10s 无反应"自动提示"任务较慢，可稍后查看"。

Day 8 — 报告页与 ECharts

场景：自然语言查数 → 后端返回 JSON spec → 前端渲染图表 + 解读。

const option = useMemo(() => buildECharts(resp.chart), [resp]);
<ReactECharts option={option} style={{ height: 320 }} />
<p className="mt-3 text-sm text-zinc-600">{resp.explanation}</p>

坑：服务端不要渲 ECharts（依赖 canvas），用 next/dynamic({ ssr: false })。
与 ai-data-analysis-system 联动。

Day 9 — 结构化输出与 useObject

用 AI SDK streamObject + zod schema 直接流式产出 JSON（图表参数、表单填充）。
前端 useObject({ schema }) 增量渲染局部字段。
验收：半张图先出来，补齐后自动收敛。

Day 10 — 会话管理与状态同步

Zustand store：threads, activeThreadId, messagesByThread。
每条 user/assistant 消息带 serverMessageId，用于后端 checkpoint 对齐。
刷新/跨页保留：persist 中间件 + localStorage。

Day 11 — 错误边界与可恢复 UI

<ErrorBoundary> 包住每个工具卡与渲染器。
网络 5xx → 红条 + "重试" 按钮；流中途 DONE_ERR → 保留已输出 + 小字提示。
把错误 trace_id 暴露给用户，方便客服查询。

Day 12 — 可访问性与性能

aria-live="polite" 流式区域，屏幕阅读器不连续打断。
prefers-reduced-motion 关动画。
长对话用 react-virtuoso 虚拟滚动，避免 DOM 膨胀。
首屏 LCP < 2.5s、交互 INP < 200ms。

Day 13 — 审批卡片 UI（HITL 前端）

当后端进入 interrupt，前端收到 type: "interrupt" 事件 → 渲染审批卡：动作、参数、影响面、批准/拒绝按钮。
提交 → POST /approve → 后端 resume(thread_id, decision)。
与 agent-state-persistence-hitl 闭环。

Day 14 — 面试演示项目

做一个"可视化 Research Agent"：流式 + 工具过程 + 引用 + 报告图表 + 可中断。
录 3 分钟 demo 视频，准备 8 分钟讲稿。

协议设计示例（自研事件协议）

type AgentEvent =
  | { type: "token"; delta: string }
  | { type: "tool_call"; id: string; name: string; args: unknown }
  | { type: "tool_result"; id: string; ok: boolean; summary: string; latencyMs: number }
  | { type: "citation"; refs: { docId: string; para: number; title: string }[] }
  | { type: "chart"; spec: EChartsOption; explanation: string }
  | { type: "interrupt"; payload: unknown }
  | { type: "error"; code: string; message: string; traceId: string }
  | { type: "done"; totalTokens: number; cost: number };

前端按 type 分发到不同渲染器，天然可扩展。

面试高频追问（深度版）

为什么选 SSE 而不是 WebSocket？ LLM 绝大多数场景是服务器→客户端单向流，SSE 天然兼容 HTTP/2、CDN、代理；双向语音才上 WS。
流式 Markdown 卡顿怎么解？ 减少重算（memo）、代码高亮懒加载、按句 flush 而不是按字符。
如何做"可追溯"问答？ 后端生成时内嵌引用占位 → 前端解析 → 点击定位原文；同时写 trace_id 便于审计。
用户断网后重连，如何续传？ SSE 事件带 id + 后端持久化 checkpoint（见 agent-state-persistence-hitl）。
前端怎么展示工具失败？ Timeline 显示 tool_result.ok=false，红色 + "重试"按钮；不要让错误静默吞掉。
RSC 适合做 AI 前端吗？ 静态外壳适合（布局、路由、SEO），交互 + 流推送仍要 Client Component。
取消请求时后端怎么协同？ req.signal.aborted 级联传给 LLM provider 和 tool；LangGraph 用 RunnableConfig.cancel。

常见陷阱

流式接口返回 application/json 导致中间件缓冲——必须 text/event-stream 并禁用 buffering。
Nginx 反代默认 proxy_buffering on，流被缓；需 proxy_buffering off; proxy_read_timeout 600s;。
useChat 把 messages 直接对象比较，漏掉增量更新。
图表每 token 重绘，卡死浏览器；必须等 tool_result 再渲染。
忘了给流式区域 aria-live，a11y 审核不过。

可交付产物

app/(chat)/...（Next.js 15 聊天外壳）
components/AgentTimeline.tsx
components/CitationPopover.tsx
components/ReportCard.tsx（ECharts）
components/ApprovalCard.tsx
lib/agent-event.ts（协议类型 + 解析器）

级别	资源
A	Vercel AI SDK 文档
A	Next.js 15 Streaming & Suspense
A	React 19 `use()` & Suspense
A	MDN SSE（EventSource）
A	ECharts 官方
B	LangGraph Streaming Guide（Python 侧）
B	Virtuoso / TanStack Virtual 虚拟滚动

课程目标（14 天）

读完本课你能：

给任意 LangGraph/FastAPI 后端配一个生产级流式前端（Next.js 15 App Router + React 19）。
讲清 SSE / WebSocket / HTTP Streaming / RSC 四种推送方式的取舍。
实现工具调用过程可视化（工具名、参数、中间结果、花费）。
做带引用/高亮的问答与图表报告页（ECharts）。
处理取消、重试、断线续传、乐观更新、错误边界。
具备"AI 前端差异化"能力——这是南京/杭州 50K+ 岗位的显著加分项。

技术选型总览

能力	推荐	备注
框架	Next.js 15 App Router + React 19	RSC + Server Actions 原生支持流
AI SDK	Vercel AI SDK v4	`streamText`、`useChat`、`useObject`
传输	SSE（首选）	单向、HTTP 友好、断线重连好做
可选	WebSocket	双向实时（语音/白板）
渲染	react-markdown + rehype	流式 Markdown + 代码高亮
图表	ECharts 6（或 Recharts）	配合后端 JSON spec
状态	Zustand / React Query	会话列表 + 断线恢复

推送方式四象限

                 服务端推                  双向实时
              ┌──────────────────┬──────────────────┐
 HTTP 友好    │  SSE (text/event) │    WebSocket     │
              │  首选，兼容 CDN    │  语音、协同白板   │
              ├──────────────────┼──────────────────┤
 特殊         │  Chunked HTTP     │  WebTransport    │
              │  (fetch + reader) │  (前沿)          │
              └──────────────────┴──────────────────┘

14 天带练路径

Day 1 — 最小 SSE Demo（Next.js 15）

后端（App Router Route Handler）：

// app/api/chat/route.ts
export async function POST(req: Request) {
  const { prompt } = await req.json();
  const stream = new ReadableStream({
    async start(ctrl) {
      for await (const token of callLLM(prompt)) {
        ctrl.enqueue(new TextEncoder().encode(`data: ${JSON.stringify({ t: token })}\n\n`));
      }
      ctrl.enqueue(new TextEncoder().encode("data: [DONE]\n\n"));
      ctrl.close();
    },
  });
  return new Response(stream, { headers: { "Content-Type": "text/event-stream" } });
}

前端：

"use client";
const [text, setText] = useState("");
const res = await fetch("/api/chat", { method: "POST", body });
const reader = res.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  // 解析 SSE event line
  decoder.decode(value, { stream: true }).split("\n\n").forEach(parseEvent);
}

Day 2 — Vercel AI SDK 封装

// 前端
const { messages, input, handleSubmit, isLoading, stop } = useChat({ api: "/api/chat" });
// 后端
return streamText({ model: openai("gpt-4o"), messages }).toDataStreamResponse();

自带：token 流、useChat 状态机、stop() 取消、错误边界。
验收：Markdown 表格、代码块流式渲染不闪烁。

Day 3 — 流式 Markdown 渲染（避免闪烁）

坑：ReactMarkdown 每 token 重解析造成卡顿。
方案：
- 增量解析 react-markdown + remark-gfm，用 memo。
- 代码块用 react-syntax-highlighter 的 light build，懒加载语言。
- 对话滚动用 scrollIntoView({block:"end"}) 节流 50ms。

Day 4 — 工具调用过程可视化

后端 emit 多种事件：

{"type":"tool_call","name":"search_docs","args":{"q":"..."}}
{"type":"tool_result","name":"search_docs","latency":820,"hits":5}
{"type":"token","delta":"根据检索..."}
{"type":"citation","docs":[{"id":"d12","title":"..."}]}

前端用一个 Timeline 组件分段展示：

⏳ search_docs(q="向量检索") ... 820ms · 5 条结果
🧠 生成中：根据检索，向量检索通常……
📎 引用：[向量数据库入门](/docs/d12)

Day 5 — 引用与高亮（Citation UI）

协议：后端给每段回答加 [[d12:para3]] 占位，前端解析成脚注。
点击引用 → 侧栏打开原文并高亮段落。
做"可追溯"是 RAG 产品的核心信任点，也是面试加分题。

Day 6 — 取消、重试、断线续传

取消：AbortController，同时服务端收到 req.signal.aborted 停 tool。
重试：失败保留上次 prompt，支持一键重发。
断线续传：SSE 事件带 id: <checkpoint>，重连时带 Last-Event-ID 让后端从 checkpoint 继续（需要 agent-state-persistence-hitl 支持）。

Day 7 — 加载骨架与 Suspense

首屏用 RSC + loading.tsx 骨架屏。
工具时延超 300ms 显示 spinner + 预计用时。
对"超过 10s 无反应"自动提示"任务较慢，可稍后查看"。

Day 8 — 报告页与 ECharts

场景：自然语言查数 → 后端返回 JSON spec → 前端渲染图表 + 解读。

const option = useMemo(() => buildECharts(resp.chart), [resp]);
<ReactECharts option={option} style={{ height: 320 }} />
<p className="mt-3 text-sm text-zinc-600">{resp.explanation}</p>

坑：服务端不要渲 ECharts（依赖 canvas），用 next/dynamic({ ssr: false })。
与 ai-data-analysis-system 联动。

Day 9 — 结构化输出与 useObject

用 AI SDK streamObject + zod schema 直接流式产出 JSON（图表参数、表单填充）。
前端 useObject({ schema }) 增量渲染局部字段。
验收：半张图先出来，补齐后自动收敛。

Day 10 — 会话管理与状态同步

Zustand store：threads, activeThreadId, messagesByThread。
每条 user/assistant 消息带 serverMessageId，用于后端 checkpoint 对齐。
刷新/跨页保留：persist 中间件 + localStorage。

Day 11 — 错误边界与可恢复 UI

<ErrorBoundary> 包住每个工具卡与渲染器。
网络 5xx → 红条 + "重试" 按钮；流中途 DONE_ERR → 保留已输出 + 小字提示。
把错误 trace_id 暴露给用户，方便客服查询。

Day 12 — 可访问性与性能

aria-live="polite" 流式区域，屏幕阅读器不连续打断。
prefers-reduced-motion 关动画。
长对话用 react-virtuoso 虚拟滚动，避免 DOM 膨胀。
首屏 LCP < 2.5s、交互 INP < 200ms。

Day 13 — 审批卡片 UI（HITL 前端）

当后端进入 interrupt，前端收到 type: "interrupt" 事件 → 渲染审批卡：动作、参数、影响面、批准/拒绝按钮。
提交 → POST /approve → 后端 resume(thread_id, decision)。
与 agent-state-persistence-hitl 闭环。

Day 14 — 面试演示项目

做一个"可视化 Research Agent"：流式 + 工具过程 + 引用 + 报告图表 + 可中断。
录 3 分钟 demo 视频，准备 8 分钟讲稿。

协议设计示例（自研事件协议）

type AgentEvent =
  | { type: "token"; delta: string }
  | { type: "tool_call"; id: string; name: string; args: unknown }
  | { type: "tool_result"; id: string; ok: boolean; summary: string; latencyMs: number }
  | { type: "citation"; refs: { docId: string; para: number; title: string }[] }
  | { type: "chart"; spec: EChartsOption; explanation: string }
  | { type: "interrupt"; payload: unknown }
  | { type: "error"; code: string; message: string; traceId: string }
  | { type: "done"; totalTokens: number; cost: number };

前端按 type 分发到不同渲染器，天然可扩展。

面试高频追问（深度版）

为什么选 SSE 而不是 WebSocket？ LLM 绝大多数场景是服务器→客户端单向流，SSE 天然兼容 HTTP/2、CDN、代理；双向语音才上 WS。
流式 Markdown 卡顿怎么解？ 减少重算（memo）、代码高亮懒加载、按句 flush 而不是按字符。
如何做"可追溯"问答？ 后端生成时内嵌引用占位 → 前端解析 → 点击定位原文；同时写 trace_id 便于审计。
用户断网后重连，如何续传？ SSE 事件带 id + 后端持久化 checkpoint（见 agent-state-persistence-hitl）。
前端怎么展示工具失败？ Timeline 显示 tool_result.ok=false，红色 + "重试"按钮；不要让错误静默吞掉。
RSC 适合做 AI 前端吗？ 静态外壳适合（布局、路由、SEO），交互 + 流推送仍要 Client Component。
取消请求时后端怎么协同？ req.signal.aborted 级联传给 LLM provider 和 tool；LangGraph 用 RunnableConfig.cancel。

常见陷阱

流式接口返回 application/json 导致中间件缓冲——必须 text/event-stream 并禁用 buffering。
Nginx 反代默认 proxy_buffering on，流被缓；需 proxy_buffering off; proxy_read_timeout 600s;。
useChat 把 messages 直接对象比较，漏掉增量更新。
图表每 token 重绘，卡死浏览器；必须等 tool_result 再渲染。
忘了给流式区域 aria-live，a11y 审核不过。

可交付产物

app/(chat)/...（Next.js 15 聊天外壳）
components/AgentTimeline.tsx
components/CitationPopover.tsx
components/ReportCard.tsx（ECharts）
components/ApprovalCard.tsx
lib/agent-event.ts（协议类型 + 解析器）

学完这篇你应该拿到什么

3 个高频追问

1 个证据

沉淀表达

面试时怎么讲

简历一句话

课程目标（14 天）

技术选型总览

推送方式四象限

14 天带练路径

Day 1 — 最小 SSE Demo（Next.js 15）

Day 2 — Vercel AI SDK 封装

Day 3 — 流式 Markdown 渲染（避免闪烁）

Day 4 — 工具调用过程可视化

Day 5 — 引用与高亮（Citation UI）

Day 6 — 取消、重试、断线续传

Day 7 — 加载骨架与 Suspense

Day 8 — 报告页与 ECharts

Day 9 — 结构化输出与 useObject

Day 10 — 会话管理与状态同步

Day 11 — 错误边界与可恢复 UI

Day 12 — 可访问性与性能

Day 13 — 审批卡片 UI（HITL 前端）

Day 14 — 面试演示项目

协议设计示例（自研事件协议）

面试高频追问（深度版）

常见陷阱

可交付产物

最新资料（2026-05 校验）

学完这篇你应该拿到什么

3 个高频追问

1 个证据

沉淀表达

面试时怎么讲

简历一句话

课程目标（14 天）

技术选型总览

推送方式四象限

14 天带练路径

Day 1 — 最小 SSE Demo（Next.js 15）

Day 2 — Vercel AI SDK 封装

Day 3 — 流式 Markdown 渲染（避免闪烁）

Day 4 — 工具调用过程可视化

Day 5 — 引用与高亮（Citation UI）

Day 6 — 取消、重试、断线续传

Day 7 — 加载骨架与 Suspense

Day 8 — 报告页与 ECharts

Day 9 — 结构化输出与 useObject

Day 10 — 会话管理与状态同步

Day 11 — 错误边界与可恢复 UI

Day 12 — 可访问性与性能

Day 13 — 审批卡片 UI（HITL 前端）

Day 14 — 面试演示项目

协议设计示例（自研事件协议）

面试高频追问（深度版）

常见陷阱

可交付产物

最新资料（2026-05 校验）