Files
yun-xue-tang-assistant/docs/evidence/completion-next-evidence.txt
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

143 lines
8.5 KiB
Plaintext
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.7.0 · 单视频自动播放 / 完成后转下一门 实跑与回归
================================================================
结论
----
用户反馈的两个问题是同一个根因链条上的两处断点,均已在真实站点复现并修复:
1) 进入课程「有概率」不自动播放
- 平台的播放页不只有 #/course/play。单个视频课程点开后走的是
#/scan?kngId=… -> #/video/play?kngId=…,音频/课件还有 #/audio/play、#/ppt/play。
- v2.6.0 的 route() 只把 #/course/play 识别为课程页,其它播放页返回 'other',
主循环既不跑 courseTick 也不跑 manualCourseTick:不点「开始学习」、不接管视频。
- 真实站点「氦泄漏通用」(type=2 / fileType=video / 60 秒,列表第 307 页)复现:
进课后 150 秒内 S.phase 一直是 entering,video=null,面板停在
「进入课程(1 分钟):氦泄漏通用」,done=0。
2) 一门课学完后不自动转到下一门
- 平台课程真正学完时,汇总文案会从「已完成 0/1」变成 **「已完成学习」**;
单视频页则是「已完成 0%」->「已完成 67%」-> **「已完成学习」**。
此时倒计时和进度条都会消失。
- v2.6.0 的 readSummary() 只匹配 /已完成(\d+)\/(\d+)/,读不到「已完成学习」和百分比,
永远不判完成:停在课程页、不回列表、也不选下一门;而且播放器会把视频重置到 0 秒,
v.ended 变回 false,脚本又调用 play() 从头重播。
- 真实站点「如何搭建分销体系,实现用户指数级增长?(上篇)」(1 节 / 127 秒)复现:
127 秒时 study/summary 已返回 finishNum=1/1、acqHours=127,页面汇总变成「已完成学习」,
但 20 秒后 S.completedThisRun 仍为 0、S.current 未清空,video 被重新 play 到 0.5 秒。
真实站点证据
------------
复现环境:https://kfmic.yunxuetang.cn(江丰云课堂),2026-10-22,Asia/Shanghai。
登录凭据来自用户级环境变量 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD,没有写入脚本或仓库。
A. 单视频课程的实际路由与完成文案(#/video/play)
------------------------------------------------
NAV /kng/#/scan?kngId=283c683a-fa98-4f69-9e08-c45116118aa1
NAV /kng/#/video/play?kngId=283c683a-fa98-4f69-9e08-c45116118aa1&projectId=&btid=&gwnlUrl=
NET /kng/study/kngInfo {"title":"氦泄漏通用","type":2,"fileType":"video",...}
NET /kng/study/summary {"finishNum":0,"totalNum":1,...,"studyHours":60}
页面汇总:已完成 0% -> 已完成 33% -> 已完成 67% -> 已完成学习
倒计时: 还需 59秒 …(从 60 秒开始,注意视频本身 107 秒,平台按 required time 计时)
开始按钮:<button class="yxtf-button yxtf-button--primary yxtf-button--larger">开始学习</button>
修复前(v2.6.0)在该页连续 150 个 tick 的状态:
status=进入课程(1 分钟):氦泄漏通用
phase=entering done=0 video=- sum=已完成0% 150 秒无变化
B. 多课时课程完成后汇总变成「已完成学习」
----------------------------------------
NET /kng/study/summary {"finishNum":0,"totalNum":1,...,"studyHours":127}
[14s] 页面汇总:已完成0/1
[21s] 视频开始播放:video=play@0/127.1
[148s] NET /kng/study/summary {"finishNum":1,"totalNum":1,"acqHours":127,...}
[149s] 页面汇总:已完成学习(倒计时、进度条消失)
status=学习中:视频如何搭建分销体系,实现用户指数型增长?(上)
done=0 video=PAUSE@0/127.1
[150s] video=play@0.5/127.1 ← 平台重置后脚本又把视频从头播放
修复内容(v2.7.0)
------------------
1) route() 识别全部播放页:#/course/play、#/video/play、#/audio/play、#/ppt/play、
#/document/play、#/article/play,以及进课过渡页 #/scan。
新增 mediaPage() 区分「有目录的多课时课程」和「单媒体播放页」。
2) readSummary() 同时解析三种真实完成文案:
- 已完成 2/3 -> { x:2, y:3, complete:false, kind:'ratio' }
- 已完成 67% -> { x:67, y:100, complete:false, kind:'percent' }
- 已完成学习 -> { x:100, y:100, complete:true, kind:'done' }
另用 [role="progressbar"] 的 aria-valuenow 兜底。
3) courseTick():
- 单视频/音频页不再走目录对齐,也不把百分比进度当成「一节学完」去切节;
- 汇总 complete 时(比例满、100%、已完成学习)统一 completeCurrent();
- 新增 doneLatchKey:倒计时归零/video.ended 后记住本节已播完,
平台把播放器重置到 0 秒时不再自动 play,避免完成后重播;
- 单媒体页等待记账时只轮询汇总,不调用 advanceLesson()。
4) 进课判定改用 URL 的 kngId:startCourse() 把课程 id 写入 S.current.id,
courseTick() 优先用 kngId 比对,标题短暂是 loading.../在线课堂 时不再误判;
宽限从 12 秒提高到 30 秒(CFG.entryGraceMs)。#/scan 只是过渡页,此时不做完成判定,
防止读到上一门课残留的「已完成学习」。
5) 自动播放兜底:「开始学习」冷却 15 秒 -> 3 秒(3 秒没起播就补点);
选择器在 button/a 之外支持最内层 div/span,并跳过 disabled 按钮;
手动模式(手动课程自动连播)在单媒体页也会点开始;
点课程卡片后 4 秒仍停在列表时自动补点,最多 2 次,不再直接记为失败跳过。
6) 完成文案连续两次读到才确认(三种完成文案统一),避免 SPA 切页瞬间
把上一门课的完成文案算到新课程上。completeCurrent() 改为强制返回列表
(不受 goToList 5 秒节流影响),并先 pause 播放器;列表页把「已完成/已学习」
也当作完成状态过滤。
回归用例(本地复刻 DOM,Playwright)
------------------------------------
node .run-tmp/align/run.mjs => 13 PASS / 0 FAIL(起点对齐 + 自动切节)
node .run-tmp/complete/run.mjs => 8 PASS / 0 FAIL
E1 首次点卡片无反应:自动补点进入课程
U1 readSummary 解析 x/y、百分比、已完成学习
U2 route 识别 course/video/audio/ppt/scan
V1 单视频课:自动播放 -> 完成后进入下一门
C1 多课时课:已完成学习 -> 回列表 -> 下一门
L1 标题 loading 但 kngId 匹配:不误判、继续播放
T1 倒计时归零后平台重置视频:不重播,汇总更新后照常进入下一门
D1 「开始学习」是 div 时仍能自动播放
真机修复后验证
--------------
场景 1:已完成的多课时课程(#/course/play,汇总「已完成学习」)
[11s] 课程完成:如何搭建分销体系,实现用户指数级增长?(上篇)第 1 门,返回列表选下一门
[12s] NAV /kng/#/list
[15s] 回到列表第 1 页,继续…
[22s] 短课程队列已就绪:待学 5131 门;最短 2 分钟
[25s] 进入课程(2 分钟):如何制定渠道战略
[27s] 跳过:如何制定渠道战略(课程包含考试/测验章节)
[28s] 回到列表第 13 页,继续… -> 第 63 页
[31s] 进入课程(2 分钟):APP做裂变的三大专属玩法
[38s] 学习中:视频APP做裂变的三大专属玩法(video=0.6/132.1)
[PASS] complete=true next=APP做裂变的三大专属玩法 playing=true
场景 2:已完成的单视频课程(#/video/play,汇总「已完成学习」)
[11s] 课程完成:氦泄漏通用 第 1 门,返回列表选下一门
[12s] NAV /kng/#/list
[16s] 短课程队列已就绪:待学 5131 门;最短 2 分钟
[19s] 进入课程(2 分钟):如何制定渠道战略 -> 跳过(考试/测验章节)
[25s] 进入课程(2 分钟):APP做裂变的三大专属玩法
[32s] 学习中:视频APP做裂变的三大专属玩法(video=1.3/132.1)
[PASS] complete=true next=APP做裂变的三大专属玩法 playing=true
复现命令(本机)
----------------
$env:PLAYWRIGHT_PATH="<playwright 包目录>"
$env:CHROME_PATH="<chromium 可执行文件>"
node .run-tmp/align/run.mjs
node .run-tmp/complete/run.mjs
# 真机观测/验证需要 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD
$env:YUN_XUE_TANG_USR=...; $env:YUN_XUE_TANG_PWD=...
node .run-tmp/real/probe-bugs2.mjs # 修复前:video/play 全程不动作
node .run-tmp/real/verify-fix.mjs # 修复后:两个场景 PASS
清理说明
--------
- 登录态 storageState(.run-tmp/real/state.json)与调试截图只在本地调试目录,验证完成后删除。
- 仓库内没有写入账号、密码、token 或 cookie。