滑索与送货逻辑

返回：文档索引 / 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依赖 ：若能够通过游戏地图获取滑索线路，在滑索上打开地图，点击下一个滑索的追踪按钮，小地图上就会显示出相对方向，一定程度上可以解决横向对齐问题，竖向校准则需进一步考虑
对中利用图像特征匹配 ：通过图像特征匹配，如模板匹配，来识别滑索图标，针对识别到的模板位置来进行进一步识别该模板对应的距离

六、部分已知问题

下滑索后无法立刻上滑索

相关文档：自动送货 / 送货地区维护工作流