MaaFramework

简体中文

English

简体中文

English

Appearance

3.3 Project Interface V2 协议 ​

注意: 本文档是关于 ProjectInterface 的编写和使用

文中将使用 PI 代指 ProjectInterface，Client 代指可以处理 PI 的工具

简介 ​

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

TIP

你可以前往 社区项目 中查找使用 PI 的通用 UI 及其他工具

版本说明 ​

由于业务进度高速迭代，MaaFramework 的发版节奏与 PI 的迭代节奏无法很好对齐。因此，PI 将进行单独的版本控制，PI 的版本号与 MaaFramework release 版本号并不完全同步。

我们将独立版本时（2026-1-30）的版本号定为 v2.1.0，后续新增与修复将会在文档中标注版本号。

日期版本变更内容
2026-1-30v2.1.0独立版本发布
2026-1-30v2.2.0新增 attach_resource_path 和 import 字段
2026-2-23v2.3.0新增 checkbox 多选类型、option.controller、option.resource、全局/resource/controller 级 option、focus.display 展示渠道标签、preset 预设配置字段、import 支持导入 preset
2026-3-5v2.3.1明确 option 适用性过滤规则
2026-3-9v2.4.0新增顶层 group 分组声明与 task.group 任务分组字段
2026-3-23v2.5.0约定 Client 启动 Agent 子进程时注入 PI_* 环境变量，传递 UI / Client 属性及当前选中的控制器与资源（i18n 已解析）
2026-4-18v2.6.0新增 resource.hash 资源完整性校验字段
2026-5-6v2.7.0新增 pretask 字段，用于在 Controller 启动前执行自定义程序，并支持将 option 取值作为最后一个参数传入
2026-6-30v2.8.0新增 setting 任务设置页 UI 声明字段；import 支持导入 global_option 与 setting 字段；新增 hotkey 配置项类型
2026-7-1v2.8.1pretask 支持 controller / resource 过滤字段，与 task.controller / task.resource 语义一致
2026-7-22v2.9.0新增 telemetry 匿名遥测（数据埋点）配置字段
2026-8-5v2.9.1新增 focus 消息模板对象的 trace 字段，用于按回调消息类型控制遥测是否上传节点结果
2026-8-23v2.9.2新增 telemetry.sentry.failure_attachments_sample_rate 失败诊断附件独立采样率字段
2026-8-24v2.10.0input 类型选项的 inputs[] 新增 password 字段，用于标记密码/密钥输入
2026-9-6v2.10.1checkbox 类型新增 min_count / max_count 字段，用于限制最小 / 最大选择数量
2026-9-8v2.10.2welcome 支持字符串数组

interface.json ​

TIP

该文件可以通过 schema 文件获得提示和校验功能

使用 VSCode 打开 项目模板 文件夹，可自动关联 schema 和文件

