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

diagnose

Use when diagnosing why a Home Assistant automation, script, device, or integration failed or misbehaved — root-cause analysis from error logs, system logs, traces, and bounded history through HA NOVA Relay. For current home status use ha-nova:health; for plain timelines use ha-nova:history.

markusleben · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add markusleben/ha-nova --skill diagnose

技能说明


name: diagnose description: Use when diagnosing why a Home Assistant automation, script, device, or integration failed or misbehaved — root-cause analysis from error logs, system logs, traces, and bounded history through HA NOVA Relay. For current home status use ha-nova:health; for plain timelines use ha-nova:history. 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 Diagnose

Scope

Root-cause a concrete failure: "why did X not run", "why did X misbehave", "what broke last night".

  • Evidence sources: automation/script traces, HA error log, system log, bounded logbook/history windows, template probes, integration diagnostics.
  • Boundary: ha-nova:health reports CURRENT home status (repairs, unavailable entities); ha-nova:history answers plain timeline questions; ha-nova:review audits config quality without a concrete incident. This skill starts from a concrete symptom.
  • The ONLY mutation in this skill is a temporary logger.set_level debug escalation (see Flow step 5) — every other fix hands off to the owning skill (ha-nova:write, ha-nova:helper, ha-nova:service-call, ha-nova:integration-setup for credential recovery).

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

File-based relay requests only:

  • ha-nova relay core --method GET --path <PATH> for REST reads (--out <result-file> for large output)
  • ha-nova relay core --method POST --path <PATH> --body-file <payload-file> for REST calls with a body (template probes, service calls)
  • ha-nova relay ws --data-file <payload-file> for WS commands
  • ha-nova trace latest <entity_id> --json / ha-nova trace list <entity_id> --json / ha-nova trace get <entity_id> <run_id> --json for run traces (positional entity, automation.<id> or script.<id>)
  • --jq-file <filter-file> for non-trivial filters

Evidence Sources

SourceCallNotes
Run tracesha-nova trace latest <entity_id> --json (also trace list <entity_id>, trace get <entity_id> <run_id>)First stop for automation/script failures: shows the exact step, condition results, and variables
System logWS {"type":"system_log/list"}PRIMARY log source: structured warnings/errors with counts and sources, works on every install type
Error logGET /api/error_log404 on HA OS/Supervised since 2025.11 (the log file moved to journald) — that is normal, not an error; stay with system_log/list. Where the file exists (Container/Core, or re-enabled), see Reading the error log
Logbook windowGET /api/logbook/<ISO-start>?end_time=<ISO-end>&entity=<entity_id>Human-readable events around the incident time
State historyGET /api/history/period/<ISO-start>?end_time=<ISO-end>&filter_entity_id=<ids>What states the involved entities actually had
Template probeha-nova relay core --method POST --path /api/template --body-file <payload-file> with {"template":"{{ ... }}"}Evaluate the exact condition/template against live state; the rendered result is the string in .data.body
Integration diagnosticsWS {"type":"diagnostics/list"}, then GET /api/diagnostics/config_entry/<entry_id> with --out <result-file>Deep integration state when an integration itself is the suspect
Device diagnosticsGET /api/diagnostics/config_entry/<entry_id>/device/<device_id> with --out <result-file>One device's slice when a single device misbehaves; resolve the (entry_id, device_id) pair via WS diagnostics/list (only entries with a device-diagnostics handler) — a device can carry several entry ids

Diagnostics redaction is integration-controlled, so downloads are potentially sensitive and NEVER hit bare stdout — save with --out, extract only relevant fields via relay jq before quoting.

Recency honesty: error_log and system_log/list only cover the time since the last Core restart. For older incidents use logbook/history windows, and say explicitly that live logs no longer reach back that far.

Reading the error log

Only where the log file exists (Container/Core installs; on HA OS/Supervised the user can restore it with ha core options --duplicate-log-file=true followed by ha core rebuild and ha core restart, since 2026.1). The upstream body is plain text, but the relay wraps it in the /core envelope — the whole log is one escaped string in .data.body, so searching the saved file line-wise does not work.

  1. ha-nova relay core --method GET --path /api/error_log --out <envelope-file>

  2. Filter the lines you need with a raw jq read (never dump the whole log):

    ha-nova relay jq -r --file <envelope-file> --jq-file <filter-file>
    

    with <filter-file>:

    .data.body | split("\n")[] | select(test("<entity_or_integration>"; "i"))
    

    -r is required for raw text output — relay core --jq does not support it, so the filtering happens in this second step. Substitute only an entity_id, domain, or integration slug — never a friendly name, which can contain (, ) or | and would break the filter. Even a slug is not literal: the . in sensor.kitchen is a regex wildcard, so escape it (sensor\\.kitchen) or the filter also matches sensor_kitchen and reports unrelated lines as evidence.

    The identifier is the ONLY selector — never OR a severity into it. test("sensor\\.kitchen|ERROR") matches every error line in the log, from every unrelated integration, and each one then looks like evidence for this incident. To narrow by severity, AND it: select(test("sensor\\.kitchen"; "i") and test("ERROR|WARNING"; "i")). And a log with no matching line is a finding in itself — say the log holds nothing about this entity, rather than widening the filter un

阅读完整来源 ↗