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

+69
View File
@@ -0,0 +1,69 @@
#!/usr/bin/env node
/**
* 用 esbuild 把 src/ 下的模块打包成单个 Tampermonkey 脚本。
*
* 产物:仓库根目录的 yun-xue-tang-assistant.user.js(与拆分前的文件名完全一致,
* 因此 dev/serve.mjs、dev/dev-loader.user.js 热加载链路无需任何改动)。
*
* 用法:
* npm run build 一次性打包
* npm run build:watch 监听 src/ 自动重新打包(配合热加载器,保存即生效)
* node scripts/build.mjs --minify 压缩产物(发布用)
*/
import esbuild from 'esbuild';
import path from 'node:path';
import { readFile, stat } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
// 本文件在 scripts/ 下,仓库根目录是它的上一级
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const SRC_DIR = path.join(ROOT, 'src');
const ENTRY = path.join(SRC_DIR, 'index.js');
const META = path.join(SRC_DIR, 'meta.js');
const OUT = path.join(ROOT, 'yun-xue-tang-assistant.user.js');
// 版本号只有 package.json 一个来源:banner 的 @version 与 config.js 的 VERSION 都由它生成
const { version } = JSON.parse(await readFile(path.join(ROOT, 'package.json'), 'utf8'));
const args = process.argv.slice(2);
const watch = args.includes('--watch');
const minify = args.includes('--minify');
const common = {
entryPoints: [ENTRY],
bundle: true,
format: 'iife',
target: ['chrome80', 'firefox78', 'safari13'],
minify,
charset: 'utf8',
// __YUN_XUE_TANG_VERSION__ 由 src/config.js 引用,构建时替换成 package.json 的版本号
define: { __YUN_XUE_TANG_VERSION__: JSON.stringify(version) },
// 用原生 import/export + format=iife,esbuild 不会注入 __export 等辅助代码。
logLevel: 'info',
};
// src/meta.js 里的 @version 写成 __YUN_XUE_TANG_VERSION__,由这里按 package.json 替换
async function bannerText() {
const raw = await readFile(META, 'utf8');
return raw.replace('__YUN_XUE_TANG_VERSION__', version).trimEnd() + '\n';
}
const buildOptions = (banner) => ({ ...common, banner: { js: banner }, outfile: OUT });
async function runOnce() {
const startedAt = Date.now();
await esbuild.build(buildOptions(await bannerText()));
const size = (await stat(OUT)).size;
console.log(`[build] 已生成 ${OUT}(${size} 字节 / ${(size / 1024).toFixed(1)} KB)${minify ? '(压缩)' : ''},耗时 ${Date.now() - startedAt}ms`);
}
async function runWatch() {
const ctx = await esbuild.context(buildOptions(await bannerText()));
await ctx.watch();
console.log('[build] 监听中:保存 src/ 下的文件即自动重新打包(dev 服务会感知哈希变化)');
}
(watch ? runWatch() : runOnce()).catch((e) => {
console.error('[build] 失败:', e);
process.exit(1);
});
+110
View File
@@ -0,0 +1,110 @@
#!/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 一起收;scripts/ 也在里面,含本文件自己) */
const DIRS = ['runner', 'dev', 'scripts', 'config'];
/** 顶层要单独检查的文件(构建产物不入源码校验,它在 scripts/ 下重新生成后自然被覆盖) */
const FILES = ['yun-xue-tang-assistant.user.js'];
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);
}
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 + ')');
+15
View File
@@ -0,0 +1,15 @@
@echo off
rem NOTE: keep this file PURE ASCII, see scripts\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 "%~dp0..\dev\serve.mjs" %*
if errorlevel 1 pause
+60
View File
@@ -0,0 +1,60 @@
@echo off
rem ---------------------------------------------------------------
rem This file must stay PURE ASCII.
rem cmd.exe reads batch files byte-by-byte with the current code page;
rem multi-byte characters (e.g. Chinese) corrupt line offsets and make
rem it report nonsense like "'npm' is not recognized".
rem All Chinese messages come from the Node runner output instead.
rem
rem Usage:
rem scripts\start-headless.cmd use config␍unner.config.mjs
rem scripts\start-headless.cmd --help print all options
rem scripts\start-headless.cmd --max 3 command line overrides config file
rem ---------------------------------------------------------------
setlocal
chcp 65001 >nul
cd /d "%~dp0.."
title YunXueTang Assistant - headless runner
where node >nul 2>nul
if errorlevel 1 goto no_node
if exist "yun-xue-tang-assistant.user.js" goto have_build
echo [build] build output not found, running npm run build ...
call npm run build
if errorlevel 1 goto build_fail
:have_build
if not exist "config␍unner.config.mjs" goto no_config
echo [config] config␍unner.config.mjs found, editing it is enough (no rebuild needed)
goto run
:no_config
echo [warn] config␍unner.config.mjs not found, built-in defaults will be used
:run
echo [run] headless runner starting, press Ctrl+C to stop
echo.
node "runner/headless.mjs" %*
set RC=%ERRORLEVEL%
if "%RC%"=="0" goto done
echo.
echo [exit] code %RC%
echo 0 finished 1 no progress 2 env/args error 3 login failed
echo full log: run-logs\headless.log
pause
exit /b %RC%
:done
exit /b 0
:no_node
echo [error] node.exe not found. Install Node.js 22+ from https://nodejs.org/
pause
exit /b 1
:build_fail
echo [error] build failed. Run npm install first.
pause
exit /b 1