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

calendar

Use when listing, reading, creating, updating, or deleting Home Assistant calendar events through HA NOVA Relay.

markusleben · 已有静态检查记录

安装与使用

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

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

技能说明


name: calendar description: Use when listing, reading, creating, updating, or deleting Home Assistant calendar events 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 Calendar

Scope

Calendar event work:

  • list calendar entities
  • read events for one calendar over a bounded window
  • summarize upcoming events across selected calendars
  • create, update, or delete one event

Not in scope:

  • calendar dashboard edits
  • automation writes that use calendar triggers
  • calendar sharing, permissions, or provider-account settings

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 REST reads, one create service, and feature-gated WebSocket writes:

  • ha-nova relay core --method GET --path /api/calendars --out <result-file>
  • ha-nova relay core --method GET --path /api/states/<calendar_entity_id> --out <result-file>
  • ha-nova relay core --method GET --path <calendar-events-path> --out <result-file>
  • ha-nova relay core --method POST --path /api/services/calendar/create_event --body-file <payload-file> --out <result-file>
  • ha-nova relay ws --data-file <payload-file> --out <result-file> for calendar/event/create (recurring creates), calendar/event/update, and calendar/event/delete
  • ha-nova relay jq --file <result-file> --jq-file <filter-file>

<calendar-events-path> is: /api/calendars/<calendar_entity_id>?start=<timestamp>&end=<timestamp>

Relay-core response body is under .data.body (envelope contract: skills/ha-nova/relay-api.md → Standard Envelope).

Flow

  1. List calendars with /api/calendars.
  2. Resolve the requested calendar by exact entity_id or exact/clear name match.
  3. If multiple calendars match, ask one blocking question.
  4. Set a bounded event window:
    • if the user gave start/end, use them
    • otherwise default to now through the next 7 days
    • if the user asks for an unbounded or very broad range, narrow it before querying
  5. Query events with /api/calendars/<entity_id>?start=<start>&end=<end>.
  6. Summarize read results:
    • title/summary
    • start and end
    • all-day vs timed; all-day events carry date-only values with an EXCLUSIVE end — a one-day event on the 14th returns end = the 15th; report it as "on the 14th", never as "ends the 15th"
    • timed events: render times in the user's local timezone, and say which timezone applies when the returned offset differs from it
    • recurring events arrive pre-expanded as individual instances within the window — count and report them as such, not as one series
    • location only when useful
    • omit private descriptions unless the user explicitly asks

Create, update, or delete

  1. Resolve one exact calendar and read /api/states/<entity_id>. Gate create on supported_features & 1, delete on & 2, and update on & 4; stop when the required bit is absent.
  2. Read a bounded event window covering the target. Update/delete require an exact event with uid; use (uid, recurrence_id) as the instance identity. If several events match the user's description, ask one blocking question. Never guess.
  3. Normalize event fields:
    • timed events use start_date_time/end_date_time for create and dtstart/dtend inside the WS event object; both values use the Home Assistant timezone and end must be after start
    • all-day events use start_date/end_date for REST create and date-only dtstart/dtend in the WS event (recurring create, update); end is exclusive
    • create requires summary; optional description and location are included only when set
    • a recurring create takes an RFC 5545 rrule string and goes through WS calendar/event/create (the REST service has no recurrence field); non-recurring creates keep the REST service
    • update is a full event replacement: merge requested changes into the current summary/start/end/description/location/rrule instead of sending a patch; omit absent optional fields, use an empty string only to clear description/location, and omit rrule to clear recurrence
  4. For an occurrence with recurrence_id, ask whether the scope is this occurrence (recurrence_range:"") or this and future occurrences ("THISANDFUTURE"). Bind that scope to the preview. For a single-occurrence update, omit rrule from the replacement event. Do not invent an entire-series mode.
  5. Show the Preview Card with operation, calendar, exact event identity, summary, start/end, timezone or all-day range, changed fields, and recurrence scope. Create/update use natural bound confirmation; delete uses the typed confirm:<token> from the core rule.
  6. Immediately before execution, re-read the target window and calendar state; this event set is the create baseline. Abort and rebuild the preview if capability, identity, current fields, or recurrence scope drifted.
  7. Execute exactly one write:
    • create: POST {"entity_id":"calendar.example","summary":"Event","start_date_time":"<start>","end_date_time":"<end>"} to /api/services/calendar/create_event
    • recurring create: WS {"type":"calendar/event/create","entity_id":"calendar.example","event":{"summary":"Event","dtstart":"<start>","dtend":"<end>","rrule":"FREQ=WEEKLY;BYDAY=MO"}} — dtstart/dtend describe the FIRST instance
    • update: WS {"type":"calendar/event/update","entity_id":"calendar.example","uid":"<uid>","recurrence_id":"<instance>","recurrence_range":"<range>","event":{"summary":"Event","dtstart":"<start>","dtend":"<end>"}}; omit recurrence keys for a non-recurring event
    • delete: WS {"type":"calendar/event/delete","entity_id":"calendar.example","uid":"<uid>","recurrence_id":"<instance>","recurrence_range":"<range>"}; omit recurrence keys for a non-recurring event
  8. Verify through bounded RES
阅读完整来源 ↗