Skip to content

跨境客服助手(六):从 SSE 到 iframe:一条回答怎么带着证据走到页面上 ​

后端把答案算对了,不代表用户能看到对的东西。

一个客服浮层要同时处理:结构化识别结果、工具调用状态、分步答案、引用卡片、转人工提示、降级提示、追问卡。如果这些内容只靠一段文本流式吐出来,前端只能猜“这句话是正文还是提示”,到了异常路径更是没法区分。

所以这里的流不是“字一个个蹦出来”,而是一组有名字、有顺序的完整事件。前端按事件类型渲染,而不是解析自然语言。

一、正常路径的事件顺序 ​

text
structured →(tool)→(conflict)→ steps → citations → done
  • structured:分流结果,哪些字段识别到了、哪些没识别,前端显示“结构化查询”,并明确“缺失字段不猜”;
  • tool:这一轮调了工具就发,含工具名、参数、状态、耗时;
  • conflict:检索发现同一政策有不同版本时发;
  • steps:答案的分步正文,每一步自带引用列表,最后一步带 done: true;
  • citations:完整引用清单;
  • done:消息 ID、引用数、是否拒答、总耗时。

服务端帧格式就是标准 SSE:

python
def sse_event(name: str, payload: dict) -> str:
    return f"event: {name}\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n"

前端用 fetch + ReadableStream 读,按空行切帧,不用 EventSource。原因是 /chat 是 POST,还要带自定义头(比如演示故障注入),EventSource 只支持 GET。

二、异常路径:宁可只有一张卡 ​

这套事件设计里最重要的是哪些路径不发 steps。

事件触发是否发 steps
handoff四类高风险 / 连续失败否
degraded工具超时或报错否
ask缺单号,需要追问否
safe命中安全词否
error管线异常否

原因在第四篇提过:steps 在前端就是“答案正文”。一旦异常路径也发一段文字,用户会默认那是答案,后面的“请转人工”很容易被忽略。

以转人工为例,只发两个事件:

python
yield sse_event("handoff", {**handoff, "messageId": message_id})
yield sse_event("done", {
    "messageId": message_id,
    "citationsCount": 0,
    "refused": True,
    "elapsedMs": elapsed_ms,
})

done.refused = true 是所有非正常回答的统一标记。评测和后台统计都只看这一个字段,不用去猜“这条消息算不算答出来了”。

追问更彻底:只发 ask,连 done 都不发。因为这一轮没有产生 assistant 消息;用户选完选项,前端带 clarify 再请求一次,才算一轮完整问答。

三、steps 为什么按“步”切,而不是按 token ​

pipeline 模式下,答案不是逐 token 生成的。管线先拿到模型输出,做完引用校验、剥离不可核验的引用,才切成若干步发出去。

这样做换来两个能力:

  1. 每一步都能挂引用。前端在对应段落后展示角标,点开落到页码;
  2. 剥离引用后不会留下半句话。校验失败的引用会被拿掉,正文仍然完整;如果全部被剥离,整轮改走 citation_stripped 拒答,不会出现“答案看着有,依据全没了”。

代价是首字延迟更高:用户要先等模型跑完,才开始看到内容。项目里保留了一个 skeleton 模式做折中:先按模板流式吐骨架,再补事实,但骨架模式同样先过转人工规则,且不承诺引用完整。默认仍然是 pipeline,因为客服场景里“慢一点但每句有依据”比“快但可能错”更合适。

后台会话记录:每一轮都带结构化结果、工具调用、引用证据与转人工标记,异常路径的 gateReason 也一并留痕

四、Widget:一个 script 标签,一个同源 iframe ​

宿主页接入只需要一行 script,再加一行可选的上下文注入:

html
<script src="/widget-app/loader.js" data-server="" data-position="right"></script>
<script>MoqianWidget.setContext({ orderNo: 'WB-10001', country: 'US' });</script>

loader.js 没有 init(),脚本执行时就会挂上入口按钮;data-server 留空表示与宿主同源,data-position 控制左右下角。它只做三件事:画一个入口按钮、创建一个同源 iframe、在两边转发消息。真正的对话 UI、状态机、样式全在 iframe 里的 widget.html。

样式隔离是主要原因。宿主站有自己的 button、a、* 规则,浮层直接插进 DOM,很难保证不被污染;iframe 里是一个独立的文档,宿主的 CSS 进不来。

代价是两边不能直接读对方的状态,只能靠 postMessage。

五、握手:ready 之前的消息不能丢 ​

iframe 加载是异步的。宿主页很可能在 ready 之前就调用了 setContext:

js
MoqianWidget.setContext({ orderNo: 'WB-10001', country: 'US' });
MoqianWidget.open();

如果直接 postMessage,这条上下文会在 iframe 还没挂监听时丢掉。所以 loader 里有一个 pending 缓存:

js
var ready = false;
var pending = { context: null, identity: null };

function flush() {
  if (!ready) return;
  if (pending.context !== null || pending.identity !== null) {
    send({
      type: 'moqian:context',
      context: pending.context || {},
      identity: pending.identity || null
    });
  }
  pending = { context: null, identity: null };
}

iframe 发来 moqian:ready 后,先置 ready = true,再把缓存冲出去;如果面板已经是打开状态,还要补发一次 moqian:open。少任何一步,表现都是“第一次打开是空白的,关掉再开又好了”。

反向的消息有五种:

消息方向用途
moqian:readyiframe → 宿主可以接收上下文了
moqian:closeiframe → 宿主面板内关闭按钮
moqian:brandiframe → 宿主品牌名、主色,入口按钮跟着变
moqian:handoffiframe → 宿主转人工时通知宿主页(可接自己的埋点)
moqian:resizeiframe → 宿主预留的尺寸通知,当前靠 CSS 自适应

moqian:handoff 还会在宿主页派发一个 CustomEvent,这样接入方不依赖 loader 的内部实现,监听 document 就行。

六、几个容易被忽略的前端细节 ​

  • 重复引入:loader.js 先检查 window.MoqianWidget,已存在就直接返回,避免一个页面出现两个浮层;
  • 移动端:窄屏下面板靠 CSS 自适应铺开,resize 消息目前只是预留;
  • 减弱动画:prefers-reduced-motion 下把弹出动画压到 1ms;
  • 可访问性:入口按钮带 aria-expanded,打开时把按钮隐藏,避免焦点落到看不见的控件上;
  • 重置会话:reset() 直接重载 iframe,同时清空 pending 和 ready。它比“清空聊天数组”更彻底,也不会留下上一轮的结构化上下文。

七、这条链路的边界 ​

  • 同源 iframe 隔离了样式,但没有隔离权限。iframe 里的请求仍然带着宿主页的 Cookie,接入方要自己确认跨站策略;
  • postMessage 的目标源在当前实现里是 '*'。对演示够用,正式接入应收紧到固定源;
  • SSE 没有断线重连。网络中断后这一轮就结束了,前端提示重试,不做断点续传;
  • 事件协议是内部约定,没有版本号。改字段名要同步改前端,不适合多团队并行演进。

到这里,一条回答从规则、检索、工具、转人工,一路走到了页面上。还差最后一环:那些被证明有用的回答,怎么回到知识库里,而不是散落在聊天记录里。下一篇讲收藏与工单两条进水管。

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