maintenance
Use when repairing Home Assistant recorder statistics (orphaned statistics, unit mismatches, sum spikes), purging recorder history, cleaning up dead entity-registry entries, or answering how long an entity has been unavailable or dead — through HA NOVA Relay. For what is unavailable right now, use ha-nova:health.
markusleben · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add markusleben/ha-nova --skill maintenance技能说明
name: maintenance description: Use when repairing Home Assistant recorder statistics (orphaned statistics, unit mismatches, sum spikes), purging recorder history, cleaning up dead entity-registry entries, or answering how long an entity has been unavailable or dead — through HA NOVA Relay. For what is unavailable right now, use ha-nova:health. 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 Maintenance
Scope
Read (always allowed):
- statistics issue triage (
recorder/validate_statistics, grouped by issue type) - recorder health (
recorder/info:backlog,recording,migration_in_progress) - long-unavailable entity report with confidence-labeled timestamps
- orphaned registry-entry candidates (report first, remove only via the gated flow)
Gated writes:
- clear orphaned statistics, relabel statistic units, repair sum spikes
- recorder purge (
recorder.purge,recorder.purge_entities) - remove dead entity-registry entries
Not in scope:
- energy source/device config (
ha-nova:energy) - repairs/status overview and current unavailability summaries (
ha-nova:health); the long-unavailable report here exists to qualify cleanup candidates, not to answer "is everything OK" - backups (
ha-nova:backup), updates (ha-nova:updates) - device deletion — no generic API; report and route to the owning integration/UI
- MQTT ghost entities recreated by a retained discovery message — the broker-side cleanup is
ha-nova:mqtt(retained-discovery cleanup); registry removal here only sticks after that topic is cleared
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 requests: ha-nova relay ws --data-file <payload-file>; --out <result-file> for large responses. WS body: .data; REST body: .data.body (skills/ha-nova/relay-api.md → Standard Envelope).
Payloads, issue matrix, and gate checklists: skills/maintenance/maintenance-reference.md — read it before any write.
Flow
Statistics triage
WS {"type":"recorder/validate_statistics"} → group results by issue type and report counts per group with examples — never dump hundreds of IDs. Map each type to its default remediation from the reference matrix (relabel vs. clear vs. report-only). Hundreds of no_state orphans are normal on older installs.
Statistics repair (gated)
Grouped clears and per-config-entry registry removals are batch operations per skills/ha-nova/batch-safety.md — one issue group or config entry per manifest, confirm:batch-... code format, completion ledger; every safety gate below stays unchanged. A registry removal may instead ride a cross-family destructive cleanup manifest (skills/ha-nova/grouped-change-set.md) with every gate below intact.
units_changed→ default is the non-destructive relabel (recorder/update_statistics_metadata,unit_classREQUIRED) — only after confirming the values are the same quantity merely mislabeled; if the sensor changed what it measures, relabel corrupts data — then clear or keep.- Orphan cleanup (
no_stateetc.) →recorder/clear_statisticsis IRREVERSIBLE. Preview per group: the FULL ID list (write long lists to a file the user can open — a capped sample never authorizes the uncapped set), each ID's data span andhas_sum, and — mandatory — theenergy/get_prefscross-check: whether any ID appears anywhere in that JSON or inenergy/info→cost_sensors(warn loudly — clearing erases its energy history), plus a scan of storage dashboards for the IDs (YAML dashboards stay a stated caveat). Manifest-bound typed confirmation in theconfirm:batch-...format (skills/ha-nova/batch-safety.md) — it binds to one issue group and the manifest's full enumerated ID set; a group above the batch cap splits into multiple manifests over disjoint subsets of that group, each with its own preview and code; never one confirmation for multiple groups. Execute in one call, but verify per ID by re-running validate; a WS timeout after ~10 s is NOT failure — the job finishes in the background, re-read instead of retrying. - Sum spike → confirm the jump is spurious (glitch, meter swap) and not real usage — when unsure, ask. Locate the bad bucket via
statistics_during_period(hourly;5minuteonly if <10 days old), derive the correctedchangefrom neighboring buckets or user input, thenrecorder/adjust_sum_statisticswithadjustment = corrected − originalat the bucket's start. Reversible via the inverse call — offer that rollback. Checkenergy/info→cost_sensorsfor a linked cost statistic; verify each of the pair before offering the paired fix. Verify by re-reading the bucket.
Recorder purge (gated)
recorder.purge(service): preview keep_days + deletions (states/events/short-term statistics). Quantify the impact first: read a small bounded pre-cutoff history sample so the preview can state that data older thankeep_daysexists and will actually go. Long-term statistics are NEVER purged — say so.repack: trueonly with an explicit warning: rebuilds the database, blocks recording, needs free disk.apply_filter: trueadditionally deletes data the recorder's include/exclude filters exclude — and for those entities/event types HA purges up to the CURRENT time, not thekeep_dayscutoff, so their recent history is erased too. The preview must say exactly that; when in doubt, offer the plain purge withoutapply_filter. The call is fire-and-forget — verifyrecorder/info(backlognormal,recording: true) plus a pre-cutoff history read returning empty (allow minutes). Typed confirmation code.recorder.purge_entities: defaultkeep_days: 0= ALL state history for the match. Expanddomains/entity_globsselectors to the concrete matched entity list BEFORE the prev