Feishu Meeting Room Book

Feishu Meeting Room Book

基于飞书日历事件学习个人常用会议室，并按本地偏好列表预定会议室。

Paths

• State file: state/feishu-meeting-room-book.json
• Helper script: skills/feishu-meeting-room-book/scripts/meeting_room_booker.py
• Refresh plan file: tmp/meeting-room-refresh-plan.json

Dependencies And Permissions

• Required OpenClaw plugin:
  • openclaw-lark or any equivalent Feishu/Lark plugin that exposes:
    • feishu_calendar_event
    • feishu_calendar_event_attendee
    • feishu_calendar_freebusy
• Required local runtime:
  • python3
  • the bundled helper script uses Python standard library only and does not require extra pip packages
• Local file access:
  • persistent state is written to state/feishu-meeting-room-book.json
  • temp working files may be written under tmp/meeting-room-events-*.json and tmp/meeting-room-candidates-*.json
• Required Feishu OAuth scopes:
  • calendar:calendar.event:read for reading recent calendar events during init/refresh
  • calendar:calendar.event:create for creating new calendar events
  • calendar:calendar.event:update for attaching meeting rooms and updating event attendees
  • calendar:calendar.free_busy:read for checking room availability
• Booking model:
  • this skill does not call a separate meeting-room booking service
  • room booking is performed by creating or updating Feishu calendar events and attaching the room as a resource attendee

Required Tools

• feishu_calendar_event
• feishu_calendar_event_attendee
• feishu_calendar_freebusy

If any Feishu tool returns auth or scope errors, finish the OAuth flow first and retry. The normal scopes for this skill are:

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

Product Rules

• Manual refresh only. Never auto-refresh cached rooms.
• The cached room list is single-city v1. Store one base location (default city) and one ordered room list. The internal state field name remains default_city.
• On first use, if state/feishu-meeting-room-book.json does not exist and the user asked to create/book a room or book an existing event, do not ask the user to initialize separately. Tell the user you are starting first-time initialization, run init immediately, and continue the original request after the default room order has been saved.
• During init/refresh, the extracted candidate order is the default priority order. Do not reshuffle it unless the user explicitly changes it.
• When creating a new event, use defaults instead of asking follow-up questions for common omissions:
  • missing title: use summary 会议
  • missing attendees: create a self-only event with no extra attendees
  • missing duration/end time: default to 1 hour
• If the user does not specify a city, use the saved base location (default city) from default_city.
• If the user specifies a different city from the saved base location (default city), create the event but do not auto-book a room. Explain that the current cache only covers the base location (default city), and tell the user to seed that city manually and run refresh.
• When no preferred room is free:
  • create_and_book: still create the event without a room
  • book_existing: keep the event unchanged and tell the user to refresh after manually seeding more rooms

Updating Candidate Rooms

Use these rules when the user asks how to update the candidate room list.

• To add a new candidate room:
  1. Ask the user to create any calendar event within the next 7 days.
  2. Tell the user to attach the desired meeting room to that event as a resource attendee.
  3. Then tell the user to say 刷新会议室列表, 更新会议室列表, 重新学习会议室, or 更新会议室候选表.
  4. Default refresh scans only a narrow seeding window and includes that room if it appears in the event payload.
• To remove a room from the candidate list:
  • Run refresh and keep only the rooms the user still wants.
  • Or keep the current list and overwrite the state with a smaller subset and a new order.
• To change room priority:
  • Run refresh and let the user reply with the final room order.
  • Or keep the current rooms and overwrite the state with a reordered --room-id list.
• Window limitation:
  • Only events in the chosen scan window affect candidates.
  • Default refresh uses now - 1 day to now + 7 days.
  • First-use init uses now - 7 days to now + 7 days.
  • Only explicit full rebuild uses now - 20 days to now + 20 days - 1 minute.
  • A seeding event outside the current scan window will not update the candidate list.

Init Or Refresh

Use this flow when the user says:

• "初始化会议室偏好"
• "初始化会议室预定技能"
• "刷新会议室列表"
• "更新会议室列表"
• "重新学习会议室"
• "更新会议室候选表"
• "全量刷新会议室列表"
• "重建会议室列表"
• or the state file does not exist

