MaaYuan Docs

切换主题

快速开始关于MaaYuan功能介绍任务介绍常见问题开发手册

零基础开发指南 ​

NOTE

只有当您想要开发MaaYuan时才需要看当前页面！ 用户请转到 说明文档 开发 MaaFramework 或开发自己的项目请到 MaaXYZ/MaaFramework

本篇文档参考：MaaFW、MAA、M9A开发指南编写！

MaaFramework官网

开发指南 | MAA 文档站

开发前须知 | M9A 文档站

Github Pull Request 代码提交流程简述 ​

  • 我不懂编程，只是想改一点点 JSON 文件/文档等，要怎么操作？ ​

欢迎收看 牛牛也能看懂的 GitHub Pull Request 使用指南

简单来说，就是整个文件夹用VScode打开，找到想编辑的代码在VScode里编辑好，然后把改好的代码粘贴到github网站上进行PR。

  • 我有编程经验，想在本地进行较为完整的项目开发，应该怎么操作？ ​

TIP

  • fork一份MaaYuan主仓库的代码，并把代码下载到本地；
  • 在本地写 pipeline、interface、custom文件，利用VSCode插件/小工具/MPE等进行截图、取ROI等操作，并利用VSCode插件/MaaDebugger/MPE等调试工具进行调试；
  • 利用git，实现本地（电脑硬盘里你的文件夹）-- 个人远程仓库（你fork的MaaYuan仓库）的交互；
  • 再利用PR，实现个人远程仓库（你fork的MaaYuan仓库）-- 上游原始仓库（MaaYuan项目仓库）的交互。

1、前置准备 ​

  1. 下载、安装VSCode并安装对应插件

    官网：https://code.visualstudio.com

    推荐下载好后，在扩展里找到 Maa Pipeline Support，进行下载安装。可以进行调试，截图、取ROI等操作，不对的会进行报错提醒。

    TIP

    • 可以下个代码补全的插件，一键补全，好用！
    • 代码格式化插件推荐： Prettier，作者Prettier蓝标

  2. 下载并安装git（官网：https://git-scm.com/ ）

  3. 下载并安装Python（≥3.11）

    官网：Welcome to Python.org

TIP

安装教程：

79 fastinstall发布了一篇小红书笔记，快来看吧！ 😆 q16mTm9mycRvoaa 😆 http://xhslink.com/a/2lRUfHM42bt6，复制本条信息，打开【小红书】App查看精彩内容！

2、代码配置 ​

  1. 如果很久以前 fork 过，先在自己仓库的 Settings 里，翻到最下面，删除。

  2. 打开 MaaYuan主仓库，点击 Fork，继续点击 Create fork

  3. 按照提示fork好之后，接下来就会来到你的个人仓库，可以看到标题是 “你的用户名/MaaYuan”，下面一行小字 forked from syoius/MaaYuan（复制自 MaaYuan主仓库）

  4. 克隆你自己的仓库到本地，并拉取子模块

    下了git后，在命令行cmd/powershell中运行

    bash
    git clone --recursive https://github.com/<你的用户名>/MaaYuan.git  
git clone --recursive https://github.com/<你的用户名>/MaaYuan.git "F:\你的文件夹"   #安装到指定文件夹

    WARNING

    请注意，一定要完整克隆子项目，不要漏了 --recursive，也不要下载 zip 包！

    这步未正确操作会导致所有 OCR（文字识别）失败！

    *MaaCommonAssets子模块：路径为 assets\MaaCommonAssets 这是一些OCR模型

如已克隆但发现资源缺失?

在项目根目录运行以下命令更新子模块：

bash
git submodule update --init --recursive
想要在指定文件夹下载？

在你心仪的文件夹右键——在终端中打开/Open git bash here输入git命令。

或 win+R，输入 cmd后，输入

cmd
cd /d "F:\你的文件夹" #转换默认cmd路径至指定文件夹，powershell和bash的指令可能有所不同
我没有下git/git下载不下来/git clone总是失败，怎么办？

这是因为git clone需要本地代理，没有代理的需要搜索镜像源/在github的镜像网站上下载code的压缩包。

  1. 配置OCR文件

    WARNING

    只有配置好OCR文件，才能正常使用调试功能！否则会一直识别不到文字

    方法一：将OCR文件解压到 assets/resource/base/model/ocr/ 目录下。

    确保路径如下：

    sh
    assets/resource/base/model/ocr/
├── det.onnx
├── keys.txt
└── rec.onnx

    NOTE

    OCR文件怎么找：

    如果之前成功下载了子模块：在 assets\MaaCommonAssets\OCR\目录下有OCR文件

    无法成功下载，只下了本体：下载 OCR（文字识别）资源文件 ppocr_v5.zip

    方法二：成功下载了子模块，也可直接在根目录下面运行

    sh
    python tools/configure.py

    如果成功，提示如下：

    OCR model configured.

    同时在 assets/resource/base/model下可以看到建好的ocr文件夹，里面有装好的ocr文件。

  2. 下载 MaaFramework 的 Release 包，解压到 deps 文件夹中。

  3. 配置编程环境

  • 编程环境：下载好 Python、VS Code，环境就基本配置好啦，接下来就需要选一个 Maa 的开发工具
  • Maa 调试/开发工具列表

