fz-mirrors/MaaAssistantArknights
0
0
Fork 0
mirror of https://github.com/MaaAssistantArknights/MaaAssistantArknights.git synced 2026-07-18 10:10:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 添加zh-tw文档

Browse Source
This commit is contained in:
Helloworld
2022-09-09 22:41:49 +08:00
parent ba7da15220
commit 14924eb8bc
12 changed files with 1588 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
README_zh-TW.md
View File

@@ -67,11 +67,11 @@ MAA 的意思是 MAA Assistant Arknights
### 基本說明
1. 請根据 [模擬器支援情況](docs/1.3-模拟器支持.md)，進行對應的操作。
1. 請根据 [模擬器支援情況](docs/zh-tw/1.3-模擬器支援.md)，進行對應的操作。
2. 修改模擬器解析度為 `16:9` 比例，最低 `1280 * 720`, 更高不限。
3. 開始使用吧！
更多使用說明請參考 [詳細介紹](docs/1.1-详细介绍.md)
更多使用說明請參考 [詳細介紹](docs/zh-tw/1.1-詳細介紹.md)
## 常見問題
@@ -81,7 +81,7 @@ MAA 的意思是 MAA Assistant Arknights
- 如何連接自定義通訊埠
- 下載速度慢，且鏡像站無法打開網頁
請參考 [常見問題](docs/1.2-常见问题.md)
請參考 [常見問題](docs/zh-tw/1.2-常見問題.md)
## 外服支援
@@ -144,7 +144,7 @@ MAA 的意思是 MAA Assistant Arknights
### Linux | macOS
請參考 [Linux 編譯教程](docs/2.1-Linux编译教程.md)
請參考 [Linux 編譯教程](docs/zh-tw/2.1-Linux編譯教程.md)
### API
@@ -155,21 +155,21 @@ MAA 的意思是 MAA Assistant Arknights
- [Java 介面](src/Java/Maaj/src/main/java/com/iguigui/maaj/easySample/MeoAssistant.java)：[整合示例](src/Java/Maaj/src/main/java/com/iguigui/maaj/easySample/MaaJavaSample.java)
- [Rust 介面](src/Rust/src/maa_sys/)：[HTTP 介面](src/Rust)
- [HTTP 介面](src/Java/Maaj/Readme.md)
- [整合文件](docs/3.1-集成文档.md)
- [回呼訊息協定](docs/3.2-回调消息协议.md)
- [任務流程協定](docs/3.4-任务流程协议.md)
- [自動抄作業協定](docs/3.3-战斗流程协议.md)
- [整合文件](docs/zh-tw/3.1-集成文件.md)
- [回呼訊息協定](docs/zh-tw/3.2-回呼訊息協定.md)
- [任務流程協定](docs/zh-tw/3.4-任務流程協定.md)
- [自動抄作業協定](docs/zh-tw/3.3-戰鬥流程協定.md)
### Issue Bot
- 使用 `Add {LABEL_NAME}` 增加標籤，使用 `Remove {LABEL_NAME}` 刪除標籤。
- 在提交說明中用 `close #{ISSUE_NUMBER}` 或 `fix #{ISSUE_NUMBER}` 給對應議題增加 `fixed` 標籤。
更多說明請參考 [Issue Bot 使用方法](docs/2.3-IssueBot使用方法.md)。
更多說明請參考 [Issue Bot 使用方法](docs/zh-tw/2.3-IssueBot使用方法.md)。
### 想參與開發，但不太會用 Github?
[Github Pull Request 流程簡述](docs/2.2-开发相关.md)
[Github Pull Request 流程簡述](docs/zh-tw/2.2-開發相關.md)
## 聲明

82
docs/zh-tw/1.1-詳細介紹.md Normal file
View File

