# intelligence-customer-service

**Repository Path**: fflo/intelligence-customer-service

## Basic Information

- **Project Name**: intelligence-customer-service
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能客服系统 (Intelligence Customer Service)

> **当前版本**: v2.5 | [查看迭代规划 →](ROADMAP.md)

基于 LangChain 和 LCEL 构建的智能客服 Demo，支持 RAG 知识库问答、多轮对话、混合检索、情感分析、多语言支持和流程化任务对话，采用 SOLID 设计原则，代码结构清晰，注释详细。

---

## 📋 目录

- [项目简介](#项目简介)
- [核心特性](#核心特性)
- [架构设计](#架构设计)
- [快速开始](#快速开始)
- [使用方式](#使用方式)
- [项目结构](#项目结构)
- [AI 开发规范](#ai-开发规范)
- [设计原则](#设计原则)
- [已实现功能](#已实现功能)
- [未来规划](#未来规划)
- [常见问题](#常见问题)

---

## 📖 项目简介

这是一个基于 LangChain 框架的智能客服系统 Demo，主要特点：

- **RAG 知识库问答**: 使用 FAISS 向量数据库实现语义检索，基于企业知识库回答用户问题
- **多轮对话**: 支持对话历史记忆，理解上下文连续对话
- **智能路由**: 自动识别用户意图，选择知识库模式或闲聊模式
- **LCEL 链式编排**: 使用 LangChain Expression Language 构建清晰的数据流
- **SOLID 设计原则**: 代码符合面向对象设计七大原则，易于扩展和维护
- **详细中文注释**: 每个模块、类、方法都有清晰的注释，适合初学者学习

---

## ✨ 核心特性

| 特性 | 说明 |
|------|------|
| **语义检索** | 基于 Embedding 向量技术，理解问题语义 |
| **混合检索** | FAISS 向量检索 + BM25 关键词检索，取长补短 (v1.2) |
| **意图识别** | 自动判断用户问题类型，智能选择回答策略 |
| **多轮对话** | 保留对话历史，支持上下文关联的连续对话 |
| **情感分析** | 识别用户情绪，动态调整回答语气 (v1.2) |
| **多语言** | 自动检测中英文，使用对应语言回答 (v1.2) |
| **任务对话** | 订单查询 / 售后处理 / 投诉反馈等流程化任务 (v1.2) |
| **知识库管理** | 支持 TXT/PDF/Word/Excel/Markdown/HTML 文档 (v1.2) |
| **持久化存储** | 向量库本地保存，避免重复向量化 |
| **插件化设计** | 支持多种 LLM 和 Embedding 提供商 |
| **RBAC 权限** | 基于角色的访问控制，4 级权限 (v2.5) |
| **多平台** | 微信小程序 + App 端适配 (v2.5) |
| **WebSocket** | 小程序/App 流式聊天 (v2.5) |
| **管理后台** | 用户管理 + 系统仪表盘 (v2.5) |

---

## 🛠️ 技术栈

### 后端技术栈

- **框架**: Django 5.x + Django REST Framework
- **数据库**: SQLite (开发) → PostgreSQL (v3.0+)
- **认证**: JWT (SimpleJWT)
- **API 文档**: drf-spectacular (OpenAPI/Swagger)
- **向量数据库**: FAISS
- **LLM 框架**: LangChain + LCEL
- **WebSocket**: Django Channels (v2.5)
- **ASGI 服务器**: Daphne (v2.5)

### 前端技术栈

- **框架**: Vue 3 + TypeScript + Vite + uni-app
- **状态管理**: Pinia
- **UI 框架**: uni-ui
- **HTTP 封装**: `uni.request` Promise 化 + 拦截器
- **编译目标**: H5 (v2.0+)、微信小程序 (v2.5)、App (v2.5)

---

## 🏗️ 架构设计

### 系统架构图

```
┌─────────────────────────────────────────────────────────────┐
│                        用户交互层                             │
│              (uni-app H5 v2.0 / Django Template 兼容)        │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                      服务门面层                               │
│              CustomerService (Facade 模式)                    │
│  • ask_stream()          • load_knowledge(directory)         │
│  • reset_history()       • task_handler (v1.2)              │
└──┬──────────────────┬──────────────────┬──────────────────┬──┘
   │                  │                  │                  │
   ▼                  ▼                  ▼                  ▼
┌────────┐    ┌────────────┐    ┌──────────────┐    ┌──────────┐
│ LLM工厂 │    │Embedding工厂│   │  文档加载器   │    │ FAISS管理 │
│        │    │            │   │              │    │          │
│创建LLM │    │创建Embedding│   │TXT/PDF/Word  │    │向量库操作 │
└────────┘    └────────────┘   │/Excel/MD/HTML│    └──────────┘
                               └──────────────┘      │
                                      │              ▼
                                      ▼    ┌──────────────────┐
                               ┌──────────┐│   LCEL 链式编排    │
                               │ 任务处理  ││ RAG/对话/意图识别│
                               │ v1.2     ││ 情感/语言/多语言 │
                               └──────────┘│ 任务对话链 (v1.2) │
                                           └──────────────────┘
```

### 数据流程图

```
用户提问
   ↓
[意图识别链] → 判断问题类型
   ↓
   ├── 知识库问题 → [RAG链]
   │                 ↓
   │           检索相关文档 (FAISS)
   │                 ↓
   │           组装 Prompt (context + question)
   │                 ↓
   │           LLM 生成回答
   │
   └── 闲聊对话 → [对话链]
                    ↓
              组装 Prompt (history + question)
                    ↓
              LLM 生成回答
   ↓
返回回答给用户
```

### LCEL 链式编排

使用 LangChain Expression Language (LCEL) 构建的三条核心链：

```python
# 1. RAG 链 - 基于知识库回答
rag_chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | RAG_PROMPT 
    | llm 
    | StrOutputParser()
)

# 2. 多语言 RAG 链 (v1.2)
multilingual_rag_chain = (
    {
        "context": itemgetter("question") | retriever | format_docs,
        "question": itemgetter("question"),
        "language": itemgetter("language"),
        "sentiment": itemgetter("sentiment"),
    }
    | MULTILINGUAL_RAG_PROMPT 
    | llm 
    | StrOutputParser()
)

# 3. 混合检索 (v1.2)
hybrid_retriever = EnsembleRetriever(
    retrievers=[faiss_retriever, bm25_retriever],
    weights=[0.6, 0.4]
)
```

---

## 🚀 快速开始

### 环境要求

- Python 3.10+ (需要使用 match-case 语法)
- pip 包管理工具

### 安装步骤

#### 1. 克隆项目

```bash
git clone <your-repo-url>
cd intelligence-customer-service
```

#### 2. 配置 LLM 和 Embedding

创建或编辑配置文件 `~/intelligence-customer-service/default-config.json`:

```json
{
  "app-info": {
    "name": "intelligence-customer-service",
    "version": "2.5"
  },
  "log-dir": null,
  "env": "test",
  "llm-list": [
    {
      "api-standard": "OpenAI",
      "model": "qwen-plus",
      "api-key": "你的apikey",
      "base-url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "temperature": 0.7,
      "max-tokens": 2000
    }
  ],
  "embedding": {
    "api-standard": "OpenAI",
    "model": "text-embedding-v3",
    "api-key": "你的apikey",
    "base-url": "https://dashscope.aliyuncs.com/compatible-mode/v1"
  }
}
```

**配置说明**:
- `llm-list`: LLM 配置列表，程序使用第一个配置
  - `api-standard`: API 标准，支持 `OpenAI` (所有兼容 OpenAI 接口的服务)
  - `model`: 模型名称，如 `gpt-3.5-turbo`, `gpt-4`, `qwen-plus` 等
  - `api-key`: 你的 API 密钥
  - `base-url`: API 地址，使用本地服务 (如 Ollama) 时修改此项
  - `temperature`: 温度参数 (0-1)，控制回答的创造性
  - `max-tokens`: 最大生成 token 数

- `embedding`: Embedding 模型配置 (**必须单独配置**)
  - `api-standard`: 同上，通常为 `OpenAI`
  - `model`: Embedding 模型名称，如 `text-embedding-ada-002` (OpenAI)、`text-embedding-v3` (阿里云)
  - `api-key`: API 密钥 (可与 LLM 相同)
  - `base-url`: API 地址 (可与 LLM 相同)

> ⚠️ **重要**: LLM 模型和 Embedding 模型是不同的，不能混用。例如 `qwen-plus` 是对话模型，不能用于 embedding；必须使用专用的 embedding 模型如 `text-embedding-v3`。

#### 3. 准备知识库 (可选)

将你的文档放入 `knowledge_base/` 目录，支持格式：
- `.txt` - 纯文本文件
- `.pdf` - PDF 文档
- `.docx` - Word 文档
- `.xlsx` / `.xls` - Excel 文档 (v1.2)
- `.md` - Markdown 文档 (v1.2)
- `.html` / `.htm` - HTML 文档 (v1.2)

项目已提供示例知识库 `knowledge_base/sample_faq.txt`

#### 4. 启动后端

```bash
# 1. 创建并激活虚拟环境
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate

# 2. 安装 Python 依赖
pip install -r requirements.txt

# 3. 数据库迁移
python manage.py migrate

# 4. 启动后端服务 (Daphne ASGI 服务器)
python main.py
# v2.5 起使用 Daphne ASGI 服务器，支持 HTTP + WebSocket
# 后端运行在 http://localhost:8000
```

#### 5. 启动前端

```bash
# 1. 进入前端项目目录
cd uni-app

# 2. 安装 Node.js 依赖
npm install

# 3. 启动 H5 开发服务器
npm run dev:h5
# 前端运行在 http://localhost:5173

# 4. 微信小程序 (v2.5)
npm run build:mp-weixin
# 编译产物在 dist/build/mp-weixin，用微信开发者工具导入

# 5. App (v2.5，通过 HBuilderX)
# 使用 HBuilderX 打开 uni-app 项目，运行到 App 端
```

> ⚠️ **Windows PowerShell 用户注意**: 如果遇到 `UnauthorizedAccess` 脚本执行策略错误，请使用 `npm.cmd` 替代 `npm`：
> ```powershell
> npm.cmd install
> npm.cmd run dev:h5
> ```

---

### API 文档

启动后端后，访问 `http://localhost:8000/api/v1/docs/` 查看 Swagger 交互式 API 文档。

文档涵盖所有 DRF API 端点，支持在线调试。

### 登录信息存储机制

**后端（服务端）**：
- 用户账号信息（用户名、密码哈希、邮箱）存储在 Django 内置的 `auth_user` 表中，数据库文件为项目根目录下的 `db.sqlite3`
- JWT Token 由 SimpleJWT 签发，服务端不存储 Token（无状态认证），通过密钥验证 Token 有效性
- Access Token 有效期 2 小时，Refresh Token 有效期 7 天（配置在 `web_django/settings.py` 的 `SIMPLE_JWT` 中）

**前端（客户端）**：
- JWT Token 通过 `uni.setStorageSync` 存储在浏览器 LocalStorage 中（H5 环境）
- 存储的 key 为：`access_token`（访问令牌）、`refresh_token`（刷新令牌）、`user_info`（用户基本信息）
- 每次 API 请求自动从 LocalStorage 读取 Token 并注入 `Authorization: Bearer <token>` 请求头
- Access Token 过期时自动使用 Refresh Token 刷新，刷新失败则清除所有存储并跳转登录页
- 退出登录时清除所有本地存储（见 `uni-app/src/utils/storage.ts`）

> **注意**：首次使用需要通过注册页面创建账号，或通过 Django 管理命令创建超级用户：
> ```bash
> python manage.py createsuperuser
> ```

---

## 使用方式

### Web 界面

启动程序后，自动打开浏览器:

```
http://127.0.0.1:8000
```

**界面功能**:

1. **智能对话**
   - 输入问题，获取流式回答
   - 支持多轮对话
   - 自动检测语言和情感 (v1.2)
   - 支持任务式对话: 订单查询 / 售后 / 投诉 (v1.2)

2. **知识库管理**
   - 上传文档 (.txt .pdf .docx .xlsx .md .html)
   - 查看文档列表
   - 删除文档
   - 自动重新构建向量库

3. **对话导出**
   - 导出为 TXT 格式
   - 导出为 JSON 格式
   - 带时间戳的完整记录

4. **RBAC 权限体系** (v2.5)
   - 4 种角色：超级管理员、管理员、客服、普通用户
   - 权限分级：知识库管理（管理员/客服）、用户管理（管理员）、对话（所有用户）
   - 管理后台：用户管理页、系统仪表盘

5. **WebSocket 聊天通道** (v2.5)
   - 用途：微信小程序和 App 不支持 SSE，通过 WebSocket 实现流式聊天
   - 端点：`ws://localhost:8000/ws/chat/`

6. **管理后台访问指南** (v2.5)

   系统包含**两套互相独立**的管理后台，满足不同使用场景：

   | # | 后台 | 地址 | 技术栈 | 适用人群 |
   |---|---|---|---|---|
   | A | Django 自带 admin | `http://127.0.0.1:8000/admin/` | Django 模板 | 运维 / 数据库直接编辑 |
   | B | uni-app 业务后台 | `http://localhost:5173/#/pages/admin/dashboard` | Vue 3 + uni-app | 日常运营 |

   > 📌 **关于 `http://127.0.0.1:8000/` 返回 404**：这是**预期行为**。Django 只暴露 `/admin/` 和 `/api/v1/` 两个路径，根路径没有首页 —— 前端页面在独立的 uni-app 开发服务器（默认 `http://localhost:5173`）上。

   #### 角色与权限要求

   | 角色 | Django admin (`/admin/`) | uni-app 业务后台 | 能修改他人权限 |
   |---|---|---|---|
   | `super_admin` 超级管理员 | ✅（需 `is_staff=True`） | ✅ 全部租户 | ✅ 所有用户 |
   | `admin` 管理员 | ✅（需 `is_staff=True`） | ✅ 仅本租户 | ✅ 本租户用户 |
   | `operator` 客服 | ❌ | ❌ | ❌ |
   | `user` 普通用户 | ❌ | ❌ | ❌ |

   > ⚠️ **两套权限独立**：`is_staff`/`is_superuser` 控制 Django admin 入口；`UserProfile.role` 控制 uni-app 业务后台和 DRF API 鉴权。两者都需要设置才能完整访问所有管理功能。

   #### 如何申请 / 获得管理员账号

   ##### 方式 1：首次初始化创建超级用户（推荐）

   ```bash
   python manage.py createsuperuser
   ```

   创建后该用户 `is_staff=True` 且 `is_superuser=True`，可立即登录 Django admin。但 `UserProfile.role` 默认仍为 `user`，还需要执行**方式 3** 把 role 提升到 `super_admin` 才能访问 uni-app 业务后台。

   ##### 方式 2：由已有管理员在后台授权（推荐日常流程）

   前提：当前登录账号是 `admin` 或 `super_admin`。

   1. 打开 uni-app 业务后台：`http://localhost:5173/#/pages/admin/users`
   2. 在用户列表中找到目标用户
   3. 点击"角色"下拉框，选择 `管理员` / `客服` / `超级管理员`
   4. 修改立即生效，无需用户重新登录

   ##### 方式 3：已有普通账号的一次性提权（开发调试场景）

   适用于自己是项目 Owner、但账号角色被初始化为 `user` 的情况。在项目根目录执行：

   ```bash
   python manage.py shell
   ```

   进入交互式 shell 后粘贴：

   ```python
   from django.contrib.auth.models import User
   from chat.models import Tenant

   USERNAME = 'your_username'  # 改成你的用户名

   u = User.objects.get(username=USERNAME)
   p = u.profile
   p.role = 'super_admin'
   if p.tenant is None:
       p.tenant = Tenant.objects.filter(slug='default').first() or Tenant.objects.first()
   p.save()
   u.is_staff = True
   u.is_superuser = True
   u.save()
   print('OK', u.username, u.is_staff, u.is_superuser, p.role, p.tenant)
   ```

   三行关键语义：
   - `is_staff=True, is_superuser=True` → 解锁 Django admin 入口
   - `role='super_admin'` → 解锁 uni-app 业务后台和 DRF API
   - 挂载默认租户 → 避免被租户中间件拦截

   #### 如何进入管理员页面

   **进入 Django 自带后台**：
   1. 启动后端：`python main.py`
   2. 浏览器访问 `http://127.0.0.1:8000/admin/`
   3. 使用 `is_staff=True` 的账号登录
   4. 左侧菜单选择"用户档案（User profiles）"可修改任意用户的 role / tenant

   **进入 uni-app 业务后台**：
   1. 启动前端：`cd uni-app && npm run dev:h5`
   2. 浏览器访问 `http://localhost:5173`，用 `admin` 或 `super_admin` 账号登录
   3. 访问以下页面（也可通过页面内导航进入）：
      - 仪表盘：`/#/pages/admin/dashboard`
      - 用户管理：`/#/pages/admin/users`
      - 租户管理：`/#/pages/admin/tenant`（仅 `super_admin` 可见）
      - 配额管理：`/#/pages/admin/quota`

   > 💡 **常见坑位**：如果登录后访问 admin 页面提示 403 或空白，多半是 `UserProfile.role` 仍是 `user`。使用方式 3 的 shell 脚本排查并修正。

---

## 项目结构

```
intelligence-customer-service/
├── chains/                  # LangChain 链式编排
├── chat/                    # Django 应用
│   ├── models.py            # 数据模型
│   ├── views.py             # 旧版视图（兼容保留）
│   ├── api_views.py         # DRF API 视图
│   ├── api_urls.py          # API 路由 (/api/v1/)
│   └── serializers.py       # DRF 序列化器
├── config/                  # 配置管理
├── document/                # 文档加载器
├── knowledge_base/          # 知识库文件
├── llm/                     # LLM 工厂
├── prompts/                 # 提示词模板
├── service/                 # 业务服务层
├── task/                    # 任务处理
├── uni-app/                 # H5 前端项目
│   ├── src/pages/           # 页面
│   ├── src/components/      # 组件
│   ├── src/stores/          # Pinia 状态管理
│   ├── src/api/             # API 调用封装
│   └── src/utils/           # 工具函数
├── utils/                   # Python 工具函数
├── vector_store/            # FAISS 向量库
├── web_django/              # Django 配置
├── main.py                  # 应用入口
├── manage.py                # Django 管理脚本
└── requirements.txt         # Python 依赖
```

---

## 🤖 AI 开发规范

本项目采用 **文档驱动 AI 开发** 模式，通过 **Skill + Rules 双轨制** 规范 AI 行为：

- **Skills**（`.qoder/skills/`）：按场景加载的指导性规范，教会 AI "如何做好"（命名规范、架构设计、提交流程等）
- **Rules**（`.qoder/rules/`）：全局生效的强制规则，规定 AI "绝不能做"（安全红线、行为底线、迭代纪律等）

AI 助手必须同时遵守 Rules（始终生效）和 Skills（按任务类型加载），确保代码质量一致、架构稳定、流程可控。

### Skill 体系总览

| Skill 文件 | 名称 | 职责 | 加载方式 |
|-----------|------|------|----------|
| [ai-behavior-protocol.md](.qoder/skills/ai-behavior-protocol.md) | AI 行为协议 | 决策框架、沟通规范、文档管理 | 始终激活 |
| [code-quality-standards.md](.qoder/skills/code-quality-standards.md) | 代码质量标准 | 命名规范、Type Hints、Docstring、错误处理 | 编码时激活 |
| [architecture-design.md](.qoder/skills/architecture-design.md) | 架构设计规范 | 层级约束、模块职责、SOLID、设计模式 | 设计时激活 |
| [development-workflow.md](.qoder/skills/development-workflow.md) | 开发流程规范 | 需求分析流程、分支策略、DoD | 规划时激活 |
| [security-compliance.md](.qoder/skills/security-compliance.md) | 安全与合规规范 | 代码示例、检查清单、最佳实践 | 安全场景激活 |
| [git-commit-standard.md](.qoder/skills/git-commit-standard.md) | Git Commit 规范 | 提交信息格式、分支管理、变更总结 | 提交时激活 |

### Rules 体系总览（全局强制）

| Rules 文件 | 名称 | 范围 | 优先级 |
|-----------|------|------|--------|
| [security-rules.md](.qoder/rules/security-rules.md) | 安全规则 | 敏感信息、输入验证、依赖安全 | 🔴 P0 最高 |
| [ai-behavior-rules.md](.qoder/rules/ai-behavior-rules.md) | AI 行为规则 | 用户主权、最小行动、禁止事项 | 🔴 P1 最高 |
| [development-rules.md](.qoder/rules/development-rules.md) | 开发原则规则 | 现有功能保护、迭代纪律、向后兼容 | 🔴 P1 高 |

### 优先级链

**规则冲突时按此顺序执行**:
```
安全 Rules > 行为 Rules > 开发 Rules > Skill 指导 > 用户指令（安全除外）
```

### 核心约束摘要

**AI 行为红线**:
- AI 是执行者，不是决策者
- 只做用户明确要求的事，不做"顺便"优化
- 任何不确定的情况必须先询问用户
- 修改代码前必须说明影响范围

**迭代开发**:
- 严格遵循 [ROADMAP.md](ROADMAP.md) 的迭代顺序
- 不跳过迭代、不提前实现未来迭代的功能
- 每次迭代完成后进入下一迭代

**问题跟踪**:
- 所有问题记录在 [ISSUES.md](ISSUES.md)
- 修复前必须查看历史记录
- 修复后标记完成状态

### 如何使用

**对于人类开发者**：
- 参考 Skill 文件了解项目编码规范
- 参考 Rules 文件了解不可触碰的红线
- 提交代码前对照检查清单自检

**对于 AI 助手**：
- **Rules**（`.qoder/rules/`）：全局强制，始终生效，不可违反
- **Skills**（`.qoder/skills/`）：按任务类型自动加载，指导如何执行
- 每次操作前自动校验 Rules，再根据场景加载对应 Skill

---

## 🎯 设计原则

本项目严格遵循 SOLID 设计原则：

| 原则 | 名称 | 实现方式 |
|------|------|----------|
| **S** | 单一职责原则 (SRP) | 每个类只负责一项职责，如 LLMFactory 只负责创建 LLM，FAISSManager 只管理向量库 |
| **O** | 开闭原则 (OCP) | 通过工厂模式，新增 LLM/Embedding 提供商无需修改现有代码 |
| **L** | 里氏替换原则 (LSP) | 所有 LLM 继承 BaseChatModel，可互相替换 |
| **I** | 接口隔离原则 (ISP) | 向量库管理器只暴露必要方法，不强迫依赖不需要的接口 |
| **D** | 依赖倒置原则 (DIP) | CustomerService 依赖抽象的 Runnable 接口，而非具体 FAISS 实现 |

### 使用的设计模式

- **工厂模式 (Factory)**: LLMFactory, EmbeddingFactory 统一创建对象
- **门面模式 (Facade)**: CustomerService 隐藏内部复杂性，提供简单接口
- **策略模式 (Strategy)**: 根据意图选择 RAG 或对话策略
- **管道模式 (Pipeline)**: LCEL 使用 `\|` 构建数据处理管道

---

## 已实现功能

### 核心功能

- [x] **RAG 知识库问答**
  - 文档加载 (TXT/PDF/Word/Excel/Markdown/HTML)
  - 智能文本切分 (RecursiveCharacterTextSplitter)
  - 向量化存储 (FAISS)
  - 混合检索: FAISS + BM25 EnsembleRetriever (v1.2)
  - 重排序 + 相关性过滤 (v1.2)
  - 基于知识库生成回答

- [x] **多轮对话**
  - 对话历史管理
  - 上下文关联回答
  - 自动截断过长历史

- [x] **智能意图识别**
  - 自动判断问题类型
  - 知识库问题 vs 闲聊对话
  - 动态选择回答策略

- [x] **情感分析** (v1.2)
  - 四类情绪识别: positive / neutral / negative / angry
  - 根据情绪动态调整回答语气

- [x] **多语言支持** (v1.2)
  - 自动检测中英文输入
  - 使用用户相同语言回答

- [x] **多轮任务对话** (v1.2)
  - 订单查询: 输入订单号 → 验证身份 → 查询结果
  - 售后服务: 订单号 → 服务类型(退货/换货/维修) → 原因 → 创建工单
  - 投诉反馈: 反馈类型 → 详细描述 → 联系方式 → 提交

- [x] **知识库优化** (v1.2)
  - 支持 6 种文档格式: TXT/PDF/Word/Excel/Markdown/HTML
  - Excel 自动提取表头和数据结构
  - Markdown 按标题层级智能分段
  - 知识版本管理 (MD5 哈希跟踪)

- [x] **LCEL 链式编排**
  - RAG 链 / 对话链 / 意图识别链
  - 情感分析链 / 语言检测链 (v1.2)
  - 多语言 RAG 链 / 多语言对话链 / 任务链 (v1.2)

### Web 界面

- [x] **Django Web 界面** (v1.1 → v1.2)
  - v1.2: 黑白灰极简高级风格
  - 响应式设计，支持移动端
  - 可折叠侧边栏
  - Toast 通知替代 alert 弹窗

- [x] **流式输出**
  - 打字机效果
  - 实时显示回答

- [x] **知识库管理**
  - 在线上传 / 删除 / 查看文档
  - 支持拖拽上传
  - 自动重新向量化

- [x] **对话导出**
  - 支持 TXT / JSON 格式
  - 带时间戳记录

### 代码质量

- [x] 详细中文注释 (适合小白学习)
- [x] SOLID 设计原则
- [x] 模块化架构
- [x] 异常处理完善
- [x] 日志记录完整

---

## 版本历史

### v2.5 (当前版本)

- **多平台编译**: 微信小程序 + App 端适配，uni-app 条件编译
- **RBAC 权限体系**: 基于 Django Group+Permission 的 4 级角色权限（超级管理员/管理员/客服/普通用户）
- **管理后台**: 用户管理 + 系统仪表盘
- **WebSocket 聊天**: Django Channels 实现，支持小程序/App 流式聊天
- **旧代码清理**: 移除 v1.x 遗留模板和视图

### v2.0

- **uni-app H5 前端**: Vue 3 + TypeScript + Vite 构建的现代化前端
- **DRF API 全覆盖**: 所有功能均通过 `/api/v1/` 提供 REST API
- **前后端分离**: 前端通过 JWT 认证消费后端 API
- **SSE 流式聊天**: uni-app 中实现打字机效果流式输出
- **Pinia 状态管理**: 全局状态管理，支持登录状态、对话历史
- **Markdown 渲染**: 聊天内容支持 Markdown 格式渲染
- **CORS 配置**: 前后端联调跨域支持

### v1.5

- **DRF API 基座**: 引入 Django REST Framework，与旧视图共存
- **JWT 认证**: SimpleJWT 实现登录、Token 刷新、注册
- **数据持久化**: `Conversation` + `Message` + `KnowledgeDocument` 模型
- **Swagger 文档**: drf-spectacular 自动生成 OpenAPI 文档
- **环境配置规范化**: python-dotenv 管理配置，添加 `.env.example`

### v1.2

- 混合检索: FAISS 向量检索 + BM25 关键词检索，通过 EnsembleRetriever 融合
- 重排序 & 过滤: 基于相关性分数过滤低质量结果
- 情感分析: 识别用户情绪 (positive/neutral/negative/angry)，调整回答语气
- 多语言: 自动检测中英文，使用对应语言回答
- 多轮任务对话: 订单查询 / 售后服务 / 投诉反馈流程化任务
- 知识库扩展: 新增 Excel / Markdown / HTML 格式支持
- 知识版本管理: MD5 哈希跟踪文档变更
- UI 升级: 黑白灰极简高级风格，Toast 通知，可折叠侧边栏
- 新增 API: 系统信息接口、任务取消接口

### v1.1

- Django Web 界面，夏日小清新配色
- SSE 流式输出
- 知识库在线管理 (上传/删除/查看)
- 对话记录导出 (TXT/JSON)

### v1.0

- RAG 知识库问答 + 多轮对话 + 意图识别
- FAISS 向量库持久化
- 命令行交互

---

## 未来规划

本项目的详细迭代规划已移至独立文档：[ROADMAP.md](ROADMAP.md)

> **当前已完成**: v1.5 (API 基座) → v2.0 (uni-app H5 前端) → v2.5 (多端发布 + 权限体系)

### 即将进行的迭代

| 迭代 | 版本 | 主题 | 预计周期 |
|------|------|------|----------|
| 迭代四 | v3.0 | 多租户商业化 | 4-5 周 |
| 迭代五 | v3.5 | 缓存 + 异步处理 | 3-4 周 |
| 迭代六 | v3.8 | 检索升级 + Agent | 5-6 周 |
| 迭代七 | v4.0 | 生产部署 + 安全 | 6-8 周 |
| 迭代八 | v4.5 | 企业级特性 | 6-8 周 |

### 核心目标

- **v3.0**: 多租户 SaaS + PostgreSQL + 配额管理
- **v3.5**: Redis + Celery + 性能优化
- **v3.8**: 向量库评估 + Agent 工具调用 + 重排序
- **v4.0**: Docker + CI/CD + 监控 + 安全加固
- **v4.5**: 客服工作台 + 数据分析 + 多渠道接入

详细内容请参考 [ROADMAP.md](ROADMAP.md)

## ❓ 常见问题

### Q1: 如何切换不同的 LLM 提供商？

修改配置文件中的 `api-standard` 和 `base-url`:

```json
{
  "api-standard": "OpenAI",
  "base-url": "http://localhost:11434/v1",  // Ollama 本地服务
  "model": "llama2"
}
```

### Q2: 向量库保存在哪里？

默认保存在 `./vector_store/faiss_index/` 目录，包含：
- `index.faiss` - FAISS 向量索引
- `index.pkl` - 文档原文和元数据

**向量库持久化机制**:
- **首次运行**: 从 `knowledge_base/` 加载文档 → 向量化 → 保存到本地
- **后续运行**: 直接从本地加载向量库，**不会重新生成**，节省时间和 API 调用
- **知识库更新后**: 需要删除旧向量库，重新生成 (见下方 Q8)

### Q8: 如何更新知识库？

当你修改或添加了 `knowledge_base/` 目录中的文档后，需要重新生成向量库：

**方法 1: 删除向量库目录** (推荐)
```bash
# Windows PowerShell
Remove-Item -Recurse -Force .\vector_store\faiss_index

# Linux/Mac
rm -rf ./vector_store/faiss_index
```

**方法 2: 手动删除**
直接删除 `vector_store/faiss_index/` 文件夹

删除后，下次运行 `python main.py` 时会：
1. 检测到本地没有向量库
2. 从 `knowledge_base/` 重新加载所有文档
3. 重新向量化并保存到本地

> ⚠️ **注意**: 如果知识库没有更新，**不要删除向量库**，否则每次启动都会重新向量化，浪费时间和 API 调用费用。

### Q3: 如何提高检索准确率？

1. **调整 chunk_size**: 在 `DocumentLoader` 中修改块大小 (默认 500)
2. **增加检索数量**: 在 `CustomerService` 中修改 `k` 值 (默认 3)
3. **优化知识库**: 确保文档质量，避免冗余和冲突信息
4. **改进 Prompt**: 调整 `RAG_PROMPT` 中的回答规则

### Q4: 支持哪些 Embedding 模型？

所有兼容 OpenAI 接口的 Embedding 服务都支持，包括：
- OpenAI: `text-embedding-ada-002`
- 阿里云 DashScope: `text-embedding-v3`
- 本地服务: Ollama、LocalAI
- 第三方代理: 任何 OpenAI 兼容 API

**配置示例 (阿里云 DashScope)**:
```json
{
  "embedding": {
    "api-standard": "OpenAI",
    "model": "text-embedding-v3",
    "api-key": "你的apikey",
    "base-url": "https://dashscope.aliyuncs.com/compatible-mode/v1"
  }
}
```

### Q5: 如何添加自定义知识库？

将文档放入 `knowledge_base/` 目录，支持格式：
- `.txt` - 纯文本
- `.pdf` - PDF 文档
- `.docx` - Word 文档
- `.xlsx` / `.xls` - Excel 文档 (v1.2)
- `.md` - Markdown 文档 (v1.2)
- `.html` / `.htm` - HTML 文档 (v1.2)

程序启动时会自动加载并构建向量库。

### Q6: 运行时报错 "No module named 'xxx'"？

确保已安装所有依赖：
```bash
pip install -r requirements.txt
```

### Q7: 为什么回答不准确？

可能原因：
1. **知识库不包含相关信息**: 检查 `knowledge_base/` 目录
2. **检索未命中**: 调整 Embedding 模型或增加检索数量
3. **Prompt 不够明确**: 修改 `customer_service_prompts.py` 中的模板
4. **LLM 能力限制**: 尝试使用更强的模型 (如 GPT-4)

---

## 📄 许可证

本项目仅供学习和演示使用。

---

## 🙏 致谢

- [LangChain](https://github.com/langchain-ai/langchain) - 强大的 LLM 应用开发框架
- [FAISS](https://github.com/facebookresearch/faiss) - 高效的向量检索库
- [OpenAI](https://openai.com/) - 提供强大的 LLM 和 Embedding API

---

## 📧 联系方式

如有问题或建议，欢迎反馈！

---

**⭐ 如果这个项目对你有帮助，请给个 Star！**