XMUM Room Booking

自动预约厦门大学马来西亚分校（XMUM）图书馆自习室。支持全部 4 种房间类型，使用 Gemini AI 自动识别登录验证码。

本项目是一个 Agent Skill，兼容 Claude Code 与 openclaw。安装后 AI Agent 会掌握如何登录系统、查询空位、选择时间段并完成预约——整个流程由 AI 自主决策和操控脚本执行，无需人工介入。

🔥 推荐用 GitHub Actions 每天自动预约：免费、不需要电脑开机，见下方「每天自动预约（GitHub Actions）」。

---

支持的房间类型

--room-type	类型	房间	容量
silent	Silent Study Room	N201–N214	2人
study	Study Room	S221–S234	2人
group (默认)	Group Discussion Room	E231–E236, W241–W246	4人
success	Student Success Room	Room 1–3	4/10人

可预约时间段

时段	工作日	周末
09:00 – 11:00	✅	✅
11:00 – 13:00	✅	✅
13:00 – 15:00	✅	✅
15:00 – 17:00	✅	✅
17:00 – 19:00	✅	❌
19:00 – 21:00	✅	❌

---

安装

方式一：一键安装（推荐）

curl -sSL https://raw.githubusercontent.com/ViryaZheng/xmum-room-booking/main/install.sh | bash

自动完成：安装依赖 → 复制 Skill 到 openclaw → 引导配置账号

方式二：手动安装

git clone https://github.com/ViryaZheng/xmum-room-booking.git
cd xmum-room-booking
pip install requests beautifulsoup4 google-genai Pillow
python3 skill/scripts/auto_booking.py --setup

---

配置（首次运行 --setup）

Campus ID:       你的学号
Password:        eServices 密码
Gemini API Key:  验证码识别用（免费申请）

申请 Gemini API Key（免费）：

1. 打开 https://aistudio.google.com/apikey
2. 登录 Google 账号 → Create API key → 复制

⚠️ Key 仅保存在本地 ~/.xmu_booking.json，不要上传到任何公开平台，否则会被 Google 自动吊销。

---

使用方法

# 自动预约（2 天后，按优先级尝试多个时间段）
python3 skill/scripts/auto_booking.py

# 指定时间偏好（多个时段按顺序尝试，第一个有位置就预约）
python3 skill/scripts/auto_booking.py --time "19:00-21:00,17:00-19:00,15:00-17:00"

# 指定日期（任意空闲时段）
python3 skill/scripts/auto_booking.py --date 2026-03-01

# 指定房间类型
python3 skill/scripts/auto_booking.py --room-type silent

# 组合使用
python3 skill/scripts/auto_booking.py --room-type study --time "09:00-11:00,11:00-13:00"

默认时间偏好：

• 工作日：19:00-21:00 → 17:00-19:00 → 15:00-17:00（依次尝试）
• 周末：15:00-17:00 → 13:00-15:00 → 11:00-13:00（依次尝试）

---

每天自动预约（GitHub Actions，推荐）

在 GitHub 上定时运行，不依赖电脑开机或联网。模板：github-actions/book-room.yml

默认配置：每天 00:02（马来西亚时间）预约后天的静音自习室，优先 13:00–15:00，满了按顺序尝试其他时段。改文件顶部的 ROOM_TYPE / DAYS_AHEAD / TIMES 即可调整。

部署（本机已完成 --setup，并装好 gh）：

# 1. 新建私有仓库（必须私有：运行日志会显示学号和预约信息）
mkdir xmum-booking-cron && cd xmum-booking-cron
mkdir -p .github/workflows
curl -sSL https://raw.githubusercontent.com/ViryaZheng/xmum-room-booking/main/github-actions/book-room.yml -o .github/workflows/book-room.yml
git init -b main && git add . && git commit -m "XMUM room booking"
gh repo create xmum-booking-cron --private --source=. --push

# 2. 从 ~/.xmu_booking.json 写入 3 个 secret（不会显示在屏幕上）
python3 -c "import json,os;c=json.load(open(os.path.expanduser('~/.xmu_booking.json')));[open(f'/tmp/.x{k}','w').write(c[v]) for k,v in [('U','username'),('P','password'),('G','gemini_key')]]" \
  && gh secret set XMUM_USERNAME < /tmp/.xU && gh secret set XMUM_PASSWORD < /tmp/.xP && gh secret set XMUM_GEMINI_KEY < /tmp/.xG; rm -f /tmp/.xU /tmp/.xP /tmp/.xG

# 3. 测试（默认只登录 + 列出空房，不预约）
gh workflow run book-room.yml
gh run watch

• 手动运行时把 dry_run 设为 false 会真实预约。
• 运行结果在仓库的 Actions 页面查看；失败时 GitHub 默认发邮件通知。
• GitHub 定时任务偶尔会延迟几分钟。

---

说明

• XMUM 系统限制只能预约今天及未来 2 天，自动模式默认预约 2 天后
• 多时间段优先级：第一个时段没位置自动尝试下一个，找到即预约
• 登录验证码识别失败时自动重试，最多 3 次
• 每个日期每人只能预约一个房间

---

免责声明

1. 仅限个人使用：本工具仅供使用者预约自己账号下的自习室，禁止用于代抢、转让或任何形式的商业用途（如收费帮人抢房间）。
2. 遵守学校规定：使用前请确认符合 XMUM 图书馆及 eServices 系统的使用条款。若校方明确禁止自动化访问，请停止使用。
3. Gemini API Key：请自行前往 https://aistudio.google.com/apikey 免费申请，在 --setup 时填入。Key 仅保存在本地，不会上传。
4. 风险自负：本工具按现状提供，作者不对账号封禁、预约失败或任何使用后果承担责任。