整体结构 ​

  • interface_version number
    接口版本号，当前为 2，固定且必须设置。用于标识 interface.json 的 JSON 结构主版本。PI 文档另有独立的语义化版本（如 v2.5.0 的环境变量约定），二者不必一一对应。

  • languages object
    多语言支持配置，键为语言代码，值为对应的翻译文件路径。若不指定，则默认仅支持中文。
    文件相对路径为 interface.json 同目录下的相对路径。

    jsonc
    "languages": {
    "zh_cn": "interface_zh.json",
    "en_us": "interface_en.json"
}

  • name string
    项目唯一标识符，用作项目ID。

  • label string
    项目显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示 name 字段的值。可选。

    jsonc
    {
  "name": "MyProject", 
  "label": "$project_name"  // 国际化项目名称
}

  • title string
    窗口标题，Client 会直接显示该内容，不添加其他修饰。可选，默认使用 name 和 version 拼接生成。支持国际化（以$开头）。

  • icon string
    应用图标文件路径，相对于项目根目录。若不指定，则使用默认图标。支持国际化（以$开头）。

  • mirrorchyan_rid string
    MirrorChyan 资源包标识符，用于资源管理和分发。

  • mirrorchyan_multiplatform boolean
    是否支持多平台，影响资源包的打包和分发策略。

  • github string
    项目GitHub仓库地址，用于版本更新检查和问题反馈。
    软件更新约定：
    经过版本历史的惨痛教训， 我们期望通用 UI 仅提供对该 github release 的更新功能，不要提供单独更新 UI 本体 / MaaFW 的功能。
    资源作者发版时自行打包其指定的 UI / MaaFW，以实现用户侧的资源版本对应唯一的 UI 和 MaaFW 版本，规避版本混搭带来的各种问题。

  • version string
    项目版本号，Client 可以展示给用户，同时用于版本更新检查。

  • contact string
    联系方式信息，显示在"关于"页面。支持文件路径、URL或直接文本，内容支持Markdown格式。支持国际化（以$开头）。

  • license string
    项目许可证信息，显示在"关于"页面。支持文件路径、URL或直接文本，内容支持Markdown格式。支持国际化（以$开头）。

  • welcome string | string[] 💡 v2.10.2
    欢迎消息，在用户首次使用时弹窗显示，亦可作为公告使用。每个字符串支持文件路径、URL或直接文本，内容支持Markdown格式，并支持国际化（以$开头）。公告标题应写入Markdown内容中。
    v2.10.2 起可使用字符串数组声明多条公告，Client 应按数组顺序展示。数组不能为空。

    jsonc
    "welcome": [
    "$notice",
    "announcements/2026/update.md"
]

    Client 应记录完整的有序公告列表；公告增删、重排以及任一内容更新均视为内容更新，并应再次提示用户。旧版 Client 可能无法解析数组写法，需要兼容旧版 Client 时请继续使用单个字符串写法。

  • description string
    项目描述信息，显示在"关于"页面。支持文件路径、URL或直接文本，内容支持Markdown格式。支持国际化（以$开头）。

  • telemetry object 💡 v2.9.0
    匿名遥测（数据埋点）配置，用于向资源作者自己的遥测平台上报崩溃与任务运行统计。并非所有 Client 都会支持。可选；未配置时不进行任何遥测。该字段作为遥测配置的统一容器，当前提供 sentry 子字段，未来可扩展其他平台。

    数据归属与隐私约定：

    • 遥测配置指向资源作者自己的平台项目，数据天然按项目隔离；不同软件使用不同配置即可区分。若多个软件共用同一配置，Client 应通过 release / tag（如项目名、version）在同一项目内区分。

    • Client 应遵循用户授权优先：即使配置了本字段，是否上报仍由用户在 Client 中的开关决定（建议默认开启、可随时关闭，且调试 / 开发版本强制禁用）。

    • sentry object
      基于 Sentry 的遥测配置。

      • dsn string
        Sentry 项目的 DSN。必填；缺省或为空字符串时不启用 Sentry 遥测。

      • tracing boolean
        是否启用性能 / 事务上报（任务开始、结束及各子任务结果以事务 / Span 形式上报）。可选，默认 true。关闭后仅上报崩溃 / 错误，不上报任务生命周期。

      • traces_sample_rate number
        事务采样率，取值 0~1。可选，默认 1.0。任务为低频业务事件，全量上报可获得精确的成功 / 失败统计；用户量较大时可调低以控制 Sentry 配额，但统计将变为抽样。

      • failure_attachments_sample_rate number 💡 v2.9.2
        失败诊断附件独立采样率，取值 0~1。可选，默认 1.0；0 表示不上传附件，1 表示上传所有符合条件的附件。仅控制随失败 / 错误事件上传的附件，不影响对应的 Error Event、Sentry Logs 或事务采样。Client 不支持采集失败诊断附件时可忽略此字段。

      • environment string
        环境标签（如 production、beta），用于在 Sentry 中区分。可选；缺省由 Client 决定（如使用更新频道，或回退为 production）。

  • controller object[]
    控制器配置，为一个对象数组，含有预设的控制器信息。

    • name string
      唯一名称标识符，用作控制器ID。

    • label string
      显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示 name 字段的值。

    • description string
      控制器详细描述信息。支持文件路径、URL或直接文本，内容支持Markdown格式。可选。支持国际化（以$开头）。

    • icon string
      控制器图标文件路径，相对于项目根目录。可选。支持国际化（以$开头）。

    • type 'Adb' | 'Win32' | 'MacOS' | 'PlayCover' | 'Gamepad' | 'Linux'
      控制器类型，取值为 Adb、Win32（仅 Windows）、MacOS（仅 macOS）、PlayCover（仅 macOS）、Gamepad（仅 Windows）和 Linux （仅 Linux）。

    • display_short_side number
      默认缩放分辨率的短边长度，用于屏幕适配。可选，默认720。与display_long_side、display_expand和display_raw互斥。

    • display_long_side number
      默认缩放分辨率的长边长度，用于屏幕适配。可选。与display_short_side、display_expand和display_raw互斥。

    • display_expand [number, number]
      Unity Canvas Scaler 的 Expand 语义参考分辨率 [width, height]：scale = max(width / raw_width, height / raw_height)，保持源宽高比，输出两边均不小于参考。可选。与display_short_side、display_long_side和display_raw互斥。

    • display_raw boolean
      是否使用原始分辨率进行截图，不进行缩放。可选，默认false。与缩放分辨率设置互斥。

    • permission_required boolean
      是否需要管理员权限运行该控制器。可选，默认 false。
      在运行任务前，若当前进程不是管理员，会提示并尝试以管理员身份重新启动。

    • attach_resource_path string[] 💡 v2.2.0
      可选。附加资源路径数组。将会在 resource.path 加载完成后，额外加载这些路径下的资源。

    • option string[] 💡 v2.3.0
      可选。控制器级的选项配置，为一个字符串数组，数组元素应与外层 option 配置中的键名对应。
      该选项生成的参数会参与到所有使用该控制器的任务的 pipeline override 中，起到控制器级参数传递的作用。
      若被引用的 option 不支持当前 controller/resource 条件，则该 option 的 pipeline_override（含其嵌套 option.option）不参与合并。 💡 v2.3.1

    • adb object
      Adb 控制器的具体配置。

      注意： V2 协议中。Adb 控制器的 input/screencap 由 MaaFramework 自动检测和选择最优方式，无需手动配置。

    • win32 object
      Win32 控制器的具体配置。

      • class_regex string
        可选。Win32 控制器搜索窗口类名使用的正则表达式。

      • window_regex string
        可选。Win32 控制器搜索窗口标题使用的正则表达式。

      • mouse string
        可选。Win32 控制器的鼠标控制方式，不提供则使用默认。详见 控制方式说明。

      • keyboard string
        可选。Win32 控制器的键盘控制方式，不提供则使用默认。详见 控制方式说明。

      • screencap string
        可选。Win32 控制器的截图方式，不提供则使用默认。详见 控制方式说明。

    • macos object
      MacOS 控制器的具体配置。

      • title_regex string
        可选。MacOS 控制器搜索窗口标题使用的正则表达式。

      • screencap string
        可选。MacOS 控制器的截图方式，不提供则使用默认。详见 控制方式说明。

      • input string
        可选。MacOS 控制器的输入方式，不提供则使用默认。详见 控制方式说明。

    • playcover object
      PlayCover 控制器的具体配置（仅 macOS）。用于控制通过 PlayCover 运行的 iOS 应用。详见 控制方式说明。

      • uuid string
        可选。目标应用的 Bundle Identifier，不提供则使用默认 maa.playcover，仅作为控制器标识符，与被操控应用无关。

    • gamepad object
      Gamepad 控制器的具体配置（仅 Windows）。用于创建虚拟游戏手柄进行游戏控制。需要安装 ViGEm Bus Driver。详见 控制方式说明。

      • class_regex string
        可选。Win32 控制器搜索窗口类名使用的正则表达式。

      • window_regex string
        可选。Win32 控制器搜索窗口标题使用的正则表达式。

      • gamepad_type string
        可选。虚拟手柄类型，取值为 Xbox360、DualShock4（或 DS4）。不提供则默认使用 Xbox360。

      • screencap string
        可选。截图方式，不提供则使用默认。仅当配置了窗口正则时有效。详见 控制方式说明。

    • linux object
      Linux 控制器的具体配置。详见 控制方式说明。

      • screencap string
        可选。Linux 控制器的截图方式，不提供则使用默认。

      • input string
        可选。Linux 控制器的输入方式，不提供则使用默认。

      • use_win32_vk_code bool 可选。为 true 时按键被视为 Win32 Virtual-Key 键码，内部转换为 Linux evdev 码；为 false 时按原始 evdev 码处理。默认 false。

      • pipewire_source string
        可选。PipeWire 截图的流来源：Gamescope 直连 gamescope 节点（node id 运行时发现），Portal 走 xdg-desktop-portal ScreenCast。仅当 screencap 为 PipeWire 时有效。默认 Gamescope。

  • resource object[]
    资源配置，为一个对象数组，含有资源加载的信息。

    • name string
      唯一名称标识符，用作资源包ID。

    • label string
      显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示 name 字段的值。可选。

    • description string
      资源详细描述信息。支持文件路径、URL或直接文本，内容支持Markdown格式。可选。

    • icon string
      资源图标文件路径，相对于项目根目录。可选。支持国际化（以$开头）。

    • path string[]
      加载的路径数组。如果提供多个路径，会依次加载，后加载的资源会覆盖前加载的资源。
      文件相对路径为 interface.json 同目录下的相对路径。
      注意: 资源不仅仅是 pipeline，也包含 image 和 model，因此不要直接指定 pipeline 目录。

    • controller string[]
      可选。指定该资源包支持的控制器类型列表。数组元素应与 controller 配置中的 name 字段对应。若不指定，则表示支持所有控制器类型。
      当用户选择了某个控制器时，只有支持该控制器的资源包才会显示在用户界面中供选择。这允许为不同控制器类型提供专门优化的资源包。

    • option string[]
      可选。资源包级的选项配置，为一个字符串数组，数组元素应与外层 option 配置中的键名对应。
      该选项生成的参数会参与到所有任务的 pipeline override 中，起到资源包级参数传递的作用。
      若被引用的 option 不支持当前 controller/resource 条件，则该 option 的 pipeline_override（含其嵌套 option.option）不参与合并。 💡 v2.3.1

    • hash string 💡 v2.6.0
      可选。资源完整性校验值。该值应为仅加载 path 后通过 MaaResourceGetHash 获取的 hash 字符串。
      校验时机为加载完 path 后、加载 controller.attach_resource_path 之前。
      若实际 hash 与该值不匹配，应向用户发出警告（例如建议重新下载资源包），但不应阻止继续使用。
      调试版本（如预发布版本）可跳过此校验。若未设置此字段，无需校验。

      jsonc
      "resource": [
    {
        "name": "Android专用资源",
        "label": "$Android专用资源",
        "controller": ["Android"],
        "path": ["resource_android"]
    },
    {
        "name": "通用资源",
        "label": "$通用资源",
        "path": ["resource"],
        "hash": "1a2b3c4d"
    }
]

  • pretask object | object[] 💡 v2.7.0
    可选。Controller 启动前执行的预任务配置，可以是单个对象或对象数组。Client 应在创建或连接 Controller 前按顺序启动这些程序，并等待其执行结束。若预任务启动失败或返回非零退出码，Client 应中止本次启动并向用户报告错误。
    预任务的 CWD 为 interface.json 所在目录。
    同一 pretask 字段也可出现在由顶层 import 加载的其他 PI 片段文件中；Client 应将各处的预任务合并为一条有序列表：先执行主 interface.json 中的条目（单个对象视为一项），再按 import 数组顺序依次追加各被引用文件中的 pretask（若为数组则按数组顺序；若为单个对象则视为一项）。实际执行顺序与该合并后的列表一致。

    • resource string[] 💡 v2.8.1
      可选。指定该预任务支持的资源包列表。数组元素应与 resource 配置中的 name 字段对应。若不指定，则表示该预任务在所有资源包中都可用。Client 可将不支持当前资源包的预任务隐藏，或以不可用（灰色/禁用）状态展示以提示用户。

    • controller string[] 💡 v2.8.1
      可选。指定该预任务支持的控制器类型列表。数组元素应与 controller 配置中的 name 字段对应。若不指定，则表示该预任务在所有控制器类型中都可用。Client 可将不支持当前控制器的预任务隐藏，或以不可用（灰色/禁用）状态展示以提示用户。

    • exec string
      必须。要执行的程序路径，可以是系统 PATH 中的可执行文件，例如 "python"。

    • args string[]
      可选。固定参数数组，按顺序传递给 exec。

    • name string
      可选。预任务的唯一标识符，建议项目内不重复，便于 Client 在配置文件、日志中区分不同预任务。Client 可在 name 缺省时回退到 exec 作为标识。

    • label string
      可选。预任务在 Client UI 中展示的名称，支持国际化字符串（以 $ 开头）。若不设置，Client 可回退到 name 或 exec。

    • description string
      可选。预任务的详细说明，用于 Client UI 中的提示/Tooltip。支持国际化字符串、文件路径或 URL，内容支持 Markdown 格式（与 task.description 相同语义）。

    • icon string
      可选。预任务在 Client UI 中显示的图标路径，相对于 interface.json 所在目录。支持国际化字符串。

    • option string[]
      可选。预任务配置项，为一个数组，数组元素应与外层 option 配置中的键名对应。Client 会根据这些配置项让用户进行选择。
      若设置了 option，Client 应将这些 option 的当前取值序列化为单行紧凑 JSON 字符串，并自动追加为最后一个参数，位于 args 之后。若未设置或为空，则不追加该 JSON 参数。
      该 JSON 对象以 option 键名为字段名，取值类型与 preset.task[].option 中的 OptionValue 一致：select / switch 为 case.name 字符串，checkbox 为 case.name 字符串数组，input 为输入字段 name 到字符串值的对象。因用户选择而激活的子配置项（option.option）也应以其自身 option 键名加入该对象；不满足当前 controller / resource 限制的 option 不应加入。
      传给预任务进程的 JSON 中，password 为 true 的字段仍应使用解密后的原文（供程序使用），但 Client 不得将该 JSON 或其中的原文写入日志。 💡 v2.10.0
      pretask.option 仅用于生成传给预任务进程的参数，不参与 pipeline_override 合并。

    单个 pretask 示例：

    jsonc
    "pretask": {
    "exec": "python",
    "args": [
        "./scripts/prepare.py",
        "--before-controller"
    ],
    "option": [
        "启动前配置"
    ]
}

    若用户选择后的 option 取值为：

    json
    {
    "启动前配置": "清理缓存"
}

    则 Client 实际传入的参数等价于：

    jsonc
    [
    "./scripts/prepare.py",
    "--before-controller",
    "{\"启动前配置\":\"清理缓存\"}"
]

    多个 pretask 示例：

    jsonc
    "pretask": [
    {
        "exec": "python",
        "args": ["./scripts/check_env.py"]
    },
    {
        "exec": "./tools/bootstrap",
        "args": ["--fast"],
        "option": ["启动前配置"]
    }
]

    通过 import 分文件管理 pretask：

    与 task、preset 类似，预任务也可拆到独立文件中由 import 引用。例如：

    jsonc
    // interface.json
{
    "import": [
        "pretask_common.json"
    ],
    "pretask": {
        "exec": "python",
        "args": ["./scripts/main_prepare.py"]
    }
}
    jsonc
    // pretask_common.json
{
    "pretask": [
        {
            "exec": "python",
            "args": ["./scripts/check_env.py"]
        }
    ]
}

    合并后，Client 应先执行 main_prepare.py，再执行 check_env.py，然后再启动 Controller。

  • agent object | object[]
    代理配置，可以是单个对象或对象数组，含有子进程（AgentServer）的信息。支持同时配置多个 Agent 以实现更复杂的自动化场景。
    自 v2.5.0 起，Client 在启动该子进程时还应按约定注入以 PI_ 为前缀的环境变量，详见下文 Agent 子进程环境变量 小节。

    • child_exec string
      子进程路径，为系统路径中可执行文件。如在环境变量（系统变量、用户变量）中存在 Python 路径，可直接写 "python"。
      CWD 为 interface.json 所在目录。

    • child_args string[]
      可选。子进程参数数组。

    • identifier string
      可选。连接标识符，被用来创建一个通信套接字。填写则会被使用，否则自动创建。

    单个 Agent 示例：

    jsonc
    "agent": {
    "child_exec": "python",
    "child_args": [
        "./agent/main.py",              // 注意 cwd 为 interface.json 所在目录
        "--test-mode"                   // 固定字符串，原样传递
    ]
}

    多个 Agent 示例：

    jsonc
    "agent": [
    {
        "child_exec": "python",
        "child_args": ["./agent/recognition.py"]
    },
    {
        "child_exec": "python",
        "child_args": ["./agent/action.py"]
    }
]

