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//ha-

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
• 选项:

integration_type

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

• 类型：选择
• 默认: service
• 选项:

platforms

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

• 类型：string（逗号分隔）
• 默认: sensor
• 示例: sensor,switch,binary_sensor
• 可用平台:

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等）。这些是您可以选择的更重或更专业的集成。

• 类型：多选
• 默认：无

生成的项目结构

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  **备注**：没有 `--vcs-ref=HEAD`，复印机解析最新的git标签并读取 `copier.yml` 来自该标签——因此，在标记之前，新的问题或模板更改不会出现。这 `--data-file` 多选题需要这种方法，因为 `-d` 旗有 [已知复印机故障](https://github.com/copier-org/copier/issues/1594) 具有多选值。

## 添加集成专用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"}

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