mirror of
https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
synced 2026-07-19 10:32:19 +08:00
14194d1118
格式化工具部分： 1. pre-commit 引入 python 的格式化工具，包括 black（代码格式化）和 isort（对“包导入顺序”的规范） 2. 允许 prettier 对文档站的 markdown 文件格式化 3. 不允许 prettier 对 markdown 文件中的代码块的代码本身进行格式化 4. 升级了 pre-commit 的各个 hook 的版本 5. 优化了 pre-commit 的日志文本显示 容器总览部分： 1. 由原来的单一轻量环境转为区分空环境、轻量环境和全量环境 2. 空环境是裸 Linux 镜像（Ubuntu），为默认环境 3. 轻量环境适合开发文档站前端 4. 全量环境适合开发 MaaCore 5. 目前，全量环境完整包含了轻量环境，轻量环境完整包含了空环境 6. 在仓库 README.md 中更新了三个环境的描述，并将链接分别设置为对应环境的创建链接 **注意：没有修改文档站中的对应文件** 7. 在各个语言的开发指南的最后，移除了 Codespace 部分的“安装额外依赖”相关描述，且将链接设置为全量环境的创建链接 **注意：没有添加“开发文档站”的指南和对应 codespace 的使用方式** 容器的轻量环境和全量环境共有部分： 1. 安装 black 和 isort 包 2. 调整 VS Code 设置，取消先前（对 markdown 文件单独指定 markdownlint 扩展作为格式化工具）的错误设置，现在 markdown 文件仍然使用默认的 prettier 扩展作为格式化工具 3. 引入 markdown-all-in-one 扩展作为语法提示工具 4. 将 node_modules 和 3rdparty 排除在 VS Code 的文本的搜索路径之外 容器的全量环境部分： 1. 为 tools 下的所有 python 脚本安装依赖 2. 使用 tools/maadeps-download.py 下载 maadeps，且将必要二进制文件软链接到 /usr/local/bin/ 3. 使用 apt 安装 cmake 和 clangd-20，将后者通过 update-alternatives 设置为系统 clangd 的默认版本 4. 使用 cmake tools 扩展，并按照 Linux 编译方法进行配置 5. 使用 clang-format 作为 c/cpp 的格式化工具，clang-format 程序主体来自 maadeps（已经软链接到 /usr/local/bin/） 6. 使用 clangd 作为 c/cpp 的语法提示工具 7. 将 MaaDeps、install 和 build 排除在 VS Code 的文本搜索路径之外 其它手动调整： 1. 更新文档站的 package.json，指定 pnpm 包管理器的版本 2. 手动保证 markdown 文件中的列表前后有空行（注意到 MarkdownLint 官方规则不一定能精准定位所有“列表前后空行”的问题，详见：https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md032---lists-should-be-surrounded-by-blank-lines ） 3. 修改了部分 markdown 文件中的 json 代码块的语法问题 **注意：相同的问题并未全部发现，仅修改了两处** 4. 在 tools 目录中，一处 python 脚本的包名误用（本地包名和某个 pip 包重名），这里修改了相应代码 5. 在 tools 目录中，一处 python 脚本使用了弃用的包 cchardet 的问题，这里更换了推荐使用的功能相近的包并修改了相应代码 自动化脚本提交的修改： 1. 自动格式化了大量 tools 中的 python 脚本 2. 自动格式化了大量 docs 中的 markdown 文件 Commits: * chore: pre-commit引入black和isort规范py文件 * chore: Auto update by pre-commit hooks [skip changelog] * chore: devcontainer添加isort扩展，排序python导入 * chore: pre-commit任务命名及更名 * style: isort fix * chore: Auto update by pre-commit hooks [skip changelog] * chore: 更新pre-commit的hook版本 * fix: 模块名与第三方库重名，大忌 * chore: 容器构建时额外安装isort * docs: md -> markdown * chore: 容器安装python包和maadeps * fix: 修复过时python包 * chore: 指定pnpm版本 * chore: container支持选择轻量环境 * chore: 去掉rust * chore: add plain env * chore: 使用clangd语言服务器 * chore: 无需单独设置markdown的格式化工具 * chore: 更新安装的clangd版本 * docs: 简易文档适配 * docs: 在仓库README中重新编排codespaces相关指引 * chore: Auto update by pre-commit hooks [skip changelog] * style: 调整缩进 * chore: 格式化工具不用特意排除被gitignore忽略的文件 * chore: sh文件在gitattributes中单列一类 * chore: 格式化docs下的markdown文件 * chore: 暂时不修改md文件中的代码块 * style: 人为明确markdown中的部分列表相关格式 * docs: 补上部分markdown的json代码块中缺失的逗号 * chore: Auto update by pre-commit hooks [skip changelog] * chore: Auto update by pre-commit hooks [skip changelog] * fix: 补上tools的服务器排序相关代码中缺失的逗号 Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * chore: 使用maadeps的clangd * build: 更新maadeps工具链版本 * style: prettier fix * revert: 还原maadeps版本 * revert: 取消使用maadeps的clangd依赖，改用系统apt安装 --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
143 lines
13 KiB
Markdown
143 lines
13 KiB
Markdown
---
|
||
order: 5
|
||
icon: ri:earth-fill
|
||
---
|
||
|
||
# グローバル版を含む海外クライアントの対応について
|
||
|
||
## 準備
|
||
|
||
このチュートリアルを始める前に、以下の内容を確認してください。
|
||
|
||
1. 必要なソフトウェアをインストールし、正しく設定されていること。大陸版クライアントまたは海外版クライアントの `readme.md` に、サポートされている機能が正しく動作するための情報があるはずです。
|
||
2. [タスクAPI](../protocol/task-schema.md) を読み、各フィールドの意味と使い方の基本を理解していること。また、コード中の `@` と `#` の意味と使い方を理解しておくこと。
|
||
3. 大陸版クライアントの `task.json` ファイルとテンプレート画像が海外クライアントに記載されていない、または不足している場合、代替手段として使用されることを理解していること。海外クライアントの `task.json` の内容は、大陸版のタスクのフィールドに合わせて書き換える必要があります。
|
||
4. ある程度の英語力があり、英語のログを読むことができ、ログから不足している画像やその他の情報を見つけることができること。
|
||
5. タスクチェーンに従って、個別に修正を行うことが推奨されることを理解していること。例えば、Awardタスクを修正する場合、`template image`, `text`, `roi` をその `next` フィールドの順序に従って段階的に修正する必要があります。こうすることで、すべてのタスクが修正後に正常に動作することを確認し、エラーを簡単に発見することができます。また、一度に多くのコンテンツを修正した場合に、どのタスクで止まっているのか忘れてしまうといった混乱も防ぐことができます。
|
||
|
||
### 変更前の準備
|
||
|
||
変更する前に、下記の注意すべきことあります。
|
||
|
||
1. 大陸版クライアントの `task.json` を参照し、海外クライアント用のテンプレート画像とテキストコンテンツが用意されていることを確認します。
|
||
2. これらの画像やテキストコンテンツにすぐにアクセスできるようにしておく。
|
||
|
||
## スクリーンショットを取得
|
||
|
||
高品質のスクリーンショットを得るためには、以下のガイドラインに従ってください。
|
||
|
||
1. エミュレータに付属のスクリーンショットツールを使って、スクリーンショットを撮影し保存します。
|
||
2. スクリーンショットのサイズが `1280*720` 以上、アスペクト比が `16:9` であることを確認する。
|
||
3. スクリーンショットにタスクバー、ステータスバー、通知バーなどの余計なコンテンツが含まれていないことを確認する。
|
||
4. スクリーンショットに、認識される必要があるすべてのコンテンツが含まれていることを確認します。
|
||
|
||
画像を切り出して、テキストや画像の関心領域（ROI）を得るためには、`Python` と `OpenCV` をインストールし、`MaaAssistantArknights/tools/CropRoi/main.py` ファイルをダウンロードする必要があります。
|
||
|
||
次に、以下の手順を実行します。
|
||
|
||
1. `main.py`と同じディレクトリに、新しい `src` と `dst` フォルダを作成します。
|
||
2. サイズを変更する必要がある、または新しいROI値を必要とするテキスト/画像の**完全なスクリーンショット**を `src` フォルダに配置します。
|
||
3. `main.py`を実行します。
|
||
4. マウスをドラッグして、余計なコンテンツが入らないようにしながら、対象範囲を選択します。
|
||
5. 範囲が決まったら、`S`で保存、`Q`ボタンで終了します。切り取られた画像は、dstフォルダに保存されます。
|
||
|
||
例えば、切り取られた後の出力は次のようになる。
|
||
|
||
```log
|
||
src: Screenshot_xxx.png
|
||
dst: Screenshot_xxx.png_426,272,177,201.png
|
||
original roi: 476, 322, 77, 101,
|
||
amplified roi: 426, 272, 177, 201
|
||
```
|
||
|
||
この例では、`Screenshot_xxx.png` が `src` フォルダに置かれたフルスクリーンショットの名前、`Screenshot_xxx.png_426,272,177,201.png` が切り出した画像の名前になります。
|
||
|
||
`original roi` はマウスで選択された領域で、`amplified roi`は拡大された領域である。拡大された領域が必要なので、task.json の roi フィールドに記入する際には `amplified roi` の値を使用する必要がある。
|
||
|
||
## テンプレート画像の修正
|
||
|
||
テンプレート画像を修正する前に、該当するクライアントのテンプレート画像フォルダと大陸版クライアントのテンプレート画像フォルダを開いておく必要があります。
|
||
|
||
例
|
||
|
||
- ENクライアントのテンプレートイメージフォルダの場所は `MaaAssistantArknights\resource\global\YoStarEN\resource\template`.
|
||
- 大陸版クライアントのテンプレートイメージフォルダの場所は `MaaAssistantArknights\resource\template`.
|
||
|
||
task.json`ファイルに記載されているテンプレート画像を参照し、大陸版クライアントと海外クライアントのテンプレート画像を比較し、海外クライアントに不足しているテンプレートを特定します。
|
||
|
||
一般的に、テキストを含むテンプレート画像は、ロゴなどの画像を除いて、スクリーンショットに置き換える必要があります。もし、画像のサイズが大陸版クライアントの対応するテンプレート画像よりも著しく大きい場合は、`roi`のサイズを修正する必要があるかもしれません。
|
||
|
||
テンプレート画像を取り込み、名前を変更したら、対応するクライアントのテンプレート画像フォルダに配置することができます。
|
||
|
||
## テキストの内容を変更する
|
||
|
||
テキスト内容を修正する前に、対応するサーバと大陸版クライアントの両方で `task.json` ファイルを開く必要があります。
|
||
|
||
例
|
||
|
||
- ENクライアントの `task.json` の場所は `MaaAssistantArknights\resource\global\YoStarEN\resource\tasks.json`.
|
||
- 大陸版クライアントの `task.json` の場所は `MaaAssistantArknights\resource\tasks.json`.
|
||
|
||
テキストを変更するには、対応するタスクを探し、`text`フィールドを対応するサーバーに表示されている内容に変更します。特定された内容は、ゲーム内の完全な内容の部分文字列である可能性があることに留意してください。一般的には、純粋なASCII文字として認識されない限り、テキストを含む`text`はすべて置き換える必要があります。
|
||
|
||
もし、テキストの長さが大陸版クライアントバージョンよりかなり長い場合、`roi`フィールドのサイズを修正する必要があるかもしれません。例えば、`"任务"`(中国語の任務)と英語の`"Mission"`の長さの差が大きすぎる場合、海外のクライアントではミッションの`roi`サイズを修正する必要があるかもしれません。
|
||
|
||
該当する海外サーバーの `task.json` ファイルにタスクが存在しない場合は、追加する必要があります。`text` フィールドに適切な内容を入力するだけです。
|
||
|
||
## ROIの範囲を変更する
|
||
|
||
ROIの範囲を変更するには
|
||
|
||
1. 対応するサーバーの `task.json` ファイルを開く。例えば、ENクライアントの `task.json` ファイルの場所は `MaaAssistantArknights\resource\global\YoStarEN\resource\tasks.json`。
|
||
2. 修正したいROI範囲に対応するタスクを探し、該当クライアントのスクリーンショットを使用して、増幅されたROIに応じて`roi`範囲のサイズを調整する。
|
||
3. 通常、`roi`の範囲を修正する必要はありませんが、テキストと大陸版のサイズの差が大きすぎる場合、修正する必要があるかもしれません。
|
||
4. 対応する海外クライアントの `task.json` ファイルにタスクが存在しない場合、タスクを追加し、 `roi` フィールドに適切な値を書き込みます。
|
||
|
||
## 設定を保存して、ソフトウェアを再起動する
|
||
|
||
変更を行った後、設定を保存し、変更を有効にするためにソフトウェアを再起動する必要があります。これを行うには、ソフトウェアを再起動してファイルを再読み込みするか、ソフトウェアディレクトリに新しい `DEBUG.txt` ファイルを作成します。これにより、"Link Start "ボタンをクリックするたびにテンプレートとファイルが再読み込みされますので、ソフトウェアを再起動する必要はありません。
|
||
|
||
成功を見届けるためには
|
||
|
||
1. 海外サーバーでソフトウェアが正常に動作することを確認するための動作確認。
|
||
2. 正常に動作しない場合は、変更内容が正しいか、ログ出力を確認し、何が問題だったかを判断する必要があります。
|
||
|
||
## ログの解析
|
||
|
||
もし、`task.json`ファイルを修正しても、プログラムが正しく機能しない場合、ログをチェックしてエラーを見つけ、それに応じて対応するタスクを修正することが有効な場合があります。ログファイルは通常、ソフトウェアのルートディレクトリにあり、`asst.log`という名前になっています。MAAを自分でコンパイルした場合は、コンパイル時に選択したコンパイルモードに応じて、 `x64Release` または `x64RelWithDebInfo` ディレクトリに配置されるかもしれません。
|
||
|
||
ログを解析することは、プログラムに関する問題を特定するのに役立ちます。以下はログの例
|
||
|
||
```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"}
|
||
[2022-12-18 17:43:18.398][INF][Px7ec][Tx15c8] Call ` C:\Program Files\BlueStacks_nxt\. \HD-Adb.exe -s 127.0.0.1:5555 exec-out "screencap | gzip -1" ` ret 0 , cost 862 ms , stdout size: 2074904 , socket size: 0
|
||
[2022-12-18 17:43:18.541][TRC][Px7ec][Tx15c8] OcrPack::recognize | roi: [ 500, 50, 300, 150 ]
|
||
[2022-12-18 17:43:18.541][TRC][Px7ec][Tx15c8] Ocr Pipeline with asst::WordOcr | enter
|
||
[2022-12-18 17:43:18.634][TRC][Px7ec][Tx15c8] Ocr Pipeline with asst::WordOcr | leave, 93 ms
|
||
[2022-12-18 17:43:18.634][TRC][Px7ec][Tx15c8] OcrPack::recognize | raw: [{ : [ 0, 0, 300, 150 ], score: 0.000000 }]
|
||
[2022-12-18 17:43:18.634][TRC][Px7ec][Tx15c8] OcrPack::recognize | proc: []
|
||
[2022-12-18 17:43:18.637][TRC][Px7ec][Tx15c8] asst::ProcessTask::_run | leave, 1101 ms
|
||
[2022-12-18 17:43:18.638][TRC][Px7ec][Tx15c8] ready to sleep 500
|
||
[2022-12-18 17:43:19.144][TRC][Px7ec][Tx15c8] end of sleep 500
|
||
[2022-12-18 17:43:19.144][TRC][Px7ec][Tx15c8] asst::ProcessTask::_run | enter
|
||
```
|
||
|
||
このログでは、以下のことがわかります。
|
||
|
||
- `"taskchain"` は現在進行中のタスクを表します。
|
||
- `"details"`はタスクの内容であり、認識すべきフィールド (`to_be_recognized`) と現在のリトライ回数 (`cur_retry`) とリトライ回数の合計 (`retry_times`) を含みます。
|
||
- `"first"` はタスクの開始を表す。
|
||
- `"taskid"` はタスク番号です。
|
||
- `"class"` と `subtask` はそれぞれ、タスクのクラスとサブタスクを表す。
|
||
- `"pre_task"` は一つ前のタスクを表す。
|
||
|
||
さらに、コマンドの実行結果 (例: `Call`) と `OCR` の情報 (例: `OcrPack::recognize`) がログに記録されます。
|
||
|
||
例えば、このログの `"to_be_recognized"`,`"cur_retry":3, "retry_times":20` は、タスクの認識を10回試行し、最大回数は20回であることを意味しています。最大回数に達すると、そのタスクはスキップされ、エラーが報告され、次のタスクが実行されます。前のタスクで問題がない場合、ここで認識に問題がある可能性があります。この問題をトラブルシューティングするには、ログに記載されているタスクに対応するテンプレートファイルがあるか、対応するタスクの `text` フィールドが正しくないか、タスク認識のための `roi` 範囲が正しくないかを確認し、必要な修正を加えてください。
|
||
|
||
対応するテンプレート画像を見ると、ENクライアントのテンプレートフォルダにこの画像のテンプレートがありますが、サイズが 大陸版クライアントのテンプレートフォルダの画像より大きいことがあります . この場合、大陸版クライアントの `roi` がENクライアントで認識されない可能性があるので、ENクライアントの `task.json` ファイル内の対応するタスクの `roi` を、ENクライアントの画像サイズに合わせて修正する必要があるかもしれません。
|
||
|
||
## 変更を送信する
|
||
|
||
[Github Pull Requst ガイド](../develop/development.md#github-pull-request-プロセス概要)を参照してください。
|