Files
yun-xue-tang-assistant/runner/config.mjs
T
void c1e883d67f 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 通过)。
2026-10-25 23:21:59 +08:00

357 lines
17 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// 运行参数与路径:配置文件 / 环境变量 / 命令行在这里集中解析,其它模块只读导出的常量。
//
// 优先级(后者覆盖前者):
// 内置默认值 < runner.config.mjs < 环境变量 YUN_XUE_TANG_* < 命令行参数 --x
//
// 配置文件是 JS 模块(见仓库根目录的 runner.config.mjs),可以写注释和表达式。
// 账号密码不在配置文件里,只认环境变量 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD,
// 避免凭据进入版本库、进程列表和计划任务历史。
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { defaultProfileDir } from './browser.mjs';
import { hasDisplay, noDisplayReason, platformName } from './platform.mjs';
export { platformName, noDisplayReason };
const HERE = path.dirname(fileURLToPath(import.meta.url));
export const ROOT = path.resolve(HERE, '..');
/** 构建产物(注入页面的单文件脚本) */
export const SCRIPT_FILE = path.join(ROOT, 'yun-xue-tang-assistant.user.js');
// ---------------------------------------------------------------------------
// 一层:内置默认值
// ---------------------------------------------------------------------------
const DEFAULTS = {
maxCourses: 0, // 0 = 不限(一直刷到没有未学完的课)
budgetMinutes: 0, // 0 = 不限
preferShort: true,
restartMinutes: 0, // 0 = 停下就退出
idleRestartMinutes: 30,
origin: 'https://kfmic.yunxuetang.cn',
url: '', // 留空 = <origin>/login.html
port: 9336,
headless: true,
chrome: '',
extraArgs: '',
profile: '', // 留空 = ./.run-profile
logFile: '', // 留空 = ./run-logs/headless.log
logMaxBytes: 5 * 1024 * 1024,
};
const argv = process.argv.slice(2);
// 已废弃 / 旧版参数别名:老脚本里的写法继续可用,不报错
const DEPRECATED = {
'--visible': '已废弃:等价于设置 headless: false(或 --headless 0),本版本仍然可用',
};
/** 旧参数名 -> 配置字段(保持向后兼容,dev/tests/ 下的脚本还在用) */
const ALIASES = {
'--max': 'maxCourses',
'--budget': 'budgetMinutes',
'--restart': 'restartMinutes',
'--idle': 'idleRestartMinutes',
'--log': 'logFile',
'--log-max': 'logMaxBytes',
};
// ---------------------------------------------------------------------------
// 两层:读配置文件(JS 模块)
// ---------------------------------------------------------------------------
/** 配置文件路径:命令行 --config > 环境变量 YUN_XUE_TANG_CONFIG > config/runner.config.mjs */
function configPath() {
const i = argv.indexOf('--config');
if (i >= 0 && argv[i + 1]) return path.resolve(argv[i + 1]);
if (process.env.YUN_XUE_TANG_CONFIG) return path.resolve(process.env.YUN_XUE_TANG_CONFIG);
const def = path.join(ROOT, 'config/runner.config.mjs');
return fs.existsSync(def) ? def : '';
}
export const CONFIG_FILE = configPath();
const CONFIG_KNOWN = new Set([...Object.keys(DEFAULTS), 'username', 'password', 'check']);
let fileConfig = {};
const configWarnings = [];
if (CONFIG_FILE) {
try {
const mod = await import(pathToFileURL(CONFIG_FILE).href + '?t=' + Date.now());
const raw = mod.default;
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
throw new Error('默认导出必须是一个对象:export default { ... }');
}
for (const [k, v] of Object.entries(raw)) {
if (!CONFIG_KNOWN.has(k)) configWarnings.push('配置文件里有未知字段「' + k + '」,已忽略');
else if (v !== undefined) fileConfig[k] = v;
}
// 配置里写了账号:不采纳,只提示一次,避免有人以为这样能生效
if (fileConfig.username !== undefined || fileConfig.password !== undefined) {
configWarnings.push('配置文件里的 username / password 已忽略:凭据只认环境变量 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD');
}
} catch (e) {
const explicit = argv.includes('--config') || !!process.env.YUN_XUE_TANG_CONFIG;
const msg = e && e.code === 'ERR_MODULE_NOT_FOUND'
? (explicit ? '指定的配置文件不存在' : '配置文件导入失败')
: '配置文件内容有误';
console.error(msg + ':' + CONFIG_FILE + '\n ' + (e && e.message ? e.message.split('\n')[0] : e));
process.exit(2);
}
}
// ---------------------------------------------------------------------------
// 命令行解析:--key value / --key=value / --flag
// ---------------------------------------------------------------------------
const BOOL_KEYS = ['preferShort', 'headless', 'check'];
const NUM_KEYS = ['maxCourses', 'budgetMinutes', 'restartMinutes', 'idleRestartMinutes', 'port', 'logMaxBytes'];
const STR_KEYS = ['origin', 'url', 'profile', 'logFile', 'chrome', 'extraArgs', 'config'];
/** kebab-case → camelCase:--max-courses → maxCourses */
function toCamel(flag) {
return flag.replace(/^--/, '').replace(/-([a-z])/g, (m, c) => c.toUpperCase());
}
const camelToFlag = (k) => '--' + k.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
function parseBool(v, raw) {
const s = String(v).trim().toLowerCase();
if (['1', 'true', 'yes', 'on', 'y'].includes(s)) return true;
if (['0', 'false', 'no', 'off', 'n'].includes(s)) return false;
console.error('参数值不是布尔值:' + raw + '(可用 1/0、true/false、on/off)');
process.exit(2);
}
const cliRaw = {};
const unknownFlags = [];
const missingValues = [];
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
if (!a.startsWith('--')) {
unknownFlags.push(a);
continue;
}
const eq = a.indexOf('=');
let name;
let inline;
if (eq > 0) {
name = a.slice(0, eq);
inline = a.slice(eq + 1);
} else {
name = a;
}
if (DEPRECATED[name]) configWarnings.push(DEPRECATED[name]);
let key = toCamel(name);
if (ALIASES[name]) key = ALIASES[name];
if (name === '--visible') key = 'headless'; // --visible = headless false
if (name === '--help' || name === '-h') key = 'help';
if (name === '--check') key = 'check';
const known = CONFIG_KNOWN.has(key) || key === 'help' || key === 'config';
if (!known) {
unknownFlags.push(name);
// 把未知参数的值一并吞掉,否则它会被当成一个独立的多余位置参数一起报
if (inline === undefined && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) i++;
continue;
}
if (!BOOL_KEYS.includes(key) && !NUM_KEYS.includes(key) && !STR_KEYS.includes(key) && key !== 'help' && key !== 'config') {
unknownFlags.push(name);
if (inline === undefined && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) i++;
continue;
}
// 布尔量可以不带值(--check 等于 --check 1);数值和字符串必须带值
let val;
if (inline !== undefined) val = inline;
else if (BOOL_KEYS.includes(key) && (argv[i + 1] === undefined || argv[i + 1].startsWith('--'))) val = '1';
else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--')) val = argv[++i];
else {
missingValues.push(name);
continue;
}
if (name === '--visible') val = String(parseBool(val, name) ? 0 : 1); // --visible 0 → headless 1
cliRaw[key] = val;
}
// ---------------------------------------------------------------------------
// 三层:环境变量
// ---------------------------------------------------------------------------
const envNum = (name, cur) => {
const v = process.env[name];
if (v === undefined || v === '') return cur;
const n = Number(v);
if (!Number.isFinite(n)) {
configWarnings.push(name + ' 不是数字,已忽略:' + v);
return cur;
}
return n;
};
const envBool = (name, cur) => {
const v = process.env[name];
if (v === undefined || v === '') return cur;
return !/^(0|false|no|off)$/i.test(v);
};
const envStr = (name, cur) => {
const v = process.env[name];
return v === undefined || v === '' ? cur : v;
};
// ---------------------------------------------------------------------------
// 合并:defaults < 配置文件 < 环境变量 < 命令行
// ---------------------------------------------------------------------------
const merged = { ...DEFAULTS, ...fileConfig };
merged.maxCourses = envNum('YUN_XUE_TANG_MAX_COURSES', merged.maxCourses);
merged.budgetMinutes = envNum('YUN_XUE_TANG_BUDGET_MINUTES', merged.budgetMinutes);
merged.restartMinutes = envNum('YUN_XUE_TANG_RESTART_MINUTES', merged.restartMinutes);
merged.idleRestartMinutes = envNum('YUN_XUE_TANG_IDLE_RESTART_MINUTES', merged.idleRestartMinutes);
merged.port = envNum('YUN_XUE_TANG_CDP_PORT', merged.port);
merged.logMaxBytes = envNum('YUN_XUE_TANG_LOG_MAX_BYTES', merged.logMaxBytes);
merged.preferShort = envBool('YUN_XUE_TANG_PREFER_SHORT', merged.preferShort);
merged.headless = envBool('YUN_XUE_TANG_HEADLESS', merged.headless);
merged.origin = envStr('YUN_XUE_TANG_ORIGIN', merged.origin);
merged.url = envStr('YUN_XUE_TANG_URL', merged.url);
merged.logFile = envStr('YUN_XUE_TANG_LOG_FILE', merged.logFile);
merged.profile = envStr('YUN_XUE_TANG_PROFILE_DIR', merged.profile);
merged.chrome = envStr('YUN_XUE_TANG_CHROME_BIN', merged.chrome);
merged.extraArgs = envStr('YUN_XUE_TANG_EXTRA_ARGS', merged.extraArgs);
// 命令行最后覆盖
const numBad = [];
for (const [key, raw] of Object.entries(cliRaw)) {
if (key === 'help' || key === 'config') continue;
if (key === 'check') { merged.check = parseBool(raw, '--check'); continue; }
if (BOOL_KEYS.includes(key)) { merged[key] = parseBool(raw, camelToFlag(key)); continue; }
if (NUM_KEYS.includes(key)) {
const n = Number(raw);
if (!Number.isFinite(n)) numBad.push(camelToFlag(key) + ' 需要数字,收到「' + raw + '」');
else merged[key] = n;
continue;
}
merged[key] = raw;
}
// ---------------------------------------------------------------------------
// 校验
// ---------------------------------------------------------------------------
const problems = [...numBad];
if (numBad.length === 0) {
if (!(merged.port >= 1 && merged.port <= 65535)) problems.push('port 必须在 1-65535 之间,收到 ' + merged.port);
if (!(merged.maxCourses >= 0)) problems.push('maxCourses 不能为负,收到 ' + merged.maxCourses);
if (!(merged.budgetMinutes >= 0)) problems.push('budgetMinutes 不能为负,收到 ' + merged.budgetMinutes);
if (!(merged.restartMinutes >= 0)) problems.push('restartMinutes 不能为负,收到 ' + merged.restartMinutes);
if (!(merged.idleRestartMinutes >= 0)) problems.push('idleRestartMinutes 不能为负,收到 ' + merged.idleRestartMinutes);
if (!(merged.logMaxBytes >= 0)) problems.push('logMaxBytes 不能为负,收到 ' + merged.logMaxBytes);
}
if (unknownFlags.length) {
const uniq = [...new Set(unknownFlags)];
problems.push('无法识别的参数:' + uniq.join(' ') + '(用 --help 查看支持的参数)');
}
if (missingValues.length) {
const uniq = [...new Set(missingValues)];
problems.push('这些参数缺少值:' + uniq.join(' '));
}
export const HELP = argv.includes('--help') || argv.includes('-h');
if (problems.length && !HELP) {
console.error('参数有误:');
for (const p of problems) console.error(' · ' + p);
console.error('\n用 --help 查看支持的参数与配置文件字段。');
process.exit(2);
}
// ---------------------------------------------------------------------------
// 导出(保持原有大写下划线命名,其它模块不用改)
// ---------------------------------------------------------------------------
export const CHECK_ONLY = !!merged.check;
export const ORIGIN = String(merged.origin || DEFAULTS.origin).replace(/\/+$/, '');
export const START_URL = merged.url ? String(merged.url) : ORIGIN + '/login.html';
export const USR = process.env.YUN_XUE_TANG_USR || '';
export const PWD = process.env.YUN_XUE_TANG_PWD || '';
export const PORT = merged.port;
/** 本次最多完成几门课(0 = 不限) */
export const MAX_COURSES = merged.maxCourses;
/** 运行多少分钟后收尾(0 = 不限) */
export const BUDGET_MINUTES = merged.budgetMinutes;
export const PROFILE_DIR = merged.profile
? path.resolve(ROOT, merged.profile)
: defaultProfileDir(ROOT);
// 没有图形显示的环境(Linux 无 DISPLAY、Windows 的 Session 0)上开不了有界面浏览器,
// 即使配置成有界面也强制无头:否则 Chrome 在 Linux 上报「Missing X server」然后退出,
// 在 Windows 服务会话里则是起来就崩。
export const WANT_VISIBLE = !merged.headless;
export const VISIBLE = WANT_VISIBLE && hasDisplay();
export const PREFER_SHORT = merged.preferShort;
/** 脚本自己停下后等待多少分钟再开新一轮(0 = 直接退出) */
export const RESTART_MINUTES = merged.restartMinutes;
/** 连续多少分钟没有任何进展判定卡死 */
export const IDLE_RESTART_MINUTES = merged.idleRestartMinutes;
export const LOG_FILE = merged.logFile
? path.resolve(ROOT, merged.logFile)
: path.join(ROOT, 'run-logs/headless.log');
export const LOG_MAX_BYTES = merged.logMaxBytes;
export const EXTRA_ARGS = String(merged.extraArgs || '').split(/\s+/).filter(Boolean);
/** 配置文件里指定的浏览器路径(空 = 自动探测;优先级低于 YUN_XUE_TANG_CHROME_BIN,见 browser.mjs) */
export const CHROME_BIN = merged.chrome || '';
export const WARNINGS = configWarnings;
/** 一条便于粘贴到 issue / 日志的自述 */
export function describeRun() {
return {
configFile: CONFIG_FILE || '(未找到,使用内置默认值)',
platform: platformName,
checkOnly: CHECK_ONLY,
headless: !VISIBLE,
port: PORT,
maxCourses: MAX_COURSES > 0 ? MAX_COURSES : '不限',
budgetMinutes: BUDGET_MINUTES > 0 ? BUDGET_MINUTES : '不限',
preferShort: PREFER_SHORT,
restartMinutes: RESTART_MINUTES,
idleRestartMinutes: IDLE_RESTART_MINUTES,
profileDir: PROFILE_DIR,
logFile: LOG_FILE,
};
}
/** --help 文本:字段、命令行名、环境变量、当前生效值一起列出 */
export function helpText() {
const rows = [
['配置字段', '命令行', '环境变量', '当前生效', '说明'],
['maxCourses', '--max-courses', 'YUN_XUE_TANG_MAX_COURSES', MAX_COURSES, '本次最多完成几门课;0 = 不限'],
['budgetMinutes', '--budget-minutes', 'YUN_XUE_TANG_BUDGET_MINUTES', BUDGET_MINUTES, '跑多少分钟后收尾;0 = 不限'],
['preferShort', '--prefer-short', 'YUN_XUE_TANG_PREFER_SHORT', PREFER_SHORT, '优先总时长最短的课程'],
['restartMinutes', '--restart-minutes', 'YUN_XUE_TANG_RESTART_MINUTES', RESTART_MINUTES, '脚本停下后等几分钟开新一轮;0 = 退出'],
['idleRestartMinutes', '--idle-restart-minutes', 'YUN_XUE_TANG_IDLE_RESTART_MINUTES', IDLE_RESTART_MINUTES, '多少分钟无进展判卡死'],
['origin', '--origin', 'YUN_XUE_TANG_ORIGIN', ORIGIN, '站点根地址'],
['url', '--url', 'YUN_XUE_TANG_URL', START_URL, '起始页面;空 = <origin>/login.html'],
['port', '--port', 'YUN_XUE_TANG_CDP_PORT', PORT, 'CDP 调试端口'],
['headless', '--headless 0|1', 'YUN_XUE_TANG_HEADLESS', !VISIBLE, '1 = 无头,0 = 有界面'],
['chrome', '--chrome', 'YUN_XUE_TANG_CHROME_BIN', CHROME_BIN || '(自动探测)', '浏览器可执行文件'],
['extraArgs', '--extra-args', 'YUN_XUE_TANG_EXTRA_ARGS', EXTRA_ARGS.join(' ') || '(无)', '追加给浏览器的参数'],
['profile', '--profile', 'YUN_XUE_TANG_PROFILE_DIR', PROFILE_DIR, '持久化 profile 目录'],
['logFile', '--log-file', 'YUN_XUE_TANG_LOG_FILE', LOG_FILE, '日志文件'],
['logMaxBytes', '--log-max-bytes', 'YUN_XUE_TANG_LOG_MAX_BYTES', LOG_MAX_BYTES, '单文件上限,超出轮转'],
['(字段 check)', '--check', '', CHECK_ONLY, '只做环境自检,不动进度'],
['(无字段)', '--config', 'YUN_XUE_TANG_CONFIG', CONFIG_FILE || '(内置默认)', '指定配置文件路径'],
];
const widths = [0, 1, 2, 3].map((c) => Math.max(...rows.map((r) => String(r[c]).length)));
const lines = [];
lines.push('云学堂无头运行器');
lines.push('');
lines.push('用法:node runner/headless.mjs [参数…]');
lines.push('优先级:内置默认值 < 配置文件 < 环境变量 YUN_XUE_TANG_* < 命令行参数');
lines.push('配置文件:' + (CONFIG_FILE || '(未找到)') + (CONFIG_FILE ? '' : ' —— 复制 config/runner.config.mjs 即可'));
lines.push('账号密码:只认环境变量 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD(不写进配置文件)');
lines.push('');
for (let i = 0; i < rows.length; i++) {
const r = rows[i].map((v, c) => (c < 4 ? String(v).padEnd(widths[c]) : String(v)));
lines.push((i === 0 ? '' : '') + r.join(' '));
if (i === 0) lines.push(' '.repeat(0) + widths.map((w) => '-'.repeat(w)).join(' '));
}
lines.push('');
lines.push('示例:');
lines.push(' node runner/headless.mjs --check # 只做环境自检');
lines.push(' node runner/headless.mjs --max-courses 3 # 本次最多 3 门');
lines.push(' node runner/headless.mjs --headless 0 # 开有界面浏览器调试');
lines.push(' node runner/headless.mjs --config ./config/runner.config.mjs # 显式指定配置文件');
lines.push('');
lines.push('旧参数名(仍然兼容):--max / --budget / --restart / --idle / --log / --log-max / --visible');
return lines.join('\n');
}