Add overall progress and completion estimates with autoplay recovery

README.md

@@ -1,59 +1,106 @@
 # 学员中心 · 2倍速学习助手
 
-适用于 `https://icampus.yunyinsh.com/course/` 的篡改猴脚本。当前版本 **1.3.1**。
+用于 [学员中心课程页](https://icampus.yunyinsh.com/course/) 的 Tampermonkey（篡改猴／油猴）脚本。支持 **2倍速播放、自动续播、测验作答和交卷、按平台合格状态换课、后台播放，以及整体进度和完成时间估算**。
 
-## 安装
+当前版本：**1.4.0**。普通使用只需要桌面 Chrome 和篡改猴，无需安装 Node.js、Git 或运行命令。
 
-下载 `icampus-study-helper.user.js`，在篡改猴管理面板的“实用工具 → 从文件导入”中安装或更新原脚本。刷新课程页，确认面板版本为1.3.1。已启动的标签页会自动接续；首次使用点击“开始”。不要同时启用旧诊断脚本。
+**[获取脚本](icampus-study-helper.user.js) · [完整安装与使用说明](2倍速脚本使用说明.md) · [更新记录](CHANGELOG.md)**
 
-默认按课程列表顺序处理，支持仅当前课程，以及只做本门测验。首次安装等待点击开始；开始后保持启用，刷新同一标签页也会接续，只有“人工取消”才清除运行状态。
+## 快速安装
 
-## 1.3.1 完成条件、自动交卷与持续运行
+1. 在 Chrome 普通窗口打开 [篡改猴官方商店页面](https://chromewebstore.google.com/detail/tampermonkey/dhdgffkkebhmkfjojejmpbldmpobfkfo)，点击“添加至 Chrome”。也可从 [篡改猴官网 Chrome 下载页](https://www.tampermonkey.net/index.php?browser=chrome) 进入。
+2. 地址栏输入 `chrome://extensions`，找到 Tampermonkey →“详情”，按下表检查设置。
+3. 在仓库打开 [icampus-study-helper.user.js](icampus-study-helper.user.js)，使用文件页面的“下载”或“原始文件 / Raw”保存完整脚本。
+4. 点击篡改猴图标 →“管理面板”→“实用工具”→“从文件导入 / Import from file”，选择下载的 `.user.js`，按提示安装。找不到该入口或不接受文件时，使用下方复制方法。
+5. 登录课程网站并刷新，确认左下角显示 **“2倍速学习助手 · 1.4.0”**。打开课程列表，展开目标分组，选择范围并点击“开始”。停止时点击“人工取消”。
 
-电脑端的“交卷”在侧栏，手机端的底部交卷按钮在电脑上隐藏。旧版只查找底部按钮，导致已答完却无法提交。新版选择当前实际可见的交卷按钮，并自动确认交卷。
+扩展应先在普通窗口安装，再按需允许在无痕窗口运行；参考 [Chrome 官方扩展帮助](https://support.google.com/chrome_webstore/answer/2664769?hl=en)。
 
-继续下一课程的条件是 **学习进度100%＋平台判定测验合格**，不要求测验得分100%。例如学习进度100%、测验75%、合格线60%，应继续下一门；学习进度75%而测验已合格，则继续学习视频。测验是否合格以平台的明确判定为准，不硬编码合格线。
+### 必要设置
 
-未合格时根据逐题反馈保存正确答案、排除错误答案并重新测验，不设置脚本自己的重考次数上限。已合格不再重考；得分不足100%的整卷不会误记为全部答案正确。
+| 设置 | 操作 |
+| --- | --- |
+| 扩展及脚本启用 | Tampermonkey扩展、篡改猴总开关、本脚本均保持启用 |
+| Chrome 138及以上 | Tampermonkey“详情”→ 开启 **允许用户脚本 / Allow User Scripts** |
+| Chrome 138以前的适用版本 | 扩展列表页右上角开启 **开发者模式** |
+| 网站访问权限 | 允许在 `https://icampus.yunyinsh.com` 自动运行，可用“在特定网站上”添加 |
+| 无痕窗口使用 | Tampermonkey“详情”→ 开启 **在无痕模式下启用 / Allow in incognito** |
+| 允许访问文件网址 | 文件导入、复制安装及本脚本的HTTPS页面运行不需要开启 |
 
-“运行中”和“等待恢复”都属于已启动。网络异常、等待评分、当前范围完成或需要人工处理时保持启用；自动定期检查或在页面变化后接续。需要停止时点“人工取消”。手动暂停视频后会等待用户恢复视频，不主动抢占暂停操作。
+按 Chrome 版本选择对应的用户脚本权限，不必一律同时开启开发者模式和“允许用户脚本”。修改后刷新课程页。依据：[Chrome 用户脚本文档](https://developer.chrome.com/docs/extensions/reference/api/userScripts)、[篡改猴权限说明](https://www.tampermonkey.net/faq.php?locale=zh&q=Q209)。
 
-## 功能
+### 也可以复制安装
 
-- 2倍速正常播放，平台确认完成后切换视频。
-- 单选、判断、多选自动作答、交卷，根据平台逐题反馈保存答案并重试。
-- 保留正确答案，排除错误选项或组合；按题干和选项文字匹配，避免选项字母换序导致误答。
-- 持续启用、等待恢复、异常提示、单标签页运行锁和本机答案记忆。
-- 默认开启“切标签页继续播放”，助手运行时保留网站原有的后台进度保存定时器。
+打开脚本的“原始文件 / Raw”，复制**全部代码** → 篡改猴图标 →“添加新脚本”→ 在编辑器内全选删除默认模板 → 粘贴 → `Ctrl+S`保存 → 刷新课程页。
 
-## 1.2.0 后台播放
+必须包含开头的 `// ==UserScript==` 配置块，不要复制行号、仓库网页文字或Markdown代码围栏。更新已有脚本时，在原脚本编辑器内替换全部内容，避免同时启用多份。
 
-安装后刷新课程页，点击“开始”，保持“切标签页继续播放”勾选，然后切换其他标签页或把浏览器放到后台。开关偏好会保存在本机。
+## 当前版本特性
 
-已加载的课程组件在页面隐藏时主动停止心跳。后台模式在课程页的助手运行期间拦截这个隐藏事件，保留正常播放和网页原本的心跳；不会改写 `document.visibilityState`、播放位置或服务器请求。回到前台仍执行网站原来的恢复逻辑。暂停助手、关闭后台模式或离开页面时恢复正常处理。
+| 功能 | 当前行为 |
+| --- | --- |
+| 2倍速播放 | 正常播放，观察网站原有进度保存结果，不跳时间轴 |
+| 自动续播 | 视频自然结束且平台确认完成后切换下一段；等待新媒体加载并尝试恢复 |
+| 自动测验 | 支持文字单选、判断、多选，自动选择、交卷、确认交卷 |
+| 错题记忆 | 根据平台逐题反馈保留正确答案、排除错误选项或组合，未合格时重试 |
+| 动态合格判断 | 读取平台“已合格”结果，不写死合格分数，已合格不再重考 |
+| 课程完成判断 | **学习进度100%＋平台判定测验合格**才换课；无需测验的课程只核对学习完成 |
+| 持续启用 | 开始后保持启用，同一标签页刷新可接续；“人工取消”清除启用状态 |
+| 后台播放 | 默认开启“切标签页继续播放”，保留网站正常播放和保存流程 |
+| 自动播放恢复（新增） | 有声自动播放被拒绝时可尝试一次静音播放；仍失败则等待点击，避免定时空转 |
+| 整体进度（新增） | 完成百分比、已完成／总课程数、平均学习进度、待合格测验数 |
+| 时间预测（新增） | 显示预计剩余时长和完成日期时间；缺失时长用已知课程均值粗估并标明 |
+| 范围与排错 | 按可见列表顺序继续、仅当前课程、只做本门测验；提供状态和运行记录 |
 
-考虑到 Chrome 可能降低后台定时器频率，后台等待窗口及标签页运行锁延长至至少180秒，返回前台后给保存请求20秒恢复时间。连续180秒没有保存确认仍会暂停，后台切换视频和答题可能比前台慢。
+**学习100%、测验75%、平台显示已合格 → 继续下一课程。学习75%、测验已合格 → 继续视频。**
 
-电脑休眠、浏览器关闭、标签页冻结/丢弃、断网或媒体自动播放被浏览器拒绝，无法靠网页脚本保证运行。若 Chrome 经常回收该页，可在性能设置中将该站点加入“始终保持活跃的网站”；脚本不会自动修改浏览器设置。
+整体完成比例按课程门数计算，学习进度另行显示。时间预测按2倍速计算，另预留每门未合格测验2分钟、每门未完成课程切换15秒；重考、网络和人工处理会使实际时间延后。暂停时保留条件估算，完成时刻显示等待恢复。
 
-## 1.1.1 修复
+## 自动检查范围
 
-修复视频切换后不继续播放的问题：为每段视频单独计时，等待新媒体数据就绪和网站恢复播放位置；播放器重建时重新绑定；临时 `AbortError` 最多重试三次。加载卡住时尝试网页播放按钮，90秒仍未就绪则最多刷新恢复一次。播放停滞或启动超时也共享这一次恢复额度。
+**统计范围与自动运行范围要分清：**
 
-自动恢复会临时保存当前课程与恢复额度，刷新后接续。1.3.0起，运行开关另外保存在标签页会话中，因此普通刷新也接续；人工取消后刷新不会启动。
+- 整体面板统计本页已收到的课程列表数据；仅当前课程模式统计当前课程。尚未读取列表时明确显示“暂统计当前课程”。
+- 自动运行按当前列表已加载、已显示的课程卡片顺序选择未完成项目。不会自动展开全部分组、翻页或扫描账号所有课程。
+- 列表数据中有但页面未显示的课程可能计入统计，却尚未进入自动运行范围。开始前请展开目标分组、清除不需要的筛选、确认目标课程已显示。
+- 刷新后列表数据和时长样本需重新读取；可先打开“我的课程”再运行。统计和预测不是平台学分保证。
 
-浏览器明确拒绝自动播放时提示手动点击播放，不会无限刷新。正常播放后的手动暂停仍会停止助手。
+## 使用与更新
 
-## 验证
+默认勾选“自动测验，按平台合格线通过”“切标签页继续播放”和“播放受限时尝试静音”。需要有声播放时可关闭静音尝试；浏览器拒绝自动播放时手动点击网页播放按钮。静音成功后面板标注“静音”，可在播放器恢复声音。
 
-运行 `npm test`，无需安装依赖。当前64项本地行为测试覆盖播放、进度保存、测验循环、媒体加载恢复、后台模式、学习进度与测验合格的独立判断、刷新接续。包含“学习100%＋测验75%合格→返回列表→打开下一课程”的完整模拟回归。
+“已启动 · 等待恢复”仍是启用状态；普通等待会定期检查或随页面变化接续。不支持的题型、登录失效、自动播放仍受限等情况需人工处理。手动暂停视频后会等待手动恢复播放；更换范围前先“人工取消”。
 
-现场已确认原问题出现时第二段视频处于 `readyState=0` 且旧版已超时停止；修复通过模拟播放器与页面回归。尚未安装修复版验证真实课程完整连播。
+**仓库推送不会自动更新浏览器已安装脚本。** 更新时重新导入最新文件，或在原脚本中替换全部代码；然后分别刷新实际使用的普通／无痕课程标签页并检查面板版本。只启用一份助手，停用旧的“学员中心 · 本地网络诊断”等测试脚本。
 
-后台模式测试模拟了网页真实的可见性处理和心跳响应，验证拦截、恢复、暂停、后台超时和延迟跳转等情况。尚未在用户浏览器中完成新版的长时间真实后台运行验证。
+## 后台运行与边界
 
-## 限制
+保持电脑唤醒、联网，浏览器及课程页保持打开。Chrome若经常回收该页，可在“设置 → 性能 → 始终保持活跃的网站”添加 `icampus.yunyinsh.com`。设置依据：[Chrome 性能帮助](https://support.google.com/chrome/answer/12929150?hl=en)。
 
-计入进度、课程完成和重试能力均以平台返回结果为准。未合格且重考入口暂不可用时会等待；已合格则继续核对学习进度。图片、材料、填空和问答题需要人工处理。请保持电脑唤醒。
+休眠、断网、标签页冻结／丢弃和自动播放限制仍可能中断；后台答题与切换也可能变慢。图片、材料、填空、问答及无法唯一识别选项的题需要人工处理。脚本不自行限制重考次数，但会尊重平台返回的次数限制、入口和反馈情况。
 
-更多说明见 [使用说明](2倍速脚本使用说明.md)。
+本脚本无外部依赖，不额外上传日志或账户信息；学习记录仍由网站正常发送。答案记忆等保存在该站点的浏览器存储，启动状态存于当前标签页会话。普通和无痕数据隔离，运行锁也不跨这两种环境；同账号只运行一个学习页面。
+
+## 验证与开发
+
+目前 **81项本地行为测试**，覆盖播放、测验、恢复、后台、完成判断，以及新增统计和自动播放恢复。实际卡住页面已通过点击播放恢复2倍速，并重新收到平台保存确认。新版本的统计、预测和静音回退通过本地模拟测试，尚未完成所有课程及长期后台的真实端到端验证。
+
+开发验证需要 Node.js 18+，无需安装第三方依赖：
+
+```sh
+git clone ssh://git@192.168.10.31:2222/qishizhe/e-learning-assistant.git
+cd e-learning-assistant
+npm test
+```
+
+该SSH地址用于Git，需要相应内网连接和仓库权限，不是浏览器下载地址。
+
+| 文件 | 用途 |
+| --- | --- |
+| [icampus-study-helper.user.js](icampus-study-helper.user.js) | 唯一需要安装的用户脚本 |
+| [2倍速脚本使用说明.md](2倍速脚本使用说明.md) | 设置、导入、复制、后台、预测说明和排错 |
+| [CHANGELOG.md](CHANGELOG.md) | 各版本变化 |
+| `*.test.cjs` | 本地行为测试 |
+| [package.json](package.json) | 测试入口与版本信息 |
+
+反馈时附脚本版本、普通／无痕模式、面板提示和必要运行记录；不要提交登录凭据、完整敏感抓包或带签名的视频链接。