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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```json { "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/`.