新增 runner/tui.mjs(~470 行):前台运行时自动开一块实时面板, 框线布局显示状态 / 课程 / 学时 / 课时 / 视频进度条 / 进度 / 最近日志。 - 学习统计 runner/study.mjs:只累计视频真在播的时长(暂停、重试退避、 页面加载都不计),学分按课程去重(重试 / 刷新不重复计) - 页面侧新增 credit 快照:平台只把本门学分写在倒计时文案里, 学完文案就消失,所以边播边记 - log.mjs 增加 setConsoleSink:面板接管终端那一路,日志文件仍是纯文本 - 面板里按 q 等价 Ctrl+C,走 stop.request 同一条优雅收尾路径 - 尺寸自适应:宽度跟随终端(不封顶 120 列),无 resize 事件的平台 靠定时刷新发现尺寸变化;变窄时按旧帧在新宽度下的折行数回退光标, 折完超过窗口高就整屏重置;宽度 / 高度不足按重要性丢字段 - 非 TTY(重定向 / 管道 / 计划任务 / --check)自动降级为逐行日志, 不写 ANSI 控制字符;--no-tui / YUN_XUE_TANG_TUI=0 可手动关闭, --no-color / NO_COLOR 关颜色 - 监控轮询从 2000ms 调到 1000ms,与面板刷新对齐 - supervisor 收尾时先收面板再逐行打退出日志,并汇总本次学习时长 / 学分 - check.mjs 增加裸 CR 检查:脚本里的 config\runner 曾被写成裸 CR, 变成 config<CR>unner 导致找不到配置文件 自测:npm run test:tui(渲染 / 列宽 / 极端尺寸)、npm run test:study(假时钟口径)
168 lines
11 KiB
Markdown
168 lines
11 KiB
Markdown
# 开发热加载(保存即生效)
|
||
|
||
目标:在编辑器里改 `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 桩。
|
||
|
||
```bash
|
||
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` 的学时/学分累计也有一份(带假时钟):
|
||
|
||
```bash
|
||
npm run test:tui # 面板渲染 / 列宽 / 尺寸自适应
|
||
npm run test:study # 学习时长与学分累计口径
|
||
```
|
||
|
||
它用假 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)
|
||
|
||
带**真实账号**跑完整媒体链路。凭据从环境变量读,不写进代码、不打印明文:
|
||
|
||
```bash
|
||
# 环境变量(已在当前环境配置)
|
||
# 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`,开机即后台常驻。
|