refactor: 重组目录结构,脚本收进 scripts/,配置独立成 config/

根目录原来平铺了构建脚本、运行器配置、两个 .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 通过)。
This commit is contained in:
void committed 2026-10-25 23:21:59 +08:00
1 parent ae117222df
commit c1e883d67f
32 files changed
+148 -125

No files matched your search

+35 -20
View File
@@ -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 修复「进入课程不从第一个未学完的课时开始」的定位过程、复刻用例与修复前后对比,