企业官网建设流程全解析

Home Assistant 实战：用 Habitica 变形物品动作把队友变成雪人

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

habitica.transformation是 Home Assistant 中 Habitica 集成提供的动作，作用是把使用角色背包里的变形物品，施加在队伍成员或你自己身上。本文以"把队友 Bob 变成雪人"为场景，讲清这个动作的 UI 配置、YAML 写法、参数取值，以及调用频率的约束，让你能在自动化或脚本中安全地用上它。

四个物品，四种变身效果

habitica.transformation能做的效果一共只有四种，由你选择使用的物品决定。该集成的item取值与变身效果一一对应，全部固定，没有第五种：

使用的前提只有一个：物品必须在使用角色的背包里。Habitica 是任务游戏化平台，日常任务会被转换成 RPG 式成长，变形物品通常来自节日活动或商店购买；背包里没有对应物品时，动作不会生效。

配置动作前需要准备好什么

配置这个动作之前，有三项检查要做，都只需要一两分钟：

• 集成已就绪：打开Settings>Devices & services>Habitica，能看到已登录的角色条目。集成自 0.78 版本起提供，登录时可选账号密码，或填写User ID加API Token（在 Habitica 网页Settings>Site Data中获取），默认连接https://habitica.com，自托管实例可改 URL。
• 记下config_entry的值：选中 Habitica 配置项，在条目详情里找到 32 位十六进制字符串，例如6b4be47a1fa7c3764f14cf756dc9899d。这是 YAML 中定位角色背包的凭据。
• 确认背包里有货：登录 Habitica 客户端，检查准备使用的物品数量大于零，动作消耗的是"背包拥有者"身上的物品，而不是目标身上的。

在 UI 中给自动化添加变形动作的完整步骤

UI 是大多数用户的主路径，全程不写一行 YAML。以新建自动化为例：

1. 进入Settings>Automations & scenes，打开已有自动化，或选Create automation>Create new automation新建。
2. 新建自动化需要在When部分添加触发器；脚本没有触发器，由其他自动化或按钮调用时运行。
3. 在Then do部分点Add action。
4. 在搜索框输入Habitica，选择Use a transformation item。
5. 依次填写三个字段：Select character（选哪个角色的背包出物品）、Transformation item（选四个物品之一）、Target character（被变身的角色，按显示名、用户名或用户 ID 匹配）。
6. 点Save。

注意这个动作没有Area、Device、Entity、Label选项：目标角色不是 Home Assistant 实体，无法通过实体选择器指认，只能直接填文本。

不写 YAML 也能试一次：开发者工具的路径

如果只是想看效果而不建自动化，可以走开发者工具：打开Settings>Tools>Actions，搜索habitica.transformation，在参数区填入config_entry、item、target，点Perform action立即执行，然后在 Habitica 客户端里确认变身。

在自动化里插好动作之后，也可以切到 YAML 模式直接查看实际内容，它长这样：

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

三个必填参数怎么填，常见错误在哪

三个参数全部必填，缺一个动作就无法执行。下表汇总了类型、含义与踩坑点：

动作的调用成本与频率上限

Habitica 对第三方应用设了每分钟 30 个请求的速率限制，所有工具和集成共享这一个池子。集成本身的开销是：每 60 秒同步 3 个请求；每次动作执行 1 个请求，执行后 5 秒再补 1 个同步请求——也就是每次调用变形动作实际花 2 个请求配额，而队伍数据每 15 分钟刷新一次。据此可以算出上限：基础同步已占掉 3 个/分钟，再叠 13 次左右的动作就会触顶，超出后请求会被拒绝。📌 建议把这类动作放在手动脚本或低频触发器（比如按天、按事件）里，不要挂在高频状态变化上。

确认变身成功与失败后的排查顺序

确认成功最快的办法是打开 Habitica 网页或 App，看目标角色的外观是否已变化；在 UI 里切 YAML 模式核对三个字段值是否与预期一致，也是常用手段。

动作没生效时，按顺序查四点：

1. 背包里真的还有该物品——使用会消耗背包物品，用完了自然无效果。
2. target是否唯一匹配：先试显示名，不唯一就换用户 ID。
3. config_entry是否指向背包拥有者：这是最常被填错的字段。
4. 是否触发了速率限制：查看日志中来自 Habitica 的限流错误，有则等一分钟再试。

若依旧失败，按 集成文档的 Troubleshooting 章节开启调试日志、下载诊断数据后再提交问题报告。

与变形动作配合使用的四个相关功能

• habitica.cast_skill：给任务施放职业技能，如盗贼的pickpocket、法师的fireball。
• habitica.start_quest/habitica.accept_quest：开启或接受队伍副本任务。
• habitica.abort_quest/habitica.leave_quest：中止或退出正在进行的副本。
• habitica.send_message：往队伍聊天或私聊发消息，适合变身之后补一句调侃。

这些动作和变形动作共用同一套config_entry定位方式，也共享每分钟 30 个请求的速率上限，批量编排时一起计入配额。

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