student-rooms CLI

多供应商学生住宿查找与监控工具。查询Yugo和Aparto的房源可用性，按学期和价格筛选，并在新选项出现时发送提醒。

设置

bash
cd /path/to/student-rooms-cli
source .venv/bin/activate

配置文件：config.yaml（如缺失，从config.sample.yaml复制）。关键设置：

yaml
target:
country: Ireland
city: Dublin
academic_year:
start_year: 2026
end_year: 2027
filters:
maxweeklyprice: 350.0
notifications:
type: openclaw # 或 stdout | webhook | telegram
openclaw:
mode: message
channel: telegram
target: CHAT_ID

命令

所有命令支持 --provider yugo|aparto|all（默认：all）和 --json 参数以输出结构化数据。

discover — 列出房源

bash
python -m student_rooms discover --provider all
python -m student_rooms discover --provider all --json
python -m student_rooms discover --city Barcelona --provider aparto --json

返回目标城市的房源名称、slug、位置和URL。

scan — 一次性可用性检查

bash

学期1房间（默认筛选）

python -m student_rooms scan --provider all --json

所有选项（全年、学期2等）

python -m student_rooms scan --all-options --json

扫描并发送最佳匹配通知

python -m student_rooms scan --provider all --notify

JSON输出结构：
json
{
matchCount: 5,
matches: [
{
provider: yugo,
property: Residence Name,
roomType: Gold Ensuite,
priceWeekly: 310.0,
priceLabel: €310/week,
available: true,
bookingUrl: https://...,
startDate: 2026-09-01,
endDate: 2027-01-31,
optionName: Semester 1,
dedupKey: yugo|slug|gold ensuite|2026-27|Semester 1
}
]
}

watch — 持续监控

bash
python -m student_rooms watch --provider all

按配置间隔扫描（默认1小时+随机抖动）。仅对新出现的选项发送提醒。本地持久化已见选项以避免重复提醒。

probe-booking — 深度预订流程探测

bash
python -m student_rooms probe-booking --provider yugo --residence Dominick Place --json
python -m student_rooms probe-booking --provider aparto --residence Binary Hub --json

返回预订上下文、可用床位、直接预订链接和门户重定向URL。支持 --residence、--room、--tenancy、--index 筛选参数。

notify — 测试通知

bash
python -m student_rooms notify --message Test alert 🏠

test-match — 测试学期匹配逻辑

bash
python -m student_rooms test-match --from-year 2026 --to-year 2027 --name Semester 1 --start-date 2026-09-01 --end-date 2027-01-31 --json

位置覆盖

使用CLI参数覆盖配置中的目标位置：

bash
python -m student_rooms scan --city Barcelona --country Spain --provider all --json

代理使用提示

• - 始终使用 --json 获取结构化输出。
• 使用 scan --json 检查当前可用性；解析 matchCount 和 matches 数组。
• 在扫描前使用 discover --json 列出存在的房源。
• 使用 watch 作为后台进程进行持续监控。
• 结合 scan --notify 在单个命令中触发提醒。
• 扫描输出中的 dedupKey 字段唯一标识每个选项，用于追踪。

OpenClaw集成

在配置中设置 notifications.type: openclaw。支持两种模式：

• - message：通过 openclaw message send 向频道/目标发送提醒文本。
• agent：以提醒为上下文触发OpenClaw代理会话。

可选：createjobon_match: true 创建一次性cron作业以协助预订。

该工具完全独立运行——仅当需要 openclaw 通知后端时才需要OpenClaw。

通知后端

后端	配置键	要求
stdout	（默认）	无
webhook

notifications.webhook.url | 任意HTTP端点（Discord、Slack、ntfy.sh） | | telegram | notifications.telegram.bottoken + chatid | Telegram机器人 | | openclaw | notifications.openclaw.target | 已安装OpenClaw CLI |

供应商说明

• - Yugo：动态API发现（国家→城市→房源→房间→租期选项）。支持完整的预订流程探测。
• Aparto：抓取apartostudent.com进行房源发现，然后探测StarRez门户termID。爱尔兰/西班牙/意大利共享一个门户；英国有独立门户；法国无StarRez门户（仅可发现）。