AI导哈

Home Assistant集成模板

一个用于快速启动Home Assistant自定义集成的Copier模板，提供完整的开发环境配置。

  • by eyalmichon
  • Jinja
  • 本地部署
  • 更新于
在 GitHub 查看 eyalmichon/ha-integration-template

使用说明

家庭助理集成模板

A. 复印机 用于引导Home Assistant与完全配置的开发环境进行自定义集成的模板。

所得

  • Devcontainer：Python 3.14、uv、gh-CLI、Ruff、Pylance——在VS Code/Coursor中打开并正常工作
  • CI工作流：Ruff-lint、Hassfest、HACS验证、CodeQL、自动发布
  • 预提交挂钩：每次提交时都使用Ruff格式+lint
  • Dependabot：自动更新GitHub操作版本
  • 一体化脚手架: manifest.json，配置流，常量，字符串，翻译
  • 试验脚手架：pytest+pytest-homeassistant自定义组件
  • MCP开发服务器：HA生命周期工具（重启、日志、状态、服务）+MQTT工具，具有自动发现功能，可添加特定于集成的工具
  • 脚本: scripts/setup （安装deps）和 scripts/develop （在本地运行HA）

快速开始

创建新集成

# Install copier (one time)
pip install copier

# Scaffold a new integration
copier copy gh:eyalmichon/ha-integration-template ./ha-my-integration

系统将提示您输入下面描述的选项。

更新现有集成

改进此模板时，将更改拉入现有集成：

cd ha-my-integration
copier update

Copier显示模板更改和本地修改之间的差异，让您像git一样合并。

模板选项参考

domain

集成域标识符。用作下的文件夹名称 custom_components/，the DOMAIN 并且在所有面向HA的标识符中。

  • 类型：string
  • 示例: my_device, smart_thermostat, solar_monitor
  • 规则：仅限小写字母、数字和下划线。必须以字母开头。

integration_name

HA UI、README、HACS列表和配置流中显示的人类可读名称。

  • 类型：string
  • 示例: My Device, Smart Thermostat, Solar Monitor

description

对集成功能的简短描述。在生成的README和HACS元数据中使用。

  • 类型：string
  • 默认: A custom Home Assistant integration
  • 示例: Monitor and control your Smart Thermostat from Home Assistant

github_user

您的GitHub用户名。用于生成URL（文档、问题跟踪器）、代码所有者和徽章链接。

  • 类型：string
  • 示例: eyalmichon
  • 生成: https://github.com/<github_user>/ha-<domain>

git_name

devcontainer中提交的Git作者名称。在项目级别配置 .git/config 通过 scripts/setup.

  • 类型：string
  • 示例: Eyal Michon

git_email

Git作者在devcontainer中提交的电子邮件。在项目级别配置 .git/config 通过 scripts/setup.

  • 类型：string
  • 示例: eyal@example.com

iot_class

集成如何连接到设备/服务。这是在 manifest.json 并在HA集成页面中显示。请参阅 HA关于IoT类的文档 了解详情。

  • 类型：选择
  • 默认: local_polling
  • 选项:
值 何时使用
local_polling 定期轮询本地设备/服务
local_push 本地设备/服务推送更新（例如通过MQTT、webhooks）
cloud_polling 定期轮询云API
cloud_push 云服务推送更新（例如通过websocket）
calculated 实体值是根据其他数据计算的，没有外部I/O
assumed_state 根据最后发送的命令假设状态（无反馈）

integration_type

这种集成会影响HA如何处理配置条目。请参阅 HA关于集成类型的文档.

  • 类型：选择
  • 默认: service
  • 选项:
值 何时使用
hub 连接到管理多个设备（如Hue、Z-Wave）的集线器/网桥
device 直接表示单个设备（例如智能插头）
service 连接到非物理设备的服务/API（例如天气、日历）

platforms

您的集成将公开的HA平台的逗号分隔列表。每个平台都成为 PLATFORMS 列入 const.py.

  • 类型：string（逗号分隔）
  • 默认: sensor
  • 示例: sensor,switch,binary_sensor
  • 可用平台:
平台 实体类型
sensor 数字/文本读数（温度、能量、计数）
binary_sensor 开/关状态（运动、门打开、连接）
switch 可切换的开/关控制
button 一键触发（重启、同步）
select 从选项列表中下拉选择
number 带最小/最大/步长的数字输入
climate 暖通空调/恒温器控制
light 灯光控制（亮度、颜色）
cover 百叶窗、车库门、百叶窗
fan 风扇速度/方向控制
lock 锁定/解锁控制
media_player 媒体播放控制
camera 相机流/快照

