From ae117222dfa0af0fb1c53cb23563f48d9dd75e2e Mon Sep 17 00:00:00 2001 From: void Date: Sun, 25 Oct 2026 23:04:40 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20v2.8.0=20=E6=97=A0=E5=A4=B4=E8=BF=90?= =?UTF-8?q?=E8=A1=8C=E5=99=A8=E3=80=81=E8=80=83=E8=AF=95=E8=87=AA=E5=8A=A8?= =?UTF-8?q?=E4=BA=A4=E5=8D=B7=E3=80=81=E6=94=B9=E4=B8=BA=E9=80=80=E9=81=BF?= =?UTF-8?q?=E9=87=8D=E8=AF=95=E4=B8=8D=E8=B7=B3=E8=AF=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增无头运行能力,解决 Linux 无图形化服务器上无法常驻的问题;同时改掉 "遇到考试课/无进展课就跳过"的策略,改为在同门课上退避重试。 - runner/:自己起无头 Chromium,用 CDP 把构建产物注入页面主世界(等价 @grant none),不装插件、不需要桌面环境或 Xvfb;含浏览器探测与启动参数、 持久化 profile、陈旧 SingletonLock 清理、优雅退出、日志轮转、启动预检 - runner.config.mjs / start-headless.cmd:通用配置 + Windows 一键入口; 凭据只走 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD 环境变量 - src/exam.js:含考试章节的课程自动进考试 → 开始/继续 → 空卷提交 → 确定, 交卷后靠平台记账推进课程;maxExamTries 限制同门课交卷次数,防不记账时死循环 - 去掉跳过与黑名单:没学完就退避重试(30s 起翻倍,最长 5 分钟), 同门课超过 maxCourseRetries 次才停整轮并提示,替代原 maxConsecutiveFailures - 每完成一门都重新拉列表接口取平台实时状态再选下一门,避免用陈旧队列 - 学习进度改存 sessionStorage(yun-xue-tang-run-state-v3),整页跳转/刷新可续; 运行开关不跨会话,浏览器重启后必须显式开跑 - dev/:新增 real-cdp / real-run / real-test / real-e2e 实跑脚本与 check.mjs 统一静态检查(JS 22 + 批处理 2),替代逐文件 node --check - docs/evidence/headless-linux-evidence.txt + 实跑截图,README 补无头部署章节 --- .gitignore | 5 + README.md | 289 +++- build.mjs | 8 +- dev/README.md | 85 +- dev/check.mjs | 115 ++ dev/dev-loader.user.js | 18 +- dev/real-cdp.mjs | 88 ++ dev/real-e2e.mjs | 421 ++++++ dev/real-run.mjs | 467 ++++++ dev/real-test.mjs | 325 +++++ dev/serve.mjs | 6 +- dev/start-dev.cmd | 7 +- docs/evidence/headless-linux-evidence.txt | 361 +++++ docs/evidence/short-course-evidence.txt | 4 +- docs/screenshots/e2e-01-after-login.png | Bin 0 -> 5184 bytes docs/screenshots/e2e-02-playing.png | Bin 0 -> 463739 bytes docs/screenshots/real-chrome-login.png | Bin 0 -> 692948 bytes package.json | 10 +- runner.config.mjs | 49 + runner/browser.mjs | 271 ++++ runner/cdp.mjs | 87 ++ runner/config.mjs | 356 +++++ runner/headless.mjs | 106 ++ runner/log.mjs | 51 + runner/page.mjs | 149 ++ runner/platform.mjs | 230 +++ runner/preflight.mjs | 97 ++ runner/selfcheck.mjs | 62 + runner/session.mjs | 342 +++++ runner/stop.mjs | 64 + runner/supervisor.mjs | 80 ++ src/complete.js | 130 +- src/config.js | 34 +- src/course.js | 97 +- src/exam.js | 302 ++++ src/index.js | 45 +- src/lifecycle.js | 10 +- src/list.js | 157 +- src/login.js | 23 +- src/meta.js | 35 +- src/panel.js | 121 +- src/player.js | 36 +- src/route.js | 11 +- src/state.js | 229 ++- src/utils.js | 9 + start-headless.cmd | 60 + yun-xue-tang-assistant.user.js | 1583 ++++++++++++++------- 47 files changed, 6198 insertions(+), 837 deletions(-) create mode 100644 dev/check.mjs create mode 100644 dev/real-cdp.mjs create mode 100644 dev/real-e2e.mjs create mode 100644 dev/real-run.mjs create mode 100644 dev/real-test.mjs create mode 100644 docs/evidence/headless-linux-evidence.txt create mode 100644 docs/screenshots/e2e-01-after-login.png create mode 100644 docs/screenshots/e2e-02-playing.png create mode 100644 docs/screenshots/real-chrome-login.png create mode 100644 runner.config.mjs create mode 100644 runner/browser.mjs create mode 100644 runner/cdp.mjs create mode 100644 runner/config.mjs create mode 100644 runner/headless.mjs create mode 100644 runner/log.mjs create mode 100644 runner/page.mjs create mode 100644 runner/platform.mjs create mode 100644 runner/preflight.mjs create mode 100644 runner/selfcheck.mjs create mode 100644 runner/session.mjs create mode 100644 runner/stop.mjs create mode 100644 runner/supervisor.mjs create mode 100644 src/exam.js create mode 100644 start-headless.cmd diff --git a/.gitignore b/.gitignore index fb644fd..51940b8 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,9 @@ node_modules/ # ---- 运行 / 调试产物 ---- # 本地实跑会在这里生成浏览器配置目录、截图和一次性调试脚本,体积很大,不入库 .run-tmp/ +# 无头运行器的持久化 profile(含登录 cookie,绝不能入库)和运行日志 +.run-profile/ +run-logs/ *.log *.tmp @@ -18,3 +21,5 @@ desktop.ini # ---- 本地私有配置(不要提交账号信息) ---- .env .env.* +# 个人临时覆盖用的运行器配置(放进仓库的 runner.config.mjs 保持通用) +runner.local.mjs diff --git a/README.md b/README.md index 3550be4..7f655f0 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ # 云学堂助手 -在云学堂(`*.yunxuetang.cn`)上自动登录、按目录顺序听课、自动切节,并在课程列表页批量推进的 -Tampermonkey 用户脚本。支持多课时课程与单视频/音频课程;一门课学完会自动回列表选下一门。 +在云学堂(`*.yunxuetang.cn`)上自动登录、按目录顺序听课、自动切节,并在课程列表页逐门推进的 +Tampermonkey 用户脚本。支持多课时课程与单视频/音频课程;含考试章节的课程会自动进入考试、 +不答题直接交卷;一门课学完会自动回列表选下一门。 平台按**真实播放时长**计时,脚本只负责「自动点播放、自动切下一节、处理防挂机弹窗」, 不快进、不改进度、不伪造学时。 @@ -12,22 +13,24 @@ Tampermonkey 用户脚本。支持多课时课程与单视频/音频课程;一 | 能力 | 说明 | | --- | --- | | 一键登录 | 面板里填账号密码,自动填充表单、勾选协议、点击登录;支持记住密码与自动登录 | -| 顺序听课 | 进入课程(手动打开或批量进入)后先对齐到「第一个未学完的课时」,从第一章第一节顺序往下学 | +| 顺序听课 | 进入课程(列表刷课或自己点开)后先对齐到「第一个未学完的课时」,从第一章第一节顺序往下学 | | 自动切节 | 本节播完(`video.ended` 或平台倒计时归零)后自动进入下一节,并等平台记账后再继续 | | 完成即跳课 | 平台汇总变成 `已完成学习`、进度 100% 或 `x/y` 满时判定整门课完成,自动回列表选下一门;不会停在已完成页,也不会把播完的视频从头重播 | | 多类型播放页 | 识别 `#/course/play`、`#/video/play`、`#/audio/play`、`#/ppt/play` 等播放页;单视频课程同样自动点「开始学习」 | | 防挂机验证 | 识别「已触发防挂机验证」弹窗并点「继续学习」;滑块/拼图类验证不绕过,提示人工处理 | -| 批量刷课 | 在列表页逐门进入未学完的课程,本次门数与连续失败上限见下方配置表 | -| 短课程优先 | 批量模式默认按课程总时长**从短到长**选课(跨页),先完成 1 分钟的课再学 1 小时的课;面板可关闭 | -| 失败隔离 | 答题/考试类课程、长时间无计时进展的课程会被跳过并记录原因,不影响后续课程 | -| 进度可续 | 运行状态存在 `localStorage`,刷新、热更新后继续上次的队列和页码 | +| 课程列表自动刷课 | 在列表页逐门进入未学完的课程;每完成一门都重新调列表接口拿平台实时状态再选下一门,本次门数上限见下方配置表 | +| 短课程优先 | 列表刷课默认按课程总时长**从短到长**选课(跨页),先完成 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. 打开 ,右下角出现「云学堂助手」面板: - - 填账号密码 → 点「一键登录并刷课」,登录后自动进入列表并开始批量学习; + - 填账号密码 → 点「一键登录并刷课」,登录后自动进入列表并开始逐门学习; - 或手动登录后,在列表页点「一键刷课」。 脚本 `@grant none`,不依赖任何本地服务,可独立运行。 @@ -39,23 +42,220 @@ Tampermonkey 用户脚本。支持多课时课程与单视频/音频课程;一 | 配置项 | 默认 | 作用 | | --- | --- | --- | | `mute` | `true` | 静音播放(自动播放更稳) | -| `autoNext` | `true` | 手动打开课程时,本节结束自动下一节 | +| `autoNext` | `true` | 当前课程自动连播:本节结束自动下一节 | | `tickMs` | `2000` | 主循环间隔 | | `startClickCooldownMs` | `3000` | 「开始学习」重复点击冷却:3 秒内没起播就补点 | | `entryGraceMs` | `30000` | 进课后标题/课程 id 尚未就绪的宽限,避免慢加载被误判为「课程不一致」 | | `stuckMs` | `5 分钟` | 连续多久没有计时进展就放弃当前课程 | | `maxCourses` | `10` | 本次最多完成多少门;`0` = 不限 | -| `maxConsecutiveFailures` | `5` | 连续失败多少门后自动停止 | +| `maxCourseRetries` | `5` | 同一门课最多重试多少次;超过则停止整轮刷课并提示(不会跳过该课) | +| `courseRetryDelayMs` | `30000` | 首次重试前的等待;每次翻倍,最长 5 分钟 | | `alignToFirstIncomplete` | `true` | 进入课程先从第一个未学完的课时学起;`false` = 沿用平台上次位置 | -| `preferShortCourses` | `true` | 批量选课时优先总时长更短的课程(正序);面板勾选框「优先短课程(时长正序)」可随时切换 | +| `preferShortCourses` | `true` | 列表刷课时优先总时长更短的课程(正序);面板勾选框「优先短课程(时长正序)」可随时切换 | +| `maxExamTries` | `2` | 同一门课「空卷交卷」的最大次数;超过仍没计入进度就按普通未完成重试(防死循环) | +| `examClickCooldownMs` | `1500` | 考试页内两次点击的间隔(毫秒) | -对齐起点对「一键刷课」和手动打开课程(需勾选「手动课程自动连播」)都生效, +对齐起点对「一键刷课」和自己点开的课程(需勾选「当前课程自动连播」)都生效, 每门课只在进入时对齐一次,之后手动点其它课时不会被拉回。 -短课程优先开启时,批量任务启动会先读取一次列表接口里的课程总时长(首次约 5–10 秒, +短课程优先开启时,列表刷课启动会先读取一次列表接口里的课程总时长(首次约 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. 调参:改仓库根目录的 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. 调参:改 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 +``` + +也可以直接双击 [`start-headless.cmd`](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 写进 runner.config.mjs,然后直接 npm run headless +``` + +Windows 上要注意:`Ctrl+C` 会让运行器优雅收尾(暂停视频、停批量、关浏览器)。 +但如果是在任务管理器里「结束任务」或 `taskkill /F`,进程会被直接终止、收尾代码不会执行; +这种情况下次启动时会自动清理残留的浏览器进程与 `lockfile`,不需要手工处理。 + +运行器做的事: + +| 能力 | 说明 | +| --- | --- | +| 脚本注入 | 每次整页跳转(新 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` / `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`,其它模块只读导出常量 | +| `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` | ~150 | 注入后要调用的页面 JS 表达式 + `page.evalJS/json/tryEval` 封装 | +| `runner/session.mjs` | ~310 | 单次会话:起浏览器 → 注入 → 自动重登 → 刷课 → 监控 → 收尾 | +| `runner/selfcheck.mjs` | ~60 | `--check` 的只读环境自检 | +| `runner/supervisor.mjs` | ~75 | 崩溃重启循环与退出码 | + +模块之间是单向依赖(`headless` → `supervisor` → `session` → `page`/`selfcheck` → `cdp`), +平台相关的判断全部下沉到 `platform.mjs`(`browser.mjs` 转发它的导出,老代码不用改), +没有循环引用,也没有需要打包的步骤:`node runner/headless.mjs` 直接跑多文件 ESM。 +改脚本内部 API(`window.__yunXueTangAuto` 上的方法)只需要动 `runner/page.mjs`。 + +命令行参数(**日常改配置文件就行**;这里的开关只是临时覆盖,适合写进 `tmux` 命令或 `~/.bashrc`): + +优先级:**内置默认值 < `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` | `/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` | 单文件上限,超出轮转 | +| `--config PATH` | `YUN_XUE_TANG_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` 拼错却以为生效了)。 + +### 配置文件 + +日常调参改仓库根目录的 `runner.config.mjs` 即可,它是普通 JS 模块(可写注释、可写表达式), +改完**不需要 `npm run build`**(构建只打包注入浏览器的 `src/`): + +```js +// 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', +}; +``` + +- 想看全部字段与当前生效值:`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 /T /F` | +| `"无法创建数据目录"` / `配置文件正在使用中` | Windows | 上次浏览器被强杀后 profile 还锁着。运行器启动时会自动清理;也可手动删掉 `.run-profile`(会丢失登录态) | +| `Ctrl+C` 后浏览器没关 | Windows | 用了任务管理器「结束任务」/ `taskkill /F` 时收尾代码不执行(TerminateProcess)。下次启动会自动清理残留进程 | +| 计划任务里一起床就退出 | 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`。 ## 开发热加载 @@ -68,7 +268,7 @@ npm run build:watch # 监听 src/,保存即自动重新打包 npm run dev # 等价于 node dev/serve.mjs,默认 127.0.0.1:8899 ``` -Windows 下也可以直接双击 [`dev/start-dev.cmd`](dev/start-dev.cmd)。脚本暴露 `window.__ytDispose()`, +Windows 下也可以直接双击 [`dev/start-dev.cmd`](dev/start-dev.cmd)。脚本暴露 `window.__yunXueTangDispose()`, 加载器在注入新版本前先释放旧实例(定时器、监听器、面板),因此视频播放不会被打断。 ## 目录结构 @@ -85,12 +285,28 @@ src/ 业务脚本源码(拆成多个模块,日 login.js 登录 / 一键刷课 list.js 列表页 + 短课程优先 player.js 播放器 / 防挂机 / 课时切换 + exam.js 考试自动空卷交卷 course.js 课程页主循环 - complete.js 完成 / 失败 + complete.js 完成 / 未完成重试 index.js 主循环 / 启动 / 调试入口 build.mjs esbuild 打包脚本 +runner.config.mjs 无头运行器配置文件(日常调参改这里,不用 build) +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 只读环境自检 + supervisor.mjs 崩溃重启循环与退出码 package-lock.json 依赖锁(esbuild) -package.json npm scripts(build / build:watch / dev / check) +package.json npm scripts(build / build:watch / dev / headless / check) yun-xue-tang-assistant.user.js 构建产物(唯一需要安装的文件,不要手改) dev/ 本地热加载开发工具(HTTP 服务 + 薄加载器) docs/screenshots/ 实跑截图 @@ -100,16 +316,27 @@ docs/evidence/ 实跑日志与接口证据 ## 本机数据 -| `localStorage` 键 | 内容 | -| --- | --- | -| `yt-batch-v2` | 批量刷课队列、当前课程、页码、已完成/失败记录 | -| `yt-login-v1` | 勾选「记住密码」时的账号密码(base64 混淆,**不是加密**) | -| `yt-auto-play-enabled` | 「手动课程自动连播」开关 | -| `yt-prefer-short` | 「优先短课程(时长正序)」开关(`1` / `0`) | -| `yt-auto-start-after-login` | 登录后自动开始刷课的一次性标记(5 分钟内有效) | +本机数据分三层存放,按「这条信息跨会话是否还成立」区分: -短课程队列缓存在 `sessionStorage` 的 `yt-short-catalog-v1`,关闭标签页即清空, -不写入长期存储。 +| `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 里(不在仓库、不入库), +删掉该目录即等于「清空登录态 + 重置进度」。 公用电脑请不要勾选「记住密码」;面板上的「清除密码」可随时删除本机保存的凭据。 @@ -119,7 +346,7 @@ docs/evidence/ 实跑日志与接口证据 - 直接改 URL 或刷新课程页时,脚本优先用 URL 里的 `kngId` 校验课程;只有 URL 没有 id、 且页面标题超过 30 秒仍是 `loading...` 时才可能误判并回到列表。从列表正常进入不受影响。 - 验证码、滑块、拼图类验证需要人工完成,脚本不会绕过。 -- 平台存在同名课程(同一门课出现在多个目录)。脚本按课程 id 精确点击,但完成/失败记录仍沿用 +- 平台存在同名课程(同一门课出现在多个目录)。脚本按课程 id 精确点击,但完成/重试记录仍沿用 按标题去重的旧逻辑,同名课程不会重复安排。 - 平台改版(目录结构、弹窗、倒计时文案、列表接口字段、完成文案变化)可能导致识别失败, 需要更新选择器/完成判定。 @@ -140,6 +367,14 @@ 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 侧适配见其中「九、跨平台适配」一节。 diff --git a/build.mjs b/build.mjs index 6bb302f..08e1d9b 100644 --- a/build.mjs +++ b/build.mjs @@ -35,16 +35,16 @@ const common = { target: ['chrome80', 'firefox78', 'safari13'], minify, charset: 'utf8', - // __YT_VERSION__ 由 src/config.js 引用,构建时替换成 package.json 的版本号 - define: { __YT_VERSION__: JSON.stringify(version) }, + // __YUN_XUE_TANG_VERSION__ 由 src/config.js 引用,构建时替换成 package.json 的版本号 + define: { __YUN_XUE_TANG_VERSION__: JSON.stringify(version) }, // 用原生 import/export + format=iife,esbuild 不会注入 __export 等辅助代码。 logLevel: 'info', }; -// src/meta.js 里的 @version 写成 __YT_VERSION__,由这里按 package.json 替换 +// src/meta.js 里的 @version 写成 __YUN_XUE_TANG_VERSION__,由这里按 package.json 替换 async function bannerText() { const raw = await readFile(META, 'utf8'); - return raw.replace('__YT_VERSION__', version).trimEnd() + '\n'; + return raw.replace('__YUN_XUE_TANG_VERSION__', version).trimEnd() + '\n'; } const buildOptions = (banner) => ({ ...common, banner: { js: banner }, outfile: OUT }); diff --git a/dev/README.md b/dev/README.md index 9260e2b..a2a754f 100644 --- a/dev/README.md +++ b/dev/README.md @@ -13,9 +13,10 @@ | `serve.mjs` | 本地 HTTP 服务,向浏览器提供源码与版本哈希(127.0.0.1:8899) | | `dev-loader.user.js` | Tampermonkey 里的薄加载器,轮询版本、释放旧实例、注入新实例 | | `start-dev.cmd` | 双击启动服务 | +| `check.mjs` | `npm run check` 的实现:自动遍历 `runner/`、`dev/` 与顶层文件跑 `node --check`,同时检查 `.cmd` 必须是纯 ASCII + CRLF(cmd.exe 逐字节按代码页读批处理,中文和裸 LF 会让行偏移错位);新增模块不用再手改命令 | 原理:加载器每 1 秒请求 `/version`,发现哈希变化就调用旧实例暴露的 -`window.__ytDispose()`(清定时器 / 监听器 / 面板),再把新源码以 `