docs(spec): 建材双要话术设计——首次索要 WhatsApp+邮箱一起要（话术层改造,引擎不动）

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-11-02 16:53:41 +08:00
parent f1f08fb55c
commit f768d139dd
1 changed files with 101 additions and 0 deletions
@@ -0,0 +1,101 @@
+# 建材（jiancai）首次索要联系方式改为 WhatsApp + 邮箱双要 — 设计文档
+
+日期：2026-11-02
+状态：已与用户对齐（含批判性审查修正）
+范围：仅 jiancai 租户的话术层（seed_profiles 配置文件），引擎代码零改动
+
+## 1. 背景与目标
+
+现状是"分步双要"：WhatsApp 硬性必收（CC 确认流 + 强制墙），邮箱只在其后**轻补问一次**（`_email_asked` 计数，"仅此一次，客户不给就不再提"）；首次索要话术为 "What's your WhatsApp **or** email?"（二选一）或只提号码。
+
+用户需求：**首次索要联系方式的话术就把 WhatsApp 和邮箱一起要**（双要），提高两渠道齐收率。
+
+## 2. 方案总纲（已拍板的决策）
+
+| 决策点 | 结论 |
+|---|---|
+| 邮箱-only 客户怎么补问号码 | **提示词兜底**——引擎不动，lead_given/contact_ask 提醒文本通用化，允许 AI 对缺失渠道（任一方向）礼貌补问一次（防骚扰墙本就放行"索要缺失渠道"，[boundary_filter.py:180](app/engine/services/boundary_filter.py) 实锤兼容） |
+| 生产落地基线 | **整体对齐出厂**——生产 prompts/wall 配置以仓库出厂档案最新版整组替换（含 cd3b58a 等出厂演进），叠加本次双要改动，一步到位 |
+| deflections_contact/pivots_contact 渠道错配 | **改渠道中性**——"send ... to your WhatsApp" → "send you ... shortly"，兼容任一渠道已留场景 |
+
+## 3. 改动清单（逐点位）
+
+### 3.1 seed_profiles/jiancai/prompts/system.md
+
+| 点位 | 改法 |
+|---|---|
+| L7 模板句族声明 | 转接句家族措辞更新为双要形态；**保留"邮箱轻补句"字样**（test_system_prompt_dual_contact 锚） |
+| L25 转接句（实质请求） | "…drop your WhatsApp and email and they'll reach out directly." |
+| L35 预算后引导句 | 双要形态 |
+| L69 磨价应对句 | "drop your WhatsApp and email and our manager will reply within 12 hours." |
+| L74 已留资确认句 | 渠道中性（去 "at your WhatsApp"） |
+| L140 中文好例 | "留个WhatsApp和邮箱？" |
+| L152 样品转接好例 | 双要形态 |
+| L155 已留资好例 | 渠道中性 |
+| L166-167 好/差例 | **不动**（已留 WhatsApp → 轻补邮箱，机制保留的锚） |
+| L179-188 索要话术池（en 4 条 + zh 4 条） | 全部改双要；**至少一条保留 "with the country code" 原样措辞**（test_system_prompt_dual_contact:44 锚） |
+| L190-195 「双渠道与国家代码」原则节 | "分步双要，一次只问一个" → "**双渠道一次要齐**：首次索要就把 WhatsApp 和邮箱一起要（理由=经理 WhatsApp 联系 + 报价单 PDF 发邮箱）；客户只给一个时，另一渠道轻补一次（邮箱按系统轻补指引逐字句；号码礼貌补问一句），不成就不再提，绝不纠缠（转化率优先）"；**保留锚词**："已在手的渠道"、"缺失渠道"、"轻补"、"formal quotation PDF"、"国家代码"≥2、"with the country code" |
+| L214 App 反向留资句 | 双要形态（与 wall `contact_ask.app` 逐字句同源） |
+| L216 互留句 | "Drop yours too — WhatsApp and email — and our manager will send the full quotation!" |
+| L173 / L221 / L227 "缺失渠道轻补一次"表述 | 通用化："缺失渠道（号码或邮箱）可再礼貌提一次，仅一次不纠缠"；L221 确认式例句渠道中性 |
+
+### 3.2 seed_profiles/jiancai/wall.json
+
+| 字段 | 改法 |
+|---|---|
+| `deflections` en/zh/es（9 条） | 全部双要（"What's your WhatsApp **and** email?" / "留个WhatsApp和邮箱？" / "¿Me dejas tu WhatsApp y tu correo?"） |
+| `pivots` en/zh/es（9 条） | 全部双要 |
+| `deflections_contact` en/zh/es（3 条） | **渠道中性**："Our manager will send you the exact quote shortly. Anything else about our pipes?"（去 "to your WhatsApp"） |
+| `pivots_contact` en/zh/es（3 条） | **渠道中性** |
+| `no_contact.app` | 双要："Drop your WhatsApp and email — our manager will reach out to you directly with the full quote!" |
+| `no_contact.already` | 渠道中性："Got it — our manager will reach out to you shortly with the full quote!" |
+| `reminders.contact_ask.app` 逐字句 | 双要（与 system.md L214 同源） |
+| `reminders.contact_ask.app_already` 逐字句 | 渠道中性；轻补子句通用化 |
+| `reminders.lead_given.forbidden` | 轻补子句通用化："缺失渠道（号码或邮箱）可再礼貌提一次（邮箱按轻补指引逐字句、号码自然补问），仅一次不纠缠"；**保留锚串** "。绝对禁止再索要客户已提供过" 与就近的 "回显补全后的完整号码" |
+| `reminders.lead_given.boundary_tail` | 内嵌引导 '发到你 WhatsApp' → '发给你'；轻补子句通用化；**保留锚串** "即可，禁止再索要联系方式" 与就近例外 |
+| `reminders.email_light` en/zh | **不动**（引擎邮箱轻补的逐字模板，兜底机制原样） |
+| `cc_templates` / `cc_guide` / `reask_patterns` / `triggers` / `zero_number` | **不动**（CC 流与防骚扰机制原样；新话术 "What's your WhatsApp and email?" 仍被 reask_patterns L127/147/163 覆盖，实现时以 hygiene 测试复核） |
+
+### 3.3 seed_profiles/jiancai/prompts/company_facts.md
+
+L30 统一兜底句："留个 WhatsApp，他直接联系你" → "留个 WhatsApp 和邮箱，他直接联系你"。
+
+### 3.4 不动的范围
+
+- **引擎代码零改动**：CC 确认流、邮箱轻补注入（`_contact_completion_note` / `_email_asked` / `cc_settled` 串行门控）全部原样
+- **auto 租户、新租户生成器模板**（site_import/system_template.md 保持"分步双要"出厂默认）不动
+- DEFAULT_WALL（代码内默认墙）不动——jiancai 走自己的 wall.json
+
+## 4. 已知限制与取舍（spec 明示）
+
+1. **号码补问无引擎计数**：邮箱方向有 `_email_asked` 一次性计数；号码方向（邮箱-only 客户被补问）纯靠 LLM 对话历史自律，理论上可能多问一次。提示词兜底方案的固有松散性，用户已知情接受。
+2. **留资摩擦**：双要抬高一档门槛，可能轻微影响留资率。纳入阶段④观察（breach_rate + 会话/线索统计），回滚 = 配置版本回退，秒级。
+3. 防骚扰墙放行缺失渠道索要是既有行为，本次不收紧——与提示词兜底方案配套成立。
+
+## 5. 测试策略
+
+1. **锚点同步（同包必改）**：
+   - test_cc_integration.py:122 `"缺失渠道仅可按轻补指引提一次"` → 新通用化措辞
+   - test_lead_email_trigger.py:454 / :693 `"缺失渠道可按轻补指引提一次"` → 新措辞
+2. **锚点保留（改话术时不得破坏）**：test_prompt_static 全部（"唯一例外"/"回显补全后的完整号码"≥4/"客户自己的号码也不回显"/"is that right"/extractor 门控句）；test_system_prompt_dual_contact 全部（"with the country code"/"formal quotation PDF"+"轻补"/"国家代码"≥2/"已在手的渠道"+"缺失渠道"/"邮箱轻补句"）；test_lead_email_trigger.py:993-1002 三处禁令锚 + 回显例外就近断言。
+3. **新增静态锚（防回退，按仓库文化）**：wall.json deflections 三语各含双要措辞（"and email"/"和邮箱"/"y tu correo"）；deflections_contact 三语不含 "your WhatsApp"（中性钉死）；system.md 含 "双渠道一次要齐"；company_facts.md 含 "WhatsApp 和邮箱"。
+4. **全量 pytest**（CLAUDE.md 强制：改 seed_profiles 必跑），基线 632 passed + 2 skipped，改后锚点同步数目一致。
+
+## 6. 生产落地（整体对齐出厂）
+
+1. 仓库改 seed_profiles + 测试 → 全量 pytest 绿 → commit。
+2. `ssh all-kefu-prod`，admin API 登录：
+   - `GET /api/platform/tenants/jiancai/config/prompts` 与 `/wall`，与仓库出厂新版 diff，**记录漂移清单**（预期=出厂侧 cd3b58a 等演进未推生产）；漂移 unexpected 时停下来人工核对再继续。
+   - `PUT` 两配置组（prompts 四件套 system/extractor/evaluator/company_facts + wall 整组）= 出厂最新版；配置版本管线自动快照 + registry_reload 热生效。
+3. 验证（真实会话，走 chat2 域名或隧道）：
+   - 问价触发索要 → 首次话术即双要（WhatsApp + 邮箱一起要）；
+   - 只给号码 → CC 确认流 + 邮箱轻补一次（原行为不回归）；
+   - 只给邮箱 → AI 礼貌补问号码一次，且不再纠缠。
+4. 观察纳入阶段④日检：留资率、双渠道齐收率、breach_rate；异常即 `POST /config/rollback` 回退版本。
+
+## 7. 验收标准
+
+- 全量 pytest 绿（锚点同步后数目与基线一致）；
+- 新增静态锚全部在位；
+- 生产 jiancai 配置版本 +1，试金石/真实会话验证三条路径（双要首问 / 号码-only 轻补邮箱 / 邮箱-only 补问号码）行为正确；
+- 引擎代码 diff 为零；auto 租户配置 diff 为零。