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, be sure to first use the Read tool to read the corresponding documentation. Do not directly call commands blindly.

Core Scenarios

The calendar skill includes the following core scenarios:

1. Scheduling an event

This is the most core scenario of the calendar skill. The core is to enable users to schedule events at low cost.

💡 Core principle: Be an intelligent assistant that provides decision support, not a form-filling machine or someone who makes decisions for the user.

Time and date inference specifications: To ensure accuracy, when time inference is involved, 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 calculate based on the current real date and weekday baseline to avoid getting the date wrong.
Range of a day: When the user mentions明天、今天and other references to a certain day in general, the time range should by default cover the entire day.Nevernarrow the query range on your own, so as not to miss evening time arrangements.
Historical time constraint: You cannot schedule a time that has already completely passed. The only exception is a schedule that "spans the current time," that is, the schedule's start time is in the past but its end time is in the future.

Workflow for scheduling an event:

Intelligently infer defaults
- The title, attendees, and duration all have default values, so there is no need to frequently confirm with the user.
- Attendees: If no other people are explicitly specified, the default attendee is onlythe user themself. When searching for a specific attendee (person, group, meeting room) returns multiple results that cannot be uniquely determined, you must ask the user to choose and confirm, and record that preference as long-term memory for automatic recognition later.
- Meeting room: Actively booking a meeting room is currently not supported, unless the corresponding meeting room ID (with the omm_ prefix) already exists in the current context and needs to be added to the schedule.
- Title: Automatically generate it based on the conversation context (for example, "communication alignment" or "requirements discussion"). If it cannot be inferred, default to "Meeting".
- Duration: Dynamically infer it based on the meeting type and context (for example, infer "review/report" as 60 minutes, etc.). If it cannot be inferred, default to 30 minutes.
Time suggestions and decision support (core experience)
- Has a clear time point(such as明早10点): Call the relevant tool (such as lark-cli calendar +freebusy lark-calendar-freebusy) First, check the availability status of the attendees during that time period (Note: if an attendee's existing event has an RSVP status of declined, that time period is considered free). If there are no conflicts, proceed directly to the next step to confirm and create; if there are conflicts, notify the user of the conflicts and ask whether to continue creating or reselect a time.
- There is a time range(such as明天、下午、本周): call the relevant tool (such as lark-cli calendar +suggestion lark-calendar-suggestion) to obtain themultiple time recommendation optionsfor the user to choose from.Only after the user confirms an optioncan the create-event operation be executed; and once the user has selected a recommended option,there is no need to query the availability information again。
- No time information at all: by default, infer a reasonable range (such as "today" or "the past two days"), and similarly obtainmultiple time recommendation optionsfor the user to choose from quickly.
- Personal-life needs(such as fitness, swimming, taking a walk, arranging a meal, milk tea, etc. Note: "meeting for coffee" counts as a work scenario): it is expectednot to call suggestion tools. Instead, infer a suitable non-working time on your own and present it to the user for confirmation. If it cannot be inferred, try proactively asking the user, and after the user gives feedback, form a memory so it can be applied directly in the future.
- Disambiguation of vague semantics and long-term memory building (Aha Moment): for a user's specific time-expression habits (such as "after work starts" or "before getting off work") or ambiguous time scenarios (such as the 12-hour clock without specifying AM or PM), subjective assumptions are strictly prohibited. Clarify the true intent through proactive questioning, and consolidate such personalized definitions into long-term preferences, driving the continuous evolution of the system's cognitive capabilities and ultimately achieving an intelligent experience where it "understands next time."
Non-blocking execution
- After the user confirms a specific time option, execute lark-cli calendar +create --summary "..." --start "..." --end "..." --attendee-ids ...
Friendly feedback
- Report the result: return a summary of the successfully created event

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 event entry in a calendar, containing attributes such as start and end time, location, title, and attendees. It supports single events and recurring events, and follows the RFC5545 iCalendar international standard.
All-day Event: an event that occupies only dates and has no specific start or end time; the end date is included within the event time.
Event Instance: a specific time instance of an event; in essence, it is an expansion of the event. A regular event and an exception event correspond to 1 Instance, while a recurring event corresponds to N Instances. When querying by time period, the instance view can be used to expand recurring events into independent instances for return, so they can be accurately displayed and managed on the timeline.
Recurrence Rule (Rrule/Recurrence Rule): defines the recurrence rule for a recurring event, for exampleFREQ=DAILY;UNTIL=20230307T155959Z;INTERVAL=14means it repeats every 14 days.
Exception Event: an event in a recurring event that is inconsistent with the original recurring event.
Attendee: The participants of a schedule can be users, groups, meeting room resources, external email addresses, etc. Each participant has an independent RSVP status.
Response Status (RSVP): The participant's reply status to a schedule invitation (accepted/declined/tentative).
FreeBusy: Query a user's busy/free status for a specified time period, used for meeting time coordination.

Resource Relationships

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

Shortcuts (recommended for priority use)

Shortcut is a high-level wrapper for common operations (lark-cli calendar +<verb> [flags]). For operations that have a Shortcut, use it first.

Shortcut	Description
`+agenda`	View schedule (defaults to today)
`+create`	Create a schedule and invite participants (ISO 8601 time)
`+freebusy`	Query the busy/free information and RSVP status of a user's primary calendar
`+suggestion`	For appointment schedule requests with undetermined times, provide multiple time recommendation options

+suggestion usage

Before calling +suggestion , be sure to read the usage instructions in lark-calendar-suggestion ; do not call the command directly.

lark-cli calendar +suggestion --start "2026-03-10T00:00:00+08:00" --end "2026-03-10T11:00:00+08:00" --attendee-ids "ou_xxx,oc_yyy" --duration-minutes 30 # 为用户ou_xxx和群组oc_yyy里的成员推荐空闲时段

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 schedule participants
create — Add schedule participants
list — Get schedule participant list

events

create — Create a schedule
delete — Delete a schedule
get — Get a schedule
instance_view — Query schedule views
patch — Update a schedule
search — Search schedules

freebusys

list — Query busy/free information for the primary calendar schedule

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 call external tools such as system commands or script code to ensure the conversion is absolutely accurate. Violations will cause serious logical errors!