Ha Integration Patterns_生活服务 skill-PHP中文网

Ha Integration Patterns

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

Home Assistant 自定义集成模式与架构决策。适用于构建 HACS 集成、自定义组件或 API 桥接，涵盖服务响应数据、HTTP 视图、存储 API 与集成架构。

家用助理集成模式

功能概述

家用助理集成模式是一项面向实际任务的技能，主要用于服务响应数据模式；默认情况下, HA服务为"火与遗忘", 返回空阵列[ ].；

核心要点

The Solutions (HA 2023.7+).；
Register Service Service Service reference Data pattern.；
The Register Service.。

使用与执行

它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；

结果检查与注意事项

若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。该技能适合用于一次性任务，也可以接入自动化工作流，与其他技能或上层代理配合完成更完整的业务链路；在组合使用时，应明确每一步的输入输出关系，并避免不同步骤之间出现参数冲突。

Home Assistant 集成模式

服务响应数据模式

问题

默认情况下，HA 服务为“即发即弃”（fire-and-forget）类型，返回空数组 []。

解决方案（HA 2023.7+）

注册服务时指定 supports_response 参数：

from homeassistant.helpers.service import SupportsResponse

hass.services.async_register(
    domain, 
    "get_full_config", 
    handle_get_full_config,
    schema=GET_CONFIG_SCHEMA,
    supports_response=SupportsResponse.ONLY,  # ← 关键参数
)

调用时添加 ?return_response 标志：

curl -X POST "$HA_URL/api/services/your_domain/get_full_config?return_response"

响应处理器

async def handle_get_full_config(hass: HomeAssistant, call: ServiceCall):
    """处理服务调用并返回数据。"""
    # ... 你的业务逻辑 ...
    return {"entities": entity_data, "automations": automation_data}

HTTP View 与 Service：何时使用哪一种

使用场景	推荐使用	不推荐使用
返回复杂数据	HTTP View	Service（未启用响应支持）
即发即弃型操作	Service	HTTP View
触发自动化	Service	HTTP View
查询状态/配置	HTTP View	内部存储 API

HTTP View 模式

适用于数据读取类 API：

from homeassistant.components.http import HomeAssistantView

class OpenClawConfigView(HomeAssistantView):
    """用于获取配置的 HTTP View。"""
    url = "/api/openclaw/config"
    name = "api:openclaw:config"
    requires_auth = True

    async def get(self, request):
        hass = request.app["hass"]
        config = await get_config_data(hass)
        return json_response(config)

# 在 async_setup 中注册：
hass.http.register_view(OpenClawConfigView())

重要提醒：避免使用内部 API

切勿使用以下划线开头的 API —— 它们属于私有接口，版本升级时可能随时变更。

❌ 错误示例：

storage_collection = hass.data["_storage_collection"]

✅ 正确做法：

# 仅使用公开 API
from homeassistant.helpers.storage import Store
store = Store(hass, STORAGE_VERSION, STORAGE_KEY)

存储模式

适用于小量数据（设置项、缓存）

from homeassistant.helpers.storage import Store

STORAGE_KEY = "your_domain.storage"
STORAGE_VERSION = 1

store = Store(hass, STORAGE_VERSION, STORAGE_KEY)

# 保存
data = {"entities": modified_entities}
await store.async_save(data)

# 加载
data = await store.async_load()

适用于大量数据（历史记录、日志）

请使用外部数据库或文件系统存储，而非 HA 提供的存储辅助工具。

需重点关注的破坏性变更

变更内容	生效版本	迁移方式
对话代理（Conversation agents）	2025.x+	直接调用 `async_process`
服务响应数据	2023.7+	添加 `supports_response` 参数
配置项迁移（Config entry migration）	2022.x+	使用 `async_migrate_entry`

务必定期查阅： https://www.home-assistant.io/blog/，确认目标版本范围内的变更说明。

HACS 集成目录结构

custom_components/your_domain/
├── __init__.py          # async_setup_entry
├── config_flow.py       # UI 配置流程
├── manifest.json        # 依赖项、版本等元信息
├── services.yaml        # 服务定义
└── storage_services.py  # 存储相关逻辑

最小化 manifest.json 示例

{
  "domain": "your_domain",
  "name": "Your Integration",
  "codeowners": ["@yourusername"],
  "config_flow": true,
  "dependencies": [],
  "requirements": [],
  "version": "1.0.0"
}