When init is triggered implicitly because the state file does not exist, explicitly tell the user:

• this is the first use of the skill
• you are learning their recent meeting room history now
• you will save a default room priority order first
• you will continue the current booking request automatically after init finishes

Steps:

1. Choose one scan mode before calling any Feishu tool:
   • default_refresh: when state already exists and the user says 刷新会议室列表, 更新会议室列表, 重新学习会议室, or 更新会议室候选表
     • scan window: now - 1 day to now + 7 days
     • save behavior: incremental update; keep existing rooms and order, append newly discovered rooms, refresh metadata for rooms seen again
   • init: when the state file does not exist or the user explicitly says 初始化会议室偏好 or 初始化会议室预定技能
     • scan window: now - 7 days to now + 7 days
     • save behavior: rebuild the state from the extracted candidates
   • full_rebuild: only when the user explicitly says 全量刷新会议室列表 or 重建会议室列表
     • scan window: now - 20 days to now + 20 days - 1 minute
     • save behavior: rebuild the state from the extracted candidates
2. Build the refresh plan with the helper script. Never compute the slice boundaries manually:

python3 skills/feishu-meeting-room-book/scripts/meeting_room_booker.py plan-refresh \
  --mode <default_refresh|init|full_rebuild> \
  --output tmp/meeting-room-refresh-plan.json

3. Read tmp/meeting-room-refresh-plan.json. Use exactly the slices[].start_time, slices[].end_time, slices[].event_file, and slices[].candidate_file values from that plan. Do not invent your own temp filenames or time windows.
4. For each slice from the plan:
   • call feishu_calendar_event with action=list
   • immediately save only that slice result to the exact event_file from the plan
   • immediately run extract on that single slice:

python3 skills/feishu-meeting-room-book/scripts/meeting_room_booker.py extract \
  --input <event_file_from_plan> \
  --output <candidate_file_from_plan>

• If extract fails with invalid JSON in <event_file> or any other parse error, treat that slice file as damaged or truncated.
• Stop immediately. Tell the user refresh failed because one slice result was not valid JSON.
• Do not continue to later slices and do not run finalize-refresh.

5. After all slices succeed, finalize refresh with one helper command. This command is the only allowed way to write state/feishu-meeting-room-book.json during refresh:

python3 skills/feishu-meeting-room-book/scripts/meeting_room_booker.py finalize-refresh \
  --input <candidate_file_from_plan_1> \
  --input <candidate_file_from_plan_2> \
  --mode <default_refresh|init|full_rebuild> \
  --state state/feishu-meeting-room-book.json \
  --output tmp/meeting-room-candidates.json

6. Read tmp/meeting-room-candidates.json. If the helper command failed or returned saved != true, stop, tell the user refresh failed, and keep the previous state unchanged.
7. Show the candidate rooms to the user with explicit priority numbers. Tell the user:
   • this is the current default priority order
   • the current base location (default city) is <default_city>
   • if this was default_refresh, explain that the existing list was preserved and newly discovered rooms were appended
   • it has already been saved as the fallback order
   • if the user does not reply, future bookings will use this default order
   • if this init was triggered by a booking request, the current request will proceed with this default order
   • if the user wants to adjust it, reply with:
     • the base location (default city) if they want to change it
     • which rooms to keep
     • the final room order
8. If the user replies with a custom order or subset, overwrite the state with:

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 "<city>" \
  --output tmp/meeting-room-candidates-confirmed.json \
  --room-id omm_first \
  --room-id omm_second

Rules:

• Learn only from resource attendees already attached to real events.
• Prefer resource attendees with rsvp_status=accept.
• If rsvp_status is missing in the event payload, keep the room candidate.
• The helper script's candidate order is already the default priority order.
• If the user gives no reordering instructions, keep the saved default order unchanged.
• default_refresh is incremental:
  • keep existing rooms even if they did not appear in the current narrow scan window
  • keep the existing order for already saved rooms
  • append newly discovered rooms after the existing list
  • only refresh metadata such as display_name, score, last_seen_at, and location_hints for rooms that were seen again
