1aeb17fcce
## 修改内容
### 1. 简化 Product Agent prompt
- 移除 `search_products` 工具说明
- 移除工具选择警告和说明
- 只保留 `search_spu_products` 作为唯一商品搜索工具
- 调整工具序号 1-5
### 2. 添加工具名自动映射
**位置**：第 195-201 行（非 JSON 格式），第 221-227 行（JSON 格式）
**功能**：
- 自动将 `search_products` 转换为 `search_spu_products`
- 防止 LLM 缓存或习惯导致的旧工具调用
- 添加日志记录映射操作
**示例**：
```python
# LLM 返回
{"tool_name": "search_products", "arguments": {"query": "ring"}}
# 自动转换为
{"tool_name": "search_spu_products", "arguments": {"keyword": "ring"}}
```
### 3. 添加参数自动映射
**位置**：第 240-246 行
**功能**：
- 自动将 `query` 参数转换为 `keyword` 参数
- 兼容 LLM 使用旧参数名的情况
**示例**：
```python
# LLM 返回
{"arguments": {"query": "ring"}}
# 自动转换为
{"arguments": {"keyword": "ring"}}
```
## 优势
1. **简化逻辑**：LLM 只有一个搜索工具可选，不会选错
2. **向后兼容**：即使 LLM 调用旧工具，也能自动转换
3. **参数兼容**：支持旧参数名 `query`，自动转为 `keyword`
4. **可观测性**：所有映射操作都有日志记录
## 预期效果
- LLM 调用 `search_spu_products`（Mall API）
- 返回商品卡片到 Chatwoot
- 即使调用旧工具也能正常工作
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