calendar (v4)

Read ../lark-shared/SKILL.md before starting (authentication, permission handling).

CRITICAL, For any task involving scheduling meetings or querying/searching for meeting rooms, the first step MUST be to read references/lark-calendar-schedule-meeting.md. Do not skip this step to call APIs or Shortcuts directly!

Identity

Calendar operations use --as user by default (to view and manage the current user's calendar). --as bot can only access the bot's own (empty) calendar and will return empty results. Do not use the bot identity to query user calendars.

# BAD, bot identity querying user calendar, returns empty list
lark-cli calendar +agenda --as bot

# GOOD, user identity querying calendar
lark-cli calendar +agenda --as user

Shortcuts

Prerequisite Routing

Core Concepts

• Event Instance: A specific time instance of an expanded recurring event. When operating on a specific instance of a recurring event, you must first locate the event_id of that instance. Do not use the event_id of the original recurring event.
• All-day Event: An event that occupies a full day without specific start and end times. The end date is included in the event duration.
• Time Block vs Time Range: A time block is a specific, determined continuous period (e.g., 14:00~15:00), while a time range is a general reference (e.g., "this afternoon"). +room-find must be based on a specific time block and cannot be based on a vague range.
• Room: "room" refers to a meeting room. A meeting room is a type of event participant (resource attendee) and cannot be booked independently of an event.

Terminology Mapping

When users say "help me book a calendar" or "check today's calendar," their actual intent is to create or query an Event, not to operate on the Calendar container itself. Automatically map colloquial "calendar" intents to "event" operations.

Intent Routing

Task Type Diversion

When handling "schedule/reschedule events, add/remove attendees, add/change meeting rooms, adjust time," you must first determine if it is a new creation or an edit:

• Strong signals for editing an existing event: The user mentions an existing event anchor (title, time slot, "this event", "that meeting") and expresses a modification action (add, remove, change to, change meeting room, adjust time). Default to the edit flow; never treat it as a new creation.
• New event creation: The user expresses an intent to create something new ("book a new meeting", "create an event", "arrange a meeting") and there is no modification action pointing to an existing event.

Time Inference Standards

• Definition of a week: Monday is the first day of the week, and Sunday is the last. When calculating relative dates like "next Monday," base the calculation on the current real-world date.
• Range of a day: When a user mentions general terms like "tomorrow" or "today," the time range should cover the entire day. Do not shorten it yourself.
• Historical time constraint: You cannot schedule events for times that have already completely passed. The only exception is an event that "spans the current time" (starts in the past, ends in the future).

Meeting Room Rules

• For any "book/query/search for available meeting rooms," you must enter the schedule-meeting workflow.
• The time input for +room-find must be a specific time block, not a time range search.
• If a user only asks to "check meeting rooms" without providing a specific time, you must first call +suggestion to get available time blocks, then pass the time block to +room-find. It is strictly forbidden to guess a time and call blindly.
• When editing an existing event, "adding a meeting room" is an incremental operation by default, preserving existing meeting rooms. Only delete old meeting rooms if the user explicitly says "change meeting room" or "remove meeting room."

API Resources

lark-cli calendar <resource> <method> [flags]

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 event attendee list

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 (returns only Event ID/Subject/Time; for details, use events get)
• share_info, Get event share link

freebusys

• list, Query primary calendar busy/free information

Out of Scope

• Querying past video meeting records → lark-vc
• Task management → lark-task
• Physical meeting room facility management → Admin console

Note (Mandatory):

• When involving the conversion between date (time) strings and timestamps, you must use system commands or script code and other external tools to ensure absolute accuracy. Failure to do so will result in severe logical errors!