2.2 集成接口一览

关于 binding

不同语言的 binding 会有不同的命名方式，且会根据 标准化接口 进行封装，请自行搜索实际的名称。部分接口可能直接在内部自动使用而不会提供（例如 StringBuffer 相关接口）。下面是一些接口在不同 binding 中的参考名称。

C API	Python 标准接口	NodeJS 标准接口
MaaVersion()	Library.version()	Global.version
MaaTaskerCreate()	Tasker()	new Tasker()
MaaTaskerDestroy(tasker_handle)	析构时自动调用	tasker.destroy()
MaaResourcePostBundle(res_handle, path)	resource.post_bundle(path)	res.post_bundle(path)
MaaControllerPostClick(ctrl_handle, x, y)	controller.post_click(x, y)	ctrl.post_click(x, y)
MaaTaskerInited(tasker_handle)	tasker.inited	tasker.inited
MaaTaskerPostTask(tasker_handle, entry, override)	tasker.post_task(entry, override)	tasker.post_task(entry, override)
MaaImageBufferResize(image_handle, width, height)	ImageBuffer.resize(width, height)	Global.resize_image(image, width, height)

MaaUtility.h

MaaVersion

返回 MaaFramework 的版本。

MaaGlobalSetOption

设置全局配置。在 binding 中会拆分为具体的配置。

• LogDir
  设置日志路径

• SaveDraw
  设置是否将识别保存到 日志路径/vision 中。开启后 RecoDetail 将可以获取到 draws

• StdoutLevel
  设置日志输出到 stdout 中的级别

• DebugMode
  设置是否启用调试模式。调试模式下，RecoDetail 将可以获取到 raw/draws；所有任务都会被视为 focus 而产生回调

• SaveOnError
  设置是否在错误时保存截图到 日志路径/on_error 中

• DrawQuality
  设置识别可视化图像的 JPEG 质量（0-100），默认值为 85

• RecoImageCacheLimit
  设置识别图像缓存数量限制，默认值为 4096

MaaGlobalLoadPlugin

• library_path: 插件库路径或名称

加载插件。可以使用完整路径或仅使用名称，仅使用名称时会在系统目录和当前目录中搜索。也可以递归搜索目录中的插件

MaaBuffer.h

MaaImageBufferResize

• handle: 图像缓冲区
• width: 目标宽度，传 0 表示按高度等比缩放
• height: 目标高度，传 0 表示按宽度等比缩放

按比例缩放 handle 中的图像数据，修改原缓冲区。width 与 height 不能同时为 0。

MaaResource.h

MaaResourceCreate

创建资源

MaaResourceDestroy

销毁资源

MaaResourceAddSink

• res: 资源
• sink: 事件回调
• trans_arg: 传递给回调的参数

添加资源事件监听器，返回监听器 id

MaaResourceRemoveSink

• res: 资源
• sink_id: 监听器 id

移除资源事件监听器

MaaResourceClearSinks

• res: 资源

清除所有资源事件监听器

MaaResourceRegisterCustomRecognition

• name: 名称
• recognition: 自定义识别器
• trans_arg: 传递给回调的参数

注册名为 name 的自定义识别器 recognition

MaaResourceUnregisterCustomRecognition

• name: 名称

移除名为 name 的自定义识别器

MaaResourceClearCustomRecognition

移除所有自定义识别器

MaaResourceRegisterCustomAction

• name: 名称
• action: 自定义操作
• trans_arg: 传递给回调的参数

注册名为 name 的自定义操作 action

MaaResourceUnregisterCustomAction

• name: 名称

移除名为 name 的自定义操作

MaaResourceClearCustomAction

移除所有自定义操作

MaaResourcePostBundle

• path: 资源路径

异步加载 path 路径下的资源。这是一个异步操作，会立即返回一个操作 id，可通过 MaaResourceStatus 和 MaaResourceWait 查询状态。

MaaResourceOverridePipeline

• pipeline_override: 用于覆盖的 json

覆盖 pipeline_override

MaaResourceOverrideNext

• node_name: 任务名
• next_list: next 列表

覆盖 node_name 的 next 列表为 next_list。注意：此方法会直接设置 next 列表，即使节点不存在也会创建。

MaaResourceOverrideImage

