新增 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(假时钟口径)
云学堂助手
在云学堂(*.yunxuetang.cn)上自动登录、按目录顺序听课、自动切节,并在课程列表页逐门推进的
Tampermonkey 用户脚本。支持多课时课程与单视频/音频课程;含考试章节的课程会自动进入考试、
不答题直接交卷;一门课学完会自动回列表选下一门。
平台按真实播放时长计时,脚本只负责「自动点播放、自动切下一节、处理防挂机弹窗」,
不快进、不改进度、不伪造学时。
功能
| 能力 | 说明 |
|---|---|
| 一键登录 | 面板里填账号密码,自动填充表单、勾选协议、点击登录;支持记住密码与自动登录 |
| 顺序听课 | 进入课程(列表刷课或自己点开)后先对齐到「第一个未学完的课时」,从第一章第一节顺序往下学 |
| 自动切节 | 本节播完(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 无人值守常驻(见下方「无头运行」) |
安装
- 浏览器安装 Tampermonkey。
- 打开 Tampermonkey 面板 → 添加新脚本 → 粘贴
yun-xue-tang-assistant.user.js全文 → 保存。 - 打开 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:
# 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 托管,因为运行器是前台进程(不内置守护模式):
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:
# 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:它会自动构建、检查 Node、跑完后
用 pause 留住退出码信息(方便看报错)。注意这个批处理文件只写 ASCII 字符——中文提示
全部由 Node 侧输出,原因见下方常见坑表里的「'鍏?npm' 不是内部或外部命令」。
Windows 上常驻的三种方式:
# 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 会话),运行器会自动开一块实时面板:
╭ 云学堂助手 · 无头运行器 ─────────────────────────────────────────────────────────╮
│ 状态 刷课中 已运行 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/):
// 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。
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。脚本暴露 window.__yunXueTangDispose(),
加载器在注入新版本前先释放旧实例(定时器、监听器、面板),因此视频播放不会被打断。
目录结构
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/evidence/,截图在 docs/screenshots/。
v2.5.2 修复「进入课程不从第一个未学完的课时开始」的定位过程、复刻用例与修复前后对比,
见 docs/evidence/align-start-evidence.txt。
v2.6.0 新增「优先短课程(时长正序)」:真实站点读取 5148 门课程、跨页跳到最短课程所在页的
实跑记录与 3 个回归用例,见 docs/evidence/short-course-evidence.txt;
面板效果见 docs/screenshots/panel-short.png。
v2.8.0 状态分层重构:刷课开关不再进 localStorage(修「还没登录就开始刷课」)、字段名语义化、
短课程模式下页码导航所有权归一到 chooseShortCourse(省掉每次多跳一页+白等 3.5 秒)。
v2.7.0 修复「进入课程有概率不自动播放」和「学完后不转下一门」:新增单视频/音频/课件播放页识别,
完成判定同时支持 已完成 x/y、已完成 N%、已完成学习;真机复现、修复前后对比与回归结果见
docs/evidence/completion-next-evidence.txt。
无头运行(Linux 服务器 / Windows 无人值守):新增 runner/,自己起无头 Chromium + CDP 注入,
持久化登录、掉登录自动重登、崩溃自愈;环境自检、真实刷课、断线重启、优雅退出的实跑记录见
docs/evidence/headless-linux-evidence.txt,
平台差异与 Windows 侧适配见其中「九、跨平台适配」一节。
