项目简介

MFAAvalonia 是基于 Avalonia UI 和 SukiUI 构建的 MaaFramework 通用 GUI。资源开发者通过 Project Interface V2 描述任务、选项、控制器和界面文本，用户即可在桌面端配置并运行自动化任务。

MFAAvalonia 本身不包含具体业务资源。通常应将它集成到基于 MaaFramework 的资源项目中使用。

主要功能

任务与资源

• 支持 Project Interface V2 的任务、选项、预设、国际化、import 与 pretask 等能力。
• 支持输入框、选择器、开关等任务选项，以及可折叠的 Markdown 预设说明。
• 每条任务显示运行中、成功、失败、已取消或未执行状态，并在执行期间及完成后显示耗时。
• 支持资源公告与 Markdown 内容展示。

实例与自动化

• 使用标签页管理多个独立实例，可搜索、重命名、复制实例 ID，并导入或导出实例配置。
• 支持定时执行、应用启动时批量执行、全局热键和命令行自动启动。
• 同一路径下已运行的 MFAAvalonia 可接收新的命令行请求，无需重复启动一个进程。

控制器与平台

• 提供 Windows x64/arm64、Linux x64/arm64 和 macOS x64/arm64 发布目标。
• 支持 MaaFramework 的 ADB、Win32 和 PlayCover 控制器；实际可用控制器取决于系统、资源配置和打包内容。
• 支持亮色、暗色主题以及可由资源定义的多语言文本。

更新、通知与诊断

• 可通过 GitHub 或 Mirror酱检查并安装程序和资源更新。
• 支持将符合条件的本地资源压缩包拖入窗口，经确认后更新；任务运行期间不会执行拖放更新。
• 支持钉钉、飞书、Telegram、Discord、SMTP、WxPusher、QMsg、OneBot、Server酱和自定义 Webhook 等外部通知方式。
• 支持可配置的任务面板布局，详见自定义布局。
• 资源可在 PI 中配置 Sentry 遥测；只有资源提供遥测配置且用户未关闭“帮助改进软件”时才会发送诊断信息。

界面预览

运行要求

不同资源可能有额外的模拟器、ADB、应用程序或系统权限要求，请以对应资源项目的说明为准。

快速开始

使用项目模板（推荐）

MaaPracticeBoilerplate 已提供 MFAAvalonia 集成流程。开发资源项目前，请先阅读项目模板的开发说明和 Project Interface V2 协议。

MFAAvalonia 面向资源发布后的配置与运行。开发和排查 Pipeline 时，请使用 MaaFramework 提供的调试工具。

手动集成

1. 从 Releases 下载与目标系统及架构匹配的版本并解压。
2. 按 Project Interface V2 的目录约定放置 interface.json、资源文件和所需组件。
3. 安装 .NET 10 Runtime，然后启动对应平台的 MFAAvalonia 可执行文件。

手动打包时，MaaFramework 原生库、资源目录和 interface.json 必须彼此匹配。一般情况下应优先使用项目模板生成发布产物。

如需提供首次启动的预设配置，可在发布包的 config 目录放置 config.template.json。仅当目录中不存在其它配置 JSON（包括 config/instances 下的实例配置）时，该文件才会转换为 config.json；更新已有安装时不会覆盖或新增用户配置。

模板还可使用 PresetSettings 字典为不同 preset 指定独立配置：

{
  "UI.LiveView.EnableLiveView": false,
  "PresetSettings": {
    "preset_a": {
      "UI.LiveView.EnableLiveView": true
    },
    "preset_b": {
      "UI.LiveView.EnableLiveView": false
    }
  }
}

PresetSettings 仅用于首次初始化 preset，转换完成后不会作为普通配置项写入 config.json。

启动参数

MFAAvalonia 支持通过命令行选择实例并执行任务。实例可以使用名称或实例 ID 指定；实例 ID 可在实例标签页的右键菜单中复制。

MFAAvalonia.exe [参数]

常用示例

# 查看帮助
.\MFAAvalonia.exe --help

# 切换到指定实例
.\MFAAvalonia.exe --instance "日常任务"
.\MFAAvalonia.exe -i 1a2b3c4d

# 自动执行指定实例
.\MFAAvalonia.exe --autostart -i "日常任务"

# 执行完成后退出
.\MFAAvalonia.exe --autostart -i 1a2b3c4d -q

# 若实例正在运行，则停止后重新执行
.\MFAAvalonia.exe --autostart -i "日常任务" --forceStart
.\MFAAvalonia.exe --autostart -c 1a2b3c4d -f

参数组合规则

• 仅指定实例参数时，只切换到对应实例，不自动执行任务。
• --autostart 指向正在运行的实例时，默认跳过本次启动，不重复添加任务。
• 同时使用 --autostart、实例参数和 -f 时，会等待现有任务停止后重新启动。
• -q 只跟踪本次命令启动的任务；与 -f 配合时，停止旧任务不会被视为本次执行完成。

资源开发文档

• Project Interface V2 协议
• MaaPracticeBoilerplate
• Android 资源项目接入
• 自定义布局
• 外部通知配置

旧版 Advanced 配置已废弃。现有资源应迁移到 Project Interface V2，不应继续依赖旧字段。

MFAAvalonia 扩展字段

MFAAvalonia 在 Project Interface V2 的 task 项中额外支持以下字段：

{
  "task": [
    {
      "name": "重复任务",
      "entry": "TaskEntry",
      "repeatable": true,
      "repeat_count": 1
    }
  ]
}

用户在界面中修改的重复次数会随实例配置保存。

公告系统

将 .md 文件放入 resource/announcement/ 目录即可作为资源公告显示。程序或资源更新的 Release Notes 会单独下载，并显示在更新提示中。

自定义图标

将 logo.ico 放置在程序根目录的 Assets 文件夹中，即可替换 MFAAvalonia 的窗口和托盘图标。

从源码构建

安装 .NET 10 SDK 后执行：

dotnet restore
dotnet build MFAAvalonia.sln -c Debug
dotnet publish MFAAvalonia.Desktop/MFAAvalonia.Desktop.csproj -c Release -r win-x64

将 win-x64 替换为项目支持的其他 RID，即可构建对应平台。运行仍需要有效的资源目录和 interface.json。

开源许可

本项目基于 GPL-3.0 License 开源。

致谢

MFAAvalonia 使用了 MaaFramework、MaaFramework.Binding.CSharp、Avalonia、SukiUI、Serilog、Newtonsoft.Json、Mirror酱 等开源项目与服务。

感谢所有为 MFAAvalonia 做出贡献的开发者。