lark-calendar

calendar (v4)

CRITICAL — Before starting, you MUST first use the Read tool to read ../lark-shared/SKILL.md, which contains authentication and permission handling CRITICAL — Before executing any Shortcuts, you must first use the Read tool to read their corresponding documentation. Directly calling commands blindly is prohibited. CRITICAL — Whenever it involves [booking events/meetings] or [querying/searching meeting rooms], the first step MUST mandatorily use the Read tool to read references/lark-calendar-schedule-meeting.md. Skipping this step and directly calling the API or Shortcut is prohibited! CRITICAL — Terminology constraint: In users' everyday expressions, phrases such as "book me a calendar" or "check today's calendar" usually actually intend the creation or querying of an event (Event), rather than operating the calendar (Calendar) container itself. Please automatically map the colloquial "calendar" intent to "event" operations (such as +create, +agenda）。

Time and date inference specifications: To ensure accuracy, when time inference is involved, please strictly follow the rules below:

Definition of weekdays: Monday is the first day of the week, and Sunday is the last day of the week. When calculating下周一and other relative dates, be sure to infer based on the current real date and weekday baseline to avoid calculating the wrong date.
Range of a day: When the user mentions明天、今天and other general references to a certain day, the time range should by default cover the entire day's time range.Nevernarrow the query range on your own, so as to avoid missing evening time arrangements.
Historical time constraint: You cannot book a time that has already completely passed. The only exception is an event that "spans the current time," that is, an event whose start time is in the past but whose end time is in the future.

Core scenarios

1. Booking events/meetings, querying/searching available meeting rooms

BLOCKING REQUIREMENT: As long as the user's intent includes "booking events/meetings" or "querying/searching available meeting rooms," you must immediately stop other thinking and prioritize using the Read tool to fully read references/lark-calendar-schedule-meeting.md! Before reading this file, executing any event creation or meeting room query operation is absolutely prohibited. CRITICAL: Subsequent operations must be strictly executed according to the workflow (Workflow) defined in the above document. When handling this scenario, by default act as an "intelligent assistant," not a "form-filling machine." Fill in the default values that can be completed first, and only proactively ask follow-up questions when there is a time conflict, the result cannot be uniquely determined, or the time semantics are ambiguous. CRITICAL: The execution order must be fixed as: first fill in default values, then determine whether the time is clear, then enter the "clear time" or "vague time/no time information" branch. Do not skip steps. CRITICAL: When the time is clear and a meeting room is needed, first +room-find, then +freebusy; when the time is vague or there is no time information, first +suggestion, and if a meeting room is needed, then batch +room-find。 CRITICAL: When the user says "check meeting rooms," "find meeting rooms," "search available meeting rooms," or "recommend commonly used meeting rooms," the default is to check meeting room availability, not to check the meeting room resource directory, and it is even more strictly prohibited to pull historical events for statistical analysis. The complete rules are subject to lark-calendar-schedule-meeting.md . BLOCKING REQUIREMENT: Even if the user's core request is "check meeting rooms", as long as [no explicit start and end times are provided], it is absolutely forbidden to directly call +room-find! You must first enter the [no time/vague time] branch, call +suggestion to get candidate time blocks, then pass the time blocks to +room-find。 BLOCKING REQUIREMENT: Whenever faced with a choice of time options or meeting room options (such as vague time, no time, or needing a meeting room), before calling +create to create a schedule, you must first show the candidate options to the user and wait for the user's explicit confirmation. It is absolutely forbidden to make decisions on the user's behalf without authorization.

Core Concepts

