@windsland52/maafw-live 0.0.0-stage → 0.4.0

package/lib/commands/annotate.js

@@ -0,0 +1,179 @@
+/**
+ * annotate（轻量 SoM）：候选区域 + 编号回画。
+ *
+ * 模型消费方式：看回画图选编号 → 查候选表 ctrl 坐标 → click / reco / crop。
+ * 候选源：OCR 框（语义最强）、变化 diff 区域、连通域、边缘密度；半透明/粒子/渐变场景
+ * 候选质量降级——那时走点选路径（crop --point），两条路径互为降级。
+ *
+ * 源帧两条路：会话内 L1 小图（缺省，一次性命令自动截一帧）或**关键帧库留存帧**（`--from-kf`，
+ * 控制器分辨率、离线、不需要设备）。库帧路径下 diff 源不可用（没有会话事件），工具如实报出，
+ * 不拿别的区域顶替——所以它适合"事后在旧帧上重跑候选"，不适合替代实时变化检测。
+ */
+import { defaultFramesDir, resolveFrame } from '../runtime/keyframes.js';
+import { EXIT, fail } from '../protocol.js';
+import { annotate, seedObservation, withDaemon } from '../runtime/actions.js';
+import { describeSession, ensureSession, offlineResource } from '../runtime/session.js';
+import { CONNECT_OPTIONS, daemonFail, argPath, sessionOptions } from './runtime.js';
+export const annotateCommand = {
+    name: 'annotate',
+    summary: '轻量 SoM：OCR/diff/连通域/边缘密度候选区域 + 编号回画（源可为会话内帧或关键帧库留存帧）',
+    usage: 'maafw-live annotate [--seq n] [--out <png>] [--resource-dir <dir>] [--project <dir>|--kind ...]\n' +
+        '       maafw-live annotate --from-kf <kf:库UUID:序号> [--frames-dir <dir>] [--out <png>] [--resource-dir <dir>|--project <dir>]\n' +
+        '       OCR 候选需要资源目录（OCR 模型）；一次性命令自动截一帧；其余候选源无依赖\n' +
+        '       --from-kf 在库里留存帧上离线跑（不需要设备；该路径没有会话事件，diff 源不可用）\n' +
+        '       --som-limit n            放开候选上限（缺省 30；网格/表格类界面必给）\n' +
+        '       --som-max-area-ratio r   巨框剔除阈值（缺省 0.12，按画面面积比；OCR 框不参与）\n' +
+        '       --emit-crops <dir>       每个进表候选批量出 PNG + .prov.json（出处完整；不跑自匹配，选号验证走正式 crop）\\n' +
+        '       回画优先落在 L0 全分辨率原图上；回执带 availability（截断/剔除/分带），别把"30 条"读成"画面就这些"',
+    options: {
+        ...CONNECT_OPTIONS,
+        seq: { type: 'string' },
+        out: { type: 'string' },
+        'resource-dir': { type: 'string' },
+        'from-kf': { type: 'string' },
+        'frames-dir': { type: 'string' },
+        'som-limit': { type: 'string' },
+        'som-max-area-ratio': { type: 'string' },
+        'emit-crops': { type: 'string' },
+        roi: { type: 'string' },
+    },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const seq = typeof ctx.values.seq === 'string' ? Number(ctx.values.seq) : undefined;
+        if (ctx.values.seq !== undefined && !Number.isFinite(seq)) {
+            return fail('BAD_ARGUMENTS', '--seq 必须是数字', undefined, EXIT.USAGE);
+        }
+        const out = argPath(ctx, typeof ctx.values.out === 'string' ? ctx.values.out : undefined);
+        const roi = typeof ctx.values.roi === 'string'
+            ? ctx.values.roi.split(',').map((x) => Number(String(x).trim()))
+            : undefined;
+        if (roi && (roi.length !== 4 || roi.some((n) => !Number.isFinite(n)))) {
+            return fail('BAD_ARGUMENTS', '--roi 需要 4 个数字：x,y,w,h（控制器分辨率坐标）', undefined, EXIT.USAGE);
+        }
+        /* 上限/阈值必须**显式拒绝**非法值，不能靠 daemon 的 `> 0` 守卫悄悄换回默认——
+         * `--som-limit 0` 被静默当成 30 时，调用方以为"不限量"，拿到的是截断表。 */
+        const somLimitRaw = ctx.values['som-limit'];
+        const somLimit = typeof somLimitRaw === 'string' ? Number(somLimitRaw) : undefined;
+        if (somLimitRaw !== undefined && (!Number.isFinite(somLimit) || somLimit <= 0)) {
+            return fail('BAD_ARGUMENTS', '--som-limit 必须是正整数（收到 ' + JSON.stringify(somLimitRaw) + '）'
+                + '；0 不等于"不限量"', undefined, EXIT.USAGE);
+        }
+        const ratioRaw = ctx.values['som-max-area-ratio'];
+        const ratio = typeof ratioRaw === 'string' ? Number(ratioRaw) : undefined;
+        if (ratioRaw !== undefined && (!Number.isFinite(ratio) || ratio <= 0 || ratio >= 1)) {
+            return fail('BAD_ARGUMENTS', '--som-max-area-ratio 要在 (0,1) 之间（画面面积比，收到 ' + JSON.stringify(ratioRaw) + '）'
+                + '；0 不等于"关闭剔除"', undefined, EXIT.USAGE);
+        }
+        const fromKf = typeof ctx.values['from-kf'] === 'string' ? ctx.values['from-kf'] : undefined;
+        if (fromKf !== undefined && seq !== undefined) {
+            return fail('BAD_ARGUMENTS', '--from-kf 与 --seq 互斥：前者在库内留存帧上跑，后者在本会话缓冲帧上跑', '取库里有哪些帧：maafw-live kf list', EXIT.USAGE);
+        }
+        /* 库帧来源：先走离线读侧解析（契约 §4.1），daemon 只接身份与路径 */
+        let kfSource;
+        if (fromKf !== undefined) {
+            const dir = argPath(ctx, typeof ctx.values['frames-dir'] === 'string' ? ctx.values['frames-dir'] : undefined) ?? defaultFramesDir();
+            const r = resolveFrame(dir, fromKf);
+            if (r.status !== 'available' || !r.path || !r.record) {
+                const code = r.status === 'corrupt' ? 'KF_CORRUPT' : (r.status === 'unsupported' ? 'KF_UNSUPPORTED' : 'KF_MISSING');
+                return fail(code, '库帧不可用（' + r.status + '）：' + String(r.reason ?? '') + '（库 ' + dir + '）', 'kf list 看库内有哪些帧；missing 表示本机不可复核，不代表历史从未观测', EXIT.FINDINGS);
+            }
+            const rec = r.record;
+            kfSource = {
+                id: rec.id, path: r.path, sha256: rec.sha256, ctrlW: rec.ctrlW, ctrlH: rec.ctrlH,
+                captureSeq: rec.captureSeq, capturedAt: rec.capturedAt,
+            };
+        }
+        const offline = kfSource !== undefined;
+        try {
+            return await withDaemon(ctx, async (client) => {
+                const s = offline ? { connected: false } : await ensureSession(client, o);
+                let resourceDir = argPath(ctx, typeof ctx.values['resource-dir'] === 'string' ? ctx.values['resource-dir'] : undefined)
+                    ?? s.plan?.resource?.paths[0];
+                if (!resourceDir && offline && o.project) {
+                    /* 离线：项目只作资源的来源（OCR 模型），不扫设备不连接 */
+                    const off = offlineResource(o.project, o.controller, o.resource, ctx.cwd);
+                    if (off.error) {
+                        return fail('PLAN_FAILED', '离线解析项目资源失败：' + off.error, '也可以直接给 --resource-dir <dir>', EXIT.FINDINGS);
+                    }
+                    resourceDir = off.paths[0];
+                }
+                /* 一次性命令缓冲为空：先截一帧（用完即删，不留临时文件）。库帧路径不截帧——源已固定。 */
+                if (!offline && seq === undefined) {
+                    await seedObservation(client, 'annotate');
+                }
+                const emitCrops = argPath(ctx, typeof ctx.values['emit-crops'] === 'string' ? ctx.values['emit-crops'] : undefined);
+                const r = await annotate(client, {
+                    ...(offline ? { kfSource } : {}),
+                    ...(!offline && seq !== undefined ? { seq } : {}),
+                    ...(out ? { out } : {}),
+                    ...(resourceDir ? { resourceDir } : {}),
+                    ...(roi ? { roi } : {}),
+                    ...(somLimit !== undefined ? { somLimit } : {}),
+                    ...(ratio !== undefined ? { somMaxAreaRatio: ratio } : {}),
+                    ...(emitCrops ? { emitCrops } : {}),
+                });
+                if (r.ok === false) {
+                    return fail('ANNOTATE', String(r.error ?? '候选生成失败'), offline
+                        ? '库帧候选失败通常是文件被改动或库记录不一致；kf resolve 可复核'
+                        : '需要观测：REPL 里先 screencap / stream start；一次性命令会自动截一帧', EXIT.FINDINGS);
+                }
+                const cands = r.candidates ?? [];
+                const sources = r.sources;
+                const src = r.source;
+                const unavailable = r.sourcesUnavailable;
+                const ctrl = Array.isArray(r.ctrl) ? r.ctrl : null;
+                const avail = r.availability;
+                const srcLine = src?.kind === 'kf'
+                    ? '源帧 ' + String(src.id) + '（留存帧，捕获 seq=' + String(src.captureSeq) + '，' +
+                        String(ctrl?.[0] ?? '?') + 'x' + String(ctrl?.[1] ?? '?') + '，离线）'
+                    : '源帧 seq=' + String(r.seq) + '（小图 ' + JSON.stringify(r.small) + ' × ctrl ' + JSON.stringify(r.ctrl) + '）';
+                /* 可用性三列：**"看起来有结果"不等于"有结果"**。截断/剔除/分带一起读，
+                 * 才分得清"这一带没东西"与"这一带的东西被上限或门槛拿掉了"。 */
+                const availLines = avail
+                    ? [
+                        '  可用性：合并池 ' + String(avail.mergedTotal ?? '?') + ' → 进表 ' + String(r.count)
+                            + '（上限 ' + String(avail.limit ?? '?') + '，截断 ' + String(avail.truncated ?? 0) + '）'
+                            + '；剔除 太小 ' + String(avail.dropped?.tooSmall ?? 0) + ' / 巨框 ' + String(avail.dropped?.tooBig ?? 0)
+                            + '（阈值 ' + String(avail.maxAreaRatio ?? '?') + '）/ 重复 ' + String(avail.dropped?.duplicated ?? 0),
+                        ...(avail.byBand ? ['  分带（上/中/下）：' + avail.byBand.map((b) => String(b.inTable) + '/' + String(b.inPool)).join('  ')] : []),
+                        ...(avail.outResolution ? ['  回画分辨率：' + String(avail.outResolution.w) + 'x' + String(avail.outResolution.h)
+                                + '（' + String(avail.outResolution.source) + '）'] : []),
+                        ...(avail.detectionResolution ? ['  检测面分辨率：' + String(avail.detectionResolution.w) + 'x'
+                                + String(avail.detectionResolution.h) + '（' + String(avail.detectionResolution.source)
+                                + '）——检测面越小，小目标越可能探不到'] : []),
+                    ]
+                    : [];
+                return {
+                    exitCode: EXIT.OK,
+                    human: [
+                        ...describeSession(s, ctx.flags.verbose),
+                        ...(offline ? ['离线候选：未连接设备（库帧是本机持久文件）'] : []),
+                        'SoM 候选 ' + String(r.count) + ' 个（ocr ' + String(sources?.ocr ?? 0) + ' / diff ' + String(sources?.diff ?? 0) +
+                            ' / conn ' + String(sources?.conn ?? 0) + ' / edge ' + String(sources?.edge ?? 0) + '）→ ' + String(r.out),
+                        '  ' + srcLine,
+                        ...availLines,
+                        ...(unavailable ? Object.entries(unavailable).map(([k, v]) => '  ' + k + ' 源不可用：' + v) : []),
+                        '  坐标为控制器分辨率（面积占比供排序：越小越像小按钮，越大越像面板/背景）：',
+                        ...cands.map((c) => '  #' + c.id + ' [' + c.source + '] ctrl=' + c.ctrl.join(',')
+                            + (typeof c.areaRatio === 'number' ? ' 面积比=' + c.areaRatio : '')
+                            + (typeof c.score === 'number' ? ' score=' + c.score : '')
+                            + (c.text ? '  "' + c.text + '"' : '')),
+                        ...(r.warn ? ['  警告：' + String(r.warn)] : []),
+                        ...(r.emitted?.count
+                            ? ['  emit-crops：' + String(r.emitted.count) + ' 条已落到 ' + String(r.emitted.dir) + '（含 .prov.json；选号验证仍走正式 crop --roi/--from-kf）']
+                            : []),
+                        '选号后：click / reco --node（roi 用 ctrl 坐标）/ crop --roi（可再 crop --from-kf 于同一帧）',
+                    ],
+                    data: r,
+                    warnings: r.warn ? [String(r.warn)] : [],
+                    written: [String(r.out)],
+                };
+            });
+        }
+        catch (e) {
+            return daemonFail(e);
+        }
+    },
+};
+export const ANNOTATE_COMMANDS = [annotateCommand];
+//# sourceMappingURL=annotate.js.map

