MaaAssistantArknights 更換主題任務實戰指南：候選主題隨機切換與 OCR 匹配原理

2026-09-12 11:02:13作者：庞眉杨Will

本篇技術指南圍繞 MaaAssistantArknights 的「更換主題」任務展開，講解如何配置候選主題名、任務的完整執行流程（回主介面、開主題列表、滑動搜尋、狀態分流）以及基於 OCR 的主題名匹配機制。讀完後你可以正確配置任務參數、理解任務失敗日誌的含義，並處理「主題被自動切回」這類實際使用場景。

功能定位

「更換主題」任務的作用是切換《明日方舟》遊戲主介面的 UI 主題。它對應核心庫中的 SwitchTheme 任務類型，實現在 SwitchThemeTask.cpp 中，任務類型常量定義於 SwitchThemeTask.h：

inline static constexpr std::string_view TaskType = "SwitchTheme";

該類繼承自 InterfaceTask，並通過 Assistant.cpp 中的 ASST_ASSISTANT_APPEND_TASK_FROM_STRING_IF_BRANCH(SwitchThemeTask) 宏註冊進任務分支體系，因此既可以在 GUI 任務佇列中使用，也可以通過任務參數 JSON 直接驅動。

使用說明

按照官方文檔 docs/zh-tw/manual/introduction/switch-theme.md 的說明，使用步驟如下：

將「更換主題」任務新增至任務佇列。
在任務設定中填寫候選主題名，即遊戲內「更換主題」列表中顯示的名稱（如「日間」「夜間」）。
填寫多個主題名時，每次執行隨機選擇一個；僅填寫一個時固定切換。
未填寫任何主題名時，跳過任務並在日誌中提示。

任務參數說明

從源碼 set_params 的實現（SwitchThemeTask.cpp）可以確認，任務參數中唯一的業務欄位是 themes，必須是字串陣列；每個元素會先做 string_trim 去除首尾空白，空字串會被過濾。若 themes 缺失或不是陣列，任務會直接返回失敗並輸出錯誤日誌：

參數	類型	必填	說明
`enable`	bool	否	任務開關。關閉時 `run()` 直接通過（見 SwitchThemeTask.cpp）
`themes`	string[]	是	候選主題名列表，需與遊戲內主題列表中的顯示名稱一致；多個時隨機抽取，僅一個時固定切換

任務參數示例：

{
    "SwitchTheme": {
        "enable": true,
        "themes": ["日間", "夜間"]
    }
}

對應的 GUI 配置模型見 SwitchThemeTask.cs，介面文案（如「填入主題名稱」「添加主題」等佔位提示）定義在各語言資源中，繁體中文見 Res/Localizations。

執行流程深度剖析

run() 主流程（SwitchThemeTask.cpp）可以拆解為四個階段，每個階段對應資料倉庫中的一組 ProcessTask 流程，與文檔描述的行為一一對應。

階段一：目標抽取與狀態預檢

任務未啟用時直接返回成功；
m_candidates 為空時，記錄 no candidate theme, skip 日誌，並通過 callback(AsstMsg::SubTaskExtraInfo, ...) 上報 what: "SwitchThemeSkipped"（SwitchThemeTask.cpp），這正是文檔中「跳過任務並在日誌中提示」的實現；
候選目標超過一個時，使用 std::default_random_engine + std::uniform_int_distribution 在候選集合中均勻隨機抽取（SwitchThemeTask.cpp），隨機引擎是 static 的，進程內持久存在。

抽取出的目標主題名會被注入到 SwitchThemeByNameSelectTheme 流程的 OCR 文本中：

Task.get<OcrTaskInfo>("SwitchThemeByNameSelectTheme")->text = { target };

這說明主題名是靠 OCR 文字辨識比對的，而非模板匹配，下文會展開。

階段二：回主介面並打開主題列表

// 回主界面（小房子快捷优先，返回按钮兜底）→ 打开装扮面板 → 进入主题列表
if (!ProcessTask(*this, { "SwitchThemeByNameBegin" }).run())

SwitchThemeByNameBegin 流程完成「回到主介面 → 打開裝扮面板 → 進入主題列表」的完整導航，先嘗試小房子快捷入口、返回按鈕兜底。

階段三：兩階段列表搜尋策略

文檔描述「目前頁面找不到則快速滑到列表頂部，再向下逐頁尋找」，源碼中這一策略分為兩段迴圈，MaxDragTimes 固定為 20（SwitchThemeTask.cpp）：

