一份用于构建强大的 Home Assistant 自定义集成和 HACS 组件的全面架构指南。
安装与下载
1. ClawHub CLI
从源直接安装技能的最快方式。
npx clawhub@latest install ha-integration-patterns
2. 手动安装
将技能文件夹复制到以下位置之一
~/.openclaw/skills/ <project>/skills/ 优先级：工作区 > 本地 > 内置
3. 提示词安装
将此提示词复制到 OpenClaw 即可自动安装。
请帮我使用 Clawhub 安装 ha-integration-patterns。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
更倾向于下载？
获取包含原生技能文件的ZIP压缩包。
什么是 Home Assistant 集成模式？
此技能为构建 Home Assistant 自定义集成提供了技术蓝图，是 Openclaw Skills 生态系统中的重要资源。它专注于从传统的“发后即忘”服务模式向现代的、数据丰富的服务响应和经过身份验证的 HTTP 视图的过渡。通过遵循这些既定模式，开发者可以在 AI 代理与智能家居硬件之间构建更可靠的桥梁，确保集成具有前瞻性并符合官方开发标准。
与 Home Assistant 集成需要对其事件循环和内部注册表有深入的理解。本指南综合了服务注册、通过 Store API 进行持久化存储以及自定义 HTTP 视图实现的最佳实践。它旨在帮助开发者避免常见的陷阱，例如使用不稳定的私有 API，这通常会导致在核心更新期间集成失败。
Home Assistant 集成模式 应用场景
- 为 Home Assistant 开发自定义 HACS 集成以扩展智能家居功能。
- 在外部 AI 代理与本地智能家居硬件之间构建 API 桥梁。
- 迁移旧版集成以使用最新的服务响应数据模式（HA 2023.7 之后）。
- 使用官方助手为集成设置和设备状态实现安全的持久化存储。
Home Assistant 集成模式 工作原理
- 确定适当的通信模式：使用服务进行操作，或使用 HTTP 视图进行复杂的数据检索。
- 配置集成的 manifest.json 并在 services.yaml 中定义服务模式，以支持现代响应结构。
- 在 Python 中实现服务处理器，利用 SupportsResponse.ONLY 或 SupportsResponse.OPTIONAL 参数向调用者返回数据。
- 使用 Home Assistant Store API 设置异步持久化存储，以确保配置在系统重启后依然存在。
- 在 custom_components 目录中部署集成结构，并使用提供的测试清单验证功能。
Home Assistant 集成模式 配置指南
确保您的开发环境可以访问 Home Assistant 实例。按照以下步骤初始化您的集成结构：
# 为您的集成创建目录结构
mkdir -p custom_components/your_domain
# 初始化核心文件
touch custom_components/your_domain/__init__.py
touch custom_components/your_domain/manifest.json
touch custom_components/your_domain/services.yaml
要启用服务响应，请在组件的初始化逻辑中注册您的服务：
# 在您的 Python 集成代码中
from homeassistant.helpers.service import SupportsResponse
hass.services.async_register(
domain,
"get_data",
handle_service_call,
supports_response=SupportsResponse.ONLY
)
Home Assistant 集成模式 数据架构与分类体系
该技能遵循自定义组件的标准 Home Assistant 目录和元数据分类。数据组织如下：
| 组件 | 文件/路径 | 描述 |
|---|---|---|
| manifest.json | 根目录 | 元数据、依赖项和版本信息 |
| services.yaml | 根目录 | 服务调用和模式的正式定义 |
| Storage API | .storage/ | 用于持久设置的分级 JSON 文件 |
| config_flow.py | 根目录 | 基于 UI 的配置向导逻辑 |
| init.py | 根目录 | 集成的核心设置和入口点 |
Home Assistant 集成模式 高级特性
- 支持服务响应数据，允许 Openclaw Skills 直接从服务调用中接收结构化 JSON。
- 实现自定义 HomeAssistantView 类，用于构建经过身份验证的 REST 端点。
- 使用具有版本控制和自动保存/加载周期的 Store API 实现异步数据持久化。
- 通过 async_migrate_entry 支持迁移逻辑，以处理集成设置中的破坏性变更。
- 严格遵守公共 API 标准，以确保跨不同 Home Assistant 核心版本的兼容性。
SKILL.md
加载中
Openclaw 相关技能
精选*
