浅念
9.6 KiB
9.6 KiB
建材（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 实锤兼容） |
| 生产落地基线 | 整体对齐出厂——生产 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"；两条邮箱轻补逐字句（en "Got it! And an email address would help too — …" / zh "收到！邮箱也留一个呗？…"）必须原文存活（test_system_prompt_dual_contact.py:90-102 对引擎常量逐字断言） |
| L214 App 反向留资句 | 双要形态，与 wall contact_ask.app 逐字句一字不差（现状两处尾部 "full quotation!" vs "full quote!" 有一词分叉，本次统一为同一字符串） |
| L216 互留句 | "Drop your WhatsApp and email too — and our manager will send the full quotation!"（实施定稿措辞，较原草案收敛） |
| L57 红线节括注 | "缺失渠道可轻补一次" → "缺失渠道——号码或邮箱——可再礼貌提一次"（Task 2 质量审查补列，与 L173/L227 同构） |
| L173 / L221 / L227 "缺失渠道轻补一次"表述 | 通用化："缺失渠道（号码或邮箱）可再礼貌提一次，仅一次不纠缠"；L221 确认式例句渠道中性 |
3.2 seed_profiles/jiancai/wall.json
| 字段 | 改法 |
|---|---|
deflections en 3 / zh 2 / es 3（共 8 条） |
全部双要（"What's your WhatsApp and email?" / "留个WhatsApp和邮箱？" / "¿Me dejas tu WhatsApp y tu correo?"） |
pivots en/zh/es（各 1 条，共 3 条） |
全部双要 |
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 明示）
- 号码补问无引擎计数：邮箱方向有
_email_asked一次性计数；号码方向（邮箱-only 客户被补问）纯靠 LLM 对话历史自律，理论上可能多问一次。提示词兜底方案的固有松散性，用户已知情接受。 - 留资摩擦：双要抬高一档门槛，可能轻微影响留资率。纳入阶段④观察（breach_rate + 会话/线索统计），回滚 = 配置版本回退，秒级。
- 防骚扰墙放行缺失渠道索要是既有行为，本次不收紧——与提示词兜底方案配套成立。
5. 测试策略
- 锚点同步（同包必改）：
- test_cc_integration.py:122
"缺失渠道仅可按轻补指引提一次"→ 新通用化措辞 - test_lead_email_trigger.py:454 / :693
"缺失渠道可按轻补指引提一次"→ 新措辞 - test_lead_email_trigger.py:681 / :692
"reach out to you at your WhatsApp"→ 新中性措辞（该串源自contact_ask.app_already逐字句与no_contact.already，渠道中性化后必红；spec 审查抓出的遗漏点）
- test_cc_integration.py:122
- 锚点保留（改话术时不得破坏）：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 三处禁令锚 + 回显例外就近断言。
- 新增静态锚（防回退，按仓库文化）：wall.json deflections 三语各含双要措辞（"and email"/"和邮箱"/"y tu correo"）；deflections_contact/pivots_contact 三语不含任何渠道词（en "your WhatsApp"、zh "你的 WhatsApp"、es "tu WhatsApp" 按语言逐一钉死，防只用 en 子串漏检 zh/es 回归）；system.md 含 "双渠道一次要齐"；company_facts.md 含 "WhatsApp 和邮箱"。
- 全量 pytest（CLAUDE.md 强制：改 seed_profiles 必跑），基线 632 passed + 2 skipped，改后锚点同步数目一致。
6. 生产落地（整体对齐出厂）
- 仓库改 seed_profiles + 测试 → 全量 pytest 绿 → commit。
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 热生效。
- 验证（真实会话，走 chat2 域名或隧道）：
- 问价触发索要 → 首次话术即双要（WhatsApp + 邮箱一起要）；
- 只给号码 → CC 确认流 + 邮箱轻补一次（原行为不回归）；
- 只给邮箱 → AI 礼貌补问号码一次，且不再纠缠。
- 观察纳入阶段④日检：留资率、双渠道齐收率、breach_rate；异常即
POST /config/rollback回退版本。
7. 验收标准
- 全量 pytest 绿（锚点同步后数目与基线一致）；
- 新增静态锚全部在位；
- 生产 jiancai 配置版本 +1，试金石/真实会话验证三条路径（双要首问 / 号码-only 轻补邮箱 / 邮箱-only 补问号码）行为正确；
- 引擎代码 diff 为零；auto 租户配置 diff 为零。