• image_name: 图片名
• image: 图片数据

覆盖 image_name 对应的图片为 image。此方法总是成功。

MaaResourceGetNodeData

• node_name: 任务名
• buffer [out]: 输出缓冲区

获取 node_name 任务当前的定义，写入到 buffer

MaaResourceClear

清除已加载内容。如果资源正在加载中，此方法会失败并返回 false。

MaaResourceStatus

• id: 操作 id

查询 id 对应操作状态

MaaResourceWait

• id: 操作 id

等待 id 对应操作完成

MaaResourceLoaded

判断是否加载正常

MaaResourceSetOption

设置资源配置。在 binding 中会拆分为具体的配置。

• InferenceDevice
  设置推理设备

• InferenceExecutionProvider
  设置推理库

MaaResourceGetHash

• buffer [out]: 输出缓冲区

获取资源 hash，写入到 buffer

MaaResourceGetNodeList

• buffer [out]: 输出缓冲区

获取任务列表，写入到 buffer

MaaResourceGetCustomRecognitionList

• buffer [out]: 输出缓冲区

获取已注册的自定义识别器名称列表，写入到 buffer

MaaResourceGetCustomActionList

• buffer [out]: 输出缓冲区

获取已注册的自定义操作名称列表，写入到 buffer

MaaResourceGetDefaultRecognitionParam

• reco_type: 识别类型字符串（如 "OCR"、"TemplateMatch"）
• buffer [out]: 输出缓冲区

从 DefaultPipelineMgr 获取指定识别类型的默认参数，序列化为 JSON 写入到 buffer

MaaResourceGetDefaultActionParam

• action_type: 动作类型字符串（如 "Click"、"Swipe"）
• buffer [out]: 输出缓冲区

从 DefaultPipelineMgr 获取指定动作类型的默认参数，序列化为 JSON 写入到 buffer

MaaController.h

MaaAdbControllerCreate

• adb_path: adb 路径
• address: 连接地址
• screencap_methods: 所有可使用的截图方式，参见 控制方式说明
• input_methods: 所有可使用的输入方式，参见 控制方式说明
• config: 额外配置
• agent_path: MaaAgentBinary 路径

创建 Adb 控制器

截图方式和输入方式会在启动时进行测速，选择最快的方案

MaaWin32ControllerCreate

• hWnd: 窗口句柄
• screencap_method: 使用的截图方式，参见 控制方式说明
• mouse_method: 使用的鼠标输入方式，参见 控制方式说明
• keyboard_method: 使用的键盘输入方式，参见 控制方式说明

创建 Win32 控制器

MaaCustomControllerCreate

• controller: 自定义控制回调结构体
• controller_arg: 传递给回调的参数

创建自定义控制器

MaaDbgControllerCreate

• read_path: 输入路径，包含通过 Recording 选项记录的操作
• write_path: 输出路径，包含执行结果
• type: 控制器模式
• config: 额外配置

创建调试控制器

MaaPlayCoverControllerCreate

• address: PlayTools 服务监听地址，格式为 host:port，如 127.0.0.1:1717
• uuid: 目标应用的 Bundle Identifier，如 com.hypergryph.arknights

创建 PlayCover 控制器，用于在 macOS 上控制通过 fork版PlayCover 运行的 iOS 应用程序。详见 控制方式说明。

MaaWlRootsControllerCreate

• wlr_socket_path: Wayland Socket 路径，如 /run/user/1000/wayland-0

创建 WlRoots 控制器，用于在 Linux 上控制在 wlroots 合成器中运行的应用程序。详见 控制方式说明。

MaaGamepadControllerCreate

• hWnd: 窗口句柄，用于截图。如果不需要截图可以传 nullptr/None/null
• gamepad_type: 手柄类型，参见 控制方式说明
• screencap_method: Win32 截图方式，参见 控制方式说明

创建 Gamepad 控制器，用于在 Windows 上模拟 Xbox 360 或 DualShock 4 手柄输入。详见 控制方式说明。

注意

• 需要安装 ViGEm Bus Driver

MaaControllerDestroy

销毁控制器

MaaControllerAddSink

• ctrl: 控制器
• sink: 事件回调
• trans_arg: 传递给回调的参数

