calendar (v4)

../lark-shared/SKILL.md

Core Scenarios

1. Schedule Booking

💡 Core Principle: Act as an intelligent assistant, provide decision support, not a form filler or make decisions on behalf of users.

• Definition of the week: Monday is the first day of the week, Sunday is the last day of the week. When calculating relative dates like "next Monday", be sure to base it on the current actual date and week benchmark to avoid miscalculations.
• Range of a day: When the user refers to a general day such as "tomorrow" or "today", the time range should default to cover the entire day. Do not reduce the query scope on your own, as this may miss evening arrangements.
• Historical Time Constraint: Cannot book time that has completely passed. The only exception is a schedule that "crosses the current time", i.e., the start time of the schedule is in the past but the end time is in the future.

1. Intelligent Inference of Default Values
   • Default values exist for title, attendees, and duration, so there is no need to frequently confirm with the user.
   • Attendees: If no other people are clearly specified, the default attendees are only the user themselves. When searching for specific attendees (people, groups, meeting rooms) yields multiple results that cannot be uniquely determined, you must ask the user to select and confirm, and record this preference as long-term memory for automatic recognition in subsequent interactions.
   • Meeting Rooms: Currently, active booking of meeting rooms is not supported unless the corresponding meeting room ID (with omm_ prefix) already exists in the current context and needs to be added to the schedule.
   • Title: Automatically generated based on the conversation context (e.g., "Communication Alignment" or "Requirement Discussion"), defaults to "Meeting" if inference is not possible.
   • Duration: Dynamically inferred based on meeting type and context (e.g., "Review/Report" is inferred as 60 minutes, etc.), defaults to 30 minutes if inference is not possible.
2. Time Suggestions and Decision Support (Core Experience)
   • With a specific time point (e.g., "10 AM tomorrow"): Call the relevant tool (such as

     lark-cli calendar +freebusy

     lark-calendar-freebusy) to first check the free/busy status of attendees during that period (Note: If an attendee's RSVP status for an existing schedule is "declined", that time period is considered free). If there are no conflicts, proceed to the next step of confirmation and creation; if there are conflicts, inform the user of the conflict and ask whether to continue creating or reselect a time.
   • With a time interval (e.g., "tomorrow", "afternoon", "this week"): Call the relevant tool (such as

     lark-cli calendar +suggestion

     lark-calendar-suggestion) to obtain multiple time recommendation options for all attendees within the interval for the user to choose from. Only after the user confirms the option can you execute the schedule creation operation; once the user selects a recommended option, there is no need to check free/busy information again.
   • No time information provided: Default to inferring a reasonable interval (e.g., "today" or "the next two days") and also obtain multiple time recommendation options for the user to quickly select from.
   • Life-related needs (e.g., fitness, swimming, walking, meal appointments, milk tea, etc. Note: "coffee appointment" is considered a work scenario): Do not call the

     suggestion

     tool. You should infer appropriate non-working hours on your own for the user to confirm. If inference is not possible, try to actively ask the user, and form a memory after receiving feedback for direct application in subsequent interactions.
   • Ambiguity Resolution and Long-Term Memory Construction (Aha Moment): For the user's exclusive time expression habits (e.g., "after work starts", "before work ends") or ambiguous time scenarios (e.g., 12-hour format without specifying AM/PM), do not make subjective assumptions. You should clarify the true intention through active confirmation, and record such personalized definitions as long-term preferences to promote the continuous evolution of the system's cognitive ability, ultimately achieving an intelligent experience of "understanding next time".
3. Non-Blocking Execution
   • After the user confirms the specific time option, execute

     lark-cli calendar +create --summary "..." --start "..." --end "..." --attendee-ids ...

4. Friendly Feedback
   • Report results: Return the summary information of the successfully created schedule

Core Concepts

• Calendar: The container for schedules. Each user has a primary calendar, and can also create or subscribe to shared calendars.
• Event: A single event entry in the calendar, containing attributes such as start/end time, location, title, attendees, etc. Supports one-time and recurring schedules, following the RFC5545 iCalendar international standard.
• All-day Event: A schedule that only occupies a date without specific start/end times, and the end date is included in the schedule time.
• Instance: A specific time instance of a schedule, essentially an expansion of the schedule. Regular events and exception events correspond to 1 Instance, while recurring events correspond to N Instances. When querying by time period, recurring schedules can be expanded into independent instances through the instance view for accurate display and management on the timeline.
• Recurrence Rule (Rrule): Defines the recurrence rule for recurring schedules, such as

  FREQ=DAILY;UNTIL=20230307T155959Z;INTERVAL=14

  which means repeating every 14 days.
• Exception: A schedule in a recurring series that is inconsistent with the original recurring schedule.
• Attendee: A participant in the schedule, which can be a user, group, meeting room resource, external email address, etc. Each attendee has an independent RSVP status.
• RSVP Status: The response status of an attendee to a schedule invitation (Accept/Decline/Tentative).
• FreeBusy: Query the user's free/busy status during a specified time period, used for meeting time coordination.

Resource Relationships

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

Shortcuts (Recommended for Priority Use)

lark-cli calendar +<verb> [flags]

+agenda

+create

+freebusy

+suggestion

+suggestion Usage

+suggestion

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>   # Must check the parameter structure before calling the API
lark-cli calendar <resource> <method> [flags] # Call the API

Important: When using the native API, must first run

schema

to check 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 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

  — Search events

freebusys

• list

  — Query free/busy information of primary calendar events

Permission Table

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

• When converting between date (time) strings and timestamps, be sure to use external tools such as system commands or script code for processing to ensure absolute accuracy. Violations will lead to serious logical errors!