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:
1 parent
ae117222df
commit
c1e883d67f
32 files changed
+148
-125
No files matched your search
+16
-12
@@ -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()`(清定时器 / 监听器 / 面板),再把新源码以 `<script>` 形式注入页面主世界。
|
||||
@@ -21,7 +25,7 @@
|
||||
|
||||
## 一次性安装
|
||||
|
||||
1. 双击 `dev/start-dev.cmd` 启动本地服务(保持窗口开着)。
|
||||
1. 双击 `scripts/start-dev.cmd` 启动本地服务(保持窗口开着)。
|
||||
2. 浏览器打开 <http://127.0.0.1:8899/>,点「安装 / 更新热加载器」,Tampermonkey 弹窗确认安装。
|
||||
> 手动方式:Tampermonkey 面板 → 添加新脚本 → 粘贴 `dev/dev-loader.user.js` 全文 → 保存。
|
||||
3. **停用或删除** Tampermonkey 里原来那份「云学堂助手」完整脚本。
|
||||
@@ -45,10 +49,10 @@
|
||||
npm run build # 先出产物
|
||||
npm run test:real # 有界面 Chrome,能看见面板真实渲染
|
||||
npm run test:real:headless # 无头模式(CI / 无人值守)
|
||||
node dev/real-test.mjs --keep # 跑完不关浏览器,便于人工复核
|
||||
node dev/tests/real-test.mjs --keep # 跑完不关浏览器,便于人工复核
|
||||
```
|
||||
|
||||
三个真机脚本(`real-test` / `real-e2e` / `real-run`)会自动适配当前平台:
|
||||
三个真机脚本(`dev/tests/real-test.mjs` / `real-e2e.mjs` / `real-run.mjs`)会自动适配当前平台:
|
||||
没有图形会话时强制 `--headless=new`(即使没传 `--headless`),并补上该平台需要的参数
|
||||
(Linux:`--no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage`;Windows:不弹崩溃恢复气泡),
|
||||
因此可以原样在无图形化服务器 / 容器 / CI / Windows 后台里跑。平台判断复用
|
||||
@@ -72,7 +76,7 @@ node dev/real-test.mjs --keep # 跑完不关浏览器,便于人工复核
|
||||
| 路由 | SPA 内改 `location.hash` 后 `route()` 自动跟随,无需重新注入 |
|
||||
| 整页重定向 | 未登录访问 `#/list` 被站点跳回登录页(新 document),脚本无残留、重注入后正常 |
|
||||
|
||||
产物:截图存到 `docs/screenshots/real-chrome-login.png`。
|
||||
产物:截图存到 `.run-tmp/screenshots/real-chrome-login.png`(测试产物不入库,`--shotdir` / `YUN_XUE_TANG_SHOT_DIR` 可改)。
|
||||
|
||||
需要 Node 22+(全局 `WebSocket` / `fetch`),无需 puppeteer / playwright。
|
||||
测试**只读**:不填账号密码、不点登录、不改线上数据。
|
||||
@@ -89,8 +93,8 @@ node dev/real-test.mjs --keep # 跑完不关浏览器,便于人工复核
|
||||
npm run test:e2e # 登录 + 列表;默认只读,不碰学习进度
|
||||
npm run test:e2e:play # 额外进入最短的未学完课程,采样 25 秒后立即暂停
|
||||
npm run test:e2e:play -- --seconds 60
|
||||
node dev/real-e2e.mjs --headless # 无头
|
||||
node dev/real-e2e.mjs --keep # 跑完不关浏览器
|
||||
node dev/tests/real-e2e.mjs --headless # 无头
|
||||
node dev/tests/real-e2e.mjs --keep # 跑完不关浏览器
|
||||
```
|
||||
|
||||
覆盖的断言(`--play` 时是 19 项,否则 12 项):
|
||||
@@ -119,7 +123,7 @@ node dev/real-e2e.mjs --keep # 跑完不关浏览器
|
||||
|
||||
| 现象 | 处理 |
|
||||
| --- | --- |
|
||||
| 左下角红条「未连上本地开发服务」 | 服务没启动,或端口被占用;运行 `dev/start-dev.cmd` |
|
||||
| 左下角红条「未连上本地开发服务」 | 服务没启动,或端口被占用;运行 `scripts/start-dev.cmd` |
|
||||
| 改完没反应 | 看控制台是否有 `热更新` 日志;确认 `npm run build:watch` 在跑,改的是 `src/` 下的模块 |
|
||||
| 页面出现两个面板 | 旧完整脚本没停用,去 Tampermonkey 停用它 |
|
||||
| 端口冲突 | `node dev/serve.mjs 8900`,同时把加载器里的 `SERVER` 常量改成对应端口 |
|
||||
@@ -132,5 +136,5 @@ node dev/real-e2e.mjs --keep # 跑完不关浏览器
|
||||
|
||||
## 开机自启(可选)
|
||||
|
||||
把 `dev/start-dev.cmd` 的快捷方式放进
|
||||
把 `scripts/start-dev.cmd` 的快捷方式放进
|
||||
`%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup`,开机即后台常驻。
|
||||
Reference in new issue
Block a user