# 2.2 集成接口一览

## 关于 binding

不同语言的 binding 会有不同的命名方式，且会根据 [标准化接口](./4.2-标准化接口设计.md) 进行封装，请自行搜索实际的名称。部分接口可能直接在内部自动使用而不会提供（例如 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`: 所有可使用的截图方式，参见 [控制方式说明](2.4-控制方式说明.md#adb-screencap)
- `input_methods`: 所有可使用的输入方式，参见 [控制方式说明](2.4-控制方式说明.md#adb-input)
- `config`: 额外配置
- `agent_path`: MaaAgentBinary 路径

创建 Adb 控制器

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

### MaaWin32ControllerCreate

- `hWnd`: 窗口句柄
- `screencap_method`: 使用的截图方式，参见 [控制方式说明](2.4-控制方式说明.md#win32-screencap)
- `mouse_method`: 使用的鼠标输入方式，参见 [控制方式说明](2.4-控制方式说明.md#win32-input)
- `keyboard_method`: 使用的键盘输入方式，参见 [控制方式说明](2.4-控制方式说明.md#win32-input)

创建 Win32 控制器

### MaaAndroidNativeControllerCreate

- `config_json`: Android Native 控制器配置 JSON，必填字段：
  - `library_path`: Android Native 控制单元库路径
  - `screen_resolution.width`: 原始截图宽度，同时也是 touch 坐标宽度
  - `screen_resolution.height`: 原始截图高度，同时也是 touch 坐标高度
  - 可选字段：`display_id`（默认 `0`）、`force_stop`（默认 `false`）

创建 Android Native 控制器，用于在 Android 环境下通过 `MaaAndroidNativeControlUnit` 完成原生输入与截图。

> `screen_resolution` 必须与控制单元返回的原始截图分辨率和 touch 坐标系保持一致，否则截图会直接失败。

### MaaCustomControllerCreate

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

创建自定义控制器

### MaaDbgControllerCreate

- `read_path`: 图片目录（或单个图片文件）路径。连接时加载所有图片，截图时轮播。所有输入操作直接返回成功。

创建调试控制器

### MaaReplayControllerCreate

- `recording_path`: 录制 JSONL 文件路径，由 `MaaRecordControllerCreate` 写入。截图路径基于该文件所在目录解析。

创建回放控制器

### MaaRecordControllerCreate

- `inner`: 内层控制器，所有操作将转发到该控制器。录制控制器不取得 `inner` 的所有权。
- `recording_path`: 录制 JSONL 文件输出路径。截图会保存到同目录下的 `{stem}-Screenshot` 文件夹。可使用 `MaaReplayControllerCreate` 回放录制数据。

创建录制控制器，包装已有控制器并记录所有操作

### MaaPlayCoverControllerCreate

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

创建 PlayCover 控制器，用于在 macOS 上控制通过 [fork版PlayCover](https://github.com/hguandl/PlayCover/releases) 运行的 iOS 应用程序。详见 [控制方式说明](2.4-控制方式说明.md#playcover-macos)。

### MaaWlRootsControllerCreate

- `wlr_socket_path`: Wayland Socket 路径，如 `/run/user/1000/wayland-0`
- `use_win32_vk_code`: 是否将按键视为 Win32 Virtual-Key 键码（VK_*）。为 `true` 时，传入 `click_key` / `key_down` / `key_up` 的键码会被视为 Win32 VK 码并在内部转换为 Linux evdev 码；为 `false` 时按原始 evdev 码处理。默认 `false`

创建 WlRoots 控制器，用于在 Linux 上控制在 wlroots 合成器中运行的应用程序。详见 [控制方式说明](2.4-控制方式说明.md#wlroots-linux)。

### MaaGamepadControllerCreate

- `hWnd`: 窗口句柄，用于截图。如果不需要截图可以传 nullptr/None/null
- `gamepad_type`: 手柄类型，参见 [控制方式说明](2.4-控制方式说明.md#手柄类型)
- `screencap_method`: Win32 截图方式，参见 [控制方式说明](2.4-控制方式说明.md#win32-screencap)

创建 Gamepad 控制器，用于在 Windows 上模拟 Xbox 360 或 DualShock 4 手柄输入。详见 [控制方式说明](2.4-控制方式说明.md#gamepad-windows)。

注意

- 需要安装 [ViGEm Bus Driver](https://github.com/ViGEm/ViGEmBus/releases)

### MaaControllerDestroy

销毁控制器

### MaaControllerAddSink

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

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

### MaaControllerRemoveSink

- `ctrl`: 控制器
- `sink_id`: 监听器 id

移除控制器事件监听器

### MaaControllerClearSinks

- `ctrl`: 控制器

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

### MaaControllerSetOption

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

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

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

- ScreenshotUseRawSize  
    设置截图不缩放

- ScreenshotResizeMethod  
    设置截图缩放插值方法（0=INTER_NEAREST, 1=INTER_LINEAR, 2=INTER_CUBIC, 3=INTER_AREA, 4=INTER_LANCZOS4），默认为 INTER_AREA(3)

- BackgroundManagedKeys  
    声明 Win32 后台受管键域。声明成功后，现有 `MaaControllerPostClickKey`、`MaaControllerPostKeyDown`、`MaaControllerPostKeyUp` 以及 pipeline 中的 `ClickKey`、`LongPressKey`、`KeyDown`、`KeyUp` 会对命中的键自动走后台守护路径。该选项仅支持 Win32 控制器；其他控制器设置会失败。

### MaaControllerPostConnection

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

### MaaControllerPostClick

- `x`, `y`: 点击坐标

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

### MaaControllerPostClickV2

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

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

### MaaControllerPostClickKey

- `key`: 虚拟键码
  - [Adb 控制器](https://developer.android.com/reference/android/view/KeyEvent)
  - [Win32 控制器](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes)
  - [MacOS 控制器](https://github.com/phracker/MacOSX-SDKs/blob/master/MacOSX10.6.sdk/System/Library/Frameworks/Carbon.framework/Versions/A/Frameworks/HIToolbox.framework/Versions/A/Headers/Events.h#L183-L329)

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

### MaaControllerPostKeyDown

- `key`: 虚拟键码
  - [Adb 控制器](https://developer.android.com/reference/android/view/KeyEvent)
  - [Win32 控制器](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes)
  - [MacOS 控制器](https://github.com/phracker/MacOSX-SDKs/blob/master/MacOSX10.6.sdk/System/Library/Frameworks/Carbon.framework/Versions/A/Frameworks/HIToolbox.framework/Versions/A/Headers/Events.h#L183-L329)

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

### MaaControllerPostKeyUp

- `key`: 虚拟键码
  - [Adb 控制器](https://developer.android.com/reference/android/view/KeyEvent)
  - [Win32 控制器](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes)
  - [MacOS 控制器](https://github.com/phracker/MacOSX-SDKs/blob/master/MacOSX10.6.sdk/System/Library/Frameworks/Carbon.framework/Versions/A/Frameworks/HIToolbox.framework/Versions/A/Headers/Events.h#L183-L329)

异步抬起键。这是一个异步操作，会立即返回一个操作 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：中键）
  - MacOS 控制器：鼠标按键（0：左键，1：右键，2：中键）
- `x`, `y`: 触点位置
- `pressure`: 触点力度

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

### MaaControllerPostTouchMove

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

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

### MaaControllerPostTouchUp

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

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

### MaaControllerPostRelativeMove

- `dx`: 水平移动距离
- `dy`: 垂直移动距离

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

### MaaControllerPostScroll

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

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

> [!NOTE]
>
> - Win32 和 macOS 控制器，以及实现了 `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`: `type`, `path`, `image_count`, `image_index`
- `replay`: `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 格式）