添加控制器事件监听器，返回监听器 id

MaaControllerRemoveSink

• ctrl: 控制器
• sink_id: 监听器 id

移除控制器事件监听器

MaaControllerClearSinks

• ctrl: 控制器

清除所有控制器事件监听器

MaaControllerSetOption

设置控制器配置。在 binding 中会拆分为具体的配置。

• ScreenshotTargetLongSide
  设置截图缩放长边到指定长度

• ScreenshotTargetShortSide
  设置截图缩放短边到指定长度

• ScreenshotUseRawSize
  设置截图不缩放

MaaControllerPostConnection

异步连接设备。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostClick

• x, y: 点击坐标

异步点击。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostClickV2

• x, y: 点击坐标
• contact: 触点编号
  • Adb 控制器：手指编号（0 为第一根手指，1 为第二根手指，以此类推）
  • Win32 控制器：鼠标按键（0：左键，1：右键，2：中键）
• pressure: 触点力度

异步点击。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostSwipe

• x1, y1: 起点坐标
• x2, y2: 终点坐标
• duration: 滑动时长 ms

异步滑动。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostSwipeV2

• x1, y1: 起点坐标
• x2, y2: 终点坐标
• duration: 滑动时长 ms
• contact: 触点编号
  • Adb 控制器：手指编号（0 为第一根手指，1 为第二根手指，以此类推）
  • Win32 控制器：鼠标按键（0：左键，1：右键，2：中键）
• pressure: 触点力度

异步滑动。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostClickKey

• key: 虚拟键码
  • Adb 控制器
  • Win32 控制器

异步单击按键。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostKeyDown

• key: 虚拟键码
  • Adb 控制器
  • Win32 控制器

异步按下键。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostKeyUp

• key: 虚拟键码
  • Adb 控制器
  • Win32 控制器

异步抬起键。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostInputText

• text: 输入文本

异步输入文本。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostStartApp

• intent: 目标应用
  • Adb 控制器：package name 或 activity
  • Win32 控制器：暂不支持

异步启动应用。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostStopApp

• intent: 目标应用
  • Adb 控制器：package name
  • Win32 控制器：暂不支持

异步关闭应用。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostTouchDown

• contact: 触点编号
  • Adb 控制器：手指编号
  • Win32 控制器：鼠标按键（0：左键，1：右键，2：中键）
• x, y: 触点位置
• pressure: 触点力度

异步按下。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostTouchMove

• contact: 触点编号
  • Adb 控制器：手指编号
  • Win32 控制器：鼠标按键（0：左键，1：右键，2：中键）
• x, y: 触点位置
• pressure: 触点力度

异步移动。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostTouchUp

• contact: 触点编号
  • Adb 控制器：手指编号
  • Win32 控制器：鼠标按键（0：左键，1：右键，2：中键）

异步抬起。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostRelativeMove

• dx: 水平移动距离
• dy: 垂直移动距离

异步执行一次相对位移。当前由 Win32 controller 提供支持。投递到不支持该能力的控制器时，操作会执行失败。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

MaaControllerPostScroll

• dx: 水平滚动距离，正值向右滚动，负值向左滚动
• dy: 垂直滚动距离，正值向上滚动，负值向下滚动

异步滚动。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

NOTE

• Win32 控制器，以及实现了 scroll 的自定义控制器支持滚动操作。
• dx/dy 的值会直接作为滚动增量发送。Windows 标准滚轮每格增量为 120（WHEEL_DELTA），建议使用 120 的整数倍以获得最佳兼容性。

MaaControllerPostInactive

异步设置控制器为不活跃状态。对于 Win32 控制器，会恢复窗口置顶状态、解除输入阻塞、恢复光标/窗口位置等侵入性操作。其他控制器无操作。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态。

NOTE

Tasker 在所有任务执行完毕后会自动调用此接口，通常无需手动调用。

MaaControllerPostScreencap

异步截图。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态，通过 MaaControllerCachedImage 获取截图。

NOTE

截图会根据截图目标尺寸设置（长边/短边）进行缩放，获取到的图像尺寸可能与设备原始分辨率不同。
使用 MaaControllerGetResolution 可获取设备的原始（未缩放）分辨率。

