@windsland52/maafw-live 0.3.0 → 0.4.0

package/lib/runtime/signal-guard.js

@@ -0,0 +1,35 @@
+/**
+ * run 阻塞期信号处理（审计 #6/#9）：Ctrl-C / SIGTERM 时不许让 daemon 里的任务裸跑。
+ *
+ * 第一下：向 daemon 发 run_stop（post_stop），run 回执照常落盘，退出码走 128+signo
+ * （SIGINT=130 / SIGTERM=143）。第二下：直接退出——第一次没杀掉说明 daemon 已不应答，
+ * 再等没有现场可留（daemon 侧另有 onHostGone 兜底清 agent 树）。
+ *
+ * 为什么抽出来：Windows 没法跨进程投递 Ctrl-C，内联在命令里就没法测；
+ * process.emit('SIGINT') 会同步触发监听，单测只验"旗标立了、run_stop 发了"。
+ */
+import { EXIT } from '../protocol.js';
+/** 挂载信号守卫；`runStop` 是"给 daemon 发停止"的那个异步调用。 */
+export function installRunSignalGuard(runStop) {
+    let code = 0;
+    const on = (c) => () => {
+        if (code) {
+            process.exit(c);
+        } // 第二下：daemon 不应答，不再等
+        code = c;
+        void runStop().catch(() => { });
+    };
+    const sigint = on(EXIT.SIGINT);
+    const sigterm = on(EXIT.SIGTERM);
+    process.on('SIGINT', sigint);
+    process.on('SIGTERM', sigterm);
+    return {
+        get code() { return code; },
+        restore() {
+            process.off('SIGINT', sigint);
+            process.off('SIGTERM', sigterm);
+            return code;
+        },
+    };
+}
+//# sourceMappingURL=signal-guard.js.map

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

@@ -1,2 +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

@@ -6,7 +6,7 @@
  * help 描述未来就会过期撒谎，只描述现状。
  */
 import type { Command } from '../protocol.js';
-/** 展示顺序：探针 → 运行时/设备 → 输入 → 识别 → 探色 → 裁剪 → SoM → 校准 → 关键帧 → timing → 会话 → skill 自检。 */
+/** 展示顺序：探针 → 运行时/设备 → 输入 → 识别 → 验真 → 探色 → 裁剪 → SoM → 校准 → 关键帧 → timing → 会话 → skill 自检。 */
 export declare const COMMANDS: Command[];
 export declare function findCommand(name: string): Command | undefined;
 /** 未知命令时给出「最接近的名字」建议（编辑距离），避免用户猜 */

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

@@ -1,10 +1,3 @@
-/**
- * 识别单测：maafw-live reco。
- *
- * 走 daemon 的 reco_test —— 它把识别放进一次性子进程执行（beta 绑定在无效模板上会原生崩溃，
- * 子进程炸掉只损失一次测试，不带走调用方）。支持阈值扫描：一次调用给出阈值-命中曲线。
- * 项目模式下资源目录从 interface.json 解析，避免手写路径与项目声明不一致。
- */
 import { type Command } from '../protocol.js';
 /** threshold 起点建议（maafw-pipeline 技能口径）：实测最高置信度 − 0.1 留余量，换场景会掉。
  * 得分在识别详情内层（detail.detail.best/all——miss 时 best 为 null，all 仍带各候选得分）；
@@ -19,5 +12,16 @@ 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

@@ -1,2 +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

@@ -32,15 +32,33 @@ export declare const CONNECT_OPTIONS: {
     raw: {
         type: "boolean";
     };
+    'no-pretask': {
+        type: "boolean";
+    };
 };
-export declare function sessionOptions(values: Record<string, unknown>): SessionOptions;
-/** daemon 抛出的错误一律翻译成结构化失败，不让堆栈进模型上下文。 */
+/**
+ * 路径参数的解析基准：调用方给的目录就是 `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;

package/lib/types/flags.d.ts

@@ -31,6 +31,10 @@ export declare const GLOBAL_OPTIONS: {
         type: "boolean";
         short: string;
     };
+    /** 把命令转发到命名会话的常驻 daemon（`repl --session <name>` 起的那个） */
+    session: {
+        type: "string";
+    };
 };
 export interface GlobalFlags {
     json: boolean;

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

@@ -8,4 +8,4 @@
 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, mergeOverride, type OverrideInput, type OverrideResult } from './override.js';
