企业官网建设流程全解析

Home Assistant habitica.transformation 教程：3 个参数把队友变成雪人

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

背包里躺着一颗雪球时，一个 habitica.transformation 动作就能让队友变身为雪人。本文给出动手前核对清单、四种变形物品的参数取值、UI 与 YAML 两条配置路径，以及在每分钟 30 次请求限额下的正确调用与排障步骤。

动手前核对清单：先检查这 4 项

• 一个有效的 Habitica 账号（官网注册）
• 集成已完成配置。两种登录方式任选其一：
  • Login to Habitica（登录 Habitica）：用户名或邮箱+密码
  • Login to other instances（登录其他实例）：需要User ID与API Token（登录 Habitica 后进入Settings（设置）>Site Data（站点数据）获取）；实例 URL 默认https://habitica.com，自托管实例可改，自签名证书场景需关闭Verify SSL certificate（验证 SSL 证书）
• 配置项 ID 已记下：Settings（设置）>Devices & services（设备与服务）中对应条目的 ID，32 位十六进制字符串，即 YAML 里config_entry的取值
• 变形物品已在该角色背包中

机制速览：habitica.transformation 是做什么的

调用后你能观察到的现象：Habitica 里目标角色的形象变成雪人、幽灵、海星或花朵；Home Assistant 侧的角色数据最迟约60 秒后跟随更新。底层原因是集成向 Habitica API 发送一条请求，从config_entry所指角色的背包里消耗一件物品，施加到target所指的角色上。

该集成自0.78版本提供，质量等级platinum，属于服务型集成（ha_integration_type: service），采用 Cloud Polling（云轮询）模式，因此所有状态都是"拉取"回来的，而非实时推送。

四件物品的参数取值固定，只接受第二列的写法：

物品必须存在于"使用者"背包，动作才不会空转。

两种配置路径

路径 A：UI 可视化配置

1. 进入Settings（设置）>Automations & scenes（自动化与场景）。
2. 打开已有自动化或脚本，或经Create automation（创建自动化）>Create new automation（创建新自动化）新建；自动化需在When（何时）加触发器，脚本不需要。
3. 在Then do（然后执行）中点Add action（添加动作）。
4. 搜索并选中Habitica: Use a transformation item（Habitica：使用变形物品）。
5. 依次选择Config entry（配置项）（物品所属角色）、Transformation item（变形物品）、Target character（目标角色）。
6. 点Save（保存）。

该动作不支持 targets，界面不会让你选 area、device、entity 或 label——目标不是 Home Assistant 实体，而是按文本匹配的 Habitica 角色，只能在动作字段内指定。

路径 B：YAML 参数参考

最小可运行示例（与 动作文档 一致）：

action: habitica.transformation data: config_entry: 6b4be47a1fa7c3764f14cf756dc9899d item: snowball target: "Bob"

在 UI 里插入动作后，可切到 YAML 编辑器核对实际生成的data。

场景示例：每天 21:00 把队友变成幽灵

alias: Halloween ghost transformation triggers: - trigger: time at: "21:00:00" actions: - action: habitica.transformation data: config_entry: 6b4be47a1fa7c3764f14cf756dc9899d item: spooky_sparkles target: "Bob"

触发器只选单一时间点，避免高频条件反复消耗请求配额；item与target都是固定值，无需模板。

限制与配额：为什么要留意请求数

集成的固定开销是：自身数据每60 秒同步一次，每次3 个请求；队伍数据（含队员子条目）每15 分钟刷新一次；每个动作1 个请求，动作结束后5 秒再追加1 个请求拉回角色数据。

高频触发或并发运行的自动化会快速耗尽配额，后续动作可能被限流。Habitica 集成文档在已知限制一节明确要求：创建自动化时保持对速率限制的警觉。

排障清单：动作没生效时按序查这 5 处

1. 物品是否存在：item必须真的在config_entry角色的背包里。
2. 名称是否唯一：target按显示名、用户名或用户 ID 三选一匹配；重名时建议直接用用户 ID。
3. 配置项是否指向正确对象：多账号场景下，config_entry决定消耗谁的背包。
4. 是否触发限流：刚密集调用过动作就稍等几分钟；对照上一节的请求数核算。
5. 收集证据：启用 debug log（调试日志）、重启集成、问题复现后停止日志（文件会自动下载），并附上 diagnostics（诊断）数据再提交问题报告，流程见集成文档的 Troubleshooting 章节。

快速验证不必写 YAML：Settings（设置）>Tools（工具）>Actions（动作）中搜索habitica.transformation，填好三个参数点Perform action（执行动作）即可。

延伸：同一识别方式下的其他动作

habitica.cast_skill（施放职业技能，如盗贼pickpocket、战士smash、法师fireball）、habitica.score_habit（给习惯打分）、habitica.start_quest（开启任务副本）、habitica.accept_quest（接受队伍邀请）都使用同样的config_entry定位方式，并共享每分钟 30 次的请求配额；规划成套 Habitica 自动化时，把它们的触发频率合并计算。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io