• Room removal is not part of incremental refresh. To remove rooms, the user must explicitly reorder/trim the list or run full_rebuild and then confirm a smaller subset.
• The current official feishu_calendar_event tool does not expose reliable paging controls for list, so keep each time slice small enough that a single slice result remains manageable.
• Never fetch a whole multi-week scan window in one tool call.
• Never widen the scan window beyond now - 20 days to now + 20 days - 1 minute.
• Never use write, edit, or any other direct file-writing tool on state/feishu-meeting-room-book.json.
• During refresh, write is allowed only for raw per-slice temp files under tmp/meeting-room-events-*.json.
• Never use shell redirection like > with meeting_room_booker.py JSON commands. Use the helper's --output flag so it writes atomically.
• If any event_file is truncated or malformed, extract will fail. Treat that as the real failure cause; do not continue with an empty or partially written candidate file.
• Never hand-copy, paraphrase, or manually reconstruct the feishu_calendar_event JSON into another file.
• Never invent candidate rooms or scores from memory if parsing fails.
• The only valid persistent state file for this skill is state/feishu-meeting-room-book.json.
• Never write or read state/meeting-room-preferences.json or any other alternate state filename.
• If writing any slice result or running extract / plan-refresh / finalize-refresh / save fails, stop immediately, tell the user refresh failed, and keep the previous state unchanged.
• Never overwrite the state with a guessed list when no new candidates were extracted.

Create And Book

Use this flow when the user wants to create a new event and also book a meeting room.

Steps:

1. If state/feishu-meeting-room-book.json is missing, run init first.
   • Tell the user you detected first use and are initializing meeting room preferences before booking.
   • After init saves the default order, continue this create-and-book flow automatically.
2. Load the state:

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

3. Parse:
   • title
   • start time
   • end time or duration
   • attendees
   • city
4. Apply defaults before asking any follow-up:
   • If title is missing, set it to 会议.
   • If attendees are missing, use no extra attendees. The event is still created for the current user because user_open_id is always passed.
   • If both end time and duration are missing, set end time to start_time + 1 hour.
5. If city is missing, use the saved base location (default city) from default_city.
6. If city is not the saved base location (default city), create the event without a room and explain the single-city v1 limitation.
7. Otherwise, iterate the cached rooms in rank order. For each room, call feishu_calendar_freebusy with action=list and room_id=<room_id>.
8. Pick the first room whose freebusy_items is empty.
9. Create the event with feishu_calendar_event action=create.
   • Always pass user_open_id
   • Put normal attendees in attendees only when the user explicitly provided them
   • Do not put the room into the initial create call
10. If a free room was found, attach it with feishu_calendar_event_attendee action=create.
11. Immediately call feishu_calendar_event_attendee action=list once to inspect the room attendee status.

Do not tell the user that topic, attendees, and duration are required. The user can simply give a start time; the defaults above fill the rest.

Interpretation:

• accept: room booked successfully
• needs_action: event created and room booking submitted; tell the user it is pending
• decline or attendee-create failure: keep the event and tell the user no room was booked

Book Existing Event

Use this flow when the user wants to add a room to an existing event.

Steps:

1. If state/feishu-meeting-room-book.json is missing, run init first.
   • Tell the user you detected first use and are initializing meeting room preferences before booking.
   • After init saves the default order, continue this booking flow automatically.
2. Resolve the target event:
   • Prefer an explicit event_id
   • Otherwise search by title/time with feishu_calendar_event action=search or action=list
   • If multiple plausible matches remain, ask the user to choose before mutating
3. Read attendees first with feishu_calendar_event_attendee action=list.
4. If the event already has a resource attendee in accept or needs_action, stop and report the current room state.
5. If the requested city is different from the saved base location (default city), do not try booking; explain the single-city v1 limitation.
6. Otherwise, iterate cached rooms with feishu_calendar_freebusy and attach the first free room with feishu_calendar_event_attendee.
7. Re-read attendees once and report the resulting room RSVP state.

Local State Shape

The helper script writes:

{
  "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"]
    }
  ]
}

This file is renewable runtime state. Keep it in state/.