lark-calendar

calendar (v4)

开始前先读 ../lark-shared/SKILL.md（认证、权限处理）。

CRITICAL — 凡涉及预约日程/会议室、调整时间或查询/搜索会议室，第一步 MUST 读 references/lark-calendar-schedule-meeting.md [blocked]。仅编辑字段（改标题/描述）或增删参会人（不涉及时间和会议室）时可跳过，直接读 references/lark-calendar-update.md [blocked]。

身份

按日程归属选身份：

• 查看/管理登录用户本人的日程 → --as user（默认，绝大多数场景）。
• 查看/管理 bot 自己创建/拥有的日程 → --as bot

对话人称映射：「我」= 登录用户，「你」= 应用（bot）；作为字段取值的人称（参会人、会议 owner 等）不参与身份判定，如「你创建日程，邀请我、会议 owner 为我」→ --as bot 创建，登录用户仅作参会人与会议 owner。

# 用户本人日程 → user
lark-cli calendar +agenda --as user
# bot 自建或参与的日程 → bot
lark-cli calendar +agenda --as bot

Shortcuts

+get — 单日程详情

通过 calendar_id + event_id 获取单个日程详情。

# calendar_id不传，默认primary
lark-cli calendar +get --calendar-id <

日程描述统一使用 description 一个字段，按 Markdown 富文本处理。读取日程时 description 返回 Markdown 富文本（仅有纯文本描述时返回该纯文本）；创建/更新日程时也通过 --description 传入 Markdown。

+get 返回不含参会人和会议室。需要参与人视角（用户 / 会议室 / 群 / 三方邮箱）请调用 +list-attendees [blocked]。

+search-event — 按关键词、时间范围和参会人搜索日程

仅返回基础字段（event_id/summary/start/end 等），需要详情请走 +get。

--attendee-ids 的多值语义：同类型内为 OR（并集）——只要日程命中列表中的任意一个同类型 ID，就会返回。

• --attendee-ids "ou_A,ou_B" = A 或 B 参加的日程（不是 A 和 B 都参加的）。

+delete — 删除日程

+agenda — 查看近期日程安排

默认查询当天。结果应整理为按日期分组、按开始时间升序的易读时间线。

注意：

• 已取消的日程自动过滤；无日程时直接告知"日程清空"。
• 时间范围超过 40 天会自动拆分查询并合并结果。

+freebusy — 查询主日历忙闲时段 / 事件 / 公共空闲

+freebusy 一个入口承担四种视角：几何计算类（busy / free / common_free）走自动合并；事件维度类（raw_busy）保留每条上游日程 + rsvp_status。

用法提示：

• +freebusy 只适用于查询忙碌/空闲时间段这一事实。如果目标是"给会议推荐一个合适的时间段"（单人或多人），必须优先使用 +suggestion [blocked]——它会综合工作时间段、忙碌时间段、休息时间段来推荐，+freebusy 只回答"哪些区间空着"，不判断该区间是否适合排会。
• 多人公共空闲：只想拿"哪些区间共同没被占"→ --type common_free [--min-duration <dur>]；想拿"推荐的会议时间段"→ 走 +suggestion。

前置条件路由

先判断是否重复性日程：若操作对象是重复性日程，必须先读 重复性日程操作规范 [blocked]，并在用户未明确范围时先确认「仅此次/全部/此次及后续」（不要默认仅此次），再按下表进入具体操作流程。

写操作反馈

创建、更新、删除、RSVP 等写操作完成后，直接基于命令返回结果反馈用户；不要为了“确认是否生效”主动发起二次查询。只有用户明确要求复查，或命令返回信息不足以回答用户问题时，才需要再查询。

核心概念

