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 链接
This commit is contained in:
void committed 2026-10-20 22:53:24 +08:00
commit 7d6493bca5
22 files changed
+2991

No files matched your search

+55
View File
@@ -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()`(清定时器 / 监听器 / 面板),再把新源码以 `<script>` 形式注入页面主世界。
因为脚本依赖页面里的 `__vue__`(登录组件),注入必须发生在主世界,不能走普通沙箱。
## 一次性安装
1. 双击 `dev/start-dev.cmd` 启动本地服务(保持窗口开着)。
2. 浏览器打开 <http://127.0.0.1:8899/>,点「安装 / 更新热加载器」,Tampermonkey 弹窗确认安装。
> 手动方式:Tampermonkey 面板 → 添加新脚本 → 粘贴 `dev/dev-loader.user.js` 全文 → 保存。
3. **停用或删除** Tampermonkey 里原来那份「云学堂助手」完整脚本。
(两份同时跑会出现两个面板、双份定时器,行为会乱。)
4. 打开 <https://kfmic.yunxuetang.cn/login.html>,F12 控制台应看到:
`[云学堂·热加载] 已注入 xxxxx 字节源码`。
## 日常使用
- 改完 `yun-xue-tang-assistant.user.js` 直接保存 → 约 1 秒内页面控制台打印
`[云学堂·热加载] 热更新 → <新哈希>`,面板会重建,视频播放不中断。
- 批量刷课的进度存在 `localStorage`(`yt-batch-v2`),热替换 / 刷新都不会丢。
- 改坏了(语法错误):加载器会拒绝注入并弹出左下角红条提示,**旧版本继续运行**,修好再保存即可。
- 想完全回到「手动刷新才生效」:把加载器里的 `MODE` 改成 `'reload'`。
## 常见问题
| 现象 | 处理 |
| --- | --- |
| 左下角红条「未连上本地开发服务」 | 服务没启动,或端口被占用;运行 `dev/start-dev.cmd` |
| 改完没反应 | 看控制台是否有 `热更新` 日志;确认改的是工作目录里的那份文件 |
| 页面出现两个面板 | 旧完整脚本没停用,去 Tampermonkey 停用它 |
| 端口冲突 | `node dev/serve.mjs 8900`,同时把加载器里的 `SERVER` 常量改成对应端口 |
| 服务没开也想用 | 加载器回退到上次缓存的源码(`GM_getValue('yt-dev-src')`) |
## 关闭开发模式
停用热加载器 + 重新安装一次完整脚本(把 `.user.js` 全文粘进 Tampermonkey)即可。
脚本本身不依赖任何本地服务,`@grant none`,可独立运行。
## 开机自启(可选)
把 `dev/start-dev.cmd` 的快捷方式放进
`%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup`,开机即后台常驻。