MAI 是一个基于 MaaFramework 和多模态大模型(Multimodal LLM)构建的 GUI 智能体系统。它通过视觉理解屏幕内容,自动规划并执行任务,旨在实现游戏和应用的自动化操作。

MAI目前很不完善,属于抛砖引玉之作。如果您有好的想法或改进的意见,非常欢迎提出issues与pr

• 三模式架构:
  • Planner (规划者):分析当前屏幕状态,将复杂任务拆解为具体的子任务,并决定下一步行动。
  • Executor (执行者):专注于执行具体的子任务操作(如点击、滑动、输入),并处理执行过程中的简单异常。
  • Verifier (验证者):在子任务完成后进行验收,确保目标真正达成,防止误判。
• 视觉理解:利用多模态大模型(如 Qwen3-vl)识别 UI 元素、理解界面状态和判断操作结果。
• 稳健的执行流:
  • 状态-动作-反馈循环
    • Context: 包含当前轮次、子任务信息以及上一轮动作的执行结果(成功/失败/无变化)。
    • Action: 模型具体操作。
    • Feedback: 系统执行操作后,将结果反馈给下一轮 Context。
  • 循环检测:内置 AAA (页面卡死) 和 ABA (页面反复) 循环检测机制,自动中断死循环。
• Web 控制台:提供直观的 Web 界面,实时显示运行日志、屏幕截图、思维链(Chain of Thought)以及当前 Agent 的状态。

• Python 3.10+
• ADB (Android Debug Bridge) - 请确保 adb 在系统环境变量中,或连接了模拟器/真机。
• MaaFramework - 本项目依赖 MaaFramework 进行底层设备控制和资源管理。

pip install -r requirements.txt

本项目基于 MaaFramework 模板创建,需要下载必要的资源文件:

python ./tools/configure.py

运行以下命令启动 MAI 服务器:

python run_server.py

服务启动后,请在浏览器中访问:http://localhost:8001

1. 连接设备:确保你的 Android 设备或模拟器已通过 ADB 连接。
2. 打开 Web 界面:访问 http://localhost:8001。
3. 输入任务:在输入框中输入你想要执行的任务(例如:"完成每日签到")。
4. 开始执行:点击按钮,Agent 将开始分析屏幕并执行操作。

• mai_server/: 核心代码目录
  • agent_controller.py: 智能体控制中枢,负责协调各组件和管理模式切换。
  • prompt_builder.py: 提示词构建器,负责组装 System Prompt 和 User Input,管理上下文历史。
  • protocol.py: 定义了系统内部的数据协议和结构。
  • working_memory.py: 工作记忆模块,存储当前任务、子任务状态和操作历史。
  • loop_detector.py: 循环检测器,识别并阻止重复操作。
  • result_analyzer.py: 结果分析器,使用 pHash 等技术判断屏幕变化。
  • llm_client.py: 模型接口封装。
  • prompts/: 存放各模式(Planner, Executor, Verifier)的 System Prompt 模板。
  • templates/: Web 前端界面模板。
• run_server.py: 项目启动脚本。
• requirements.txt: Python 依赖列表。

更详细的系统架构设计和接口定义,请参考:

• MAI架构设计文档
• MAI接口与数据规范
• MAAFW对接文档

Powered by MaaFramework