docs: 完善文档

docs: 完善文档

README.md

@@ -30,7 +30,7 @@
 ## 开发相关
 
 - [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 + 自定义任务）
+  > 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)

docs/zh_cn/develop/Pipeline 编写.md

@@ -9,38 +9,45 @@
 #### 资源命名
 
 - 对于图片等文件，采用大驼峰命名法，所有单词的首字母都大写。
-- 对于 `pipeline.json` 文件，一般来说，采用蛇形命名法，单词之间用下划线分隔，所有字母小写，特别地，专有名词的活动采取大驼峰命名法，一般在 `activity` 内。
-- 对于 `image` 下文件夹，每个文件夹对应一个 `pipeline.json` 文件，文件夹名采用大驼峰命名法，特别地，`activity` 内 `pipeline.json` 对应的 `image` 放到 `Combat/Activity` 处。
+- 对于 `pipeline.json` 文件，一般来说，采用蛇形命名法，单词之间用下划线分隔，所有字母小写，  
+  特别地，专有名词的活动采取大驼峰命名法，一般在 `activity` 内。
+- 对于 `image` 下文件夹，每个文件夹对应一个 `pipeline.json` 文件，文件夹名采用大驼峰命名法，  
+  特别地，`activity` 内 `pipeline.json` 对应的 `image` 放到 `Combat/Activity` 处。
 
-#### task 命名
+#### Task 命名
 
 大多数采用大驼峰命名法，特别地，部分情况下用 `_` 连接前、后缀。
 
 前缀一般为 `Sub` 或 当前活动缩写（如 `SOD` 黄昏的音序、`EITM` 山麓的回音）等，其他情况建议不要前缀。
 
 后缀一般为 `数字` 或 `状态` 等，表示该任务的具体阶段或状态。（建议新写的任务不加后缀）
 
-### task 编写
+### 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` 加入自身可提高任务的稳定性。（存在程序未正确接受动作的情况）
+> - 建议多写些 `Flag` 任务进行判断，以保证任务的稳定性。
+> - 部分情况下，可在 `next` 加入自身，以提高任务的稳定性。（存在程序未正确接受动作的情况）
 
 ### next & interrupt 任务顺序
 
 总体上，`interrupt` 第一个任务 比 `next` 最后一个任务低一优先级。
 
-在 `next` 或 `interrupt` 内部，统一先按照优先级由高到低顺序排列，不能出现优先级倒挂的情况。（现有判断一个小弹窗的任务B，和判断跳出弹窗前界面的任务A。如果弹窗出现时依旧能匹配到任务A，则任务B的优先级应该高于任务A，否则会出现无法处理B而卡死于A的情况）
+在 `next` 或 `interrupt` 内部，统一先按照优先级由高到低顺序排列，不能出现优先级倒挂的情况。举例：
+
+```plaintext
+现有判断一个小弹窗的任务B，和判断跳出弹窗前界面的任务A。
+如果弹窗出现时依旧能匹配到任务A，则任务B的优先级应该高于任务A，否则会出现无法处理B而卡死于A的情况
+```
 
 同一优先级内的任务，可按照匹配频率由高到低顺序排列，以便提高命中率，降低资源消耗。
 
 ### 注释规范
 
-注释共两种：
+`pipeline.json` 文件中，注释共两种属性字段：
 
 1. `.*_doc$|^doc$`： 以 _doc 结尾的字符串或者正好是 doc 的字符串。
 2. `.*_code$|^code$`：以 _code 结尾的字符串或者正好是 code 的字符串。

docs/zh_cn/develop/interface.json 编写.md

@@ -2,7 +2,7 @@
 
 [参考资料——interface.schema.json](https://github.com/MaaXYZ/MaaFramework/blob/main/tools/interface.schema.json)
 
-interface.json
+`interface.json` 旨在提供菜单配置。
 
 ## controller
 
@@ -26,6 +26,7 @@ interface.json
                 "{PROJECT_DIR}/resource/bilibili"
             ]
         }
+    ]
 }
 ```
 
@@ -46,6 +47,7 @@ interface.json
             "template_doc": "修改为当期活动入口的template",
             "template": "Combat/Activity/LondonDawningEnterTheShow.png"
         }
+    }
 }
 ```
 
@@ -143,11 +145,12 @@ interface.json
         }
     }
 }
+```
 
 ## version
 
 版本。不必填写，ci install 时会自动生成。
 
 ## message
 
-信息。目前为 MaaPiCli 运行时第一行输出的文字。
+信息。目前为 `MaaPiCli` 运行时第一行输出的文字。

docs/zh_cn/develop/外服适配.md

@@ -1,6 +1,6 @@
 # 外服适配
 
-目前来说，1999的外服都可以选择中文，选择后与国服相差不多，所以适配要做的事情也不是很多。
+目前来说，1999的外服都可以在游戏设置中选择中文，修改后与国服相差不多，所以适配要做的事情也不是很多。
 
 ## 资源适配
 

docs/zh_cn/develop/开发前须知.md

@@ -1,5 +1,7 @@
 # 开发前须知
 
+> [!NOTE]
+>
 > 只有当您想要开发 M9A 时才需要看当前页面！
 >
 > 用户请转到 [M9A 使用手册](../manual/新手上路.md)。
@@ -24,6 +26,8 @@
     git clone --recursive https://github.com/<你的用户名>/M9A.git
     ```
 
+    > [!IMPORTANT]
+    >
     > **--recursive 一定不要忘！****--recursive 一定不要忘！****--recursive 一定不要忘！**
     >
     > OCR异常失败很可能就是没加recursive导致。