package/lib/commands/calibrate.js

@@ -0,0 +1,61 @@
+/**
+ * 变化检测阈值校准：静止画面采帧，统计分块亮度差 / 全局位差率的噪声分布，
+ * 推荐 blockThresh / changeGlobal。校准期间画面必须静止（max≫p99 会警告重跑）。
+ */
+import { EXIT, fail } from '../protocol.js';
+import { calibrate, withDaemon } from '../runtime/actions.js';
+import { describeSession, ensureSession } from '../runtime/session.js';
+import { CONNECT_OPTIONS, daemonFail, sessionOptions } from './runtime.js';
+export const calibrateCommand = {
+    name: 'calibrate',
+    summary: '变化检测阈值校准：静止画面采帧定噪声地板，推荐 blockThresh / changeGlobal',
+    usage: 'maafw-live calibrate [--frames n] [--interval ms] --project <dir>|--kind ...\n' +
+        '       采集期间保持画面静止；结果给出可直接粘贴的 stream start 参数',
+    options: { ...CONNECT_OPTIONS, frames: { type: 'string' }, interval: { type: 'string' } },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        if (!o.project && !o.kind) {
+            return fail('BAD_ARGUMENTS', '校准要设备：给 --project <dir>（推荐）或 --kind win32|adb|gamepad', undefined, EXIT.USAGE);
+        }
+        const frames = typeof ctx.values.frames === 'string' ? Number(ctx.values.frames) : undefined;
+        if (frames !== undefined && !Number.isFinite(frames)) {
+            return fail('BAD_ARGUMENTS', '--frames 必须是数字（6..60，默认 24）', undefined, EXIT.USAGE);
+        }
+        const interval = typeof ctx.values.interval === 'string' ? Number(ctx.values.interval) : undefined;
+        if (interval !== undefined && !Number.isFinite(interval)) {
+            return fail('BAD_ARGUMENTS', '--interval 必须是毫秒数（默认 300）', undefined, EXIT.USAGE);
+        }
+        try {
+            return await withDaemon(ctx, async (client) => {
+                const s = await ensureSession(client, o);
+                const r = await calibrate(client, {
+                    ...(frames !== undefined ? { frames } : {}),
+                    ...(interval !== undefined ? { interval } : {}),
+                });
+                if (r.ok === false) {
+                    return fail('CALIBRATE', String(r.error ?? '校准失败'), undefined, EXIT.FINDINGS);
+                }
+                const block = r.block;
+                const global = r.global;
+                return {
+                    exitCode: r.warn ? EXIT.FINDINGS : EXIT.OK,
+                    human: [
+                        ...describeSession(s, ctx.flags.verbose),
+                        '校准 ' + String(r.frames) + ' 帧（分块亮度差 / 全局位差率的噪声分布）：',
+                        '  分块差  p50=' + block.p50 + '  p99=' + block.p99 + '  max=' + block.max,
+                        '  位差率  p50=' + global.p50 + '  p99=' + global.p99 + '  max=' + global.max,
+                        '  推荐：' + String(r.apply),
+                        ...(r.warn ? ['  警告：' + String(r.warn)] : []),
+                    ],
+                    data: r,
+                    ...(r.warn ? { warnings: [String(r.warn)] } : {}),
+                };
+            });
+        }
+        catch (e) {
+            return daemonFail(e);
+        }
+    },
+};
+export const CALIBRATE_COMMANDS = [calibrateCommand];
+//# sourceMappingURL=calibrate.js.map

