使用指南

本指南将帮助你完成从登录系统到配置天猫精灵的完整流程。

1. 登录系统

  1. 访问登录页面：https://your-domain.pages.dev/LOGIN_PATH
  2. 输入配置的 ADMIN_PASSWORD
  3. 点击 登录
  4. 登录成功后会自动跳转到管理页面

安全提示：只有知道 LOGIN_PATH 的人才能访问登录页。 未认证用户访问受保护页面（如 /manage.html）会自动跳转到首页（文档页），不会暴露登录路径。

2. 创建意图映射

步骤详解

  1. 点击"添加映射"按钮

    在管理页面顶部，点击蓝色的"添加映射"按钮

  2. 填写意图标识

    输入天猫精灵的意图名称（如：TurnOnLight）。这个名称必须与天猫精灵开放平台中配置的意图名称完全一致。

  3. 选择实体设备

    • 在搜索框中输入设备名称或实体 ID 进行搜索
    • 从下拉列表中选择目标设备
    • 系统会自动根据设备类型筛选可用的接口

  4. 选择调用接口

    根据设备类型，系统会显示可用的接口选项：

    • 灯光设备：打开灯光、关闭灯光、切换灯光
    • 风扇设备：打开风扇、关闭风扇、切换风扇
    • 开关设备：打开开关、关闭开关、切换开关

  5. 填写回复内容（可选）

    输入天猫精灵执行操作后的语音回复内容（如："好的，已为您打开灯光"）。如果不填写，系统会使用接口的默认描述。

  6. 保存映射

    点击"保存"按钮，映射会立即保存到 KV 并更新内存缓存。

3. 编辑和删除映射

编辑映射

  1. 在映射列表中，点击要编辑的映射的"编辑"按钮
  2. 修改需要更改的字段
  3. 点击"保存"完成更新

删除映射

  1. 在映射列表中，点击要删除的映射的"删除"按钮
  2. 确认删除操作
  3. 映射会从 KV 和内存缓存中删除

4. 配置天猫精灵技能

在天猫精灵开放平台配置

  1. 创建技能

    登录天猫精灵开放平台，创建新的技能项目

  2. 配置意图

    • 创建意图，意图名称必须与系统中配置的意图标识完全一致
    • 配置意图的触发词（用户说出的语音指令）
    • 配置意图的参数（如果需要）

  3. 配置服务地址

    • 设置服务地址为：https://your-project.pages.dev/api/tomi（将 your-project.pages.dev 替换为你的实际域名）
    • 请求方式：POST
    • 如果配置了 TOMI_SECRET_KEY 环境变量，需要在请求头中配置密钥：
      • 请求头名称：X-Tomi-Secret
      • 请求头值：your_secret_key_here（与 TOMI_SECRET_KEY 环境变量的值一致）

    安全提示：如果未设置 TOMI_SECRET_KEY 环境变量，则不需要配置请求头。但为了安全，强烈建议在生产环境中设置密钥验证。详细配置方法请参考 天猫精灵平台配置指南。

  4. 完成域名校验

    • 在域名校验页面，复制显示的文件名和内容
    • 在 Home Voice Box 的环境变量中配置 ALIGENIE_NAME 和 ALIGENIE_CONTENT
    • 系统会自动处理校验文件，访问 /aligenie/文件名 即可返回校验内容

  5. 提交审核

    完成所有配置后，提交技能审核

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

5. 测试语音控制

测试流程

  1. 确保天猫精灵技能已通过审核并发布
  2. 在天猫精灵设备前说出配置的语音指令（如："打开厨房灯"）
  3. 系统会自动：
    • 接收天猫精灵的请求
    • 提取意图标识
    • 从内存缓存中查找映射
    • 调用对应的 Home Assistant API
    • 返回配置的回复内容
  4. 天猫精灵会播报回复内容

调试技巧

  • 在 Cloudflare Dashboard 中查看 Functions 日志，了解请求详情
  • 检查 Home Assistant 日志，确认 API 调用是否成功
  • 在管理页面查看意图映射是否正确配置
  • 在管理页面查看意图映射是否正确配置

使用技巧

意图命名建议

  • 使用有意义的名称，如 TurnOnKitchenLight、TurnOnKitchenSwitch 而不是 Action1
  • 保持命名一致性，如统一使用驼峰命名法
  • 避免使用特殊字符和空格

回复内容建议

  • 回复内容应该简洁明了，适合语音播报
  • 可以包含设备名称，如："好的，已为您打开厨房灯"、"好的，已为您打开厨房开关"
  • 避免过长的回复内容

设备类型示例

灯光设备示例：

  • 意图标识：TurnOnKitchenLight
  • 实体ID：light.kitchen
  • 调用接口：turnOnLight
  • 回复内容：好的，已为您打开厨房灯

风扇设备示例：

  • 意图标识：TurnOnFan
  • 实体ID：fan.xiaomi_fan
  • 调用接口：turnOnFan
  • 回复内容：好的，已为您打开风扇

开关设备示例：

  • 意图标识：TurnOnKitchenSwitch
  • 实体ID：switch.kitchen
  • 调用接口：turnOnSwitch
  • 回复内容：好的，已为您打开厨房开关

性能优化

  • 意图映射数据存储在内存中，查询速度极快
  • 首次请求时会自动初始化缓存
  • 增删改操作会自动同步更新内存缓存