Habitica 集成 habitica.transformation 动作实战指南：用变形物品变身队友一次讲透
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
想在队伍里看到队友被变成雪人、幽灵或者海星吗？在 Home Assistant 的 Habitica 集成中，habitica.transformation动作可以替你完成这件事：从角色背包里取出一件变形物品，用在自己或任意一名队伍成员身上。
下面会先讲清账号与集成配置这些前置门槛，再带你走通 UI 零代码和 YAML 三行两种调用方式，最后讲透请求配额、故障排查和同系列动作，读完即可放心写自己的自动化。
开工前：账号、集成与 config_entry 三样先备好
- 需要一个有效的 Habitica 账号（在官网注册即可）。
- 在 Home Assistant 的设置流程中有两种登录方式：选Login to Habitica用用户名或邮箱 + 密码登录；选Login to other instances则填
User ID和API Token（登录 Habitica 后在Settings > Site Data里获取），还能指定实例 URL（默认https://habitica.com）并开关 SSL 证书校验。 - 配置完成后，Settings > Devices & services里会为你的角色生成一条配置条目，它那个 32 位十六进制的 ID，就是 YAML 里
config_entry的取值。多角色时靠它区分"谁在用物品"。🔑
四种变形物品速览：先看背包里有没有
| 变身效果 | 物品（UI 名称） | YAML 取值 |
|---|---|---|
| 雪人 snowfriend | Snowball 雪球 | snowball |
| 幽灵 ghost | Spooky sparkles 惊悚闪光 | spooky_sparkles |
| 海星 starfish | Seafoam 海沫 | seafoam |
| 花朵 flower | Shiny seed 闪亮种子 | shiny_seed |
硬性前提：物品必须真实躺在使用角色的背包（inventory）里，否则动作无法执行。变形物品一般来自节日活动或商店购买，动手前先在 Habitica 里确认一下背包。
方式一：界面里零代码完成变身
- 打开Settings > Automations & scenes，进入一个现有自动化/脚本，或新建一个（新自动化记得在When里加触发器，脚本则不需要）。
- 在Then do区域点Add action，搜索并选中Habitica: Use a transformation item。
- 依次填写三个必填项：Select character（背包所属角色）、Transformation item（要用的物品）、Target character（被变身的对象）。
- 点Save保存。
你会注意到它没有 targets 选项——不提示选区域、设备、实体或标签。因为目标角色不是 Home Assistant 实体，而是按显示名称、用户名或用户 ID 文本匹配出来的 Habitica 角色，所以只能写进动作自己的字段里。
方式二：YAML 里三行搞定调用
最简片段如下（放在自动化或脚本的 actions 里）：
action: habitica.transformation data: config_entry: 6b4be47a1fa7c3764f14cf756dc9899d item: snowball target: "Bob"三个参数缺一不可：config_entry定位"哪个角色在丢物品"；item只能取snowball、spooky_sparkles、seafoam、shiny_seed四值之一，且背包里必须有货；target是变身对象，按显示名称、用户名或用户 ID 匹配。💡
底层机制：把请求当作一笔"配额预算"来花
Habitica 对所有第三方应用统一限制每分钟 30 次请求，你在所有工具和集成中的消耗合并计算，这就像一笔共享预算。集成的"固定开销"是：每 60 秒同步自身数据 3 次请求，每 15 分钟刷新一次队伍数据；而每次动作本身花 1 次请求，动作结束后约 5 秒还会追加 1 次同步请求，把背包、外观等新数据拉回来。📊 因此触发频繁的自动化或并发跑多个变形动作，会明显蚕食预算，写自动化时请给这个红线留出余量。
变身没生效？按这个顺序逐项排查
- 背包里是否真的有该物品，数量是否够用。
target填写的名称/用户名能否唯一匹配到目标角色。config_entry是否指向了"持有物品"的那个角色，别和另一个账号的 ID 搞混。- 是否因高频调用触发了每分钟 30 次的速率限制。
- 以上都正常仍不行，就启用调试日志、重启集成，复现后停止日志并下载诊断数据，附在问题报告里。🔍
延伸：同系列动作也值得一试
habitica.transformation只是该集成 18 个动作之一，habitica.cast_skill（对任务施放职业技能）、habitica.score_habit等打分动作、habitica.start_quest（开启副本）与habitica.accept_quest（接受队伍邀请）都沿用同一套config_entry定位方式，同样共享那笔请求配额，掌握本文方法后可直接迁移使用。
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
