@windsland52/maafw-live 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,190 @@
+export interface InterfaceProblem {
+    message: string;
+}
+/** 控制器的显示声明；映射为 daemon connect 的 shortSide / longSide / rawSize。 */
+export interface DisplayDecl {
+    shortSide?: number;
+    longSide?: number;
+    raw?: boolean;
+    expand?: [number, number];
+}
+export interface Win32Decl {
+    classRegex?: string;
+    windowRegex?: string;
+    screencap?: string;
+    mouse?: string;
+    keyboard?: string;
+}
+export interface GamepadDecl {
+    classRegex?: string;
+    windowRegex?: string;
+    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 */
+    type: string;
+    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;
+    /** 资源根目录（含 pipeline / image / model），相对 interface.json 所在目录，声明顺序即加载顺序 */
+    paths: string[];
+    /** 只对这些控制器生效；空数组 = 全部 */
+    controllers: string[];
+    /** v2.3.0：资源级配置项名单（override 链第二级） */
+    option?: string[];
+    /** v2.6.0：资源完整性校验值（仅加载 path 后的 MaaResourceGetHash；不匹配只警告不阻断） */
+    hash?: string;
+    /** 原始条目（未裁剪）：PI_RESOURCE 要传"被选中那条的完整对象" */
+    raw?: unknown;
+}
+export interface InterfaceTask {
+    name: string;
+    /** pipeline 入口节点名；缺省时入口即任务名 */
+    entry?: string;
+    /** 只在这些控制器下可用（隐藏/禁用语义）；空 = 全部 */
+    controller?: string[];
+    /** 只在这些资源下可用；空 = 全部 */
+    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 {
+    name: string;
+    pipelineOverride?: Record<string, unknown>;
+    /** 选中该 case 后生效的子配置项 */
+    option?: string[];
+}
+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 {
+    name: string;
+    task: Array<{
+        name: string;
+        enabled?: boolean;
+        option?: Record<string, unknown>;
+    }>;
+}
+/** PI `agent` 声明：宿主侧子进程（如 uv run python agent/main.py），经 agent 协议注册 custom
+ * 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 */
+    file: string | null;
+    /** 所在目录——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[];
+    tasks: InterfaceTask[];
+    /** option 字典（主文件 + import 合并，后导入覆盖同名） */
+    options: Record<string, InterfaceOption>;
+    presets: InterfacePreset[];
+    /** 全局配置项键名（override 链最低级） */
+    globalOption: string[];
+    /** controller 启动前任务；连接前按声明序执行（非零退出即中止本次连接） */
+    pretask: InterfacePretask[];
+    /** agent 子进程声明；run 时由 daemon 桥接（spawn 子进程 + bind_resource + sink 注册 + connect，
+     * 见 framed.mjs setupAgents）。此处只负责读出 exec/args。 */
+    agents: InterfaceAgent[];
+    problems: InterfaceProblem[];
+}
+export declare function findInterfaceFile(dir: string): string | null;
+export declare function loadInterface(dir: string): LoadedInterface;

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

@@ -0,0 +1,78 @@
+/**
+ * pipeline_override 合成（PI v2）。
+ *
+ * **输出是分层数组，不是预合并对象**（上游语义，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 { 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：逐元素交给框架 `override_pipeline`，层间字段继承（数组尾=最高优先级） */
+    override: Record<string, unknown>[];
+    /** 需要人工注意的事项（选项无取值、preset 未找到等） */
+    warns: string[];
+    /** 人类可读的生效记录：option=值（级别） */
+    applied: string[];
+}
+/**
+ * 把调用方的覆盖（`--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 值是对象还是字符串"上分叉。
+ *
+ * 优先级（协议未规定，本地约定）：CLI > preset > 声明里的初始值（`default_case` / `inputs[].default`）。
+ */
+export declare function resolveOptionValue(o: InterfaceOption, ctx: OptionValueCtx): ResolvedOptionValue | null;
+export declare function computePipelineOverride(input: OverrideInput): OverrideResult;

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

