modelstage 0.0.0-stage → 0.5.24

package/tool/lib/spine-motions.mjs

@@ -0,0 +1,104 @@
+// ============================================================================
+// tool/lib/spine-motions.mjs —— Spine 动作名的「分组 / 循环 / 置信度」判定（纯函数）
+//
+// 为什么独立成纯函数 + 数据文件：
+//   Spine 的动作命名规则因游戏而异（bd2 与碧蓝航线画风/命名都不同），写死在代码里
+//   既难维护、也会绑定到某个前端。能力层应当只提供
+//   「规则数据 + 判定函数」，由调用方（新前端/导出工具）自行决定怎么用。
+//
+// 判定优先级：overrides（精确名） → families（正则族，按声明顺序首个命中） → defaults
+// 置信度：high = 规则显式匹配且有实测样本；low = 未命中任何规则（交给调用方保守处理）
+// ============================================================================
+
+import fs from 'node:fs';
+
+/** 读取规则文件（调用方可用自己的路径） */
+export function loadRules(file) {
+  const text = fs.readFileSync(file, 'utf8').replace(/^\s*\/\/.*$/gm, ''); // 允许 // 注释
+  const rules = JSON.parse(text);
+  validateRules(rules);
+  return rules;
+}
+
+/**
+ * 校验规则结构（失败抛可读错误，避免"规则写错了却静默不生效"）。
+ * 不做业务判断，只保证字段存在、类型正确、正则可编译。
+ */
+export function validateRules(rules) {
+  if (!rules || typeof rules !== 'object') throw new Error('规则文件不是对象');
+  if (!rules.defaults || typeof rules.defaults.loop !== 'boolean') throw new Error('规则缺少 defaults.loop（布尔）');
+  if (!rules.defaults.confidence) throw new Error('规则缺少 defaults.confidence');
+  const fams = rules.families;
+  if (!Array.isArray(fams)) throw new Error('规则缺少 families 数组');
+  for (const [i, f] of fams.entries()) {
+    const at = `families[${i}]`;
+    if (!f || typeof f.group !== 'string' || !f.group) throw new Error(`${at}.group 必须是非空字符串`);
+    if (!Array.isArray(f.patterns) || !f.patterns.length) throw new Error(`${at}.patterns 必须是非空数组`);
+    for (const p of f.patterns) {
+      try { new RegExp(p); } catch (e) { throw new Error(`${at} 的正则非法 ${JSON.stringify(p)}：${e.message}`); }
+    }
+    if (typeof f.loop !== 'boolean') throw new Error(`${at}.loop 必须是布尔`);
+    if (typeof f.hits !== 'number') throw new Error(`${at}.hits 必须是数字（实测命中数）`);
+    if (typeof f.note !== 'string' || !f.note.trim()) throw new Error(`${at}.note 必须写明依据`);
+  }
+  if (rules.overrides !== undefined && !Array.isArray(rules.overrides)) throw new Error('overrides 必须是数组');
+  return true;
+}
+
+/**
+ * 判定单个动作名。
+ * @param {string} name 动作名
+ * @param {object} rules loadRules 的结果
+ * @returns {{name:string, group:string, loop:boolean, confidence:'high'|'low', rule:string|null}}
+ */
+export function classify(name, rules) {
+  const n = String(name == null ? '' : name);
+  const ruleName = (r) => (r && r.id ? String(r.id) : null);
+
+  // ① 精确名覆盖（少量特例：名字一样但语义不同，比如 mission 与 mission_complete）
+  for (const o of (rules && rules.overrides) || []) {
+    if (o && o.name === n) {
+      return {
+        name: n,
+        group: o.group || n,
+        loop: typeof o.loop === 'boolean' ? o.loop : rules.defaults.loop,
+        confidence: o.confidence || 'high',
+        rule: ruleName(o) || `override:${n}`,
+      };
+    }
+  }
+  // ② 正则族（按声明顺序，首个命中即用）
+  for (const f of (rules && rules.families) || []) {
+    for (const p of f.patterns) {
+      let hit = false;
+      try { hit = new RegExp(p).test(n); } catch { hit = false; }
+      if (hit) {
+        return { name: n, group: f.group, loop: !!f.loop, confidence: f.confidence || 'high', rule: ruleName(f) || `family:${f.group}` };
+      }
+    }
+  }
+  // ③ 兜底：分组=动作名本身，不循环，低置信（宁可一次性动作也不误判成循环）
+  return { name: n, group: n, loop: !!rules.defaults.loop, confidence: rules.defaults.confidence || 'low', rule: null };
+}
+
+/** 批量判定（保持输入顺序） */
+export function classifyAll(names, rules) {
+  return (names || []).map((n) => classify(n, rules));
+}
+
+/** 统计规则命中情况（自检/报告用：证明每条规则都有实测样本） */
+export function countHits(names, rules) {
+  const out = [];
+  for (const f of (rules && rules.families) || []) {
+    let n = 0;
+    for (const name of names || []) {
+      for (const p of f.patterns) {
+        let hit = false;
+        try { hit = new RegExp(p).test(String(name)); } catch { hit = false; }
+        if (hit) { n++; break; }
+      }
+    }
+    out.push({ group: f.group, declaredHits: f.hits, actualHits: n, ok: f.hits === n });
+  }
+  return out;
+}

