Skip to content

售后知识助手(六):SSE 与一行代码都不改的浮层 ​

跟客户 IT 聊集成,最常听到的一句话是:「我们那个工单系统是好几年前外包做的,源码……在不在都不好说。」

这不是玩笑。很多设备厂的售后系统就是这样:能用,没人敢动。你让他们改前端、接 SDK、加一个 React 组件,项目当场就黄了。

所以浮层的设计目标只有一条:客户的系统一行业务代码都不用改,在页面模板末尾加两行 script 就能用。

你在这里

浮层提问 → 安全红线 → 结构化条件 → 混合检索 → 证据门 → 生成与引用校验 → SSE 返回

一、两行 script 接入 ​

宿主页面要做的全部事情:

html
<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 来行,做三件事:

  1. 把浮层面板放进一个同源的 iframe。客户老系统的 CSS 可能写得很野,* { box-sizing: content-box }、全局 button 样式,什么都有。iframe 是最彻底的样式隔离,浮层里的东西不受宿主影响,也不污染宿主。
  2. 暴露一个很小的全局对象 window.MoqianWidget:setContext()、open()、close()、reset(),就这四个方法。
  3. 用 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 + 流式读取,自己按空行切帧:

javascript
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,中文不转义,抓包和看日志时能直接读:

python
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 道评测题是怎么出的、怎么判的、哪里还不够。

本文阅读--次|全站访问--次|访客--人