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