@windsland52/maafw-live 0.0.0-stage → 0.4.0

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

package/lib/runtime/session-forward.js

@@ -0,0 +1,79 @@
+/**
+ * `--session <name>` 转发：一次性 CLI 把 argv 送进命名会话的常驻进程执行。
+ *
+ * 为什么命令自己不用关心：转发发生在命令分发**之前**（index.ts 的拦截），命令拿到的
+ * 是会话侧 dispatchArgv 注入 client 后跑出来的同一个 CommandResult——信封、退出码、
+ * data 与直接执行同形（设计审查 P0-3 L2）。
+ *
+ * 死会话自愈：meta 在但 pid 已死时，用 meta.connectArgs 原样重起（连接参数在
+ * 起会话时就存了），调用方不必记得这条会话当初怎么连的。
+ */
+import { cliPackage } from '../pkg.js';
+import { pidAlive, readSessionMeta, sendToSessionExec, sessionServeLogTail, spawnSessionServer, stopSession, waitPipeReady, } from './session-ipc.js';
+import { EXIT, fail } from '../protocol.js';
+const FORWARD_TIMEOUT_MS = 600_000;
+/**
+ * 从命令行 argv（含命令名）剥掉 `--session` 旗标本体，剩下的就是要送去会话执行的命令。
+ */
+export function stripSessionFlag(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const t = argv[i];
+        if (t === '--session') {
+            i++;
+            continue;
+        }
+        if (t.startsWith('--session='))
+            continue;
+        out.push(t);
+    }
+    return out;
+}
+/**
+ * 转发一条命令到命名会话。返回的 CommandResult 就当作本命令的结果——
+ * 调用方（index.ts）直接 emit，不再二次加工。
+ */
+export async function forwardToSession(name, argv) {
+    let meta = readSessionMeta(name);
+    if (!meta) {
+        return fail('SESSION_NOT_FOUND', `会话 '${name}' 不存在（没有 meta）`, `先起会话：maafw-live repl --session ${name} --project <dir>（或 --kind win32 --target <title>）`, EXIT.USAGE);
+    }
+    if (!pidAlive(meta.pid)) {
+        /* 死会话自愈：清掉残留后用 meta 里存的连接参数原样重起 */
+        const savedArgs = meta.connectArgs;
+        stopSession(name);
+        meta = spawnSessionServer(name, process.argv[1] ?? '', savedArgs);
+        const ready = await waitPipeReady(meta.pipe, 20000);
+        if (!ready) {
+            const tail = sessionServeLogTail(name);
+            stopSession(name);
+            return fail('SESSION_NOT_READY', `会话 '${name}' 已死且自动重起失败：管道 ${meta.pipe} 20s 内不可连`, (tail.length ? '常驻进程日志尾部：\n    ' + tail.join('\n    ') : '重起参数 ' + JSON.stringify(savedArgs)), EXIT.FAIL);
+        }
+    }
+    try {
+        const rep = await sendToSessionExec(meta, argv, FORWARD_TIMEOUT_MS);
+        if (rep.result) {
+            /* rep.lines = 待认领输出（异步收尾、连接横幅）+ 本命令 human。直接当 human 用：
+             * 比只看 result.human 多了异步尾巴，与非转发形态观感一致。 */
+            if (rep.lines.length)
+                rep.result.human = rep.lines;
+            /* 混版可见：meta 里记了起会话的 CLI 版本——npm test / npm install 升级后老会话仍跑
+             * 旧 lib，行为会漂；不硬断（旧会话仍能服务），只在 human 里留一行让人查得到。 */
+            const running = cliPackage().version;
+            if (meta.cliVersion && meta.cliVersion !== running) {
+                rep.result.human = [
+                    '⚠ 会话 ' + JSON.stringify(name) + ' 由 maafw-live ' + meta.cliVersion + ' 起，' +
+                        '当前 CLI 是 ' + running + '——行为可能已漂移（--session-stop ' + name + ' 后重连可拿到新代码）',
+                    ...(rep.result.human ?? []),
+                ];
+            }
+            return rep.result;
+        }
+        /* exec 回执却没有 result：常驻进程版本过旧（起会话用的还是旧包），让它明说怎么修 */
+        return fail('SESSION_REPLY', `会话 '${name}' 的回执里没有结构化结果（常驻进程是旧版本起的）`, `maafw-live repl --session-stop ${name} 后重试`, EXIT.FAIL);
+    }
+    catch (e) {
+        return fail('SESSION_IO', `会话 '${name}' 不可达：${e instanceof Error ? e.message : String(e)}`, `用 maafw-live repl --session-status ${name} 查状态；死了会自动重起`, EXIT.FAIL);
+    }
+}
+//# sourceMappingURL=session-forward.js.map