@windsland52/maafw-live 0.3.0 → 0.4.0

package/lib/runtime/pretask.js

@@ -0,0 +1,217 @@
+/**
+ * pretask：连接 Controller **之前**跑一次的子进程（PI v2.7.0+，过滤字段 v2.8.1）。
+ *
+ * 契约（MaaFW 5.14.2 `3.3-ProjectInterfaceV2协议`，pinned commit 8061d5bc）：
+ * - 命令行 = `exec` + `args[]` + 可选末位 JSON（只有 `option` 非空时才追加）；
+ * - 那个 JSON 是**单行紧凑**字符串，作为**单个 argv 元素**传递，值为 OptionValue
+ *   （select/switch → `case.name`；checkbox → `case.name` 数组；input → `{字段: 值}`）；
+ * - 按声明序串行、等它结束，CWD = interface.json 所在目录；
+ * - **非零退出即中止本次启动**——任务根本不开始。
+ *
+ * 协议没规定、由本工具定的三处（写在这里，免得下一个人重新猜）：
+ * 1. 声明了 `controller` / `resource` 过滤且当前不适用时**跳过并说明**。协议只说 Client
+ *    可以隐藏/置灰，不保证跳过执行；但"启动模拟器"这类命令跑错控制器代价更大。
+ * 2. 末位 JSON **不用 preset**：pretask 发生在任务选择之前，而 preset 是按任务的快照。
+ *    这里只吃 CLI `--option` 与声明里的初始值（`default_case` / `inputs[].default`）。
+ * 3. 超时协议没规定，本工具定 120s（`MAAFW_PRETASK_TIMEOUT_MS` 覆盖；<=0 关超时）：
+ *    "启动模拟器"挂成死等时不能靠调用方 Ctrl-C 收摊（设计审查 P0-2）。超时杀的是
+ *    **进程树**（Windows taskkill /T）——pretask 拉起模拟器的链式脚本只杀头部会留孙代。
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { resolveOptionValue } from '../interface/override.js';
+/** 子进程输出只留尾部：够归因，不会把大日志塞进上下文。 */
+const TAIL_LIMIT = 4000;
+/**
+ * 拼一条 pretask 的完整 argv（含末位 JSON）。**纯函数**：执行与参数构造分开，
+ * 参数形状可以离线单测——这部分错了就是"脚本收到了奇怪的参数但没人报错"。
+ */
+export function buildPretaskArgv(p, loaded, ctx) {
+    const warns = [];
+    const json = {};
+    for (const key of p.option) {
+        const o = loaded.options[key];
+        if (!o) {
+            warns.push('pretask ' + (p.name ?? p.exec) + ' 引用了未定义的 option ' + key + '，未写入末位 JSON');
+            continue;
+        }
+        /* 适用性过滤：不满足当前 controller / resource 的 option 不进这个对象 */
+        if (o.controller?.length && ctx.controllerName && !o.controller.includes(ctx.controllerName))
+            continue;
+        if (o.resource?.length && ctx.resourceName && !o.resource.includes(ctx.resourceName))
+            continue;
+        const v = resolveOptionValue(o, ctx.valueCtx);
+        if (!v)
+            continue;
+        if (v.kind === 'fields') {
+            json[key] = v.fields;
+            continue;
+        }
+        /* case 型取值要校验：写一个不存在的 case 名进 JSON，脚本会按错的配置跑而不报错 */
+        const known = o.type === 'checkbox' ? v.cases : [v.cases[0]];
+        const bad = known.filter((c) => !o.cases.some((x) => x.name === c));
+        if (bad.length) {
+            warns.push('pretask ' + (p.name ?? p.exec) + ' 的 option ' + key + ' 取值 ' + bad.join(' / ') + ' 不是已声明的 case，未写入末位 JSON');
+            continue;
+        }
+        json[key] = o.type === 'checkbox' ? v.cases : v.cases[0];
+    }
+    const argv = [p.exec, ...p.args, ...(Object.keys(json).length ? [JSON.stringify(json)] : [])];
+    return { argv, warns };
+}
+/** pretask 超时缺省 120s：够"启动模拟器到可连"的常态，又兜住真正挂死的脚本。 */
+export const PRETASK_TIMEOUT_MS = 120000;
+function pretaskTimeoutMs() {
+    const raw = process.env.MAAFW_PRETASK_TIMEOUT_MS;
+    if (raw === undefined)
+        return PRETASK_TIMEOUT_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : PRETASK_TIMEOUT_MS;
+}
+/** 进程树杀：pretask 常是"拉起模拟器"的壳脚本，只杀头部会留孙代占设备。 */
+function killTree(child) {
+    const pid = child.pid;
+    if (pid === undefined) {
+        try {
+            child.kill();
+        }
+        catch { /* ignore */ }
+        return;
+    }
+    if (process.platform === 'win32') {
+        try {
+            spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { timeout: 5000 });
+        }
+        catch { /* ignore */ }
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * 执行一条 pretask；timeoutMs<=0 不限时。
+ * Windows 的 .cmd/.bat 必须过 cmd.exe（CreateProcess 只认 exe；不带 shell 的 spawn 同步抛
+ * EINVAL，原实现却提示"检查 PATH"——把用户往完全错的方向带）。args 逐元素传给 cmd.exe：
+ * Node 会自己做 cmd 元字符转义，不经 shell:true（那个走全串拼接，空格参数必坏）。
+ */
+function spawnOnce(exe, args, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        let tail = '';
+        let settled = false;
+        const done = (r) => {
+            if (!settled) {
+                settled = true;
+                resolve(r);
+            }
+        };
+        const isBatch = process.platform === 'win32' && /\.(cmd|bat)$/i.test(exe);
+        const realExe = isBatch ? 'cmd.exe' : exe;
+        const realArgs = isBatch ? ['/d', '/s', '/c', exe, ...args] : args;
+        let child;
+        try {
+            child = spawn(realExe, realArgs, {
+                cwd: cwd ?? undefined, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true,
+                /* POSIX 单独成组，超时才能 -pid 收整棵树；Windows 不靠 detached（它另有语义），taskkill /T 收。 */
+                ...(isBatch || process.platform === 'win32' ? {} : { detached: true }),
+            });
+        }
+        catch (e) {
+            done({ code: null, signal: null, tail: '', error: String(e.message || e) });
+            return;
+        }
+        const feed = (b) => { tail = (tail + String(b)).slice(-TAIL_LIMIT); };
+        child.stdout?.on('data', feed);
+        child.stderr?.on('data', feed);
+        child.on('error', (e) => done({ code: null, signal: null, tail, error: e.message }));
+        child.on('exit', (code, signal) => done({ code, signal, tail }));
+        if (timeoutMs > 0) {
+            const timer = setTimeout(() => {
+                killTree(child);
+                done({ code: null, signal: null, tail, timedOut: true });
+            }, timeoutMs);
+            timer.unref?.();
+        }
+    });
+}
+/**
+ * 按声明序执行全部适用的 pretask。任一条失败即返回 ok:false（调用方据此中止连接）。
+ * 不抛异常：失败是一种结果，由调用方决定怎么呈现。
+ */
+export async function runPretasks(input) {
+    const { loaded } = input;
+    const ran = [];
+    const skipped = [];
+    const notes = [];
+    const warns = [];
+    const valueCtx = {
+        ...(input.optionCases ? { optionCases: input.optionCases } : {}),
+        ...(input.optionFields ? { optionFields: input.optionFields } : {}),
+    };
+    for (const p of loaded.pretask ?? []) {
+        const label = p.name ?? p.exec;
+        if (p.controller?.length && input.controllerName && !p.controller.includes(input.controllerName)) {
+            skipped.push(label + '（声明只适用于控制器 ' + p.controller.join(' / ') + '）');
+            continue;
+        }
+        if (p.resource?.length && input.resourceName && !p.resource.includes(input.resourceName)) {
+            skipped.push(label + '（声明只适用于资源 ' + p.resource.join(' / ') + '）');
+            continue;
+        }
+        const built = buildPretaskArgv(p, loaded, {
+            controllerName: input.controllerName,
+            resourceName: input.resourceName,
+            valueCtx,
+        });
+        warns.push(...built.warns);
+        const [exe, ...args] = built.argv;
+        const started = Date.now();
+        const r = await spawnOnce(exe, args, loaded.dir, input.timeoutMs ?? pretaskTimeoutMs());
+        const outcome = {
+            name: label, exec: exe, argv: built.argv, code: r.code, signal: r.signal, ms: Date.now() - started, tail: r.tail,
+        };
+        ran.push(outcome);
+        if (r.error) {
+            return {
+                ok: false, ran, skipped, notes, warns,
+                error: {
+                    code: 'PRETASK_SPAWN',
+                    message: 'pretask ' + label + ' 启动失败：' + r.error,
+                    hint: '检查 exec 是否在 PATH 里（协议的 exec 不走 shell，不能写管道/重定向）',
+                },
+            };
+        }
+        if (r.timedOut) {
+            return {
+                ok: false, ran, skipped, notes, warns,
+                error: {
+                    code: 'PRETASK_TIMEOUT',
+                    message: 'pretask ' + label + ' 超时（' + (input.timeoutMs ?? pretaskTimeoutMs()) + 'ms）已树杀，本次启动中止',
+                    hint: (r.tail ? '子进程输出尾部：\n' + r.tail + '\n' : '') +
+                        '启动模拟器类脚本确实需要更久时，用 MAAFW_PRETASK_TIMEOUT_MS 放宽（毫秒），不是去掉超时',
+                },
+            };
+        }
+        if (r.code !== 0) {
+            return {
+                ok: false, ran, skipped, notes, warns,
+                error: {
+                    code: 'PRETASK_FAILED',
+                    message: 'pretask ' + label + ' 以 ' + (r.signal ? '信号 ' + r.signal : '退出码 ' + r.code) +
+                        ' 结束，本次启动中止（PI 契约：非零退出即中止）',
+                    ...(r.tail ? { hint: '子进程输出尾部：\n' + r.tail } : {}),
+                },
+            };
+        }
+        notes.push('pretask 已执行：' + label + '（' + outcome.ms + 'ms）');
+    }
+    if (skipped.length)
+        notes.push('跳过 ' + skipped.length + ' 条 pretask：' + skipped.join('；'));
+    return { ok: true, ran, skipped, notes, warns };
+}
+//# sourceMappingURL=pretask.js.map