Calendar: A container for schedules. Each user has a primary calendar, and can also create or subscribe to shared calendars.
Event: A single schedule in a calendar, containing attributes such as start and end times, location, title, and attendees. Supports single events and recurring events, following the RFC5545 iCalendar international standard.
All-day Event: An event that occupies only by date and has no specific start and end times; the end date is included within the event time.
Instance: A specific time instance of an event, essentially an expansion of the event. A normal event and an exception event correspond to 1 Instance, while a recurring event corresponds to N Instances. When querying by time period, recurring events can be expanded into independent instances via the instance view, so that they can be accurately displayed and managed on the timeline.
Rrule/Recurrence Rule: Defines the recurrence rule of a recurring event, for exampleFREQ=DAILY;UNTIL=20230307T155959Z;INTERVAL=14means it repeats every 14 days.
Exception: An event in a recurring event that is inconsistent with the original recurring event.
Attendee: A participant of an event, which can be a user, a group, a meeting room resource, an external email address, etc. Each attendee has an independent RSVP status.
RSVP: The attendee's reply status to the event invitation (accepted/declined/tentative).
FreeBusy: Queries a user's busy/free status in a specified time period, used for meeting time coordination.
Room: "room" is not "room"; it is "meeting room". When understanding and processing intents, please accurately map "room" and "room" to "meeting room" and its related operations.
Time Slot / Time Block: Refers to aspecific and definitecontinuous time period (such as 14:00~15:00). In the documentation, it is strictly different from the general "time range/interval" (such as "this afternoon", "next week"). When calling exact operations such as booking and querying available meeting rooms, it must be based on a definite "time block" rather than a vague "time range".

Resource Relationships

Calendar (日历)
└── Event (日程)
    ├── Attendee (参会人)
    └── Reminder (提醒)

Shortcuts (recommended for priority use)

Shortcut is a high-level encapsulation of common operations (lark-cli calendar +<verb> [flags]). Operations with Shortcuts should be used first.

Shortcut	Description
`+agenda`	View schedule (default today)
`+create`	Create an event and invite attendees (ISO 8601 time)
`+freebusy`	Query the busy/free information and RSVP status of the user's primary calendar
`+room-find`	For one or moreExplicitTime-block lookup for available meeting rooms (When there is no explicit time, direct invocation is prohibited; you must first go through +suggestion）
`+rsvp`	Respond to calendar events (accept/decline/tentative)
`+suggestion`	Based on a non-explicit time or a time range, recommend multiple available time-block options

Meeting room related rules

A meeting room is a type of calendar event participant (resource attendee) and cannot exist independently of a calendar event or be booked independently.
Whenever the user's intent is to "book/query/search for available meeting rooms," they must enter the references/lark-calendar-schedule-meeting.md workflow for processing.
+room-find The time input must be adeterminate time block, and cannot be a time range search.
Mandatory constraint: If the user only requests to "query meeting rooms" but does not provide an explicit time, you must first call +suggestion to obtain available time blocks, and then pass the time blocks to +room-find for batch querying. It is strictly prohibited to guess the time directly and blindly call +room-find。

API Resources

lark-cli schema calendar.<resource>.<method>   # 调用 API 前必须先查看参数结构
lark-cli calendar <resource> <method> [flags] # 调用 API

Important: When using the native API, you must first run schema to view the --data / --params parameter structure; do not guess the field format.

calendars

create — Create a shared calendar
delete — Delete a shared calendar
get — Query calendar information
list — Query calendar list
patch — Update calendar information
primary — Query the user's primary calendar
search — Search calendars

event.attendees

batch_delete — Delete calendar event participants
create — Add calendar event participants
list — Get the calendar event participant list

events

create — Create calendar event
delete — Delete calendar event
get — Get calendar event
instance_view — Query calendar event view
patch — Update calendar event
search — Search calendar events

freebusys

list — Query free/busy information for calendar events in the primary calendar

Permission table

Method	Required scope
`calendars.create`	`calendar:calendar:create`
`calendars.delete`	`calendar:calendar:delete`
`calendars.get`	`calendar:calendar:read`
`calendars.list`	`calendar:calendar:read`
`calendars.patch`	`calendar:calendar:update`
`calendars.primary`	`calendar:calendar:read`
`calendars.search`	`calendar:calendar:read`
`event.attendees.batch_delete`	`calendar:calendar.event:update`
`event.attendees.create`	`calendar:calendar.event:update`
`event.attendees.list`	`calendar:calendar.event:read`
`events.create`	`calendar:calendar.event:create`
`events.delete`	`calendar:calendar.event:delete`
`events.get`	`calendar:calendar.event:read`
`events.instance_view`	`calendar:calendar.event:read`
`events.patch`	`calendar:calendar.event:update`
`events.search`	`calendar:calendar.event:read`
`freebusys.list`	`calendar:calendar.free_busy:read`

Note (mandatory):

When converting between date (time) strings and timestamps, be sure to use external tools such as system commands or script code to ensure absolute accuracy of the conversion. Violators will cause serious logical errors!