@windsland52/maafw-live 0.0.0-stage → 0.4.0

package/lib/commands/input.js

@@ -0,0 +1,257 @@
+/**
+ * 输入注入命令：click / swipe / key / text。
+ *
+ * 全部经 maafw 控制器本体注入（不直接调 adb），坐标是控制器分辨率空间——默认短边 720，
+ * 与 pipeline 里 roi / 模板图同一坐标系。要设备就必须给 --project（推荐）或 --kind。
+ */
+import { EXIT, fail } from '../protocol.js';
+import { input, withDaemon } from '../runtime/actions.js';
+import { describeSession, ensureSession } from '../runtime/session.js';
+import { CONNECT_OPTIONS, daemonFail, sessionOptions } from './runtime.js';
+function needSession(o, ctx) {
+    /* 会话侧（--session 转发 / REPL）ctx.client 已注入、设备已连，连接参数再强要 argv
+     * 会拒掉 `click x y --session <名>` 这种本来合法的用法。 */
+    if (ctx?.client)
+        return null;
+    if (!o.project && !o.kind) {
+        return fail('BAD_ARGUMENTS', '要设备才能注入输入：给 --project <dir>（推荐）或 --kind win32|adb|gamepad', 'CLI 不做连接持久化；多步操作用 maafw-live repl 连接一次后连续注入', EXIT.USAGE);
+    }
+    return null;
+}
+function num(values, key) {
+    const v = values[key];
+    if (typeof v === 'string' && v !== '') {
+        const n = Number(v);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+}
+async function inject(ctx, o, payload, human, timeoutMs = 20000, expectGuard = false) {
+    try {
+        return await withDaemon(ctx, async (client) => {
+            const s = await ensureSession(client, o);
+            const r = await input(client, payload, timeoutMs);
+            /* daemon 回执恒 ok:true 包 handler 返回值——"业务拒绝"（{ok:false,code,...}）落在 data，
+             * 不抛错。必须查 r.ok===false：帧身份守卫拒发就在这里，不能再走"已点击"成功路径。 */
+            if (r.ok === false) {
+                const msg = String(r.error ?? 'daemon 拒绝');
+                if (expectGuard && /帧身份守卫|EXPECT_FAILED/.test(msg + String(r.code ?? ''))) {
+                    return fail('EXPECT_FAILED', msg, '重看当前画面再点', EXIT.FINDINGS);
+                }
+                return fail(String(r.code ?? 'INPUT_REJECTED'), msg, undefined, EXIT.FINDINGS);
+            }
+            /* 动作回执帧（daemon 已落盘到 runDir/action-frames/）：一次性 CLI 下 seq 没有消费者
+             * （frame_get 不可达），路径才是能复核"动作前后"的东西。 */
+            const ret = (r.retention ?? {});
+            const files = [ret.before?.file, ret.after?.file].filter((f) => typeof f === 'string');
+            const evidence = files.length ? ['证据帧：' + files.join(' 、')] : [];
+            return { exitCode: EXIT.OK, human: [...describeSession(s, ctx.flags.verbose), ...human(r), ...evidence], data: r };
+        });
+    }
+    catch (e) {
+        /* 帧身份守卫拒发：daemon 回 ok:false 经 client.call 变 Error（只带 error 文本）。
+         * 用文本前缀识别——守卫错误都以"帧身份守卫"开头；落到 FINDINGS（画面已变是"发现"，不是崩）。 */
+        if (expectGuard && /帧身份守卫/.test(String(e?.message ?? e))) {
+            return fail('EXPECT_FAILED', String(e?.message ?? e), '重看当前画面再点', EXIT.FINDINGS);
+        }
+        return daemonFail(e);
+    }
+}
+export const clickCommand = {
+    name: 'click',
+    summary: '点击一个坐标（控制器分辨率空间，默认短边 720）',
+    usage: 'maafw-live click <x> <y> [--project <dir>|--kind ...] [--contact n] [--pressure n]\n' +
+        '       [--expect-seq N | --expect-frame <hash>]——帧身份守卫：画面已变则拒发输入（FINDINGS 退出）',
+    options: {
+        ...CONNECT_OPTIONS, contact: { type: 'string' }, pressure: { type: 'string' },
+        'expect-seq': { type: 'string' }, 'expect-frame': { type: 'string' },
+    },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const miss = needSession(o, ctx);
+        if (miss)
+            return miss;
+        const x = Number(ctx.positionals[0]);
+        const y = Number(ctx.positionals[1]);
+        if (!Number.isFinite(x) || !Number.isFinite(y)) {
+            return fail('BAD_ARGUMENTS', '用法：maafw-live click <x> <y>', undefined, EXIT.USAGE);
+        }
+        const expectSeq = num(ctx.values, 'expect-seq');
+        const expectFrame = typeof ctx.values['expect-frame'] === 'string' && ctx.values['expect-frame']
+            ? String(ctx.values['expect-frame']) : undefined;
+        /* 帧身份守卫在一次性 CLI 下必然失败：daemon 随命令死，seq 从 1 起——守卫核对的"当前帧"
+         * 只能是这一帧本身。要跨命令的帧身份得用常驻会话（maafw-live repl --session <名>，
+         * 会话侧注入 ctx.client，与 withDaemon 的新建路径区分开）。 */
+        if ((expectSeq !== undefined || expectFrame !== undefined) && ctx.client === undefined) {
+            return fail('EXPECT_FAILED', '帧身份守卫（--expect-seq / --expect-frame）需要常驻会话——一次性命令的 daemon 每条都重启，seq 从 1 起，守卫永远核不到你存的那帧。要跨命令核帧用：maafw-live repl --session <名> --cmd "click x y --expect-seq N"', undefined, EXIT.FINDINGS);
+        }
+        return inject(ctx, o, { kind: 'click', x, y, contact: num(ctx.values, 'contact') ?? 0, pressure: num(ctx.values, 'pressure') ?? 1,
+            ...(expectSeq !== undefined ? { expectSeq } : {}),
+            ...(expectFrame ? { expectFrame } : {}) }, (r) => ['已点击 (' + x + ', ' + y + ')，' + String(r.ms) + 'ms'], 20000, true);
+    },
+};
+export const swipeCommand = {
+    name: 'swipe',
+    summary: '滑动（起点到终点，控制器分辨率空间）；--via 给中途路径点 = 一条笔画画折线',
+    usage: 'maafw-live swipe <x1> <y1> <x2> <y2> [--duration ms] [--via "x,y;x,y"] [--project <dir>|--kind ...]\n' +
+        '       带 --via 时走 touch_down→逐点 touch_move→touch_up（中途不抬手）——连线/谱曲/拖拽排序要的就是这个',
+    options: {
+        ...CONNECT_OPTIONS, duration: { type: 'string' }, contact: { type: 'string' },
+        pressure: { type: 'string' }, via: { type: 'string' },
+    },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const miss = needSession(o, ctx);
+        if (miss)
+            return miss;
+        const [x1, y1, x2, y2] = ctx.positionals.slice(0, 4).map((v) => Number(v));
+        if (![x1, y1, x2, y2].every((n) => Number.isFinite(n))) {
+            return fail('BAD_ARGUMENTS', '用法：maafw-live swipe <x1> <y1> <x2> <y2>', undefined, EXIT.USAGE);
+        }
+        const viaRaw = typeof ctx.values.via === 'string' ? ctx.values.via : undefined;
+        let via;
+        if (viaRaw !== undefined) {
+            via = viaRaw.split(';').map((s) => s.split(',').map((x) => Number(String(x).trim())));
+            if (!via.length || via.some((p) => p.length !== 2 || p.some((n) => !Number.isFinite(n)))) {
+                return fail('BAD_ARGUMENTS', '--via 每段要 2 个数字（x,y），段间用 ; 分隔，例："100,200;150,250"', undefined, EXIT.USAGE);
+            }
+        }
+        return inject(ctx, o, {
+            kind: 'swipe', x1, y1, x2, y2,
+            duration: num(ctx.values, 'duration') ?? 300,
+            contact: num(ctx.values, 'contact') ?? 0,
+            pressure: num(ctx.values, 'pressure') ?? 1,
+            ...(via ? { via } : {}),
+        }, (r) => [via
+                ? '已折线滑动 (' + x1 + ',' + y1 + ') → ' + via.map((p) => '(' + p.join(',') + ')').join(' → ')
+                    + ' → (' + x2 + ',' + y2 + ')，' + String(r.ms) + 'ms（一条笔画，' + String(via.length) + ' 个路径点）'
+                : '已滑动 (' + x1 + ',' + y1 + ') → (' + x2 + ',' + y2 + ')，' + String(r.ms) + 'ms']);
+    },
+};
+export const keyCommand = {
+    name: 'key',
+    summary: '按键（Android KeyEvent 码：3=Home、4=返回、187=最近任务）',
+    usage: 'maafw-live key <code> [--project <dir>|--kind ...]',
+    options: { ...CONNECT_OPTIONS },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const miss = needSession(o, ctx);
+        if (miss)
+            return miss;
+        const code = Number(ctx.positionals[0]);
+        if (!Number.isFinite(code))
+            return fail('BAD_ARGUMENTS', '用法：maafw-live key <code>', undefined, EXIT.USAGE);
+        return inject(ctx, o, { kind: 'key', code }, (r) => ['已按键 ' + code + '，' + String(r.ms) + 'ms']);
+    },
+};
+export const keysCommand = {
+    name: 'keys',
+    summary: '组合键（key_down 全按下 → key_up 反序抬起；如 Ctrl+C = 17,67）',
+    usage: 'maafw-live keys <code[,code+...]> [--hold ms] [--project <dir>|--kind ...]',
+    options: { ...CONNECT_OPTIONS, hold: { type: 'string' } },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const miss = needSession(o, ctx);
+        if (miss)
+            return miss;
+        const raw = String(ctx.positionals[0] ?? '');
+        const codes = raw.split(/[+,]/).map((s) => Number(s.trim())).filter((n) => Number.isFinite(n) && n > 0);
+        if (!codes.length) {
+            return fail('BAD_ARGUMENTS', '用法：maafw-live keys <code[,code+...]>（至少一个正整数键码）', undefined, EXIT.USAGE);
+        }
+        return inject(ctx, o, { kind: 'keys', codes, hold: num(ctx.values, 'hold') ?? 60 }, (r) => ['已组合键 ' + codes.join('+') + '，' + String(r.ms) + 'ms']);
+    },
+};
+export const pressCommand = {
+    name: 'press',
+    summary: '长按（touch_down → 保持 duration → touch_up）',
+    usage: 'maafw-live press <x> <y> [--duration ms] [--project <dir>|--kind ...]',
+    options: { ...CONNECT_OPTIONS, duration: { type: 'string' } },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const miss = needSession(o, ctx);
+        if (miss)
+            return miss;
+        const x = Number(ctx.positionals[0]);
+        const y = Number(ctx.positionals[1]);
+        if (!Number.isFinite(x) || !Number.isFinite(y)) {
+            return fail('BAD_ARGUMENTS', '用法：maafw-live press <x> <y>', undefined, EXIT.USAGE);
+        }
+        return inject(ctx, o, { kind: 'press', x, y, duration: num(ctx.values, 'duration') ?? 800 }, (r) => ['已长按 (' + x + ', ' + y + ')，' + String(r.ms) + 'ms']);
+    },
+};
+export const dbclickCommand = {
+    name: 'dbclick',
+    summary: '双击（两次 click，间隔 --gap，默认 60ms）',
+    usage: 'maafw-live dbclick <x> <y> [--gap ms] [--project <dir>|--kind ...]',
+    options: { ...CONNECT_OPTIONS, gap: { type: 'string' } },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const miss = needSession(o, ctx);
+        if (miss)
+            return miss;
+        const x = Number(ctx.positionals[0]);
+        const y = Number(ctx.positionals[1]);
+        if (!Number.isFinite(x) || !Number.isFinite(y)) {
+            return fail('BAD_ARGUMENTS', '用法：maafw-live dbclick <x> <y>', undefined, EXIT.USAGE);
+        }
+        return inject(ctx, o, { kind: 'dbclick', x, y, gap: num(ctx.values, 'gap') ?? 60 }, (r) => ['已双击 (' + x + ', ' + y + ')，' + String(r.ms) + 'ms']);
+    },
+};
+export const scrollCommand = {
+    name: 'scroll',
+    summary: '滚轮（dx/dy 格数，建议 120 的倍数 = WHEEL_DELTA；Win32/MacOS）',
+    usage: 'maafw-live scroll <dx> <dy> [--project <dir>|--kind ...]',
+    options: { ...CONNECT_OPTIONS },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const miss = needSession(o, ctx);
+        if (miss)
+            return miss;
+        const dx = Number(ctx.positionals[0]);
+        const dy = Number(ctx.positionals[1]);
+        if (!Number.isFinite(dx) || !Number.isFinite(dy)) {
+            return fail('BAD_ARGUMENTS', '用法：maafw-live scroll <dx> <dy>（如 0 -120 向上一格）', undefined, EXIT.USAGE);
+        }
+        return inject(ctx, o, { kind: 'scroll', dx, dy }, (r) => ['已滚动 (' + dx + ', ' + dy + ')，' + String(r.ms) + 'ms']);
+    },
+};
+export const moveCommand = {
+    name: 'move',
+    summary: '鼠标相对移动（Win32/MacOS；FPS 锁鼠标场景配合 mouse_lock_follow）',
+    usage: 'maafw-live move <dx> <dy> [--project <dir>|--kind ...]',
+    options: { ...CONNECT_OPTIONS },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const miss = needSession(o, ctx);
+        if (miss)
+            return miss;
+        const dx = Number(ctx.positionals[0]);
+        const dy = Number(ctx.positionals[1]);
+        if (!Number.isFinite(dx) || !Number.isFinite(dy)) {
+            return fail('BAD_ARGUMENTS', '用法：maafw-live move <dx> <dy>', undefined, EXIT.USAGE);
+        }
+        return inject(ctx, o, { kind: 'move', dx, dy }, (r) => ['已相对移动 (' + dx + ', ' + dy + ')，' + String(r.ms) + 'ms']);
+    },
+};
+export const textCommand = {
+    name: 'text',
+    summary: '输入文本（经控制器注入）',
+    usage: 'maafw-live text <string> [--project <dir>|--kind ...]',
+    options: { ...CONNECT_OPTIONS },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const miss = needSession(o, ctx);
+        if (miss)
+            return miss;
+        const text = ctx.positionals.join(' ');
+        if (!text)
+            return fail('BAD_ARGUMENTS', '用法：maafw-live text <string>', undefined, EXIT.USAGE);
+        return inject(ctx, o, { kind: 'text', text }, (r) => ['已输入 ' + text.length + ' 字符，' + String(r.ms) + 'ms']);
+    },
+};
+export const INPUT_COMMANDS = [
+    clickCommand, swipeCommand, keyCommand, keysCommand,
+    pressCommand, dbclickCommand, scrollCommand, moveCommand, textCommand,
+];
+//# sourceMappingURL=input.js.map

