把单文件脚本拆成 src/ 下 13 个 ES 模块,用 esbuild 打回同名 .user.js, 产物文件名不变,dev/ 热加载链路无需改动。 - build.mjs:esbuild 打包(--watch / --minify),版本号只从 package.json 读取,同时替换 meta.js 的 @version 与 config.js 的 VERSION - 统一版本号来源,消除 package.json / meta.js / config.js 三处手写 - 补回 'use strict'(esbuild IIFE 默认不带,属真实行为回归) - 清理重复实现:pauseAllMedia、listData、shortQuery、drain、clearPending、 cbAuto 模块级引用、共用 cssText - 去掉搬代码时残留的 IIFE 缩进、死字段、二次兜底默认值、过期注释 - README / dev/README 同步构建流程与目录结构 行为无变化,仅 src/config.js 的 CFG 改成构建期注入版本号。
云学堂助手
在云学堂(*.yunxuetang.cn)上自动登录、按目录顺序听课、自动切节,并在课程列表页批量推进的
Tampermonkey 用户脚本。支持多课时课程与单视频/音频课程;一门课学完会自动回列表选下一门。
平台按真实播放时长计时,脚本只负责「自动点播放、自动切下一节、处理防挂机弹窗」,
不快进、不改进度、不伪造学时。
功能
| 能力 | 说明 |
|---|---|
| 一键登录 | 面板里填账号密码,自动填充表单、勾选协议、点击登录;支持记住密码与自动登录 |
| 顺序听课 | 进入课程(手动打开或批量进入)后先对齐到「第一个未学完的课时」,从第一章第一节顺序往下学 |
| 自动切节 | 本节播完(video.ended 或平台倒计时归零)后自动进入下一节,并等平台记账后再继续 |
| 完成即跳课 | 平台汇总变成 已完成学习、进度 100% 或 x/y 满时判定整门课完成,自动回列表选下一门;不会停在已完成页,也不会把播完的视频从头重播 |
| 多类型播放页 | 识别 #/course/play、#/video/play、#/audio/play、#/ppt/play 等播放页;单视频课程同样自动点「开始学习」 |
| 防挂机验证 | 识别「已触发防挂机验证」弹窗并点「继续学习」;滑块/拼图类验证不绕过,提示人工处理 |
| 批量刷课 | 在列表页逐门进入未学完的课程,本次门数与连续失败上限见下方配置表 |
| 短课程优先 | 批量模式默认按课程总时长从短到长选课(跨页),先完成 1 分钟的课再学 1 小时的课;面板可关闭 |
| 失败隔离 | 答题/考试类课程、长时间无计时进展的课程会被跳过并记录原因,不影响后续课程 |
| 进度可续 | 运行状态存在 localStorage,刷新、热更新后继续上次的队列和页码 |
安装
- 浏览器安装 Tampermonkey。
- 打开 Tampermonkey 面板 → 添加新脚本 → 粘贴
yun-xue-tang-assistant.user.js全文 → 保存。 - 打开 https://kfmic.yunxuetang.cn/login.html,右下角出现「云学堂助手」面板:
- 填账号密码 → 点「一键登录并刷课」,登录后自动进入列表并开始批量学习;
- 或手动登录后,在列表页点「一键刷课」。
脚本 @grant none,不依赖任何本地服务,可独立运行。
配置
配置项集中在 src/config.js 的 CFG(改完 npm run build 重新打包):
| 配置项 | 默认 | 作用 |
|---|---|---|
mute |
true |
静音播放(自动播放更稳) |
autoNext |
true |
手动打开课程时,本节结束自动下一节 |
tickMs |
2000 |
主循环间隔 |
startClickCooldownMs |
3000 |
「开始学习」重复点击冷却:3 秒内没起播就补点 |
entryGraceMs |
30000 |
进课后标题/课程 id 尚未就绪的宽限,避免慢加载被误判为「课程不一致」 |
stuckMs |
5 分钟 |
连续多久没有计时进展就放弃当前课程 |
maxCourses |
10 |
本次最多完成多少门;0 = 不限 |
maxConsecutiveFailures |
5 |
连续失败多少门后自动停止 |
alignToFirstIncomplete |
true |
进入课程先从第一个未学完的课时学起;false = 沿用平台上次位置 |
preferShortCourses |
true |
批量选课时优先总时长更短的课程(正序);面板勾选框「优先短课程(时长正序)」可随时切换 |
对齐起点对「一键刷课」和手动打开课程(需勾选「手动课程自动连播」)都生效, 每门课只在进入时对齐一次,之后手动点其它课时不会被拉回。
短课程优先开启时,批量任务启动会先读取一次列表接口里的课程总时长(首次约 5–10 秒,
结果在当前标签页缓存 5 分钟),把未学完课程按 studyHours 正序排队,再跳到目标页
逐个进入。接口不可用(未登录、跨域、平台改版)时自动降级为「当前页按时长正序」,
再不行就回到原来的列表顺序,不会让批量任务卡住。
开发热加载
源码已拆分为 src/ 下的多个模块,构建后合成单文件脚本。改完保存即生效,不用复制粘贴、不用刷新页面。详见 dev/README.md。
npm install # 首次需要(安装 esbuild)
npm run build # 打包 src/ → yun-xue-tang-assistant.user.js
npm run build:watch # 监听 src/,保存即自动重新打包
npm run dev # 等价于 node dev/serve.mjs,默认 127.0.0.1:8899
Windows 下也可以直接双击 dev/start-dev.cmd。脚本暴露 window.__ytDispose(),
加载器在注入新版本前先释放旧实例(定时器、监听器、面板),因此视频播放不会被打断。
目录结构
src/ 业务脚本源码(拆成多个模块,日常改这里)
meta.js UserScript 头 + 用法注释
config.js CFG / 常量 / VERSION
lifecycle.js 定时器·监听器·dispose
utils.js DOM 工具
state.js S / R / 持久化
panel.js 悬浮面板
route.js 路由识别
login.js 登录 / 一键刷课
list.js 列表页 + 短课程优先
player.js 播放器 / 防挂机 / 课时切换
course.js 课程页主循环
complete.js 完成 / 失败
index.js 主循环 / 启动 / 调试入口
build.mjs esbuild 打包脚本
package-lock.json 依赖锁(esbuild)
package.json npm scripts(build / build:watch / dev / check)
yun-xue-tang-assistant.user.js 构建产物(唯一需要安装的文件,不要手改)
dev/ 本地热加载开发工具(HTTP 服务 + 薄加载器)
docs/screenshots/ 实跑截图
docs/evidence/ 实跑日志与接口证据
运行报告.md 2026-10-19 实跑报告(v2.0.3)
本机数据
localStorage 键 |
内容 |
|---|---|
yt-batch-v2 |
批量刷课队列、当前课程、页码、已完成/失败记录 |
yt-login-v1 |
勾选「记住密码」时的账号密码(base64 混淆,不是加密) |
yt-auto-play-enabled |
「手动课程自动连播」开关 |
yt-prefer-short |
「优先短课程(时长正序)」开关(1 / 0) |
yt-auto-start-after-login |
登录后自动开始刷课的一次性标记(5 分钟内有效) |
短课程队列缓存在 sessionStorage 的 yt-short-catalog-v1,关闭标签页即清空,
不写入长期存储。
公用电脑请不要勾选「记住密码」;面板上的「清除密码」可随时删除本机保存的凭据。
已知限制
- 平台按真实播放时长计时,倍速/快进不会减少所需时间;脚本不提供这类加速。
- 直接改 URL 或刷新课程页时,脚本优先用 URL 里的
kngId校验课程;只有 URL 没有 id、 且页面标题超过 30 秒仍是loading...时才可能误判并回到列表。从列表正常进入不受影响。 - 验证码、滑块、拼图类验证需要人工完成,脚本不会绕过。
- 平台存在同名课程(同一门课出现在多个目录)。脚本按课程 id 精确点击,但完成/失败记录仍沿用 按标题去重的旧逻辑,同名课程不会重复安排。
- 平台改版(目录结构、弹窗、倒计时文案、列表接口字段、完成文案变化)可能导致识别失败, 需要更新选择器/完成判定。
免责声明
本项目仅用于个人学习自动化实践。请遵守所在单位与平台的使用规定,是否使用及由此产生的后果由使用者自行承担。
实跑记录
真实站点(kfmic.yunxuetang.cn)的完整实跑过程、发现的问题与修复记录见 运行报告.md,
证据文件在 docs/evidence/,截图在 docs/screenshots/。
v2.5.2 修复「进入课程不从第一个未学完的课时开始」的定位过程、复刻用例与修复前后对比,
见 docs/evidence/align-start-evidence.txt。
v2.6.0 新增「优先短课程(时长正序)」:真实站点读取 5148 门课程、跨页跳到最短课程所在页的
实跑记录与 3 个回归用例,见 docs/evidence/short-course-evidence.txt;
面板效果见 docs/screenshots/panel-short.png。
v2.7.0 修复「进入课程有概率不自动播放」和「学完后不转下一门」:新增单视频/音频/课件播放页识别,
完成判定同时支持 已完成 x/y、已完成 N%、已完成学习;真机复现、修复前后对比与回归结果见
docs/evidence/completion-next-evidence.txt。
