跨境客服助手:政策查库,订单查工具,风险交给人
跨境独立站的客服问题,大概可以分成三类:
- “美国退货窗口多久?”——答案在政策文档里,但模型不知道你家的政策,也不能替你想;
- “我的订单 WB-10001 到哪了?”——答案在订单系统里,模型更不知道,猜一个到达时间就是事故;
- “我要退款,不然就投诉。”——这类话不该由机器人接,哪怕它背得出退款条款。
moqian-cbecom-assistant 就是按这三类问题长出来的。它不是“一个会聊天的客服”,而是一条先判断该走哪条路、再决定能不能回答的管线:政策查知识库,订单查工具,风险交给人工。
项目地址:zhaoxuejie/moqian-cbecom-assistant,Apache-2.0。自带 13 份英文虚构语料、15 条 mock 订单和 90 条分层评测用例;品牌、客户、订单、政策全部虚构。

你在这里
这是系列概览。先把系统分成几段、每段守什么纪律讲清楚,不展开代码。八篇专题各讲一段,代码和数字都回到仓库里核实过。
一、三条路,四个出口
系统的入口只有一个 /chat,但在调用模型之前,管线已经做过一次确定性分流:
这张图里有四个“出口”,每一个都对应一条产品纪律:
| 出口 | 触发条件 | 行为 |
|---|---|---|
| 转人工 | 退款诉求、投诉、法务、账户安全,或连续两轮失败 | 固定话术 + 联系方式,不检索、不调模型 |
| 追问 | 订单 / 物流类问题但没有单号 | 只问一轮,选项里允许“没有单号” |
| 降级 | 工具超时或报错 | 明说查不到,强制转人工,不给半成品答案 |
| 拒答 | 证据门不过,或引用被剥光 | 说明资料里没有,计入知识缺口 |
除此之外才是正常回答:检索、生成、每一步挂引用。
二、三个“不让模型做”的决定
这套系统里最值得写的不是用了什么模型,而是哪些事坚决不给模型做。
决定一:意图不让模型分类
分流用的是正则和词表,不是提示词。原因很实际:评测要能断言“该调工具调了没、该追问有没有追问”,规则可复现、可解释;模型分类会多一次往返和一份不确定性,而这一层的判断依据本来就明确——单号有固定格式,诉求有固定说法。
更重要的是兜底方向:真判不出来时,默认走 policy,宁可多查一次知识库,也不要猜成“事实问题”去编答案。
决定二:订单事实不让模型润色
工具返回订单状态、物流节点、预计送达之后,回答由固定模板拼出来,字段缺了就写“未提供”。让模型润色一次,等于给它一次编造数字的机会。
这条决定在演示里很直观:把工具超时注入打开,回答不会变成“大概明天到”,而是一句固定降级话术,加一个必须转人工的标记。
决定三:证据不足不让模型“尽力回答”
检索之后有一道代码写的证据门:命中条数、向量最高分、查询词覆盖率,三条硬指标都过才允许生成。不过就返回 gap,把缺的词记进知识缺口。
模型永远愿意“尽力回答”,所以“该拒答”不能交给提示词,只能交给代码。
三、系统长什么样
后端是 FastAPI + PostgreSQL(pgvector),任务队列直接用数据库表,不引 Redis 或 Celery;前端是零构建的原生 JS,访客浮层跑在同源 iframe 里,管理后台单独一套页面。
app/ 业务装配:API、RAG 编排、意图、工具、转人工、品牌
modules/ 通用机制:检索、证据、引用、解析、任务、模型客户端
frontend/ 零构建前端:后台与访客 Widget
migrations/ 有序 SQL 迁移(含 15 条虚构订单)
samples/ 13 份英文虚构语料
evals/ 90 条分层用例与运行器依赖方向是 app → modules,模块之间互不 import;行业词汇(国家、政策、订单号格式、四类风险)只留在 app/,公共层只做机制。这条边界在后面几篇会反复出现——比如“哪些国家适用、哪一版还在生效”属于行业语义,所以它不在检索模块里,而在检索之后的 app/retrieval_policy.py。
四、八篇专题怎么读
| 篇目 | 主题 | 你会看到 |
|---|---|---|
| 一 | 规则意图路由 | 单号识别、政策式问法、追问卡、复用转人工词表 |
| 二 | 两路召回与证据门 | RRF、去重、国家/有效期后置过滤、跨语种覆盖率 |
| 三 | 知识入库流水线 | 700 字切片、页码归属、元数据下放、过期政策 |
| 四 | 订单工具与降级 | 工具选择、5 秒超时、确定性模板、故障注入 |
| 五 | 四类风险转人工 | 只匹配诉求短语、写请求、连续失败阈值 |
| 六 | SSE 与 iframe 浮层 | 事件顺序、异常路径、postMessage 握手 |
| 七 | 知识沉淀两条进水管 | 收藏与工单、待确认候选、幂等键、审核留痕 |
| 八 | 分层评测与部署边界 | 90 条用例、指标口径、三容器编排 |
三条阅读路径:
- 想接客服机器人:先读第一、五篇,把“什么该分流、什么必须交给人”想清楚;
- 想做 RAG 工程:第二、三篇是主线,第四、六篇补工具与链路;
- 想看治理闭环:第七、八篇讲知识怎么回流、怎么证明它没变坏。
五、它现在还不是什么
它没有接 Shopify、支付平台或真实物流。订单和物流是数据库里的虚构 mock 数据,工具调用只证明边界和失败处理,不代表已经完成平台适配。
它也不执行退款、不裁决纠纷、不自动接通外部客服平台。“转人工”在当前实现里是提供联系方式并留痕,需要真实业务系统时得自己补授权、审计与工单回写。
另外,仓库里的表结构保留了源项目的一些字段名(engineer_id、device_model 这类),跨境语义通过 meta_json 和 host_context 承载。这是开源整理时没有彻底改名的技术债,读代码时别被字段名带偏。
下一篇从入口开始:一句话进来,规则怎么在调用模型之前把它分到正确的路上。