0f13102a02
## 主要修复 ### 1. JSON 解析错误处理 - 修复所有 Agent 的 LLM 响应解析失败时返回原始内容的问题 - 当 JSON 解析失败时，返回友好的兜底消息而不是原始文本 - 影响文件: customer_service.py, order.py, product.py, aftersale.py ### 2. FAQ 快速路径修复 - 修复 customer_service.py 中变量定义顺序问题 - has_faq_query 在使用前未定义导致 NameError - 添加详细的错误日志记录 ### 3. Chatwoot 集成改进 - 添加响应内容调试日志 - 改进错误处理和日志记录 ### 4. 订单查询优化 - 将订单列表默认返回数量从 10 条改为 5 条 - 统一 MCP 工具层和 Mall Client 层的默认值 ### 5. 代码清理 - 删除所有测试代码和示例文件 - 刋试文件包括: test_*.py, test_*.html, test_*.sh - 删除测试目录: tests/, agent/tests/, agent/examples/ Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
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+ (本地开发)
配置环境
# 复制环境变量模板
cp .env.example .env
# 编辑配置
vim .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
启动服务
# 构建并启动所有服务
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 开发
cd agent
# 安装依赖
pip install -r requirements.txt
# 运行测试
python -m pytest tests/
# 本地调试
python main.py
MCP 服务开发
cd mcp_servers/{service_name}
# 安装依赖
pip install -r requirements.txt
# 启动服务 (默认端口见 docker-compose.yml)
python server.py
添加新功能
- 在
hyperf_api/openapi.yaml中定义 API 契约 - 实现 MCP 工具函数
- 编写 Agent Prompt 模板
- 在对应 Agent 中集成新能力
- 编写测试用例
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 | 售后记录 |
测试
# 运行 Agent 测试
cd agent && python -m pytest tests/
# 测试 API 端点
python agent/test_endpoint.py
License
MIT