Skip to content
BranchesTags

Repository files navigation

MXU

MXU 是一个基于 MaaFramework PI V2 协议的通用 GUI 客户端，使用 Tauri + React + TypeScript 构建。

它可以解析任何符合 PI V2 标准的 interface.json 文件，为 MaaFramework 生态中的自动化项目提供开箱即用的图形界面。

✨ 特性

Tip

MXU 已支持最新最潮的 PI v2.5.0 协议！

  • 📋 任务管理 - 可视化配置任务列表，支持拖拽排序
  • 🔧 多实例支持 - 同时管理多个独立运行的实例（标签页多开）
  • 🎮 多控制器类型 - 支持 Adb、Win32、MacOS、Linux、PlayCover、Gamepad
  • 🌍 国际化 - 界面内置多种语言，自动加载 interface.json 中的翻译
  • 🎨 明暗主题 - 支持 Light/Dark 主题切换
  • 📱 实时截图 - 显示设备实时画面，可自定义帧率
  • 📝 运行日志 - 查看任务执行日志和 Agent 输出
  • ⏰ 定时任务 - 支持配置定时执行策略
  • 🔄 自动更新 - 支持 MirrorChyan 和 GitHub 自动下载更新
  • 🤖 Agent 支持 - 支持 MaaAgentClient 实现自定义识别器和动作

🚀 快速开始

依赖文件

MXU Releases 中提供了单可执行文件（Windows 为 mxu.exe，Linux/macOS 为 mxu），您需要配置以下依赖：

目录结构如下

your-project/
├── mxu.exe (或 mxu)
├── maafw/
│   ├── MaaFramework.dll (Windows)
│   ├── MaaToolkit.dll
│   └── ... 其他依赖库
├── interface.json
└── resource/

随后运行 mxu.exe（Windows）或 ./mxu（Linux/macOS）即可！~

命令行参数

MXU 支持以下启动参数：

参数 功能 说明
-h / --help 显示帮助信息 输出 MXU 当前支持的命令行参数说明并退出，不启动图形界面。
--autostart 标记为“开机自启动”启动 进入开机自启动模式，并触发自动执行逻辑。该参数主要由 MXU 创建的系统自启动任务自动传入，通常无需手动设置。
-i <实例名> / --instance <实例名> 指定要自动启动的实例 仅在 --autostart 模式下生效。若指定的实例名存在，则优先使用该实例，而不是设置中配置的默认自动执行实例。也支持 -i=<实例名>、--instance=<实例名> 写法。
-q / --quit-after-run 自动执行完成后退出程序 当本次启动实际触发了自动执行后，等待任务结束并自动关闭 MXU，适合配合自启动场景做“一次性后台执行”。

示例：

# 查看命令行帮助
mxu.exe --help

# 使用系统自启动模式，并指定自动执行的实例名
mxu.exe --autostart --instance "日常任务"

# 自动执行完成后自动退出
mxu.exe --autostart -i "日常任务" --quit-after-run

用户文件

用户配置保存在 config 文件夹中，调试日志保存在 debug 文件夹中。亦可在 设置 - 调试 中直接打开文件夹。

🧩 MXU 扩展

MXU 在 PI V2 协议 之外提供了一组可选扩展字段，用于补齐协议未覆盖的界面细节。

它们都不是协议的组成部分，不写也能正常工作；写了之后其它客户端未必识别，具体行为以本仓库实现为准（代码里的 MXU 扩展 注释即这些字段的登记处）。

行内 Markdown label

option / case / input 的 label 支持行内 Markdown，最常见的用法是给选项名称配一个小图标：

{
  "option": {
    "Stage": {
      "type": "select",
      "label": "关卡选择",
      "cases": [
        { "name": "Stage1", "label": "![](resource/image/icon/stage1.png) 第一关 ★1" },
        { "name": "Stage2", "label": "![](resource/image/icon/stage2.png) 第二关 ★2" }
      ]
    }
  }
}

支持的行内语法（判定规则见 src/utils/richText.ts）：

