calendar (v4)

CRITICAL, Before starting, you MUST use the Read tool to read ../lark-shared/SKILL.md, which contains information on authentication and permission handling. CRITICAL, Before executing any Shortcuts, you must use the Read tool to read their corresponding documentation. Do not call commands blindly. CRITICAL, For any tasks involving "scheduling meetings/events" or "querying/searching for meeting rooms," the first step MUST be to use the Read tool to read references/lark-calendar-schedule-meeting.md. Skipping this step to call an API or Shortcut directly is prohibited! CRITICAL, Terminology constraint: When users say things like "help me schedule a calendar" or "check today's calendar," their actual intent is usually to create or query an Event, not to operate on the Calendar container itself. Please automatically map colloquial "calendar" intents to "event" operations (e.g., +create, +agenda). CRITICAL, Intent routing for meetings and events:

• Querying past meetings: If a user explicitly queries past meetings (e.g., "yesterday's meeting," "last week's meeting"), prioritize using ../lark-vc/SKILL.md to search meeting records. This is because meeting data includes not only meetings initiated from events but also instant meetings; querying only event data will result in incomplete information.
• Querying calendars/events or future meetings: If the user explicitly expresses "calendar," "event," or involves future arrangements, it falls under the business domain of this skill (lark-calendar). Please continue to use this skill for processing. CRITICAL, Task type triage: When handling "scheduling/rescheduling events, adding/removing attendees, adding/changing meeting rooms, or adjusting times," you must first determine whether the user is "creating a new event" or "editing an existing event."
• Strong signals for editing an existing event: The user explicitly mentions an existing event anchor (e.g., title, time slot, "this event," "this meeting") and expresses a modification action (e.g., "add," "remove," "change to," "change meeting room," "adjust time"). Such requests default to editing an existing event and must never be treated as a new creation.
• Prerequisite for editing an existing event: Once identified as an edit, you MUST first locate the event_id of the target event or specific instance before proceeding. If it is a recurring event, you MUST first locate the event_id of the corresponding instance.
• Creating a new event: Only enter the new creation flow when the user expresses an intent to "schedule a new meeting/create an event/arrange a meeting" and there is no modification action pointing to an existing event.

CRITICAL, Verification and synchronization delay: After deleting an event (delete), modifying an event (patch), or adding/removing attendees/meeting rooms, if you need to perform a secondary query to verify the result, you MUST wait at least 2 seconds before querying to prevent missing the latest data due to synchronization delays. Note: Do not mention to the user that you waited for these 2 seconds.

CRITICAL, Operations on recurring event instances: You now have the full capability to operate on specific instances of a recurring event (e.g., editing a specific instance, deleting a specific instance, adding/removing attendees for a specific instance, adding/removing meeting rooms for a specific instance). Simply pass the event_id of the corresponding instance in the operation. Therefore, you MUST first locate the event_id of that specific instance (this can be obtained via events search_event or by checking +agenda for the relevant time range). It is strictly prohibited to use the event_id of the original recurring event directly for these operations.

Time and date inference specifications: To ensure accuracy, strictly follow these rules when inferring time:

• Definition of a week: Monday is the first day of the week, and Sunday is the last day. When calculating relative dates like "next Monday," be sure to base it on the current real date and the day of the week to avoid calculation errors.
• Range of a day: When a user mentions "tomorrow," "today," etc., the time range should default to cover the entire day. Do not reduce the query range on your own, as this may cause you to miss evening arrangements.
• Historical time constraint: You cannot schedule time that has already completely passed. The only exception is an event that "spans the current time," meaning the event start time is in the past but the end time is in the future.

Core Scenarios

1. Scheduling new events/meetings, editing existing events, querying/searching for available meeting rooms