Agent 子进程环境变量 💡 v2.5.0 ​

Agent 与 MaaFramework 主进程分离运行时，子进程无法自动获知通用 UI 的名称与版本、界面语言、用户当前选中的控制器与资源包等信息；这些内容也不在 MaaFW C API 的常规回调中暴露。为便于自定义识别/动作等逻辑读取 Client 侧上下文 与 当前 PI 选择在运行时的快照，约定由 Client 在启动 agent 子进程时，向进程环境注入下列变量（名称全大写，值为字符串）。

变量名说明
PI_INTERFACE_VERSIONClient 在「PI 扩展能力」侧实现的协议版本，语义化版本字符串（如 v2.5.0）。子进程可据此判断是否依赖某批变量或行为；不要与 interface.json 中的数字字段 interface_version（当前固定为 2）混为一谈。
PI_CLIENT_NAME通用 UI / Client 名称标识，如 MFAA、MXU、VSCODE、MPE、MaaDebugger 等。
PI_CLIENT_VERSIONClient 自身版本号（语义化版本字符串，由 Client 定义）。
PI_CLIENT_LANGUAGE当前 UI 语言代码，如 zh_cn、en_us（与 languages 键或 Client 约定一致即可）。
PI_CLIENT_MAAFW_VERSION该 Client 集成/打包的 MaaFramework 库版本（语义化版本字符串）。
PI_VERSION与 interface.json 顶层 version 字段一致，表示资源项目版本号。
PI_CONTROLLER单行 JSON 字符串：当前用户选中的那条 controller 数组元素对应的完整对象。所有支持 i18n 的字段（如 label、description 等）应已替换为展示用最终文本，不再保留以 $ 开头的翻译键引用。
PI_RESOURCE单行 JSON 字符串：当前用户选中的那条 resource 数组元素对应的完整对象，同样完成 i18n 解析，格式为紧凑 JSON（无换行），便于通过环境变量传递。

