BJTU Classroom Query

基于 Playwright 的北交大教室查询自动化工具。

数据来源

数据源	能力	是否需要登录
教务系统（Playwright 脚本）	课表占用：哪些时间段有课	✅ 需要
实时人数接口（第三方）	当前教室在场人数	❌ 不需要

两者结合可以得出综合结论：当前有无课 + 实际人数 → 教室是否值得去。

核心功能

• AI 登录：集成智谱 AI 视觉模型，自动识别 CAS 登录页面的数学计算验证码。
• 状态缓存：自动保存登录状态 (auth_state.json)，避免频繁登录触发验证。
• 智能选择：支持学期、周次、教学楼的模糊匹配和自动选择。
• 空闲分析：自动解析教务系统复杂的表格结构，提取每日空闲的大节信息。
• 实时人数：调用第三方接口，获取教室当前在场人数和容量。

快速开始

1. 配置环境

确保项目根目录下存在 .env 文件，并包含以下配置：

ZHIPU_API_KEY=your_zhipu_api_key
BJTU_USERNAME=your_username
BJTU_PASSWORD=your_password

2. 运行查询

# 查询当前学期（自动推断）第14周 思源东楼 102 的空闲情况
uv run bjtuo-classroom-query/scripts/query_classroom.py --week "14" --building "思源东楼" --classroom "102"

# 指定学期
uv run bjtuo-classroom-query/scripts/query_classroom.py --semester "2025-2026-1" --week "14" --building "思源东楼"

参数说明

参数	说明	示例
--week	周次 (1-31)	14
--semester	学期代码	2025-2026-1
--building	教学楼 (支持模糊匹配)	思源东楼, 九教, 东一
--classroom	教室号 (可选)	102
--show-browser	显示浏览器窗口（默认无头模式）	(标志位)

实时人数查询（无需登录）

接口：GET http://yaya.csoci.com:2333/api/classnum/?building={教学楼名称}

第三方接口，非学校官方，数据约每 10-20 秒更新一次。

# 查询思源东楼实时人数（中文参数必须 URL 编码）
curl "http://yaya.csoci.com:2333/api/classnum/?building=%E6%80%9D%E6%BA%90%E4%B8%9C%E6%A5%BC"

返回格式：

{
  "time": ["2026-02-05 13:13:07", "2026-02-05 13:13:25"],
  "data": [
    ["SY101", 5.55, 5, 90],
    ["SY102", 15.62, 5, 32]
  ]
}

字段	说明
time	数据采集时间范围
data[i][0]	教室名称
data[i][1]	占用率 %
data[i][2]	当前人数
data[i][3]	总容量

注意：当 人数 >= 容量 时，通常为传感器异常，数据不可信。

支持的教学楼（共 11 栋，见 数据参考）

综合查询工作流

当用户询问"XX教室现在能去吗"、"哪个教室空着"等问题时，按以下步骤执行：

Step 1：查课表（有无上课）

uv run bjtuo-classroom-query/scripts/query_classroom.py \
  --week "<当前周次>" --building "<教学楼>" --classroom "<教室号>"

得到：该教室今天各节课的占用情况。

Step 2：查实时人数

curl "http://yaya.csoci.com:2333/api/classnum/?building=<URL编码后的楼名>"

从返回的 data 数组中找到对应教室，读取 [人数, 容量]。

Step 3：综合给出结论

课表状态	实时人数	结论
当前节次无课	人数少（< 容量30%）	✅ 空闲，推荐
当前节次无课	人数多（≥ 容量30%）	⚠️ 虽无课但人多，可能有人自习
当前节次有课	人数多	❌ 正在上课，不要去
当前节次有课	人数少	⚠️ 课表显示有课但人少，可能已结束或取消

输出示例：

思源东楼 102（SY102）
- 课表：本节（第3节）无课，下节（第4节）有课
- 实时：当前 5 人 / 32 座（15.6%）
- 结论：✅ 现在可以去，但第4节前需离开

数据参考

• 可用选项参考 (教学楼/学期/实时接口对照)