docs: 添加项目 README 文档
This commit is contained in:
wangliang
239
README.md
Normal file
239
README.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user