MAI

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 的状态。

快速开始

1. 环境准备

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

2. 安装依赖

pip install -r requirements.txt

3. 配置资源

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

python ./tools/configure.py

4. 启动服务

运行以下命令启动 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