MaaControllerPostShell

• cmd: 要执行的 shell 命令

异步执行 ADB 设备上的 shell 命令。这是一个异步操作，会立即返回一个操作 id，可通过 MaaControllerStatus 和 MaaControllerWait 查询状态，通过 MaaControllerGetShellOutput 获取输出。

注意：此接口仅对 ADB 控制器有效。其他类型的控制器将返回错误。

MaaControllerStatus

• id: 操作 id

查询 id 对应操作状态

MaaControllerWait

• id: 操作 id

等待 id 对应操作完成

MaaControllerConnected

判断是否已连接

MaaControllerCachedImage

• buffer [out]: 输出缓冲区

获取最新一次截图，写入到 buffer

NOTE

返回的图像是经过缩放的，尺寸根据截图目标尺寸设置（长边/短边）而定，可能与设备原始分辨率不同。
使用 MaaControllerGetResolution 可获取设备的原始（未缩放）分辨率。

MaaControllerGetResolution

• width [out]: 输出原始宽度
• height [out]: 输出原始高度

获取设备的原始（未缩放）分辨率。

NOTE

返回的是设备屏幕的实际分辨率，未经任何缩放处理。
而通过 MaaControllerCachedImage 获取的截图是经过缩放的，其尺寸可能与此原始分辨率不同。
需要在首次截图后才能获取到有效值。

MaaControllerGetShellOutput

• buffer [out]: 输出缓冲区

获取最近一次 shell 命令执行的输出，写入到 buffer

MaaControllerGetUuid

• buffer [out]: 输出缓冲区

获取设备 uuid，写入到 buffer

MaaControllerGetInfo

• buffer [out]: 输出缓冲区

获取控制器信息（JSON 字符串），写入到 buffer。
返回的 JSON 始终包含 type 字段，表示控制器类型。根据类型不同，还包含各自的构造参数等信息。
连接状态、UUID、分辨率等可通过其他专用接口获取（如 MaaControllerConnected、MaaControllerGetUuid、MaaControllerGetResolution），不在此重复。

各类型返回字段：

• adb: type, adb_path, adb_serial, screencap_methods, input_methods, agent_path, config
• win32: type, hwnd, screencap_method, mouse_method, keyboard_method
• playcover: type, address
• gamepad: type, hwnd, gamepad_type, screencap_method
• wlroots: type, wlr_socket_path
• custom: type（如果自定义控制器实现了 get_info 回调，还会包含其返回的额外字段）
• dbg_carousel_image: type, path, image_count, image_index
• dbg_replay_recording: type, record_count, record_index

MaaTasker.h

MaaTaskerCreate

创建实例

MaaTaskerDestroy

销毁实例

MaaTaskerAddSink

• tasker: 实例
• sink: 事件回调
• trans_arg: 传递给回调的参数

添加实例事件监听器，返回监听器 id

MaaTaskerRemoveSink

• tasker: 实例
• sink_id: 监听器 id

移除实例事件监听器

MaaTaskerClearSinks

• tasker: 实例

清除所有实例事件监听器

MaaTaskerAddContextSink

• tasker: 实例
• sink: 事件回调
• trans_arg: 传递给回调的参数

添加上下文事件监听器，返回监听器 id

MaaTaskerRemoveContextSink

• tasker: 实例
• sink_id: 监听器 id

移除上下文事件监听器

MaaTaskerClearContextSinks

• tasker: 实例

清除所有上下文事件监听器

MaaTaskerSetOption

设置实例配置。在 binding 中会拆分为具体的配置。

暂无可配置项

MaaTaskerBindResource

• res: 资源

关联资源

MaaTaskerBindController

• ctrl: 控制器

关联控制器

MaaTaskerInited

判断是否正确初始化

MaaTaskerPostTask

• entry: 任务入口
• pipeline_override: 用于覆盖的 json

异步执行任务。这是一个异步操作，会立即返回一个任务 id，可通过 MaaTaskerStatus 和 MaaTaskerWait 查询状态，通过 MaaTaskerGetTaskDetail 获取任务详情。

MaaTaskerPostRecognition

• reco_type: 识别类型字符串
• reco_param: 识别参数 json
• image: 前序截图

