核心功能与用法
本 Skill 提供 Home Assistant 自定义集成的系统化架构指导，主要解决以下开发场景：
1. Service 响应数据模式（HA 2023.7+）
- 突破传统 "fire-and-forget" 限制，通过
supports_response=SupportsResponse.ONLY实现带返回值的 Service 调用 - 调用时附加
?return_response参数获取 JSON 响应 - 适用于需要返回配置数据、实体状态的复杂操作场景
2. HTTP View vs Service 决策矩阵
| 场景 | 推荐方案 | 原因 |
|------|---------|------|
| 返回复杂数据 | HTTP View | 天然支持结构化响应 |
| 触发自动化 | Service | 与 HA 事件系统深度集成 |
| 纯查询操作 | HTTP View | RESTful 语义更清晰 |
| 无返回值动作 | Service | 轻量级，符合 HA 设计哲学 |
3. 存储层架构
- 小型数据（设置、缓存）：使用
homeassistant.helpers.storage.Store - 大型数据（历史、日志）：必须采用外部数据库/文件存储
- 严禁使用下划线前缀的内部 API
4. HACS 合规结构
标准化目录布局包含 __init__.py、config_flow.py、manifest.json、services.yaml 等必需文件，确保与 HACS 生态兼容。
显著优点
- 权威性高：基于 HA 官方开发者文档和版本演进实践
- 版本感知：明确标注各特性引入版本（2022.x - 2025.x+），提供迁移路径
- 反模式警示：通过 "Wrong vs Right" 对比，避免常见的内部 API 误用
- 实战验证：包含 HA-OpenClaw Bridge 项目的真实经验教训
潜在局限
- 版本碎片化：HA 演进速度快，部分模式在旧版本（<2023.7）不可用
- Python 专属：示例代码均为 Python，非 Python 开发者需额外转换
- 未覆盖前端：专注于后端集成，不涉及 Lovelace 卡片开发
- 测试深度有限：Testing Checklist 较简略，缺乏自动化测试框架指导
适合人群
- 计划开发 HACS 自定义集成的 Python 开发者
- 需要将外部系统桥接到 HA 的架构师
- 维护现有集成需适配新版 HA 的维护者
常规风险
- 破坏性变更：HA 版本升级可能导致集成失效，需持续关注官方 Blog
- 认证配置：HTTP View 的
requires_auth=True若配置不当存在未授权访问风险 - 存储性能：误用 Store 存储大量数据会导致 HA 启动变慢
- 并发安全：Storage API 非线程安全，需在 async 上下文正确使用