ha-config-flow
Work on the Home Assistant config flow of this custom integration — the setup UI, options flow, reauthentication, reconfigure, discovery (zeroconf, dhcp, ssdp, bluetooth, usb, mqtt, homekit), subentries, unique IDs, and config entry version migration. Use when asked to "add a config option", "add a setting", "ask the user for X during setup", "add an options flow", "support reauth", "add discovery", "make the host configurable", "migrate the config entry", or when editing config_flow_handler/, its schemas/ and validators/, or manifest discovery matchers. Covers reserved step names, acceptable unique IDs, abort reasons, validation, and the migration contract. SYMPTOMS — load this if you are about to: use a host or IP as the unique ID; create a config entry without validating the connection; store a credential in `entry.options`; read `entry.data[key]` for a key old entries will not have; or change entry data without bumping VERSION/MINOR_VERSION.
- License 许可
- MIT
- 所属仓库
- amg0/ha_ksenia
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ha-config-flow
- description
- Work on the Home Assistant config flow of this custom integration — the setup UI, options flow, reauthentication, reconfigure, discovery (zeroconf, dhcp, ssdp, bluetooth, usb, mqtt, homekit), subentries, unique IDs, and config entry version migration. Use when asked to "add a config option", "add a setting", "ask the user for X during setup", "add an options flow", "support reauth", "add discovery", "make the host configurable", "migrate the config entry", or when editing config_flow_handler/, its schemas/ and validators/, or manifest discovery matchers. Covers reserved step names, acceptable unique IDs, abort reasons, validation, and the migration contract. SYMPTOMS — load this if you are about to: use a host or IP as the unique ID; create a config entry without validating the connection; store a credential in `entry.options`; read `entry.data[key]` for a key old entries will not have; or change entry data without bumping VERSION/MINOR_VERSION.
02 资源文件 4
- 参考文档references/discovery-matchers.md4.0 KB
- 参考文档references/flow-types.md6.2 KB
- 参考文档references/migration.md1.6 KB
- 参考文档references/oauth2.md5.7 KB
03 SKILL.md 正文
Work on the config flow
The config flow is the only supported way to configure a device or service integration (ADR-0010). Everything the user
can change lives here, and mistakes here are expensive: unique_id and the shape of entry.data are effectively
permanent.
Read blueprint.config_flow.instructions.md
first. It is the authoritative rule set: data-vs-options, reserved step names, acceptable unique IDs and their
normalisation, schema hygiene, title placeholders, and the migration contract. Copilot injects it automatically when
you edit a config flow file; other agents must open it. This skill is the order of operations and the decisions; the
MUST/NEVER list for each individual flow is in the first reference below.
| File | When to read |
|---|---|
references/flow-types.md |
Implementing one flow — user, discovery, reauth, reconfigure, options, subentry |
references/discovery-matchers.md |
Writing a manifest.json discovery matcher, or using a discovery helper API |
references/oauth2.md |
The service authenticates with OAuth2 rather than an API key or a password |
references/migration.md |
A config entry migration can fail, and the user needs a way to retry it |
Package layout
Where each piece goes. The example ships __init__.py, config_flow.py, schemas/config.py and
validators/credentials.py; create the rest when something needs them, rather than leaving empty scaffolding behind.
config_flow_handler/
├── __init__.py # exports
├── config_flow.py # user, reauth, reauth_confirm, reconfigure, discovery steps
├── options_flow.py # post-setup options, only when there is something to tune
├── handler.py # logic shared between the flows above
├── subentry_flow.py # multi-device / multi-account subentries
├── schemas/
│ ├── config.py # probatio schemas for setup steps
│ └── options.py # probatio schemas for the options flow
└── validators/
├── credentials.py # "can we actually talk to it" checks
└── sanitizers.py # input normalisation (strip, lowercase host, …)
The top-level config_flow.py is a thin shim Home Assistant discovers — leave it alone.
Adding a config option
- Decide data or options using the table in the instructions file. This is the one irreversible choice here.
A polling interval is neither — it is not a field at all. In an integration without options yet, the first real
option is when
options_flow.pyandschemas/options.pyget created. - Add the
CONF_*key toconst.py. - Add the field to
schemas/config.pyorschemas/options.pywith a selector and a default. - Consume it: coordinator reads
entry.options, client readsentry.data. - Add the
dataanddata_descriptiontranslation keys (ha-translations). - Handle existing entries that predate the key — a default at read time, or a
MINOR_VERSIONbump plus migration. This is the step that gets forgotten and breaks upgrades.
Adding discovery
-
Add the matcher to
manifest.json— readreferences/discovery-matchers.mdfirst, because each protocol has a rule that fails silently when you guess (lowercase-only zeroconf properties, DHCP MACs arriving without separators, VID/PID pairs shared by hundreds of devices):"zeroconf": [{ "type": "_myservice._tcp.local.", "name": "blueprint*" }] -
Implement the matching
async_step_<method>()following the discovery MUST/NEVER list inreferences/flow-types.md. -
Decide what the discovery payload gives you as a stable unique ID. If it offers nothing stable, stop and discuss it — do not fall back to the IP address.
-
Confirm the flow end-to-end in the UI: the card shows a useful name, a second discovery of the same device aborts, and a device that changed IP updates the existing entry rather than creating a second one.
Config entry migration
Bump MINOR_VERSION for additive changes, VERSION for restructuring. Read
ha-breaking-changes first — changing entry data affects every existing install.
Implement async_migrate_entry() in custom_components/<domain>/__init__.py:
async def async_migrate_entry(hass: HomeAssistant, entry: {ClassPrefix}ConfigEntry) -> bool:
"""Migrate an old config entry."""
if entry.version == 1 and entry.minor_version < 2:
data = {**entry.data, CONF_PORT: DEFAULT_PORT}
hass.config_entries.async_update_entry(entry, data=data, minor_version=2)
return True
No downgrade branch and no return False — the contract is under
Version and Migration; a migration
that can fail needs references/migration.md.
Migrations must be idempotent and must never delete a key they do not understand. Cover every migration with a test
(ha-testing).
Validate
script/lint && script/type-check
script/hassfest # cross-checks every step/error/abort key against translations
script/test
Then restart Home Assistant and walk every flow you touched — add, reconfigure, options, and, by invalidating the credential, reauth. hassfest proves the translation keys exist; only walking the flow proves it is usable. A flow that passes CI and dead-ends on the second step is the normal failure here.
Walk it from the terminal first — it is faster, it is repeatable, and it shows the serialised schema Home Assistant actually built, which is where defaults and selectors go wrong:
script/ha flow start # or --reconfigure
script/ha flow step <flow_id> host=192.0.2.10 username=admin password=secret
script/ha flow options # then step through it the same way
script/ha entries # the entry exists and loaded
Each step prints its step_id, any errors, and every field with its type and default. Full reference:
references/ha-cli.md.
Two things only the browser can confirm, so finish there: that the translated labels and data_description hints read
correctly, and that the form renders the way the selectors promise.
Do not
- Do not do blocking I/O or long retries inside a flow step; validate with a short timeout.
- Do not call the flow done before walking it end to end.
- Do not give an optional free-text field
default=None— probatio injects that default when the field is left empty and the selector then rejects it, making the form unsubmittable. Carry the current value indescription={"suggested_value": ...}instead.
04 同仓库更多 Skills
issues
Triage/fix the GitHub issue backlog via branch + PR, with auto-merge on green CI for this session.
ha-translations
Add or fix user-facing strings for this Home Assistant custom integration — translations/en.json and other languages, icons.json, entity names and states, config flow labels and errors, service action descriptions, exception messages, and repair issue text. Use when asked to "update translations", "add a translation key", "translate", "fix the entity name", "add strings for the new sensor/action/option", "add icons", or when hassfest reports a missing or unused translation key. Covers the key structure, which keys each feature needs, placeholders, the icons.json contract, and the project's strict rule about only touching en.json. SYMPTOMS — load this if you are about to: write user-facing English into Python; edit a language file other than `en.json`; add an entity without its `entity.<platform>.<key>.name` key; skip `data_description` on a config flow field; or set `icon=` instead of using `icons.json`.
ha-testing
Write, fix, or extend automated tests for this Home Assistant custom integration using pytest and pytest-homeassistant-custom-component. Use when asked to "add tests", "write a test", "the tests fail", "improve coverage", "add a regression test", "test the config flow", "update snapshots", or when a behavioural change needs verification before it can be called done. Covers the tests/ layout, the conftest.py fixtures this project needs, mocking the API client, config flow and entity test patterns, registry assertions, syrupy snapshots, freezing time, and the script/test commands. SYMPTOMS — load this if you are about to: instantiate an entity class directly instead of asserting on `hass.states`; write a test without `enable_custom_integrations`; use `time.sleep` instead of `async_fire_time_changed`; silence a DeprecationWarning to make the suite pass; or commit a snapshot you have not read.
ha-service-action
Add, change, or remove a Home Assistant service action (also called a "service" or "action") in this custom integration. Use when asked to "add a service", "add an action", "expose X as a service call", "add a service that returns data", "make this callable from an automation", or when editing services.yaml, the service_actions/ package, service schemas, service response data, or the async_setup() registration. Covers the services.yaml contract, probatio schemas, selectors, entity/device targeting, response data, translated error messages, and the Bronze quality-scale rule that actions must be registered in async_setup(). SYMPTOMS — load this if you are about to: register an action in `async_setup_entry()`; add a `services.yaml` field without a selector; add an `entity_id` field where `target:` belongs; raise a plain English `HomeAssistantError`; or swallow an action failure into a log line.
ha-release
Cut a release of this Home Assistant custom integration, or prepare the commits that feed it. Use when asked to "release", "cut a version", "bump the version", "prepare release notes", "what will the next version be", "write a commit message", "why didn't release-please pick this up", or when reviewing whether a change is user-facing. Covers the Conventional Commits rules commitlint enforces here, how release-please derives the version and changelog, the pre-1.0 bump rules, script/version and script/release-notes, skipping a commit from the notes, and the commit rules this project enforces for agents. SYMPTOMS — load this if you are about to: commit without an explicit request; offer to `git push`; label a user-facing fix as `chore` (chore, like every hidden type, never reaches the changelog and never triggers a release); write a commit subject over 100 characters or in sentence case; or edit the version in `manifest.json` by hand.
ha-quality-review
Perform a structured quality review of this Home Assistant custom integration, either as a full audit or scoped to a diff. Use when asked to "review the integration", "audit the code", "check quality scale", "are we bronze/silver/gold", "is this ready to release", "review my changes", "what's missing before publishing", or before opening a pull request that touches integration code. Covers running the automated gates first, then auditing architecture, the Integration Quality Scale rules, error handling, security, performance, user experience, and documentation — and reporting findings ranked by severity with concrete fixes. SYMPTOMS — load this if you are about to: report a review that only restates linter output; claim real-device testing that did not happen; give a finding without a file path and a fix; or judge quality without running `script/hassfest` and the test suite first.