assistant/docs/PRODUCT_SEARCH_SERVICE.md

商品搜索服务实现文档

功能概述

添加了基于 Mall API 的商品搜索服务，支持根据关键词搜索 SPU 商品，并以 Chatwoot cards 格式展示搜索结果。

技术架构

用户发送搜索请求
    ↓
Router Agent 识别商品意图
    ↓
Product Agent 处理
    ↓
调用 Product MCP 工具: search_spu_products
    ↓
MallClient 调用 Mall API: /mall/api/spu
    ↓
返回商品列表
    ↓
发送 Chatwoot Cards 展示商品

修改的文件

1. MallClient - SPU 搜索 API

文件: mcp_servers/shared/mall_client.py:267-306

新增方法:

async def search_spu_products(
    self,
    keyword: str,
    page_size: int = 60,
    page: int = 1
) -> dict[str, Any]

功能: 调用 Mall API /mall/api/spu 接口搜索商品

2. Product MCP - SPU 搜索工具

文件: mcp_servers/product_mcp/server.py:291-378

新增工具: search_spu_products

参数:

• keyword (必需): 搜索关键词
• page_size: 每页数量（默认 60，最大 100）
• page: 页码（默认 1）
• user_token (必需): 用户 JWT token，用于 Mall API 认证
• user_id: 用户 ID（自动注入）
• account_id: 账户 ID（自动注入）

返回数据格式:

{
  "success": true,
  "products": [
    {
      "spu_id": "12345",
      "spu_sn": "61607",
      "product_name": "Product Name",
      "product_image": "https://...",
      "price": "99.99",
      "special_price": "89.99",
      "stock": 100,
      "sales_count": 50
    }
  ],
  "total": 156,
  "keyword": "61607"
}

3. Chatwoot 集成 - 商品卡片发送

文件: agent/integrations/chatwoot.py:1086-1243

新增方法:

async def send_product_cards(
    self,
    conversation_id: int,
    products: list[dict[str, Any]],
    language: str = "en"
) -> dict[str, Any]

功能: 发送商品搜索结果卡片到 Chatwoot

卡片数据结构:

{
  "content": "Found 3 products",
  "content_type": "cards",
  "content_attributes": {
    "items": [
      {
        "title": "Product Name",
        "description": "Special: €89.99 | Stock: 100 | Sold: 50",
        "media_url": "https://...",
        "actions": [
          {
            "type": "link",
            "text": "View Details",
            "uri": "https://www.gaia888.com/product/detail?spuId=12345"
          },
          {
            "type": "link",
            "text": "Buy Now",
            "uri": "https://www.gaia888.com/product/detail?spuId=12345"
          }
        ]
      }
    ]
  }
}

4. Product Agent - 搜索结果处理

文件: agent/agents/product.py:206-313

修改内容: 在 _generate_product_response 方法中添加特殊处理逻辑

逻辑:

1. 检测是否为 search_spu_products 工具返回
2. 如果是，直接调用 send_product_cards 发送商品卡片
3. 如果失败，降级到文本响应

5. Product Agent - Prompt 更新

文件: agent/agents/product.py:22-52

修改内容: 更新 PRODUCT_AGENT_PROMPT 可用工具列表

更新:

• 将 search_spu_products 设为第一个工具（推荐使用）
• 说明此工具使用 Mall API 搜索商品 SPU，支持用户 token 认证，返回卡片格式展示
• 原有的 search_products 标记为高级搜索工具（使用 Hyperf API）

6. Docker Compose - 环境变量配置

文件: docker-compose.yml:146-170

修改内容: 为 Product MCP 添加 Mall API 相关环境变量和 env_file

product_mcp:
  env_file:
    - .env
  environment:
    MALL_API_URL: ${MALL_API_URL}
    MALL_TENANT_ID: ${MALL_TENANT_ID:-2}
    MALL_CURRENCY_CODE: ${MALL_CURRENCY_CODE:-EUR}
    MALL_LANGUAGE_ID: ${MALL_LANGUAGE_ID:-1}
    MALL_SOURCE: ${MALL_SOURCE:-us.qa1.gaia888.com}

使用方式

用户在 Chatwoot 中搜索商品

示例对话:

用户: 搜索 61607
用户: 我想找手机
用户: 查找电脑产品

Agent 调用流程

1. Router Agent 识别商品搜索意图
2. Product Agent 接收请求
3. LLM 决定调用 search_spu_products 工具
4. Product MCP 执行工具调用：
   • 从 state 获取 user_token（用户的 JWT token）
   • 创建 MallClient 实例
   • 调用 Mall API /mall/api/spu?keyword=xxx&pageSize=60&page=1
   • 解析返回结果
5. Product Agent 接收工具结果
6. Chatwoot 集成 发送商品卡片

商品卡片展示

中文界面

┌─────────────────────────────────┐
│ 找到 3 个商品                       │
├─────────────────────────────────┤
│ ┌─────────────────────────────┐ │
│ │ [图片]                       │ │
│ │ Product Name                 │ │
│ │ 特价: €89.99 | 库存: 100     │ │
│ │ [查看详情] [立即购买]        │ │
│ └─────────────────────────────┘ │
│ ┌─────────────────────────────┐ │
│ │ [图片]                       │ │
│ │ Product Name 2               │ │
│ │ €99.99 | 库存: 50            │ │
│ │ [查看详情] [立即购买]        │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────┘

