Project Interface V2 协议

注意: 本文档是关于 ProjectInterface 的编写和使用
文中将使用 PI 代指 ProjectInterface，Client 代指可以处理 PI 的工具

💡 v5.x 版本新引入了本 V2 协议，新增众多亮点功能，各通用 UI 正在集成适配中！
若您期望使用稳定版本，请参考 V1 协议，同时欢迎加入开发群催更 V2~

简介

所谓 ProjectInterface，即 MaaFramework 的一个标准化的项目结构声明，该声明目前包含 interface.json 一个文件。通过定义 PI，你可以使用 MaaFramework 的各种衍生工具。因此，即使你打算纯粹依靠通用编程语言集成，也建议定义包含基础信息的 PI。

目前尚无已支持 V2 协议的 UI

`interface.json`

该文件可以通过 schema 文件获得提示和校验功能
使用 VSCode 打开项目模板文件夹，可自动关联 schema 和文件

v2 版本读取的文件仍为 interface.json（但额外支持 json with comments）, sample 中为了便于区分 v1 暂时命名不同

整体结构

interface_version number
接口版本号，当前为 2，固定且必须设置。用于标识 ProjectInterface 协议版本。
languages object
多语言支持配置，键为语言代码，值为对应的翻译文件路径。若不指定，则默认仅支持中文。
json
```
"languages": {
    "zh_cn": "interface_zh.json",
    "en_us": "interface_en.json"
}
```
name string
项目唯一标识符，用作项目ID。
label string
项目显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示name字段的值。可选。
json
```
{
  "name": "MyProject", 
  "label": "$project_name"  // 国际化项目名称
}
```
title string
窗口标题，Client 会直接显示该内容，不添加其他修饰。可选，默认使用 name 和 version 拼接生成。支持国际化（以$开头）。
icon string
应用图标文件路径，相对于项目根目录。若不指定，则使用默认图标。支持国际化（以$开头）。
mirrorchyan_rid string
MirrorChyan 资源包标识符，用于资源管理和分发。
mirrorchyan_multiplatform boolean
是否支持多平台，影响资源包的打包和分发策略。
auto_update_ui boolean
是否支持独立更新UI。若为 false，则仅跟随资源发布更新UI，由资源作者在CI中指定UI版本，用户界面不显示UI更新选项。
auto_update_maafw boolean
是否支持独立更新MaaFramework。若为 false，则仅跟随资源发布更新MaaFramework，由资源作者在CI中指定框架版本，用户界面不显示框架更新选项。
github string
项目GitHub仓库地址，用于版本更新检查和问题反馈。
version string
项目版本号，Client 可以展示给用户，同时用于版本更新检查。
contact string
联系方式信息，显示在"关于"页面。支持文件路径、URL或直接文本，内容支持Markdown格式。支持国际化（以$开头）。
license string
项目许可证信息，显示在"关于"页面。支持文件路径、URL或直接文本，内容支持Markdown格式。支持国际化（以$开头）。
welcome string
欢迎消息，在用户首次使用时弹窗显示，亦可作为公告使用。支持文件路径、URL或直接文本，内容支持Markdown格式。系统会记录显示内容，当内容更新时会再次弹窗显示。支持国际化（以$开头）。
description string
项目描述信息，显示在"关于"页面。支持文件路径、URL或直接文本，内容支持Markdown格式。支持国际化（以$开头）。
controller object[]
控制器配置，为一个对象数组，含有预设的控制器信息。
- name string
  唯一名称标识符，用作控制器ID。
- label string
  显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示name字段的值。
- description string
  控制器详细描述信息。支持文件路径、URL或直接文本，内容支持Markdown格式。可选。支持国际化（以$开头）。
- icon string
  控制器图标文件路径，相对于项目根目录。可选。支持国际化（以$开头）。
- type 'Adb' | 'Win32'
  控制器类型，取值为 Adb 和 Win32。
- display_short_side number
  默认缩放分辨率的短边长度，用于屏幕适配。可选，默认720。与display_long_side和display_raw互斥。
- display_long_side number
  默认缩放分辨率的长边长度，用于屏幕适配。可选。与display_short_side和display_raw互斥。
- display_raw boolean
  是否使用原始分辨率进行截图，不进行缩放。可选，默认false。与缩放分辨率设置互斥。
- adb object
  Adb 控制器的具体配置。
  - input number
    可选。Adb 控制器的控制方式，不提供则使用默认。具体定义参见 Input和Screencap。
  - screencap number
    可选。Adb 控制器的截图方式，不提供则使用默认。具体定义参见 Input和Screencap。
  - config object
    可选。Adb 控制器的额外配置，不提供则使用空对象。具体定义参见 Adb Config。
