# edu_cs

**Repository Path**: shawn888888/edu_cs

## Basic Information

- **Project Name**: edu_cs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-14
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 教育智能客服系统（edu_cs）

面向在线教育行业的智能客服系统：基于业务中台数据，提供课程咨询、订单查询、学习进度查询、
退款申请、工单提交等场景的智能问答与多轮任务型对话，并配套 Vue3 演示前端。

## 目录结构

```
edu_cs/
├── edu-data/            # 业务中台（FastAPI + MySQL，只读复用，不改动）
├── edu_cs_backend/      # 智能客服后端（FastAPI + LLM 主 NLU）
├── edu_cs_frontend/     # 演示前端（Vue3 + Vite + Element Plus）
└── 需求说明.md          # 项目需求（仅本地）
```

## 技术栈

| 端 | 技术 |
|---|---|
| 业务中台 | Python 3.12 · FastAPI · MySQL 8（`edu` 库） |
| 客服后端 | Python 3.12 · FastAPI · Uvicorn · httpx · pymysql |
| 演示前端 | Vue 3 · Vite · Pinia · Element Plus · axios |

## 核心能力

- **LLM 主 NLU**：意图识别与槽位指令生成由大模型完成（OpenAI 兼容接口，注入最近对话历史理解指代），
  规则引擎仅作兜底；防幻觉三道防线（schema 校验 / 系统侧白名单 / 业务存在性校验）
- **多轮任务型对话**：订单查询（无单号自动列订单）、学习进度、退款申请、工单提交
  （槽位收集、流程暂存/恢复/取消、否定检测自动取消）
- **会话持久化**：会话 / 消息 / 轨迹存 MySQL 独立库 `edu_cs`，支持会话恢复与历史回溯
- **SSE 流式响应** + 非流式双模式
- **可靠性**：单次对话异常隔离（永不 500 击穿服务）、外部 API 超时与降级、LLM 无 key 自动降级
- **可观测性**：全链路轨迹（意图→流程→动作→耗时）+ 工单审计
- **调试面板**：实时展示意图 / 流程 / 槽位 / 轨迹 / 耗时

## 对话引擎边界

每轮请求遵循“理解提出计划，系统校验并执行”的链路：

```text
消息模型 → 历史上下文 → NLU / LLM
        → TurnPlan → TurnPlanValidator
        → FlowManager / ActionRegistry
        → 业务中台 → 回复、状态与轨迹持久化
```

- `app/domain` 定义消息和版本化会话状态；旧 JSON 可以继续恢复。
- `app/plan` 定义无副作用的 `TurnPlan` 和命令校验，LLM 不能直接修改状态。
- `config/flows.yaml` 管理流程名称、槽位顺序和动作名称；Python 动作注册表负责实际副作用。
- `app/engine/history.py` 统一构建带对象消息的有限历史，避免各处重复拼接 prompt。
- `edu-data` 只作为业务中台依赖，客服项目不修改其中的代码和数据结构。

## 快速开始

前置：MySQL 8（root 密码见各 `.env.example`）、Node ≥ 20、uv / Python 3.12。

### 1. 业务中台（edu-data）

```bash
cd edu-data
cp .env.example .env      # 填 DB_PASSWORD
uv sync
uv run init_db.py                        # 初始化数据库
uv run -m generate.main --profile smoke  # 生成样本数据（full 为全量）
uv run -m app.main                       # 启动 http://127.0.0.1:8000
```

### 2. 客服后端（edu_cs_backend）

- **PyCharm**：打开项目 → 解释器选 `.venv` → 右键 `run.py` → Run 'run'
- **命令行**：

```bash
cd edu_cs_backend
uv sync
cp .env.example .env      # LLM_API_KEY 可选：不填则 NLU 走规则兜底
uv run python scripts/init_db.py   # 创建会话库 edu_cs（幂等）
uv run python run.py               # 启动 http://127.0.0.1:8001
```

### 3. 演示前端（edu_cs_frontend）

```bash
cd edu_cs_frontend
npm install
npm run dev               # 打开 http://127.0.0.1:5173
```

打开页面 → 选择演示学员 → 新建会话 → 输入"我要退款"等体验多轮流程，右侧调试面板实时查看意图/槽位/轨迹。

## LLM 配置（可选）

在 `edu_cs_backend/.env` 配置后重启，NLU 即走大模型主路径（未配置自动降级规则引擎）：

```
LLM_API_KEY=sk-xxxx
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL=deepseek-chat
```

## 测试

```bash
cd edu_cs_backend && uv run pytest -v    # 86 项（独立测试库 edu_cs_test）
cd edu_cs_backend && uv run python scripts/smoke_e2e.py     # 冒烟
cd edu_cs_backend && uv run python scripts/acceptance.py    # 正式验收（幂等）
```

## 说明

- `.env` 均不入库，克隆后请按 `.env.example` 配置；`edu-data` 为只读复用，代码不做改动。
- 演示数据为 `edu-data` 生成器产出；验收脚本会在业务库创建退款/工单记录（正常业务操作）。