Lark Calendar

calendar (v4)

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

核心场景

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

1. 预约日程

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

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

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

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

预约日程的工作流：

1. 智能推断默认值

• 标题，参与人，时长均存在默认值，无需频繁的和用户确认。
• 参会人：如未明确指定其他人，默认参会人仅为用户自己。当搜索特定参与人（人、群、会议室）出现多个结果无法唯一确定时，必须询问用户进行选择确认，并将该偏好记录为长期记忆，以便后续自动识别。
• 会议室：目前不支持主动预定会议室，除非当前上下文中已经存在对应的会议室ID(omm_ 前缀) 且需要添加到日程中。
• 标题：根据对话上下文自动生成（例如“沟通对齐”或“需求讨论”），如无法推断则默认为“会议”。
• 时长：基于会议类型和上下文动态推断（例如：“评审/汇报”推断为 60 分钟等），如无法推断，则默认为 30 分钟。

2. 时间建议与辅助决策（核心体验）

• 有明确时间点（如明早10点）：调用相关工具（如 lark-cli calendar +freebusy lark-calendar-freebusy）先查询该时间段参会人的忙闲状态（注：若参会人已有日程的 RSVP 状态为拒绝，则认为该时段为空闲）。若均无冲突，直接进入下一步确认并创建；若有冲突，提示用户冲突情况并询问是否继续创建或重新选择时间。
• 有时间区间（如明天、下午、本周）：调用相关工具（如 lark-cli calendar +suggestion lark-calendar-suggestion）获取该区间内所有参会人的多个时间推荐方案供用户选择。必须在用户确认方案后，才能执行创建日程操作；且用户一旦选择了推荐的方案，无需再次查询忙闲信息。
• 无任何时间信息：默认推断一个合理区间（如“今天”或“近两天”），并同样获取多个时间推荐方案供用户快速选择。
• 生活类需求（如健身、游泳、遛弯、约饭、奶茶等，注意“约咖啡”算工作场景）：预期不调用 suggestion 工具。应自行推断合适的非工作时间给到用户确认。如果无法推断，请尝试主动询问用户，并在用户给出反馈后形成记忆，以便后续直接应用。
• 模糊语义消解与长期记忆构建 (Aha Moment)：针对用户专属的时间表达习惯（如“上班后”、“下班前”）或存在歧义的时间场景（如未指明上下午的12小时制），严禁主观臆断。应通过主动澄清明确真实意图，并将此类个性化定义沉淀为长期偏好，推动系统认知能力的持续进化，最终实现“下次即懂”的智能化体验。

3. 非阻断式执行

• 待用户确认具体时间选项后，执行 lark-cli calendar +create --summary "..." --start "..." --end "..." --attendee-ids ...

4. 友好反馈

• 报告结果：返回创建成功的日程摘要信息

核心概念

• 日历（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 (日历)
└── Event (日程)
    ├── Attendee (参会人)
    └── Reminder (提醒)

Shortcuts（推荐优先使用）

Shortcut 是对常用操作的高级封装（lark-cli calendar +<verb> [flags]）。有 Shortcut 的操作优先使用。

+suggestion 使用

在调用 +suggestion 之前，务必读取 lark-calendar-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>   # 调用 API 前必须先查看参数结构
lark-cli calendar <resource> <method> [flags] # 调用 API

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

calendars

• create — 创建共享日历
• delete — 删除共享日历
• get — 查询日历信息
• list — 查询日历列表
• patch — 更新日历信息
• primary — 查询用户主日历
• search — 搜索日历

event.attendees

• batch_delete — 删除日程参与人
• create — 添加日程参与人
• list — 获取日程参与人列表

events

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

freebusys

• list — 查询主日历日程忙闲信息

权限表

注意（强制性）：

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

calendar +agenda

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

查看近期日程安排。只读操作，不修改任何日程。

需要的scopes: ["calendar:calendar.event:read"]

命令

# 查看今天日程（默认）
lark-cli calendar +agenda

# 自定义时间范围（ISO 8601）
lark-cli calendar +agenda --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"

# 自定义时间范围（仅日期）
lark-cli calendar +agenda --start 2026-03-10 --end 2026-03-17

# 人类可读格式输出
lark-cli calendar +agenda --format pretty

# 指定日历
lark-cli calendar +agenda --calendar-id cal_xxx

参数

时间格式

--start 和 --end 支持以下格式：

输出格式

将结果整理为易读的日程表：

## 2026-03-10 周一

09:00 - 09:30  站会
10:00 - 11:00  产品评审
14:00 - 15:00  与 Alice 1:1

## 2026-03-11 周二

（无日程）

注意：按日期分组，并严格按照开始时间升序（从早到晚的时间线）排序输出。 显示标题、时长、忙闲状态和rsvp状态。

提示

• 已取消的日程会自动过滤，无需额外处理。
• 如无日程，告知用户"日程清空"。
• 大于 40 天的时间范围会自动拆分查询并合并结果。
• 查看多个日历：先用 lark-cli calendar calendars list --page-all 列出日历列表，再逐个查询。

参考

• lark-calendar -- 日历全部命令
• lark-shared -- 认证和全局参数

calendar +create

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

创建日程并按需邀请参会人。

需要的scopes: ["calendar:calendar.event:create","calendar:calendar.event:update"]

推荐命令

# 创建日程 + 邀请参会人（ISO 8601 时间）
lark-cli calendar +create \
  --summary "产品评审" \
  --start "2026-03-12T14:00+08:00" \
  --end "2026-03-12T15:00+08:00" \
  --attendee-ids ou_aaa,ou_bbb

# 无参会人
lark-cli calendar +create \
  --summary "午餐" \
  --start "2026-03-12T12:00+08:00" \
  --end "2026-03-12T13:00+08:00"

# 指定日历
lark-cli calendar +create --summary "..." --start "..." --end "..." \
  --calendar-id cal_xxx

参数：

自动设置 attendee_ability: "can_modify_event"，参会人可查看彼此并编辑日程。

自动设置 free_busy_status: "busy"，默认日程忙闲状态为忙碌。

自动设置 reminders: [{"minutes": 5}]，默认日程开始前 5 分钟提醒。

失败保护：若添加参会人失败（如 open_id 错误），CLI 会自动删除刚创建的空日程（回滚，不通知参会人）。

高级用法（完整 API 命令）

如需配置 location（地理位置，不含会议室位置）、visibility（日程公开范围）、自定义 reminders（提醒设置）、自定义 attendee_ability（参与人权限）、自定义 free_busy_status（日程忙闲状态）、参与人可选参加状态或全天日程等高级参数，请使用完整的 API 命令： 注意：

• 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天。如果只有一天的话，开始日期和结束日期是相同。

# 第一步：创建日程（含高级参数）
## 查看完整参数定义
lark-cli schema calendar.events.create
## 创建日程
lark-cli calendar events create --calendar-id primary --data '{
  "summary": "产品评审",
  "description": "本周分享主题：CLI 架构设计",
  "start_time": { "timestamp": "1741586400" },
  "end_time": { "timestamp": "1741593600" },
  "location": { "name": "5F-大会议室" },
  "attendee_ability": "can_modify_event",
  "reminders": [{ "minutes": 15 }]
}'

# 第二步：添加参会人（使用第一步返回的 calendar_id 和 event_id）
## 查看完整参数定义
lark-cli schema calendar.event.attendees.create
## 添加参会人
lark-cli calendar event.attendees create \
  --calendar-id <CALENDAR_ID> --event-id <EVENT_ID> \
  --data '{"attendees": [{"type": "user", "user_id": "ou_xxx"}]}'

