xinyouhe/ai-kefu-jc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
143dfd4789361bce61ad0ccea2ef2148a73f3908
ai-kefu-jc/docs/superpowers/specs/2026-09-29-building-materials-ai-kefu-design.md
T

12 KiB
Raw Blame History

HESUPIPE 建材 AI 客服 — 设计文档

  • 日期：2026-09-29
  • 状态：已与需求方逐节确认
  • 参考项目：D:\refactor\ai-kefu（Hesu Auto 汽车出口 AI 客服，同集团姊妹业务）
  • 本项目目录：D:\refactor\ai-kefu-jc

1. 背景与目标

集团汽车业务（hesucar.com）已有一个成熟的 AI 客服系统（FastAPI + SQLite + 智谱 GLM）， 实现"AI 需求了解 + 留资获客 + 邮件/CRM 推送"闭环。现要为管道建材业务 （HESUPIPE，hesupipe.com，河南和硕集团）复制一套功能相同的 AI 客服。

核心需求：

  • AI 客服嵌入 hesupipe.com 外贸站，服务全球 B2B 管道采购买家
  • AI 只做"需求了解 + 留资"：价格/交期/MOQ 等实质问题一律转客户经理（不明确回答）
  • 线索通过邮件 + UniService CRM 推送交给人工
  • 管理后台查看会话/画像/意向/推送日志

非目标（v1 明确不做）：

  • RAG/向量知识库（参考项目已论证否决，静态事实卡防编造）
  • 人工坐席实时接管对话
  • 前端界面 i18n / 阿语 RTL 适配（记 v2）

2. 方案选型

方案 A（已选定）：完整拷贝 + 建材化定制 —— 复制参考项目全部架构与测试， 按清单定制 ~15% 行业相关内容。

已否决：方案 B（从零搭建，工作量翻倍易漏成熟机制）、方案 C（多行业单代码库改造， 动已上线的稳定项目）。

方案 A 的固有代价：两项目 ~85% 代码相同，上游修 bug 需手动同步。缓解：本项目 CLAUDE.md 记录上游项目路径与 changelog 目录，维护时对照。

3. 复制边界

复制：app/、static/、tests/、scripts/、docs/（changelog 归档保留）、 Dockerfile、docker-compose.yml、deploy.sh、openresty.conf、 requirements*.txt、pytest.ini、.gitignore、.dockerignore、.env.example。

排除：.git/（新项目新建仓库）、data/cc_ai_kefu.db（含生产数据，从空库开始）、 .env（含真实密钥）、__pycache__/、.pytest_cache/、.ruff_cache/、 .playwright-mcp/。

顺手清理：

  • 删除 static/blog.html（WordPress 演示宿主页，与客服功能无关）
  • 移除 redis：requirements 依赖、docker-compose 服务、.env.example 配置 （代码从未使用，纯减负）

4. 提示词建材化设计（核心定制）

四个文件框架结构全部保留，只换行业语义：

4.1 system.md（人设与边界）

  • 六段结构保留：语言规则/职能边界/红线/说话风格/对话推进/好差示例
  • 人设：HESUPIPE 管道出口外贸销售
  • 知识域：管材品类（HDPE/PVC/PPR/球墨铸铁等）、口径（DN/mm/inch）、 压力等级（PN/SDR）、标准（ISO4427/ASTM/SCH 系列）、应用场景 （给水/燃气/排污/灌溉/疏浚/养殖）
  • 预算路径："Which application? Water supply, gas, drainage or irrigation?" （替代汽车项目的 "SUV or sedan?"）
  • 红线补充：MOQ、交期 lead time、装柜 container loading、样品费 sample、 认证证书清单、价格区间——一律不明确回答，引导留资转客户经理
  • 好差示例改写为管道真实场景（如 PE100 给水管 DN110 PN16、PVC 排水管）
  • 语言规则（含多语言墙配套，见 §6）：保留"客户用什么语言就用什么语言回复"； 新增约束——拒绝价格/交期/MOQ 等实质问题时，必须包含固定英文短句 （"Please leave your contact and our manager will send the full quotation"）， 保证输出墙正则可靠拦截
  • 回复时效话术用 "reply within 12 hours" 类承诺，不提中国作息时间

