Files
yun-xue-tang-assistant/dev
voidandClaude Sonnet 4.6 f41fc72fe2 fix: 移除课程门数上限,避免与每日积分目标冲突
maxCourses 按整门课计数,而积分按课时计;只剩考试的课会白占名额,
曾出现 5 门用光但今日视频积分只拿到 1/3 就停止的情况。现在只由
今日积分完成、没有可学内容或 budgetMinutes 决定收尾。

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-02 19:36:57 +08:00
..

开发热加载(保存即生效)

目标:在编辑器里改 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/ 测试脚本(真机测试 + 终端面板纯函数测试,见下方「真机测试」)
../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__(登录组件),注入必须发生在主世界,不能走普通沙箱。

一次性安装

  1. 双击 scripts/start-dev.cmd 启动本地服务(保持窗口开着)。
  2. 浏览器打开 http://127.0.0.1:8899/,点「安装 / 更新热加载器」,Tampermonkey 弹窗确认安装。

    手动方式:Tampermonkey 面板 → 添加新脚本 → 粘贴 dev/dev-loader.user.js 全文 → 保存。

  3. 停用或删除 Tampermonkey 里原来那份「云学堂助手」完整脚本。 (两份同时跑会出现两个面板、双份定时器,行为会乱。)
  4. 打开 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   # 跑完不关浏览器,便于人工复核

终端面板自测(不用浏览器)

runner/tui.mjs 有个不联网、不开浏览器的纯函数测试;runner/study.mjs 的学时/学分累计也有一份(带假时钟):

npm run test:tui      # 面板渲染 / 列宽 / 尺寸自适应
npm run test:study    # 学习时长与学分累计口径
npm run test:points   # 每日积分:类型识别 / 封顶 / 去重 / 跨天清零 / 选类顺序

它用假 stdout 渲染真实帧,逐行量列宽,重点盯五件容易错的事:

  • 中文/全角/emoji 占 2 列,ANSI 转义序列占 0 列(算错边框就歪、中文被劈成半个);
  • 截断到指定列宽时要补 \x1b[0m,否则颜色会溢出到下几行;
  • 尺寸自适应:宽度直接跟终端(240 列终端框线就是 240),从 40 行到 8 行的每种高度都不超出窗口,矮到 15 行时自动省掉课时/日志行但仍保留学时与视频进度;
  • 没有 resize 事件的平台(Windows 传统控制台):完全不发事件也能在定时刷新里发现尺寸变化,最大化后框线跟着变宽、缩小后自动清整块重画(不会把旧帧的尾巴留在屏上),尺寸没变时不多做一次清屏;
  • 折行感知的回退:终端变窄时会把宽行重排成多行,所以按「旧帧在新宽度下的可视行数」算回退步数;如果折完比窗口还高(最大化后还原)就整屏重置(Esc[H + Esc[2J),否则旧面板的上半截会永远留在屏幕上;小幅变窄(折完仍装得下)走精确回退,不丢上方历史;
  • 36 列窄终端 / 8 行矮终端下不崩、不超界;缩窗(100×24 → 60×12)后硬重绘的回退步数受新窗口高限制,不会把上面历史顶出屏幕;
  • 学时/学分累计:暂停时不计时、播放中按两帧间隔累加、倒计时元素消失后沿用学分缓存、完成数没变不重复计分、换课后重新读分。

study-test.mjs 用假时钟(不依赖真实时间)把口径钉死:

  • 暂停 30 秒一点都不计、
  • 两帧间隔超过 60 秒(浏览器重启 / 进程挂起)直接丢弃不补计、
  • 同一门课重复完成不重复计分、没读到学分的课完成后不瞎加分、
  • 0.1 + 0.2 这种浮点累加输出成 0.3 而不是 0.30000000000000004。

另外还断言了「禁用时是空操作」(上层可以无条件调 tui.set())和 「finish() 只生效一次且会恢复光标」。改面板布局后先跑这个,比真机跑一轮快得多。

三个真机脚本(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,开机即后台常驻。