集成接口一览

关于 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)	res.post_bundle(path)	res.post_bundle(path)
MaaControllerPostClick(ctrl_handle, x, y)	ctrl.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)

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: 插件库路径或名称

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

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

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: 额外配置

创建调试控制器

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 查询状态。

MaaControllerPostSwipe

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

异步滑动。这是一个异步操作，会立即返回一个操作 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 查询状态。

MaaControllerPostScroll

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

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

NOTE

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

MaaControllerPostScreencap

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

MaaControllerPostShell

• cmd: 要执行的 shell 命令

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

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

MaaControllerStatus

• id: 操作 id

查询 id 对应操作状态

MaaControllerWait

• id: 操作 id

等待 id 对应操作完成

MaaControllerConnected

判断是否已连接

MaaControllerCachedImage

• buffer [out]: 输出缓冲区

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

MaaControllerGetShellOutput

• buffer [out]: 输出缓冲区

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

MaaControllerGetUuid

• buffer [out]: 输出缓冲区

获取设备 uuid，写入到 buffer

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

清理所有可查询的信息

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

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 的命中计数

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 客户端

传入空则自动生成

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

分离服务线程