@@ -0,0 +1,68 @@
+import type { LoadedInterface } from './load.js';
+/** daemon device_list 的条目：adb 的 id 是 address，win32 的 id 是 hwnd。 */
+export interface DeviceLike {
+    kind?: string;
+    id?: string;
+    name?: string;
+    cls?: string;
+}
+export interface PlanOverrides {
+    controller?: string;
+    win32?: {
+        hwnd?: string | null;
+    };
+    gamepad?: {
+        hwnd?: string | null;
+    };
+    adb?: {
+        address?: string | null;
+    };
+    /** 手动 target（--target）：playcover=<address>/<uuid>；macos=<窗口 id 或标题子串>；linux=<config JSON> */
+    manualTarget?: string | null;
+}
+export interface ControllerPlan {
+    ok: boolean;
+    code?: string;
+    error?: string;
+    controllerName: string | null;
+    /** 直接展开给 daemon 的 connect 参数 */
+    connect: Record<string, unknown>;
+    /** 失败时的候选设备，供调用方提示用户显式指定 */
+    candidates?: DeviceLike[];
+    notes?: string[];
+}
+export interface ResourcePlan {
+    paths: string[];
+    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;
+/**
+ * 解析资源路径：resource[] 是互斥单选（Client 语义）——不传 override 时取第一个适用于
+ * 所选控制器的条目，条目自身多路径按声明顺序叠加（如"B 服"= base + bilibili）；
+ * attach_resource_path 在选中控制器后追加。override（--resource）先按资源名匹配，
+ * 匹配不上再按文件系统路径解释（原有行为）。
+ *
+ * 有多个条目都适用时，选中的那个与备选一起进 notes——"取第一个"是语义，但静默取第一个
+ * 会让用错资源包的人查不出原因。
+ */
+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

@@ -0,0 +1,14 @@
+export interface PackageInfo {
+    name: string;
+    version: string;
+    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

@@ -0,0 +1,124 @@
+/**
+ * CLI 协议层：统一 JSON 信封 + 命令契约 + 退出码语义。
+ *
+ * 信封结构抄 create-maa-project 的 `--report`——它已被真实消费方验证过，
+ * 属于本生态的既有事实标准。目的：让「技能 / 脚本 / CI / 人」消费同一份稳定结构，
+ * 不必各自解析文本输出，也不必各自发明字段名。
+ *
+ * 注意（这是本文件的唯一不变量）：信封字段只增不改。技能会按字段名读取，
+ * 改名等于静默破坏所有消费方。
+ */
+import type { ParseArgsOptionsConfig } from 'node:util';
+import type { GlobalFlags } from './flags.js';
+/** 信封结构版本。字段增删时递增，消费方可据此拒绝不认识的形状。 */
+export declare const SCHEMA_VERSION = 1;
+/**
+ * 退出码语义。
+ *
+ * 关键区分：`FAIL` 是「命令没跑成」，`FINDINGS` 是「跑成了，但发现了问题」。
+ * 技能与 CI 必须能分开这两种情况——reco 识别未命中不是执行失败，
+ * 但也不该返回 0 让调用方以为一切正常。
+ */
+export declare const EXIT: {
+    /** 命令正常完成，未发现问题 */
+    readonly OK: 0;
+    /** 命令自身失败（未预期异常、IO 错误） */
+    readonly FAIL: 1;
+    /** 参数 / 用法错误 */
+    readonly USAGE: 2;
+    /** 命令正常跑完，但发现了问题（reco 未命中、run 调用级失败、观测类命令的警告等） */
+    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 {
+    message: string;
+    /** 稳定的机器可读标识，供技能分支判断；不要用 message 做判断 */
+    code: string;
+    hint?: string;
+}
+export interface Envelope {
+    schemaVersion: number;
+    command: string;
+    /** 命令本身是否执行成功。FINDINGS 仍算 ok=true——它跑成了，只是有发现 */
+    ok: boolean;
+    exitCode: number;
+    /** 本次操作的项目根，无法确定时为 null */
+    root: string | null;
+    written: string[];
+    removed: string[];
+    skipped: string[];
+    /** 需要人工跟进的事项（如「先跑 maa project sync」） */
+    pending: string[];
+    suggestedCommands: string[];
+    warnings: string[];
+    /** 命令特定载荷 */
+    data: unknown;
+    error: CliError | null;
+}
+/** 命令返回的结果。信封字段在此给默认值，命令只填关心的部分。 */
+export interface CommandResult {
+    exitCode: ExitCode;
+    data?: unknown;
+    /** 非 --json 时逐行打印的内容。命令自己决定怎么排版 */
+    human?: string[];
+    warnings?: string[];
+    written?: string[];
+    removed?: string[];
+    skipped?: string[];
+    pending?: string[];
+    suggestedCommands?: string[];
+    error?: CliError;
+    root?: string | null;
+}
+export interface CommandContext {
+    /** 命令名之后的位置参数 */
+    positionals: string[];
+    /** 已解析的全部选项（含全局选项） */
+    values: Record<string, unknown>;
+    flags: GlobalFlags;
+    /** 已解析并校验过存在性的工作目录（绝对路径） */
+    cwd: string;
+    /**
+     * 复用既有 daemon 客户端（REPL / 命名会话 dispatch 时注入）。一次性命令路径此字段为空，
+     * `withDaemon` 才会新起一个 daemon、用完即关——两条路径跑的是同一份 Command.run。
+     */
+    client?: import('./client/daemon.js').DaemonClient;
+}
+export interface Command {
+    name: string;
+    /** 一行说明，用于顶层 help 列表 */
+    summary: string;
+    /** 完整用法行，如 `maafw-live env [--deep] [--maafw <dir>]` */
+    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;
+export interface EmitOptions {
+    json: boolean;
+    color: boolean;
+}
+/**
+ * 输出命令结果。
+ *
+ * --json 时只输出信封（stdout 保持纯 JSON，可被管道解析）；
+ * 否则输出命令自己的 human 渲染 + 警告 + 建议命令。
+ * 错误与警告一律走 stderr，避免污染 stdout 的 JSON。
+ */
+export declare function emit(command: string, r: CommandResult, o: EmitOptions): void;
+/** 失败结果的快捷构造 */
+export declare function fail(code: string, message: string, hint?: string, exitCode?: ExitCode): CommandResult;