assistant/README.md

# 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