BLOCKING REQUIREMENT: As long as the user's intent includes "scheduling an event/meeting" or "querying/searching for available meeting rooms," you must immediately stop other thinking and prioritize using the Read tool to fully read references/lark-calendar-schedule-meeting.md! Executing any event creation or meeting room query operation before reading this file is strictly prohibited. CRITICAL: You must strictly follow the workflow defined in the aforementioned document to execute subsequent operations. When handling this scenario, act as an "intelligent assistant," not a "form filler." Fill in default values where possible, and only ask follow-up questions when there are time conflicts, results cannot be uniquely determined, or there is ambiguity in time semantics. CRITICAL: The execution order must be fixed: first determine the task type (new/edit); if editing, first locate the target event_id; then fill in default values or inherit known information from the located event; then determine if the time is clear; finally, enter the "clear time" or "fuzzy time/no time information" branch. Do not skip steps. CRITICAL: When the time is clear and a meeting room is needed, first execute +room-find based on the finalized time block, then execute +freebusy as needed; when the time is fuzzy or there is no time information, first use +suggestion, and if a meeting room is needed, perform batch +room-find. If editing an existing event without changing the time, and only adding a meeting room, you must execute +room-find based on the original time of the located event, and by default, retain existing meeting rooms; only delete the original meeting room if the user explicitly expresses "change meeting room" or "remove meeting room." CRITICAL: When a user says "check meeting rooms," "find meeting rooms," "search for available meeting rooms," or "recommend common meeting rooms," it defaults to checking meeting room availability, not checking a directory of meeting room resources. It is strictly prohibited to pull historical event data 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," if they have not provided a clear start and end time, it is strictly prohibited to call +room-find directly! You must first enter the "no time/fuzzy time" branch, call +suggestion to get candidate time blocks, and then pass the time block to +room-find. BLOCKING REQUIREMENT: Whenever you are faced with a choice of time slots or meeting room options (such as fuzzy time, no time, or needing a meeting room), you must present the candidate options to the user and wait for their explicit confirmation before finally executing the creation of a new event or updating an existing one. It is strictly prohibited to make decisions for the user without authorization.

Core Concepts

• Calendar: A container for events. Each user has a primary calendar and can also create or subscribe to shared calendars.
• Event: A single item in a calendar, containing attributes such as start/end time, location, title, and attendees. Supports single events and recurring events, following the RFC5545 iCalendar international standard.
• All-day Event: An event that occupies time by date only, without specific start/end times. The end date is included in the event time.
• Instance: A specific time instance of an event, which is essentially an expansion of the event. Regular events and exception events correspond to 1 instance, while recurring events correspond to N instances. When querying by time period, recurring events can be expanded into independent instances via the instance view for accurate display and management on a timeline.
• Rrule/Recurrence Rule: Defines the repetition rule for a recurring event, e.g., FREQ=DAILY;UNTIL=20230307T155959Z;INTERVAL=14 means it repeats every 14 days.
• Exception: An event within a recurring series that differs from the original recurrence rule.
• Attendee: A participant in an event, which can be a user, group, meeting room resource, external email address, etc. Each attendee has an independent RSVP status.
• RSVP: The response status of an attendee to an event invitation (accepted/declined/tentative).
• FreeBusy: Queries the busy/free status of a user during a specified time period, used for meeting time coordination.
• Room: Refers to a meeting room. Please accurately map "room" to "meeting room" and its related operations when understanding and processing intents.
• Time Slot / Time Block: Refers to a specific and definite continuous time period (e.g., 14:00~15:00). In the documentation, it is strictly distinguished from general "time ranges/intervals" (e.g., "this afternoon," "next week"). When calling exact operations like booking or querying available meeting rooms, you must base them on a definite "time block" rather than a fuzzy "time range."

Resource Relationships

Calendar
└── Event
    ├── Attendee
    └── Reminder

Shortcuts (Recommended for priority use)

Shortcuts are high-level encapsulations of common operations (lark-cli calendar +<verb> [flags]). Use Shortcuts whenever available.

Meeting Room Rules

• Meeting rooms are a type of attendee (resource attendee) for an event and cannot exist or be booked independently of an event.
• Whenever the user's intent is "booking/querying/searching for available meeting rooms," you must enter the references/lark-calendar-schedule-meeting.md workflow for processing.
• The time input for +room-find must be a definite time block, not a time range search.
• Mandatory constraint: If the user only requests "check meeting rooms" but does not provide a clear 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 and call +room-find blindly.
• When editing an existing event, if the user expresses "add a meeting room/add another meeting room," the default semantics are incremental addition, and existing meeting rooms must be retained; only perform deletion of old meeting rooms if the user explicitly expresses "change meeting room," "replace the original meeting room," or "remove meeting room."

API Resources

lark-cli schema calendar.<resource>.<method>   # Must check parameter structure before calling API
lark-cli calendar <resource> <method> [flags] # Call API

Important: When using native APIs, you must first run schema to view the --data / --params parameter structure. Do not guess field formats.

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 user's primary calendar
• search, Search calendars

event.attendees

• batch_delete, Delete event attendees
• create, Add event attendees
• list, Get list of event attendees

events

• create, Create an event
• delete, Delete an event
• get, Get an event
• instance_view, Query event view
• patch, Update an event
• search_event, Search events (Note: Currently only returns event ID, subject, and time information; for more details, use the events get command)
• share_info, Get event share link

freebusys

• list, Query busy/free information for the primary calendar

Permissions Table

Note (Mandatory):

• When involving conversions between date (time) strings and timestamps, be sure to call system commands or script code and other external tools to ensure absolute accuracy in the conversion. Violations will lead to serious logical errors!