lark-calendar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

calendar (v4)

CRITICAL — 开始前 MUST 先用 Read 工具读取
../lark-shared/SKILL.md
，其中包含认证、权限处理 CRITICAL — 所有的 Shortcuts 在执行之前，务必先使用 Read 工具读取其对应的说明文档，禁止直接盲目调用命令。

CRITICAL — MUST use the Read tool to read
../lark-shared/SKILL.md
before starting, which contains authentication and permission handling CRITICAL — Before executing any Shortcuts, be sure to use the Read tool to read their corresponding documentation. Do not call commands blindly directly.

核心场景

Core Scenarios

日历技能包含以下核心场景：

The calendar skill includes the following core scenarios:

1. 预约日程

1. Schedule Booking

这是日历技能最核心的场景，核心是让用户低成本地实现日程预约。

💡 核心原则：做智能助理，提供辅助决策，而不是表单填写机或替用户做主。

时间与日期推断规范： 为确保准确性，在涉及时间推断时，请严格遵循以下规则：

星期的定义：周一是一周的第一天，周日是一周的最后一天。计算
```
下周一
```
等相对日期时，务必基于当前真实日期和星期基准进行推算，避免算错日期。
一天的范围：当用户提到
```
明天
```
、
```
今天
```
等泛指某一天时，时间范围应默认覆盖整天时间范围。切勿自行缩减查询范围，以免遗漏晚上的时间安排。
历史时间约束：不能预约已经完全过去的时间。唯一的例外情况是“跨越当前时间”的日程，即日程的开始时间在过去，但结束时间在未来。

预约日程的工作流：

智能推断默认值
- 标题，参与人，时长均存在默认值，无需频繁的和用户确认。
- 参会人：如未明确指定其他人，默认参会人仅为用户自己。当搜索特定参与人（人、群、会议室）出现多个结果无法唯一确定时，必须询问用户进行选择确认，并将该偏好记录为长期记忆，以便后续自动识别。
- 会议室：目前不支持主动预定会议室，除非当前上下文中已经存在对应的会议室ID(omm_ 前缀) 且需要添加到日程中。
- 标题：根据对话上下文自动生成（例如“沟通对齐”或“需求讨论”），如无法推断则默认为“会议”。
- 时长：基于会议类型和上下文动态推断（例如：“评审/汇报”推断为 60 分钟等），如无法推断，则默认为 30 分钟。
时间建议与辅助决策（核心体验）
- 有明确时间点（如
```
明早10点
```
  ）：调用相关工具（如
```
lark-cli calendar +freebusy
```
  lark-calendar-freebusy）先查询该时间段参会人的忙闲状态（注：若参会人已有日程的 RSVP 状态为拒绝，则认为该时段为空闲）。若均无冲突，直接进入下一步确认并创建；若有冲突，提示用户冲突情况并询问是否继续创建或重新选择时间。
- 有时间区间（如
```
明天
```
  、
```
下午
```
  、
```
本周
```
  ）：调用相关工具（如
```
lark-cli calendar +suggestion
```
  lark-calendar-suggestion）获取该区间内所有参会人的多个时间推荐方案供用户选择。必须在用户确认方案后，才能执行创建日程操作；且用户一旦选择了推荐的方案，无需再次查询忙闲信息。
- 无任何时间信息：默认推断一个合理区间（如“今天”或“近两天”），并同样获取多个时间推荐方案供用户快速选择。
- 生活类需求（如健身、游泳、遛弯、约饭、奶茶等，注意“约咖啡”算工作场景）：预期不调用
```
suggestion
```
  工具。应自行推断合适的非工作时间给到用户确认。如果无法推断，请尝试主动询问用户，并在用户给出反馈后形成记忆，以便后续直接应用。
- 模糊语义消解与长期记忆构建 (Aha Moment)：针对用户专属的时间表达习惯（如“上班后”、“下班前”）或存在歧义的时间场景（如未指明上下午的12小时制），严禁主观臆断。应通过主动澄清明确真实意图，并将此类个性化定义沉淀为长期偏好，推动系统认知能力的持续进化，最终实现“下次即懂”的智能化体验。

非阻断式执行

待用户确认具体时间选项后，执行

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

友好反馈
- 报告结果：返回创建成功的日程摘要信息

This is the most core scenario of the calendar skill, focusing on enabling users to book schedules at low cost.

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

Time and Date Inference Specifications: To ensure accuracy, strictly follow the following rules when inferring time:

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.

