ad7f30d54c
## 问题 Product MCP 启动时出现警告： ``` WARNING Tool already exists: search_products ``` 导致工具调用时返回 404 错误： ``` POST /tools/search_products HTTP/1.1 404 Not Found ``` ## 根本原因 Product MCP 中有两个同名工具： 1. **第 40-99 行**：旧的 `search_products`（使用 Hyperf API） 2. **第 292-378 行**：新的 `search_products`（使用 Mall API） FastMCP 无法注册同名工具，导致注册失败。 ## 解决方案 删除旧的 `search_products` 工具定义（第 40-99 行），保留新的使用 Mall API 的版本。 ## 修改内容 **文件**: mcp_servers/product_mcp/server.py - 删除第 40-99 行（旧的 search_products 工具） - 保留第 291 行开始的新的 search_products 工具 ## 影响 - 移除了基于 Hyperf API 的旧搜索功能 - 所有商品搜索统一使用 Mall API - 不再支持复杂过滤条件（category, brand, price_range 等） - 简化为关键词搜索，返回商品卡片格式 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