2.3-自定义任务.md

自定义任务

除依照流水线协议编写 Json 实现低代码开发外，MaaFramework 也支持通过多种方式自行编写代码来实现自定义任务：

• FFI（语言交互接口）

  MaaFramework 提供了 C 和 Python API，且理论上支持所有主流语言。
  但目前已适配的 Binding 较少，仅支持 C 和 Python，其他语言可能需要您自行编写（也欢迎在写完后向我们提交 PR！）。
  优点：执行效率相对较高，更符合标准编程范式。

• 执行器代理

  简单来说，开发者可以编写一个自己的 exe，并通过 MaaToolkit 相关接口传入 exe 路径。MaaFramework 会在执行到对应任务时，调用该 exe，并通过启动参数传入当前画面的图片、识别结果、任务名等信息。
  开发者可在自己的 exe 中执行任意操作，并可以按照 协议 直接输出（print / std::cout / ...）部分命令。MaaFramework 会通过管道捕获这些输出命令，执行如点击滑动、截图识别等动作，再通过管道传出执行结果。开发者可以使用标准输入（input / std::cin / ...）来获取这些结果。
  这里的 exe 指代任何可执行文件，包括 exe, bat, shell, python 脚本等（也同样支持 Linux / macOS 下的可执行文件）。
  优点：简单。

FFI

开发者可实现自定义动作、自定义识别器，并通过注册接口传入。
其中的 SyncContext 用于在自定义任务中调用如点击滑动、截图识别等。

• C 语言

  • 自定义识别器
  • 自定义动作
  • 注册接口
  • SyncContext
  • Sample

• Python

  • 自定义识别器
  • 自定义动作
  • 注册接口
  • SyncContext
  • Sample

执行器代理

启动参数

自定义识别器（CustomRecognizer）

对于自定义识别器，启动参数为：

/path/to/my_recognizer.exe  custom_arg_1  custom_arg_2  ...  sync_context  image_path  task_name  custom_recognition_param

• /path/to/my_recognizer.exe

  通过注册接口传入的可执行文件路径。若是 Python 等脚本，也可直接传入 Python.exe。

• custom_arg_1 custom_arg_2 ...

  通过注册接口传入的自定义参数（多个参数）。若是 Python 等脚本，其中第一个参数则为你的 .py 文件路径。

• sync_context

  按照协议向 MaaFramework 输出命令时，所需要带上的实例信息。详见 输入输出协议。

• image_path

  当前画面截图的图片文件路径。

• task_name

  当前正在执行的任务名。

• custom_recognition_param

  在流水线 Json 中定义的 custom_recognition_param 值。

自定义动作（CustomAction）

对于自定义动作，启动参数为：

/path/to/my_action.exe  custom_arg_1  custom_arg_2  ...  sync_context  task_name  custom_action_param  cur_box  cur_rec_detail

• /path/to/my_action.exe

  通过注册接口传入的可执行文件路径。若是 Python 等脚本，也可直接传入 Python.exe。

• custom_arg_1 custom_arg_2 ...

  通过注册接口传入的自定义参数（多个参数）。若是 Python 等脚本，其中第一个参数则为你的 .py 文件路径。

• task_name

  当前正在执行的任务名。

• sync_context

  按照协议向 MaaFramework 输出命令时，所需要带上的实例信息。详见 输入输出协议。

• custom_action_param

  在流水线 Json 中定义的 custom_action_param 值。

• cur_box

  本任务识别器当前识别到的目标位置。格式为 Json 数组，[x, y, w, h]。

• cur_rec_detail

  本任务识别器识别到的详细信息。格式为 Json，具体协议待补充~

输入输出协议

控制器代理执行的命令均为同步执行。且每输出一条命令后，都需要使用标准输入（input / std::cin / scanf / ...）取回执行结果，否则会影响后续命令的执行。

命令格式为 JSON，大致结构为

{
    "function": string,
    "sync_context": string,
    // ......
}

• function: string
  执行的命令，必选。 可选的值：RunTask | RunRecognition | RunAction | Click | Swipe | PressKey | InputText | TouchDown | TouchMove | TouchUp | Screencap

• sync_context: string
  实例信息，必选。启动自定义识别器/自定义动作时，由启动参数传入的字符串。

执行结果格式为 JSON，大致结果为

{
    "return": bool,
    // ......
}

• return: bool
  执行成功与否。

RunTask

执行某个子任务。

该命令需要更多的参数，结构为

{
    "function": "RunTask",
    "sync_context": string,
    "task_name": string,
    "task_param": object
}

• task_name: string
  任务名，必选。

• task_param: string
  任务额外参数，可选。

执行结果为

{
    "return": bool
}

RunRecognition

执行某个任务的识别部分。

该命令需要更多的参数，结构为

{
    "function": "RunRecognition",
    "sync_context": string,
    "image": string,
    "task_name": string,
    "task_param": object
}

• image: string
  待识别图片文件路径，必选。

• task_name: string
  任务名，必选。

• task_param: string
  任务额外参数，可选。

执行结果为

{
    "return": bool,
    "box": [int, int, int, int],
    "detail": any
}

RunAction

执行某个任务的动作部分。

该命令需要更多的参数，结构为

{
    "function": "RunAction",
    "sync_context": string,
    "task_name": string,
    "task_param": object,
    "cur_box": [int, int, int, int],
    "cur_rec_detail": any
}

• task_name: string
  任务名，必选。

• task_param: string
  任务额外参数，可选。

• cur_box: array<int, 4>
  模拟识别到的范围，必选。

• cur_rec_detail: any
  模拟识别到的详情，必选。

执行结果为

{
    "return": bool
}

Click

执行点击操作。

该命令需要更多的参数，结构为

{
    "function": "Click",
    "sync_context": string,
    "x": int,
    "y": int
}

执行结果为

{
    "return": bool
}

Swipe

执行滑动操作。

该命令需要更多的参数，结构为

{
    "function": "Swipe",
    "sync_context": string,
    "x1": int,
    "y1": int,
    "x2": int,
    "y2": int,
    "duration": int
}

执行结果为

{
    "return": bool
}

PressKey

执行按键操作。

该命令需要更多的参数，结构为

{
    "function": "PressKey",
    "sync_context": string,
    "keycode": int
}

执行结果为

{
    "return": bool
}

InputText

执行输入文本操作。

该命令需要更多的参数，结构为

{
    "function": "InputText",
    "sync_context": string,
    "input_text": string
}

执行结果为

{
    "return": bool
}

TouchDown

执行触摸按下操作。

该命令需要更多的参数，结构为

{
    "function": "TouchDown",
    "sync_context": string,
    "contact": int,
    "x": int,
    "y": int,
    "pressure": int
}

执行结果为

{
    "return": bool
}

TouchMove

执行触摸移动操作。

该命令需要更多的参数，结构为

{
    "function": "TouchMove",
    "sync_context": string,
    "contact": int,
    "x": int,
    "y": int,
    "pressure": int
}

执行结果为

{
    "return": bool
}

TouchUp

执行触摸抬起操作。

该命令需要更多的参数，结构为

{
    "function": "TouchUp",
    "sync_context": string,
    "contact": int
}

执行结果为

{
    "return": bool
}

Screencap

执行截图操作。

{
    "function": "Screencap",
    "sync_context": string
}

执行结果为

{
    "return": bool,
    "image": string
}

CachedImage

获取最近一次的截图。

{
    "function": "CachedImage",
    "sync_context": string
}

执行结果为

{
    "return": bool,
    "image": string
}