feishu-calendar

Name: feishu-calendar
Author: op7418

2installs665forks

How to install feishu-calendar?

op7418/codepilot/feishu-calendar

$npx -y skills add op7418/CodePilot --skill feishu-calendar

Installs into the current project.

Summary

飞书日历与日程管理工具集。包含日历管理、日程管理、参会人管理、忙闲查询。

Files · 1

View on GitHub

SKILL.md

1	# 飞书日历管理 (feishu-calendar)
2
3	## 🚨 执行前必读
4
5	- ✅ 时区固定：Asia/Shanghai（UTC+8）
6	- ✅ 时间格式：ISO 8601 / RFC 3339（带时区），例如 `2026-02-25T14:00:00+08:00`
7	- ✅ create 最小必填：summary, start_time, end_time
8	- ✅ user_open_id 强烈建议：从 SenderId 获取（ou_xxx），确保用户能看到日程
9	- ✅ ID 格式约定：用户 `ou_...`，群 `oc_...`，会议室 `omm_...`，邮箱 `email@...`
10
11	---
12
13	## 📋 快速索引：意图 → 工具 → 必填参数
14
15	\| 用户意图 \| 工具 \| action \| 必填参数 \| 强烈建议 \| 常用可选 \|
16	\|---------\|------\|--------\|---------\|---------\|---------\|
17	\| 创建会议 \| feishu_calendar_event \| create \| summary, start_time, end_time \| user_open_id \| attendees, description, location \|
18	\| 查某时间段日程 \| feishu_calendar_event \| list \| start_time, end_time \| - \| - \|
19	\| 改日程时间 \| feishu_calendar_event \| patch \| event_id, start_time/end_time \| - \| summary, description \|
20	\| 搜关键词找会 \| feishu_calendar_event \| search \| query \| - \| - \|
21	\| 回复邀请 \| feishu_calendar_event \| reply \| event_id, rsvp_status \| - \| - \|
22	\| 查重复日程实例 \| feishu_calendar_event \| instances \| event_id, start_time, end_time \| - \| - \|
23	\| 查忙闲 \| feishu_calendar_freebusy \| list \| time_min, time_max, user_ids[] \| - \| - \|
24	\| 邀请参会人 \| feishu_calendar_event_attendee \| create \| calendar_id, event_id, attendees[] \| - \| - \|
25	\| 删除参会人 \| feishu_calendar_event_attendee \| batch_delete \| calendar_id, event_id, user_open_ids[] \| - \| - \|
26
27	---
28
29	## 🎯 核心约束（Schema 未透露的知识）
30
31	### 1. user_open_id 为什么必填？
32
33	工具使用用户身份：日程创建在用户主日历上，用户本人能看到。
34
35	但为什么还要传 user_open_id：将发起人也添加为参会人，确保：
36	- ✅ 发起人会收到日程通知
37	- ✅ 发起人可以回复 RSVP 状态（接受/拒绝/待定）
38	- ✅ 发起人出现在参会人列表中
39	- ✅ 其他参会人能看到发起人
40
41	如果不传：
42	- ⚠️ 用户能看到日程，但不会作为参会人
43	- ⚠️ 如果只有其他参会人，发起人不在列表中（不符合常规逻辑）
44
45	### 2. 参会人权限（attendee_ability）
46
47	工具已默认设置 `attendee_ability: "can_modify_event"`，参会人可以编辑日程和管理参与者。
48
49	\| 权限值 \| 能力 \|
50	\|--------\|------\|
51	\| `none` \| 无权限 \|
52	\| `can_see_others` \| 可查看参与人列表 \|
53	\| `can_invite_others` \| 可邀请他人 \|
54	\| `can_modify_event` \| 可编辑日程（推荐） \|
55
56	### 3. 统一使用 open_id（ou_...格式）
57
58	- ✅ 创建日程：`user_open_id = SenderId`
59	- ✅ 邀请参会人：`attendees[].id = "ou_xxx"`
60	- ✅ 删除参会人：`user_open_ids = ["ou_xxx"]`（工具已优化，直接传 open_id 即可）
61
62	⚠️ ID 格式区分：
63	- `ou_xxx`：用户的 open_id（你应该使用的）
64	- `user_xxx`：日程内部的 attendee_id（list 接口返回，仅用于内部记录）
65
66	### 4. 会议室预约是异步流程
67
68	添加会议室类型参会人后，会议室进入异步预约流程：
69	1. API 返回成功 → `rsvp_status: "needs_action"`（预约中）
70	2. 后台异步处理
71	3. 最终状态：`accept`（成功）或 `decline`（失败）
72
73	查询预约结果：使用 `feishu_calendar_event_attendee.list` 查看 `rsvp_status`。
74
75	### 5. instances action 仅对重复日程有效
76
77	⚠️ 重要：`instances` action 仅对重复日程有效，必须满足：
78	1. event_id 必须是重复日程的 ID（该日程具有 `recurrence` 字段）
79	2. 如果对普通日程调用，会返回错误
80
81	如何判断：
82	1. 先用 `get` action 获取日程详情
83	2. 检查返回值中是否有 `recurrence` 字段且不为空
84	3. 如果有，则可以调用 `instances` 获取实例列表
85
86	---
87
88	## 📌 使用场景示例
89
90	### 场景 1: 创建会议并邀请参会人
91
92	```json
93	{
94	"action": "create",
95	"summary": "项目复盘会议",
96	"description": "讨论 Q1 项目进展",
97	"start_time": "2026-02-25 14:00:00",
98	"end_time": "2026-02-25 15:30:00",
99	"user_open_id": "ou_aaa",
100	"attendees": [
101	{"type": "user", "id": "ou_bbb"},
102	{"type": "user", "id": "ou_ccc"},
103	{"type": "resource", "id": "omm_xxx"}
104	]
105	}
106	```
107
108	### 场景 2: 查询用户未来一周的日程
109
110	```json
111	{
112	"action": "list",
113	"start_time": "2026-02-25 00:00:00",
114	"end_time": "2026-03-03 23:59:00"
115	}
116	```
117
118	### 场景 3: 查看多个用户的忙闲时间
119
120	```json
121	{
122	"action": "list",
123	"time_min": "2026-02-25 09:00:00",
124	"time_max": "2026-02-25 18:00:00",
125	"user_ids": ["ou_aaa", "ou_bbb", "ou_ccc"]
126	}
127	```
128
129	注意：user_ids 是数组，支持 1-10 个用户。当前不支持会议室忙闲查询。
130
131	### 场景 4: 修改日程时间
132
133	```json
134	{
135	"action": "patch",
136	"event_id": "xxx_0",
137	"start_time": "2026-02-25 15:00:00",
138	"end_time": "2026-02-25 16:00:00"
139	}
140	```
141
142	### 场景 5: 搜索日程（按关键词）
143
144	```json
145	{
146	"action": "search",
147	"query": "项目复盘"
148	}
149	```
150
151	### 场景 6: 回复日程邀请
152
153	```json
154	{
155	"action": "reply",
156	"event_id": "xxx_0",
157	"rsvp_status": "accept"
158	}
159	```
160
161	---
162
163	## 🔍 常见错误与排查
164
165	\| 错误现象 \| 根本原因 \| 解决方案 \|
166	\|---------\|---------\|---------\|
167	\| 发起人不在参会人列表中 \| 未传 `user_open_id` \| 强烈建议传 `user_open_id = SenderId` \|
168	\| 参会人看不到其他参会人 \| `attendee_ability` 权限不足 \| 工具已默认设置 `can_modify_event` \|
169	\| 时间不对 \| 使用了 Unix 时间戳 \| 改用 ISO 8601 格式（带时区）：`2024-01-01T00:00:00+08:00` \|
170	\| 会议室显示"预约中" \| 会议室预约是异步的 \| 等待几秒后用 `list` 查询 `rsvp_status` \|
171	\| 修改日程报权限错误 \| 当前用户不是组织者，且日程未设置可编辑权限 \| 确保日程创建时设置了 `attendee_ability: "can_modify_event"` \|
172	\| 无法查看参会人列表 \| 当前用户无查看权限 \| 确保是组织者或日程设置了 `can_see_others` 以上权限 \|
173
174	---
175
176	## 📚 附录：背景知识
177
178	### A. 日历架构模型
179
180	飞书日历采用三层架构：
181	```
182	日历（Calendar）
183	└── 日程（Event）
184	└── 参会人（Attendee）
185	```
186
187	关键理解：
188	1. 用户主日历：日程创建在发起用户的主日历上，用户本人能看到
189	2. 参会人机制：通过添加参会人（attendee），让其他人的日历中也显示此日程
190	3. 权限模型：日程的 `attendee_ability` 参数控制参会人能否编辑日程、邀请他人、查看参与人列表
191
192	### B. 参会人类型
193
194	- `type: "user"` + `id: "ou_xxx"` — 飞书用户（使用 open_id）
195	- `type: "chat"` + `id: "oc_xxx"` — 飞书群组
196	- `type: "resource"` + `id: "omm_xxx"` — 会议室
197	- `type: "third_party"` + `id: "email@example.com"` — 外部邮箱
198
199	### C. 日程的生命周期
200
201	1. 创建：在用户主日历上创建日程（工具使用用户身份）
202	2. 邀请参会人：通过 attendee API 将日程分享给其他参会人
203	3. 参会人回复：参会人可以 accept/decline/tentative
204	4. 修改：组织者或有权限的参会人可以修改
205	5. 删除：删除后状态变为 `cancelled`
206
207	### D. 日历类型说明
208
209	\| 类型 \| 说明 \| 能否删除 \| 能否修改 \|
210	\|------\|------\|---------\|---------\|
211	\| `primary` \| 主日历（每个用户/应用一个） \| ❌ 否 \|

