docs: 完善文档

MaaXYZ · Nov 29, 2024 · 025271e · 025271e
1 parent f5ba3e5
commit 025271e
Show file tree

Hide file tree

Showing 5 changed files with 41 additions and 24 deletions.
diff --git a/docs/zh_cn/develop/Pipeline 编写.md b/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 的字符串。

diff --git a/docs/zh_cn/develop/interface.json 编写.md b/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` 运行时第一行输出的文字。
diff --git a/docs/zh_cn/develop/外服适配.md b/docs/zh_cn/develop/外服适配.md
@@ -1,6 +1,6 @@
 # 外服适配
 
-目前来说，1999的外服都可以选择中文，选择后与国服相差不多，所以适配要做的事情也不是很多。
+目前来说，1999的外服都可以在游戏设置中选择中文，修改后与国服相差不多，所以适配要做的事情也不是很多。
 
 ## 资源适配
 

diff --git a/docs/zh_cn/develop/开发前须知.md b/docs/zh_cn/develop/开发前须知.md
@@ -1,5 +1,7 @@
 # 开发前须知
 
+> [!NOTE]
+>
 > 只有当您想要开发 M9A 时才需要看当前页面！
 >
 > 用户请转到 [M9A 使用手册](../manual/新手上路.md)。
@@ -34,25 +36,23 @@
 
     - 下载并安装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>`：推送本地仓库到远程仓库
 
@@ -97,6 +97,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 的仓库，等待维护者审核

diff --git a/docs/zh_cn/develop/项目重构.md b/docs/zh_cn/develop/项目重构.md
@@ -4,7 +4,7 @@
 
 注意对其修改时不要落下任何用到该资源的任务。
 
-> [!NOTE]
+> [!TIP]
 >
 > 善用全局搜索
 
@@ -30,3 +30,5 @@
 #### 简化任务链
 
 目的：简化 pipeline、理清逻辑
+
+部分任务可放在 `当前 task` 的 `父 task`（或 `父 task` 的 `父 task` 等等）的 `interrupt` 中，若一味的放入 `next` 则会导致任务链过长，影响阅读以及 pipeline 的简洁性。