240 lines
8.7 KiB
Markdown
240 lines
8.7 KiB
Markdown
# B2B Shopping AI Assistant
|
|
|
|
基于 AI 的 B2B 电商智能客服助手平台，支持订单查询、产品咨询、售后服务等业务场景。
|
|
|
|
## 功能特性
|
|
|
|
- **智能对话**: 基于智谱 AI (GLM-4) 的自然语言理解与生成
|
|
- **订单管理**: 查询、修改、取消订单，物流追踪，发票获取
|
|
- **产品服务**: 产品搜索、库存查询、B2B 报价、个性化推荐
|
|
- **售后支持**: 退货、换货、投诉、工单处理
|
|
- **知识库问答**: FAQ 智能问答
|
|
- **多渠道接入**: 通过 Chatwoot 支持多种客服渠道
|
|
|
|
## 技术架构
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 客户端渠道 │
|
|
│ (Website Widget / API / Chatwoot) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Chatwoot (消息平台) │
|
|
│ http://localhost:3000 │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ LangGraph Agent (AI 代理层) │
|
|
│ http://localhost:8000 │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ Router │ │ Product │ │ Order │ │ Aftersale│ │
|
|
│ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │
|
|
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ MCP Servers (工具服务) │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ Strapi │ │ Order │ │ Aftersale│ │ Product │ │
|
|
│ │ MCP │ │ MCP │ │ MCP │ │ MCP │ │
|
|
│ │ :8001 │ │ :8002 │ │ :8003 │ │ :8004 │ │
|
|
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 后端服务 (Hyperf PHP) │
|
|
│ http://hyperf-api:9501/api/v1 │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ Orders │ │ Products │ │ Aftersales │
|
|
│ └──────────┘ └──────────┘ └──────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 目录结构
|
|
|
|
```
|
|
├── agent/ # AI Agent 主服务
|
|
│ ├── agents/ # 各业务 Agent 实现
|
|
│ ├── core/ # 核心框架
|
|
│ ├── integrations/ # 第三方集成
|
|
│ ├── prompts/ # 提示词模板
|
|
│ ├── utils/ # 工具函数
|
|
│ └── webhooks/ # Webhook 处理
|
|
│
|
|
├── mcp_servers/ # MCP 服务集群
|
|
│ ├── strapi_mcp/ # 知识库 MCP
|
|
│ ├── order_mcp/ # 订单 MCP
|
|
│ ├── aftersale_mcp/ # 售后 MCP
|
|
│ ├── product_mcp/ # 产品 MCP
|
|
│ └── shared/ # 共享模块
|
|
│
|
|
├── hyperf_api/ # Hyperf PHP 后端
|
|
│ └── openapi.yaml # API 契约文档
|
|
│
|
|
├── docs/ # 文档
|
|
├── scripts/ # 脚本工具
|
|
├── tests/ # 测试用例
|
|
├── docker-compose.yml # Docker 编排配置
|
|
└── nginx.conf # Nginx 配置
|
|
```
|
|
|
|
## 快速开始
|
|
|
|
### 环境要求
|
|
|
|
- Docker & Docker Compose
|
|
- Python 3.10+ (本地开发)
|
|
- PHP 8.1+ (本地开发)
|
|
|
|
### 配置环境
|
|
|
|
```bash
|
|
# 复制环境变量模板
|
|
cp .env.example .env
|
|
|
|
# 编辑配置
|
|
vim .env
|
|
```
|
|
|
|
必需配置项：
|
|
|
|
```env
|
|
# AI 模型
|
|
ZHIPU_API_KEY=your_api_key
|
|
ZHIPU_MODEL=glm-4
|
|
|
|
# 数据库
|
|
POSTGRES_PASSWORD=your_secure_password
|
|
|
|
# Chatwoot
|
|
CHATWOOT_SECRET_KEY_BASE=your_secret_key
|
|
CHATWOOT_API_TOKEN=your_api_token
|
|
|
|
# 后端 API
|
|
HYPERF_API_URL=http://hyperf-api:9501
|
|
HYPERF_API_TOKEN=your_token
|
|
|
|
# Strapi (可选)
|
|
STRAPI_API_URL=http://your-strapi:1337
|
|
STRAPI_API_TOKEN=your_token
|
|
```
|
|
|
|
### 启动服务
|
|
|
|
```bash
|
|
# 构建并启动所有服务
|
|
docker-compose up -d --build
|
|
|
|
# 查看服务状态
|
|
docker-compose ps
|
|
|
|
# 查看日志
|
|
docker-compose logs -f agent
|
|
```
|
|
|
|
### 服务端口
|
|
|
|
| 服务 | 端口 | 说明 |
|
|
|------|------|------|
|
|
| Agent | 8000 | AI 代理服务 |
|
|
| Chatwoot | 3000 | 客服平台 |
|
|
| Nginx | 8080 | 文档静态服务 |
|
|
| Strapi MCP | 8001 | 知识库服务 |
|
|
| Order MCP | 8002 | 订单服务 |
|
|
| Aftersale MCP | 8003 | 售后服务 |
|
|
| Product MCP | 8004 | 产品服务 |
|
|
|
|
### 访问地址
|
|
|
|
- **客服平台**: http://localhost:3000
|
|
- **API 文档**: http://localhost:8080/docs/
|
|
- **Agent 健康检查**: http://localhost:8000/health
|
|
|
|
## 开发指南
|
|
|
|
### Agent 开发
|
|
|
|
```bash
|
|
cd agent
|
|
|
|
# 安装依赖
|
|
pip install -r requirements.txt
|
|
|
|
# 运行测试
|
|
python -m pytest tests/
|
|
|
|
# 本地调试
|
|
python main.py
|
|
```
|
|
|
|
### MCP 服务开发
|
|
|
|
```bash
|
|
cd mcp_servers/{service_name}
|
|
|
|
# 安装依赖
|
|
pip install -r requirements.txt
|
|
|
|
# 启动服务 (默认端口见 docker-compose.yml)
|
|
python server.py
|
|
```
|
|
|
|
### 添加新功能
|
|
|
|
1. 在 `hyperf_api/openapi.yaml` 中定义 API 契约
|
|
2. 实现 MCP 工具函数
|
|
3. 编写 Agent Prompt 模板
|
|
4. 在对应 Agent 中集成新能力
|
|
5. 编写测试用例
|
|
|
|
## API 概览
|
|
|
|
### 订单服务
|
|
|
|
| 端点 | 方法 | 描述 |
|
|
|------|------|------|
|
|
| `/api/v1/orders/query` | POST | 查询订单 |
|
|
| `/api/v1/orders/{id}/logistics` | GET | 物流追踪 |
|
|
| `/api/v1/orders/{id}/modify` | PUT | 修改订单 |
|
|
| `/api/v1/orders/{id}/cancel` | POST | 取消订单 |
|
|
| `/api/v1/orders/{id}/invoice` | GET | 获取发票 |
|
|
|
|
### 产品服务
|
|
|
|
| 端点 | 方法 | 描述 |
|
|
|------|------|------|
|
|
| `/api/v1/products/search` | POST | 产品搜索 |
|
|
| `/api/v1/products/{id}` | GET | 产品详情 |
|
|
| `/api/v1/products/recommend` | POST | 产品推荐 |
|
|
| `/api/v1/products/quote` | POST | B2B 报价 |
|
|
| `/api/v1/products/inventory/check` | POST | 库存查询 |
|
|
|
|
### 售后服务
|
|
|
|
| 端点 | 方法 | 描述 |
|
|
|------|------|------|
|
|
| `/api/v1/aftersales/return` | POST | 申请退货 |
|
|
| `/api/v1/aftersales/exchange` | POST | 申请换货 |
|
|
| `/api/v1/aftersales/complaint` | POST | 投诉处理 |
|
|
| `/api/v1/aftersales/ticket` | POST | 创建工单 |
|
|
| `/api/v1/aftersales/query` | GET | 售后记录 |
|
|
|
|
## 测试
|
|
|
|
```bash
|
|
# 运行 Agent 测试
|
|
cd agent && python -m pytest tests/
|
|
|
|
# 测试 API 端点
|
|
python agent/test_endpoint.py
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|