滑索與送貨邏輯

返回：文件索引 / README

本文記錄滑索和自動送貨兩個模組的核心思想與邏輯推演過程，供後續開發和維護參考。

一、總體思路

整個送貨自動化可拆分為三個相互獨立但順序依賴的子問題：

搶單：在委託列表中識別並接取符合條件的委託。(已有)
取貨：通過滑索系統到達倉儲節點，拾取貨物。
送達：通過滑索系統到達目標 NPC，提交貨物完成委託。

二、滑索系統（ZipLineMixin）

2.1 核心問題

滑索可能有多個可連通的滑索，每個連線點對應一個可識別的距離數字（如 14m、108m）。程式無法直接知道"當前哪個連線點在螢幕中央"，只能通過 OCR 掃描當前畫面中的數字來判斷。

因此，到達特定連線點等價於：將目標距離數字移動到螢幕中心。

2.2 對齊演算法

流程如下：

flowchart TD
    A[开始对齐目标距离] --> B[OCR 扫描距离文本]
    B --> C{找到目标距离}
    C -->|是| D[计算目标与屏幕中心偏差]
    C -->|否| E{有历史位置}
    E -->|是| F[按指数衰减预测位置]
    E -->|否| G[随机探索视角]
    F --> D
    G --> B
    D --> H{偏差在容差内}
    H -->|否| I[移动视角]
    I --> B
    H -->|是| J[点击连接点]
    J --> K[持续按 E 推进]
    K --> L{出现移动或离开提示}
    L -->|否| K
    L -->|是| M[本段完成]

對螢幕做 OCR，同時用 HSV 顏色過濾器（金色文字 + 白色文字）隔離噪聲，提高數字識別準確率。
如果找到目標數字，計算其中心與螢幕中心的偏差 (dx, dy)。
若偏差超出容差（預設 50px），向偏差方向移動攝像頭，反覆迭代直至對齊。
目標對中、短暫丟失後的預測和搜尋策略由 NavigationMixin.align_ocr_or_find_target_to_center() 統一實現；ZipLineMixin 負責提供距離正則、HSV 處理器和 max_time=100。
對中失敗、序列格式非法等錯誤直接向上丟擲，由任務統一異常處理。這一分層使滑索程式碼只維護“距離序列 + 互動”，通用導航搜尋策略集中在 navigation_mixin.py。

可利用的部分特性：固定角色模型可以遮住複雜背景，因此可以先切換到特定角色，然後藉助角色模型遮擋來提高 OCR 的穩定性。

2.3 發射與推進

對齊完成後：

點選連線點（滑鼠左鍵）。
進入迴圈，持續按 E 鍵，每 0.1 秒檢查一次螢幕底部的狀態文字。
出現本地化資源 zip_line_mixin 中的「向目標移動」或「離開滑索架」匹配項時，代表本段滑索已觸發或完成，退出迴圈，進入下一段。
等待首次登上滑索的超時為 60 秒；每一段推進的超時為 240 秒，超時均丟擲異常。

持續按 E 的原因是：遊戲在滑索距離很短的情況下，程式如果再進行ocr容易因為延遲錯過按E的時機導致異常，採用高頻重複輸入來確保不錯過觸發視窗。實現上使用底層按鍵傳送 send_key("e")，因為遊戲內該互動鍵不可改綁，因此不走通用熱鍵對映。

2.4 多段序列

配置中每個目的地對應一個距離序列（如 "14,108,64,109,60"），由 parse_int_sequence 解析；支援逗號字串或整數列表，非法 token 會拋 ValueError。程式按順序逐段執行，並按 need_v、目標導航和底部提示決定右鍵收尾。

三、送貨任務編排（DeliveryTask）

3.1 整體流程串聯

flowchart TD
    A[接取委托] --> B[传送至出发点]
    B --> C[滑索前往仓储节点]
    C --> D[取货并回到滑索]
    D --> E[OCR 识别当前地区配置的目标 NPC]
    E --> F[按目标滑索序列前往]
    F --> G[到达并提交货物]
    G --> H{还有接取机会}
    H -->|是| A
    H -->|否| I[结束]

按以下順序執行一次完整送貨：

接取委托
    ↓
传送至出发点（task_to_transfer_point）
    ↓
滑索前往仓储节点取货并回到滑索（to_storage_point_and_back_zip_line）
    ↓
OCR 识别目标 NPC（来自当前地区 `delivery_targets_by_location`）
    ↓
滑索前往目标 NPC（on_zip_line_start）
    ↓
到达并提交货物（to_end_and_submit）

迴圈最多重試 3 次(因為最多有三次接取機會)

3.2 取貨邏輯

滑索前往倉儲節點取貨並回到滑索的思路：

前提:上一步完成後，落地有滑索的情況下可以直接上滑索

等待「登上滑索架」提示出現，點選並上滑索。
按配置的「通向{地點}送貨點」序列滑行（每個送貨地點一個鍵，如「通向武陵城送貨點」「通向試驗園區送貨點」）。
下滑索後，任務小藍點可能變暗此時使用追蹤鍵(v),使其變亮,然後再次上滑索進行一次關於小藍點的對中
到達倉儲節點附近後，通過任務小藍點進行輔助對齊，步行靠近倉儲節點。
檢測到「倉儲節點」及「取貨」提示後點擊取貨。
取貨後需檢測最近滑索架並前往後續送達流程。

3.3 目標 NPC 識別

倉儲點取貨後，遊戲介面左側會顯示送達點或目標 NPC。候選項來自當前地區 delivery_targets_by_location 的並集，並通過 assets/lang/world_map.json 取得當前語言匹配器；識別到的規範目標名用於選擇同名滑索序列和後續導航。

3.4 送達邏輯

在到達目標 NPC 後：

檢測 NPC 名稱或「提交」等互動提示出現。
點選提交完成委託。
等待結算 UI 消失後返回，準備下一次迴圈。

3.5 功能開關設計

提供「僅接取」和「僅送貨」兩個開關，方便在除錯或特殊場景下只跑流程的某一段，而不必修改程式碼。「選擇測試物件」則允許單獨測試某段滑索序列或完整迴圈，降低除錯成本。

四、關鍵設計取捨

問題	取捨思路
滑索對齊為何用 OCR 而非影像特徵匹配	距離數字是滑索到滑索間最直觀的資訊，OCR 更通用,使用者輸入配置也更直觀；圖示模板維護成本高
為何持續按 E 而非判斷時機後按一次	滑索距離短時互動觸發時機很短，高頻輸入容錯性更強；且該互動鍵在遊戲內不可改綁，故直接傳送底層 E 鍵輸入
OCR 失敗時為何用預測而非立即重試	相機還在移動時目標短暫消失屬正常，立即重置會導致震盪
為何走完一條完整滑索鏈後要再次上滑索	防止下滑索後，小藍點特徵被互動UI遮住導致無法識別，而上滑索後不會出現此種UI遮擋情況

五、可能的替代方案

滑索對齊改進

地圖上獲取線路，降低ocr依賴 ：若能夠通過遊戲地圖獲取滑索線路，在滑索上開啟地圖，點選下一個滑索的追蹤按鈕，小地圖上就會顯示出相對方向，一定程度上可以解決橫向對齊問題，豎向校準則需進一步考慮
對中利用影像特徵匹配 ：通過影像特徵匹配，如模板匹配，來識別滑索圖示，針對識別到的模板位置來進行進一步識別該模板對應的距離

六、部分已知問題

下滑索後無法立刻上滑索

相關文件：自動送貨 / 送貨地區維護工作流