- win32 object
  Win32 控制器的具体配置。
  - class_regex string
    可选。Win32 控制器搜索窗口类名使用的正则表达式。
  - window_regex string
    可选。Win32 控制器搜索窗口标题使用的正则表达式。
  - input number
    可选。Win32 控制器的控制方式，不提供则使用默认。具体定义参见 Input和Screencap。
  - screencap number
    可选。Win32 控制器的截图方式，不提供则使用默认。具体定义参见 Input和Screencap。
resource object[]
资源配置，为一个对象数组，含有资源加载的信息。
- name string
  唯一名称标识符，用作资源包ID。
- label string
  显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示name字段的值。可选。
- description string
  资源详细描述信息。支持文件路径、URL或直接文本，内容支持Markdown格式。可选。
- icon string
  资源图标文件路径，相对于项目根目录。可选。支持国际化（以$开头）。
- path string[]
  加载的路径数组。如果提供多个路径，会依次加载，后加载的资源会覆盖前加载的资源。
  支持通过 {PROJECT_DIR} 占位符指代 interface.json 文件所在的目录。系统会将字符串中的所有 {PROJECT_DIR} 替换为实际路径。由于当前工作目录默认为 interface.json 所在目录，相对路径可以直接使用。
  json
```
"resource": [
    {
        "name": "Official",
        "path": [
            "{PROJECT_DIR}/resource"  // 占位符会被替换为实际路径
        ]
    },
    {
        "name": "Custom", 
        "path": [
            "resource",              // 相对路径，相对于interface.json所在目录
            "resource_custom"        // 相对路径，相对于interface.json所在目录
        ]
    }
]
```
  注意: 资源不仅仅是 pipeline，也包含 image 和 model，因此不要直接指定 pipeline 目录。
- controller string[]
  可选。指定该资源包支持的控制器类型列表。数组元素应与 controller 配置中的 name 字段对应。若不指定，则表示支持所有控制器类型。
  当用户选择了某个控制器时，只有支持该控制器的资源包才会显示在用户界面中供选择。这允许为不同控制器类型提供专门优化的资源包。
  json
```
"resource": [
    {
        "name": "Android专用资源",
        "label": "$Android专用资源",
        "controller": ["Android"],
        "path": ["{PROJECT_DIR}/resource_android"]
    },
    {
        "name": "通用资源",
        "label": "$通用资源",
        "path": ["{PROJECT_DIR}/resource"]
    }
]
```
agent object
代理配置，为一个对象，含有子进程（AgentServer）的信息。
- child_exec string
  子进程路径，为系统路径中可执行文件。如在环境变量（系统变量、用户变量）中存在 Python 路径，可直接写 "python"。
- child_args string[]
  可选。子进程参数数组。
  支持通过 {PROJECT_DIR} 占位符指代 interface.json 文件所在的目录
  json
```
"agent": {
    "child_exec": "python",
    "child_args": [
        "{PROJECT_DIR}/agent/main.py",  // 使用占位符，替换路径后传递
        "--test-mode"                   // 固定字符串，原样传递
    ]
}
```
  说明：系统会将字符串中的所有 {PROJECT_DIR} 占位符替换为 interface.json 文件所在目录的实际路径。由于当前工作目录默认设置为 interface.json 所在目录，相对路径可以直接使用。
  注意：这里的路径指安装后 interface.json 文件所在的目录，不同项目请根据实际情况确定。
- identifier string
  可选。连接标识符，被用来创建一个通信套接字。填写则会被使用，否则自动创建。
task object[]
任务配置，为一个对象数组，含有可执行任务的信息。
- name string
  任务唯一标识符，用作任务ID。
- label string
  任务显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示name字段的值。可选。
- entry string
  任务入口，为 pipeline 中 Task 的名称。
- default_check boolean
  是否默认选中该任务。可选，默认false。Client在初始化时会根据该值决定是否默认勾选该任务。
- description string
  任务详细描述信息，帮助用户理解任务功能。支持文件路径、URL或直接文本，内容支持Markdown格式。可选。
- icon string
  任务图标文件路径，相对于项目根目录。用于在用户界面中显示。可选。支持国际化（以$开头）。
- resource string[]
  可选。指定该任务支持的资源包列表。数组元素应与 resource 配置中的 name 字段对应。若不指定，则表示该任务在所有资源包中都可用。
  当用户选择了某个资源包时，只有支持该资源包的任务才会显示在用户界面中供选择。这允许为不同资源包提供专门的任务配置，比如活动任务只在特定资源包中可用。
  json