约定说明：

  • 若某项信息当前不可用，Client 可不设置对应变量或置空；子进程应做容错，勿假定全部存在。
  • PI_CONTROLLER / PI_RESOURCE 仅描述当前选择；若运行期切换了控制器或资源包，Client 应在重启子进程或约定的时机更新环境（具体是否重启由 Client 实现决定，本协议不强制）。
  • 变量值需符合操作系统对环境变量长度与字符集的限制；JSON 宜采用紧凑序列化（minify）。

示例（值已转义示意，实际为单行）：

text
PI_INTERFACE_VERSION=v2.5.0
PI_CLIENT_NAME=MFAA
PI_CLIENT_VERSION=v1.0.0
PI_CLIENT_LANGUAGE=zh_cn
PI_CLIENT_MAAFW_VERSION=v5.9.0
PI_VERSION=v2.2.0
PI_CONTROLLER={"name":"Win32-Window","label":"Win32-默认","description":"默认控制器","type":"Win32","win32":{"class_regex":"UnityWndClass","window_regex":"Endfield","screencap":"Background","mouse":"SendMessageWithCursorPos","keyboard":"PostMessage"},"permission_required":true}
PI_RESOURCE={"name":"官服","label":"官服","path":["./resource"]}

  • group object[] 💡 v2.4.0
    可选。任务分组声明，为一个对象数组，用于声明任务分组及其展示属性。

    • name string
      分组唯一标识符，用作分组 ID。任务通过 task.group 引用该名称。

    • label string
      分组显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示 name 字段的值。可选。

    • description string
      分组详细描述信息，帮助用户理解该分组的用途。支持文件路径、URL或直接文本，内容支持 Markdown 格式。可选。

    • icon string
      分组图标文件路径，相对于项目根目录。用于在用户界面中显示。可选。支持国际化（以$开头）。

    • default_expand boolean
      可选，默认 true。该分组在 Client 中是否默认展开。

    jsonc
    "group": [
    {
        "name": "daily",
        "label": "$日常任务",
        "description": "$日常任务说明",
        "icon": "groups/daily.png",
        "default_expand": true
    },
    {
        "name": "battle",
        "label": "$战斗任务"
    }
]

  • task object[]
    任务配置，为一个对象数组，含有可执行任务的信息。

    • name string
      任务唯一标识符，用作任务ID。

    • label string
      任务显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示 name 字段的值。可选。

    • entry string
      任务入口，为 pipeline 中起点 Node 的名称。

    • default_check boolean
      是否默认选中该任务。可选，默认false。Client 在初始化时会根据该值决定是否默认勾选该任务。

    • description string
      任务详细描述信息，帮助用户理解任务功能。支持文件路径、URL或直接文本，内容支持 Markdown 格式。可选。

    • icon string
      任务图标文件路径，相对于项目根目录。用于在用户界面中显示。可选。支持国际化（以$开头）。

    • group string[] 💡 v2.4.0
      可选。指定该任务所属的分组列表。数组元素应与顶层 group 配置中的 name 字段对应。若不指定，则表示该任务不属于任何显式分组。

      同一个任务可以同时属于多个分组。Client 应将这些值仅视为分组归属关系；任务身份、勾选状态、预设引用以及配置项取值仍然以 task.name 作为唯一键。

      jsonc
      "task": [
    {
        "name": "领取奖励",
        "label": "$领取奖励",
        "entry": "CollectReward",
        "group": ["daily"]
    },
    {
        "name": "刷图",
        "label": "$刷图",
        "entry": "FarmStage",
        "group": ["daily", "battle"]
    }
]

    • resource string[]
      可选。指定该任务支持的资源包列表。数组元素应与 resource 配置中的 name 字段对应。若不指定，则表示该任务在所有资源包中都可用。
      当用户选择了某个资源包时，Client 可将不支持该资源包的任务隐藏，或以不可用（灰色/禁用）状态展示以提示用户。这允许为不同资源包提供专门的任务配置，比如活动任务只在特定资源包中可用。

      jsonc
      "task": [
    {
        "name": "活动任务",
        "label": "$活动任务",
        "entry": "ActivityTask",
        "resource": ["Official"],
        "description": "仅在官服资源包中可用的活动任务"
    },
    {
        "name": "通用任务",
        "label": "$通用任务",
        "entry": "CommonTask"
    }
]

    • controller string[]
      可选。指定该任务支持的控制器类型列表。数组元素应与 controller 配置中的 name 字段对应。若不指定，则表示该任务在所有控制器类型中都可用。
      当用户选择了某个控制器时，Client 可将不支持该控制器的任务隐藏，或以不可用（灰色/禁用）状态展示以提示用户。这允许为不同控制器类型提供专门的任务配置，比如某些任务只适用于 Adb 控制器，某些任务只适用于 Win32 控制器。

      jsonc
      "task": [
    {
        "name": "安卓专属任务",
        "label": "$安卓专属任务",
        "entry": "AndroidOnlyTask",
        "controller": ["Android"],
        "description": "仅在安卓控制器中可用的任务"
    },
    {
        "name": "PC专属任务",
        "label": "$PC专属任务",
        "entry": "Win32OnlyTask",
        "controller": ["Win32Emulator"],
        "description": "仅在Win32控制器中可用的任务"
    },
    {
        "name": "通用任务",
        "label": "$通用任务",
        "entry": "CommonTask"
    }
]

    • pipeline_override pipeline
      可选。任务参数，执行任务时会覆盖已加载的资源。该项结构与 pipeline 中的 json 文件完全一致，需要包含 任务名 部分，例如:

      jsonc
      "pipeline_override": {
    "Quit": {
        "enabled": true
    }
}

    • option string[]
      可选。任务配置项，为一个数组，含有若干后续 option 对象中的键的值，Client 会根据要求用户进行选择。
      Client 可以使用 option 中的顺序来展示配置项。

  • option record<string, object>
    配置项定义，为一个对象映射，含有配置项的信息。

    • key
      唯一名称标识符，任务会使用该名称进行引用。

    • type string
      配置项类型。可选，默认 "select"。可选值：

      • "select": 下拉选项框，用户从预定义的选项中选择一个
      • "checkbox": 多选框，用户从预定义的选项中选择多个 💡 v2.3.0
      • "input": 用户输入框，允许用户手动输入内容
      • "hotkey": 快捷键捕获框，允许用户通过按键捕获快捷键 💡 v2.8.0
      • "switch": 选择框，Yes or No

    • controller string[] 💡 v2.3.0
      可选。指定该配置项适用的控制器类型列表。数组元素应与 controller 配置中的 name 字段对应。若不指定，则表示该配置项在所有控制器类型中都可用。
      当用户选择了某个控制器时，Client 可将不适用于该控制器的配置项隐藏，或以不可用（灰色/禁用）状态展示以提示用户。
      当当前控制器不在该列表中时，该配置项视为未激活：其自身及其子配置项（option.option）产生的所有 pipeline_override 均不参与合并。 💡 v2.3.1

    • resource string[] 💡 v2.3.0
      可选。指定该配置项适用的资源包列表。数组元素应与 resource 配置中的 name 字段对应。若不指定，则表示该配置项在所有资源包中都可用。
      当用户选择了某个资源包时，Client 可将不适用于该资源包的配置项隐藏，或以不可用（灰色/禁用）状态展示以提示用户。
      当当前资源包不在该列表中时，该配置项视为未激活：其自身及其子配置项（option.option）产生的所有 pipeline_override 均不参与合并。 💡 v2.3.1

    • label string
      配置项显示标签，用于在用户界面中展示。支持国际化字符串（以$开头）。可选。

    • description string
      配置项详细描述信息，帮助用户理解配置项的作用。支持文件路径、URL或直接文本，内容支持Markdown格式。可选。支持国际化（以$开头）。

    • icon string
      配置项图标文件路径，相对于项目根目录。可选。支持国际化（以$开头）。

    • cases object[]
      仅在 type 为 "select"/"checkbox"/"switch" 时使用。可选项，为一个对象数组，含有各个可选项的信息。

      注意： 当 type 为 "checkbox" 时，用户可以同时选中多个 case，所有被选中的 case 的 pipeline_override 会按照 cases 数组中的定义顺序依次合并生效，与用户勾选的先后顺序无关。可通过 min_count / max_count 限制最少 / 最多选中数量。 💡 v2.10.1

      注意： 当 type 为 "switch" 时，仅支持两个 cases，且需遵循以下规则：

      • 如果 case.name 为 "Yes"、"yes"、"Y" 或 "y" 之一，该 case 会被识别为 Yes 选项
      • 如果 case.name 为 "No"、"no"、"N" 或 "n" 之一，该 case 会被识别为 No 选项
      • Client 会根据 case 的 name 来匹配用户的 Y/N 输入，其他输入会被要求重新输入

      建议使用 "Yes" 和 "No" 作为两个 case 的 name，以保证跨 Client 的一致性。

      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
        输入字段的默认值。可选。password 为 true 时禁止设置此字段；JSON Schema 会拒绝该组合。 💡 v2.10.0

      • pipeline_type string
        输入字段在 pipeline_override 中的数据类型。可选值："string", "int", "bool"。当使用 pipeline_override 中的变量替换时，会根据该类型进行类型转换。

      • verify string
        正则表达式，用于校验用户输入是否合法。可选。

      • pattern_msg string
        正则校验用户输入错误时，显示的信息。可选。支持国际化（以$开头）。

      • password bool 💡 v2.10.0
        可选，默认 false。为 true 时，将该输入字段视为密码 / 密钥。

        Client 必须遵守以下约束：

        • 界面： 使用密码输入框（掩码显示），不得在 UI 中回显原文。已保存的值在界面中同样应掩码展示。
        • 日志与遥测： 不得将原文写入日志、遥测、崩溃报告或任何可分享的输出。需要占位时使用掩码（如 ******），或直接省略该字段。
        • 配置存储： 写入用户配置文件时必须加密存储，不得以明文落盘。读取配置后仅在内存中解密，供 pipeline_override 替换、pretask 传参等运行时使用。
        • 加密实现： 算法与密文格式由 Client 自行决定，密文不必跨 Client / 跨设备可互解。建议优先使用操作系统提供的凭据保护（如 Windows DPAPI、macOS Keychain、Linux Secret Service）。
        • default / preset： 密码字段禁止设置 default（JSON Schema 会拒绝 password: true 与 default 同时出现）。资源作者不要把密码字段写入 preset。interface.json 通常会随资源分发，明文密钥不得出现在其中。

    • hotkeys object[]
      仅在 type 为 "hotkey" 时使用。快捷键配置，为一个对象数组，定义用户可捕获的快捷键字段。 💡 v2.8.0

      Client 应渲染快捷键捕获控件。用户按下目标键（或组合键）后，Client 将其保存为人类可读的快捷键字符串（如 "E"、"Ctrl+A"），不应直接保存虚拟按键码或 JSON 数组。组合键以 + 连接，末段为主键，前段依次为修饰键（如 Ctrl+Shift+A 中 A 为主键，Ctrl、Shift 为修饰键）。

      在生成 pipeline_override 时，Client 应依据当前所选控制器的 type（如 Win32、Adb、WlRoots），将快捷键字符串映射为该控制器支持的虚拟按键码。映射规则应与 ClickKey、KeyDown 等动作所用键码表一致。

      • name string
        快捷键字段唯一标识符，用作字段 ID。

      • label string
        快捷键字段显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示 name 字段的值。可选。

      • description string
        快捷键字段详细描述信息，帮助用户理解该快捷键的用途。支持文件路径、URL 或直接文本，内容支持 Markdown 格式。可选。支持国际化（以$开头）。

      • default string
        快捷键字段的默认值。可选。直接填写人类可读的快捷键字符串（如 "E"、"1"、"Ctrl+A"），无需填写虚拟按键码。Client 据此初始化控件展示；用户重新捕获后，保存的仍应为快捷键字符串。

    • pipeline_override pipeline
      当配置项为 "input" 或 "hotkey" 类型时使用，作为用户输入内容的替换模板。支持在字符串中使用 {名称} 格式引用输入字段或快捷键字段的值。可选。

      当配置项为 "hotkey" 类型时，Client 在替换占位符时应输出整数（虚拟按键码），而非字符串。支持的占位符形式：

      占位符含义
      {名称}等价于 {名称}.primary
      {名称}.primary组合键中的主键
      {名称}.modifier1第 1 个修饰键（如 Ctrl）
      {名称}.modifier2第 2 个修饰键（如 Alt、Shift）

      上述占位符的替换结果为单个整数（虚拟按键码），适用于 key 为 int 的按键动作，例如：

      jsonc
      "pipeline_override": {
    "__SomeActionKeyDown": {
        "key": "{UseTool.primary}"
    }
}

      NOTE

      Pipeline 协议中 ClickKey 的 key 字段还支持 list<int>（一次动作依次按下多个键，如 [17, 65] 表示 Ctrl+A）。hotkey 占位符仅替换为单个整数，不会自动展开为数组。一般单键改绑（如战斗技能 E、1、F1）使用 {名称}.primary 即可；若确需组合键的一次性 ClickKey 数组形式，Integrator 需在 pipeline 中另行设计（例如直接写键码数组，或拆成多个 KeyDown/KeyUp 节点）。

    • default_case string | string[]
      默认选项名称。可选。

      • 当 type 为 "select" / "switch" 时，填写单个字符串，Client 使用该值作为选项的初始选中值。
      • 当 type 为 "checkbox" 时，填写字符串数组，Client 使用该值作为多选框的初始选中值。 💡 v2.3.0
        default_case 的元素数量应满足 min_count / max_count（若已设置）。 💡 v2.10.1

    • min_count number 💡 v2.10.1
      仅在 type 为 "checkbox" 时使用。可选，默认 0。用户至少需要选中的 case 数量，为非负整数。
      为 0 时允许不选。该值不应大于 cases 的长度；若同时设置了 max_count，则不应大于 max_count。
      Client 应在用户选择时校验：选中数量少于 min_count 时提示用户补选，不应带着不满足下限的选择启动任务。

    • max_count number 💡 v2.10.1
      仅在 type 为 "checkbox" 时使用。可选。用户最多可以选中的 case 数量，为非负整数。不设置表示不限制（最多可选中全部 case）。
      该值不应大于 cases 的长度；若同时设置了 min_count，则不应小于 min_count。
      Client 应在用户选择时阻止超过 max_count 的勾选。

  • global_option string[] 💡 v2.3.0
    可选。全局选项配置，为一个字符串数组，数组元素应与 option 配置中的键名对应。
    该选项生成的参数会参与到所有任务的 pipeline override 中，无论用户选择了什么资源包或控制器。
    与 resource.option 和 controller.option 不同，全局选项不依赖于任何资源包或控制器的选择。
    但 global_option 引用的 option 仍需满足该 option 自身的 resource / controller 限制；不满足时不应用任何 pipeline_override。 💡 v2.3.1

    jsonc
    "global_option": [
    "战斗划火柴",
    "战斗自动闪避"
]

  • setting object[] 💡 v2.8.0
    可选。任务设置页 UI 声明，供 MXU 等 Client 渲染全局任务配置专用设置区域。 每个元素描述一个设置分区；Client 可按数组顺序渲染各分区。

    • name string
      分区唯一标识符，用作分区锚点与内部键。

    • label string
      在用户界面中展示的分区名称。支持国际化字符串（以$开头）。如果未设置，则显示 name 字段的值。可选。

    • description string
      分区描述文本。支持文件路径、URL 或直接文本，内容支持 Markdown 格式。可选。支持国际化（以$开头）。

    • icon string
      分区图标文件路径，相对于项目根目录。可选。支持国际化（以$开头）。

    • option string[]
      可选。来自顶层 option 配置的有序 option 键名列表。Client 应按给定顺序渲染这些 option，并复用既有 option 协议定义作为实际控件。

    • default_expand boolean
      可选，默认为 true。该分区在 Client 中是否默认展开。

    jsonc
    "setting": [
    {
        "name": "task_global",
        "label": "$任务全局设置",
        "description": "$任务全局设置说明",
        "icon": "setting/task_global.png",
        "option": ["战斗划火柴", "战斗自动闪避"],
        "default_expand": true
    }
]

  • import string[] 💡 v2.2.0
    可选。导入其他 PI 文件的路径数组。文件相对路径为 interface.json 同目录下的相对路径。
    支持导入这些文件中的 task、option、preset 💡 v2.3.0、group 💡 v2.4.0、pretask 💡 v2.7.0、global_option 与 setting 💡 v2.8.0 字段。
    Client 会依次加载这些文件，并将它们的内容与当前文件进行合并，从而实现配置的拆分和复用。

    合并规则：

    字段合并方式
    task追加到主文件 task 数组末尾
    option对象合并；同名键以后导入文件为准
    global_option追加到主文件数组末尾；按 option 键名去重，保留先出现的项 💡 v2.8.0
    setting追加到主文件 setting 数组末尾 💡 v2.8.0
    preset追加到主文件 preset 数组末尾
    group追加到主文件 group 数组末尾；按 name 去重，保留先出现的项

  • preset object[] 💡 v2.3.0
    可选。预设配置，为一个对象数组。每个预设是一套预定义的任务勾选状态与选项值的快照，用户可一键应用，快速切换不同使用场景。

    • name string
      唯一标识符，用作预设 ID。

    • label string
      显示名称，用于在用户界面中展示。支持国际化字符串（以$开头）。如果未设置，则显示 name 字段的值。可选。

    • description string
      预设详细描述信息，帮助用户理解该预设的适用场景。支持文件路径、URL 或直接文本，内容支持 Markdown 格式。可选。支持国际化（以$开头）。

    • icon string
      预设图标文件路径，相对于项目根目录。可选。支持国际化（以$开头）。

    • task object[]
      预设包含的任务配置列表。

      • name string
        必须。与顶层 task[].name 对应的任务名称。

      • enabled boolean
        可选，默认 true。该任务在预设中是否勾选。

      • option record<string, OptionValue>
        可选。该任务各配置项的预设值，键为顶层 option 中的键名。OptionValue 的类型取决于对应 option 的 type：

        option.typeOptionValue 类型示例
        select / switchstring（case.name）"x3" / "Yes"
        checkboxstring[]（case.name 数组）["自动战斗", "自动拾取"]
        inputrecord<string, string>（输入字段 name → 值）{ "章节号": "4" }
        hotkeyrecord<string, string>（快捷键字段 name → 快捷键字符串）{ "FightCombo": "E" }

        password 为 true 的输入字段不要写入 preset。 💡 v2.10.0

    预设示例：

    jsonc
    "preset": [
    {
        "name": "刷日常",
        "label": "$刷日常",
        "description": "每日例行套餐：荒原 + 心相 + 3-9 + 领奖",
        "icon": "preset_daily.png",
        "task": [
            { "name": "收取荒原", "enabled": true },
            { "name": "每日心相（意志解析）", "enabled": true },
            {
                "name": "常规作战",
                "enabled": true,
                "option": {
                    "作战关卡": "3-9 厄险（百灵百验鸟）",   // select 类型：填 case.name
                    "复现次数": "x3",                       // select 类型：填 case.name
                    "刷完全部体力": "No",                   // switch 类型：填 case.name
                    "启用功能": ["自动战斗", "自动拾取"]    // checkbox 类型：填 case.name 数组
                }
            },
            { "name": "领取奖励", "enabled": true },
            { "name": "活动：绿湖噩梦 17 艰难（活动已结束）", "enabled": false }
        ]
    },
    {
        "name": "实时辅助",
        "label": "$实时辅助",
        "description": "后台挂机辅助，仅执行自动辅助类任务",
        "task": [
            {
                "name": "常规作战",
                "enabled": true,
                "option": {
                    "启用功能": ["自动战斗", "自动拾取", "自动回血"]
                }
            }
        ]
    }
]

    通过 import 分文件管理预设：

    预设配置可以通过 import 拆分到独立文件中，方便管理和复用。例如：

    jsonc
    // interface.json
{
    "import": [
        "preset_daily.json",
        "preset_realtime.json"
    ],
    "preset": [
        // 也可以在主文件中直接定义预设，会与导入的预设合并
    ]
}
    jsonc
    // preset_daily.json
{
    "preset": [
        {
            "name": "刷日常",
            "label": "$刷日常",
            "description": "每日例行套餐",
            "task": [
                { "name": "收取荒原", "enabled": true },
                { "name": "领取奖励", "enabled": true }
            ]
        }
    ]
}