People who liked this also viewed

6 picks

Type

feishu-calendar

2installs665forks

View on GitHub

How to install feishu-calendar?

op7418/codepilot/feishu-calendar

$npx -y skills add op7418/CodePilot --skill feishu-calendar

Installs into the current project.

Summary

飞书日历与日程管理工具集。包含日历管理、日程管理、参会人管理、忙闲查询。

Files · 1

View on GitHub

SKILL.md

1	# 飞书日历管理 (feishu-calendar)
2
3	## 🚨 执行前必读
4
5	- ✅ 时区固定：Asia/Shanghai（UTC+8）
6	- ✅ 时间格式：ISO 8601 / RFC 3339（带时区），例如 `2026-02-25T14:00:00+08:00`
7	- ✅ create 最小必填：summary, start_time, end_time
8	- ✅ user_open_id 强烈建议：从 SenderId 获取（ou_xxx），确保用户能看到日程
9	- ✅ ID 格式约定：用户 `ou_...`，群 `oc_...`，会议室 `omm_...`，邮箱 `email@...`
10
11	---
12
13	## 📋 快速索引：意图 → 工具 → 必填参数
14
15	\| 用户意图 \| 工具 \| action \| 必填参数 \| 强烈建议 \| 常用可选 \|
16	\|---------\|------\|--------\|---------\|---------\|---------\|
17	\| 创建会议 \| feishu_calendar_event \| create \| summary, start_time, end_time \| user_open_id \| attendees, description, location \|
18	\| 查某时间段日程 \| feishu_calendar_event \| list \| start_time, end_time \| - \| - \|
19	\| 改日程时间 \| feishu_calendar_event \| patch \| event_id, start_time/end_time \| - \| summary, description \|
20	\| 搜关键词找会 \| feishu_calendar_event \| search \| query \| - \| - \|
21	\| 回复邀请 \| feishu_calendar_event \| reply \| event_id, rsvp_status \| - \| - \|
22	\| 查重复日程实例 \| feishu_calendar_event \| instances \| event_id, start_time, end_time \| - \| - \|
23	\| 查忙闲 \| feishu_calendar_freebusy \| list \| time_min, time_max, user_ids[] \| - \| - \|
24	\| 邀请参会人 \| feishu_calendar_event_attendee \| create \| calendar_id, event_id, attendees[] \| - \| - \|
25	\| 删除参会人 \| feishu_calendar_event_attendee \| batch_delete \| calendar_id, event_id, user_open_ids[] \| - \| - \|
26
27	---
28
29	## 🎯 核心约束（Schema 未透露的知识）
30
31	### 1. user_open_id 为什么必填？
32
33	工具使用用户身份：日程创建在用户主日历上，用户本人能看到。
34
35	但为什么还要传 user_open_id：将发起人也添加为参会人，确保：
36	- ✅ 发起人会收到日程通知
37	- ✅ 发起人可以回复 RSVP 状态（接受/拒绝/待定）
38	- ✅ 发起人出现在参会人列表中
39	- ✅ 其他参会人能看到发起人
40
41	如果不传：
42	- ⚠️ 用户能看到日程，但不会作为参会人
43	- ⚠️ 如果只有其他参会人，发起人不在列表中（不符合常规逻辑）
44
45	### 2. 参会人权限（attendee_ability）
46
47	工具已默认设置 `attendee_ability: "can_modify_event"`，参会人可以编辑日程和管理参与者。
48
49	\| 权限值 \| 能力 \|
50	\|--------\|------\|
51	\| `none` \| 无权限 \|
52	\| `can_see_others` \| 可查看参与人列表 \|
53	\| `can_invite_others` \| 可邀请他人 \|
54	\| `can_modify_event` \| 可编辑日程（推荐） \|
55
56	### 3. 统一使用 open_id（ou_...格式）
57
58	- ✅ 创建日程：`user_open_id = SenderId`
59	- ✅ 邀请参会人：`attendees[].id = "ou_xxx"`
60	- ✅ 删除参会人：`user_open_ids = ["ou_xxx"]`（工具已优化，直接传 open_id 即可）
61
62	⚠️ ID 格式区分：
63	- `ou_xxx`：用户的 open_id（你应该使用的）
64	- `user_xxx`：日程内部的 attendee_id（list 接口返回，仅用于内部记录）
65
66	### 4. 会议室预约是异步流程
67
68	添加会议室类型参会人后，会议室进入异步预约流程：
69	1. API 返回成功 → `rsvp_status: "needs_action"`（预约中）
70	2. 后台异步处理
71	3. 最终状态：`accept`（成功）或 `decline`（失败）
72
73	查询预约结果：使用 `feishu_calendar_event_attendee.list` 查看 `rsvp_status`。
74
75	### 5. instances action 仅对重复日程有效
76
77	⚠️ 重要：`instances` action 仅对重复日程有效，必须满足：
78	1. event_id 必须是重复日程的 ID（该日程具有 `recurrence` 字段）
79	2. 如果对普通日程调用，会返回错误
80
81	如何判断：
82	1. 先用 `get` action 获取日程详情
83	2. 检查返回值中是否有 `recurrence` 字段且不为空
84	3. 如果有，则可以调用 `instances` 获取实例列表
85
86	---
87
88	## 📌 使用场景示例
89
90	### 场景 1: 创建会议并邀请参会人
91
92	```json
93	{
94	"action": "create",
95	"summary": "项目复盘会议",
96	"description": "讨论 Q1 项目进展",
97	"start_time": "2026-02-25 14:00:00",
98	"end_time": "2026-02-25 15:30:00",
99	"user_open_id": "ou_aaa",
100	"attendees": [
101	{"type": "user", "id": "ou_bbb"},
102	{"type": "user", "id": "ou_ccc"},
103	{"type": "resource", "id": "omm_xxx"}
104	]
105	}
106	```
107
108	### 场景 2: 查询用户未来一周的日程
109
110	```json
111	{
112	"action": "list",
113	"start_time": "2026-02-25 00:00:00",
114	"end_time": "2026-03-03 23:59:00"
115	}
116	```
117
118	### 场景 3: 查看多个用户的忙闲时间
119
120	```json
121	{
122	"action": "list",
123	"time_min": "2026-02-25 09:00:00",
124	"time_max": "2026-02-25 18:00:00",
125	"user_ids": ["ou_aaa", "ou_bbb", "ou_ccc"]
126	}
127	```
128
129	注意：user_ids 是数组，支持 1-10 个用户。当前不支持会议室忙闲查询。
130
131	### 场景 4: 修改日程时间
132
133	```json
134	{
135	"action": "patch",
136	"event_id": "xxx_0",
137	"start_time": "2026-02-25 15:00:00",
138	"end_time": "2026-02-25 16:00:00"
139	}
140	```
141
142	### 场景 5: 搜索日程（按关键词）
143
144	```json
145	{
146	"action": "search",
147	"query": "项目复盘"
148	}
149	```
150
151	### 场景 6: 回复日程邀请
152
153	```json
154	{
155	"action": "reply",
156	"event_id": "xxx_0",
157	"rsvp_status": "accept"
158	}
159	```
160
161	---
162
163	## 🔍 常见错误与排查
164
165	\| 错误现象 \| 根本原因 \| 解决方案 \|
166	\|---------\|---------\|---------\|
167	\| 发起人不在参会人列表中 \| 未传 `user_open_id` \| 强烈建议传 `user_open_id = SenderId` \|
168	\| 参会人看不到其他参会人 \| `attendee_ability` 权限不足 \| 工具已默认设置 `can_modify_event` \|
169	\| 时间不对 \| 使用了 Unix 时间戳 \| 改用 ISO 8601 格式（带时区）：`2024-01-01T00:00:00+08:00` \|
170	\| 会议室显示"预约中" \| 会议室预约是异步的 \| 等待几秒后用 `list` 查询 `rsvp_status` \|
171	\| 修改日程报权限错误 \| 当前用户不是组织者，且日程未设置可编辑权限 \| 确保日程创建时设置了 `attendee_ability: "can_modify_event"` \|
172	\| 无法查看参会人列表 \| 当前用户无查看权限 \| 确保是组织者或日程设置了 `can_see_others` 以上权限 \|
173
174	---
175
176	## 📚 附录：背景知识
177
178	### A. 日历架构模型
179
180	飞书日历采用三层架构：
181	```
182	日历（Calendar）
183	└── 日程（Event）
184	└── 参会人（Attendee）
185	```
186
187	关键理解：
188	1. 用户主日历：日程创建在发起用户的主日历上，用户本人能看到
189	2. 参会人机制：通过添加参会人（attendee），让其他人的日历中也显示此日程
190	3. 权限模型：日程的 `attendee_ability` 参数控制参会人能否编辑日程、邀请他人、查看参与人列表
191
192	### B. 参会人类型
193
194	- `type: "user"` + `id: "ou_xxx"` — 飞书用户（使用 open_id）
195	- `type: "chat"` + `id: "oc_xxx"` — 飞书群组
196	- `type: "resource"` + `id: "omm_xxx"` — 会议室
197	- `type: "third_party"` + `id: "email@example.com"` — 外部邮箱
198
199	### C. 日程的生命周期
200
201	1. 创建：在用户主日历上创建日程（工具使用用户身份）
202	2. 邀请参会人：通过 attendee API 将日程分享给其他参会人
203	3. 参会人回复：参会人可以 accept/decline/tentative
204	4. 修改：组织者或有权限的参会人可以修改
205	5. 删除：删除后状态变为 `cancelled`
206
207	### D. 日历类型说明
208
209	\| 类型 \| 说明 \| 能否删除 \| 能否修改 \|
210	\|------\|------\|---------\|---------\|
211	\| `primary` \| 主日历（每个用户/应用一个） \| ❌ 否 \|

People who liked this also viewed

6 picks

Type