feishu-calendar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

飞书日历管理 (feishu-calendar)

Feishu Calendar Management (feishu-calendar)

🚨 执行前必读

🚨 Pre-execution Notes

✅ 时区固定：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@...
```

✅ Fixed Time Zone: Asia/Shanghai (UTC+8)
✅ Time Format: ISO 8601 / RFC 3339 (with time zone), e.g.,
```
2026-02-25T14:00:00+08:00
```
✅ Minimum Required for create: summary, start_time, end_time
✅ Highly Recommended: user_open_id: Obtain from SenderId (ou_xxx) to ensure the user can view the schedule
✅ ID Format Convention: User
```
ou_...
```
, Group
```
oc_...
```
, Meeting Room
```
omm_...
```
, Email
```
email@...
```

📋 快速索引：意图 → 工具 → 必填参数

📋 Quick Index: Intent → Tool → Required Parameters

用户意图	工具	action	必填参数	强烈建议	常用可选
创建会议	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[]	-	-
删除参会人	feishu_calendar_event_attendee	batch_delete	calendar_id, event_id, user_open_ids[]	-	-

User Intent	Tool	action	Required Parameters	Highly Recommended	Common Optional
Create Meeting	feishu_calendar_event	create	summary, start_time, end_time	user_open_id	attendees, description, location
Query Schedules in a Time Period	feishu_calendar_event	list	start_time, end_time	-	-
Modify Schedule Time	feishu_calendar_event	patch	event_id, start_time/end_time	-	summary, description
Search Meetings by Keyword	feishu_calendar_event	search	query	-	-
Reply to Invitation	feishu_calendar_event	reply	event_id, rsvp_status	-	-
Query Recurring Schedule Instances	feishu_calendar_event	instances	event_id, start_time, end_time	-	-
Query Free/Busy Status	feishu_calendar_freebusy	list	time_min, time_max, user_ids[]	-	-
Invite Attendees	feishu_calendar_event_attendee	create	calendar_id, event_id, attendees[]	-	-
Remove Attendees	feishu_calendar_event_attendee	batch_delete	calendar_id, event_id, user_open_ids[]	-	-

🎯 核心约束（Schema 未透露的知识）

🎯 Core Constraints (Knowledge Not Disclosed in Schema)

1. user_open_id 为什么必填？

1. Why is user_open_id required?

工具使用用户身份：日程创建在用户主日历上，用户本人能看到。

但为什么还要传 user_open_id：将发起人也添加为参会人，确保：

✅ 发起人会收到日程通知
✅ 发起人可以回复 RSVP 状态（接受/拒绝/待定）
✅ 发起人出现在参会人列表中
✅ 其他参会人能看到发起人

如果不传：

⚠️ 用户能看到日程，但不会作为参会人
⚠️ 如果只有其他参会人，发起人不在列表中（不符合常规逻辑）

Tool Uses User Identity: The schedule is created on the user's primary calendar, so the user can see it.

But why pass user_open_id?: Add the organizer as an attendee to ensure:

✅ The organizer receives schedule notifications
✅ The organizer can reply with RSVP status (accept/decline/tentative)
✅ The organizer appears in the attendee list
✅ Other attendees can see the organizer

If not passed:

⚠️ The user can see the schedule but will not be an attendee
⚠️ If only other attendees exist, the organizer is not in the list (does not conform to normal logic)

2. 参会人权限（attendee_ability）

2. Attendee Permissions (attendee_ability)

工具已默认设置

attendee_ability: "can_modify_event"

，参会人可以编辑日程和管理参与者。

权限值	能力
`none`	无权限
`can_see_others`	可查看参与人列表
`can_invite_others`	可邀请他人
`can_modify_event`	可编辑日程（推荐）

The tool is defaulted to

attendee_ability: "can_modify_event"

, allowing attendees to edit the schedule and manage participants.

Permission Value	Ability
`none`	No permissions
`can_see_others`	Can view the attendee list
`can_invite_others`	Can invite others
`can_modify_event`	Can edit the schedule (recommended)

3. 统一使用 open_id（ou_...格式）

3. Uniform Use of open_id (ou_... format)

✅ 创建日程：
```
user_open_id = SenderId
```
✅ 邀请参会人：
```
attendees[].id = "ou_xxx"
```
✅ 删除参会人：
```
user_open_ids = ["ou_xxx"]
```
（工具已优化，直接传 open_id 即可）

⚠️ ID 格式区分：

```
ou_xxx
```
：用户的 open_id（你应该使用的）
```
user_xxx
```
：日程内部的 attendee_id（list 接口返回，仅用于内部记录）

✅ Create Schedule:
```
user_open_id = SenderId
```
✅ Invite Attendees:
```
attendees[].id = "ou_xxx"
```
✅ Remove Attendees:
```
user_open_ids = ["ou_xxx"]
```
(optimized by the tool, directly pass open_id)

⚠️ ID Format Distinction:

```
ou_xxx
```
: User's open_id (you should use this)
```
user_xxx
```
: Internal attendee_id returned by the list interface (only for internal records)

4. 会议室预约是异步流程

4. Meeting Room Reservation is an Asynchronous Process

添加会议室类型参会人后，会议室进入异步预约流程：

API 返回成功 →
```
rsvp_status: "needs_action"
```
（预约中）
后台异步处理
最终状态：
```
accept
```
（成功）或
```
decline
```
（失败）

查询预约结果：使用

feishu_calendar_event_attendee.list

查看

rsvp_status

。

After adding a meeting room-type attendee, the meeting room enters an asynchronous reservation process:

API returns success →
```
rsvp_status: "needs_action"
```
(reserving)
Background processes asynchronously
Final status:
```
accept
```
(success) or
```
decline
```
(failure)

Query Reservation Result: Use

feishu_calendar_event_attendee.list

to check

rsvp_status

5. instances action 仅对重复日程有效

5. instances Action Only Works for Recurring Schedules

⚠️ 重要：

instances

action 仅对重复日程有效，必须满足：

event_id 必须是重复日程的 ID（该日程具有
```
recurrence
```
字段）
如果对普通日程调用，会返回错误

如何判断：

先用
```
get
```
action 获取日程详情
检查返回值中是否有
```
recurrence
```
字段且不为空
如果有，则可以调用
```
instances
```
获取实例列表

⚠️ Important: The

instances

action only works for recurring schedules, which must meet:

event_id must be the ID of a recurring schedule (the schedule has the
```
recurrence
```
field)
If called for a regular schedule, an error will be returned

How to Judge:

First use the
```
get
```
action to get schedule details
Check if the return value has a non-empty
```
recurrence
```
field
If yes, call
```
instances
```
to get the instance list

📌 使用场景示例

📌 Usage Scenario Examples

场景 1: 创建会议并邀请参会人

Scenario 1: Create a Meeting and Invite Attendees

json

{
  "action": "create",
  "summary": "项目复盘会议",
  "description": "讨论 Q1 项目进展",
  "start_time": "2026-02-25 14:00:00",
  "end_time": "2026-02-25 15:30:00",
  "user_open_id": "ou_aaa",
  "attendees": [
    {"type": "user", "id": "ou_bbb"},
    {"type": "user", "id": "ou_ccc"},
    {"type": "resource", "id": "omm_xxx"}
  ]
}

json

{
  "action": "create",
  "summary": "Project Retrospective Meeting",
  "description": "Discuss Q1 Project Progress",
  "start_time": "2026-02-25 14:00:00",
  "end_time": "2026-02-25 15:30:00",
  "user_open_id": "ou_aaa",
  "attendees": [
    {"type": "user", "id": "ou_bbb"},
    {"type": "user", "id": "ou_ccc"},
    {"type": "resource", "id": "omm_xxx"}
  ]
}

场景 2: 查询用户未来一周的日程

Scenario 2: Query a User's Schedules for the Next Week

json

{
  "action": "list",
  "start_time": "2026-02-25 00:00:00",
  "end_time": "2026-03-03 23:59:00"
}

json

{
  "action": "list",
  "start_time": "2026-02-25 00:00:00",
  "end_time": "2026-03-03 23:59:00"
}

场景 3: 查看多个用户的忙闲时间

Scenario 3: View Free/Busy Time of Multiple Users

json

{
  "action": "list",
  "time_min": "2026-02-25 09:00:00",
  "time_max": "2026-02-25 18:00:00",
  "user_ids": ["ou_aaa", "ou_bbb", "ou_ccc"]
}

注意：user_ids 是数组，支持 1-10 个用户。当前不支持会议室忙闲查询。

json

{
  "action": "list",
  "time_min": "2026-02-25 09:00:00",
  "time_max": "2026-02-25 18:00:00",
  "user_ids": ["ou_aaa", "ou_bbb", "ou_ccc"]
}

Note: user_ids is an array, supporting 1-10 users. Meeting room free/busy query is not currently supported.

场景 4: 修改日程时间

Scenario 4: Modify Schedule Time

json

{
  "action": "patch",
  "event_id": "xxx_0",
  "start_time": "2026-02-25 15:00:00",
  "end_time": "2026-02-25 16:00:00"
}

json

{
  "action": "patch",
  "event_id": "xxx_0",
  "start_time": "2026-02-25 15:00:00",
  "end_time": "2026-02-25 16:00:00"
}

场景 5: 搜索日程（按关键词）

Scenario 5: Search Schedules (by Keyword)

json

{
  "action": "search",
  "query": "项目复盘"
}

json

{
  "action": "search",
  "query": "Project Retrospective"
}

场景 6: 回复日程邀请

Scenario 6: Reply to Schedule Invitation

json

{
  "action": "reply",
  "event_id": "xxx_0",
  "rsvp_status": "accept"
}

json

{
  "action": "reply",
  "event_id": "xxx_0",
  "rsvp_status": "accept"
}

🔍 常见错误与排查

🔍 Common Errors and Troubleshooting

错误现象	根本原因	解决方案
发起人不在参会人列表中	未传 `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` 以上权限

Error Phenomenon	Root Cause	Solution
Organizer not in attendee list	Did not pass `user_open_id`	Highly recommended to pass `user_open_id = SenderId`
Attendees cannot see other attendees	Insufficient `attendee_ability` permissions	The tool is defaulted to `can_modify_event`
Incorrect time	Used Unix timestamp	Switch to ISO 8601 format (with time zone): `2024-01-01T00:00:00+08:00`
Meeting room shows "reserving"	Meeting room reservation is asynchronous	Wait a few seconds and query `rsvp_status` with `list`
Permission error when modifying schedule	Current user is not the organizer, and the schedule is not set with editable permissions	Ensure `attendee_ability: "can_modify_event"` is set when creating the schedule
Cannot view attendee list	Current user has no viewing permissions	Ensure you are the organizer or the schedule is set with permissions above `can_see_others`

📚 附录：背景知识

📚 Appendix: Background Knowledge

A. 日历架构模型

A. Calendar Architecture Model

飞书日历采用 三层架构：

日历（Calendar）
  └── 日程（Event）
       └── 参会人（Attendee）

关键理解：

用户主日历：日程创建在发起用户的主日历上，用户本人能看到
参会人机制：通过添加参会人（attendee），让其他人的日历中也显示此日程
权限模型：日程的
```
attendee_ability
```
参数控制参会人能否编辑日程、邀请他人、查看参与人列表

Feishu Calendar adopts a Three-tier Architecture:

Calendar
  └── Event
       └── Attendee

Key Understandings:

User Primary Calendar: The schedule is created on the organizer's primary calendar, so the user can see it
Attendee Mechanism: By adding attendees, the schedule is also displayed in other attendees' calendars
Permission Model: The schedule's
```
attendee_ability
```
parameter controls whether attendees can edit the schedule, invite others, or view the attendee list

B. 参会人类型

B. Attendee Types

```
type: "user"
```
+
```
id: "ou_xxx"
```
— 飞书用户（使用 open_id）
```
type: "chat"
```
+
```
id: "oc_xxx"
```
— 飞书群组
```
type: "resource"
```
+
```
id: "omm_xxx"
```
— 会议室

type: "third_party"

id: "email@example.com"

— 外部邮箱

```
type: "user"
```
+
```
id: "ou_xxx"
```
— Feishu User (use open_id)
```
type: "chat"
```
+
```
id: "oc_xxx"
```
— Feishu Group
```
type: "resource"
```
+
```
id: "omm_xxx"
```
— Meeting Room

type: "third_party"

id: "email@example.com"

— External Email

C. 日程的生命周期

C. Schedule Lifecycle

创建：在用户主日历上创建日程（工具使用用户身份）
邀请参会人：通过 attendee API 将日程分享给其他参会人
参会人回复：参会人可以 accept/decline/tentative
修改：组织者或有权限的参会人可以修改
删除：删除后状态变为
```
cancelled
```

Creation: Create a schedule on the user's primary calendar (tool uses user identity)
Invite Attendees: Share the schedule with other attendees via the attendee API
Attendee Reply: Attendees can accept/decline/tentative
Modification: The organizer or authorized attendees can modify it
Deletion: After deletion, the status becomes
```
cancelled
```

D. 日历类型说明

D. Calendar Type Description

类型	说明	能否删除	能否修改
`primary`	主日历（每个用户/应用一个）	❌ 否	✅ 是
`shared`	共享日历（用户创建并共享）	✅ 是	✅ 是
`resource`	会议室日历	❌ 否	❌ 否
`google`	绑定的 Google 日历	❌ 否	❌ 否
`exchange`	绑定的 Exchange 日历	❌ 否	❌ 否

Type	Description	Deletable	Editable
`primary`	Primary Calendar (one per user/app)	❌ No	✅ Yes
`shared`	Shared Calendar (created and shared by users)	✅ Yes	✅ Yes
`resource`	Meeting Room Calendar	❌ No	❌ No
`google`	Bound Google Calendar	❌ No	❌ No
`exchange`	Bound Exchange Calendar	❌ No	❌ No

E. 回复状态（rsvp_status）说明

E. RSVP Status (rsvp_status) Description

状态	含义（用户）	含义（会议室）
`needs_action`	未回复	预约中
`accept`	已接受	预约成功
`tentative`	待定	-
`decline`	拒绝	预约失败
`removed`	已被移除	已被移除

Status	Meaning (User)	Meaning (Meeting Room)
`needs_action`	Not replied	Reserving
`accept`	Accepted	Reservation successful
`tentative`	Tentative	-
`decline`	Declined	Reservation failed
`removed`	Removed	Removed

F. 使用限制（来自飞书 OAPI 文档）

F. Usage Limits (from Feishu OAPI Documentation)

每个日程最多 3000 名参会人
单次添加参会人上限：
- 用户类参会人：1000 人
- 会议室：100 个
主日历不可删除（type 为 primary 的日历）
会议室预约可能失败：
- 时间冲突
- 无预约权限
- 会议室配置限制

Maximum 3000 attendees per schedule
Single Attendee Addition Limit:
- User-type attendees: 1000 people
- Meeting Rooms: 100 rooms
Primary Calendar cannot be deleted (calendar type is primary)
Meeting Room Reservation May Fail:
- Time conflict
- No reservation permission
- Meeting room configuration restrictions