Option 覆盖顺序 💡 v2.3.0 ​

各级 option 生成的 pipeline_override 会按照以下顺序依次合并，后合并的会覆盖先合并的同名字段：

  1. global_option — 全局选项，最先生效，优先级最低
  2. resource.option — 资源包级选项
  3. controller.option — 控制器级选项
  4. task.option — 任务级选项，最后生效，优先级最高

即：task.option > controller.option > resource.option > global_option。

在进入上述合并顺序前，需先过滤“未激活”的 option。任何不满足当前 controller / resource 条件的 option（包括来自 global_option、resource.option、controller.option、task.option 以及嵌套 option.option）都不得产生 pipeline_override。 💡 v2.3.1

pretask.option 不参与上述覆盖顺序；它只会将 option 的当前取值序列化为预任务进程的最后一个参数。 💡 v2.7.0

这样设计的理由是：越具体的配置（任务级）应当具有越高的优先级，越通用的配置（全局级）则作为兜底默认值。

示例：

假设 global_option 和某个 task.option 同时引用了同一个 option，且该 option 的某个 case 对同一个 pipeline 节点做了不同的 override，那么任务级的 override 将最终生效。

配置项示例 ​

select 类型选项示例 ​

jsonc
{
  "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 类型选项示例 ​

jsonc
{
  "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": "{超时时间}"
        }
      }
    }
  }
}