获取操作信息

### MaaTaskerGetWaitFreezesDetail

- `wf_id`: Wait Freezes ID
- `node_name [out]`: 节点名缓冲区
- `phase [out]`: 阶段字符串缓冲区（"pre" / "post" / "repeat" / "context"）
- `success [out]`: 是否成功
- `elapsed_ms [out]`: 总耗时（毫秒）
- `reco_id_list [out]`: 识别号数组，每次画面对比的识别 ID
- `reco_id_list_size [in, out]`: 识别号数组大小（输入时表示缓冲区大小，输出时表示实际大小）
- `roi [out]`: 实际比较的 ROI 区域

获取等待画面静止的详细信息。通过回调中的 `wf_id` 获取，各 `reco_id` 可通过 `MaaTaskerGetRecognitionDetail` 查询对应的 draw 图片。

### 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`: 窗口

获取窗口句柄

> [!NOTE]
>
> - Win32 下，返回值语义为原生 `HWND`。
> - macOS 下，返回值语义为窗口的 `windowID`（`CGWindowID` / `SCWindow.windowID`），在接口层会强制转换为 `void*` 返回，因此它不是 Cocoa `NSWindow*` 指针。

### MaaToolkitDesktopWindowGetClassName

- `window`: 窗口

获取窗口类名

> [!NOTE]
>
> - Win32 下，返回值语义为窗口类名。
> - macOS 下，返回值语义为应用包名（`SCWindow.owningApplication.bundleIdentifier`）。

### MaaToolkitDesktopWindowGetWindowName

- `window`: 窗口

获取窗口名称

> [!NOTE]
>
> - Win32 下，返回值语义为窗口名称。
> - macOS 下，返回值语义为窗口标题（`SCWindow.title`）。

## 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

分离服务线程
