@windsland52/maafw-live 0.0.0-stage → 0.4.0

package/lib/types/runtime/actions.d.ts

@@ -0,0 +1,248 @@
+import { resolveResourcePaths, type ControllerPlan, type DeviceLike, type LoadedInterface } from '../interface/index.js';
+import { type DaemonClient, type SpawnOptions } from '../client/daemon.js';
+/** 设备会话的连接参数（手动路径）。kind/target 之外全部来自 maafw 的控制器能力。
+ * playcover/macos 仅 macOS、linux 仅 Linux；device_list 只枚举 adb/win32，
+ * 其余三种没有自动发现，靠 connect 的 target/config 显式指定（doc: daemon-protocol.md:49）。 */
+export interface ManualConnect {
+    kind: 'adb' | 'win32' | 'gamepad' | 'playcover' | 'macos' | 'linux';
+    target?: string;
+    /** playcover：uuid（也可写在 target 里） */
+    uuid?: string;
+    /** linux：等价于 target 的 JSON */
+    config?: string;
+    /** 截图缩放覆盖（会改变 Tasker 识别图像的坐标系，模板/roi 随之变化） */
+    shortSide?: number;
+    longSide?: number;
+    rawSize?: boolean;
+    screencap?: string;
+    mouse?: string;
+    keyboard?: string;
+    gamepadType?: string;
+}
+export interface ConnectSession {
+    ok: boolean;
+    error?: string;
+    session?: Record<string, unknown> | null;
+    /** 本次连接重建了控制器、因而停掉了上一轮的帧流（需要看帧就重新 stream_start） */
+    streamStopped?: boolean;
+}
+/**
+ * 给命令一个 daemon 客户端：ctx.client 有就借用（REPL / 命名会话，**不关**——
+ * 会话的生命周期不归命令管）；没有才 spawn 一次性的，跑完即关。
+ * 统一入口的意义：命令只需写一遍，`--session` 转发与 REPL 复用走的是同一份实现。
+ */
+export declare function withDaemon<T>(ctx: {
+    client?: DaemonClient;
+}, fn: (client: DaemonClient) => Promise<T>, options?: SpawnOptions): Promise<T>;
+export declare const probe: (c: DaemonClient) => Promise<Record<string, unknown>>;
+export declare const deviceList: (c: DaemonClient, kind?: "all" | "adb" | "win32") => Promise<DeviceLike[]>;
+export declare const connect: (c: DaemonClient, args: Record<string, unknown>) => Promise<ConnectSession>;
+export declare const disconnect: (c: DaemonClient) => Promise<{
+    ok: boolean;
+}>;
+export declare const screencap: (c: DaemonClient, out?: string) => Promise<Record<string, unknown>>;
+/**
+ * 一次性命令的"先产生一次观测"：截一帧进 daemon 的 L0，然后**把临时文件删掉**。
+ *
+ * 为什么需要这一帧：L0 是进程态，一次性命令（`crop` / `annotate` / `color`）每次 spawn 自己的
+ * daemon，不先截一帧就没有原图可用。为什么必须删：daemon 收帧时就把像素读进缓冲了，
+ * 落盘那份只为喂它一次——不删就是每跑一次在系统临时目录留一张 720p 截图（实测攒到 42 张 / 54MB）。
+ * 失败不抛：没有观测时命令自己会报"先 screencap / stream"这类可行动的错。
+ */
+export declare function seedObservation(c: DaemonClient, prefix: string): Promise<void>;
+export declare const streamStart: (c: DaemonClient, args?: {
+    fps?: number;
+    scale?: number;
+    maxFrames?: number;
+    l0Roll?: number;
+    l0Anchor?: number;
+    l0Bytes?: number;
+    blockThresh?: number;
+    changeGlobal?: number;
+}) => Promise<Record<string, unknown>>;
+export declare const streamStop: (c: DaemonClient) => Promise<{
+    ok: boolean;
+}>;
+export declare const streamStatus: (c: DaemonClient) => Promise<Record<string, unknown>>;
+/** 事件环查询：一次性 CLI 用。事件环活在 daemon 里，跨进程只能现查（REPL 另有本地副本）。 */
+export declare const eventsList: (c: DaemonClient, args?: {
+    since?: number;
+    limit?: number;
+}) => Promise<{
+    ok: boolean;
+    total: number;
+    matched: number;
+    cap: number;
+    truncated: boolean;
+    events: Array<Record<string, unknown>>;
+}>;
+export declare const frameGet: (c: DaemonClient, args: {
+    seq?: number;
+    roi?: number[];
+    out?: string;
+    src?: "auto" | "full" | "ring";
+}) => Promise<Record<string, unknown>>;
+/** 等状态谓词成立：stable=画面静下来 / change=画面动了。取代调用方硬睡时钟。 */
+export declare const waitState: (c: DaemonClient, args?: {
+    mode?: "stable" | "change";
+    timeout?: number;
+    quiet?: number;
+    roi?: number[];
+    threshold?: number;
+}) => Promise<Record<string, unknown>>;
+/** 两帧在若干 ROI 上的差分：回答"这一步改了哪几格"。 */
+export declare const frameDiff: (c: DaemonClient, args: {
+    a: number;
+    b: number;
+    rois: number[][];
+}) => Promise<Record<string, unknown>>;
+export declare const colorProbe: (c: DaemonClient, args: {
+    seq?: number;
+    roi?: number[];
+}) => Promise<Record<string, unknown>>;
+/** 裁剪源 = 关键帧库留存帧（离线解析出来的身份 + 路径；daemon 会复核 sha256 与像素尺寸）。 */
+export interface CropKfSource {
+    id: string;
+    path: string;
+    sha256: string;
+    ctrlW: number;
+    ctrlH: number;
+    captureSeq: number | null;
+    capturedAt: string | null;
+}
+export declare const tplCrop: (c: DaemonClient, args: {
+    seq?: number;
+    roi?: number[];
+    point?: number[];
+    pad?: number;
+    out?: string;
+    resourceDir?: string;
+    cross?: boolean;
+    kfSource?: CropKfSource;
+    prov?: boolean;
+    /** 出处侧车改写到该目录下（保持同名）；缺省写在模板旁 */
+    provOut?: string;
+    /** 热缓存路径下把本次实际用的那一帧升格进库，出处随即带上可复核的 `kf:` 身份 */
+    keepSource?: boolean;
+    /** snap 收紧阈值的**测量用覆盖**（定标 A/B）；缺省即生产常数 */
+    snapTol?: number;
+    snapFrac?: number;
+    /** 边缘收紧那一路（默认 false）：true 时把"局部对比度"判据也放进候选池。
+     * 常数可再覆盖（定标用）：edgeZ 环上对比度 p90 倍数（默认 2）、edgeMin 绝对地板（默认 24）、
+     * edgeFrac 行/列命中比例门槛（默认 0.02）。 */
+    edge?: boolean;
+    edgeZ?: number;
+    edgeMin?: number;
+    edgeFrac?: number;
+}) => Promise<Record<string, unknown>>;
+export declare const annotate: (c: DaemonClient, args: {
+    seq?: number;
+    out?: string;
+    resourceDir?: string;
+    kfSource?: CropKfSource;
+    /** 候选上限（缺省 30；截断按横向分带轮转，`mergedTotal` 才是去重后的真实规模） */
+    somLimit?: number;
+    /** 边缘源门槛的**测量用覆盖**（定标 A/B）；缺省即生产常数 */
+    somEdgeZ?: number;
+    somEdgeMin?: number;
+    /** 连通域合并 IoU 的测量用覆盖 */
+    somIoU?: number;
+    /** 巨框剔除阈值（画面面积比，缺省 0.12；OCR 框不参与）——背景/立绘/整屏变化区不该占表 */
+    somMaxAreaRatio?: number;
+    /** 只保留落在该区域（控制器空间）内的候选，且在**取上限之前**过滤：
+     * 区域内的候选只跟自己竞争。上限截断的正解是收小搜索面，不是把上限调大。 */
+    roi?: number[];
+    /** 检测面：full(缺省，有 L0 时用控制器分辨率原图) | small（强制降采样小图，快但小目标会漏） */
+    somScale?: "full" | "small";
+}) => Promise<Record<string, unknown>>;
+export declare const calibrate: (c: DaemonClient, args?: {
+    frames?: number;
+    interval?: number;
+}) => Promise<Record<string, unknown>>;
+export declare const runStop: (c: DaemonClient) => Promise<{
+    ok: boolean;
+}>;
+export declare const l0Status: (c: DaemonClient) => Promise<Record<string, unknown>>;
+export declare const kfPromote: (c: DaemonClient, args: {
+    seq?: number;
+    latest?: boolean;
+    note?: string;
+}) => Promise<Record<string, unknown>>;
+export declare function run(c: DaemonClient, args: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;
+export declare const input: (c: DaemonClient, payload: Record<string, unknown>, timeoutMs?: number) => Promise<Record<string, unknown>>;
+/** 截图能力探测（A 路前提）：两次 post_screencap 间隔比 hash/亮度。timeout 给 interval+10s。 */
+export declare const screencapProbe: (c: DaemonClient, intervalMs?: number, occluded?: boolean) => Promise<Record<string, unknown>>;
+/** 识别单测。`timeoutMs` 供**多候选**调用方放宽（候选逐例串行，耗时随候选数线性增长：
+ * daemon 侧的子进程预算也跟着用例数放宽，见 framed.mjs 的 recoChildBudget）。 */
+export declare const recoTest: (c: DaemonClient, args: Record<string, unknown>, timeoutMs?: number) => Promise<Record<string, unknown>>;
+/**
+ * 控制器类型 → 需要扫描的设备类型；**无设备可枚举的类型返回 null**（调用方跳过扫描）。
+ * daemon 的 device_list 只枚举 adb/win32——PlayCover/MacOS/Linux 给 'win32' 会白白发起
+ * 一次必然失败的扫描（曾经就是这样，把无关窗口列表塞进计划错误里）。
+ */
+export declare function deviceKindFor(loaded: LoadedInterface, controllerName: string | null): 'adb' | 'win32' | null;
+export interface ProjectPlan {
+    loaded: LoadedInterface;
+    plan: ControllerPlan | null;
+    controllerName: string | null;
+    resource: ReturnType<typeof resolveResourcePaths> | null;
+    error?: string;
+}
+/**
+ * 载入项目 → 扫设备 → 规划控制器 → 解析资源路径。
+ *
+ * 为什么不猜设备：interface.json 的 controller[] 已经声明了 Adb/Win32、窗口类名与标题正则、
+ * 截图与输入方法、以及识别缩放（display_short_side）——猜错不只是连错窗口，还会把 roi 与
+ * 模板的坐标系一起猜错。interface.json 的读法只有 src/interface/ 一份，别处不许再解析一遍。
+ */
+export declare function planProject(c: DaemonClient, dir: string, overrides?: {
+    controller?: string;
+    hwnd?: string;
+    gamepadHwnd?: string;
+    address?: string;
+    resource?: string;
+    manualTarget?: string;
+    cwd?: string;
+}): Promise<ProjectPlan>;
+/** `run` 的项目模式装配：入口解析、任务适用性、四级 override、agent 桥接。 */
+export interface ProjectRunInput {
+    /** 已规划的项目（`planProject` / REPL `connect project` 的产物） */
+    project: ProjectPlan;
+    /** interface 的 task 名或 pipeline 入口名（两者都认，与一次性 CLI 同规则） */
+    entry: string;
+    /** preset 名：取值覆盖 default_case（PI v2.3.0） */
+    presetName?: string | null;
+    /** CLI 按次取值：option 键 → case 名（select/switch 单值；checkbox 数组） */
+    optionCases?: Record<string, string | string[]>;
+    /** CLI 按次取值：option 键 → { 字段名: 原文 }（input / hotkey） */
+    optionFields?: Record<string, Record<string, string>>;
+    /** 用户 --override：对象=追加一层 / 数组=逐层追加（最高优先级），框架逐层继承 */
+    override?: Record<string, unknown> | Record<string, unknown>[];
+}
+/** 装配结果：要么可直接交给 `act.run`，要么是一份可行动的错误（不抛异常）。 */
+export type ProjectRunPrep = {
+    ok: true;
+    /** 直接交给 act.run 的参数（资源整链 + 入口 + 合成 override + agent 声明） */
+    args: Record<string, unknown>;
+    /** 解析后的 pipeline 入口名（interface task 名 → task.entry） */
+    entry: string;
+    taskName: string | null;
+    /** 生效记录：option=值（级别，via preset/default） */
+    applied: string[];
+    /** 需要人工注意的事项（option 无取值、agent 缺位等） */
+    warns: string[];
+} | {
+    ok: false;
+    code: string;
+    error: string;
+    hint?: string;
+    warns: string[];
+};
+/**
+ * 项目模式 run 的唯一装配点：一次性 CLI 与 REPL `run` 都走这里。
+ *
+ * 为什么必须共享：REPL 曾经只吃 `--override`、不叠 interface 的四级链，同一项目同一入口
+ * 在 REPL 里 option / preset / default_case 全部不生效——agent 主路径与一次性命令跑出两套
+ * 行为，而且不报错。入口解析、task 适用性、pretask/agent 警示也一并收口，避免第二份规则。
+ */
+export declare function prepareProjectRun(input: ProjectRunInput): ProjectRunPrep;

package/lib/types/runtime/keyframes.d.ts

@@ -0,0 +1,43 @@
+export declare const KF_SCHEMA = 1;
+export interface KfRecord {
+    id: string;
+    file: string;
+    sha256: string;
+    session: {
+        daemon: string;
+        gen: number;
+        kind: string | null;
+        target: string | null;
+    };
+    capturedAt: string;
+    captureSeq: number;
+    ctrlW: number;
+    ctrlH: number;
+    smallW: number | null;
+    smallH: number | null;
+    scale: number | null;
+    source: string;
+    note: string | null;
+}
+export interface KfManifest {
+    schema: number;
+    libraryId: string;
+    next: number;
+    frames: KfRecord[];
+}
+export type KfResolveStatus = 'available' | 'missing' | 'corrupt' | 'unsupported';
+export declare function defaultFramesDir(): string;
+/** 读 manifest。坏文件/未知 schema 明确报错，不默认为当前版。 */
+export declare function loadManifest(dir: string): {
+    manifest?: KfManifest;
+    error?: string;
+};
+/** 按完整 ID 帧解析：available 时给出经过完整性校验的路径；missing/corrupt/unsupported 各自可诊断。 */
+export declare function resolveFrame(dir: string, id: string): {
+    status: KfResolveStatus;
+    record?: KfRecord;
+    path?: string;
+    reason?: string;
+};
+/** list 用：一行人类可读摘要（与 --json 的 data 各自完整，不共用裁剪）。 */
+export declare function describeRecord(r: KfRecord): string;

package/lib/types/runtime/log-watch.d.ts

@@ -0,0 +1,28 @@
+export interface WatchOptions {
+    /** 要跟随的日志文件（绝对路径或相对 cwd） */
+    paths?: string[];
+    /** 条目级跟随：文件 / glob（含 * ? [ ]）/ 目录（取每 tick 最新 mtime 的一个文件）；
+     * 每次 tick 重新解析——日更文件名（跨午夜换新名）不丢尾巴。 */
+    entries?: string[];
+    /** 推送间隔（ms）：攒够这么久的行再一次性回调，避免逐行刷屏 */
+    intervalMs?: number;
+    /** 只推送匹配这些正则的行；缺省推全部 */
+    include?: RegExp[];
+    /** 丢弃匹配这些正则的行 */
+    exclude?: RegExp[];
+    /** 每次推送最多带多少行（超出折叠成一句「还有 N 行」） */
+    maxLinesPerFlush?: number;
+}
+export interface WatchHandle {
+    /** 停止跟随并返回累计统计 */
+    stop(): WatchStats;
+}
+export interface WatchStats {
+    /** 累计读到的原始行数 */
+    lines: number;
+    /** 其中被推送给调用方的行数 */
+    pushed: number;
+    /** 实际跟随成功的文件 */
+    files: string[];
+}
+export declare function watchLogs(opts: WatchOptions, onFlush: (lines: string[]) => void): WatchHandle;

package/lib/types/runtime/node-source.d.ts

@@ -0,0 +1,25 @@
+/** 读 `--xxx-file <path>`：`-` 读 stdin（一次性命令才有意义，REPL 里 stdin 是命令流） */
+export declare function readJsoncArg(spec: string, flag: string): {
+    value?: unknown;
+    error?: string;
+};
+/**
+ * 节点表识别：文件里是 `{ "<节点名>": {…}, … }` 而不是一个节点。
+ *
+ * 判据：**单节点必有 `recognition`**（V1 字符串或 V2 对象），且节点表的每个值都是对象、
+ * 至少有一个带 `recognition`。要求"至少一个带 recognition"是为了把 `{"action":{…}}` 这种
+ * **缺 recognition 的单节点**留给"缺字段"的报错——它看起来也像"所有值都是对象"。
+ * 这条只服务于报错文案（提示去用 `--node-name`），不构成"pipeline 文件"能力，也不改变执行路径。
+ */
+export declare function isNodeTable(value: Record<string, unknown>): boolean;
+/** `--node-file` → 单个节点 */
+export declare function readNodeFile(spec: string): {
+    node?: Record<string, unknown>;
+    error?: string;
+    hint?: string;
+};
+/** `--param-file` → recognition.param 那一层参数对象 */
+export declare function readParamFile(spec: string): {
+    param?: Record<string, unknown>;
+    error?: string;
+};

package/lib/types/runtime/ocr-model.d.ts

@@ -0,0 +1,8 @@
+export type OcrModelStatus = 'present' | 'missing';
+/**
+ * 资源链上是否能找到 OCR 模型。`modelName` 是节点/参数里声明的模型名（缺省空串）。
+ *
+ * 只查文件存在性、不解析 onnx：判断的是"框架会不会找到它"，不是"模型能不能跑"。
+ * 按框架的合并规则判：det 与 rec 可以来自不同段，rec 与 keys 必须同段。
+ */
+export declare function ocrModelStatus(resourceDirs: string[], modelName?: string | null): OcrModelStatus;

package/lib/types/runtime/pi-env.d.ts

@@ -0,0 +1,24 @@
+/**
+ * agent 子进程的 `PI_*` 环境变量（PI v2.5.0 起）。
+ *
+ * 为什么需要这一层：项目里的 agent 常用 `PI_CONTROLLER` / `PI_RESOURCE` / `PI_CLIENT_MAAFW_VERSION`
+ * 决定"选哪套资源、用哪种语言、能不能跑"。不注入时它们**不报错**——直接落到 agent 自带的默认值，
+ * 于是任务"跑通了，但不是同一个东西"。协议用规范性"应"要求 Client 注入，同时允许逐项缺省，
+ * 所以这里只填拿得到值的项：拿不到就不写，不编默认值。
+ *
+ * 出处：MaaFramework 5.14.2 `3.3-ProjectInterfaceV2协议` 环境变量表
+ * （pinned commit 8061d5bcaa3f07afcc1008795913663f64de46c8）。5.14.2 共 8 个变量；
+ * `PI_USER_DATA_DIR` 是 PI v2.11.0 / MaaFW 5.15.0 才引入的，本仓锁 5.14.2，**不要**加。
+ *
+ * 已知偏差：本工具不解析 i18n 的 `$` 键，所以 `PI_CONTROLLER` / `PI_RESOURCE` 里的
+ * label / description 可能是原始 `$key` 而不是展示文本（协议要求已解析）。项目没配
+ * `languages` 时不存在这个问题；i18n 落地后这里要跟着改。
+ */
+import type { LoadedInterface } from '../interface/load.js';
+export interface PiEnvInput {
+    loaded: LoadedInterface;
+    controllerName: string | null;
+    resourceName: string | null;
+}
+/** 生成要注入 agent 子进程的环境变量；返回空对象表示本次没有可注入的项。 */
+export declare function buildAgentEnv(i: PiEnvInput): Record<string, string>;

package/lib/types/runtime/pretask.d.ts

@@ -0,0 +1,53 @@
+import type { InterfacePretask, LoadedInterface } from '../interface/load.js';
+import { type OptionValueCtx } from '../interface/override.js';
+export interface PretaskOutcome {
+    name: string;
+    exec: string;
+    argv: string[];
+    code: number | null;
+    signal: string | null;
+    ms: number;
+    /** stdout+stderr 尾部（失败时给人看） */
+    tail: string;
+}
+export interface PretaskResult {
+    ok: boolean;
+    ran: PretaskOutcome[];
+    /** 因过滤/缺 exec 未执行的那些（带原因） */
+    skipped: string[];
+    notes: string[];
+    warns: string[];
+    error?: {
+        code: string;
+        message: string;
+        hint?: string;
+    };
+}
+export interface PretaskInput {
+    loaded: LoadedInterface;
+    controllerName: string | null;
+    resourceName: string | null;
+    optionCases?: Record<string, string | string[]>;
+    optionFields?: Record<string, Record<string, string>>;
+    /** 单条 pretask 的总时限；<=0 不限时。缺省 MAAFW_PRETASK_TIMEOUT_MS → 120s。 */
+    timeoutMs?: number;
+}
+/**
+ * 拼一条 pretask 的完整 argv（含末位 JSON）。**纯函数**：执行与参数构造分开，
+ * 参数形状可以离线单测——这部分错了就是"脚本收到了奇怪的参数但没人报错"。
+ */
+export declare function buildPretaskArgv(p: InterfacePretask, loaded: LoadedInterface, ctx: {
+    controllerName: string | null;
+    resourceName: string | null;
+    valueCtx: OptionValueCtx;
+}): {
+    argv: string[];
+    warns: string[];
+};
+/** pretask 超时缺省 120s：够"启动模拟器到可连"的常态，又兜住真正挂死的脚本。 */
+export declare const PRETASK_TIMEOUT_MS = 120000;
+/**
+ * 按声明序执行全部适用的 pretask。任一条失败即返回 ok:false（调用方据此中止连接）。
+ * 不抛异常：失败是一种结果，由调用方决定怎么呈现。
+ */
+export declare function runPretasks(input: PretaskInput): Promise<PretaskResult>;

package/lib/types/runtime/prune.d.ts

@@ -0,0 +1,4 @@
+export declare function pruneDir(dir: string, opts: {
+    keep: number;
+    suffix?: string;
+}): void;

package/lib/types/runtime/receipts.d.ts

@@ -0,0 +1,7 @@
+export declare function runsDir(): string;
+/** 回执文件名：`run-<ISO 时间戳去分隔符>-<entry>.json`（时间戳保留到毫秒，含 Z 时区标记）。
+ *  `now` 可注入：单测据此制造"同一毫秒撞名"，不必靠 sleep。 */
+export declare function receiptFileName(entry: string, now?: Date): string;
+export declare function writeRunReceipt(record: unknown, entry: string, now?: Date): {
+    path?: string;
+};

package/lib/types/runtime/reco-args.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 declare function roiOutOfBounds(roi: number[] | undefined, w: unknown, h: unknown): string | null;

package/lib/types/runtime/reco-verdict.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 识别未命中的原因与计数：**只有这一份判据**，一次性 CLI 与 REPL 都读它。
+ *
+ * 为什么单独立文件：miss 的病因直接决定下一步查什么（roi 里没有字 / expected 过滤掉了 /
+ * 分数不够 / 模板根本读不到），两个壳各推一遍必然分叉，而分叉的代价是把"expected 不匹配"
+ * 当成"模板读不到"去翻资源目录。
+ *
+ * 名字按**算法**分开给，不共用一套 OCR 口径：OCR 没有阈值这回事，模板匹配也没有 `expected`
+ * 这回事——共用口径就会编出不存在的病因。表以外的算法不猜，如实不给原因。
+ *
+ * OCR 的空结果还有一个同形病因：**模型没加载时框架不报错，只回空结果**。这条不在本文件的
+ * 职责内（要查文件系统），由调用方用 `runtime/ocr-model` 判好、以 `options.ocrModel` 传进来。
+ *
+ * 派生的前提是**先看 hit**：`noConfidence` 旧式判据（`threshold 建议为 null`）在 OCR 命中时
+ * 也成立（OCR 无数值分），不看 `ok` 就会把命中标成"无置信度"。
+ */
+export interface RecoResultLike {
+    ok?: boolean;
+    detail?: unknown;
+    /** 子进程捕获到的识别调用异常（此时 detail 为 null）；不是"未命中"，是"没跑成" */
+    error?: unknown;
+}
+/** 打分摘要（与 `suggestThreshold` 同源，跨层传结构而不传函数，避免 runtime → commands 反向依赖） */
+export interface ScoreSummary {
+    bestScore: number;
+    lowMatch: boolean;
+}
+/** 派生原因时需要调用方补的外部事实：本文件保持纯函数，文件系统检查由调用方做（runtime/ocr-model） */
+export interface MissOptions {
+    /** OCR 模型是否在资源链里；'missing' 时"空结果"先指向模型，不是 roi */
+    ocrModel?: 'present' | 'missing';
+}
+export interface MissDetail {
+    missReason: string | null;
+    rawCount: number | null;
+    filteredCount: number | null;
+    /** 识别调用本身报错（detail 缺失），不是"未命中"——渲染层要分开标，别打 [未中] */
+    failed: boolean;
+}
+export interface MissVerdict {
+    /** 回执级原因：所有未命中的原因一致时才有值 */
+    missReason: string | null;
+    /** 回执级去重后的原因（多例扫描可能不止一种） */
+    missReasons: string[];
+    /** 只在单例回执上给：多例求和会被读成"候选有多少个"，而它其实是逐例之和 */
+    rawCount: number | null;
+    filteredCount: number | null;
+    perResult: MissDetail[];
+}
+export declare function describeMisses(results: RecoResultLike[], type: string, scores: ScoreSummary | null, options?: MissOptions): MissVerdict;

package/lib/types/runtime/roi-compare.d.ts

@@ -0,0 +1,117 @@
+export type Roi = number[];
+/** 图像尺寸（未知时传 undefined：判不动就不判，不猜）。 */
+export interface FrameSize {
+    w?: unknown;
+    h?: unknown;
+}
+/** 允许说"分不出来"的并列带宽度：最优与次优分差小于它就不下结论。 */
+export declare const DEFAULT_GAP = 0.15;
+/** 一个候选位置。`origin` = 输入候选列表里的下标（输出可还原回输入）。 */
+export interface Candidate {
+    roi: Roi;
+    origin: number;
+}
+/** 被越界判据挡下的候选：**跳过并报出是谁**，不静默丢弃。 */
+export interface SkippedCandidate {
+    roi: Roi;
+    origin: number;
+    reason: string;
+}
+export interface CandidateSet {
+    candidates: Candidate[];
+    skipped: SkippedCandidate[];
+}
+/** 显式全套：每个元素就是 `[x,y,w,h]`。位置假设已经知道时用这条（**没有周期假设**）。 */
+export declare function fromRois(rois: unknown[], size?: FrameSize): CandidateSet;
+export interface Offset {
+    dx: number;
+    dy: number;
+}
+/** 相对一个基准位置的平移：x / y 分量都允许，列表允许非均匀（逐行不同的列距照样能表达）。 */
+export declare function fromOffsets(offsets: Offset[], base: Roi, size?: FrameSize): CandidateSet;
+/** 扫描轴：闭区间 `from..to`、步长 `step`（正数）。`from === to` 就是单点。 */
+export interface ScanAxis {
+    from: number;
+    to: number;
+    step: number;
+}
+export interface ScanSpec {
+    dx?: ScanAxis;
+    dy?: ScanAxis;
+}
+/** 一个轴的取值列表（单点恒为 1 个值）。 */
+export declare function axisValues(axis: ScanAxis | undefined): number[];
+export interface ScanInfo {
+    dx: ScanAxis | null;
+    dy: ScanAxis | null;
+    count: number;
+}
+export declare function scanInfo(spec: ScanSpec): ScanInfo;
+/** 发现模式：笛卡尔积 dx × dy 全部落在**同一个基准 roi** 上（不是判据，见命令层文案）。 */
+export declare function fromScan(spec: ScanSpec, base: Roi, size?: FrameSize): CandidateSet;
+/**
+ * `--scan` 语法解析：`dx=-160..160/8,dy=0`（逗号分段，轴是 dx / dy，值是 `<n>` 或 `<from>..<to>/<step>`）。
+ *
+ * 范围**必须带步长**：候选数是 (to−from)/step 线性增长、而耗时按候选数线性增长，
+ * 缺省步长等于让一次手滑变成几百个候选。
+ */
+export declare function parseScan(raw: string): {
+    value?: ScanSpec;
+    error?: string;
+};
+/** 一例识别的可比较部分。分数在详情内层（miss 时 best 为 null、all 仍带候选得分）。 */
+export interface Sample {
+    score: number | null;
+    ok: boolean;
+    box: number[];
+}
+export declare function sampleOf(result: {
+    ok?: unknown;
+    detail?: unknown;
+} | undefined): Sample;
+export interface CompareItem extends Sample {
+    roi: Roi;
+    origin: number;
+}
+export interface RankedItem extends CompareItem {
+    rank: number;
+    /** 落在"与最优的差 < gap"这条并列带里（带是按分数降序的前缀） */
+    inBand: boolean;
+}
+export type Verdict = 'HIT' | 'MISS' | 'AMBIGUOUS';
+export type CompareReason = 
+/** 唯一最优 */
+'unique'
+/** 与最优并列的 ≥ 2 个，分不开 */
+ | 'ambiguous'
+/** 最优没过 --threshold */
+ | 'below-threshold'
+/** 一个候选都没得分：目标在这张图上什么都没匹配上 */
+ | 'no-evidence'
+/** 没有候选（全部越界 / 空输入） */
+ | 'no-candidates';
+export interface CompareOutcome {
+    /** **只有拿得到分数的候选**，按分数降序编号 1..M（没有分数就没有名次） */
+    ranked: RankedItem[];
+    bestGap: number | null;
+    gap: number;
+    /** 与最优并列的 **rank** 列表（1 起） */
+    withinGap: number[];
+    verdict: Verdict;
+    reason: CompareReason;
+}
+/**
+ * 三态判据。优先序（**别重排**）：**先把没有证据的候选剔除，再谈歧义**——
+ *  ① 可评估候选 0 个 → 未命中；② 最优未过 threshold → 未命中；
+ *  ③ 与最优并列（|Δ| < gap）的 ≥ 2 → AMBIGUOUS；④ 否则唯一最优。
+ *
+ * "剔除"以**输出形状**兑现：`score: null` 的候选**不在 `ranked` 里**——没有分数就没有名次，
+ * 也进不了并列带（"没有证据"既不是 0 分，也不许被当成垫底来把最优衬托成唯一）。
+ * 剩下有证据的那些谁更优，才是这里回答的问题；"还有候选没被评估过"由调用方写进退出码（3）
+ * 与逐例回执，不改变这里的结论——一次 41 点的扫描里，落在背景上的点本来就拿不到相关系数
+ * （实测 `all: []`），把它们算成"分不出来"会淹没真正的信号。
+ */
+export declare function aggregate(items: CompareItem[], options?: {
+    gap?: number;
+    threshold?: number;
+}): CompareOutcome;

package/lib/types/runtime/session-forward.d.ts

@@ -0,0 +1,10 @@
+import { type CommandResult } from '../protocol.js';
+/**
+ * 从命令行 argv（含命令名）剥掉 `--session` 旗标本体，剩下的就是要送去会话执行的命令。
+ */
+export declare function stripSessionFlag(argv: string[]): string[];
+/**
+ * 转发一条命令到命名会话。返回的 CommandResult 就当作本命令的结果——
+ * 调用方（index.ts）直接 emit，不再二次加工。
+ */
+export declare function forwardToSession(name: string, argv: string[]): Promise<CommandResult>;