MaaLYSK
✦v0.4.1-beta3

简体中文

English

简体中文

English

切换主题

零基础开发指南 ​

NOTE

只有当您想要开发MaaLYSK时才需要看当前页面！ 用户请转到 使用手册 开发 MaaFramework 或开发自己的项目请到 MaaXYZ/MaaFramework

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

MaaFramework官网

开发指南 | MAA 文档站

开发前须知 | M9A 文档站

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

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

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

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

NOTE

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

约定式提交规范

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

TIP

  • fork一份MaaLYSK主仓库的代码，并把代码下载到本地；

  • 在本地写pipeline、interface、custom文件，利用VSCode插件/小工具/MPE等进行截图、取ROI等操作，并利用VSCode插件/MaaDebugger/MPE等调试工具进行调试；

  • 利用git，实现本地（电脑硬盘里你的文件夹）-- 个人远程仓库（你fork的MaaLYSK仓库）的交互；

  • 再利用PR，实现个人远程仓库（你fork的MaaLYSK仓库）-- 上游原始仓库（MaaLYSK项目仓库）的交互。

1、前置准备 ​

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

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

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

    图片说明

    TIP

    • 可以下个代码补全的插件，一键补全，好用！
    • 代码格式化工具推荐Prettier，作者Prettier蓝标
    • 格式化插件列表见开发规范-MaaLYSK格式化要求

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

    git下载页面git下载页面

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

    官网：Welcome to Python.org

2、代码配置 ​

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

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

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

    *图片仅为示例，应该forkMaaLYSK主仓库而不是MaaFramework！

    fork页面示例

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

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

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

    WARNING

    --recursive 一定不要忘！--recursive 一定不要忘！--recursive 一定不要忘！
    OCR异常失败很可能就是没加recursive导致

    *MaaCommonAssets子模块

    • 路径为assets\MaaCommonAssets 这是一些OCR模型

    • 如果--recursive总是失败：单独下载子模块，解压到上述路径。

      拥有Mirror酱：前往Mirror酱项目列表 - MaaCommonAssets下载

      加入QQ开发群，群文件下载。群号：1071536530

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

    可运行：

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

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

    git bash

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

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

    这是因为git clone需要本地代理，没有代理的需要搜索镜像源。

    将git clone命令更改为镜像源下载，如：

    sh
    git clone --recursive https://gitclone.com/github.com/<你的用户名>/MaaLYSK.git

    也可自行搜索其他镜像源并进行操作

  5. 配置OCR文件

    WARNING

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

    命令行配置OCR文件：

    直接在根目录下面运行（需成功下载子模块）

    sh
    python tools/ci/configure.py

    如果成功，提示如下：

    ocr成功提示

    同时在assets/resource/base/model下可以看到建好的ocr文件夹，里面有装好的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

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

TIP

目前可跳过这步，仅在需要本地测试命令行版本时执行

  1. 配置编程环境

  1. 开始开发

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

    开始愉快的MaaLYSK代码之旅，有更多问题可查看MaaLYSK开发文档剩余章节，并阅读MaaFW官方文档。

    TIP

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

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

    参考文档（MaaFW官方文档）：

    任务流水线（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，比如银砂/辉曜的切换，就是通过在override里写收取信号之后，下一步识别”银砂”还是“辉曜”实现

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

    话不多说，具体代码可参考代码编写指南以及开发文档剩余章节，结合项目代码更好理解！可参考MaaLYSK、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>
    当 MaaLYSK仓库出现更改（如其他人的commit），你可能需要把这些更改同步到你的分支

    （1）关联 MaaLYSK 原仓库：

    sh
    git remote add upstream https://github.com/Witty36/MaaLYSK.git

    （2）根据情况选择操作

    • 已提交代码后远程有修改，进行合并修改：
    sh
    git fetch upstream                  #抓取远程仓库更新
git rebase upstream/main            #变基合并
git push origin main                #将本地合并后代码推送到你仓库的main分支
    • 本地未修改或无需保存，强制将本地更新为远程仓库版本（放弃本地操作）：
    sh
    git fetch upstream                  #抓取远程仓库更新
git reset --hard upstream/main      #强制重置把本地fix分支同步为上游仓库的main分支
git push origin main --force        #强制将与上游仓库同步的本地分支推送到你仓库的main分支
    • 未提交代码，暂存后重置本地更新
    sh
    git add .                           #将所有更改提交到暂存区
git stash push -m "暂存信息"         #暂存改动代码
git fetch upstream                  #抓取远程仓库更新
git reset --hard upstream/main      #强制重置把本地fix分支同步为上游仓库的main分支
git push origin main --force        #强制将与上游仓库同步的本地分支推送到你仓库的main分支
git stash pop                       #把刚才暂存的改动恢复回来

    如果fork时间很久，建议直接删除重新fork

git 参考资料：一张图看懂git原理

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

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

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

CAUTION

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

假如你不熟悉 git 的使用，你可能需要创建并切换到一个新的分支，而不是直接提交在 main 上

这样你的提交就能在新的分支上生长，不会受到 main 更新的打扰

  1. 提交 Pull Request

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

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

    GitHub网页端 Pull Request 参考教程