password 输入字段示例 💡 v2.10.0 ​

同一 input 选项中可以混合普通字段与密码字段。密码字段不要填写 default。

jsonc
{
  "option": {
    "账号登录": {
      "type": "input",
      "label": "$账号登录",
      "inputs": [
        {
          "name": "username",
          "label": "$用户名",
          "pipeline_type": "string"
        },
        {
          "name": "password",
          "label": "$密码",
          "pipeline_type": "string",
          "password": true
        }
      ],
      "pipeline_override": {
        "Login": {
          "custom_action_param": {
            "username": "{username}",
            "password": "{password}"
          }
        }
      }
    }
  }
}

checkbox 类型选项示例 💡 v2.3.0 ​

jsonc
{
  "option": {
    "战斗划火柴": {
      "type": "checkbox",
      "label": "$战斗划火柴",
      "description": "选择要启用的划火柴功能，可多选",
      "min_count": 1,
      "max_count": 2,
      "default_case": ["普通划火柴", "蓄力划火柴"],
      "cases": [
        {
          "name": "普通划火柴",
          "label": "$普通划火柴",
          "description": "启用普通划火柴",
          "pipeline_override": {
            "NormalMatch": {
              "enabled": true
            }
          }
        },
        {
          "name": "蓄力划火柴",
          "label": "$蓄力划火柴",
          "description": "启用蓄力划火柴",
          "pipeline_override": {
            "ChargedMatch": {
              "enabled": true
            }
          }
        },
        {
          "name": "连续划火柴",
          "label": "$连续划火柴",
          "description": "启用连续划火柴",
          "pipeline_override": {
            "ComboMatch": {
              "enabled": true
            }
          }
        }
      ]
    }
  }
}