异步执行识别。这是一个异步操作，会立即返回一个任务 id，可通过 MaaTaskerStatus 和 MaaTaskerWait 查询状态，通过 MaaTaskerGetTaskDetail 获取任务详情。

MaaTaskerPostAction

• action_type: 操作类型字符串
• action_param: 操作参数 json
• box: 前序识别位置
• reco_detail: 前序识别详情

异步执行操作。这是一个异步操作，会立即返回一个任务 id，可通过 MaaTaskerStatus 和 MaaTaskerWait 查询状态，通过 MaaTaskerGetTaskDetail 获取任务详情。

MaaTaskerStatus

• id: 操作 id

查询 id 对应操作状态

MaaTaskerWait

• id: 操作 id

等待 id 对应操作完成

MaaTaskerRunning

判断实例是否还在运行

MaaTaskerPostStop

异步停止实例。这是一个异步操作，会立即返回一个任务 id。停止操作会中断当前运行的任务，并停止资源加载和控制器操作。可通过 MaaTaskerStatus 和 MaaTaskerWait 查询状态。

MaaTaskerStopping

判断实例是否正在停止中（尚未停止）

MaaTaskerGetResource

获取关联的资源

MaaTaskerGetController

获取关联的控制器

MaaTaskerClearCache

清理所有可查询的信息

MaaTaskerOverridePipeline

• task_id: 任务 ID
• pipeline_override: 用于覆盖的 JSON

覆盖指定任务的 pipeline，在任务执行期间动态修改 pipeline 配置。

MaaTaskerGetRecognitionDetail

• reco_id: 识别号
• node_name [out]: 节点名缓冲区
• algorithm [out]: 识别算法缓冲区
• hit [out]: 是否命中
• box [out]: 命中位置
• detail_json [out]: 识别详情缓冲区
• raw [out]: 截图缓冲区（仅调试模式有效）
• draws [out]: 附带识别结果的截图缓冲区（仅调试模式有效）

获取识别信息

MaaTaskerGetActionDetail

• action_id: 操作号
• node_name [out]: 节点名
• action [out]: 动作类型名称（如 "Click", "Swipe" 等）
• box [out]: 操作区域（识别框）
• success [out]: 操作返回值（controller 调用的返回值）
• detail_json [out]: 调用 controller 的实际参数（JSON 格式）

获取操作信息

MaaTaskerGetNodeDetail

• node_id: 节点号
• node_name [out]: 节点名缓冲区
• reco_id [out]: 对应识别号
• action_id [out]: 对应操作号
• completed [out]: 操作结果

获取节点信息

MaaTaskerGetTaskDetail

• task_id: 任务号
• entry [out]: 任务入口缓冲区
• node_id_list [out]: 节点号数组
• node_id_list_size [in, out]: 节点号数组大小（输入时表示缓冲区大小，输出时表示实际大小）
• status [out]: 任务状态

获取任务信息

MaaTaskerGetLatestNode

• node_name: 任务名
• latest_id [out]: 最新节点号

获取任务 node_name 的最新节点号

MaaContext.h

MaaContextRunTask

• entry: 任务入口
• pipeline_override: 用于覆盖的 json

同步执行任务。执行失败则返回 MaaInvalidId，成功则返回任务 id，可通过 MaaTaskerGetTaskDetail 获取任务详情。

MaaContextRunRecognition

• entry: 任务名
• pipeline_override: 用于覆盖的 json
• image: 前序截图

同步执行 entry 对应的识别逻辑，返回识别号。执行失败则返回 MaaInvalidId，成功则返回识别 id，可通过 MaaTaskerGetRecognitionDetail 获取识别详情。

不会执行后续操作，不会执行后续 next

MaaContextRunAction

• entry: 任务名
• pipeline_override: 用于覆盖的 json
• box: 前序识别位置
• reco_detail: 前序识别详情

同步执行 entry 对应的操作逻辑，返回操作号。执行失败则返回 MaaInvalidId，成功则返回操作 id，可通过 MaaTaskerGetActionDetail 获取操作详情。

不会执行后续 next

MaaContextRunRecognitionDirect

• reco_type: 识别类型（如 "OCR", "TemplateMatch" 等）
• reco_param: 识别参数 json
• image: 前序截图

