commit 7d6493bca54bde8fdc0eb26eb188c6d39cc39561 Author: void Date: Tue Oct 20 22:53:24 2026 +0800 chore: 初始化仓库并清理项目 - 新增 .gitignore / .gitattributes:忽略 .run-tmp、依赖与系统/编辑器文件,统一换行符 - 删除 .run-tmp(约 460 MB 浏览器配置目录与一次性调试脚本), 将实跑报告引用的日志与截图移入 docs/evidence、docs/screenshots - 新增根 README(安装、配置、开发、隐私与已知限制)与 package.json(npm run dev / check) - 整理 courseTick 步骤编号,移除未使用的 CFG.resumeOnPause / CFG.nextDelayMs - 修正热加载器描述与实跑报告中的旧文件名、失效的 .run-tmp 链接 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..72f2941 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,14 @@ +# 统一换行符,避免 Windows / macOS 混合编辑产生整文件 diff +* text=auto eol=lf + +# Windows 批处理必须 CRLF,否则 cmd.exe 解析 if/goto 可能出错 +*.cmd text eol=crlf +*.bat text eol=crlf + +# 二进制文件不做文本转换 +*.png binary +*.jpg binary +*.jpeg binary +*.gif binary +*.ico binary +*.woff2 binary diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fb644fd --- /dev/null +++ b/.gitignore @@ -0,0 +1,20 @@ +# ---- 依赖 ---- +node_modules/ + +# ---- 运行 / 调试产物 ---- +# 本地实跑会在这里生成浏览器配置目录、截图和一次性调试脚本,体积很大,不入库 +.run-tmp/ +*.log +*.tmp + +# ---- 编辑器 / 系统 ---- +.vscode/ +.idea/ +.DS_Store +Thumbs.db +desktop.ini +*~ + +# ---- 本地私有配置(不要提交账号信息) ---- +.env +.env.* diff --git a/README.md b/README.md new file mode 100644 index 0000000..fffacc9 --- /dev/null +++ b/README.md @@ -0,0 +1,93 @@ +# 云学堂助手 + +在云学堂(`*.yunxuetang.cn`)上自动登录、按目录顺序听课、自动切节,并在课程列表页批量推进的 +Tampermonkey 用户脚本。平台按**真实播放时长**计时,脚本只负责「自动点播放、自动切下一节、 +处理防挂机弹窗」,不快进、不改进度、不伪造学时。 + +![控制面板](docs/screenshots/panel.png) + +## 功能 + +| 能力 | 说明 | +| --- | --- | +| 一键登录 | 面板里填账号密码,自动填充表单、勾选协议、点击登录;支持记住密码与自动登录 | +| 顺序听课 | 进入课程后先对齐到「第一个未学完的课时」,从第一章第一节顺序往下学 | +| 自动切节 | 本节播完(`video.ended` 或平台倒计时归零)后自动进入下一节,并等平台记账后再继续 | +| 防挂机验证 | 识别「已触发防挂机验证」弹窗并点「继续学习」;滑块/拼图类验证不绕过,提示人工处理 | +| 批量刷课 | 在列表页逐门进入未学完的课程,默认本次最多 10 门,连续失败 5 门自动停止 | +| 失败隔离 | 答题/考试类课程、长时间无计时进展的课程会被跳过并记录原因,不影响后续课程 | +| 进度可续 | 运行状态存在 `localStorage`,刷新、热更新后继续上次的队列和页码 | + +## 安装 + +1. 浏览器安装 [Tampermonkey](https://www.tampermonkey.net/)。 +2. 打开 Tampermonkey 面板 → 添加新脚本 → 粘贴 [`yun-xue-tang-assistant.user.js`](yun-xue-tang-assistant.user.js) 全文 → 保存。 +3. 打开 ,右下角出现「云学堂助手」面板: + - 填账号密码 → 点「一键登录并刷课」,登录后自动进入列表并开始批量学习; + - 或手动登录后,在列表页点「一键刷课」。 + +脚本 `@grant none`,不依赖任何本地服务,可独立运行。 + +## 配置 + +脚本顶部的 `CFG` 是唯一的配置入口: + +| 配置项 | 默认 | 作用 | +| --- | --- | --- | +| `mute` | `true` | 静音播放(自动播放更稳) | +| `autoNext` | `true` | 手动打开课程时,本节结束自动下一节 | +| `tickMs` | `2000` | 主循环间隔 | +| `startClickCooldownMs` | `15000` | 「开始学习」重复点击冷却 | +| `stuckMs` | `5 分钟` | 连续多久没有计时进展就放弃当前课程 | +| `maxCourses` | `10` | 本次最多完成多少门;`0` = 不限 | +| `maxConsecutiveFailures` | `5` | 连续失败多少门后自动停止 | +| `alignToFirstIncomplete` | `true` | 进入课程先从第一个未学完的课时学起;`false` = 沿用平台上次位置 | + +## 开发热加载 + +改完脚本保存即生效,不用复制粘贴、不用刷新页面。详见 [dev/README.md](dev/README.md)。 + +```powershell +npm run dev # 等价于 node dev/serve.mjs,默认 127.0.0.1:8899 +``` + +Windows 下也可以直接双击 [`dev/start-dev.cmd`](dev/start-dev.cmd)。脚本暴露 `window.__ytDispose()`, +加载器在注入新版本前先释放旧实例(定时器、监听器、面板),因此视频播放不会被打断。 + +## 目录结构 + +```text +yun-xue-tang-assistant.user.js 业务脚本本体(唯一需要安装的文件) +dev/ 本地热加载开发工具(HTTP 服务 + 薄加载器) +docs/screenshots/ 实跑截图 +docs/evidence/ 实跑日志与接口证据 +运行报告.md 2026-10-19 实跑报告(v2.0.3) +``` + +## 本机数据 + +| `localStorage` 键 | 内容 | +| --- | --- | +| `yt-batch-v2` | 批量刷课队列、当前课程、页码、已完成/失败记录 | +| `yt-login-v1` | 勾选「记住密码」时的账号密码(base64 混淆,**不是加密**) | +| `yt-auto-play-enabled` | 「手动课程自动连播」开关 | +| `yt-auto-start-after-login` | 登录后自动开始刷课的一次性标记(5 分钟内有效) | + +公用电脑请不要勾选「记住密码」;面板上的「清除密码」可随时删除本机保存的凭据。 + +## 已知限制 + +- 平台按真实播放时长计时,倍速/快进不会减少所需时间;脚本不提供这类加速。 +- 直接改 URL 或刷新课程页时,页面标题可能短暂为 `loading...`,批量逻辑存在误判并回到列表的可能; + 从列表正常进入课程不受影响。 +- 验证码、滑块、拼图类验证需要人工完成,脚本不会绕过。 +- 平台改版(目录结构、弹窗、倒计时文案变化)可能导致识别失败,需要更新选择器。 + +## 免责声明 + +本项目仅用于个人学习自动化实践。请遵守所在单位与平台的使用规定,是否使用及由此产生的后果由使用者自行承担。 + +## 实跑记录 + +真实站点(`kfmic.yunxuetang.cn`)的完整实跑过程、发现的问题与修复记录见 [运行报告.md](运行报告.md), +证据文件在 [`docs/evidence/`](docs/evidence/),截图在 [`docs/screenshots/`](docs/screenshots/)。 diff --git a/dev/README.md b/dev/README.md new file mode 100644 index 0000000..c6d2d65 --- /dev/null +++ b/dev/README.md @@ -0,0 +1,55 @@ +# 开发热加载(保存即生效) + +目标:在编辑器里改 `yun-xue-tang-assistant.user.js`,保存后浏览器里的脚本自动换成新版本, +**不用复制粘贴、不用重装、不用刷新页面**。 + +## 结构 + +| 文件 | 作用 | +| --- | --- | +| `../yun-xue-tang-assistant.user.js` | 业务脚本本体(唯一需要修改的文件) | +| `serve.mjs` | 本地 HTTP 服务,向浏览器提供源码与版本哈希(127.0.0.1:8899) | +| `dev-loader.user.js` | Tampermonkey 里的薄加载器,轮询版本、释放旧实例、注入新实例 | +| `start-dev.cmd` | 双击启动服务 | + +原理:加载器每 1 秒请求 `/version`,发现哈希变化就调用旧实例暴露的 +`window.__ytDispose()`(清定时器 / 监听器 / 面板),再把新源码以 `