广西干部网络学院 · 班级课程自动学习
概述
本技能在真实浏览器（Playwright，有头模式）中模拟人工操作，完成
登录 → 学习中心 → 我的班级 → 必修课全部学完 → 添加选修课 → 学满 N 门选修 全流程。
视频由站点真实页面播放，学时由站方服务器记录；脚本只负责导航、排队与值守。
适用前提（务必先向用户确认）：
- 仅用于用户本人拥有的学习账号（本人或其授权家人），须由用户主动提供账号与密码；
- 不用于代他人刷课、批量注册或任何绕过平台规则的场景。
文件布局
scripts/
├── gx_study.py # 主入口（命令行参数见下）
├── login.py # 登录 + 验证码自动识别（ddddocr）+ 会话超时处理
├── study.py # 三阶段学习流程（必修→添加选修→学选修）
├── infra.py # 配置/日志/学时记录(records.json)/通知
├── setup_env.py # 依赖自检与安装（--install）
├── config.template.yaml # 配置模板 → 复制为 scripts/config.yaml
└── requirements.txt # 依赖清单（onnxruntime 必须为 1.20.1）
references/
└── troubleshooting.md # 实测踩坑手册（启动失败/验证码/卡进度等）
运行时 config.yaml、logs/、screenshots/、user_data/（浏览器登录态）都生成在
scripts/ 目录下。换账号必须同时换 login.persistent_profile_dir，否则登录态串台。
标准执行流程
第 1 步 · 收集凭据
向用户要两项信息：账号（用户名）与密码。密码处理规则：
- 首选写入环境变量：setx GX_PASSWORD "密码"，config 中 password 留空；
- 或直接写入 scripts/config.yaml（提醒用户该文件为明文，勿外传）；
- 严禁把密码写进日志、对话记录或任何交付文档。
第 2 步 · 准备环境
# 自检（不装东西，只报告缺什么）
python scripts/setup_env.py
# 缺依赖时一键安装（清华镜像 + playwright install chromium）
python scripts/setup_env.py --install
在 Windows + WorkBuddy 环境下优先用托管 venv：
C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe
（若该 venv 依赖被重置，先跑 --install 重装）。
第 3 步 · 写配置
复制 config.template.yaml → scripts/config.yaml，填入账号，确认关键参数：
| 参数 | 默认 | 说明 |
|---|---|---|
study.elective_target |
40 | 必修全部完成后选修课完成门数；0=不限 |
study.daily_minutes |
720 | 每日学时上限（720=12小时），学满即停 |
study.stop_when_daily_reached |
true | true=每日模式（次日重跑续学）；false=连续跑到全部完成 |
course_pick.max_pages_elective |
5 | 课程中心自动选课页数（约 10 门/页，5 页≈50 门 ≥ 40 门目标） |
resilience.max_run_minutes |
10080 | 单次任务兜底时限 |
首次调试建议先跑 python scripts/gx_study.py --test-login 验证登录链路。
第 4 步 · 后台启动
cd <技能 scripts 目录> && python gx_study.py --timeout 780 # 每日 12h 模式
用后台方式运行；--timeout 为本次最长运行分钟数（覆盖配置值）。
第 5 步 · 启动后 2 分钟检查
tail 最新日志（logs/gx_study_*.log），出现 「开始学习」或「进度：」 且百分比
递增即正常。详见 references/troubleshooting.md 处理异常。
第 6 步 · 向用户汇报与提醒
启动成功后必须告知用户：
1. 学习期间不要锁屏/休眠（浏览器需保持活动；电源计划设为不睡眠）；
2. 若浏览器弹出验证码人工提示（自动识别连续 20 次未过才会出现），请在
manual_verify_timeout_min（默认 10 分钟）内手动完成，脚本自动继续；
3. 运行结束时脚本通过 notify.channel 发送结果通知；助手应汇总
「今日累计学习 X 分钟 / 完成课程明细（learned/passed/failed 门数）」给用户。
机制说明（应对用户询问）
- 登录验证：登录页为图形算术验证码（base64 GIF，如
83-7=?）。脚本用 ddddocr
多预处理变体（放大/灰度/二值/反色）OCR 后多数投票求值提交，最多 20 次，
每次失败自动「换一张」；仍失败则暂停等人工（10 分钟超时后放弃本次，下次重跑重试）。
登录态存于user_data/profile，长期免登录；会话过期时自动重登。 - 进度保存：双层。① 站方服务器记录每门课百分比（重新打开即续播）；
② 本地user_data/records.json记录当日分钟数与课程明细（学满daily_minutes即停）。 - 异常处理：网络/页面超时自动重试（
resilience.*）；播放进度 30 分钟无推进自动
放弃该课换下一门；单门课超过max_minutes_per_course自动跳过；会话超时弹窗自动
关闭并重登；任何失败自动截图到screenshots/供排查。 - 结果反馈：运行结束按结果发送系统通知（完成/未达标/异常三种），退出码：
0 成功、1 异常、2 配置/依赖错、3 登录失败、4 超时。
约束与边界
- 只驱动用户本人账号的真实页面播放，不伪造学时数据、不攻击验证码服务；
- 有头浏览器必需（无头易被检测且人工兜底无法操作），因此机器不可锁屏；
- 同一 profile 同时只能有一个实例；启动前若已有健康实例（日志持续推进），
绝不再启动第二个，详见 troubleshooting.md。
