# 云学堂助手 在云学堂(`*.yunxuetang.cn`)上自动登录、按目录顺序听课、自动切节,并在课程列表页逐门推进的 Tampermonkey 用户脚本。支持多课时课程与单视频/音频课程;含考试章节的课程会自动进入考试、 不答题直接交卷;一门课学完会自动回列表选下一门。 平台按**真实播放时长**计时,脚本只负责「自动点播放、自动切下一节、处理防挂机弹窗」, 不快进、不改进度、不伪造学时。 ![控制面板](docs/screenshots/panel.png) ## 功能 | 能力 | 说明 | | --- | --- | | 一键登录 | 面板里填账号密码,自动填充表单、勾选协议、点击登录;支持记住密码与自动登录 | | 顺序听课 | 进入课程(列表刷课或自己点开)后先对齐到「第一个未学完的课时」,从第一章第一节顺序往下学 | | 自动切节 | 本节播完(`video.ended` 或平台倒计时归零)后自动进入下一节,并等平台记账后再继续 | | 完成即跳课 | 平台汇总变成 `已完成学习`、进度 100% 或 `x/y` 满时判定整门课完成,自动回列表选下一门;不会停在已完成页,也不会把播完的视频从头重播 | | 多类型播放页 | 识别 `#/course/play`、`#/video/play`、`#/audio/play`、`#/ppt/play` 等播放页;单视频课程同样自动点「开始学习」 | | 防挂机验证 | 识别「已触发防挂机验证」弹窗并点「继续学习」;滑块/拼图类验证不绕过,提示人工处理 | | 课程列表自动刷课 | 在列表页逐门进入未学完的课程;每完成一门都重新调列表接口拿平台实时状态再选下一门,本次门数上限见下方配置表 | | 短课程优先 | 列表刷课默认按课程总时长**从短到长**选课(跨页),先完成 1 分钟的课再学 1 小时的课;面板可关闭 | | 每日积分模式 | 按**课时类型**计分:文档 1 次、视频 3 次、音频 2 次、微课 2 次,每次 3 分,单日封顶 24 分。先补文档/音频/微课单条内容,视频额度靠课程里的视频课时;某类满额自动切下一类,四类都满(或剩余类型没内容)就停止刷课。计数存 localStorage、跨刷新/重启不丢、跨天清零;面板可随时关闭 | | 考试自动空卷 | 含考试章节的课程不再跳过:自动点进考试节 → 开始/继续考试 → 一题不做直接「提交考试」→ 点「确定」交卷,交卷后课程进度被平台记账,课程即可完成。只有本页真的点过「提交考试/确定交卷」,看到的结果页才算一次交卷;平台恢复的旧结果页会先回「考试说明页」重新进入,不会在结果页和课程页之间空转。同一门课最多交卷 `maxExamTries` 次,超过仍不记账就跳过该课继续下一门(写明原因) | | 不跳过普通课程 | 没有任何「跳过本课」入口,也不会把普通课程加入黑名单;没学完就退避重试(30 秒起翻倍,最长 5 分钟),同一门课最多重试 `maxCourseRetries` 次,超过才停下整轮刷课并提示原因,等人工处理。**唯一例外**:考试空卷交卷达到 `maxExamTries` 仍未计入进度,或考试页始终没有可点的「开始考试/提交考试」——继续重试只会反复进同一门课,因此本轮跳过它、继续刷其它课 | | 进度可续 | 学习进度存在 `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`,不依赖任何本地服务,可独立运行。 ## 配置 配置项集中在 `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` | 列表刷课时优先总时长更短的课程(正序);面板勾选框「优先短课程(时长正序)」可随时切换 | | `pointsEnabled`(`localStorage`) | `true` | 每日积分模式:文档 1 / 视频 3 / 音频 2 / 微课 2(每次 3 分,封顶 24 分);面板勾选框「每日积分模式」可随时切换 | | `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 都自动适配 | | Docker 容器 | 自带官方 Chrome 与 Node 22,镜像内已完成构建;见下方「容器(Docker)」 | | 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` | 是否优先短课程(时长正序) | | `--points-mode 0\|1` | `YUN_XUE_TANG_POINTS_MODE` | `pointsMode` | `1` | 每日积分模式:文档1/视频3/音频2/微课2,封顶即停 | | `--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` | 单文件上限,超出轮转 | | `--bark-url URL` | `YUN_XUE_TANG_BARK_URL` | `barkUrl` | 空 | Bark 推送地址(含设备 key),运行器自己收尾时推手机通知;空 = 不推送 | | `--bark-group NAME` | `YUN_XUE_TANG_BARK_GROUP` | `barkGroup` | 空 | Bark 通知分组(App 里按组折叠) | | `--bark-ttl N` | `YUN_XUE_TANG_BARK_TTL` | `barkTtl` | `0` | 通知在 Bark 服务端保留多少秒;`0` = 默认 | | `--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` 会被**忽略并告警**(凭据只认环境变量);写未知字段也会告警 ### 完成提醒(Bark) 运行器**自己结束**时(正常刷完 / 达到上限 / 长时间无进展 / 连续登录失败)会推一条 [Bark](https://github.com/Finb/Bark) 手机通知,正文是今日积分、完成门数、用时和结束原因: ```json { "title": "云学堂助手:任务完成", "body": "今日积分 15/24 · 文档1/1 视频3/3 音频1/2 微课0/2\n完成 4 门 · 用时 18 分 6 秒\n脚本已停止:今日积分:可用内容已学完" } ``` 配置(三选一,优先级从低到高): ```js // config/runner.config.mjs barkUrl: 'https://api.day.app/<你的设备 key>', // 也接受带 {title}/{body} 的完整模板 barkGroup: '云学堂助手', // 通知分组 barkTtl: 600, // 服务端保留秒数 ``` ```sh YUN_XUE_TANG_BARK_URL=https://api.day.app/ YUN_XUE_TANG_BARK_GROUP=云学堂助手 node runner/headless.mjs ``` ```sh # 环境变量优先级最高;Docker 里写进 .env 即可(.env 不入库) YUN_XUE_TANG_BARK_URL=https://api.day.app/ ``` - 手动 `Ctrl+C` 主动停止**不推送**(人在终端前,不需要再提醒);`--check` 自检也不推送。 - 推送失败只在日志里告警(网络不通 / key 错),不影响运行器退出码。 - 配了 `restartMinutes` 时,重复的同一结论(例如「今日积分已学完」)只推一次,不会每轮刷屏。 - `--help` 与启动日志里的 key 会打码成 `/***`,避免日志泄露推送权限。 退出码:`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)。下次启动会自动清理残留进程 | | 面板显示错行 / 有残留字符 | 全平台 | 终端被非运行器输出(后台脚本、`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` 会直接拦下这类文件 | ### 容器(Docker) 仓库自带 `Dockerfile` / `docker-compose.yml` / `.dockerignore`,镜像里已经装好 Node 22 与 **官方 google-chrome-stable**(不是发行版 chromium —— 后者不带 H.264/AAC, 课程视频会一直停在 0 秒),并在构建阶段跑完 `npm run build`,所以镜像开箱即用。 构建镜像推荐用仓库自带的脚本,它会把国内换源、按 `package.json` 版本打标签、构建后自检 这几件容易漏的事一趟做完(纯 `docker build` 当然也能用,下面第 1 步就是它展开后的样子): ```bash npm run docker:build # 默认标签 <包名>:<版本号> + <包名>:latest npm run docker:build -- --mirror # 国内网络:apt 换清华源、npm 换 npmmirror npm run docker:build -- --check # 构建完顺手跑一次 --check 自检 npm run docker:build -- --dry-run # 只打印将要执行的 docker 命令,不构建 npm run docker:build -- --help # 全部选项(--tag / --platform / --no-cache / --pull / --chrome-url …) Windows 下也可以直接双击 scripts\build-docker.cmd;Linux/macOS 用 ./scripts/build-docker.sh ``` `APT_MIRROR` / `NPM_REGISTRY` / `CHROME_DEB_URL` 三个构建参数按 **命令行 > 环境变量 > 仓库根 `.env`** 的优先级取值,所以也可以把它们写进 `.env` 一次配好,之后直接 `npm run docker:build`。 ```bash # 1. 构建(首次约 3-5 分钟,主要是下 Chrome 的 deb) docker build -t yun-xue-tang-assistant . # 2. 先自检:只读,不登录、不动进度,不需要账号 docker run --rm yun-xue-tang-assistant --check # 3. 正式刷课(凭据只走环境变量,别写进镜像) docker run -d --name yun-xue-tang \ -e YUN_XUE_TANG_USR='你的账号' \ -e YUN_XUE_TANG_PWD='你的密码' \ -e YUN_XUE_TANG_MAX_COURSES=100 \ -v "$PWD/.run-profile:/app/.run-profile" \ -v "$PWD/run-logs:/app/run-logs" \ --shm-size=512m \ --restart on-failure:3 \ yun-xue-tang-assistant # 4. 看日志 / 收尾 docker logs -f yun-xue-tang # 或 tail -f run-logs/headless.log docker stop yun-xue-tang # SIGTERM → 暂停视频 → 停批量 → 关浏览器 ``` 用 `docker compose` 更省事(账号写在 `.env` 里,`.env` 已在 `.gitignore`): ```bash cp .env.example .env # 填 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD docker compose build docker compose run --rm yun-xue-tang --check # 自检 docker compose run --rm yun-xue-tang --max-courses 3 # 只刷 3 门,跑完就退 docker compose up -d # 常驻 docker compose logs -f docker compose down ``` 需要注意的几点: | 事项 | 说明 | | --- | --- | | 挂载目录 | `/app/.run-profile`(登录 cookie,**别提交**)与 `/app/run-logs`(日志)要挂出来,否则重建容器就等于重登 + 丢日志 | | 卷权限 | 容器内以 root 跑。用绑定挂载时宿主机目录会被写成 root 所有;想用自己的 UID 就在 compose 里加 `user: "${UID}:${GID}"`(运行器会据此自动降级沙箱参数) | | `/dev/shm` | 容器默认只有 64MB,`shm_size: 512m` 更稳(运行器本身也加了 `--disable-dev-shm-usage` 兜底) | | 沙箱 | 容器内 Chrome 沙箱受限,运行器检测到 root/容器会自动补 `--no-sandbox --disable-setuid-sandbox`,不用手写 | | 终端面板 | 面板要求 stdout 是 TTY,后台容器里自动关闭、退回逐行日志。想在 `docker run -it` 里看面板:`docker run -it -e YUN_XUE_TANG_TUI=1 …` | | 验证码 | 首个登录若被要求验证码/滑块,无头环境无法完成:先在宿主机用 `npm run headless -- --headless 0` 有界面登录一次,再把宿主机 `.run-profile` 目录挂进容器复用 cookie | | 时区 | 镜像默认 `TZ=Asia/Shanghai`,日志时间戳与之对齐;要改就用 `-e TZ=...` | | 退出码与重启策略 | 与裸机一致:`0` 正常收尾、`1` 无进展、`2` 环境/参数问题、`3` 连续登录失败。**别用 `--restart always / unless-stopped`**:它们不看退出码,刷完课(`0`)会自动重启再来一轮,形成热循环;用 `--restart on-failure:3` 这类只在失败时重试的策略 | | 缺凭据 | 入口脚本在**没传参数且没填凭据**时自动降级成 `--check`,避免容器无意义重启空转 | | Chrome 下载失败 | 国内机器常从 dl.google.com 下不动,用构建参数换镜像源:`docker build --build-arg CHROME_DEB_URL=https://你的镜像/google-chrome-stable_current_amd64.deb .` | | 镜像内容 | 构建阶段已跑 `npm ci` + `npm run build`,产物 `/app/yun-xue-tang-assistant.user.js` 在镜像里;`node_modules` / `.run-profile` / `run-logs` / `.env` 由 `.dockerignore` 排除在外 | 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 换行符与忽略规则 Dockerfile 容器镜像:Node 22 + 官方 Chrome,构建期完成 npm run build docker-compose.yml 一键构建 / 自检 / 常驻(挂载 profile、日志,限制 shm 与日志大小) .dockerignore 镜像上下文排除 node_modules / .run-profile / run-logs / docs docker/ entrypoint.sh 容器入口:建目录 → 无凭据时降级 --check → exec 运行器 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 考试自动空卷交卷 exam-plan.js 考试结果页处置决策(纯函数,可单测) course.js 课程页主循环 complete.js 完成 / 未完成重试 / 跳课 index.js 主循环 / 启动 / 调试入口 scripts/ 开发与运维脚本(不在构建产物里) build.mjs esbuild 打包脚本(产物写回仓库根) check.mjs 静态检查:node --check + 批处理纯 ASCII/CRLF 校验 build-docker.mjs 构建镜像(换源 / 打标签 / 构建后自检,参数见 --help) build-docker.cmd Windows 一键构建镜像(双击即可) build-docker.sh Linux / macOS 构建镜像(转交 build-docker.mjs) 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 只读环境自检 notify.mjs 任务结束时的 Bark 手机通知 tui.mjs 终端面板(框线 + 进度条,q 退出,非 TTY 自动关闭) study.mjs 学习统计(本次播放时长 / 获得学分) supervisor.mjs 崩溃重启循环与退出码 config/ runner.config.mjs 无头运行器配置(日常调参改这里,不用 build) .env.example 账号环境变量模板(复制成 .env 后填;.env 不入库) 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-daily-points-mode` | 「每日积分模式」开关(`1` / `0`) | | `yun-xue-tang-daily-points-v1` | 今日积分计数(按本地日期自动清零,含当天已计分的课时去重表) | | `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 分钟) | | `yun-xue-tang-points-inventory-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 秒)。 每日积分模式:按课时类型(文档/视频/音频/微课)分别计数,文档 1、视频 3、音频 2、微课 2, 每次 3 分封顶 24 分;先补文档/音频/微课单条内容,视频靠课程课时;某类满额自动换下一类, 四类都满或无内容即停。计数落 localStorage 并跨天清零,面板与无头 TUI 都显示今日积分。 离线回归见 `node dev/tests/points-test.mjs`(`npm run test:points`)。 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 侧适配见其中「九、跨平台适配」一节。