语法 效果
![](路径) / ![说明](路径) 行内 16px 图标，相对路径基于 interface.json 所在目录
[文字](https://…) 链接
`代码` 行内代码样式
**加粗** 加粗
<b> <br> <img> 等 常见的行内 HTML 标签（渲染前经 DOMPurify 清理）

注意事项：

  • label 默认按纯文本渲染，只有出现上表中的标记时才走 Markdown 解析，因此纯文本 label 没有任何额外开销。
  • 只支持行内语法。多行段落、列表、标题、表格等块级内容请写在 description 里（description 支持 Markdown、文件路径与 URL）。
  • 悬停提示（tooltip）始终显示去掉标记的纯文本，不会出现 ![](...) 这类源码。
  • 图标读取失败时会被忽略，不会显示破图；建议控制在 16px 左右，与 option / case 的 icon 字段视觉一致。
  • 该能力只作用于 option、case、input 的 label；task、resource、controller、任务分组的 label 仍为纯文本。

输入项扩展字段

input 类型的 inputs[] 在协议字段之外支持以下扩展：

字段 类型 说明
input_type "text" | "file" | "time" 渲染对应控件：file 文件选择器、time 时间选择器，缺省为普通文本框
placeholder string 输入框占位提示，支持 $ 国际化
password boolean 密码字段：界面掩码显示、配置加密存储，日志与遥测中同样脱敏 
{
  "input": {
    "type": "input",
    "label": "启动参数",
    "inputs": [
      { "name": "ConfigPath", "label": "配置文件", "input_type": "file" },
      { "name": "Token", "label": "访问令牌", "password": true },
      {
        "name": "StartAt",
        "label": "启动时间",
        "input_type": "time",
        "placeholder": "$task.startAtHint"
      }
    ]
  }
}

任务设置页（setting）

interface.json 顶层可声明 setting，把这些 option 收纳到「设置 - 任务设置」中，并自定义分组外观：

{
  "setting": [
    {
      "name": "advanced",
      "label": "$settings.advanced",
      "description": "日常任务用到的高级参数",
      "icon": "resource/image/icon/advanced.png",
      "default_expand": false,
      "option": ["MaxRetry", "Timeout"]
    }
  ]
}
字段 类型 说明
name string 分组唯一标识，同时作为设置页锚点 ID
label string 分组显示名称，支持 $ 国际化；缺省回退到 name
description string 分组说明，支持 $ 国际化
icon string 分组图标，相对路径基于 interface.json 所在目录
default_expand boolean 默认是否展开，缺省展开
option string[] 该分组包含的顶层 option 键名；不存在的键会被忽略

setting 只描述“怎么展示”，option 本身仍定义在顶层 option 里。使用 import 导入其它 PI 文件时，导入文件的 setting 会按导入顺序追加合并。

Tip

MXU 还内置了若干与 pipeline 无关的「特殊任务」（延迟、等待到指定时间点、启动外部程序），它们由 MXU 自身实现，无需资源提供 pipeline；新增方式见 docs/add-special-task.md。

📖 开发调试

🧭 开发说明

MXU 在很大程度上属于 vibe coding：开发与产品决策主要由维护者的直觉、审美与真实使用场景驱动，在主观判断下保持体验一致，而不是先锁定一份长期冻结的技术蓝图或与外部共识逐条对齐。由此，仓库整体是产品导向而非技术导向——优先级放在用户体验与运行稳定性上；实现方式、工程「潮流」或技术细节并非讨论焦点。

关于贡献与合并预期，请事先了解：

  • 缺陷修复：欢迎直接提交 Pull Request；聚焦问题、范围清晰的修复通常更易审阅与合入。
  • 新功能、重构或行为/交互层面的较大改动：维护者会按产品方向与一致性独立判断，不保证接受。若未经事先沟通就投入大量开发，存在合入被拒的可能。
  • 小众与极客向功能：仅服务于极少数场景、或需要大量背景知识才能理解的价值主张，大概率不会通过。维护者优先面向大多数用户保持界面清晰；每多一个入口、开关或选项，都会抬高学习与决策成本，因此会刻意控制功能暴露面。
  • 建议流程：若计划增加能力或调整架构/交互，请先提交 Issue 说明动机、用户场景与拟定方案，与维护者对齐设计后再实现，以减少无效劳动与预期落差。

说白了就是：怎么写、合什么，主要看维护者顺不顺眼、普通用户会不会多背一层菜单；不是堆技术秀肌肉，也没法照单全收所有点子。想上大改动先开个 Issue 对一下，比闷头做完被拒省心。

感谢配合与理解。

安装依赖

Node.js (>= 18)

# macOS (Homebrew)
brew install node

# Windows (winget)
winget install OpenJS.NodeJS

pnpm (>= 8)

npm install -g pnpm

Rust (>= 1.70)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

项目依赖

pnpm install

开发调试

pnpm tauri dev

启动前端开发服务器和 Tauri 桌面应用，支持热重载。

生产构建

pnpm tauri build

构建产物位于 src-tauri/target/release/ 目录。

🤝 相关项目

  • MaaFramework - 基于图像识别的自动化黑盒测试框架

📄 License

GNU Affero General Public License v3.0

❤️ 鸣谢

感谢以下开发者对 MXU 作出的贡献：

贡献者

☕ 赞助

About

MaaFramework Next UI

Resources

Readme
AGPL-3.0 license
Activity

Stars

101 stars

Watchers

0 watching

Forks

85 forks
Report repository

Releases

Contributors

Languages