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