注意： checkbox 类型中，多个被选中 case 的 pipeline_override 按照 cases 数组中的定义顺序依次合并，与用户勾选的先后顺序无关。

国际化支持 ​

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

例如：

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

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

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

资源覆盖 ​

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

旧任务

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

新任务

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

合并后的任务

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

节点通知处理 ​

MaaFramework 在任务执行过程中会通过回调函数发送节点通知，Client 需要实现相应的处理逻辑，以便向用户展示任务执行状态。

回调函数签名 ​

Client 需要注册一个回调函数来接收通知，函数签名参考 MaaDef.h：

c
typedef void(MAA_CALL* MaaEventCallback)(
    void* handle,
    const char* message,
    const char* details_json,
    void* trans_arg
);
  • message: 消息类型标识（如 Node.Action.Starting、Node.Recognition.Succeeded 等）
  • details_json: 包含具体数据的 JSON 字符串

消息模板机制 ​

资源作者可以在 Pipeline 中通过 focus 字段配置消息模板。focus 是一个字典，键为消息类型，值为模板字符串或模板对象。模板字符串支持文件路径、URL 或直接文本，内容支持 Markdown 格式，支持国际化（以$开头）。Client 收到回调后，应根据模板进行占位符替换并按指定方式展示给用户；对象写法还可配置是否将本次节点结果上传到遥测平台。

