@windsland52/maafw-live 0.0.0-stage → 0.4.0

package/lib/runtime/ocr-model.js

@@ -0,0 +1,45 @@
+/**
+ * OCR 模型是否在资源链里：只回答"链上有没有框架会去读的那几个文件"。
+ *
+ * 为什么需要它：OCR 的 miss 与模板匹配不同——**模型没加载时框架不报错**，只回一个空结果
+ * （`detail.all: []`、`hit:false`、约 200ms），与"roi 里真的没有字"完全同形（实测：一个不带
+ * `model/` 的资源目录跑 `--type OCR` 就是这个签名）。不做这条判断，`describeMisses` 会把
+ * "没加载 OCR 模型"报成"roi 内无文字"——正是本提案要清掉的那类误诊。
+ *
+ * 依据（MaaFramework 5.11.2 pinned source；本机运行时 5.14.2，相差一个小版本，
+ * 相关实现见 `Resource/ResourceMgr.cpp::load_bundle` 与 `Resource/OCRResMgr.cpp`
+ * 的 `lazy_load` / `load_deter` / `load_recer`）：
+ *  - `load_bundle` 对每个 bundle 调一次 `lazy_load(<bundle>/model/ocr)`，把该目录登记进
+ *    roots 列表（后加载的在后），目录不存在就不登记；
+ *  - `load_deter(name)` 遍历 roots，取第一个存在 `<root>/<name>/det.onnx` 的 root；
+ *    `load_recer(name)` 遍历 roots，取第一个 `<root>/<name>/rec.onnx` 与
+ *    `<root>/<name>/keys.txt` **同时**存在的 root；
+ *  - `load_ocrer(name)` 要求 deter 与 recer 都拿到，所以判据是**合并**的：det 与 rec 允许
+ *    来自不同 root（base 放 det、overlay 放 rec+keys 是齐的），但 rec 与 keys 必须同属一个
+ *    root——它们是 load_recer 同一次调用里的两项，不会被拆开拼；
+ *  - `<name>` 来自节点参数 `model`，缺省空串 = 直接放在 `model/ocr/` 下；
+ *  - 缺任一项 → 拿不到 ocrer，`OCRer::predict` 只是记日志并回空结果，**不抛错**。
+ *
+ * 因此这里不能把"某一段目录三件套齐全"当判据：那会把"det 在 base、rec+keys 在 overlay"
+ * 误报成 missing，而它其实完全可用——误报会把人引去补模型，真正该看的 roi 反而被略过。
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const DET = 'det.onnx';
+/** recer 的两项必须同目录同时存在：对应 `load_recer` 同一次调用里的两个文件。 */
+const RECER = ['rec.onnx', 'keys.txt'];
+/**
+ * 资源链上是否能找到 OCR 模型。`modelName` 是节点/参数里声明的模型名（缺省空串）。
+ *
+ * 只查文件存在性、不解析 onnx：判断的是"框架会不会找到它"，不是"模型能不能跑"。
+ * 按框架的合并规则判：det 与 rec 可以来自不同段，rec 与 keys 必须同段。
+ */
+export function ocrModelStatus(resourceDirs, modelName) {
+    const name = typeof modelName === 'string' ? modelName.trim() : '';
+    // 每段一个候选目录，顺序与框架扫 roots 的顺序一致（这里不需要顺序，只在同段内成组）。
+    const folders = resourceDirs.map((dir) => name === '' ? join(dir, 'model', 'ocr') : join(dir, 'model', 'ocr', name));
+    if (!folders.some((folder) => existsSync(join(folder, DET))))
+        return 'missing';
+    return folders.some((folder) => RECER.every((f) => existsSync(join(folder, f)))) ? 'present' : 'missing';
+}
+//# sourceMappingURL=ocr-model.js.map

package/lib/runtime/pi-env.js

@@ -0,0 +1,34 @@
+import { cliPackage, maaNodeVersion } from '../pkg.js';
+/**
+ * 本工具**实际兑现**的 PI 能力版本。
+ *
+ * 不写"最新"：这个值给 agent 判特性用，谎报会让它以为没实现的行为存在。
+ * 当前兑现到 v2.7.0：option 四级链 / preset / import / `attach_resource_path` /
+ * option 适用性过滤 / `resource.hash` 完整性校验（v2.6，warn-only）/ pretask（v2.7）。
+ */
+const PI_INTERFACE_VERSION = 'v2.7.0';
+/** 本 CLI 的人类输出固定中文、没有 UI 语言切换——按协议示例的 `zh_cn` 形态如实报。 */
+const PI_CLIENT_LANGUAGE = 'zh_cn';
+/** 生成要注入 agent 子进程的环境变量；返回空对象表示本次没有可注入的项。 */
+export function buildAgentEnv(i) {
+    const env = {
+        PI_INTERFACE_VERSION,
+        PI_CLIENT_NAME: 'maafw-live',
+        PI_CLIENT_VERSION: cliPackage().version,
+        PI_CLIENT_LANGUAGE,
+    };
+    const maafw = maaNodeVersion();
+    if (maafw)
+        env.PI_CLIENT_MAAFW_VERSION = maafw;
+    /* 顶层 version 是**项目**版本（不是 interface_version=2） */
+    if (i.loaded.projectVersion)
+        env.PI_VERSION = i.loaded.projectVersion;
+    const c = i.controllerName ? i.loaded.controllers.find((x) => x.name === i.controllerName) : undefined;
+    if (c && c.raw !== undefined)
+        env.PI_CONTROLLER = JSON.stringify(c.raw);
+    const r = i.resourceName ? i.loaded.resources.find((x) => x.name === i.resourceName) : undefined;
+    if (r && r.raw !== undefined)
+        env.PI_RESOURCE = JSON.stringify(r.raw);
+    return env;
+}
+//# sourceMappingURL=pi-env.js.map

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