售后知识助手(六):SSE 与一行代码都不改的浮层
跟客户 IT 聊集成,最常听到的一句话是:「我们那个工单系统是好几年前外包做的,源码……在不在都不好说。」
这不是玩笑。很多设备厂的售后系统就是这样:能用,没人敢动。你让他们改前端、接 SDK、加一个 React 组件,项目当场就黄了。
所以浮层的设计目标只有一条:客户的系统一行业务代码都不用改,在页面模板末尾加两行 script 就能用。
你在这里
浮层提问 → 安全红线 → 结构化条件 → 混合检索 → 证据门 → 生成与引用校验 → SSE 返回
一、两行 script 接入
宿主页面要做的全部事情:
<script src="/widget-app/loader.js" data-server="" data-position="right"></script>
<script>
MoqianWidget.setContext(
{ ticketNo: 'HY-WO-2026-0107', deviceModel: 'HY-G1000/1.6-JXW', batch: 'B23 及以后' },
{ source: 'host_injected', claimedEngineerId: 'HY-ENG-006' }
)
</script>第一行加载浮层,右下角出现一个圆形按钮。第二行告诉浮层「当前是哪张工单、哪台设备、谁在用」,工单号、型号、批次通常就在页面上,模板里本来就能取到。
loader.js 只有 200 来行,做三件事:
- 把浮层面板放进一个同源的 iframe。客户老系统的 CSS 可能写得很野,
* { box-sizing: content-box }、全局button样式,什么都有。iframe 是最彻底的样式隔离,浮层里的东西不受宿主影响,也不污染宿主。 - 暴露一个很小的全局对象
window.MoqianWidget:setContext()、open()、close()、reset(),就这四个方法。 - 用 postMessage 把上下文送进 iframe。浮层从来不直接读宿主页面的 DOM,宿主给什么它用什么。
还有个小细节:宿主页面可能不小心把 loader 引了两次(模板继承里很常见),第一行就判断 window.MoqianWidget 是否已存在,避免页面上叠出两个浮层。
上下文不是凭证
这里要讲清楚一个安全边界。postMessage 送进来的上下文,浮层是照单全收的:loader 发消息时目标源写的是 '*',iframe 里收消息时也没有校验来源。
这样做能成立,是因为上下文在这个系统里不授予任何权限:
- 型号、批次只用来收窄检索范围。传错了,最坏的结果是查不到、回退全库,结构化条件卡片上会明确提示。
- 工号是一个声明,后端会做「在册校验」:这个工号在不在账号表里。在册就记为「已识别」,问答日志归到这个人名下;不在册就是「未识别」,照样能问。后台问答日志的页脚写得很直白:身份来源是「声明 + 在册校验」,不是身份认证,不用于任何授权。
也就是说,有人伪造上下文,能做到的只是「用别人的工号问了几个问题」,拿不到任何别人看不到的东西。
如果将来上下文要承载权限
比如按工号限制能看哪些资料,那 postMessage 的来源校验就必须收紧(发送方写明目标源,接收方校验 event.origin),而且工号要换成宿主签发、后端可验证的令牌。现在的松,是因为它确实不需要紧;需求一变,这里是第一个要改的地方。
二、为什么是 SSE,又为什么不用 EventSource
服务端往浏览器推数据,常见的是 WebSocket 和 SSE。这里是单向推送:工程师问一句,服务端回一串事件,不需要双向通道。SSE 就是普通的 HTTP 响应,过代理、过网关、过公司防火墙都更省心。
但浏览器自带的 EventSource 有两个硬限制:只能发 GET,不能加自定义请求头。而 /chat 要 POST 一个问题加上下文,还要在请求头里带会话凭证 X-Widget-Session。所以前端用的是 fetch + 流式读取,自己按空行切帧:
var reader = resp.body.getReader();
var decoder = new TextDecoder('utf-8');
var buffer = '';
while (true) {
var chunk = await reader.read();
if (chunk.done) break;
buffer += decoder.decode(chunk.value, { stream: true });
var idx;
while ((idx = buffer.indexOf('\n\n')) >= 0) {
var raw = buffer.slice(0, idx);
buffer = buffer.slice(idx + 2);
var frame = parseFrame(raw);
if (frame) onEvent(frame.name, frame.data);
}
}frontend/widget/adapters/api.js#L88-L135
decode(..., { stream: true }) 不能省。一个汉字是 3 个字节,网络分包可能正好切在一个汉字中间,不带 stream: true 就会解出乱码。
服务端那头,构造一帧只要一行,但要注意 ensure_ascii=False,中文不转义,抓包和看日志时能直接读:
def sse_event(name: str, payload: dict) -> str:
data = json.dumps(payload, ensure_ascii=False)
return f"event: {name}\ndata: {data}\n\n"踩坑:反向代理会把流「攒」起来
SSE 最常见的故障不在代码里,在 Nginx 里。它默认会缓冲上游响应,攒够了再一起发给浏览器,前端看到的就是「等了半天,所有内容一次性蹦出来」。/chat 的响应头里固定带着 X-Accel-Buffering: no 和 Cache-Control: no-cache,契约里也写明了这两个响应头的固定取值。
三、事件契约:十个名字,一个顺序
/chat 一共可能发出十种事件,名字和载荷结构都写在接口契约里,第 1 篇提到的契约测试会检查事件名集合有没有漂移:
| 事件 | 什么时候发 |
|---|---|
structured | 永远是第一帧:这一问用的检索条件(现象、型号、批次、缺了什么) |
ask | 条件不够,追问一轮(比如先确认批次) |
conflict | 命中多个批次的资料,提示并列展示 |
steps | 排查步骤,每步一帧,带引用编号 |
citations | 本次回答引用的证据清单 |
done | 正常结束 |
gap | 证据不足,拒答 |
safe | 命中安全红线 |
refused | 演示环境额度用完 |
error | 服务异常 |
正常路径的顺序是固定的:structured →(conflict)→ steps → citations → done。异常路径有一条硬规矩,写在服务端代码的开头:
异常路径
gap/safe/error不发半成品答案。
也就是说,一旦走到拒答或出错,前面绝不会已经推出去几个步骤。工程师不会看到「前三步给了,第四步说资料不足」这种让人不知道该不该照做的局面。
四、说是流式,其实是「先算完,再分帧」
这里得说句实话。在默认的问答模式下,服务端是等整轮计算全部完成(检索、证据门、生成、引用校验),才开始一帧一帧往外发的。第一帧 structured 到达浏览器的时候,答案其实已经算好了。
为什么不像聊天机器人那样一个字一个字地吐?因为步骤在推送之前必须先通过引用校验。如果边生成边推,第 2 步已经显示在屏幕上了,校验才发现它的引用是编的,这时候再把它撤回来,工程师可能已经照着做了。在这个场景里,「先显示、后撤回」比「慢一点」要糟糕得多。
代价是首帧等待时间约等于整轮时延,评测里 p50 是 3.8 秒。这段时间里浮层显示的是「正在检索手册与历史工单……」。
这块还有改进空间,我心里有两个方向:
- 把
structured提前发。检索条件在检索之前就确定了,没必要等生成完。这只需要把问答管线拆成两段,先发条件卡,再算答案。 - 按步骤流式。引用校验本来就是逐行做的,一个步骤就是一行。模型每吐完一行,校验这一行,合格就推出去。这样既是流式,又不会推出未经校验的内容。
两件都不难,只是目前的时延还在可接受范围内,优先级没排上来。
五、引用原文:按需取,只给看过的
步骤后面的引用编号是可以点开的,点开看到的是这个证据单元的全文和出处。首屏的 citations 事件里只有标题和出处摘要,原文等工程师点开时再取,避免一次塞进整本手册。
取原文的接口有一条限制,契约里写着:只返回本轮命中证据集内的编号,不存在就 404,不泄露库内其它切片。实现上是查这个会话里被引用过的证据。浮层不是一个「随便输编号就能翻知识库」的口子,你只能看到系统给你看过的东西。
六、失败要说人话
浮层里的每一种失败,都写成了工程师能看懂、知道下一步该干什么的话:
- 网络断了:「与助手的连接中断了,本次回答未完成;网络恢复后会自动重试一次,也可以点『重新连接』立即重试。」
- 模型超时:「模型服务超时或报错,本次未生成回答;若持续失败请转人工,接通时会连同当前工单与对话一并带过去。」
- 证据不足:第 4 篇讲过的拒答卡,附带转人工按钮。
工程师常在机房、井道里用平板,信号不好是常态,所以断网之后会自动重试一次,而不是直接报错了事。
七、不需要 npm install 的前端
整个前端是零构建的:原生 JavaScript,没有 React、没有 Vue、没有打包工具,由后端同源托管,改完刷新浏览器就能看到。浮层要嵌进客户的老系统,后台要能在一台没有 Node 环境的服务器上跑,零构建是最省事的选择。
不用框架,不代表没有结构。frontend/README.md 定了三层边界:
| 层 | 职责 | 禁止 |
|---|---|---|
展示层(pages/、styles/) | 结构、样式、文案骨架 | |
控制器层(controllers/) | DOM 渲染、交互、状态流转 | 直接 fetch |
适配层(adapters/) | 调接口、字段映射 | 操作 DOM |
接口形状变了,只改适配层;页面改版,只改展示层和控制器。两端唯一共用的是一份设计令牌 tokens.css(颜色、字体、状态色),README 里还专门解释了为什么没有 shared/ 组件层:两端的 DOM、图标和交互并不共用,硬抽一层只会制造耦合。
行业词汇同样不进前端:欢迎语、示例问题、品牌色、转人工文案,全部由后端配置下发。浮层的 app.js 有 1200 行,里面找不到「电梯」两个字。
八、小结
| 设计 | 理由 |
|---|---|
| 两行 script + iframe | 客户老系统不用改代码;样式双向隔离 |
| 上下文走 postMessage,不当凭证 | 只收窄检索、归属日志,不授予任何权限 |
| fetch 读流,自己切帧 | EventSource 不能 POST、不能带请求头 |
| 事件名写进契约 | 前后端以契约为准,测试防漂移 |
| 先校验,再推送 | 不能把未经校验的步骤推到工程师面前 |
| 引用原文只给看过的 | 浮层不是翻知识库的口子 |
| 零构建、三层边界 | 部署省心;没有框架也有结构 |
问答链路到这里就走完了。下一篇换个角度:怎么证明这条链路真的靠谱,那 80 道评测题是怎么出的、怎么判的、哪里还不够。