From c1e883d67fa35d7df32fbb6acd7d871512f74bcb Mon Sep 17 00:00:00 2001 From: void Date: Sun, 25 Oct 2026 23:21:59 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E9=87=8D=E7=BB=84=E7=9B=AE?= =?UTF-8?q?=E5=BD=95=E7=BB=93=E6=9E=84=EF=BC=8C=E8=84=9A=E6=9C=AC=E6=94=B6?= =?UTF-8?q?=E8=BF=9B=20scripts/=EF=BC=8C=E9=85=8D=E7=BD=AE=E7=8B=AC?= =?UTF-8?q?=E7=AB=8B=E6=88=90=20config/?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 根目录原来平铺了构建脚本、运行器配置、两个 .cmd 启动器和一份中文名的 实跑报告,四类东西混在一起,新人分不清哪个是源码、哪个是产物。这次按 职责分层重排: - 构建与检查脚本收进 scripts/:build.mjs、check.mjs - 一键启动器收进 scripts/:start-headless.cmd、start-dev.cmd - 运行器配置独立成 config/runner.config.mjs(日常调参不用重新 build) - 真机测试收进 dev/tests/:real-cdp / real-test / real-e2e / real-run - 运行报告改成 ASCII 名并移入 docs/reports/run-report-v203.md - v2.0.x 时期的 7 份原始抓取片段归档到 docs/archive/v2.0-snapshots/, docs/evidence/ 只留当前版本的有效证据 - 测试每次重新生成的 3 张截图(e2e-01-after-login、e2e-02-playing、 real-chrome-login)移出仓库并加入 .gitignore,改写到 .run-tmp/screenshots/; docs/screenshots/ 只保留手工挑选的 5 张展示图 路径修正:build.mjs 的 ROOT 上跳一级;dev/tests/ 四个脚本 ROOT 上跳两级、 对 runner/browser.mjs 的引用改 ../../;runner/config.mjs 默认配置文件路径改 config/runner.config.mjs;两个 .cmd 的 cd 改为仓库根、start-dev.cmd 指向 dev/serve.mjs;package.json 全部 npm scripts 同步;README、dev/README、证据 文件与源码注释里的路径一并更新。 顺带修掉测试里硬编码的 v2.7.0 断言:版本号改为从 package.json 读取。 验证:npm run build(104798 字节 / 102.3 KB)、npm run check(24/24)、 npm run test:real:headless(24/24 通过)。 --- .gitignore | 4 +- README.md | 55 +++++++++++------- runner.config.mjs => config/runner.config.mjs | 0 dev/README.md | 28 +++++---- dev/dev-loader.user.js | 6 +- dev/{ => tests}/real-cdp.mjs | 4 +- dev/{ => tests}/real-e2e.mjs | 5 +- dev/{ => tests}/real-run.mjs | 3 +- dev/{ => tests}/real-test.mjs | 16 +++-- .../v2.0-snapshots}/advance-evidence.txt | 0 .../completion-banner-evidence.txt | 0 .../v2.0-snapshots}/probe.txt | 0 .../v2.0-snapshots}/probe2.txt | 0 .../v2.0-snapshots}/probe4.txt | 0 .../v2.0-snapshots}/report.txt | 0 .../v2.0-snapshots}/v203-advance-evidence.txt | 0 docs/evidence/align-start-evidence.txt | 2 +- docs/evidence/headless-linux-evidence.txt | 44 +++++++------- docs/evidence/short-course-evidence.txt | 2 +- .../reports/run-report-v203.md | 32 +++++----- docs/screenshots/e2e-01-after-login.png | Bin 5184 -> 0 bytes docs/screenshots/e2e-02-playing.png | Bin 463739 -> 0 bytes docs/screenshots/real-chrome-login.png | Bin 692948 -> 0 bytes package.json | 14 ++--- runner/browser.mjs | 2 +- runner/cdp.mjs | 2 +- runner/config.mjs | 10 ++-- runner/supervisor.mjs | 2 +- build.mjs => scripts/build.mjs | 11 ++-- {dev => scripts}/check.mjs | 13 ++--- {dev => scripts}/start-dev.cmd | 4 +- .../start-headless.cmd | 14 ++--- 32 files changed, 148 insertions(+), 125 deletions(-) rename runner.config.mjs => config/runner.config.mjs (100%) rename dev/{ => tests}/real-cdp.mjs (96%) rename dev/{ => tests}/real-e2e.mjs (99%) rename dev/{ => tests}/real-run.mjs (99%) rename dev/{ => tests}/real-test.mjs (95%) rename docs/{evidence => archive/v2.0-snapshots}/advance-evidence.txt (100%) rename docs/{evidence => archive/v2.0-snapshots}/completion-banner-evidence.txt (100%) rename docs/{evidence => archive/v2.0-snapshots}/probe.txt (100%) rename docs/{evidence => archive/v2.0-snapshots}/probe2.txt (100%) rename docs/{evidence => archive/v2.0-snapshots}/probe4.txt (100%) rename docs/{evidence => archive/v2.0-snapshots}/report.txt (100%) rename docs/{evidence => archive/v2.0-snapshots}/v203-advance-evidence.txt (100%) rename 运行报告.md => docs/reports/run-report-v203.md (82%) delete mode 100644 docs/screenshots/e2e-01-after-login.png delete mode 100644 docs/screenshots/e2e-02-playing.png delete mode 100644 docs/screenshots/real-chrome-login.png rename build.mjs => scripts/build.mjs (84%) rename {dev => scripts}/check.mjs (89%) rename {dev => scripts}/start-dev.cmd (76%) rename start-headless.cmd => scripts/start-headless.cmd (74%) diff --git a/.gitignore b/.gitignore index 51940b8..affeebd 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,8 @@ node_modules/ # ---- 运行 / 调试产物 ---- # 本地实跑会在这里生成浏览器配置目录、截图和一次性调试脚本,体积很大,不入库 .run-tmp/ +# 真机测试(dev/tests/real-*.mjs)每次跑都重新生成的截图 +.run-tmp/screenshots/ # 无头运行器的持久化 profile(含登录 cookie,绝不能入库)和运行日志 .run-profile/ run-logs/ @@ -21,5 +23,5 @@ desktop.ini # ---- 本地私有配置(不要提交账号信息) ---- .env .env.* -# 个人临时覆盖用的运行器配置(放进仓库的 runner.config.mjs 保持通用) +# 个人临时覆盖用的运行器配置(仓库里的 config/runner.config.mjs 保持通用) runner.local.mjs diff --git a/README.md b/README.md index 7f655f0..7821206 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ Tampermonkey 用户脚本。支持多课时课程与单视频/音频课程;含 sudo apt install -y chromium # 或安装官方包:google-chrome-stable # 2. 构建产物 npm install && npm run build -# 3. 调参:改仓库根目录的 runner.config.mjs(maxCourses、budgetMinutes、preferShort…) +# 3. 调参:改 config/runner.config.mjs(maxCourses、budgetMinutes、preferShort…) # 只想临时覆盖就用命令行,例如 npm run headless -- --max-courses 3 # 4. 凭据走环境变量(不要写进配置文件) export YUN_XUE_TANG_USR='你的账号' @@ -112,7 +112,7 @@ tail -f run-logs/headless.log # 也可以直接看日志文件 winget install --id Google.Chrome # 2. 构建产物 npm install; npm run build -# 3. 调参:改 runner.config.mjs(无需重新 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='你的密码' @@ -121,7 +121,7 @@ npm run headless:check npm run headless ``` -也可以直接双击 [`start-headless.cmd`](start-headless.cmd):它会自动构建、检查 Node、跑完后 +也可以直接双击 [`scripts/start-headless.cmd`](scripts/start-headless.cmd):它会自动构建、检查 Node、跑完后 用 `pause` 留住退出码信息(方便看报错)。注意这个批处理文件**只写 ASCII 字符**——中文提示 全部由 Node 侧输出,原因见下方常见坑表里的「`'鍏?npm' 不是内部或外部命令`」。 @@ -136,7 +136,7 @@ schtasks /create /tn "云学堂助手" /tr "node runner\headless.mjs" /sc onlogo # C. 只跑一段(例如每天凌晨跑 2 小时):命令行临时覆盖配置 npm run headless -- --budget-minutes 120 -# 或把 budgetMinutes: 120 写进 runner.config.mjs,然后直接 npm run headless +# 或把 budgetMinutes: 120 写进 config/runner.config.mjs,然后直接 npm run headless ``` Windows 上要注意:`Ctrl+C` 会让运行器优雅收尾(暂停视频、停批量、关浏览器)。 @@ -165,7 +165,7 @@ Windows 上要注意:`Ctrl+C` 会让运行器优雅收尾(暂停视频、停 | --- | --- | --- | | `runner/headless.mjs` | ~130 | 入口:解析参数 → 预检 → 交给 supervisor,只做组装 | | `runner/config.mjs` | ~360 | 三层合并(配置文件 / 环境变量 / 命令行)+ 校验 + `--help`,其它模块只读导出常量 | -| `runner.config.mjs`(仓库根) | ~50 | **日常调参就改这里**:普通 JS 模块,可写注释,改完不用 build | +| `config/runner.config.mjs` | ~50 | **日常调参就改这里**:普通 JS 模块,可写注释,改完不用 build | | `runner/platform.mjs` | ~230 | 平台差异:有无图形会话、沙箱参数、进程树收尾、残留进程清理、排查命令 | | `runner/preflight.mjs` | ~95 | 启动前检查:产物、Node 版本、凭据、浏览器、调试端口(端口被占会先自愈) | | `runner/log.mjs` | ~50 | 终端 + 文件日志,超上限轮转成 `.1` | @@ -184,7 +184,7 @@ Windows 上要注意:`Ctrl+C` 会让运行器优雅收尾(暂停视频、停 命令行参数(**日常改配置文件就行**;这里的开关只是临时覆盖,适合写进 `tmux` 命令或 `~/.bashrc`): -优先级:**内置默认值 < `runner.config.mjs` < 环境变量 `YUN_XUE_TANG_*` < 命令行参数**。 +优先级:**内置默认值 < `config/runner.config.mjs` < 环境变量 `YUN_XUE_TANG_*` < 命令行参数**。 | 参数 | 环境变量 | 配置文件字段 | 默认 | 作用 | | --- | --- | --- | --- | --- | @@ -203,7 +203,7 @@ Windows 上要注意:`Ctrl+C` 会让运行器优雅收尾(暂停视频、停 | `--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` | 单文件上限,超出轮转 | -| `--config PATH` | `YUN_XUE_TANG_CONFIG` | — | `./runner.config.mjs` | 指定另一个配置文件 | +| `--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` | **不写入配置文件** | 必填 | 账号密码。故意只走环境变量:命令行会进进程列表/计划任务历史 | @@ -212,11 +212,11 @@ Windows 上要注意:`Ctrl+C` 会让运行器优雅收尾(暂停视频、停 ### 配置文件 -日常调参改仓库根目录的 `runner.config.mjs` 即可,它是普通 JS 模块(可写注释、可写表达式), +日常调参改 `config/runner.config.mjs` 即可,它是普通 JS 模块(可写注释、可写表达式), 改完**不需要 `npm run build`**(构建只打包注入浏览器的 `src/`): ```js -// runner.config.mjs +// config/runner.config.mjs export default { maxCourses: 0, // 0 = 不限,一直刷到没有未学完的课 budgetMinutes: 0, // 0 = 不限运行时长 @@ -268,12 +268,16 @@ npm run build:watch # 监听 src/,保存即自动重新打包 npm run dev # 等价于 node dev/serve.mjs,默认 127.0.0.1:8899 ``` -Windows 下也可以直接双击 [`dev/start-dev.cmd`](dev/start-dev.cmd)。脚本暴露 `window.__yunXueTangDispose()`, +Windows 下也可以直接双击 [`scripts/start-dev.cmd`](scripts/start-dev.cmd)。脚本暴露 `window.__yunXueTangDispose()`, 加载器在注入新版本前先释放旧实例(定时器、监听器、面板),因此视频播放不会被打断。 ## 目录结构 ```text +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 @@ -289,9 +293,11 @@ src/ 业务脚本源码(拆成多个模块,日 course.js 课程页主循环 complete.js 完成 / 未完成重试 index.js 主循环 / 启动 / 调试入口 -build.mjs esbuild 打包脚本 -runner.config.mjs 无头运行器配置文件(日常调参改这里,不用 build) -start-headless.cmd Windows 一键启动无头运行器(双击即可) +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 @@ -305,13 +311,22 @@ runner/ 无头运行器(Linux / Windows,无图形 session.mjs 单次会话:起浏览器 / 注入 / 自动重登 / 崩溃自愈 selfcheck.mjs --check 只读环境自检 supervisor.mjs 崩溃重启循环与退出码 -package-lock.json 依赖锁(esbuild) -package.json npm scripts(build / build:watch / dev / headless / check) -yun-xue-tang-assistant.user.js 构建产物(唯一需要安装的文件,不要手改) +config/ + runner.config.mjs 无头运行器配置(日常调参改这里,不用 build) dev/ 本地热加载开发工具(HTTP 服务 + 薄加载器) -docs/screenshots/ 实跑截图 -docs/evidence/ 实跑日志与接口证据 -运行报告.md 2026-10-19 实跑报告(v2.0.3) + 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 持续跑:跨章节 / 跨课程 / 断线重启 +docs/ + reports/ 历史实跑报告 + run-report-v203.md 2026-10-19 实跑报告(v2.0.3) + evidence/ 当前版本的证据(叙述 + 接口日志) + archive/v2.0-snapshots/ v2.0.x 时期的原始抓取片段(仅存档) + screenshots/ 手工挑选的展示截图(测试自动截图不进库) ``` ## 本机数据 @@ -357,7 +372,7 @@ docs/evidence/ 实跑日志与接口证据 ## 实跑记录 -真实站点(`kfmic.yunxuetang.cn`)的完整实跑过程、发现的问题与修复记录见 [运行报告.md](运行报告.md), +真实站点(`kfmic.yunxuetang.cn`)的完整实跑过程、发现的问题与修复记录见 [`docs/reports/run-report-v203.md`](docs/reports/run-report-v203.md), 证据文件在 [`docs/evidence/`](docs/evidence/),截图在 [`docs/screenshots/`](docs/screenshots/)。 v2.5.2 修复「进入课程不从第一个未学完的课时开始」的定位过程、复刻用例与修复前后对比, diff --git a/runner.config.mjs b/config/runner.config.mjs similarity index 100% rename from runner.config.mjs rename to config/runner.config.mjs diff --git a/dev/README.md b/dev/README.md index a2a754f..b094562 100644 --- a/dev/README.md +++ b/dev/README.md @@ -5,15 +5,19 @@ ## 结构 +`dev/` 只放「在浏览器里跑」的开发工具(HTTP 服务 + 薄加载器 + 真机测试), +构建与检查脚本在 `../scripts/`,运行器配置在 `../config/`。 + | 文件 | 作用 | | --- | --- | -| `src/` | 业务脚本源码(拆成多个模块,改这里) | -| `build.mjs` | 用 esbuild 把 `src/` 打包成单文件 `.user.js`(产物文件名与原脚本一致,热加载链路无需改动) | +| `../src/` | 业务脚本源码(拆成多个模块,改这里) | +| `../scripts/build.mjs` | 用 esbuild 把 `src/` 打包成单文件 `.user.js`(产物写在仓库根,热加载链路无需改动) | | `../yun-xue-tang-assistant.user.js` | **构建产物**(不要手改,改 `src/` 后 `npm run build`) | | `serve.mjs` | 本地 HTTP 服务,向浏览器提供源码与版本哈希(127.0.0.1:8899) | | `dev-loader.user.js` | Tampermonkey 里的薄加载器,轮询版本、释放旧实例、注入新实例 | -| `start-dev.cmd` | 双击启动服务 | -| `check.mjs` | `npm run check` 的实现:自动遍历 `runner/`、`dev/` 与顶层文件跑 `node --check`,同时检查 `.cmd` 必须是纯 ASCII + CRLF(cmd.exe 逐字节按代码页读批处理,中文和裸 LF 会让行偏移错位);新增模块不用再手改命令 | +| `tests/` | 真机测试脚本(真实 Chrome + 真实站点,见下方「真机测试」) | +| `../scripts/start-dev.cmd` | 双击启动服务 | +| `../scripts/check.mjs` | `npm run check` 的实现:自动遍历 `runner/`、`dev/`、`scripts/`、`config/` 跑 `node --check`,同时检查 `.cmd` 必须是纯 ASCII + CRLF(cmd.exe 逐字节按代码页读批处理,中文和裸 LF 会让行偏移错位);新增模块不用再手改命令 | 原理:加载器每 1 秒请求 `/version`,发现哈希变化就调用旧实例暴露的 `window.__yunXueTangDispose()`(清定时器 / 监听器 / 面板),再把新源码以 `