飞书会议室预订

基于飞书日历事件学习用户常用会议室，并依据本地偏好顺序自动预订会议室。

路径

• 状态文件：state/feishu-meeting-room-book.json
• 辅助脚本：skills/feishu-meeting-room-book/scripts/meeting_room_booker.py
• 刷新计划文件：tmp/meeting-room-refresh-plan.json

依赖项与权限

• 必需的 OpenClaw 插件：
  • openclaw-lark，或任何提供以下能力的等效飞书/Lark 插件：
    • feishu_calendar_event
    • feishu_calendar_event_attendee
    • feishu_calendar_freebusy
• 必需的本地运行时：
  • python3
  • 所附带的辅助脚本仅使用 Python 标准库，无需额外 pip 包
• 本地文件访问权限：
  • 持久化状态写入 state/feishu-meeting-room-book.json
  • 临时工作文件可能写入 tmp/meeting-room-events-*.json 和 tmp/meeting-room-candidates-*.json
• 必需的飞书 OAuth 权限范围（scopes）：
  • calendar:calendar.event:read：用于初始化/刷新阶段读取近期日历事件
  • calendar:calendar.event:create：用于创建新的日历事件
  • calendar:calendar.event:update：用于附加会议室并更新事件参会人
  • calendar:calendar.free_busy:read：用于检查会议室可用性
• 预订模型：
  • 该技能不调用独立的会议室预订服务
  • 会议室预订通过创建或更新飞书日历事件，并将会议室作为 resource attendee 附加来实现

必需工具

• feishu_calendar_event
• feishu_calendar_event_attendee
• feishu_calendar_freebusy

若任一飞书工具返回鉴权或权限范围错误，请先完成 OAuth 流程，再重试。本技能所需的正常权限范围为：

• calendar:calendar.event:read
• calendar:calendar.event:create
• calendar:calendar.event:update
• calendar:calendar.free_busy:read

产品规则

• 仅支持手动刷新，禁止自动刷新缓存的会议室列表。
• 缓存的会议室列表为单城市 v1 版本：仅存储一个基础位置（默认城市）和一个有序的会议室列表。内部状态字段名仍为 default_city。
• 首次使用时，若 state/feishu-meeting-room-book.json 不存在，且用户请求创建/预订会议室或为已有事件预订会议室，**不得**要求用户单独执行初始化。应主动告知用户即将启动首次初始化，立即运行 init 流程，并在默认会议室顺序保存后继续处理原始请求。
• 在初始化/刷新过程中，提取出的候选顺序即为默认优先级顺序。除非用户明确要求调整，否则不得重新排序。
• 创建新事件时，对常见缺失字段使用默认值，避免追问：
  • 标题缺失：使用摘要 会议
  • 参会人缺失：创建仅含当前用户的事件（无额外参会人）
  • 持续时间/结束时间缺失：默认为 1 小时
• 若用户未指定城市，则使用 default_city 中保存的基础位置（默认城市）。
• 若用户指定的城市与已保存的基础位置（默认城市）不同，则仍可创建事件，但**不自动预订会议室**；需向用户说明当前缓存仅覆盖基础位置（默认城市），并提示其手动为该城市“播种”（seed）会议室后执行刷新。
• 当无首选会议室空闲时：
  • create_and_book：仍创建事件，但不附加会议室
  • book_existing：保持事件不变，并提示用户手动添加更多会议室后刷新

更新候选会议室列表

当用户询问如何更新候选会议室列表时，遵循以下规则：

• 添加新候选会议室：
  1. 请用户在接下来 7 天内创建任意一个日历事件。
  2. 请用户将目标会议室作为 resource attendee 附加到该事件上。
  3. 然后请用户说 刷新会议室列表、更新会议室列表、重新学习会议室 或 更新会议室候选表。
  4. 默认刷新仅扫描较窄的“播种窗口”，若该会议室出现在事件载荷中，则会被纳入候选列表。
• 从候选列表中移除会议室：
  • 执行刷新操作，并仅保留用户仍希望保留的会议室。
  • 或维持当前列表，通过更小的子集及新顺序覆写状态文件。
• 调整会议室优先级：
  • 执行刷新操作，并由用户回复最终的会议室顺序。
  • 或维持当前会议室列表，通过重排后的 --room-id 参数列表覆写状态。
• 时间窗口限制：
  • 仅处于所选扫描窗口内的事件会影响候选列表。
  • 默认刷新窗口为：now - 1 day 至 now + 7 days
  • 首次初始化窗口为：now - 7 days 至 now + 7 days
  • 仅显式执行全量重建时使用：now - 20 days 至 now + 20 days - 1 minute
  • 若“播种事件”超出当前扫描窗口，则不会更新候选列表。

初始化或刷新流程

当用户说出以下任一指令时，触发该流程：

• “初始化会议室偏好”
• “初始化会议室预定技能”
• “刷新会议室列表”
• “更新会议室列表”
• “重新学习会议室”
• “更新会议室候选表”
• “全量刷新会议室列表”
• “重建会议室列表”
• 或状态文件不存在

