entity-discovery
Use when searching or resolving Home Assistant entities by name, room, or domain through HA NOVA Relay, and live state snapshots across a domain — what is open, on, running, locked, who is home.
markusleben · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add markusleben/ha-nova --skill entity-discovery技能说明
name: entity-discovery description: Use when searching or resolving Home Assistant entities by name, room, or domain through HA NOVA Relay, and live state snapshots across a domain — what is open, on, running, locked, who is home. license: MIT compatibility: Requires the ha-nova CLI (run 'ha-nova setup' first) and the HA NOVA Relay in Home Assistant (App, or standalone container on Container/Core).
HA NOVA Entity Discovery
Scope
Use for:
- listing entities by domain
- searching entities by user phrase
- bulk inventory by
prefix,domain,area, orlabel - resolving likely targets before writes
Read-only behavior.
- No
POST,PUT,PATCH, orDELETErelay writes. - If the user moves from discovery to mutation, stop after resolution and hand off to the write-capable skill.
Bootstrap (once per session)
Read and follow ../ha-nova/session-bootstrap.md.
Verify relay CLI: ha-nova relay health
If this fails: ha-nova setup
Relay Contract
Use file-based relay requests by default:
ha-nova relay ws --data-file <payload-file>ha-nova relay core --method <METHOD> --path <PATH> --body-file <payload-file>when a body is needed--jq-file <filter-file>for non-trivial filters; keep inline--jqfor short selectors only--out <result-file>for large reads- On Windows PowerShell, never chain commands with
&&or||; run separate shell commands instead. - Never call external
jq; use relay-native filters orha-nova relay jq --file <result-file> ....
Flow
Step 1: Search entity registry
Entity registry uses compact abbreviated keys: ei=entity_id, en=name, ai=area_id.
Search both entity_id and name. Use short keyword stems to handle spelling variants. Cap display at 20 rows through the canonical envelope below — never a bare slice.
For bulk selectors, follow skills/ha-nova/bulk-patterns.md.
prefix: case-insensitive prefix match on the entity_id suffix and display namedomain: exact domain filterarea: resolve the area, then usesearch/relatedas the primary shortlist source; useaionly as optional extra evidence when presentlabel: escalate to the full registry only when label evidence is required;config/entity_registry/listreturns the entity array directly in.datahelper+area: not a first-class bulk selector contract; do not imply room-owned helper discovery unless live helper-area semantics are explicitly defined
For domain counts or domain shortlists:
- count only the requested domain unless the user explicitly asks for heuristics or related domains
- use
--jq-file <filter-file>for the count filter - if you need a follow-up count from a saved file, use
ha-nova relay jq --file <result-file> length
Create <payload-file> with {"type":"config/entity_registry/list_for_display"}, then run:
ha-nova relay ws --data-file <payload-file> --jq-file <filter-file>
Write <filter-file> by copying the canonical skills/ha-nova/discovery-filter.jq
and replacing KEYWORD with the pattern; if the canonical file is unavailable
(flat-copy installs), recreate it with exactly:
[.data.entities[] | select((.ei + " " + (.en // "")) | test("KEYWORD";"i")) | {entity_id: .ei, name: .en, area_id: .ai}]
| {total: length, shown: (.[0:20] | length), omitted: ([length - 20, 0] | max), truncated: (length > 20), matches: .[0:20]}
It returns {total, shown, omitted, truncated, matches} — the 20-row cap
applies to matches only; the counts are exact.
This generic test("KEYWORD";"i") filter is for free-text search, not explicit prefix matching.
For an explicit prefix selector, match the suffix and display name with startswith(...), not loose substring search.
If the compact search does not resolve a suitable target — no results, or only matches the user rejects or that plainly are not what they meant — escalate ONCE to the full registry (config/entity_registry/list) and match against aliases[] too — list_for_display does not carry them, and an alias is exactly where a household keeps the name it actually says (a household's own word for light.floor_lamp_living). Only then try synonyms, alternative terms, or shorter keyword stems. Use OR for multiple variants: test("kw1|kw2|kw3";"i"). When a resolved entity had no matching alias and the user's word was clearly their habitual name, offer once to store it as an alias via ha-nova:organize.
Diacritics: test(...;"i") folds case, not accents — a name with é/ü/ö does not match its plain-ASCII spelling. Whenever the keyword or likely entity names carry accents or umlauts (common in non-English homes), put the transliterated variants into the OR-pattern: test("café|cafe";"i"), and for umlauts include both the ue/oe/ae and bare-vowel forms.
If too many: narrow with AND: test("kw1";"i") and test("kw2";"i").
Fail closed on truncation: while truncated is true the result proves neither absence nor uniqueness — the target may sit past the cap. Narrow automatically (area, domain, exact identifier, aliases, extra AND terms) until truncated is false before concluding either; report total/shown/omitted with the rows.
Never dump entire domains without a user-intent keyword, and never show an unfiltered full-registry dump.
When the task is multi-target inventory:
- save the shortlist with
--out <result-file> - do not trim to 20 inside the initial selector filter
- dedupe first, then sort deterministically, then compute the exact matched count, then apply the 20-row display cap
- keep ordering deterministic: domain, then entity_id
- return the exact matched count separately from the displayed rows
Step 2: Get state or config
# State
ha-nova relay core --method GET --path /api/states/{entity_id}
# Automation/script config — always resolve unique_id first (see relay-api.md → ID Types)
ha-nova relay ws --data-file <payload-file> --out <registry-file>
ha-nova relay jq -r --f
阅读完整来源 ↗