跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

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, or label
  • resolving likely targets before writes

Read-only behavior.

  • No POST, PUT, PATCH, or DELETE relay 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 --jq for 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 or ha-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 name
  • domain: exact domain filter
  • area: resolve the area, then use search/related as the primary shortlist source; use ai only as optional extra evidence when present
  • label: escalate to the full registry only when label evidence is required; config/entity_registry/list returns the entity array directly in .data
  • helper + 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
阅读完整来源 ↗