focus 值的两种写法 ​

简写（纯字符串）： 等价于 display: "log"，内容仅展示在运行日志中；trace 使用默认值。

jsonc
"focus": {
    "Node.Action.Starting": "{name} 开始执行"
}

完整写法（对象）： 可通过 display 指定展示渠道，通过 trace 控制是否上传遥测。 💡 v2.3.0（trace 为 💡 v2.9.1）

jsonc
"focus": {
    "Node.Action.Starting": {
        "content": "{name} 开始执行",
        "display": "toast",
        "trace": false
    }
}
display 可选值 💡 v2.3.0 ​
值说明行为特征
"log"运行日志（默认）追加到日志流，不打断操作
"toast"应用内轻提示短暂浮现后自动消失，不阻塞
"notification"系统级通知推送到 OS 通知中心，应用在后台时也可收到
"dialog"非阻塞式对话框弹出信息框，任务流水线在后台继续执行
"modal"阻塞式弹窗弹出后任务暂停等待用户确认，适合需要人工干预的场景

display 支持数组，同一条消息可同时推送到多个渠道：

jsonc
"focus": {
    "Node.Action.Succeeded": {
        "content": "✅ {name} 执行成功",
        "display": ["log", "toast"]
    },
    "Node.Action.Failed": {
        "content": "❌ 执行失败，请检查环境",
        "display": ["log", "modal"]
    }
}
trace 默认值 💡 v2.9.1 ​

在已配置 telemetry.sentry 且 tracing 启用（或未显式关闭）的前提下：

消息类型默认值说明
Node.PipelineNode.Failedtrue与常见 Client 对流水线节点失败的默认上报行为对齐
其他 Node.xxx 消息false需在对应消息的模板对象中显式写 "trace": true 才会上传

Pipeline 中的完整配置示例：

jsonc
{
  "NodeA": {
    "focus": {
      "Node.Recognition.Succeeded": "{name} 识别命中，准备开始执行",
      "Node.Action.Starting": {
        "content": "{name} 开始执行，任务 ID: {task_id}",
        "display": ["log", "toast"]
      },
      "Node.Action.Failed": {
        "content": "{name} 执行失败",
        "display": "modal",
        "trace": true
      },
      "Node.PipelineNode.Succeeded": {
        "trace": true
      }
    }
  }
}

回调函数收到的参数示例：

c
// message 参数:
"Node.Action.Starting"

// details_json 参数（解析后）:
{
    "task_id": 12345,
    "action_id": 11111,
    "name": "NodeA",
    "focus": {
        "Node.Recognition.Succeeded": "{name} 识别命中，准备开始执行",
        "Node.Action.Starting": {
            "content": "{name} 开始执行，任务 ID: {task_id}",
            "display": ["log", "toast"]
        },
        "Node.Action.Failed": {
            "content": "{name} 执行失败",
            "display": "modal",
            "trace": true
        },
        "Node.PipelineNode.Succeeded": {
            "trace": true
        }
    }
}

Client 处理流程 ​

  1. 在回调函数中解析 details_json 参数
  2. 检查解析后的对象中是否存在 focus 字段
  3. 若存在，根据 message 参数在 focus 中查找对应的模板（字符串或对象）
  4. 若模板为字符串，则 content 即为该字符串，display 视为 ["log"]，trace 使用默认值；若为对象，则分别读取 content、display、trace
  5. 若存在 content，使用 details_json 中的数据替换占位符（如 {name}、{task_id}），再根据 display 指定的渠道展示给用户 💡 v2.3.0
  6. 解析有效 trace：对象中显式给出则用之，否则使用默认值；在全局遥测已启用时，仅当有效值为 true 才上传本次节点结果 💡 v2.9.1

以上述示例为例，收到 Node.Action.Starting 时，应在日志中追加并弹出 toast：NodeA 开始执行，任务 ID: 12345

更多消息类型 ​

完整的回调消息列表和详细说明请参考 回调协议 和 MaaMsg.h。