英文界面

┌─────────────────────────────────┐
│ Found 3 products                  │
├─────────────────────────────────┤
│ ┌─────────────────────────────┐ │
│ │ [Image]                      │ │
│ │ Product Name                 │ │
│ │ Special: €89.99 | Stock: 100 │ │
│ │ [View Details] [Buy Now]     │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────┘

多语言支持

商品卡片支持以下语言：

语言	代码	示例描述
中文	zh	特价: €89.99 | 库存: 100
英语	en	Special: €89.99 | Stock: 100
荷兰语	nl	Aanbieding: €89.99 | Voorraad: 100
德语	de	Angebot: €89.99 | Lager: 100
西班牙语	es	Oferta: €89.99 | Stock: 100
法语	fr	Spécial: €89.99 | Stock: 100
意大利语	it	Offerta: €89.99 | Stock: 100
土耳其语	tr	Özel: €89.99 | Stok: 100

API 接口说明

Mall API: 搜索 SPU 商品

端点: GET /mall/api/spu

请求参数:

keyword: 搜索关键词（商品名称、编号等）
pageSize: 每页数量（默认 60，最大 100）
page: 页码（默认 1）

请求头:

Authorization: Bearer {user_token}
Content-Type: application/json
tenant-Id: 2
currency-code: EUR
language-id: 1
source: us.qa1.gaia888.com

响应格式:

{
  "code": 200,
  "msg": "success",
  "result": {
    "list": [
      {
        "spuId": "12345",
        "spuSn": "61607",
        "productName": "Product Name",
        "productImage": "https://...",
        "price": "99.99",
        "specialPrice": "89.99",
        "stock": 100,
        "salesCount": 50
      }
    ],
    "total": 156
  }
}

配置要求

环境变量

在 .env 文件中配置：

# Mall API
MALL_API_URL=https://apicn.qa1.gaia888.com
MALL_TENANT_ID=2
MALL_CURRENCY_CODE=EUR
MALL_LANGUAGE_ID=1
MALL_SOURCE=us.qa1.gaia888.com

# 前端 URL（用于生成商品详情链接）
FRONTEND_URL=https://www.gaia888.com

必需条件

1. 用户认证: 商品搜索需要用户登录，获取 JWT token
2. Token 注入: Agent 会自动从 Chatwoot webhook 中提取 user_token
3. 网络访问: Agent 需要能够访问 Mall API（apicn.qa1.gaia888.com）

测试

1. 测试脚本

运行测试脚本（需要提供有效的 user token）:

python test_product_search.py

2. 在 Chatwoot 中测试

1. 打开 Chatwoot 对话框
2. 发送搜索请求，例如：
   • "搜索 61607"
   • "我想找手机"
   • "查找商品：电脑"

3. 查看 MCP 工具

访问 Product MCP 健康检查：

curl http://localhost:8004/health

预期响应：

{
  "status": "healthy",
  "service": "product_mcp",
  "version": "1.0.0"
}

故障排查

问题 1: 返回 "用户未登录"

原因: 缺少有效的 user_token

解决方案:

1. 确保用户已在 Chatwoot 中登录
2. 检查 webhook 是否正确提取 user_token
3. 查看日志：docker-compose logs -f agent

问题 2: 返回空商品列表

原因:

• 关键词不匹配
• Mall API 返回空结果

解决方案:

1. 尝试不同的关键词
2. 检查 Mall API 是否可访问
3. 查看 Mall API 响应日志

问题 3: 卡片无法显示

原因:

• 商品图片 URL 无效
• Chatwoot 不支持 cards 格式

解决方案:

1. 检查 product_image 字段是否为有效 URL
2. 验证 Chatwoot API 版本是否支持 cards
3. 查看 Chatwoot 集成日志

性能优化

已实现的优化

1. 分页限制: 默认返回 60 个商品，避免数据过大
2. 用户认证: 使用用户 token 而不是全局 API token，更安全
3. 错误处理: 优雅降级到文本响应

未来可优化

1. 缓存热门搜索: 缓存常见关键词的搜索结果
2. 并行搜索: 支持多关键词并行搜索
3. 智能推荐: 基于搜索历史智能推荐

相关文件清单

文件	说明
mcp_servers/shared/mall_client.py	Mall API 客户端（新增 SPU 搜索方法）
mcp_servers/product_mcp/server.py	Product MCP（新增 SPU 搜索工具）
agent/integrations/chatwoot.py	Chatwoot 集成（新增商品卡片方法）
agent/agents/product.py	Product Agent（新增卡片处理逻辑）
docker-compose.yml	容器配置（Product MCP 环境变量）

版本历史

• 2026-01-26: 初始版本
  • 添加 Mall API SPU 搜索支持
  • 添加 Chatwoot cards 商品展示
  • 支持多语言商品卡片
  • 集成用户认证

---

文档版本: 1.0 最后更新: 2026-01-26 维护者: Claude Code