package/tool/lib/spine-runtime.mjs

@@ -0,0 +1,131 @@
+// ============================================================================
+// tool/lib/spine-runtime.mjs —— Spine 运行时源码定位 + 在 Node 里受控加载
+//
+// 为什么要单独一层：Spine 的 .skel/.json 只能由**对应版本**的运行时解析，
+//   而运行时代码是浏览器风格的打包体（会摸 document/window）。这里在 Node 的 vm 沙箱里
+//   垫一个最小 DOM 垫片把它跑起来，只用来做**数据层解析**（不渲染、不碰 WebGL）。
+//
+// 源码来源（按优先级，逐条探测，命中即用）：
+//   ① src/spine-runtimes/spine-webgl-<ver>.js        —— 项目内（该目录不入库）
+//   ② ../spine-runtimes/spine-webgl-<ver>.js         —— 工作区共享
+//   ③ 环境变量 SPINE_RUNTIME_DIR 指定的目录
+//
+// 没有内联兜底：运行时源码必须由外部提供，找不到时显式报错并给修复指引。
+//
+// 懒加载：首次真正要解析某版本时才读源码 + 建沙箱，之后按版本缓存；不在服务启动时加载。
+// ============================================================================
+
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..', '..');
+const WORKSPACE = path.resolve(ROOT, '..');
+
+/**
+ * 数据根：与 web.sh / serve.mjs 同一口径（MODELSTAGE_DATA_ROOT 覆盖，缺省项目根）。
+ * 下载物落在 <dataRoot>/runtimes/spine/<ver>/spine-webgl-<ver>.js。
+ * @returns {string}
+ */
+function dataRootDir() {
+  const env = (process.env.MODELSTAGE_DATA_ROOT || '').trim();
+  return env ? path.resolve(env) : ROOT;
+}
+
+/** 运行时源码候选目录（按优先级） */
+const RUNTIME_DIRS = [
+  path.join(ROOT, 'src', 'spine-runtimes'),
+  path.join(WORKSPACE, 'spine-runtimes'),
+  // **末尾追加**（上面两条的既有优先次序不动）：tool/fetch-runtimes.mjs 的下载落点。
+  //   必须放最后 —— "项目自带优先"不能因为引入下载功能而静默失效。
+  path.join(dataRootDir(), 'runtimes', 'spine'),
+];
+
+
+
+const sourceCache = new Map();   // version → { code, origin }
+/**
+ * 取某版本的运行时源码。
+ * @param {string} version 如 '3.8' / '4.2'
+ * @returns {{code:string, origin:string}|null}
+ */
+export function getRuntimeSource(version) {
+  if (sourceCache.has(version)) return sourceCache.get(version);
+  let hit = null;
+  for (const dir of RUNTIME_DIRS) {
+    // 两种布局都要认：
+    //   平铺  <dir>/spine-webgl-<ver>.js            —— 项目自带 / 环境变量目录的既有布局
+    //   分版本 <dir>/<ver>/spine-webgl-<ver>.js      —— tool/fetch-runtimes.mjs 的下载布局
+    //      （分版本目录是为了让每个版本各自带 LICENSE 与 SOURCE.json）
+    for (const p of [path.join(dir, `spine-webgl-${version}.js`), path.join(dir, version, `spine-webgl-${version}.js`)]) {
+      if (fs.existsSync(p)) { hit = { code: fs.readFileSync(p, 'utf8'), origin: p }; break; }
+    }
+    if (hit) break;
+  }
+  if (!hit && process.env.SPINE_RUNTIME_DIR) {
+    const p = path.join(process.env.SPINE_RUNTIME_DIR, `spine-webgl-${version}.js`);
+    if (fs.existsSync(p)) hit = { code: fs.readFileSync(p, 'utf8'), origin: p };
+  }
+  sourceCache.set(version, hit);
+  return hit;
+}
+
+/** 可用版本列表（扫描候选目录；平铺与分版本两种布局都算） */
+export function listRuntimeVersions() {
+  const out = new Set();
+  const addFrom = (dir) => {
+    for (const f of fs.readdirSync(dir)) {
+      const m = f.match(/^spine-webgl-(.+)\.js$/);
+      if (m) out.add(m[1]);
+    }
+  };
+  for (const dir of RUNTIME_DIRS) {
+    if (!fs.existsSync(dir)) continue;
+    addFrom(dir);
+    // 分版本子目录（下载布局）也要列出来
+    let subs = [];
+    try { subs = fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name); } catch { /* 跳过 */ }
+    for (const sub of subs) {
+      try { addFrom(path.join(dir, sub)); } catch { /* 跳过读不了的子目录 */ }
+    }
+  }
+  return [...out].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+}
+
+const sandboxCache = new Map();   // version → { spine, origin }
+/**
+ * 在 vm 沙箱里加载某版本运行时，返回其导出的 spine 对象（懒加载 + 缓存）。
+ *   沙箱只垫数据层需要的最小 DOM 能力：createElement 返回带 getContext()=null 的假 canvas，
+ *   足以让运行时完成模块初始化，但任何真正的渲染调用都会失败 —— 这正是我们要的边界。
+ */
+export function loadRuntime(version) {
+  if (sandboxCache.has(version)) return sandboxCache.get(version);
+  const src = getRuntimeSource(version);
+  if (!src) throw new Error(`没有可用的 Spine ${version} 运行时源码。请任选一种方式提供：SPINE_RUNTIME_DIR 环境变量 / src/spine-runtimes/ / 工作区共享 ../spine-runtimes/`);
+  const sandbox = {
+    console: { log() {}, info() {}, warn() {}, error() {}, debug() {} },
+    performance: { now: () => Date.now() },
+    navigator: { userAgent: 'node-spine-meta' },
+    setTimeout, clearTimeout, setInterval, clearInterval,
+    TextDecoder, TextEncoder,
+    URL, Blob,
+    document: {
+      createElement: () => ({ getContext: () => null, style: {}, addEventListener() {}, width: 0, height: 0 }),
+      addEventListener() {}, removeEventListener() {},
+    },
+    addEventListener() {}, removeEventListener() {},
+  };
+  sandbox.window = sandbox;
+  sandbox.self = sandbox;
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(src.code, sandbox, { filename: `spine-${version}.js` });
+  if (!sandbox.spine) throw new Error(`Spine ${version} 运行时加载后没有导出 spine 对象（源码来源：${src.origin}）`);
+  const hit = { spine: sandbox.spine, origin: src.origin };
+  sandboxCache.set(version, hit);
+  return hit;
+}
+
+export const PATHS = { ROOT, WORKSPACE, RUNTIME_DIRS };