package/lib/commands/color.js

@@ -0,0 +1,73 @@
+/**
+ * 探色命令：ROI 实测主色/均值（RGB/HSV/灰度）——模型只选色不报色值。
+ *
+ * 为什么不靠模型读像素：色值必须来自实测（降采样小图按该帧捕获尺寸换算后的 ROI），
+ * 模型选完色后用 reco ColorMatch 出框（走已修好的参数透传链），出框与否是事实不是判断。
+ */
+import { EXIT, fail } from '../protocol.js';
+import { colorProbe, seedObservation, withDaemon } from '../runtime/actions.js';
+import { describeSession, ensureSession } from '../runtime/session.js';
+import { CONNECT_OPTIONS, daemonFail, sessionOptions } from './runtime.js';
+export const colorCommand = {
+    name: 'color',
+    summary: '探色：ROI 实测均值/HSV/主色（控制器分辨率坐标；选中后用 reco ColorMatch 出框）',
+    usage: 'maafw-live color [--roi x,y,w,h] [--seq n] --project <dir>|--kind ...\n' +
+        '       一次性命令先自动截一帧再测；REPL 里测缓冲最新帧（先 screencap / stream）',
+    options: { ...CONNECT_OPTIONS, roi: { type: 'string' }, seq: { type: 'string' } },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        if (!o.project && !o.kind) {
+            return fail('BAD_ARGUMENTS', '要设备才能探色：给 --project <dir>（推荐）或 --kind win32|adb|gamepad', '多步操作用 maafw-live repl（连接一次后连续观测）', EXIT.USAGE);
+        }
+        const roi = typeof ctx.values.roi === 'string'
+            ? ctx.values.roi.split(',').map((x) => Number(String(x).trim()))
+            : undefined;
+        if (roi && (roi.length !== 4 || roi.some((n) => !Number.isFinite(n)))) {
+            return fail('BAD_ARGUMENTS', '--roi 需要 4 个数字：x,y,w,h（控制器分辨率坐标，与 pipeline 的 roi 同空间）', undefined, EXIT.USAGE);
+        }
+        const seq = typeof ctx.values.seq === 'string' ? Number(ctx.values.seq) : undefined;
+        if (ctx.values.seq !== undefined && !Number.isFinite(seq)) {
+            return fail('BAD_ARGUMENTS', '--seq 必须是数字', undefined, EXIT.USAGE);
+        }
+        try {
+            return await withDaemon(ctx, async (client) => {
+                const s = await ensureSession(client, o);
+                /* 一次性命令缓冲为空：先截一帧产生观测（screencap 现在进环，有捕获身份）。
+                 * 截帧文件用完即删——它只是观测载体，既不落用户 cwd，也不留在临时目录。 */
+                if (seq === undefined) {
+                    await seedObservation(client, 'color');
+                }
+                const r = await colorProbe(client, {
+                    ...(seq !== undefined ? { seq } : {}),
+                    ...(roi ? { roi } : {}),
+                });
+                if (r.ok === false) {
+                    return fail('COLOR_PROBE', String(r.error ?? '探色失败'), 'REPL 里先 screencap 或 stream start；一次性命令会自动截一帧', EXIT.FINDINGS);
+                }
+                const mean = r.mean;
+                const hsv = r.hsv;
+                const dom = r.dominant;
+                return {
+                    exitCode: EXIT.OK,
+                    human: [
+                        ...describeSession(s, ctx.flags.verbose),
+                        '探色 seq=' + String(r.seq) + (roi ? '  roi=' + roi.join(',') : '  （整帧）'),
+                        '  均值 RGB ' + mean.r + ',' + mean.g + ',' + mean.b + '  灰度 ' + mean.gray +
+                            '  HSV ' + hsv.h + '°,' + hsv.s + '%,' + hsv.v + '%',
+                        '  主色 RGB ' + dom.rgb.join(',') + '（覆盖 ' + Math.round(dom.ratio * 100) + '%）',
+                        '出框验证：maafw-live reco --type ColorMatch --param \'{"color":[' + dom.rgb.join(',') + '],"threshold":0.05}\' …',
+                    ],
+                    data: r,
+                    suggestedCommands: [
+                        'maafw-live reco --type ColorMatch --param \'{"color":[' + dom.rgb.join(',') + '],"threshold":0.05}\' --image <png> --resource-dir <dir>',
+                    ],
+                };
+            });
+        }
+        catch (e) {
+            return daemonFail(e);
+        }
+    },
+};
+export const COLOR_COMMANDS = [colorCommand];
+//# sourceMappingURL=color.js.map

