@windsland52/maafw-live 0.0.0-stage → 0.4.0

package/lib/types/client/daemon.d.ts

@@ -0,0 +1,86 @@
+/** 帧元数据（像素默认不出 daemon；预览帧落盘后给路径）。 */
+export interface FrameMeta {
+    seq: number;
+    t: number;
+    diff?: number;
+    w?: number;
+    h?: number;
+    preview?: string;
+}
+/** 帧流事件：画面变化/稳定，以及 Tasker 的节点级消息（按帧序对齐）。 */
+export interface StreamEvent {
+    type: string;
+    seq?: number;
+    t: number;
+    diff?: number;
+    node?: string | null;
+    msg?: string;
+    id?: number | string | null;
+}
+export interface DaemonEvents {
+    frames: FrameMeta[];
+    events: StreamEvent[];
+    /** 流级异常与通知：`stream_error`（设备掉线等）与 `stream_stopped`（控制器销毁导致流被停） */
+    errors: string[];
+    logs: string[];
+    /** 最新预览帧路径（daemon 收到 init 的 runDir 后写入 runDir/preview.png） */
+    preview: string | null;
+}
+/**
+ * daemon 推送的消息种类。`subscribe` 的回调按种类拿不同载荷：
+ * `frame` → FrameMeta、`event` → StreamEvent、`stream_error` → 错误文本、`stream_stopped` → 停流原因。
+ */
+export type DaemonMessageKind = 'frame' | 'event' | 'stream_error' | 'stream_stopped';
+/** `init` 的回执：daemon 身份与落点（客户端 spawn 后立刻握手的那一次）。 */
+export interface DaemonInit {
+    previewPath: string | null;
+    daemonId: string;
+    framesDir: string;
+    kfQuota: number;
+}
+/**
+ * 握手结果。**失败不抛异常**：老实现用 `id:-1` 发出去就不管，回执在分发链里被丢弃，
+ * init 失败无从得知；现在如实回报，同时不把"daemon 不回 init"变成调用方的致命错误
+ * （协议要求每条请求都有应答，但客户端不该因为对方没回一条就全盘不进）。
+ */
+export type DaemonInitResult = {
+    ok: true;
+    data: DaemonInit;
+} | {
+    ok: false;
+    error: string;
+};
+export interface DaemonClient {
+    readonly events: DaemonEvents;
+    /** spawn 后那次 `init` 握手的回执（framesDir / daemonId / kfQuota）；需要时才会 spawn daemon。 */
+    init(): Promise<DaemonInitResult>;
+    /** 发一条命令并等应答；超时会硬杀 daemon（下次调用自动重生）。 */
+    call<T = unknown>(cmd: string, args?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    /** daemon stderr + 非 JSON stdout 行（maa 原生日志，识别失败根因常在这）。 */
+    logTail(n?: number): string[];
+    /** 订阅帧/事件/流错误/流停止；返回退订函数。 */
+    subscribe(kind: DaemonMessageKind, cb: (message: unknown) => void): () => void;
+    stats(): {
+        calls: number;
+        restarts: number;
+        alive: boolean;
+        pid: number | null;
+        daemonPath: string;
+    };
+    /** 停流 + 断开 + 结束子进程。 */
+    close(): void;
+}
+export interface SpawnOptions {
+    /** 预览帧与临时产物的目录；默认 ~/.maafw-live */
+    runDir?: string;
+    /** 显式 daemon 路径；默认包内 lib/daemon/framed.mjs，可用 MAA_DAEMON 覆盖 */
+    daemonPath?: string;
+    /** 默认调用超时 */
+    timeoutMs?: number;
+    /** 关键帧库磁盘配额（字节，>0 生效；缺省 1GiB，daemon 侧 env MAAFW_KF_QUOTA_BYTES 亦可覆盖） */
+    kfQuotaBytes?: number;
+}
+export declare function defaultRunDir(): string;
+/** 定位 daemon 脚本：显式参数 → MAA_DAEMON → 包内 lib/daemon/framed.mjs。 */
+export declare function resolveDaemonPath(explicit?: string): string;
+export declare function spawnDaemon(options?: SpawnOptions): DaemonClient;

package/lib/types/commands/annotate.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from '../protocol.js';
+export declare const annotateCommand: Command;
+export declare const ANNOTATE_COMMANDS: Command[];

package/lib/types/commands/calibrate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 变化检测阈值校准：静止画面采帧，统计分块亮度差 / 全局位差率的噪声分布，
+ * 推荐 blockThresh / changeGlobal。校准期间画面必须静止（max≫p99 会警告重跑）。
+ */
+import { type Command } from '../protocol.js';
+export declare const calibrateCommand: Command;
+export declare const CALIBRATE_COMMANDS: Command[];

package/lib/types/commands/color.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 探色命令：ROI 实测主色/均值（RGB/HSV/灰度）——模型只选色不报色值。
+ *
+ * 为什么不靠模型读像素：色值必须来自实测（降采样小图按该帧捕获尺寸换算后的 ROI），
+ * 模型选完色后用 reco ColorMatch 出框（走已修好的参数透传链），出框与否是事实不是判断。
+ */
+import { type Command } from '../protocol.js';
+export declare const colorCommand: Command;
+export declare const COLOR_COMMANDS: Command[];

package/lib/types/commands/crop.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from '../protocol.js';
+export declare const cropCommand: Command;
+export declare const CROP_COMMANDS: Command[];

package/lib/types/commands/dispatch.d.ts

@@ -0,0 +1,22 @@
+import type { DaemonClient } from '../client/daemon.js';
+import { type GlobalFlags } from '../flags.js';
+import { type Command, type CommandResult } from '../protocol.js';
+export interface DispatchEnv {
+    /** 复用既有 daemon（命名会话 / REPL 注入）；一次性路径留空，由 withDaemon 现起现关。 */
+    client?: DaemonClient;
+    /** 命令看到的工作目录（一次性 CLI 是 --cwd 解析结果；会话侧是 serve 进程的 cwd） */
+    cwd: string;
+}
+export interface DispatchOutcome {
+    cmd: Command | null;
+    /** emit 需要的全局旗标（--json / --color 也在这里解析过） */
+    flags: GlobalFlags;
+    result: CommandResult;
+}
+/**
+ * 分发一条 argv（含命令名，即 `argv[0]` 是命令名）。
+ * 永不抛异常：BAD_ARGUMENTS / UNKNOWN_COMMAND / SESSION_REQUIRED / UNEXPECTED 都收敛成
+ * CommandResult——会话常驻进程不能因为一条坏命令挂掉。
+ */
+export declare function dispatchArgv(argv: string[], env: DispatchEnv): Promise<DispatchOutcome>;
+export declare function isDirectory(p: string): boolean;

package/lib/types/commands/env.d.ts

@@ -0,0 +1,21 @@
+import { type Command } from '../protocol.js';
+/**
+ * qualifier 归一化：同一个 pre-release 在两个生态里写法不同，比较前先落到同一形态。
+ *   `-beta.1` / `beta.1` / `beta1` / `b1` → `b1`；`alpha` → `a`；`rc` / `pre` / `preview` → `rc`；
+ *   `.dev1` → `dev1`；`.post1` → `post1`；没有后缀 → 空串（正式版）。
+ * 认不出的后缀原样保留：宁可把它判成不一致，也不要凭猜测把两个不相干的后缀当同一个。
+ */
+export declare function normalizeQualifier(qualifier: string): string;
+/**
+ * 把精确版本拆成 release 线与**归一化后的** qualifier：`5.15.0b1` → `5.15.0` + `b1`，
+ * `5.15.0-beta.1` 同样落到 `5.15.0` + `b1`。
+ *
+ * 对账要分别看两段：release 线不同是换了个版本；release 相同而 qualifier 不同是**同一条线上的
+ * 另一份构建**（正式版 vs 预发布、b1 vs rc1 都是）。只比字符串会把两种拼写当不一致；
+ * 只比 release 又会把正式版与预发布报成一致——两头都错。
+ */
+export declare function splitRelease(version: string): {
+    release: string;
+    qualifier: string;
+} | null;
+export declare const envCommand: Command;

package/lib/types/commands/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 命令注册表。
+ *
+ * 只注册**已经实现且能跑通**的命令。未实现的能力不在这里挂空壳，也不进 `--help`——
+ * 挂空壳会让 `maafw <cmd>` 的失败原因从「没这个命令」变成「没实现」，技能无法区分；
+ * help 描述未来就会过期撒谎，只描述现状。
+ */
+import type { Command } from '../protocol.js';
+/** 展示顺序：探针 → 运行时/设备 → 输入 → 识别 → 验真 → 探色 → 裁剪 → SoM → 校准 → 关键帧 → timing → 会话 → skill 自检。 */
+export declare const COMMANDS: Command[];
+export declare function findCommand(name: string): Command | undefined;
+/** 未知命令时给出「最接近的名字」建议（编辑距离），避免用户猜 */
+export declare function suggestCommand(name: string, maxDistance?: number): string | undefined;

package/lib/types/commands/input.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 输入注入命令：click / swipe / key / text。
+ *
+ * 全部经 maafw 控制器本体注入（不直接调 adb），坐标是控制器分辨率空间——默认短边 720，
+ * 与 pipeline 里 roi / 模板图同一坐标系。要设备就必须给 --project（推荐）或 --kind。
+ */
+import { type Command } from '../protocol.js';
+export declare const clickCommand: Command;
+export declare const swipeCommand: Command;
+export declare const keyCommand: Command;
+export declare const keysCommand: Command;
+export declare const pressCommand: Command;
+export declare const dbclickCommand: Command;
+export declare const scrollCommand: Command;
+export declare const moveCommand: Command;
+export declare const textCommand: Command;
+export declare const INPUT_COMMANDS: Command[];

package/lib/types/commands/kf.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 关键帧命令：kf status / kf promote / kf list / kf resolve。
+ *
+ * 升格（promote）是 daemon 内存操作——从 L0 缓存取原图落盘并登记，必须在捕获它的那个
+ * daemon 会话里做（ REPL 里 stream/输入/run 之后立刻升格，"看到即升格，不攒到最后"）。
+ * list / resolve 是纯离线文件操作，不依赖 daemon 存活（契约 §4.1）。
+ */
+import { type Command } from '../protocol.js';
+export declare const kfCommand: Command;
+export declare const KF_COMMANDS: Command[];

package/lib/types/commands/probe.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `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 { type Command } from '../protocol.js';
+export declare const screencapProbeCommand: Command;

package/lib/types/commands/reco.d.ts

@@ -0,0 +1,27 @@
+import { type Command } from '../protocol.js';
+/** threshold 起点建议（maafw-pipeline 技能口径）：实测最高置信度 − 0.1 留余量，换场景会掉。
+ * 得分在识别详情内层（detail.detail.best/all——miss 时 best 为 null，all 仍带各候选得分）；
+ * 无数值得分的类型（OCR 等）返回 null，不编造。低于 0.5 视为模板与画面不匹配：
+ * 未命中不是调低阈值的理由，建议不适用。 */
+export interface ThresholdSuggestion {
+    bestScore: number;
+    suggest: number | null;
+    lowMatch: boolean;
+}
+export declare function suggestThreshold(results: Array<{
+    ok: boolean;
+    detail?: unknown;
+}>): ThresholdSuggestion | null;
+/**
+ * OCR 模型名：框架按 `model/ocr/<name>/` 找模型，缺省空串 = 直接放在 `model/ocr/` 下。
+ * 优先级：资源 dump（V2 缺省也填满）> 手写节点的 V2 param / V1 顶层 model > `--type` 的 `--param`。
+ */
+export declare function ocrModelName(node: Record<string, unknown> | undefined, param: Record<string, unknown> | undefined, dump: {
+    recognition?: {
+        param?: {
+            model?: unknown;
+        };
+    };
+} | undefined): string | undefined;
+export declare const recoCommand: Command;
+export declare const RECO_COMMANDS: Command[];

package/lib/types/commands/repl.d.ts

@@ -0,0 +1,10 @@
+import { type Command } from '../protocol.js';
+/** repl `reco <type> k=v …` 的参数解析：沿用既有惯例（数字转 number），列表参数转数组。 */
+export declare function recoParam(tokens: string[]): Record<string, unknown>;
+export declare const replCommand: Command;
+/**
+ * REPL 行 → argv 的方言翻译表。翻不了（REPL 私有命令）返回 null，调用方走 line 路径。
+ * 这是会话"两个实现漂移"的止血带：翻译完进的是 dispatchArgv，与一次性 CLI 同一份
+ * 实现——`run T --option` 在 --cmd 里从此生效（P0-3）。
+ */
+export declare function replToArgv(line: string): string[] | null;

package/lib/types/commands/roi-check.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from '../protocol.js';
+export declare const roiCheckCommand: Command;
+export declare const ROI_CHECK_COMMANDS: Command[];

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

@@ -0,0 +1,3 @@
+import { type Command } from '../protocol.js';
+export declare const roiCompareCommand: Command;
+export declare const ROI_COMPARE_COMMANDS: Command[];

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

@@ -0,0 +1,66 @@
+import { type Command, type CommandResult } from '../protocol.js';
+import { type SessionOptions } from '../runtime/session.js';
+/** 连接类选项：凡是要设备的命令都接受同一组，保证"怎么连"只有一套说法。 */
+export declare const CONNECT_OPTIONS: {
+    project: {
+        type: "string";
+    };
+    controller: {
+        type: "string";
+    };
+    resource: {
+        type: "string";
+    };
+    hwnd: {
+        type: "string";
+    };
+    address: {
+        type: "string";
+    };
+    kind: {
+        type: "string";
+    };
+    target: {
+        type: "string";
+    };
+    'short-side': {
+        type: "string";
+    };
+    'long-side': {
+        type: "string";
+    };
+    raw: {
+        type: "boolean";
+    };
+    'no-pretask': {
+        type: "boolean";
+    };
+};
+/**
+ * 路径参数的解析基准：调用方给的目录就是 `ctx.cwd`（CLI 的 --cwd），不是 process.cwd()。
+ * 只处理**纯路径参数**（--project / --resource-dir / --out / --image / --frames-dir 等）——
+ * `--resource` 同时是"资源名"，能不能按路径解析要留给 resolveResourcePaths（名字优先），
+ * 所以它在 SessionOptions.cwd 里透传，不在这里 resolve。
+ */
+export declare function argPath(ctx: {
+    cwd: string;
+}, v: string | undefined): string | undefined;
+export declare function sessionOptions(ctx: {
+    values: Record<string, unknown>;
+    cwd: string;
+}): SessionOptions;
+/** daemon 抛出的错误翻译成结构化失败。退出码按错误的**性质**分：
+ * 前置缺失（脚本找不到 / 会话规划失败）退 4；运行时故障（调用超时、进程退出、发送失败）退 1——
+ * 同一个 code 在所有路径退同一个码，agent 才不会按"缺环境"去查"daemon 卡住"。 */
+export declare function daemonFail(e: unknown, hint?: string): CommandResult;
+export declare const probeCommand: Command;
+export declare const deviceCommand: Command;
+export declare const connectCommand: Command;
+export declare const disconnectCommand: Command;
+export declare const screencapCommand: Command;
+export declare const eventsCommand: Command;
+export declare const frameCommand: Command;
+export declare const waitCommand: Command;
+export declare const runCommand: Command;
+export declare const stopCommand: Command;
+export declare const RUNTIME_COMMANDS: Command[];

package/lib/types/commands/skill.d.ts

@@ -0,0 +1,17 @@
+import { type Command } from '../protocol.js';
+/** 包内 skill 目录：lib/commands/ → <包根>/skills/maafw-live（本地 checkout 同构） */
+export declare function skillPayloadDir(): string;
+export interface SkillFileStatus {
+    path: string;
+    status: 'same' | 'different' | 'missing' | 'extra';
+    /** different 时的成因提示；行尾差异常来自跨平台工具改写，值得单独指出 */
+    note?: string;
+    bytes?: number;
+    sha256?: string;
+}
+/**
+ * 逐文件比对（纯函数，单测直接喂两个目录）。只比字节：任何不同都是 different，
+ * 但在**仅行尾不同**（CRLF ↔ LF）时补一条 note——那不是内容分叉，是工具改写。
+ */
+export declare function compareSkillTrees(payload: string, target: string): SkillFileStatus[];
+export declare const skillCommand: Command;

package/lib/types/commands/timing.d.ts

@@ -0,0 +1,64 @@
+/**
+ * timing：从帧流与节点事件反推 pipeline 的 delay / timeout 建议值。
+ *
+ * 做法：自动开流 → 跑任务（--runs n 次采样）→ 对齐两类时间线——
+ *  - 节点时长（record.nodes）→ 节点级 timeout 建议（P95 × 1.5 余量）
+ *  - 节点完成后的画面稳定时间（完成事件到下一个 stable 事件的时距）→ post-delay /
+ *    wait_freezes 建议；下一节点先于 stable 开始则标"未稳定"（连续动画/识别窗口过紧）。
+ * 分布口径：建议值只取成功 run（失败 run 的时长是提前终止的，对 timeout 建议是误导）；
+ * 单次采样退化为 P50=P95=该值，与历史单次行为逐字段一致。
+ */
+import { type Command } from '../protocol.js';
+interface TimedNode {
+    name: string;
+    ms: number;
+    status: string;
+    settle: number | null;
+    nextBeforeStable: boolean;
+}
+/** 单次采样的产物：一次 run 的任务结果 + 该 run 事件区间内的对齐分析 */
+export interface RunSample {
+    index: number;
+    ok: boolean;
+    durationMs: number;
+    nodes: TimedNode[];
+    events: number;
+}
+export interface NodeStat {
+    name: string;
+    status: string;
+    /** 成功 run 中该节点出现的 run 数（少于成功总数 = 有分支/跳过） */
+    runs: number;
+    /** 总执行次数——同名节点在同一 run 内可能重复（重试/JumpBack/Next 环），
+     * 分布统计按全部出现算，丢掉重复会漏掉真正的慢样本 */
+    occurrences: number;
+    msP50: number;
+    msP95: number;
+    settleP50: number | null;
+    settleP95: number | null;
+    settleSamples: number;
+    nextBeforeStable: boolean;
+}
+export interface TimingAggregate {
+    successful: number;
+    failed: number;
+    durationP50: number;
+    durationP95: number;
+    /** 各 run 最长节点时长的 P95——建议值的基准（覆盖"最慢节点"这一任务级口径） */
+    maxNodeP95: number;
+    /** 各 run 最长稳定时间的 P95；全无 stable 样本时为 null */
+    maxSettleP95: number | null;
+    nodeStats: NodeStat[];
+    suggest: {
+        nodeTimeoutMs: number;
+        taskTimeoutMs: number;
+        postDelayMs: number | null;
+    };
+}
+/** 最近邻秩百分位：sorted 升序；n=1 时任意 p 返回该值，n 小时偏保守端（P95 取最大） */
+export declare function percentile(values: number[], p: number): number;
+/** 跨 run 聚合（纯函数，单测直断言）：节点统计与建议值都只算成功样本 */
+export declare function aggregateTiming(samples: RunSample[]): TimingAggregate;
+export declare const timingCommand: Command;
+export declare const TIMING_COMMANDS: Command[];
+export {};

package/lib/types/commands/version.d.ts

@@ -0,0 +1,3 @@
+/** `maafw-live version` —— CLI 与运行环境版本。技能用它做版本对齐；`--check` 对 registry 查有没有新版。 */
+import { type Command } from '../protocol.js';
+export declare const versionCommand: Command;

package/lib/types/exec.d.ts

@@ -0,0 +1,31 @@
+export interface ExecResult {
+    ok: boolean;
+    /** 进程退出码；被信号杀死或启动失败时为 null */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    /** 启动失败的原因（ENOENT 等） */
+    spawnError?: string;
+}
+export interface ExecOptions {
+    timeout?: number;
+    cwd?: string;
+    /** 传入 stdin 的内容 */
+    input?: string;
+    /** 内部用：把参数按原样交给子进程（实现 cmd 的引号规则时需要，见 run()） */
+    verbatim?: boolean;
+}
+/**
+ * 执行外部命令。
+ *
+ * Windows 上 `.cmd` / `.bat`（npm、npx、pnpm）不是可执行文件：execFile 直接跑会**同步抛 EINVAL**
+ * （Node 对 CVE-2024-27980 的修复，本模块曾因此让 `env` 在只缺 adb 的机器上整条失败），
+ * 所以先 `where` 解析出可执行路径，再经 `ComSpec` 执行。而 cmd 的引号规则有讲究：`/s` 会剥掉最外层
+ * 引号，所以命令串要**整体再包一层引号**并配 `windowsVerbatimArguments`——实测
+ * `cmd /d /s /c ""C:\Program Files\nodejs\npm.cmd" --version"` 是唯一能跑通的拼法。
+ * 不直接用 `shell: true`：给 shell 传参会触发 `DEP0190` 弃用警告，且"命令不存在"会退化成
+ * "cmd 跑起来了但退出 1"（本地化报错，判不准）。
+ */
+export declare function run(bin: string, args?: string[], opts?: ExecOptions): Promise<ExecResult>;
+/** 取首行有效输出，供「版本号探测」这类场景用 */
+export declare function firstLine(s: string): string;

package/lib/types/flags.d.ts

@@ -0,0 +1,62 @@
+export declare const GLOBAL_OPTIONS: {
+    json: {
+        type: "boolean";
+    };
+    'dry-run': {
+        type: "boolean";
+    };
+    yes: {
+        type: "boolean";
+    };
+    'no-interactive': {
+        type: "boolean";
+    };
+    'no-color': {
+        type: "boolean";
+    };
+    cwd: {
+        type: "string";
+    };
+    limit: {
+        type: "string";
+    };
+    verbose: {
+        type: "boolean";
+    };
+    help: {
+        type: "boolean";
+        short: string;
+    };
+    version: {
+        type: "boolean";
+        short: string;
+    };
+    /** 把命令转发到命名会话的常驻 daemon（`repl --session <name>` 起的那个） */
+    session: {
+        type: "string";
+    };
+};
+export interface GlobalFlags {
+    json: boolean;
+    /** 预留位：当前没有"只计算不落盘"的实现，值不被消费 */
+    dryRun: boolean;
+    /** 预留授权位：当前版本没有确认步骤，值不被消费 */
+    yes: boolean;
+    /** 预留门控位：当前版本没有交互式提问，值不被消费 */
+    interactive: boolean;
+    color: boolean;
+    cwd: string;
+    /** 预留位：当前没有输出条数上限，值不被消费 */
+    limit: number;
+    /** 预留位：当前没有详细输出，值不被消费 */
+    verbose: boolean;
+    help: boolean;
+    version: boolean;
+}
+/**
+ * 从 parseArgs 的 values 推导全局标志。
+ *
+ * `--no-color` 只关闭颜色；未指定时按 TTY 自动判断（管道里自动无色）。
+ * 注意不能用 NO_COLOR 环境变量以外的方式覆盖显式传入的值。
+ */
+export declare function readGlobalFlags(values: Record<string, unknown>, cwd: string): GlobalFlags;

package/lib/types/image.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 纯 JS 图像工具：复用 daemon 里那套无依赖 PNG 编解码（不做第二份实现）。
+ *
+ * daemon（daemon/framed.mjs）本来就带 PNG 解码 / 缩放 / 编码 —— 它要在没有 native 依赖的
+ * 前提下处理帧 —— 但只在子进程里用。这里用非字面量说明符动态 import 取它的 __test 导出：
+ * 避免为一个 .mjs 引入声明文件、把构建链复杂化，同时用下面的接口把契约钉死。
+ *
+ * 与 daemon 帧流共用同一条降采样路径，因此"面板预览看到的缩放"和"识别用的缩放"不会分叉。
+ */
+/** PNG Buffer 的尺寸。 */
+export declare function pngSize(buf: Buffer): Promise<{
+    w: number;
+    h: number;
+}>;
+/** 按"长边不超过 maxSide"缩放 PNG（只缩不放，原图更小时原样返回）。 */
+export declare function scalePngLongSide(buf: Buffer, maxSide: number): Promise<Buffer>;
+/**
+ * 按矩形裁一块出来（控制器分辨率坐标系，越界自动夹紧）。
+ *
+ * 面板的"模板匹配即时校验"用它：把人框的这块裁成模板图，再交给识别去比对 —— 因此这一步
+ * 必须与帧流/识别走同一条解码路径，不能各自实现（否则裁出来的像素与识别看到的不是同一份）。
+ */
+export declare function cropPng(buf: Buffer, rect: [number, number, number, number]): Promise<Buffer>;
+/** data URL → PNG Buffer；非图片 data URL 返回 null。 */
+export declare function dataUrlToPng(dataUrl: string): Buffer | null;
+/** PNG Buffer → data URL（面板侧统一 data:image/png）。 */
+export declare function pngToDataUrl(buf: Buffer): string;

package/lib/types/index.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<number>;

package/lib/types/interface/hotkey.d.ts

@@ -0,0 +1,36 @@
+/**
+ * hotkey 占位符 → 当前控制器的虚拟按键码（PI v2.8.0+）。
+ *
+ * 协议只给规则、不给表：`{名称}` / `{名称}.primary` / `{名称}.modifier1` / `{名称}.modifier2`
+ * 要替换成"**当前控制器 type** 支持的虚拟按键码"，且"映射规则应与 ClickKey、KeyDown 等动作所用
+ * 键码表一致"（MaaFW 5.14.2 `3.3-ProjectInterfaceV2协议`，pinned commit 8061d5bc）。
+ *
+ * 这里四张表的数值是各 OS **公开的键码常量**，不是谁发明的东西：
+ * - `Win32`  → Windows Virtual-Key Codes（`VK_*`，见 winuser.h）
+ * - `Adb`    → Android `KeyEvent`（`KEYCODE_*`）
+ * - `MacOS`  → Carbon `Events.h`（`kVK_*`，ANSI 键盘物理位置）
+ * - `WlRoots`/`Linux` → Linux `input-event-codes.h`（`KEY_*`/evdev）
+ *
+ * 取值与 MXU 的实现交叉核对过（MXU 是 AGPL-3.0，本仓 MIT：**只核数值，不搬代码**）。
+ * 键名按 MXU 的持久化约定规范化（大写、`+` 连接、末段为主键），因为它就是协议里"人类可读
+ * 快捷键字符串"的实际来源之一。
+ */
+/** 一张表：规范化键名 → 虚拟按键码 */
+export type HotkeyTable = Record<string, number>;
+/** 按控制器 **type** 取表（不是 name）。没有表的类型返回 null——调用方要告警，不能退回 Win32 猜。 */
+export declare function hotkeyTableFor(controllerType: string | null, useWin32VkCode?: boolean): HotkeyTable | null;
+/** "Ctrl+Shift+A" → { primary: "A", modifiers: ["Ctrl","Shift"] }；末段为主键。 */
+export declare function splitHotkeyCombo(value: string): {
+    primary: string;
+    modifiers: string[];
+};
+/**
+ * 把一个 hotkey 字段解析成四种占位符的取值。
+ *
+ * 缺修饰键不是错（单键 "E" 本来就没有修饰键），补 0 = 无按键；**主键查不到是错**——
+ * 写个 0 进去等于"按了空键"，任务会静默点不动。
+ */
+export declare function resolveHotkeyTokens(fieldName: string, raw: string, table: HotkeyTable): {
+    tokens: Record<string, number>;
+    error?: string;
+};

package/lib/types/interface/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 项目声明（interface.json / ProjectInterface v2）的窄解析与连接规划。
+ *
+ * 这是"认识项目"的唯一一份实现：控制器声明 → daemon connect 参数、
+ * 资源声明 → resource 目录、task 声明 → run 入口解析、
+ * option/preset → pipeline_override 四级合并链。
+ */
+export { parseJsonc } from './jsonc.js';
+export { loadInterface, findInterfaceFile, type DisplayDecl, type GamepadDecl, type InterfaceController, type InterfaceOption, type InterfacePreset, type InterfaceProblem, type InterfaceResource, type InterfaceTask, type LoadedInterface, type OptionCase, type Win32Decl, } from './load.js';
+export { planController, resolveResourcePaths, type ControllerPlan, type DeviceLike, type PlanOverrides, type ResourcePlan, } from './plan.js';
+export { computePipelineOverride, appendOverride, type OverrideInput, type OverrideResult } from './override.js';

package/lib/types/interface/jsonc.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 容错 JSON：真实项目的 interface.json 带 `//` 注释（官方解析器基于 meojson），
+ * strict JSON.parse 会直接拒绝，因此先做最小脱敏——字符串外的注释与尾随逗号去掉。
+ *
+ * 取舍：只做这两件**最小**的事，不做单引号 / 无引号键 / 多行字符串那类扩展——
+ * 越是"看起来像 JSON"的输入，越容易被静默改写成作者没写的意思。
+ * 另：开头的 BOM（Windows 记事本等会写）先剥掉，它会让 JSON.parse 报 "Unexpected token"。
+ */
+export declare function parseJsonc(text: string): unknown;