Files
yun-xue-tang-assistant/dev/README.md
T
void 65bf63ea6a feat: v2.9.0 终端实时面板,学习时长与学分统计
新增 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(假时钟口径)
2026-10-26 21:49:13 +08:00

168 lines
11 KiB
Markdown
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.
# 开发热加载(保存即生效)
目标:在编辑器里改 `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`,开机即后台常驻。