工具总览：MaaFramework社区项目

工具简介
MaaDebugger独立调试工具
Maa Pipeline SupportVSCode 插件，提供调试、截图、获取 ROI、取色等功能
MFA Tools Plus独立截图、获取 ROI、滑动、文字及取色工具
MaaLogAnalyzer可视化分析基于 MaaFramework 开发应用的日志
MaaPipelineExtremer - EditorMPE 网站，可视化编辑和分析 MaaYuan 的流程代码

  1. 开始开发

    使用上一个步骤中安装的开发工具开发MaaYuan，虚拟环境会自动创建在 .venv目录中。

    开始愉快的MaaYuan代码之旅，可以官方文档的使用参考。

    TIP

    推荐使用 VSCode 插件进行开发调试、MaaLogAnalyzer 进行用户日志分析、MPE进行流程查看梳理思路

    安装插件后，如果写的时候哪里不对都会标红。等vscode里都不红了之后再用Maa Debugger/Maa Pipeline support调试看运行流程有没有问题。

    参考文档：

    任务流水线（Pipeline）协议 | MaaFramework

    Project Interface V2 协议 | MaaFramework

    回调协议 | MaaFramework

    专用 VSCode 插件教程 | MAA 文档站

    IMPORTANT

    主要要编的代码：

    1、每个任务的代码（pipeline）：在 resource/pipeline下面的 .json文件里（每个任务的单独代码，就是识别到xx点击，接下来再识别xx，编写的规则参照 任务流水线（Pipeline）协议

    2、显示在gui上的页面（Interface）：在 interface.json中（任务写好了，想让它显示在gui中，并且能够显示任务说明、选项内容，参照 Project Interface V2 协议

    3、选项的实现：在 interface.json中写每个选项对应的 pipeline_override。

    4、日志中消息提醒（focus）：在每个 node中编写 focus信息实现，具体参照节点信息输出和官方文档回调协议

    话不多说，自行看代码更好理解！可参考MaaYuan、M9A的已有代码进行理解

  2. 程序测试

    利用 7. 编程环境中的小工具进行开发，推荐使用VSCode插件，也可使用MaaDebugger调试工具进行测试。选择你编写的代码，进行执行。

  3. git 操作（命令行版）

    通常用的最多的基本命令有：

    • git add <file>：添加文件到暂存区，* 代表全部文件
    • git commit -m "message"：提交暂存区到本地仓库。message 请遵循 约定式提交规范，让你的 commit 信息更加清晰
    • git pull origin <branch>：拉取远程仓库到本地仓库
    • git push origin <branch>：推送本地仓库到远程仓库
    bash
    git checkout -b <branch-name> # 创建并切换到新的分支

    完成开发后，推送你修改的本地分支到远程仓库（fork 的仓库，地址中是你的用户名）

    bash
    git push origin <branch-name>
    • 当 MaaYuan仓库出现更改（如其他人的commit），你可能需要把这些更改同步到你的分支

    （1）关联 MaaYuan 原仓库：

    sh
    git remote add upstream https://github.com/syoius/MaaYuan.git

    （2）拉取远程仓库更新：

    sh
    git fetch upstream

    （3）变基（推荐）或者合并修改：

    sh
    git rebase upstream/main # 变基，使commit历史更清晰，完成你的个人pr时建议使 用rebase而不是merge来合并修改

不会用命令行？在VSCode里也可以提交！

ctrl+s进行保存。源代码管理处可以进行拉取（git pull）、暂存（git add）、提交（git commit）、推送（git push）等操作，同命令行操作差不多。

参照给傻子的Git教程_哔哩哔哩_bilibili

  1. 提交 Pull Request

    你修改的代码已经提交到你的仓库（github网站上[你的个人远程仓库](https://github.com/<你的用户名>/MaaYuan)，为 origin/<分支名>）。

    现在你需要提交一个 Pull Request 到 MaaYuan的仓库（github上面MaaYuan的总仓库，upstream/<分支名>），等待维护者审核。

    GitHub网页端 Pull Request 参考教程

NOTE

PR的基本格式要求（约定式提交）：便于我查看和了解你这个代码干了什么，是加了新功能/改了bug/改了文档......

约定式提交规范

CAUTION

开发过程中，每一定数量，记得提交一个 commit, 别忘了写上 message

推荐自动生成提交信息工具：OpenCommit

假如你不熟悉 git 的使用，你可能需要创建并切换到一个新的分支，而不是直接提交在 main 上。这样你的提交就能在新的分支上生长，不会受到 main 更新的打扰。

MaaYuan 为免费开源项目，欢迎前往 GitHub 关注文档更新。

MaaYuan Docs · Built with VitePress