Files
yun-xue-tang-assistant/README.md
T
void 8200bfa0c5 feat: v2.7.0 单视频课程自动播放、学完自动转下一门,并加入短课程优先
脚本 v2.5.1 → v2.7.0 的三批改动合并提交:

- 起点对齐(v2.5.2):进课后先对齐到「第一个未学完的课时」,再顺序往下学;
  切换成功以目录高亮为准,失败如实提示「未能切换」
- 优先短课程(v2.6.0):批量按列表接口的 studyHours 正序跨页选课,先学短课;
  接口不可用时依次降级为「当前页时长正序」「原列表顺序」;面板可随时关闭,
  开关存 localStorage(yt-prefer-short),队列缓存放在 sessionStorage
- 多播放页识别(v2.7.0):除 #/course/play 外,识别 #/video/play、#/audio/play、
  #/ppt/play、#/document/play、#/article/play 与过渡页 #/scan,
  单视频/音频课程同样自动点「开始学习」,不再停在 entering
- 完成判定(v2.7.0):readSummary() 同时解析「已完成 x/y」「已完成 N%」
  「已完成学习」,并支持 progressbar 的 aria-valuenow 兜底;整门课完成即回列表
  选下一门,不再停在已完成页把视频从头重播
- 稳定性:新增 entryGraceMs(30s)避免慢加载被误判为课程不一致;
  startClickCooldownMs 从 15s 缩短到 3s,未起播可及时补点
- 文档:README 补充新能力、配置项与存储键;运行报告标注 v2.7.0;
  新增 align-start / short-course / completion-next 三份实跑证据与面板截图
2026-10-22 23:04:40 +08:00

126 lines
7.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 云学堂助手
在云学堂(`*.yunxuetang.cn`)上自动登录、按目录顺序听课、自动切节,并在课程列表页批量推进的
Tampermonkey 用户脚本。支持多课时课程与单视频/音频课程;一门课学完会自动回列表选下一门。
平台按**真实播放时长**计时,脚本只负责「自动点播放、自动切下一节、处理防挂机弹窗」,
不快进、不改进度、不伪造学时。
![控制面板](docs/screenshots/panel.png)
## 功能
| 能力 | 说明 |
| --- | --- |
| 一键登录 | 面板里填账号密码,自动填充表单、勾选协议、点击登录;支持记住密码与自动登录 |
| 顺序听课 | 进入课程(手动打开或批量进入)后先对齐到「第一个未学完的课时」,从第一章第一节顺序往下学 |
| 自动切节 | 本节播完(`video.ended` 或平台倒计时归零)后自动进入下一节,并等平台记账后再继续 |
| 完成即跳课 | 平台汇总变成 `已完成学习`、进度 100% 或 `x/y` 满时判定整门课完成,自动回列表选下一门;不会停在已完成页,也不会把播完的视频从头重播 |
| 多类型播放页 | 识别 `#/course/play`、`#/video/play`、`#/audio/play`、`#/ppt/play` 等播放页;单视频课程同样自动点「开始学习」 |
| 防挂机验证 | 识别「已触发防挂机验证」弹窗并点「继续学习」;滑块/拼图类验证不绕过,提示人工处理 |
| 批量刷课 | 在列表页逐门进入未学完的课程,默认本次最多 10 门,连续失败 5 门自动停止 |
| 短课程优先 | 批量模式默认按课程总时长**从短到长**选课(跨页),先完成 1 分钟的课再学 1 小时的课;面板可关闭 |
| 失败隔离 | 答题/考试类课程、长时间无计时进展的课程会被跳过并记录原因,不影响后续课程 |
| 进度可续 | 运行状态存在 `localStorage`,刷新、热更新后继续上次的队列和页码 |
## 安装
1. 浏览器安装 [Tampermonkey](https://www.tampermonkey.net/)。
2. 打开 Tampermonkey 面板 → 添加新脚本 → 粘贴 [`yun-xue-tang-assistant.user.js`](yun-xue-tang-assistant.user.js) 全文 → 保存。
3. 打开 <https://kfmic.yunxuetang.cn/login.html>,右下角出现「云学堂助手」面板:
- 填账号密码 → 点「一键登录并刷课」,登录后自动进入列表并开始批量学习;
- 或手动登录后,在列表页点「一键刷课」。
脚本 `@grant none`,不依赖任何本地服务,可独立运行。
## 配置
脚本顶部的 `CFG` 是唯一的配置入口:
| 配置项 | 默认 | 作用 |
| --- | --- | --- |
| `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` 正序排队,再跳到目标页
逐个进入。接口不可用(未登录、跨域、平台改版)时自动降级为「当前页按时长正序」,
再不行就回到原来的列表顺序,不会让批量任务卡住。
## 开发热加载
改完脚本保存即生效,不用复制粘贴、不用刷新页面。详见 [dev/README.md](dev/README.md)。
```powershell
npm run dev # 等价于 node dev/serve.mjs,默认 127.0.0.1:8899
```
Windows 下也可以直接双击 [`dev/start-dev.cmd`](dev/start-dev.cmd)。脚本暴露 `window.__ytDispose()`,
加载器在注入新版本前先释放旧实例(定时器、监听器、面板),因此视频播放不会被打断。
## 目录结构
```text
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](运行报告.md),
证据文件在 [`docs/evidence/`](docs/evidence/),截图在 [`docs/screenshots/`](docs/screenshots/)。
v2.5.2 修复「进入课程不从第一个未学完的课时开始」的定位过程、复刻用例与修复前后对比,
见 [`docs/evidence/align-start-evidence.txt`](docs/evidence/align-start-evidence.txt)。
v2.6.0 新增「优先短课程(时长正序)」:真实站点读取 5148 门课程、跨页跳到最短课程所在页的
实跑记录与 3 个回归用例,见 [`docs/evidence/short-course-evidence.txt`](docs/evidence/short-course-evidence.txt);
面板效果见 [`docs/screenshots/panel-short.png`](docs/screenshots/panel-short.png)。
v2.7.0 修复「进入课程有概率不自动播放」和「学完后不转下一门」:新增单视频/音频/课件播放页识别,
完成判定同时支持 `已完成 x/y`、`已完成 N%`、`已完成学习`;真机复现、修复前后对比与回归结果见
[`docs/evidence/completion-next-evidence.txt`](docs/evidence/completion-next-evidence.txt)。