+export { computePipelineOverride, appendOverride, type OverrideInput, type OverrideResult } from './override.js';

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

@@ -21,6 +21,12 @@ export interface GamepadDecl {
     gamepadType?: string;
     screencap?: string;
 }
+/** MacOS 控制器声明（PI schema：`macos.{title_regex,screencap,input}`） */
+export interface MacOSDecl {
+    titleRegex?: string;
+    screencap?: string;
+    input?: string;
+}
 export interface InterfaceController {
     name: string;
     /** Adb / Win32 / Gamepad / MacOS / PlayCover / Linux */
@@ -28,10 +34,23 @@ export interface InterfaceController {
     display?: DisplayDecl;
     win32?: Win32Decl;
     gamepad?: GamepadDecl;
+    macos?: MacOSDecl;
     /** v2.2.0：在 resource.path 之后追加加载的资源目录（相对 interface.json 所在目录） */
     attachResourcePath: string[];
     /** v2.3.0：控制器级配置项名单（override 链第三级） */
     option?: string[];
+    /** Linux 控制器声明（PI schema）：`use_win32_vk_code` 决定服务端按 Win32 VK 还是 evdev 解释键码；
+     *  `screencap`/`input`/`pipewire_source` 等交给 daemon 按 maa-support-extension 规则组 config JSON */
+    linux?: {
+        useWin32VkCode?: boolean;
+        screencap?: string;
+        input?: string;
+        pipewireSource?: string;
+    };
+    /** `permission_required`（schema 字段）：控制器需要管理员/root 权限运行——连接失败时的排查提示 */
+    permissionRequired?: boolean;
+    /** 原始条目（未裁剪）：PI_CONTROLLER 要传"被选中那条的完整对象"，不能按本工具用到的字段重建 */
+    raw?: unknown;
 }
 export interface InterfaceResource {
     name: string;
@@ -41,6 +60,10 @@ export interface InterfaceResource {
     controllers: string[];
     /** v2.3.0：资源级配置项名单（override 链第二级） */
     option?: string[];
+    /** v2.6.0：资源完整性校验值（仅加载 path 后的 MaaResourceGetHash；不匹配只警告不阻断） */
+    hash?: string;
+    /** 原始条目（未裁剪）：PI_RESOURCE 要传"被选中那条的完整对象" */
+    raw?: unknown;
 }
 export interface InterfaceTask {
     name: string;
@@ -52,6 +75,25 @@ export interface InterfaceTask {
     resource?: string[];
     /** 配置项键名（按展示顺序）；对应 InterfaceOption 字典的键 */
     option?: string[];
+    /** task 级覆盖：键=节点名、值=字段覆盖（与 case 级同构，但**没有** `{字段名}` 替换语义） */
+    pipelineOverride?: Record<string, unknown>;
+}
+/** input option 的输入字段：`{name}` 占位引用的就是这里的 `name`。 */
+export interface InputField {
+    name: string;
+    /** 初始值。协议只把它定义成"默认值"，没说 Client 在无人输入时该不该拿它替换——本工具用。 */
+    default?: string;
+    /** 替换时的转型类型；枚举只有 `string` / `int` / `bool`（**没有** float） */
+    pipelineType?: string;
+    /** 正则校验（协议把它归给 Client 的输入校验职责） */
+    verify?: string;
+    /** `password`（v2.10.0）：值为密码——不得把原文写进输出/日志，与 `default` 互斥（schema 已禁） */
+    password?: boolean;
+}
+/** hotkey option 的快捷键字段（v2.8.0）：持久化值是人类可读字符串，如 `E` / `Ctrl+A`（末段为主键）。 */
+export interface HotkeyField {
+    name: string;
+    default?: string;
 }
 /** option 字典条目：switch/select/checkbox 的 case 携带 pipeline_override。 */
 export interface OptionCase {
@@ -64,11 +106,26 @@ export interface InterfaceOption {
     name: string;
     type: string;
     cases: OptionCase[];
+    /**
+     * input / hotkey 专用的覆盖模板：**整个 option 一份**，值里含 `{字段名}` 占位。
+     *
+     * 与 `cases[].pipeline_override` 是协议里两处不同字段（select/switch/checkbox 走 case，
+     * input/hotkey 走这里）。只建模前者会永远读不到后者的模板。
+     */
+    pipelineOverride?: Record<string, unknown>;
+    /** input 的输入字段（`inputs[]`） */
+    inputs?: InputField[];
+    /** hotkey 的快捷键字段（`hotkeys[]`，v2.8.0）——容器不是 inputs */
+    hotkeys?: HotkeyField[];
     /** 初始选中：switch/select 单 case 名；checkbox 为 case 名数组 */
     defaultCase?: string | string[];
     /** 适用性过滤（v2.3.1：不满足的 option 不得产生 pipeline_override） */
     controller?: string[];
     resource?: string[];
+    /** checkbox 最少选中数（v2.10.1，默认 0） */
+    minCount?: number;
+    /** checkbox 最多选中数（v2.10.1，缺省 = 不限） */
+    maxCount?: number;
 }
 /** preset：任务与 option 取值的快照（v2.3.0），应用时覆盖 default_case。 */
 export interface InterfacePreset {
@@ -80,10 +137,30 @@ export interface InterfacePreset {
     }>;
 }
 /** PI `agent` 声明：宿主侧子进程（如 uv run python agent/main.py），经 agent 协议注册 custom
- * action / recognition。maa-node 绑定未暴露 AgentClient 桥接——本工具只能诊断，不能 spawn。 */
+ * action / recognition。daemon 的 run 会 spawn 并桥接（bind_resource + sink 注册 + connect）。 */
 export interface InterfaceAgent {
     exec: string;
     args: string[];
+    /**
+     * `identifier`（schema 字段）：连接标识符——项目声明固定值时 daemon 把它原样交给
+     * `Client` 并追加为子进程末参（socket 同名）。注意语义是"上次断线可重连"，不是
+     * "本次独占"：固定 identifier 残留旧 socket 时 connect 会等满超时才败（上游已知坑）。
+     */
+    identifier?: string;
+}
+/** PI `pretask` 声明（v2.7.0+）：连接 Controller **之前**跑一次的子进程。 */
+export interface InterfacePretask {
+    name?: string;
+    /** 必填：可执行程序（字符串，不是数组） */
+    exec: string;
+    /** 追加在 exec 之后的参数 */
+    args: string[];
+    /** 这些 option 的取值会被序列化成末位 JSON 参数（不参与 pipeline_override） */
+    option: string[];
+    /** v2.8.1 过滤：空/缺省 = 全部控制器适用 */
+    controller?: string[];
+    /** v2.8.1 过滤：空/缺省 = 全部资源适用 */
+    resource?: string[];
 }
 export interface LoadedInterface {
     /** interface.json 绝对路径；未找到为 null */
@@ -91,6 +168,8 @@ export interface LoadedInterface {
     /** 所在目录——resource.path 与 attach_resource_path 的相对基准 */
     dir: string | null;
     version: number | null;
+    /** 顶层 `version` 字符串（**项目**版本，与 interface_version 无关）：PI_VERSION 就是它 */
+    projectVersion: string | null;
     name: string | null;
     controllers: InterfaceController[];
     resources: InterfaceResource[];
@@ -100,12 +179,10 @@ export interface LoadedInterface {
     presets: InterfacePreset[];
     /** 全局配置项键名（override 链最低级） */
     globalOption: string[];
-    /** controller 启动前任务；CLI 不执行，仅用于警告 */
-    pretask: Array<{
-        name?: string;
-        exec?: string;
-    }>;
-    /** agent 子进程声明；CLI 未桥接（绑定无 AgentClient），仅用于警告与失败归因 */
+    /** controller 启动前任务；连接前按声明序执行（非零退出即中止本次连接） */
+    pretask: InterfacePretask[];
+    /** agent 子进程声明；run 时由 daemon 桥接（spawn 子进程 + bind_resource + sink 注册 + connect，
+     * 见 framed.mjs setupAgents）。此处只负责读出 exec/args。 */
     agents: InterfaceAgent[];
     problems: InterfaceProblem[];
 }

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

@@ -1,33 +1,78 @@
 /**
- * pipeline_override 四级合并链（PI v2 v2.3.x）：global_option → resource.option →
- * controller.option → task.option，后合并覆盖先合并；适用性过滤（option 自带的
- * controller/resource 条件不满足时不产生 override）；checkbox 多选按 cases 声明序合并；
- * 嵌套 option 在其父 case 之后合并。
+ * pipeline_override 合成（PI v2）。
  *
- * 取值解析顺序：preset 显式值 > default_case。两级都没有 → 警告并跳过（不猜）。
- * 本 CLI 是无人值守消费面：不做交互选择，preset 是把 MaaPiCli 用户选择带进来的唯一通道。
+ * **输出是分层数组，不是预合并对象**（上游语义，MaaFramework @8061d5b 已核）：
+ * `RuntimeParam::Task.pipeline_override` 是 `json::array`，Configurator 把 task 基底放
+ * `[0]`、每个 option case / input 模板各占一层；`Context::override_pipeline` 逐层
+ * `parse_node(node, layer, default=上一层结果)`——缺失字段继承前值，`recognition`/`action`
+ * 的 `param` 在同 type 时按键继承。**边界在层间**：上一层把 recognition.type 换成别种，
+ * param 就不能继承上一层的字段。若我们客户端先摊平成一个对象，跨层"换 type"后的
+ * param 会被错认为"同 type 继承"——只有分层数组能保边界。
+ *
+ * 层序（与上游 Configurator 一致，后者覆盖先者）：
+ * 1. **task 级 `pipeline_override`** 作 `[0]`（上游同样放数组首位）。
+ * 2. **option 四级链**：global_option → resource.option → controller.option → task.option，
+ *    每个生效 case / input 模板各占一层；进链前先按 option 的 controller/resource
+ *    条件过滤（v2.3.0 / v2.3.1）。checkbox 多选按 cases 声明序各成一层；
+ *    嵌套 option 紧跟其父 case 之后。
+ * 3. **input / hotkey 的模板替换**：`option.<键>.pipeline_override` 是**整个 option 一份**
+ *    的模板，里面有 `{字段名}` 占位——注意它与 `cases[].pipeline_override` 是协议里两处不同字段。
+ *
+ * 取值优先级（**协议未规定**，本工具自定）：CLI `--option` > preset > `default_case`。
+ * preset 是把 GUI 用户选择搬进来的通道；CLI 表示"这一跑就按这个"，所以压过 preset。
+ * input 字段还有第三档来源：`inputs[].default`（协议把它定义成默认值，本工具在无人输入时拿它替换）。
  */
-import type { LoadedInterface } from './load.js';
+import type { InterfaceOption, LoadedInterface } from './load.js';
 export interface OverrideInput {
     loaded: LoadedInterface;
     controllerName: string | null;
     resourceName: string | null;
     taskName: string | null;
     presetName?: string | null;
+    /** CLI 按次取值：option 键 → case 名（select/switch 单值；checkbox 数组） */
+    optionCases?: Record<string, string | string[]>;
+    /** CLI 按次取值：option 键 → { 字段名: 原文 }（input / hotkey 的字段映射） */
+    optionFields?: Record<string, Record<string, string>>;
 }
 export interface OverrideResult {
-    override: Record<string, unknown>;
+    /** 分层 override：逐元素交给框架 `override_pipeline`，层间字段继承（数组尾=最高优先级） */
+    override: Record<string, unknown>[];
     /** 需要人工注意的事项（选项无取值、preset 未找到等） */
     warns: string[];
     /** 人类可读的生效记录：option=值（级别） */
     applied: string[];
 }
 /**
- * 把一份 pipeline_override 并入累计结果：同节点字段替换（与协议"不深度合并"一致）。
+ * 把调用方的覆盖（`--override`）追加到分层数组尾部 = 最高优先级。
+ * 对象 = 一层；数组 = 逐层（框架本来就接受数组，逐层继承，别在这里预合并）。
+ * 四级链、`run --override`、`timing --override` 共用这一个追加口——三处曾经各写一份，
+ * 代价是同一个参数在不同命令里表现不同。
+ */
+export declare function appendOverride(layers: Record<string, unknown>[], ov: Record<string, unknown> | Record<string, unknown>[] | undefined): void;
+export interface OptionValueCtx {
+    /** 命中的 preset 任务条目（`preset[].task[]`）：取值快照 */
+    presetTask?: {
+        option?: Record<string, unknown>;
+    };
+    /** CLI 按次取值：case 名 */
+    optionCases?: Record<string, string | string[]>;
+    /** CLI 按次取值：字段映射 */
+    optionFields?: Record<string, Record<string, string>>;
+}
+export type ResolvedOptionValue = {
+    kind: 'cases';
+    cases: string[];
+    via: string;
+} | {
+    kind: 'fields';
+    fields: Record<string, string>;
+    via: string;
+};
+/**
+ * 解析一个 option 的当前取值（**唯一一份实现**）：pipeline_override 合成与 pretask 的末位 JSON
+ * 都走这里，两边各写一套迟早会在"preset 的 input 值是对象还是字符串"上分叉。
  *
- * **唯一一份实现**：四级链、`run --override`、`timing --override` 都走这里。这三处曾经各写一份，
- * 代价是同一个参数在不同命令里表现不同。非对象值必须**原样替换、不能展开**：字符串会被摊成
- * `{0:'a',1:'b'}`，`null` / 数字会静默变成空对象——等于把用户写的节点悄悄丢掉。
+ * 优先级（协议未规定，本地约定）：CLI > preset > 声明里的初始值（`default_case` / `inputs[].default`）。
  */
-export declare function mergeOverride(acc: Record<string, unknown>, po: Record<string, unknown>): void;
+export declare function resolveOptionValue(o: InterfaceOption, ctx: OptionValueCtx): ResolvedOptionValue | null;
 export declare function computePipelineOverride(input: OverrideInput): OverrideResult;

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

@@ -17,7 +17,7 @@ export interface PlanOverrides {
     adb?: {
         address?: string | null;
     };
-    /** 手动 target（--target）：playcover=<address>/<uuid>；linux=<config JSON> */
+    /** 手动 target（--target）：playcover=<address>/<uuid>；macos=<窗口 id 或标题子串>；linux=<config JSON> */
     manualTarget?: string | null;
 }
 export interface ControllerPlan {
@@ -36,6 +36,22 @@ export interface ResourcePlan {
     names: string[];
     /** 本次实际选中的 resource 名（attach_resource_path 之外的来源条目） */
     selected: string | null;
+    /** 需要人工注意的事项：多个条目都适用时说明选了哪一个（resource[] 是互斥单选，选了就只能用一个） */
+    notes?: string[];
+    /**
+     * v2.6.0 资源完整性校验：声明了 resource.hash 时给出。`pathDirs` 是**只有** `path[]`
+     * 的那段（不含 attach），`attachDirs` 是控制器 `attach_resource_path`——校验时机是
+     * 加载完 path 后、加载 attach 之前，两段必须分开才能只在边界处读 `res.hash`。
+     */
+    hashCheck?: {
+        resourceName: string;
+        expected: string;
+        pathDirs: string[];
+        attachDirs: string[];
+    };
+    /** --resource 指到的值没匹配上任何条目，且不是磁盘上存在的目录：拒绝启动
+     * （打错一个字 = selected=null = 资源级 option/pretask 过滤全部跳过，比报错更贵）。 */
+    error?: string;
 }
 export declare function planController(loaded: LoadedInterface, overrides: PlanOverrides, devices: DeviceLike[]): ControllerPlan;
 /**
@@ -43,5 +59,10 @@ export declare function planController(loaded: LoadedInterface, overrides: PlanO
  * 所选控制器的条目，条目自身多路径按声明顺序叠加（如"B 服"= base + bilibili）；
  * attach_resource_path 在选中控制器后追加。override（--resource）先按资源名匹配，
  * 匹配不上再按文件系统路径解释（原有行为）。
+ *
+ * 有多个条目都适用时，选中的那个与备选一起进 notes——"取第一个"是语义，但静默取第一个
+ * 会让用错资源包的人查不出原因。
  */
-export declare function resolveResourcePaths(loaded: LoadedInterface, controllerName?: string, override?: string): ResourcePlan;
+export declare function resolveResourcePaths(loaded: LoadedInterface, controllerName?: string, override?: string, 
+/** `--resource` 当目录路径时的解析基准（CLI 的 ctx.cwd；缺省 = process.cwd()） */
+cwd?: string): ResourcePlan;

package/lib/types/option-args.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `run --option` 的 argv 解析。
+ *
+ * 只做**切分**，不判 option 类型、不查 case 是否存在——类型、适用性、case 名合法性只有 interface
+ * 知道，判定收口在 `computePipelineOverride` 一处，CLI 与 REPL 各写一套就会分叉。
+ *
+ * 两种写法：
+ * - `<键>=<值>`：select / switch 的 case 名；checkbox 用逗号分隔多个 case
+ * - `<键>.<字段>=<值>`：input 的输入字段（占位符 `{字段名}` 引用的就是它）
+ */
+export interface OptionArgs {
+    /** option 键 → case 名（单值或数组） */
+    cases: Record<string, string | string[]>;
+    /** option 键 → { 字段名: 原文 } */
+    fields: Record<string, Record<string, string>>;
+    /** 写法非法时的原因（调用方决定怎么报） */
+    error?: string;
+}
+export declare function parseOptionArgs(list: unknown): OptionArgs;

package/lib/types/pkg.d.ts

@@ -4,3 +4,11 @@ export interface PackageInfo {
     description?: string;
 }
 export declare function cliPackage(): PackageInfo;
+/**
+ * 运行中**实际加载**的 maa-node 版本（PI_CLIENT_MAAFW_VERSION）。
+ *
+ * 为什么不用 package.json 的声明值：那里写的是范围（^5.14.2），而 agent 侧拿这个变量是要判协议
+ * 兼容的——报范围等于没报。maa-node 不导出 `version`，也不保证导出 package.json，
+ * 所以从入口向上找包根。拿不到返回空串（调用方据此不注入，而不是编一个）。
+ */
+export declare function maaNodeVersion(): string;

package/lib/types/protocol.d.ts

@@ -30,6 +30,10 @@ export declare const EXIT: {
     readonly FINDINGS: 3;
     /** 前置环境缺失（缺 maa-node / 缺 checkout / 缺设备） */
     readonly ENV: 4;
+    /** 被 SIGINT（Ctrl-C）中断：128+2 */
+    readonly SIGINT: 130;
+    /** 被 SIGTERM 中断：128+15 */
+    readonly SIGTERM: 143;
 };
 export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
 export interface CliError {
@@ -80,6 +84,11 @@ export interface CommandContext {
     flags: GlobalFlags;
     /** 已解析并校验过存在性的工作目录（绝对路径） */
     cwd: string;
+    /**
+     * 复用既有 daemon 客户端（REPL / 命名会话 dispatch 时注入）。一次性命令路径此字段为空，
+     * `withDaemon` 才会新起一个 daemon、用完即关——两条路径跑的是同一份 Command.run。
+     */
+    client?: import('./client/daemon.js').DaemonClient;
 }
 export interface Command {
     name: string;
@@ -89,6 +98,13 @@ export interface Command {
     usage: string;
     /** 命令私有选项；全局选项由入口自动合并 */
     options?: ParseArgsOptionsConfig;
+    /**
+     * 需要会话态才能工作的命令（会话 daemon 才有帧流 / 事件环 / 在跑任务）。
+     * `true` 整命令要；谓词形态按子命令分（frame get 要、frame status 不要；kf promote 要、
+     * kf list 不要）。一次性形态下入口直接退 2 + 指向 `--session <name>` 的提示，
+     * 不让"看起来成功了"的空跑存在（stop 停空 daemon、frame get 恒 NO_FRAME 这类）。
+     */
+    requiresSession?: boolean | ((ctx: CommandContext) => boolean);
     run(ctx: CommandContext): Promise<CommandResult>;
 }
 export declare function toEnvelope(command: string, r: CommandResult): Envelope;