Workflow for Schedule Booking:

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.
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".

Non-Blocking Execution

After the user confirms the specific time option, execute

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

Friendly Feedback
- Report results: Return the summary information of the successfully created schedule

核心概念

Core Concepts

日历（Calendar）：日程的容器。每个用户有一个主日历（primary calendar），也可以创建或订阅共享日历。
日程（Event）：日历中的单个事件条目，包含起止时间、地点、标题、参与人等属性。支持单次日程和重复日程，遵循RFC5545 iCalendar国际标准。
全天日程（All-day Event）: 只按日期占用、没有具体起止时刻的日程，结束日期是包含在日程时间内的。
日程实例（Instance）：日程的具体时间实例，本质是对日程的展开。普通日程和例外日程对应1个Instance，重复性日程对应N个Instance。在按时间段查询时，可通过实例视图将重复日程展开为独立的实例返回，以便在时间线上准确展示和管理。
重复规则（Rrule/Recurrence Rule）：定义重复性日程的重复规则，比如
```
FREQ=DAILY;UNTIL=20230307T155959Z;INTERVAL=14
```
表示每14天重复一次。
例外日程（Exception）：重复性日程中与原重复性日程不一致的日程。
参会人（Attendee）：日程的参与者，可以是用户、群、会议室资源、外部邮箱地址等。每个参与人有独立的RSVP状态。
响应状态（RSVP）：参与人对日程邀请的回复状态（接受/拒绝/待定）。
忙闲时间（FreeBusy）：查询用户在指定时间段的忙闲状态，用于会议时间协调。

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 (提醒)

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

Shortcuts（推荐优先使用）

Shortcuts (Recommended for Priority Use)

Shortcut 是对常用操作的高级封装（

lark-cli calendar +<verb> [flags]

）。有 Shortcut 的操作优先使用。

Shortcut	说明
`+agenda`	查看日程安排（默认今天）
`+create`	创建日程并邀请参会人（ISO 8601 时间）
`+freebusy`	查询用户主日历的忙闲信息和rsvp的状态
`+suggestion`	针对时间未确定的预约日程需求，提供多个时间推荐方案

Shortcuts are advanced encapsulations of common operations (

lark-cli calendar +<verb> [flags]

). Operations with Shortcuts should be used first.

Shortcut	Description
`+agenda`	View schedule arrangements (default to today)
`+create`	Create a schedule and invite attendees (ISO 8601 time)
`+freebusy`	Check the free/busy status of the user's primary calendar and RSVP status
`+suggestion`	Provide multiple time recommendation solutions for appointment schedule requests with undetermined times

+suggestion 使用

+suggestion Usage

在调用

+suggestion

之前，务必读取 lark-calendar-suggestion 中的使用说明，禁止直接调用命令。

bash

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里的成员推荐空闲时段

Before calling

+suggestion

, be sure to read the usage instructions in lark-calendar-suggestion. Do not call the command directly.

bash

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

bash

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

重要：使用原生 API 时，必须先运行
schema
查看
--data
/
--params
参数结构，不要猜测字段格式。

bash

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
```
— 创建共享日历
- ```
delete
```
  — 删除共享日历
- ```
get
```
  — 查询日历信息
- ```
list
```
  — 查询日历列表
- ```
patch
```
  — 更新日历信息
- ```
primary
```
  — 查询用户主日历
- ```
search
```
  — 搜索日历

```
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
```
— 删除日程参与人
- ```
create
```
  — 添加日程参与人
- ```
list
```
  — 获取日程参与人列表

```
batch_delete
```
— Delete event attendees
- ```
create
```
  — Add event attendees
- ```
list
```
  — Get event attendee list

events

```
create
```
— 创建日程
- ```
delete
```
  — 删除日程
- ```
get
```
  — 获取日程
- ```
instance_view
```
  — 查询日程视图
- ```
patch
```
  — 更新日程
- ```
search
```
  — 搜索日程

```
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
```
— 查询主日历日程忙闲信息

```
list
```
— Query free/busy information of primary calendar events

权限表

Permission Table

方法	所需 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`

注意（强制性）：

涉及日期（时间）字符串与时间戳的相互转换时，务必调用系统命令或脚本代码等外部工具进行处理，以确保转换的绝对准确。违者将导致严重的逻辑错误！

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 for processing to ensure absolute accuracy. Violations will lead to serious logical errors!