diff --git a/docs/.vuepress/public/images/zh-tw/TODO b/docs/.vuepress/public/images/zh-tw/TODO deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/.vuepress/public/images/zh-tw/combat-start-interface-example.png b/docs/.vuepress/public/images/zh-tw/combat-start-interface-example.png new file mode 100644 index 0000000000..f4085fb14f Binary files /dev/null and b/docs/.vuepress/public/images/zh-tw/combat-start-interface-example.png differ diff --git a/docs/.vuepress/public/images/zh-tw/readme/1-dark.png b/docs/.vuepress/public/images/zh-tw/readme/1-dark.png new file mode 100644 index 0000000000..4dd9a20d63 Binary files /dev/null and b/docs/.vuepress/public/images/zh-tw/readme/1-dark.png differ diff --git a/docs/.vuepress/public/images/zh-tw/readme/1-light.png b/docs/.vuepress/public/images/zh-tw/readme/1-light.png new file mode 100644 index 0000000000..e9c8348894 Binary files /dev/null and b/docs/.vuepress/public/images/zh-tw/readme/1-light.png differ diff --git a/docs/.vuepress/public/images/zh-tw/readme/2-dark.png b/docs/.vuepress/public/images/zh-tw/readme/2-dark.png new file mode 100644 index 0000000000..6e79cec1ed Binary files /dev/null and b/docs/.vuepress/public/images/zh-tw/readme/2-dark.png differ diff --git a/docs/.vuepress/public/images/zh-tw/readme/2-light.png b/docs/.vuepress/public/images/zh-tw/readme/2-light.png new file mode 100644 index 0000000000..e4d0e62102 Binary files /dev/null and b/docs/.vuepress/public/images/zh-tw/readme/2-light.png differ diff --git a/docs/.vuepress/public/images/zh-tw/readme/3-dark.png b/docs/.vuepress/public/images/zh-tw/readme/3-dark.png new file mode 100644 index 0000000000..17a9f5b964 Binary files /dev/null and b/docs/.vuepress/public/images/zh-tw/readme/3-dark.png differ diff --git a/docs/.vuepress/public/images/zh-tw/readme/3-light.png b/docs/.vuepress/public/images/zh-tw/readme/3-light.png new file mode 100644 index 0000000000..064c25b306 Binary files /dev/null and b/docs/.vuepress/public/images/zh-tw/readme/3-light.png differ diff --git a/docs/.vuepress/public/images/zh-tw/readme/4-dark.png b/docs/.vuepress/public/images/zh-tw/readme/4-dark.png new file mode 100644 index 0000000000..d35421b6dd Binary files /dev/null and b/docs/.vuepress/public/images/zh-tw/readme/4-dark.png differ diff --git a/docs/.vuepress/public/images/zh-tw/readme/4-light.png b/docs/.vuepress/public/images/zh-tw/readme/4-light.png new file mode 100644 index 0000000000..40291c388a Binary files /dev/null and b/docs/.vuepress/public/images/zh-tw/readme/4-light.png differ diff --git a/docs/zh-tw/develop/README.md b/docs/zh-tw/develop/README.md index 5da31a5fb1..8e235437ab 100644 --- a/docs/zh-tw/develop/README.md +++ b/docs/zh-tw/develop/README.md @@ -6,4 +6,4 @@ dir: order: 2 --- - + \ No newline at end of file diff --git a/docs/zh-tw/develop/ci-tutorial.md b/docs/zh-tw/develop/ci-tutorial.md index 11c2b4d21e..0f05ead222 100644 --- a/docs/zh-tw/develop/ci-tutorial.md +++ b/docs/zh-tw/develop/ci-tutorial.md @@ -5,153 +5,153 @@ icon: devicon-plain:githubactions # CI 系統解析 -MAA 借助 Github Action 完成了大量的自動化工作，包括網站的構建，自動更新資源，最終文件的構建與發版等等過程。隨著時間的推移，這些 CI 逐漸開始嵌套，部分甚至引向了其他的存儲庫。本文檔旨在為想要對 MAA 的 CI 系統做出改進的各位做一個簡要的介紹。 +MAA 藉由 GitHub Actions 完成了大量的自動化工作，包括網站建置、資源自動更新、最終檔案的編譯與發布等過程。隨著時間推移，這些 CI 逐漸開始嵌套，部分甚至連結到了其他的倉庫。本文檔旨在為想要改進 MAA CI 系統的開發者提供一份簡要介紹。 -閱讀本文之前，最好對 MAA 的項目結構以及組成有一個基本的概念。 +閱讀本文之前，建議先對 MAA 的專案結構與組成有基本的概念。 ::: tip -你可以通過在本頁面內搜尋 CI 文件名來快速導航到想看的部分 +您可以透過在本頁面內搜尋 CI 檔名來快速導航到想看的內容。 ::: -工作流的文件均存放在 `.github/workflows` 下，各個文件可以按功能分為以下幾部分： +工作流（Workflow）檔案均存放於 `.github/workflows` 目錄下，各檔案可依功能分為以下幾部分： -- [代碼測試](#代碼測試) -- [代碼構建](#代碼構建) -- [代碼安全檢查](#代碼安全檢查) +- [程式碼測試](#程式碼測試) +- [程式碼建置](#程式碼建置) +- [程式碼安全檢查](#程式碼安全檢查) - [版本發布](#版本發布) - [資源更新](#資源更新) -- [網站構建](#網站構建) +- [網站建置](#網站建置) - [Issues 管理](#issues-管理) - [Pull Requests 管理](#pull-requests-管理) - [MirrorChyan 相關](#mirrorchyan-相關) - [其他](#其他) -此外，我們還通過 [pre-commit.ci](https://pre-commit.ci/) 實現了代碼的自動格式化和圖片資源的自動優化，它在發起 PR 後會自動執行，一般無需特別在意。 +此外，我們還透過 [pre-commit.ci](https://pre-commit.ci/) 實現了程式碼自動格式化與圖片資源自動優化，它在發起 PR 後會自動執行，一般無需特別在意。 -## Github Action 部分 +## GitHub Actions 部分 -### 代碼測試 +### 程式碼測試 `smoke-testing.yml` -本工作流主要負責對 MaaCore 做出基本的檢測，包括資源文件加載，部分簡單 task 運行測試等等。 +本工作流主要負責對 MaaCore 進行基礎檢測，包括資源檔案載入、部分簡單任務（Task）執行測試等。 -由於測試用例已經較久沒有更新，該工作流現在基本是為了保證資源文件不會出現錯誤，以及 MaaCore 的代碼沒有出現影響到構建的致命性錯誤。 +由於測試案例（Test Cases）已較久未更新，該工作流目前的初衷是確保資源檔案不會出錯，以及 MaaCore 的程式碼沒有出現影響建置的致命性錯誤。 -### 代碼構建 +### 程式碼建置 `ci.yml` -本工作流負責對代碼進行全量構建工作，包含 MAA 的所有組件，構建成品即為可運行的 MAA。 +本工作流負責對程式碼進行全量建置工作，包含 MAA 的所有組件，建置產物即為可執行的 MAA。 -除了必要的 MaaCore 外，Windows 構建產物會包含 MaaWpfGui，MacOS 構建產物會包含 MaaMacGui，Linux 構建產物會包含 MaaCLI。 +除了必要的 MaaCore 外，Windows 建置產物會包含 MaaWpfGui，macOS 建置產物會包含 MaaMacGui，Linux 建置產物則包含 MaaCLI。 -該工作流在出現任何新 Commit 以及 PR 時都會自動運行，且當該工作流由發版 PR 觸發時，本次的構建產物將會直接用於發版，並且會創建一個 Release。 +該工作流在有任何新提交（Commit）或 PR 時都會自動執行；當該工作流由發版 PR 觸發時，本次的建置產物將直接用於發布，並自動建立一個 Release。 -### 代碼安全檢查 +### 程式碼安全檢查 -代碼安全檢查通過 CodeQL 對代碼和工作流進行安全分析，具體工作流如下： +程式碼安全檢查透過 CodeQL 對程式碼與工作流進行安全分析，具體工作流如下： `codeql-core.yml` -本工作流負責對 MaaCore 和 MaaWpfGui 的 C++ 和 C# 代碼進行安全分析，檢測潛在的安全漏洞。 +負責對 MaaCore 與 MaaWpfGui 的 C++ 和 C# 程式碼進行安全分析，偵測潛在的安全漏洞。 -該工作流在修改相關源代碼的 PR 時自動運行，同時每天 UTC 時間 11:45 自動執行定期檢查。 +該工作流在修改相關原始碼的 PR 時會自動執行，同時於每天 UTC 時間 11:45 進行定期檢查。 `codeql-wf.yml` -本工作流負責對 GitHub Actions 工作流文件本身進行安全分析，確保 CI/CD 流程的安全性。 +負責對 GitHub Actions 工作流檔案本身進行安全分析，確保 CI/CD 流程的安全性。 -該工作流在修改工作流文件的 PR 時自動運行，同時每天 UTC 時間 12:00 自動執行定期檢查。 +該工作流在修改工作流檔案的 PR 時會自動執行，同時於每天 UTC 時間 12:00 進行定期檢查。 ### 版本發布 -版本發布，簡稱發版，是向用戶發布更新的必要操作，由以下工作流組成： +版本發布（簡稱發版）是向用戶發布更新的必要操作，由以下工作流組成： -- `release-nightly-ota.yml` 發布內測版 -- `release-ota.yml` 發布正式版/公測版 - - `release-preparation.yml` 為正式版/公測版生成 changelog 和準備發布 - - `pr-auto-tag.yml` 對正式版/公測版生成 tag +- `release-nightly-ota.yml` 發布內測版（Nightly） +- `release-ota.yml` 發布正式版 / 公測版（Beta） + - `release-preparation.yml` 為正式版 / 公測版產生 Changelog 並準備發布 + - `pr-auto-tag.yml` 對正式版 / 公測版產生 Tag ::: tip -上述文件名內的 ota 意為 Over-the-Air，也就是我們常說的「增量更新包」，因此 MAA 的發版過程實際上包含了對過往版本構建 OTA 包的步驟 +上述檔名稱內的 OTA 意為 Over-the-Air（雲端更新），也就是我們常說的 `增量更新檔案`，因此 MAA 的發版過程實際上包含了對過往版本建置 OTA 檔案的步驟。 ::: #### 內測版 `release-nightly-ota.yml` -本工作流會在每天 UTC 時間 22 點自動運行，以保證內測版的發版頻率。當然，你也可以在做出更改需要驗證時手動發版。 +本工作流會在每天 UTC 時間 22 點自動執行，以保證內測版的更新頻率。當然，您也可以在做出更改需要驗證時手動觸發發布。 -需要注意的是，內測版的發布僅針對 Windows 用戶，MacOS 與 Linux 用戶並不能接收到內測更新。 +需要注意的是，內測版發布僅針對 Windows 用戶，macOS 與 Linux 用戶目前無法接收到內測更新。 -#### 正式版/公測版 +#### 正式版 / 公測版 -這兩個通道的發版流程相對複雜一點，我們通過模擬一次發版步驟來解釋各工作流的作用： +這兩個版本的發布流程相對複雜，我們透過模擬一次發布步驟來解釋各工作流的作用： -1. 建立由 `dev` 到 `master` 分支的 pr，且該 pr 的名字需要為 `Release v******` -2. `release-preparation.yml` 會生成最近的正式版/公測版到當前版本的 changelog（以一個新 pr 的形式） -3. 對 changelog 進行手動調整，並且添加簡要描述 -4. 合併 pr，觸發 `pr-auto-tag.yml`，創建 tag 並且同步分支 -5. Release 事件觸發 `release-ota.yml`，對 master 打完 tag 後進行 ota 包的構建以及附件上傳 +1. 建立從 `dev` 到 `master` 分支的 PR，且該 PR 的標題需為 `Release v******`。 +2. `release-preparation.yml` 會產生從最近版本到當前版本的 Changelog（以一個新 PR 的形式呈現）。 +3. 對 Changelog 進行手動調整，並加入簡要描述。 +4. 合併 PR，觸發 `pr-auto-tag.yml` 建立 Tag 並同步分支。 +5. Release 事件觸發 `release-ota.yml`，對 master 標上 Tag 後進行 OTA 包建置及附件上傳。 ### 資源更新 -這部分工作流主要負責 MAA 的資源更新以及優化，具體工作流如下： +這部分工作流主要負責 MAA 的資源更新與優化，具體如下： -- `res-update-game.yml` 定期執行，從指定的倉庫拉取遊戲資源 -- `sync-resource.yml` 將資源同步到 MaaResource 倉庫，用於資源更新 -- `optimize-templates.yml` 優化包括模板圖在內的圖片大小 +- `res-update-game.yml` 定期執行，從指定倉庫拉取遊戲資源。 +- `sync-resource.yml` 將資源同步到 MaaResource 倉庫，用於資源更新。 +- `optimize-templates.yml` 優化包括範本圖片在內的圖片檔案大小。 -### 網站構建 +### 網站建置 `website-workflow.yml` -本工作流主要負責 MAA 文檔站的構建與發布。 +本工作流主要負責 MAA 文件站的建置與發布。 -請注意，網站的發布與發版強綁定，平常修改網頁組件的時候只會進行構建以保證不會有錯誤，在發版時才會正式部署到 GitHub Pages 上。 +請注意，網站的發布與版本更新強烈綁定。平時修改網頁組件時僅會進行建置以確保無誤，只有在正式發布版本時才會部署到 GitHub Pages。 ### Issues 管理 `issue-checker.yml` -通過正則匹配給各個 Issue 打 Tag，以此來分類標記 Issue 內容，方便查看與管理。 +透過正規表達式（Regex）比對為各個 Issue 標記 Tag，以此分類 Issue 內容，方便查看與管理。 `issue-checkbox-checker.yml` -通過正則匹配自動關閉勾選「我未仔細閱讀」的 Issue；若「我未仔細閱讀」未被勾選，則將所有勾選框折疊。 +透過正規表達式自動關閉勾選「我未仔細閱讀」的 Issue；若該項未被勾選，則將所有勾選框（Checkbox）折疊。 `stale.yml` -檢查超過 90 天沒有活動的 Bug Issue，將其標記並發起通知，7 天後若還沒有活動則關閉。 +檢查超過 90 天沒有活動的 Bug Issue 並標記通知，若 7 天後仍無活動則自動關閉。 ### Pull Requests 管理 `pr-checker.yml` -該工作流用於檢查 PR 中的 Commit Message 是否符合 [約定式提交](https://www.conventionalcommits.org/zh-hans/v1.0.0/)，以及是否包含 Merge Commit，若上述條件符合則會作出提示。 +檢查 PR 中的 Commit Message 是否符合 [約定式提交](https://www.conventionalcommits.org/zh-hans/v1.0.0/)，以及是否包含 Merge Commit，若不符合則會發出提示。 ### MirrorChyan 相關 -MirrorChyan 是有償的更新鏡像服務，與其相關的工作流如下： +MirrorChyan 是有償的更新鏡像服務，相關工作流如下： -- `release-package-distribution.yml` 同步更新包到 MirrorChyan -- `mirrorchyan_release_note.yml` 生成 MirrorChyan 的 Release Note +- `release-package-distribution.yml` 同步更新包至 MirrorChyan。 +- `mirrorchyan_release_note.yml` 產生 MirrorChyan 的 Release Note。 ### 其他 `markdown-checker.yml` -負責檢查倉庫中的所有 Markdown 文件中是否包含無效鏈接。 +檢查倉庫中所有 Markdown 檔案是否包含無效連結（死連結）。 `blame-ignore.yml` -自動忽略 Commit Message 包含 `blame ignore` 的提交，保證倉庫歷史的乾淨。 +自動忽略 Commit Message 包含 `blame ignore` 的提交，以保持 Git Blame 歷史紀錄的簡潔。 `cache-delete.yml` -在 PR 合併後清理相關的緩存，以此來節省緩存用量。 +在 PR 合併後清理相關快取（Cache），以節省 GitHub 儲存空間。 `update-submodules.yml` -定期更新 MaaMacGui 和 maa-cli 等子模組到最新版本。該工作流每天 UTC 時間 21:50 自動執行（在每日內測版發布之前），確保子模組保持最新狀態。 +定期將 MaaMacGui 與 maa-cli 等子模組更新至最新版本。該工作流於每天 UTC 時間 21:50 自動執行（在每日內測版發布之前），確保子模組保持在最新狀態。 \ No newline at end of file diff --git a/docs/zh-tw/develop/development.md b/docs/zh-tw/develop/development.md index 53bb2e5717..21f3246e94 100644 --- a/docs/zh-tw/develop/development.md +++ b/docs/zh-tw/develop/development.md @@ -6,79 +6,79 @@ icon: iconoir:developer # 開發指南 ::: tip -本頁面主要描述了 PR 流程以及 MAA 的檔案格式化要求，如果你想要具體了解如何對 MAA 的運行邏輯做出更改，請參看 [協議文檔](../protocol/) +本頁面主要描述了 PR 流程以及 MAA 的檔案格式化要求，如果您想要具體了解如何對 MAA 的運行邏輯進行更改，請參閱 [協議文件](../protocol/) ::: ::: tip -你可以 [向 DeepWiki 詢問](https://deepwiki.com/MaaAssistantArknights/MaaAssistantArknights)，以初步了解 MAA 專案的整體架構。 +您可以 [向 DeepWiki 詢問](https://deepwiki.com/MaaAssistantArknights/MaaAssistantArknights)，以初步了解 MAA 專案的整體架構。 ::: -## 我不懂寫程式，只是想改一點點 JSON 文件/文件等，要怎麼操作？ +## 我不懂程式設計，只想改一點點 JSON 檔案 / 文件等，要怎麼操作？ -歡迎收看 [牛牛也能看懂的 GitHub Pull Request 使用指南](./pr-tutorial.md) （純網頁端操作 Github.com） +歡迎收看 [牛牛也能看懂的 GitHub Pull Request 使用指南](./pr-tutorial.md) （純網頁端操作 github.com） -## 我只想簡單修改幾行代碼，但配置環境太麻煩，純網頁編輯又很難用，怎麼辦？ +## 我只想簡單修改幾行程式碼，但配置環境太麻煩，純網頁編輯又很難用，怎麼辦？ -請使用 [GitHub Codespaces](https://github.com/codespaces) 在線開發環境，盡情嘗試！ +請使用 [GitHub Codespaces](https://github.com/codespaces) 線上開發環境，盡情嘗試！ 我們預置了多種不同的開發環境以供選擇： -- 空白環境，裸 Linux 容器（默認） +- 基礎環境，純 Linux 容器（預設） [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/MaaAssistantArknights/MaaAssistantArknights?devcontainer_path=.devcontainer%2Fdevcontainer.json) -- 輕量環境，適合文檔站前端開發 +- 精簡環境，適合文件站前端開發 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/MaaAssistantArknights/MaaAssistantArknights?devcontainer_path=.devcontainer%2F0%2Fdevcontainer.json) -- 全量環境，適合 MAA Core 相關開發（不推薦使用，建議本地開發，完整配置相關環境。詳見下一章節） +- 完整環境，適合 MAA Core 相關開發（不推薦使用，建議本機開發，完整配置相關環境。詳見下一章節） [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/MaaAssistantArknights/MaaAssistantArknights?devcontainer_path=.devcontainer%2F1%2Fdevcontainer.json) ## 完整環境配置流程（Windows） -1. 如果很久以前 Fork 過，先在自己倉庫的 `Settings` 裡，翻到最下面，刪除 -2. 打開 [MAA 主倉庫](https://github.com/MaaAssistantArknights/MaaAssistantArknights)，點擊 `Fork`，繼續點擊 `Create fork` -3. 複製你自己倉庫下的 dev 分支到本地，並拉取子模組 +1. 如果很久以前 Fork 過，先在自己倉庫的 `Settings` 裡，翻到最下面，將其刪除。 +2. 打開 [MAA 主倉庫](https://github.com/MaaAssistantArknights/MaaAssistantArknights)，點擊 `Fork`，繼續點擊 `Create fork`。 +3. 複製（Clone）您自己倉庫下的 dev 分支到在地，並拉取子模組（Submodules）。 ```bash - git clone --recurse-submodules <你的倉庫的 git 連結> -b dev + git clone --recurse-submodules <您的倉庫 git 連結> -b dev ``` ::: warning 如果正在使用 Visual Studio 等不附帶 `--recurse-submodules` 參數的 Git GUI，則需在複製後再執行 `git submodule update --init` 以拉取子模組。 ::: -4. 下載預構建的第三方庫 +4. 下載預編譯的第三方函式庫 - **需要有 Python 環境，請自行搜索 Python 安裝教學** + **需要有 Python 環境，請自行搜尋 Python 安裝教學。** ```cmd python tools/maadeps-download.py ``` -5. 配置編程環境 +5. 配置開發環境 - 下載並安裝 `CMake` - - 下載並安裝 `Visual Studio 2026 Community`, 安裝的時候需要選中 `基於 C++ 的桌面開發` 和 `.NET 桌面開發`。 + - 下載並安裝 `Visual Studio 2026 Community`，安裝時需要選中 `使用 C++ 的桌面開發` 和 `.NET 桌面開發`。 -6. 執行 cmake 項目配置 +6. 執行 CMake 專案配置 ```cmd mkdir -p build cmake -G "Visual Studio 18 2026" -B build -DBUILD_WPF_GUI=ON -DBUILD_DEBUG_DEMO=ON ``` -7. 雙擊打開 `build/MAA.slnx` 文件，Visual Studio 會自動載入整個項目。 -8. 設置 VS - - VS 上方配置選擇 `Debug` `x64` - - 右鍵 `MaaWpfGui` - 設為啟動項目 - - 按 F5 運行 +7. 雙擊開啟 `build/MAA.sln` 檔案，Visual Studio 會自動載入整個專案。 +8. 設定 Visual Studio + - Visual Studio 上方配置選擇 `Debug` `x64` + - 右鍵點擊 `MaaWpfGui` - 設為啟動專案。 + - 按 F5 執行。 ::: tip - 若需調試 Win32Controller（Windows 視窗控制）相關功能，需要自行從 [MaaFramework Releases](https://github.com/MaaXYZ/MaaFramework/releases) 下載對應平台的壓縮包，將 `bin` 目錄中的 `MaaWin32ControlUnit.dll` 放到 MAA 的 DLL 同目錄下（如 `build/bin/Debug`）。歡迎 PR 一個自動下載腳本！ + 若需針對 Win32Controller（Windows 視窗控制）相關功能進行除錯，需要自行從 [MaaFramework Releases](https://github.com/MaaModular/MaaFramework/releases) 下載對應平台的壓縮檔案，將 `bin` 目錄中的 `MaaWin32ControlUnit.dll` 放到 MAA 的 DLL 同目錄下（例如 `build/bin/Debug`）。歡迎 PR 一個自動下載腳本！ ::: -9. 到這裡，你就可以愉快地 ~~瞎 JB 改~~ 發電了 +9. 到這裡，你就可以愉快地 ~~瞎雞巴改~~ 發電了 10. 開發過程中，每一定數量，記得提交一個 Commit, 別忘了寫上 Message 假如你不熟悉 git 的使用，你可能想要新建一個分支進行更改，而不是直接提交在 `dev` 上 @@ -89,14 +89,15 @@ git checkout your_own_branch 這樣你的提交就能在新的分支上生長，不會受到 `dev` 更新的打擾 -11. 完成開發後，推送你修改過的本地分支（以 `dev` 為例）到遠程（Fork 的倉庫） +11. 完成開發後，推送你修改過的本地分支（以 `dev` 為例）到遠端（Fork 的倉庫） ```bash git push origin dev ``` -12. 打開 [MAA 主倉庫](https://github.com/MaaAssistantArknights/MaaAssistantArknights)。提交一個 Pull Request，等待管理員通過。別忘了你是在 dev 分支上修改，別提交到 master 分支去了 -13. 當 MAA 原倉庫出現更改（別人做的），你可能需要把這些更改同步到你的分支 +12. 打開 [MAA 主倉庫](https://github.com/MaaAssistantArknights/MaaAssistantArknights)。提交一個 Pull Request，等待管理員通過。別忘了您是在 dev 分支上修改，別提交到 master 分支去了。 + +13. 當 MAA 原倉庫出現更改（他人貢獻）時，您可能需要把這些更改同步到您的分支： 1. 關聯 MAA 原倉庫 ```bash @@ -124,18 +125,18 @@ git checkout your_own_branch 4. 重複上述 8, 9, 10, 11 中的操作 ::: tip -在打開 VS 之後，和 Git 有關的操作可以不用命令行工具，直接使用 VS 自帶的“Git 更改”即可 +開啟 Visual Studio 之後，和 Git 有關的操作可以不用命令列工具，直接使用 Visual Studio 內建的「Git 變更」功能即可。 ::: ## MAA 的檔案格式化要求 -MAA 使用一系列的格式化工具來保證倉庫中的代碼和資源文件美觀統一，以便於維護和閱讀 +MAA 使用一系列的格式化工具來確保倉庫中的程式碼和資源檔案美觀統一，以便於維護和閱讀。 -請確保在提交之前已經格式化，或是[啟用 Pre-commit Hooks 來進行自動格式化](#利用-pre-commit-hooks-自動進行程式碼格式化) +請確保在提交之前已經完成格式化，或是[啟用 Pre-commit Hooks 來進行自動格式化](#利用-pre-commit-hooks-自動進行程式碼格式化) 目前啟用的格式化工具如下： -| 文件類型 | 格式化工具 | +| 檔案類型 | 格式化工具 | | --------- | --------------------------------------------------------------- | | C++ | [clang-format](https://clang.llvm.org/docs/ClangFormat.html) | | Json/Yaml | [Prettier](https://prettier.io/) | @@ -143,18 +144,18 @@ MAA 使用一系列的格式化工具來保證倉庫中的代碼和資源文件 ### 利用 Pre-commit Hooks 自動進行程式碼格式化 -1. 確保你的電腦上有 Python 與 Node 環境 +1. 確保您的電腦上有 Python 與 Node 環境 -2. 在項目根目錄下執行以下命令 +2. 在專案根目錄下執行以下命令： ```bash pip install pre-commit pre-commit install ``` -如果pip安裝後依然無法運行 Pre-commit，請確認 PIP 安裝地址已被添加到 PATH +如果 pip 安裝後依然無法執行 pre-commit，請確認 pip 安裝路徑已被添加到 PATH。 -接下來，每次提交時都將會自動運行格式化工具，來確保你的代碼格式符合規範 +接下來，每次提交時都將會自動執行格式化工具，以確保您的程式碼格式符合規範。 ### 在 Visual Studio 中啟用 clang-format @@ -164,15 +165,16 @@ MAA 使用一系列的格式化工具來保證倉庫中的代碼和資源文件 python -m pip install clang-format ``` -2. 使用 Everything 等工具 找到 clang-format.exe 的安裝位置。作為參考，若您使用了 Anaconda，clang-format.exe 將安裝在 YourAnacondaPath/Scripts/clang-format.exe +2. 使用 Everything 等工具找到 `clang-format.exe` 的安裝位置。作為參考，若您使用了 Anaconda，`clang-format.exe` 將安裝在 `YourAnacondaPath/Scripts/clang-format.exe` -3. 在 Visual Studio `工具-選項` 中搜索 `clang-format` -4. 點擊 `啟用 ClangFormat 支持`，然後選擇下面的 `使用自訂 clang-format.exe 文件`，選擇第 2 步找到的 `clang-format.exe` +3. 在 Visual Studio `工具-選項` 中搜尋 `clang-format` -![Visual Studio 設置 clang-format](/images/zh-cn/development-enable-vs-clang-format.png) +4. 點擊 `啟用 ClangFormat 支援`，然後選擇下方的 `使用自定義 clang-format.exe 檔案`，選擇第 2 步找到的 `clang-format.exe` -然後你的 Visual Studio 就能愉快的使用支持 C++20 語法的 clang-format 啦！ +![Visual Studio 設定 clang-format](/images/zh-cn/development-enable-vs-clang-format.png) -你也可以使用 `tools\ClangFormatter\clang-formatter.py` 來直接調用你的 clang-format 來進行格式化，只需要在項目根目錄下執行： +然後您的 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\MaaCore` diff --git a/docs/zh-tw/develop/documentation-guidelines.md b/docs/zh-tw/develop/documentation-guidelines.md index 6997a82dbf..25cc6bfdba 100644 --- a/docs/zh-tw/develop/documentation-guidelines.md +++ b/docs/zh-tw/develop/documentation-guidelines.md @@ -6,52 +6,58 @@ icon: jam:write-f # 文件編寫指南 ::: tip -本文件的目的在於指導文件編寫者更好地使用主題提供的功能，以達到更易讀的效果。 +本文件的目的在於指導文件編寫者更好地使用主題提供的功能，以此達到更易讀的效果。 ::: -我們的文件基於 [vuepress](https://github.com/vuejs/vuepress) 構建，使用了 [vuepress-theme-plume](https://github.com/pengzhanbo/vuepress-theme-plume) 主題，你也可以查看[官方文件](https://theme-plume.vuejs.press/)來獲取更詳細的說明，這裡僅介紹一些常用的功能。 +我們的文件基於 [VuePress](https://github.com/vuejs/vuepress) 建置，使用了 [vuepress-theme-plume](https://github.com/pengzhanbo/vuepress-theme-plume) 主題。您也可以查看 [官方文件](https://theme-plume.vuejs.press/) 來獲取更詳細的說明。本文僅介紹部分常用功能，或經我們自定義後的特殊功能。 -## 本地部署 +## 本機開發 -1. 安裝 [pnpm](https://pnpm.io/zh/installation)，並參考 [Pull Request 流程簡述](./development.md#github-pull-request-流程簡述)將倉庫克隆到本地。 -2. 在 `docs` 目錄下新建終端，運行 `pnpm i` 下載依賴。 -3. 運行 `pnpm run dev` 進行部署。 +1. 安裝 [pnpm](https://pnpm.io/installation)，並參考 [Pull Request 流程簡述](./development.md#github-pull-request-流程簡述) 將倉庫複製（Clone）到本機。 +2. 在 `docs` 目錄下開啟終端機，執行 `pnpm i` 安裝相依套件。 +3. 執行 `pnpm run dev` 啟動開發預覽環境。 -## 容器 +## 容器與卡片 -~~不是 docker 那個容器~~ - -該主題提供了關於提示、注釋、信息、注意、警告和詳情自定義容器的支持，我們可以利用這一特性來強調部分內容。 +該主題提供了關於提示、註釋、資訊、注意、警告和詳情自定義容器的支援，我們可以利用這一特性來強調部分內容。 容器的使用方法： ```markdown -::: [容器類型] [容器標題（可選）] -你想寫的內容 +::: [容器類型] [容器標題（選填）] +您想寫的內容 ::: ``` -接受的容器内容与其默认标题如下： +或是使用 GitHub 風格語法： + +```markdown +> [!容器類型] +> 您想寫的內容 +``` + +可接受的容器類型與其預設標題如下： - `tip` 提示 -- `note` 注釋 -- `info` 信息 +- `note` 註釋 +- `info` 相關資訊 - `warning` 注意 - `danger` 警告 - `details` 詳情 +- `demo-warpper` ==特殊容器== -### 容器示例 +### 容器範例 ::: tip 這是提示容器 ::: ::: note -這是注釋容器 +這是註釋容器 ::: ::: info -這是信息容器 +這是資訊容器 ::: ::: warning @@ -59,30 +65,215 @@ icon: jam:write-f ::: ::: danger -這是危險容器 +這是警告容器 ::: ::: details 這是詳情容器 ::: -## 圖標 +::: demo-wrapper +這是一個很特殊的容器 +::: -該主題提供了圖標支持，你可以在以下地方使用圖標： +## 麥克筆標記 -- 文件標題：在 frontmatter 中設置文件標題旁邊的圖標 +您可以使用標記語法來對想要顯示的內容進行標記，用於強調重點事項。 -- 導航欄/側邊欄：設置在導航欄與側邊欄中顯示的圖標 +使用方法：用 `==標記內容=={標記顏色（選填）}` 的語法進行標記，請注意標記兩邊需要有空格。 -- 文件內容：在文件中使用圖標 +**輸入：** -### 設置文件的圖標 +```markdown +MaaAssistantArknights 是由 ==很多豬== 開發的 +``` -你可以在文件的 [frontmatter](#frontmatter) 中使用 icon 來設置文件的圖標。 +**輸出：** -这个图标会显示在文档标题的旁边。 +MaaAssistantArknights 是由 ==很多豬== 開發的 -::: details 本文件的 frontmatter 設置 +主題還內建了以下的配色方案： + +- **default**: `==Default==` - ==Default== +- **info**: `==Info=={.info}` - ==Info=={.info} +- **note**: `==Note=={.note}` - ==Note=={.note} +- **tip**: `==Tip=={.tip}` - ==Tip=={.tip} +- **warning**: `==Warning=={.warning}` - ==Warning=={.warning} +- **danger**: `==Danger=={.danger}` - ==Danger=={.danger} +- **caution**: `==Caution=={.caution}` - ==Caution=={.caution} +- **important**: `==Important=={.important}` - ==Important=={.important} + +## 隱藏文字 + +出於某種原因，您可能需要將文件的某部分暫時塗黑，在這種情況下您可以使用隱藏文字功能。 + +您可以使用 `!!需要隱秘的內容!!{配置（選填）}` 的語法來使用，預設效果如下： + +!!總感覺在看萌娘百科（劃掉!! + +有以下配置可以使用： + +::: demo-wrapper +輸入： + +```markdown ++ 遮罩層效果 + 滑鼠懸停：!!滑鼠懸停看到我了!!{.mask .hover} ++ 遮罩層效果 + 點擊：!!點擊看到我了!!{.mask .click} ++ 文字模糊效果 + 滑鼠懸停：!!滑鼠懸停看到我了!!{.blur .hover} ++ 文字模糊效果 + 點擊：!!點擊看到我了!!{.blur .click} +``` + +輸出： + +- 遮罩層效果 + 滑鼠懸停：!!滑鼠懸停看到我了!!{.mask .hover} +- 遮罩層效果 + 點擊：!!點擊看到我了!!{.mask .click} +- 文字模糊效果 + 滑鼠懸停：!!滑鼠懸停看到我了!!{.blur .hover} +- 文字模糊效果 + 點擊：!!點擊看到我了!!{.blur .click} + +::: + +## 步驟 + +當您正在撰寫一個步驟化的教學時，有序列表可能會因為嵌套而失去層次感，這種時候 `steps` 容器就是最好的選擇。 + +注意該容器用四個冒號來標記開始和結束，與常規的容器不同。 + +輸入： + +````markdown +:::: steps +1. 步驟 1 + + ```ts + console.log('Hello World!') + ``` + +2. 步驟 2 + + 這裡是步驟 2 的相關內容 + +3. 步驟 3 + + ::: tip + 提示容器 + ::: + +4. 結束 +:::: +```` + +輸出： + +:::: steps +1. 步驟 1 + + ```ts + console.log('Hello World!') + ``` + +2. 步驟 2 + + 這裡是步驟 2 的相關內容 + +3. 步驟 3 + + ::: tip + 提示容器 + ::: + +4. 結束 + +:::: + +## 智慧圖片容器 + +我們基於主題提供的功能包裝了一個圖片容器。該容器能夠在淺色與深色主題下自動顯示對應主題的圖片，同時支援自動適應排版。 + +您可以在 Markdown 正文中使用 `` 元件來呼叫該方法，具體的語法和效果如下： + +::: demo-wrapper + +這是語法： + +```markdown + +``` + +這是渲染效果： + + + +::: + +## 欄位容器 + +該語法較為複雜，請參閱 [官方文件](https://theme-plume.vuejs.press/guide/markdown/field/) 進行使用。 + +效果展示如下： + +:::: field-group +::: field name="theme" type="ThemeConfig" required default="{ base: '/' }" +主題配置 +::: + +::: field name="enabled" type="boolean" optional default="true" +是否啟用 +::: + +::: field name="callback" type="(...args: any[]) => void" optional default="() => {}" + +回呼函數 +::: + +::: field name="other" type="string" deprecated + +已棄用屬性 +::: +:::: + +## 圖示 + +該主題提供了圖示支援，您可以在以下地方使用圖示： + +- 文件標題：在 frontmatter 中設定文件標題旁邊的圖示。 + +- 導覽列 / 側邊欄：設定在導覽列與側邊欄中顯示的圖示。 + +- 文件內容：在文件內部使用圖示。 + +### 設定文件的圖示 + +您可以在文件的 [frontmatter](#frontmatter) 中使用 `icon` 來設定文件的圖示。 + +這個圖示會顯示在文件標題的旁邊。 + +::: details 本文件的 frontmatter 設定 ```markdown --- @@ -92,36 +283,41 @@ icon: jam:write-f ::: -### 在文件中使用圖標 +### 在文件中使用圖示 -你可以使用 `` 組件在 markdown 中添加圖標。該組件有以下屬性： +您可以使用 `` 元件在 Markdown 中新增圖示。該元件有以下屬性： -- `icon` 接受圖標關鍵字及 Url，如 `jam:write-f`，`ic:round-home` 等 -- `color` 接受 css 風格的顏色值，如 `#fff`，`red` 等（該選項僅對 svg 圖標有效） -- `size` 接受 css 風格的大小，如 `1rem`，`2em`，`100px` 等 +- `icon` 接受圖示關鍵字及 URL，如 `jam:write-f`，`ic:round-home` 等。 +- `color` 接受 CSS 風格的顏色值，如 `#fff`，`red` 等（該選項僅對 SVG 圖示有效）。 +- `size` 接受 CSS 風格的大小，如 `1rem`，`2em`，`100px` 等。 -::: details 案例 - +::: demo-wrapper 範例 + +輸入： ```markdown - +- home - +- vscode - +- twitter - ``` - -```markdown - -``` +輸出： + +- home - +- vscode - +- twitter - + ::: -### 圖標關鍵字的獲取 +### 圖示關鍵字的獲取 -本文件使用的圖標來自於 [iconify](https://iconify.design/)，你可以在其給出的 [圖標搜索界面](https://icon-sets.iconify.design/) 中搜索你想要的圖標，然後復制其關鍵字。 +本文件使用的圖示來自於 [iconify](https://iconify.design/)，您可以在其提供的 [圖示搜尋介面](https://icon-sets.iconify.design/) 中搜尋您想要的圖示，然後複製其關鍵字。 ## Frontmatter -Frontmatter 是 Markdown 文件開頭一段用 --- 包裹起來的內容，其內部使用 yml 語法。通過 Frontmatter，我們可以標識文件的編輯時間，使用的圖標，分類，標籤等等。 +Frontmatter 是 Markdown 文件開頭一段用 `---` 包裹起來的內容，其內部使用 YAML 語法。透過 Frontmatter，我們可以標示文件的編輯時間、使用的圖示、分類、標籤等等。 -::: details 示例 +::: details 範例 ```markdown --- @@ -137,8 +333,8 @@ order: 1 ::: -各字段含義如下： +各欄位含義如下： -- `date` 文件的編輯時間 -- `icon` 文件標題旁邊的圖標 -- `order` 文件在側邊欄中的排序 +- `date`：文件的編輯時間 +- `icon`：文件標題旁邊的圖示 +- `order`：文件在側邊欄中的排序 diff --git a/docs/zh-tw/develop/issue-bot-usage.md b/docs/zh-tw/develop/issue-bot-usage.md index b87d95cd66..96187fe433 100644 --- a/docs/zh-tw/develop/issue-bot-usage.md +++ b/docs/zh-tw/develop/issue-bot-usage.md @@ -5,66 +5,65 @@ icon: bxs:bot # Issue Bot 使用方法 -Issue Bot 使用的 action 為 [issue-checker](https://github.com/zzyyyl/issue-checker) ，配置文件為 [issue-checker.yml](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/.github/issue-checker.yml) 。 +Issue Bot 使用的 Action 為 [issue-checker](https://github.com/zzyyyl/issue-checker)，配置檔案為 [issue-checker.yml](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/.github/issue-checker.yml)。 ::: warning -Pull Request 被增加 `ambiguous` 標籤是因為沒有按照 commitizen 規則提交 +拉取請求（PR）被加上 `ambiguous` 標籤是因為沒有按照 Commitizen 規範提交。 ::: ## 功能 ### 自動觸發 -- 給 issue 和 Pull Request 增加標籤，包括 `module` 系列、`Client` 系列、`ambiguous`、`translation required` 等。 - Issue Bot 會根據關鍵字自動增加分類標籤。 - 具體關鍵字可以參考 [配置檔案](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/.github/issue-checker.yml)。 -- 給作者是可見性設定為 public 的 MAA 成員的 issue 和 Pull Request 增加 `MAA Team` 標籤。 +- 針對議題 (Issue) 與拉取請求 (Pull Request)，Issue Bot 會根據關鍵字自動進行分類，並加上 `module` 系列、`Client` 系列、`ambiguous`、`translation required` 等標籤。 + 具體關鍵字可以參閱 [配置檔案](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/.github/issue-checker.yml)。 +- 針對身分設為公開 (Public) 的 MAA 成員，為其發起的議題與拉取請求加上 `MAA Team` 標籤。 -#### Issue 及其評論 +#### 議題 (Issue) 及其評論 -- 給文件上傳失敗的 issue 增加 `incomplete` 標籤並評論，告訴用戶文件上傳失敗。 +- 為上傳檔案失敗的議題增加 `incomplete` 標籤並留言評論，提醒用戶檔案上傳失敗。 -#### Pull Request +#### 拉取請求 (Pull Request) -Issue Bot 會對 Pull Request 標題的格式進行簡單審查。它會增加 `ambiguous` 標籤，除非 Pull Request 標題以下列任一單詞開頭： +Issue Bot 會對拉取請求標題的格式進行簡單審查。除非標題以下列任一單字開頭，否則它會增加 `ambiguous` 標籤： -- `build` `chore` `ci` `doc` `docs` `feat` `fix` `perf` `refactor` `rfc` `style` `test` -- `Merge` `merge` `Revert` `revert` +- `build`, `chore`, `ci`, `doc`, `docs`, `feat`, `fix`, `perf`, `refactor`, `rfc`, `style`, `test` +- `Merge`, `merge`, `Revert`, `revert`, `Reapply`, `reapply` ### 手動觸發 -多使用關鍵字詳細描述問題來自動觸發分類標籤，少使用下列指令。 -但 **當你知道自己的行為會導致 Issue Bot 誤解時除外**。 +請多利用關鍵字詳細描述問題以自動觸發分類標籤，盡量少使用下列指令。 +但**當您知道自己的行為會導致 Issue Bot 誤解時除外**。 -#### Issue 及 Pull Request +#### 議題 (Issue) 及拉取請求 (Pull Request) -- `Remove {LABEL_NAME}` 可以刪除一個標籤。 -- `Remove labels` 可以刪除所有標籤。 -- `Skip {LABEL_NAME}` 可以跳過一個標籤。 -- `Skip labels` 可以跳過所有標籤。 +- `Remove {LABEL_NAME}`：可以刪除一個標籤。 +- `Remove labels`：可以刪除所有標籤。 +- `Skip {LABEL_NAME}`：可以跳過一個標籤。 +- `Skip labels`：可以跳過所有標籤。 -#### Issue Comments 及 Pull Request Comments +#### 議題評論 (Issue Comments) 及拉取請求評論 (Pull Request Comments) -- `Skip {LABEL_NAME}` 可以保證不增加標籤。 -- `Skip labels` 可以保證不增加任何標籤。 -- 以下幾種方法可以為 issue 增加 `fixed` 標籤：1 +- `Skip {LABEL_NAME}`：可以保證不增加特定標籤。 +- `Skip labels`：可以保證不增加任何標籤。 +- 以下幾種方法可以為議題增加 `fixed` 標籤：1 - `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}` 可以在目前 issue 增加 `duplicate` 標籤。 -- **當你知道自己的 issue 評論會導致 Issue Bot 誤解時，盡量添加一些 skip 操作。** +- `Duplicate of #{ISSUE_NUMBER}`：可以為目前議題增加 `duplicate` 標籤。 +- **當您知道自己的議題評論會導致 Issue Bot 誤解時，請盡量添加一些 skip 操作。** ::: info 注意 -1 這裡的 COMMIT_HASH 需要完整的 40 位 +1 這裡的 COMMIT_HASH 需要完整的 40 位元字元。 ::: -#### 推送（Push） +#### 推送 (Push) -對於一個推送中的任意提交： +對於一次推送中的任意提交（Commit）： -- 在 commit message 中包含以下幾種任意一個，可以在對應 issue 加上 `fixed` 標籤： +- 在 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}` + - `close https://github.com/MaaAssistantArknights/MaaAssistantArknights/issues/{ISSUE_NUMBER}` \ No newline at end of file diff --git a/docs/zh-tw/develop/linux-tutorial.md b/docs/zh-tw/develop/linux-tutorial.md index 8b47ebb17f..bae30c6581 100644 --- a/docs/zh-tw/develop/linux-tutorial.md +++ b/docs/zh-tw/develop/linux-tutorial.md @@ -5,66 +5,99 @@ icon: teenyicons:linux-alt-solid # Linux 編譯教學 -**本教程需要讀者有一定的 Linux 環境配置能力及程式設計基礎！**，若您僅希望直接安裝MAA而非自行編譯，請閱讀[使用者手冊 - Linux 模擬器與容器](../manual/device/linux.md)。 +**本教學需要讀者具備一定的 Linux 環境配置能力與程式設計基礎！** 若您僅希望直接安裝 MAA 而非自行編譯，請參閱[用戶手冊 - Linux 模擬器與容器](../manual/device/linux.md)。 ::: info 注意 -MAA 的構建方法仍在討論中, 本教程的內容可能過時, 請以 [GitHub workflow file](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/.github/workflows/ci.yml#L134) 中的指令碼為準。也可參考 [AUR PKGBUILD](https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=maa-assistant-arknights)、[nixpkgs](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/ma/maa-assistant-arknights/package.nix)。 +MAA 的建置方法仍在討論中，本教學內容可能過時，請以 [GitHub workflow file](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/.github/workflows/ci.yml#L134) 中的腳本為準。 +您也可以參考 [AUR PKGBUILD](https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=maa-assistant-arknights) 或 [nixpkgs](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/ma/maa-assistant-arknights/package.nix)。 +::: + +::: info +Mac 使用者可以使用 `tools/build_macos_universal.zsh` 腳本進行編譯。 +建議參考 MaaAssistantArknights/MaaMacGui 專案的 [README.md](https://github.com/MaaAssistantArknights/MaaMacGui/blob/master/README.md)。 ::: ## 編譯過程 -1. 下載編譯所需的依賴 - - Ubuntu/Debian +:::: steps - ```bash - sudo apt install gcc-14 g++-14 cmake zlib1g-dev +1. 下載編譯所需的依賴項目 + ::: code-tabs + @tab:active Ubuntu/Debian + + ```bash :no-line-numbers + sudo apt install cmake ``` -2. 構建第三方庫 - - 下載預構建的第三方庫 + @tab Arch - > **Note** - > 包含在相對較新的 Linux 發行版 (Ubuntu 22.04) 中編譯的動態庫，如果您系統中的 libstdc++ 版本較老，可能遇到 ABI 不兼容的問題。 + ```bash :no-line-numbers + sudo pacman -S --needed cmake + ``` + + ::: + +2. 建置第三方函式庫 + + 可以選擇下載預編譯的函式庫，或從原始碼編譯。 + - 下載預編譯的第三方函式庫（推薦） + + > [!Note] + > ~~先前提供的動態連結庫是在較新的 Linux 發行版 (Ubuntu 22.04) 中編譯的，若您的系統 libstdc++ 版本較舊，可能會遇到 ABI 不相容的問題。~~ + > 目前已透過交叉編譯降低了執行環境要求，僅需相依於 glibc 2.31 (Ubuntu 20.04)。 ```bash python tools/maadeps-download.py ``` - - 自行構建第三方庫 + 如果您發現上述預編譯庫因 ABI 版本等原因無法在您的系統執行，且不打算使用容器等方案，也可以嘗試自行編譯。 + - 自行建置第三方函式庫（耗時較長） ```bash - git submodule update --init --recursive - python maadeps-build.py + git clone https://github.com/MaaAssistantArknights/MaaDeps + cd MaaDeps + # 若系統環境版本過低無法使用我們預設提供的 LLVM 20，請考慮不使用交叉編譯，直接使用在地編譯環境。 + # 需調整 src/MaaUtils/MaaDeps/cmake 中的 toolchain 設定。 + python linux-toolchain-download.py + python build.py ``` 3. 編譯 MAA ```bash - mkdir -p build - CC=gcc-14 CXX=g++-14 cmake -B build \ + cmake -B build \ -DINSTALL_RESOURCE=ON \ - -DINSTALL_PYTHON=ON + -DINSTALL_PYTHON=ON \ + -DCMAKE_TOOLCHAIN_FILE=src/MaaUtils/MaaDeps/cmake/maa-x64-linux-toolchain.cmake cmake --build build ``` - 來將 MAA 安裝到目標位置，注意 MAA 推薦通過指定 `LD_LIBRARY_PATH` 來執行，不要使用以系統管理員身分將 MAA 裝入 `/` + 將 MAA 安裝到目標路徑。請注意，MAA 建議透過指定 `LD_LIBRARY_PATH` 來執行，請勿使用管理員權限將 MAA 安裝至 `/usr` 目錄。 + + > 目前應該不需指定 `LD_LIBRARY_PATH` 即可正常執行。 ```bash cmake --install build --prefix ``` -## 集成文件 +4. 結束，您現在應該能在目錄下看到建置完成的檔案了。 + +:::: + +## 整合文件 [~~或許算不上文件~~](../protocol/integration.md) ### Python -可參考 [Python demo](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/src/Python/sample.py) 中 `__main__` 的實現 +可參考 [Python demo](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/src/Python/sample.py) 中 `__main__` 中的實作方式。 ### C++ -可參考 [CppSample](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/src/Cpp/main.cpp) 中的實現 +可參考 [CppSample](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/src/Cpp/main.cpp) 中的實作方式。 ### C Sharp -可參考 [MaaWpfGui](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/src/MaaWpfGui/Main/AsstProxy.cs) 中的實現 + + +可參考 [MaaWpfGui](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/master/src/MaaWpfGui/Main/AsstProxy.cs) 中的實作方式。 diff --git a/docs/zh-tw/develop/overseas-client-adaptation.md b/docs/zh-tw/develop/overseas-client-adaptation.md index 51758e956f..e5075ea8de 100644 --- a/docs/zh-tw/develop/overseas-client-adaptation.md +++ b/docs/zh-tw/develop/overseas-client-adaptation.md @@ -7,41 +7,39 @@ icon: ri:earth-fill ## 準備工作 -在開始這個教學之前，請確保你已經： +在開始本教學之前，請確保您已經： -1. 安裝並正確配置了所需軟體。在陸服或相應用戶端的 `readme.md` 中應該會有相關資訊，確保所支援的功能可以正常執行。 -2. 閱讀了 `3.4-任務流程協議.md`，對各個欄位的含義和用法有基本瞭解，並能理解 `@`、`#` 類型任務的含義和用法。 -3. 瞭解外服的 `task.json` 和範本圖片中未提及的和缺少的內容會使用陸服的 `task.json` 和範本圖片等內容作為備選。外服的 `task.json` 中的內容會覆蓋並重寫陸服對應任務的相應欄位。 -4. 具備一定的英語能力，能夠閱讀英文日誌，並能通過日誌找出缺失的圖片等資訊。 -5. 建議按照任務鏈進行修改。例如，對於 `Award` 任務，根據陸服 `task.json` 中 `Award` 任務的 `next` 順序逐步替換 `範本圖片` / `文字` / `修改 roi`，以確保修改後的每一步都能正常執行，或者能夠迅速發現錯誤。這樣可以避免因為一次修改修改了太多內容而不清楚程式因為哪一步卡住而不能執行。 +1. 安裝並正確配置所需軟體：請參考官服或對應客戶端的 `README.md`，確保目前支援的功能皆可正常執行。 +2. 閱讀 [任務流程協議](../protocol/task-schema.md)：對各欄位的含義與用法有基本了解，並理解 `@`、`#` 類型任務的定義。 +3. 理解資源覆蓋邏輯：外服的 `task.json` 與範本圖片中未提及或缺失的內容，會自動以官服內容作為備選；若外服的 `task.json` 中已定義相關欄位，則會覆蓋並重寫官服的設定。 +4. 具備基本英文能力：需能閱讀英文日誌（Log），並能透過日誌分析缺失的圖片或資訊。 +5. 建議按任務鏈進行修改：例如針對 `Award` 任務，建議根據官服 `task.json` 的 `next` 順序，逐步替換「範本圖片」、「文字」或「修改 ROI」，確保每一步修改都能正常執行。這有助於快速定位錯誤，避免因一次改動過多而難以偵錯。 ### 修改前準備 -在進行修改之前，有幾個準備工作需要注意： +1. 參考官服 `task.json`，準備好外服專用的範本圖片與文字內容。 +2. 確保在修改過程中能隨時獲取這些素材。 -1. 參考陸服 task.json，確保你已經準備好了與陸服不同的用於外服的範本圖片和文字內容。 -2. 確保你能夠隨時獲取這些圖片和文字內容。 +## 獲取螢幕截圖 -## 獲取截圖 +為了獲取高品質的截圖，請遵循以下指南： -為了獲取高品質的截圖，請依照以下說明： +1. 使用模擬器內建的截圖工具進行擷取並儲存。 +2. 截圖尺寸需大於 `1280*720`，長寬比為 `16:9`。 +3. 截圖中不應包含無關內容（如：系統任務欄、狀態列、通知中心等）。 +4. 確保截圖涵蓋所有需要辨識的內容。 -1. 使用模擬器內建的截圖工具進行截圖並保存。 -2. 確保截圖的尺寸大於 `1280*720`，長寬比為 `16:9`。 -3. 確保截圖中不包含任何無關內容，例如任務欄、狀態欄、通知欄等。 -4. 確保截圖中包含所有需要辨識的內容。 +為了裁剪圖片並獲取文字或圖片的 `ROI`，建議使用 `MaaAssistantArknights/tools/ImageCropper` 工具。 -為了裁剪圖片並獲取文字 / 圖片 `roi`，你需要使用 `MaaAssistantArknights/tools/ImageCropper` 工具。 +**ImageCropper** 是一個功能強大的工具，支援對預先準備好的截圖或透過 ADB 連線設備進行 ROI 區域擷取、儲存及取色操作。 -**ImageCropper** 是一個強大的截圖工具，支援對預先準備好的截圖或透過 ADB 連接裝置進行 ROI 區域的截取、保存、取色操作。 +### 環境配置 -### 環境設定 +需要 `Python` 環境，推薦版本為 `3.11`，最低需求為 `3.9` 以上。 -需要 `python` 環境，推薦版本為 `3.11`，最低版本為 `3.9` 以上。 +### 安裝依賴項目 -### 安裝依賴 - -Windows 使用者推薦直接執行 `install.bat`，或手動安裝： +Windows 用戶推薦直接執行 `install.bat`，或手動安裝： ```shell python -m pip install -r requirements.txt @@ -49,23 +47,23 @@ python -m pip install -r requirements.txt ### 使用步驟 -1. 如果有預先準備好的截圖，需保存到 `./src/` 路徑下 -2. 執行 `start.bat` 或 `python main.py [device serial]`（裝置位址為可選） - - 工具會自動搜尋已連接的 ADB 裝置，根據提示選擇裝置（按 ENTER 跳過選擇） - - 也可以直接使用 `python main.py [device serial]` 連接指定裝置 -3. 在彈窗中左鍵選擇目標區域，滾輪縮放圖片，右鍵移動圖片 -4. 使用快捷鍵操作： - - 按 `S` 或 `ENTER` 保存目標區域 - - 按 `F` 保存全螢幕標準化截圖 - - 按 `R` 不保存，只輸出 ROI 範圍 - - 按 `C` 不保存，輸出 ROI 範圍和 ColorMatch 的所需欄位 - - 按 `Z`、`DELETE` 或 `BACKSPACE` 撤銷 - - 按 `0` ~ `9` 縮放視窗 - - 按 `Q` 或 `ESC` 退出 - - 按任意鍵跳過 / 更新當前截圖 -5. 目標區域截圖保存在 `./dst/` 路徑下 +1. 若有預先準備好的截圖，請存放到 `./src/` 路徑下。 +2. 執行 `start.bat` 或 `python main.py [device serial]`（設備位址為選填）。 + - 工具會自動搜尋已連線的 ADB 設備，請根據提示選擇（按 ENTER 跳過選擇）。 + - 亦可直接使用 `python main.py [device serial]` 連線指定設備。 +3. 在視窗中左鍵選擇目標區域，滾輪縮放圖片，右鍵移動圖片。 +4. 可使用快捷鍵操作： + - `S` 或 `ENTER`：儲存目標區域。 + - `F`：儲存全螢幕標準化截圖。 + - `R`：不儲存，僅在控制台輸出 ROI 範圍。 + - `C`：不儲存，輸出 ROI 範圍與 ColorMatch 所需欄位。 + - `Z`、`DELETE` 或 `BACKSPACE`：復原。 + - `0` ~ `9`：縮放視窗。 + - `Q` 或 `ESC`：退出。 + - 任意鍵：跳過或重新整理目前截圖。 +5. 裁剪後的圖片會儲存在 `./dst/` 路徑下。 -例如完成一次裁剪後的輸出內容為： +範例輸出內容： ```log src: Screenshot_xxx.png @@ -74,71 +72,65 @@ original roi: 476, 322, 77, 101, amplified roi: 426, 272, 177, 201 ``` -其中， +其中： -`Screenshot_xxx.png` 為放入 `src` 資料夾的完整截圖的名稱。`Screenshot_xxx.png_426,272,177,201.png` 為截取後的圖片。 +`Screenshot_xxx.png` 為放入 `src` 資料夾的完整截圖檔案名稱。`Screenshot_xxx.png_426,272,177,201.png` 為截取後的圖片。 -`original roi` 為滑鼠選取的區域。`amplified roi` 為擴大後的區域，你需要的是擴大後的範圍，因此在 `task.json` 中的 `roi` 欄位填入的就是這個值。 +`original roi` 為滑鼠選取的原始區域。`amplified roi` 為擴大後的區域，您在 `task.json` 中的 `roi` 欄位中應填入此數值。 ## 修改範本圖片 -在修改範本圖片之前，需要打開對應用戶端的範本圖片資料夾和陸服的範本圖片資料夾。 +在修改範本圖片之前，需要先開啟對應客戶端的範本圖片資料夾，以及官服的範本圖片資料夾。 例如： - 美服的範本圖片資料夾位置為 `MaaAssistantArknights\resource\global\YoStarEN\resource\template`。 -- 陸服的範本圖片資料夾位置為 `MaaAssistantArknights\resource\template`。 +- 官服的範本圖片資料夾位置為 `MaaAssistantArknights\resource\template`。 -參考 `task.json` 中提到的範本圖片，對比陸服和外服的範本圖片，找出外服中缺少的範本。 +請參考 `task.json` 中提到的範本圖片，對比官服和外服的範本圖片，找出外服中缺少的範本。 -通常情況下，除了標誌等圖片，包含文字的範本都需要通過截圖來替換。如果圖片尺寸明顯大於陸服的對應範本圖片，則需要修改 `roi` 的大小。 +通常情況下，除了標誌 (Logo) 等圖片外，包含文字的範本都需要透過螢幕截圖來替換。如果圖片尺寸明顯大於官服對應的範本圖片，則需要修改 `roi` 的大小。 -將截取並重新命名完成的範本圖片放入對應用戶端的範本圖片資料夾。 +將截取並重新命名完成的範本圖片，放入對應客戶端的範本圖片資料夾中。 ## 修改文字內容 -在修改文字內容之前，需要打開對應伺服器的 `task.json` 和陸服的 `task.json`。 +在修改文字內容之前，需要開啟對應客戶端的 `task.json` 與官服的 `task.json`。 例如： - 美服的 `task.json` 位置為 `MaaAssistantArknights\resource\global\YoStarEN\resource\tasks.json`。 -- 陸服的 `task.json` 位置為 `MaaAssistantArknights\resource\tasks.json`。 +- 官服的 `task.json` 位置為 `MaaAssistantArknights\resource\tasks.json`。 -找到對應任務，將 `text` 欄位修改為對應伺服器內顯示的內容。注意，辨識的內容可以是遊戲內完整內容的字串。 +找到對應任務後，將 `text` 欄位修改為該客戶端內顯示的內容。請注意，辨識內容可以是遊戲中完整內容的部分字串。 -通常情況下，除非是純 ASCII 字元辨識，否則包含文字的 `text` 都需要替換。 +通常情況下，除非是純 ASCII 字元辨識，否則包含文字的 `text` 都建議替換。若文字長度明顯大於官服（例如 `"任務"` 與 `"Mission"` 長度差距過大），則需要調整外服該任務的 `roi` 大小。 -如果文字長度明顯大於陸服，則需要修改 `roi` 的大小，如 `"任務"` 和 `"Mission"` 長度差距過大，則需要修改外服該任務 `roi` 的大小。 - -如果對應外服的 `task.json` 中沒有該任務，則需要添加任務，只需要填寫 `text` 欄位即可。 +若對應客戶端的 `task.json` 中沒有該任務，則需手動新增任務，並填寫 `text` 欄位即可。 ## 修改 ROI 範圍 -1. 打開對應伺服器的 `task.json`，如美服的位置為 `MaaAssistantArknights\resource\global\YoStarEN\resource\tasks.json` -2. 找到對應需要修改的 `roi` 範圍的任務，使用您準備好的外服遊戲介面截圖，根據 `amplified roi`，調整 `roi` 範圍的大小。 -3. 通常情況下， `roi` 不需要修改，只有和陸服的辨識內容大小差距過大時才需要修改。 -4. 如對應外服的 `task.json` 中任務不存在，則新增任務，寫上 `roi` 欄位。 +1. 開啟對應客戶端的 `task.json`（例如美服路徑： `MaaAssistantArknights\resource\global\YoStarEN\resource\tasks.json`）。 +2. 找到對應需要修改 `roi` 範圍的任務，使用您準備好的外服截圖，根據 `amplified roi` 數值來調整 `roi` 的範圍大小。 +3. 通常情況下 `roi` 不需要修改，只有當辨識內容與官服的大小差距過大時才需要調整。 +4. 若外服客戶端的 `task.json` 中該任務不存在，則手動新增並填上 `roi` 欄位。 -## 保存設定並重新啟動軟體 +## 儲存設定並重新啟動軟體 -在修改完成後，重新啟動軟體，重新載入檔案，使修改生效。 - -或在軟體目錄下新建一個 `DEBUG.txt`，這樣每次點擊開始都會重新載入範本和文件，不需要重開。 +修改完成後，重新啟動軟體以載入文件並使修改生效。或者，您也可以在軟體目錄下新建一個 `DEBUG.txt` 再開啟軟體，如此一來每次點擊「Link Start」時程式都會重新載入範本與檔案，無需反覆重啟。 檢查是否成功： -1. 檢查軟體的執行情況，確保軟體能夠在外服中正常使用。 -2. 如不能正常執行，需要檢查修改是否正確，或查看日誌輸出，進而找到出錯的地方。 +1. 檢查軟體執行狀況，確保軟體能在外服環境中正常使用。 +2. 若無法正常運作，請檢查修改內容是否正確，或查看日誌輸出來定位出錯位置。 -## 解讀日誌 +## 解讀日誌 (Log) -有些時候，我們修改完了 `task.json` 之後發現程式仍然不能正確執行，這時候我們考慮考慮查看日誌找到出錯的地方，進而修改對應任務。 +有時候修改完 `task.json` 後發現程式仍無法正確執行，此時可以透過查看日誌來找出錯誤點，進而修改對應任務。 -日誌檔的位置在軟體的根目錄下，檔案名為 `asst.log`。 +日誌檔案位於軟體根目錄下，檔名為 `asst.log`。如果您是自行編譯 MAA，則日誌會在 `\x64\Release` 或 `x64\RelWithDebInfo` 資料夾中（具體路徑視編譯模式而定）。 -如果你是自己編譯的 MAA ，則在 `\x64\Release` 或 `x64\RelWithDebInfo` ，具體在哪個資料夾取決你編譯時選擇的編譯模式。 - -下面是一段日誌範例： +以下是一段日誌範例： ```log [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"} @@ -154,23 +146,20 @@ amplified roi: 426, 272, 177, 201 [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` 代表前一個任務。 +- `taskchain`：代表目前執行中的任務鏈。 +- `details`：任務的具體內容，包含待辨識欄位 (`to_be_recognized`)、目前重試次數 (`cur_retry`) 以及總重試次數 (`retry_times`)。 +- `first`：代表任務的起始。 +- `taskid`：任務編號。 +- `class` 和 `subtask`：分別代表任務類別與子任務。 +- `pre_task`：代表前一個執行的任務。 +此外，日誌還會記錄指令的執行狀況（如 `Call`）和 `OCR` 與 OCR 辨識資訊（如 `OcrPack::recognize`）。 -此外，日誌中還會記錄命令的執行情況（如 `Call`）和 `OCR` 的資訊（如 `OcrPack::recognize`）。 +在範例日誌中，`"to_be_recognized"`,`"cur_retry":3,"retry_times":20` 表示已重複辨識 3 次（上限為 20 次），一旦達到上限就會跳過該任務並報錯。若先前的任務沒問題，基本可以確定是此處辨識出錯。此時應檢查日誌提到的任務，確認是否有對應的範本圖片檔案、`text` 文字是否正確、以及 `roi` 範圍是否精準？ -在這段日誌中 `"to_be_recognized"`,`"cur_retry":3,"retry_times":20` 表示已經重複辨識了 10 次，最大辨識次數為 20 次，到了最大辨識次數後會跳過該任務並報錯，繼續執行下一個任務。 +透過檢查對應範本圖片，若發現外服範本資料夾中有該圖片，但尺寸明顯大於官服圖片，導致官服的 `roi` 設定無法正常辨識，此時就必須修改外服客戶端的 `task.json` 中的 `roi`，使其與外服圖片大小相符。 -如果前面的任務沒有問題，我們基本可以確定是這裡的辨識出了問題，需要查看日誌中的提到的任務，尋找是否有對應的 `範本圖片`，對應任務的 `text` 是否錯誤，任務辨識 `roi` 範圍是否正確，進而找出問題所在並修改。 +## 提交您的修改 -通過查看對應範本圖片，發現美服範本圖片資料夾中有這張圖的範本，但是大小明顯大於陸服圖片，導致陸服的 `roi` 用在美服上辨識不出來，所以需要修改美服的 `task.json` 中的對應任務 `roi`，使其與美服圖片大小對應。 - -## 提交你的修改 - -請參考 [Github Pull Request 說明](../develop/pr-tutorial.md)。 +請參考 [Github Pull Request 指南](./pr-tutorial.md) \ No newline at end of file diff --git a/docs/zh-tw/develop/pr-tutorial.md b/docs/zh-tw/develop/pr-tutorial.md index bb076f2240..2a467ed176 100644 --- a/docs/zh-tw/develop/pr-tutorial.md +++ b/docs/zh-tw/develop/pr-tutorial.md @@ -5,22 +5,22 @@ icon: mingcute:git-pull-request-fill # 純網頁端 PR 教學 -牛牛也能看懂的 GitHub Pull Request 使用指南 (\*´▽｀)ノノ +牛牛也能看懂的 GitHub Pull Request 使用指南 (\*´▽ ｀)ノノ ::: warning -本教學中對很多概念進行了簡化，為了讓更多朋友能實際用起來，甚至有一些很不優雅~~但是簡單~~的操作，還有一些不那麽正確的解釋，還請大佬們輕噴。 -若您有一定的 git 使用經驗及程式基礎，~~那你還看個~~🔨，可以看稍微進階一點的教學 [Github Pull Request 流程簡述](development.md) +本教學中對許多概念進行了簡化，為了讓更多朋友能實際上手，甚至有一些不那麼「優雅」~~但簡單~~的操作，以及一些不完全精確的解釋，還請各位大神手下留情。 +若您具備一定的 Git 使用經驗及程式設計基礎，~~那你還看這個 🔨~~，可以參考進階版的教學：[GitHub Pull Request 流程簡述](./development.md)。 ::: ## 基本概念及名詞解釋 -這一章節內容略微枯燥，不感興趣可以直接跳過到下面實作部分，有不理解的再回來看 +這一章節內容略顯枯燥，如果不感興趣可以直接跳到下面的實作部分，遇到不理解的地方再回來查看。 ### Repository（倉庫） -簡稱 repo，存放我們代碼及其他資源檔案的地方 +簡稱 Repo 或倉庫，是存放程式碼及其他資源檔案的地方。 -👇 可以簡單理解為目前這個網頁及裡面所有的內容，就是 MAA 的倉庫（我們一般稱之為 MAA 的主倉庫） +👇 可以簡單理解為目前這個網頁及其所有內容，就是 MAA 的倉庫（我們一般稱之為 MAA 的主倉庫）。 -2. 把 “僅 master 分支” 這個選項去掉，然後點擊 Create Fork +2. 接著直接點擊 Create Fork。 -3. 接下來來到了你的個人倉庫，可以看到標題是 “你的名字/MaaAssistantArknights”，下面一行小字 forked from MaaAssistantArknights/MaaAssistantArknights （複製自 MAA 主倉庫） +3. 現在來到了您的個人倉庫，標題會顯示為 `您的帳號名稱/MaaAssistantArknights`，下方會有一行小字標註 `forked from MaaAssistantArknights/MaaAssistantArknights`（複製自 MAA 主倉庫）。 -4. 找到你要改的檔案，可以點 “Go to file” 進行全局搜尋，也可以直接在下面的資料夾裡翻（如果你知道檔案在哪的話） +4. 找到要修改的檔案。可以點擊 Go to file 進行全域搜尋，如果您知道文件在哪裡的話，也可以直接在下方的資料夾翻找。 -5. 打開檔案後，直接點擊檔案右上角的 ✏️ 進行編輯 +5. 開啟檔案後，點擊右上角的 ✏️ 按鈕進行編輯。 -6. 開改！（當然如果是資源檔案這種，我們建議先在你電腦上的 MAA 資料夾裡測試修改，確認沒問題了再貼上到網頁上，避免改錯了） -7. 改完了，翻到最下面，寫一下你改了啥 +6. 開始修改！（如果是資源檔案，建議先在電腦上的 MAA 資料夾測試，確認沒問題後再貼到網頁上，以免改錯）。 + +7. 修改完成後，點擊右上角的 👇 這個按鈕開啟提交頁面，並寫下您的修改說明。 + 我們有一套簡單的提交標題[命名格式](https://www.conventionalcommits.org/zh-hans/v1.0.0/)，建議盡量遵守；若暫時無法理解，也可以先簡單描述。 + -8. 還有第二個檔案要改的？改完了發現弄錯了想再改改？都沒關係！重複 5-8 即可！ -9. 全改好了進行 PR ！直接點 **個人倉庫** 裡的 Pull Request 標籤頁 - 如果有 Compare & Pull Request 按鈕，那最好，直接點他！如果沒有也不用著急，點下面的 New Pull Request 也是一樣的（請看步驟 11） +8. 還有其他檔案要改？或是發現改錯了想再修補？沒關係！重複步驟 4-7 即可。 + +9. 全部改好後，準備發起 PR！點擊 Code 回到**個人倉庫**首頁。 + 如果有出現 Compare & Pull Request 按鈕，請直接點擊它；若沒看到，點擊下方的 Contribute（貢獻）按鈕，再點 Open Pull Request 也是一樣的。 -10. 這時候來到了主倉庫，請核對一下你要 PR 的是否確認。 - 如圖中，中間有個向左的箭頭，是將右邊的 個人姓名/MAA 的 dev 分支，申請合併到 主倉庫/MAA 的 dev 分支。 +10. 此時會進入主倉庫的 PR 頁面，請核對提交內容是否正確。 + 如下圖所示，箭頭方向是將右側「您的帳號 / MAA」的 `dev` 分支合併到「主倉庫 / MAA」的 `dev` 分支。頁面下方會顯示兩者間的差異。 - 然後寫一下標題，你修改的具體內容等等的，然後點確認 + 接著填寫標題與具體修改內容，最後點擊確認。 + PR 標題同樣建議遵循[命名格式](https://www.conventionalcommits.org/zh-hans/v1.0.0/)。 -11. 等待 MAA Team 的大佬們審核吧！當然他們也可能會提意見 - 👇 比如（純屬娛樂切勿當真） +11. 接下來請耐心等待 MAA Team 的審核！當然他們可能也會提出自己的意見。 + 👇 比如（純屬娛樂，請勿當真） + { + light: 'images/zh-cn/pr-tutorial/pr-11-light.png', + dark: 'images/zh-cn/pr-tutorial/pr-11-dark.png' + } + ]" /> -12. 如果大佬們說要再修改一些小問題的話，回到 **你的個人倉庫**，切換到先前的 dev 分支，重複 步驟 3-9 即可！ - 注意不需要操作步驟 2（重新 fork），也不需要操作步驟 10（重新 Pull Request），你目前的 Pull Request 仍處於待審核狀態，後續的修改會直接進入到這個 Pull Request 中 - 👇 比如可以看到最下面多了一條 “重新修改演示” 的內容 +12. 若大佬要求針對細節進行修正，請回到**您的個人倉庫**，重複步驟 4-7 即可。 + 請注意，不需要重新 Fork（步驟 1-2）或重新發起 PR（步驟 9-10）。您目前的 PR 仍處於開啟狀態，後續的修改會自動更新到同一個 PR 中。 + 👇 可以看到最下面多了一條「重新修改演示」的內容 + { + light: 'images/zh-cn/pr-tutorial/pr-12-light.png', + dark: 'images/zh-cn/pr-tutorial/pr-12-dark.png' + } + ]" /> -13. 等大佬們審批通過，就全部完成啦！**版本發布後**，你的 GitHub 頭像將會自動進入到貢獻者列表名單中，非常感謝各位的無私奉獻！ - ~~怎麽全是二次元啊，哦我也是啊，那沒事了~~ - ::: tip 貢獻 / 參與者 - 感謝所有參與到開發 / 測試中的朋友們，是大家的幫助讓 MAA 越來越好！ (\*´▽｀)ノノ +13. 當大佬們審核通過並被合併（Merged）後，就大功告成了！您的修改已正式進入 MAA 主倉庫。 - [![Contributors](https://contributors-img.web.app/image?repo=MaaAssistantArknights/MaaAssistantArknights&max=105&columns=15)](https://github.com/MaaAssistantArknights/MaaAssistantArknights/graphs/contributors) - ::: - -14. 下次如果還想提別的 PR，請先切換到 dev 分支，然後直接如下圖操作 - ::: warning - 這個操作會強制將你的個人倉庫同步到和主倉庫一模一樣的狀態，這是最簡單粗暴但行之有效的解決衝突的方法。但如果你的個人倉庫已經有額外的編輯了，會被直接刪掉！ - ::: - 如果確定不會造成衝突，請使用右側綠色的 `Update Branch` 按鈕 - - 如果你不清楚 / 不 care 我上面說的這一大堆，也請點擊左側的按鈕 +14. 下次若想再發起新的 PR，請先回到個人倉庫首頁，點擊 Sync fork 讓您的倉庫與主倉庫同步。 + 注意：若出現紅色的 Discard 1 commit，請優先點擊它；若無，則點擊綠色的 Update branch。接著即可重複步驟 4-10 進行新的修改。 - 接著重複步驟 3-14，修改、提 PR 即可 ~ +在**版本發布後**，您的 GitHub 頭像將會自動出現在貢獻者名單中。非常感謝您的無私奉獻！ +~~怎麼全是二次元啊，哦我也是，那沒事了~~ +::: tip 貢獻/參與者 +感謝所有參與開發與測試的朋友，是大家的幫助讓 MAA 變得更好！ (\*´▽ ｀)ノノ + +[![Contributors](https://contributors-img.web.app/image?repo=MaaAssistantArknights/MaaAssistantArknights&max=105&columns=15)](https://github.com/MaaAssistantArknights/MaaAssistantArknights/graphs/contributors) +::: \ No newline at end of file diff --git a/docs/zh-tw/develop/vsc-ext-tutorial.md b/docs/zh-tw/develop/vsc-ext-tutorial.md index 24ea186114..6ffb90d8bf 100644 --- a/docs/zh-tw/develop/vsc-ext-tutorial.md +++ b/docs/zh-tw/develop/vsc-ext-tutorial.md @@ -3,129 +3,127 @@ order: 8 icon: iconoir:code-brackets --- -# 專用 VSCode 插件教學 +# 專用 VSCode 擴充功能教學 -該插件針對 MaaAssistantArknights/MaaFramework 提供了一系列方便開發的能力，包括但不限於以下功能： +此擴充功能針對 MaaAssistantArknights/MaaFramework 提供了一系列便利開發的功能，包括但不限於以下項目： -- tasks.json 支持，包含 `template 預覽`，`next 跳轉`，`任務引用` 等等 -- 截取/裁剪圖片 +- `tasks.json` 支援：包含 `template 預覽`、`next 跳轉`、`任務引用` 等。 +- 擷取與裁剪圖片。 -具體內容可以前往 [插件商店](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support) 或是 [倉庫](https://github.com/neko-para/maa-support-extension) 查看 +具體詳細內容可以前往 [擴充功能商店](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support) 或 [GitHub 倉庫](https://github.com/neko-para/maa-support-extension) 查看。 ## 安裝 -推薦直接在 VSCode 的插件列表中搜索 `Maa` 來安裝 +推薦直接在 VSCode 的擴充功能清單中搜尋 `Maa` 進行安裝。 ::: tip -首次使用時, 插件會自動下載預設版本的資源 -搜索命令 `Maa: 選擇下載源`, 可切換下載源 (npm / cnpm) +首次使用時，擴充功能會自動下載預設版本的資源。 +搜尋命令 `Maa: 選擇下載源`，可切換下載來源（npm / cnpm）。 ::: -## 功能 +## 功能介紹 ### 控制面板 -左側添加了專用控制面板, 圖示 ![MaaSupport ControlPanel](/images/maa-support-panel.svg) +左側活動列添加了專用控制面板，圖示如下： ![MaaSupport ControlPanel](/images/maa-support-panel.svg) -插件的絕大部分功能均基於 `interface.json` 配置. 在控制面板最頂部可以選擇生效的 `interface.json`. +擴充功能絕大部分的功能皆基於 `interface.json` 配置。在控制面板最上方可以選擇目前生效的 `interface.json`。 -插件有 `Maa` 相容模式. 當在打開文件夾下檢測到存在 `src/MaaCore` 文件夾時, 會自動啟用. +此外，擴充功能具備 `Maa` 相容模式。當在開啟的資料夾下偵測到 `src/MaaCore` 資料夾時，系統會自動啟用該模式。 ### 語義化資源分析 -通過切換控制面板中的 `資源` 下拉框, 選擇預期的資源. 插件會根據對應路徑來進行索引和診斷. +透過切換控制面板中的「資源」下拉選單選擇預期資源，擴充功能會根據對應路徑進行索引與診斷。 -如果發現想要編輯的 json 文件沒有插件提示, 請檢查是否啟用的資源並沒有包含該文件. +若發現想編輯的 JSON 檔案沒有出現提示，請檢查目前啟動的資源是否包含該檔案。 -> 所謂 `任務的定義`, 指任務對象的鍵 +> 所謂「任務的定義」，是指任務物件中的鍵 (Key)。 > -> 所謂 `任務的引用`, 指其它任務中可以填入任務名稱的值 (例如 `next` 中) +> 所謂「任務的引用」，是指其他任務中可以填入任務名稱的值 (Value)（例如 `next` 欄位中）。 -#### 查詢任務定義/引用 +#### 查詢任務定義與引用 -插件支持跳轉到定義, 跳轉到引用, 查看任務定義. +擴充功能支援跳轉至定義、跳轉至引用，以及查看任務定義。 -開啟 `Maa` 相容模式時, 可以解析 `模板任務`, 支持同步基類查詢任務定義和引用; 懸停任務定義, 可以查看同名圖片。 +開啟 `Maa` 相容模式時，可解析 `範本任務`，支援連動父類別查詢任務定義與引用；懸停在任務定義上時，可查看同名的範本圖片。 -使用 `Ctrl+T` 快捷鍵，可以快速查詢並跳轉任務定義。 +使用 `Ctrl + T` 快捷鍵，可快速搜尋並跳轉至任務定義。 -#### 查詢/打開圖片 +#### 查詢與開啟圖片 -插件支持打開圖片. +擴充功能支援直接開啟圖片。 -開啟 `Maa` 相容模式時, 允許圖片路徑進行遞迴搜索. +開啟 `Maa` 相容模式時，支援圖片路徑的遞迴搜尋。 -#### 補全任務 +#### 任務自動補全 -插件支持根據所有已知任務進行自動補全. +擴充功能支援根據所有已知任務進行自動補全。 -開啟 `Maa` 相容模式時, 輸入 `@` 將會觸發補全. +開啟 `Maa` 相容模式時，輸入 `@` 符號將觸發補全選單。 -#### 補全圖像路徑 +#### 補全圖片路徑 -插件支持根據所有已知圖片路徑進行自動補全. +擴充功能支援根據所有已知圖片路徑進行自動補全。 -開啟 `Maa` 相容模式時, 允許圖片路徑進行遞迴搜索. +開啟 `Maa` 相容模式時，支援圖片路徑的遞迴搜尋。 -#### 校驗任務/圖像路徑 +#### 校驗任務與圖片路徑 -插件支持定時掃描並分析所有任務. +擴充功能支援定時掃描並分析所有任務： -- 檢查是否有重名任務定義 -- 檢查是否有未知任務引用 -- 檢查是否有未知圖片引用 -- 檢查單個任務中是否有重複的任務引用 +- 檢查是否有重複命名的任務定義。 +- 檢查是否有未知的任務引用。 +- 檢查是否有未知的圖片引用。 +- 檢查單一任務中是否有重複的任務引用。 -#### 多路徑資源支持 +#### 多路徑資源支援 -插件支持資源包含多個路徑, 會按照指定順序進行邏輯覆蓋, 即後載入的可以引用到前載入的內容. +擴充功能支援資源包含多個路徑，並會按照指定順序進行邏輯覆蓋，即後載入的內容可以引用到先載入的內容。 -### 計算任務 / 任務列表表達式 (僅 Maa) +### 計算任務 / 任務列表運算式 (僅限 MAA) -通過控制面板, 可以計算任務實際展開的內容, 以及每一項的來源; 可以計算任務列表表達式展開的結果 +透過控制面板，可以計算任務實際展開的內容及其每一項的來源，亦可計算任務列表運算式展開後的結果。 -### MaaPiCli 功能 (僅 MaaFramework 項目) +### MaaPiCli 功能 (僅限 MaaFramework 專案) -通過控制面板, 可以掃描並選擇控制器, 選擇資源, 添加並管理任務, 以及執行任務. +透過控制面板，可以掃描並選擇控制器、選擇資源、添加並管理任務，以及執行任務。 -### 截圖裁剪 / 快速識別 +### 截圖裁剪與快速辨識 -在 VSCode 的命令面板中搜索執行 `Maa: 打開截圖工具`, 可打開 `截圖 / 裁剪` 面板. +在 VSCode 的命令面板中搜尋並執行 `Maa: 開啟截圖工具`，即可開啟 `截圖 / 裁剪` 面板。 -> 使用 `Ctrl+Shift+P` (MacOS 上則是 `Command+Shift+P`) 呼出命令面板 +> 使用 `Ctrl + Shift + P` (macOS 為 `Command + Shift + P`) 呼叫命令面板。 -- 選擇並連接控制器後, 可使用 `截圖` 按鈕直接獲取截圖 -- 可使用 `上傳` 按鈕手動上傳 -- 按住 `Ctrl` 鍵, 框選需要裁剪的區域 -- 使用滾輪可進行縮放 -- 裁剪完成後, 使用 `下載` 按鈕, 可自動將裁剪結果保存到啟用資源的最頂層的圖片目錄 -- 使用 `複製` 按鈕，可將 ROI 以陣列的形式複製到剪貼簿 -- 按下 `工具` 按鈕，將開啟識別工具面板，可以直接對目前圖片進行識別測試 +- 選擇並連線控制器後，可使用「截圖」按鈕直接獲取螢幕截圖。 +- 可使用 `上傳` 按鈕手動上傳圖片。 +- 按住 `Ctrl` 鍵，框選需要裁剪的區域。 +- 使用滑鼠滾輪可進行縮放。 +- 裁剪完成後，使用 `下載` 按鈕，可自動將裁剪結果儲存至啟動資源中最頂層的圖片目錄。 +- 使用 `複製` 按鈕，可將 ROI 以陣列形式複製到剪貼簿。 +- 按下 `工具` 按鈕將開啟辨識工具面板，可直接對當前圖片進行辨識測試。 ::: warning +若 OCR 的辨識結果為空，請檢查 [OCR 模型](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#%E6%96%87%E5%AD%97%E8%AF%86%E5%88%AB%E6%A8%A1%E5%9E%8B%E6%96%87%E4%BB%B6) 是否配置正確。 -如果 OCR 的識別結果為空, 請檢查 [OCR 模型](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#%E6%96%87%E5%AD%97%E8%AF%86%E5%88%AB%E6%A8%A1%E5%9E%8B%E6%96%87%E4%BB%B6) 是否已正確配置. - -對於 MAA, 插件將自動維護使用的模型, 只需要選擇正確的資源即可. - +針對 MAA，擴充功能將自動維護所使用的模型，您只需要選擇正確的資源即可。 ::: ### 日誌查看功能 #### MaaFramework 日誌 -在 VSCode 的命令面板中搜索執行 `Maa: 打開maa日誌`, 可查看調試期間產生的 `maa.log` 日誌. +在 VSCode 的命令面板中搜尋並執行 `Maa: 開啟 maa 日誌`，可查看偵錯期間產生的 `maa.log` 日誌。 -#### Maa Pipeline Support 擴充日誌 +#### MAA Pipeline Support 擴充功能日誌 -在 VSCode 的命令面板中搜索執行 `Maa: 打開插件日誌`, 可查看調試期間產生的 `mse.log` 日誌. +在 VSCode 的命令面板中搜尋並執行 `Maa: 開啟插件日誌`，可查看擴充功能運作期間產生的 `mse.log` 日誌。 -### 底部狀態欄 +### 底部狀態列 -#### MaaSupport <插件版本> +#### MaaSupport <擴充功能版本> -點擊可聚焦控制面板 +點擊可聚焦至控制面板。 #### MaaFramework -點擊可切換插件使用的 `MaaFramework` 版本。其中，可選擇的版本被限制為當前插件所支持的版本，如果列表中沒有你需要的版本，請考慮更換插件版本。 +點擊可切換擴充功能使用的 `MaaFramework` 版本。可選擇的版本受限於當前擴充功能支援的範圍，若清單中沒有需要的版本，請考慮更換擴充功能之版本。 \ No newline at end of file diff --git a/docs/zh-tw/manual/README.md b/docs/zh-tw/manual/README.md index 66ee83e635..1d5e4c9f86 100644 --- a/docs/zh-tw/manual/README.md +++ b/docs/zh-tw/manual/README.md @@ -1,9 +1,9 @@ --- -title: 用戶說明書 +title: 使用手冊 icon: mdi:user index: false dir: order: 1 --- - + \ No newline at end of file diff --git a/docs/zh-tw/manual/cli/README.md b/docs/zh-tw/manual/cli/README.md index 8e666b0b8a..efde3b0d4d 100644 --- a/docs/zh-tw/manual/cli/README.md +++ b/docs/zh-tw/manual/cli/README.md @@ -1,21 +1,17 @@ --- -title: CLI 使用說明 +title: CLI 使用指南 icon: material-symbols:terminal index: true dir: order: 6 --- -::: important Translation Required -This page is outdated and maybe still in Simplified Chinese. Translation is needed. -::: - -一个使用 Rust 编写的简单 MAA 命令行工具。 +一個使用 Rust 編寫的簡單 MAA 命令列工具。 ## 功能 -- 运行预定义或自定义的任务，例如 `maa fight`，`maa run `; -- 使用 `maa install` 和 `maa update` 安装和更新MaaCore及资源； +- 執行預定義或自定義的任務，例如 `maa fight`、`maa run `。 +- 使用 `maa install` 和 `maa update` 安裝和更新 MaaCore 及資源。 - 使用 `maa self update` 更新自身。 - + \ No newline at end of file diff --git a/docs/zh-tw/manual/cli/config.md b/docs/zh-tw/manual/cli/config.md index e288a54287..e3abf67379 100644 --- a/docs/zh-tw/manual/cli/config.md +++ b/docs/zh-tw/manual/cli/config.md @@ -5,95 +5,91 @@ icon: material-symbols:settings # 配置 -::: important Translation Required -This page is outdated and maybe still in Simplified Chinese. Translation is needed. -::: +## 配置目錄 -## 配置目录 +maa-cli 配置檔案位於特定的配置目錄中，您可以透過 `maa dir config` 獲取配置目錄路徑。配置目錄也可以透過環境變數 `MAA_CONFIG_DIR` 更改。在下文的範例中，我們將以 `$MAA_CONFIG_DIR` 代表配置目錄。 -maa-cli 配置文件位于特定的配置目录中，你可以通过 `maa dir config` 获取配置目录。配置目录也可以通过环境变量 `MAA_CONFIG_DIR` 更改。在下面的例子中，我们将用 `$MAA_CONFIG_DIR` 来表示配置目录。 +所有的配置檔案皆可使用 TOML、YAML 或 JSON 格式。在下文範例中，我們將使用 TOML 格式並以 `.toml` 作為副檔名，但您可以根據需求混合使用這三種格式，只要副檔名正確即可。 -所有的配置文件都可以使用 TOML，YAML 或者 JSON 格式，在下面的例子中，我们将使用 TOML 格式，并使用 `.toml` 作为文件扩展名。但是你可以混合这三种格式中的任意一种，只要你的文件扩展名正确。 +此外，部分任務接受 `filename` 作為參數。若您使用相對路徑，該路徑將相對於配置目錄下的對應子目錄。例如：自定義基建計畫檔案的相對路徑應相對於 `$MAA_CONFIG_DIR/infrast`，而保全派駐的作業檔案則相對於 `$MAA_CONFIG_DIR/ssscopilot`。 -此外，部分任务接受 `filename` 作为参数，如果你使用相对路径，那么相对路径将会相对于配置目录的对应子目录。比如自定义基建计划文件的相对路径应该相对于 `$MAA_CONFIG_DIR/infrast`，而保全派驻的作业文件则相对于 `$MAA_CONFIG_DIR/ssscopilot`。 +## 自定義任務 -## 自定义任务 +每一個自定義任務都是獨立的檔案，應存放於 `$MAA_CONFIG_DIR/tasks` 目錄中。 -每一个自定义任务都是一个单独的文件，它们应该位于 `$MAA_CONFIG_DIR/tasks` 目录中。 +### 基本結構 -### 基本结构 - -一个任务文件包含多个子任务，每一个子任务是一个 MAA 任务，其包含一下几个选项： +一個任務檔案包含多個子任務，每個子任務都是一個 MAA 任務，包含以下選項： ```toml [[tasks]] -name = "启动游戏" # 任务的名字，可选，默认为任务类型 -type = "StartUp" # 任务的类型 -params = { client_type = "Official", start_game_enabled = true } # 对应任务的参数 +name = "啟動遊戲" # 任務名稱，選填，預設為任務類型 +type = "StartUp" # 任務類型 +params = { client_type = "Official", start_game_enabled = true } # 對應任務的參數 ``` -具体的任务类型和参数可以在 [MAA 集成文档][task-types] 中找到。注意，目前 maa-cli 并不会验证参数名和参数值是否正确，即使出错也不会产生任何错误信息，除非 MaaCore 在运行时检测到错误。 +具體的任務類型與參數可以參考 [MAA 整合文件][task-types]。請注意，目前 maa-cli 不會驗證參數名稱與數值是否正確，即使出錯也不會產生任何錯誤訊息，除非 MaaCore 在執行時偵測到錯誤。 -### 任务条件 +### 任務條件 -如果你想要根据一些条件运行不同参数的任务，你可以定义多个任务的变体： +如果您想要根據某些條件執行不同參數的任務，您可以定義多個任務的變體： ```toml [[tasks]] -name = "基建换班" +name = "基建換班" type = "Infrast" [tasks.params] mode = 10000 facility = ["Trade", "Reception", "Mfg", "Control", "Power", "Office", "Dorm"] dorm_trust_enabled = true -filename = "normal.json" # 自定义的基建计划的文件名应该位于`$MAA_CONFIG_DIR/infrast` +filename = "normal.json" # 自定義的基建計畫檔案名稱應位於 `$MAA_CONFIG_DIR/infrast` -# 在 18:00:00到第二天的 04:00:00 使用计划 0，在 12:00:00 之前使用计划 1，之后使用计划 2 +# 在 18:00:00 到隔天的 04:00:00 使用計畫 0，在 12:00:00 之前使用計畫 1，之後使用計畫 2 [[tasks.variants]] -condition = { type = "Time", start = "18:00:00", end = "04:00:00" } # 当结束时间小于开始时间时，结束时间被视为第二天的时间 +condition = { type = "Time", start = "18:00:00", end = "04:00:00" } # 當結束時間小於開始時間時，結束時間被視為隔天的時間 params = { plan_index = 0 } [[tasks.variants]] -condition = { type = "Time", end = "12:00:00" } # 如果开始时间被省略，那么只要当前时间小于结束时间时，这个条件就会被匹配 +condition = { type = "Time", end = "12:00:00" } # 如果省略開始時間，那麼只要目前時間小於結束時間，這個條件就會被匹配 params = { plan_index = 1 } [[tasks.variants]] -condition = { type = "Time", start = "12:00:00" } # 如果结束时间被省略，那么只要当前时间大于开始时间时，这个条件就会被匹配 +condition = { type = "Time", start = "12:00:00" } # 如果省略結束時間，那麼只要目前時間大於開始時間，這個條件就會被匹配 params = { plan_index = 2 } ``` -这里的 `condition` 字段用于确定哪一个变体应该被使用，而匹配的变体的 `params` 字段将会被合并到任务的参数中。 +這裡的 `condition` 欄位用於確定應使用哪一個變體，而匹配成功的變體其 `params` 欄位將會被合併到任務的參數中。 -**注意**：如果你的自定义基建计划文件使用相对路径，应该相对于 `$MAA_CONFIG_DIR/infrast`。此外，由于基建文件是由 MaaCore 而不是 maa-cli 读取的，因此这些文件的格式必须是 JSON。同时，maa-cli 不会读取基建文件，也不会根据其中定义的时间段来选择相应的子计划。因此，必须通过 `condition` 字段来指定在相应时间段使用正确的基建计划的参数中的 `plan_index` 字段。这样可以确保在适当的时间段使用正确的基建计划。 +**請注意**：如果您的自定義基建計畫檔案使用相對路徑，應該相對於 `$MAA_CONFIG_DIR/infrast`。此外，由於基建檔案是由 MaaCore 而非 maa-cli 讀取的，因此這些檔案的格式必須是 JSON。同時，maa-cli 不會讀取基建檔案，也不會根據其中定義的時間段來選擇對應的子計畫。因此，必須透過 `condition` 欄位來指定在對應時間段使用正確的基建計畫參數中的 `plan_index` 欄位。這樣可以確保在適當的時間段使用正確的基建計畫。 -除了 `Time` 条件，还有 `DateTime`，`Weekday`，`DayMod`条件。`DateTime` 条件用于指定一个时间段，`Weekday` 条件用于指定一周中的某些天，`DayMod` 用于指定一个自定义周期的某些天。 +除了 `Time` 條件，還有 `DateTime`，`Weekday`，`DayMod` 條件。`DateTime` 條件用於指定一個時間段，`Weekday` 條件用於指定一週中的某些天，`DayMod` 用於指定一個自定義週期的某些天。 ```toml [[tasks]] type = "Fight" -# 在夏活期间，刷SL-8 +# 在夏活期間，刷 SL-8 [[tasks.variants]] params = { stage = "SL-8" } condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } -# 在夏活期间以外的周二、周四和周六，刷CE-6 +# 在夏活期間以外的週二、週四和週六，刷 CE-6 [[tasks.variants]] condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"], timezone = "Official"} params = { stage = "CE-6" } -# 其他时间，刷1-7 +# 其他時間刷 1-7 [[tasks.variants]] params = { stage = "1-7" } ``` -对与上述所有时间相关的条件，其都可以通过 `timezone` 参数来指定时区，这个参数的值可以是一个数字，表示与 UTC 的偏移量，如果你的时区是东八区，那么你可以指定 `timezone = 8`。这个参数也可以是一个客户端类型，比如 `timezone = "Official"`，这样将会使用官服对应的服务器时间来判断。**注意**，官服的时区不是东八区而是东四区，因为游戏中每天开始时间是 04:00:00 而不是 00:00:00。如果不指定时区，那么直接使用你的本地时区。 +對於上述所有與時間相關的條件，都可以透過 `timezone` 參數來指定時區，這個參數的值可以是一個數字，表示與 UTC 的偏移量，如果您的時區是東八區，那麼您可以設定 `timezone = 8`。這個參數也可以是一個客戶端類型，例如 `timezone = "Official"`，這樣將會使用官服對應的伺服器時間來判斷。**注意**，官服的時區不是東八區而是東四區，因為遊戲中每天開始時間是 04:00:00 而不是 00:00:00。如果不指定時區，那麼直接使用您的本地時區。 -除了上述确定的条件之外，还有一个依赖于热更新资源的条件 `OnSideStory`，当你启动该条件后，maa-cli 会尝试读取相应的资源来判断当前是否有正在开启的活动，如果有那么对应的变体会被匹配。 比如上述夏活期间刷 `SL-8` 的条件就可以简化为 `{ type = "OnSideStory", client = "Official" }`，这里的 `client` 参数用于确定你使用的客户端，因为不同的客户端的活动时间不同，对于使用官服或者 b 服的用户，这可以省略。通过这个条件，每次活动更新之后你可以只需要更新需要刷的关卡而不需要手动编辑对应活动的开放时间。 +除了上述確定的條件之外，還有一個依賴於熱更新資源的條件 `OnSideStory`，當您啟用該條件後，maa-cli 會嘗試讀取對應的資源來判斷目前是否有正在開啟的活動，如果有，那麼對應的變體會被匹配。例如上述夏活期間刷 `SL-8` 的條件就可以簡化為 `{ type = "OnSideStory", client = "Official" }`，這裡的 `client` 參數用於確定您使用的客戶端，因為不同客戶端的活動時間不同，對於使用官服或 B 服的使用者，這可以省略。透過這個條件，每次活動更新之後，您只需要更新需要刷的關卡，而不需要手動編輯對應活動的開放時間。 -除了以上基础条件之外，你可以使用 `{ type = "And", conditions = [...] }`，`{ type = "Or", conditions = [...] }`, `{ type = "Not", condition = ... }` 来对条件进行逻辑运算。 -对于想要基建多天排班的用户，可以将 `DayMod` 和 `Time` 组合使用，可以实现多天排班。比如，你想要实现每两天换六次班，那么你可以这样写： +除了以上基礎條件之外，您可以使用 `{ type = "And", conditions = [...] }`，`{ type = "Or", conditions = [...] }`, `{ type = "Not", condition = ... }` 來對條件進行邏輯運算。 +對於想要基建多天排班的使用者，可以將 `DayMod` 和 `Time` 組合使用，實現多天排班。例如，您想要實現每兩天換六次班，那麼您可以這樣寫： ```toml [[tasks]] @@ -112,12 +108,12 @@ params = { plan_index = 0 } [tasks.variants.condition] type = "And" conditions = [ - # 这里的 divisor 用来指定周期，remainder 用来指定偏移量 - # 偏移量等于 num_days_since_ce % divisor - # 这里的 num_days_since_ce 是公元以来的天数，0001-01-01 是第一天 - # 当天偏移量你可以通过 `maa remainder ` 来获取. - # 比如，2024-1-27 是第 738,912 天，那么 738912 % 2 = 0 - # 当天的偏移量为 0，那么本条件将会被匹配 + # 這裡的 divisor 用來指定週期，remainder 用來指定偏移量 + # 偏移量等於 num_days_since_ce % divisor + # 這裡的 num_days_since_ce 是公元以來的天數，0001-01-01 是第一天 + # 當天偏移量您可以透過 `maa remainder ` 來獲取. + # 比如，2024-1-27 是第 738,912 天，那麼 738912 % 2 = 0 + # 當天的偏移量為 0，那麼本條件將會被匹配 { type = "DayMod", divisor = 2, remainder = 0 }, { type = "Time", start = "04:00:00", end = "12:00:00" }, ] @@ -136,9 +132,9 @@ conditions = [ [[tasks.variants]] params = { plan_index = 2 } [tasks.variants.condition] -# 注意这里必须使用 Or 条件，不能直接使用 Time { start = "20:00:00", end = "04:00:00" } -# 在这种情况下， 第二天的 00:00:00 - 04:00:00 不会被匹配 -# 当然通过调整你的排班时间避免跨天是更好的选择，这里只是为了演示 +# 注意這裡必須使用 Or 條件，不能直接使用 Time { start = "20:00:00", end = "04:00:00" } +# 在這種情況下，第二天的 00:00:00 - 04:00:00 不會被匹配 +# 當然透過調整您的排班時間避免跨天是更好的選擇，這裡只是為了演示 type = "Or" conditions = [ { type = "And", conditions = [ @@ -188,16 +184,16 @@ conditions = [ ] ``` -在默认的策略下，如果有多个变体被匹配，第一个将会被使用。如果没有给出条件，那么变体将会总是被匹配，所以你可以把没有条件的变体放在最后，作为默认的情况。 +在預設策略下，如果有多個變體被匹配，第一個將會被使用。如果沒有給出條件，那麼變體將會總是被匹配，所以您可以把沒有條件的變體放在最後，作為預設的情況。 -你可以使用 `strategy` 字段来改变匹配策略： +您可以使用 `strategy` 欄位來改變匹配策略： ```toml [[tasks]] type = "Fight" -strategy = "merge" # 或者 "first" (默认) +strategy = "merge" # 或者 "first" (預設) -# 在周天晚上使用所有的将要过期的理智药 +# 在週日晚上使用所有將要過期的理智藥 [[tasks.variants]] params = { expiring_medicine = 1000 } @@ -208,27 +204,27 @@ conditions = [ { type = "Weekday", weekdays = ["Sun"] }, ] -# 默认刷1-7 +# 預設刷 1-7 [[tasks.variants]] params = { stage = "1-7" } -# 在周二、周四和周六，刷CE-6 +# 在週二、週四和週六，刷 CE-6 [[tasks.variants]] condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] } params = { stage = "CE-6" } -# 在夏活期间，刷SL-8 +# 在夏活期間，刷 SL-8 [[tasks.variants]] params = { stage = "SL-8" } condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } ``` -这个例子和上面的例子将刷同样的关卡，但是在周天晚上，将会使用所有的将要过期的理智药。在 `merge` 策略下，如果有多个变体被匹配，后面的变体的参数将合并入前面的变体的参数中。如果多个变体都有相同的参数，那么后面的变体的参数将会覆盖前面的变体的参数。 +這個範例和上面的範例將刷同樣的關卡，但是在週日晚上，將會使用所有將要過期的理智藥。在 `merge` 策略下，如果有多個變體被匹配，後面的變體參數將合併入前面變體的參數中。如果多個變體都有相同的參數，那麼後面變體的參數將會覆蓋前面變體的參數。 -如果没有变体被匹配，那么任务将不会被执行，这可以用于只在特定的条件下运行子任务： +如果沒有變體被匹配，那麼任務將不會被執行，這可以用於只在特定的條件下執行子任務： ```toml -# 只在在18:00:00之后进行信用商店相关的操作 +# 只在 18:00:00 之後進行信用商店相關的操作 [[tasks]] type = "Mall" @@ -236,59 +232,59 @@ type = "Mall" condition = { type = "Time", start = "18:00:00" } ``` -### 用户输入 +### 使用者輸入 -对于一些任务，你可能想要在运行时输入一些参数，例如关卡名称。 你可以将对应需要输入的参数设置为 `Input` 或者 `Select` 类型： +對於一些任務，您可能想要在執行時輸入一些參數，例如關卡名稱。您可以將對應需要輸入的參數設定為 `Input` 或者 `Select` 類型： ```toml [[tasks]] type = "Fight" -# 选择一个关卡 +# 選擇一個關卡 [[tasks.variants]] condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } [tasks.variants.params.stage] -# 可选的关卡，必须提供至少一个可选值 -# 可选值可以是一个值，也可以是同时包含值和描述的一个表 +# 可選的關卡，必須提供至少一個可選值 +# 可選值可以是一個值，也可以是同時包含值和描述的一個表 alternatives = [ - "SL-7", # 将被显示为 "1. SL-7" - { value = "SL-8", desc = "轻锰矿" } # 将被显示为 "2. SL-8 (轻锰矿)" + "SL-7", # 將被顯示為 "1. SL-7" + { value = "SL-8", desc = "輕錳礦" } # 將被顯示為 "2. SL-8 (輕錳礦)" ] -default_index = 1 # 默认值的索引，从 1 开始，如果没有设置，输入空值将会重新提示输入 -description = "a stage to fight in summer event" # 描述，可选 -allow_custom = true # 是否允许输入自定义的值，默认为 false，如果允许，那么非整数的值将会被视为自定义的值 +default_index = 1 # 預設值的索引，從 1 開始，如果沒有設定，輸入空值將會重新提示輸入 +description = "a stage to fight in summer event" # 描述，選填 +allow_custom = true # 是否允許輸入自定義的值，預設為 false，如果允許，那麼非整數的值將會被視為自定義的值 -# 无需任何输入 +# 無需任何輸入 [[tasks.variants]] condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] } params = { stage = "CE-6" } -# 输入一个关卡 +# 輸入一個關卡 [[tasks.variants]] [tasks.variants.params.stage] -default = "1-7" # 默认的关卡，可选（如果没有默认值，输入空值将会重新提示输入） -description = "a stage to fight" # 描述，可选 +default = "1-7" # 預設的關卡，選填（如果沒有預設值，輸入空值將會重新提示輸入） +description = "a stage to fight" # 描述，選填 -# 当输入的关卡是 1-7 时，需要输入使用理智药的数量 +# 當輸入的關卡是 1-7 時，需要輸入使用理智藥的數量 [tasks.variants.params.medicine] -# 参数可以设置为条件参数，这样只有满足条件时才需要输入 -# conditions 字段是一个表，其中键是同一层级下其他参数名，值是期望的值 -# 这里的条件是 stage 是 1-7， 如果存在多个条件，那么所有条件都必须满足 +# 參數可以「設定」為條件參數，這樣只有滿足條件時才需要輸入 +# conditions 欄位是一個表，其中鍵是同一層級下其他參數名稱，值是期望的值 +# 這裡的條件是 stage 為 1-7，如果存在多個條件，那麼所有條件都必須滿足 conditions = { stage = "1-7" } default = 1000 description = "medicine to use" ``` -对于 `Input` 类型，当运行任务时，你将会被提示输入一个值。如果你输入了一个空值，如果有默认值，那么默认值将会被使用，否则你将会被提示重新输入。 -对于 `Select` 类型，当运行任务时，你将会被提示输入一个的索引或者自定义的值（如果允许）。如果你输入了一个空值，如果有默认值，那么默认值将会被使用，否则你将会被提示重新输入。 +對於 `Input` 類型，執行任務時您會被提示輸入一個值。若輸入為空且設有預設值，將自動採用該預設值，否則會提示重新輸入。 +對於 `Select` 類型，執行任務時您會被提示輸入索引或自訂值（若允許）。若輸入為空且設有預設值，將自動採用該預設值，否則會提示重新輸入。 -`--batch` 选项可以用于在运行任务时跳过所有的输入，这将会使用默认值；如果有任何输入没有默认值，那么将会导致错误。 +`--batch` 選項可用於在執行任務時跳過所有輸入，此時系統將自動採用預設值；若有任何輸入項未設定預設值，則會產生錯誤。 -## MaaCore 相关配置 +## MaaCore 相關配置 -和 MaaCore 相关的配置需要放在 `$MAA_CONFIG_DIR/profiles` 目录中。该目录下的每一个文件都是一个配置文件，你可以通过 `-p` 或者 `--profile` 选项来指定配置文件名，不指定时尝试读取 `default` 配置文件。 +與 MaaCore 相關的配置需要放在 `$MAA_CONFIG_DIR/profiles` 目錄中。該目錄下的每一個檔案都是一個配置檔案，您可以透過 `-p` 或者 `--profile` 選項來指定配置檔案名稱，不指定時嘗試讀取 `default` 配置。 -目前支持的配置字段如下： +目前支援的配置欄位如下： ```toml [connection] @@ -313,159 +309,167 @@ adb_lite_enabled = false kill_adb_on_exit = false ``` -### 连接配置 +### 連線配置 -`[connection]` 相关字段用于指定 MaaCore 连接游戏的参数： +`[connection]` 相關欄位用於指定 MaaCore 連線遊戲的參數： ```toml [connection] -adb_path = "adb" # adb 可执行文件的路径，默认值为 "adb"，这意味着 adb 可执行文件在环境变量 PATH 中 -address = = "emulator-5554" # 连接地址，比如 "emulator-5554" 或者 "127.0.0.1:5555" -config = "General" # 连接配置，通常不需要修改 +adb_path = "adb" # adb 執行檔的路徑，預設值為 "adb"，這意味著 adb 執行檔在環境變數 PATH 中 +address = = "emulator-5554" # 連線位址，例如 "emulator-5554" 或者 "127.0.0.1:5555" +config = "General" # 連線配置，通常不需要修改 ``` -`adb_path` 是 `adb` 可执行文件的路径，你可以指定其路径，或者将其添加到环境变量 `PATH` 中，以便 MaaCore 可以找到它。大多数模拟器自带 `adb`，你可以直接使用其自带的 `adb`，而不需要额外安装，否则你需要自行安装 `adb`。`address` 是 `adb` 的连接地址。对于模拟器，你可以使用 `127.0.0.1:[端口号]`，常用的模拟器端口号参见[常见问题][emulator-ports]。如果你没有指定 `address`，那么会尝试通过 `adb devices` 来获取连接的设备，如果有多个设备连接，那么将会使用第一个设备，如果没有找到任何设备，那么将会尝试连接到 `emulator-5554`。`config` 用于指定一些平台和模拟器相关的配置。对于 Linux 他默认为 `CompatPOSIXShell`，对于 macOS 他默认为 `CompatMac`，对于 Windows 他默认为 `General`。更多可选配置可以在资源文件夹中的 `config.json` 文件中找到。 +`adb_path` 是 `adb` 執行檔的路徑，您可以指定其路徑，或者將其添加到環境變數 `PATH` 中，以便 MaaCore 可以找到它。大多數模擬器內建 `adb`，您可以直接使用其內建的 `adb`，而不需要額外安裝，否則您需要自行安裝 `adb`。`address` 是 `adb` 的連線位址。對於模擬器，您可以使用 `127.0.0.1:[連接埠號]`，常用的模擬器連接埠號可參閱 [常見問題][emulator-ports]。如果您沒有指定 `address`，那麼會嘗試透過 `adb devices` 來獲取連線的設備，如果有多個設備連線，那麼將會使用第一個設備，如果沒有找到任何設備，那麼將會嘗試連線到 `emulator-5554`。`config` 於指定一些平台和模擬器相關的配置。對於 Linux 它預設為 `CompatPOSIXShell`，對於 macOS 它預設為 `CompatMac`，對於 Windows 它預設為 `General`。更多可選配置可以在資源資料夾中的 `config.json` 檔案中找到。 -对于一些常用的模拟器，你可以直接使用 `preset` 来使用预设的配置： +對於一些常用的模擬器，您可以直接使用 `preset` 來使用預設的配置： ```toml [connection] -preset = "MuMuPro" # 使用 MuMuPro 预设的连接配置 -adb_path = "/path/to/adb" # 如果你需要的话，你可以覆盖预设的 adb 路径，大多数情况下你不需要这么做 -address = "127.0.0.1:7777" # 如果你需要的话，你可以覆盖预设的地址 +preset = "MuMuPro" # 使用 MuMuPro 預設的連線配置 +adb_path = "/path/to/adb" # 如果您需要的話，可以覆蓋預設的 adb 路徑，大多數情況下您不需要這麼做 +address = "127.0.0.1:7777" # 如果您需要的話，可以覆蓋預設的位址 ``` -目前只有 `MuMuPro` 一个模拟器的预设，如果有其他常用模拟器的预设，欢迎提交 issue 或者 PR。 +目前只有 `MuMuPro` 一個模擬器的預設，如果有其他常用模擬器的預設，歡迎提交 issue 或者 PR。 -此处有一个特殊的预设 `PlayCover`，其用于在 macOS 上连接直接通过 `PlayCover` 原生运行的游戏客户端。这种情况下不需要指定 `adb_path` 且 `address` 不是 `adb` l连接的地址而是 `PlayTools` 的地址，具体使用参见 [PlayCover 支持文档][playcover-doc]. +#### 特殊預設 -### 资源配置 +目前預先配置了兩種預設，為 `PlayCover (MacOS)`, `Waydroid (Linux)` -`[resource]` 相关字段用于指定 MaaCore 加载的资源： +- `PlayCover` 用於在 macOS 上連線直接透過 `PlayCover` 原生執行的遊戲客戶端。這種情況下不需要指定 `adb_path` 且 `address` 不是 `adb` 連線的位址而是 `PlayTools` 的位址，具體使用方式可參考 [PlayCover 支援文件][playcover-doc]. + +- `Waydroid` 用於在 Linux 上連線直接透過 `Waydroid` 原生執行的遊戲客戶端。這種情況下仍需要指定 `adb_path`，具體使用方式可參考 [Waydroid 支援文件][waydroid-doc]. + +### 資源配置 + +`[resource]` 相關欄位用於指定 MaaCore 載入的資源： ```toml [resource] -global_resource = "YoStarEN" # 非中文版本的资源 -platform_diff_resource = "iOS" # 非安卓版本的资源 -user_resource = true # 是否加载用户自定义的资源 +global_resource = "YoStarEN" # 非中文版本的資源 +platform_diff_resource = "iOS" # 非安卓版本的資源 +user_resource = true # 是否載入使用者自定義的資源 ``` -当使用非简体中文游戏客户端时，由于 MaaCore 默认加载的资源是简体中文的，你需要指定 `global_resource` 字段来加载非中文版本的资源。当使用 iOS 版本的游戏客户端时，你需要指定 `platform_diff_resource` 字段来加载 iOS 版本的资源。这两者都是可选的，如果你不需要加载这些资源，你可以将这两个字段设置为空。其次，这两者也会被自动设置，如果你的 `startup` 任务中指定了 `client_type` 字段，那么 `global_resource` 将会被设置为对应客户端的资源，而当你使用 `PlayTools` 连接时，`platform_diff_resource` 将会被设置为 `iOS`。最后，当你想要加载用户自定义的资源时，你需要将 `user_resource` 字段设置为 `true`。 +當使用非簡體中文遊戲客戶端時，由於 MaaCore 預設載入的資源是簡體中文的，您需要指定 `global_resource` 欄位來載入非中文版本的資源。當使用 iOS 版本的遊戲客戶端時，您需要指定 `platform_diff_resource` 欄位來載入 iOS 版本的資源。這兩者都是選填的，如果您不需要載入這些資源，可以將這兩個欄位設定為空。其次，這兩者也會被自動設定，如果您的 `startup` 任務中指定了 `client_type` 欄位，那麼 `global_resource` 將會被設定為對應客戶端的資源，而當您使用 `PlayTools` 連線時，`platform_diff_resource` 將會被設定為 `iOS`。最後，當您想要載入使用者自定義的資源時，您需要將 `user_resource` 欄位設定為 `true`。 -### 静态选项 +### 靜態選項 -`[static_options]` 相关字段用于指定 MaaCore 静态选项： +`[static_options]` 相關欄位用於指定 MaaCore 靜態選項： ```toml [static_options] -cpu_ocr = false # 是否使用 CPU OCR，默认使用 CPU OCR -gpu_ocr = 1 # 使用 GPU OCR 时使用的 GPU ID，如果这个值被留空，那么将会使用 CPU OCR +cpu_ocr = false # 是否使用 CPU OCR，預設使用 CPU OCR +gpu_ocr = 1 # 使用 GPU OCR 時使用的 GPU ID，如果這個值被留空，那麼將會使用 CPU OCR ``` -### 实例选项 +### 實例選項 -`[instance_options]` 相关字段用于指定 MaaCore 实例的选项： +`[instance_options]` 相關欄位用於指定 MaaCore 實例的選項： ```toml [instance_options] -touch_mode = "ADB" # 使用的触摸模式，可选值为 "ADB"，"MiniTouch"，"MaaTouch" 或者 "MacPlayTools" -deployment_with_pause = false # 是否在部署时暂停游戏 +touch_mode = "ADB" # 使用的觸控模式，可選值為 "ADB"、"MiniTouch"、"MaaTouch" 或者 "MacPlayTools" +deployment_with_pause = false # 是否在部署時暫停遊戲 adb_lite_enabled = false # 是否使用 adb-lite -kill_adb_on_exit = false # 是否在退出时杀死 adb +kill_adb_on_exit = false # 是否在退出時殺死 adb ``` -注意，`touch_mode` 可选项 `MacPlayTools` 和连接方式 `PlayTools` 绑定。当你使用 `PlayTools` 连接时，`touch_mode` 将会被强制设置为 `MacPlayTools`。 +請注意，`touch_mode` 可選項 `MacPlayTools` 和連線方式 `PlayTools` 綁定。當您使用 `PlayTools` 連線時，`touch_mode` 將會被強制設定為 `MacPlayTools`。 -## CLI 相关配置 +## CLI 相關配置 -CLI 相关的配置需要放在 `$MAA_CONFIG_DIR/cli.toml` 中。目前其包含的配置如下： +CLI 相關的配置需要放在 `$MAA_CONFIG_DIR/cli.toml` 中。目前其包含的配置如下： ```toml -# MaaCore 安装和更新相关配置 +# MaaCore 安裝和更新相關配置 [core] -channel = "Stable" # 更新通道，可选值为 "Alpha"，"Beta" "Stable"，默认为 "Stable" -test_time = 0 # 用于测试镜像速度的时间，0 表示不测试，默认为 3 -# 查询 MaaCore 最新版本的 api 地址，留空表示使用默认地址 +channel = "Stable" # 更新通道，可選值為 "Alpha"、"Beta" "Stable"，預設為 "Stable" +test_time = 0 # 用於測試鏡像站速度的時間，0 表示不測試，預設為 3 +# 查詢 MaaCore 最新版本的 api 位址，留空表示使用預設位址 api_url = "https://github.com/MaaAssistantArknights/MaaRelease/raw/main/MaaAssistantArknights/api/version/" -# 配置是否安装 MaaCore 对应的组件，不推荐使用，分开安装可能会导致版本不一致，从而导致一些问题，该选项可能在未来的版本中移除 +# 配置是否安裝 MaaCore 對應的組件，不推薦使用，分開安裝可能會導致版本不一致，從而導致一些問題，該選項可能在未來的版本中移除 [core.components] -library = true # 是否安装 MaaCore 的库，默认为 true -resource = true # 是否安装 MaaCore 的资源，默认为 true +library = true # 是否安裝 MaaCore 的函式庫，預設為 true +resource = true # 是否安裝 MaaCore 的資源，預設為 true -# CLI 更新相关配置 +# CLI 更新相關配置 [cli] -channel = "Stable" # 更新通道，可选值为 "Alpha"，"Beta" "Stable"，默认为 "Stable" -# 查询 maa-cli 最新版本的 api 地址，留空表示使用默认地址 +channel = "Stable" # 更新通道，可選值為 "Alpha"、"Beta" "Stable"，預設為 "Stable" +# 查詢 maa-cli 最新版本的 api 位址，留空表示使用預設位址 api_url = "https://github.com/MaaAssistantArknights/maa-cli/raw/version/" -# 下载预编译二进制文件的地址，留空表示使用默认地址 +# 下載預編譯執行檔的位址，留空表示使用預設位址 download_url = "https://github.com/MaaAssistantArknights/maa-cli/releases/download/" -# 配置是否安装 maa-cli 对应的组件 +# 配置是否安裝 maa-cli 對應的組件 [cli.components] -binary = true # 是否安装 maa-cli 的二进制文件，默认为 true +binary = true # 是否安裝 maa-cli 的執行檔，預設為 true -# 资源热更新相关配置 +# 資源熱更新相關配置 [resource] -auto_update = true # 是否在每次运行任务时自动更新资源，默认为 false -warn_on_update_failure = true # 是否在更新失败时发出警告而不是直接报错 -backend = "libgit2" # 资源热更新后端，可选值为 "git" 或者 "libgit2"，默认为 "git" +auto_update = true # 是否在每次執行任務時自動更新資源，預設為 false +warn_on_update_failure = true # 是否在更新失敗時發出警告而不是直接報錯 +backend = "libgit2" # 資源熱更新後端，可選值為 "git" 或者 "libgit2"，預設為 "git" -# 资源热更新远程仓库相关配置 +# 資源熱更新遠端倉庫相關配置 [resource.remote] -# 远程资源仓库的 URL，留空以使用默认 URL -# GitHub 仓库支持 HTTPS 和 SSH 两种协议访问，建议使用 HTTPS 协议，因为通常情况下不需要额外配置 +branch = "main" # 遠端倉庫的分支，預設為 "main" +# 遠端資源倉庫的 URL，留空以使用預設 URL +# GitHub 倉庫支援 HTTPS 和 SSH 兩種協定存取，建議使用 HTTPS 協定，因為通常情況下不需要額外配置 url = "https://github.com/MaaAssistantArknights/MaaResource.git" # url = "git@github.com:MaaAssistantArknights/MaaResource.git" -# 如果你必须使用 SSH 协议，你需要提供 SSH 密钥，最简单的方法是提供密钥的路径 -ssh_key = "~/.ssh/id_ed25519" # ssh 密钥的路径 -# maa 默认密钥是未加密的，如果你的密钥是受密码保护的，你需要提供密码来解密密钥 -# 注意：只有你使用 libgit2 后端时 maa 才会将密码传递给 libgit2 -# 当你使用 git 后端时，git 会自己提示你输入密码 -# 如果你使用 git 后端且你的密钥受密码保护，请使用 ssh-agent 来管理你的密钥 -passphrase = "password" # ssh 密钥的密码 -# 然而在配置文件中存储明文密码是不安全的，因此有一些方法可以避免这种情况 -# 1. 将 `passphrase` 设置为 true，然后 maa-cli 将每次提示你输入密码 -# 这种方法安全但是较为繁琐且无法在 batch 模式下使用 +# 如果您必須使用 SSH 協定，您需要提供 SSH 金鑰，最簡單的方法是提供金鑰的路徑 +ssh_key = "~/.ssh/id_ed25519" # ssh 金鑰的路徑 +# maa 預設金鑰是未加密的，如果您的金鑰是受密碼保護的，您需要提供密碼來解密金鑰 +# 注意：只有您使用 libgit2 後端時 maa 才會將密碼傳遞給 libgit2 +# 當您使用 git 後端時，git 會自己提示您輸入密碼 +# 如果您使用 git 後端且您的金鑰受密碼保護，請使用 ssh-agent 來管理您的金鑰 +passphrase = "password" # ssh 金鑰的密碼 +# 然而在配置檔案中儲存明文密碼是不安全的，因此有一些方法可以避免這種情況 +# 1. 將 `passphrase` 設定為 true，然後 maa-cli 將每次提示您輸入密碼 +# 這種方法安全但是較為繁瑣且無法在 batch 模式下使用 # passphrase = true -# 2. 将 `passphrase` 设置为环境变量名，然后 maa-cli 将使用环境变量作为密码 -# 这种方法比明文密码更安全，但是仍然有一定的风险，因为环境变量可能被任何程序访问 +# 2. 將 `passphrase` 設定為環境變數名稱，然後 maa-cli 將使用環境變數作為密碼 +# 這種方法比明文密碼更安全，但是仍然有一定的風險，因為環境變數可能被任何程式存取 # passphrase = { env = "MAA_SSH_PASSPHRASE" } -# 3. 将 `passphrase` 设置为命令，然后 maa-cli 将执行该命令以获取密码 -# 如果你使用了密码管理器来管理你的密码，这种方法可能是最安全的且方便的 +# 3. 將 `passphrase` 設定為指令，然後 maa-cli 將執行該指令以獲取密碼 +# 如果您使用了密碼管理器來管理您的密碼，這種方法可能是最安全的且方便的 # passphrase = { cmd = ["pass", "show", "ssh/id_ed25519"] } -# 4. 使用 ssh-agent 来管理你的密钥，**推荐** -# ssh-agent 会将你的密钥保存在内存中，这样你就不需要每次输入密码 -# 注意，你需要确保 ssh-agent 已经启动并且已经添加了你的密钥，同时 SSH_AUTH_SOCK 环境变量已经设置 -# use_ssh_agent = true # 使用 ssh-agent 进行身份验证，如果设置为 true，将忽略 ssh_key 和 passphrase 字段 +# 4. 使用 ssh-agent 來管理您的金鑰，**推薦** +# ssh-agent 會將您的金鑰保存在記憶體中，這樣您就不需要每次輸入密碼 +# 注意，您需要確保 ssh-agent 已經啟動並且已經添加了您的金鑰，同時 SSH_AUTH_SOCK 環境變數已經設定 +# use_ssh_agent = true # 使用 ssh-agent 進行身份驗證，如果設定為 true，將忽略 ssh_key 和 passphrase 欄位 ``` -**注意事项**： +**注意事項**： -- MaaCore 的更新通道中 `Alpha` 只在 Windows 上可用； -- 由于 CLI 默认的 API 链接和下载链接都是 GitHub 的链接，因此在国内可能会有一些问题，你可以通过配置 `api_url` 和 `download_url` 来使用镜像。 -- 即使启动了资源热更新，你依然需要安装 MaaCore 的资源，因为资源热更新并不包含所有的资源文件，只是包含部分可更新的资源文件，基础资源文件仍然需要安装。 -- 资源热更新是通过 Git 来拉取远程仓库，如果后端设置为 `git` 那么 `git` 命令行工具必须可用。 -- 如果你想要使用 SSH 协议来拉取远程仓库，你必须配置 `ssh_key` 字段，这个字段应该是一个路径，指向你的 SSH 私钥。 -- 如果你的 SSH 私钥是受密码保护的，你需要提供密码来解密私钥，或者使用 ssh-agent 来管理你的密钥。 -- 远程仓库的 `url` 设置目前只对首次安装资源有效，如果你想要更改远程仓库的地址，你需要通过 `git` 命令行工具手动更改，或者删除对应的仓库。仓库所在位置可以通过 `maa dir hot-update` 获取。 +- MaaCore 的更新通道中 `Alpha` 只在 Windows 上可用。 +- 由於 CLI 預設的 API 連結和下載連結都是 GitHub 的連結，因此在連線較慢的地區可能會有一些問題，您可以透過配置 `api_url` 和 `download_url` 來使用鏡像站。 +- 即使啟動了資源熱更新，您依然需要安裝 MaaCore 的資源，因為資源熱更新並不包含所有的資源檔案，只是包含部分可更新的資源檔案，基礎資源檔案仍然需要安裝。 +- 資源熱更新是透過 Git 來拉取遠端倉庫，如果後端設定為 `git` 那麼 `git` 命令列工具必須可用。 +- 如果您想要使用 SSH 協定來拉取遠端倉庫，您必須配置 `ssh_key` 欄位，這個欄位應該是一個路徑，指向您的 SSH 私鑰。 +- 如果您的 SSH 私鑰是受密碼保護的，您需要提供密碼來解密私鑰，或者使用 ssh-agent 來管理您的金鑰。 +- 遠端倉庫的 `url` 設定目前只對首次安裝資源有效，如果您想要更改遠端倉庫的位址，您需要透過 `git` 命令列工具手動更改，或者刪除對應的倉庫。倉庫所在位置可以透過 `maa dir hot-update` 獲取。 -## 参考配置 +## 參考配置 -- [示例配置][example-config] +- [範例配置][example-config] - [自用配置][wangl-cc-dotfiles] ## JSON Schema -你可以在 [`schemas` 目录][schema-dir] 中找到 maa-cli 的 JSON Schema 文件，你可以使用这些文件来验证你的配置文件，或者在编辑器中获得自动补全。 +您可以在 [`schemas` 目錄][schema-dir] 中找到 maa-cli 的 JSON Schema 檔案，您可以使用這些檔案來驗證您的配置檔案，或者在編輯器中獲得自動補全。 -- 自定任务文件的 JSON Schema 文件为 [`task.schema.json`][task-schema]； -- MaaCore 配置的 JSON Schema 文件为 [`asst.schema.json`][asst-schema]； -- CLI 配置的 JSON Schema 文件为 [`cli.schema.json`][cli-schema]。 +- 自定義任務檔案的 JSON Schema 檔案為 [`task.schema.json`][task-schema]； +- MaaCore 配置的 JSON Schema 檔案為 [`asst.schema.json`][asst-schema]； +- CLI 配置的 JSON Schema 檔案為 [`cli.schema.json`][cli-schema]。 -[task-types]: ../../protocol/integration.md#任务类型一览 -[emulator-ports]: ../../manual/connection.md#获取端口号 -[playcover-doc]: ../../manual/device/macos.md#✅-playcover-原生运行最流畅-🚀 +[task-types]: ../../protocol/integration.md#任務類型一覽 +[emulator-ports]: ../../manual/connection.md#模擬器連接埠相關文件 +[playcover-doc]: ../../manual/device/macos.md#✅-playcover-原生執行最流暢-🚀 +[waydroid-doc]: ../../manual/device/linux.md#✅-waydroid [example-config]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/config_examples [wangl-cc-dotfiles]: https://github.com/wangl-cc/dotfiles/tree/main/home/dot_config/maa [schema-dir]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/ diff --git a/docs/zh-tw/manual/cli/faq.md b/docs/zh-tw/manual/cli/faq.md index 04914e6cc1..754accc072 100644 --- a/docs/zh-tw/manual/cli/faq.md +++ b/docs/zh-tw/manual/cli/faq.md @@ -3,17 +3,13 @@ order: 2 icon: ph:question-fill --- -# 常见问题 +# 常見問題 -::: important Translation Required -This page is outdated and maybe still in Simplified Chinese. Translation is needed. -::: +## 1. 如何在 macOS 上使用 `$HOME/.config/maa` 作為配置目錄？ -## 1. 如何在 macOS 上使用 `$HOME/.config/maa` 作为配置文件目录？ - -由于 Rust 库 [Directories](https://github.com/dirs-dev/directories-rs/) 在 macOS 上默认使用 Apple 风格目录，maa-cli 默认也使用 Apple 风格的配置目录。但是对于命令行程序来说，XDG 风格的目录更加合适。如果你想要使用 XDG 风格目录，你可以设置 `XDG_CONFIG_HOME` 环境变量，如 `export XDG_CONFIG_HOME="$HOME/.config"`，这会让 maa-cli 使用 XDG 风格配置目录。如果你想要使用 XDG 风格配置目录，但是不想设置环境变量，你可以使用下面的命令创建一个符号链接： +由於 Rust 函式庫 [Directories](https://github.com/dirs-dev/directories-rs/) 在 macOS 上預設使用 Apple 風格目錄，maa-cli 預設也使用 Apple 風格的配置目錄。但對於命令列程式來說，XDG 風格的目錄更加合適。如果您想要使用 XDG 風格目錄，您可以設定 `XDG_CONFIG_HOME` 環境變數，例如 `export XDG_CONFIG_HOME="$HOME/.config"`，這會讓 maa-cli 使用 XDG 風格的配置目錄。如果您想要使用 XDG 風格的配置目錄，但不想設定環境變數，您可以使用下方的指令建立一個符號連結： ```bash mkdir -p "$HOME/.config/maa" ln -s "$HOME/.config/maa" "$(maa dir config)" -``` +``` \ No newline at end of file diff --git a/docs/zh-tw/manual/cli/install.md b/docs/zh-tw/manual/cli/install.md index 31e373a8f7..96c18c8888 100644 --- a/docs/zh-tw/manual/cli/install.md +++ b/docs/zh-tw/manual/cli/install.md @@ -3,17 +3,13 @@ order: 1 icon: material-symbols:download --- -# 安装及编译 +# 安裝及編譯 -::: important Translation Required -This page is outdated and maybe still in Simplified Chinese. Translation is needed. -::: +maa-cli 提供多種方式安裝，包括預編譯執行檔、套件管理員以及透過 `cargo` 自行編譯安裝。 -maa-cli 提供多种方式安装，包括预编译二进制文件、包管理器和通过 `cargo` 自行编译安装。 +## 預編譯執行檔 -## 预编译二进制文件 - -安装 maa-cli 最简单的方式是使用安装脚本一键安装： +安裝 maa-cli 最簡單的方式是使用安裝指令碼一鍵安裝： ::: tabs#pre-compile @@ -31,27 +27,27 @@ Invoke-WebRequest -Uri "https://raw.githubusercontent.com/MaaAssistantArknights/ ::: -后续你可以通过 `maa self update` 来更新 maa-cli。 +後續您可以透過 `maa self update` 來更新 maa-cli。 -如果你的平台不在上述列表中，可以尝试自行[编译安装](#编译安装)。 +如果您的平台不在上述列表中，可以嘗試自行[編譯安裝](#編譯安裝)。 -## 通过包管理器安装 +## 透過套件管理員安裝 -对于 macOS 和受支持的 Linux 发行版用户，可以使用包管理器安装 maa-cli。 +對於 macOS 和受支援的 Linux 發行版使用者，可以使用套件管理員安裝 maa-cli。 ### macOS -Homebrew 用户可以通过非官方的 [tap](https://github.com/MaaAssistantArknights/homebrew-tap/) 安装 maa-cli： +Homebrew 使用者可以透過非官方的 [tap](https://github.com/MaaAssistantArknights/homebrew-tap/) 安裝 maa-cli： ::: code-tabs -@tab:active 稳定版 +@tab:active 穩定版本 ```bash :no-line-numbers brew install MaaAssistantArknights/tap/maa-cli ``` -@tab 不稳定版/预发行版 +@tab 不穩定版本 / 預發行版本 ```bash :no-line-numbers brew install MaaAssistantArknights/tap/maa-cli-beta @@ -61,11 +57,11 @@ brew install MaaAssistantArknights/tap/maa-cli-beta ### Linux -Arch、Nix 以及 Linux Homebrew 用户可以通过包管理器安装 maa-cli。 +Arch、Nix 以及 Linux Homebrew 使用者可以透過套件管理員安裝 maa-cli。 #### Arch Linux -可以安装 [AUR 包](https://aur.archlinux.org/packages/maa-cli/)： +可以安裝 [AUR 套件](https://aur.archlinux.org/packages/maa-cli/)： ::: code-tabs @@ -85,17 +81,17 @@ yay -S maa-cli #### ❄️ Nix -用户可以直接运行: +使用者可以直接執行： ::: code-tabs -@tab:active 稳定版 +@tab:active 穩定版本 ```bash :no-line-numbers nix run nixpkgs#maa-cli ``` -@tab 每夜构建 +@tab Nightly 版本 ```bash :no-line-numbers nix run github:Cryolitia/nur-packages#maa-cli-nightly @@ -103,31 +99,31 @@ nix run github:Cryolitia/nur-packages#maa-cli-nightly ::: -稳定版打包至 [nixpkgs](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/ma/maa-cli/package.nix) 中，使用 `nixpkgs` 中的 Rust 工具链；每夜构建位于 [NUR](https://github.com/Cryolitia/nur-packages/blob/master/pkgs/maa-assistant-arknights/maa-cli.nix) 中，使用 Beta channel 的 Rust 工具链，由 Github Actions 每日自动更新和构建验证。 +穩定版本已收錄至 [nixpkgs](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/ma/maa-cli/package.nix) 中，並使用 `nixpkgs` 中的 Rust 工具鏈；Nightly 版本則位於 [NUR](https://github.com/Cryolitia/nur-packages/blob/master/pkgs/maa-assistant-arknights/maa-cli.nix)，使用 Beta 分支的 Rust 工具鏈，且每日經由 GitHub Actions 自動更新與驗證建置結果。 #### Homebrew -对于在 Linux 上使用 Homebrew 的用户，请参见上述 macOS 的安装方式。 +對於在 Linux 上使用 Homebrew 的使用者，請參考上述 macOS 的安裝方式。 #### 其他发行版 -请使用 [预编译二进制文件](#预编译二进制文件) 或是 [自行编译安装](#编译安装)。 +請使用 [預編譯執行檔](#預編譯執行檔) 或是 [自行編譯安裝](#編譯安裝)。 -我们也欢迎各位有兴趣的开发者将 maa-cli 提交到更多发行版的官方仓库或是用户仓库！ +我們也歡迎各位有興趣的開發者將 maa-cli 提交到更多發行版的官方倉庫或是使用者倉庫！ -## 编译安装 +## 編譯安裝 -Rust 开发者可以通过 `cargo` 自行编译安装 maa-cli： +Rust 開發者可以透過 `cargo` 自行編譯安裝 maa-cli： ::: code-tabs -@tab:active 稳定版本 +@tab:active 穩定版本 ```bash :no-line-numbers cargo install --git https://github.com/MaaAssistantArknights/maa-cli.git --bin maa --tag stable --locked ``` -@tab 开发版本 +@tab 開發版本 ```bash :no-line-numbers cargo install --git https://github.com/MaaAssistantArknights/maa-cli.git --bin maa --locked @@ -136,49 +132,49 @@ cargo install --git https://github.com/MaaAssistantArknights/maa-cli.git --bin m ::: ::: warning -maa-cli 目前的最低支持 Rust 版本 (MSRV) 为 1.88。请注意，MSRV 可能随时发生变化，我们建议始终使用最新的 Rust 工具链以获得最佳体验。 +maa-cli 目前的最低支援 Rust 版本 (MSRV) 為 1.88。請注意，MSRV 可能隨時發生變化，我們建議始終使用最新的 Rust 工具鏈以獲得最佳體驗。 ::: -### 编译选项 +### 編譯選項 -从源码编译时，你可以通过 `--no-default-features` 禁用默认的特性，然后通过 `--features` 来启用特定的特性。目前可用的特性有： +從原始碼編譯時，您可以透過 `--no-default-features` 停用預設的特性，然後透過 `--features` 來啟用特定的特性。目前可用的特性有： -- `cli_installer`: 启用 `maa self update` 命令，用于更新自身，这个特性默认启用； -- `core_installer`: 启用 `maa install` 和 `maa update` 命令，用于安装和更新 MaaCore 及资源，这个特性默认启用； -- `git2`: 提供 `libgit2` 资源更新后端，这个特性默认启用。 +- `cli_installer`: 啟用 `maa self update` 指令，用於更新自身，這個特性預設啟用。 +- `core_installer`: 啟用 `maa install` 和 `maa update` 指令，用於安裝和更新 MaaCore 及資源，這個特性預設啟用。 +- `git2`: 提供 `libgit2` 資源更新後端，這個特性預設啟用。 -## 安装 MaaCore 及资源 +## 安裝 MaaCore 及資源 -maa-cli 只提供了一个命令行界面，它需要 MaaCore 和资源来运行任务。 +maa-cli 只提供了一個命令列介面，它需要 MaaCore 和資源來執行任務。 -根据安装方式和平台的不同，你的操作也有所区别： +根據安裝方式和平台的不同，您的操作也會有所區別： ::: tabs#maacore -@tab:active 预编译 -对于使用预编译二进制或者自行编译的用户，maa-cli 可以帮助你安装和更新： +@tab:active 預編譯 +對於使用預編譯執行檔或者自行編譯的使用者，maa-cli 可以協助您安裝和更新： ```bash :no-line-numbers maa install ``` @tab Windows -对于 Windows 平台的用户，在运行 `maa install` 命令前，请以管理员身份在命令提示符或 PowerShell 中运行以下命令，以安装必要组件 VC++ 运行库： +對於 Windows 使用者，在執行 `maa install` 指令前，請以管理員身份在命令提示字元或 PowerShell 中執行以下指令，以安裝必要組件 VC++ 執行環境 (Redistributable)： ```bat :no-line-numbers winget install "Microsoft.VCRedist.2015+.x64" --override "/repair /passive /norestart" --uninstall-previous --accept-package-agreements --force ``` -然后再运行 `maa install`。 +然後再執行 `maa install`。 @tab Arch -你可以使用 maa-cli 安装预编译的 MaaCore: +您可以使用 maa-cli 安裝預編譯的 MaaCore： ```bash :no-line-numbers maa install ``` -你也可以通过 [AUR](https://aur.archlinux.org/packages/maa-assistant-arknights/) 安装 maa-core +您也可以透過 [AUR](https://aur.archlinux.org/packages/maa-assistant-arknights/) 安裝 maa-core ```bash :no-line-numbers paru -S maa-assistant-arknights @@ -191,10 +187,10 @@ yay -S maa-assistant-arknights ``` @tab Nix -Nix 上的 maa-cli 强制依赖 MaaCore，因此 Nix 用户无需，也不应该手动安装 MaaCore。 +Nix 上的 maa-cli 強制依賴 MaaCore，因此 Nix 使用者無需、也不應該手動安裝 MaaCore。 ::: ::: warning -`maa install` 下载的是 MAA 官方预编译的 MaaCore，而包管理器安装的 MaaCore 可能使用与官方预编译版本不同的编译选项和依赖版本，这也许会导致性能和功能上的略微差异。 -::: +`maa install` 下載的是 MAA 官方預編譯的 MaaCore，而套件管理員安裝的 MaaCore 可能使用與官方預編譯版本不同的編譯選項和依賴版本，這也許會導致效能和功能上的些微差異。 +::: \ No newline at end of file diff --git a/docs/zh-tw/manual/cli/usage.md b/docs/zh-tw/manual/cli/usage.md index 85093a6e7e..9a74c771cd 100644 --- a/docs/zh-tw/manual/cli/usage.md +++ b/docs/zh-tw/manual/cli/usage.md @@ -5,109 +5,105 @@ icon: material-symbols:summarize # 使用 -::: important Translation Required -This page is outdated and maybe still in Simplified Chinese. Translation is needed. -::: - -maa-cli 主要功能是通过调用 MaaCore，自动化完成明日方舟的游戏任务。此外，为了方便使用，maa-cli 还提供了管理 MaaCore 的功能。 +maa-cli 的主要功能是透過呼叫 MaaCore，自動化完成《明日方舟》的遊戲任務。此外，為了方便使用，maa-cli 還提供了管理 MaaCore 的功能。 ::: tip -对于使用 Windows 包管理器 (winget) 安装 maa-cli 的用户，以下命令中的 `maa` 需要替换为 `maa-cli` 。 +對於使用 Windows 套件管理員 (winget) 安裝 maa-cli 的使用者，以下指令中的 `maa` 需要替換為 `maa-cli`。 ::: ## 管理 MaaCore -maa-cli 可以安装和更新 MaaCore 及资源，只需运行以下命令： +maa-cli 可以安裝和更新 MaaCore 及資源，只需執行以下指令： ```bash -maa install # 安装 MaaCore 及资源 -maa update # 更新 MaaCore 及资源 +maa install # 安裝 MaaCore 及資源 +maa update # 更新 MaaCore 及資源 ``` ## 更新 maa-cli 自身 -maa-cli 可以更新自身，只需运行以下命令： +maa-cli 可以更新自身，只需執行以下指令： ```bash maa self update ``` -**注意**：使用包管理器安装 maa-cli 的用户请使用包管理器更新 maa-cli，此命令在这些用户中无效。 +**注意**：使用套件管理員安裝 maa-cli 的使用者請使用套件管理員更新 maa-cli，此指令對這些使用者無效。 ## 初始化配置 -一旦完成了 MaaCore 的安装，通常情况下，你无需额外配置就可以直接运行任务。默认配置可能不适用于所有用户，因此你可以通过以下命令来初始化配置： +一旦完成了 MaaCore 的安裝，通常情況下，您無需額外設定就可以直接執行任務。預設配置可能不適用於所有使用者，因此您可以透過以下指令來進行初始化： ```bash maa init ``` -通过这个命令，你可以交互式地配置 [MaaCore 的相关配置][config-core]。 +透過這個指令，您可以互動式地進行 [MaaCore 的相關配置][config-core]。 -## 运行任务 +## 執行任務 -完成 MaaCore 的安装和配置后，你可以运行任务了。maa-cli 支持两种类型的任务：预定义任务和自定义任务。 +完成 MaaCore 的安裝與配置後，您就可以執行任務了。maa-cli 支援兩種類型的任務：預定義任務和自定義任務。 -### 预定义任务 +### 預定義任務 -对于常见任务，maa-cli 提供了一些预定义的任务： +對於常見任務，maa-cli 提供了一些預定義的任務： -- `maa startup [client]`: 启动游戏并进入主界面，`[client]` 是客户端类型，如果留空则不会启动游戏客户端。 -- `maa closedown [client]`: 关闭游戏客户端，`[client]` 是客户端类型，默认为 `Official`。 -- `maa fight [stage]`: 运行战斗任务，`[stage]` 是关卡名称，例如 `1-7`；留空选择上次或者当前关卡。 -- `maa copilot ...`: 自动抄作业，其中 `` 是作业的 URI，多个 URI 会依次执行，`maa_uri` 可以是 `maa://1234` 或者 本地文件路径 `./1234.json`。 -- `maa sscopilot `: 自动保全派驻，其中 `` 是保全派驻作业的 URI。 -- `maa roguelike `: 自动集成战略，`` 是集成战略的主题，可选值为 `Phantom`，`Mizuki`，`Sami`，`Sarkaz` 以及 `JieGarden`. -- `maa reclamation `: 自动生息演算，`` 是生息演算的主题，目前仅 `Tales` 主题可用。 +- `maa startup [client]`：啟動遊戲並進入主介面，`[client]` 是客戶端類型，如果留空則不會啟動遊戲客戶端。 +- `maa closedown [client]`：關閉遊戲客戶端，`[client]` 是客戶端類型，預設為 `Official`。 +- `maa fight [stage]`：執行戰鬥任務，`[stage]` 是關卡名稱，例如 `1-7`；留空則選擇上次或當前關卡。 +- `maa copilot ...`：自動抄作業，其中 `` 是作業的 URI，多個 URI 會依序執行，`maa_uri` 可以是 `maa://1234` 或本地檔案路徑 `./1234.json`。 +- `maa sscopilot `：自動保全派駐，其中 `` 是保全派駐作業的 URI。 +- `maa roguelike `：自動集成戰略，`` 是集成戰略的主題，可選值為 `Phantom`，`Mizuki`，`Sami`，`Sarkaz` 以及 `JieGarden`。 +- `maa reclamation `：自動生息演算，`` 是生息演算的主題，目前僅 `Tales` 主題可用。 -上述任务接受一些参数，你可以通过 `maa --help` 来查看具体的参数。 +上述任務接受一些參數，您可以透過 `maa --help` 查看具體的參數。 -对于官服玩家，如果你想要打开游戏，使用 3 个理智药刷 BB-7，然后关闭游戏，你可以运行以下命令： +對於官服玩家，如果您想要開啟遊戲，使用 3 個理智藥刷 BB-7，然後關閉遊戲，您可以執行以下指令： ```bash maa startup Official && maa fight BB-7 -m 3 && maa closedown ``` -### 自定义任务 +### 自定義任務 -由于MAA支持的任务繁多，maa-cli无法提供所有任务的预定义选项。除此之外，你可能需要像上述的例子一样运行多个任务。为了解决这个问题，maa-cli提供了自定义任务的功能。自定义任务能够组合不同的任务，并且更精细地控制每个任务的参数以及执行顺序。此外，自定义任务支持条件判断，可以根据条件来决定是否执行某个任务，或者以何种参数执行某个任务。这可以用于自动化你的日常任务。自定义任务通过配置文件定义，具体配置文件的位置和编写方式请参考 [自定义任务文档][custom-task]。在编写好配置文件后，你可以通过 `maa run ` 来运行自定义任务，这里的 `` 是一个自定义任务文件名，不包括扩展名。 +由於 MAA 支援的任務繁多，maa-cli 無法提供所有任務的預定義選項。除此之外，您可能需要像上述的例子一樣執行多個任務。為了解決這個問題，maa-cli 提供了自定義任務的功能。自定義任務能夠組合不同的任務，並且更精確地控制每個任務的參數以及執行順序。此外，自定義任務支援條件判斷，可以根據條件來決定是否執行某個任務，或者以何種參數執行某個任務。這可以用於自動化您的日常任務。自定義任務透過配置檔案定義，具體配置檔案的位置和編寫方式請參考 [自定義任務文件][custom-task]。在編寫好配置檔案後，您可以透過 `maa run ` 來執行自定義任務，這裡的 `` 是一個自定義任務檔案名稱，不包括副檔名。 -### 任务总结 +### 任務總結 -不管是预定义任务还是自定义任务，maa-cli 都会在任务运行结束后输出任务的总结信息， -其包括每个子任务的运行时间（开始时间、结束时间、运行时长）。对于部分任务，还会输出任务的结果汇总： +不管是預定義任務還是自定義任務，maa-cli 都會在任務執行結束後輸出任務的總結資訊， +其包括每個子任務的執行時間（開始時間、結束時間、執行時長）。對於部分任務，還會輸出任務的結果彙整： -- `fight` 任务: 关卡名称，次数，消耗理智药个数以及掉落统计； -- `infrast`: 各设施进驻的干员，对于制造站和贸易站，还会包括产物类型； -- `recruit`: 每次公招的 tag ，星级以及状态，以及总共的招募次数； -- `roguelike`: 探索次数，投资次数。 +- `fight` 任務：關卡名稱、次數、消耗理智藥個數以及掉落統計。 +- `infrast`：各設施進駐的幹員，對於製造站和貿易站，還會包括產物類型。 +- `recruit`：每次公招的 tag、星級以及狀態，以及總共的招募次數。 +- `roguelike`：探索次數、投資次數。 -如果你不想要任务总结，可以通过 `--no-summary` 参数来关闭。 +如果您不想要任務總結，可以透過 `--no-summary` 參數來關閉。 -### 任务日志 +### 任務日誌 -maa-cli 会输出日志，日志输出级别从低到高分别为 `Error`，`Warn`，`Info`，`Debug` 和 `Trace`。默认的日志输出级别为 `Warn`。日志级别可以通过 `MAA_LOG` 环境变量来设置，例如 `MAA_LOG=debug`。你也可以通过 `-v` 或者 `-q` 来增加或者减少日志输出级别。 +maa-cli 會輸出日誌，日誌輸出層級從低到高分別為 `Error`，`Warn`，`Info`，`Debug` 和 `Trace`。預設的日誌輸出層級為 `Warn`。日誌層級可以透過 `MAA_LOG` 環境變數來設定，例如 `MAA_LOG=debug`。您也可以透過 `-v` 或 `-q` 來增加或減少日誌輸出層級。 -maa-cli 默认会向标准误 (stderr) 输出日志。`--log-file` 选项可以将日志输出到文件中，日志保存在 `$(maa dir log)/YYYY/MM/DD/HH:MM:SS.log` 中，其中 `$(maa dir log)` 是日志目录，你可以通过 `maa dir log` 获取。你也可以通过 `--log-file=path/to/log` 来指定日志文件的路径。 +maa-cli 預設會向標準錯誤輸出 (stderr) 輸出日誌。`--log-file` 選項可以將日誌輸出到檔案中，日誌儲存在 `$(maa dir log)/YYYY/MM/DD/HH:MM:SS.log` 中，其中 `$(maa dir log)` 是日誌目錄，您可以透過 `maa dir log` 獲取。您也可以透過 `--log-file=path/to/log` 來指定日誌檔案的路徑。 -默认情况下，所有输出的日志会包含时间戳和日志级别的前缀。你可以通过环境变量 `MAA_LOG_PREFIX` 来改变这个行为。设置为 `Always` 时，总是会包含前缀，设置为 `Auto` 时输出到日志文件时会包含前缀，而输出到 stderr 时不会包含前缀，而设置为 `Never` 时即使是写入日志文件时也不会包含前缀。 +預設情況下，所有輸出的日誌會包含時間戳記和日誌層級的前綴。您可以透過環境變數 `MAA_LOG_PREFIX` 來改變這個行為。設定為 `Always` 時，總是會包含前綴；設定為 `Auto` 時，輸出到日誌檔案時會包含前綴，而輸出到 stderr 時則不會包含前綴；設定為 `Never` 時，即使是寫入日誌檔案時也不會包含前綴。 -### 其他子命令 +### 其他子指令 -除了上述的命令外，maa-cli 还提供了其他一些子命令： +除了上述的指令外，maa-cli 還提供了其他一些子指令： -- `maa list`: 列出所有可用的任务； -- `maa dir `: 获取特定目录的路径，比如 `maa dir config` 可以用来获取配置目录的路径; -- `maa version`: 获取 `maa-cli` 以及 `MaaCore` 的版本信息； -- `maa convert [output]`: 将 `JSON`，`YAML` 或者 `TOML` 格式的文件转换为其他格式; -- `maa complete `: 生成自动补全脚本; -- `maa activity [client]`: 获取游戏的当前活动信息，`client` 是客户端类型，默认为 `Official`。 -- `maa cleanup`: 清除 `maa-cli` 和 `MaaCore` 的缓存。 -- `maa import [-t ]:` 导入配置文件，`file` 是配置文件的路径。`-t` 选项可以指定配置文件的类型，如 `cli`, `profile`, `infrast` 等。 +- `maa list`：列出所有可用的任務。 +- `maa dir `：獲取特定目錄的路徑，例如 `maa dir config` 可以用來獲取配置目錄的路徑。 +- `maa version`：獲取 `maa-cli` 以及 `MaaCore` 的版本資訊。 +- `maa convert [output]`：將 `JSON`，`YAML` 或 `TOML` 格式的檔案轉換為其他格式。 +- `maa complete `：產生自動補全指令碼。 +- `maa activity [client]`：獲取遊戲的目前活動資訊，`client` 是客戶端類型，預設為 `Official`。 +- `maa cleanup`：清除 `maa-cli` 和 `MaaCore` 的暫存 (cache)。 +- `maa import [-t ]`：匯入配置檔案，`file` 是配置檔案的路徑。`-t` 選項可以指定配置檔案的類型，如 `cli`, `profile`, `infrast` 等。 -更多命令的使用方法可以通过 `maa help` 查看，具体命令的使用方法可以 通过 `maa help ` 查看。 +更多指令的使用方法可以透過 `maa help` 查看，具體指令的使用方法可以透過 `maa help ` 查看。 -[config-core]: config.md#maacore-相关配置 -[custom-task]: config.md#自定义任务 +[config-core]: config.md#maacore-相關配置 +[custom-task]: config.md#自定義任務 diff --git a/docs/zh-tw/manual/connection.md b/docs/zh-tw/manual/connection.md index 10363d75c1..4326d9d8f9 100644 --- a/docs/zh-tw/manual/connection.md +++ b/docs/zh-tw/manual/connection.md @@ -3,238 +3,253 @@ order: 3 icon: mdi:plug --- -# 連接設定 +# 連線設定 + +## 自動偵測 + +MAA 可以透過目前**正在執行中的單一模擬器**，自動偵測並填充 ADB 路徑、連線位址與連線配置。 + +截至 MAA v5.22.3 為止，支援自動偵測的模擬器及其連線位址如下： + +- BlueStacks 藍疊模擬器 5：`127.0.0.1:5555/5556/5565/5575/5585/5595/5554` +- MuMu 模擬器：`127.0.0.1:16384/16416/16448/16480/16512/16544/16576` +- 雷電模擬器 9：`emulator-5554/5556/5558/5560`、`127.0.0.1:5555/5557/5559/5561` +- 夜神模擬器：`127.0.0.1:62001/59865` +- 逍遙模擬器：`127.0.0.1:21503` + +若偵測失敗，請嘗試以系統管理員權限啟動 MAA 並再次偵測。若仍失敗，請參考下文進行手動設定，並參考上述清單向我們回報。 ## ADB 路徑 :::info 技術細節 -自動檢測使用的是模擬器的 ADB，但有時自動檢測會出現問題，此時就需要手動設定。 -`強制替換 ADB` 是下載 Google 提供的 ADB 後再進行替換，如果自己設定 Google 的 ADB 即可一勞永逸。 +自動偵測預設會使用模擬器內建的 ADB，當自動偵測出現問題時才需要手動設定。 +點選 `強制替換 ADB` 會自動下載 Google 提供的 ADB 並自動填入路徑。 +若系統環境變數中已有可用的 ADB，可直接填寫 `adb`。 ::: ### 使用模擬器提供的 ADB -前往模擬器安裝路徑，Windows 可在模擬器執行時，在工作管理員中右鍵程式點選 `開啟檔案位置`。 +前往模擬器的安裝路徑。在 Windows 系統中，您可以在模擬器執行時，於工作管理員對該程序點擊右鍵，選擇 `開啟檔案所在位置`。 -頂層或下層目錄中應該會有一個名字中帶有 `adb` 的 exe 檔案，可以使用搜索功能，然後選擇。 +在該層或下層目錄中，應該能找到一個檔名包含 `adb` 的 exe 檔案（可使用搜尋功能），將其選取即可。 -:::details 一些範例 +:::details 範例檔名 `adb.exe` `HD-adb.exe` `adb_server.exe` `nox_adb.exe` ::: ### 使用 Google 提供的 ADB -[點選下載](https://dl.google.com/android/repository/platform-tools-latest-windows.zip) 後解壓縮，然後選擇其中的 `adb.exe`。 +[點此下載](https://dl.google.com/android/repository/platform-tools-latest-windows.zip) 後解壓縮，並選取其中的 `adb.exe`。 -推薦直接解壓縮到 MAA 資料夾下，這樣可以直接在 ADB 路徑中填寫 `.\platform-tools\adb.exe`，也可以隨著 MAA 資料夾一起移動。 +建議直接解壓縮到 MAA 資料夾下，這樣可以直接在 ADB 路徑中填寫 `.\platform-tools\adb.exe`，方便隨著 MAA 資料夾移動。 -## 連接地址 +## 連線位址 ::: tip -執行在本機的模擬器連接地址應該是 `127.0.0.1:<埠號>` 或 `emulator-<四位數字>`。 +執行於本機電腦的模擬器，連線位址通常為 `127.0.0.1:<連接埠>` 或 `emulator-<四位數字>`。 ::: -### 獲取埠號 +### 模擬器連接埠相關文件 -#### 模擬器相關文件及參考埠 +- [BlueStacks 藍疊模擬器 5](https://support.bluestacks.com/hc/zh-tw/articles/360061342631)：模擬器設定 → 進階中可查看目前的連線位址。 +- [MuMu 模擬器](https://mumu.163.com/help/20240807/40912_1073151.html?maa)：主視窗（多開器）右上角選單按鈕 → 設定中心 → 底部 `ADB 端口` 可查看正在執行的多開連接埠。 +- [MuMu 模擬器 Pro](https://mumu.163.com/mac/function/20240126/40028_1134600.html) +- [雷電模擬器 9](https://help.ldmnq.com/docs/LD9adbserver#edc3863750608062bcb3feea256413dc) +- [夜神模擬器](https://support.yeshen.com/zh-CN/qt/ml) +- [逍遙模擬器](https://bbs.xyaz.cn/forum.php?mod=viewthread&tid=365537) -- [Bluestacks 5](https://support.bluestacks.com/hc/zh-tw/articles/360061342631-%E5%A6%82%E4%BD%95%E5%B0%87%E6%82%A8%E7%9A%84%E6%87%89%E7%94%A8%E5%BE%9EBlueStacks-4%E8%BD%89%E7%A7%BB%E5%88%B0BlueStacks-5#%E2%80%9C2%E2%80%9D) `5555` -- [MuMu](https://mumu.163.com/help/20240807/40912_1073151.html?maa) `16384` -- [MuMu Pro](https://mumu.163.com/mac/function/20240126/40028_1134600.html) `16384` -- [逍遙](https://bbs.xyaz.cn/forum.php?mod=viewthread&tid=365537) `21503` -- [夜神](https://support.yeshen.com/zh-CN/qt/ml) `62001` - -其他模擬器可參考 [趙青青的部落格](https://www.cnblogs.com/zhaoqingqing/p/15238464.html)。 - -#### 獲取多開埠 - -- MuMu 多開器右上角可檢視正在執行的多開埠。 -- Bluestacks 5 模擬器設定內可檢視當前的多開埠。 -- _待補充_ +其他模擬器可參閱 [趙青青的博客](https://www.cnblogs.com/zhaoqingqing/p/15238464.html)。 ::: details 備選方案 -- 方案 1 : 使用 ADB 命令檢視模擬器埠 - 1. 啟動**一個**模擬器，並確保沒有其他安卓裝置連接在此電腦上。 - 2. 在存放有 ADB 可執行檔案的資料夾中啟動終端。 - 3. 執行以下命令。 +- **方案 1：使用 ADB 指令查看模擬器連接埠** + 1. 啟動**一個**模擬器，並確保沒有其他 Android 裝置連接到此電腦。 + 2. 在存放 ADB 執行檔的資料夾中啟動終端機（Terminal）。 + 3. 執行以下指令： ```sh - # Windows 命令提示符 + # Windows 命令提示字元 (cmd) adb devices # Windows PowerShell .\adb devices ``` - 以下為輸出內容的例子： + 輸出範例如下： ```text List of devices attached - 127.0.0.1:<埠號> device + 127.0.0.1:<連接埠> device emulator-<四位數字> device ``` - 使用 `127.0.0.1:<埠>` 或 `emulator-<四位數字>` 作為連接地址。 + 使用 `127.0.0.1:<連接埠>` 或 `emulator-<四位數字>` 作為連線位址即可。 -- 方案 2 : 查詢已建立的 ADB 連接 +- 方案 2 ：尋找已建立的 ADB 連線 1. 執行方案 1。 - 2. 按下 `Win+S` 開啟搜尋欄，輸入 `資源監視器` 並開啟。 - 3. 切換到 `網路` 索引標籤，在 `接聽連接埠` 的名稱列中查詢模擬器程式名，如 `HD-Player.exe`。 - 4. 記錄模擬器程式的所有接聽連接埠。 - 5. 在 `TCP 連接` 的名稱列中查詢 `adb.exe`，在遠端連接埠列中與模擬器接聽連接埠一致的埠，即為模擬器除錯埠。 + 2. 按下 `Win+S` 開啟搜尋列，輸入 `資源監控制器` 並開啟。 + 3. 切換到 `網路` 索引標籤，在 `接聽連接埠` 的名稱欄位中尋找模擬器程序名稱（例如 `HD-Player.exe`）。 + 4. 記錄模擬器程序所有的接聽連接埠。 + 5. 在 `TCP 連線` 的名稱欄位尋找 `adb.exe`，遠端連接埠與模擬器接聽連接埠一致者，即為偵錯連接埠。 ::: -### 藍疊模擬器 Hyper-V 每次啟動埠號都不一樣 +### BlueStacks 藍疊模擬器 Hyper-V 每次啟動連接埠都不一樣 -在 `連接設定` 中設定 `連接配置` 為 `藍疊模擬器` ，隨後勾選 `自動檢測連接` 和 `每次重新檢測`。 +在 `連線設定` 中將 `連線配置` 設為 `藍疊模擬器`，隨後勾選 `自動偵測連線` 和 `每次重新偵測`。 -通常情況下這樣就可以連接。如果無法連接，可能是存在多個模擬器核心，或出現了問題，請閱讀下文進行額外設定。 +通常這樣即可連線。若無法連線，可能是因為存在多個核心或設定異常，請參考下文進行進階設定。 -#### 指定 `Bluestacks.Config.Keyword` +:::: steps -::: info 注意 -如果啟用了多開功能或安裝了多個模擬器核心，則需要進行額外設定來指定使用的模擬器編號 -::: +1. 指定 `Bluestacks.Config.Keyword` -在 `.\config\gui.json` 中搜索 `Bluestacks.Config.Keyword` 欄位，內容為 `"bst.instance.<模擬器編號>.status.adb_port"`，模擬器編號可在模擬器路徑的 `BlueStacks_nxt\Engine` 中看到 + ::: info 注意 + 若啟用了多開功能或安裝了多個模擬器核心，則需要指定使用的模擬器編號。 + ::: -::: details 範例 -Nougat64 核心： + 在 `.\config\gui.json` 中搜尋 `Bluestacks.Config.Keyword` 欄位，內容格式為 `"bst.instance.<模擬器編號>.status.adb_port"`。編號可於模擬器路徑的 `BlueStacks_nxt\Engine` 中確認。 -```json -"Bluestacks.Config.Keyword":"bst.instance.Nougat64.status.adb_port", -``` + ::: details 範例 + Nougat64 核心： -Pie64_2 核心：（核心名稱後的數字代表這是一個多開核心） + ```json + "Bluestacks.Config.Keyword":"bst.instance.Nougat64.status.adb_port", + ``` -```json -"Bluestacks.Config.Keyword": "bst.instance.Pie64_2.status.adb_port", -``` + Pie64_2 核心（核心名稱後的數字代表這是一個多開核心）： -::: + ```json + "Bluestacks.Config.Keyword": "bst.instance.Pie64_2.status.adb_port", + ``` -#### 指定 `Bluestacks.Config.Path` + ::: -::: info 注意 -MAA 現在會嘗試從登錄檔中讀取 `bluestacks.conf` 的儲存位置，當該功能無法工作時，則需要手動指定配置檔案路徑 -::: +2. 指定 `Bluestacks.Config.Path` -1. 在藍疊模擬器的資料目錄下找到 `bluestacks.conf` 這個檔案 - - 國際版預設路徑為 `C:\ProgramData\BlueStacks_nxt\bluestacks.conf` - - 中國版預設路徑為 `C:\ProgramData\BlueStacks_nxt_cn\bluestacks.conf` + ::: info 注意 + MAA 現在會嘗試從登錄檔（Registry）讀取 `bluestacks.conf` 的位置，若偵測失敗才需要手動指定路徑。 + ::: + 1. 在 BlueStacks 藍疊模擬器的數據目錄下找到 `bluestacks.conf` 檔案： + - 國際版預設路徑： `C:\ProgramData\BlueStacks_nxt\bluestacks.conf` + - 中國版預設路徑： `C:\ProgramData\BlueStacks_nxt_cn\bluestacks.conf` - 注：`C:\ProgramData`為隱藏目錄，必要時請在檔案資源管理器的地址欄中直接貼上該地址，以便進入目錄並進行尋找。 + 備註：`C:\ProgramData` 為隱藏目錄，請直接在檔案總管地址欄貼上路徑進入。 -2. 如果是第一次使用，請執行一次 MAA，使 MAA 自動生成配置檔案。 + 2. 初次使用請先執行一次 MAA 以產生設定檔。 + + 3. **先關閉** MAA，**再**開啟 `gui.json`。找到 `Configurations` 下目前的設定名稱（可在 `設定-切換配置` 中查看，預設為 `Default`），搜尋 `Bluestacks.Config.Path` 並填入 `bluestacks.conf` 的完整路徑（斜線請使用轉義符 `\\`）。 -3. **先關閉** MAA，**然後**開啟 `gui.json`，找到 `Configurations` 下的當前配置名欄位（可在 設定-切換配置 中檢視，預設為 `Default`），在其中搜索欄位 `Bluestacks.Config.Path`，填入 `bluestacks.conf` 的完整路徑。（注意斜槓要用轉義 `\\`） + ::: details 範例 + 以 `C:\ProgramData\BlueStacks_nxt\bluestacks.conf` 為例： -::: details 範例 -以 `C:\ProgramData\BlueStacks_nxt\bluestacks.conf` 為例 + ```json + { + "Configurations": { + "Default": { + "Bluestacks.Config.Path": "C:\\ProgramData\\BlueStacks_nxt\\bluestacks.conf" + // 其餘配置欄位，不要手動輸入修改 + } + } + } + ``` -```json -{ - "Configurations": { - "Default": { - "Bluestacks.Config.Path": "C:\\ProgramData\\BlueStacks_nxt\\bluestacks.conf" - // 其餘配置欄位，不要手動輸入修改 - } - } -} -``` + ::: -::: +3. 返回 MAA 並測試 -## 連接配置 + 您可以使用 `設定 - 執行設定` 中的 `截圖測試` 功能，檢查連線的是否為預期的核心。 -需選擇對應模擬器的配置，若列表中沒有則選擇通用配置。若通用配置不可用，請嘗試並選擇其他任一可用的配置。 +:::: -具體區別可以閱讀[原始碼](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/dev/resource/config.json#L57)。 +## 連線配置 + +請選擇對應模擬器的配置，若清單中沒有則選擇「通用配置」。若通用配置不可用，請嘗試並選擇其他任一可用的配置。 + +具體區別可以參閱 [原始碼](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/dev/resource/config.json#L57)。 ### MuMu 截圖增強模式 -需使用官版或方舟專版的 MuMu V4.1.26 及更新版本。 +需使用官版或方舟專版 MuMu V4.1.26 及更新版本。 -1. `設定` - `連接設定`，勾選 `啟用 MuMu 截圖增強模式`，MAA 會在勾選開關時嘗試通過註冊表自動填寫安裝路徑。 +1. 在 `設定 - 連線設定` 勾選 `啟用 MuMu 截圖增強模式`，MAA 會嘗試自動獲取路徑。 -2. `MuMu 安裝路徑` 填寫 `MuMu Player` 或 `MuMuPlayerGlobal-12.0` 或 `YXArkNights-12.0` 資料夾的路徑，如 `C:\Program Files\Netease\MuMuPlayerGlobal-12.0`。 +2. `MuMu 安裝路徑` 填寫 `MuMu Player` 或 `MuMuPlayerGlobal-12.0` 或 `YXArkNights-12.0` 資料夾路徑（例如 `C:\Program Files\Netease\MuMuPlayerGlobal-12.0`）。 -3. 若正在使用 MuMu 網絡橋接，則需勾選 `MuMu 網絡橋接模式` 後手動填寫 MuMu 多開器內對應模擬器的序號，如主多開為 `0`。 +3. 若正在使用 MuMu 網路橋接，需勾選 `MuMu 網路橋接模式` 並手動填寫多開器內對應的模擬器序號，主多開為 `0`。 ### 雷電截圖增強模式 -需使用中國版或國際版雷電模擬器 9 V9.1.32 及更新版本。 +需使用官版或國際版雷電模擬器 9 V9.1.32 及更新版本。 -1. `設定` - `連接設定`，勾選 `啟用 LD 截圖增強模式`，MAA 會在勾選開關時嘗試通過註冊表自動填寫安裝路徑。 +1. 在 `設定 - 連線設定` 勾選 `啟用 LD 截圖增強模式`，MAA 會嘗試自動獲取路徑。 -2. `LD 安裝路徑` 填寫 `LDPlayer9` 資料夾的路徑，如 `C:\leidian\LDPlayer9\`。 +2. `LD 模擬器路徑` 填寫 `LDPlayer9` 資料夾路徑（例如 `C:\leidian\LDPlayer9\`）。 -3. `例項編號` 填寫雷電多開器內對應模擬器的編號（ID），如主多開為 `0`。 +3. `執行個體編號` 填寫雷電多開器內對應的模擬器序號（ID），主多開為 `0`。 ## 觸控模式 -1. [Minitouch](https://github.com/DeviceFarmer/minitouch)：使用 C 編寫的 Android 觸控事件器，操作 `evdev` 裝置，提供 Socket 介面供外部程式觸發觸控事件和手勢。從 Android 10 開始，Minitouch 在 SELinux 為 `Enforcing` 模式時不再可用。[源](https://github.com/DeviceFarmer/minitouch?tab=readme-ov-file#for-android-10-and-up) -2. [MaaTouch](https://github.com/MaaAssistantArknights/MaaTouch)：由 MAA 基於 Java 對 Minitouch 的重新實現，使用安卓原生的 `InputDevice`，並添加了額外特性。高版本 Android 可用性尚待測試。~~幫我們做做測試~~ -3. Adb Input：直接呼叫 ADB 使用安卓的 `input` 命令進行觸控操作，相容性最強，速度最慢。 +1. [Minitouch](https://github.com/DeviceFarmer/minitouch)：基於 C 語言編寫的 Android 觸控事件驅動程式，透過操作 `evdev` 裝置，提供 Socket 介面供外部程式觸發觸控事件與手勢。自 Android 10 開始，若系統的 SELinux 為 `Enforcing`（強制）模式，Minitouch 將無法運作。[來源](https://github.com/DeviceFarmer/minitouch?tab=readme-ov-file#for-android-10-and-up) +2. [MaaTouch](https://github.com/MaaAssistantArknights/MaaTouch)：由 MAA 基於 Java 對 Minitouch 的重新實作，改用 Android 原生的 `InputDevice`介面，並加入額外特性。目前在高版本 Android 上的相容性仍待測試，~~幫我們做做測試~~。 +3. Adb Input：直接呼叫 ADB 執行 Android 內建的 `input` 指令來進行觸控操作。此方式的相容性最強，但執行速度最慢。 ## ADB Lite -由 MAA 獨立實現的 ADB Client，使用 TCP 直接與 ADB Server 通訊。相較原版 ADB 可以避免不停開啟多個 ADB 程式，減少效能開銷，但部分截圖方式不可用。[PR](https://github.com/MaaAssistantArknights/MaaAssistantArknights/pull/3315) +由 MAA 獨立實現的 ADB 用戶端，使用 TCP 直接與 ADB Server 通信。相較原版 ADB 可避免頻繁開啟 ADB 程序並減少效能開銷，但部分截圖方式不支援。[PR](https://github.com/MaaAssistantArknights/MaaAssistantArknights/pull/3315) -推薦啟用，但具體優缺點尚待反饋。~~幫我們做做測試 x2~~ +推薦開啟，但具體表現尚待回饋。~~幫我們做做測試 x2~~ -## MAA 和模擬器多開 +## MAA 與模擬器多開 -::: info -若需要多開模擬器同時操作，可將 MAA 資料夾複製多份，使用 **不同的 MAA**、**同一個 adb.exe**、**不同的連接地址** 來進行連接。 +::: info 實作方式 +若需多開模擬器同時執行，可將 MAA 資料夾複製多份，透過 **不同的 MAA 程式**、**同一個 adb.exe**、**不同的連線地址** 來進行連線。 ::: ### 自動啟動多開模擬器 -以[藍疊國際版](./device/windows.md)為例，介紹兩種自動啟動多開模擬器的方式。 +以 [BlueStacks 藍疊模擬器國際版](./device/windows.md) 為例，介紹兩種自動啟動多開模擬器的方式。 -#### 透過附加命令啟動 +#### 透過附加指令啟動 1. 啟動**單一**模擬器多開。 -2. 開啟工作管理員，找到對應模擬器程式，轉到詳細資訊索引標籤，右鍵列首，點選 `選擇列`，勾選 `命令列`。 -3. 在多出來的 `命令列` 列中找到 `...\Bluestacks_nxt\HD-Player.exe"` 後的內容。 -4. 將找到的類似於 `--instance Nougat32` 的內容填寫到 `啟動設定` - `附加命令` 中。 +2. 開啟工作管理員，找到對應的模擬器程序，切換到「詳細資料」索引標籤，右鍵點擊標題列，點選 `選擇行`（或選擇列），勾選 `命令列`。 +3. 在多出來的 `命令列` 欄位中，找到 `...\Bluestacks_nxt\HD-Player.exe"` 之後的內容。 +4. 將找到的內容（例如：`--instance Nougat32 `）填寫到 MAA 的 `啟動設定 - 附加指令` 中。 ::: note -操作結束後建議重新隱藏 `步驟 2` 中開啟的 `命令列` 列以防止卡頓 +操作結束後，建議重新隱藏 `步驟 2` 中開啟的 `命令列` 欄位以避免系統卡頓。 ::: ::: details 範例 ```text -多開1: +多開 1: 模擬器路徑: C:\Program Files\BlueStacks_nxt\HD-Player.exe -附加命令: --instance Nougat32 --cmd launchApp --package "com.hypergryph.arknights" -多開2: +附加指令: --instance Nougat32 --cmd launchApp --package "com.hypergryph.arknights" +多開 2: 模擬器路徑: C:\Program Files\BlueStacks_nxt\HD-Player.exe -附加命令: --instance Nougat32_1 --cmd launchApp --package "com.hypergryph.arknights.bilibili" +附加指令: --instance Nougat32_1 --cmd launchApp --package "com.hypergryph.arknights.bilibili" ``` -其中 `--cmd launchApp --package` 部分為啟動後自動執行指定包名應用，可自行更改。 +其中 `--cmd launchApp --package` 部分是啟動後自動執行指定包名的應用程式，可根據需求自行更改。 ::: -#### 透過模擬器的快捷方式啟動 +#### 透過模擬器的捷徑啟動 -部分模擬器支援建立應用快捷方式，可直接使用應用的快捷方式直接啟動模擬器並開啟明日方舟。 +部分模擬器支援建立應用程式捷徑，可直接使用捷徑啟動模擬器並開啟《明日方舟》。 -1. 開啟多開管理器，新增對應模擬器的快捷方式。 -2. 將模擬器快捷方式的路徑填入 `啟動設定` - `模擬器路徑` 中 +1. 開啟多開管理器，新增對應模擬器的捷徑到桌面。 +2. 將該模擬器捷徑的路徑填入 MAA 的 `啟動設定 - 模擬器路徑` 中。 ::: details 範例 ```text -多開1: +多開 1: 模擬器路徑: C:\ProgramData\Microsoft\Windows\Start Menu\Programs\BlueStacks\多開1.lnk -多開2: +多開 2: 模擬器路徑: C:\ProgramData\Microsoft\Windows\Start Menu\Programs\BlueStacks\多開2-明日方舟.lnk ``` ::: -若使用 `模擬器路徑` 進行多開操作，建議將 `啟動設定` - `附加命令` 置空。 +若使用 `模擬器路徑` （捷徑方式）進行多開操作，建議將 `啟動設定 - 附加指令` 欄位清空。 \ No newline at end of file diff --git a/docs/zh-tw/manual/device/README.md b/docs/zh-tw/manual/device/README.md index c12e904a92..ebc35941ac 100644 --- a/docs/zh-tw/manual/device/README.md +++ b/docs/zh-tw/manual/device/README.md @@ -1,9 +1,9 @@ --- -title: 模擬器和設備支持 +title: 模擬器與設備支援 icon: mingcute:laptop-fill index: false dir: order: 5 --- - + \ No newline at end of file diff --git a/docs/zh-tw/manual/device/android.md b/docs/zh-tw/manual/device/android.md index ca1e524e4d..119b3d52ef 100644 --- a/docs/zh-tw/manual/device/android.md +++ b/docs/zh-tw/manual/device/android.md @@ -6,53 +6,54 @@ icon: mingcute:android-fill # Android 實體設備 ::: warning -此方法涉及 ADB 命令行，穩定性較低且仍需與電腦連接，**不推薦** 0 基礎玩家嘗試。 +此方法涉及 ADB 命令列，穩定性較低且仍需與電腦連線，**不推薦**零基礎玩家嘗試。 ::: ::: info 注意 +0. 需同時參考 [連線設定](../connection.md)。 1. 從 Android 10 開始，Minitouch 在 SELinux 為 `Enforcing` 模式時不再可用，請切換至其他觸控模式，或將 SELinux **臨時**切換為 `Permissive` 模式。 -2. 由於 Android 生態極為複雜，可在 MAA `設定` - `連接設定` 中嘗試將 `連接配置` 修改為 `通用模式` 或 `兼容模式` 或 `第二解析度` 或 `通用模式（屏蔽異常輸出）`，直到某個模式可以正常使用。 -3. 由於 MAA 僅支援 `16:9` 比例的解析度，所以非 `16:9` 或 `9:16` 螢幕比例的設備需要強制修改解析度，這包含大多數現代設備。若被連接設備螢幕解析度比例原生為 `16:9` 或 `9:16`，則可跳過 `更改解析度` 部分。 -4. 請將設備導航方式切換為除 `全面屏手勢` 以外的方式，如 `經典導航鍵` 等以避免誤操作。 -5. 請將遊戲內設定中的 `異形屏UI適配` 一項調整為 0 以避免任務出錯。 +2. 由於 Android 生態極為複雜，可在 MAA `設定 - 連線設定` 中嘗試將 `連線配置` 修改為 `通用模式` 或 `相容模式` 或 `第二解析度` 或 `通用模式（屏蔽異常輸出）`，直到某個模式可以正常使用。 +3. 由於 MAA 僅支援 `16:9` 比例的解析度，因此非 `16:9` 或 `9:16` 螢幕比例的設備需要強制修改解析度，這包含大多數現代設備。若被連線設備螢幕解析度比例原生為 `16:9` 或 `9:16`，則可跳過 `更改解析度` 部分。 +4. 請將設備導覽方式切換為除 `全螢幕手勢` 以外的方式，如 `經典導覽鍵` 等以避免誤操作。 +5. 請將遊戲內設定中的 `螢幕 UI 調整` 該項數值調整為 0 以避免任務出錯。 ::: ::: tip -典型的 `16:9` 比例的解析度有 `3840*2160` (4K)、`2560*1440` (2K)、`1920*1080` (1080P)、`1280*720` (720P)。 +典型的 `16:9` 比例解析度有 `3840*2160` (4K)、`2560*1440` (2K)、`1920*1080` (1080P)、`1280*720` (720P)。 ::: -## 下載、運行 adb 調試工具並連接設備 +## 下載、執行 ADB 除錯工具並連線設備 -1. 下載 [adb](https://dl.google.com/android/repository/platform-tools-latest-windows.zip) 並解壓。 -2. 打開解壓後的資料夾，清空地址欄並輸入 `cmd` 後按回車。 -3. 在彈出的命令提示符視窗中輸入 `adb`，若顯示大量英文幫助文本則運行成功。 -4. 手機開啟 `USB 調試`，每個品牌的手機進入方式可能不同，請善用搜尋引擎。廠商可能會提供有關 USB 調試的額外選項，如 MIUI 中的 `USB 安裝` 和 `USB 調試（安全設置）`，請同時開啟。 -5. 將手機通過數據線連接至電腦，在剛剛的命令提示符視窗中輸入以下命令。 +1. 下載 [ADB](https://dl.google.com/android/repository/platform-tools-latest-windows.zip) 並解壓縮。 +2. 開啟解壓縮後的資料夾，清空位址列並輸入 `cmd` 後按下 Enter。 +3. 在彈出的命令提示字元視窗中輸入 `adb`，若出現大量英文說明文字則表示執行成功。 +4. 手機開啟 `USB 除錯`。每個品牌手機的開啟路徑可能不同，請善用搜尋引擎。廠商可能會提供有關 USB 除錯的額外選項，例如 MIUI 中的 `USB 安裝` 和 `USB 除錯（安全設定）`，請同時開啟。 +5. 將手機透過傳輸線連線至電腦，在剛才的命令提示字元視窗中輸入以下指令： ```bash adb devices ``` -- 成功執行後會顯示已連接 `USB 調試` 設備的信息。 - - 連接成功的例子： +- 成功執行後會顯示已連線 `USB 除錯` 設備的資訊。 + - 連線成功的例子： ```bash List of devices attached VFNDU1682100xxxx device ``` - - **`device` 前的英文數字組合為設備序列號，同時也作為 MAA 的 `連接地址`。** + - **`device` 前的英數字組合為設備序號，同時也作為 MAA 的 `連線位址`。** -- 現代安卓設備進行 `USB 調試` 需在被調試設備上點擊彈窗授權，若未授權則例子如下： +- 現代 Android 設備進行 `USB 除錯` 需在被除錯設備上點選彈窗授權，若未授權則例子如下： ```bash List of devices attached VFNDU1682100xxxx unauthorized ``` -- 若無論如何都提示未授權或設備序列號後顯示 `offline`，則需重啟設備及電腦後重試。如仍未解決問題，可刪除當前用戶個人資料夾下的 `.android` 資料夾並再次重啟後重試，具體位置請自行搜尋。 +- 若無論如何都提示未授權或設備序號後顯示 `offline`，則需重啟設備及電腦後重試。如仍未解決問題，可刪除目前使用者個人資料夾下的 `.android` 資料夾並再次重啟後重試，具體位置請自行搜尋。 ## 更改解析度 @@ -60,10 +61,10 @@ icon: mingcute:android-fill 手機螢幕解析度為 `短邊*長邊`，而非電腦顯示器的 `長邊*短邊`。具體數值請根據目標設備自行確定。 ::: -- 如果上文設備列表內僅有一台設備，則可直接運行以下命令更改/還原解析度。 +- 如果上文設備列表內僅有一台設備，則可直接執行以下指令更改 / 還原解析度。 ```bash - # 查看當前解析度 + # 查看目前解析度 adb shell wm size # 還原預設解析度 adb shell wm size reset @@ -74,10 +75,10 @@ icon: mingcute:android-fill adb shell wm size 1080x1920 ``` -- 若存在多台設備，則需在 `adb` 和 `shell` 中間添加參數 `-s <目標設備序列號>`，例子如下。 +- 若存在多台設備，則需在 `adb` 和 `shell` 中間加上參數 `-s <目標設備序號>`，範例如下： ```bash - # 查看當前解析度 + # 查看目前解析度 adb -s VFNDU1682100xxxx shell wm size # 還原預設解析度 adb -s VFNDU1682100xxxx shell wm size reset @@ -88,109 +89,111 @@ icon: mingcute:android-fill adb -s VFNDU1682100xxxx shell wm size 1080x1920 ``` -- 部分設計不規範的應用可能在還原解析度後內容佈局仍然錯亂，一般重啟對應應用或設備即可解決。 +- 部分設計不規範的應用程式可能在還原解析度後內容佈局仍然錯亂，一般重啟對應應用程式或設備即可解決。 ::: danger 注意 -強烈建議在**下次重啟設備前**還原解析度，否則因設備而定可能會導致不可預料的後果，~~包括但不限於佈局混亂，觸控錯位，應用閃退，無法解鎖等~~。 +強烈建議在**下次重啟設備前**還原解析度，否則依設備而定可能會導致不可預料的後果，~~包括但不限於佈局混亂、觸控錯位、應用程式閃退、無法解鎖等~~。 ::: ::: danger 注意 -已知在部分實體裝置上，`帳號切換` 功能可能無法正常運作。MAA 主要在電腦端模擬器環境下執行，因此目前沒有修復該問題的計畫。 +已知在部分實體設備上 `帳號切換` 功能可能無法正常運作。MAA 主要在電腦端模擬器環境運作，因此並無計畫修復該問題。 -如果你遇到這個問題，可以透過以下任意一種方式調整顯示 DPI（建議取值為 `[100–800]`）： +如果您遇到這個問題，可以透過以下任意一種方式修改螢幕密度 (DPI)（建議取值為 `[100-800]`）： - 使用指令 `adb shell wm density ` 直接修改 DPI -- 調整 `開發人員選項 → 最小寬度`，透過修改 `最小寬度` 間接改變 DPI +- 調整 `開發者選項 → 最小寬度`，透過修改 `最小寬度` 間接修改 DPI - 注：`DPI` 與 `最小寬度` 呈反比，換算關係為 `最小寬度 = 螢幕寬度(px) / (DPI / 160)` + 備註：`DPI` 和 `最小寬度` 成反比，換算關係為 `最小寬度 = 螢幕寬度(px) / (DPI / 160)` -**請注意此操作具有風險，可能導致設備異常。請確保你清楚自己在做什麼，若發生故障須自行承擔後果。** +**請注意該操作存在風險，可能使設備運作異常。請確保您知道自己在做什麼，設備故障後果自負。** -強烈建議在**下次重新啟動設備前**還原這些變更。若忘記預設值，無論使用哪種方式修改，都可以使用指令 `adb shell wm density reset` 還原。 +強烈建議在**下次重啟設備前**還原這些更改。若忘記預設值，無論使用何種方式修改，均可使用指令 `adb shell wm density reset` 還原。 ::: ## 自動化更改解析度 -1. 在 MAA 目錄下新建兩個文本檔案，分別在其中填入以下內容。 +1. 在 MAA 目錄下新建兩個文字檔案，分別在其中填入以下內容： ```bash # 調整解析度為 1080p - adb -s <目標設備序列號> shell wm size 1080x1920 - # 降低螢幕亮度（可選） - adb -s <目標設備序列號> shell settings put system screen_brightness 1 + adb -s <目標設備序號> shell wm size 1080x1920 + # 降低螢幕亮度（選填） + adb -s <目標設備序號> shell settings put system screen_brightness 1 ``` ```bash # 還原解析度 - adb -s <目標設備序列號> shell wm size reset - # 提高螢幕亮度（可選） - adb -s <目標設備序列號> shell settings put system screen_brightness 20 - # 返回桌面（可選） - adb -s <目標設備序列號> shell input keyevent 3 - # 鎖屏（可選） - adb -s <目標設備序列號> shell input keyevent 26 + adb -s <目標設備序號> shell wm size reset + # 提高螢幕亮度（選填） + adb -s <目標設備序號> shell settings put system screen_brightness 20 + # 返回桌面（選填） + adb -s <目標設備序號> shell input keyevent 3 + # 鎖定螢幕（選填） + adb -s <目標設備序號> shell input keyevent 26 ``` -2. 將第一個檔案重命名為 `startup.bat`，第二個檔案重命名為 `finish.bat`。 - - 如果重命名後沒有彈出修改擴展名的二次確認對話框，且檔案圖示沒有變化，請自行搜尋“Windows 如何顯示檔案擴展名”。 +2. 將第一個檔案重新命名為 `startup.bat`，第二個檔案重新命名為 `finish.bat`。 + - 如果重新命名後沒有彈出修改副檔名的確認對話框，且檔案圖示沒有變化，請自行搜尋「Windows 如何顯示檔案副檔名」。 -3. 在 MAA 的 `設定` - `連接設定` - `開始前腳本` 和 `結束後腳本` 中分別填入 `startup.bat` 和 `finish.bat`。 +3. 在 MAA 的 `設定 - 連線設定 - 開始前腳本` 和 `結束後腳本` 中分別填入 `startup.bat` 和 `finish.bat`。 -## 連接 MAA +## 連線 MAA -### 有線連接 +### 有線連線 ::: tip -使用有線連接不需要任何 IP 地址或埠，只需要 `adb devices` 給出的設備序列號。 +使用有線連線不需要任何 IP 位址或連接埠，只需要 `adb devices` 提供的設備序號。 ::: -1. 將上文獲取到的目標設備序列號填入 MAA `設定` - `連接設定` - `連接地址` 中。 +1. 將上文獲取到的目標設備序號填入 MAA `設定 - 連線設定 - 連線位址` 中。 2. Link Start! -### 無線連接 +### 無線連線 -- 請確保設備與電腦處在同一區域網環境下且能互相通信。諸如 `AP 隔離`、`訪客網路` 等設定會阻止設備間通信，具體請查閱對應路由器文檔。 -- 無線調試在設備重啟後失效，需要重新設定。 +- 請確保設備與電腦處在同一區域網路環境下且能互相通訊。諸如 `AP 隔離`、`訪客網路` 等設定會阻止設備間通訊，具體請查閱對應路由器文件。 +- 無線除錯在設備重啟後會失效，需要重新設定。 -#### 使用 `adb tcpip` 開啟無線埠 +#### 使用 `adb tcpip` 開啟無線連接埠 -1. 在剛剛的命令提示符視窗中輸入以下命令以開啟無線調試。 +1. 在剛才的命令提示字元視窗中輸入以下指令以開啟無線除錯： ```bash adb tcpip 5555 - # 存在多台設備則添加參數 -s 以指定序列號 + # 存在多台設備則新增參數 -s 以指定序號 ``` -2. 查看設備 IP 地址。 - - 進入手機 `設定` - `WLAN`，點擊當前已連接的無線網路查看 IP 地址。 - - 各類品牌設備設定位置不同，請自行查找。 +2. 查看設備 IP 位址 + - 進入手機 `設定 - WLAN`，點選目前已連線的無線網路查看 IP 位址。 + - 各品牌設備設定位置不同，請自行查找。 + +3. 將 `:5555` 填入 MAA `設定 - 連線設定 - 連線位址` 中，例如 `192.168.1.2:5555`。 -3. 將 `:5555` 填入 MAA `設定` - `連接設定` - `連接地址` 中，如 `192.168.1.2:5555`。 4. Link Start! -#### 使用 `adb pair` 開啟無線埠 +#### 使用 `adb pair` 開啟無線連接埠 ::: tip -`adb pair` 無線配對，即使用安卓 11 及更新版本中開發者選項內的 `無線調試` 進行配對後連接，與 `adb tcpip` 相比可以避免有線連接。 +`adb pair` 無線配對，即使用 Android 11 及更新版本中開發者選項內的 `無線偵錯` 進行配對後連線，與 `adb tcpip` 相比可以避免有線連線。 ::: -1. 進入手機開發者選項，點擊 `無線調試` 並開啟，點擊確定，點擊 `使用配對碼配對設備`，在配對完成前不要關閉出現的彈窗。 +1. 進入手機開發者選項，點選 `無線偵錯` 並開啟，點選確定，點選 `使用配對碼配對設備`，在配對完成前不要關閉出現的彈窗。 2. 進行配對。 - 1. 在命令提示符中輸入 `adb pair <設備彈窗給出的 IP 地址和埠>`，按回車。 - 2. 輸入 `<設備彈窗給出的六位配對碼>`，按回車。 - 3. 視窗出現 `Successfully paired to ` 等內容，同時設備上的彈窗自動消失，底部已配對的設備中出現計算機名稱。 + 1. 在命令提示字元中輸入 `adb pair <設備彈窗提供的 IP 位址和連接埠>`，按下 Enter。 + 2. 輸入 `<設備彈窗提供的六位配對碼>`，按下 Enter。 + 3. 視窗出現 `Successfully paired to ` 等內容，同時設備上的彈窗自動消失，底部已配對的設備中出現電腦名稱。 + +3. 將目前設備螢幕上顯示的 <`IP 位址和連接埠>` 填入 MAA `設定 - 連線設定 - 連線位址` 中，例如 `192.168.1.2:11451`，請注意**一定與剛才填寫的位址不同**。 -3. 將當前設備螢幕上給出的 `` 填入 MAA `設定` - `連接設定` - `連接地址` 中，如 `192.168.1.2:11451`，**一定和剛剛填寫的不一樣**。 4. Link Start! -#### 使用 root 權限開啟無線埠 +#### 使用 root 權限開啟無線連接埠 -~~都接觸到 root 了還用得著看這段文檔嗎~~ +~~都接觸到 Root 了還需要看這段文件嗎~~ -1. 下載、安裝 [WADB](https://github.com/RikkaApps/WADB/releases) 並授予其 root 權限。 -2. 打開 WADB，啟動無線 adb。 -3. 將 WADB 提供的 IP 地址及埠填入 MAA `設定` - `連接設定` - `連接地址` 中，如 `192.168.1.2:5555`。 -4. Link Start! +1. 下載、安裝 [WADB](https://github.com/RikkaApps/WADB/releases) 並授予其 Root 權限。 +2. 開啟 WADB，啟動無線 ADB。 +3. 將 WADB 提供的 IP 位址及連接埠填入 MAA `設定 - 連線設定 - 連線位址` 中，例如 `192.168.1.2:5555`。 +4. Link Start! \ No newline at end of file diff --git a/docs/zh-tw/manual/device/linux.md b/docs/zh-tw/manual/device/linux.md index c7f746fabe..649efe887c 100644 --- a/docs/zh-tw/manual/device/linux.md +++ b/docs/zh-tw/manual/device/linux.md @@ -11,75 +11,118 @@ icon: teenyicons:linux-alt-solid ### 使用 maa-cli -[maa-cli](https://github.com/MaaAssistantArknights/maa-cli) 是一個使用 Rust 編寫的簡單 MAA 命令列工具。相關安裝與使用教程請閱讀[CLI 使用指南](../cli)。 +[maa-cli](https://github.com/MaaAssistantArknights/maa-cli) 是一個使用 Rust 編寫的簡單 MAA 命令列工具。相關安裝與使用教學請閱讀 [CLI 使用指南](../cli/)。 + +### 使用 Wine + +MAA WPF GUI 當前可以透過 Wine 執行。 + +#### 安裝步驟 + +1. 前往 [.NET 發佈頁](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) 下載並安裝 Windows 版 .NET **桌面**執行環境 (Runtime)。 + +2. 下載 Windows 版 MAA，解壓縮後執行 `wine MAA.exe`。 + +::: info 注意 +需要在連線設定中將 ADB 路徑設定為 [Windows 版 `adb.exe`](https://dl.google.com/android/repository/platform-tools-latest-windows.zip)。 + +如果您需要透過 ADB 連線 USB 設備，請先在 Wine 外執行 `adb start-server`，即透過 Wine 連線原生 ADB server。 +::: + +#### 使用 Linux 原生 MaaCore（實驗性功能） + +下載 [MAA Wine Bridge](https://github.com/MaaAssistantArknights/MaaAssistantArknights/tree/dev/src/MaaWineBridge) 原始碼並建置，用產生的 `MaaCore.dll`（ELF 檔案）替換 Windows 版本，並將 Linux 原生動態函式庫（`libMaaCore.so` 以及依賴項）放在同一目錄下。 + +此時透過 Wine 執行 `MAA.exe`，將會載入 Linux 原生動態函式庫。 + +::: info 注意 +使用 Linux 原生 MaaCore 時，需要在連線設定中將 ADB 路徑設定為 Linux 原生 ADB。 +::: + +#### Linux 桌面整合（實驗性功能） + +桌面整合提供原生桌面通知支援，以及將 fontconfig 字型配置對應到 WPF 的功能。 + +將 MAA Wine Bridge 產生的 `MaaDesktopIntegration.so` 放到 `MAA.exe` 同目錄下即可啟用。 + +#### 已知問題 + +- Wine DirectWrite 強制啟用 hinting，且不將 DPI 傳遞給 FreeType，導致字型顯示效果不佳。 +- 不使用原生桌面通知時，彈出通知會搶佔全系統滑鼠焦點，導致無法操作其他視窗。可以透過 `winecfg` 啟用虛擬桌面模式緩解，或停用桌面通知。 +- Wine-staging 使用者需要關閉 `winecfg` 中的 `隱藏 Wine 版本` 選項，以便 MAA 正確偵測 Wine 環境。 +- Wine 的 Light 主題會導致 WPF 中部分文字顏色異常，建議在 `winecfg` 中切換到無主題（Windows 經典主題）。 +- Wine 使用舊式 XEmbed 系統匣圖示，在 GNOME 下可能無法正常工作。 +- 使用 Linux 原生 MaaCore 時暫不支援自動更新（~~更新程式：我想我應該下載個 Windows 版~~） ### 使用 Python -#### 1. 安裝 MAA 動態庫 +:::: steps -1. 在 [MAA 官網](https://maa.plus/) 下載 Linux 動態庫並解壓，或從軟體源安裝： - - AUR：[maa-assistant-arknights](https://aur.archlinux.org/packages/maa-assistant-arknights)，按照安裝後的提示編輯檔案 - - Nixpkgs: [maa-assistant-arknights](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/ma/maa-assistant-arknights/package.nix) +1. 安裝 MAA 動態函式庫 + 1. 在 [MAA 官網](https://maa.plus/) 下載 Linux 動態函式庫並解壓縮，或從軟體源安裝： + - AUR：[maa-assistant-arknights](https://aur.archlinux.org/packages/maa-assistant-arknights)，按照安裝後的提示編輯檔案 + - Nixpkgs: [maa-assistant-arknights](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/ma/maa-assistant-arknights/package.nix) + 2. 進入 `./MAA-v{版本號}-linux-{架構}/Python/` 目錄下開啟 `sample.py` 檔案 -2. 進入 `./MAA-v{版本號}-linux-{架構}/Python/` 目錄下打開 `sample.py` 文件 + ::: tip + 預編譯的版本包含在相對較新的 Linux 發行版 (Ubuntu 22.04) 中編譯的動態函式庫，如果您系統中的 libstdc++ 版本較舊，可能遇到 ABI 不相容的問題。 + 可以參閱 [Linux 編譯教學](../../develop/linux-tutorial.md) 重新編譯或使用容器執行。 + ::: -::: tip -預編譯的版本包含在相對較新的 Linux 發行版 (Ubuntu 22.04) 中編譯的動態庫，如果您系統中的 libstdc++ 版本較老，可能遇到 ABI 不兼容的問題 -可以參考 [Linux編譯教學](../../develop/linux-tutorial.md) 重新編譯或使用容器執行 -::: +2. ADB 配置 + 1. 找到 [`if asst.connect('adb.exe', '127.0.0.1:5554'):`](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/b4fc3528decd6777441a8aca684c22d35d2b2574/src/Python/sample.py#L62) 一欄 + 2. ADB 工具呼叫 + - 如果模擬器使用 `Android Studio` 的 `avd`，其內建 ADB。可以直接在 `adb.exe` 一欄填寫 ADB 路徑，通常在 `$HOME/Android/Sdk/platform-tools/` 裡面可以找到，例如： -#### 2. `adb` 配置 + ```python + if asst.connect("/home/foo/Android/Sdk/platform-tools/adb", "模擬器的 ADB 位址"): + ``` -1. 找到 [`if asst.connect('adb.exe', '127.0.0.1:5554'):`](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/722f0ddd4765715199a5dc90ea1bec2940322344/src/Python/sample.py#L48) 一欄 + - 如果使用其他模擬器須先下載 ADB： `$ sudo apt install adb` 後填寫路徑或利用 `PATH` 環境變數直接填寫 `adb` 即可。 -2. `adb` 工具調用 - - 如果模擬器使用 `Android Studio` 的 `avd` ，其內建 `adb` 。可以直接在 `adb.exe` 一欄填寫 `adb` 路徑，一般在 `$HOME/Android/Sdk/platform-tools/` 裡面可以找到，例如： + 3. 模擬器 ADB 路徑獲取 + - 可以直接使用 ADB 工具： `$ adb路徑 devices`，例如： - ```python - if asst.connect("/home/foo/Android/Sdk/platform-tools/adb", "模擬器的 adb 地址"): - ``` + ```shell + $ /home/foo/Android/Sdk/platform-tools/adb devices + List of devices attached + emulator-5554 device + ``` - - 如果使用其他模擬器須先下載 `adb` ： `$ sudo apt install adb` 後填寫路徑或利用 `PATH` 環境變量直接填寫 `adb` 即可 + - 回傳的 `emulator-5554` 就是模擬器的 ADB 位址，覆蓋掉 `127.0.0.1:5555`，例如： -3. 模擬器 `adb` 路徑獲取 - - 可以直接使用 adb 工具： `$ adb路徑 devices` ，例如： + ```python + if asst.connect("/home/foo/Android/Sdk/platform-tools/adb", "emulator-5554"): + ``` - ```shell - $ /home/foo/Android/Sdk/platform-tools/adb devices - List of devices attached - emulator-5554 device - ``` + 4. 這時候可以測試一下： `$ python3 sample.py`，如果回傳 `連接成功` 則基本成功了。 - - 返回的 `emulator-5554` 就是模擬器的 adb 地址，覆蓋掉 `127.0.0.1:5555` ，例如： +3. 任務配置 - ```python - if asst.connect("/home/foo/Android/Sdk/platform-tools/adb", "emulator-5554"): - ``` +自定義任務：根據需要參閱 [整合文件](../../protocol/integration.md) 對 `sample.py` 的 [`# 任務及參數請參考 docs/integration.md`](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/722f0ddd4765715199a5dc90ea1bec2940322344/src/Python/sample.py#L54) 一欄進行修改。 -4. 這時候可以測試下： `$ python3 sample.py` ，如果返回 `連接成功` 則基本成功了 - -#### 3. 任務配置 - -自定義任務： 根據需要參考 [集成文件](../../protocol/integration.md) 對 `sample.py` 的 [`# 任務及參數請參考 docs/集成文件.md`](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/722f0ddd4765715199a5dc90ea1bec2940322344/src/Python/sample.py#L54) 一欄進行修改 +:::: ## 模擬器支援 ### ✅ [AVD](https://developer.android.com/studio/run/managing-avds) -必選配置： 16:9 的螢幕解析度，且解析度需大於 720p +必選配置：16:9 的螢幕解析度，且解析度須大於 720p -推薦配置： x86_64 的框架 (R - 30 - x86_64 - Android 11.0) 配合 MAA 的 Linux x64 動態庫 +推薦配置：x86_64 的架構 (R - 30 - x86_64 - Android 11.0) 配合 MAA 的 Linux x64 動態函式庫 + +請注意：從 Android 10 開始，Minitouch 在 SELinux 為 `Enforcing` 模式時不再可用，請切換至其他觸控模式，或將 SELinux **臨時**切換為 `Permissive` 模式。 ### ⚠️ [Genymotion](https://www.genymotion.com/) -高版本安卓內建 x86_64 框架，輕量但是執行明日方舟時易閃退 +高版本 Android 內建 x86_64 架構，輕量但在執行《明日方舟》時易閃退。 -暫未嚴格測試， adb 功能和路徑獲取沒有問題 +暫未嚴格測試，ADB 功能與路徑獲取沒有問題。 -## 容器化安卓的支援 +## 容器化 Android 的支援 ::: tip -以下方案通常對核心模組有一定要求，請根據具體方案和發行版安裝合適的核心模組 +以下方案通常對核心模組 (kernel module) 有一定要求，請根據具體方案和發行版本安裝合適的核心模組。 ::: ### ✅ [Waydroid](https://waydro.id/) @@ -91,8 +134,12 @@ waydroid prop set persist.waydroid.width 1280 waydroid prop set persist.waydroid.height 720 ``` -設定 adb 的 IP 地址：打開 `設定` - `關於` - `IP 地址` ，記錄第一個 `IP` ，將 `${記錄的 IP}:5555` 填入`sample.py` 的 adb IP 一欄。 +設定 ADB 的 IP 位址：開啟 `設定` - `關於` - `IP地址` ，記錄第一個 `IP` ，將 `${記錄的IP}:5555` 填入 `sample.py` 的 adb IP 一欄。 + +如果使用 amdgpu，`screencap` 指令可能向 stderr 輸出資訊導致圖片解碼失敗。 +可以執行 `adb exec-out screencap | xxd | head` 並檢查輸出中是否有類似 `/vendor/etc/hwdata/amdgpu.ids: No such file...` 的文字來確認這一點。 +嘗試將 `resource/config.json` 中的截圖指令由 `adb exec-out screencap` 改為 `adb exec-out 'screencap 2>/dev/null'`。 ### ✅ [redroid](https://github.com/remote-android/redroid-doc) -安卓 11 版本的鏡像可正常執行遊戲，需要暴露 5555 adb 通訊埠. +Android 11 版本的映像檔可正常執行遊戲，需要開放 5555 ADB 連接埠。 \ No newline at end of file diff --git a/docs/zh-tw/manual/device/macos.md b/docs/zh-tw/manual/device/macos.md index 7a9f105311..94199f2262 100644 --- a/docs/zh-tw/manual/device/macos.md +++ b/docs/zh-tw/manual/device/macos.md @@ -5,64 +5,64 @@ icon: basil:apple-solid # Mac 模擬器 -::: tip -遇到問題請先參考 [常見問題](../faq.md) -::: - ## Apple Silicon 晶片 -### ✅ [PlayCover](https://playcover.io)（原生執行最流暢🚀） +### ✅ [PlayCover](https://playcover.io) 原生執行最流暢 🚀 -試驗性支援，遇到問題請多多提 issue，並在標題中提及 iOS。 +實驗性支援，遇到問題請多加提交 Issue，並在標題中提及 `MacOS`。 -注意：由於 `macOS` 本身機制的問題，將遊戲視窗最小化、台前調度狀態下切換到別的視窗、將視窗移動到別的桌面 / 螢幕之後，截圖會出現問題，導致無法正確執行。請參考👉🏻️[issue](https://github.com/MaaAssistantArknights/MaaAssistantArknights/issues/4371#issuecomment-1527977512) +請注意：由於 `MacOS` 本身機制的限制，將遊戲視窗最小化、幕前排程 (Stage Manager) 狀態下切換到其他視窗、或將視窗移動到其他桌面 / 螢幕後，截圖會出現問題，導致無法正確執行。相關 Issue [#4371](https://github.com/MaaAssistantArknights/MaaAssistantArknights/issues/4371#issuecomment-1527977512) 0. 要求：MAA 版本 v4.13.0-rc.1 以上 1. 下載 [fork 版本的 PlayCover](https://github.com/hguandl/PlayCover/releases) 並安裝。 -2. 下載 [脫殼的明日方舟用戶端安裝包](https://decrypt.day/app/id1454663939)，並在 PlayCover 中安裝。 +2. 下載 [脫殼的《明日方舟》客戶端安裝包](https://decrypt.day/app/id1454663939)，並在 PlayCover 中安裝。 -3. 在 PlayCover 中右鍵明日方舟，選擇 `設定` - `繞過`，勾選 `啟用 PlayChain`、`啟用繞過越獄檢測`、`插入內省庫`、`MaaTools`，然後點擊 `好`。 +3. 在 PlayCover 中右鍵點選《明日方舟》，選擇 `設定` - `繞過`，勾選 `啟用 PlayChain`、`啟用繞過越獄偵測`、`插入內省庫`、`MaaTools`，然後點選 `好`。 -4. 此時再啟動明日方舟，即可正常執行。標題欄結尾會有 `[localhost:通訊埠號]`，說明已經成功啟用。 +4. 此時再啟動《明日方舟》，即可正常執行。標題列結尾會有 `[localhost:連接埠號]`，說明已經成功啟用。 -5. 在 MAA 中，點擊 `設定` - `連接設定`，`觸控模式` 選擇 `MacPlayTools`。`連接地址` 填入上面標題欄 `[]` 裡的內容。 +5. 在 MAA 中，點選 `設定 - 連線設定`，`觸控模式` 選擇 `MacPlayTools`。`連線位址` 填入上面標題列 `[]` 內容。 -6. 設定完成，MAA 可以連接了。如果遇到圖像辨識出錯，可以嘗試在 PlayCover 內將解析度設定為 1080P。 +6. 設定完成，MAA 可以連線了。如果遇到圖像識別出錯，可以嘗試在 PlayCover 內將解析度設定為 1080P。 -7. 3-5 步驟只需要做一次，之後只需要啟動明日方舟即可。在明日方舟每次更新用戶端之後，需要重新做第 2 步。 +7. 3-5 步驟只需要做一次，之後只需要啟動《明日方舟》即可。在《明日方舟》每次更新客戶端之後，需要重新執行第 2 步。 + +### ✅ [MuMu 模擬器 Pro](https://mumu.163.com/mac/) + +支援，但測試較少，需使用除 `MacPlayTools` 以外的觸控模式。相關 Issue [#8098](https://github.com/MaaAssistantArknights/MaaAssistantArknights/issues/8098) ### ✅ [AVD](https://developer.android.com/studio/run/managing-avds) -支援。 +支援，但從 Android 10 開始，Minitouch 在 SELinux 為 `Enforcing` 模式時不再可用。請切換至其他觸控模式，或將 SELinux **臨時**切換為 `Permissive` 模式。 -### ✅ [藍疊模擬器Air版](https://www.bluestacks.com/mac) （免費，針對 Apple M 系列晶片進行優化的版本） +### ✅ [BlueStacks 藍疊模擬器 Air 版](https://www.bluestacks.com/mac) （免費，針對 Apple M 系列晶片進行優化的版本） -支援，經測試，可用 maatouch 經`127.0.0.1:5555`連接。 +支援，經測試，可用 maatouch 透過 `127.0.0.1:5555` 連線。 -需要在模擬器 **`設定`** - **`進階`** 中開啟 **`Android除錯（ADB）`**。 +需要在模擬器 `設定` - `進階` 中打開 `Android 調試 (ADB)`。 ## Intel 晶片 ::: tip -由於 Mac 版開發人手不足，更新速度相對較慢，更推薦使用 Mac 自帶的多系統安裝 Windows，並使用 Windows 版 MAA。 +由於 Mac 版開發人手較少，更新速度相對較慢，更推薦使用 Mac 內建的 Boot Camp 安裝 Windows，並使用 Windows 版 MAA。 ::: -### ✅ [藍疊模擬器](https://www.bluestacks.cn/) +### ✅ [BlueStacks 藍疊模擬器](https://www.bluestacks.cn/) -完美支援。需要在模擬器 `設定` - `引擎設定` 中打開 `允許 ADB 連接`。 +完美支援。需要在模擬器 `設定` - `引擎設定` 中打開 `允許 ADB 連線`。 -### ✅ [藍疊模擬器國際版](https://www.bluestacks.com/tw/index.html) +### ✅ [BlueStacks 藍疊模擬器國際版](https://www.bluestacks.com/tw/index.html) -完美支援。需要在模擬器 `設定` - `進階` 中打開 `Android 調試橋`。 +完美支援。需要在模擬器 `設定` - `進階` 中打開 `Android 調試橋 (ADB)`。 -### ✅ [夜神模擬器](https://www.yeshen.com/) +### ✅ [夜神模擬器 (NoxPlayer)](https://www.yeshen.com/) 完美支援。 -補充：mac 下夜神模擬器的 adb 二進制檔案的位置為 `/Applications/NoxAppPlayer.app/Contents/MacOS/adb`，在父目錄 `MacOS` 下可使用 `adb devices` 命令查看 adb 通訊埠。 +補充：mac 下夜神模擬器的 ADB 執行檔路徑為 `/Applications/NoxAppPlayer.app/Contents/MacOS/adb`，在父目錄 `MacOS` 下可使用 `adb devices` 指令查看 ADB 連接埠。 ### ✅ [AVD](https://developer.android.com/studio/run/managing-avds) -支援。 +支援，但從 Android 10 開始，Minitouch 在 SELinux 為 `Enforcing` 模式時不再可用。請切換至其他觸控模式，或將 SELinux **臨時**切換為 `Permissive` 模式。 \ No newline at end of file diff --git a/docs/zh-tw/manual/device/windows.md b/docs/zh-tw/manual/device/windows.md index 8303b9520b..d63080f007 100644 --- a/docs/zh-tw/manual/device/windows.md +++ b/docs/zh-tw/manual/device/windows.md @@ -5,7 +5,7 @@ icon: ri:windows-fill # Windows 模擬器 -以下模擬器排序為隨機生成，排名不分先後。 +以下模擬器排序為隨機產生，排名不分先後。