聊天工作台实战

学习目标

把 A01-A13 的零件装成一个可交付的聊天工作台：会话管理、流式交互、错误处理、调用记录一样不少；并用一份行为验证清单和真实调用记录完成验收。

问题场景

零件各自都工作：状态机没问题、流解析没问题、存储没问题。装到一起第一天就出事：切会话时占位消息残留、重试后调用记录对不上、错误提示盖住正在流出的文本。集成阶段的问题从来不是零件问题，是接缝问题。

核心解释

先定装配顺序，自底向上，每层独立可验证：

1. 服务端能力层   lib/ai/adapter + tools     —— A03 / A15
2. 会话与持久化   route + 三张表              —— A13
3. 流式协议       SSE 事件流                  —— A10
4. 界面状态机     发送 / 流式 / 停止 / 重试    —— A06 / A11 / A12
5. 会话列表 UI    新建 / 切换 / 加载历史       —— A11 / A13

界面骨架就是把各课的钩子组合起来：

function Workbench() {
  const [conversations, setConversations] = useState<Conv[]>([]);
  const [activeId, setActiveId] = useState<string | null>(null);
  const [messages, setMessages] = useState<Msg[]>([]);
  const [status, setStatus] = useState<Status>("idle"); // A06 的四态
  // send / stop / retry / switchTo 的实现分别在 A06、A12、A11 课
}

验收看两组证据。第一组是真实调用记录（对 ai_call 表的检查，A13 的表）：

-- 每次成功对话应有一行：model 非空、token 数为正、耗时有值
SELECT model, prompt_tokens, completion_tokens, latency_ms, status
FROM ai_call ORDER BY created_at DESC LIMIT 10;

第二组是界面行为验证清单，每条都要实际操作：

场景	操作	预期
正常对话	发送一条消息	流式输出，done 后可继续输入
重复提交	streaming 中连点发送	被忽略，无第二条回复
停止	生成中点停止	流停止，半截保留，无错误弹窗
断网重试	Offline 发送 → 恢复 → 重试	unreachable 文案 → 重试成功，无重复消息
切换会话	A 流式中切到 B	A 的请求取消，B 只显示 B 的历史
刷新	生成中刷新	无永久转圈，历史完整

示例拆解

集成期最常见的三个接缝与修法：

// 接缝 1：切会话的三步顺序，错了就残留（A12 + A11 的组合）
function switchTo(id: string) {
  stop();             // 1. 先停当前请求（abort 链）
  resetStreamState(); // 2. 清流式缓冲与占位
  loadHistory(id);    // 3. 再拉目标会话
}
// 接缝 2：错误提示与流式文本并存——错误走独立提示区，不混进消息流
// 接缝 3：重试后 ai_call 多一行记录，这是预期行为，不是重复 bug

关键点：

• 接缝 1 最容易漏第 2 步：请求停了，但缓冲和占位还挂着，新会话里就出现旧残影。
• 规模控制：先跑通「发送 → 流式 → done」主链路，再依次补停止、重试、切换；十个功能同时开工只会全部半成品。
• 交付物清单：验证清单的勾选结果 + 一段真实调用记录（SQL 结果或截图），两者缺一不可。

动手任务

1. 把六行验证清单完整过一遍，逐条记录实际结果；没过的写明原因与下一步。
2. 用 SQL 汇总最近 10 次调用的平均 latency 与总 token 消耗，记进学习笔记。
3. 找一个清单之外的边界场景（超长输入、纯空格消息、连开两个标签页），补进清单并验证。

常见错误

• 跳过集成清单直接交：演示路径通了，边界场景全是坑。
• 用假流验收：demo-stream 能验协议，验不出 token、延迟、错误分类——行为验证必须走真实调用链路。
• 错误提示盖住流式输出：错误与正文挤同一区域，视觉状态打架，用户不知道该看哪个。
• 只验自己设计的路径：清单要覆盖「用户会做的蠢事」：连点、乱切、断网、刷新，而不是只验理想操作。

检查与复盘

自查清单：

• 五层装配顺序能默写，每层对应的课程说得清
• 验证清单全部执行过且留有记录
• ai_call 表里有与清单对应的真实数据

参考资料

• ai-sdk 文档：Chatbot —— 成熟聊天界面的功能面参照，对照你的工作台查漏
• Next.js 文档：Route Handlers —— 服务端链路的组织
• React 官方文档：Managing State —— 多区块状态的组织方式
• 下一课 A15 进入工具调用：让模型「举手申请」而不是「直接执行」。