4.2 company_facts.md（公司事实卡 = 全部知识库）

  • 内容来源：抓取 hesupipe.com（首页/关于我们/产品分类页/证书页/销售网络/ 新闻中的真实项目案例）
  • 收录范围：公司概况（1998 年成立、2007 年起出口、河南郑州）、十大产品线总表、 应用领域、认证、销售网络
  • 只收录可验证硬事实，WordPress 模板化填充内容（物流/客服段落）一律不收
  • 不含：价格、交期、产能硬数据、MOQ——未知一律走"转客户经理"兜底
  • 防编造原则（统一兜底/不扩展）原样保留
  • 审核关卡（必经步骤）：事实卡初稿完成后，需求方业务侧（懂管道产品的人） 逐条过目确认，审核通过才可上线——AI 说的每句公司情况都来自这张卡，卡错则 AI 一本正经说错话

4.3 extractor.md（信息提取字段）

中文键画像字段改建材语义：

  • 意向品类（HDPE 给水管/PVC 排水管/…）
  • 规格要求：自由文本保留客户原话（不过度结构化——客户经理报价需要原文复述）
  • 标准要求单独一列（ISO/ASTM/EN/SCH）
  • 采购数量、用途（给水/燃气/排污/灌溉）、项目类型、目标国家、预算提及

4.4 evaluator.md（意向评估）

三级（interested / not_interested / pending）保留；评估语义改管道采购： 明确品类+规格+数量 = 高意向；泛泛了解 = pending。

5. 代码级改动清单

位置 改动
app/services/conversation.py BOUNDARY_TRIGGER_RE 补建材触发词（MOQ、lead time、装柜、container loading、sample、certificate）；context 种子 vehicle_name/vehicle_id → product_name/product_id；提醒话术"车型"→"产品方案"
app/services/boundary_filter.py 见 §6 多语言墙分层设计；汽车特定排除项（公里/km/年款/车龄）改为建材排除项（DN/mm/inch/PN/SDR 规格数字、ISO/ASTM 标准号）
app/services/contact_pipeline.py canon 归一化加一行 Unicode→ASCII 数字转换（٠-٩→0-9，阿语号码 CRM 可直接拨）
app/services/email_service.py 发件人名【XYH】→【HESUPIPE】
app/main.py FastAPI title → "HESUPIPE AI 客服"
app/api/routes/chat_rest.py docstring、context 种子键名同步
app/services/rate_limit.py docstring 更新
scripts/breach_rate.py 价格词模式跟随多语言扩充同步
DB 文件名 data/hesupipe_ai_kefu.db
docker-compose 容器名 hs-ai-kefu（redis 服务删除）
openresty.conf 路径 hesupipe_ai_kefu

已验证无需改动：lead_push_service.py（payload 的 profile 为 raw_info 整体 透传，零行业字段硬编码）、static/admin.html 画像渲染（Object.keys 动态）。

6. 多语言输出墙分层设计（漏洞 1 修订）

参考项目现状：提示词要求跟随任意语言，但正则墙只精确覆盖中英；语言无关的 零号码墙（≥10 位数字）和 $+数字模式兜底其余。汽车项目英语流量占绝对主力， 暴露面小；建材项目南美（西语）/中东（阿语）/俄语区/欧洲流量占比高，必须扩充。

分层设计（沿用参考项目思路 + 按建材市场扩充）：

  1. 保留：中英全量模式、零号码墙、邮箱墙（语言无关，已验证）
  2. 扩充价格墙：
    • 货币：€+数字（参考项目没有，对欧出口必备）、£+数字（英国流量）
    • 西语/葡语/俄语/阿语高频价格词+数字组合： precio/costo/preço（巴西为南美最大单一市场）/цена/стоимость/سعر/ثمن
    • 时间承诺：días/semanas/дней/недель/أيام
  3. 迂回话术池：EN/ZH 基础上加 ES 池（南美第一大流量）；其余语言 fallback 英文（与参考项目"粗匹配+默认英文"同构）
  4. 提示词配套（见 §4.1）：拒绝话术必含固定英文短句，保证正则可靠命中
  5. 防误杀验证：DN800、PN16、SDR11、PE100、600mm、SCH40、3/4 inch、 ISO4427、20ft/40ft 等规格形态不得触发价格墙/零号码墙（专项测试）

7. 集成与部署配置

项 配置
UniService 推送 代码原样；external_key_prefix=ai-kefu-jc（与汽车项目线索隔离）；API URL/Key 沿用现有 UniService 账号
邮件 SMTP 沿用现有配置；NOTIFY_EMAIL 指向管道业务客户经理邮箱
LLM 智谱 GLM（glm-4-flash），Key 复用或新建均可
端口 8017（汽车项目 8016 旁）
域名 实施时需求方提供（如 ai.hesupipe.com）
前端联系 WhatsApp 与邮箱默认值见 §11（实施时需求方确认）