# 可选第三步（推荐）：若第二步失败，回滚删除空日程
## 查看完整参数定义
lark-cli schema calendar.events.delete
## 删除空日程
lark-cli calendar events delete \
  --calendar-id <CALENDAR_ID> --event-id <EVENT_ID> \
  --params '{"need_notification":false}'

完整 API 命令的时间参数是 Unix 秒字符串（非 ISO 8601）。

当你手动拆成两步执行时，建议保留“失败后回滚删除”的第三步，避免遗留空日程。

参会人类型

[!CAUTION]

这是写入操作 -- 执行前必须确认用户意图。

参考

• lark-calendar -- 日历全部命令
• lark-shared -- 认证和全局参数
• lark-calendar-suggestion -- 智能推荐空闲时段

calendar +freebusy

前置条件： 先阅读 `../lark-shared/SKILL.md`。

查询用户主日历的忙闲信息，返回指定时间范围内的忙碌时段列表和rsvp的状态。

需要的scopes: ["calendar:calendar.free_busy:read"]

命令

# 查询当前用户今天的忙闲（默认）
lark-cli calendar +freebusy

# 自定义时间范围（仅日期）
lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12

# 自定义时间范围（完整 ISO 8601）
lark-cli calendar +freebusy --start "2026-03-11T08:00:00+08:00" --end "2026-03-11T18:00:00+08:00"

# 查询指定用户的忙闲信息
lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx

# 人类可读格式输出
lark-cli calendar +freebusy --format pretty

参数

时间格式

--start 和 --end 支持以下格式：

输出示例

表格格式

start             end               rsvp_status
----------------  ----------------  -----------
2026-03-11 10:00  2026-03-11 10:30  接受
2026-03-11 14:00  2026-03-11 15:00  待定

共 2 个忙碌时段

JSON 格式

[
  {
    "start_time": "2026-03-11T10:00:00+08:00",
    "end_time": "2026-03-11T10:30:00+08:00",
    "rsvp_status": "accept"
  },
  {
    "start_time": "2026-03-11T14:00:00+08:00",
    "end_time": "2026-03-11T15:00:00+08:00",
    "rsvp_status": "tentative"
  }
]

典型场景

1. 查找日程会议空闲时段

# 查询今天的忙碌时段
lark-cli calendar +freebusy

# 查询工作时间段
lark-cli calendar +freebusy \
  --start "2026-03-11T08:00:00+08:00" \
  --end "2026-03-11T18:00:00+08:00"

2. 检查团队成员可用性

# 查询多个成员，对比找出共同空闲时间
lark-cli calendar +freebusy --start 2026-03-12 --user-id ou_member_a
lark-cli calendar +freebusy --start 2026-03-12 --user-id ou_member_b

注意事项

1. 只查询主日历 — 此命令只返回用户主日历的忙闲信息，不包括其他订阅日历 2. 隐私保护 — 只返回忙碌时段的起止时间，不包含日程标题、描述等详细信息 3. bot 身份 — bot 必须通过 --user-id 指定要查询的用户

与其他命令对比

选择建议：

• 仅需了解是否有空 → 使用 +freebusy（更快，隐私保护）
• 需要查看日程详情 → 使用 +agenda

参考

• lark-calendar-agenda — 查看日程安排
• lark-calendar-create — 创建日程
• lark-calendar-suggestion — 针对时间未确定的预约日程需求，提供多个时间推荐方案
• lark-calendar — 日历完整 API

calendar +suggestion

前置条件： 先阅读 `../lark-shared/SKILL.md`。

针对时间未确定的预约日程需求，提供多个时间推荐方案，用户可以根据需要选择方案，解决协调会议时间的难题。

调用时机 (Agent Guidance):

• ✅ 当用户意图是预约日程，但时间未完全确定（如今天、近三天、本周、下午, 无时间描述）时，调用此工具来获取推荐时间块给用户选择。
• ❌ 当用户已经明确了具体的时间点（如今天下午3点），则不需要调用此工具，应直接调用 lark-cli calendar +create 工具创建日程。