@@ -0,0 +1,82 @@
# MAA使用說明
## 詳細介紹
### 刷理智
- 若選項中沒有你需要的關卡，請手動進入遊戲 **藍色開始按鈕** 畫面，並選擇 `當前關卡`。
- 主畫面上的 `吃理智`、`吃石頭`、`指定次數` 三個選項為短路開關，即三個選項中的任一條件達到，均會視為任務完成，停止刷理智。
- 舉例1：設定 `吃理智藥` : `999`、`吃石頭` : `10`、`指定次數` : `1`。則在刷完 **一次** 後，由於滿足了 `指定次數`:`1` 的條件，視為任務完成，停止刷理智。
- 舉例2：不勾選 `吃理智藥`、不勾選 `吃石頭`，設定 `指定次數` : `100`。則在當前可用理智全部刷完後（可能只刷了幾次），由於滿足了 `不吃理智藥`、`不吃石頭` 的條件，視為任務完成，停止刷理智。
- 刷完自動上傳 [企鵝物流資料統計](https://penguin-stats.cn/)
- 可自定義企鵝物流 ID
- 辨識並顯示材料掉落
- 斷線後會重連，繼續刷上次的圖
- 凌晨 4 點更新後也會重連，繼續刷上次的圖
- 支援剿滅模式
- 支援打完升級了的情況
- 支援代理失敗的情況，會自動放棄本次行動
### 基建換班
#### 換班策略
自動計算並選擇 **單設施內的最優解**，支援所有通用類技能和特殊技能組合；支援辨識經驗書、赤金、源石碎片、芯片，分別使用不同的幹員組合！
#### 宿舍入駐心情閾值
辨識心情進度列的百分比；心情小於該閾值的幹員，不會再去上班，直接進駐宿舍。
#### 特殊說明
- 基建換班目前均為單設施最優解，但非跨設施的全局最優解。例如：`巫戀+龍舌蘭`、`紅雲+稀音` 等這類單設施內的組合，都是可以正常辨識並使用的；`迷迭香`、`紅松騎士團` 這類多個設施間聯動的體系，暫不支援使用。
- 若 `無人機用途` 選擇 `貿易站-龍門幣` ，則將額外辨識是否有 `巫戀組`，並優先為其使用。
- 會客室僅缺一個線索時，會選擇對應流派的幹員；否則會選擇通用幹員。
- 會客室僅當自有線索滿時，才會送出線索，並且只送三個。有需要的同學可自行修改 `resource/tasks.json` 中 `SelectClue` - `maxTimes` 欄位，自定義送出個數。
- 控制中樞策略太過複雜，目前只考慮 `阿米婭`、`詩懷雅`、`凱爾希`、`彩虹小隊` 及其他心情 +0.05 的幹員，後續逐步優化。
- 部分異格幹員會在基建內產生衝突，請留意輔助畫面上是否有提示 “幹員衝突”，若有請手動再查看下基建換班情況（可能會有某個設施沒人）
### 公開招募辨識
- 自動公招和公招辨識是兩個獨立的功能！
- 自動公招支援使用 `加急許可`，全自動連續公招！請進入設定中選擇~
- 出 5、6 星都會有彈窗提示
- 自動公招時自動選取資料上傳 [企鵝物流資料統計](https://penguin-stats.cn/) 和 [素材獲取一圖流](https://yituliu.site/)
### 自動肉鴿功能
- 設定中的三個選項
- 盡可能往後打：用於刷蠟燭
- 刷源石錠投資，第一層商店後直接退出：刷源石錠最高效的模式，建議手動選擇 `古堡觀光` （簡單）模式
- 刷源石錠投資，投資後退出：兼顧刷蠟燭和刷源石錠投資的模式
- 肉鴿已支援自動辨識幹員及練度，並自動選擇較優幹員及技能
- 支援斷線重連、支援凌晨 4 點更新後繼續回去刷
- 如果軟體出現 bug 卡住了，會自動放棄當次探索並重試。但如果經常在某個地方卡住然後放棄、嚴重影響效率的，歡迎提個 issue 回饋一下~
### 自動抄作業
歡迎加作業分享 Q 群: 912322156
#### 抄作業
- 本功能需要在有 `開始行動` 的關卡入口畫面開始執行
- 若需要選擇助戰等，關閉 `自動編隊` 功能，並手動編隊後再開始即可
#### 寫作業
- exe 同目錄下有簡易的製作器，可以結合 [文件](3.3-戰鬥流程協議.md) 使用
- 地圖坐標獲取：填寫 `stage_name` 後直接開一局，會在目錄下生成 `map.png`, 可以用於參考。後面會想辦法直接在製作器上顯示坐標（畫餅）
- 支援演習模式，不用一直浪費理智測試的
- 若某個幹員名字一直辨識不對，可以打開日誌 `asst.log` 看一下到底被辨識成了什麼，並修改 `resource/tasks.json` - `CharsNameOcrReplace` 進行正規替換
- 推薦在作業描述裡填上你自己的名字（作者名）、參考的攻略影片 url, 其他想說的等等（
### 其他亂七八糟的說明
- 主畫面上要執行的任務，是可以拖動改變順序的。同樣設定中基建換班的順序，也是可以拖動改變的。
- 主畫面和設定中更改的配置一般都會自動保存，含有*號的選項除外。
- 所有點擊操作，都是點擊按鈕內隨機位置，並模擬卜瓦松分佈（按鈕偏中間位置點的概率大，越往旁邊點到的概率越小）。
- 底層算法純 C++ 開發，並設計了多重的快取技術，最大限度降低 CPU 和記憶體佔用。
- 軟體支援自動更新 ✿✿ヽ(°▽°)ノ✿ 推薦非槓精的同學使用測試版，一般來說更新快且 bug 少（什麼 MIUI (╯‵□′)╯︵┻━┻
- 如果新版本自動下載失敗，可手動下載後，直接把壓縮檔放到同目錄下，會自動更新的。

75
docs/zh-tw/1.2-常見問題.md Normal file
View File

@@ -0,0 +1,75 @@
# 常見問題
## 軟體一打開就閃退
### 可能性 0 : 下載的壓縮檔不完整
- 若您是第一次使用本軟體，請不要下載檔案名中有 `OTA` 字樣的壓縮檔，這個是用於增量更新的，無法單獨使用
- 若您是在某次自動更新後無法使用了，可能是自動更新功能存在一些 bug, 可以嘗試重新手動下載完整的檔案使用
### 可能性 1 : 執行庫問題
請嘗試安裝 [Visual C++ Redistributable](https://docs.microsoft.com/zh-CN/cpp/windows/latest-supported-vc-redist?view=msvc-160#visual-studio-2015-2017-2019-and-2022)、[.NET Framework 4.8](https://dotnet.microsoft.com/download/dotnet-framework/net48) 並重新啟動電腦後執行本軟體。
### 可能性 2 : CPU 指令集不支援
項目使用 `PaddleOCR` 對遊戲部分畫面進行辨識。 `PaddleOCR` 用到了較新發佈的 CPU 才支援的 `AVX` 指令集，而一些較老的 CPU 可能並不支援該指令集。
您可以嘗試下載 [NoAVX](../3rdparty/ppocr_noavx.zip) 版本的 `PaddleOCR`, 解壓後替換本軟體中同名的檔案。這是對於使用不支援 `AVX` 指令集的 CPU 的使用者的性能降低的替代方案，如非必要，請不要使用。
_具體可以下載 [CPU-Z](https://www.cpuid.com/softwares/cpu-z.html)，檢視“指令集”中有無 `AVX` 這一項來判斷_
### 可能性 3 : 其它執行庫問題
如果您是 Windows Server 或其他精簡版系統的使用者，可嘗試使用 [Microsoft C++ 生成工具](https://visualstudio.microsoft.com/zh-hans/visual-cpp-build-tools/) 進行完整的開發環境配置（僅需要安裝 .NET 及 C++ 開發環境）。
**請注意，此項操作將會耗費您10G左右的硬碟空間，請務必在排查完畢其他可能性後使用。 **
## 連接錯誤
提示 : 請參考 [模擬器支援](1.3-模擬器支援.md) 確定您的模擬器是受支援的。如果是藍疊模擬器，請注意在模擬器設定中打開 `Android 調試橋`
若您使用了遊戲加速器等軟體，請關閉軟體並 **重啟電腦** 再次嘗試
### 方式 1 : 確認 adb 及連接位址正確
- 確認 MAA `設定` - `連接設定` - `adb 路徑` 是否自動填寫了，若已填寫請忽略這步。若未填寫：
* 方法 1: 找到你的模擬器安裝路徑，大概率會有一個 `adb.exe`（不一定就叫這個名字，可能叫 `nox_adb.exe`, `HD-adb.exe`, `adb_server.exe`... 總之是名字帶 `adb` 的 exe），選擇它！
* 方法 2: 自行下載 [adb](https://dl.google.com/android/repository/platform-tools-latest-windows.zip) 並解壓，選擇裡面的 `adb.exe`
- 確認您的連接位址填寫正確。可在網上搜索您使用的模擬器 adb 位址是什麼，一般是類似 `127.0.0.1:5555` 這樣的格式（雷電模擬器除外）
### 方式 2 : 換模擬器
推薦 [藍疊國際版](https://www.bluestacks.com/download.html) Nougat 64 bit
_注意藍疊安裝完後，需要在模擬器設定中打開 `Android 調試橋`_
### 方式 3 : 重啟（電腦）試試
重啟能解決 90% 的問題（確信
## 辨識錯誤/任務開始後一直不動、沒有反應
提示 1. 自動戰鬥功能，是需要手動點到關卡頁有 `開始行動` 按鈕的地方再開始任務的。請確認是否是這個問題~
提示 2. 按照下面的次序依次進行，若問題解決則無需繼續向下
1. 請根據 [模擬器支援情況](1.3-模擬器支援.md) 確定您的模擬器是受支援的
2. 修改模擬器解析度設定，`320 dpi`
3. 修改模擬器解析度設定，橫向 `1280 * 720` 解析度
4. 換模擬器，推薦 [藍疊國際版](https://www.bluestacks.com/download.html) Nougat 64 bit（請注意藍疊需要在模擬器設定裡開啟 adb）
5. 若仍有問題，請提 issue
## 自定義連接
- 下載 [adb](https://dl.google.com/android/repository/platform-tools-latest-windows.zip) 並解壓
- 進入軟體 `設定` - `連接設定`，選擇 adb.exe 的檔案路徑、填寫 adb 位址（需要填寫 IP + 通訊埠，例如 `127.0.0.1:5555`），並選擇你的模擬器類型
## 下載速度慢，且鏡像站無法打開網頁
1. 請打開 [下載連結](../../README.md#下載連結) 中您所需要版本的連結（非鏡像站）
2. 找到您所需要下載的檔案連結
3. 右鍵該連結，選擇 `複製連結位址`
4. 將連結位址貼到瀏覽器位址欄
5. 將連結位址中的 `github.com` 替換為 `download.fastgit.org`
6. 確認以開始下載

145
docs/zh-tw/1.3-模擬器支援.md Normal file
View File

@@ -0,0 +1,145 @@
## 模擬器支援
### ✅ [藍疊模擬器](https://www.bluestacks.cn/)
完美支援。需要在模擬器 `設定` - `引擎設定` 中打開 `允許ADB連接`
### ✅ [藍疊模擬器國際版](https://www.bluestacks.com/tw/index.html)（推薦使用👍）
完美支援。需要在模擬器 `設定` - `進階` 中打開 `Android調試橋`
### ✅ [藍疊模擬器國際版 Hyper-V 版本](https://support.bluestacks.com/hc/zh-tw/articles/4415238471053-BlueStacks-5-%E6%94%AF%E6%8F%B4-Hyper-V-%E7%9A%84-Windows-10-%E5%92%8C-11-%E4%B8%8A%E7%9A%84%E9%9B%BB%E8%85%A6%E8%A6%8F%E6%A0%BC%E9%9C%80%E6%B1%82)
支援
- 在模擬器 `設定` - `進階` 中打開 `Android調試橋`
- 由於藍疊 Hyper-V 的埠號在不斷變動，所以留了個專用的小後門：
1. 在藍疊模擬器的資料目錄下找到 `bluestacks.conf` 這個檔案（預設路徑為 `C:\ProgramData\BlueStacks_nxt\bluestacks.conf`）
2. 如果是第一次使用，請開啟一次 MAA，會在同目錄下生成 `gui.json`
3. **先關閉** MAA，**然後** 打開 `gui.json`，新增一個欄位 `Bluestacks.Config.Path`，填入 `bluestacks.conf` 的完整路徑（注意斜線要用跳脫字元 `\\`）
示例：（以 `C:\ProgramData\BlueStacks_nxt\bluestacks.conf` 為例）
```jsonc
"Bluestacks.Config.Path":"C:\\ProgramData\\BlueStacks_nxt\\bluestacks.conf",
```
4. 開啟 MAA，LinkStart！
- 如果你還需要多開（不使用多開請忽略這步），可以再修改 MAA 檢測配置檔案的保留字。
參照上述步驟，添加 `Bluestacks.Config.Keyword` 欄位
示例：
```jsonc
"Bluestacks.Config.Keyword":"bst.instance.Nougat64.status.adb_port",
```
### ✅ [夜神模擬器](https://www.yeshen.com/)
完美支援
### ✅ [夜神模擬器 安卓 9](https://www.yeshen.com/)
完美支援
### ⚠️ [MuMu 模擬器](https://mumu.163.com/)
支援。但
- 需要使用管理員權限打開 MAA 才能自動獲取 adb 路徑和位址（因為 MuMu 本身是管理員啟動的）
- 如果不希望管理員啟動，可以在 MAA 設定中自行填寫 adb 路徑和位址
- 可能會卡在主畫面無法辨識，過一會提示任務出錯：和 MuMu 的彩現方式有關，暫時不知道根本原因，推薦換模擬器（
### 🚫 MuMu 手游助手（星雲引擎）
不支援。沒開放 adb 埠
### 🚫 MuMu 模擬器 安卓 9
不支援。 adb 截圖出來是黑的，無法解決
### 🚫 雷電模擬器
勉強支援，但非常不推薦使用。雷電存在小概率畫面顛倒及黑屏的問題，會造成各種奇怪的問題。
例如準備點擊左上角返回鍵的一瞬間畫面顛倒 180°，導致點到了右下角的碎石確認按鈕，造成誤碎石（這個情況有用戶真實遇到過）
### ⚠️ [逍遙模擬器](https://www.xyaz.cn/)
支援。但可能有莫名其妙的辨識錯誤問題
### 🚫 騰訊手游助手
不支援。沒開放 adb 埠
### ⚠️ [Win11 WSA](https://docs.microsoft.com/zh-cn/windows/android/wsa/)
勉強支援。
- 需要使用 [自定義連接](#⚙️-自定義連接) 的方式來連接.
- WSA 2204 或更高版本（版本號在子系統設定的 `關於` 頁面中），連接配置選擇 `通用配置`
- WSA 2203 或更老版本（版本號在子系統設定頁面的上方），連接配置選擇 `WSA 舊版本`
- 由於本軟體僅對 720p 以上 `16:9` 解析度支援較好，所以請手動拖動視窗大小，盡量貼近 16:9 比例（如果你的顯示器是 16:9 的，可以直接按 `F11` 全屏）
- 輔助執行過程中請盡量保證明日方舟在前台且無其他安卓應用同時在前台執行，否則可能導致遊戲暫停執行或輔助辨識錯誤。
- WSA 的截圖經常莫名其妙截出來一個白色畫面，導致辨識異常，還是不推薦使用。
### ✅ [AVD](https://developer.android.com/studio/run/managing-avds)
支援。
### ⚙️ 自定義連接
1. 下載 [adb](https://dl.google.com/android/repository/platform-tools-latest-windows.zip) 並解壓
2. 進入軟體 `設定` - `連接設定`，填寫 adb 路徑及位址（需要填寫 IP + 通訊埠，例如 `127.0.0.1:5555` ）
### ⚙️ 手機、平板等非 `16:9` 解析度裝置
由於 MAA 僅對 `16:9` 解析度支援較好，所以需要手動強制修改一下解析度
1. 手機打開 USB 調試，連接線連接電腦主機；或直接使用無線 adb 調試
2. 執行 `命令提示字元（CMD）`，查看裝置位址並連接
- 若使用 USB 連接線連接手機：輸入以下命令查看裝置 id
```bash
adb devices # 查看當前已連接裝置情況
```
成功執行後會顯示如下資訊
```bash
C:\Users\username>adb devices
List of devices attached
VFNDU1682100xxxx device # device 之前的資訊即為裝置 id
```
- 若使用無線 adb 連接手機：可進入手機 `設定 -> WLAN -> 查看` 找到對應的 IP 位址；埠號一般為 5555 或 5037
```bash
adb connect <IP 位址 + 埠號> # 例如 192.168.0.10:5555
```
- 若提示 `"adb" 不是內部命令或外部命令`，則可能是沒有為 adb 配置環境變數。此時需輸入 adb 的完整位址方可執行命令，例如
```bash
D:\adb解壓資料夾\adb.exe devices # 此處可以直接把 adb.exe 拖到 CMD 窗口裡，再輸入 [空格] devices
```
如有長期執行 adb 命令的需求，為 adb 配置環境變數即可免於輸入完整位址，具體方法可自行檢索
3. 進入裝置的命令列執行操作
```bash
adb -s <裝置 id 或 IP + 埠號> shell # 進入該裝置的命令列
wm size # 查看當前裝置的解析度
wm size 720x1280 # 調整解析度到 720p
```
4. 在 MAA 軟體設定中填寫好 adb 路徑以及手機位址（裝置 id 或 IP + 通訊埠）
5. 在遊戲內部的設定畫面將 `異形屏適配` 一項調整到 0（關閉狀態）。
如果不設定該項，之後使用 adb 調整解析度可能會出現手機介面 UI 和按鍵回應的位置錯開（？）的情況
6. 使用 MAA (≧∇≦)ﾉ
7. 任務結束，退出 MAA 之前，恢復手機原本的解析度
```bash
wm size reset # 恢復原本的解析度
```

70
docs/zh-tw/2.1-Linux編譯教程.md Normal file
View File

@@ -0,0 +1,70 @@
# Linux 編譯教程
**本教程需要讀者有一定的 Linux 環境配置能力及編程基礎！ **
雖然沒想明白為什麼 Linux 下需要用助手掛模擬器，嘛總之大家有這個需求還是弄一下_(:з」∠)_
作者是 Linux 小白，所以雖說是教程，也只是分享一下自己的踩坑經歷，如果遇到其他問題歡迎提出 ISSUE 一起討論下 orz
## 下載編譯第三方庫
### Opencv
請自行檢索教程安裝，沒什麼特別的，作者當前成功驗證過的版本為`4.5.3`版本。其他版本應該也可以，但仍然推薦使用`4.5.3`版本，與項目保持一致，避免一些不必要的問題。僅`Opencv`本體即可，不需要額外安裝`opencv_contrib`。
### PaddleOCR
1. 使用我魔改了介面的版本：<https://github.com/MaaAssistantArknights/PaddleOCR>
2. 參考 [這個教程](https://github.com/MaaAssistantArknights/PaddleOCR/blob/release/2.5/deploy/cpp_infer/readme_ch.md)
3. 額外依賴的 `paddle_inference` 直接 [下載](https://paddleinference.paddlepaddle.org.cn/master/user_guides/download_lib.html) 即可。其中 `avx` 和 `mkl` 兩者都可以提高計算效率，建議選擇。但如果 CPU 不支援，則只能選擇 `noavx` 和 `openblas` 的相容性版本（一般稍微新一點的 CPU 都支援兩者了，AMD 的也沒關係）。 `cuda` 和 `cudnn` 是 GPU 加速庫，在 `PaddleOCR` 上可能比較麻煩，我沒折騰過，有興趣可以嘗試下
4. 若 `cmake` 找不到 `Opencv` ，可嘗試修改 [Opencv 的查找路徑](https://github.com/MaaAssistantArknights/PaddleOCR/blob/release/2.5/deploy/cpp_infer/CMakeLists.txt#L49)
5. 若您使用**非** `MKL` 版本，需要關閉 [MKL 巨集定義](https://github.com/MaaAssistantArknights/PaddleOCR/blob/release/2.5/deploy/cpp_infer/src/args.cpp#L24) （改為 `false`）
編譯選項參考
```bash
cmake ../ -DPADDLE_LIB=/your_path/paddle_inference/ -DOpenCV_DIR=/your_path_to_opencv/ -DWITH_STATIC_LIB=OFF -DBUILD_SHARED=ON
# 若裝置不支援 MKL, 可再額外添加 -DWITH_MKL=OFF 選項，並下載對應的 PaddlePaddle 預測庫版本
```
### zlib
Ubuntu 下:
```bash
sudo apt update && sudo apt install zlib1g-dev
sudo ldconfig
```
其他發行版若源中沒有 zlib, 也可嘗試透過 [原始碼](https://github.com/madler/zlib) 編譯
## MeoAssistant
1. 直接拷貝上面編譯的第三方庫到 `3rdparty/lib` 或者 手動修改 `CMakeLists.txt` 指定第三方庫路徑
2. `3rdparty/include/opencv` 中的標頭檔是 `4.5.3` 版本的，若是使用其他版本，請注意標頭檔衝突問題（直接將你的 `opencv` 標頭檔覆蓋過去就好）
3. 安裝 `adb`
4. 複製資源檔案到 `libMeoAssitant.so` 同一目錄下
```sh
cd tools
sh ./update_resource.sh <YourBuildDir>
```
5. 透過 [Python 介面](../src/Python/asst.py) 或 [C 介面](../include/AsstCaller.h) 進行呼叫，需要自行編寫少量的程式碼
6. `cmake` 可透過添加 `-DBUILD_TEST=ON` 選項來編譯一個測試小 demo
## 集成文件
[~~或許算不上文件~~](https://github.com/MistEO/MeoAssistantArknights/wiki)
### Python
可參考 [Python demo](../src/Python/sample.py) 中 `__main__` 的實現
### C
可參考 [TestCaller](../tools/TestCaller/main.cpp) 中的實現
### C sharp
可參考 [MeoAsstGui](../src/MeoAsstGui/Helper/AsstProxy.cs) 中的實現

63
docs/zh-tw/2.2-開發相關.md Normal file
View File

@@ -0,0 +1,63 @@
# 開發相關
## Github Pull Request 流程簡述
1. 如果很久以前 fork 過，先在自己儲存庫的 `Settings` 裡，翻到最下面，刪除
2. 打開 [MAA 主儲存庫](https://github.com/MaaAssistantArknights/MaaAssistantArknights)，點擊 `Fork`，繼續點擊 `Create fork`
3. clone 儲存庫（你自己賬戶下） dev 分支到本地
```bash
git clone <你的儲存庫 git 連結> -b dev
```
4. 配置編程環境
1. 下載並安裝 `Visual Studio 2022 community`, 安裝的時候需要選中 `基於c++的桌面開發` 和 `.NET桌面開發`
5. 雙擊打開 `MeoAssistantArknights.sln` 檔案。 Visual Studio 會自動加載整個項目。
6. 測試一下是否成功搭建編程環境，選擇參數 `Release`, `x64`, 右鍵 `MeoAsstGui` 設為啟動項目；點擊啟動，選擇繼續調試。如果成功打開了 GUI，就說明成功搭建了環境。如果求穩，可以繼續連接模擬器跑一下 MAA
7. 到這裡，你就可以愉快地 ~~瞎 ㄐㄅ 改~~ 發電了
8. 開發過程中，每一定數量，記得提交一個 commit, 別忘了寫上 message
9. 完成開發後，推送本地分支到遠端（自己）
```bash
git push origin dev
```
10. 打開 [MAA 主儲存庫](https://github.com/MaaAssistantArknights/MaaAssistantArknights)。提交一個 pull request，等待管理員通過。別忘了你是在 dev 分支上修改，別提交到 master 分支去了
11. 當 MAA 原儲存庫出現更改（別人做的），你需要把這些更改同步到你 fork 的儲存庫
1. 關聯 MAA 原儲存庫
```bash
git remote add upstream https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
```
2. 從 MAA 原儲存庫拉取更新
```bash
git fetch upstream
```
3. 合併修改
```bash
git merge
```
4. 重複上述 7, 8, 9, 10 中的操作
注：在打開 VS2022 之後，和 git 有關的操作可以不用命令列工具，直接使用 vs 自帶的“Git 更改”即可
## 在 Visual Studio 中啟用 clang-format
1. 下載 [clang-format.zip](https://github.com/MaaAssistantArknights/MaaAssistantArknights/files/9482197/clang-format.zip) 或者編譯 [zzyyyl/llvm-project](https://github.com/zzyyyl/llvm-project/tree/fix/clang-format)，得到一個 `clang-format.exe`
2. 在 `工具-設定` 中檢索 `clang-format`
3. 點擊 `啟用 ClangFormat 支援`，然後選擇下面的 `使用自定義 clang-format.exe 檔案`，選擇第一步得到的 `clang-format.exe`
![Visual Studio 設置 clang-format](https://user-images.githubusercontent.com/74587068/188262146-bf36f10a-db94-4a3c-9802-88b703342fb6.png)
然後你的 Visual Studio 就能愉快地使用支援 c++20 語法的 clang-format 啦！
你也可以使用 `tools\ClangFormatter\clang-formatter.py` 來直接執行你的 clang-format 來進行格式化，只需要在項目根目錄下執行：
- `python tools\ClangFormatter\clang-formatter.py --clang-format=PATH\TO\YOUR\clang-format.exe --input=src\MeoAssistant`

69
docs/zh-tw/2.3-IssueBot使用方法.md Normal file
View File

@@ -0,0 +1,69 @@
# Issue bot 使用方法
Issue bot 使用的 action 為 [issue-checker](https://github.com/zzyyyl/issue-checker)，設定檔為 [issue-checker.yml](.github/issue-checker.yml)。
**注意：拉取請求被增加 `ambiguous` 標籤是因為沒有按照 commitizen 規範提交。 **
## 功能
### 自動觸發
- 給上傳檔案失敗的議題評論，告訴使用者檔案上傳失敗。
- 給 議題 和 拉取請求 增加標籤，包括 `module` 系列，`Client` 系列，`ambiguous`，`translation required` 等。
Issue bot 會根據保留字自動增加分類標籤，也可以透過手動添加的方式增加或刪除標籤。
具體保留字可以參考[設定檔](.github/issue-checker.yml)。
- 給可見性設置為 public 的 MAA 成員增加 `MAA Team` 標籤。
#### 拉取請求（Pull Request）
Issue bot 會對拉取請求標題的格式進行簡單審查。它會增加 `ambiguous` 標籤，除非拉取請求標題以下列任一單字開頭：
- `build` `chore` `ci` `doc` `docs` `feat` `fix` `perf` `refactor` `rfc` `style` `test`
- `Merge` `merge` `Revert` `revert`
### 手動觸發
多使用保留字詳細描述問題來自動觸發分類標籤，少使用下列指令。但**當你知道自己的行為會導致 Issue bot 誤解時除外**。
盡量不要直接增加或刪除分類標籤，因為手動增加或刪除的分類標籤可能在修改後會被恢復原樣。
#### 議題（Issue）及其評論
在 修改/新增 一個議題時：
- `Add {LABEL_NAME}` 可以增加一個標籤。
- `Remove {LABEL_NAME}` 可以刪除一個標籤。
- `Remove labels` 可以刪除所有標籤。
在 修改/新增 一個議題評論時：
- `Add ambiguous` 可以保證不刪除 `ambiguous` 標籤，但沒有 `ambiguous` 標籤時不會添加。
- `Remove {LABEL_NAME}` 可以保證不增加標籤。 <sup>1</sup>
- `Remove labels` 可以保證不增加任何標籤。 <sup>1</sup>
- 以下幾種方法可以為議題增加 `fixed` 標籤：<sup>2</sup>
- `https://github.com/MaaAssistantArknights/MaaAssistantArknights/commit/{COMMIT_HASH} fixed`
- `fixed by https://github.com/MaaAssistantArknights/MaaAssistantArknights/commit/{COMMIT_HASH}`
- `{VERSION} fixed`
- `fixed by {VERSION}`
- `Duplicate of #{ISSUE_NUMBER}` 可以為當前議題增加 `duplicate` 標籤。
- **當你知道自己的議題評論會導致 Issue bot 誤解時，盡量添加一些 remove 操作。 **
_Note<sup>1</sup>: `Remove ambiguous` 和 `Remove labels` 會刪除 `ambiguous` 標籤。 _
_Note<sup>2</sup>: 這裡的 COMMIT_HASH 需要完整的 40 位。 _
#### 拉取請求（Pull Request）及其評論
與[議題（Issue）及其評論](#議題issue及其評論)基本相同。另外：
- `Release {VERSION}` 會增加 `release` 標籤。
- **不會**自動添加 `fixed`, `duplicate` 標籤。
#### 推送（Push）
對於一個推送中的任意提交：
- 在 commit message 中包含以下幾種任意一個，可以為對應議題加上 `fixed` 標籤：
- `fix #{ISSUE_NUMBER}`
- `close #{ISSUE_NUMBER}`
- `fix https://github.com/MaaAssistantArknights/MaaAssistantArknights/issues/{ISSUE_NUMBER}`
- `close https://github.com/MaaAssistantArknights/MaaAssistantArknights/issues/{ISSUE_NUMBER}`

240
docs/zh-tw/3.1-集成文件.md Normal file
View File

@@ -0,0 +1,240 @@
# 集成檔案
## 介面介紹
### `AsstAppendTask`
#### 介面原型
```c++
TaskId ASSTAPI AsstAppendTask(AsstHandle handle, const char* type, const char* params);
```
#### 介面说明
添加任務
#### 返回值
- `TaskId`
若添加成功，返回該任務 ID, 可用於後續設置任務參數；
若添加失敗，返回 0
#### 參數說明
- `AsstHandle handle`
實例控制代碼
- `const char* type`
任務類型
- `const char* params`
任務參數，json string
##### 任務類型一覽
- `StartUp`
開始喚醒
```jsonc
// 對應的任務參數
{
"enable": bool, // 是否啟用本任務，可選，預設為 true
"client_type": string, // 用戶端版本，可選，預設為空
// 選項："Official" | "Bilibili"
"start_game_enabled": bool // 是否自動啟動用戶端，可選，預設不啟動
}
```
- `Fight`
刷理智
```jsonc
// 對應的任務參數
{
"enable": bool, // 是否啟用本任務，可選，預設為 true
"stage": string, // 關卡名，可選，預設為空，辨識當前/上次的關卡。不支援執行時設置
// 支援全部主線關卡，如 "1-7"、"S3-2"等
// 另支援少部分資源關卡，如 "CE-6" 等（請參考 C# 集成示例）
"medicine": int, // 最大使用理智藥數量，可選，預設 0
"stone": int, // 最大吃石頭數量，可選，預設 0
"times": int, // 指定次數，可選，預設無窮大
"drops": { // 指定掉落數量，可選，預設不指定
"30011": int, // key - item_id, value 數量. key 可參考 resource/item_index.json 檔案
"30062": int // 是或的關係
},
/* 以上全部是或的關係，即任一達到即停止任務 */
"report_to_penguin": bool, // 是否匯報企鵝資料，可選，預設 false
"penguin_id": string, // 企鵝資料匯報 id, 可選，預設為空。僅在 report_to_penguin 為 true 時有效
"server": string, // 伺服器，可選，預設 "CN", 會影響掉落辨識及上傳
// 選項："CN" | "US" | "JP" | "KR"
"client_type": string, // 用戶端版本，可選，預設為空。用於遊戲崩潰時重啟並連回去繼續刷，若為空則不啟用該功能
// 選項："Official" | "Bilibili"
"DrGrandet": bool, // 節省理智碎石模式，可選，預設 false，僅在可能產生碎石效果時生效。
// 在碎石確認畫面等待，直到當前的 1 點理智恢復完成後再立刻碎石
}
```
- `Recruit`
公開招募
```jsonc
// 對應的任務參數
{
"enable": bool, // 是否啟用本任務，可選，預設為 true
"refresh": bool, // 是否刷新三星 Tags, 可選，預設 false
"select": [ // 會去點擊標籤的 Tag 等級，必選
int,
...
],
"confirm": [ // 會去點擊確認的 Tag 等級，必選。若僅公招計算，可設置為空陣列
int,
...
],
"times": int, // 招募多少次，可選，預設 0。若僅公招計算，可設置為 0
"set_time": bool, // 是否設置招募時限。僅在 times 為 0 時生效，可選，預設 true
"expedite": bool, // 是否使用加急許可，可選，預設 false
"expedite_times": int, // 加急次數，僅在 expedite 為 true 時有效。
// 可選，預設無限使用（直到 times 達到上限）
"skip_robot": bool, // 是否在辨識到小車詞條時跳過，可選，預設跳過
"recruitment_time": { // Tag 等級（大於等於 3）和對應的希望招募時限，單位為分鐘，預設值都為 540（即 09:00:00）
"3": int,
"4": int,
...
},
"report_to_penguin": bool, // 是否匯報企鵝資料，可選，預設 false
"penguin_id": string, // 企鵝資料匯報 id, 可選，預設為空。僅在 report_to_penguin 為 true 時有效
"report_to_yituliu": bool, // 是否匯報一圖流資料，可選，預設 false
"yituliu_id": string, // 一圖流匯報 id, 可選，預設為空。僅在 report_to_yituliu 為 true 時有效
}
```
- `Infrast`
基建換班
```jsonc
{
"enable": bool, // 是否啟用本任務，可選，預設為 true
"mode": int, // 換班工作模式，保留介面，暫時可以不傳。不支援執行時設置
"facility": [ // 要換班的設施（有序），必選。不支援執行時設置
string, // 設施名，"Mfg" | "Trade" | "Power" | "Control" | "Reception" | "Office" | "Dorm"
...
],
"drones": string, // 無人機用途，可選項，預設 _NotUse
// "_NotUse"、"Money"、"SyntheticJade"、"CombatRecord"、"PureGold"、"OriginStone"、"Chip"
"threshold": float, // 宿舍進駐心情閾值，可選，取值範圍 [0, 1.0]，預設 0.3
"replenish": bool // 貿易站“源石碎片”是否自動補貨，可選，預設 false
}
```
- `Visit`
訪問好友
```jsonc
// 對應的任務參數
{
"enable": bool // 是否啟用本任務，可選，預設為 true
}
```
- `Mall`
領取信用及商店購物。
會先有序的按 `buy_first` 購買一遍，再從左到右並避開 `blacklist` 購買第二遍
```jsonc
// 對應的任務參數
{
"enable": bool, // 是否啟用本任務，可選，預設為 true
"shopping": bool, // 是否購物，可選，預設 false。不支援執行時設置
"buy_first": [ // 優先購買列表，可選。不支援執行時設置
string, // 商品名，如 "招聘許可"、"龍門幣" 等
...
],
"blacklist": [ // 黑名單列表，可選。不支援執行時設置
string, // 商品名，如 "加急許可"、"家具零件" 等
...
]
}
```
- `Award`
領取日常獎勵
```jsonc
// 對應的任務參數
{
"enable": bool // 是否啟用本任務，可選，預設為 true
}
```
- `Roguelike`
無限刷肉鴿
```jsonc
{
"enable": bool, // 是否啟用本任務，可選，預設為 true
"mode": int, // 模式，可選項。預設 0
// 0 - 刷蠟燭，盡可能穩定地打更多層數
// 1 - 刷源石錠，第一層投資完就退出
// 2 - 【即將棄用】兩者兼顧，投資過後再退出，沒有投資就繼續往後打
// 3 - 【開發中】嘗試通關，盡可能打得遠
"starts_count": int, // 開始探索 次數，可選，預設 INT_MAX。達到後自動停止任務
"investments_count": int,
// 投資源石錠 次數，可選，預設 INT_MAX。達到後自動停止任務
"stop_when_investment_full": bool,
// 投資滿了自動停止任務，可選，預設 false
"squad": string, // 開局分隊，可選，例如 "突擊戰術分隊" 等，預設 "指揮分隊"
"roles": string, // 開局職業組，可選，例如 "先手必勝" 等，預設 "取長補短"
"core_char": string // 開局幹員名，可選，僅支援單個幹員中！文！名！ 。預設辨識練度自動選擇
}
```
- `Copilot`
自動抄作業
```jsonc
{
"enable": bool, // 是否啟用本任務，可選，預設為 true
"stage_name": string, // 關卡名，需要與作業 JSON 中的 stage_name 欄位相同。不支援執行時設置
"filename": string, // 作業 JSON 的檔案路徑，絕對、相對路徑均可。不支援執行時設置
"formation": bool // 是否進行 “快捷編隊”，可選，預設否。不支援執行時設置
}
```
作業 JSON請參考 [戰鬥流程協議](3.3-戰鬥流程協議.md)
- `Depot`
倉庫辨識
```jsonc
// 對應的任務參數
{
"enable": bool // 是否啟用本任務，可選，預設為 true
}
```
### `AsstSetTaskParams`
#### 介面原型
```c++
bool ASSTAPI AsstSetTaskParams(AsstHandle handle, TaskId id, const char* params);
```
#### 介面說明
設置任務參數
#### 返回值
- `bool`
返回是否設置成功
#### 參數說明
- `AsstHandle handle`
實例控制代碼
- `TaskId task`
任務 ID, `AsstAppendTask` 介面的返回值
- `const char* params`
任務參數，json string，與 `AsstAppendTask` 介面相同。
未標註“不支援執行時設置”的欄位都支援實時修改；否則若當前任務正在運行，會忽略對應的欄位

510
docs/zh-tw/3.2-回呼訊息協定.md Normal file
View File

@@ -0,0 +1,510 @@
## 回呼訊息協定
### 回呼函式原型
```c++
typedef void(ASST_CALL* AsstCallback)(int msg, const char* details, void* custom_arg);
```
### 參數總覽
- `int msg`
訊息類型
```c++
enum class AsstMsg
{
/* Global Info */
InternalError = 0, // 內部錯誤
InitFailed, // 初始化失敗
ConnectionInfo, // 連接相關資訊
AllTasksCompleted, // 全部任務完成
/* TaskChain Info */
TaskChainError = 10000, // 任務鏈執行/辨識錯誤
TaskChainStart, // 任務鏈開始
TaskChainCompleted, // 任務鏈完成
TaskChainExtraInfo, // 任務鏈額外資訊
/* SubTask Info */
SubTaskError = 20000, // 原子任務執行/辨識錯誤
SubTaskStart, // 原子任務開始
SubTaskCompleted, // 原子任務完成
SubTaskExtraInfo // 原子任務額外資訊
};
```
- `const char* details`
訊息詳情，json 字串，詳見 [欄位解釋](#欄位解釋)
- `void* custom_arg`
呼叫方自定義參數，會原樣傳出 `AsstCreateEx` 介面中的 `custom_arg` 參數，C 系語言可利用該參數傳出 `this` 指標
### 欄位解釋
#### InternalError
Todo
#### InitFailed
```jsonc
{
"what": string, // 錯誤類型
"why": string, // 錯誤原因
"details": object // 錯誤詳情
}
```
### ConnectionInfo
```jsonc
{
"what": string, // 資訊類型
"why": string, // 資訊原因
"uuid": string, // 設備唯一碼（連接失敗時為空）
"details": {
"adb": string, // AsstConnect 介面 adb_path 參數
"address": string, // AsstConnect 介面 address 參數
"config": string // AsstConnect 介面 config 參數
}
}
```
#### 常見 `What` 欄位
- `ConnectFailed`
連接失敗
- `Connected`
已連接，注意此時的 `uuid` 欄位值為空（下一步才是獲取）
- `UuidGot`
已獲取到設備唯一碼
- `UnsupportedResolution`
解析度不被支援
- `ResolutionError`
解析度獲取錯誤
- `Reconnecting`
連接斷開（adb / 模擬器 炸了），正在重連
- `Reconnected`
連接斷開（adb / 模擬器 炸了），重連成功
- `Disconnect`
連接斷開（adb / 模擬器 炸了），並重試失敗
- `ScreencapFailed`
截圖失敗（adb / 模擬器 炸了），並重試失敗
#### AllTasksCompleted
```jsonc
{
"taskchain": string, // 最後的任務鏈
"uuid": string, // 設備唯一碼
"finished_tasks": [ // 已經執行過的任務 id
int,
...
]
}
```
##### 常見 `taskchain` 欄位
- `StartUp`
開始喚醒
- `Fight`
刷理智
- `Mall`
信用點及購物
- `Recruit`
自動公招
- `RecruitCalc`
公招辨識
- `Infrast`
基建換班
- `Roguelike`
無限刷肉鴿
- `Debug`
調試
#### TaskChain 相關訊息
```jsonc
{
"taskchain": string, // 當前的任務鏈
"taskid": int, // 當前任務 TaskId
"uuid": string // 設備唯一碼
}
```
#### TaskChainExtraInfo
Todo
#### SubTask 相關訊息
```jsonc
{
"subtask": string, // 子任務名
"class": string, // 子任務符號名
"taskchain": string, // 當前任務鏈
"taskid": int, // 當前任務 TaskId
"details": object, // 詳情
"uuid": string // 設備唯一碼
}
```
##### 常見 `subtask` 欄位
- `ProcessTask`
```jsonc
// 對應的 details 欄位舉例
{
"task": "StartButton2", // 任務名
"action": 512,
"exec_times": 1, // 已執行次數
"max_times": 999, // 最大執行次數
"algorithm": 0
}
```
- Todo 其他
###### 常見 `task` 欄位
- `StartButton2`
開始戰鬥
- `MedicineConfirm`
使用理智藥
- `StoneConfirm`
碎石
- `RecruitRefreshConfirm`
公招刷新標籤
- `RecruitConfirm`
公招確認招募
- `RecruitNowConfirm`
公招使用加急許可
- `ReportToPenguinStats`
匯報到企鵝資料統計
- `ReportToYituliu`
匯報到一圖流巨量資料
- `InfrastDormDoubleConfirmButton`
基建宿舍的二次確認按鈕，僅當幹員衝突時才會有，請提示使用者
- `Roguelike1Start`
肉鴿開始探索
- `Roguelike1StageTraderInvestConfirm`
肉鴿投資了源石錠
- `Roguelike1StageTraderInvestSystemFull`
肉鴿投資達到了遊戲上限
- `Roguelike1ExitThenAbandon`
肉鴿放棄了本次探索
- `Roguelike1MissionCompletedFlag`
肉鴿戰鬥完成
- `Roguelike1MissionFailedFlag`
肉鴿戰鬥失敗
- `Roguelike1StageSafeHouseEnter`
肉鴿關卡：詭異行商
- `Roguelike1StageSafeHouseEnter`
肉鴿關卡：安全的角落
- `Roguelike1StageEncounterEnter`
肉鴿關卡：不期而遇/古堡饋贈
- `Roguelike1StageCambatDpsEnter`
肉鴿關卡：普通作戰
- `Roguelike1StageEmergencyDps`
肉鴿關卡：緊急作戰
- `Roguelike1StageDreadfulFoe`
肉鴿關卡：險路惡敵
- `StartGameTask`
打開用戶端失敗（設定檔與傳入client_type不匹配）
- Todo 其他
#### SubTaskExtraInfo
```jsonc
{
"taskchain": string, // 當前任務鏈
"class": string, // 子任務類型
"what": string, // 資訊類型
"details": object, // 資訊詳情
"uuid": string, // 設備唯一碼
}
```
##### 常見 `what` 及 `details` 欄位
- `StageDrops`
關卡材料掉落資訊
```jsonc
// 對應的 details 欄位舉例
{
"drops": [ // 本次辨識到的掉落材料
{
"itemId": "3301",
"quantity": 2,
"itemName": "技巧概要·卷1"
},
{
"itemId": "3302",
"quantity": 1,
"itemName": "技巧概要·卷2"
},
{
"itemId": "3303",
"quantity": 2,
"itemName": "技巧概要·卷3"
}
],
"stage": { // 關卡資訊
"stageCode": "CA-5",
"stageId": "wk_fly_5"
},
"stars": 3, // 行動結束星級
"stats": [ // 本次執行期間總的材料掉落
{
"itemId": "3301",
"itemName": "技巧概要·卷1",
"quantity": 4
},
{
"itemId": "3302",
"itemName": "技巧概要·卷2",
"quantity": 3
},
{
"itemId": "3303",
"itemName": "技巧概要·卷3",
"quantity": 4
}
]
}
```
- `RecruitTagsDetected`
公招辨識到了 Tags
```jsonc
// 對應的 details 欄位舉例
{
"tags": [
"費用回复",
"防護",
"先鋒幹員",
"輔助幹員",
"近戰位"
]
}
```
- `RecruitSpecialTag`
公招辨識到了特殊 Tag
```jsonc
// 對應的 details 欄位舉例
{
"tag": "高級資深幹員"
}
```
- `RecruitResult`
公招辨識結果
```jsonc
// 對應的 details 欄位舉例
{
"tags": [ // 所有辨識到的 tags，目前來說一定是 5 個
"削弱",
"減速",
"術師幹員",
"輔助幹員",
"近戰位"
],
"level": 4, // 總的星級
"result": [
{
"tags": [
"削弱"
],
"level": 4, // 這組 tags 的星級
"opers": [
{
"name": "初雪",
"level": 5 // 幹員星級
},
{
"name": "隕星",
"level": 5
},
{
"name": "槐琥",
"level": 5
},
{
"name": "夜煙",
"level": 4
},
{
"name": "流星",
"level": 4
}
]
},
{
"tags": [
"減速",
"術師幹員"
],
"level": 4,
"opers": [
{
"name": "夜魔",
"level": 5
},
{
"name": "格雷伊",
"level": 4
}
]
},
{
"tags": [
"削弱",
"術師幹員"
],
"level": 4,
"opers": [
{
"name": "夜煙",
"level": 4
}
]
}
]
}
```
- `RecruitTagsRefreshed`
公招刷新了 Tags
```jsonc
// 對應的 details 欄位舉例
{
"count": 1, // 當前槽位已刷新次數
"refresh_limit": 3 // 當前槽位刷新次數上限
}
```
- `RecruitTagsSelected`
公招選擇了 Tags
```jsonc
// 對應的 details 欄位舉例
{
"tags": [
"減速",
"術師幹員"
]
}
```
- `RecruitSlotCompleted`
當前公招槽位任務完成
- `RecruitError`
公招辨識錯誤
- `EnterFacility`
基建進入了設施
```jsonc
// 對應的 details 欄位舉例
{
"facility": "Mfg", // 設施名
"index": 0 // 設施序號
}
```
- `NotEnoughStaff`
基建可用幹員不足
```jsonc
// 對應的 details 欄位舉例
{
"facility": "Mfg", // 設施名
"index": 0 // 設施序號
}
```
- `ProductOfFacility`
基建產物
```jsonc
// 對應的 details 欄位舉例
{
"product": "Money", // 產物名
"facility": "Mfg", // 設施名
"index": 0 // 設施序號
}
```
- `StageInfo`
自動作戰關卡資訊
```jsonc
// 對應的 details 欄位舉例
{
"name": string // 關卡名
}
```
- `StageInfoError`
自動作戰關卡辨識錯誤
- `PenguinId`
企鵝物流 ID
```jsonc
// 對應的 details 欄位舉例
{
"id": string
}
```
- `DepotInfo`
倉庫辨識結果
```jsonc
// 對應的 details 欄位舉例
"done": bool, // 是否已經辨識完了，為 false 表示仍在辨識中（過程中的資料）
"arkplanner": { // https://penguin-stats.cn/planner
"object": {
"items": [
{
"id": "2004",
"have": 4,
"name": "高級作戰記錄"
},
{
"id": "mod_unlock_token",
"have": 25,
"name": "模組資料塊"
},
{
"id": "2003",
"have": 20,
"name": "中級作戰記錄"
}
],
"@type": "@penguin-statistics/depot"
},
"data": "{\"@type\":\"@penguin-statistics/depot\",\"items\":[{\"id\":\"2004\",\"have\":4,\"name\":\"高級作戰記錄\"},{\"id\":\"mod_unlock_token\",\"have\":25,\"name\":\"模組資料塊\"},{\"id\":\"2003\",\"have\":20,\"name\":\"中級作戰記錄\"}]}"
},
"lolicon": { // https://arkn.lolicon.app/#/material
"object": {
"2004" : 4,
"mod_unlock_token": 25,
"2003": 20
},
"data": "{\"2003\":20,\"2004\": 4,\"mod_unlock_token\": 25}"
}
// 目前只支援 ArkPlanner 和 Lolicon 的格式，以後可能會相容更多網站
```
- `UnsupportedLevel`
自動抄作業，不支援的關卡名

136
docs/zh-tw/3.3-戰鬥流程協定.md Normal file
View File

@@ -0,0 +1,136 @@
# 戰鬥流程協定
`resource/copilot/*.json` 的使用方法及各欄位說明
## 完整欄位一覽
```jsonc
{
"stage_name": "暴君", // 關卡名，必選。關卡中文名、code、stageId、levelId等，只要能保證唯一均可。
"opers": [ // 指定幹員
{
"name": "棘刺", // 幹員名
"skill": 3, // 技能序號。可選，預設 1，取值範圍 [1, 3]
"skill_usage": 0, // 技能用法。可選，預設 0
// 0 - 不自動使用（依賴 "actions" 欄位）
// 1 - 好了就用，有多少次用多少次（例如幹員 棘刺 3 技能、桃金孃 1 技能等）
// 2 - 好了就用，僅使用一次（例如幹員 山 2 技能）
// 3 - 自動判斷使用時機（畫餅.jpg）
// 如果是全自動的技能，填 0
"requirements": { // 練度要求。保留介面，暫未實現。可選，預設為空
"elite": 2, // 精英化等級。可選，預設為 0, 不要求精英化等級
"level": 90, // 幹員等級。可選，預設為 0
"skill_level": 10, // 技能等級。可選，預設為 0
"module": 1, // 模組編號。可選，預設為 0
"potentiality": 1 // 潛能要求。可選，預設為 0
}
},
],
"groups": [
{
"name": "任意正常群補", // 群組名，必選
// 自己隨便取名字，與下面 deploy 中的 name 對應起來就行
"opers": [ // 幹員任選其一，無序，會優先選練度高的，用法同上述 opers 欄位
{
"name": "夜鶯",
"skill": 3,
"skill_usage": 2 // 若是指定時刻，不同的幹員技能 cd 可能不同，請留意
},
{
"name": "白面鴞",
"skill": 2,
"skill_usage": 2
}
]
}
],
"actions": [ // 戰鬥中的操作。有序，執行完前一個才會去執行下一個。必選
{
"type": "部署", // 操作類型，可選，預設 "Deploy"
// "Deploy" | "Skill" | "Retreat" | "SpeedUp" | "BulletTime" | "SkillUsage" | "Output" | "SkillDaemon"
// "部署" | "技能" | "撤退" | "二倍速" | "子彈時間" | "技能用法" | "列印" | "擺完掛起"
// 中英文皆可，效果相同
// 若為 "部署", 當費用不夠時，會一直等待到費用夠（除非 timeout）
// 若為 "技能", 當技能 cd 沒轉好時，一直等待到技能 cd 好（除非 timeout）
// "二倍速" 是可切換的，即使用一次變成二倍速，再次使用又變回一倍速
// "子彈時間" 保留介面，暫未實現，即點擊任意幹員後的 1/5 速度，再進行任意 action 會恢復正常速度
// "列印" 畫面不顯示這條步驟，僅用於輸出 doc 裡的內容（用來做字幕之類的）
// "擺完掛起" 僅使用 "好了就用" 的技能，其他什麼都不做，直到戰鬥結束
// 目前下面三個條件是且的關係，即 &&
"kills": 0, // 擊殺數條件，如果沒達到就一直等待。可選，預設為 0，直接執行
"cost_changes": 5, // 費用變化量條件，如果沒達到就一直等待。可選，預設為 0，直接執行
// 注意是從開始執行本 actions 開始計算的（即前一個 action 結束時的費用作為基準）
// 另外僅在費用是兩位數的時候辨識得比較準，三位數的費用可能會辨識錯，不推薦使用
"cooling": 2, // CD 中幹員數量條件，如果沒達到就一直等待。可選，預設 -1，不辨識
// TODO: 其他條件
// TODO: "condition_type": 0, // 執行條件間的關係，可選，預設 0
// // 0 - 且； 1 - 或
"name": "棘刺", // 幹員名 或 群組名， type 為 "部署" 時必選，為 "技能" | "撤退" 時可選
"location": [ 5, 5 ], // 部署幹員的位置。
// type 為 "部署" 時必選。
// type 為 "技能" | "撤退" 時可選，
// "技能"：僅推薦場地上自動的裝置等，不填寫 name，並使用 location 開啟技能。正常部署的幹員推薦使用 name 開啟技能
// "撤退"：僅推薦有多個同名召喚物時，不填寫 name, 並使用 location 進行撤退。正常部署的幹員推薦 name 進行撤退
"direction": "左", // 部署幹員的幹員朝向。 type 為 "部署" 時必選
// "Left" | "Right" | "Up" | "Down" | "None"
// "左" | "右" | "上" | "下" | "無"
// 中英文皆可，效果相同
"skill_usage": 1, // 修改技能用法。當 type 為 "技能用法" 時必選
// 舉例：剛下桃金娘需要她幫忙打幾個怪，不能自動開技能，中後期平穩了需要她自動開技能
// 則可以在對應時刻設置為 1
"pre_delay": 0, // 前置延時。可選，預設 0, 單位毫秒
"rear_delay": 0, // 後置延時。可選，預設 0, 單位毫秒
// "timeout": 999999999, // 保留欄位，暫未實現。
// 超時時間。當 type 為 "部署" | "技能" 時可選。預設 INT_MAX, 單位毫秒
// 等待超時則放棄當前動作, 轉而執行下一個動作
"doc": "下棘刺了！", // 描述，可選。會顯示在畫面上，沒有實際作用
"doc_color": "orange" // 描述文字的顏色，可選，預設灰色。會顯示在畫面上，沒有實際作用。
},
// 舉例 1
{
"name": "任意正常群補",
"location": [ 5, 6 ],
"direction": "右"
},
// 舉例 2
{
"name": "史爾特爾",
"location": [ 4, 5 ],
"direction": "左",
"doc": "你史爾特爾奶奶來啦！",
"doc_color": "red"
},
// 舉例 3
{
"type": "二倍速"
}
],
"minimum_required": "v4.0", // 最低要求 maa 版本號，必選。保留欄位，暫未實現
"doc": { // 描述，可選。
"title": "低練度高成功率作業",
"title_color": "dark",
"details": "對練度要求很低balabala……", // 建議在這裡寫上你的名字！ （作者名）、參考的影片攻略連結等
"details_color": "dark"
},
}
```
## 舉例
[Sample](../resource/copilot/test.json)
[GA-EX8 突襲作業](../resource/copilot/GA-EX8-raid.json)

162
docs/zh-tw/3.4-任務流程協定.md Normal file
View File

@@ -0,0 +1,162 @@
# 任務流程協定
`resource/tasks.json` 的使用方法及各欄位說明
## 完整欄位一覽
```jsonc
{
"TaskName" : { // 任務名
"algorithm": "MatchTemplate", // 可選項，表示辨識算法的類型
// 不填寫時預設為 MatchTemplate
// - JustReturn: 不進行辨識，直接執行 action
// - MatchTemplate: 匹配圖片
// - OcrDetect: 字元辨識
// - Hash: 雜湊計算
"template": "xxx.png", // 僅當 algorithm 為 MatchTemplate 時有效；可選項，要匹配的圖片檔案名
// 不填時寫預設 "任務名.png"
"text": [ "接管作戰", "代理指揮" ], // 僅當 algorithm 為 OcrDetect 時有效；必選項，要辨識的文字內容，只要任一匹配上了即認為辨識到了
"action": "ClickSelf", // 可選項，表示辨識到後的動作
// 不填寫時預設為 DoNothing
// - ClickSelf: 點擊辨識到的位置（辨識到的目標範圍內隨機點）
// - ClickRand: 點擊整個畫面中隨機位置
// - DoNothing: 什麼都不做
// - Stop: 停止當前任務
// - ClickRect: 點擊指定的區域，對應 specificRect 欄位，不建議使用該選項
// - SwipeToTheLeft: 滑動到最左側
// - SwipeToTheRight: 滑動到最右側
// - SlowlySwipeToTheLeft: 緩慢左滑
// - SlowlySwipeToTheRight: 緩慢右滑
"sub": [ "SubTaskName1", "SubTaskName2" ],
// 可選項，子任務。會在執行完當前任務後，依次執行每一個子任務
// 可以套娃，子任務再套子任務。但要注意不要寫出了無窮迴圈
"subErrorIgnored": true, // 可選項，是否忽略子任務的錯誤。
// 不填寫預設 false
// 為 false 時，若某個子任務出錯，則不繼續執行後續任務（相當於本任務出錯了）
// 為 true 時，子任務是否出錯沒有影響
"next": [ "OtherTaskName1", "OtherTaskName2"],
// 可選項，表示執行完當前任務和 sub 任務後，下一個要執行的任務
// 會從前往後依次去辨識，去執行第一個匹配上的
// 不填寫預設執行完當前任務直接停止
"maxTimes": 10, // 可選項，表示該任務最大執行次數
// 不填寫時預設無窮大
// 達到最大次數後，若存在 exceededNext 欄位，則執行 exceededNext；否則直接任務停止
"exceededNext": [ "OtherTaskName1", "OtherTaskName2" ],
// 可選項，表示達到了最大執行次數後要執行的任務
// 不填寫時，達到了最大執行次數則停止；填寫後就執行這裡的，而不是 next 裡的
"onErrorNext": [ "OtherTaskName1", "OtherTaskName2" ],
// 可選項，表示執行出錯時，後續要執行的任務
"preDelay": 1000, // 可選項，表示辨識到後延遲多久才執行 action，單位毫秒；不填寫時預設 0
"rearDelay": 1000, // 可選項，表示 action 執行完後延遲多久才去辨識 next, 單位毫秒；不填寫時預設 0
"roi": [ 0, 0, 1280, 720], // 可選項，表示辨識的範圍，格式為 [ x, y, width, height ]
// 以 1280 * 720 為基準自動縮放；不填寫時預設 [ 0, 0, 1280, 720 ]
// 盡量填寫，減小辨識範圍可以減少性能消耗，加快辨識速度
"cache": true, // 可選項，表示該任務是否使用快取，預設為 true;
// 第一次辨識到後，以後永遠只在第一次辨識到的位置進行辨識，開啟可大幅節省性能
// 但僅適用於待辨識目標位置完全不會變的任務，若待辨識目標位置會變請設為 false
"rectMove": [0, 0, 0, 0], // 可選項，辨識後的目標移動，不建議使用該選項。以 1280 * 720 為基準自動縮放
// 例如辨識到了 A 圖示，但實際要點擊的是 A 圖示旁邊的某個位置，則進行移動後再點擊。
// 可以的話盡量直接辨識要點擊的位置，不建議使用該選項
"reduceOtherTimes": [ "OtherTaskName1", "OtherTaskName2" ],
// 可選項，執行後減少其他任務的執行計數。
// 例如執行了吃理智藥，則說明上一次點擊藍色開始行動按鈕沒生效，所以藍色開始行動要-1
"specificRect": [ 100, 100, 50, 50],
// 僅當 action 為 ClickRect 時有效且必選，表示指定的點擊位置（範圍內隨機一點）。
// 以 1280 * 720 為基準自動縮放
/* 以下欄位僅當 algorithm 為 MatchTemplate 時有效 */
"templThreshold": 0.8, // 可選項，圖片模板匹配得分的閾值，超過閾值才認為辨識到了。
// 預設 0.8, 可根據紀錄查看實際得分是多少
"maskRange": [ 1, 255 ], // 可選項，灰階遮罩範圍。例如將圖片不需要辨識的部分塗成黑色（灰階值為 0）
// 然後設置"maskRange"的範圍為 [ 1, 255 ], 匹配的時候即刻忽略塗黑的部分
/* 以下欄位僅當 algorithm 為 OcrDetect 時有效 */
"fullMatch": false, // 可選項，文字辨識是否需要全字匹配（不能多字），預設為 false
// false 時只要是子串即可：例如 text: [ "開始" ]，實際辨識到了 "開始行動"，也算辨識成功；
// true 時則必須辨識到了 "開始"，多一個字都不行
"ocrReplace": [ // 可選項，針對常見辨識錯的文字進行替換（支持正規表示式）
[ "乾員", "幹員" ],
[ ".+擊幹員", "狙擊幹員" ]
]
/* 以下欄位僅當 algorithm 為 Hash 時有效 */
// 算法不成熟，僅部分特例情況中用到了，暫不推薦使用
// Todo
}
}
```
## 一些小技巧
- `next` 中再填寫自身的任務名，可形成迴圈。例如
```jsonc
{
"Waiting": {
"algorithm": "OcrDetect",
"text": [ "正在加載" ],
"next": [
"Succeed", // 首先辨識 "加載完成"，
"Waiting" // 如果沒辨識到，再辨識 "正在加載"
]
},
"Succeed": {
"algorithm": "OcrDetect",
"text": [ "加載完成" ],
"next": [
"OtherTask"
]
}
}
```
- `algorithm` 的 `JustReturn` 不建議形成迴圈，如果出現 adb 斷開等情況，會出現一直當做辨識成功
- 某些任務每次要執行 N 次，可將該任務複製 N 遍，分別取不同的名字，例如
```jsonc
{
"DoIt": {
"next": [
"DoItAgain"
]
},
"DoItAgain": {
"next": [
"OtherTask"
]
}
}
```
## Schema 檢驗
本項目為 `tasks.json` 配置了 json schema 檢驗，schema 檔案為`docs/maa_tasks_schema.json`。
### Visual Studio
在 `MeoAssistant.vcxporj` 中已對其進行配置，開箱即用。提示效果較為晦澀，且有部分資訊缺失。
### Visual Studio Code
在 `.vscode/settings.json` 中已對其進行配置，用 vscode 打開該**項目資料夾**即可使用。提示效果較好。

26
docs/zh-tw/3.5-肉鸽輔助協定.md Normal file
View File

@@ -0,0 +1,26 @@
# 肉鴿戰鬥流程協定
`resource/roguelike_copilot.json` 的使用方法及各欄位說明
## 完整欄位一覽
```jsonc
[
{
"stage_name": "馴獸小屋", // 關卡名，必選
"replacement_home": [ // 替換掉家門的位置，可選，預設為空
[ 2, 8 ] // 會使用這裡面的坐標來代替藍門的坐標，然後堵門
],
"key_kills": [ // 關鍵擊殺數，可選，預設為空
15, // 若不為空，幹員技能會攢著，不是好了就放，而是等到擊殺數達到時再釋放
... // 當跑完陣列裡所有的元素之後，再把幹員技能變成好了就放
]
},
{
"stage_name": "巡邏隊",
"replacement_home": [
[ 2, 8 ]
]
}
]
```