哈尔滨工业大学—空教室查询Skill

哈工大校园生活实用技能 · 帮同学秒找自习室

在哈工大，想找一间自习室，不用再一栋楼一栋楼跑、一间教室一间教室看。用这个 Skill，一条命令就能把全校任意教学楼整学期的空闲教室查清楚，整理成一张一目了然的 Excel：哪个时段哪栋楼哪间教室空着，全在里面。

任意楼：正心楼 / 格物楼 / 电机楼 / 管理楼 / 致知楼 / 理学楼 / 二校区各楼…（自动到教务系统里找，找不到会列出所有能查的楼）
任意学期：默认自动选最新学期
任意周次：默认第 1—19 周，可自定义

一、这个技能能帮你什么

| 场景 | 怎么用 | |---|---| | 「今天下午哪里能自习？」 | 抓正心楼或全校，看下午各时段空闲教室 | | 「快期末了，找个人少的楼」 | 按周统计空闲率，挑最空的楼 | | 「给学弟学妹做个自习攻略」 | 把整学期数据整理成 Excel 分享出去 |

二、装好只需 2 步

1. 放对位置

把整个文件夹复制到技能目录：

| 系统 | 路径 | |---|---| | Windows | %USERPROFILE%\.workbuddy\skills\ | | macOS / Linux | ~/.workbuddy/skills/ |

装完后对着 AI 说「查哈工大空教室」「查格物楼自习教室」就会自动调用。

2. 确认环境

node -v          # 需要 18 以上
python --version # 需要 3.x
python -m pip install openpyxl   # 只有生成 Excel 需要

使用前提（重要）：

需要能连上教务系统：校内连校园网（HIT-WLAN 或有线），校外连 VPN 也能正常登录

需要一个能登录哈工大教务系统（jwts）的账号——也就是你自己的教务账号

脚本不会要你输入登录信息，也不保存它。你需要做的，是脚本打开浏览器后，在弹出的窗口里亲手登录一次教务系统。登录态存在你的浏览器配置目录里，之后抓取才读得到数据。

简单说：这个技能帮你自动点查询、自动整理表格，但"登录"这一步必须由你自己（用你的教务账号）完成。

3. 新手环境自检（1 分钟搞定）

不确定自己电脑装没装好？在终端（Windows 用 PowerShell / 或 Git Bash）依次敲下面三条，看到版本号就说明 OK：

node -v                    # 看到 v18 或更高 → OK；没输出 → 去 nodejs.org 下载装一个
python --version           # 看到 Python 3.x → OK；没输出 → 去 python.org 下载装一个
python -m pip install openpyxl   # 只有想要生成 Excel 才需要，装一次就行

三条都不懂也没关系：只要你能打开浏览器登录教务系统，把上面命令的报错截图发给会用电脑的同学/或让 AI 帮你查"如何安装 node/python"，5 分钟就能搞定。装好后再跑 auto.sh 就全自动了。

提示：生成 Excel 的依赖（openpyxl）只影响最后一步"出表格"，不影响抓取数据本身。临时没装也能先抓出 JSON 原始数据。

三、一键全流程

cd 你想放产物的文件夹
bash <技能目录>/scripts/auto.sh 正心楼

之后你只需要做一件事：在弹出的浏览器窗口里，用你自己的教务账号登录（教务账号，手动输入）。脚本每 3 秒自动检测一次登录状态，检测到就自动往下跑，全程不用再敲命令。

⚠️ 登录这一步是必须的，脚本无法替你完成——它不会要你的登录信息，也拿不到你的登录信息。之前本机能直接抓，是因为你已经登录过、登录态还在；换一台电脑/清掉配置后，就要重新登录一次。

跑完你会得到：

哈工大正心楼教室使用情况_1-19周.xlsx   ← 最终成果（Excel 表格）
zx_week_1.json ~ zx_week_19.json      ← 原始数据（可重出表）
classroom_cache.json                  ← 本地缓存（之后秒查靠它，不用再登录）

其他用法：

bash auto.sh 格物楼 5 10      # 只抓第 5—10 周
bash auto.sh all              # 全校（不筛楼）
bash auto.sh 电机楼 1 19 9224 # 换调试端口

三·五、秒查模式：抓一次，查一学期

一个学期的教室课表基本不变，所以不用每次都登录抓取。auto.sh 抓完会自动生成一个本地缓存 classroom_cache.json，之后你随时问"哪间教室空"，AI 直接读缓存秒回——不用登录、不用开浏览器。

# 抓完一次后，日常查询只需要这一句（AI 会帮你跑）：
python <技能目录>/scripts/query.py --free --week 3 --day 周三 --section "5,6"
# 结果：第3周 · 星期三 · 第5,6节 空闲教室（共 N 间）...

