![](data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32"><text y="28" font-size="28">🤑</text></svg>)
23 电商小二 — Agent 对话系统
学习理念：这是整门课程中和 Agent 开发最直接相关的一个项目。前面 Ch19 掌柜智库是知识图谱RAG、Ch20 掌柜问数是 Text2SQL，而电商小二是一个完整的 LLM 驱动对话系统——它有对话管理（DialogueState）、规划调度（TurnPlanner）、任务执行（Flow+Action）、知识检索（KnowledgeHandler）、闲聊（ChitChatHandler）。这套架构几乎可以直接复用到任何需要"AI 客服/助手"的场景。
海外对标：Rasa（开源对话框架）、LangGraph Agent（规划+工具调用）、Amazon Lex（对话引擎）
本节 AI 替代率：~55% | 人工干预率：~45%
| 角色 | 能力范围 |
|---|---|
| 🤖 AI 擅长 | 生成 Flow YAML 配置、Action 代码骨架、Jinja2 提示词模板 |
| 👤 人类需理解 | TurnPlanner 的规划思路、DialogueState 的状态流转、Handler 三路分流的逻辑 |
零、项目全景
一、资源索引
所有学习材料的关系及位置，详见 5.设计文档/README.md。此处仅列出 study 文档的学习路线：
| 文档 | 对应模块 | 优先级 |
|---|---|---|
| 📄 01_项目概述与架构.md | 功能概览、环境搭建、DialogueEngine、分层架构 | 🔥 |
| 📄 02_对话状态管理.md | DialogueState、Session/Turn、序列化持久化 | 🔥 |
| 📄 03_TurnPlanner与Handler体系.md | LLM规划、三路分流、Clarify澄清 | 🔥 |
| 📄 04_TaskHandler：Flow+Command+Action.md | 流程编排、命令处理、动作系统 | 🔥 |
| 📄 05_KnowledgeHandler与ChitChatHandler.md | 知识检索Proider体系、闲聊处理 | 🟡 |
| 📄 06_API层与完整集成.md | FastAPI路由、依赖注入、Engine组装、前后端联调 | 🟡 |
二、学习路径
| 优先级 | 时间 | 文档 | 说明 |
|---|---|---|---|
| 🔥 | 10 min | 📄 01_项目概述与架构.md | 必读——搞懂整个系统长什么样 |
| 🔥 | 15 min | 📄 02_对话状态管理.md | 核心数据模型——读代码前先理解状态设计 |
| 🔥 | 20 min | 📄 03_TurnPlanner与Handler体系.md | 核心创新——LLM 怎么决定"下一步干啥" |
| 🔥 | 25 min | 📄 04_TaskHandler：Flow+Command+Action.md | 最长一篇——任务流程的完整实现 |
| 🟡 | 15 min | 📄 05_KnowledgeHandler与ChitChatHandler.md | 知识检索+闲聊兜底 |
| 🟡 | 10 min | 📄 06_API层与完整集成.md | 看完这篇就可以自己跑起来了 |
三、知识重复标记
| 知识点 | 首次出现 | 本项目的角色 | 第几次学 | 建议 |
|---|---|---|---|---|
| FastAPI 路由/依赖注入 | Ch16→Ch17 | API 层 | 🔵 第 3 次 | 关注差异点 |
| LLM 客户端封装 | Ch16 | 基础设施 | 🟢 第 2 次 | 了解即可 |
| Jinja2 模板 | Ch17 | Prompt 模板 | 🟢 第 2 次 | 了解即可 |
| SQLAlchemy ORM | Ch20 | 对话状态持久化 | 🟢 第 2 次 | 了解即可 |
| Pydantic Settings | — | 配置管理 | 🟢 第 2 次 | 了解即可 |
| DialogueEngine（对话引擎） | 🔥 全新 | 核心调度 | 🔴 第 1 次 | 重点学 |
| DialogueState 对话状态 | 🔥 全新 | 状态管理 | 🔴 第 1 次 | 重点学 |
| TurnPlanner LLM 规划 | 🔥 全新 | 规划决策 | 🔴 第 1 次 | 重点学 |
| Flow + Action 系统 | 🔥 全新 | 任务执行 | 🔴 第 1 次 | 重点学 |
| Handler 三路分流 | 🔥 全新 | 处理路由 | 🔴 第 1 次 | 重点学 |
| KnowledgeProvider 体系 | 🔥 全新 | 知识检索 | 🔴 第 1 次 | 了解即可 |
| Clarify 澄清 | 🔥 全新 | 追问机制 | 🔴 第 1 次 | 了解即可 |
四、技术栈健康度
| 技术 | 健康度 | 说明 |
|---|---|---|
| FastAPI | 🔥 巅峰 | 异步 Web 框架事实标准 |
| LangChain | ⚠️ 衰退 | 已被 LiteLLM/PydanticAI 等追赶，但仍有大量存量项目 |
| SQLAlchemy | 🔥 巅峰 | Python ORM 事实标准 |
| Pydantic | 🔥 巅峰 | Python 数据验证标准 |
| Jinja2 | 🟢 稳定 | 模板引擎，Prompt 模板仍广泛使用 |
| PyYAML | 🟢 稳定 | YAML 解析 |
| Vue3 + Vite | 🔥 巅峰 | 前端标准 |
| Docker Compose | 🔥 巅峰 | 本地开发环境标准 |
五、AI 协作指南
本文档看完后，以下问题直接问 AI：
Q: "帮我设计一个对话状态（DialogueState）的数据结构，支持多轮任务流程"
Q: "DialogueEngine 的消息处理和 Handler 分发的伪代码怎么写？"
Q: "用 YAML 定义一个电商客服的'退货申请'流程，包含 collect 和 action 步骤"
Q: "TurnPlanner 的 prompt 该怎么写，才能让 LLM 准确判断走哪条轨道？"
Q: "自定义 Action 的代码结构是怎样的？帮我写一个查天气预报的 Action"
AI 能做的：
- 生成完整的 Flow YAML 配置
- 生成自定义 Action 代码骨架
- 生成 TurnPlanner 的 prompt 模板
- 对比不同对话管理方案的优缺点