package/tool/lib/test-lock.mjs

@@ -0,0 +1,178 @@
+// tool/lib/test-lock.mjs —— 测试运行的「单实例锁」（同一项目同时只允许一个测试实例）
+//
+// 为什么需要：两个人（或两个 AI 会话）同时跑 e2e 会互相踩——端口/共享浏览器/DPR/像素采样都会串味，
+//   结果是"我这边红你那边绿"扯不清。互斥之后，第二个实例**明确跳过并说清谁在跑**，
+//   而不是继续跑出假红（假红比不跑更贵：会误导修错地方）。
+//
+// 约定：
+//   · 锁文件 <repoRoot>/runtime/test.lock，内容 JSON：{ pid, startedAt, startedAtMs, host, label, tool }
+//   · 第二次获取失败 → 退出码 75（EX_TEMPFAIL，区别于 0 通过 / 1 失败），并打印持有者与已运行时长
+//   · 陈旧锁自动接管：持有者 PID 已不存在 ⇒ 直接接管（崩溃/被 kill 不该永久锁死项目）
+//   · 子进程继承：调用方设置 DSH_TEST_LOCK_HELD=1，子工具（如 check-console）不再重复加锁
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** "跳过"专用退出码（BSD EX_TEMPFAIL）：与 0 通过 / 1 失败明确区分 */
+export const EXIT_SKIPPED = 75;
+
+/** 子进程继承用的环境变量名 */
+export const HELD_ENV = 'DSH_TEST_LOCK_HELD';
+
+/**
+ * PID 是否还活着。
+ * @param {number} pid
+ * @returns {boolean}
+ */
+export function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0); // 只探测，不发信号
+    return true;
+  } catch (e) {
+    return e && e.code === 'EPERM'; // 存在但无权限 ⇒ 视为活着
+  }
+}
+
+/**
+ * 进程的真实启动时刻（Linux /proc）。
+ * 用来识别 **PID 复用**：操作系统回收 PID 后会把它分配给新进程，此时 `kill(pid,0)` 依然成功，
+ * 光看 isAlive 会以为锁还被持有 ⇒ 项目被永久锁死。判据：进程启动时刻**晚于**锁创建时刻 ⇒
+ * 它不可能是锁的持有者。
+ * @returns {number|null} epoch 毫秒；非 Linux 或读取失败返回 null（退回旧行为）
+ */
+export function procStartMs(pid) {
+  try {
+    const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+    // comm 字段可能含空格与括号（形如 (chrome-headless)，也可能含右括号）⇒ 取最后一个 ')' 之后
+    const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+    const startTicks = Number(rest[19]); // 第 22 个字段 starttime（pid/comm/state 之后从 0 数）
+    const btime = Number((fs.readFileSync('/proc/stat', 'utf8').match(/^btime (\d+)$/m) || [])[1]);
+    if (!Number.isFinite(startTicks) || !Number.isFinite(btime)) return null;
+    const CLK_TCK = 100; // 常见值；仅用于量级比较，不做精确计时
+    return btime * 1000 + (startTicks * 1000) / CLK_TCK;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 把锁内容渲染成一句人话（谁在跑 / PID / 开始时间 / 已运行多久）。
+ * @param {object} holder
+ * @returns {string}
+ */
+export function describeHolder(holder) {
+  if (!holder) return '(未知持有者)';
+  const startedMs = Number(holder.startedAtMs) || 0;
+  const elapsed = startedMs ? Math.max(0, Math.round((Date.now() - startedMs) / 1000)) : null;
+  const dur = elapsed === null ? '时长未知'
+    : (elapsed < 60 ? `${elapsed}s` : `${Math.floor(elapsed / 60)}m${String(elapsed % 60).padStart(2, '0')}s`);
+  return `PID ${holder.pid} · 开始 ${holder.startedAt || '?'} · 已运行 ${dur} · ${holder.label || '?'} · ${holder.tool || '?'}`;
+}
+
+/** 读锁文件；不存在或损坏返回 null */
+function readLock(file) {
+  try {
+    const raw = fs.readFileSync(file, 'utf8');
+    const j = JSON.parse(raw);
+    return j && typeof j === 'object' ? j : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 原子创建：openSync('wx') 成功才算拿到锁（避免两个进程同时判"没有锁"再互相覆盖） */
+function createExclusive(file, body) {
+  try {
+    const fd = fs.openSync(file, 'wx', 0o644);
+    fs.writeSync(fd, JSON.stringify(body, null, 2));
+    fs.closeSync(fd);
+    return true;
+  } catch (e) {
+    if (e && e.code === 'EEXIST') return false;
+    throw e;
+  }
+}
+
+/**
+ * 获取测试单实例锁。
+ * @param {{root: string, label?: string, tool?: string}} opts
+ * @returns {{acquired: boolean, holder?: object, file: string, tookOver?: boolean, release: Function}}
+ */
+export function acquireTestLock(opts) {
+  const root = opts.root;
+  const dir = path.join(root, 'runtime');
+  const file = path.join(dir, 'test.lock');
+  const body = {
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    startedAtMs: Date.now(),
+    host: os.hostname(),
+    label: opts.label || 'test',
+    tool: opts.tool || process.argv.slice(1).join(' '),
+  };
+  const noop = { acquired: true, file, release: () => {} };
+
+  // 子进程：父进程已持锁 ⇒ 不再加锁（否则 test-all → check-console 会自己把自己锁死）
+  if (process.env[HELD_ENV] === '1') return { ...noop, inherited: true };
+
+  fs.mkdirSync(dir, { recursive: true });
+
+  if (createExclusive(file, body)) {
+    return { acquired: true, file, release: makeRelease(file) };
+  }
+
+  // 已被占用：判断持有者是否还活着
+  const holder = readLock(file);
+  let alive = holder && isAlive(Number(holder.pid));
+  let pidReused = false;
+  if (alive) {
+    // PID 复用检测：进程启动晚于锁创建 ⇒ 抢锁的进程早已退出，这个 PID 是新进程
+    const startMs = procStartMs(Number(holder.pid));
+    const lockMs = Number(holder.startedAtMs) || 0;
+    if (startMs && lockMs && startMs > lockMs + 2000) {
+      alive = false;
+      pidReused = true;
+    }
+  }
+  if (alive) return { acquired: false, holder, file, release: () => {} };
+
+  // 陈旧锁（进程已死/文件损坏）⇒ 接管；崩溃不该把项目永久锁死
+  try {
+    fs.writeFileSync(file, JSON.stringify(body, null, 2), 'utf8');
+    return { acquired: true, file, tookOver: true, pidReused, holder, release: makeRelease(file) };
+  } catch (e) {
+    return { acquired: false, holder: holder || { pid: 0, label: `锁文件不可写：${e.message}` }, file, release: () => {} };
+  }
+}
+
+/** 释放：只删自己的锁（别人的锁不能被误删） */
+function makeRelease(file) {
+  return () => {
+    const cur = readLock(file);
+    if (cur && Number(cur.pid) !== process.pid) return; // 已不是我的锁，不动
+    try {
+      fs.unlinkSync(file);
+    } catch {
+      /* 已删除 */
+    }
+  };
+}
+
+/** 注册进程退出/中断时的自动释放（含 SIGINT/SIGTERM：Ctrl-C 也要解锁） */
+export function releaseOnExit(lock) {
+  if (!lock || !lock.acquired) return;
+  let done = false;
+  const bye = () => {
+    if (done) return;
+    done = true;
+    lock.release();
+  };
+  process.on('exit', bye);
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(sig, () => {
+      bye();
+      process.exit(EXIT_SKIPPED);
+    });
+  }
+}

package/tool/lib/test-report.mjs

@@ -0,0 +1,133 @@
+// tool/lib/test-report.mjs —— 回归结果落盘（每套一份 JSON + 本轮汇总 + latest 指针）
+//
+// 为什么需要：以前跑完只看终端汇总，跑挂/超时后想回溯"哪套、什么错、当时内存多少"就得整轮重跑。
+//   落盘后 AI 只读 `runtime/test-results/latest.json` 一个入口就能拿到全部结果。
+//
+// 一个关键能力：**把"真失败"和"超时被杀"分开**。
+//   套件被 SIGKILL 时 failed/total 都是 null，以前会被报成"红"（假红），
+//   实际情况是"跑太久被砍"。这类必须单独标出来，否则会让人去查根本不该查的业务代码。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 读系统可用内存（MB）；拿不到返回 null（非 Linux 或 /proc 不可读） */
+export function memAvailableMB() {
+  try {
+    // dsh-skip-quality 只读 /proc/meminfo（约 1~2KB 的固定格式伪文件），memory-bomb 不适用
+    const txt = fs.readFileSync('/proc/meminfo', 'utf8');
+    const m = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(txt);
+    return m ? Math.round(Number(m[1]) / 1024) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 时间戳目录名：yyyyMMdd-HHmmss（本地时区，便于人对号） */
+export function runStamp(date = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}${p(date.getMonth() + 1)}${p(date.getDate())}-${
+    p(date.getHours())}${p(date.getMinutes())}${p(date.getSeconds())}`;
+}
+
+/** 取文本尾巴（行数上限），用于 stdoutTail/stderrTail 诊断 */
+export function tailLines(text, maxLines = 200) {
+  const lines = String(text || '').split('\n');
+  return lines.slice(Math.max(0, lines.length - maxLines)).join('\n');
+}
+
+/**
+ * 判定一套的结局。**这是"超时 vs 真失败"的唯一判据**。
+ *
+ * @param {{result: object|null, status: number|null, signal: string|null, ms: number, limitMs: number}} p
+ * @returns {{status: string, hint: string}}
+ *   ok                 有结构化结果且 failed=0
+ *   failed             有结构化结果且 failed>0（真断言失败）
+ *   killed-by-timeout  没结果且被信号杀掉/退出码异常，且耗时≥上限（超时，不是断言失败）
+ *   no-result          没结果但不是超时（脚本崩、chrome 起不来、输出不是 JSON…）
+ */
+export function classifyOutcome({ result, status, signal, ms, limitMs }) {
+  if (result && Number.isFinite(result.failed)) {
+    return result.failed > 0
+      ? { status: 'failed', hint: `${result.failed} 项断言未通过` }
+      : { status: 'ok', hint: '' };
+  }
+  const nearLimit = Number.isFinite(limitMs) && ms >= limitMs * 0.9;
+  if (signal === 'SIGKILL' || status === 2 || (nearLimit && !result)) {
+    const how = signal ? `被 ${signal} 杀掉` : `退出码 ${status}`;
+    return {
+      status: 'killed-by-timeout',
+      hint: `套件跑了 ${ms}ms，接近/超过上限 ${limitMs}ms，${how} —— 提高超时或查它为什么慢（不是断言失败）`,
+    };
+  }
+  return { status: 'no-result', hint: `没产出结构化结果（exitCode=${status}），看 stdoutTail/stderrTail` };
+}
+
+/** 递归建目录并写 JSON（原子写：先写 .tmp 再 rename，避免读到半个文件） */
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 1)}\n`, 'utf8');
+  fs.renameSync(tmp, file);
+}
+
+/** 一套的落盘文件名（套件名已限定为 kebab-case，直接当文件名安全） */
+function suiteFile(dir, suiteName) {
+  return path.join(dir, `${suiteName}.json`);
+}
+
+/**
+ * 开一轮：建目录、写初始汇总（running=true）。
+ * @param {{outRoot: string, base: string, suites: string[], startedAt: string}} p
+ * @returns {{dir: string, summaryPath: string}}
+ */
+export function openRun({ outRoot, base, suites, startedAt }) {
+  const dir = path.join(outRoot, runStamp());
+  fs.mkdirSync(dir, { recursive: true });
+  const summaryPath = path.join(dir, 'run-summary.json');
+  writeJson(summaryPath, {
+    startedAt,
+    finishedAt: null,
+    running: true,          // 跑完置 false —— 外部可据此判断"还在跑吗"
+    exitCode: null,
+    base,
+    plannedSuites: suites,
+    suites: [],
+    env: { memAvailableMBAtStart: memAvailableMB(), node: process.version, pid: process.pid },
+  });
+  return { dir, summaryPath };
+}
+
+/** 单套写盘（每套跑完立刻写，后台跑中途被杀也留得下已跑部分） */
+export function writeSuiteResult(dir, entry) {
+  writeJson(suiteFile(dir, entry.suite), entry);
+}
+
+/** 更新汇总（每套跑完调一次，保证 running=true 期间也能看到进度） */
+export function updateSummary(summaryPath, patch) {
+  let prev = {};
+  try { prev = JSON.parse(fs.readFileSync(summaryPath, 'utf8')); } catch { prev = {}; }
+  writeJson(summaryPath, { ...prev, ...patch });
+}
+
+/**
+ * 收尾：写 finishedAt/exitCode/running=false，并把 `latest.json` 指过来。
+ * latest 里只放"去哪读"，避免同一份数据写两处后漂移。
+ */
+export function finishRun({ outRoot, dir, summaryPath, exitCode }) {
+  updateSummary(summaryPath, {
+    finishedAt: new Date().toISOString(),
+    running: false,
+    exitCode,
+    env: { ...(readJson(summaryPath, {}).env || {}), memAvailableMBAtEnd: memAvailableMB() },
+  });
+  writeJson(path.join(outRoot, 'latest.json'), {
+    run: path.basename(dir),
+    summary: path.relative(outRoot, summaryPath),
+    finishedAt: new Date().toISOString(),
+  });
+}
+
+/** 读 JSON（失败返回默认值） */
+export function readJson(file, fallback) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+}

package/tool/parse-jsonc.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// parse-jsonc.mjs — 带注释的 JSON 解析（JSONC），零依赖
+//
+// 为什么需要：标准 JSON 不支持注释，但配置文件是人要反复手改的，没注释很难维护。
+//   用 YAML 能原生支持注释，但要引入依赖（本项目刻意保持零依赖，见 zero-dep 规范）。
+//   折中方案：JSON + 轻量注释剥离，既零依赖，又能写 // 与 /* */ 注释。
+//
+// 关键正确性要求（易踩坑）：
+//   剥离注释时必须**跳过字符串内部**，否则会误伤路径/URL 里的 // 或 /*，
+//   例如 "path": "https://example.com/a//b" 里的 // 不是注释。
+//   本实现逐字符扫描并跟踪字符串状态（含转义 \" 处理），只在字符串外剥离。
+//
+// 用法：
+//   const { parseJsonc } = await import('./parse-jsonc.mjs');
+//   const cfg = parseJsonc(fs.readFileSync(file, 'utf8'));
+
+/**
+ * 剥离 JSONC 文本中的注释（保留字符串原样）。
+ * @param {string} text 原始文本
+ * @returns {string} 可被 JSON.parse 解析的文本
+ */
+export function stripComments(text) {
+  let out = '';
+  let inStr = false;
+  let esc = false;
+  let i = 0;
+  const n = text.length;
+
+  while (i < n) {
+    const ch = text[i];
+    const next = text[i + 1];
+
+    if (inStr) {
+      out += ch;
+      if (esc) { esc = false; }
+      else if (ch === '\\') { esc = true; }
+      else if (ch === '"') { inStr = false; }
+      i++;
+      continue;
+    }
+
+    // 字符串开始
+    if (ch === '"') { inStr = true; out += ch; i++; continue; }
+
+    // 行注释 //
+    if (ch === '/' && next === '/') {
+      while (i < n && text[i] !== '\n') i++;
+      continue; // 换行由下一轮原样输出，保持行号对齐
+    }
+
+    // 块注释 /* */
+    if (ch === '/' && next === '*') {
+      i += 2;
+      while (i < n && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i += 2; // 跳过结束符 */
+      continue;
+    }
+
+    out += ch;
+    i++;
+  }
+  return out;
+}
+
+/**
+ * 解析 JSONC（先剥离注释再 JSON.parse）。
+ * @param {string} text 原始文本
+ * @param {string} [label] 报错时的文件名提示
+ * @returns {any} 解析结果
+ */
+export function parseJsonc(text, label = '配置') {
+  const cleaned = stripComments(text);
+  try {
+    return JSON.parse(cleaned);
+  } catch (e) {
+    throw new Error(`${label}解析失败: ${e.message}（已剥离注释后再解析；若报错位置与原文不符，注意注释会改变行号）`);
+  }
+}
+
+// 直接运行：读文件并打印解析结果，便于排查配置
+// 仅 CLI 自跑时执行（被 import 时此分支不会进入），故不走 logger
+if (process.argv[1] && process.argv[1].endsWith('parse-jsonc.mjs') && process.argv[2]) {
+  const fs = await import('node:fs');
+  const cfg = parseJsonc(fs.readFileSync(process.argv[2], 'utf8'), process.argv[2]);
+  console.log(JSON.stringify(cfg, null, 2));
+}