MaaAssistantArknights/docs/zh-tw/protocol/callback-schema.md

order, icon

order	icon
2	material-symbols:u-turn-left

回呼訊息協定

::: info 注意 回呼訊息 (Callback) 隨版本更新快速迭代中，本文件可能過時。如需獲取最新內容可參考 C# 整合原始碼 :::

回呼函式原型

typedef void(ASST_CALL* AsstCallback)(int msg, const char* details, void* custom_arg);

參數總覽

• int msg
  消息類型

  enum class AsstMsg
  {
   /* Global Info */
   InternalError     = 0,           // 內部錯誤
   InitFailed        = 1,           // 初始化失敗
   ConnectionInfo    = 2,           // 連線相關資訊
   AllTasksCompleted = 3,           // 全部任務完成
   AsyncCallInfo     = 4,           // 外部非同步調用資訊
   Destroyed         = 5,           // 執行個體已銷毀
  
   /* 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

details 欄位為空。

InitFailed

:::: field-group ::: field name="what" type="string" required 錯誤類型。 :::
::: field name="why" type="string" required 錯誤原因。 :::
::: field name="details" type="object" required 錯誤詳情。 :::
::::

ConnectionInfo

:::: field-group ::: field name="what" type="string" required 資訊類型。 ::: ::: field name="why" type="string" required 資訊原因。 ::: ::: field name="uuid" type="string" 設備唯一碼（連線失敗時為空）。 ::: ::: field name="details" type="object" required 連線詳情。其結構如下：

• adb (string, required): AsstConnect 介面 adb_path 參數。
• address (string, required): AsstConnect 介面 address 參數。
• config (string, required): AsstConnect 介面 config 參數。

::: ::::

常見 What 欄位

• ConnectFailed
  連線失敗
• Connected
  已連接，注意此時的 uuid 欄位值為空（下一步才是獲取）
• UuidGot
  已獲取到設備唯一碼
• UnsupportedResolution
  解析度不被支援
• ResolutionError
  解析度獲取錯誤
• Reconnecting
  連線中斷（adb / 模擬器 炸了），正在重連
• Reconnected
  連線中斷（adb / 模擬器 炸了），重連成功
• Disconnect
  連線中斷（adb / 模擬器 炸了），並重試失敗
• ScreencapFailed
  截圖失敗（adb / 模擬器 炸了），並重試失敗
• TouchModeNotAvailable
  不支援的觸控模式

AsyncCallInfo

:::: field-group ::: field name="uuid" type="string" required 設備唯一碼。 ::: ::: field name="what" type="string" required 回呼類型，例如 Connect | Click | Screencap 等。 ::: ::: field name="async_call_id" type="number" required 非同步請求 ID，即調用 AsstAsyncXXX 時的回傳值。 ::: ::: field name="details" type="object" required 非同步調用詳情。其結構如下：

• ret (boolean, required): 實際調用的回傳值。
• cost (number, required): 耗時，單位毫秒。

::: ::::

AllTasksCompleted

:::: field-group ::: field name="taskchain" type="string" required 最後的任务鏈。 ::: ::: field name="uuid" type="string" required 設備唯一碼。 ::: ::: field name="finished_tasks" type="array" required 已經執行過的任務 ID 列表。 ::: ::::

常見 taskchain 欄位

• StartUp
  開始喚醒
• CloseDown
  關閉遊戲
• Fight
  刷理智
• Mall
  信用點及購物
• Recruit
  自動公招
• Infrast
  基建換班
• Award
  領取日常獎勵
• Roguelike
  無限刷肉鴿
• Copilot
  自動抄作業
• SSSCopilot
  自動抄保全作業
• Depot
  倉庫辨識
• OperBox
  幹員 Box 辨識
• Reclamation
  生息演算
• Custom
  自定義任務
• SingleStep
  單步任務
• VideoRecognition
  影片辨識任務
• Debug
  偵錯

TaskChain 相關消息

:::: field-group ::: field name="taskchain" type="string" required 目前的任務鏈。 ::: ::: field name="taskid" type="number" required 目前任務 TaskId。 ::: ::: field name="uuid" type="string" required 設備唯一碼。 ::: ::::

TaskChainExtraInfo

details 欄位為空。

SubTask 相關消息

:::: field-group ::: field name="subtask" type="string" required 子任務名稱。 ::: ::: field name="class" type="string" required 子任務符號名稱。 ::: ::: field name="taskchain" type="string" required 目前任務鏈。 ::: ::: field name="taskid" type="number" required 目前任務 TaskId。 ::: ::: field name="details" type="object" required 詳情。 ::: ::: field name="uuid" type="string" required 設備唯一碼。 ::: ::::

常見 subtask 欄位

• ProcessTask
details 欄位内容如下：

  :::: field-group ::: field name="task" type="string" required 任務名稱。 ::: ::: field name="action" type="number" required Action ID。 ::: ::: field name="exec_times" type="number" required 已執行次數。 ::: ::: field name="max_times" type="number" required 最大執行次數。 ::: ::: field name="algorithm" type="number" required 辨識算法。 ::: ::::

• Todo 其他

常見 task 欄位

• StartButton2
  開始戰鬥
• MedicineConfirm
  使用理智藥
• ExpiringMedicineConfirm
  使用即將過期的理智藥
• StoneConfirm
  碎石
• RecruitRefreshConfirm
  公招刷新標籤
• RecruitConfirm
  公招確認招募
• RecruitNowConfirm
  公招使用加急許可
• ReportToPenguinStats
  匯報到企鵝數據統計
• ReportToYituliu
  匯報到一圖流大數據
• InfrastDormDoubleConfirmButton
  基建宿舍的二次確認按鈕。僅當幹員衝突時才會出現，請提示使用者。
• StartExplore
  肉鴿開始探索
• StageTraderInvestConfirm
  肉鴿投資源石錠
• StageTraderInvestSystemFull
  肉鴿投資達到遊戲上限
• ExitThenAbandon
  肉鴿放棄本次探索
• MissionCompletedFlag
  肉鴿戰鬥完成
• MissionFailedFlag
  肉鴿戰鬥失敗
• StageTraderEnter
  肉鴿關卡：詭異行商
• StageSafeHouseEnter
  肉鴿關卡：安全的角落
• StageEncounterEnter
  肉鴿關卡：不期而遇 / 古堡饋贈
• StageCombatOpsEnter
  肉鴿關卡：普通作戰
• StageEmergencyOps
  肉鴿關卡：緊急作戰
• StageDreadfulFoe
  肉鴿關卡：險路惡敵
• StartGameTask 打開客戶端失敗（設定檔與傳入 client_type 不匹配）
• Todo 其他

SubTaskExtraInfo

:::: field-group ::: field name="taskchain" type="string" required 目前任務鏈。 ::: ::: field name="class" type="string" required 子任務類型。 ::: ::: field name="what" type="string" required 資訊類型。 ::: ::: field name="details" type="object" required 資訊詳情。 ::: ::: field name="uuid" type="string" required 設備唯一碼。 ::: ::::

常見 what 及 details 欄位

• StageDrops
  關卡材料掉落資訊。details 欄位結構如下：

  • drops (array, required)：本次辨識到的掉落材料，陣列每一項包含：
    • itemId (string, required)：材料 ID。
    • quantity (number, required)：掉落數量。
    • itemName (string, required)：材料名稱。
  • stage (object, required)：關卡資訊，包含：
    • stageCode (string, required)：關卡編號。
    • stageId (string, required)：關卡 ID。
  • stars (number, required)：行動結束星級。
  • stats (array, required)：本次執行期間總計材料掉落，陣列每一項包含：
    • itemId (string, required)：材料 ID。
    • itemName (string, required)：材料名稱。
    • quantity (number, required)：總計數量。
    • addQuantity (number, required)：本次新增的掉落數量。

• RecruitTagsDetected
  公招辨識到了 Tags。details 欄位內容如下：

  :::: field-group ::: field name="tags" type="array" required 辨識到的 Tag 列表。 ::: ::::

• RecruitSpecialTag
  公招辨識到了特殊 Tag。details 欄位內容如下：

  :::: field-group ::: field name="tag" type="string" required 特殊 Tag 名稱，例如 高級資深幹員。 ::: ::::

• RecruitPreservedTag
  公招辨識到了已設定為保留的 Tag。details 欄位內容如下：

  :::: field-group ::: field name="tag" type="string" required 觸發保留的 Tag 名稱，例如 支援機械。 ::: ::::

• RecruitResult
  公招辨識結果。details 欄位結構如下：

  • tags (array, required)：所有辨識到的 tags，目前固定為 5 個。
  • level (number, required)：組合的最高星級。
  • result (array, required)：具體的組合結果，陣列每一項包含：
    • tags (array, required)：參與組合的 tags。
    • level (number, required)：這組 tags 的星級。
    • opers (array, required)：可能招募到的幹員，陣列每一項包含：
      • name (string, required)：幹員名稱。
      • level (number, required)：幹員星級。

• RecruitTagsRefreshed
  公招刷新了 Tags。details 欄位內容如下：

  :::: field-group ::: field name="count" type="number" required 目前槽位已刷新次數。 ::: ::: field name="refresh_limit" type="number" required 目前槽位刷新次數上限。 ::: ::::

• RecruitNoPermit
  公招無招聘許可。details 欄位內容如下：

  :::: field-group ::: field name="continue" type="boolean" required 是否繼續刷新。 ::: ::::

• RecruitTagsSelected
  公招選擇了 Tags。details 欄位內容如下：

  :::: field-group ::: field name="tags" type="array" required 選擇的 Tag 列表。 ::: ::::

• RecruitSlotCompleted
  目前公招槽位任務完成。details 欄位為空。

• RecruitError
  公招辨識錯誤。details 欄位為空。

• EnterFacility
  基建進入了設施。details 欄位內容如下：

  :::: field-group ::: field name="facility" type="string" required 設施名稱。 ::: ::: field name="index" type="number" required 設施序號。 ::: ::::

• NotEnoughStaff
  基建可用幹員不足。details 欄位內容如下：

  :::: field-group ::: field name="facility" type="string" required 設施名稱。 ::: ::: field name="index" type="number" required 設施序號。 ::: ::::

• ProductOfFacility
  基建產物。details 欄位內容如下：

  :::: field-group ::: field name="product" type="string" required 產物名稱。 ::: ::: field name="facility" type="string" required 設施名稱。 ::: ::: field name="index" type="number" required 設施序號。 ::: ::::

• StageInfo
  自動作戰關卡資訊。details 欄位內容如下：

  :::: field-group ::: field name="name" type="string" required 關卡名稱。 ::: ::::

• StageInfoError
  自動作戰關卡辨識錯誤。details 欄位為空。

• PenguinId
  企鵝物流 ID。details 欄位內容如下：

  :::: field-group ::: field name="id" type="string" required 企鵝物流 ID。 ::: ::::

• Depot
  倉庫辨識結果。details 欄位結構如下：

  • done (boolean, required)：是否已經辨識完了，為 false 表示仍在辨識中（過程中的數據）。
  • data (string, required)：json 字串，格式為 {"物品ID": 數量, ...}，例如 {"2001":18000,"31043":317}。

• OperBox
  幹員辨識結果。details 欄位結構如下：

  • done (boolean, required)：是否已經辨識完了，為 false 表示仍在辨識中（過程中的數據）。
  • all_oper (array, required)：全幹員列表，陣列每一項包含：
    • id (string, required)：幹員 ID。
    • name (string, required)：幹員名稱。
    • own (boolean, required)：是否擁有。
    • rarity (number, required)：幹員稀有度 [1, 6]。
  • own_opers (array, required)：已擁有幹員的詳細資訊列表，陣列每一項包含：
    • id (string, required)：幹員 ID。
    • name (string, required)：幹員名稱。
    • own (boolean, required)：是否擁有。
    • elite (number, required)：精英等級 [0, 2]。
    • level (number, required)：幹員等級。
    • potential (number, required)：幹員潛能 [1, 6]。
    • rarity (number, required)：幹員稀有度 [1, 6]。

• UnsupportedLevel
  自動抄作業，不支援的關卡名稱。details 欄位為空。

ReportRequest

該欄位主要用於核心模組向 UI 層傳遞網路請求資訊，UI 負責執行具體的 HTTP 彙報操作。

:::: field-group ::: field name="url" type="string" required 請求的完整 URL，例如 https://penguin-stats.io/PenguinStats/api/v2/report。 ::: ::: field name="headers" type="object" required 請求 Headers 的 Key-Value 設定（不包含 Content-Type，由 UI 層自行加入）。 ::: ::: field name="body" type="string" required 請求 Body 內容（通常為 json 格式的字串）。 ::: ::: field name="subtask" type="string" required 子任務名稱，辨識具體彙報任務，如 ReportToPenguinStats、ReportToYituliu。 ::: ::::