Skip to content

About

优学院刷课助手(Ulearning Watch):网课自动播放、自动连播、断点续跑、自动处理「计时学习已暂停」弹窗

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

优学院刷课助手 · Ulearning Watch

CI

优学院(Ulearning)网课自动播放助手 — 自动连播、自动保存学习记录、自动处理「计时学习已暂停」弹窗。

A cross-platform Node.js CLI that drives your own Ulearning account through Playwright: it plays course videos, turns pages, saves study records early, and recovers from the platform's idle-timeout modal.

免责声明:本项目仅供个人学习与技术研究,请仅用于你本人已选、且允许自主安排学习时间的课程。使用自动化工具可能违反平台用户协议或学校的课程要求,由此产生的一切后果由使用者自行承担。


功能

  • 任意课程:只填课程链接,程序自动调用平台接口读取章节目录,不再需要手工整理 directory.json
  • 视频 + 文本页混合处理:按页面实际内容识别视频页,播完自动翻页
  • 完成度不掉队:主动调用播放器的“保存进度”(userSaveRecord()),播放中每 2 分钟保存一次,避免平台「每 5 分钟才自动保存」导致的误判
  • 防走神暂停:每 60 秒向页面派发一次活动事件,重置平台的 10 分钟无操作计时;即使弹出了「计时学习已暂停」,也会自动点「继续学习」并恢复播放
  • 登录会话自动续期:支持机构账号(学校/学号/密码)自动重登,也支持手动登录模式
  • 崩溃自动重启:播放器卡死、页面无法前进、网络中断时自动重开会话
  • 多课程排队:按配置顺序依次完成
  • 可管理:status 看进度,stop 优雅退出;日志与状态落盘
  • 防睡眠:Windows / macOS / Linux 下尽力阻止系统休眠(失败不影响运行)

环境要求

  • Node.js 18+
  • Google Chrome 或 Microsoft Edge(默认复用系统浏览器,无需额外下载)
  • 也可以运行 npx playwright install chromium 使用 Playwright 自带的 Chromium

支持 Windows / macOS / Linux。

安装

git clone https://github.com/YOUR_NAME/ulearning-watch.git
cd ulearning-watch
npm install

快速开始

# 1. 生成配置文件
npx ulearning-watch init

# 2. 编辑 config.json:填写机构名称、学号、密码和课程链接
# 3. 先试运行:登录 + 读取目录,不观看
npx ulearning-watch watch --dry

# 4. 正式运行
npx ulearning-watch watch

Windows 用户也可以直接双击仓库根目录的 start.bat / stop.bat。

在 Windows 上不保留控制台窗口、后台运行:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start-background.ps1

课程链接怎么获取

在浏览器登录 优学院课程页,进入要学习的课程,复制地址栏中的整段链接,形如:

https://courseweb.ulearning.cn/ulearning/index.html#/course/textbook?courseId=167254

把整段链接填到 courses[].url 即可;也可以只填数字 courseId。

配置说明

config.example.json 的完整字段:

字段 默认值 说明
browser.channel chrome 浏览器类型:chrome / msedge / chromium
browser.profileDir 程序数据目录 持久化浏览器资料目录(保存登录 Cookie);相对路径基于配置文件位置
browser.muteAudio true 静音播放
login.mode auto auto:有账号密码时自动登录,失败后转手动;manual:只等待手动登录
login.url 优学院登录页 一般不用改
login.institution — 机构名称,例如 武汉工程大学
login.account — 学号 / 工号
login.password — 密码
login.manualTimeoutSec 600 自动登录失败后等待手动登录的秒数;0 表示不等待
courses[].name 自动生成 课程显示名
courses[].url — 课程链接或 courseId
watch.playbackRate 1 播放倍速,0.5 ~ 4。部分课程对倍速有额外要求,请谨慎调高
watch.saveIntervalSec 120 播放中主动保存学习记录的间隔
watch.idleNudgeSec 60 防走神活动事件的间隔(必须小于平台的 10 分钟阈值)
watch.textSaveAfterSec 20 文本页打开多久后主动保存一次记录
watch.textMaxWaitSec 120 文本页最多等待多久仍未完成就前进
watch.noVideoWaitSec 60 视频页迟迟没有 <video> 元素时的等待上限
watch.stallRestartAfterSec 180 视频多久没有进度视为停滞
watch.stallFixes 2 停滞时重开页面的次数
watch.maxReplays 1 服务器仍未判定完成时最多重播次数
watch.pollSec 10 主循环轮询间隔
watch.sessionRestartDelaySec 15 会话出错后重启等待时间
watch.maxSessionRestarts 0 单课程最多连续失败次数,0 表示不限
watch.studyLockRetrySec 120 被其他学习会话占用时的重试等待时间
watch.maxStudyLockRetries 5 连续被占用多少次后跳过该课程
keepAwake true 尽力阻止系统休眠
log.level info debug / info / warn / error
log.file 程序数据目录 日志文件路径

账号密码的三种填法

优先级:环境变量 > 配置文件。