当因状态文件不存在而隐式触发初始化时，需明确告知用户：

• 这是该技能的首次使用
• 正在学习其近期会议室使用历史
• 将首先保存默认的会议室优先级顺序
• 初始化完成后将自动继续当前预订请求

步骤：

1. 在调用任何飞书工具前，选择一种扫描模式：
   • default_refresh：适用于状态已存在，且用户发出“刷新会议室列表”、“更新会议室列表”、“重新学习会议室”或“更新会议室候选表”等指令时
     • 扫描窗口：now - 1 day 至 now + 7 days
     • 保存行为：增量更新；保留现有会议室及其顺序，追加新发现的会议室，并刷新再次出现的会议室元数据（如 display_name、score、last_seen_at、location_hints）
   • init：适用于状态文件不存在，或用户明确发出“初始化会议室偏好”或“初始化会议室预定技能”指令时
     • 扫描窗口：now - 7 days 至 now + 7 days
     • 保存行为：基于提取出的候选列表重建整个状态
   • full_rebuild：仅当用户明确发出“全量刷新会议室列表”或“重建会议室列表”指令时使用
     • 扫描窗口：now - 20 days 至 now + 20 days - 1 minute
     • 保存行为：基于提取出的候选列表重建整个状态
2. 使用辅助脚本构建刷新计划。 切勿手动计算时间切片边界：

python3 skills/feishu-meeting-room-book/scripts/meeting_room_booker.py plan-refresh 
  --mode  
  --output tmp/meeting-room-refresh-plan.json

3. 读取 tmp/meeting-room-refresh-plan.json。 严格使用该计划中 slices[].start_time、slices[].end_time、slices[].event_file 和 slices[].candidate_file 的值。 不得自行构造临时文件名或时间窗口。
4. 对计划中的每个切片：
   • 调用 feishu_calendar_event 并设置 action=list
   • 立即将该切片结果精确保存至计划中指定的 event_file
   • 立即对该单一切片执行提取操作：

python3 skills/feishu-meeting-room-book/scripts/meeting_room_booker.py extract 
  --input  
  --output 

• 若 extract 因 invalid JSON in 或其他解析错误失败，则视该切片文件已损坏或截断。
• 立即中止流程，告知用户刷新失败，原因为某一时间切片结果非有效 JSON。
• 不得继续后续切片，亦不得运行 finalize-refresh。

5. 所有切片均成功后，使用唯一辅助命令完成刷新。 该命令是刷新期间向 state/feishu-meeting-room-book.json 写入的**唯一允许方式**：

python3 skills/feishu-meeting-room-book/scripts/meeting_room_booker.py finalize-refresh 
  --input  
  --input  
  --mode  
  --state state/feishu-meeting-room-book.json 
  --output tmp/meeting-room-candidates.json

6. 读取 tmp/meeting-room-candidates.json。 若辅助命令失败，或返回 saved != true，则中止流程，告知用户刷新失败，并保持先前状态不变。
7. 向用户展示候选会议室列表，明确标注优先级序号，并说明：
   • 此为当前默认优先级顺序
   • 当前基础位置（默认城市）为
   • 若本次为 default_refresh，需解释原有列表已被保留，新发现的会议室已追加至末尾
   • 该顺序已作为回退（fallback）顺序保存
   • 若用户未作回复，后续预订将直接使用此默认顺序
   • 若本次初始化由预订请求触发，则当前请求将按此默认顺序继续执行
   • 若用户希望调整，请回复：
     • 如需更改基础位置（默认城市），请提供新城市名
     • 需保留哪些会议室
     • 最终的会议室顺序
8. 若用户回复了自定义顺序或子集，则通过以下命令覆写状态：

python3 skills/feishu-meeting-room-book/scripts/meeting_room_booker.py save 
  --input tmp/meeting-room-candidates.json 
  --state state/feishu-meeting-room-book.json 
  --default-city "" 
  --output tmp/meeting-room-candidates-confirmed.json 
  --room-id omm_first 
  --room-id omm_second

规则：

• 仅从已附加到真实事件上的 resource attendee 学习。
• 优先选用 rsvp_status=accept 的资源参会人。
• 若事件载荷中缺失 rsvp_status 字段，则仍保留该会议室候选。
• 辅助脚本生成的候选顺序即为默认优先级顺序。
• 若用户未提供重排序指令，则保持已保存的默认顺序不变。
• default_refresh 为增量式：
  • 即使某会议室未在当前窄窗口中出现，也保留在现有列表中
  • 已保存会议室的原有顺序保持不变
  • 新发现的会议室追加至现有列表末尾
  • 仅刷新再次出现的会议室的元数据（如 display_name、score、last_seen_at、location_hints）
• 移除会议室不属于增量刷新范畴。如需移除，用户必须显式重排/裁剪列表，或运行 full_rebuild 后确认更小子集。
• 当前官方 feishu_calendar_event 工具未暴露可靠的分页控制（针对 list），因此须确保每个时间切片足够小，使单次切片结果易于管理。
• 严禁单次工具调用获取跨越多周的完整扫描窗口。
• 严禁将扫描窗口扩展至 now - 20 days 至 now + 20 days - 1 minute 范围之外。
• 严禁对 state/feishu-meeting-room-book.json 使用 write、edit 或任何其他直接文件写入工具。
• 刷新期间，仅允许对 tmp/meeting-room-events-*.json 下的原始每切片临时文件执行 write 操作。
• 严禁对 meeting_room_booker.py 的 JSON 命令使用 shell 重定向（如 >）。请始终使用辅助脚本的 --output 参数以确保原子写入。
• 若任一 event_file 被截断或格式异常，extract 将失败。应将此视为真实失败原因；不得继续使用空文件或部分写入的候选文件。
• 严禁手动复制、改写或人工重构 feishu_calendar_event 的 JSON 到其他文件。
• 若解析失败，严禁凭记忆臆造候选会议室或评分。
• 该技能唯一有效的持久化状态文件为 state/feishu-meeting-room-book.json。
• 严禁写入或读取 state/meeting-room-preferences.json 或任何其他替代状态文件名。
• 若写入任一切片结果，或运行 extract / plan-refresh / finalize-refresh / save 任一命令失败，须立即中止，告知用户刷新失败，并保持先前状态不变。
• 若未提取出任何新候选会议室，严禁用猜测列表覆写状态。

创建并预订

当用户希望创建新事件并同时预订会议室时，使用此流程。

步骤：

1. 若 state/feishu-meeting-room-book.json 缺失，则先执行初始化。
   • 告知用户已检测到首次使用，将在预订前初始化会议室偏好。
   • 初始化完成后自动继续本创建并预订流程。
2. 加载状态：

python3 skills/feishu-meeting-room-book/scripts/meeting_room_booker.py show --state state/feishu-meeting-room-book.json --json

3. 解析以下字段：
   • 标题
   • 开始时间
   • 结束时间或持续时间
   • 参会人
   • 城市
4. 在提出任何追问前应用默认值：
   • 若标题缺失，则设为 会议。
   • 若参会人缺失，则不添加额外参会人（事件仍将为当前用户创建，因 user_open_id 始终传入）。
   • 若结束时间和持续时间均缺失，则设结束时间为 start_time + 1 hour。
5. 若城市缺失，则使用 default_city 中保存的基础位置（默认城市）。
6. 若指定城市与已保存的基础位置（默认城市）不同，则创建事件但不附加会议室，并说明单城市 v1 限制。
7. 否则，按缓存列表的排名顺序遍历会议室。对每个会议室，调用 feishu_calendar_freebusy 并设置 action=list 和 room_id=。
8. 选取首个 freebusy_items 为空的会议室。
9. 使用 feishu_calendar_event 并设置 action=create 创建事件。
   • 始终传入 user_open_id
   • 仅当用户明确提供了参会人时，才将其填入 attendees
   • 初始创建调用中**不得**包含会议室
10. 若找到空闲会议室，则使用 feishu_calendar_event_attendee 并设置 action=create 将其附加。
11. 立即调用一次 feishu_calendar_event_attendee 并设置 action=list，以检查会议室参会人状态。

无需告知用户主题、参会人和持续时间为必填项。用户只需提供开始时间，其余字段均由上述默认值填充。

状态解读：

• accept：会议室预订成功
• needs_action：事件已创建，会议室预订已提交；告知用户该操作处于待处理状态
• decline 或参会人创建失败：保留事件，并告知用户未成功预订会议室

为已有事件预订会议室

当用户希望为已有事件添加会议室时，使用此流程。

步骤：

1. 若 state/feishu-meeting-room-book.json 缺失，则先执行初始化。
   • 告知用户已检测到首次使用，将在预订前初始化会议室偏好。
   • 初始化完成后自动继续本预订流程。
2. 解析目标事件：
   • 优先使用显式提供的 event_id
   • 否则，使用 feishu_calendar_event 并设置 action=search 或 action=list，按标题/时间搜索
   • 若仍存在多个合理匹配项，则在修改前请用户选择
3. 首先使用 feishu_calendar_event_attendee 并设置 action=list 读取参会人列表。
4. 若事件已存在状态为 accept 或 needs_action 的资源参会人，则中止并报告当前会议室状态。
5. 若请求的城市与已保存的基础位置（默认城市）不同，则不尝试预订；需说明单城市 v1 限制。
6. 否则，使用 feishu_calendar_freebusy 遍历缓存会议室，并使用 feishu_calendar_event_attendee 附加首个空闲会议室。
7. 重新读取参会人列表一次，并报告最终的会议室 RSVP 状态。

本地状态结构

辅助脚本写入如下结构：

{
  "version": 1,
  "default_city": "Shanghai",
  "updated_at": "2026-03-17T20:00:00+08:00",
  "rooms": [
    {
      "room_id": "omm_xxx",
      "display_name": "A5-01",
      "rank": 1,
      "score": 18,
      "last_seen_at": "2026-03-16T10:00:00+08:00",
      "location_hints": ["Shanghai HQ"]
    }
  ]
}

该文件为可再生的运行时状态，请始终存放于 state/ 目录下。