docs: user manual & developer documentation (#265)

aaaaaaaa，改分支名导致分支又被删了，还无法恢复

---------

Co-authored-by: a16797 <[email protected]>

.gitignore

@@ -417,7 +417,7 @@ FodyWeavers.xsd
 !.vscode/settings.json
 # !.vscode/tasks.json
 # !.vscode/launch.json
-# !.vscode/extensions.json
+!.vscode/extensions.json
 *.code-workspace
 
 # Local History for Visual Studio Code

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+    "recommendations": [
+        "ms-python.black-formatter",
+        "nekosu.maa-support",
+        "davidanson.vscode-markdownlint"
+    ]
+}

.vscode/settings.json

@@ -21,6 +21,9 @@
             "url": "/deps/tools/interface_config.schema.json"
         }
     ],
+    "files.exclude": {
+        "__pycache__": true
+    },
     "[json]": {
         "editor.formatOnSave": true,
         "editor.insertSpaces": true,
@@ -29,5 +32,12 @@
     },
     "[python]": {
         "editor.defaultFormatter": "ms-python.black-formatter"
+    },
+    "[markdown]": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
+    },
+    "markdownlint.config": {
+        "MD028": false
     }
 }

README.md

@@ -1,84 +1,45 @@
 # M9A
 
-基于全新架构的 亿韭韭韭 小助手。图像技术 + 模拟控制，解放双手！  
+基于全新架构的 亿韭韭韭 小助手。图像技术 + 模拟控制，解放双手！
 由 [MaaFramework](https://github.com/MaaXYZ/MaaFramework) 强力驱动！
 
-## 功能介绍
+## 功能列表
 
 目前已有的功能：
 
 - 启动/关闭游戏
 - 收取荒原、魔精收取生产物品
 - 每日心相（意志解析）
-- 刷体力、最优材料关卡、活动关卡导航、吃糖选项
+- 刷体力、最优材料关卡、活动关卡、吃糖选项
+- 每周深眠域
 - 领取日常奖励
 - 轶事派遣
-- 雨中悬想：迷思海（“寻思”每周扫荡）
+- 雨中悬想：迷思海（"寻思"周扫荡）
 - 局外演绎：山麓的回音（肉鸽）
-- 每周深眠域（使用游戏自带自动战斗）
-
-近期可能会支持的功能：
-- 自定义刷体力关卡
 
 ## 使用说明
 
-下载地址：<https://github.com/MaaXYZ/M9A/releases>
-
-### Windows
-
-- 对于绝大部分用户，请下载 `M9A-win-x86_64-vXXX.zip`
-- 若确定自己的电脑是 arm 架构，请下载 `M9A-win-aarch64-vXXX.zip`  
-  _请注意！Windows 的电脑几乎全都是 x86_64 的，可能占 99.999%，除非你非常确定自己是 arm，否则别下这个！_
-- 解压后运行 `MFAWPF.exe`（图形化界面）或 `MaaPiCli.exe`（命令行）即可
-
-### macOS
-
-- 若使用 Intel 处理器，请下载 `M9A-macos-x86_64-vXXX.zip`
-- 若使用 M1, M2 等 arm 处理器，请下载 `M9A-macos-aarch64-vXXX.zip`
-- 使用方式：
-
-  ```bash
-  chmod a+x MaaPiCli
-  ./MaaPiCli
-  ```
-
-### Linux
-
-~~用 Linux 的大佬应该不需要我教~~
-
-## 其他说明
+- [新手上路](./docs/zh_cn/manual/%E6%96%B0%E6%89%8B%E4%B8%8A%E8%B7%AF.md)(必看)
 
-- 提示“应用程序错误”，一般是缺少运行库，请安装一下 [vc_redist](https://aka.ms/vs/17/release/vc_redist.x64.exe)
-- 添加 `-d` 参数可跳过交互直接运行任务，如 `./MaaPiCli.exe -d`
-- 2.0 版本已支持 mumu 后台保活，会在 run task 时获取 mumu 最前台的 tab
-- 反馈问题请附上日志文件 `debug/maa.log`以及问题界面的截图，谢谢！
+- [部分功能介绍](./docs/zh_cn/manual/%E9%83%A8%E5%88%86%E5%8A%9F%E8%83%BD%E4%BB%8B%E7%BB%8D.md)(推荐)
 
+- [连接设置](./docs/zh_cn/manual/%E8%BF%9E%E6%8E%A5%E8%AE%BE%E7%BD%AE.md)(可选)
 
-
-## How to build
-
-**如果你要编译源码才看这节，否则直接 [下载](https://github.com/MaaXYZ/M9A/releases) 即可**
-
-0. 完整克隆本项目及子项目
-
-    ```bash
-    git clone --recursive https://github.com/MaaXYZ/M9A.git
-    ```
-
-1. 下载 MaaFramework 的 [Release 包](https://github.com/MaaXYZ/MaaFramework/releases)，解压到 `deps` 文件夹中
-2. 安装
-
-    ```python
-    python ./install.py
-    ```
-
-生成的二进制及相关资源文件在 `install` 目录下
+- [常见问题](./docs/zh_cn/manual/%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98.md)(推荐)
 
 ## 开发相关
 
 - [MaaFW 开发思路](https://github.com/MaaXYZ/MaaFramework/blob/main/docs/zh_cn/1.1-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B.md#%E5%BC%80%E5%8F%91%E6%80%9D%E8%B7%AF)  
-  M9A 目前使用其中第一种方式（纯 Pipeline 低代码），后续可能会迁移到第二种方式（Pipeline + 自定义任务）
-- [Pipeline 流水线协议](https://github.com/MaaXYZ/MaaFramework/blob/main/docs/zh_cn/3.1-%E4%BB%BB%E5%8A%A1%E6%B5%81%E6%B0%B4%E7%BA%BF%E5%8D%8F%E8%AE%AE.md)
+  > M9A 目前使用其中第一种方式（纯 Pipeline 低代码），  
+  > 后续可能会迁移到第二种方式（Pipeline + 自定义任务）
+- [开发前须知](./docs/zh_cn/develop/开发前须知.md)
+- [interface.json 编写](./docs/zh_cn/develop/interface.json%20编写.md)
+- [Pipeline 编写](./docs/zh_cn/develop/Pipeline%20编写.md)
+- [Bug 排查](./docs/zh_cn/develop/Bug%20排查.md)
+- [项目重构](./docs/zh_cn/develop/项目重构.md)
+- [活动资源维护](./docs/zh_cn/develop/活动资源维护.md)
+- [外服适配](./docs/zh_cn/develop/外服适配.md)
+- [文档编写](./docs/zh_cn/develop/文档编写.md)
 
 更多文档请前往 [MaaFramework](https://github.com/MaaXYZ/MaaFramework) 主仓库查看
 
@@ -88,11 +49,10 @@
 
 感谢以下开发者对本项目作出的贡献:
 
-<a href="https://github.com/MaaXYZ/M9A/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=MaaXYZ/M9A&max=1000" />
-</a>
+[![Contributors](https://contrib.rocks/image?repo=MaaXYZ/M9A&max=1000)](https://github.com/MaaXYZ/M9A/graphs/contributors)
 
 ## Join us
+
 - M9A 闲聊群 QQ 群：175638678
 - M9A 开发群 QQ 群：649344857
 - MaaFramework 开发交流 QQ 群: 595990173

docs/.markdownlint.yaml

@@ -112,7 +112,7 @@ MD026:
 MD027: false
 
 # MD028/no-blanks-blockquote - Blank line inside blockquote
-MD028: true
+MD028: false
 
 # MD029/ol-prefix - Ordered list item prefix
 MD029:

docs/zh_cn/develop/Bug 排查.md

@@ -0,0 +1,83 @@
+# Bug 排查
+
+修 bug 也是开发中重要的一环，如何快速准确地定位、分析、解决 bug 是有技巧的。本文将介绍一些常见的 bug 排查方法。
+
+> [!NOTE]
+>
+> 以下内容仅供参考，注意时效性。
+
+## 前置准备
+
+与 bug 发现者沟通，尽可能的获取 bug 相关的信息，如：
+
+- 资源版本
+- 系统版本
+- 问题的细节（发生的时间、场景等）
+- 配置文件、日志、截图等
+
+## 定位问题
+
+### 确认资源版本以及运行方式
+
+对于 M9A 来说，有两种运行方式：1. MaaPiCli 2. MFAWPF
+
+根据观察，MaaPiCli运行时有行log为
+
+```plaintext
+[2024-11-28 19:46:32.571][INF][Px14600][Tx16498][Parser.cpp][L56][MaaNS::ProjectInterfaceNS::Parser::parse_interface] Interface Version: [data.version=v2.4.11]
+```
+
+既能看出资源版本，又能看出是以 MaaPiCli 方式运行。
+
+```plaintext
+[2024-11-30 01:46:56.490][INF][Px20060][Tx33876][Parser.cpp][L56][MaaNS::ProjectInterfaceNS::Parser::parse_interface] Interface Version: [data.version=] 
+```
+
+当 `version` 为空时，MaaPiCli log 为以上样式。
+
+确认资源版本可以了解是否为已修复bug版本，确认运行方式则是因为不同运行方式，config文件不同，同时可能生成的bug也不同。
+
+### 确定问题 log 范围
+
+- 根据问题描述发生的时间缩小范围
+- 根据问题发生的任务缩小范围
+- 根据[ERR]确定错误相关原因
+- 根据bug相关的[ERR]处反向查找 `Task Hit` ，以确定出错任务
+
+## 分析问题
+
+在这里我将问题大致分为三类：资源加载问题、连接问题以及 pipeline 问题（timeout）。
+
+### 资源加载问题
+
+资源改名时覆盖安装导致的资源加载失败：
+
+```log
+[2024-11-17 22:29:04.185][ERR][Px10564][Tx9380][PipelineResMgr.cpp][L211][MaaNS::ResourceNS::PipelineResMgr::parse_config] key already exists [key=OutsideDeduction] 
+```
+
+### 连接问题
+
+模拟器连接失败：
+
+```log
+[2024-11-24 23:44:05.539][ERR][Px26056][Tx55883][ControlUnitMgr.cpp][L55][MaaNS::CtrlUnitNs::ControlUnitMgr::connect] failed to connect [adb_path_=D:/MuMu Player 12/shell/adb.exe] [adb_serial_=127.0.0.1:16384]
+```
+
+### pipeline 问题
+
+一般来说，是pipeline逻辑有漏洞导致的，需要进一步分析。
+
+常用的解决方法有：
+
+- 增加 `flag` 任务
+- 增加 `pre/post_wait_freezes` （注意默认 `target` 是否是你想要的）
+- 更改实现逻辑（如更换识别方式以及动作逻辑）
+
+## 解决问题
+
+前两种参考[常见问题](../manual/常见问题.md)解决，pipeline 问题需要进一步分析。
+
+## 验证修复
+
+修复后发布测试版，经测试无误后解决问题。

docs/zh_cn/develop/Pipeline 编写.md

@@ -0,0 +1,82 @@
+# Pipeline 编写
+
+## 编写规范
+
+### 命名规范
+
+为保证资源的美观一致，请尽量遵循以下现有规则。
+
+#### 资源命名
+
+- 对于图片等文件，采用大驼峰命名法，所有单词的首字母都大写。
+- 对于 `pipeline.json` 文件，一般来说，采用蛇形命名法，单词之间用下划线分隔，所有字母小写，  
+  特别地，专有名词的活动采取大驼峰命名法，一般在 `activity` 内。
+- 对于 `image` 下文件夹，每个文件夹对应一个 `pipeline.json` 文件，文件夹名采用大驼峰命名法，  
+  特别地，`activity` 内 `pipeline.json` 对应的 `image` 放到 `Combat/Activity` 处。
+
+#### Task 命名
+
+大多数采用大驼峰命名法，特别地，部分情况下用 `_` 连接前、后缀。
+
+前缀一般为 `Sub` 或 当前活动缩写（如 `SOD` 黄昏的音序、`EITM` 山麓的回音）等，其他情况建议不要前缀。
+
+后缀一般为 `数字` 或 `状态` 等，表示该任务的具体阶段或状态。（建议新写的任务不加后缀）
+
+### Task 编写
+
+参考[Pipeline 协议详细说明](https://github.com/MaaXYZ/MaaFramework/blob/main/docs/zh_cn/3.1-%E4%BB%BB%E5%8A%A1%E6%B5%81%E6%B0%B4%E7%BA%BF%E5%8D%8F%E8%AE%AE.md)
+
+> [!NOTE]
+>
+> - 一般 `next` 放置当前任务的出口任务，`interrupt` 放置当前任务的中断任务。
+> - 建议多写些 `Flag` 任务进行判断，以保证任务的稳定性。
+> - 部分情况下，可在 `next` 加入自身，以提高任务的稳定性。（存在程序未正确接受动作的情况）
+
+### next & interrupt 任务顺序
+
+总体上，`interrupt` 第一个任务 比 `next` 最后一个任务低一优先级。
+
+在 `next` 或 `interrupt` 内部，统一先按照优先级由高到低顺序排列，不能出现优先级倒挂的情况。举例：
+
+```plaintext
+现有判断一个小弹窗的任务B，和判断跳出弹窗前界面的任务A。
+如果弹窗出现时依旧能匹配到任务A，则任务B的优先级应该高于任务A，否则会出现无法处理B而卡死于A的情况
+```
+
+同一优先级内的任务，可按照匹配频率由高到低顺序排列，以便提高命中率，降低资源消耗。
+
+### 注释规范
+
+`pipeline.json` 文件中，注释共两种属性字段：
+
+1. `.*_doc$|^doc$`： 以 _doc 结尾的字符串或者正好是 doc 的字符串。
+2. `.*_code$|^code$`：以 _code 结尾的字符串或者正好是 code 的字符串。
+
+前者为对当前 task（或某字段）的说明，后者为对必填字段的占位。举例：
+
+```json
+{
+    "EnterTheActivityMain": {
+        "doc": "进入当期活动主界面",
+        "template_code": "在interface.json中修改template",
+        "recognition": "TemplateMatch",
+        "roi": [
+            885,
+            123,
+            340,
+            183
+        ],
+        "action": "Click",
+        "post_wait_freezes": 300,
+        "next": [
+            "ActivityMainFlag",
+            "EnterTheActivityMain"
+        ]
+    }
+}
+```
+
+`doc` 为当前 task 说明。
+
+`template_code` 为必填字段占位，
+原因是 `recognition` 为 `TemplateMatch` 时， "template" 字段必填，但我们想在 `interface.json` 中修改，故用 `template_code` 占位。