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

+16 -12
View File
@@ -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`,开机即后台常驻。
-115
View File
@@ -1,115 +0,0 @@
#!/usr/bin/env node
/**
* 静态检查:对仓库里会直接 `node` 执行的脚本跑 `node --check`,
* 并对批处理文件做两项硬性检查(这两项一旦坏掉就极难排查):
* 1. 必须是纯 ASCII —— cmd.exe 按当前代码页逐字节读批处理,
* 多字节字符(中文)会让行偏移错位,报出 "'鍏?npm' is not recognized" 这种怪错;
* 2. 必须用 CRLF 行尾 —— 只有 LF 时 cmd.exe 会把上一行的尾部当成命令的一部分,
* 同样报出莫名其妙的 "'01' is not recognized"。
*
* 以前 package.json 的 check 脚本是一长串 `node --check a && node --check b && …`,
* 每次新增模块都要手改那行命令(漏了就默默不检查)。现在改为自动遍历目录。
*
* 用法:npm run check
*/
import fs from 'node:fs';
import path from 'node:path';
import { spawnSync } from 'node:child_process';
import { fileURLToPath } from 'node:url';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
/** 要遍历的目录(JS 与 bat 一起收) */
const DIRS = ['runner', 'dev'];
/** 顶层要单独检查的文件(runner.config.mjs 是配置文件,也要求语法正确) */
const FILES = ['build.mjs', 'runner.config.mjs', 'yun-xue-tang-assistant.user.js'];
const TOP_CMD = ['start-headless.cmd'];
const SKIP_DIRS = new Set(['node_modules', '.git', '.run-profile', 'run-logs', '.run-tmp']);
function walk(dir, out = []) {
for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, ent.name);
if (ent.isDirectory()) {
if (!SKIP_DIRS.has(ent.name)) walk(p, out);
} else if (/\.m?js$|\.cmd$|\.bat$/i.test(ent.name)) {
out.push(p);
}
}
return out;
}
const jsTargets = [];
const cmdTargets = [];
for (const d of DIRS) {
const dir = path.join(ROOT, d);
if (fs.existsSync(dir)) {
for (const f of walk(dir)) {
if (/\.m?js$/.test(f)) jsTargets.push(f);
else cmdTargets.push(f);
}
}
}
for (const f of FILES) {
const p = path.join(ROOT, f);
if (fs.existsSync(p)) jsTargets.push(p);
}
for (const f of TOP_CMD) {
const p = path.join(ROOT, f);
if (fs.existsSync(p)) cmdTargets.push(p);
}
let failed = 0;
// ---- 1. JS 语法 ----
for (const file of jsTargets.sort()) {
const r = spawnSync(process.execPath, ['--check', file], { encoding: 'utf8' });
if (r.status !== 0) {
failed++;
console.error(' FAIL ' + path.relative(ROOT, file));
console.error((r.stderr || '').trim());
}
}
// ---- 2. 批处理文件:纯 ASCII + CRLF ----
for (const file of cmdTargets.sort()) {
const rel = path.relative(ROOT, file);
const buf = fs.readFileSync(file);
const bad = [];
const nonAscii = [];
for (let i = 0; i < buf.length; i++) {
if (buf[i] > 0x7f) nonAscii.push(i);
}
if (nonAscii.length) {
const first = nonAscii[0];
const ctx = buf.slice(Math.max(0, first - 20), first + 20).toString('utf8');
bad.push('含 ' + nonAscii.length + ' 个非 ASCII 字节(首次出现在偏移 ' + first + ',上下文 “' + ctx + '”);'
+ 'cmd.exe 按代码页逐字节读取,中文会让行偏移错位');
}
let lf = 0;
let crlf = 0;
for (let i = 0; i < buf.length; i++) {
if (buf[i] === 0x0a) {
lf++;
if (i > 0 && buf[i - 1] === 0x0d) crlf++;
}
}
if (lf !== crlf) {
bad.push('有 ' + (lf - crlf) + ' 处裸 LF 行尾(共 ' + lf + ' 个 LF / ' + crlf + ' 个 CRLF);'
+ 'cmd.exe 会把上一行尾部当成命令的一部分');
}
if (bad.length) {
failed++;
console.error(' FAIL ' + rel);
for (const b of bad) console.error(' - ' + b);
}
}
const total = jsTargets.length + cmdTargets.length;
if (failed) {
console.error('\n静态检查:' + failed + '/' + total + ' 个文件失败');
process.exit(1);
}
console.log('静态检查:' + total + '/' + total + ' 个文件通过'
+ '(JS ' + jsTargets.length + ' · 批处理 ' + cmdTargets.length + ')');
+3 -3
View File
@@ -21,7 +21,7 @@
* 3. 服务没开时回退到上一次缓存的源码,保证照常可用;
* 4. 新源码语法错误时拒绝注入,旧实例继续运行(不会把页面搞挂)。
*
* 依赖:先运行 dev/start-dev.cmd(或 node dev/serve.mjs)启动本地服务。
* 依赖:先运行 scripts/start-dev.cmd(或 node dev/serve.mjs)启动本地服务。
* 生效方式:MODE = 'hot' 不刷新页面;'reload' 变更后整页刷新。
*/
(function () {
@@ -203,8 +203,8 @@
console.warn(TAG, '开发服务不可用,使用缓存源码:', e.message);
apply(cached);
} else {
console.error(TAG, '开发服务不可用且无缓存。请先运行 dev/start-dev.cmd');
badge('未连上本地开发服务(' + SERVER + ')\n请运行 dev/start-dev.cmd');
console.error(TAG, '开发服务不可用且无缓存。请先运行 scripts/start-dev.cmd');
badge('未连上本地开发服务(' + SERVER + ')\n请运行 scripts/start-dev.cmd');
}
}).then(function () {
if (isTop) schedule(POLL_MS);
-15
View File
@@ -1,15 +0,0 @@
@echo off
rem NOTE: keep this file PURE ASCII, see start-headless.cmd for why.
rem (cmd.exe parses batch files byte-by-byte with the current code page;
rem multi-byte characters corrupt line offsets.)
chcp 65001 >nul
cd /d "%~dp0.."
title YXT Cruise - dev server
where node >nul 2>nul
if errorlevel 1 (
echo [error] node.exe not found. Install Node.js from https://nodejs.org/
pause
exit /b 1
)
node "%~dp0serve.mjs" %*
if errorlevel 1 pause
+2 -2
View File
@@ -5,9 +5,9 @@
import fs from 'node:fs';
import {
resolveBrowser as _resolveBrowser, safetyArgs as _safetyArgs, hasDisplay,
} from '../runner/browser.mjs';
} from '../../runner/browser.mjs';
export { cleanStaleSingleton } from '../runner/browser.mjs';
export { cleanStaleSingleton } from '../../runner/browser.mjs';
export async function connect(wsUrl) {
const ws = new WebSocket(wsUrl);
+3 -2
View File
@@ -27,7 +27,8 @@ import { fileURLToPath } from 'node:url';
import { connect, sleep, httpJson, findChrome, forceHeadless, safetyArgs } from './real-cdp.mjs';
const HERE = path.dirname(fileURLToPath(import.meta.url));
const ROOT = path.resolve(HERE, '..');
// 本文件在 dev/tests/ 下,仓库根目录是上两级
const ROOT = path.resolve(HERE, '..', '..');
const SCRIPT_SRC = fs.readFileSync(path.join(ROOT, 'yun-xue-tang-assistant.user.js'), 'utf8');
const argv = process.argv.slice(2);
@@ -44,7 +45,7 @@ const SAMPLE_SECONDS = Number(opt('--seconds', 25));
const HEADLESS = flag('--headless') || process.env.YUN_XUE_TANG_HEADLESS === '1';
const KEEP = flag('--keep');
const PORT = Number(process.env.YUN_XUE_TANG_CDP_PORT || 9334);
const SHOT_DIR = opt('--shotdir', path.join(ROOT, 'docs/screenshots'));
const SHOT_DIR = opt('--shotdir', path.join(ROOT, '.run-tmp', 'screenshots'));
const ORIGIN = 'https://kfmic.yunxuetang.cn';
const CANDIDATES = [
+2 -1
View File
@@ -27,7 +27,8 @@ import { fileURLToPath } from 'node:url';
import { connect, sleep, httpJson, findChrome, forceHeadless, safetyArgs } from './real-cdp.mjs';
const HERE = path.dirname(fileURLToPath(import.meta.url));
const ROOT = path.resolve(HERE, '..');
// 本文件在 dev/tests/ 下,仓库根目录是上两级
const ROOT = path.resolve(HERE, '..', '..');
const SCRIPT_SRC = fs.readFileSync(path.join(ROOT, 'yun-xue-tang-assistant.user.js'), 'utf8');
const argv = process.argv.slice(2);
+10 -6
View File
@@ -16,7 +16,7 @@
* YUN_XUE_TANG_CHROME Chrome/Edge 可执行文件路径
* YUN_XUE_TANG_CDP_PORT 调试端口,默认 9333
* YUN_XUE_TANG_URL 起始页面,默认 https://kfmic.yunxuetang.cn/login.html
* YUN_XUE_TANG_SHOT_DIR 截图目录,默认 docs/screenshots
* YUN_XUE_TANG_SHOT_DIR 截图目录,默认 .run-tmp/screenshots(不入库)
*
* 需要 Node 22+(用到全局 WebSocket 与 fetch);只做只读探测:
* 不填写账号密码、不点登录、不修改线上数据。
@@ -29,9 +29,13 @@ import { fileURLToPath } from 'node:url';
import { connect, sleep, httpJson, findChrome, forceHeadless, safetyArgs } from './real-cdp.mjs';
const HERE = path.dirname(fileURLToPath(import.meta.url));
const ROOT = path.resolve(HERE, '..');
// 本文件在 dev/tests/ 下,仓库根目录是上两级
const ROOT = path.resolve(HERE, '..', '..');
const SCRIPT_FILE = path.join(ROOT, 'yun-xue-tang-assistant.user.js');
const SCRIPT_SRC = fs.readFileSync(SCRIPT_FILE, 'utf8');
// 版本号只有 package.json 一个来源(与 build.mjs 注入产物的一致),避免断言写死后每次升版都要改测试
const VERSION = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version;
const EXPECT_VERSION = 'v' + VERSION;
const CANDIDATES = [
process.env.YUN_XUE_TANG_CHROME,
@@ -49,7 +53,7 @@ const PORT = Number(process.env.YUN_XUE_TANG_CDP_PORT || 9333);
const START_URL = process.env.YUN_XUE_TANG_URL || 'https://kfmic.yunxuetang.cn/login.html';
const HEADLESS = process.env.YUN_XUE_TANG_HEADLESS === '1' || process.argv.includes('--headless');
const KEEP = process.env.YUN_XUE_TANG_KEEP === '1' || process.argv.includes('--keep');
const SHOT_DIR = process.env.YUN_XUE_TANG_SHOT_DIR || path.join(ROOT, 'docs/screenshots');
const SHOT_DIR = process.env.YUN_XUE_TANG_SHOT_DIR || path.join(ROOT, '.run-tmp', 'screenshots');
const results = [];
const consoleLogs = [];
@@ -171,7 +175,7 @@ try {
})())`);
check('面板渲染进真实 DOM 且可见', panel && panel.visible && panel.w > 0 && panel.h > 0,
panel && { 宽: panel.w, 高: panel.h, position: panel.position, zIndex: panel.zIndex });
check('面板版本号 v2.7.0', panel && panel.version === 'v2.7.0', panel && panel.version);
check('面板版本号 ' + EXPECT_VERSION, panel && panel.version === EXPECT_VERSION, panel && panel.version);
check('固定在右下角', panel && panel.right >= 0 && panel.right < 40 && panel.bottom >= 0 && panel.bottom < 40,
panel && { 距右: panel.right, 距下: panel.bottom });
check('面板含按钮与密码框', panel && panel.buttons.length >= 2 && panel.inputTypes.includes('password'),
@@ -246,7 +250,7 @@ try {
})`);
check('dispose 后真实 DOM 面板被移除', hot.panel === false && hot.api === 'undefined',
hot);
check('重新注入后面板唯一且版本正确', hot2.count === 1 && hot2.api === 'object' && hot2.version === 'v2.7.0', hot2);
check('重新注入后面板唯一且版本正确', hot2.count === 1 && hot2.api === 'object' && hot2.version === EXPECT_VERSION, hot2);
// ---- 9. 截图存证 ----
try {
@@ -300,7 +304,7 @@ try {
bodyScrollable: document.body.scrollHeight > 0,
})`);
check('重定向后重新注入:面板唯一且脚本正常',
reinjected.panel === 1 && reinjected.version === 'v2.7.0' && reinjected.route !== 'no-api', reinjected);
reinjected.panel === 1 && reinjected.version === EXPECT_VERSION && reinjected.route !== 'no-api', reinjected);
check('列表页导航无脚本报错', scriptErrors().length === 0, scriptErrors().map((e) => e.text.slice(0, 140)));
// ---- 汇总控制台 ----