先試當前頁：直接執行 SwitchThemeByNameSelectTheme 嘗試選中目標，命中即結束；
快速回到頂部：若當前頁未命中，重複執行 SwitchThemeByNameListAtTop（識別列表頂部標誌）並用 SwitchThemeByNameDragThemeList 向上滑動，直到到達頂部。源碼註釋明確了這樣設計的理由——「目標多在靠下的新主題區，途中逐屏識別收益低」，因此先盲滑到頂而非邊滑邊識別；
從頂向下逐屏查找：到達頂部後進入 SwitchThemeByNameDragDownList 迴圈（SwitchThemeTask.cpp），每一屏先識別當前頁再翻页，「頂部第一屏才會被選中」，避免漏掉首屏目標。

兩段迴圈都檢查 need_exit()，支援執行中退出；均無法選中時，執行 SwitchThemeByNameCancelTheme 取消退出，並上報 what: "SwitchThemeNotFound" 及附加資訊 details.theme 標明失敗的主題名（SwitchThemeTask.cpp）。

階段四：選中後的狀態互斥分流

選中目標項後並不代表切換成功。源碼用一個按順序取首個命中的流程鏈完成互斥分流（SwitchThemeTask.cpp）：

流程名	介面狀態	結果
`SwitchThemeByNameLockedTheme`	確認按鈕為灰色（未解鎖）	命中即視為未解鎖；註釋說明灰確認按鈕因顏色不敏感可被模板命中，故「未解鎖」判斷放在最前
`SwitchThemeByNameAlreadySet`	該主題已是當前主題	命中即無需切換
`SwitchThemeByNameConfirmTheme`	可正常確認	點擊確認完成切換

三種狀態都不滿足屬異常情況，任務會點「取消」退出並按失敗處理。GUI 側根據這些子任務回調在任務佇列輸出對應日誌（見下節）。

OCR 匹配與罕用字校正

「主題名依靠文字辨識比對，少數罕用字可能被誤認成字形相近的字而找不到主題（如「淞」被辨識成「淋」；實測遇到的誤認已內建校正）」——這是文檔對匹配機制的原始描述，與源碼中將目標名直接賦給 OCR 流程 text 欄位的做法一致。GUI 的提示文案（SwitchThemeTip，見 en-us.xaml 等多語言資源）同樣提醒使用者：個別不常用字（如「凇」「淞」）識別可能出現形近偏差導致主題未找到。

若仍遇到找不到主題的情況，文檔給出的處理方式是：透過「問題回饋」提交日誌壓縮檔，日誌中包含實際辨識結果，便於維護者補充校正規則。這裡的校正規則屬於資源倉庫側的資料，不在本倉庫源碼中維護，因此遇到罕用字誤認時，以提交日誌反饋為準。

日誌與回調對照

GUI 在 AsstProxy.cs 中對 SwitchTheme 任務的子任務回調與 SubTaskExtraInfo 做了日誌映射，排查問題時可以對照：

觸發來源	任務日誌（以簡體中文資源為例）	顏色
`SwitchThemeByNameConfirmTheme` / `SwitchThemeByNameSelectTheme`	已切換主題：{主題名}	成功
`SwitchThemeByNameAlreadySet`	目標已是當前主題：{主題名}，無需切換	成功
`SwitchThemeByNameLockedTheme`	主題未解鎖，無法切換：{主題名}	錯誤
`SubTaskExtraInfo: SwitchThemeSkipped`	未填寫主題名稱，跳过更换主題	提示
`SubTaskExtraInfo: SwitchThemeNotFound`	主題未找到：{主題名}，請核對名稱與遊戲內主題列表一致	錯誤

繁體中文的實際文案以 Res/Localizations 為準；上表中的「已切換主題」等文字取自 zh-cn.xaml，僅供語義對照。

主題被自動切回後如何換回

這是文檔中特別提示的一個實用場景：

MAA 尚未支援的新主題切換成功後，後續任務可能因無法辨識其主介面，而觸發「切回日間主題」的保護機制。把本任務放在任務佇列末尾並填入原主題名，即可在所有任務結束後把主題換回來。

操作要點有兩個：其一，任務必須放在任務佇列末尾，確保所有需要辨識主介面的任務已在原主題環境下完成；其二，候選主題名填寫切換前的原主題名（例如原為「日間」就填「日間」），而不是填新主題名。從源碼結構看，這一行為依賴「任務執行時會先回到主介面」的導航前置步驟，因此即使任務中途中斷後介面處於非主介面狀態，該任務也能把介面帶回主介面後再進行切換。