• 日程实例（Instance）：重复性日程展开后的具体时间实例。「仅此次」操作时使用具体实例的 event_id；「全部」或「此次及后续」操作时需对原重复性日程操作（使用原日程 event_id），并按需处理例外。
• 重复性日程例外（Exception）：对重复性日程某次实例做过「仅此次」编辑后产生的独立日程（拥有独立 event_id）。删除/更新「全部」时必须同时处理例外，否则例外会残留。
• 全天日程（All-day Event）：只按日期占用、没有具体起止时刻的日程，结束日期是包含在日程时间内的。
• 时间块 vs 时间范围：时间块是具体确定的连续时间段（如 14:00~15:00），时间范围是泛指（如"今天下午"）。+room-find 必须基于确定时间块，不能基于模糊范围。
• 会议室（Room）："room"不是"房间"，是"会议室"。会议室是日程的一种参与人（resource attendee），不能脱离日程单独预定。
• 日程会议 ID（Meeting ID）：日程的历史视频会议 ID，在日程上开过视频会议才会有。
• 日程分享链接 vs 会议链接：两者是不同事物，不可混用。
  • 日程分享链接：https://<domain>/calendar/share?token=<token>，指向日程本身，用于分享日程详情。分享日程给某个人、某个群或粘贴到文档中，需要的都是这个日程分享链接（通过 calendar events share_info 获取），不是 applink；禁止自己拼接 applink 或用 applink 代替。
  • 会议链接：https://<domain>/j/<number>，指向视频会议入口；同一重复性日程序列的所有实例共用同一个会议链接。

术语映射

用户日常说的"帮我约个日历""查一下今天的日历"，实际意图是针对**日程（Event）**的创建或查询，而非操作日历（Calendar）容器本身。自动将口语化的"日历"意图映射为"日程"操作。

意图路由

日程与会议的关系：用户口中的「会议」通常不区分日程和视频会议。定义、三种查询意图（当前/未来/过去）的分流规则见 日程与视频会议的关系 [blocked]。

任务类型分流

处理"预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间"时，必须先判断新建 vs 编辑：

• 编辑已有日程的强信号：用户提到已存在的日程锚点（标题、时间段、这个日程、这场会）并表达修改动作（添加、移除、改到、换会议室、调整时间）。默认走编辑流，绝不能按新建处理。
• 新建日程：用户表达新增意图（"新约一个会""创建一个日程""安排一次会议"），且没有指向既有日程的修改动作。

时间推断规范

• 星期的定义：周一是一周的第一天，周日是最后一天。计算"下周一"等相对日期时，基于当前真实日期推算。
• 一天的范围：用户提到"明天""今天"等泛指某天时，时间范围应覆盖整天，不要自行缩减。
• 历史时间约束：不能预约已经完全过去的时间。唯一例外是"跨越当前时间"的日程（开始在过去、结束在未来）。

会议室规则

• 凡是"预定/查询/搜索可用会议室"，都必须进入 schedule-meeting 工作流 [blocked]，会议室参数规范详见 +room-find [blocked]。
• +room-find 的时间输入必须是确定时间块，不能是时间区间搜索。
• 用户仅要求"查会议室"但未提供明确时间时，必须先调用 +suggestion 获取可用时间块，再将时间块交给 +room-find。严禁猜测时间盲目调用。
• 编辑已有日程时，"添加会议室"默认是增量语义，保留已有会议室；只有用户明确说"更换会议室""移除会议室"时才删除旧会议室。

API Resources

calendar_id 可以直接传 primary，代表当前调用身份的主日历 ID。

查询资源的方法列表以及方法的使用方式

• 列出某资源下的方法：lark-cli calendar <resource> -h
• 查看方法的cli flag：lark-cli calendar <resource> <method> -h
• 查看方法API参数：lark-cli schema calendar.<resource>.<method>

<resource> 为 calendars（日历本身）/ events（日程）/ event.attendees（参与人）/ freebusys（忙闲）。例：lark-cli schema calendar.events.delete。

常用其他域命令

搜索用户/群不支持 bot 身份，必须用 --as user。解析不到或类型不明确时，向用户澄清该参会人类型，不要靠名字形态硬猜类型。

不在本 skill 范围

• 查询过去的视频会议记录 → lark-meeting
• 待办任务管理 → lark-task
• 通讯录 → lark-contact
• 即时通讯 → lark-im
• 会议室物理设施管理 → 管理员后台

注意（强制性）：

• 涉及日期（时间）字符串与时间戳的相互转换时，务必调用系统命令或脚本代码等外部工具进行处理，以确保转换的绝对准确；换算禁止依赖容器默认时区（常为 UTC，会导致 8 小时偏移），必须显式指定目标时区。违者将导致严重的逻辑错误！