docs: 新增智能客户流失预警与经营自愈系统 PRD 文档

添加项目产品需求文档，详细描述 RetainAI 系统的产品定位、核心业务场景、多智能体设计以及演进路线图，旨在补齐增长平台的后链路业务闭环。

docs/PRD.md

@@ -0,0 +1,129 @@
+---
+title: 智能客户流失预警与经营自愈系统 (RetainAI) PRD
+version: v2.0 (结合 AI 增长经营自动化平台架构)
+date: 2026-04-13
+status: 规划中
+---
+
+# 智能客户流失预警与经营自愈系统 (RetainAI) PRD
+
+> **设计背景说明**：
+> 本 PRD 深度融合了“AI 增长经营自动化平台（ai-growth-platform）”的系统全景与工程理念。如果说增长平台解决了“获客承接 → 成单履约 → 广告转化回传”的**前链路闭环**，那么 RetainAI 则是补齐了**“售后存量经营 → 流失预警 → 自动挽留干预 → LTV 修复”的后链路闭环**。
+
+## 1. 产品概述
+### 1.1 产品定位
+打造一款**“无需算法工程师介入、直接驱动业务干预”**的全自动机器学习与客户留存引擎。
+系统不仅具备**模型训练自主诊断与自愈能力（Auto-Debugging）**，更能无缝对接到增长平台的“多平台推送（Push Jobs）与邮件跟进”队列中，实现从“预测流失”到“执行挽留”的无人值守业务闭环。
+
+### 1.2 核心价值（亮点）
+- **全生命周期闭环**：打破“模型只输出概率”的孤岛，将高危流失名单直接转化为“营销推送任务（Marketing Push Jobs）”或“人工交接包（Handoffs）”。
+- **模型自愈与可审计**：展示 Multi-Agent 在机器学习全链路的“自适应与自愈”能力；所有的 Agent 运行态（Agent Runs）、自调参代码 Diff 均记录留痕，保证全过程可审计。
+- **AI 安全与红线控制**：干预策略生成时，严格遵守业务红线（如超大额折扣需人工审批），命中红线则触发 Handoff 转人工接管。
+
+---
+
+## 2. 核心业务场景与端到端闭环
+
+本系统作为增长平台的“通用 AI 预测与自愈引擎”，基于**“纯 Python 标准库实现”**的极致轻量化约束，横向扩展至以下具备“小数据量、高业务价值、强可解释性”特征的高优场景：
+
+### 2.1 核心场景 1：VIP 大客户专属服务分级 (High-Value Client Triage)
+- **为什么适合纯 Python**：大客户（VIP）基数通常在数千级别以内，数据量小但单客价值极高；业务部门要求对模型的每一个权重和计算逻辑具有绝对的“白盒”解释权，不能使用黑盒算法包。
+- **业务价值**：在客服工单进线时，预测该客户升级为“SVIP（超高净值）”的潜力，决定是否走专属绿色通道。
+- **数据特征**：历史订单数、客诉解决时长、使用高级功能的频率等（通常不超过 20 个维度）。
+- **预测目标**：该客户在未来 6 个月内是否会贡献超过 $10k 的利润（0/1 二分类）。
+- **即时行动**：高潜客户进线时，Agent 自动拦截普通排队，生成“客户背景摘要交接包”，直接分配给高级客户成功经理（CSM）。
+
+### 2.2 核心场景 2：高意向线索自动打分与破冰 (High-Intent Lead Scoring)
+- **为什么适合纯 Python**：线索打分往往需要与现有的 CRM（如 Salesforce）或自建后端深度集成。纯 Python 无需安装 numpy/scikit-learn 即可部署在 AWS Lambda 或极简 Serverless 环境中，实现毫秒级冷启动。
+- **业务价值**：前链路获客场景，帮助销售在每天涌入的成百上千条询盘中，精准锁定最有可能成单的 20%。
+- **数据特征**：页面停留时长、Pricing 页访问次数、表单填写完整度、注册渠道归因等。
+- **预测目标**：该线索是否会在 48 小时内转化为订单（0/1 二分类）。
+- **即时行动**：高分线索触发业务 Agent 生成“破冰交接包”并 Push 到销售的 Slack；低分线索进入自动邮件 Nudge 队列培育。
+
+### 2.3 核心场景 3：边缘设备/离线环境风控拦截 (Edge/Offline Fraud Detection)
+- **为什么适合纯 Python**：在某些跨境出海的线下门店或弱网仓储终端，设备算力受限，无法安装庞大的 ML 环境，甚至无法联网调用云端 API。纯 Python 脚本配合预训练权重（JSON 格式）是唯一可靠的离线推理方案。
+- **业务价值**：在用户现场刷卡或货到付款（COD）发货前，拦截高概率欺诈或恶意拒收的订单。
+- **数据特征**：下单时间异常度、收货地址黑名单命中率、设备指纹风险分、历史退货率。
+- **预测目标**：该订单是否会发生拒付/恶意退货（0/1 二分类）。
+- **即时行动**：风控 Agent 直接挂起订单状态（挂起 `confirmed`），触发人工审核，避免发出货物导致资损。
+
+### 2.4 核心场景 4：工业遗留系统 (Legacy PLC) 异常信号微决策 (Industrial Signal Anomaly)
+- **为什么适合纯 Python**：变电站或水处理厂的旧款工业控制系统（PLC）或网关通常运行着极老的操作系统，不仅严禁安装任何未经审计的第三方 C 扩展库（防止供应链攻击），甚至没有足够的磁盘空间。多 Agent 在云端完成复杂训练和调参后，最终下发的只是一段**仅包含基础数学运算的纯 Python 推理代码**，实现“零侵入”部署。
+- **业务价值**：在靠近传感器的边缘端，毫秒级判断设备是否发生真实物理故障，避免误报导致整条生产线停机。
+- **数据特征**：传感器电压波动频率、温度上升斜率、电流谐波特征等（时序数据提取出的表格特征）。
+- **预测目标**：该信号波动是真实故障（1）还是环境干扰（0）。
+- **即时行动**：预测为真实故障时，边缘 Agent 直接触发 PLC 继电器切断电源；若置信度处于边缘，则将数据打包上报云端进行人工复核。
+
+---
+
+### 2.5 主链路流转（以高意向线索打分为例）
+1. **数据回流**：增长平台中的线索数据（Site Visits, Lead Forms, Email Interactions）作为基础特征，自动沉淀为训练样本。
+2. **自动建模与自愈**：数据科学家 Agent 与 ML 工程师 Agent 自动完成特征提取、模型训练。若遇到极值导致梯度爆炸（NaN），系统自动诊断并在 Python 脚本中注入 `clip` 或正则化代码并重试。
+3. **意向预测与归因**：对实时进线的线索进行打分，输出高危名单及特征归因（如“访问 Pricing 页 3 次是主要因素”）。
+4. **多角色协同策略**：业务 Agent 联合文案 Agent 生成“销售破冰交接包（客户画像摘要 + 破冰话术建议）”。
+5. **安全门禁与分发**：
+   - **低意向线索**：直接进入增长平台的 `email_followups` 自动化队列发送标准培育邮件。
+   - **高意向线索**：生成 Handoff，通过 Push Jobs 流转至销售人员的 Slack 或 CRM 工作台优先处理。
+6. **经营复盘**：干预后追踪线索是否最终转化为订单，回流闭环优化模型权重。
+
+---
+
+## 3. 多智能体 (Agent) 核心角色设计
+
+系统由三大核心 Agent 协同工作，并在策略执行端引入类似增长平台的多角色协同机制：
+
+### 👨‍🔬 Agent A：数据科学家 (Data Scientist)
+- **职责**：自动从 DB 提取订单/售后等业务数据，执行 EDA，并自动编写特征工程代码（One-hot、缺省值插补等）。
+
+### 🧙‍♂️ Agent B：模型训练与自愈专家 (ML Engineer) —— **【技术护城河】**
+- **职责**：自动编写基线模型训练脚本。
+- **自愈机制 (Auto-Debugging)**：
+  - **NaN / 发散**：捕获报错堆栈，诊断是否为学习率过大、梯度爆炸，自动修改代码（如降低 LR、加梯度裁剪）并重试。
+  - **过拟合 / 欠拟合**：监控 Loss 曲线，自动引入正则化（L1/L2/Dropout）或增加特征交叉。
+- **可靠性保障**：每次重试与调参过程必须落库到 `agent_runs` 与 `audit_logs`，支持调参轨迹全量回放。
+
+### 🕵️‍♀️ Agent C：业务策略与协同团队 (Business Analyst Squad)
+- **职责**：将模型输出的冰冷概率转化为具体执行动作。
+- **多角色协同机制**：
+  - **分析师**：根据归因权重解释流失原因。
+  - **文案 (Copywriter)**：生成针对性的多语种挽留话术草稿（如 WhatsApp 安抚、邮件召回）。
+  - **风控 (Ops)**：校验挽留成本是否超过单客 LTV 阈值。
+- **输出**：生成结构化干预方案，入队推送或转交人工。
+
+---
+
+## 4. 系统可靠性与工程治理 (Engineering & Ops)
+
+深度继承 ai-growth-platform 的工程标准，本系统在落地时必须满足以下约束：
+
+1. **任务调度与幂等 (Scheduler & Idempotency)**
+   - 模型的定期重训、每日预测跑批均由 Scheduler 触发，通过 DB 行级锁（`FOR UPDATE SKIP LOCKED`）抢占任务，避免并发重复训练。
+   - 挽留动作下发到 Push 队列时，基于 `customer_id` 和 `campaign_id` 生成 `idempotency_key`，利用 `ON CONFLICT` 避免重复发券打扰。
+2. **AI 边界与状态回流 (AI Safety & Status Sync)**
+   - **红线控制**：任何涉及“修改退货条款、大额金钱补偿”的策略，强制拦截并生成 Handoff 交接单。
+   - **状态回写**：外部营销推送必须有状态回流（sent/failed 及错误码），闭环追踪挽留触达结果。
+3. **运维与可观测性 (Traceability & Ops)**
+   - 提供类似于 `/ops/traces` 的页面，可视化展示模型训练报错、Agent 诊断反思 (Reflection)、代码修复及重试的完整流转，解决“黑盒训练”问题。
+
+---
+
+## 5. 演进路线图 (Roadmap)
+
+### 🏁 Phase 1: 业务底座与单次训练跑通 (MVP)
+- **数据层**：建立 `churn_predictions`、`intervention_jobs` 等底层表结构。
+- **算法层**：实现 Agent A（探查）和 Agent B（基线模型训练），能够基于静态 CSV 跑通基础训练。
+- **业务层**：输出高危名单列表。
+
+### 🛠 Phase 2: 核心攻坚 —— 模型训练自愈与 Agent 留痕
+- 构建 Agent 运行沙箱，安全执行生成的代码并拦截标准输出与报错。
+- 刻意“埋雷”（注入极端异常值或设置错误超参），开发 Agent B 的自动诊断与修复循环（Backoff 重试）。
+- 实现 `agent_runs` 留痕，在后台可视化展示“报错 -> 反思 -> 修复代码 -> 成功”的全过程。
+
+### 🚀 Phase 3: 协同挽留与系统闭环 (Intervention & ROI)
+- 引入 Agent C 多角色交接包生成机制，针对高危用户生成话术与挽留策略。
+- **连通增长平台**：将挽留策略自动写入真实业务库的 `marketing_push_jobs` 表。
+- 开发“留存经营看板”，真正将预测动作转化为“净回款 (Net Revenue)”与 LTV 的增长追踪。
+
+---
+*文档生成日期：2026-04-13*
+*关联基座项目：[ai-growth-platform](file:///Users/by/important/ai-growth-platform/README.md)*