package/lib/runtime/prune.js

@@ -0,0 +1,28 @@
+/**
+ * 落盘目录的保留上限（runs/、png/ 共用）：按 mtime 留最新 keep 个，删其余。
+ * 背景：~/.maafw-live 下这些目录以前没有上限——回执与截图只进不出，
+ * 用久了会无声膨胀（实测 runs/ 44 个、frames 15MB）。修剪失败不抛：
+ * 落盘/清理从来不是任务结论，最坏是目录多留几个。
+ *
+ * 只删 suffix 匹配的文件，不碰目录与其他扩展名；目录本身不存在时直接返回。
+ * daemon 侧（framed.mjs）的 out/ 有同逻辑的内联副本——它自包含、不能 import lib。
+ */
+import { readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+export function pruneDir(dir, opts) {
+    try {
+        const suffix = opts.suffix ?? '';
+        const names = readdirSync(dir)
+            .filter((n) => n.endsWith(suffix))
+            .map((n) => ({ n, t: statSync(join(dir, n)).mtimeMs }))
+            .sort((a, b) => b.t - a.t); /* 新的在前 */
+        for (const f of names.slice(Math.max(0, opts.keep))) {
+            try {
+                unlinkSync(join(dir, f.n));
+            }
+            catch { /* 单个删不掉就留 */ }
+        }
+    }
+    catch { /* 目录不存在/读不了：按没有要清的看 */ }
+}
+//# sourceMappingURL=prune.js.map

package/lib/runtime/receipts.js

@@ -0,0 +1,57 @@
+/**
+ * run 回执落盘（repl 与一次性 CLI 共用）：W1 runs 存储的种子。
+ *
+ * 目录默认 `~/.maafw-live/runs/`，可用 `MAAFW_LIVE_RUNS_DIR` 覆盖——
+ * 单测必须指向临时目录，不许往真实 home 写桩数据（2026-10-26 实测污染过一轮）。
+ * 落盘失败不属于任务结论：返回体没有 path 时，调用方自行退化（如打印完整 JSON）。
+ *
+ * 文件名带完整毫秒时间戳，且**独占创建**（flag 'wx'）：回执是"当时只能观测一次"的证据，
+ * 被后来的同名写入静默覆盖就等于丢证据——所以撞名不覆盖，改为加序号重试。
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { pruneDir } from './prune.js';
+/** 保留上限：回执是"一次性观测"的证据，留够回看的就够，不让它无声膨胀。 */
+const RUNS_KEEP = 50;
+export function runsDir() {
+    const override = process.env.MAAFW_LIVE_RUNS_DIR;
+    return override && override !== '' ? override : join(homedir(), '.maafw-live', 'runs');
+}
+/** 回执文件名：`run-<ISO 时间戳去分隔符>-<entry>.json`（时间戳保留到毫秒，含 Z 时区标记）。
+ *  `now` 可注入：单测据此制造"同一毫秒撞名"，不必靠 sleep。 */
+export function receiptFileName(entry, now = new Date()) {
+    const stamp = now.toISOString().replace(/[-:.]/g, '');
+    const safeEntry = entry.replace(/[\\/:*?"<>|\s]+/g, '_');
+    return 'run-' + stamp + '-' + safeEntry + '.json';
+}
+/** 同一毫秒内最多重试到这个序号（撞名说明并发落盘，实际不会逼近这个量级） */
+const MAX_SAME_NAME = 100;
+export function writeRunReceipt(record, entry, now = new Date()) {
+    try {
+        const dir = runsDir();
+        mkdirSync(dir, { recursive: true });
+        const base = receiptFileName(entry, now);
+        const body = JSON.stringify(record, null, 2) + '\n';
+        for (let n = 0; n < MAX_SAME_NAME; n++) {
+            const name = n === 0 ? base : base.replace(/\.json$/, '-' + n + '.json');
+            const path = join(dir, name);
+            try {
+                writeFileSync(path, body, { flag: 'wx' });
+                pruneDir(dir, { keep: RUNS_KEEP, suffix: '.json' });
+                return { path };
+            }
+            catch (e) {
+                /* 撞名是"已有同名回执"，换序号重试；别的 IO 错误按落盘失败处理 */
+                if (e.code !== 'EEXIST')
+                    throw e;
+            }
+        }
+        return {};
+    }
+    catch {
+        /* 落盘失败：调用方按"没有 path"退化，不吞任务结论 */
+        return {};
+    }
+}
+//# sourceMappingURL=receipts.js.map

package/lib/runtime/reco-args.js

@@ -0,0 +1,38 @@
+/**
+ * reco 参数面的共享判据：**roi 空间**校验。
+ *
+ * 为什么单独立一个文件：repl 与一次性 CLI 都要能给「roi 越出所用图像尺寸」下一个明确结论，
+ * 判据必须只有一份 —— 两处各写一遍，迟早分叉成「CLI 报错、repl 静默」，而静默的正是最贵的那种
+ * （G16：ctrl 坐标的 roi 打在 L1 小图上 → `results: []`，看起来像"模板没读到"）。
+ */
+/**
+ * roi（控制器/图像空间）是否越出图像尺寸。越界就是**参数用错空间**，不是"没识别到"：
+ * 边界相等不算越界（`x+w === w` 是贴右边）。
+ *
+ * **左上边界同样要判**：负坐标是最典型的"空间算错"（L1↔ctrl 换算时先减了偏移），
+ * 而它只比右下是看不出来的（`[-50,200,80,300]` 的右下 = 30/500，落在画面里）。
+ * 漏判的代价正是本判据要防的那件事：回落到"静默未中 + 指向模板/资源"。
+ *
+ * 返回 null 表示在界内或无法判定（缺尺寸）。
+ */
+export function roiOutOfBounds(roi, w, h) {
+    if (!roi || roi.length !== 4)
+        return null;
+    const iw = Number(w);
+    const ih = Number(h);
+    if (!Number.isFinite(iw) || !Number.isFinite(ih) || iw <= 0 || ih <= 0)
+        return null;
+    const [x, y, rw, rh] = roi;
+    const right = x + rw;
+    const bottom = y + rh;
+    if (x >= 0 && y >= 0 && right <= iw && bottom <= ih)
+        return null;
+    const where = (x < 0 || y < 0)
+        ? '（左上 ' + x + ',' + y + ' 为负' + (right > iw || bottom > ih ? '，且右 ' + right + ' / 下 ' + bottom + ' 超出' : '') + '）'
+        : '（右 ' + right + ' / 下 ' + bottom + '）';
+    return 'roi 越出图像：roi=' + roi.join(',') + where
+        + ' 超出图像尺寸 ' + iw + 'x' + ih
+        + ' —— 这是**参数用错空间**（roi 按图像像素给；负值多半是换算时先减了偏移），不是识别未命中；'
+        + '控制器的 roi 要按所用图的尺寸换算（L1 小图 vs 控制器原图差一个 scale）';
+}
+//# sourceMappingURL=reco-args.js.map

package/lib/runtime/reco-verdict.js

@@ -0,0 +1,82 @@
+/**
+ * 识别未命中的原因与计数：**只有这一份判据**，一次性 CLI 与 REPL 都读它。
+ *
+ * 为什么单独立文件：miss 的病因直接决定下一步查什么（roi 里没有字 / expected 过滤掉了 /
+ * 分数不够 / 模板根本读不到），两个壳各推一遍必然分叉，而分叉的代价是把"expected 不匹配"
+ * 当成"模板读不到"去翻资源目录。
+ *
+ * 名字按**算法**分开给，不共用一套 OCR 口径：OCR 没有阈值这回事，模板匹配也没有 `expected`
+ * 这回事——共用口径就会编出不存在的病因。表以外的算法不猜，如实不给原因。
+ *
+ * OCR 的空结果还有一个同形病因：**模型没加载时框架不报错，只回空结果**。这条不在本文件的
+ * 职责内（要查文件系统），由调用方用 `runtime/ocr-model` 判好、以 `options.ocrModel` 传进来。
+ *
+ * 派生的前提是**先看 hit**：`noConfidence` 旧式判据（`threshold 建议为 null`）在 OCR 命中时
+ * 也成立（OCR 无数值分），不看 `ok` 就会把命中标成"无置信度"。
+ */
+function innerDetail(detail) {
+    const outer = detail;
+    const inner = outer && typeof outer === 'object' ? outer.detail : undefined;
+    return inner && typeof inner === 'object' ? inner : null;
+}
+function countOf(v) {
+    return Array.isArray(v) ? v.length : null;
+}
+function reasonFor(hit, type, rawCount, scores, ocrModel, failure) {
+    if (hit)
+        return null;
+    /* 调用本身报错（detail 为 null）优先于一切算法口径：这不是"未命中"，别按未命中解释 */
+    if (failure !== null)
+        return '识别调用报错：' + failure;
+    if (type === 'OCR') {
+        if (rawCount === 0) {
+            /* 模型没加载时框架不报错，只回空结果——与"roi 里没有字"同形，先排前者 */
+            if (ocrModel === 'missing')
+                return 'OCR 模型不在资源链里（model/ocr 需 det.onnx + rec.onnx + keys.txt）';
+            return 'roi 内无文字';
+        }
+        if (rawCount !== null && rawCount > 0)
+            return 'expected 无匹配';
+        return null;
+    }
+    if (type === 'TemplateMatch') {
+        if (scores === null)
+            return '识别未返回任何置信度（模板/资源读不到）';
+        if (scores.lowMatch)
+            return '模板与画面不匹配（最高置信度 ' + scores.bestScore + '）';
+        return '低于阈值（最高置信度 ' + scores.bestScore + '）';
+    }
+    return null;
+}
+export function describeMisses(results, type, scores, options = {}) {
+    const perResult = results.map((r) => {
+        const inner = innerDetail(r.detail);
+        const rawCount = countOf(inner?.all);
+        const filteredCount = countOf(inner?.filtered);
+        /* detail 缺失 = 子进程捕获到异常（正常 miss 时框架仍回 detail 对象）。异常文本直接给人看，
+         * 但截断：它是框架的原生消息，可能很长。 */
+        const hasDetail = r.detail !== null && typeof r.detail === 'object';
+        const errText = typeof r.error === 'string' && r.error.trim() !== '' ? r.error.trim() : null;
+        const failure = hasDetail ? null : (errText ?? '未返回 detail（调用失败）');
+        return {
+            missReason: reasonFor(r.ok === true, type, rawCount, scores, options.ocrModel, failure && failure.length > 160 ? failure.slice(0, 160) + ' …' : failure),
+            rawCount,
+            filteredCount,
+            failed: failure !== null && r.ok !== true,
+        };
+    });
+    const reasons = [];
+    for (const p of perResult) {
+        if (p.missReason && !reasons.includes(p.missReason))
+            reasons.push(p.missReason);
+    }
+    const single = results.length === 1 ? perResult[0] : undefined;
+    return {
+        missReason: reasons.length === 1 ? reasons[0] : null,
+        missReasons: reasons,
+        rawCount: single ? single.rawCount : null,
+        filteredCount: single ? single.filteredCount : null,
+        perResult,
+    };
+}
+//# sourceMappingURL=reco-verdict.js.map

package/lib/runtime/roi-compare.js

@@ -0,0 +1,198 @@
+/**
+ * 候选集合比较的判据内核：**给定外来目标 + 一组位置假设 → 排序表 + bestGap + 并列带 + 三态结论**。
+ *
+ * 为什么把它从 `roi-check` 里拆出来：旧形态把候选写死成"沿 x 偏移 ±pitch/2"——y 从不偏移，
+ * 还要求你先知道周期。而真实棋盘的行距 ≠ 列距、列距本身也逐行不同（单一标量周期不成立），
+ * 所以"半周期关系"只是近似。判据的正确形状是**候选集合比较**：候选从哪来（显式全套 / 相对平移 /
+ * 发现模式）是调用方的事，这里只负责"生成 → 逐个取分 → 排序 → 下结论"。
+ *
+ * 三条不许动的性质：
+ *  1. **没有证据 ≠ 0 分**：`score: null` 的候选不进 `ranked`（没有分数就没有名次），也不许被当成
+ *     垫底来"把最优衬托成唯一"；
+ *  2. **`bestGap` 无上限地照给**：永远报第 1 与第 2 名的真实分差，不做阈值截断——
+ *     只报"带内"的差值等于把"差多少"这件事藏起来；
+ *  3. **顺序可追溯**：候选带 `origin`（输入列表下标），排序稳定（同分按 origin），
+ *     于是输出能被还原回输入，而不是"看起来像排序过"。
+ *
+ * 纯函数、不碰 IO、不碰协议：退出码与文案归命令层。
+ */
+import { roiOutOfBounds } from './reco-args.js';
+/** 允许说"分不出来"的并列带宽度：最优与次优分差小于它就不下结论。 */
+export const DEFAULT_GAP = 0.15;
+const round3 = (n) => Math.round(n * 1000) / 1000;
+function finiteRoi(value) {
+    if (!Array.isArray(value) || value.length !== 4)
+        return null;
+    const roi = value.map(Number);
+    return roi.every((n) => Number.isFinite(n)) ? roi : null;
+}
+/** 唯一的越界口径：一律走 `roiOutOfBounds`（它连左上负坐标一起判）。 */
+function collect(raw, size) {
+    const candidates = [];
+    const skipped = [];
+    for (const e of raw) {
+        if (!e.roi) {
+            skipped.push({ roi: e.echo, origin: e.origin, reason: '不是 4 个有限数字，无法当 roi' });
+            continue;
+        }
+        const oob = roiOutOfBounds(e.roi, size?.w, size?.h);
+        if (oob) {
+            skipped.push({ roi: e.roi, origin: e.origin, reason: oob });
+            continue;
+        }
+        candidates.push({ roi: e.roi, origin: e.origin });
+    }
+    return { candidates, skipped };
+}
+/** 显式全套：每个元素就是 `[x,y,w,h]`。位置假设已经知道时用这条（**没有周期假设**）。 */
+export function fromRois(rois, size) {
+    return collect(rois.map((r, origin) => ({
+        roi: finiteRoi(r),
+        echo: Array.isArray(r) ? r.map(Number) : [],
+        origin,
+    })), size);
+}
+/** 相对一个基准位置的平移：x / y 分量都允许，列表允许非均匀（逐行不同的列距照样能表达）。 */
+export function fromOffsets(offsets, base, size) {
+    return collect(offsets.map((o, origin) => {
+        const roi = [base[0] + o.dx, base[1] + o.dy, base[2], base[3]];
+        return { roi: finiteRoi(roi), echo: roi, origin };
+    }), size);
+}
+/** 一个轴的取值列表（单点恒为 1 个值）。 */
+export function axisValues(axis) {
+    if (!axis)
+        return [0];
+    const step = Number.isFinite(axis.step) && axis.step > 0 ? axis.step : 1;
+    const out = [];
+    for (let v = axis.from; v <= axis.to + 1e-9; v += step)
+        out.push(round3(v));
+    return out;
+}
+export function scanInfo(spec) {
+    return {
+        dx: spec.dx ?? null,
+        dy: spec.dy ?? null,
+        count: axisValues(spec.dx).length * axisValues(spec.dy).length,
+    };
+}
+/** 发现模式：笛卡尔积 dx × dy 全部落在**同一个基准 roi** 上（不是判据，见命令层文案）。 */
+export function fromScan(spec, base, size) {
+    const xs = axisValues(spec.dx);
+    const ys = axisValues(spec.dy);
+    const raw = [];
+    let origin = 0;
+    for (const dx of xs) {
+        for (const dy of ys) {
+            const roi = [base[0] + dx, base[1] + dy, base[2], base[3]];
+            raw.push({ roi: finiteRoi(roi), echo: roi, origin: origin++ });
+        }
+    }
+    return collect(raw, size);
+}
+/**
+ * `--scan` 语法解析：`dx=-160..160/8,dy=0`（逗号分段，轴是 dx / dy，值是 `<n>` 或 `<from>..<to>/<step>`）。
+ *
+ * 范围**必须带步长**：候选数是 (to−from)/step 线性增长、而耗时按候选数线性增长，
+ * 缺省步长等于让一次手滑变成几百个候选。
+ */
+export function parseScan(raw) {
+    const spec = {};
+    for (const part of String(raw).split(',')) {
+        const seg = part.trim();
+        if (!seg)
+            continue;
+        const eq = seg.indexOf('=');
+        if (eq < 0)
+            return { error: '--scan 每段要写成 <轴>=<值>：' + seg + '（形如 dx=-160..160/8,dy=0）' };
+        const axis = seg.slice(0, eq).trim();
+        if (axis !== 'dx' && axis !== 'dy')
+            return { error: '--scan 只认识 dx / dy 两个轴，不认识：' + seg };
+        const body = seg.slice(eq + 1).trim();
+        const m = /^(-?\d+(?:\.\d+)?)(?:\.\.(-?\d+(?:\.\d+)?)(?:\/(\d+(?:\.\d+)?))?)?$/.exec(body);
+        if (!m)
+            return { error: '--scan 的值要写成 <n> 或 <from>..<to>/<step>：' + seg };
+        const from = Number(m[1]);
+        if (m[2] === undefined) {
+            spec[axis] = { from, to: from, step: 1 };
+            continue;
+        }
+        if (m[3] === undefined) {
+            return { error: '--scan 的范围要给步长（' + seg + ' 应写成 ' + body + '/<step>）：耗时随候选数线性增长，缺步长会让候选数失控' };
+        }
+        const to = Number(m[2]);
+        const step = Number(m[3]);
+        if (!(step > 0))
+            return { error: '--scan 的步长要正数：' + seg };
+        if (to < from)
+            return { error: '--scan 的区间为空（from > to）：' + seg };
+        spec[axis] = { from, to, step };
+    }
+    if (spec.dx === undefined && spec.dy === undefined) {
+        return { error: '--scan 至少要给一个轴：dx=… 或 dy=…' };
+    }
+    return { value: spec };
+}
+export function sampleOf(result) {
+    const inner = result?.detail?.detail;
+    const best = inner?.best?.score;
+    const boxes = (inner?.all ?? [])
+        .map((x) => Number(x.score))
+        .filter((n) => Number.isFinite(n))
+        .concat(Number.isFinite(Number(best)) ? [Number(best)] : []);
+    const box = inner?.best?.box;
+    return {
+        score: boxes.length ? Math.max(...boxes) : null,
+        ok: result?.ok === true,
+        box: Array.isArray(box) ? box : [],
+    };
+}
+/**
+ * 三态判据。优先序（**别重排**）：**先把没有证据的候选剔除，再谈歧义**——
+ *  ① 可评估候选 0 个 → 未命中；② 最优未过 threshold → 未命中；
+ *  ③ 与最优并列（|Δ| < gap）的 ≥ 2 → AMBIGUOUS；④ 否则唯一最优。
+ *
+ * "剔除"以**输出形状**兑现：`score: null` 的候选**不在 `ranked` 里**——没有分数就没有名次，
+ * 也进不了并列带（"没有证据"既不是 0 分，也不许被当成垫底来把最优衬托成唯一）。
+ * 剩下有证据的那些谁更优，才是这里回答的问题；"还有候选没被评估过"由调用方写进退出码（3）
+ * 与逐例回执，不改变这里的结论——一次 41 点的扫描里，落在背景上的点本来就拿不到相关系数
+ * （实测 `all: []`），把它们算成"分不出来"会淹没真正的信号。
+ */
+export function aggregate(items, options = {}) {
+    const gap = options.gap ?? DEFAULT_GAP;
+    const threshold = options.threshold;
+    const byScore = items
+        .filter((x) => x.score !== null)
+        .sort((a, b) => (b.score - a.score) || (a.origin - b.origin));
+    const best = byScore.length ? byScore[0].score : null;
+    const second = byScore.length > 1 ? byScore[1].score : null;
+    const bestGap = best !== null && second !== null ? round3(best - second) : null;
+    const band = best === null ? [] : byScore.filter((x) => best - x.score < gap);
+    const withinGap = band.map((_, i) => i + 1);
+    const ranked = byScore.map((x, i) => ({
+        ...x,
+        rank: i + 1,
+        inBand: i < band.length,
+    }));
+    let verdict = 'MISS';
+    let reason = 'no-candidates';
+    if (items.length === 0) {
+        reason = 'no-candidates';
+    }
+    else if (!byScore.length) {
+        reason = 'no-evidence';
+    }
+    else if (threshold !== undefined && best < threshold) {
+        reason = 'below-threshold';
+    }
+    else if (band.length >= 2) {
+        verdict = 'AMBIGUOUS';
+        reason = 'ambiguous';
+    }
+    else {
+        verdict = 'HIT';
+        reason = 'unique';
+    }
+    return { ranked, bestGap, gap, withinGap, verdict, reason };
+}
+//# sourceMappingURL=roi-compare.js.map