需要的scopes: ["calendar:calendar.free_busy:read"]

命令

# 获取默认的时间推荐方案（搜索范围：当前时刻至当天结束）
lark-cli calendar +suggestion

# 获取指定时间区间内的推荐方案（支持日期简写或完整 ISO 8601）
lark-cli calendar +suggestion \
  --start "2026-03-19" \
  --end "2026-03-20"

# 结合参与人及会议时长获取推荐方案（时长单位：分钟）
# --attendee-ids 支持传入用户（ou_ 前缀）和群组（oc_ 前缀）混合列表
lark-cli calendar +suggestion \
  --start "2026-03-19T14:00:00+08:00" \
  --end "2026-03-19T18:00:00+08:00" \
  --attendee-ids ou_xxx,oc_yyy \
  --duration-minutes 60

# 排除特定时间段
lark-cli calendar +suggestion \
  --start "2026-03-19T08:00:00+08:00" \
  --end "2026-03-19T18:00:00+08:00" \
  --exclude "2026-03-19T12:00:00+08:00~2026-03-19T13:00:00+08:00"

# JSON 格式输出
lark-cli calendar +suggestion \
  --start "2026-03-19T08:00:00+08:00" \
  --end "2026-03-19T18:00:00+08:00" \
  --format json

参数

时间格式

--start、--end 以及 --exclude 支持以下格式自动解析：

输出格式

将推荐结果整理为易读的选项列表，并附上润色后的推荐理由：

## 2026-03-19 周四

- **选项 1：10:00 - 10:30**
  推荐理由：所有参与者均空闲。

AI 行为指导：

- 结构化展示选项与理由：以清晰的列表呈现推荐时间方案，并直接询问用户意向。必须结合“用户原始需求”与“推荐理由”说明每个时间块的优势，输出话术需简明、直接、无歧义。

- 如实反馈冲突情况：注意，返回的推荐方案不一定都是完全空闲的（即使明确要求找空闲时间，系统在难以满足时也会返回包含忙闲冲突的方案）。判断推荐方案是否完全空闲，可以从推荐理由中是否表达了“完全空闲”或“没有任何忙闲冲突”来判断。如果推荐方案存在忙闲冲突，必须在展示方案时向用户如实说明冲突情况，绝不能误导用户认为是完全空闲。

- 主动提供优化建议：当满足以下任一条件时（1. 返回结果包含 ai_action_guidance 字段内容；2. 用户要求找个空闲时间，但所有推荐方案都不是完全空闲的），你必须主动提供优化建议。若存在 ai_action_guidance 字段，需严格依据其核心意图生成引导话术；否则，请基于实际冲突情况主动提供合理的替代方案（如：建议调整时间范围、会议时长或参与人）。

典型场景

1. 查找多人的共同空闲会议时间

# 指定两名参与人，并要求找一个 45 分钟的空闲时段
lark-cli calendar +suggestion \
  --start "2026-03-19T08:00:00+08:00" \
  --end "2026-03-19T18:00:00+08:00" \
  --attendee-ids ou_member_a,ou_member_b \
  --duration-minutes 45

2. 用户对当前推荐不满意，要求“换一批”

# 将上一次推荐的时段作为排除条件传入
lark-cli calendar +suggestion \
  --start "2026-03-19T08:00:00+08:00" \
  --end "2026-03-19T18:00:00+08:00" \
  --exclude "2026-03-19T10:00:00+08:00~2026-03-19T10:30:00+08:00"

与其他命令对比

选择建议：

• 寻找开会时间 → 优先使用 +suggestion，直接获取智能推荐方案
• 了解个人当前忙碌情况 → 使用 +freebusy

参考

• lark-calendar-create — 创建日程
• lark-calendar-freebusy — 查询忙闲时段和rsvp状态
• lark-calendar — 日历完整 API