SSE流式输出实战:edgeone-makers-tools如何打造打字机效果的AI对话
SSE流式输出实战:edgeone-makers-tools如何打造打字机效果的AI对话
edgeone-makers-tools 是腾讯云 EdgeOne Makers 平台的官方 AI Agent 开发技能包,它把 SSE 流式输出 约定成了所有 AI 对话端点的统一标准。借助它,你可以轻松打造 打字机效果 的 AI 对话——回答不再干等十几秒,而是像打字机一样一个字一个字蹦出来,配合心跳保活与断线重试,体验丝滑不卡壳。
💡 一句话理解:SSE(Server-Sent Events,服务器推送事件) 是一种让服务器把数据"一段一段"持续推给浏览器的技术。AI 对话正是靠它,才实现了我们熟悉的"边生成边显示"的打字机效果。
一、为什么 AI 对话要靠 SSE 流式输出?
想象一下两种打开 AI 聊天框的体验:
| 体验 | 传统"整段返回" | SSE 流式输出 |
|---|---|---|
| 等待感 | 干等 5~15 秒,屏幕空转 | 0.5 秒就开始蹦字 |
| 观感 | 像卡死了 | 像真人打字 |
| 长回答 | 越等越焦虑 | 边读边生成 |
| 中断处理 | 只能刷新重来 | 可点"停止"即时叫停 |
打字机效果的本质:AI 模型是"一个 token 一个 token"生成的。如果后端把整段话攒完再一次性吐给浏览器,用户就得干等;而 SSE 流式输出让后端"生成一点就推一点",前端每收到一小段就立刻追加到屏幕上——于是文字就像被一台打字机敲出来。
👉 在 makers-agents 技能说明 中,"实现带中断支持的 SSE 流式输出(Implementing SSE streaming with abort support)" 正是被列为 AI 端点必须掌握的核心能力之一。
二、SSE 流式输出的"统一剧本":8 种事件 + 心跳
很多团队各自为战,前端一会儿收到字符串、一会儿收到 JSON,维护起来一锅粥。edgeone-makers-tools 在 SSE 协议约定文档 里,把所有 AI 端点的"说话方式"统一成了一套剧本:
- 每个端点都返回
text/event-stream类型 - 每条消息都是一个带
type字段的 JSON 小块 - 前端根据
type分发处理 - 每 5 秒发一个
ping心跳保活 - 结束时发一个
data: [DONE]收尾
📡 统一事件类型表
| 事件 type | 关键字段 | 通俗含义 |
|---|---|---|
ai_response |
content |
⭐ 打字机主角——模型的增量文本 |
tool_call |
name |
AI 准备调用某个工具(如搜索、查天气) |
tool_result |
name、content |
工具执行结果(截断到约 500 字) |
suggest_actions |
actions[] |
推荐操作(可点击的快捷选项) |
file_output |
base64、filename |
可下载的文件产出 |
usage |
各类 token 数 | 本次消耗的 Token 统计 |
ping |
ts |
心跳,告诉前端"我还活着" |
error_message |
content |
报错,但绝不让整条流崩掉 |
[DONE] |
— | 本轮结束的唯一标志 |
✅ 为什么
ai_response是打字机的主角? 因为它是唯一"增量式"的文本事件。模型每吐出一小段字,后端就发一条ai_response,前端把它拼到气泡里——几十条这样的消息叠加起来,就是你看到的逐字蹦出效果。
一个最简单的消息长这样:
data: {"type":"ai_response","content":"你好"}
data: {"type":"ai_response","content":",有什么"}
data: [DONE]
三、前端怎么"接住"这条流:让打字机不掉字
后端只管往水管里灌水,前端要做的就是边接边显示。这里有两个新手最容易踩的坑,edgeone-makers-tools 在文档里专门给了"保命"提醒:
坑 1:一定要记住"有没有收到 [DONE]"
[DONE] 是区分**"正常结束"和"中途被掐断"**的唯一标志。前端读流时要专门记一个 sawDone 开关:
- 收到了
[DONE]→ 正常收尾 - 没收到、连接却断了 → 说明流被截断,该提示"连接中断,请重试",而不是假装这是一条"空回答"
⚠️ 文档原话:只靠"最后收集到多少字"来判断,会把一次被中断的回合误报成空回答——用户看到"AI 没说话",其实只是网络中途断了。
坑 2:冷启动慢,靠心跳撑住
一个新端点第一次被访问时,AI 实例是"冷"的,可能十秒以上才有第一个字出来。这段时间里,中间的代理、网关、路由器很容易误判"没动静了"就掐断连接。于是每 5 秒发一个 ping 心跳,让中间环节知道"这条流还活着",稳住直到第一个字真正出现。
👉 关于会话与前端调用规范的完整约定,见 conversation-id 前端约定。
四、四根"防卡壳"的响应头(配置一次,全局受益)
SSE 能不能真正"边生成边显示",还取决于响应头是否告诉沿途的代理"别给我攒着"。edgeone-makers-tools 规定 AI 端点必须带上这四个头:
| 响应头 | 值 | 作用 |
|---|---|---|
Content-Type |
text/event-stream |
声明这是一条事件流 |
Cache-Control |
no-cache |
不许缓存,保证实时 |
Connection |
keep-alive |
保持长连接不断开 |
X-Accel-Buffering |
no |
⭐ 告诉 Nginx 等代理"别缓冲",逐段透传 |
🔑 最容易被忽视的就是
X-Accel-Buffering: no——漏了它,流会在代理那里被"攒成一坨"再一次性放出,打字机瞬间变"整段蹦"。
五、一键叫停:/stop 与 conversation-id 的"反向约定"
打字机效果还差最后一块拼图——随时能停。用户点"停止"时,前端会调用 /stop 端点。这里有一条反直觉的铁律:
/chat等 AI 端点 → 必须带makers-conversation-id请求头/stop端点 → 绝对不能带这个头,而是把conversation_id放进请求体
为什么?如果 /stop 也带上会话头,请求会被"粘性路由"钉回同一个正卡住的 AI 实例,反而找不到正在运行的任务,导致"停止"静默失效。
| 端点 | 类型 | 带 makers-conversation-id 头? |
会话 ID 放哪? |
|---|---|---|---|
/chat、/outline 等 AI 端点 |
agent | ✅ 必须 | 放请求头 |
/stop |
agent | ❌ 绝不能 | 放请求体 |
/history、/health 等数据端点 |
cloud-function | 推荐 | 头或体皆可 |
🛠️ 会话 ID 通常由前端生成并存进
localStorage,刷新页面也不丢,这样跨多次提问,AI 还记得你们聊过什么。
六、动手上手:用 edgeone-makers-tools 三步走
好消息是,你不需要从零记这些约定——这正是 edgeone-makers-tools 存在的意义:它是一份"随问随查"的 AI 技能包,把平台规范拆成了按需加载的文档。
- 装技能包:在 Claude Code / Cursor / CodeBuddy 等工具里执行
npx skills add(或从 CodeBuddy 插件市场 / SkillHub 搜索安装),一条命令即可注册。 - 让 AI 帮你写:直接说"在 EdgeOne Makers 上做一个 AI 聊天端点",AI 会自动读取 makers-agents 指南,按统一剧本生成带 SSE 的端点。
- 本地跑起来:用
edgeone makers dev启动,浏览器打开本地预览,就能看到回答逐字蹦出的打字机效果。
📦 这套技能包遵循"一个技能、按需路由"的设计:顶层 SKILL.md 是一张路由表,只有命中当前任务时才去读对应的能力文档,避免一次性塞爆上下文。
七、小结:打字机效果的背后
| 你看到的体验 | 背后的 SSE 机制 |
|---|---|
| 文字逐字蹦出 | ai_response 增量事件 + 前端逐段追加 |
| 等待时不假死 | 每 5 秒 ping 心跳保活 |
| 显示实时不卡顿 | X-Accel-Buffering: no 等四个响应头 |
| 能一键叫停 | /stop + conversation-id 双通道约定 |
| 断了能识别 | [DONE] 收尾 + sawDone 断流检测 |
| 出错不崩 | error_message 事件,绝不让整条流中断 |
一句话收尾:打字机效果不是魔法,而是"SSE 统一剧本 + 心跳保活 + 正确响应头 + 会话约定"四件事的叠加。 edgeone-makers-tools 把这套剧本固化成开箱即用的技能,让你专注写对话逻辑,而不是反复纠结流式协议怎么拼。
📖 想深入细节?直接翻 SSE 协议约定文档,它覆盖了统一事件表、心跳、响应头、可复用 Helper 以及前端读流契约的全部约定。