package/lib/commands/kf.js

@@ -0,0 +1,167 @@
+/**
+ * 关键帧命令：kf status / kf promote / kf list / kf resolve。
+ *
+ * 升格（promote）是 daemon 内存操作——从 L0 缓存取原图落盘并登记，必须在捕获它的那个
+ * daemon 会话里做（ REPL 里 stream/输入/run 之后立刻升格，"看到即升格，不攒到最后"）。
+ * list / resolve 是纯离线文件操作，不依赖 daemon 存活（契约 §4.1）。
+ */
+import { EXIT, fail } from '../protocol.js';
+import { defaultFramesDir, describeRecord, loadManifest, resolveFrame } from '../runtime/keyframes.js';
+import { kfPromote, l0Status, withDaemon } from '../runtime/actions.js';
+import { ensureSession } from '../runtime/session.js';
+import { CONNECT_OPTIONS, daemonFail, sessionOptions } from './runtime.js';
+const DIR_HINT = '库根默认 ~/.maafw-live/frames（与 daemon 的 runDir 一致）';
+export const kfCommand = {
+    name: 'kf',
+    summary: '关键帧：status 看 L0 缓存，promote 升格原图进本地库，list/resolve 离线解析',
+    usage: 'maafw-live kf status [--project <dir>|--kind ...]\n' +
+        '       maafw-live kf promote <seq|seq seq|a..b|latest> [--note <s>] [--project <dir>|--kind ...]\n' +
+        '       maafw-live kf list [--dir <frames>]      （离线，不需要设备）\n' +
+        '       maafw-live kf resolve <kf:...> [--dir <frames>]   （离线）',
+    options: { ...CONNECT_OPTIONS, note: { type: 'string' }, dir: { type: 'string' }, latest: { type: 'boolean' } },
+    /* promote 要的是"捕获帧的那个 daemon 会话"：一次性进程 seq=0 恒失败
+     *（P0-3 L4）。list/resolve/status 离线或边界语义可用，不拦。 */
+    requiresSession: (ctx) => ctx.positionals[0] === 'promote',
+    async run(ctx) {
+        const sub = ctx.positionals[0] ?? 'status';
+        if (sub === 'list' || sub === 'resolve') {
+            const dir = typeof ctx.values.dir === 'string' ? ctx.values.dir : defaultFramesDir();
+            if (sub === 'list') {
+                const { manifest, error } = loadManifest(dir);
+                if (error)
+                    return fail('KF_MANIFEST', error, DIR_HINT, EXIT.FINDINGS);
+                if (!manifest) {
+                    return {
+                        exitCode: EXIT.OK,
+                        human: ['关键帧库 ' + dir + '：尚无留存（manifest 未创建；升格后会自动生成）'],
+                        data: { dir, count: 0, frames: [] },
+                    };
+                }
+                return {
+                    exitCode: EXIT.OK,
+                    human: [
+                        '关键帧库 ' + dir + '：' + manifest.frames.length + ' 条（libraryId ' + manifest.libraryId + '）',
+                        ...manifest.frames.map(describeRecord),
+                    ],
+                    data: { dir, count: manifest.frames.length, frames: manifest.frames },
+                };
+            }
+            const id = ctx.positionals[1];
+            if (!id)
+                return fail('BAD_ARGUMENTS', '用法：maafw-live kf resolve <kf:库UUID:序号>', undefined, EXIT.USAGE);
+            const r = resolveFrame(dir, id);
+            const human = ['解析 ' + id + '：' + r.status + (r.reason ? '（' + r.reason + '）' : '')];
+            if (r.record)
+                human.push('  ' + describeRecord(r.record));
+            if (r.path)
+                human.push('  path: ' + r.path);
+            if (r.record)
+                human.push('  sha256: ' + r.record.sha256);
+            return { exitCode: EXIT.OK, human, data: r };
+        }
+        if (sub === 'status') {
+            try {
+                return await withDaemon(ctx, async (client) => {
+                    const st = await l0Status(client);
+                    const roll = st.roll;
+                    const anchor = st.anchor;
+                    return {
+                        exitCode: EXIT.OK,
+                        human: [
+                            'L0 原图缓存：滚动区 ' + String(roll?.count) + '/' + String(roll?.cap) +
+                                '（' + String(roll?.bytes) + ' bytes），锚区 ' + String(anchor?.count) + '/' + String(anchor?.cap) +
+                                '（' + String(anchor?.bytes) + ' bytes），seq=' + String(st.seq),
+                            '关键帧库：' + String(st.framesDir),
+                            '锚区条目（seq, source）：',
+                            ...(anchor?.entries ?? [])
+                                .map((e) => '  seq=' + e.seq + '  ' + String(e.source)),
+                        ],
+                        data: st,
+                    };
+                });
+            }
+            catch (e) {
+                return daemonFail(e);
+            }
+        }
+        if (sub === 'promote') {
+            const o = sessionOptions(ctx);
+            /* 批量：kf promote 3909 3910 | kf promote 10..15 | kf promote 10,11,12。
+             * 逐条升格、成功/淘汰分开报告；淘汰的附 frame_get <seq> 降级命令（L1 参考帧）。 */
+            const seqToks = ctx.positionals.slice(1).flatMap((t) => t.split(',')).filter((t) => t !== '');
+            let args = {};
+            const range = seqToks.length === 1 && /^(\d+)\.\.(\d+)$/.exec(seqToks[0]);
+            if (range) {
+                const a = Number(range[1]), b = Number(range[2]);
+                if (a > b || b - a > 200) {
+                    return fail('BAD_ARGUMENTS', '范围 ' + seqToks[0] + ' 非法（a..b 且跨度 ≤200）', undefined, EXIT.USAGE);
+                }
+                args.seqs = Array.from({ length: b - a + 1 }, (_, i) => a + i);
+            }
+            else if (seqToks.length > 1 || (seqToks.length === 1 && /^\d+$/.test(seqToks[0]))) {
+                const nums = seqToks.map((t) => Number(t));
+                if (nums.some((n) => !Number.isInteger(n) || n <= 0)) {
+                    return fail('BAD_ARGUMENTS', 'seq 必须是正整数：' + seqToks.join(' '), undefined, EXIT.USAGE);
+                }
+                if (nums.length === 1)
+                    args = { seq: nums[0] };
+                else
+                    args = { seqs: nums };
+            }
+            else if (seqToks[0] === 'latest' || ctx.values.latest === true) {
+                args = { latest: true };
+            }
+            if (typeof ctx.values.note === 'string')
+                args.note = ctx.values.note;
+            if (!args.seq && !args.latest && !(args.seqs && args.seqs.length)) {
+                return fail('BAD_ARGUMENTS', '给序号（kf promote 42）、多个序号（kf promote 42 43）、范围（kf promote 10..15）、或 kf promote latest；身份在接受请求时固定，已淘汰则失败', '升格要在捕获它的 daemon 会话里做（repl：stream/输入/run 后立刻升格）；一次性命令的 L0 通常只有边界帧', EXIT.USAGE);
+            }
+            try {
+                return await withDaemon(ctx, async (client) => {
+                    if (o.project || o.kind) {
+                        /* 设备会话存在才值得连：L0 缓存是进程态，连一次至少能把输入/截图边界帧留下 */
+                        await ensureSession(client, o);
+                    }
+                    const r = await kfPromote(client, args);
+                    /* 批量：逐条列结果；淘汰的 seq 附可复制的 frame_get 降级命令（L1 参考帧） */
+                    if (Array.isArray(r.results)) {
+                        const results = r.results;
+                        const lines = [];
+                        for (const it of results) {
+                            if (it.ok)
+                                lines.push('  seq=' + it.seq + ' → ' + it.id + (it.idempotent ? '（幂等）' : ''));
+                            else
+                                lines.push('  seq=' + it.seq + ' ✗ ' + it.error);
+                        }
+                        const failed = Number(r.failed ?? 0);
+                        if (failed > 0) {
+                            return { exitCode: EXIT.FINDINGS, human: ['批量升格：' + r.promoted + ' 成功 / ' + failed + ' 失败', ...lines], data: r };
+                        }
+                        return { exitCode: EXIT.OK, human: ['批量升格 ' + r.promoted + ' 例全部成功', ...lines], data: r };
+                    }
+                    if (r.ok === false) {
+                        return fail('KF_PROMOTE', String(r.error ?? '升格失败'), 'L0 淘汰是诚实失败：换 frame_get 导 L1 参考帧，或重采', EXIT.FINDINGS);
+                    }
+                    const rec = r.record;
+                    return {
+                        exitCode: EXIT.OK,
+                        human: [
+                            '已升格：' + String(r.id) + (r.idempotent ? '（幂等重试，返回原对象）' : ''),
+                            ...(rec ? ['  捕获 seq=' + rec.captureSeq + '，控制器尺寸 ' + rec.ctrlW + 'x' + rec.ctrlH + '，source=' + rec.source] : []),
+                            '  path: ' + String(r.path),
+                            '  sha256: ' + String(r.sha256),
+                        ],
+                        data: r,
+                        written: [String(r.path)],
+                    };
+                });
+            }
+            catch (e) {
+                return daemonFail(e);
+            }
+        }
+        return fail('BAD_ARGUMENTS', '用法：kf status | kf promote [seq|latest] | kf list | kf resolve <id>', undefined, EXIT.USAGE);
+    },
+};
+export const KF_COMMANDS = [kfCommand];
+//# sourceMappingURL=kf.js.map

