基于 LangChain + LangGraph 技术栈的电信 CRM 智能助手学习项目，从简单的 RAG 问答逐步演进到 Multi-Agent 协作系统。覆盖电信 CRM 五大核心场景：套餐咨询、账单缴费、故障诊断、携号转网挽留、客户流失预警。
系统通过 UnifiedAgent 统一入口自动路由用户意图，分发到五个专业模块处理：
用户输入 → UnifiedAgent（意图路由）
├── Phase 1: QAChain（RAG 套餐咨询）
├── Phase 2: BillingAgent（账单缴费）
├── Phase 3: DiagnosisAgent（故障诊断）
├── Phase 4: RetentionWorkflow（携号转网挽留）
└── Phase 5: ChurnAgent（流失预警分析）
| Phase | 能力 | 核心技术 | 复杂度 |
|---|---|---|---|
| 1 | 套餐查询与推荐 | RAG（检索增强生成）+ 查询改写 + LLM 重排序 | ⭐ |
| 2 | 账单查询与缴费 | 意图识别 → 工具执行 → 结果生成（三步分离） | ⭐⭐ |
| 3 | 故障诊断 | 状态机驱动多步推理 + SQLite 数据查询 | ⭐⭐⭐ |
| 4 | 携号转网挽留 | LangGraph 状态机 + Human-in-the-loop | ⭐⭐⭐⭐ |
| 5 | 客户流失预警 | Multi-Agent 协作（分析师 → 策略师 → 审核官） | ⭐⭐⭐⭐⭐ |
用户口语化问题 → 查询改写优化 → ChromaDB 向量检索 → LLM 重排序 → 生成回答。
- 知识库来源：SQLite 结构化套餐数据 + Markdown 文档
- 嵌入模型：DashScope text-embedding-v2
- 检索策略：Top-K 检索 + LLM 二次重排序
- 无关问题拦截：非电信问题自动拒绝
三步分离架构，不依赖模型自动 Tool Calling（兼容 DeepSeek 等非 Function Calling 模型）：
- 意图识别（LLM）：识别 query_customer / query_bill / query_history / pay_bill
- 工具执行（代码）：直接调用 SQLite 操作函数
- 结果生成（LLM）：将结构化数据转为自然语言回答
状态机驱动，每轮 LLM 只做当前状态所需的判断：
- 宽带故障流程：确认光猫状态 → 重启指导 → 检查欠费 → 区域故障查询 → 创建工单
- 手机信号流程：确认详情 → 查询流量使用 → 基站维护公告 → 诊断建议 → 创建工单
- 诊断全程记录日志，自动关联客户信息
基于 LangGraph 的有状态工作流：
collect_reason → analyze_customer → gen_offer → human_review(中断点) → handle_decision → end
- 根据转网原因（价格/信号/服务/其他）智能生成挽留方案
- Human-in-the-loop 设计，支持人工审核中断点
- 方案接受后自动降低客户流失风险评分
三个专业 Agent 协作辩论：
| Agent | 职责 | 产出 |
|---|---|---|
| Data Analyst | 检测 5 类流失信号（缴费摩擦、服务质变、联系频密、合约到期、已有风险） | 风险画像 |
| Strategy | 根据风险画像生成挽留方案 | 行动方案 |
| Auditor | 从成本、效果、合规角度交叉验证方案 | 审核意见 |
- 低风险客户自动跳过挽留流程
- 审核未通过最多进行 3 轮辩论调整
- 高风险或审核通过后自动创建主动关怀工单
| 层 | 技术选型 |
|---|---|
| 语言 | Python 3.12+ |
| AI 框架 | LangChain + LangGraph |
| 向量库 | ChromaDB（本地持久化） |
| 大语言模型 | DeepSeek Chat（兼容 OpenAI API） |
| 嵌入模型 | DashScope text-embedding-v2 |
| 数据存储 | SQLite |
| 可观测性 | LangSmith |
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt创建 .env 文件：
DEEPSEEK_API_KEY=your_deepseek_api_key
DASHSCOPE_API_KEY=your_dashscope_api_keypython data/seed_data.py生成的数据包含：
- 7 种套餐（5G 畅享/尊享、宽带融合、孝心卡、校园卡）
- 20 个客户（含不同流失风险等级）
- 6 个月的历史账单
- 模拟故障工单
- RAG 知识库文档（Markdown）
python cli_test.py统一入口模式自动路由用户意图，也可通过 .phase0 ~ .phase5 切换单独测试各模块。
├── src/
│ ├── unified_agent.py # 统一入口（意图路由）
│ ├── config.py # 配置（API Key、模型参数）
│ ├── rag_engine/
│ │ ├── knowledge_base.py # ChromaDB 构建
│ │ ├── retriever.py # 查询改写 + 检索 + 重排序
│ │ └── qa_chain.py # RAG QA 管线
│ ├── tools/
│ │ ├── billing_tools.py # 账单缴费工具集
│ │ └── billing_agent.py # 账单缴费 Agent
│ ├── agents/
│ │ ├── diagnosis_tools.py # 故障诊断工具集
│ │ └── diagnosis_agent.py # 故障诊断 Agent（状态机）
│ ├── workflows/
│ │ ├── retention_graph.py # 携号转网 LangGraph 状态机
│ │ └── retention_agent.py # 挽留工作流对话封装
│ └── multi_agent/
│ └── churn_agents.py # 流失预警 Multi-Agent 系统
├── data/
│ ├── seed_data.py # 模拟数据生成
│ ├── crm.db # SQLite 数据库
│ └── knowledge_base/ # RAG 知识库文档
├── tests/ # 各 Phase 测试用例
├── openspec/ # OpenSpec 规范文档
├── cli_test.py # CLI 交互入口
└── requirements.txt
pytest tests/ -v各 Phase 独立测试用例，覆盖核心业务场景和边界情况。
本项目按 5 个 Phase 渐进式构建，从简单的 RAG 查询到 Multi-Agent 辩论系统，展示 AI Agent 开发的复杂度递进。每个 Phase 的测试用例通过即代表该阶段能力达标。
遵循 OpenSpec 规范驱动开发（SDD）工作流：写 spec → 理解需求 → 实现 → 测试验证。