From 5b7788ec0859d529651ee2a8b2c4ef5599b1ad9e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B5=85=E5=BF=B5?= Date: Tue, 29 Sep 2026 11:39:18 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20HESUPIPE=20=E5=BB=BA=E6=9D=90AI?= =?UTF-8?q?=E5=AE=A2=E6=9C=8D=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 基于 D:\refactor\ai-kefu 汽车AI客服项目复制+建材化定制的完整设计。 方案A：完整拷贝+定制，含多语言输出墙分层、开发期推送隔离等修订。 Co-Authored-By: Claude Code --- ...09-29-building-materials-ai-kefu-design.md | 189 ++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-29-building-materials-ai-kefu-design.md diff --git a/docs/superpowers/specs/2026-09-29-building-materials-ai-kefu-design.md b/docs/superpowers/specs/2026-09-29-building-materials-ai-kefu-design.md new file mode 100644 index 0000000..70f4a92 --- /dev/null +++ b/docs/superpowers/specs/2026-09-29-building-materials-ai-kefu-design.md @@ -0,0 +1,189 @@ +# 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——未知一律走"转客户经理"兜底 +- 防编造原则（统一兜底/不扩展）原样保留 + +### 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/цена/стоимость/سعر/ثمن + - 时间承诺：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 `+8615987108317`、邮箱 `hesu@hesuu.com`（两个官网号码最终用哪个，实施时确认） | + +**开发期安全流程（漏洞 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 侧）；上线前完成，不阻塞开发 + +## 9. 测试策略 + +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 联调验收 + +## 10. 风险登记 + +| 风险 | 等级 | 缓解 | +|---|---|---| +| 多语言墙覆盖不全 | 中 | §6 分层 + 专项测试；上线后跑 breach_rate 观测 | +| 事实卡收录模板化内容导致编造 | 中 | §4.2 只收硬事实 + 人工审核事实卡 | +| GDPR 欧洲合规 | 低 | §8 隐私提示；不阻塞 | +| 双项目长期同步代价 | 低 | CLAUDE.md 记录血缘；changelog 对照 | +| glm-4-flash 多语言提取/评估退化 | 低 | 测试覆盖；必要时升级模型 | + +## 11. 需求方提供的凭据/资源（实施时） + +| 项 | 说明 | +|---|---| +| 智谱 API Key | 复用参考项目 .env 或新建 | +| SMTP 账号密码 | 复用参考项目 .env | +| UniService API Key | 复用参考项目 .env（同一 CRM 账号） | +| NOTIFY_EMAIL | 管道业务询盘收件邮箱（需求方指定） | +| WhatsApp 号码二选一 | 15937108317 / 15890151617 | +| 客服头像图 | HESUPIPE logo 或管道主题图 | +| 部署域名 + 服务器 | 如 ai.hesupipe.com |