package/lib/commands/probe.js

@@ -0,0 +1,70 @@
+/**
+ * `maafw-live screencap-probe` —— 截图能力探测：判定"后台可截"（A 路前提）。
+ *
+ * 方法（契约 demo-trace §3）：用另一个窗口把目标**完全盖住**，两次 `post_screencap`
+ * 间隔比 blockHash 与亮度。探针不知道"此刻是否真的遮挡"——所以 `--occluded` 让用户
+ * 显式声明；不给时判定结果如实标 `occluded:null`，不把"未声明遮挡"混成"前台结论"。
+ *
+ * 判据：
+ *   changed==true + occluded   → 后台可截（A 路前提成立）
+ *   changed==true + !occluded  → 像素在变——要判"后台可截"得在遮挡下重测
+ *   changed==false + 正常亮度  → 静止（目标停止渲染？改应用设置）
+ *   黑图 / post_screencap 报错 → 截图方法不兼容，换 `win32.screencap` 方法
+ */
+import { EXIT, fail } from '../protocol.js';
+import { screencapProbe, withDaemon } from '../runtime/actions.js';
+import { describeSession, ensureSession } from '../runtime/session.js';
+import { CONNECT_OPTIONS, daemonFail, sessionOptions } from './runtime.js';
+const needSession = (o, ctx) => ctx?.client || o.project || o.kind ? null : fail('NO_SESSION', '用法：maafw-live screencap-probe --project <dir> 或 --kind ...', undefined, EXIT.USAGE);
+export const screencapProbeCommand = {
+    name: 'screencap-probe',
+    summary: '截图能力探测：判定"后台可截"（A 路前提）——两次截图比像素与亮度',
+    usage: 'maafw-live screencap-probe [--project <dir>|--kind ...] [--interval ms] [--occluded]\n' +
+        '       先 connect/起会话；要用另一个窗口把目标完全盖住后，带 --occluded 再跑一次',
+    options: {
+        ...CONNECT_OPTIONS,
+        interval: { type: 'string' },
+        occluded: { type: 'boolean' },
+    },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const miss = needSession(o, ctx);
+        if (miss)
+            return miss;
+        const interval = ctx.values.interval !== undefined ? Number(ctx.values.interval) : 3000;
+        const occluded = ctx.values.occluded === true;
+        try {
+            return await withDaemon(ctx, async (client) => {
+                const s = await ensureSession(client, o);
+                const r = await screencapProbe(client, interval, occluded);
+                const first = (r.first ?? {});
+                const second = (r.second ?? {});
+                const lines = [
+                    ...describeSession(s, ctx.flags.verbose),
+                    '截图能力探测：两次 post_screencap 间隔 ' + String(r.intervalMs) + 'ms'
+                        + (r.occluded === true ? '（已声明窗口被完全遮挡）' : '（未声明遮挡——判据只在遮挡态成立）'),
+                ];
+                if (first.ok)
+                    lines.push('  第 1 帧：' + first.w + 'x' + first.h + ' hash=' + String(first.hash).slice(0, 24) + '… mean=' + first.mean);
+                else if (first.error !== undefined || 'ok' in first)
+                    lines.push('  第 1 帧：失败——' + String(first.error));
+                if (second.ok)
+                    lines.push('  第 2 帧：' + second.w + 'x' + second.h + ' hash=' + String(second.hash).slice(0, 24) + '… mean=' + second.mean);
+                else if (second.error !== undefined || 'ok' in second)
+                    lines.push('  第 2 帧：失败——' + String(second.error));
+                if (r.changed !== null && r.changed !== undefined)
+                    lines.push('  像素：' + (r.changed ? '在变' : '未变'));
+                lines.push('  判定：' + String(r.verdict) + '——' + String(r.note ?? ''));
+                const verdict = String(r.verdict);
+                const exitCode = verdict === 'changing' && occluded ? EXIT.OK
+                    : verdict === 'error' ? EXIT.FINDINGS
+                        : EXIT.FINDINGS; // black/static 都是要处置的发现；changing 但没声明遮挡 = 未定论
+                return { exitCode, human: lines, data: r };
+            });
+        }
+        catch (e) {
+            return daemonFail(e);
+        }
+    },
+};
+//# sourceMappingURL=probe.js.map