跨境客服助手(六):从 SSE 到 iframe:一条回答怎么带着证据走到页面上
后端把答案算对了,不代表用户能看到对的东西。
一个客服浮层要同时处理:结构化识别结果、工具调用状态、分步答案、引用卡片、转人工提示、降级提示、追问卡。如果这些内容只靠一段文本流式吐出来,前端只能猜“这句话是正文还是提示”,到了异常路径更是没法区分。
所以这里的流不是“字一个个蹦出来”,而是一组有名字、有顺序的完整事件。前端按事件类型渲染,而不是解析自然语言。
一、正常路径的事件顺序
structured →(tool)→(conflict)→ steps → citations → donestructured:分流结果,哪些字段识别到了、哪些没识别,前端显示“结构化查询”,并明确“缺失字段不猜”;tool:这一轮调了工具就发,含工具名、参数、状态、耗时;conflict:检索发现同一政策有不同版本时发;steps:答案的分步正文,每一步自带引用列表,最后一步带done: true;citations:完整引用清单;done:消息 ID、引用数、是否拒答、总耗时。
服务端帧格式就是标准 SSE:
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 在前端就是“答案正文”。一旦异常路径也发一段文字,用户会默认那是答案,后面的“请转人工”很容易被忽略。
以转人工为例,只发两个事件:
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 生成的。管线先拿到模型输出,做完引用校验、剥离不可核验的引用,才切成若干步发出去。
这样做换来两个能力:
- 每一步都能挂引用。前端在对应段落后展示角标,点开落到页码;
- 剥离引用后不会留下半句话。校验失败的引用会被拿掉,正文仍然完整;如果全部被剥离,整轮改走
citation_stripped拒答,不会出现“答案看着有,依据全没了”。
代价是首字延迟更高:用户要先等模型跑完,才开始看到内容。项目里保留了一个 skeleton 模式做折中:先按模板流式吐骨架,再补事实,但骨架模式同样先过转人工规则,且不承诺引用完整。默认仍然是 pipeline,因为客服场景里“慢一点但每句有依据”比“快但可能错”更合适。

四、Widget:一个 script 标签,一个同源 iframe
宿主页接入只需要一行 script,再加一行可选的上下文注入:
<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:
MoqianWidget.setContext({ orderNo: 'WB-10001', country: 'US' });
MoqianWidget.open();如果直接 postMessage,这条上下文会在 iframe 还没挂监听时丢掉。所以 loader 里有一个 pending 缓存:
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:ready | iframe → 宿主 | 可以接收上下文了 |
moqian:close | iframe → 宿主 | 面板内关闭按钮 |
moqian:brand | iframe → 宿主 | 品牌名、主色,入口按钮跟着变 |
moqian:handoff | iframe → 宿主 | 转人工时通知宿主页(可接自己的埋点) |
moqian:resize | iframe → 宿主 | 预留的尺寸通知,当前靠 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 没有断线重连。网络中断后这一轮就结束了,前端提示重试,不做断点续传;
- 事件协议是内部约定,没有版本号。改字段名要同步改前端,不适合多团队并行演进。
到这里,一条回答从规则、检索、工具、转人工,一路走到了页面上。还差最后一环:那些被证明有用的回答,怎么回到知识库里,而不是散落在聊天记录里。下一篇讲收藏与工单两条进水管。