```
"task": [
    {
        "name": "活动任务",
        "label": "$活动任务",
        "entry": "ActivityTask",
        "resource": ["Official"],
        "description": "仅在官服资源包中可用的活动任务"
    },
    {
        "name": "通用任务",
        "label": "$通用任务", 
        "entry": "CommonTask"
    }
]
```
- pipeline_override pipeline
  可选。任务参数，执行任务时会覆盖已加载的资源。该项结构与 pipeline 中的 json 文件完全一致，需要包含任务名部分，例如:
  json
```
"pipeline_override": {
    "Quit": {
        "enabled": true
    }
}
```
- option string[]
  可选。任务配置项，为一个数组，含有若干后续 option 对象中的键的值，Client 会根据要求用户进行选择。
  Client 可以使用 option 中的顺序来展示配置项。
option record<string, object>
配置项定义，为一个对象映射，含有配置项的信息。
- key
  唯一名称标识符，任务会使用该名称进行引用。
- type string
  配置项类型。可选，默认 "select"。可选值：
  - "select": 下拉选项框，用户从预定义的选项中选择
  - "input": 用户输入框，允许用户手动输入内容
- label string
  配置项显示标签，用于在用户界面中展示。支持国际化字符串（以$开头）。可选。
- description string
  配置项详细描述信息，帮助用户理解配置项的作用。支持文件路径、URL或直接文本，内容支持Markdown格式。可选。支持国际化（以$开头）。
- icon string
  配置项图标文件路径，相对于项目根目录。可选。支持国际化（以$开头）。
- cases object[]
  仅在 type 为 "select" 时使用。可选项，为一个对象数组，含有各个可选项的信息。
  Client 可以使用 cases 中的顺序来展示可选项。
  - name string
    选项唯一标识符，用作选项ID。
  - label string
    选项显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示name字段的值。可选。
  - description string
    选项详细描述信息。支持文件路径、URL或直接文本，内容支持Markdown格式。可选。支持国际化（以$开头）。
  - icon string
    选项图标文件路径，相对于项目根目录。可选。支持国际化（以$开头）。
  - option string[]
    子配置项列表。可选。只有当用户选中当前选项时，才会显示这些子配置项。这些子配置项同样放在外层的 option 中定义，支持无限嵌套。
  - pipeline_override pipeline
    同 task 中的 pipeline_override，在选项激活时生效。
- inputs object[]
  仅在 type 为 "input" 时使用。输入配置，为一个对象数组，定义用户可输入的字段。
  - name string
    输入字段唯一标识符，用作输入字段ID。
  - label string
    输入字段显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示name字段的值。可选。
  - description string
    输入字段详细描述信息，帮助用户理解输入要求。支持文件路径、URL或直接文本，内容支持Markdown格式。可选。支持国际化（以$开头）。
  - default string
    输入字段的默认值。可选。
  - pipeline_type string
    输入字段在 pipeline_override 中的数据类型。可选值："string", "int", "bool"。当使用 pipeline_override 中的变量替换时，会根据该类型进行类型转换。
  - verify string
    正则表达式，用于校验用户输入是否合法。可选。
- pipeline_override pipeline
  当配置项为 "input" 类型时使用，作为用户输入内容的替换模板。支持在字符串中使用 {名称} 格式引用输入字段的值。可选。
- default_case string
  默认选项名称，仅在 type 为 "select" 时使用。Client 可以使用该值作为选项的初始选中值。可选。

配置项示例

select 类型选项示例

json

{
  "option": {
    "作战关卡": {
      "type": "select",
      "label": "$选择作战关卡",
      "description": "选择要刷的关卡",
      "default_case": "3-9 厄险",
      "cases": [
        {
          "name": "3-9 厄险（百灵百验鸟）",
          "label": "$3-9厄险",
          "description": "刷百灵鸟",
          "icon": "百灵鸟.png",
          "option": [
            "使用理智药",
            "刷完xxx"
          ],
          "pipeline_override": {
            "EnterTheShow": {
              "next": "MainChapter_3"
            }
          }
        }
      ]
    }
  }
}

input 类型选项示例

json

{
  "option": {
    "自定义关卡": {
      "type": "input",
      "label": "自定义关卡",
      "description": "自己选打什么关",
      "icon": "扳手.png",
      "inputs": [
        {
          "name": "章节号",
          "label": "$章节号",
          "description": "关卡章节号，用阿拉伯数字表示",
          "default": "4",
          "pipeline_type": "string",
          "verify": "^\\d+$"
        },
        {
          "name": "超时时间",
          "label": "$超时时间",
          "description": "等待超时时间",
          "default": "20000",
          "pipeline_type": "int",
          "verify": "^\\d+$"
        }
      ],
      "pipeline_override": {
        "EnterTheShow": {
          "next": "MainChapter_{章节号}",
          "timeout": "{超时时间}"
        }
      }
    }
  }
}

Input和Screencap

Input

定义 MaaFramework 会使用何种方式来控制。

