天猫精灵(AliGenie)调试指南

当前问题分析

根据您的描述"触发成功但还是不正常",可能有以下几种情况:

1. 触发成功但无响应/响应错误

可能原因:

后端服务未正常启动或无法访问
意图配置不完整
槽位(Slot)配置错误
网络连接问题

解决方案:

A. 检查服务状态

# 检查本地服务
curl http://localhost:8000/api/health

# 检查公网服务  
curl https://mbe.hi-maker.com/api/health

# 查看服务日志
docker logs mbe-api --tail 100

B. 检查AliGenie配置

在AliGenie开发平台需要配置:

后端服务地址 (必填)
- 公网地址: https://mbe.hi-maker.com/api/aligenie/skill
- 注意: 必须是HTTPS,天猫精灵不支持HTTP
域名验证 (首次配置)
- 验证文件: https://mbe.hi-maker.com/aligenie/323aa2fd4c69780935b939d96c38ca97.txt
- 应该返回: Jfc4Z4Ur15JwUBuvUQD5wg7Nu8+l+HscqYlfofbyJdavfNxDWpPP4tUuhaygT1it
意图配置示例

意图名称: chat
意图别名: 米塞斯
意图识别语: 通用对话
槽位类型: 通用

推荐配置3个基础意图:

意图名称	意图标识	示例用语
米塞斯聊天	chat	"你好"、"介绍一下你自己"
知识查询	query	"什么是比特币"、"米塞斯是谁"
帮助	help	"你能做什么"、"如何使用"

2. 响应格式错误

天猫精灵要求特定的响应格式:

{
  "returnCode": "0",
  "returnMessage": "success", 
  "returnValue": {
    "reply": "这是回复内容",
    "resultType": "RESULT",
    "executeCode": "SUCCESS",
    "actions": [],
    "properties": {},
    "shouldEndSession": false
  }
}

3. 常见问题及解决方法

问题1: "触发成功"但天猫精灵无响应

原因:

webhook未正确配置
服务器响应超时(>5秒)
返回格式错误

调试方法:

# 运行测试脚本
python test_aligenie.py

# 或测试特定语句
python test_aligenie.py "你好，请介绍一下你自己"

问题2: 天猫精灵说"服务出错"

原因:

返回的returnCode不是"0"
网络连接失败
后端处理异常

检查方法:

查看天猫精灵平台的"测试中心" - "调试日志"
查看后端日志: docker logs mbe-api --tail 100 -f
使用调试页面: https://mbe.hi-maker.com/api/aligenie/debug

问题3: 天猫精灵听不懂/无法触发

原因:

未配置唤醒词或技能名称
意图训练不足
槽位配置不当

解决方法:

在AliGenie平台设置技能唤醒词,例如: "米塞斯"
完善意图的示例用语,至少10条
测试语音命令格式:
- "打开米塞斯" (唤醒技能)
- "米塞斯,你好" (带技能名)
- "你好" (已唤醒状态下)

4. 完整测试流程

步骤1: 验证服务可访问性

# Windows PowerShell
Invoke-WebRequest -Uri "https://mbe.hi-maker.com/api/aligenie/skill" -Method HEAD

期望返回: HTTP 200

步骤2: 测试意图响应

import requests
import json

# 模拟天猫精灵请求
payload = {
    "header": {
        "namespace": "AliGenie.Skill.Service",
        "name": "SkillService",
        "messageId": "test123",
        "payLoadVersion": "2"
    },
    "payload": {
        "intentName": "chat",
        "utterance": "你好",
        "sessionId": "session123",
        "skillId": "202601251802424",
        "deviceId": "test_device",
        "userId": "test_user",
        "requestType": "intent",
        "slots": {}
    }
}

response = requests.post(
    "https://mbe.hi-maker.com/api/aligenie/skill",
    json=payload,
    timeout=10
)

print(json.dumps(response.json(), ensure_ascii=False, indent=2))

期望输出:

{
  "returnCode": "0",
  "returnMessage": "success",
  "returnValue": {
    "reply": "您好!我是米塞斯智能助手..."
  }
}

步骤3: 在天猫精灵平台测试

进入技能管理 → 测试
选择"模拟对话"
输入测试语句: "你好"
查看响应和日志

5. 调试技巧

使用内置调试页面

访问: https://mbe.hi-maker.com/api/aligenie/debug

在页面上:

输入测试语句
点击"发送测试请求"
查看完整的请求和响应

查看实时日志

# Docker环境
docker logs mbe-api -f | Select-String "aligenie"

# 或查看所有日志
docker logs mbe-api -f

使用Postman测试

创建POST请求: https://mbe.hi-maker.com/api/aligenie/skill
Headers: Content-Type: application/json
Body: 使用上面的payload示例
发送并查看响应

6. 配置检查清单

Cloudflare Tunnel正常运行
后端服务(mbe-api)正常运行
域名验证文件可访问
Webhook地址配置正确
至少配置1个意图
意图有足够的示例用语(≥10条)
技能已保存并上线
技能已在"我的技能"中启用

7. 错误码参考

错误码	说明	解决方法
1033	Cloudflare错误	检查Tunnel状态
404	路径不存在	检查webhook URL
500	服务器错误	查看后端日志
超时	响应时间>5秒	优化后端性能

8. 快速修复命令

# 重启服务
cd d:\Mises\mises-behavior-engine
docker compose down
docker compose up -d

# 查看服务状态
docker ps

# 测试接口
python test_aligenie.py

9. 获取帮助

如果问题仍未解决:

查看完整日志: docker logs mbe-api --tail 500
检查天猫精灵平台的"调试日志"
访问调试页面查看详细错误信息
检查网络连接和DNS解析

联系信息

API文档: https://mbe.hi-maker.com/docs
调试页面: https://mbe.hi-maker.com/api/aligenie/debug
天猫精灵开发文档: https://aligenie.com/doc