assist
Use when working with Home Assistant's own built-in voice assistant (Assist) — testing what it understands, inspecting, editing, or creating Assist pipelines, managing which entities are exposed to voice, listing TTS/STT/wake-word engines, and teaching Assist custom sentences — through HA NOVA Relay. Not for Alexa or Google Assistant — setting those up is `ha-nova:integration-setup` (or `ha-nova:yaml-config` for a manual cloud config), and one that STOPPED working is a concrete failure for `ha-nova:diagnose`.
markusleben · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add markusleben/ha-nova --skill assist技能说明
name: assist
description: Use when working with Home Assistant's own built-in voice assistant (Assist) — testing what it understands, inspecting, editing, or creating Assist pipelines, managing which entities are exposed to voice, listing TTS/STT/wake-word engines, and teaching Assist custom sentences — through HA NOVA Relay. Not for Alexa or Google Assistant — setting those up is ha-nova:integration-setup (or ha-nova:yaml-config for a manual cloud config), and one that STOPPED working is a concrete failure for ha-nova:diagnose.
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 Assist
Scope
Home Assistant's built-in voice assistant (Assist):
- test what Assist understands — send an utterance and see the real answer, without speaking
- inspect, create, and edit Assist pipelines (which STT, conversation agent, TTS a pipeline uses) and change the preferred one
- teach Assist custom sentences (see Custom Sentences below)
- manage which entities are exposed to voice, and their aliases
- list available TTS, STT, conversation, and wake-word engines
Not in scope: speaking through a speaker (ha-nova:media for TTS announcements), microphone/satellite hardware setup, or the third-party assistants (Alexa/Google) — setup goes to ha-nova:integration-setup (or ha-nova:yaml-config for a manual cloud config), and a failure ("Alexa stopped working") to ha-nova:diagnose like any other integration incident.
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
ha-nova relay ws --data-file <payload-file>for WS commandsha-nova relay core --method POST --path /api/conversation/process --body-file <payload-file>to test an utterance--out <result-file>for large listings
Flow
- Testing an utterance (the most useful thing here):
POST /api/conversation/processwith{"text":"turn on the kitchen light","language":"en"}(add"agent_id"to target a specific agent). The response says what Assist understood and what it did.- This ACTUALLY EXECUTES the command. "Turn on the light" turns the light on. Treat it as a service call: preview it, confirm it, and never fire a test utterance that changes something without asking.
- A read-only utterance ("what is the temperature in the kitchen") is safe to run directly.
"conversation_id"continues a previous exchange; omit it for a fresh one.
- Pipelines: WS
assist_pipeline/pipeline/listshows every pipeline pluspreferred_pipeline. Each carriesstt_engine,conversation_engine,tts_engine, and language settings.- change the preferred one: WS
assist_pipeline/pipeline/set_preferredwithpipeline_id - create: WS
assist_pipeline/pipeline/create. The named default is clone-preferred-with-a-different-engine: read the preferred pipeline from the list, carry its settings fields over, add the REQUIRED newname, and swap only the engine(s) the user asked for (the local-LLM move: same STT/TTS, differentconversation_engine). Resolve the new engine id from step 4's inventories — never invent one. Preview every field, labeling cloned vs changed, confirm, then create; verify by re-reading the pipeline list for the new pipeline with the requested settings. Creating never changes the preferred pipeline — offerset_preferredseparately - update: WS
assist_pipeline/pipeline/update— read the pipeline first, then send ALL its settings fields with your change, addressed bypipeline_id(the list'sidvalue). Never send it asid— that slot is the WS request id. A partial payload drops settings. - delete: WS
assist_pipeline/pipeline/delete— typed confirmation code; a pipeline in use by a satellite breaks it
- change the preferred one: WS
- Exposed entities (what voice can even see): WS
homeassistant/expose_entity/list; expose or hide with WShomeassistant/expose_entity(assistants: ["conversation"],entity_ids,should_expose). Aliases live in the entity registry (ha-nova:organizeowns those).- Exposing an entity gives voice control over it — preview the list before changing it.
- Risk-weight the preview: exposing a
lock,alarm_control_panel, or a cover with a garage/gate/doordevice_classmeans anyone within earshot can actuate physical access by voice — flag these entities explicitly as high-consequence before confirming.
- Engines: WS
tts/engine/list,stt/engine/list,conversation/agent/list,wake_word/info. Read-only inventories; use them to explain what a pipeline can be built from. - Verify pipeline changes by re-reading the pipeline list, and exposure changes by re-reading
expose_entity/list— never report success from the command response alone. After a pipeline or exposure change made to FIX an utterance, offer to re-run that exact utterance as the proof (with the standing warning that a test utterance executes what it understands).
Custom Sentences
Teach Assist a phrase it does not understand out of the box. This skill owns the workflow; the file paths, payload mechanics, and search query live in skills/fallback/relay-ready.md → Assist Custom Sentences — read that section first, do not duplicate it here.
- Opt-in gate: sentence files need the relay's opt-in file access (
ha-nova:yaml-config→ Bootstrap explains enabling it). Without it, stop and say so. - Write the sentence file (and, only when the intent is new, the
intent_script:block inconfiguration.yaml) per the fallback section's mechanics —backup: true, read the whole file before replacing it. - Validate BEFORE any reload: when
configuration.yamlchanged,POST /api/config/core/check_configFIRST. Oninvalid, restore that file's.bakimmediately and do not reload. - Reload the right thing: `con