Adb Input

参考 MaaDef.h

将下面选择的方式 按位或 合并为一个值提供。MaaFramework 将会按照固定优先级顺序尝试所有提供的方式，选择首个可用方式。

默认尝试除 EmulatorExtras 外所有方式。

优先级: EmulatorExtras > Maatouch > MinitouchAndAdbKey > AdbShell

AdbShell 1
使用 adb 进程进行控制。
MinitouchAndAdbKey 2
使用 adb 进程进行按键控制，使用 minitouch 工具进行触摸控制。
Maatouch 4
使用 maatouch 工具控制。
EmulatorExtras 8
使用模拟器专用工具进行控制。目前支持的模拟器:
- MuMu 12
- 雷电 9

Win32 Input

参考 MaaDef.h

选择下面的值提供。

无默认值。Client 可以选择一个作为默认值。

Win32 下不同程序处理输入的方法不同，不存在一个通用方式。

Seize 1
抢占式控制。该模式下用户的光标将直接被 MaaFramework 移动，目标窗口将会保持激活。
SendMessage 2
使用 SendMessage 控制。该模式下目标窗口可以失焦。

Screencap

定义 MaaFramework 会使用何种方式来截图。

Adb Screencap

参考 MaaDef.h

将下面选择的方式 按位或 合并为一个值提供。MaaFramework 将会尝试所有提供的方式，选择最快的可用方式。

默认尝试除 RawByNetcat，MinicapDirect，MinicapStream 外所有方式。

MinicapDirect 和 MinicapStream 由于会编码为 jpg，为有损编码，将显著降低模板匹配的效果，不建议使用。

EncodeToFileAndPull 1
通过内置 screencap 进程截图，编码为 png 输出到文件，通过 adb 进程拉取文件，读取文件。
Encode 2
通过内置 screencap 进程截图，编码为 png，通过 adb 进程管道传输。
RawWithGzip 4
通过内置 screencap 进程截图，通过 gzip 压缩，通过 adb 进程管道传输。
RawByNetcat 8
通过内置 screencap 进程截图，通过 nc 进程网络传输。
MinicapDirect 16
通过 minicap 工具截图和编码为 jpg，通过 adb 进程管道传输。
MinicapStream 32
通过 minicap 工具流式截图和编码为 jpg，通过 adb 进程管道传输。
EmulatorExtras 64
使用模拟器专用工具进行截图。

Win32 Screencap

参考 MaaDef.h

选择下面的值提供。

无默认值。Client 可以选择一个作为默认值。

Win32 下不同程序处理绘制的方法不同，不存在一个通用方式。

GDI 1
FramePool 2
DXGI_DesktopDup 4

Adb Config

可以通过 config 对象覆盖控制器的部分默认逻辑。通常只有在使用 EmulatorExtras 且进行多开时会需要特定配置。

国际化支持

对于所有支持国际化的字符串字段，如果字符串以 $ 开头，则表示该字符串是国际化字符串，Client 需要从翻译文件中读取实际值再显示。

例如：

json

{
  "name": "MyDemo3",
  "label": "$MyDemo3",
  "controller": [
    {
      "name": "Android",
      "label": "$安卓端"
    }
  ]
}

对应的翻译文件（如 interface_zh.json）：

json

{
  "MyDemo3": "我的演示3",
  "安卓端": "安卓设备"
}

资源覆盖

后加载的资源中如果发现了和已加载资源同名的任务，会对任务进行合并。通常情况下，可以认为新的任务的顶级键会替换旧任务的。例如:

旧任务

json

{
    "task1": {
        "enabled": false,
        "recognition": "DirectHit",
        "next": [ "T1", "T2" ]
    }
}

新任务

json

{
    "task1": {
        "enabled": true,
        "action": "Click",
        "next": [ "T2", "T3" ]
    }
}

合并后的任务

jsonc

{
    "task1": {
        "enabled": true,
        "recognition": "DirectHit",
        "action": "Click",
        "next": [ "T2", "T3" ]       // 直接替换，内部不会合并
    }
}

Project Interface V2 协议 ​

简介 ​

interface.json ​

整体结构 ​

配置项示例 ​

select 类型选项示例 ​

input 类型选项示例 ​

Input和Screencap ​

Input ​

Adb Input ​

Win32 Input ​

Screencap ​

Adb Screencap ​

Win32 Screencap ​

Adb Config ​

国际化支持 ​

资源覆盖 ​

Project Interface V2 协议

简介

`interface.json`

整体结构

配置项示例

select 类型选项示例

input 类型选项示例

Input和Screencap

Input

Adb Input

Win32 Input

Screencap

Adb Screencap

Win32 Screencap

Adb Config

国际化支持

资源覆盖