想换楼 / 换学期 / 数据过期了 → 再跑一次 auto.sh，缓存自动重建
缓存文件叫 classroom_cache.json，可删可重建
也就是说：日常查询不用登录（秒查缓存），只有第一次或需要最新数据时才登录抓一次

数据会过时吗？会，所以要会刷新

缓存是某一天抓的快照，不是实时数据。如果学期中间有调课、停课、补课、考试周占用、临时活动，缓存可能和实际对不上。怎么办？

每次查询，query.py 都会自动显示"数据抓取于 X 月 X 日"——心里有数
觉得数据可能过时（调课密集期 / 考试周 / 感觉不对）时，重新跑一次 auto.sh 刷新即可：

bash <技能目录>/scripts/auto.sh 正心楼   # 重新登录抓取，自动重建缓存

刷新 = 一条命令，登录后全自动。日常秒查 + 需要时刷新，就是最平衡的用法。

四、Excel 里有什么

| 页签 | 内容 | |---|---| | 总览 | 每周空闲率 + 最挤的 3 个时段 | | 教室汇总 | 每间教室整学期被占用多少次、空闲率、最忙的一周 | | 第N周 | 明细矩阵：教室 × 42 时段，绿=空闲，红=有课 | | 数据说明 | 数据来源、抓取参数、有什么局限 |

真实输出长什么样（节选自 examples/zx_week_1.json 的真实数据）

以 正心楼 603 教室 · 第 1 周为例，zx_week_1.json 里记录的真实状态（🟩=空闲，🟥=有课）：

| 节次 | 周一 | 周二 | 周三 | 周四 | 周五 | 周六 | 周日 | |---|---|---|---|---|---|---|---| | 1-2 节 | 🟥 | 🟥 | 🟩 | 🟥 | 🟥 | 🟩 | 🟩 | | 3-4 节 | 🟩 | 🟥 | 🟥 | 🟥 | 🟥 | 🟩 | 🟩 | | 5-6 节 | 🟥 | 🟥 | 🟥 | 🟥 | 🟥 | 🟩 | 🟩 | | 7-8 节 | 🟥 | 🟥 | 🟥 | 🟥 | 🟥 | 🟩 | 🟩 | | 9-10 节 | 🟩 | 🟥 | 🟩 | 🟩 | 🟥 | 🟩 | 🟩 | | 11-12 节 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 |

一眼就能看出：周六、周日全天空闲，工作日 11-12 节最空——自习挑这个时间段基本随便坐。整个文件夹里 158 间教室、19 周、每间 42 个时段，全是这样的真实数据，不是模拟的。

五、出问题了怎么办

| 症状 | 原因 | 怎么办 | |---|---|---| | 报「系统里查不到某某楼」 | 教务系统没有这栋楼（比如诚意楼） | 看报错里列出的可选楼清单，换一个名 | | 连不上调试端口 | 浏览器没开调试模式 | 跑 start_browser.sh 9223（会自动验证） | | 缺少 openpyxl | 依赖没装到当前 python | 用跑脚本的那个 python 执行 python -m pip install openpyxl | | 某周只抓到 20 间 | 页面没加载完 | 脚本会自动加时重试 3 次 | | 中途停止，提示登录过期 | 登录失效 / 断网 | 看一眼浏览器窗口重新登录，然后 scrape.py --weeks N-19 从断点继续 | | 连不上 jwts.hit.edu.cn | 没连网，或用了 https | 校内连校园网、校外连 VPN；必须 http 不是 https |

六、一个必须知道的局限

教务系统的「空教室查询」通常只返回当周至少有一个空闲时段的教室。某间教室整周 42 个时段全满，它可能不会出现在那一周的结果里——「没出现」不等于「不存在」，这是系统本身的规则，表格没有造假也没有遗漏。

七、这个包安全吗

✅ 脚本里不含任何登录信息：没有账号、姓名，没有写死任何机器路径
✅ 你的登录信息只进教务系统官方登录页，脚本从不读取、不传输、不保存它——登录是你自己在浏览器里亲手完成的
✅ 登录态只留在你自己的浏览器配置目录里，脚本只看它是否已登录，不碰登录态本身
✅ 只做只读查询：不提交、不修改教务系统里任何数据
✅ 全部脚本开源可读，逐行检查没问题

一句话说清楚"账号登录"这件事：这个技能不需要也不接触你的登录信息——但使用它必须先由你本人登录一次教务系统（就像打开教务网页查成绩一样）。脚本负责的是"登录之后"的自动查询和整理。

关于登录态留存（看完再决定）

浏览器登录态会保存在系统临时目录下的 hit-jwts-profile-浏览器名 文件夹里（比如 Chrome 是 hit-jwts-profile-chrome），好处是下次抓取不用重新登录。共享电脑或在意登录态留存的话，抓完数据后删掉这个文件夹即可（Windows 下就是 %TEMP%\hit-jwts-profile-chrome），下次抓取会重新弹出登录页，不影响使用。