From 7b78c9bfd022718dd1337cb63dc6d2b3f84251cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B5=85=E5=BF=B5?= Date: Tue, 29 Sep 2026 20:12:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=98=E7=BD=91=E5=B5=8C=E5=85=A5?= =?UTF-8?q?=E6=8C=87=E5=8D=97+CLAUDE.md=E8=A1=80=E7=BC=98+README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Code --- CLAUDE.md | 85 +++++++++++++++++++++++++++ README.md | 102 ++++++++++++++++++++++++++++++++ docs/embed-guide.md | 139 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 326 insertions(+) create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 docs/embed-guide.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e019575 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,85 @@ +# CLAUDE.md + +HESUPIPE 管道建材 AI 客服（hesupipe.com，河南和硕集团）。 +FastAPI + SQLite + 智谱 GLM，嵌入外贸官网，做"AI 需求了解 + 留资获客 + 邮件/UniService +CRM 推送"，AI 不回答价格/交期/MOQ 等实质问题，一律引导留资转客户经理。 + +## 血缘与上游同步（重要） + +本项目**复制自**参考项目 `D:\refactor\ai-kefu`（Hesu Auto 汽车出口 AI 客服，同集团姊妹 +业务），约 **85% 代码同源**。复制时的架构决策见 +`docs/superpowers/specs/2026-09-29-building-materials-ai-kefu-design.md`（方案 A：完整拷贝 ++ 建材化定制）。 + +**同步规则**：上游修 bug / 改正则 / 调提示词机制后，本项目需**手动同步**。 + +1. 看上游 `D:\refactor\ai-kefu\docs\` 下的 changelog 文件（按日期命名，如 + `2026-09-28-lead-push-changelog.md`）——本项目 `docs/` 下有同批文件的拷贝（截至 + 复制日 2026-09-29），对比两边目录即可发现上游新增的变更记录； +2. 评估该修复是否适用于本项目（建材差异部分见下），适用则同步代码 + 同步测试； +3. 同步后在本次提交信息里注明"同步自上游 "。 + +**禁止反向操作**：不要把本项目的建材定制覆盖回上游。 + +## 与上游的关键差异清单（改这些地方时别照抄上游） + +| 差异点 | 本项目 | 上游（ai-kefu） | +|---|---|---| +| 行业与提示词 | 4 个提示词全部建材化：`system.md`（管道外贸人设+MOQ/交期/样品/认证红线）、`company_facts.md`（HESUPIPE 事实卡）、`extractor.md`（意向品类/规格要求/标准要求/采购数量等字段）、`evaluator.md`（管道采购意向分级） | 汽车（Hesu Auto）语义 | +| boundary_filter 多语言墙 | 墙按建材市场扩充：`€`/`£`+数字、西葡俄阿价格词（precio/costo/custo/preço/цена/стоимость/سعر/أسعار/ثمن，含复数与阿语定冠词 ال 连写形态）+天数词（días/дней/أيام 等）；迂回话术池 EN/ZH/**ES**；规格防误杀（DN/PN/SDR/PE100/SCH/ISO4427/20ft 不拦） | 只中英 + `$` + 零号码墙 | +| 线索键前缀 | `PUSH_EXTERNAL_KEY_PREFIX=ai-kefu-jc`（与汽车项目线索空间隔离，**勿改回 ai-kefu**） | `ai-kefu` | +| 端口 | 8017 | 8016 | +| Docker 容器名 | `hs-ai-kefu` | （上游原名不同） | +| 品牌 | HESUPIPE，品牌蓝 `#066fc0`（theme.js 与 widget.js 中的主题派生单元整块同步，`tests/test_theme_static.py` 强制一致） | HESU，橙色 | +| DB 文件 | `data/hesupipe_ai_kefu.db` | `data/cc_ai_kefu.db` | +| openresty 路径 | `hesupipe_ai_kefu` | （上游路径） | +| context 种子键 | `product_name` / `product_id` | `vehicle_name` / `vehicle_id` | + +主题派生单元（调色板函数块）在 `static/widget.js` 与 `static/js/theme.js` 中逐字相同， +只可整块替换，不可单边修改——`tests/test_theme_static.py` 会强制校验。 + +## 开发约定 + +- **推送开关**：开发/测试期 `.env` 保持 `PUSH_ENABLED=false`，防止测试线索推爆生产 CRM。 + 生产环境必须 `true`（需求方已确认最终状态为启用）。全量验收通过后一次性切换。 +- **合并门槛**：`pytest` **230 项全绿**。LLM 全 mock，验证代码正确性。 +- **真实 LLM 验收**：mock 测不了 AI 表现（守边界/语言跟随/不回显号码）。用真实智谱 Key + + `scripts/mock_uniservice.py`（本地 9099，`PYTHONUTF8=1` 启动，期待 `X-Api-Key: test-key-123`） + 联调，验收清单与现状见 `docs/test-checklist.md`（2026-09-29 已通过，含 4 项不阻塞残差）。 +- **提示词改动**：`app/prompts/` 下 4 个 .md 是 AI 行为的源头；改动后跑 pytest（有文案断言） + 并视改动性质补一轮真实验收。 +- **环境坑（Windows）**：mock_uniservice 必须以 `PYTHONUTF8=1` 启动，否则 GBK 控制台遇 + emoji payload 即崩溃；中文文档用 Write 工具写，别用 bash heredoc。 + +## 常用命令 + +```bash +# 测试（合并门槛，230 项） +pytest + +# 本地启动（端口 8017） +pip install -r requirements.txt +cp .env.example .env # 填 ZHIPU_API_KEY 等 +uvicorn app.main:app --host 0.0.0.0 --port 8017 + +# 本地联调推送（PUSH_ENABLED=false 时不影响；验证推送链路用） +PYTHONUTF8=1 python scripts/mock_uniservice.py # 监听 9099，X-Api-Key: test-key-123 + +# 生产部署（服务器上） +bash deploy.sh # docker compose 构建并启动，健康检查 127.0.0.1:8017/health +``` + +- 聊天演示页 `/`，管理后台 `/admin`，健康检查 `/health`。 +- 挂件嵌入官网指引：`docs/embed-guide.md`。 + +## 上线观察期（第一周必做） + +上线不是终点。**上线后第一周**跑 `scripts/breach_rate.py` 观测双向偏差： + +- **漏放**：AI 回复里出现价格/交期/MOQ 数字而墙没拦下（多语言新词表已随建材化扩充， + 仍可能有长尾语言形态漏网）； +- **误杀**：正常建材规格聊天（DN800/PN16/SDR11 之类）被墙误拦。 + +发现即补正则 + 补测试，流程见设计文档 §9.3。已知 4 项不阻塞残差（西语模板句翻译、 +样品措辞、extractor 占位词、多轮压力下偶发漂移）记录在 `docs/test-checklist.md`， +靠此观察期收敛。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..7fc5084 --- /dev/null +++ b/README.md @@ -0,0 +1,102 @@ +# 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 反代 + +## 本地启动 + +```bash +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` + +## 测试 + +```bash +pip install -r requirements-dev.txt +pytest +``` + +- **230 项全绿是合并门槛**（LLM 全 mock，验证代码正确性）。 +- 真实 LLM 验收（守边界/语言跟随/留资链路/推送联调）用 `scripts/mock_uniservice.py` + 配合真实智谱 Key 进行，清单与最近一次验收结果见 `docs/test-checklist.md`。 + +## 部署（生产） + +```bash +# 服务器上（.env 已按生产配置就绪） +bash deploy.sh +``` + +`deploy.sh` = docker compose 停旧 → 构建 → 启动（容器名 `hs-ai-kefu`，宿主端口 8017）→ +健康检查。外层用 OpenResty 反代到公网（配置见 `openresty.conf`，后端路径 +`hesupipe_ai_kefu`），WebSocket（`/ws/chat`）与 HTTP 同端口。 + +### 上线切换检查单（开发 → 生产，一次性完成） + +- [ ] `.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` 提供，一行 ` + +``` + +粘贴后刷新官网任意页面，右下角应出现蓝色 "Chat with us" 胶囊按钮，即嵌入成功。 + +> **本地/测试环境预览**：部署前想先看效果，把 `src` 换成本地服务地址 +> `http://localhost:8017/static/widget.js`（需本地启动服务）。 + +--- + +## 2. 贴到哪里（WordPress 三种主流方式，任选其一） + +### 方式 A：自定义 HTML 小工具（最简单，推荐） + +1. WordPress 后台 → **外观 → 小工具** +2. 找到 **自定义 HTML** 小工具，添加到 **Footer（页脚）** 区域 +3. 把上面的嵌入代码整段粘贴进内容框 +4. 保存，刷新官网前台页面验证 + +### 方式 B：主题设置里的"页脚脚本"输入框 + +很多商业主题自带代码注入功能： + +1. **外观 → 自定义**（或 主题设置），找类似 **Footer Scripts / 页脚代码 / 跟踪代码** 的输入框 +2. 把嵌入代码整段粘贴进去 +3. 保存发布 + +> 如果主题同时有"页眉脚本"和"页脚脚本"，选**页脚**（页面加载更快）。 + +### 方式 C：直接编辑页脚模板 footer.php（懂一点主题编辑时用） + +1. **外观 → 主题文件编辑器** → 右侧选择 **Footer (footer.php)** +2. 找到 `` 标签，把嵌入代码粘贴到 `` 的**上一行** +3. 点"更新文件" + +> **注意**：直接改主题文件时，主题更新后改动会被覆盖。建议在**子主题（Child Theme）**里改， +> 或改用方式 A/B。 + +--- + +## 3. 可调配置说明 + +以下配置全部写在 `