fa2c8f8102
## 问题 搜索商品时返回错误的工具调用 search_products 而非 search_spu_products ## 根本原因 Product Agent 的 PRODUCT_AGENT_PROMPT 中没有列出 search_spu_products 工具， 导致 LLM 不知道可以使用 Mall API 的 SPU 搜索工具 ## 修改内容 ### agent/agents/product.py - 将 search_spu_products 设为第一个工具（推荐使用） - 说明此工具使用 Mall API 搜索商品 SPU，支持用户 token 认证，返回卡片格式展示 - 原有的 search_products 标记为高级搜索工具（使用 Hyperf API） - 调整工具序号 1-6 ### docs/PRODUCT_SEARCH_SERVICE.md - 添加 Product Agent Prompt 更新说明章节 - 调整章节序号 ## 预期效果 LLM 现在应该优先使用 search_spu_products 工具进行商品搜索， 返回 Mall API 的商品数据并以 Chatwoot cards 格式展示 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