直接使用识别类型和参数执行识别，无需通过 pipeline entry。返回识别号。执行失败则返回 MaaInvalidId，成功则返回识别 id，可通过 MaaTaskerGetRecognitionDetail 获取识别详情。

不会执行后续操作，不会执行后续 next

MaaContextRunActionDirect

• action_type: 操作类型（如 "Click", "Swipe" 等）
• action_param: 操作参数 json
• box: 前序识别位置
• reco_detail: 前序识别详情

直接使用操作类型和参数执行操作，无需通过 pipeline entry。返回操作号。执行失败则返回 MaaInvalidId，成功则返回操作 id，可通过 MaaTaskerGetActionDetail 获取操作详情。

不会执行后续 next

MaaContextOverridePipeline

• pipeline_override: 用于覆盖的 json

覆盖 pipeline_override

MaaContextOverrideNext

• node_name: 任务名
• next_list: next 列表

覆盖 node_name 的 next 列表为 next_list。如果节点不存在，此方法会失败并返回 false。

MaaContextOverrideImage

• image_name: 图片名
• image: 图片数据

覆盖 image_name 对应的图片为 image。此方法总是成功。

MaaContextGetNodeData

• node_name: 任务名
• buffer [out]: 输出缓冲区

获取 node_name 任务当前的定义，写入到 buffer

MaaContextGetTaskId

获取对应任务号

MaaContextGetTasker

获取实例

MaaContextClone

复制上下文

MaaContextSetAnchor

• anchor_name: 锚点名称
• node_name: 节点名称

设置锚点 anchor_name 对应的节点为 node_name

MaaContextGetAnchor

• anchor_name: 锚点名称
• buffer [out]: 输出缓冲区

获取锚点 anchor_name 对应的节点名称，写入到 buffer

MaaContextGetHitCount

• node_name: 节点名称
• count [out]: 命中计数

获取节点 node_name 的命中计数，写入到 count

MaaContextClearHitCount

• node_name: 节点名称

清除节点 node_name 的命中计数

MaaContextWaitFreezes

• time: 等待时间（毫秒），简单模式下直接传入
• box: 识别命中的区域，用于 target 为 Self 时计算 ROI
• wait_freezes_param: 可选的高级参数 JSON 对象，包含以下字段：
  • time: 等待时间（毫秒）
  • target: 目标区域，支持 Self（默认）、PreTask、Region 等类型
  • threshold: 相似度阈值（默认 0.95）
  • method: 比对方法（默认为模板匹配默认方法）
  • rate_limit: 截图间隔（毫秒，默认 1000）
  • timeout: 超时时间（毫秒，默认 20000）

等待画面静止。time 和 wait_freezes_param.time 互斥：两者不能同时为非零，也不能同时为零。

MaaToolkitConfig.h

MaaToolkitConfigInitOption

• user_path: 配置存储路径
• default_json: 默认配置

从 user_path 中加载全局配置

MaaToolkitAdbDevice.h

MaaToolkitAdbDeviceListCreate

创建设备列表

MaaToolkitAdbDeviceListDestroy

• handle: 设备列表句柄

销毁设备列表

MaaToolkitAdbDeviceFind

• buffer [out]: 输出缓冲区

搜索所有已知安卓模拟器，写入到 buffer

MaaToolkitAdbDeviceFindSpecified

• adb_path: adb 路径
• buffer [out]: 输出缓冲区

根据指定 adb_path 搜索模拟器，写入到 buffer

MaaToolkitAdbDeviceListSize

• list: 设备列表

获取设备列表大小

MaaToolkitAdbDeviceListAt

• list: 设备列表
• index: 索引

获取设备列表中指定索引的设备

MaaToolkitAdbDeviceGetName

• device: 设备

获取设备名称

MaaToolkitAdbDeviceGetAdbPath

• device: 设备

获取设备 adb 路径

MaaToolkitAdbDeviceGetAddress

• device: 设备

获取设备连接地址

MaaToolkitAdbDeviceGetScreencapMethods

• device: 设备

获取设备支持的截图方式

MaaToolkitAdbDeviceGetInputMethods

• device: 设备

获取设备支持的输入方式

MaaToolkitAdbDeviceGetConfig

