CRITICAL — Before starting, you MUST first use the Read tool to read lark-shared/SKILL.md, which contains authentication, permission handling, and security rules.
Applicable Scenarios
- "Help me schedule a meeting with XX and YY" / "Arrange a technical review meeting"
- "Find a time tomorrow afternoon when everyone is free" / "Schedule a 30-minute meeting"
- "See which day this week we can have a meeting" / "Help me schedule a meeting"
- "When are Zhang San and Li Si free" / "Smart scheduling"
- "Help me create a meeting invitation" / "Schedule next week's retrospective meeting"
- "Help me book a meeting room" / "Is there an available meeting room on the 17th floor tomorrow afternoon"
- "Help me book a meeting room for a 6-person meeting" / "Book a meeting room"
Automates the entire process of "find free time → check available meeting rooms → recommend optimal time slot + meeting room → create calendar event", achieving one-stop meeting scheduling for "people + rooms".
Prerequisites
Only supports user identity. Before execution, ensure authorization has been granted:
lark-cli auth login --domain calendar,contact
Workflow
用户需求 ──► 解析参会人 & 时间范围 & 会议室偏好
│
├─► contact +search（解析姓名 → user_id）
│
▼
calendar freebusy list
（查询每人忙闲状态）
│
▼
AI 计算共同空闲时段
│
▼
会议室查询 & 忙闲检查（可选）
（查可用会议室 → 筛选空闲 → 匹配偏好）
│
┌───────┼───────┐
▼ ▼ ▼
推荐1 推荐2 推荐3
(时段+会议室) (次优) (备选)
│
▼
用户选择 → calendar +create
（创建日程 + 邀请参会人 + 预约会议室）
Step 1: Parse user requirements
Extract from natural language:
| Information item | Example | Default value |
|---|---|---|
| Attendees | "with Zhang San and Li Si" | None (must be specified) |
| Duration | "30 minutes" / "1 hour" | 60 minutes |
| Time range | "tomorrow afternoon" / "this week" / "next Monday to Wednesday" | Next 3 business days |
| Meeting topic | "Technical review" / "Requirements alignment" | None |
| Preferences | "prefer morning" / "avoid lunch time" | None |
| Meeting room preferences | "17th floor" / "can accommodate 6 people" / "must have a projector" | None (skip meeting room booking if not specified) |
Meeting room trigger determination: When the user mentions keywords such as "meeting room", "book a room", "book a space", "offline meeting", etc., or specifies floor/capacity/equipment preferences, enter the meeting room booking process. If the user only needs an online meeting or does not mention meeting room needs, skip Step 5.
Step 2: Parse attendee identities
Refer to lark-contact/SKILL.md。
# 按姓名搜索用户
lark-cli contact +search --query "张三" --format json
Extract from the returned results:
user_id: used to query busy/free status and create calendar eventsname: confirm whether it is the target user
When there are multiple matches: list them for the user to choose ("Found 2 people named 'Zhang San', please confirm which one").
Step 3: Determine the search time range
# 获取搜索范围（示例：未来 3 个工作日）
date "+%Y-%m-%dT09:00:00%z" # 起始
date -v+3d "+%Y-%m-%dT18:00:00%z" # 结束
Note: Date calculations must use the
datecommand, and must not be done mentally.
Working hours assumption：
- Default working days 09:00-18:00
- Lunch break 12:00-13:00 marked as unavailable
- Weekends are not included in the search scope (unless the user explicitly requests it)
Step 4: Query availability status
Reference lark-calendar/SKILL.md。
Method A (recommended): use +freebusy Shortcut
# 查询多人忙闲（推荐方式，v1.0.5+）
lark-cli calendar +freebusy --start "<start_time>" --end "<end_time>" --user-ids "<user_id_1>,<user_id_2>,<user_id_3>"
Method B: use +suggestion to let the API directly recommend available time slots
When the user only gives a time range (such as "tomorrow", "next week") rather than an exact point in time, you can directly use +suggestion to get multiple recommended options:
# 获取 AI 推荐的空闲时段（v1.0.5+）
lark-cli calendar +suggestion --start "<start_time>" --end "<end_time>" --attendee-ids "<user_id_1>,<user_id_2>" --duration-minutes 60
Selection strategy：
- The user specified an exact point in time ("tomorrow at 3 PM") → use
+freebusyto check for conflicts- The user gave a time range ("tomorrow", "this week") → use
+suggestionto get recommendations, saving manual calculation+suggestionis unavailable → fall back to+freebusy+ AI manual calculation
Method C (fallback): use the native API
# 原生 freebusy API
lark-cli calendar freebusy list --data '{
"time_min": "<start_time>",
"time_max": "<end_time>",
"user_ids": ["<user_id_1>", "<user_id_2>", "<user_id_3>"]
}' --format json
Step 5: Meeting room query and booking (optional — execute when the user needs a meeting room)
When the user needs to book a meeting room, use calendar +room-find to complete querying and filtering in one stop.
Method A (recommended): use +room-find Shortcut（v1.0.8+）
# 一站式查找可用会议室（推荐方式）
lark-cli calendar +room-find \
--start "<slot_start_time>" \
--end "<slot_end_time>" \
--capacity <参会人数>
+room-find automatically completes: get meeting room list → query availability → filter by capacity/availability → return available meeting room recommendations.
Optional parameters (filter by user preference):
- Specify floor/building → filter in the results by
floor_name/building_nameFilter - Specify capacity →
--capacityparameter (defaults to the number of attendees as the minimum requirement)
Method B (fallback): manual 3-step query
When +room-find is unavailable, fall back to the manual process:
# 1. 查询会议室列表
lark-cli calendar meeting_rooms list --data '{ "page_size": 50 }' --format json
# 2. 查询候选会议室忙闲
lark-cli calendar freebusy list --data '{
"time_min": "<slot_start_time>",
"time_max": "<slot_end_time>",
"room_ids": ["<room_id_1>", "<room_id_2>", "<room_id_3>"]
}' --format json
# 3. 手动匹配空闲会议室
Matching priority rules:
| Factor | Priority | Description |
|---|---|---|
| Capacity match | Highest | Capacity ≥ number of attendees, and not excessively wasteful (capacity ≤ 2× number of attendees) |
| Floor preference | High | If the user specifies a floor, match exactly |
| Equipment requirements | Medium | If the user mentions a projector/whiteboard, etc., it must match |
| Closest distance | Low | Same floor > adjacent floor > other floors |
Fallback strategy: If there are no available meeting rooms on the specified floor/building, automatically expand to adjacent floors or other floors in the same building, and note this in the recommendation.
Step 6: Calculate common available time slots and display recommendations
Algorithm logic:
- Merge each attendee's busy time slots into one "occupied timeline"
- Remove all "occupied" time slots from working hours
- Filter out continuous available segments ≥ the required meeting duration
- If a meeting room is needed: match an available meeting room for each candidate time slot (Step 5)
- Sort and recommend according to the following rules:
Sorting weights:
| Factor | Weight | Description |
|---|---|---|
| Earliest available | High | The earlier the better (urgent scenarios) |
| Productive work hours | Medium | 10:00-11:30 and 14:00-16:00 are better than other time slots |
| Avoid lunch break | Medium | Time slots crossing 12:00-13:00 are deprioritized |
| Avoid before end of workday | Low | Time slots 17:00-18:00 are deprioritized |
| User preference | Highest | If the user specifies "morning" / "afternoon", strictly follow it |
| Meeting room match | High | Prioritize time slots with suitable meeting rooms (for scenarios requiring a meeting room) |
Display format (with meeting room):
## 🗓️ 会议排期建议
### 会议信息
- **主题**：{会议主题}
- **参会人**：{张三、李四、王五}（共 N 人）
- **时长**：{60} 分钟
- **会议室偏好**：{17 楼，≥6 人}
### ✅ 推荐时段
| # | 日期 | 时间段 | 会议室 | 容量 | 推荐理由 |
|---|------|--------|--------|------|---------|
| 1 ⭐ | 明天（周二） | 10:00-11:00 | 17F-深圳湾 | 8人 | 所有人空闲，黄金时段，楼层匹配 |
| 2 | 明天（周二） | 14:00-15:00 | 17F-前海 | 6人 | 所有人空闲，午后效率时段 |
| 3 | 后天（周三） | 09:00-10:00 | 16F-南山 ⚠️ | 10人 | 所有人空闲，但非指定楼层 |
### ⚠️ 冲突说明
- 明天上午 09:00-10:00：张三有「产品需求评审」
- 后天下午：李四有「客户拜访」（全下午不可用）
- 17F 全部会议室明天下午 15:00-17:00 已被预约
请选择一个时段（输入序号），我将创建会议邀请并预约会议室。
Display format (no meeting room needed — pure online mode):
## 🗓️ 会议排期建议
### 会议信息
- **主题**：{会议主题}
- **参会人**：{张三、李四、王五}（共 N 人）
- **时长**：{60} 分钟
### ✅ 推荐时段
| # | 日期 | 时间段 | 推荐理由 |
|---|------|--------|---------|
| 1 ⭐ | 明天（周二） | 10:00-11:00 | 所有人空闲，黄金工作时段 |
| 2 | 明天（周二） | 14:00-15:00 | 所有人空闲，午后效率时段 |
| 3 | 后天（周三） | 09:00-10:00 | 所有人空闲，但较早 |
### ⚠️ 冲突说明
- 明天上午 09:00-10:00：张三有「产品需求评审」
- 后天下午：李四有「客户拜访」（全下午不可用）
请选择一个时段（输入序号），我将创建会议邀请。
Step 7: Create event (after user confirmation)
Reference lark-calendar/SKILL.md。
⚠️ Security rule: You must wait for the user to confirm their choice before creating the event.
Note：v1.0.8+
+createA video conference link is attached by default. If a purely offline meeting is needed (no video link), use the native API and do not setvc_type。
No meeting room:
# 创建日程并邀请参会人（默认带视频会议链接）
lark-cli calendar +create \
--summary "<会议主题>" \
--start "<选定开始时间>" \
--end "<选定结束时间>" \
--attendees "<user_id_1>,<user_id_2>,<user_id_3>"
With meeting room reservation:
# 创建日程 + 邀请参会人 + 预约会议室
lark-cli calendar +create \
--summary "<会议主题>" \
--start "<选定开始时间>" \
--end "<选定结束时间>" \
--attendees "<user_id_1>,<user_id_2>,<user_id_3>" \
--meeting-room "<room_id>"
Note: If
+createdoes not support the--meeting-roomparameter, use the native API:lark-cli calendar events create --data '{ "summary": "<会议主题>", "start_time": {"timestamp": "<unix_ts>", "timezone": "Asia/Shanghai"}, "end_time": {"timestamp": "<unix_ts>", "timezone": "Asia/Shanghai"}, "attendees": [ {"type": "user", "user_id": "<user_id_1>"}, {"type": "user", "user_id": "<user_id_2>"}, {"type": "resource", "room_id": "<room_id>"} ] }' --format json
After successful creation, output:
## ✅ 会议已创建
- **主题**：{会议主题}
- **时间**：{YYYY-MM-DD HH:mm - HH:mm}
- **会议室**：{17F-深圳湾（8人）} ← 仅含会议室时显示
- **参会人**：{张三、李四、王五}
- **邀请状态**：已发送日程邀请
参会人将收到飞书日历通知。
Fault tolerance mechanism
| Exception scenario | Handling method |
|---|---|
| Name search returns no results | Prompt the user to confirm the name or provide a user_id |
| Multiple users with the same name | List them for the user to choose |
| No common free time slot | Show the closest options (time slots where only 1-2 people have conflicts), and suggest the user coordinate |
| freebusy API unavailable | Fall back to +agenda querying each person one by one |
| Event creation failed | Display the error message and suggest the user create it manually |
| No free time at all within the time range | Suggest expanding the search range (check more days), or reducing the number of participants |
| No available meeting room | Prompt that there is no free meeting room on the specified floor/time slot, and suggest expanding the range or switching to online |
| Meeting room API unavailable | Skip the meeting room reservation and only create the event (fall back to pure scheduling mode), and note it in the output |
| Insufficient meeting room capacity | Recommend alternative meeting rooms in ascending order of capacity, and note "capacity does not fully match" |
Permission table
| Step | Command | Required scope | Required or not |
|---|---|---|---|
| Search users | contact +search |
contact:user.base:readonly |
✅ Required |
| Query busy/free | calendar freebusy list |
calendar:calendar.freebusy:read |
✅ Required |
| View event | calendar +agenda |
calendar:calendar.event:read |
Optional |
| Create event | calendar +create |
calendar:calendar.event:write |
✅ Required |
| Query meeting rooms | calendar +room-find or meeting_rooms list |
calendar:meeting_room:readonly |
Optional (when reserving a meeting room) |
| Meeting room busy/free | calendar +room-find or freebusy list (room_ids) |
calendar:calendar.freebusy:read |
Optional (when reserving a meeting room) |
Reference
- lark-shared — Authentication, permissions (required reading)
- lark-calendar —
+agenda、+create, detailed usage of freebusy and meeting_rooms - lark-contact —
+searchdetailed usage