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

history

Use when reading Home Assistant entity history, logbook timelines, or long-term statistics through HA NOVA Relay.

markusleben · 已有静态检查记录

安装与使用

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

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

技能说明


name: history description: Use when reading Home Assistant entity history, logbook timelines, or long-term statistics through HA NOVA Relay. 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 History

Scope

Read-only timeline work:

  • entity state history over a bounded time range
  • logbook queries over a bounded time range
  • long-term statistics over a bounded time range
  • concise "what happened?" summaries

Not in scope:

  • live subscriptions
  • system logs
  • trace debugging
  • calendar queries (use ha-nova:calendar)
  • giant raw exports

Use ha-nova:diagnose for traces (it owns trace analysis; ha-nova:read only surfaces raw trace data when the user explicitly asks for it with no failure question attached), ha-nova:calendar for calendars, and ha-nova:fallback for subscriptions.

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:

  • ha-nova relay core --method GET --path <history-path> --out <result-file>
  • ha-nova relay core --method GET --path <logbook-path> --out <result-file>
  • ha-nova relay ws --data-file <payload-file> --out <result-file>
  • ha-nova relay jq --file <result-file> --jq-file <filter-file>

For ha-nova relay jq, the filter is positional unless --jq-file is used. Do not invent a --jq flag.

Canonical paths:

  • /api/history/period/<start>?filter_entity_id=<entity_id>&end_time=<end>
  • /api/logbook/<start>?entity=<entity_id>&end_time=<end> — entity takes a comma-separated LIST for several entities (verified on 2026.8.0: the endpoint splits on commas and ignores unknown ids), and omitting it entirely returns the whole home for that window. filter_entity_id belongs to the HISTORY endpoint; using it here silently returns everything.
  • recorder/statistics_during_period

Prefer minimal_response and no_attributes on large history queries when the task only needs state transitions. Envelope parsing follows skills/ha-nova/relay-api.md → Standard Envelope; relay-core response shape here stays under .data.body.

  • history series: .data.body[0]
  • logbook entries: .data.body
  • do not probe .[0] or .[0][0] against the relay envelope Recorder statistics response stays under WS .data.

Statistics semantics (recorder/statistics_during_period) — check which keys the response actually carries before summarizing:

  • Measurement stats (temperature, humidity) carry mean/min/max. Metered total_increasing stats (energy, water, gas) are consumption: request change in the types list and SUM the per-bucket change values over the window (the pattern skills/energy/energy-reference.md uses) — never an average, and never last sum − first sum, which drops the first bucket's consumption and reads 0 for a single bucket.
  • Long-term statistics carry their own unit, which can differ from the entity's current unit after a unit change (the exact trap ha-nova:maintenance repairs) — report the unit from the statistics metadata, and flag a mismatch instead of mixing units.
  • statistic_id is not always an entity_id: external statistics use domain:object_id (colon) and have no entity — resolve via recorder/list_statistic_ids when unsure.
  • Daily/monthly buckets follow the HA server's local timezone including DST shifts — a "day" is not a fixed 24 h; name the bucket timezone when precision matters.
  • The queried window is what was REQUESTED, not what was observed: report the actual first-to-last sample span and material gaps alongside the requested window, and never phrase a result as covering "the last N days" when the evidence spans less (skills/ha-nova/write-safety.md → Time-Window Evidence — applies to raw history summaries too). For recorder/statistics_during_period the response carries aggregated period BUCKETS, not sample timestamps: report the first-to-last bucket span and NAME it as bucket coverage — sample density claims come only from raw state history, never from LTS buckets.

Flow

  1. Resolve the exact entity target when needed.
  2. Set a bounded window.
    • if the user gave a range, use it
    • otherwise default to the last 24 hours for history/logbook
    • otherwise default to the last 30 days for statistics/trend questions
    • if the requested window is too broad, narrow it before querying
  3. Choose the source:
    • history for state transitions and values
    • logbook for human-readable events and automation activity
    • statistics for multi-day trends, comparisons, or long-term summaries
  4. Execute the read into <result-file>.
  5. Summarize first:
    • key transitions
    • first/last seen values
    • notable gaps or bursts
    • key periods or trend direction for statistics
    • if the raw state series can contain unknown or unavailable, do not run numeric min/max across the whole series unless you first filter to numeric states safely
    • prefer simple reductions that do not depend on fragile timestamp parsing unless the user explicitly asked for gap analysis
    • for the default summary, do not build complex jq expressions just to recover min/max event timestamps; numeric range plus a few direct sample timestamps is enough
  6. Only show raw excerpts if the user explicitly asks.

Output Format

Apply skills/ha-nova/output-rules.md to all user-facing output.

  • Target
  • Window
  • Summary
  • Key events, Key transitions, or Key periods
  • Next step

These slots render the Report shape (output-rules.md). Keep default output compact. Raw payload dumps are opt-in only.

Safety

  • Read-only skill: never issue mutating relay or service calls.

  • For write intent, hand off to the owning skill; unfamiliar writes go through ha-nova:fallback first.

  • Read-only skill. No writes.

  • No guessed entity ids

阅读完整来源 ↗