package/lib/commands/crop.js

@@ -0,0 +1,228 @@
+/**
+ * 模板裁剪：低精度输入（宽松框或点+外扩）→ snap 收紧 → 从源帧原图裁剪 →
+ * 同帧自匹配逐边重试取得分最高边界。
+ *
+ * 关键约束：模板尺寸必须与识别空间一致——只从控制器分辨率的完整原图裁，
+ * 不从降采样小图裁。点→ROI 派生与裁剪共享同一条 snap 链（roadmap 条目4/5）。
+ *
+ * 源帧两条路：
+ *  - L0 热缓存（缺省）：进程态，seq 或最新；跨帧验证缺省开（新帧再匹配一次）。
+ *  - 关键帧库留存帧（--from-kf）：库内 L0 文件，跨会话可用、**不需要设备**——
+ *    不可复现状态的动线正是这条（捕获它的那次会话早已结束）。跨帧验证缺省关：
+ *    留存帧对应的状态通常已不在画面上，拿当前帧比只会得到假警告。
+ *
+ * 裁出的 PNG 是 L2 派生图（契约 §2），旁边写 `<out>.prov.json` 出处记录
+ * （契约 §5：L2 记录来源及裁剪 / 缩放变换）——出处与模板同生共死，可一起提交进仓库。
+ */
+import { defaultFramesDir, resolveFrame } from '../runtime/keyframes.js';
+import { EXIT, fail } from '../protocol.js';
+import { seedObservation, tplCrop, withDaemon } from '../runtime/actions.js';
+import { describeSession, ensureSession, offlineResource } from '../runtime/session.js';
+import { CONNECT_OPTIONS, daemonFail, argPath, sessionOptions } from './runtime.js';
+function nums(raw, count, what) {
+    if (raw === undefined)
+        return undefined;
+    const v = raw.split(',').map((x) => Number(String(x).trim()));
+    if (v.length !== count || v.some((n) => !Number.isFinite(n))) {
+        throw new Error(what + ' 需要 ' + count + ' 个数字');
+    }
+    return v;
+}
+/** 库里解析出来的帧 → daemon 的裁剪源（身份与路径；daemon 会复核 sha256 与像素尺寸）。 */
+function kfSourceOf(r) {
+    const rec = r.record;
+    return {
+        id: rec.id,
+        path: String(r.path),
+        sha256: rec.sha256,
+        ctrlW: rec.ctrlW,
+        ctrlH: rec.ctrlH,
+        captureSeq: rec.captureSeq,
+        capturedAt: rec.capturedAt,
+    };
+}
+export const cropCommand = {
+    name: 'crop',
+    summary: '模板裁剪：宽松框/点 → snap 收紧 → 原图裁剪 → 自匹配验证（源可为 L0 热缓存或关键帧库留存帧）',
+    usage: 'maafw-live crop --roi x,y,w,h | --point x,y [--pad n] [--seq n] [--out <png>] [--no-cross] --project <dir>|--kind ...\n' +
+        '       maafw-live crop --from-kf <kf:库UUID:序号> --roi x,y,w,h [--frames-dir <dir>] [--resource-dir <dir> | --project <dir>] [--cross]\n' +
+        '       源帧缺省是 L0 最新原图（screencap/stream/输入都会产生）；连接真机时自动做跨帧验证（新帧再匹配一次）\n' +
+        '       --from-kf 改从关键帧库留存帧裁：离线可用（不需要设备），跨帧验证缺省关（留存帧对应的状态通常已不在画面上）\n' +
+        '       裁出的 PNG 是 L2 派生图，旁边写 <out>.prov.json 出处记录（来源 + 裁剪变换；--no-prov 可关）\n' +
+        '       --keep-source 顺手把本次裁剪用的那一帧升格进关键帧库，出处随即带上可复核的 kf: 身份\n' +
+        '       （契约的模型是 L0 缓存 → 选择性升格 → 从库帧裁；少了这步，出处只剩一个随进程消失的 seq）\n' +
+        '       --prov-out <dir> 把出处写到该目录下（同名），用于模板要进资源包、而资源包只装框架要加载的东西：\n' +
+        '       约定不变量是"同一相对路径"（如 state-plan/provenance/ 与 image/ 同构）',
+    options: {
+        ...CONNECT_OPTIONS,
+        roi: { type: 'string' },
+        point: { type: 'string' },
+        pad: { type: 'string' },
+        seq: { type: 'string' },
+        out: { type: 'string' },
+        'resource-dir': { type: 'string' },
+        'no-cross': { type: 'boolean' },
+        'from-kf': { type: 'string' },
+        'frames-dir': { type: 'string' },
+        cross: { type: 'boolean' },
+        'no-prov': { type: 'boolean' },
+        'prov-out': { type: 'string' },
+        'keep-source': { type: 'boolean' },
+    },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        let roi;
+        let point;
+        try {
+            roi = nums(typeof ctx.values.roi === 'string' ? ctx.values.roi : undefined, 4, '--roi');
+            point = nums(typeof ctx.values.point === 'string' ? ctx.values.point : undefined, 2, '--point');
+        }
+        catch (e) {
+            return fail('BAD_ARGUMENTS', e.message, undefined, EXIT.USAGE);
+        }
+        if (!roi && !point) {
+            return fail('BAD_ARGUMENTS', '给 --roi x,y,w,h（宽松框）或 --point x,y（自动外扩成宽松框）', undefined, EXIT.USAGE);
+        }
+        const seq = typeof ctx.values.seq === 'string' ? Number(ctx.values.seq) : undefined;
+        if (ctx.values.seq !== undefined && !Number.isFinite(seq)) {
+            return fail('BAD_ARGUMENTS', '--seq 必须是数字', undefined, EXIT.USAGE);
+        }
+        const pad = typeof ctx.values.pad === 'string' ? Number(ctx.values.pad) : undefined;
+        if (pad !== undefined && !Number.isFinite(pad)) {
+            return fail('BAD_ARGUMENTS', '--pad 必须是数字（点→ROI 外扩半径，默认 24）', undefined, EXIT.USAGE);
+        }
+        const out = argPath(ctx, typeof ctx.values.out === 'string' ? ctx.values.out : undefined);
+        const fromKf = typeof ctx.values['from-kf'] === 'string' ? ctx.values['from-kf'] : undefined;
+        if (fromKf !== undefined && seq !== undefined) {
+            return fail('BAD_ARGUMENTS', '--from-kf 与 --seq 互斥：前者从库内留存帧裁，后者从本会话 L0 热缓存裁', '取库里有哪些帧：maafw-live kf list', EXIT.USAGE);
+        }
+        if (fromKf !== undefined && ctx.values.cross === true && ctx.values['no-cross'] === true) {
+            return fail('BAD_ARGUMENTS', '--cross 与 --no-cross 互斥', undefined, EXIT.USAGE);
+        }
+        /* 库帧来源：先走离线读侧解析（契约 §4.1），daemon 只接身份与路径——
+         * 解析失败就在这一层如实报，不把不可复核的帧送进裁剪。 */
+        let kfSource;
+        if (fromKf !== undefined) {
+            const dir = argPath(ctx, typeof ctx.values['frames-dir'] === 'string' ? ctx.values['frames-dir'] : undefined) ?? defaultFramesDir();
+            const r = resolveFrame(dir, fromKf);
+            if (r.status !== 'available' || !r.path || !r.record) {
+                const code = r.status === 'corrupt' ? 'KF_CORRUPT' : (r.status === 'unsupported' ? 'KF_UNSUPPORTED' : 'KF_MISSING');
+                return fail(code, '库帧不可用（' + r.status + '）：' + String(r.reason ?? '') + '（库 ' + dir + '）', 'kf list 看库内有哪些帧；missing 表示本机不可复核，不代表历史从未观测', EXIT.FINDINGS);
+            }
+            kfSource = kfSourceOf(r);
+        }
+        const wantCross = ctx.values.cross === true;
+        /* 库帧路径默认离线：留存帧是本机持久文件，裁剪不需要设备。要跨帧验证才连。 */
+        const offline = kfSource !== undefined && !wantCross;
+        if (kfSource !== undefined && wantCross && !o.project && !o.kind) {
+            return fail('BAD_ARGUMENTS', '--cross 需要连接设备：给 --project <dir> 或 --kind', '不留 --cross 就是纯离线裁剪（留存帧的价值所在）', EXIT.USAGE);
+        }
+        try {
+            return await withDaemon(ctx, async (client) => {
+                const s = offline ? { connected: false } : await ensureSession(client, o);
+                /* 自匹配要加载资源（模板走 override_image，不写项目目录）；项目模式用规划出的资源 */
+                let resourceDir = argPath(ctx, typeof ctx.values['resource-dir'] === 'string' ? ctx.values['resource-dir'] : undefined)
+                    ?? s.plan?.resource?.paths[0];
+                if (!resourceDir && offline && o.project) {
+                    /* 离线：项目只是资源的来源，不是连接的对象——只读 interface.json，不扫设备 */
+                    const off = offlineResource(o.project, o.controller, o.resource, ctx.cwd);
+                    if (off.error) {
+                        return fail('PLAN_FAILED', '离线解析项目资源失败：' + off.error, '也可以直接给 --resource-dir <dir>', EXIT.FINDINGS);
+                    }
+                    resourceDir = off.paths[0];
+                }
+                if (!resourceDir) {
+                    return fail('BAD_ARGUMENTS', '自匹配需要资源目录：给 --resource-dir <dir> 或 --project <dir>', undefined, EXIT.USAGE);
+                }
+                /* L0 是进程态：一次性命令先截一帧产生观测（截帧文件用完即删，不落用户 cwd、也不留在临时目录）。
+                 * 库帧路径不截帧——源已经固定，重截只会拿到另一个时刻。 */
+                if (kfSource === undefined && seq === undefined) {
+                    await seedObservation(client, 'crop');
+                }
+                const r = await tplCrop(client, {
+                    ...(roi ? { roi } : {}),
+                    ...(point ? { point } : {}),
+                    ...(pad !== undefined ? { pad } : {}),
+                    ...(kfSource === undefined && seq !== undefined ? { seq } : {}),
+                    ...(kfSource ? { kfSource } : {}),
+                    ...(out ? { out } : {}),
+                    resourceDir,
+                    /* 跨帧验证缺省：热缓存路径交给 daemon 判（连接着就做）；库帧路径显式关，--cross 才做 */
+                    ...(kfSource !== undefined && !wantCross ? { cross: false } : (wantCross ? { cross: true } : {})),
+                    ...(ctx.values['no-cross'] === true ? { cross: false } : {}),
+                    ...(ctx.values['no-prov'] === true ? { prov: false } : {}),
+                    ...(typeof ctx.values['prov-out'] === 'string' && ctx.values['prov-out']
+                        ? { provOut: ctx.values['prov-out'] }
+                        : {}),
+                    ...(ctx.values['keep-source'] === true ? { keepSource: true } : {}),
+                });
+                if (r.ok === false) {
+                    return fail('TPL_CROP', String(r.error ?? '裁剪失败'), kfSource ? '库帧裁剪失败通常是文件被改动或库记录不一致；kf resolve 可复核' : '源帧取 L0 最新原图：先 screencap / stream / 输入产生观测', EXIT.FINDINGS);
+                }
+                const box = r.box;
+                const src = r.source;
+                const cross = r.cross;
+                /* 贴合度信号：宽松框 → 最终框的几何对比（得分那一路分辨不出贴合度：三种窗口自匹配都是 1.0） */
+                const tg = r.tighten;
+                const space = r.spaceCheck;
+                const srcLine = src && src.kind === 'kf'
+                    ? '源帧 ' + String(src.id) + '（留存帧，捕获 seq=' + String(src.captureSeq) + '，' +
+                        String(src.ctrlW) + 'x' + String(src.ctrlH) + '，sha ' + String(src.sha256).slice(0, 12) + '）'
+                    : '源帧 seq=' + String(r.seq) + '（' + String(r.ctrlW) + 'x' + String(r.ctrlH) + '，L0 热缓存）';
+                const spaceLine = space && space.current
+                    ? '  空间核对：源 ' + String(r.ctrlW) + 'x' + String(r.ctrlH) + (space.match ? ' = ' : ' ≠ ') +
+                        '当前控制器 ' + space.current.w + 'x' + space.current.h
+                    : '  空间核对：未连接设备，未与当前控制器尺寸比对（模板空间 = 源帧捕获时尺寸 ' +
+                        String(r.ctrlW) + 'x' + String(r.ctrlH) + '）';
+                const human = [
+                    ...describeSession(s, ctx.flags.verbose),
+                    ...(offline ? ['离线裁剪：未连接设备（留存帧是本机持久文件，裁剪不需要设备）'] : []),
+                    '模板 ' + String(r.w) + 'x' + String(r.h) + ' → ' + String(r.path),
+                    '  ' + srcLine,
+                    '  宽松框 ' + JSON.stringify(r.loose) + ' → 收紧 ' + JSON.stringify(box) +
+                        (tg?.from && tg?.to
+                            ? '（' + tg.from.join('×') + ' → ' + tg.to.join('×') +
+                                (tg.areaRatio !== null && tg.areaRatio !== undefined ? '，面积 ' + tg.areaRatio + '×' : '') +
+                                (tg.grew ? '，反而放大' : '') + '）'
+                            : '') +
+                        (tg?.looseMatch
+                            ? '；宽松框自匹配 ' + tg.looseMatch.score + (tg.looseMatch.positionOk ? '（位置正确，说明得分分辨不出贴合度）' : '（位置漂移）')
+                            : '') +
+                        (r.snapped ? '' : '（snap 无内容收紧，用原框）'),
+                    '  自匹配 ' + (r.positionOk === false ? '位置错误（best 落在 ' + JSON.stringify(r.selfMatchBox ?? null) + '）' : '位置正确') +
+                        '，得分 ' + String(r.score) + '（' + String(r.tries) + ' 次评估）',
+                    ...(cross
+                        ? ['  跨帧验证 seq=' + String(cross.seq) + '：得分 ' + String(cross.score) +
+                                (cross.posOk ? '，位置正确' : '，位置漂移 ' + JSON.stringify(cross.box ?? null))]
+                        : [kfSource
+                                ? '  跨帧验证：跳过（源为留存帧，它对应的状态通常已不在当前画面上；状态可复现时给 --cross）'
+                                : (ctx.values['no-cross'] === true
+                                    ? '  跨帧验证：已按 --no-cross 关闭'
+                                    : '  跨帧验证：未做（未连接设备）')]),
+                    spaceLine,
+                    ...(r.provPath
+                        ? ['L2 出处：' + String(r.provPath) + '（来源 + 裁剪变换；随模板一起提交进仓库）']
+                        : ['L2 出处：未写（--no-prov）']),
+                    ...(r.keptSource && r.keptSource.id
+                        ? ['源帧已留档：' + String(r.keptSource.id) + '（出处随之升级为可复核的 kf: 身份）']
+                        : []),
+                    ...(r.warns ?? []).map((w) => '  警告：' + w),
+                    'pipeline 用法：roi ' + box.join(',') + ' + template 该文件（同帧验证：maafw-live reco --node …）',
+                ];
+                const warns = r.warns ?? [];
+                return {
+                    exitCode: warns.length ? EXIT.FINDINGS : EXIT.OK,
+                    human,
+                    data: r,
+                    written: [String(r.path), ...(r.provPath ? [String(r.provPath)] : [])],
+                    ...(warns.length ? { warnings: warns } : {}),
+                };
+            });
+        }
+        catch (e) {
+            return daemonFail(e);
+        }
+    },
+};
+export const CROP_COMMANDS = [cropCommand];
+//# sourceMappingURL=crop.js.map