mirror of https://github.com/MaaAssistantArknights/MaaAssistantArknights.git synced 2026-07-17 10:00:44 +08:00

Files

Lucien Shaw 14194d1118 chore: 完善容器配置及依赖安装 (#14208 )

格式化工具部分：
1. pre-commit 引入 python 的格式化工具，包括 black（代码格式化）和 isort（对“包导入顺序”的规范）
2. 允许 prettier 对文档站的 markdown 文件格式化
3. 不允许 prettier 对 markdown 文件中的代码块的代码本身进行格式化
4. 升级了 pre-commit 的各个 hook 的版本
5. 优化了 pre-commit 的日志文本显示

容器总览部分：
1. 由原来的单一轻量环境转为区分空环境、轻量环境和全量环境
2. 空环境是裸 Linux 镜像（Ubuntu），为默认环境
3. 轻量环境适合开发文档站前端
4. 全量环境适合开发 MaaCore
5. 目前，全量环境完整包含了轻量环境，轻量环境完整包含了空环境
6. 在仓库 README.md 中更新了三个环境的描述，并将链接分别设置为对应环境的创建链接
   **注意：没有修改文档站中的对应文件**
7. 在各个语言的开发指南的最后，移除了 Codespace 部分的“安装额外依赖”相关描述，且将链接设置为全量环境的创建链接
   **注意：没有添加“开发文档站”的指南和对应 codespace 的使用方式**

容器的轻量环境和全量环境共有部分：
1. 安装 black 和 isort 包
2. 调整 VS Code 设置，取消先前（对 markdown 文件单独指定 markdownlint 扩展作为格式化工具）的错误设置，现在 markdown 文件仍然使用默认的 prettier 扩展作为格式化工具
3. 引入 markdown-all-in-one 扩展作为语法提示工具
4. 将 node_modules 和 3rdparty 排除在 VS Code 的文本的搜索路径之外

容器的全量环境部分：
1. 为 tools 下的所有 python 脚本安装依赖
2. 使用 tools/maadeps-download.py 下载 maadeps，且将必要二进制文件软链接到 /usr/local/bin/
3. 使用 apt 安装 cmake 和 clangd-20，将后者通过 update-alternatives 设置为系统 clangd 的默认版本
4. 使用 cmake tools 扩展，并按照 Linux 编译方法进行配置
5. 使用 clang-format 作为 c/cpp 的格式化工具，clang-format 程序主体来自 maadeps（已经软链接到 /usr/local/bin/）
6. 使用 clangd 作为 c/cpp 的语法提示工具
7. 将 MaaDeps、install 和 build 排除在 VS Code 的文本搜索路径之外

其它手动调整：
1. 更新文档站的 package.json，指定 pnpm 包管理器的版本
2. 手动保证 markdown 文件中的列表前后有空行（注意到 MarkdownLint 官方规则不一定能精准定位所有“列表前后空行”的问题，详见：https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md032---lists-should-be-surrounded-by-blank-lines ）
3. 修改了部分 markdown 文件中的 json 代码块的语法问题
   **注意：相同的问题并未全部发现，仅修改了两处**
4. 在 tools 目录中，一处 python 脚本的包名误用（本地包名和某个 pip 包重名），这里修改了相应代码
5. 在 tools 目录中，一处 python 脚本使用了弃用的包 cchardet 的问题，这里更换了推荐使用的功能相近的包并修改了相应代码

自动化脚本提交的修改：
1. 自动格式化了大量 tools 中的 python 脚本
2. 自动格式化了大量 docs 中的 markdown 文件

Commits:

* chore: pre-commit引入black和isort规范py文件

* chore: Auto update by pre-commit hooks [skip changelog]

* chore: devcontainer添加isort扩展，排序python导入

* chore: pre-commit任务命名及更名

* style: isort fix

* chore: Auto update by pre-commit hooks [skip changelog]

* chore: 更新pre-commit的hook版本

* fix: 模块名与第三方库重名，大忌

* chore: 容器构建时额外安装isort

* docs: md -> markdown

* chore: 容器安装python包和maadeps

* fix: 修复过时python包

* chore: 指定pnpm版本

* chore: container支持选择轻量环境

* chore: 去掉rust

* chore: add plain env

* chore: 使用clangd语言服务器

* chore: 无需单独设置markdown的格式化工具

* chore: 更新安装的clangd版本

* docs: 简易文档适配

* docs: 在仓库README中重新编排codespaces相关指引

* chore: Auto update by pre-commit hooks [skip changelog]

* style: 调整缩进

* chore: 格式化工具不用特意排除被gitignore忽略的文件

* chore: sh文件在gitattributes中单列一类

* chore: 格式化docs下的markdown文件

* chore: 暂时不修改md文件中的代码块

* style: 人为明确markdown中的部分列表相关格式

* docs: 补上部分markdown的json代码块中缺失的逗号

* chore: Auto update by pre-commit hooks [skip changelog]

* chore: Auto update by pre-commit hooks [skip changelog]

* fix: 补上tools的服务器排序相关代码中缺失的逗号

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* chore: 使用maadeps的clangd

* build: 更新maadeps工具链版本

* style: prettier fix

* revert: 还原maadeps版本

* revert: 取消使用maadeps的clangd依赖，改用系统apt安装

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

2025-09-30 19:39:48 +08:00

8.6 KiB

Raw Blame History

order, icon

order	icon
5	ri:earth-fill

外服適配教學

準備工作

在開始這個教學之前，請確保你已經：

安裝並正確配置了所需軟體。在陸服或相應用戶端的 readme.md 中應該會有相關資訊，確保所支援的功能可以正常執行。
閱讀了 3.4-任務流程協議.md，對各個欄位的含義和用法有基本瞭解，並能理解 @、# 類型任務的含義和用法。
瞭解外服的 task.json 和範本圖片中未提及的和缺少的內容會使用陸服的 task.json 和範本圖片等內容作為備選。外服的 task.json 中的內容會覆蓋並重寫陸服對應任務的相應欄位。
具備一定的英語能力，能夠閱讀英文日誌，並能通過日誌找出缺失的圖片等資訊。
建議按照任務鏈進行修改。例如，對於 Award 任務，根據陸服 task.json 中 Award 任務的 next 順序逐步替換 範本圖片 / 文字 / 修改 roi，以確保修改後的每一步都能正常執行，或者能夠迅速發現錯誤。這樣可以避免因為一次修改修改了太多內容而不清楚程式因為哪一步卡住而不能執行。

修改前準備

在進行修改之前，有幾個準備工作需要注意：

參考陸服 task.json，確保你已經準備好了與陸服不同的用於外服的範本圖片和文字內容。
確保你能夠隨時獲取這些圖片和文字內容。

獲取截圖

為了獲取高品質的截圖，請依照以下說明：

使用模擬器內建的截圖工具進行截圖並保存。
確保截圖的尺寸大於 1280*720，長寬比為 16:9。
確保截圖中不包含任何無關內容，例如任務欄、狀態欄、通知欄等。
確保截圖中包含所有需要辨識的內容。

為了裁剪圖片並獲取文字 / 圖片 roi，你需要安裝 python 和 opencv，並下載 MaaAssistantArknights/tools/CropRoi/main.py 檔案。

然後，按照以下步驟操作：

在 main.py 同目錄下新建 src 和 dst 資料夾。
將需要修改大小或獲取文字 / 圖片 roi 的 完整截圖 放入 src 資料夾。
執行 main.py。
使用滑鼠拖動選擇目標範圍，儘量不要包含無關內容。
確定範圍後，按 S 鍵保存，按 Q 鍵退出。裁剪後的圖片將被保存在 dst 資料夾。

例如完成一次裁剪後的輸出內容為：

src: Screenshot_xxx.png
dst: Screenshot_xxx.png_426,272,177,201.png
original roi: 476, 322, 77, 101,
amplified roi: 426, 272, 177, 201

其中，

Screenshot_xxx.png 為放入 src 資料夾的完整截圖的名稱。Screenshot_xxx.png_426,272,177,201.png 為截取後的圖片。

original roi 為滑鼠選取的區域。amplified roi 為擴大後的區域，你需要的是擴大後的範圍，因此在 task.json 中的 roi 欄位填入的就是這個值。

修改範本圖片

在修改範本圖片之前，需要打開對應用戶端的範本圖片資料夾和陸服的範本圖片資料夾。

例如：

美服的範本圖片資料夾位置為 MaaAssistantArknights\resource\global\YoStarEN\resource\template。
陸服的範本圖片資料夾位置為 MaaAssistantArknights\resource\template。

參考 task.json 中提到的範本圖片，對比陸服和外服的範本圖片，找出外服中缺少的範本。

通常情況下，除了標誌等圖片，包含文字的範本都需要通過截圖來替換。如果圖片尺寸明顯大於陸服的對應範本圖片，則需要修改 roi 的大小。

將截取並重新命名完成的範本圖片放入對應用戶端的範本圖片資料夾。

修改文字內容

在修改文字內容之前，需要打開對應伺服器的 task.json 和陸服的 task.json。

例如：

美服的 task.json 位置為 MaaAssistantArknights\resource\global\YoStarEN\resource\tasks.json。
陸服的 task.json 位置為 MaaAssistantArknights\resource\tasks.json。

找到對應任務，將 text 欄位修改為對應伺服器內顯示的內容。注意，辨識的內容可以是遊戲內完整內容的字串。

通常情況下，除非是純 ASCII 字元辨識，否則包含文字的 text 都需要替換。

如果文字長度明顯大於陸服，則需要修改 roi 的大小，如 "任務" 和 "Mission" 長度差距過大，則需要修改外服該任務 roi 的大小。

如果對應外服的 task.json 中沒有該任務，則需要添加任務，只需要填寫 text 欄位即可。

修改 ROI 範圍

打開對應伺服器的 task.json，如美服的位置為 MaaAssistantArknights\resource\global\YoStarEN\resource\tasks.json
找到對應需要修改的 roi 範圍的任務，使用您準備好的外服遊戲介面截圖，根據 amplified roi，調整 roi 範圍的大小。
通常情況下， roi 不需要修改，只有和陸服的辨識內容大小差距過大時才需要修改。
如對應外服的 task.json 中任務不存在，則新增任務，寫上 roi 欄位。

保存設定並重新啟動軟體

在修改完成後，重新啟動軟體，重新載入檔案，使修改生效。

或在軟體目錄下新建一個 DEBUG.txt，這樣每次點擊開始都會重新載入範本和文件，不需要重開。

檢查是否成功：

檢查軟體的執行情況，確保軟體能夠在外服中正常使用。
如不能正常執行，需要檢查修改是否正確，或查看日誌輸出，進而找到出錯的地方。

解讀日誌

有些時候，我們修改完了 task.json 之後發現程式仍然不能正確執行，這時候我們考慮考慮查看日誌找到出錯的地方，進而修改對應任務。

日誌檔的位置在軟體的根目錄下，檔案名為 asst.log。

如果你是自己編譯的 MAA ，則在 \x64\Release 或 x64\RelWithDebInfo ，具體在哪個資料夾取決你編譯時選擇的編譯模式。

下面是一段日誌範例：

[2022-12-18 17:43:17.535][INF][Px7ec][Tx15c8] {"taskchain":"Award","details":{"to_be_recognized":["Award@ReturnTo","Award","ReceiveAward","DailyTask","WeeklyTask","Award@CloseAnno","Award@CloseAnnoTexas","Award@TodaysSupplies","Award@FromStageSN"],"cur_retry":10,"retry_times":20},"first":["AwardBegin"],"taskid":2,"class":"asst::ProcessTask","subtask":"ProcessTask","pre_task":"AwardBegin"}
[2022-12-18 17:43:18.398][INF][Px7ec][Tx15c8] Call ` C:\Program Files\BlueStacks_nxt\.\HD-Adb.exe -s 127.0.0.1:5555 exec-out "screencap | gzip -1" ` ret 0 , cost 862 ms , stdout size: 2074904 , socket size: 0
[2022-12-18 17:43:18.541][TRC][Px7ec][Tx15c8] OcrPack::recognize | roi: [ 500, 50, 300, 150 ]
[2022-12-18 17:43:18.541][TRC][Px7ec][Tx15c8] Ocr Pipeline with asst::WordOcr | enter
[2022-12-18 17:43:18.634][TRC][Px7ec][Tx15c8] Ocr Pipeline with asst::WordOcr | leave, 93 ms
[2022-12-18 17:43:18.634][TRC][Px7ec][Tx15c8] OcrPack::recognize | raw: [{ : [ 0, 0, 300, 150 ], score: 0.000000 }]
[2022-12-18 17:43:18.634][TRC][Px7ec][Tx15c8] OcrPack::recognize | proc: []
[2022-12-18 17:43:18.637][TRC][Px7ec][Tx15c8] asst::ProcessTask::_run | leave, 1101 ms
[2022-12-18 17:43:18.638][TRC][Px7ec][Tx15c8] ready to sleep 500
[2022-12-18 17:43:19.144][TRC][Px7ec][Tx15c8] end of sleep 500
[2022-12-18 17:43:19.144][TRC][Px7ec][Tx15c8] asst::ProcessTask::_run | enter

在這段日誌中，你可以看到：

taskchain 代表當前進行中的任務。
details 是任務的內容，包括需要辨識的欄位（to_be_recognized）和當前重試次數（cur_retry）和總重試次數（retry_times）。
first 代表任務的開始。
taskid 是任務的編號。
class 和 subtask 分別代表任務的類別和子任務。
pre_task 代表前一個任務。

此外，日誌中還會記錄命令的執行情況（如 Call）和 OCR 的資訊（如 OcrPack::recognize）。

在這段日誌中 "to_be_recognized","cur_retry":3,"retry_times":20 表示已經重複辨識了 10 次，最大辨識次數為 20 次，到了最大辨識次數後會跳過該任務並報錯，繼續執行下一個任務。

如果前面的任務沒有問題，我們基本可以確定是這裡的辨識出了問題，需要查看日誌中的提到的任務，尋找是否有對應的 範本圖片，對應任務的 text 是否錯誤，任務辨識 roi 範圍是否正確，進而找出問題所在並修改。

通過查看對應範本圖片，發現美服範本圖片資料夾中有這張圖的範本，但是大小明顯大於陸服圖片，導致陸服的 roi 用在美服上辨識不出來，所以需要修改美服的 task.json 中的對應任務 roi，使其與美服圖片大小對應。

提交你的修改

請參考 Github Pull Request 說明。

8.6 KiB Raw Blame History Unescape Escape