• device: 设备

获取设备配置

MaaToolkitDesktopWindow.h

MaaToolkitDesktopWindowListCreate

创建窗口列表

MaaToolkitDesktopWindowListDestroy

• handle: 窗口列表句柄

销毁窗口列表

MaaToolkitDesktopWindowFindAll

• buffer [out]: 输出缓冲区

查询所有窗口信息，写入到 buffer

MaaToolkitDesktopWindowListSize

• list: 窗口列表

获取窗口列表大小

MaaToolkitDesktopWindowListAt

• list: 窗口列表
• index: 索引

获取窗口列表中指定索引的窗口

MaaToolkitDesktopWindowGetHandle

• window: 窗口

获取窗口句柄

MaaToolkitDesktopWindowGetClassName

• window: 窗口

获取窗口类名

MaaToolkitDesktopWindowGetWindowName

• window: 窗口

获取窗口名称

MaaAgentClientAPI.h

MaaAgentClientCreateV2

• identifier: 连接标识符缓冲区（可为空，为空则自动生成）

创建 Agent 客户端

传入空则自动生成 IPC identifier
传入纯数字字符串（1-65535）时，会将其视为 TCP 端口号并监听 127.0.0.1
在不支持 AF_UNIX 的旧版 Windows（Build 17063 之前）上，会自动回退到 TCP 模式

MaaAgentClientCreateTcp

• port: TCP 端口号 (0-65535)

创建 Agent 客户端（TCP 模式）

Agent 客户端会监听 127.0.0.1 上的指定 TCP 端口。如果传入 0，则系统会自动选择一个可用端口。AgentServer 端使用 MaaAgentClientIdentifier 获取的端口号作为 identifier 即可通过 TCP 连接。

MaaAgentClientDestroy

销毁 Agent 客户端

MaaAgentClientIdentifier

• identifier [out]: 输出缓冲区

获取实际监听地址，写入到 identifier

MaaAgentClientBindResource

• res: 资源

将 Agent 客户端关联到资源 res

MaaAgentClientRegisterResourceSink

• res: 资源

注册资源事件监听器

MaaAgentClientRegisterControllerSink

• ctrl: 控制器

注册控制器事件监听器

MaaAgentClientRegisterTaskerSink

• tasker: 实例

注册实例事件监听器

MaaAgentClientConnect

连接

MaaAgentClientDisconnect

断开连接

MaaAgentClientConnected

判断是否已连接

MaaAgentClientAlive

判断 Agent 服务端是否仍可响应

MaaAgentClientSetTimeout

• milliseconds: 超时时间 ms

设置 Agent 服务端超时时间

MaaAgentClientGetCustomRecognitionList

• buffer [out]: 输出缓冲区

获取 Agent 连接后注册的自定义识别器名称列表，写入到 buffer

MaaAgentClientGetCustomActionList

• buffer [out]: 输出缓冲区

获取 Agent 连接后注册的自定义操作名称列表，写入到 buffer

MaaAgentServerAPI.h

MaaAgentServerRegisterCustomRecognition

• name: 名称
• recognition: 自定义识别器
• trans_arg: 传递给回调的参数

注册名为 name 的自定义识别器 recognition

MaaAgentServerRegisterCustomAction

• name: 名称
• action: 自定义操作
• trans_arg: 传递给回调的参数

注册名为 name 的自定义操作 action

MaaAgentServerAddResourceSink

• sink: 事件回调
• trans_arg: 传递给回调的参数

添加资源事件监听器，返回监听器 id

MaaAgentServerAddControllerSink

• sink: 事件回调
• trans_arg: 传递给回调的参数

添加控制器事件监听器，返回监听器 id

MaaAgentServerAddTaskerSink

• sink: 事件回调
• trans_arg: 传递给回调的参数

添加实例事件监听器，返回监听器 id

MaaAgentServerAddContextSink

• sink: 事件回调
• trans_arg: 传递给回调的参数

添加上下文事件监听器，返回监听器 id

MaaAgentServerStartUp

• identifier: 连接地址

启动服务，连接到 identifier

MaaAgentServerShutDown

停止服务

MaaAgentServerJoin

同步等待服务线程结束

MaaAgentServerDetach

分离服务线程