Files

wangliang e093995368 feat: 增强 Agent 系统和完善项目结构

主要改进:
- Agent 增强: 订单查询、售后支持、客服路由等功能优化
- 新增语言检测和 Token 管理模块
- 改进 Chatwoot webhook 处理和用户标识
- MCP 服务器增强: 订单 MCP 和 Strapi MCP 功能扩展
- 新增商城客户端、知识库、缓存和同步模块
- 添加多语言提示词系统 (YAML)
- 完善项目结构: 整理文档、脚本和测试文件
- 新增调试和测试工具脚本

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-01-16 16:28:47 +08:00

3.8 KiB

Raw Permalink Blame History

Order MCP 实现计划

概述

根据实际 API 接口分析，需要重构 order_mcp 以适配真实的 Gaia888 商城 API。

当前问题

1. API 端点不匹配

当前: POST /orders/query
实际: GET /mall/api/order/show?orderId=xxx

2. 请求方法不匹配

当前: POST with JSON body
实际: GET with query parameters

3. 缺少必要的 Headers

实际 API 需要以下 Headers：

Authorization: Bearer {token}
tenant-Id: {tenant_id}
currency-code: {currency}
language-id: {language_id}
source: {source}
Device-Type: {device_type}

实施计划

步骤 1: 更新 shared/hyperf_client.py

目标: 支持自定义 Headers 和更灵活的 API 配置

修改内容:

添加可选的 tenant_id, currency_code, language_id, source, device_type 配置
在请求中自动添加这些 Headers
支持不同的 base_url（Gaia888 API）

代码变更:

class HyperfSettings(BaseSettings):
    hyperf_api_url: str
    hyperf_api_token: str
    tenant_id: int = 2
    currency_code: str = "EUR"
    language_id: int = 1
    source: str = "us.qa1.gaia888.com"
    device_type: str = "pc"

步骤 2: 更新 order_mcp/server.py

目标: 重构 query_order 工具以适配真实 API

修改内容:

将 POST 请求改为 GET 请求
将 JSON body 参数改为 query string 参数
更新端点路径为 /mall/api/order/show
添加 get_order_detail 工具（如果需要）

新工具设计:

query_order - 订单查询

@mcp.tool()
async def query_order(
    order_id: str,
    user_id: Optional[str] = None
) -> dict:
    """查询订单详情
    
    Args:
        order_id: 订单号
        user_id: 用户ID（可选，用于权限验证）
    
    Returns:
        订单详细信息
    """

get_order_list - 订单列表查询（新增）

@mcp.tool()
async def get_order_list(
    user_id: str,
    status: Optional[str] = None,
    page: int = 1,
    page_size: int = 10
) -> dict:
    """查询用户订单列表
    
    Args:
        user_id: 用户ID
        status: 订单状态筛选
        page: 页码
        page_size: 每页数量
    
    Returns:
        订单列表和分页信息
    """

步骤 3: 更新环境变量配置

.env 文件需要添加:

# Order MCP 配置
TENANT_ID=2
CURRENCY_CODE=EUR
LANGUAGE_ID=1
SOURCE=us.qa1.gaia888.com
DEVICE_TYPE=pc

步骤 4: 更新 docker-compose.yml

确保环境变量传递:

order_mcp:
  environment:
    HYPERF_API_URL: ${HYPERF_API_URL}
    HYPERF_API_TOKEN: ${HYPERF_API_TOKEN}
    TENANT_ID: ${TENANT_ID:-2}
    CURRENCY_CODE: ${CURRENCY_CODE:-EUR}
    LANGUAGE_ID: ${LANGUAGE_ID:-1}
    SOURCE: ${SOURCE:-us.qa1.gaia888.com}
    DEVICE_TYPE: ${DEVICE_TYPE:-pc}

API 端点映射

功能	当前端点	实际端点	方法
订单详情	/orders/query	/mall/api/order/show	GET
订单列表	/orders/query	/mall/api/order/list	GET
物流跟踪	/orders/{id}/logistics	/mall/api/order/logistics	GET
取消订单	/orders/{id}/cancel	/mall/api/order/cancel	POST

数据模型

订单详情响应格式

{
  "orderId": "202071324",
  "status": "shipped",
  "totalAmount": 5000.00,
  "items": [...],
  "shippingAddress": {...},
  "trackingNumber": "SF1234567890",
  "createdAt": "2026-01-10 10:00:00"
}

测试计划

单元测试 - 测试 HyperfClient 的 Header 生成
集成测试 - 测试与真实 API 的连接
端到端测试 - 通过 agent 调用 order_mcp 工具

注意事项

安全性: JWT token 需要定期刷新
错误处理: 需要处理 API 返回的各种错误码
缓存: 考虑添加订单查询缓存以减少 API 调用
日志: 记录所有 API 调用和响应

3.8 KiB Raw Permalink Blame History Unescape Escape