has_config_flow

是否包含配置流（设置>设备和服务中的基于UI的设置向导）。几乎总是 true 用于新的集成。

  • 类型：boolean
  • 默认: true

python_version

devcontainer的Python版本 pyproject.toml。应与您的目标家庭助理版本所需的版本相匹配。家庭助理2026.3+需要Python 3.14+；较旧的HA版本仍然支持Python 3.13。

  • 类型：string
  • 默认: 3.14

install_hacs

是否安装 计算机危险判定系统 （家庭助理社区商店）在开发环境中。将下载和依赖项安装添加到开发脚本中。本地开发您自己的集成时不需要，但如果您想与其他自定义集成一起测试，则很有用。

  • 类型：boolean
  • 默认: false

dev_integrations

可选的额外HA集成可包含在开发中 configuration.yaml基本配置已经包含了所有轻量级的内置集成（自动化、脚本、场景、输入助手、模板、记录器、历史记录、日志、sun等）。这些是您可以选择的更重或更专业的集成。

  • 类型：多选
  • 默认：无
选择 价值
MQTT代理（本地蚊子） mqtt
REST命令/传感器 rest
移动应用支持 mobile_app
能源仪表板 energy
媒体来源 media_source

生成的项目结构

ha-my-integration/
  .devcontainer/devcontainer.json     # Dev environment config
  .github/
    workflows/                        # CI: lint, hassfest, HACS, release, CodeQL
    dependabot.yml                    # Auto-update GH Actions
  .cursor/mcp.json                    # MCP server config
  .pre-commit-config.yaml             # Ruff hooks
  custom_components/my_device/        # Integration code
    __init__.py                       # Setup/unload entry
    config_flow.py                    # Config flow
    const.py                          # Domain + platforms
    manifest.json                     # HA manifest
    strings.json                      # UI strings
    translations/en.json              # English translations
    brand/                            # Local icon/logo for HA 2026.3+
  scripts/
    setup                             # Install deps + pre-commit
    develop                           # Run HA locally
    mcp_server/                       # Dev MCP tools
      tools/ha.py                     # HA lifecycle tools
      tools/mqtt.py                   # MQTT tools
  tests/
    conftest.py                       # Test fixtures
  pyproject.toml                      # Python config
  hacs.json                           # HACS metadata

开发此模板

当对模板本身进行更改时，您可以使用以下命令在本地进行测试，而无需提交或推送 --vcs-ref=HEAD。此操作会通知复印机使用最新提交加上任何脏的（未提交的）更改，绕过基于标记的版本解析：

# Test with defaults
copier copy --trust --vcs-ref=HEAD --defaults \
  -d domain=test_integration \
  -d integration_name="Test Integration" \
  -d git_name="Test User" \
  -d git_email="test@example.com" \
  ./path/to/ha-integration-template /tmp/test-scaffold

# Test with multiselect options via a data file (workaround for -d multiselect bug)
cat > /tmp/copier-data.yml << 'EOF'
domain: test_integration
integration_name: Test Integration
description: A test
github_user: testuser
git_name: Test User
git_email: test@example.com
iot_class: local_polling
integration_type: service
platforms: "sensor,binary_sensor"
has_config_flow: true
python_version: "3.14"
dev_integrations:
  - mqtt
  - rest
EOF

copier copy --trust --vcs-ref=HEAD --defaults \
  --data-file /tmp/copier-data.yml \
  ./path/to/ha-integration-template /tmp/test-scaffold

备注：没有 --vcs-ref=HEAD，复印机解析最新的git标签并读取 copier.yml 来自该标签——因此，在标记之前，新的问题或模板更改不会出现。这 --data-file 多选题需要这种方法，因为 -d 旗有 已知复印机故障 具有多选值。

添加集成专用MCP工具

MCP服务器自动发现工具模块。在中添加新文件 scripts/mcp_server/tools/:

# scripts/mcp_server/tools/my_device.py
from typing import Any


def register(mcp) -> None:
    @mcp.tool
    async def my_device_status() -> dict[str, Any]:
        """Check My Device status."""
        return {"status": "ok"}

它将被自动提取，无需导入或注册。

相关 MCP