天猫精灵开发平台配置指南

概述

天猫精灵开放平台是阿里巴巴为开发者提供的智能语音技能开发平台。通过该平台，你可以：

• 创建自定义语音技能
• 配置意图和触发词
• 连接后端服务（Home Voice Box）
• 发布技能供用户使用

参考文档： 天猫精灵开放平台官方文档

前置要求

• 阿里巴巴账号（淘宝/天猫账号）
• 已部署的 Home Voice Box 服务（参考 Cloudflare Pages 部署指南）
• 已配置的环境变量（参考 配置指南）

注册和登录

1. 访问开放平台

1. 访问 天猫精灵开放平台
2. 点击右上角 登录 按钮
3. 使用淘宝/天猫账号登录

2. 进入开发者中心

登录后，进入 开发者中心 → 技能开发。

创建技能

1. 新建技能

1. 在技能开发页面，点击 创建技能 或 新建技能
2. 选择技能类型：自定义技能
3. 填写技能基本信息：
   • 技能名称：例如 "智能家居控制"
   • 技能描述：简要描述技能功能
   • 技能图标：上传技能图标（可选）
4. 点击 确定 创建技能

2. 配置技能基本信息

在技能详情页面，完善技能的基本信息，包括：

• 技能名称和描述
• 技能分类
• 使用场景说明

配置意图

1. 创建意图

1. 在技能详情页面，进入 意图管理 或 意图配置
2. 点击 新建意图 或 添加意图
3. 填写意图信息：
   • 意图名称：必须与 Home Voice Box 中配置的意图标识完全一致（如：TurnOnLight）
   • 意图描述：简要描述意图功能
4. 点击 保存

2. 配置触发词

1. 在意图详情页面，进入 触发词 或 用户话术 配置
2. 添加用户可能说出的语音指令，例如：
   • "打开厨房灯"
   • "把灯打开"
   • "开灯"
3. 可以添加多个触发词，提高识别准确率
4. 点击 保存

3. 配置意图参数（可选）

如果你的意图需要参数（如设备名称、操作类型等），可以在意图配置中添加参数：

1. 在意图详情页面，进入 参数配置
2. 添加参数，例如：
   • 参数名：device（设备名称）
   • 参数类型：文本或枚举
   • 必填：是否必填
3. 保存参数配置

注意：当前版本的 Home Voice Box 主要使用意图名称来匹配操作，参数功能为可选。如果使用参数，需要在 functions/api/tomi.js 中解析参数。

配置服务地址

1. 设置服务地址

1. 在技能详情页面，进入 服务配置 或 后端服务
2. 选择服务类型：HTTPS
3. 填写服务地址：
   https://your-project.pages.dev/api/tomi

   将 your-project.pages.dev 替换为你的实际 Cloudflare Pages 域名

4. 请求方式：POST
5. 点击 保存

2. 配置请求格式

确保请求格式配置正确：

• Content-Type：application/json
• 字符编码：UTF-8

3. 配置请求头密钥（可选，但强烈推荐）

为了增强安全性，建议配置请求头密钥验证：

1. 在 Home Voice Box 的环境变量中设置 TOMI_SECRET_KEY（参考 配置指南）
2. 在天猫精灵平台的服务配置中，添加自定义请求头：
   • 请求头名称：X-Tomi-Secret
   • 请求头值：your_secret_key_here（与 TOMI_SECRET_KEY 环境变量的值一致）
3. 保存配置

域名校验

1. 获取校验信息

1. 在技能详情页面，进入 域名校验 或 安全配置
2. 系统会显示需要校验的文件名和内容
3. 复制显示的文件名（例如：verify_123456.txt）
4. 复制显示的文件内容（一串随机字符）

2. 配置到 Home Voice Box

1. 在 Home Voice Box 的环境变量中配置：
   • ALIGENIE_NAME：校验文件名
   • ALIGENIE_CONTENT：校验文件内容
2. 系统会自动处理校验文件，访问 /aligenie/文件名 即可返回校验内容

3. 验证域名校验

1. 在天猫精灵平台点击 验证 按钮
2. 系统会自动访问 https://your-domain.com/aligenie/文件名
3. 如果返回的内容与平台显示的内容一致，验证通过

测试技能

1. 使用测试工具

1. 在技能详情页面，进入 测试 或 调试
2. 输入测试话术（如："打开厨房灯"）
3. 查看返回结果，确认意图识别是否正确
4. 检查服务调用是否成功

2. 在真实设备上测试

1. 确保技能已保存并发布（或处于测试状态）
2. 在天猫精灵设备前说出配置的语音指令
3. 观察设备是否执行相应操作
4. 检查 Home Voice Box 的日志，确认请求是否正常接收

提交审核

1. 完善技能信息

在提交审核前，确保以下信息已完善：

• 技能名称和描述
• 技能图标
• 使用场景说明
• 隐私政策（如需要）
• 用户协议（如需要）

2. 提交审核

1. 在技能详情页面，点击 提交审核 或 发布
2. 填写审核信息
3. 等待平台审核（通常需要几个工作日）
4. 审核通过后，技能即可供用户使用

最佳实践

意图命名规范

• 使用有意义的名称，如 TurnOnKitchenLight 而不是 Action1
• 保持命名一致性，统一使用驼峰命名法
• 避免使用特殊字符和空格
• 确保意图名称与 Home Voice Box 中的配置完全一致

触发词设计

• 添加多种表达方式，提高识别准确率
• 使用自然语言，符合用户习惯
• 避免过于相似的触发词，减少误识别
• 定期测试和优化触发词

服务稳定性

• 确保服务地址可访问（使用 HTTPS）
• 配置合理的超时时间
• 实现错误处理和重试机制
• 监控服务日志，及时发现问题

故障排除

意图识别失败

• 检查意图名称是否与 Home Voice Box 中的配置完全一致
• 确认触发词是否配置正确
• 尝试添加更多触发词
• 检查语音识别日志

服务调用失败

• 检查服务地址是否正确
• 确认服务是否可访问（使用浏览器或 curl 测试）
• 查看 Home Voice Box 的日志，确认请求是否到达
• 检查环境变量配置是否正确

域名校验失败

• 确认 ALIGENIE_NAME 和 ALIGENIE_CONTENT 环境变量已正确配置
• 访问 https://your-domain.com/aligenie/文件名 检查是否能返回正确内容
• 确认文件名和内容与平台显示的一致

参考资源

• 天猫精灵开放平台官方文档
• 技能开发指南
• API 接口文档
• Home Voice Box 使用指南