根目录原来平铺了构建脚本、运行器配置、两个 .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 通过)。
开发热加载(保存即生效)
目标:在编辑器里改 src/ 下的源码模块,保存后自动重新打包,浏览器里的脚本自动换成新版本,
不用复制粘贴、不用重装、不用刷新页面。
结构
dev/ 只放「在浏览器里跑」的开发工具(HTTP 服务 + 薄加载器 + 真机测试),
构建与检查脚本在 ../scripts/,运行器配置在 ../config/。
| 文件 | 作用 |
|---|---|
../src/ |
业务脚本源码(拆成多个模块,改这里) |
../scripts/build.mjs |
用 esbuild 把 src/ 打包成单文件 .user.js(产物写在仓库根,热加载链路无需改动) |
../yun-xue-tang-assistant.user.js |
构建产物(不要手改,改 src/ 后 npm run build) |
serve.mjs |
本地 HTTP 服务,向浏览器提供源码与版本哈希(127.0.0.1:8899) |
dev-loader.user.js |
Tampermonkey 里的薄加载器,轮询版本、释放旧实例、注入新实例 |
tests/ |
真机测试脚本(真实 Chrome + 真实站点,见下方「真机测试」) |
../scripts/start-dev.cmd |
双击启动服务 |
../scripts/check.mjs |
npm run check 的实现:自动遍历 runner/、dev/、scripts/、config/ 跑 node --check,同时检查 .cmd 必须是纯 ASCII + CRLF(cmd.exe 逐字节按代码页读批处理,中文和裸 LF 会让行偏移错位);新增模块不用再手改命令 |
原理:加载器每 1 秒请求 /version,发现哈希变化就调用旧实例暴露的
window.__yunXueTangDispose()(清定时器 / 监听器 / 面板),再把新源码以 <script> 形式注入页面主世界。
因为脚本依赖页面里的 __vue__(登录组件),注入必须发生在主世界,不能走普通沙箱。
一次性安装
- 双击
scripts/start-dev.cmd启动本地服务(保持窗口开着)。 - 浏览器打开 http://127.0.0.1:8899/,点「安装 / 更新热加载器」,Tampermonkey 弹窗确认安装。
手动方式:Tampermonkey 面板 → 添加新脚本 → 粘贴
dev/dev-loader.user.js全文 → 保存。 - 停用或删除 Tampermonkey 里原来那份「云学堂助手」完整脚本。 (两份同时跑会出现两个面板、双份定时器,行为会乱。)
- 打开 https://kfmic.yunxuetang.cn/login.html,F12 控制台应看到:
[云学堂·热加载] 已注入 xxxxx 字节源码。
日常使用
- 改完
src/下的模块保存 →npm run build:watch自动重新打包,约 1 秒内页面控制台打印[云学堂·热加载] 热更新 → <新哈希>,面板会重建,视频播放不中断。 - 列表刷课的进度存在
localStorage(yun-xue-tang-batch-v2),热替换 / 刷新都不会丢。 - 改坏了(语法错误):构建失败,加载器会拒绝注入并弹出左下角红条提示,旧版本继续运行,修好再保存即可。
- 想完全回到「手动刷新才生效」:把加载器里的
MODE改成'reload'。
真机测试
在真实浏览器 + 真实云学堂页面上验证脚本,不靠 Node 里的 DOM 桩。
npm run build # 先出产物
npm run test:real # 有界面 Chrome,能看见面板真实渲染
npm run test:real:headless # 无头模式(CI / 无人值守)
node dev/tests/real-test.mjs --keep # 跑完不关浏览器,便于人工复核
三个真机脚本(dev/tests/real-test.mjs / real-e2e.mjs / real-run.mjs)会自动适配当前平台:
没有图形会话时强制 --headless=new(即使没传 --headless),并补上该平台需要的参数
(Linux:--no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage;Windows:不弹崩溃恢复气泡),
因此可以原样在无图形化服务器 / 容器 / CI / Windows 后台里跑。平台判断复用
runner/platform.mjs,不在这里重复实现。
想在生产环境长期无头挂机(持久化登录、掉登录自动重登、崩溃自愈),用
runner/headless.mjs, 见主 README 的「无头运行(Linux / Windows 服务器)」。
原理:用独立临时用户目录启动 Chrome(不影响日常配置),开 CDP 端口后新建标签页打开
https://kfmic.yunxuetang.cn/login.html,把 yun-xue-tang-assistant.user.js 注入页面主世界
(等价 Tampermonkey @grant none),然后在真实 DOM 上断言:
| 断言 | 说明 |
|---|---|
| 面板渲染 | #yun-xue-tang-panel 可见、position:fixed、距右下各 16px、含密码框与 4 个按钮 |
| 版本号 | #yun-xue-tang-version = v2.7.0(与 package.json 一致) |
| 页面识别 | 真实登录页 isLoginPage() === true、readSummary/readCountdown 安全返回 null |
| 点击不崩 | 真点「一键登录并刷课」后脚本仍存活、无自身 error 日志 |
| 持久化 | 真实 localStorage 可读写 |
| 热替换 | __yunXueTangDispose() 后真实 DOM 面板移除、__yunXueTangAuto 被删;再注入面板唯一 |
| 路由 | SPA 内改 location.hash 后 route() 自动跟随,无需重新注入 |
| 整页重定向 | 未登录访问 #/list 被站点跳回登录页(新 document),脚本无残留、重注入后正常 |
产物:截图存到 .run-tmp/screenshots/real-chrome-login.png(测试产物不入库,--shotdir / YUN_XUE_TANG_SHOT_DIR 可改)。
需要 Node 22+(全局 WebSocket / fetch),无需 puppeteer / playwright。
测试只读:不填账号密码、不点登录、不改线上数据。
真机登录 / 进课测试(E2E)
带真实账号跑完整媒体链路。凭据从环境变量读,不写进代码、不打印明文:
# 环境变量(已在当前环境配置)
# YUN_XUE_TANG_USR 员工邮箱 / 账号
# YUN_XUE_TANG_PWD 密码
npm run test:e2e # 登录 + 列表;默认只读,不碰学习进度
npm run test:e2e:play # 额外进入最短的未学完课程,采样 25 秒后立即暂停
npm run test:e2e:play -- --seconds 60
node dev/tests/real-e2e.mjs --headless # 无头
node dev/tests/real-e2e.mjs --keep # 跑完不关浏览器
覆盖的断言(--play 时是 19 项,否则 12 项):
| 阶段 | 断言 |
|---|---|
| 登录页 | 脚本注入、识别到账号/密码框、setNativeValue 写入真实输入框值一致、隐私政策勾选 |
| 登录 | 真点「一键登录并刷课」后真正登录成功(离开登录页);无脚本 error |
| 新 document | 登录是整页跳转,模拟 Tampermonkey 按 @match 重新注入后面板恢复 |
| 列表 | 16 张卡片(共 322 页)、scanCards 标题/状态解析、Vue 组件 kngListData 可读、studyHours 时长可用 |
进课(--play) |
挑最短的未学完课程进入(减少对真实进度影响)、readSummary/readCountdown/lessonItems 读到真实数据 |
播放(--play) |
真实 <video> 被接管:muted=true、playbackRate=1、paused=false、currentTime 真实推进 |
| 收尾 | 立即 pauseAllMedia + S.batchRunning=false,__yunXueTangDispose() 后面板/API 清理干净 |
行为与安全:
- 不加
--play时会在登录成功后立即停用列表刷课(清yun-xue-tang-auto-start-after-login、S.batchRunning=false), 避免在真实账号上意外推进课程。 - 加
--play只采样默认 25 秒就暂停并释放,不会把整节课刷完;结束时会打印进度快照(如进入前「已完成2/3」→ 采样后「已完成2/3」)便于核对是否被改动。 - 实测:进课
2025坚持的力量(273s 的第 3 节)采样 25 秒,currentTime推进到 63s,进度保持2/3未变。
登录后收集的日志里会出现一条
填写账号密码后,点「一键登录并刷课」,这是loginPageTick轮询刷新状态文案造成的噪声(发生在点击登录之前),不影响登录结果。
常见问题
| 现象 | 处理 |
|---|---|
| 左下角红条「未连上本地开发服务」 | 服务没启动,或端口被占用;运行 scripts/start-dev.cmd |
| 改完没反应 | 看控制台是否有 热更新 日志;确认 npm run build:watch 在跑,改的是 src/ 下的模块 |
| 页面出现两个面板 | 旧完整脚本没停用,去 Tampermonkey 停用它 |
| 端口冲突 | node dev/serve.mjs 8900,同时把加载器里的 SERVER 常量改成对应端口 |
| 服务没开也想用 | 加载器回退到上次缓存的源码(GM_getValue('yun-xue-tang-dev-src')) |
关闭开发模式
停用热加载器 + 重新安装一次完整脚本(把构建产出的 .user.js 全文粘进 Tampermonkey)即可。
脚本本身不依赖任何本地服务,@grant none,可独立运行。
开机自启(可选)
把 scripts/start-dev.cmd 的快捷方式放进
%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup,开机即后台常驻。