Files
yun-xue-tang-assistant/docs/evidence/align-start-evidence.txt
T
void c1e883d67f refactor: 重组目录结构,脚本收进 scripts/,配置独立成 config/
根目录原来平铺了构建脚本、运行器配置、两个 .cmd 启动器和一份中文名的
实跑报告,四类东西混在一起,新人分不清哪个是源码、哪个是产物。这次按
职责分层重排:

- 构建与检查脚本收进 scripts/:build.mjs、check.mjs
- 一键启动器收进 scripts/:start-headless.cmd、start-dev.cmd
- 运行器配置独立成 config/runner.config.mjs(日常调参不用重新 build)
- 真机测试收进 dev/tests/:real-cdp / real-test / real-e2e / real-run
- 运行报告改成 ASCII 名并移入 docs/reports/run-report-v203.md
- v2.0.x 时期的 7 份原始抓取片段归档到 docs/archive/v2.0-snapshots/,
  docs/evidence/ 只留当前版本的有效证据
- 测试每次重新生成的 3 张截图(e2e-01-after-login、e2e-02-playing、
  real-chrome-login)移出仓库并加入 .gitignore,改写到 .run-tmp/screenshots/;
  docs/screenshots/ 只保留手工挑选的 5 张展示图

路径修正:build.mjs 的 ROOT 上跳一级;dev/tests/ 四个脚本 ROOT 上跳两级、
对 runner/browser.mjs 的引用改 ../../;runner/config.mjs 默认配置文件路径改
config/runner.config.mjs;两个 .cmd 的 cd 改为仓库根、start-dev.cmd 指向
dev/serve.mjs;package.json 全部 npm scripts 同步;README、dev/README、证据
文件与源码注释里的路径一并更新。

顺带修掉测试里硬编码的 v2.7.0 断言:版本号改为从 package.json 读取。

验证:npm run build(104798 字节 / 102.3 KB)、npm run check(24/24)、
npm run test:real:headless(24/24 通过)。
2026-10-25 23:21:59 +08:00

69 lines
4.9 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.5.2 · 起点对齐回归(本地复刻目录)
==================================================
背景
----
用户反馈:进入课程后不会从「第一个未学完的课时」开始,前面的课时被跳过 / 整门课学不完。
真实站点需要登录,无法在本地直接复现,因此按 docs/archive/v2.0-snapshots/probe.txt、probe2.txt、probe4.txt
里记录的真实目录结构,复刻课程页 DOM,再用无头 Chromium 注入用户脚本跑 20 秒,
读取目录高亮、面板状态与控制台日志。复刻页面与用例脚本在 .run-tmp/align/(本机调试用,未入库)。
复刻的真实结构(来自 probe2.txt / probe4.txt)
--------------------------------------------
- .yxtulcdsdk-catalog ul > li:章节点含子 ul,课时是叶子 li
- 课时 li > div.ml24.flex-center.flex-space-between > span.item(tag-type 在标题之前)+ 右侧 svg 状态图标
- 完成态图标:起点 M10 2.75 的实心圆 + 对勾;未学完:空心圆;当前课时:带「!」的圆
- 进入课程时平台停在「上次学习的位置」(用例里用 resume 参数模拟)
- 本节视频 ended 后平台把完成数 +1,脚本据此切下一节
用例与结果(v2.5.1 → v2.5.2)
------------------------------
A1 批量 · 点击句柄在 li PASS → PASS
A2 批量 · 点击句柄在行容器 PASS → PASS
A3 批量 · 点击句柄在标题 span FAIL(停在平台上次位置第 5 节)→ PASS
A4 批量 · 点击句柄在状态图标 PASS(第 6 次点击才命中)→ PASS
A5 批量 · 完成态只有文字标签 FAIL(已学完被当成未学,退回第 1 节)→ PASS
A6 批量 · 全部未学 PASS → PASS
A7 批量 · 切换有确认弹窗 PASS → PASS
A8 批量 · 目标在折叠章(展开箭头是 svg) PASS → PASS(展开章节日志正常)
A9 手动 · 点击句柄在 li FAIL(完全不对齐,停在第 5 节)→ PASS
A10 手动 · 点击句柄在标题 span FAIL(同上)→ PASS
A11 批量 · 本节结束后切下一节 FAIL(记账后仍停在第 3 节)→ PASS
A12 批量 · 本节结束后切下一节(图标句柄) FAIL(同上)→ PASS
A13 手动 · 本节结束后切下一节 FAIL(未对齐,无进展)→ PASS
汇总:v2.5.1 = 6 PASS / 7 FAIL;v2.5.2 = 13 PASS / 0 FAIL
原因
----
1) clickLesson() 只点 li 和「li 内第一个 .hand」。真实目录里 .hand 是右侧的 <svg>,
而 SVGSVGElement 没有 HTMLElement.click()(Chromium 实测 typeof svg.click === 'undefined'),
svg.click() 抛 TypeError 后被 try/catch 静默吞掉,等于没点;句柄挂在标题 span /
行容器上时,前 4 次点击都没命中,脚本就放弃并「按当前位置继续」。
2) isLessonCompleted() 的文本兜底写成 /(已学完|已完成)$/,要求标签出现在 li 文本末尾;
真实目录的 tag-type 在标题之前(probe2.txt:<span class="tag-type">视频</span>标题),
标成「已学完 第1节」时永远匹配不到 → 已学完的课时被当成未学 → 目标退回第 1 节。
3) 起点对齐只写在 courseTick()(批量刷课)里,manualCourseTick()(手动打开课程)没有对齐。
4) findNextLessonElement() 返回 li 内第一个 .hand(真实目录里是 svg),
advanceLesson() / manualCourseTick() 直接 next.click() → 同 (1),切节点击不生效。
(docs 里 2.0.3 实跑看起来「切成功」,其实是平台自己播完自动连播。)
修复(v2.5.2)
--------------
- 新增 clickNode():HTMLElement 用 click(),svg 等没有 click() 的节点改派发 MouseEvent。
- clickLesson() 按「标题 span → 行容器 → li → 状态图标」逐次尝试,并补 pointer/mouse 序列;
对齐重试次数 4 → 8。
- isLessonCompleted() 文案匹配去掉结尾锚定,并补充 aria-label/title/class 语义与图标路径兜底。
- 起点对齐抽成 alignToFirstIncomplete(),courseTick() 与 manualCourseTick() 共用;
手动模式按课程标题判断换课,每门课只对齐一次,标题还是 loading 时不做任何判断。
- findNextLessonElement() 改回返回课时 li;切节用 switchLesson()(标题 → 行容器 → li → 图标,
每步先确认还没切过去),advanceLesson() 与手动连播共用。
- 章节展开、确认弹窗按钮统一走 clickNode();确认弹窗只在弹层内找按钮,避免误点页面其它按钮。
复现方式(本机)
----------------
$env:PLAYWRIGHT_PATH="<playwright 包目录>"
$env:CHROME_PATH="<chromium 可执行文件>"
node .run-tmp/align/run.mjs # 当前脚本
$env:SCRIPT=".run-tmp/align/before.user.js"; node .run-tmp/align/run.mjs # 修复前对照