Files
MaaAssistantArknights/docs/zh-tw/protocol/callback-schema.md
Lucien Shaw e461208bf9 chore: 完善容器配置及依赖安装 (#14208)
格式化工具部分:
1. pre-commit 引入 python 的格式化工具,包括 black(代码格式化)和 isort(对“包导入顺序”的规范)
2. 允许 prettier 对文档站的 markdown 文件格式化
3. 不允许 prettier 对 markdown 文件中的代码块的代码本身进行格式化
4. 升级了 pre-commit 的各个 hook 的版本
5. 优化了 pre-commit 的日志文本显示

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

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

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

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

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

Commits:

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

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

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

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

* style: isort fix

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

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

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

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

* docs: md -> markdown

* chore: 容器安装python包和maadeps

* fix: 修复过时python包

* chore: 指定pnpm版本

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

* chore: 去掉rust

* chore: add plain env

* chore: 使用clangd语言服务器

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

* chore: 更新安装的clangd版本

* docs: 简易文档适配

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

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

* style: 调整缩进

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

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

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

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

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

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

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

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

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

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

* chore: 使用maadeps的clangd

* build: 更新maadeps工具链版本

* style: prettier fix

* revert: 还原maadeps版本

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

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
2025-09-30 19:39:48 +08:00

640 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
order: 2
icon: material-symbols:u-turn-left
---
# 回呼訊息協議
::: info 注意
回呼訊息隨版本更新快速迭代中,本檔案可能過時。如需獲取最新内容可参考 [簡中檔案](../../zh-cn/protocol/callback-schema.md) 或 [C# 集成源碼](https://github.com/MaaAssistantArknights/MaaAssistantArknights/blob/dev/src/MaaWpfGui/Main/AsstProxy.cs)
:::
## 回調函數原型
```cpp
typedef void(ASST_CALL* AsstCallback)(int msg, const char* details, void* custom_arg);
```
## 參數總覽
- `int msg`
消息類型
```cpp
enum class AsstMsg
{
/* Global Info */
InternalError = 0, // 內部錯誤
InitFailed = 1, // 初始化失敗
ConnectionInfo = 2, // 連接相關資訊
AllTasksCompleted = 3, // 全部任務完成
AsyncCallInfo = 4, // 外部異步調用資訊
/* TaskChain Info */
TaskChainError = 10000, // 任務鏈執行/辨識錯誤
TaskChainStart = 10001, // 任務鏈開始
TaskChainCompleted = 10002, // 任務鏈完成
TaskChainExtraInfo = 10003, // 任務鏈額外資訊
TaskChainStopped = 10004, // 任務鏈手動停止
/* SubTask Info */
SubTaskError = 20000, // 原子任務執行/辨識錯誤
SubTaskStart = 20001, // 原子任務開始
SubTaskCompleted = 20002, // 原子任務完成
SubTaskExtraInfo = 20003, // 原子任務額外資訊
SubTaskStopped = 20004, // 原子任務手動停止
/* Web Request */
ReportRequest = 30000, // 上報請求
};
```
- `const char* details`
消息詳情json 字符串,詳見 [欄位解釋](#欄位解釋)
- `void* custom_arg`
調用方自定義參數,會原樣傳出 `AsstCreateEx` 接口中的 `custom_arg` 參數C 系語言可利用該參數傳出 `this` 指針
## 欄位解釋
### InternalError
Todo
### InitFailed
```json
{
"what": string, // 錯誤類型
"why": string, // 錯誤原因
"details": object // 錯誤詳情
}
```
### ConnectionInfo
```json
{
"what": string, // 資訊類型
"why": string, // 資訊原因
"uuid": string, // 設備唯一碼(連接失敗時為空)
"details": {
"adb": string, // AsstConnect 接口 adb_path 參數
"address": string, // AsstConnect 接口 address 參數
"config": string // AsstConnect 接口 config 參數
}
}
```
### 常見 `What` 欄位
- `ConnectFailed`
連接失敗
- `Connected`
已連接,注意此時的 `uuid` 欄位值為空(下一步才是獲取)
- `UuidGot`
已獲取到設備唯一碼
- `UnsupportedResolution`
解析度不被支援
- `ResolutionError`
解析度獲取錯誤
- `Reconnecting`
連接斷開adb / 模擬器 炸了),正在重連
- `Reconnected`
連接斷開adb / 模擬器 炸了),重連成功
- `Disconnect`
連接斷開adb / 模擬器 炸了),並重試失敗
- `ScreencapFailed`
截圖失敗adb / 模擬器 炸了),並重試失敗
- `TouchModeNotAvailable`
不支援的觸控模式
### AsyncCallInfo
```json
{
"uuid": string, // 設備唯一碼
"what": string, // 回調類型,"Connect" | "Click" | "Screencap" | ...
"async_call_id": int, // 異步請求 id即調用 AsstAsyncXXX 時的返回值
"details": {
"ret": bool, // 實際調用的返回值
"cost": int64, // 耗時,單位毫秒
}
}
```
### AllTasksCompleted
```json
{
"taskchain": string, // 最後的任務鏈
"uuid": string, // 設備唯一碼
"finished_tasks": [ // 已經執行過的任務 id
int,
...
]
}
```
#### 常見 `taskchain` 欄位
- `StartUp`
開始喚醒
- `CloseDown`
關閉遊戲
- `Fight`
刷理智
- `Mall`
信用點及購物
- `Recruit`
自動公招
- `Infrast`
基建換班
- `Award`
領取日常獎勵
- `Roguelike`
無限刷肉鴿
- `Copilot`
自動抄作業
- `SSSCopilot`
自動抄保全作業
- `Depot`
倉庫辨識
- `OperBox`
幹員 box 辨識
- `Reclamation`
生息演算
- `Custom`
自定義任務
- `SingleStep`
單步任務
- `VideoRecognition`
影片辨識任務
- `Debug`
偵錯
### TaskChain 相關消息
```json
{
"taskchain": string, // 當前的任務鏈
"taskid": int, // 當前任務 TaskId
"uuid": string // 設備唯一碼
}
```
### TaskChainExtraInfo
Todo
### SubTask 相關消息
```json
{
"subtask": string, // 子任務名
"class": string, // 子任務符號名
"taskchain": string, // 當前任務鏈
"taskid": int, // 當前任務 TaskId
"details": object, // 詳情
"uuid": string // 設備唯一碼
}
```
#### 常見 `subtask` 欄位
- `ProcessTask`
```json
// 對應的 details 欄位舉例
{
"task": "StartButton2", // 任務名
"action": 512,
"exec_times": 1, // 已執行次數
"max_times": 999, // 最大執行次數
"algorithm": 0
}
```
- Todo 其他
##### 常見 `task` 欄位
- `StartButton2`
開始戰鬥
- `MedicineConfirm`
使用理智藥
- `ExpiringMedicineConfirm`
使用 48 小時內過期的理智藥
- `StoneConfirm`
碎石
- `RecruitRefreshConfirm`
公招刷新標籤
- `RecruitConfirm`
公招確認招募
- `RecruitNowConfirm`
公招使用加急許可
- `ReportToPenguinStats`
匯報到企鵝數據統計
- `ReportToYituliu`
匯報到一圖流大數據
- `InfrastDormDoubleConfirmButton`
基建宿舍的二次確認按鈕,僅當幹員衝突時才會有,請提示用戶
- `StartExplore`
肉鴿開始探索
- `StageTraderInvestConfirm`
肉鴿投資了源石錠
- `StageTraderInvestSystemFull`
肉鴿投資達到了遊戲上限
- `ExitThenAbandon`
肉鴿放棄了本次探索
- `MissionCompletedFlag`
肉鴿戰鬥完成
- `MissionFailedFlag`
肉鴿戰鬥失敗
- `StageTraderEnter`
肉鴿關卡:詭異行商
- `StageSafeHouseEnter`
肉鴿關卡:安全的角落
- `StageEncounterEnter`
肉鴿關卡:不期而遇 / 古堡饋贈
- `StageCombatDpsEnter`
肉鴿關卡:普通作戰
- `StageEmergencyDps`
肉鴿關卡:緊急作戰
- `StageDreadfulFoe`
肉鴿關卡:險路惡敵
- `StartGameTask`
打開用戶端失敗(配置檔案與傳入 client_type 不匹配)
- Todo 其他
### SubTaskExtraInfo
```json
{
"taskchain": string, // 當前任務鏈
"class": string, // 子任務類型
"what": string, // 資訊類型
"details": object, // 資訊詳情
"uuid": string, // 設備唯一碼
}
```
#### 常見 `what` 及 `details` 欄位
- `StageDrops`
關卡材料掉落資訊
```json
// 對應的 details 欄位舉例
{
"drops": [ // 本次辨識到的掉落材料
{
"itemId": "3301",
"quantity": 2,
"itemName": "技巧概要·卷1"
},
{
"itemId": "3302",
"quantity": 1,
"itemName": "技巧概要·卷2"
},
{
"itemId": "3303",
"quantity": 2,
"itemName": "技巧概要·卷3"
}
],
"stage": { // 關卡資訊
"stageCode": "CA-5",
"stageId": "wk_fly_5"
},
"stars": 3, // 行動結束星級
"stats": [ // 本次執行期間總的材料掉落
{
"itemId": "3301",
"itemName": "技巧概要·卷1",
"quantity": 4,
"addQuantity": 2 //本次新增的掉落數量
},
{
"itemId": "3302",
"itemName": "技巧概要·卷2",
"quantity": 3,
"addQuantity": 1
},
{
"itemId": "3303",
"itemName": "技巧概要·卷3",
"quantity": 4,
"addQuantity": 2
}
]
}
```
- `RecruitTagsDetected`
公招辨識到了 Tags
```json
// 對應的 details 欄位舉例
{
"tags": [
"費用回覆",
"防護",
"先鋒幹員",
"輔助幹員",
"近戰位"
]
}
```
- `RecruitSpecialTag`
公招辨識到了特殊 Tag
```json
// 對應的 details 欄位舉例
{
"tag": "高級資深幹員"
}
```
- `RecruitResult`
公招辨識結果
```json
// 對應的 details 欄位舉例
{
"tags": [ // 所有辨識到的 tags目前來說一定是 5 個
"削弱",
"減速",
"術師幹員",
"輔助幹員",
"近戰位"
],
"level": 4, // 總的星級
"result": [
{
"tags": [
"削弱"
],
"level": 4, // 這組 tags 的星級
"opers": [
{
"name": "初雪",
"level": 5 // 幹員星級
},
{
"name": "隕星",
"level": 5
},
{
"name": "槐琥",
"level": 5
},
{
"name": "夜煙",
"level": 4
},
{
"name": "流星",
"level": 4
}
]
},
{
"tags": [
"減速",
"術師幹員"
],
"level": 4,
"opers": [
{
"name": "夜魔",
"level": 5
},
{
"name": "格雷伊",
"level": 4
}
]
},
{
"tags": [
"削弱",
"術師幹員"
],
"level": 4,
"opers": [
{
"name": "夜煙",
"level": 4
}
]
}
]
}
```
- `RecruitTagsRefreshed`
公招刷新了 Tags
```json
// 對應的 details 欄位舉例
{
"count": 1, // 當前槽位已刷新次數
"refresh_limit": 3 // 當前槽位刷新次數上限
}
```
- `RecruitNoPermit`
公招無招聘許可
```json
// 對應的 details 欄位舉例
{
"continue": true, // 是否繼續刷新
}
```
- `RecruitTagsSelected`
公招選擇了 Tags
```json
// 對應的 details 欄位舉例
{
"tags": [
"減速",
"術師幹員"
]
}
```
- `RecruitSlotCompleted`
當前公招槽位任務完成
- `RecruitError`
公招辨識錯誤
- `EnterFacility`
基建進入了設施
```json
// 對應的 details 欄位舉例
{
"facility": "Mfg", // 設施名
"index": 0 // 設施序號
}
```
- `NotEnoughStaff`
基建可用幹員不足
```json
// 對應的 details 欄位舉例
{
"facility": "Mfg", // 設施名
"index": 0 // 設施序號
}
```
- `ProductOfFacility`
基建產物
```json
// 對應的 details 欄位舉例
{
"product": "Money", // 產物名
"facility": "Mfg", // 設施名
"index": 0 // 設施序號
}
```
- `StageInfo`
自動作戰關卡資訊
```json
// 對應的 details 欄位舉例
{
"name": string // 關卡名
}
```
- `StageInfoError`
自動作戰關卡辨識錯誤
- `PenguinId`
企鵝物流 ID
```json
// 對應的 details 欄位舉例
{
"id": string
}
```
- `Depot`
倉庫辨識結果
```json
// 對應的 details 欄位舉例
"done": bool, // 是否已經辨識完了,為 false 表示仍在辨識中(過程中的數據)
"arkplanner": { // https://penguin-stats.io/planner
"object": {
"items": [
{
"id": "2004",
"have": 4,
"name": "高級作戰記錄"
},
{
"id": "mod_unlock_token",
"have": 25,
"name": "模組數據塊"
},
{
"id": "2003",
"have": 20,
"name": "中級作戰記錄"
}
],
"@type": "@penguin-statistics/depot"
},
"data": "{\"@type\":\"@penguin-statistics/depot\",\"items\":[{\"id\":\"2004\",\"have\":4,\"name\":\"高級作戰記錄\"},{\"id\":\"mod_unlock_token\",\"have\":25,\"name\":\"模組數據塊\"},{\"id\":\"2003\",\"have\":20,\"name\":\"中級作戰記錄\"}]}"
},
"lolicon": { // https://arkntools.app/#/material
"object": {
"2004" : 4,
"mod_unlock_token": 25,
"2003": 20
},
"data": "{\"2003\":20,\"2004\": 4,\"mod_unlock_token\": 25}"
}
// 目前只支援 ArkPlanner 和 Lolicon (Arkntools) 的格式,以後可能會兼容更多網站
```
- `OperBox`
幹員辨識結果
```json
// 對應的 details 欄位舉例
"done": bool, // 是否已經辨識完了,為 false 表示仍在辨識中(過程中的數據)
"all_oper": [
{
"id": "char_002_amiya",
"name": "阿米婭",
"own": true,
"rarity": 5
},
{
"id": "char_003_kalts",
"name": "凱爾希",
"own": true,
"rarity": 6
},
{
"id": "char_1020_reed2",
"name": "焰影葦草",
"own": false,
"rarity": 6
},
]
"own_opers": [
{
"id": "char_002_amiya", // 幹員id
"name": "阿米婭", // 幹員名稱
"own": true, // 是否擁有
"elite": 2, // 精英度 0,1,2
"level": 50, // 幹員等級
"potential": 6, // 幹員潛能 [1, 6]
"rarity": 5 // 幹員稀有度 [1, 6]
},
{
"id": "char_003_kalts",
"name": "凱爾希",
"own": true,
"elite": 2,
"level": 50,
"potential": 1,
"rarity": 6
}
]
```
- `UnsupportedLevel`
自動抄作業,不支援的關卡名
### ReportRequest
該字段主要用於核心模塊向 UI 層傳遞網絡請求信息UI 負責執行具體的 HTTP 上報操作。
```json
{
"url": "string", // 請求的完整URL例如https://penguin-stats.io/PenguinStats/api/v2/report
"headers": { // 請求頭鍵值對(不包含 Content-TypeUI 層自行添加)
"authorization": "PenguinID 1234567890",
"User-Agent": "MaaAssistantArknights/1.2.3 cpr/4.5.6"
},
"body": "string", // 請求正文內容(通常為 JSON 格式的字串)
"subtask": "string" // 子任務名稱,標識具體上報任務,如 "ReportToPenguinStats"、"ReportToYituliu"
}
```