@@ -33,38 +37,37 @@
 5. 配置编程环境
 
     - 下载并安装vscode
-    - 安装调试/开发工具
-        - [MaaDebugger](https://github.com/MaaXYZ/MaaDebugger) | 独立调试工具
-        - [Maa Pipeline Support](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support) | VSCode 插件，提供调试、截图、获取ROI、取色等功能
-        - [ImageCropper](https://github.com/MaaXYZ/MaaFramework/tree/main/tools/ImageCropper) | 独立图片裁剪及 ROI 获取工具
-        - [MFA Tools](https://github.com/SweetSmellFox/MFATools) | 独立截图、获取ROI及取色工具
+    - 选择性安装调试/开发工具
+
+        | 工具 | 简介 |
+        | --- | --- |
+        | [MaaDebugger](https://github.com/MaaXYZ/MaaDebugger) | 独立调试工具 |
+        | [Maa Pipeline Support](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support) | VSCode 插件，提供调试、截图、获取ROI、取色等功能 |
+        | [ImageCropper](https://github.com/MaaXYZ/MaaFramework/tree/main/tools/ImageCropper) | 独立图片裁剪及 ROI 获取工具 |
+        | [MFA Tools](https://github.com/SweetSmellFox/MFATools) | 独立截图、获取ROI及取色工具 |
 
 6. 开始开发
 
-    开始愉快的改代码吧
+    开始愉快的改代码吧，开始前查看[相关阅读](#相关阅读)。
 
 7. git 操作
 
-    git 参考资料：
-    - [git 官方文档](https://git-scm.com/docs)
-    - [git 简明指南](https://www.runoob.com/manual/git-guide/)
-    - [git 教程|菜鸟教程](https://www.runoob.com/git/git-tutorial.html)
-
-    通常用的最多的命令有：
+    通常用的最多的基本命令有：
     - `git add <file>`：添加文件到暂存区，`*` 代表全部文件
-    - `git commit -m "message"`：提交暂存区到本地仓库。[约定式提交规范](https://www.conventionalcommits.org/zh-hans/v1.0.0/)，让你的 commit 信息更加清晰
+    - `git commit -m "message"`：提交暂存区到本地仓库。`message` 请遵循 [约定式提交规范](https://www.conventionalcommits.org/zh-hans/v1.0.0/)，让你的 commit 信息更加清晰
     - `git pull origin <branch>`：拉取远程仓库到本地仓库
     - `git push origin <branch>`：推送本地仓库到远程仓库
 
-    开发过程中，每一定数量，记得提交一个 commit, 别忘了写上 message
-    假如你不熟悉 git 的使用，你可能需要创建并切换到一个新的分支，而不是直接提交在 main 上
+    > [!TIP]
+    >
+    > 开发过程中，每一定数量，记得提交一个 commit, 别忘了写上 message
+    > 假如你不熟悉 git 的使用，你可能需要创建并切换到一个新的分支，而不是直接提交在 main 上
+    > 这样你的提交就能在新的分支上生长，不会受到 main 更新的打扰
 
     ```bash
-    git checkout -b <branch-name>
+    git checkout -b <branch-name> # 创建并切换到新的分支
     ```
 
-    这样你的提交就能在新的分支上生长，不会受到 main 更新的打扰
-
     完成开发后，推送你修改的本地分支到远程仓库（fork 的仓库）
 
     ```bash
@@ -97,6 +100,11 @@
         git merge upstream/main
         ```
 
+    git 参考资料：
+    - [git 官方文档](https://git-scm.com/docs)
+    - [git 简明指南](https://www.runoob.com/manual/git-guide/)
+    - [git 教程|菜鸟教程](https://www.runoob.com/git/git-tutorial.html)
+
 8. 提交 Pull Request
 
     你修改的代码已经提交到你的仓库，现在你需要提交一个 Pull Request 到 M9A 的仓库，等待维护者审核
@@ -107,7 +115,7 @@
 
 M9A 使用一系列的格式化工具来保证仓库中的代码和资源文件美观统一，以便于维护和阅读
 
-请确保在提交之前已经格式化，或是[启用 Pre-commit Hooks 进行自动格式化](#利用 Pre-commit Hooks 自动进行代码格式化)
+请确保在提交之前已经格式化，或是[启用 Pre-commit Hooks 进行自动格式化](#pre-commit-hooks)
 
 目前启用的格式化工具如下：
 
@@ -118,6 +126,8 @@ M9A 使用一系列的格式化工具来保证仓库中的代码和资源文件
 
 ### 利用 Pre-commit Hooks 自动进行代码格式化
 
+<a id="pre-commit-hooks"></a>
+
 1. 确保你的电脑上有 Python 与 Node 环境
 
 2. 在项目根目录下执行以下命令

docs/zh_cn/develop/项目重构.md

@@ -4,7 +4,7 @@
 
 注意对其修改时不要落下任何用到该资源的任务。
 
-> [!NOTE]
+> [!TIP]
 >
 > 善用全局搜索
 
@@ -29,4 +29,10 @@
 
 #### 简化任务链
 
-目的：简化 pipeline、理清逻辑
+##### 目的
+
+简化 pipeline、理清逻辑
+
+##### 操作
+
+部分任务可放在 `当前 task` 的 `父 task`（或 `父 task` 的 `父 task` 等等）的 `interrupt` 中，若一味的放入 `next` 则会导致任务链过长，影响 pipeline 的可读性和简洁性。