# macOS / Linux
export ULEARN_INSTITUTION='武汉工程大学'
export ULEARN_ACCOUNT='2607010302'
export ULEARN_PASSWORD='******'
# Windows PowerShell
$env:ULEARN_INSTITUTION='武汉工程大学'
$env:ULEARN_ACCOUNT='2607010302'
$env:ULEARN_PASSWORD='******'

config.json 已在 .gitignore 中,不要把包含账号密码的配置提交到 GitHub。

常用命令

ulearning-watch watch                     # 依次观看配置中的所有课程
ulearning-watch watch --course 2          # 只观看第 2 门课程
ulearning-watch watch --course 167254     # 只观看 courseId=167254 的课程
ulearning-watch watch --course 职业发展    # 按课程名模糊匹配
ulearning-watch watch --dry               # 只登录、读取目录并打印,不观看
ulearning-watch status                    # 查看是否在运行、当前页、完成计数
ulearning-watch stop                      # 发送停止请求,必要时强制结束进程树
ulearning-watch init --force              # 重新生成配置文件

--config <path> 可指定其他配置文件;--verbose 输出调试日志。

文件位置

内容 位置
配置(默认) ./config.json
浏览器资料 Windows:%LOCALAPPDATA%\ulearning-watch\profile;macOS:~/Library/Application Support/ulearning-watch;Linux:~/.local/state/ulearning-watch
日志 同上目录下的 logs/watch.log
运行状态 同上目录下的 state.json

可用环境变量 ULEARN_HOME 改程序数据目录,用 ULEARN_PROFILE_DIR 单独改浏览器资料目录。

工作原理(简述)

  1. 使用持久化 Chrome 资料目录启动浏览器,复用登录 Cookie。
  2. 打开课程页;会话过期时用机构账号登录,或等待手动登录。
  3. 点击「继续学习 / 开始学习」进入 learnCourse.html 播放器,从地址中取得 courseId / classId / chapterId。
  4. 在播放器页面内调用平台自己的接口 GET /course/stu/{courseId}/directory?classId=… 获取完整章节目录(页面 id、relationid、contentType)。
  5. 主循环:
    • 每 60 秒派发一次合成 mousemove/mousedown,重置平台 NoAction 的 10 分钟计时;
    • 检测 #alertModal,遇到「计时学习已暂停」自动点「继续学习」,并恢复视频播放;
    • 视频页:播放、每 2 分钟保存记录、播完后立即保存并校验完成状态;
    • 文本页:打开后主动保存一次记录,等待平台标记完成;
    • 通过「下一页」翻页,失败时回退到目录点击。
  6. 平台完成判定为「已观看时长 / 视频时长 ≥ 95%」,本工具与平台自身的保存节奏配合,避免“播完了却判未完成”。

目录结构

ulearning-watch/
├─ bin/ulearning-watch.js   # CLI 入口
├─ src/
│  ├─ cli.js                # 命令与参数解析
│  ├─ config.js             # 配置加载、校验、课程筛选
│  ├─ logger.js             # 日志
│  ├─ paths.js              # 数据目录
│  ├─ state.js              # 运行状态落盘
│  ├─ lock.js               # 单实例锁、stop 支持
│  ├─ browser.js            # 浏览器启动与回退
│  ├─ auth.js               # 登录 / 会话续期
│  ├─ player.js             # 播放器页面操作
│  ├─ directory.js          # 课程目录获取与规范化
│  ├─ watcher.js            # 观看主循环
│  └─ keepawake.js          # 防睡眠
├─ test/                    # node --test 单元测试
├─ config.example.json
├─ start.bat / stop.bat     # Windows 便捷脚本
└─ README.md

常见问题

浏览器启动失败
确认安装了 Chrome/Edge,或运行 npx playwright install chromium。若资料目录被其他 Chrome 进程占用,先关闭对应窗口。

登录失败 / 一直停在登录页
检查机构名称与学号密码;某些学校使用统一身份认证,无法用机构账号登录时,把 login.mode 改为 manual,程序会等待你在弹出的浏览器中手动登录。

一直卡在某个视频
查看日志 logs/watch.log。若视频内嵌了课中题,程序无法替你作答,会在多次尝试后强制前进;该页完成度取决于平台判定。

章节测验 / 讨论 / 作业
本工具只处理视频与普通文本页,不会作答任何测验。遇到需要人工完成的页面会跳过并记录日志。

需要一直开着电脑吗
需要。程序通过浏览器播放视频,关闭浏览器/终端即停止。keepAwake 会尽力阻止系统休眠。

会被判定为异常吗
本工具不修改平台数据,只模拟正常观看(播放、停页、保存)。但自动化本身可能被平台或学校视为违规,请自行评估风险。

能否多账号/多门课同时跑
同一资料目录只能运行一个实例;多门课程请在 courses 中排队,程序会依次处理。

参与贡献

欢迎提交 Issue / PR。修改前请先跑通 npm test。

开发

npm test          # 运行单元测试(不启动浏览器)
npm run dry       # 真实登录 + 打印目录

欢迎提交 Issue / PR。修改前请先跑通 npm test。

License

MIT

About

优学院刷课助手(Ulearning Watch):网课自动播放、自动连播、断点续跑、自动处理「计时学习已暂停」弹窗

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages