效率与协作
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>forcalendar/event/create(recurring creates),calendar/event/update, andcalendar/event/deleteha-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
- List calendars with
/api/calendars. - Resolve the requested calendar by exact
entity_idor exact/clear name match. - If multiple calendars match, ask one blocking question.
- 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
- Query events with
/api/calendars/<entity_id>?start=<start>&end=<end>. - 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
- Resolve one exact calendar and read
/api/states/<entity_id>. Gate create onsupported_features & 1, delete on& 2, and update on& 4; stop when the required bit is absent. - 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. - Normalize event fields:
- timed events use
start_date_time/end_date_timefor create anddtstart/dtendinside the WSeventobject; both values use the Home Assistant timezone and end must be after start - all-day events use
start_date/end_datefor REST create and date-onlydtstart/dtendin the WSevent(recurring create, update); end is exclusive - create requires
summary; optionaldescriptionandlocationare included only when set - a recurring create takes an RFC 5545
rrulestring and goes through WScalendar/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
rruleto clear recurrence
- timed events use
- 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, omitrrulefrom the replacement event. Do not invent an entire-series mode. - 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. - 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.
- 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/dtenddescribe 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
- create: POST
- Verify through bounded RES