飞书日历管理（feishu-calendar）
一、用途 飞书日历与日程管理工具集，用于在飞书日历中管理日历、日程、参会人以及查询忙闲信息。
二、主要能力
- 日历管理：涉及日历与日程、参会人的三层架构。
- 日程管理：创建会议、查询某时间段日程、修改日程时间、按关键词搜索日程、回复日程邀请、查询重复日程实例。
- 参会人管理：邀请参会人，支持用户、群组、会议室、第三方邮箱等类型。
- 忙闲查询：查看多个用户的忙闲时间。
三、使用方式 时区固定为 Asia/Shanghai（UTC+8）。时间格式为 ISO 8601 / RFC 3339（带时区），例如 2026-02-25T14:00:00+08:00。create 最小必填 summary、start_time、end_time，强烈建议传入 user_open_id（从 SenderId 获取，ou_xxx），以确保用户能看到日程。ID 格式约定：用户 ou_...，群 oc_...，会议室 omm_...，邮箱 email@...。
工具与必填参数：
- feishu_calendar_event / create：必填 summary、start_time、end_time；强烈建议 user_open_id；常用可选 attendees、description、location。
- feishu_calendar_event / list：必填 start_time、end_time。
- feishu_calendar_event / patch：必填 event_id、start_time/end_time；可选 summary、description。
- feishu_calendar_event / search：必填 query。
- feishu_calendar_event / reply：必填 event_id、rsvp_status。
- feishu_calendar_event / instances：必填 event_id、start_time、end_time。
- feishu_calendar_freebusy / list：必填 time_min、time_max、user_ids[]。
- feishu_calendar_event_attendee / create：必填 calendar_id、event_id、attendees[]。
核心约束：user_open_id 用于将发起人也添加为参会人，确保发起人收到日程通知、可回复 RSVP、出现在参会人列表中、其他参会人能看到发起人；不传则用户能看到日程但不会作为参会人。参会人权限 attendee_ability 已默认设为 can_modify_event，参会人可编辑日程和管理参与者；权限值包括 none、can_see_others、can_invite_others、can_modify_event。统一使用 open_id（ou_...），注意 ou_xxx 为用户 open_id，user_xxx 为日程内部 attendee_id（仅用于内部记录）。会议室预约是异步流程，添加会议室类型参会人后 API 返回成功且 rsvp_status 为 needs_action（预约中），后台异步处理，最终为 accept（成功）或 decline（失败），可用 feishu_calendar_event_attendee.list 查看 rsvp_status。instances 仅对重复日程有效，需先用 get 获取详情并检查 recurrence 字段非空。
四、适用场景示例 场景 1：创建会议并邀请参会人，传 summary、description、start_time、end_time、user_open_id 及 attendees（含用户与会议室）。 场景 2：查询用户未来一周的日程（list，传 start_time、end_time）。 场景 3：查看多个用户的忙闲时间（feishu_calendar_freebusy list，user_ids 数组支持 1-10 个用户，当前不支持会议室忙闲查询）。 场景 4：修改日程时间（patch，传 event_id 与新的 start_time、end_time）。 场景 5：按关键词搜索日程（search，传 query）。 场景 6：回复日程邀请（reply，传 event_id 与 rsvp_status）。
五、常见错误与排查 发起人不在参会人列表中：未传 user_open_id，建议传 user_open_id = SenderId。 参会人看不到其他参会人：attendee_ability 权限不足，工具已默认设置 can_modify_event。 时间不对：使用了 Unix 时间戳，应改用 ISO 8601 格式（带时区），如 2024-01-01T00:00:00+08:00。 会议室显示“预约中”：会议室预约是异步的，等待几秒后用 list 查询 rsvp_status。 修改日程报权限错误：当前用户不是组织者且日程未设置可编辑权限，确保创建时设置了 attendee_ability: can_modify_event。 无法查看参会人列表：当前用户无查看权限，确保是组织者或日程设置了 can_see_others 以上权限。
六、背景知识 日历架构模型为三层：日历（Calendar）- 日程（Event）- 参会人（Attendee）。用户主日历上创建日程，用户本人可见；通过添加参会人让其他人的日历也显示此日程；attendee_ability 控制参会人能否编辑日程、邀请他人、查看参与人列表。 参会人类型：type user + id ou_xxx（飞书用户，open_id）；type chat + id oc_xxx（飞书群组）；type resource + id omm_xxx（会议室）；type third_party + id email@example.com（外部邮箱）。 日程生命周期：创建、邀请参会人、参会人回复、修改、删除（删除后状态变为 cancelled）。 日历类型与可否删除/修改：primary 主日历不可删除、可修改；shared 共享日历可删除、可修改；resource 会议室日历不可删除、不可修改；google 绑定的 Google 日历不可删除、不可修改；exchange 绑定的 Exchange 日历不可删除、不可修改。 回复状态 rsvp_status：needs_action（用户未回复／会议室预约中）、accept（已接受／预约成功）、tentative（待定）、decline（拒绝／预约失败）、removed（已被移除）。 使用限制（来自飞书 OAPI 文档）：每个日程最多 3000 名参会人；单次添加参会人上限用户类 1000 人、会议室 100 个；主日历（type 为 primary）不可删除；会议室预约可能因时间冲突、无预约权限、会议室配置限制而失败。
七、限制 时区固定为 Asia/Shanghai（UTC+8）；时间需使用带时区的 ISO 8601 / RFC 3339 格式；instances 仅对重复日程有效；忙闲查询当前不支持会议室；会议室预约为异步，结果需另行查询。其他未在资料中说明的能力暂未提供。