开发期安全流程（漏洞 2 修订）：开发与验收阶段 PUSH_ENABLED=false + scripts/mock_uniservice.py 本地联调 + NOTIFY_EMAIL 指测试邮箱； 全部验收通过后一次性切换生产配置。最终状态为启用（需求方已确认）。

8. 前端改动

  • chat.html / widget.js / chat.js：HESU Support → HESUPIPE Support； 欢迎语改管道场景（"What kind of piping project are you working on?"）； 热门话题（Get Quotation / Pipe Specifications / Delivery & Shipping）； WhatsApp/邮箱默认值更新
  • admin.html：VOLT → HESUPIPE
  • theme.js 默认品牌色：橙 #f08a31 → HESUPIPE 品牌蓝（色值实施时从官网取； widget data-color 覆盖机制保留）
  • 头像图片：换管道主题/HESUPIPE logo（需求方提供或生成）
  • GDPR（第二轮深挖新增项）：挂件首次对话前加一行 "By chatting, you agree to our privacy policy"（隐私政策页放 hesupipe.com， WordPress 侧）；上线前完成，不阻塞开发
  • 官网嵌入交付（第三轮补充，必交付物）：产出一段可直接粘贴的挂件嵌入代码 （script 标签 + data-* 配置示例）+ 给官网管理员的一页接入说明 （贴在哪、怎么配主题色/位置/WhatsApp 号）。系统做完≠有人用——官网不挂上去， 买家看不到，等于白做

9. 测试策略

9.1 自动化测试（LLM 全 mock，验证代码正确性）

  1. 全量拷贝 170+ 测试 → 更新含文案断言的用例（HESU/VOLT/车型示例 → HESUPIPE/管材场景）
  2. 多语言墙专项：西语/俄语价格句必须拦截；DN800/PN16/SDR11/SCH40/ ISO4427/20ft 规格形态不得误杀；"USD 1200/ton"、"$500/ton"、€ 报价必须拦截
  3. 阿语数字提取：٠١٢٣٤٥٦٧٨٩ 形式号码提取并转 ASCII
  4. extractor 建材字段提取用例
  5. pytest 全绿 + widget-test.html 挂件手动验收 + mock_uniservice 联调验收

9.2 真人验收（真实 LLM，验证 AI 表现——mock 测不了这些）

pytest 全绿只证明代码没写错，不证明 AI 聊得好。上线前用真 Key 实聊验收清单 （参考汽车项目 docs/test-checklist.md 改写）：

  • 英文问价 / 西语问价 / 问 MOQ / 要样品 / 问交期 / 问认证 → 一律不正面回答， 引导留资，回复语言跟随客户
  • 客户留电话 → 画像更新、触发邮件（测试邮箱）+ mock 推送
  • 客户中途换号码 → 更正邮件触发、不重复轰炸
  • 已留资后再问价 → 不再索要联系方式
  • 建材规格聊天（DN110 PN16 之类）→ 不误杀、正常聊
  • 管理后台能看到上述会话、画像 chips、意向分级、推送日志

9.3 上线观察期（第一周）

上线不是终点。第一周跑 scripts/breach_rate.py（同步多语言词表后）观测： 漏放的价格形态、误杀的规格数字，发现即补正则。参考项目当年也是逐圈修出来的。

10. 风险登记

风险 等级 缓解
多语言墙覆盖不全 中 §6 分层 + 专项测试；上线后跑 breach_rate 观测
事实卡收录模板化内容导致编造 中 §4.2 只收硬事实 + 人工审核事实卡
GDPR 欧洲合规 低 §8 隐私提示；不阻塞
双项目长期同步代价 低 CLAUDE.md 记录血缘；changelog 对照
与汽车项目共用智谱 Key/SMTP 额度 低 现量小无碍；某一方爆量时再拆分独立账号
glm-4-flash 多语言提取/评估退化 低 测试覆盖；必要时升级模型

11. 需求方提供的凭据/资源（实施时）

项 说明
智谱 API Key 复用参考项目 .env 或新建
SMTP 账号密码 复用参考项目 .env
UniService API Key 复用参考项目 .env（同一 CRM 账号）
NOTIFY_EMAIL 管道业务询盘收件邮箱（需求方指定）
WhatsApp 号码二选一 15937108317（官网主号码）/ 15890151617；邮箱 hesu@hesuu.com
客服头像图 HESUPIPE logo 或管道主题图
部署域名 + 服务器 如 ai.hesupipe.com
Reference in New Issue View Git Blame Copy Permalink