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

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_class REQUIRED) — 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_state etc.) → recorder/clear_statistics is 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 and has_sum, and — mandatory — the energy/get_prefs cross-check: whether any ID appears anywhere in that JSON or in energy/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 the confirm: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; 5minute only if <10 days old), derive the corrected change from neighboring buckets or user input, then recorder/adjust_sum_statistics with adjustment = corrected − original at the bucket's start. Reversible via the inverse call — offer that rollback. Check energy/info → cost_sensors for 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 than keep_days exists and will actually go. Long-term statistics are NEVER purged — say so. repack: true only with an explicit warning: rebuilds the database, blocks recording, needs free disk. apply_filter: true additionally deletes data the recorder's include/exclude filters exclude — and for those entities/event types HA purges up to the CURRENT time, not the keep_days cutoff, so their recent history is erased too. The preview must say exactly that; when in doubt, offer the plain purge without apply_filter. The call is fire-and-forget — verify recorder/info (backlog normal, recording: true) plus a pre-cutoff history read returning empty (allow minutes). Typed confirmation code.
  • recorder.purge_entities: default keep_days: 0 = ALL state history for the match. Expand domains/entity_globs selectors to the concrete matched entity list BEFORE the prev
阅读完整来源 ↗