Files
yun-xue-tang-assistant/README.md
T
void 7d6493bca5 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 链接
2026-10-20 22:53:24 +08:00

94 lines
4.8 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` 或平台倒计时归零)后自动进入下一节,并等平台记账后再继续 |
| 防挂机验证 | 识别「已触发防挂机验证」弹窗并点「继续学习」;滑块/拼图类验证不绕过,提示人工处理 |
| 批量刷课 | 在列表页逐门进入未学完的课程,默认本次最多 10 门,连续失败 5 门自动停止 |
| 失败隔离 | 答题/考试类课程、长时间无计时进展的课程会被跳过并记录原因,不影响后续课程 |
| 进度可续 | 运行状态存在 `localStorage`,刷新、热更新后继续上次的队列和页码 |
## 安装
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`,不依赖任何本地服务,可独立运行。
## 配置
脚本顶部的 `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/)。