Files
yun-xue-tang-assistant/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

446 lines
36 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.
# 云学堂助手
在云学堂(`*.yunxuetang.cn`)上自动登录、按目录顺序听课、自动切节,并在课程列表页逐门推进的
Tampermonkey 用户脚本。支持多课时课程与单视频/音频课程;含考试章节的课程会自动进入考试、
不答题直接交卷;一门课学完会自动回列表选下一门。
平台按**真实播放时长**计时,脚本只负责「自动点播放、自动切下一节、处理防挂机弹窗」,
不快进、不改进度、不伪造学时。
![控制面板](docs/screenshots/panel.png)
## 功能
| 能力 | 说明 |
| --- | --- |
| 一键登录 | 面板里填账号密码,自动填充表单、勾选协议、点击登录;支持记住密码与自动登录 |
| 顺序听课 | 进入课程(列表刷课或自己点开)后先对齐到「第一个未学完的课时」,从第一章第一节顺序往下学 |
| 自动切节 | 本节播完(`video.ended` 或平台倒计时归零)后自动进入下一节,并等平台记账后再继续 |
| 完成即跳课 | 平台汇总变成 `已完成学习`、进度 100% 或 `x/y` 满时判定整门课完成,自动回列表选下一门;不会停在已完成页,也不会把播完的视频从头重播 |
| 多类型播放页 | 识别 `#/course/play`、`#/video/play`、`#/audio/play`、`#/ppt/play` 等播放页;单视频课程同样自动点「开始学习」 |
| 防挂机验证 | 识别「已触发防挂机验证」弹窗并点「继续学习」;滑块/拼图类验证不绕过,提示人工处理 |
| 课程列表自动刷课 | 在列表页逐门进入未学完的课程;每完成一门都重新调列表接口拿平台实时状态再选下一门,本次门数上限见下方配置表 |
| 短课程优先 | 列表刷课默认按课程总时长**从短到长**选课(跨页),先完成 1 分钟的课再学 1 小时的课;面板可关闭 |
| 考试自动空卷 | 含考试章节的课程不再跳过:自动点进考试节 → 开始/继续考试 → 一题不做直接「提交考试」→ 点「确定」交卷,交卷后课程进度被平台记账,课程即可完成;同一门课最多交卷 `maxExamTries` 次,防平台不记账时死循环 |
| 不跳过课程 | 没有任何「跳过本课」入口,也不会把某门课加入黑名单;没学完就退避重试(30 秒起翻倍,最长 5 分钟),同一门课最多重试 `maxCourseRetries` 次,超过才停下整轮刷课并提示原因,等人工处理 |
| 进度可续 | 学习进度存在 `sessionStorage`(`yun-xue-tang-run-state-v3`),整页跳转/刷新后继续上次的队列和页码;**运行开关不跨会话** —— 浏览器重启、运行器新建标签页后一律回到待机,必须显式开跑(避免未登录就报「运行中」) |
| 无头运行 | 在有/无图形界面的机器上都能跑;`runner/` 可自己起无头 Chromium 并注入脚本,适合 Linux 服务器 / Windows 无人值守常驻(见下方「无头运行」) |
## 安装
1. 浏览器安装 [Tampermonkey](https://www.tampermonkey.net/)。
2. 打开 Tampermonkey 面板 → 添加新脚本 → 粘贴 [`yun-xue-tang-assistant.user.js`](yun-xue-tang-assistant.user.js) 全文 → 保存。
3. 打开 <https://kfmic.yunxuetang.cn/login.html>,右下角出现「云学堂助手」面板:
- 填账号密码 → 点「一键登录并刷课」,登录后自动进入列表并开始逐门学习;
- 或手动登录后,在列表页点「一键刷课」。
脚本 `@grant none`,不依赖任何本地服务,可独立运行。
## 配置
配置项集中在 `src/config.js` 的 `CFG`(改完 `npm run build` 重新打包):
| 配置项 | 默认 | 作用 |
| --- | --- | --- |
| `mute` | `true` | 静音播放(自动播放更稳) |
| `autoNext` | `true` | 当前课程自动连播:本节结束自动下一节 |
| `tickMs` | `2000` | 主循环间隔 |
| `startClickCooldownMs` | `3000` | 「开始学习」重复点击冷却:3 秒内没起播就补点 |
| `entryGraceMs` | `30000` | 进课后标题/课程 id 尚未就绪的宽限,避免慢加载被误判为「课程不一致」 |
| `stuckMs` | `5 分钟` | 连续多久没有计时进展就放弃当前课程 |
| `maxCourses` | `10` | 本次最多完成多少门;`0` = 不限 |
| `maxCourseRetries` | `5` | 同一门课最多重试多少次;超过则停止整轮刷课并提示(不会跳过该课) |
| `courseRetryDelayMs` | `30000` | 首次重试前的等待;每次翻倍,最长 5 分钟 |
| `alignToFirstIncomplete` | `true` | 进入课程先从第一个未学完的课时学起;`false` = 沿用平台上次位置 |
| `preferShortCourses` | `true` | 列表刷课时优先总时长更短的课程(正序);面板勾选框「优先短课程(时长正序)」可随时切换 |
| `maxExamTries` | `2` | 同一门课「空卷交卷」的最大次数;超过仍没计入进度就按普通未完成重试(防死循环) |
| `examClickCooldownMs` | `1500` | 考试页内两次点击的间隔(毫秒) |
对齐起点对「一键刷课」和自己点开的课程(需勾选「当前课程自动连播」)都生效,
每门课只在进入时对齐一次,之后手动点其它课时不会被拉回。
短课程优先开启时,列表刷课启动会先读取一次列表接口里的课程总时长(首次约 5–10 秒,
结果在当前标签页缓存 5 分钟),把未学完课程按 `studyHours` 正序排队,再跳到目标页
逐个进入。接口不可用(未登录、跨域、平台改版)时自动降级为「当前页按时长正序」,
再不行就回到原来的列表顺序,不会让刷课任务卡住。
## 无头运行(Linux / Windows 服务器)
用 `runner/headless.mjs` 把整套逻辑跑在一个无头 Chromium 里:自己起浏览器、用 CDP 把构建产物
注入页面主世界(等价 Tampermonkey `@grant none`),不需要装浏览器插件、不需要桌面环境、
不需要 Xvfb。Linux 与 Windows 都支持,macOS 也能跑。
支持的环境:
| 环境 | 说明 |
| --- | --- |
| Linux 服务器 | 机房机器、云主机、容器;root 运行、`/dev/shm` 只有 64MB 都自动适配 |
| Windows 桌面 | 后台挂着跑;关掉控制台窗口或 `Ctrl+C` 都能让它收尾 |
| Windows 服务器核心版 / 无桌面 | 无交互桌面也能跑(Chromium 无头不需要窗口站) |
| Windows 服务 / 计划任务 Session 0 | 会检测到 `SESSIONNAME=Services` 强制无头,`headless: false` 被忽略 |
| macOS | 无头可用(本机调试场景) |
**Linux / macOS:**
```bash
# 1. 依赖(Ubuntu / Debian 为例)
sudo apt install -y chromium # 或安装官方包:google-chrome-stable
# 2. 构建产物
npm install && npm run build
# 3. 调参:改 config/runner.config.mjs(maxCourses、budgetMinutes、preferShort…)
# 只想临时覆盖就用命令行,例如 npm run headless -- --max-courses 3
# 4. 凭据走环境变量(不要写进配置文件)
export YUN_XUE_TANG_USR='你的账号'
export YUN_XUE_TANG_PWD='你的密码'
# 5. 先自检(只读:不登录、不点课程、不改进度)
npm run headless:check
# 6. 正式跑,前台常驻,Ctrl+C 结束
npm run headless
```
Linux 上建议用 `tmux` / `nohup` 托管,因为运行器是**前台进程**(不内置守护模式):
```bash
tmux new -d -s yun-xue-tang 'cd ~/yun-xue-tang-assistant && npm run headless'
tmux attach -t yun-xue-tang # 看实时输出
tail -f run-logs/headless.log # 也可以直接看日志文件
```
**Windows:**
```powershell
# 1. 浏览器:Chrome 或 Edge 都行(Edge 是 Chromium 内核,同样可用)
winget install --id Google.Chrome
# 2. 构建产物
npm install; npm run build
# 3. 调参:改 config/runner.config.mjs(无需重新 build)
# 4. 凭据(PowerShell;用 CMD 请改成 set YUN_XUE_TANG_USR=...)
$env:YUN_XUE_TANG_USR='你的账号'
$env:YUN_XUE_TANG_PWD='你的密码'
# 5. 自检 + 正式跑
npm run headless:check
npm run headless
```
也可以直接双击 [`scripts/start-headless.cmd`](scripts/start-headless.cmd):它会自动构建、检查 Node、跑完后
用 `pause` 留住退出码信息(方便看报错)。注意这个批处理文件**只写 ASCII 字符**——中文提示
全部由 Node 侧输出,原因见下方常见坑表里的「`'鍏?npm' 不是内部或外部命令`」。
Windows 上常驻的三种方式:
```powershell
# A. 隐藏窗口后台跑(立刻返回,日志看 run-logs\headless.log)
Start-Process -WindowStyle Hidden node -ArgumentList "runner/headless.mjs" -WorkingDirectory $PWD
# B. 计划任务:登录时自动开始(勾「不管用户是否登录」也能跑,会强制无头)
schtasks /create /tn "云学堂助手" /tr "node runner\headless.mjs" /sc onlogon /rl highest
# C. 只跑一段(例如每天凌晨跑 2 小时):命令行临时覆盖配置
npm run headless -- --budget-minutes 120
# 或把 budgetMinutes: 120 写进 config/runner.config.mjs,然后直接 npm run headless
```
Windows 上要注意:`Ctrl+C` 会让运行器优雅收尾(暂停视频、停批量、关浏览器)。
但如果是在任务管理器里「结束任务」或 `taskkill /F`,进程会被直接终止、收尾代码不会执行;
这种情况下次启动时会自动清理残留的浏览器进程与 `lockfile`,不需要手工处理。
### 终端面板
在终端里前台运行时(`npm run headless`、`tmux`、SSH 会话),运行器会自动开一块实时面板:
```text
╭ 云学堂助手 · 无头运行器 ─────────────────────────────────────────────────────────╮
│ 状态 刷课中 已运行 1:12:01 │
│ 课程 2025年安全生产月专题培训课程(第三期) │
│ 学时 已学 1:23:45 · 学分 12.75 · 本门 6.52 │
│ 课时 第三章 事故应急处置与自救互救 已学 62% │
│ 视频 ████████████████████░░░░░░░░░░░░ 62% 13:32/22:00 │
│ 进度 本次 3/10 · 累计 17 · 课时数 8 · 等待重试 12s · 倒计时 42s │
│ 日志 ./run-logs/headless.log · 已注入 4 次 │
├ 最近日志 ────────────────────────────────────────────────────────────────────────┤
│ [2024-05-21 09:12:03] [信息] 浏览器就绪:HeadlessChrome/124.0.6367.91 │
│ [2024-05-21 09:12:07] [信息] 已注入脚本(第 1 次):…/course/play/xxx │
╰──────────────────────────────────────────────────────────────────────────────────╯
q 退出(等价 Ctrl+C:暂停视频、停批量、关浏览器)· 完整日志照常写入日志文件
```
- **学习统计**:`学时` 那行给出两个数字——
- `已学`:**视频真正在播**的累计时长(排队、重试退避、页面加载都不计;暂停时右侧会标「暂停中,不计时」,好确认面板是活的而不是卡住了);
- `学分`:**本次运行里真正刷完**的课程累计能拿到的学分,按课程去重,重试/刷新页面不会重复计。
- `本门 6.52` 是当前在刷这门课学完能拿多少分——平台只把这个数字写在倒计时文案里(「还需 2小时 8分钟 可完成本课程学习并获得6.52学分」),学完后文案元素就消失了,所以运行器是边播边记。
- 两个数字都只统计本次运行(不落盘、不加 `stats.json`),退出即清零;退出时日志里会多一行「本次学习:视频累计播放 1:23:45,获得 12.75 学分」。
- 注意学分口径是「运行器亲眼看到刷完的课」,如果中途 `Ctrl+C` 退出,正在刷的那门课即使已经学了 90% 也不会算进学分(平台只在课程真正完成时才给分)。
- **只读**:面板不接收命令,唯一的按键是 `q`(等价 `Ctrl+C`,走同一套优雅退出:暂停视频 → 停批量 → 关浏览器)。`Ctrl+L` 可强制重绘。
- **自动降级**:stdout 不是 TTY(重定向到文件、计划任务、`nohup cmd > out.txt`)时自动关闭,回到原来的逐行日志,不会往日志里写 ANSI 控制字符。
- **不想用面板**:`--no-tui`(或配置文件 `tui: false`、环境变量 `YUN_XUE_TANG_TUI=0`)。
- **不想用颜色**:`--no-color`、配置文件 `color: false` 或 `NO_COLOR=1`;关闭后只剩框线与符号,排版不变。
- **完整日志不受影响**:面板只是终端的另一种显示方式,`run-logs/headless.log` 还是纯文本、按时间递增,`tail -f` 照常可看。
- **跟随窗口**:面板宽度直接取终端宽度,多宽就画多宽(不再封顶 120 列),每秒重画一次。拖拽窗口或用 `tmux` 分屏时,能收到 `resize` 事件的终端(Linux / macOS / Windows Terminal)去抖 60ms 后立即重排;收到不到的(Windows 传统控制台 `conhost` 拖窗口、最大化,Node 不会发任何事件)由每秒的定时刷新发现尺寸变了、自动重画,最多晚 1 秒。
- **变窄 / 还原**时要额外处理一件事:终端会把之前那些更宽的行重新折成多行,旧面板实际占的屏幕行数会比记录的逻辑行数多。运行器按「旧帧在新宽度下会折成几行」来回退光标,而不是数逻辑行;如果折完比整个窗口还高(最大化后还原就是这样),光标退不到块首,只能整屏重置(`Esc[H` + `Esc[2J`)后在顶部重画——代价是上方已经滚出去的历史日志不在屏幕上(但 `run-logs/*.log` 里一直都有一份)。小幅变窄(折完仍装得下窗口)走精确回退,不丢历史。
- **宽度不够**时按重要性丢字段,而不是一律打省略号:「进度」先丢倒计时、课时数,「视频」先缩进度条、再丢 `13:32/22:00` 这种时间标——剩下的始终是百分比和「本次/累计」骨架。
- **高度不够**时先降级成紧凑模式(不足 15 行省掉课时、日志两行,但**学时行一定保留**),再矮(不足 10 行)连 `q` 提示也省掉,更矮时连日志区一起省。任何时候帧高都不超过窗口,否则会把回滚区里的历史顶掉。
运行器做的事:
| 能力 | 说明 |
| --- | --- |
| 脚本注入 | 每次整页跳转(新 document)后自动补注入,和 Tampermonkey 按 `@match` 重注入等价 |
| 持久化登录 | 浏览器 profile 固定到 `./.run-profile`,cookie / localStorage 都留着,重启不用重登 |
| 掉登录自动重登 | cookie 失效或被踢回登录页时,用 `YUN_XUE_TANG_USR` / `YUN_XUE_TANG_PWD` 自动登录并接着刷课 |
| 崩溃自愈 | CDP 断线、浏览器崩溃、90 秒读不到脚本状态都会重启浏览器,并由看护循环在新会话里显式重新开跑(浏览器重启后 sessionStorage 清空,进度里的「完成书目」会重新从平台接口取) |
| 无进展保护 | 连续 30 分钟没有任何进展(`YUN_XUE_TANG_IDLE_RESTART_MINUTES`)时退出,避免无意义挂机 |
| 优雅退出 | `Ctrl+C` / `q`(面板里)/ `SIGTERM` 时先 `pauseAllMedia`、停批量、再关浏览器,不留脏状态(Windows 上监听 `SIGINT` / `SIGBREAK` / `SIGHUP`) |
| 残留自愈 | 上次被强杀(`kill -9` / 任务管理器「结束任务」)留下的浏览器进程与锁文件,启动时按 profile 目录自动清理,端口不会一直被占 |
| 平台适配 | 平台差异集中在 `runner/platform.mjs`:有无图形会话、沙箱参数、进程树收尾、端口排查命令都按系统出 |
| 日志 | 同时写终端和 `./run-logs/headless.log`(`YUN_XUE_TANG_LOG_MAX_BYTES` 默认 5MB,超出轮转成 `.1`) |
### 代码结构
`runner/` 按职责拆成小模块,入口只有 90 行,改哪块就看哪个文件:
| 文件 | 行数级别 | 职责 |
| --- | --- | --- |
| `runner/headless.mjs` | ~130 | 入口:解析参数 → 预检 → 交给 supervisor,只做组装 |
| `runner/config.mjs` | ~360 | 三层合并(配置文件 / 环境变量 / 命令行)+ 校验 + `--help`,其它模块只读导出常量 |
| `config/runner.config.mjs` | ~50 | **日常调参就改这里**:普通 JS 模块,可写注释,改完不用 build |
| `runner/platform.mjs` | ~230 | 平台差异:有无图形会话、沙箱参数、进程树收尾、残留进程清理、排查命令 |
| `runner/preflight.mjs` | ~95 | 启动前检查:产物、Node 版本、凭据、浏览器、调试端口(端口被占会先自愈) |
| `runner/log.mjs` | ~50 | 终端 + 文件日志,超上限轮转成 `.1` |
| `runner/stop.mjs` | ~60 | 终止信号优雅退出(Windows 走 SIGINT/SIGBREAK/SIGHUP) |
| `runner/browser.mjs` | ~230 | 浏览器探测、启动参数、陈旧锁与孤儿进程清理 |
| `runner/cdp.mjs` | ~90 | 极简 CDP 客户端(Node 22+ 原生 WebSocket,无第三方依赖) |
| `runner/page.mjs` | ~155 | 注入后要调用的页面 JS 表达式 + `page.evalJS/json/tryEval` 封装 |
| `runner/session.mjs` | ~310 | 单次会话:起浏览器 → 注入 → 自动重登 → 刷课 → 监控 → 收尾 |
| `runner/selfcheck.mjs` | ~60 | `--check` 的只读环境自检 |
| `runner/tui.mjs` | ~470 | 终端面板:框线布局、进度条、ANSI 宽度对齐、`q` 退出、尺寸自适应、非 TTY 自动关闭 |
| `runner/study.mjs` | ~110 | 学习统计:本次跑了多久(只算视频真在播)、拿到多少学分(按课程去重) |
| `runner/supervisor.mjs` | ~85 | 崩溃重启循环、退出码与本次学习统计汇总 |
模块之间是单向依赖(`headless` → `supervisor` → `session` → `page`/`selfcheck` → `cdp`),
平台相关的判断全部下沉到 `platform.mjs`(`browser.mjs` 转发它的导出,老代码不用改),
没有循环引用,也没有需要打包的步骤:`node runner/headless.mjs` 直接跑多文件 ESM。
`tui.mjs` 只单向依赖 `log.mjs`(接管终端输出)与 `study.mjs`(学时/学分累计),
所以对它来说 `session.mjs`、`supervisor.mjs` 都是「可选调用方」——面板关了也不会影响它们任何逻辑。
`study.mjs` 不读终端也不读浏览器(只吃快照 + 一个可替换的时钟),所以能脱离两者直接用假时钟测。
改脚本内部 API(`window.__yunXueTangAuto` 上的方法)只需要动 `runner/page.mjs`。
命令行参数(**日常改配置文件就行**;这里的开关只是临时覆盖,适合写进 `tmux` 命令或 `~/.bashrc`):
优先级:**内置默认值 < `config/runner.config.mjs` < 环境变量 `YUN_XUE_TANG_*` < 命令行参数**。
| 参数 | 环境变量 | 配置文件字段 | 默认 | 作用 |
| --- | --- | --- | --- | --- |
| `--check` | — | (不支持) | 关 | 只做环境自检:浏览器能启动、页面能打开、脚本能注入、视频编解码可用;不登录、不动进度,通过则退出码 0 |
| `--max-courses N`(旧名 `--max`) | `YUN_XUE_TANG_MAX_COURSES` | `maxCourses` | `10` | 本次最多完成 N 门课,`0` = 不限 |
| `--budget-minutes N`(旧名 `--budget`) | `YUN_XUE_TANG_BUDGET_MINUTES` | `budgetMinutes` | `0` | 运行 N 分钟后收尾退出(适合放进 cron 定长跑) |
| `--restart-minutes N`(旧名 `--restart`) | `YUN_XUE_TANG_RESTART_MINUTES` | `restartMinutes` | `0` | 脚本自己停下后等待多少分钟再开新一轮;`0` = 直接退出 |
| `--idle-restart-minutes N`(旧名 `--idle`) | `YUN_XUE_TANG_IDLE_RESTART_MINUTES` | `idleRestartMinutes` | `30` | 连续多少分钟无进展判定卡死 |
| `--prefer-short 0\|1` | `YUN_XUE_TANG_PREFER_SHORT` | `preferShort` | `1` | 是否优先短课程(时长正序) |
| `--headless 0\|1`(旧名 `--visible`) | `YUN_XUE_TANG_HEADLESS` | `headless` | `1` | `1` = 无头;`0` = 开有界面浏览器(仅本机调试;无图形会话时被忽略并强制无头) |
| `--origin URL` | `YUN_XUE_TANG_ORIGIN` | `origin` | `https://kfmic.yunxuetang.cn` | 站点根地址(换分公司环境时改这个) |
| `--url URL` | `YUN_XUE_TANG_URL` | `url` | `<origin>/login.html` | 起始页面 |
| `--port N` | `YUN_XUE_TANG_CDP_PORT` | `port` | `9336` | CDP 调试端口,同机多实例时分开 |
| `--profile DIR` | `YUN_XUE_TANG_PROFILE_DIR` | `profile` | `./.run-profile` | 持久化 profile 目录,删掉即重置登录态与进度缓存 |
| `--chrome PATH` | `YUN_XUE_TANG_CHROME_BIN` | `chrome` | 自动探测 | 指定 Chrome/Chromium 可执行文件 |
| `--extra-args "…"` | `YUN_XUE_TANG_EXTRA_ARGS` | `extraArgs` | 空 | 追加给浏览器的命令行参数(空格分隔) |
| `--log-file PATH`(旧名 `--log`) | `YUN_XUE_TANG_LOG_FILE` | `logFile` | `./run-logs/headless.log` | 日志文件路径 |
| `--log-max-bytes N`(旧名 `--log-max`) | `YUN_XUE_TANG_LOG_MAX_BYTES` | `logMaxBytes` | `5242880` | 单文件上限,超出轮转 |
| `--no-tui` | `YUN_XUE_TANG_TUI` | `tui` | 开 | `1`/`0`,是否在终端显示实时面板;stdout 不是 TTY 时自动关闭 |
| `--no-color` | `YUN_XUE_TANG_COLOR` | `color` | 开 | `1`/`0`,面板是否带 ANSI 颜色(也认 `NO_COLOR`) |
| `--config PATH` | `YUN_XUE_TANG_CONFIG` | — | `./config/runner.config.mjs` | 指定另一个配置文件 |
| `--help` / `-h` | — | — | — | 打印完整参数表(含配置文件字段、环境变量、当前生效值) |
| — | `YUN_XUE_TANG_HAS_DISPLAY` | — | 自动判断 | `1`/`0` 强制认定「有无图形会话」(Linux 看 `DISPLAY`,Windows 看 `SESSIONNAME`;判断不准时用) |
| — | `YUN_XUE_TANG_USR` / `YUN_XUE_TANG_PWD` | **不写入配置文件** | 必填 | 账号密码。故意只走环境变量:命令行会进进程列表/计划任务历史 |
未知参数、缺值参数、非数字值都会**直接报错并以退出码 2 退出**(不再静默忽略,避免 `--prefer-short` 拼错却以为生效了)。
### 配置文件
日常调参改 `config/runner.config.mjs` 即可,它是普通 JS 模块(可写注释、可写表达式),
改完**不需要 `npm run build`**(构建只打包注入浏览器的 `src/`):
```js
// config/runner.config.mjs
export default {
maxCourses: 0, // 0 = 不限,一直刷到没有未学完的课
budgetMinutes: 0, // 0 = 不限运行时长
preferShort: true, // 时长正序选课
restartMinutes: 0, // 0 = 停下就退出
idleRestartMinutes: 30,
port: 9336,
profile: './.run-profile',
logFile: './run-logs/headless.log',
tui: true, // 终端面板;false = 逐行日志
color: true, // 面板颜色;false 或不设 NO_COLOR 都可
};
```
- 想看全部字段与当前生效值:`node runner/headless.mjs --help`
- 想只为一个场景换配置:`node runner/headless.mjs --config ./my.mjs`
- 个人机器的差异建议放 `runner.local.mjs`(已在 `.gitignore` 里)并用 `--config ./runner.local.mjs`
- 配置文件里写 `username` / `password` 会被**忽略并告警**(凭据只认环境变量);写未知字段也会告警
退出码:`0` 正常收尾(达到 `maxCourses` / `budgetMinutes` / 无更多可学课程)、`1` 无进展卡死、
`2` 环境或参数问题(缺构建产物、缺凭据、找不到浏览器、端口被占、参数写错)、`3` 连续 5 次登录失败(见 runner/)
(多半是密码错误或站点要求验证码)。
无图形环境常见的坑:
| 现象 | 平台 | 原因与处理 |
| --- | --- | --- |
| 启动报 `Missing X server or $DISPLAY` | Linux | 有界面模式需要显示服务。运行器已自动判断:无 `DISPLAY` 强制无头 |
| `Running as root without --no-sandbox is not supported` | Linux | 运行器在 Linux 上默认加 `--no-sandbox --disable-setuid-sandbox` |
| 标签页莫名崩溃 / `Target closed` | Linux 容器 | `/dev/shm` 太小(默认 64MB)。运行器自动加 `--disable-dev-shm-usage` |
| 中文显示成方块 | Linux | 只影响截图观感(脚本靠 DOM 文本匹配,不依赖字体)。需要截图时 `apt install fonts-noto-cjk` |
| 视频一直 0 秒、`error.code=4` | 全平台 | 该 Chromium 不带 H.264/AAC 专有编解码器。Linux 上改装 `google-chrome-stable`(官方包带);Windows 上用官方 Chrome/Edge 即可。`npm run headless:check` 会直接告诉你 |
| 登录页自动登录失败 | 全平台 | 站点要求验证码/滑块时无头环境无法完成,需要人工在 `headless: false`(有界面)模式下登录一次,之后靠持久化 profile 的 cookie |
| 端口被占 | 全平台 | 运行器会先清理「命令行带本 profile」的残留浏览器(自愈);仍被别的程序占用时按提示换 `--port`。提示命令按平台出:Linux `pkill -f "remote-debugging-port=9336"`,Windows `netstat -ano \| findstr :9336` + `taskkill /PID <PID> /T /F` |
| `"无法创建数据目录"` / `配置文件正在使用中` | Windows | 上次浏览器被强杀后 profile 还锁着。运行器启动时会自动清理;也可手动删掉 `.run-profile`(会丢失登录态) |
| `Ctrl+C` 后浏览器没关 | Windows | 用了任务管理器「结束任务」/ `taskkill /F` 时收尾代码不执行(TerminateProcess)。下次启动会自动清理残留进程 |
| 面板显示错行 / 有残留字符 | 全平台 | 终端被非运行器输出(后台脚本、`echo`、另一个进程)插话会打乱面板,按 `Ctrl+L` 重绘一次即可;或用 `--no-tui` 退回逐行日志 |
| 计划任务里一起床就退出 | Windows | 运行在 Session 0 没有桌面。运行器检测 `SESSIONNAME=Services` 后强制无头,正常;若仍失败看 `run-logs/headless.log` |
| `'鍏?npm' 不是内部或外部命令` / `'01' 不是内部或外部命令` / `'rofile' 不是内部或外部命令` | Windows | 批处理文件里出现了**中文(非 ASCII)字符**或**裸 LF 行尾**。cmd.exe 按当前代码页逐字节读批处理,多字节字符和 LF 都会让行偏移错位,于是把一行拆成几段当命令执行。修法:`.cmd` 只用 ASCII 且必须 CRLF。`npm run check` 会直接拦下这类文件 |
Linux 上不需要 Xvfb,但如果你确实想跑有界面模式(例如远程看面板、人工过验证码),
可以 `apt install xvfb x11vnc` 后 `xvfb-run -s "-screen 0 1360x940x24" npm run headless -- --headless 0`。
## 开发热加载
源码已拆分为 `src/` 下的多个模块,构建后合成单文件脚本。改完保存即生效,不用复制粘贴、不用刷新页面。详见 [dev/README.md](dev/README.md)。
```powershell
npm install # 首次需要(安装 esbuild)
npm run build # 打包 src/ → yun-xue-tang-assistant.user.js
npm run build:watch # 监听 src/,保存即自动重新打包
npm run dev # 等价于 node dev/serve.mjs,默认 127.0.0.1:8899
```
Windows 下也可以直接双击 [`scripts/start-dev.cmd`](scripts/start-dev.cmd)。脚本暴露 `window.__yunXueTangDispose()`,
加载器在注入新版本前先释放旧实例(定时器、监听器、面板),因此视频播放不会被打断。
## 目录结构
```text
README.md 说明文档(本文件)
package.json / package-lock.json npm scripts 与依赖锁(唯一依赖:esbuild)
.gitattributes / .gitignore 换行符与忽略规则
yun-xue-tang-assistant.user.js 构建产物(唯一需要安装的文件,不要手改)
src/ 业务脚本源码(拆成多个模块,日常改这里)
meta.js UserScript 头 + 用法注释
config.js CFG / 常量 / VERSION
lifecycle.js 定时器·监听器·dispose
utils.js DOM 工具
state.js S / R / 持久化
panel.js 悬浮面板
route.js 路由识别
login.js 登录 / 一键刷课
list.js 列表页 + 短课程优先
player.js 播放器 / 防挂机 / 课时切换
exam.js 考试自动空卷交卷
course.js 课程页主循环
complete.js 完成 / 未完成重试
index.js 主循环 / 启动 / 调试入口
scripts/ 开发与运维脚本(不在构建产物里)
build.mjs esbuild 打包脚本(产物写回仓库根)
check.mjs 静态检查:node --check + 批处理纯 ASCII/CRLF 校验
start-dev.cmd Windows 一键启动本地热加载服务(双击即可)
start-headless.cmd Windows 一键启动无头运行器(双击即可)
runner/ 无头运行器(Linux / Windows,无图形化环境)
headless.mjs 入口:组装 配置 → 预检 → supervisor
config.mjs 参数 / 配置文件 / 环境变量三层合并 + --help
platform.mjs 平台差异(图形会话、沙箱、进程树、残留清理、排查命令)
preflight.mjs 启动前检查(产物 / Node / 凭据 / 浏览器 / 端口)
log.mjs 终端 + 文件日志
stop.mjs 终止信号优雅退出
browser.mjs 浏览器探测、启动参数、陈旧锁与孤儿进程清理
cdp.mjs 极简 CDP 客户端(Node 22+ 原生 WebSocket)
page.mjs 页面求值封装与注入后调用的表达式
session.mjs 单次会话:起浏览器 / 注入 / 自动重登 / 崩溃自愈
selfcheck.mjs --check 只读环境自检
tui.mjs 终端面板(框线 + 进度条,q 退出,非 TTY 自动关闭)
study.mjs 学习统计(本次播放时长 / 获得学分)
supervisor.mjs 崩溃重启循环与退出码
config/
runner.config.mjs 无头运行器配置(日常调参改这里,不用 build)
dev/ 本地热加载开发工具(HTTP 服务 + 薄加载器)
serve.mjs 本地 HTTP 服务(默认 127.0.0.1:8899)
dev-loader.user.js Tampermonkey 里的薄加载器
tests/ 真机测试(真实 Chrome + 真实站点)
real-cdp.mjs 极简 CDP 客户端(三个测试共用)
real-test.mjs 面板渲染 / 路由 / 热替换断言(只读)
real-e2e.mjs 真实账号登录 → 列表 → 进课 → 播放
real-run.mjs 持续跑:跨章节 / 跨课程 / 断线重启
tui-test.mjs 终端面板自测(不用浏览器:列宽 / 截断 / 极端尺寸)
study-test.mjs 学习统计自测(假时钟:暂停不计时 / 防重复计分)
docs/
reports/ 历史实跑报告
run-report-v203.md 2026-10-19 实跑报告(v2.0.3)
evidence/ 当前版本的证据(叙述 + 接口日志)
archive/v2.0-snapshots/ v2.0.x 时期的原始抓取片段(仅存档)
screenshots/ 手工挑选的展示截图(测试自动截图不进库)
```
## 本机数据
本机数据分三层存放,按「这条信息跨会话是否还成立」区分:
| `localStorage` 键(用户偏好,跨会话有效) | 内容 |
| --- | --- |
| `yun-xue-tang-login-v1` | 勾选「记住密码」时的账号密码(base64 混淆,**不是加密**) |
| `yun-xue-tang-auto-play-enabled` | 「当前课程自动连播」开关 |
| `yun-xue-tang-prefer-short` | 「优先短课程(时长正序)」开关(`1` / `0`) |
| `yun-xue-tang-target-catalog-url` | 目标目录 URL:决定刷哪个学院/目录的课(短课程队列的缓存键也来自它) |
| `yun-xue-tang-auto-start-after-login` | 登录后自动开始刷课的一次性标记(5 分钟内有效) |
| `sessionStorage` 键(本次运行,关掉标签页即清空) | 内容 |
| --- | --- |
| `yun-xue-tang-run-state-v3` | 本轮是否在跑、页码、当前课程、本轮已完成与待重试记录 |
| `yun-xue-tang-short-catalog-v1` | 短课程时长队列缓存(TTL 5 分钟) |
旧版本(v2.8.0 之前)把所有状态整块存在 `localStorage` 的 `yun-xue-tang-batch-v2` 里,
包括「是否在跑」。现在这个键只在启动时做一次性迁移:只迁进度(已完成书目、
待重试、页码、目标目录),**不再恢复运行状态与当前课程**,迁移完即删除。
无头运行时这些键存在 `./.run-profile/` 下的浏览器 profile 里(不在仓库、不入库),
删掉该目录即等于「清空登录态 + 重置进度」。
公用电脑请不要勾选「记住密码」;面板上的「清除密码」可随时删除本机保存的凭据。
## 已知限制
- 平台按真实播放时长计时,倍速/快进不会减少所需时间;脚本不提供这类加速。
- 直接改 URL 或刷新课程页时,脚本优先用 URL 里的 `kngId` 校验课程;只有 URL 没有 id、
且页面标题超过 30 秒仍是 `loading...` 时才可能误判并回到列表。从列表正常进入不受影响。
- 验证码、滑块、拼图类验证需要人工完成,脚本不会绕过。
- 平台存在同名课程(同一门课出现在多个目录)。脚本按课程 id 精确点击,但完成/重试记录仍沿用
按标题去重的旧逻辑,同名课程不会重复安排。
- 平台改版(目录结构、弹窗、倒计时文案、列表接口字段、完成文案变化)可能导致识别失败,
需要更新选择器/完成判定。
## 免责声明
本项目仅用于个人学习自动化实践。请遵守所在单位与平台的使用规定,是否使用及由此产生的后果由使用者自行承担。
## 实跑记录
真实站点(`kfmic.yunxuetang.cn`)的完整实跑过程、发现的问题与修复记录见 [`docs/reports/run-report-v203.md`](docs/reports/run-report-v203.md),
证据文件在 [`docs/evidence/`](docs/evidence/),截图在 [`docs/screenshots/`](docs/screenshots/)。
v2.5.2 修复「进入课程不从第一个未学完的课时开始」的定位过程、复刻用例与修复前后对比,
见 [`docs/evidence/align-start-evidence.txt`](docs/evidence/align-start-evidence.txt)。
v2.6.0 新增「优先短课程(时长正序)」:真实站点读取 5148 门课程、跨页跳到最短课程所在页的
实跑记录与 3 个回归用例,见 [`docs/evidence/short-course-evidence.txt`](docs/evidence/short-course-evidence.txt);
面板效果见 [`docs/screenshots/panel-short.png`](docs/screenshots/panel-short.png)。
v2.8.0 状态分层重构:刷课开关不再进 localStorage(修「还没登录就开始刷课」)、字段名语义化、
短课程模式下页码导航所有权归一到 `chooseShortCourse`(省掉每次多跳一页+白等 3.5 秒)。
v2.7.0 修复「进入课程有概率不自动播放」和「学完后不转下一门」:新增单视频/音频/课件播放页识别,
完成判定同时支持 `已完成 x/y`、`已完成 N%`、`已完成学习`;真机复现、修复前后对比与回归结果见
[`docs/evidence/completion-next-evidence.txt`](docs/evidence/completion-next-evidence.txt)。
无头运行(Linux 服务器 / Windows 无人值守):新增 `runner/`,自己起无头 Chromium + CDP 注入,
持久化登录、掉登录自动重登、崩溃自愈;环境自检、真实刷课、断线重启、优雅退出的实跑记录见
[`docs/evidence/headless-linux-evidence.txt`](docs/evidence/headless-linux-evidence.txt),
平台差异与 Windows 侧适配见其中「九、跨平台适配」一节。