Files
yun-xue-tang-assistant/运行报告.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

194 lines
11 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.
# 云学堂助手 · 实跑报告(v2.0.3)
> 历史记录:本报告对应 **v2.0.3**,当时的文件名为 `yunxuetang-auto-play.user.js`。
> 脚本现已更名为 [`yun-xue-tang-assistant.user.js`](yun-xue-tang-assistant.user.js),当前版本 **v2.7.0**,
> 下文记录的修复均已包含在当前版本中。v2.6.0 新增「优先短课程(时长正序)」,
> 实跑与回归证据见 [`docs/evidence/short-course-evidence.txt`](docs/evidence/short-course-evidence.txt);
> v2.7.0 修复单视频课程不自动播放与课程完成后不转下一门,
> 证据见 [`docs/evidence/completion-next-evidence.txt`](docs/evidence/completion-next-evidence.txt)。
日期:2026-10-19 21:19–21:51(Asia/Shanghai)
脚本:`yun-xue-tang-assistant.user.js`(v2.0.3 时名为 `yunxuetang-auto-play.user.js`),最终版本 **v2.0.3**
## 结论
- 脚本在真实站点(`kfmic.yunxuetang.cn`,江丰云课堂)跑通:登录 → 课程列表 → 批量选课 → 自动进入课程 → 静音 1x 播放 → 读取进度/倒计时。
- **自动切节已端到端验证通过**:302 秒的第 1 节播完后平台进度 `0/3 → 1/3`,脚本切到第 2 节;v2.0.3 复跑又把第 2 节(305 秒)播完,进度 `1/3 → 2/3`,切到第 3 节「下(钱百峰)」。
- 实跑共发现 4 个真实问题,均已修复:
1. 「2小时 8分钟 34秒」格式的倒计时解析为 `null`;
2. 只剩分钟(「还需 5分钟」)的倒计时也解析为 `null`;
3. 自动切节会点回当前节(目录「章」节点也包含 `.liactive`);
4. 平台在切节后自动显示的「还需 5分钟」是**下一节**的时长,旧逻辑可能据此把已结束的上一节视频拉回开头重播。
- 实际影响了账号进度:`2025坚持的力量` 已完成第 1、2 节,当前 `2/3`;第 3 节在 58 秒处手动暂停。`KFMI2025...` 本轮又播了约 221 秒,进度仍为 `0/8`。
## 实跑 1:长课程 + 批量入口
| 步骤 | 实际结果 |
| --- | --- |
| 登录页 | `https://kfmic.yunxuetang.cn/login.html`,标题「登录-江丰云课堂」 |
| 课程列表 | 第 1 页 16 张卡片;前两张「已学完」被正确跳过 |
| 选中课程 | `KFMI2025年品质能力强化培训(APQP/CP/FMEA)`(学习中) |
| 目录 | 10 个 `li` = 2 个章节点 + 8 个课时;汇总「已完成 0/8」 |
| 播放 | `paused=false`、`muted=true`、`playbackRate=1`;`currentTime` 79s → 114s → 234s |
| 倒计时 | 「还需 2小时 8分钟 34秒」 |
| 停止 | 手动停在 234s,避免无人值守跑 2 小时以上 |
![课程播放中(首轮)](docs/screenshots/watch-006.png)
## 实跑 2:短课时验证自动切节
为了不让批量模式继续跑 2 小时的 KFMI 课程,这次把 `S.current` 指向短课程后开启批量逻辑(列表筛选逻辑已在实跑 1 验证)。课程来自同一列表,状态「学习中」:
`2025坚持的力量(黄文杰、袁倩靖、钱百峰)`,总时长 880 秒,共 3 节:
| 节 | 时长 | 起始进度 |
| --- | --- | --- |
| 上(黄文杰) | 302s | 0 |
| 中(袁倩靖) | 305s | 0 |
| 下(钱百峰) | 273s | 0 |
时间线(本地时间):
| 时间 | 事件 |
| --- | --- |
| 21:31:28 | 第 1 节开始播放,`duration=302.4s`,静音 1x |
| 21:36:33 | 平台 `study/summary` 返回 `finishNum: 0 → 1`,`acqHours: 0 → 302` |
| 21:36:34.933 | 脚本日志「本节已记录,切换下一节…」 |
| 21:36:34.934 | 脚本日志「进入下一节」 |
| 21:36:40.930 | 脚本日志「学习中:…中(袁倩靖)」;汇总「已完成 1/3」 |
| 21:37:04 | 第 2 节播放到 20.6s 时手动暂停(最终停在 55.7s) |
平台接口证据:
```
026 study/summary finishNum=0/3 acqHours=0
049 study/summary finishNum=1/3 acqHours=302
```
脚本日志证据:
```
[21:36:34.933] [云学堂自动] 本节已记录,切换下一节…
[21:36:34.934] [云学堂自动] 进入下一节
[21:36:40.930] [云学堂自动] 学习中:视频江丰创业故事微宣讲《坚持的力量》中(袁倩靖)
```
![切到下一节后的画面](docs/screenshots/15-after-advance.png)
## v2.0.3 复跑:第 2 节 → 第 3 节
这一轮专门验证「视频结束后不会被下一节的倒计时文案拉回重播」。为了避开目录点击,这次直接用第 2 节的 `locateshare` 地址进入:
| 时间 | 事件 |
| --- | --- |
| 21:45:37 | 第 2 节开始播放(平台自动起播),`duration=304.5s`;21:46:17 脚本接管时已到 40s |
| 21:50:46 | 平台 `study/summary` 返回 `finishNum=2/3`,`acqHours=607`(302+305) |
| 21:50:47.198 | 脚本日志「本节已记录,切换下一节…」 |
| 21:50:47.198 | 脚本日志「进入下一节」 |
| 21:50:53.198 | 脚本日志「学习中:…下(钱百峰)」,新视频 `duration=273s` 开始播放 |
| 21:51:01+ | 第 3 节正常计时;到 58.4s 时手动暂停 |
关键点:第 2 节结束时,页面先出现的是第 3 节的提示「还需 4分钟 33秒」(第 3 节总长 273 秒),不是上一节的剩余时间;脚本没有把它当成第 2 节还没结束,也没有 seek 回 0,而是按 `video.ended` 直接进入第 3 节。平台汇总从 `1/3` 变为 `2/3`。
平台接口:
```
073 study/summary finishNum=1/3 acqHours=342
096 study/summary finishNum=2/3 acqHours=607
```
![第 3 节播放中,汇总 2/3](docs/screenshots/16-v203-next.png)
测试过程中有一个插曲:第一次在批量运行中直接 `goto` 第 2 节地址,页面加载瞬间标题还是 `loading...`,脚本判定「页面课程与队列不一致」,按保护逻辑回到列表并选中了第一门未完成课程 KFMI,播了约 221 秒后才被手动停掉。正常从列表进入课程不会触发;但**刷新课程页/直接改 URL** 时确实可能遇到,属于已知限制,本轮未改。
## 问题 1:小时级倒计时解析失败
真实文案:
```
还需 2小时 8分钟 34秒 可完成本课程学习并获得6.52学分,加油!
```
旧正则 `/还需(\d+)分钟(\d+)秒/` 只认「分钟+秒」,`readCountdown()` 返回 `null`。
修复(`readCountdown()`):改为小时/分钟/秒都可选,并至少匹配到一个数字。
## 问题 2:只剩分钟时也解析失败
这条文案不是上一节完成后的“剩余时间”,而是平台切到下一节后自动显示的下一节提示。实跑日志能看清顺序:
```
21:36:28 当前节「还需 5秒」 汇总 0/3
21:36:33 倒计时为空 汇总 1/3
21:36:48 下一节「还需 5分钟」 下一节已播放 5.6s
```
也就是说,`5分钟` 是下一节的总时长。对下一节本身来说它是有效的倒计时,但第一次修复后仍要求「秒」,所以这条会解析成 `null`。已把秒改为可选,并用 4 种真实格式验证:
| 文案 | 解析结果 |
| --- | --- |
| 还需2小时7分钟59秒… | 7679 |
| 还需5分钟… | 300 |
| 还需4分钟10秒… | 250 |
| 还需59秒… | 59 |
## 问题 3:自动切节会点回当前节
真实目录里「章」节点也包含 `.liactive`,旧代码 `findIndex(li => li.querySelector('.liactive'))` 先命中章节点,于是「下一节」= 当前节。
线上对比(KFMI 课程):
- 旧逻辑:`视频2025-05-29--1`(当前节)
- 修复后:`视频2025-05-29--2`(正确下一节)
修复(`findNextLessonElement()` / `lessonItems()`):新增 `lessonItems()` 过滤包含子 `ul` 的章节点;用 `active.closest('li')` 定位当前课时后再取下一个。`findFirstIncompleteLessonElement()` 同步改用 `lessonItems()`。
短课时实测已证明修复有效:脚本没有点回「上(黄文杰)」,而是进入「中(袁倩靖)」。
## 问题 4:切节后的「还需 5分钟」被误当成上一节还没结束
旧判断:
```js
const localDone = (cd != null && cd <= 0) ||
(v && v.ended && (cd == null || cd <= 3));
```
如果视频已经 `ended`,但页面先挂出下一节的「还需 5分钟」(`cd=300`),`localDone` 会是 `false`;随后 `ensurePlaying()` 命中 `v.ended && cd > 3`,把视频 `currentTime = 0` 并重新播放,导致本节迟迟不切走。
这次实跑在 21:36:33 时倒计时刚好为空,所以脚本正常切了;但按你指出的平台行为,这条文案不能作为上一节是否结束的依据。修复:
- `localDone` 改为 `v.ended || cd <= 0`,`video.ended` 是本节结束的主信号(`courseTick()` 中的 `localDone`)。
- `ensurePlaying()` 遇到 `ended` 直接返回,不再 seek 回 0(`if (v.ended) return`)。
- 删除只为“提前结束补时长”服务的 `lastRestartAt` 重播分支;平台按真实时长计时,脚本本身也不快进,不需要它。
## 其他小修
- 视频开始播放后,面板从「点击开始学习…」恢复为「学习中:…」。
- 列表状态标签优先匹配 `已学完/学习中/未开始/…`,避免其它标签被误判。
- 版本号:2.0.0 → 2.0.1(前两个修复)→ 2.0.2(分钟级倒计时)→ **2.0.3**(完成后提示不再触发重播)。
## 说明
- 平台按真实播放时长计时,倍速/快进不会减少所需时间;本次没有伪造进度。
- v2.0.2 验证了第 1 → 2 节;v2.0.3 验证了第 2 → 3 节,均实际切成功。
- 第 3 节只有 273 秒,结束提示是下一节的「4分钟 33秒」,没有正好出现「5分钟」文案;但结束判断已改为 `video.ended`,本次确认没有重播。
- 第 3 节停在 58 秒,没有再继续,避免把课程刷到 3/3。
- 直接改 URL/刷新课程页时,页面标题短暂为 `loading...`,批量逻辑可能误判为课程不一致并回到列表;正常从列表进入不受影响。
- 测试浏览器的登录配置目录已删除,未把会话留在工作区。
## 证据文件
- [`docs/evidence/advance-evidence.txt`](docs/evidence/advance-evidence.txt):平台进度 0→1、切节日志、最终状态
- [`docs/evidence/v203-advance-evidence.txt`](docs/evidence/v203-advance-evidence.txt):v2.0.3 第 2→3 节、平台进度 1→2、最终状态
- [`docs/evidence/completion-banner-evidence.txt`](docs/evidence/completion-banner-evidence.txt):完成后「还需 5分钟」出现的时序
- [`docs/evidence/countdown-regex-test.txt`](docs/evidence/countdown-regex-test.txt):4 种倒计时格式的解析结果
- [`docs/evidence/probe.txt`](docs/evidence/probe.txt)、[`probe2.txt`](docs/evidence/probe2.txt)、[`probe4.txt`](docs/evidence/probe4.txt):目录结构与新旧切节逻辑对比
- [`docs/evidence/report.txt`](docs/evidence/report.txt):首轮运行状态与日志摘录
- [`docs/screenshots/watch-006.png`](docs/screenshots/watch-006.png):首轮播放中截图
- [`docs/screenshots/15-after-advance.png`](docs/screenshots/15-after-advance.png):v2.0.2 切到第 2 节后的画面
- [`docs/screenshots/16-v203-next.png`](docs/screenshots/16-v203-next.png):v2.0.3 切到第 3 节、汇总 2/3 的画面
> 整理仓库时已删除 `.run-tmp/`(浏览器配置目录、一次性调试脚本与其余截图,约 460 MB);
> 报告引用到的日志与截图已移到 `docs/` 下保留。