HESUPIPE 建材 AI 客服

为 HESUPIPE（hesupipe.com，河南和硕集团管道建材出口业务）打造的官网 AI 客服系统。 服务全球 B2B 管道采购买家：AI 了解需求（品类/规格/数量/用途/目标国家）→ 引导留资 → 线索经邮件 + UniService CRM 推送交人工客户经理跟进。

AI 只做"需求了解 + 留资"：价格、交期、MOQ、样品费、质保年限等实质问题一律不正面回答， 多语言输出墙（中/英/西/葡/俄/阿 + €/£ 货币符号）兜底拦截，引导留资转客户经理。

本项目复制自同集团汽车业务 AI 客服（ai-kefu，~85% 代码同源）并建材化定制。 血缘与同步规则见 CLAUDE.md；设计文档见 docs/superpowers/specs/2026-09-29-building-materials-ai-kefu-design.md。

技术栈

• 后端：Python / FastAPI + SQLAlchemy(async) + SQLite（data/hesupipe_ai_kefu.db）
• LLM：智谱 GLM（默认 glm-4-flash，zhipuai SDK，流式输出）
• 前端：原生 JS 挂件（static/widget.js，Shadow DOM 隔离，可嵌入任意官网）+ WebSocket 流式对话
• 线索出口：SMTP 邮件（aiosmtplib）+ UniService CRM HTTP 推送（httpx，带重试矩阵）
• 部署：Docker + docker compose + OpenResty 反代

本地启动

pip install -r requirements.txt

cp .env.example .env
# 编辑 .env，至少填入：
#   ZHIPU_API_KEY=...          智谱 API Key（必需）
#   其余 SMTP / 推送配置可先留占位

uvicorn app.main:app --host 0.0.0.0 --port 8017

• 聊天演示页：http://localhost:8017/
• 管理后台：http://localhost:8017/admin
• 健康检查：http://localhost:8017/health
• 挂件本地测试页：static/widget-test.html

测试

pip install -r requirements-dev.txt
pytest

• 230 项全绿是合并门槛（LLM 全 mock，验证代码正确性）。
• 真实 LLM 验收（守边界/语言跟随/留资链路/推送联调）用 scripts/mock_uniservice.py 配合真实智谱 Key 进行，清单与最近一次验收结果见 docs/test-checklist.md。

部署（生产）

# 服务器上（.env 已按生产配置就绪）
bash deploy.sh

deploy.sh = docker compose 停旧 → 构建 → 启动（容器名 hs-ai-kefu，宿主端口 8017）→ 健康检查。外层用 OpenResty 反代到公网（配置见 openresty.conf，后端路径 hesupipe_ai_kefu），WebSocket（/ws/chat）与 HTTP 同端口。

上线切换检查单（开发 → 生产，一次性完成）

• 事实卡业务侧审核（设计文档 §4.2 必经关卡）：懂管道产品的人逐条过目 app/prompts/company_facts.md——AI 说的每句公司情况都来自这张卡
• 清验收测试数据：删除或归档 data/hesupipe_ai_kefu.db （含验收期的 15 个测试会话与推送日志，直接上生产会污染后台视图）
• .env 中 PUSH_ENABLED=true（开发期为 false，防测试线索推爆生产 CRM）
• PUSH_API_URL / PUSH_API_KEY 换成真实 UniService 地址与 Key （PUSH_EXTERNAL_KEY_PREFIX=ai-kefu-jc 保持不变，与汽车项目线索隔离）
• NOTIFY_EMAIL 换成管道业务客户经理邮箱（非测试邮箱）
• SMTP 配置为真实发件账号（已在生产服务器就绪）
• 绑定生产域名（如 ai.hesupipe.com）并配好 HTTPS 证书
• 官网按 docs/embed-guide.md 嵌入挂件
• 上线后第一周跑 scripts/breach_rate.py 观测漏放/误杀（设计文档 §9.3）

管理后台

入口 /admin（登录走 /api/admin/login）。三视图：

• 会话列表：全部对话、消息数、意向分级、联系方式、邮件已发标记
• 会话详情：完整对话记录 + 客户画像 chips（意向品类/规格要求/标准要求/采购数量/ 用途/目标国家/联系方式）
• 推送日志：lead / correction 推送记录与状态（含重试轨迹）

挂件嵌入官网

挂件由本服务 /static/widget.js 提供，一行 <script> 即可嵌入官网（WordPress 或任意 建站系统）。嵌入代码、配置项（位置/主题色/WhatsApp/邮箱/自动邀请等）、三种 WordPress 粘贴方式与上线检查单，见 docs/embed-guide.md。

主题色默认已是 HESUPIPE 品牌蓝 #066fc0，可用 data-color 覆盖，整套配色自动派生。

目录速览

app/
  prompts/          4 个提示词（system/company_facts/extractor/evaluator）——建材化核心
  services/         会话管理、boundary_filter 多语言墙、留资管道、推送、邮件
  api/              WebSocket + REST 路由、admin 路由
static/             widget.js（官网挂件）、chat.html、admin.html、js/theme.js
scripts/            mock_uniservice.py（联调）、breach_rate.py（上线观测）
docs/               changelog 归档、test-checklist.md、embed-guide.md、设计文档
tests/              230 项 pytest（LLM 全 mock）