WARNING

MapNavigator 仍处在快速迭代中，各类边界情况的处理还在陆续补齐。本文只能作为大致参考，阈值、时限和个别分支很可能很快过时；主体结构一般不变。文中代码行为以 MaaEnd v2 分支 84de1e1（2026-10-05）为准。

MapNavigator 是 MaaEnd 的寻路模块，按 Pipeline 给出的路线把角色带到目标点，沿途执行跳跃、交互、采集、挖掘、滑索等动作，坐标取自 MapLocator。本文按一次导航的执行顺序描述当前实现：入口与状态机、NavMesh 规划、启动续接、到达判定、走廊跟随与转向、输入后端、卡死恢复与 watchdog、跨区、语义动作、滑索，最后是实测耗时。NavMesh 规划器的内部实现单独成文，见 NavMesh：终末地路径规划。各部分附上对应的 PR，说明参数从哪来。

整体流程

导航主循环每执行一轮叫一刻（tick）。

flowchart TD
    IN([MapNavigateAction<br/>一条 path]) --> PREP[重入保护、等首个定位<br/>NAVMESH 展开、Bootstrap]
    PREP --> CAP

    subgraph TICK [Navigate：每刻 = 本刻工作 + 固定休眠 33 ms]
        CAP[取位、滞留、镜头对齐<br/>内联 ZONE、HEADING、FIND] --> TRK[路线跟踪、走廊跟随<br/>软重规划、走廊消费]
        TRK --> ARR{{到达判定}}
        ARR -->|未到| DRV[watchdog、恢复阶梯<br/>转向、前进、冲刺]
        ARR -->|到点| NODE[到点动作<br/>末端纠正]
    end

    DRV -.->|停滞| STALL([恢复阶梯]):::bg
    DRV --> NEXT([下一刻])
    NODE -->|还有路点| NEXT
    NODE -->|终点| OK([返回成功])

    CAP -.->|定位丢失| LOST([盲跳、全局重定位]):::bg
    TRK -.->|偏离走廊| RP([重规划]):::bg
    NODE -.->|TRANSFER、滑索、FIND、TRIGGER| WAIT([等待 phase]):::bg

    classDef bg stroke-dasharray: 4 3

进入时先过重入保护：同一个 MaaTasker 已在导航则拒绝。随后最多等 100 次 × 100 ms 取得首个定位，把 NAVMESH 段规划成 RUN 路点；规划失败时切掉已走过的前缀再展开一次（#5247「展开失败时跳过已走过的前缀再重试」）。Bootstrap 只执行一次，找到角色当前所在的路段并接上起步规划，之后进入 Navigate 循环。

虚线为旁路。旁路恢复后回到下一刻；超过各自的时限则返回失败。四个等待 phase WaitTransfer、WaitZipline、WaitFind、WaitTrigger 有自己的循环，卡死检测、绕障、重规划和提示扫描只在 Navigate phase 生效。

每刻在工作做完之后固定休眠 33 ms，实际周期是本刻工作耗时加 33 ms。延迟检测按健康时每刻约 110 ms 设计，超过 280 ms 的刻算作慢刻；本文测量的 PlayCover 上中位约 200 ms，见性能。

难点

• 只有小地图：移动时能用的信息只有两样，一是 MapLocator 从小地图解出的坐标和朝向，二是随包预烘的静态地形（见 NavMesh），相当于蒙着眼走路，只知道自己在哪、面朝哪。画面另外只在三处用到：交互提示的识别、挡路设备的模板匹配、用黑屏判断落水。撞墙、卡住、跌下台子、走进水里，都只能事后从坐标序列的变化或定位丢失里推断出来。下面几条都受这一点限制。
• 控制回路慢且有滞后：每刻要截图、定位、发转向，PlayCover 上一刻的中位耗时约 200 ms。一次转向要过几刻才在朝向读数上体现，按原始误差每刻下发，同一个转角会被发好几遍，过冲后再往回找，表现为左右摆（#4939「扣除已发出未兑现的转向,删除冗余的阻尼项」）。见转向。
• 地形：窄桥、台阶、落差、深水都在路上，规划要在窄缝和绕远的宽路之间取舍。见路径搜索。
• 卡死：#3526「[自动采集]寻路卡死但未触发急停」中角色一直往前跳水，发现时已经跳了两个小时；定位丢失时前进键一直按着顶墙，约 13 分钟后才被外层超时（#3509）。见卡死与恢复、watchdog。
• 地图上没有的障碍：玩家自建的设备、网格没记录的石头会挡在路上（#4975、#5576）。见卡死与恢复。
• 到点精度：采集点间距只有 2.1 到 3.7，常规判定圈 3.25 一次会吞掉一串（#5030）。见到达判定。
• 跨区与传送：区域切换、室内分层、传送、机关送人时，坐标会跳变或暂时丢失。见跨区。
• 滑索：索上看不到小地图，落点只能在落地后再分类；拦路的塔会把人截停在半路。见滑索。
• 平台差异：桌面用鼠标，ADB 和 PlayCover 用触屏滑动，单笔转向上限、最小发送间隔、触点采样各不相同。见输入后端。
• 机器差异：健康时每刻约 110 ms，到 350 ms 左右就走不动了。见延迟检测。
• 灵敏度不是默认值：转向量按默认视角灵敏度换算，玩家改过灵敏度时，同一条指令会转过头或转不到位。#5583 起导航在行走中自动检测，判决成立后按检测出的倍率缩放转向量。见灵敏度检测。

演进

#1170「feat: cppMapNavigator」（2026-03-10，+7806/−43）是首版，状态机有 9 个 phase：Bootstrap、AlignHeading、AdvanceOnRoute、WaitZoneTransition、WaitRelocation、RecoverRejoin、ExactTargetRefine、Finished、Failed。转向侧维护一个虚拟偏航角 virtual_yaw，并在线学习每度对应的鼠标量（EMA，α 0.382，范围 1.0 到 4.0）。#1179 当天删掉了 ExactTargetRefine。

#1999「adb/playcover 支持」加入 ADB 与 Win32 后端，删掉 WaitRelocation 和 RecoverRejoin，加入 WaitTransfer，同时引入 Runners/ 下的五个 runner 和 979 行的 turn_execution_engine。

#2162「大道至简 至于大道在哪你别管」（+2134/−4226，60 个文件）把 AlignHeading、AdvanceOnRoute、WaitZoneTransition 合并为单一的 Navigate phase，删掉整个 Runners/、turn_execution_engine、virtual_yaw 和转向比例估计。PR 描述把结构收敛为「路线跟踪 + 统一转向 + 语义流转」，平台差异沉到输入层。#2290 再删掉 PoseEstimator，转向只看航向误差。此后 phase 只增加了等待类：#5079 的 WaitZipline、#5891 的 WaitFind 和 #6155 的 WaitTrigger。

Phase 结构稳定之后，大部分改动落在两处：规划器一路从三角网 A*⁠^[1]换到体素格上的两段搜索；Navigate phase 里不断加入兜底，每一道都对应一类实际卡死或失败的 issue。

输入与输出

输入是 Pipeline 自定义动作 MapNavigateAction 的参数，核心是一条路线 path。下面是自动售卖任务走向物资调度终端的一段：

{
  "path": [
    { "action": "ZONE", "zone_id": "OMVBase01" },
    { "action": "NAVMESH", "target": [185.9, 141.39] },
    {
      "action": "INTERACT",
      "target": [185.9, 130],
      "interact_text": ["物资调度终端", "物資調度終端"],
      "interact_rec": true
    }
  ]
}

路线由路点组成，每个路点是坐标加动作。坐标与 MapLocator 相同，为底图像素，下文的距离单位除特别注明外都是底图像素。路点有两种写法：数组 [x, y, 动作…, strict, zone]，或带 action 字段的对象。

动作共 15 种：

路线级参数及默认值：

路点上自带的值优先。

输出是成功或失败，重试交给 Pipeline 的 on_error。返回值的几种来源：

• 参数为空、path 为空、或 NAVMESH 展开后为空：直接返回成功。
• 参数解析失败、控制器后端不支持、同一个 tasker 已在导航：返回失败。
• 导航跑完：到达终点且记过终点证据才算成功；失败时日志写明原因，共 20 多种，见失败原因。

状态机

入口

MapNavigateAction 解析参数，解析 interact_text 指向的 OCR 节点和滑索数据，然后交给 NaviController::Navigate。入口还打开 normalize_position_via_navmesh：规划在 NavMesh 底图上进行，实时定位要先用 NavMesh 数据包自带的分层仿射换到 NavMesh 底图的像素系，角色位置和规划结果才在同一个坐标系里。

Navigate 的第一件事是防止导航套导航（#5067「INTERACT 升级为异步交互,提示触发统一使用距离闸」）。进程里有一张带锁的登记表，记着哪些 tasker 正在导航。进入 Navigate 时先把当前 tasker 登记上去；表里已经有它，说明这个 tasker 正在导航，这次调用直接返回失败。导航结束时，不论成败，登记都会撤掉。

防的是这种情况：导航途中调起的交互子任务是一段 Pipeline，它的 next 可能又接回导航动作；子任务是同步执行的，于是同一条导航线程上会套出第二层导航，两层抢同一个控制器和定位器，而且可以一直套下去。按 tasker 登记以后，一个 tasker 同一时间只有一层导航，同一进程里多台设备各自导航，互不影响。

登记是 Navigate 的第一步，前面什么都不做，所以被拒的调用几乎没有开销：作者的 Pipeline 即使无限重试这个节点，每次也只是查一下表，不会去加载数据包或等定位。

之后依次：预加载 NavMesh 数据包，等首个定位（100 次 × 100 ms），展开 NAVMESH 段，构造会话，进入 Run。Run 是导航的主体：

1. 执行 Bootstrap，选出起点，见启动与续接。它有几级兜底，总能选出一个起点。
2. 预先跑一次提示识别。识别第一次运行要做初始化，耗时较长，趁角色还站着先跑掉，免得落在行走中的某一刻上。
3. 启动后台扫描线程。
4. 按 phase 一刻一刻执行，直到收到停止，或进入 Finished、Failed。
5. 检查终点证据。路线尾部有提示待触发时，站定 150 ms 再执行，最多宽限 1500 ms，见采集与交互。

Phase

导航任何时候都只处于一个 phase（NaviPhase），主循环每一刻只执行当前 phase 的那一份工作。大部分时间处于 Navigate，沿路线走；轮到传送、滑索、FIND、TRIGGER 这类要等另一件事完成的点时，切到对应的等待 phase，事情办完再切回 Navigate。

回 Navigate 之前都会先看路线还有没有剩下的点；没有了就直接结束，有终点证据进 Finished，没有进 Failed。TRIGGER 只能做路线的最后一个点，带一个识别节点：行进途中每 300 ms 拿定位刚截的画面识别一次，命中就算导航成功；走到点上还没命中，才切到 WaitTrigger 原地等，见 TRIGGER。

等待 phase 单独分出来，是为了在等待期间关掉 Navigate 里的卡死检测、绕障、重规划和对交互提示的响应。这些判断的依据都一样：角色正按指令朝目标走，坐标却迟迟没有往目标推进，说明卡住或走偏了。等待期间角色并没有在按指令走路，坐标动或不动都说明不了这一点，照常判断只会误报，因此设计：

• WaitTransfer、WaitZipline：角色被机关或滑索带着移动，坐标的变化来自机关和滑索。
• WaitTrigger：角色站在点上等识别，坐标长时间不变是正常的，卡死检测却会判成卡死，接着去绕障。
• WaitFind：角色跟着画面里的目标框移动，小地图只在写了 find_arrive 时用来量离终点的距离，这些判断拿不到连续的坐标。退出时进度、恢复状态和定位跟踪都从头开始。

等待 phase 的每一刻还会清掉顶墙计数和挡路设备的观测：等待结束时角色可能已经换了位置，旧记录不再适用。

每刻顺序

Navigate phase 每一刻（Tick）执行 TickNavigate，步骤按功能归成下面几段。顺序本身就是设计的一部分：先确认坐标可信，再决定往哪走，最后才判断是否卡住。

几处顺序的原因：

• 软重规划在走廊消费和停滞时钟之前。偏离走廊触发的重规划生成的是一条新的、通常更长的走廊，停滞时钟随之清零；进度倒退触发的重规划不清零：它触发的原因正是角色沿走廊没有进展，重新生成的还是同一条走廊，挡路的是网格看不到的动态障碍；每次都清零的话，唯一能绕开障碍的卡死恢复会被一直推迟。
• 设备探测从停滞第一刻就开始喂。等恢复阶梯跑到设备那一级时，探测结果已经存好，读取不再花时间。
• 镜头对齐排在就地消费之前，紧跟着的 HEADING 转身从对齐后的镜头起算。
• TRIGGER 识别排在丢定位处理之前。要识别的画面（剧情、对话框、界面）常常盖住小地图，出现的那一刻定位正好失败；先识别，命中就直接结束导航。

失败原因

所有失败走同一个出口：停下所有移动，清掉路线跟踪和恢复状态，切到 Failed，再打一条错误日志，带上原因、当前距离、航向误差和停滞时长。

每个时限背后都是一类曾经无限卡住的情形，具体来源在对应章节里。

路线与动作

解析

数组写法按元素类型识别：开头两个数是坐标，布尔值是 strict，数组是动作列表，字符串是区域名。字符串长得像动作名或关键字时拒绝，避免把拼错的动作当成区域。

对象写法的键有别名，按优先级取第一个出现的：

其他规则：

• 同一坐标写多个动作时展开为多个路点；其中有非 RUN 动作时丢弃 RUN。动作列表为空时补 RUN。
• NAVMESH 强制严判。规划出来的这一腿按严判的判定圈和前视收尾，与作者有没有写 strict_arrival 无关。
• interact_text 这类文本列表遇到空值直接报错。空文本在识别侧能匹配任何提示，正好是这些字段要避免的见提示就按。
• 路线级的交互、FIND 默认值在路点解析完之后下发，路点自带的值优先。FIND 参数冲突只在真正喂到某个 FIND 点上时才报错。
• route_required（#5197）把路线切成分段，滑索规划按分段进行。

enable_bootstrap_navmesh 是给叠层地区准备的开关：楼层高度（tier floor）落在空中时，起步规划会绕出几百格；关掉它，Bootstrap 落到现成的两档兜底（串行续接、直接朝路线头走），照录制点走。

动作特性（#5586）

每种动作的静态策略写在 ActionTraits 表里，一种动作一行：

• 严判：到点必须停准。路点上的 strict 与这一列取或，路线只能把非严判的动作改严。
• 末端纠正：进圈后再纠正到位才验收，只对路线上明写了 strict 的点生效，见末端纠正。
• 分段边界：开启滑索时，全局规划在这些点处分段，见滑索。
• FIND 不设严判。FIND 的锚点只是开始找的位置，收尾由视觉伺服完成。
• TRIGGER 设成分段边界，开启滑索时这个点原样保留；不在边界上的点可能被滑索规划换成普通规划点，trigger_node 也就丢了。

此处由表派生出几个谓词，后文将会反复用到：

此前这些判定散落在 RequiresStrictArrival、SettlesAtArrival、IsIntrinsicRouteBoundary 等函数里。改为表之后，表以外含 ActionType:: 的判定从 33 行减到 15 行。

路径搜索

NAVMESH 路点在导航开始前规划，结果展开为一串带净空信息的 RUN 点。导航中的起步接入、动态重规划、卡死绕障、跨层逃逸、滑索的步行腿也调用同一个规划器。

规划器的实现原理十分复杂，因此单独成文，详见 NavMesh：终末地路径规划，按执行顺序讲数据包、预烘场、垂直可达判据、窗口分档、两段搜索、视线判据、后处理和诊断。本节只留导航侧要用到的部分：规划的大致流程、交回导航的结果，以及展开器自己的兜底。

规划概览

水平方向的单位是底图像素，竖直方向是米。按滑索数据里的仿射推算，武陵 1 像素约 1.33 m，四号谷地约 1.42 m；体素边长 0.25 像素，约 0.33 到 0.36 m。垂直可达判据里可直接迈上的台阶高 0.5，跨窄凸起或浅坑允许抬升 1.25，角色没有摔落伤害，向下落差不设上限；台沿下落另查碰撞体，见垂直可达判据。

黄色粗线为拓扑层的逐格路径，红色为最终路点。

• 左图在四号谷地，拓扑层沿道路中轴走，几何层在路面内取直，502 个拓扑格最后剩 21 个路点。规划共 161 ms：开窗 65 ms，拓扑层 51 ms，几何层 24 ms。
• 右图在武陵，路线经过水面上的一段折线桥。桥面窄，几何层贴着拓扑层走，51 个路点，共 116 ms。

白色虚线是起终点连线，右图的连线横穿水面，路线经折线桥绕过去。

规划器的几次大改：#3084 是三角网 A*；#4460 改为每次规划在窗口内现场体素化；#5026 把格图挪到随包预烘；#5405 改为拓扑与几何两段搜索；#5450 加入旁包和窗口分档。见 NavMesh 一文的演进。

规划结果

规划器交回一条折线，每点带所在格的净空和所在面的高度，另附一组航点下标和台沿下落的落点，展开器照抄。面高写进路点，运行中重规划时，起点楼层取角色正在走的那段规划线上的面高（两端路点之间按投影插值）。落点改成严判点，带上下层面高和起跳点；角色沿下落方向越过它才算到，越过之前起点楼层仍按台上算。净空随路点交给跟随层，用于收紧判定圈和限制切弯，见到达判定、走廊跟随。

NAVMESH 路点可以用 target_deck_y 声明终点落在哪一层重叠面上（#4836「NAVMESH 航点支持声明所在重叠面」），高度匹配容差 2。它决定终点停在哪个 span，也让起点先只吸附种子格里有终点那一类面的三角；终点的三角吸附仍用楼层高度。刚从滑索落到架子上时，导航另传架子高度作为起点声明面，起点按它吸附（#6205「滑索落地重规划起点层与同步规划停步计时」），见 NavMesh 一文的起点所在的面。

导航时规划器只交回路点或错误文本，日志里留下窗口行或失败行；窗口、分段耗时和各阶段点列只有 WebUI 的路线预览会收集，见诊断。

兜底

一个 NAVMESH 路点的展开顺序：

1. 规划。成功则跳到第 6 步。
2. 起点恢复（#4188「起点位于 off-mesh 时先盲走到最近网格点」）：在 32 以内找最近的网格点，有起点声明面时按声明面选层，没有就按起点楼层；距离超过 0.5 就先插一个 RUN 点盲走过去，再从那里重新规划。
3. 禁区：端点落在作者禁区里时直接失败，后面的兜底一律跳过。禁区是作者画死的约束，后面每一条兜底都不看可走面，交给它们就相当于让角色从禁区里穿过去。
4. 滑索桥接：开启滑索时，步行不通先试滑索，见滑索。连续滑索可能分别接上起终两侧的可走面，步行不连通时这一腿仍可能到达；滑索结果是完整的规划，优先于后面的二维盲走。
5. 盲走探针（#3505「NAVMESH 目标不可达时盲走补全最后一段」）：起点到目标规划不通时，改为规划到目标附近一个走得到的点，最后一段从那里直线走到目标。这段直线没有规划路线可跟，所以称为盲走。候选点（探针）取在目标到起点的连线上：第一个就是目标本身，之后每个比上一个离目标远 2，最远离目标 42，起点更近时到起点为止。探针只用来挑规划的终点，全部在出发前算完。每个探针先吸附到 12 以内最近的可走格，吸附不上就跳过；吸附上了就从起点规划到吸附点，第一个规划成功的采用。角色先沿这条路线走到吸附点，再按追加的一个 RUN 点直线走到目标。盲走不能超过 30，超过则整个路点失败；吸附最多挪 12，离目标超过 42 的探针剩下的盲走一定超过 30，所以探针最远取到 42。总预算 8000 ms。声明了 target_deck_y 时禁用：盲走兜底是二维的，走到目标正上方也算到，用它兜底就把错层吞了回去。
6. 开启滑索时，步行结果会与滑索比较。
7. 输出路点：终点严判，中间拐点不严判，每点带净空和面高；台沿下落的落点改为严判，target_deck_y 取下层面高，另记起跳点。作者声明的 target_deck_y 写在最后一个点上。重规划的锚点就是这里生成的点，声明落在点上才能在重规划之后保留下来。

保留作者路线（#5205「避免盲走兜底跳过作者路线」）：开启滑索时，作者写的移动点变成可选提示，每个分段先从起点到终点整段规划一次，让步行和滑索在同一个比较里竞争。这次整段规划不允许盲走：全局规划只有完整抵达终点才能跳过作者提示，盲走只是逐点执行时的局部兜底，走到可走面边缘再直冲终点算不上完整路线。失败就逐点按原动作重放作者提示。此前一次全局规划接受了盲走兜底，先走到离终点约 27.64 的可走面边缘再盲走过去，4 个作者提示点全被跳过，角色走进了水里。

手写 RUN 段：作者手写的 RUN 折线按原样直走（#3929「移除对预制菜的神秘判定」）。只剩一个手写的尾点时也直着走过去（#4947「尾部裸坐标点不再交给 A* 贴回网格」），交给 A* 会为了贴回网格绕远路，无视作者的预期路线。这两条在运行期的走廊生成里判断。

展开失败：整条路线展开失败时，按角色位置切掉已走过的前缀再展开一次（#5247），续接点的判法见启动与续接。

缓存与并发

• 数据包加载放进单线程任务队列，按「路径#区」缓存在进程级的表里，不淘汰。导航在等首个定位之前就把加载排进队列。各区的条目共用同一份格图段字节和同一份旁包（#6219「规划提速并共用旁包与格图段」）。
• 引擎内按区缓存清洗后的数据，只留最近两个，通常是一层底层加一层分层。
• 同一引擎上的规划持锁串行。
• 展开阶段的规划可以取消。运行期的重规划不能取消，在当前这一刻里同步执行，人停在原地等它算完：规划前先松开前进键，规划耗时从两个停滞时钟和偏离 watchdog 的计时里扣掉（#6205「滑索落地重规划起点层与同步规划停步计时」）。更早的 #6109 先给动态覆盖的规划加上了偏离 watchdog 的扣除，起因是 #6104 的失败：两次规划共 12.6 s 全算成了偏离时间，见偏离。

启动与续接（Bootstrap）

角色开始导航时可能已经站在路线中段，比如 Pipeline 重试，或上一个节点已经走了一部分。Bootstrap 要回答两个问题：角色现在属于路线的哪一段，以及从当前位置怎么走过去。

起步流程

flowchart LR
    subgraph G1a [起步 A*]
        direction TB
        B["BeginNavigation<br/>清空状态与禁区，置位镜头对齐"] --> E{"线路开启<br/>起步 A*？"}
        E -->|是| C["续接候选<br/>定扫描起点"]
        C --> S["可达锚点扫描<br/>第一个规划得通的点"]
        S --> O["动态覆盖<br/>对锚点再规划一次"]
        O -->|成功| N1(["Navigate"])
        O -->|失败| X1(["转串行续接"])
        E -->|否| X1
    end
    subgraph G1b [串行续接]
        direction TB
        R{"续接候选在<br/>路线中段？"} -->|是| Q["从候选点接着走"] --> N2(["Navigate"])
        R -->|否| H["从路线头开始"] --> N2
    end
    G1a --> G1b

起步 A* 由线路的 enable_bootstrap_navmesh 控制。两条取锚点的路子最后都要调 PlanNavmeshRoute，关掉开关就等于起步不做规划，直接落到串行续接的两档兜底。开关只看线路声明，代码不做自动判断：自动判断”网格不对劲”容易误伤正常的路线。

续接候选

续接候选决定角色属于哪一段。先在路线的线段上找投影。设一条线段从路点 $A$（段首）连到下一个路点 $B$（段尾），角色位置为 $P$，从 $P$ 向直线 $AB$ 作垂线，垂足记作 $Q$：

• 投影参数 $t$：$Q$ 在 $A\to B$ 上走过的比例。点积 $\overrightarrow{AP}\cdot \overrightarrow{AB}=|AP||AB|\cos \alpha$，$\alpha$ 是两个向量的夹角。除以一次 $|AB|$ 得到 $|AP|\cos \alpha$，就是 $Q$ 离 $A$ 的距离（$Q$ 在 $A$ 之前时为负）；再除以一次 $|AB|$，换算成占段长的比例。$t=0$ 时 $Q$ 就是 $A$，$t=1$ 时是 $B$，$t=0.5$ 是中点；$t<0$ 时垂足落在 $A$ 之前，$t>1$ 时落在 $B$ 之后。
• 离线距离：$|PQ|$，$P$ 到这条线段的垂直距离。
• 离段首、离段尾：$|PA|$ 和 $|PB|$，$P$ 到两个端点的距离。

这些距离都是底图平面上两点间的直线距离。

判定规则：

• 每对相邻、同区的路点构成一条线段，不限动作类型；两点重合的线段跳过。$t\in [0,1]$（垂足落在两端点之间）且离线距离 $\le 3.0$ 的线段为候选。
• 认段首是从 $A$ 接着走，人要先回到 $A$；认段尾是从 $B$ 接着走，$A$ 算已经走过。$t\le 0.35$ 认段首；$0.35<t\le 0.60$ 时，$|PA|+0.5<|PB|$ 才认段首；其余认段尾。
• 中间那档在 $P$ 正好落在线段上时可以换算成 $t$ 的分界。记段长 $L=|AB|$，这时 $|PA|=tL$，$|PB|=(1-t)L$，代入 $tL+0.5<(1-t)L$ 得 $t<0.5-0.25/L$。段长 10 时分界在 0.475；段长短于 1.67 时 $0.5-0.25/L<0.35$，这一档用不上，分界就是 0.35。$P$ 离线越远，$|PA|$ 和 $|PB|$ 的差越小，分界还会再往段首移。
• 多段同时成为候选时取离线距离最小的一段，相等时归前面的段。

没有线段成为候选时（离所有线段都超过 3.0，或垂足都落在端点外），改看路点本身。只看区兼容、离 $P$ 不超过 18 的路点，下面「候选」指这些点，距离指 $P$ 到路点的距离：

1. 有站在点上（距离 ≤ 1.5）的，取路线顺序里最早的一个。环形路线的首尾常常重合，取最早的才不会把路线头当成路线尾。
2. 记离 $P$ 最近的候选为 $N$，$N$ 之前各候选到 $P$ 的最小距离为 $D$。$N$ 之前没有候选，或 $|PN|+5.0<D$，取 $N$。
3. 其余情况从 $N$ 往前回退。这一步的距离改为前驱到 $N$ 的距离：前驱要带坐标、区兼容、离 $N$ 不超过 18，碰到 ZONE、HEADING 这类无坐标标记就停。

左图是投影规则，色块表示角色站在那里时从哪个点接着走，白色区域交给离线规则。右图是离线规则的示意：最近点 w3 离角色 5.7，更早的点里最近的 w0 是 8.5，$5.7+5.0\ge 8.5$，于是从 w3 往回退；每个前驱都在 w3 的 18 以内，一直退到 w0。

回退时每个前驱都和最近点比距离，链长因此有界。无坐标的 ZONE、HEADING 标记截断回退；最近点之前只有这类标记时，从路线头开始。

这条规则来自 #5060「bootstrap 续接不再只按最近点判定」。此前角色不在线上时只按最近点判断归属，零点几的距离差就能让一整簇路点被跳过。现在跳过路点需要证据，证据不足则从更早的点接着走。

可达锚点

续接候选给出扫描的起点，之后往后找第一个能规划过去的路点：

• 跳过区不兼容的路点；遇到声明了别的区的 ZONE 就停；遇到没有坐标的必经锚点（比如 HEADING）就停。
• 对候选跑一次规划：终点钉在候选声明的面上；起点楼层取角色正在走的那段规划线的面高，刚从滑索落到架子上时再带上架子高度作为起点声明面。够不到终点那张面的候选不会被选中。第一个规划成功的就是锚点，扫描到此为止：再往后比较代价挑更近的，等于在归属判定之后又做一次就近吞点。
• 必经的语义锚点规划失败时停止扫描。
• 最多规划 8 次。每个不可达的候选都要跑满一次搜索，单次就是秒级，曾有一次连续 34 个候选不可达，额外卡了约 70 s；预算用尽就放弃这轮扫描，交给下一级回退。
• 扫描无果时取续接候选之后的第一个锚点。

动态覆盖

选中锚点后，对它再规划一次，把规划出的点插到锚点之前，这一步叫动态覆盖（overlay）：

1. 松开前进键，规划耗时从偏离 watchdog 和两个停滞时钟里扣掉（#6109、#6205）。
2. 规划时带上当前的运行期禁区，以及与扫描相同的起点楼层和起点声明面。
3. 规划点以非严判 RUN 插入，不含终点，锚点本身保留原动作。
4. 规划点为空、锚点又在判定圈外时，补一个领头节点，避免路线只剩一个点。
5. 续接位置变了再重置硬性进度时钟。
6. 跟随状态重置，起步确认清零。规划点为空且角色已在判定圈内时，直接记为已起步。

锚点因此会被规划两次：扫描一次，覆盖一次。#6104 的日志里分别是 118 ms 和 117 ms。

覆盖失败时，续接候选在路线中段就从它接着走；再不行就从路线头开始。

导航中途的重规划走同一个覆盖函数。单次重规划失败不终止导航，退回当前路线继续走，持续没有进展时由卡死恢复的各级超时收口。路线没有被替换，所以只清跟随进度，起步确认保持原状。

镜头对齐

#5917「起步前对齐镜头与角色朝向」：导航的反馈量默认是小地图箭头给出的角色朝向（heading_source 取 character），按前进键时角色却沿镜头方向走，两者不一致时控制环的反馈和实际走向对不上。因此先在起步前把镜头转到导航使用的朝向，按 W 时角色就沿控制环看到的方向走。对齐时只转镜头，前进键保持松开。镜头与导航朝向的差值小于 10° 时跳过，转完等 300 ms 再取一次位置。heading_source 取 camera 时，导航朝向和镜头朝向是同一帧读出的同一个值，差值为 0，对齐每次都跳过。

小地图中心的三角形是角色箭头，白色扇形是镜头的视野，扇形中线就是镜头朝向，角度以正上方为 0°、顺时针增大。左图取 character，控制环读的是箭头 40°，按 W 时角色沿镜头 110° 走，两者差 70°；扇形中线落在绿色虚线的 ±10° 以内时跳过对齐。中图把镜头转 −70°，扇形中线与箭头重合，角色原地站着。右图取 camera，导航朝向直接取扇形中线，差值恒为 0。

导航开始时置位一次（ArmCameraAlign），之后每次站定去做别的事（传送、过图、挖掘、交互、FIND、滑索、严判到点、JUMP、FIGHT）都重新置位，在下一个 Navigate 刻消费：做这些事的过程中镜头可能被挪走。

刹车、卡住重发和脱困不置位。对齐排在就地消费的语义动作之前，紧随其后的 HEADING 转身也从对齐后的镜头起算。

到达判定

判定圈

左图是自动采集路线 AutoCollectRoute10Goto3 的 8 个采集点，相邻间距 2.5 到 8.2。红色虚线是常规的 3.25 圈，一个圈能盖住好几个相邻点；绿色是收紧后的 1.5 圈，点与点基本分开。右图是一个采集点周围的几道带：判定圈之外，还有接近时切走路（3.0 进入、4.5 退出）和禁冲刺（8.0）两道，见冲刺与走路。

提示点收紧到 1.5 来自 #5030「增强自动采集,收紧判定圈并接近时切走路」。收紧之后真站不上去时，硬性无进展超过 6000 ms 就放回常规值，避免多出一种卡死。

规划生成的点按走廊净空收紧。通道比判定圈还窄时，常规的判定圈会让角色提前弃点、直奔下一点，抄出一条撞墙的弦。

到点处理

进圈之后：

1. 还没确认起步时不推进，见下一节。
2. 严判点进入原始判定圈（2.25，不受上表的放宽和收紧影响）时，先做末端纠正。滑索和传送门有各自的站位与提交距离，判定圈被放宽或收紧的那几种情况要的正是宽松的判定，这些都不做纠正。
3. 严判点仍在移动时刹停，再等 150 ms。PORTAL 也走这一步，之后再按下前进走进传送门。
4. 按动作分派：TRANSFER、PORTAL、ZIPLINE、DIG、FIND、INTERACT、SPRINT、JUMP、FIGHT 各有处理函数；RUN、COLLECT 直接推进。HEADING、ZONE 没有坐标，NAVMESH 展开后换成了规划点，三者实际到不了这一步。

起步确认

起步确认最早来自 #2162，对应 startup_motion_confirmed：角色位移达到 0.8 或换区之后才算起步，在此之前三条推进路径都不生效：到点推进、经过即推进、走廊消费（#4164「走廊路点消费对齐起步门控」）。没有这一步，起点附近的路点会在角色动起来之前就被消费掉，转向直接对准更远的点。

跟随状态每次重置，起步确认都会清零：串行续接、每次动态覆盖、作者路线重规划、挖掘之后、异步交互之后，以及滑索动作里的三处。例外有两个：动态覆盖为空且角色已在判定圈内时直接确认；重规划失败退回当前路线时保留原来的确认状态。

经过即推进

角色常常从路点旁边擦过，没有进圈。路线跟踪器在两个连续 RUN 点之间维护一条线段的投影状态：

const bool projection_growing =
    state->best_projection_on_segment >= 0.55 && segment->clamped_projection + 0.05 >= state->best_projection_on_segment;
const bool route_fact_passed =
    segment->next_distance + position_quantum < segment->current_distance || segment->turn_back_yaw >= 110.0;
const bool hard_pass_evidence = route_fact_passed || segment->raw_projection >= 1.05 || near_next_waypoint;
const bool should_latch = !state->passed_waypoint_latched && segment->raw_projection >= 0.40
    && (((cross <= 1.5) && hard_pass_evidence) || ((cross <= 3.0) && projection_growing && hard_pass_evidence));

• 前提：当前点和下一点都是非严判 RUN，且同区。
• 投影：原始投影参数 ≥ 0.40。
• 横向偏差：≤ 1.5；或 ≤ 3.0 且投影还在增长（历史最好值 ≥ 0.55，当前值不比它少 0.05 以上）。
• 硬证据，任一条：离下一点比离当前点近 0.25 以上（一个定位量化步）；回头看当前点的角度 ≥ 110°；原始投影 ≥ 1.05；已进入下一点的判定圈。

满足以上条件先标记为已经过，标记之后还要夹紧投影 ≥ 0.90、原始投影 ≥ 1.05、或进入下一点的判定圈，三者之一才真正推进。一刻可以连推好几个点。历史最好投影只在横向偏差 ≤ 3.0 时更新；还没标记且横向偏差超过 3.0 时，这条线段的状态清零。

走廊消费

规划生成的点可能很密，转角处又常被抄近路。走廊跟随层沿走廊算出角色的弧长，路点的走廊弧长不超过角色弧长 + 0.25 的，一并视为经过。扫描到锚点或第一个非连续 RUN 点为止。这一机制来自 #3458「navmesh dynamic detour recovery overlay」。

动图逐刻回放 #6104 日志 06:15 那一趟的 18.11 s 到 19.58 s，相邻路点相距 0.8 到 3 像素。右侧三行是当前路点的三项推进判定：到点比的是离路点的距离和判定圈；经过即推进要求角色在当前路点到下一点这条边上的投影参数 t 至少 0.40；走廊消费比的是路点和垂足 F 从走廊起点 A 量起的弧长。哪一项推进了路点，哪一行就高亮。到点推进的那几刻，推进完这一刻的处理就结束了，日志里没有记下走廊投影，第三行留空。

18.30 s 推进到 w24 后走廊重建，角色还在 w24 之前，于是把当时的位置 A 插在折线开头。之后角色从 w24 内侧擦过，一直在判定圈 1.75 之外。到 18.95 s，离 w24 2.09，t 是 0.375；从 A 沿走廊量弧长，w24 是 2.87，在 s(F) + 0.25 = 4.18 以内，w24 被消费；w25 是 5.69，扫描停在 w25。

角色的投影被夹在走廊窗口之外时要小心：投影在窗口之前，一律不消费；投影在窗口之后、横向偏差超过 2.2，也不消费。#4630「走廊消费在投影夹到末点时不再整段吞点」修复的正是投影夹到末点时一次吞掉整段路点的问题，对应 #4610「环境监测旧庭树失败」和 #4625「环境监测任务有两个失败了」。

上图是投影夹在窗口外的两种情况，窗口指从游标所在的边到末边的这一段。角色在窗口之前时，垂足夹到游标边的起点，那里的路点按弧长会被算作经过，这一刻一律跳过消费。角色在窗口末端之外时，垂足夹到锚点，锚点之前的路点会一次全部算作经过；横偏在 2.2 以内时角色就在锚点附近，照常消费，超过 2.2 时跳过。

走廊消费成功后，恢复阶梯和全局重捕获计数清零，再跑一次路线跟踪。

末端纠正

#5198「严判点到达后减速并纠正过冲」作用于路线上明写了 strict、且动作带末端纠正特性的点：RUN、SPRINT、JUMP、FIGHT、TRANSFER、NAVMESH、DIG。对这些点，判定圈是纠正的触发条件：进圈只说明剩下的残差值得走回去，纠正到位才验收。纠正时前进键一直按着，松开前进键再拖视角只会转镜头，角色仍朝原来的方向。

接近时先减速：严判点在判定圈外 6.0 起禁冲刺，接近段切走路。走路让滑行距离减半，到点后要走回去的那段也短一半。进圈后的循环：

1. 取一帧干净的定位，定位器沿用上一次输出或黑屏的帧跳过，最多等 12 帧 × 120 ms。等不到就刹停，按原判定圈收下。
2. 本步走了 0.4 以上才更新朝向和速度：朝向取本步的位移方向，速度取位移除以真实经过的时间。转身的那段时间角色也在走，按睡眠时长算会把速度估高。
3. 残差 ≤ 0.5 即验收，日志 “Strict arrival verified.”。
4. 满 4 次纠正、连续 2 步走不到 0.4、或用满 6000 ms，按原判定圈收下，日志 “Strict arrival settle gave up, accepting on band.”。
5. 转向目标方向，前进键一直按着，步长取 $\max (\text{残差},0.6)$，按实测速度换算为按住时长，夹在 120 到 450 ms。第一步还不知道速度，固定 200 ms。

步长下限 0.6 来自小地图定位的静止处理：两次输出相距不到 0.40 时，定位器沿用上一次的坐标（见 MapLocator），比这更短的一步分不清是走了还是没走，所以步长不低于它。连续两步位移都不到 0.4，说明按键根本没让角色挪动，再纠正也只是原地重复。

纠正本身从不判失败，最坏情况和加纠正之前一样按判定圈收下。

左图取自 #6104 日志里的一次严判到点。灰线是走廊跟随，9.48 s 切走路；进圈后第 1 步残差 1.26，开环按 200 ms，实际走向和目标方向差了 24°；第 2 步残差 0.64，按第 1 步实测的速度算出 170 ms；之后残差 0.37，验收。右图是按住时长与残差的关系，实测走路速度约 3.7 像素/s。

终点

路线尾部被消费时，还要确认角色真的到了终点，任一条成立即可：

• 终点在到达时记过账，日志 “Final arrival evidence recorded.”。
• 角色当前与终点同区，且在终点验收带以内：严判 2.0，否则 2.5。

都不成立时以 route_tail_without_final_success 失败，日志 “Route tail consumed without final success evidence.”。经过即推进和走廊消费都可能把终点前的点吞掉，这条检查防止路线在没到终点时报成功。

走廊跟随

走廊是角色从当前位置走到锚点（下一个需要停准的点）所沿的一条路。它的中心线是一条折线，途中的路点是折线的顶点；NAVMESH 规划出的路线还给每个顶点记了宽度，即该处可通行区域的半宽，称为净空，下图折线两侧的灰色范围就是它。路点本身是一串离散的点，按路点跟随时，角色到了一个点才转向下一个，每次换点航向都会跳变。连成走廊之后路是连续的，角色每一刻都能在上面量出三样东西：自己对应路上的哪个位置（投影点），离中心线多远（横向偏差），沿路往前一段朝哪个方向（前视点）。转向追的是这个方向，横向偏差太大时重新生成走廊。

当前路点是带坐标的 RUN 时，由 NavRunController 跟随。它在当前点和锚点之间建一条折线作为走廊，每刻把角色投影上去，沿折线往前量出前视点，算出这一刻要追的航向。这与路径跟踪里的 pure pursuit⁠^[2]同一思路：每刻追路径前方一段距离处的点。路点级的 RouteTracker 同时在跑，它给出的 route_heading 指向当前路点本身，走廊建不起来的刻退回用它。

走廊的起点在建走廊时定下：路线自己的点从当前路点开始，再按角色位置裁剪或在开头补上角色位置；A* 走廊直接从角色位置出发，规则见走廊来源。净空只有 NAVMESH 展开出的顶点才有，手写的点没有，拐角用它限制切角。走廊建好后一直沿用，直到下一次作废重建。

黄线是走廊折线：从走廊起点经过当前路点和途中的连续 RUN 点，一直到锚点；灰色是各顶点净空连成的范围。这条走廊是在上一个路点推进时建的，起点就是当时角色所在的位置，之后角色偏到了折线一侧。角色向折线做垂线，垂足是投影点，垂线长是横向偏差；从投影点沿折线量出前视距离，得到前视点，corridor_heading 从角色指向它（精确的取法见瞄准点）。route_heading 指向当前路点，straight_to_anchor 是角色到锚点的直线距离。

走廊每刻的输出被几处读取：

锚点

严判 RUN 以自身为锚点。连续 RUN 从当前点往后找，第一个带坐标、且不是连续 RUN 的点就是锚点，即下一个语义动作点或严判点；途中遇到别区的 ZONE 声明、或 HEADING 这类没坐标的必需语义点就停，取已经扫过的最后一个带坐标的点。

每行是路线上的一段路点，黄色底是走廊覆盖的路点。上：当前点是连续 RUN，往后扫到第一个语义动作点（这里是采集点）为锚点。中：严判 RUN 的锚点就是它自己，走廊只到这一个点。下：扫到 HEADING 这类没坐标的必需语义点就停，锚点取它前面最后一个带坐标的点。

严判 RUN 要求精确到点，锚点只能是它自己；连续 RUN 可以越过普通路点一直看到下一个语义锚点，所以它的走廊一直延伸到下一个需要停准的地方，中间的普通 RUN 点只是折线顶点。锚点下标或 zone 变化时，整条走廊作废（invalidate），软重规划次数也一起清零。路点推进、动态覆盖、路线重规划、全局重捕获之后会置 nav_run_dirty，下一刻同样作废重建。

走廊来源

buildPlan 按顺序取：

1. 路线自己的点。从当前点连到锚点，带上每个点的走廊半宽（NAVMESH 展开的点有，手写的点没有）。取到 2 个点以上时直接用。中途遇到没坐标的点、或路线先结束了，就返回空，不信一条够不到锚点的线。
2. 末端单个裸坐标。当前点就是锚点、折线只有这一个点时，若它是连续 RUN、没有净空、离角色超过 0.25，就从角色直线连过去（#4947）。作者手写的裸坐标按直着走过去处理，交给 A* 会为了贴回网格绕远路；NAVMESH 展开出的点带净空，末点又是严判，不走这一条。
3. A*。以上都不成立时从角色位置规划到锚点，带上目标层高和当前的虚拟禁区。严判 RUN 以自身为锚点，折线只有一个点，所以它的走廊总是这条 A*。

前两种以 literal = true 提交，第三种为 false。

用路线自己的点之前，要先裁到角色所在的位置。折线总是从会话的当前路点开始，规划生成的点判定圈按净空收紧，常常只有一个像素左右；角色从路点旁一个像素处擦过时，折线起点就落在角色身后，这时再把角色位置接到折线开头，走廊会让角色掉头去走已经走过的地面。裁剪的规则：

• 逐条边往前丢：角色在这条边上的投影参数 $t\ge 1$（$t$ 的定义见续接候选，$t\ge 1$ 表示垂足已越过边的终点），且离边的终点不超过 4.0，才丢掉这条边的起点。
• 遇到转角 ≥ 90° 的顶点就停。过了直角，出边会把角色往来时的方向带，角色还没绕过拐角，在入边上的垂足就已经跑出了入边末端；在这里裁掉，跟随层拿到的是一条直接横穿拐角的线。
• 4.0 的上限防定位漂移。定位偶尔会在几秒内报出几百像素外的位置，不设上限的话，这种位置会被当成已经越过全部顶点，剩下的折线被整段删掉。
• 最后角色离当前边的垂足在 2.5 以内、且垂足落在边的内部，才把起点替换成垂足。

裁不上（角色还在折线起点之前，或离得远）时，若角色离起点超过 0.25，就把角色当前位置插到折线开头，净空复制首项。

w0 是会话的当前路点。(a) 角色已经从 w0 旁擦过，垂足落在 w0→w1 内部，起点换成垂足；红虚线是不裁、直接把角色接到 w0 的走廊，开头一段要掉头。(b) 角色在 w0→w1、w1→w2 上的投影都越过了边的终点，到 w1、w2 的距离 3.4、1.7 都不超过 4.0，两条边的起点依次丢掉；在 w2→w3 上垂足落在边内、离角色不到 2.5，起点换成垂足。(c) 角色在首边上的投影参数 $t\le 0$，一个顶点都不裁，角色位置插到开头。

走廊建失败后，同一个锚点 3000 ms 内不再重试。失败的规划没有留下可作废的走廊，不设冷却的话下一刻马上又会重建；失败的规划又是最慢的一种，会走完整个窗口分档才放弃。每刻重试的开销远高于这段时间退回路点级转向的代价。

投影

const double raw_t = ((position.x - a.x) * dx + (position.y - a.y) * dy) / len_sq;
const double t = std::clamp(raw_t, 0.0, 1.0);
const double px = a.x + t * dx;
const double py = a.y + t * dy;
const double cross = std::hypot(position.x - px, position.y - py);
if (!best || cross < best->cross_track) {

投影找的是角色在走廊上对应的位置。每条边的算法和续接候选里的投影参数相同：边从 $A$ 到 $B$，角色在 $P$，

$\mathrm{clamp}(x,a,b)$ 把 $x$ 限制在 $[a,b]$ 里：小于 $a$ 取 $a$，大于 $b$ 取 $b$。垂足落在边外时 $t$ 被夹到 0 或 1，$F$ 取较近的端点，所以 $F$ 总是这条边上离 $P$ 最近的点，$e$ 是 $P$ 到这条边的距离。代码里的 raw_t、t、(px, py)、cross 依次是夹之前的 $t$、夹之后的 $t$、$F$、$e$。

每条边各算出一组 $F$ 和 $e$，取 $e$ 最小的边：它的 $F$ 是投影点，$e$ 是横向偏差。扫描从游标所在的边开始，到最后一条边为止；$e$ 相等时取先出现的边。每刻结束把游标设为投影边，下一刻从这里扫起，所以投影只会往前走，折返的走廊上投影留在后经过的那一段。扫描的第一条边上 raw_t < 0（角色还没到这条边的起点），或最后一条边上 raw_t > 1（角色已经过了走廊终点）时，标记为窗口外。

一条折返的走廊，去程 e0、e1 和回程 e4、e5 相距约 2.6。黄线是游标及之后、这一刻参与扫描的边，灰虚线是游标之前、不再扫描的边；空心圆是投影点。游标每刻末移到投影边：第 4 刻投影到 e1，从第 5 刻起从 e1 扫起；第 8 刻投影到 e4。第 11 刻角色斜着切向去程一侧，离 e0 的距离 1.25 比离 e5 的 1.52 还近，从头扫会投影回去程（红虚线）；从游标 e4 扫起，投影留在回程的 e5 上。

每刻位移

前视距离按”每刻走多远”来定，所以先要估计每刻位移。

• 控制器自己数刻，没动的刻也计数。
• 与上一个样本相距不超过 0.25（一个定位量化步）时不记样本。
• 速度超过 40 像素/秒，或刻序号间隔超过 8 刻，清空窗口重来。前者快到不可能是行走，多半是重新捕获后落到了别处；后者跨过了一段停滞，旧样本对这段时间一无所知。两种情况下样本对都不再代表一刻的行进。
• 最多保留 8 个样本、2000 ms。
• 估计值 $s$ 按下式从窗口里的样本算出。

$q_0,q_1,\dots ,q_n$ 是参与估计的样本位置，按时间排列。$q_n$ 是最新样本；$q_0$ 是起点样本，取离最新样本至少 700 ms 的样本里最晚的一个，没有这样的样本时取窗口里最早的一个。$k_0$、$k_n$ 是 $q_0$、$q_n$ 记录时的刻序号。分子是样本连成的折线长度，分母是两端相隔的刻数，没记样本的刻也算在分母里，所以 $s$ 是这段时间里平均每刻走的距离。

速度采样排在所有提前返回之前。走廊建不起来的刻也照样采样，走廊恢复后的第一刻就有可用的速度估计。

取自 #6104 日志里一趟起步后的前 18 刻（5.02–7.18 s）。左上是窗口里样本的位置，粗线是参与估计的那段折线，黑圈是起点样本；下方时间轴上 ● 是样本，× 是离上一个样本不超过 0.25、没记样本的刻，○ 是被挤出窗口的样本。第 1–4 刻只有一个样本，没有估计，前视距离取 2.5。第 2–4 刻没记样本，刻序号照样增加：第 5 刻的估计是第 1、5 刻两个样本间的弧长除以 4 刻，得 0.23，7 倍是 1.6，夹到下限 2.0。第 12 刻起，往回 700 ms 以外有了样本，起点换成最后一个这样的样本（第 6 刻）。第 15 刻起窗口满 8 个，每记一个新样本就挤出最老的一个。这 18 刻按上面的规则算出的前视距离，与日志里投影点沿走廊到前视点的距离逐刻一致。

前视距离

if (!route.startup_motion_confirmed) {
    return kNavRunLookaheadLowSpeedM;          // 2.5
}
const std::optional<double> step = estimateStepPerTick();
if (!step) {
    return kNavRunLookaheadLowSpeedM;          // 2.5
}
return std::clamp(kNavRunLookaheadPreviewTicks * *step, kNavRunLookaheadMinM, kNavRunLookaheadMaxM); // 7, 2, 14

$L$ 是前视距离，$s$ 是上一节的每刻位移，$7s$ 就是角色 7 刻走的路程，结果夹在 2 到 14 之间。起步尚未确认、或还没有速度估计时 $L=2.5$。

**为什么要设计一个前视距离？**走到拐点再发转向，等角色真正转过来，它已经在拐点之后好一段了。原因都在控制回路里：

• 指令生效有延迟。一刻要截图、定位、算航向、发转向，健康时约 110 ms，PlayCover 上中位约 200 ms（见难点）。发出的转向要过约 2 刻才开始体现：掉头锁定那张表里，3.267 发出 70°，3.412 的读数没动，3.564 才动了 11.7°。
• 转身时角色照常前进。转向期间前进键一直按着，指令生效之前角色沿旧方向走；生效之后每刻也只转 60° 左右（同一张表里相邻两刻转了 56°、63°），70° 的弯还要再花一刻多。
• 位置一刻一采样。每刻位移 1.6 时相邻两次定位相隔 1.6，定位很少恰好落在拐点上：这一刻还差 0.9，下一刻已经越过 0.7。“到了拐点”最早也要越过之后才知道。

三样叠在一起，角色过了拐点还要沿旧方向走两三刻。走廊在拐点 $V$ 转了 $\theta$ 角，角色过了拐点沿旧方向又走了 $x$，到达 $Q$；从 $Q$ 向出边作垂线，垂足为 $H$。$V$、$H$、$Q$ 构成直角三角形，直角在 $H$，斜边 $VQ=x$，$V$ 处的角是 $\theta$，所以角色离出边中心线

转角 $\theta =70°$，$\sin 70°\approx 0.94$，每刻位移 1.6。多走 1 刻，$x=1.6$，离中心线 1.5，还在净空 2.0 以内；多走 2 刻，$x=3.2$，离中心线 3.0，已经出了走廊。

前视把发转向的时机提前。转角不超过 50° 的弯，拐角一进入前视范围，走廊航向就开始转；超过 50° 的弯，前视点先停在拐点上，离拐点不到拐角提交距离时才越过拐点、开始转。延迟耗掉的那段路因此大半落在拐点之前。

示意，与拐角的动图同一个拐角：转 70°，净空 2.0，每刻位移 1.6。延迟按掉头那次的实测取整：第 k 刻发出的转向从第 k + 2 刻起才开始转，之后每刻最多转 60°。左边到了拐点（离拐点不到 0.8 或已越过）才转：第 7 刻定位离拐点还差 0.9，第 8 刻已越过 0.7，这一刻才发出转向；生效前又沿原方向走了 2 刻，第 9–14 刻都在净空之外，最远离中心线 3.9。右边按前视走：第 6 刻离拐点 2.5，进入拐角提交距离，提前发出转向；同样等 2 刻，延迟耗掉的 3.2 里有 2.5 花在拐点之前，转弯从拐点后 0.7 处开始，最远离中心线 1.2，一直在净空以内。

直线上同样需要前视。角色偏在走廊一侧时，如果追脚下的投影点，航向垂直扎向中心线，加上延迟，过了线才收住，再垂直扎回来，左右来回摆。追前方距离 $R$ 处的点，回线的角度是 $\arctan (e/R)$，$e$ 是横向偏差。偏差越小角度越小，角色斜着并回中心线，推导见瞄准点。

前视点沿走廊往前量，给出角色要追的方向，所以前视距离就是全部的转弯预判：拐角进入前视范围之后，转向目标才开始转。前视距离按刻数计，同时跟着速度和循环周期变。固定距离在角色减速时预判过多；链路慢到每刻走得更远时，又留不出反应的余量。按刻数计，同一套参数在快机和慢机上给出同样多的反应刻数。7 刻来自实机盲测：两种呈现顺序下 7 都胜过 5，也胜过 9；11 明显有害，会切角、游荡，耗时翻倍。

前视距离的历史：

#4604 的夹紧让前视弦离走廊折线不超过 0.5，实测的跟踪误差约为这个值的 1.7 倍，多出来的部分是跟随滞后。#4682 删掉夹紧，前视统一 6.0，按观测到的 5–8 px/s 行进速度留够转完一个弯的时间；这个距离随速度定死，#4809 改为从每刻实测位移推算。

取自 #6104 日志里的一趟（29.9–33.8 s），角色从左下走到 w20，在 w20 折返向左，再进入 w22–w25 的 U 形弯。每帧是一刻：黄线是这一刻的走廊折线，蓝色一段是投影点沿走廊量到前视点的距离，红箭头是走廊航向。这一段每刻位移 0.76–1.26，前视距离 5.30–8.83。30.28 s 起前视点停在拐点 w20 上，量到的距离从 6.04 缩到 2.91；30.98 s 进入拐角提交距离，前视点越过 w20，停在 w21 上，规则见下一节。到点的刻没有走廊输出，下一刻从角色位置重建走廊。角色在 w20 的折返处冲出了折线，31.29 s 重建后横向偏差逐刻升到 1.40。32.44–33.27 s 前视点先后停在 w22、w23 上。整份日志 2610 个走廊跟随刻的横向偏差中位 0.26，P90 0.95，P99 1.80，最大 2.58。

拐角

前视点沿折线往前推，遇到拐角时有两条规则决定它是停在拐点上还是越过去。

示意。走廊在拐点转 70°，拐点处净空 2.0；每刻位移 1.6，前视距离 11.2，拐角提交距离 $d_c=\min (4\times 1.6,2.0/\sin 35°)=\min (6.4,3.49)\approx 3.5$。角色每刻朝瞄准点走 1.6。第 1–6 刻投影点离拐点超过 3.5，前视点停在拐点上，灰圈是按前视距离本该落到的位置，走廊航向仍沿当前边；第 7 刻投影点离拐点 2.61，前视点越过拐点，走廊航向开始转。

if (len >= kNavRunCorridorEdgeMinM) {
    const double heading = NaviMath::CalcTargetRotation(a.x, a.y, b.x, b.y);
    const double turn = std::abs(NaviMath::NormalizeAngle(heading - base_heading));
    if (turn > kNavRunLookaheadTurnBudgetDeg && travelled > CornerCommitDistance(path, edge, turn, commit_distance)) {
        return a;
    }
}

转角预算 50°。前视点从投影点往前推，每经过一个拐点，看拐点后那条边相对当前边转了多少：

$h_0$ 是角色当前所在边（投影边）的航向，$h_i$ 是后面第 $i$ 条边的航向，航向的定义见瞄准点末尾。$\mathrm{wrap}$ 把角度差换算到 $(-180°,180°]$：两条边航向 350° 和 10°，直接相减是 340°，wrap 之后是 −20°，实际只差 20°。${\Delta }_i>50°$ 时，前视点停在这条边的起点，也就是这个拐点上。预算看的是相对当前边累积的转角：四个 30° 的台阶和一个急弯一样会让角色偏出走廊。

${\Delta }_i$ 是相对 $h_0$ 的净航向差。同向的台阶会累加，四个 30° 的台阶在第二级就是 60°，超出预算；左右交替的折线（+30、−30、+30）净差始终不超过 30°，不会停。

前视点停下，是为了不越过角色还没开始转的弯。前视距离按刻数计，慢循环上它会变长，前视点已经绕过拐角，拐角本身却还在很远的地方；角色朝前视点直线开过去，切的是弯的内侧，那里就是墙。

拐角提交距离（CornerCommitDistance），记作 $d_c$。投影点沿走廊到拐点的距离不超过 $d_c$ 时，前视点才越过拐点。

$s$ 是每刻位移，$L$ 是前视距离，$4s$ 是 4 刻的路程；没有速度估计时 $d_c=2$。拐点的净空 $c$ 已知时，再按这个拐角的转角 $\theta$ 取

这个上限来自切角的几何。角色离拐点 $d$ 时开始朝拐角里转，走的是一条弦，从拐点内侧切过去。按对称的情形估算：弦的两端在入边和出边上，各离拐点 $d$。拐点和弦的两端构成等腰三角形，顶角是 $180°-\theta$，两个底角各为 $\theta /2$。从拐点向弦作垂线，得到一个斜边为 $d$、底角为 $\theta /2$ 的直角三角形，垂线长

就是弦切进弯内侧的深度。净空 $c$ 是拐点处可通行区域的半宽，弯内侧的墙最近可能就在离拐点 $c$ 处，所以要求 $d\sin (\theta /2)\le c$，即 $d\le c/\sin (\theta /2)$。手写路线没有净空，只用按速度算的 $d_c$。

与上面的动图同一个拐角：$\theta =70°$，$c=2.0$，每刻位移 1.6。按速度算的 $4s=6.4$，切进 $6.4\sin 35°\approx 3.67$，超过净空（灰虚线）；按净空算的上限 $2.0/\sin 35°\approx 3.49$，切进的深度恰好是 2.0（红线）。两者取小，$d_c\approx 3.5$。

拐角提交距离也按刻数计，转弯因此总有同样多的刻数去完成；固定的世界距离在慢循环上不到一刻，角色到拐点时还朝着旧方向。4 刻少于前视的 7 刻，拐点落在 4 刻到 7 刻的距离之间时，前视点仍停在拐点上。

短边。短于 0.75 的边只计入前视距离，转角判断跳过它。规划器的顶点按格放置，太短的边方向只是量化噪声，在它上面误判出一个拐角会让前视点停住。

瞄准点

const double dx = lookahead.x - anchor.x;          // anchor 是投影点
const double dy = lookahead.y - anchor.y;
constexpr double kChordFloorM = 1e-6;
const double chord = std::hypot(dx, dy);
if (chord <= kChordFloorM) {
    return NaviMath::CalcTargetRotation(position.x, position.y, lookahead.x, lookahead.y);
}
const double reach = std::max(kNavRunAimReachMinM, chord);   // 6.0
return NaviMath::CalcTargetRotation(position.x, position.y, anchor.x + dx / chord * reach, anchor.y + dy / chord * reach);

记投影点为 $F$（代码里的 anchor）、前视点为 $G$，两点间的直线距离 $|FG|$ 称为弦长。瞄准点 $T$ 从 $F$ 沿 $F\to G$ 的方向推出 $R$：

$\overrightarrow{FG}/|FG|$ 是 $F\to G$ 方向上长度为 1 的向量，乘以 $R$ 就是沿这个方向走 $R$。弦长不短于 6 时 $R=|FG|$，$T$ 就是 $G$；弦长不足 6 时 $T$ 落在 $G$ 再往前的位置。走廊航向从角色位置 $P$ 指向 $T$。

角色偏在走廊一侧时，这个航向自带回线的分量。设 $G$ 在角色所在的同一条直边上，$P$ 离边的距离是横向偏差 $e$，$T$ 在边上 $F$ 前方 $R$ 处。$P$、$F$、$T$ 构成直角三角形，直角在 $F$，两条直角边是 $e$ 和 $R$，走廊航向与边的方向差

$R$ 越大，同样的 $e$ 造成的 $\delta$ 越小。$R$ 的下限 6 用来压住定位噪声：前视点停在近处的拐点上时，弦长可能只有 2 左右，$R$ 若跟着缩短，定位量化带来的那一点横向偏差就会单独越过转向死区。$R$ 也不短于弦长：比前视点更近的瞄准点在循环滞后下会转过头。

示意，角色偏在走廊一侧 0.8 处。(a) 前视点在当前边上 10.0 外，弦长不短于 6.0，瞄准点就是前视点；走廊航向与边的方向差 $\arctan (0.8/10.0)\approx 4.6°$，朝折线一侧偏，这就是回线的分量。(b) 前视点停在 2.5 外的拐点上，瞄准点沿弦的方向推到 6.0。直接追前视点（灰虚线）与边的方向差 $\arctan (0.8/2.5)\approx 17.7°$，追瞄准点（红线）为 $\arctan (0.8/6.0)\approx 7.6°$。

定位坐标按 0.25 量化，横向偏差因此可能凭空多出 0.25。$R=6$ 时它造成 $\arctan (0.25/6)\approx 2.4°$ 的航向误差，低于 6.6° 的转向死区；$R=2$ 时是 $\arctan (0.25/2)\approx 7.1°$，已经超过死区。

航向由 CalcTargetRotation 算出。从 $(x_1,y_1)$ 指向 $(x_2,y_2)$，记 $\Delta x=x_2-x_1$，$\Delta y=y_2-y_1$：

$atan2(a,b)$ 是点 $(b,a)$ 相对横轴正向的角度，范围 $(-\pi ,\pi ]$，乘 $180/\pi$ 换成度。底图坐标的 $y$ 轴朝下，往北是 $-y$ 方向，所以这里把往北的分量 $-\Delta y$ 放在 $b$ 的位置，往东的分量 $\Delta x$ 放在 $a$ 的位置，算出的是从正北顺时针量到目标方向的角度：正北 0°，正东 90°，正南 180°，正西 −90°，对 360 取模后为 270°。结果取整，所以日志里的走廊航向和目标航向都是整数。

前方转角

前方转角统计投影点之后 8.0 路程内的边。这 8.0 沿折线量：从投影点出发逐条往后数边，每数一条就从 8.0 里扣掉它的长度（当前边只扣投影点到末端那一段），扣完为止；8.0 在某条边中途用完时，这条边整条算进范围。范围内长度至少 0.75 的边参与比较。记其中第一条的航向为 $h_0$，结果是

$h_i$ 取遍范围内各条长边的航向，$\mathrm{wrap}$ 与拐角里相同。结果交给冲刺条件。短于 0.75 的边只扣长度：规划器的顶点按格放置，这么短的边方向只是量化噪声。

当前边从投影点到末端剩下不足 0.75 时，基准会落到下一条边上，脚下这个拐角就不计入。冲刺条件同时要求航向误差小于 25°，这种情况通常也不满足。

示意，蓝色是从投影点沿折线量出的 8.0。(a) 基准是投影点所在的当前边。长 0.5 的短边不比较；后面两条边与基准差 30° 和 75°，结果取 75°。8.0 在 75° 那条边的中途用完，这条边整条参与比较，再往后的边不看。(b) 投影点离当前边末端只剩 0.5，这一段不比较，基准落到往北的下一条边上，脚下 90° 的拐角不计入，结果是后一条边的 25°。

软重规划

每刻投影之后检查是否重新生成走廊：

• 横向偏差小于 1.25 时忽略进度倒退，同时把进度时钟刷成当前时间。
• 每个锚点最多 3 次，次数挂在走廊上，锚点或 zone 变化时清零。远离走廊可以跳过冷却，同样占用这 3 次；用完之后交给外层 3.5 s 起跳的卡死与恢复。
• 重规划后重新投影，打 INFO “NavRunController soft replan.”，字段为原因、本锚点第几次、重规划后的横向偏差、锚点下标。路线自己的点重建时按走廊来源的规则裁剪：裁不上就把角色插到折线开头，横向偏差为 0；起点换成垂足时，横向偏差等于角色到垂足的距离，不超过 2.5。A* 走廊从角色位置出发，横向偏差为 0。#6104 日志里软重规划共 24 次，23 次重规划后的横向偏差是 0；另一次起点裁到了垂足，为 2.34。
• 偏离走廊和进度倒退对停滞时钟的处理不同，见每刻顺序。

示意，相邻两帧相隔 0.2 s。走廊通向右边的锚点，三圈线是离当前走廊 1.25、2.2、4.0 的横向偏差，灰虚线是被换掉的旧走廊；下方是横向偏差随时间的变化，灰底是每次重规划后的 1.2 s 冷却。0.6 s 横向偏差 2.3，偏离走廊，第 1 次重规划，新走廊从角色位置出发，横向偏差回到 0。1.0 s 又到 2.28，还在冷却中，不重规划。1.2 s 超过 4.0，远离走廊，跳过冷却做第 2 次。1.4–2.0 s 角色停在原地，2.0 s 时已 0.8 s 没有进展，但横向偏差只有 0.10，不算进度倒退，进度时钟刷新。2.2 s 起角色横移到偏差 1.5 左右，2.8 s 又满 0.8 s 没有进展，这次横向偏差不小于 1.25，进度倒退，第 3 次。3.0 s、3.2 s 又先后偏离、远离走廊，3 次已用完，交给外层的卡死与恢复。

原因编号还有 AnchorChanged（1）和 ZoneChanged（2），它们走 invalidate 后重建，不算软重规划，日志里的 nav_run_replan_reason 只会出现 0、3、4。

有几种情况这一刻拿不到走廊航向：走廊建失败（处于 3000 ms 冷却）、投影丢失、投影落在窗口外且横向偏差超过 4.0。这些刻退回路点级的 route_heading。straight_to_anchor 在这些提前返回之前就已写出：路点级的退路看的是几个像素外的下一个路点，锚点却还在几十像素外，没有这个值，走廊断掉的这段时间里无进展 watchdog 会一直把角色读成已经到达。

转向

转向与推进顺序

走廊给出目标航向之后，TickNavigate 按下面的顺序转向和推进：

1. 目标航向：有走廊航向用走廊航向，否则用 route_heading。
2. 朝向角速度：本刻朝向和参考朝向之差，折算到每 100 ms。
3. 结清在途转角账：把上一刻以来朝向的实际变化从待转角里扣掉，过期的作废。
4. 航向误差 $e=\mathrm{wrap}(h^{\ast }-h)$，$h^{\ast }$ 是目标航向、$h$ 是当前朝向，交给 SteeringController::Update。
5. SetForwardState(true)，按住前进。
6. ApplySteering：按后端拆批发出，实际发出的量记入在途转角账。
7. 灵敏度检测记一刻。
8. 前进键闭环：按着前进却连续几刻没动就重发。
9. 延迟检测记一刻。
10. 提示点附近抑制冲刺；判断冲刺条件。

度与单位

控制器以度为单位工作，发给后端前换算成鼠标量或滑动像素。

• 桌面端：记窗口宽 $W$、高 $H$（像素），

  $$\text{一圈单位数}=\mathrm{round}(2.23006W),\text{偏航每度单位数}=\frac{\text{一圈单位数}}{360}$$

  1280 宽时一圈 2854，每度约 7.93。俯仰的可动行程是 180°，所以

  $$\text{俯仰每度单位数}=\frac{2.23006H}{180}$$

  取不到分辨率时退回工作分辨率的宽度。

• 2.23006 在 aa813aaf（03-10）中替换了原来固定的 5690/360，使转向量随分辨率变化。

• ADB：每度 3.0 像素。

• 灵敏度系数：乘在偏航和俯仰上。偏航从度到单位只有这一处换算，校正系数也只乘在这里和俯仰上。见灵敏度检测。

• 换算：转 $\Delta \theta$ 度发出的单位数

  $$n=\mathrm{round}(\Delta \theta \times \text{每度单位数}\times s)$$

  $s$ 是灵敏度系数，$n$ 为 0 时补成 ±1。

#6104 日志里 30° 对应 297 单位，7.4° 对应 73，和 1600 宽窗口的每度 9.91 吻合。

控制律

常量：死区 6.6°，前进中单刻上限 90°，原地上限 70°，Kp 1.0，可信角速度上限每 100 ms 60°，掉头锁定 150° 进、120° 出。

if (rate_magnitude > kHeadingRatePlausibleMaxDeg) {          // 60 / 100 ms
    LogDebug << "SteeringController glitch-suppressed." ...;
    return command;                                         // 本刻不转
}
if (std::abs(heading_error) < kTurnLatchExitDeg) {          // 120
    turn_latch_sign = 0;
}
else if (turn_latch_sign == 0 && std::abs(heading_error) >= kTurnLatchEnterDeg) {   // 150
    turn_latch_sign = heading_error >= 0.0 ? 1 : -1;
}
if (turn_latch_sign != 0) {
    heading_error = std::abs(heading_error) * turn_latch_sign;
}

const double pending = std::clamp(pending_turn_deg, std::min(0.0, heading_error), std::max(0.0, heading_error));
const double effective_error = heading_error - pending;
const double p_term = std::abs(effective_error) < kHeadingDeadband ? 0.0 : effective_error * kKp;
const double max_cmd = moving_forward ? kMovingMaxCmd : kTurningMaxCmd;
const double cmd = std::clamp(p_term, -max_cmd, max_cmd);
command.yaw_delta_deg = cmd;
command.issued = std::abs(cmd) >= 2.0;

执行顺序：毛刺抑制 → 掉头锁定 → 扣除在途 → 死区 → 比例 → 限幅。

扣除在途。已经发出、朝向读数还没体现的转角先从误差里减掉。游戏转完一条封顶的指令要好几刻，控制器却每刻都在算，每刻按原始误差下发，同一个转角会被发好几遍，过冲后再往回找，就是左右摆。扣除量夹在 0 和误差之间，剩下的部分和原误差同号，扣除只会让指令变小，指令方向保持不变。

死区只作用于比例项，用来压住直线上低于噪声的航向误差。真正的拐角误差很大，大角度转向不受死区影响。

上限。moving_forward 在 SetForwardState(true) 之前读取，所以刚停下之后的第一刻也按原地上限 70° 算。一份 #6097 之前的 PlayCover 日志里，起步第一刻就是 moving_forward=false、cmd=-70。

issued 要求 ≥ 2.0，这条从不起作用：Kp 为 1、死区 6.6，非零的指令绝对值都不小于 6.6。

四个罗盘取自 #6104 日志（Windows 桌面端，单笔上限 30°），每个是一刻：黑箭头是读到的朝向，绿线是目标方向，浅绿扇区是 ±6.6° 死区；从朝向开始先画在途（黄），再接本刻发出的量（蓝，白线分笔），灰色是本刻没补上、留给下一刻的部分。① 误差 −5.3° 落在死区里，不发。② 误差 −45.5°，前几刻已经发出、读数还没体现的 13.5° 先扣掉，只补 32°。③ 和 ④ 的误差都在 139° 左右：前进中发满 90°，原地转身只发 70°。

掉头锁定

误差接近 180° 时两侧一样远，一度的读数抖动就能让指令方向翻转 360°。#4839「近乎掉头的转向锁定方向,不再左右横跳」（cherry-pick 自 #4831）在误差达到 150° 时锁定方向，降到 120° 以下才解锁。锁定之后角色朝同一侧一直转到底；两侧都能转到目标，锁定哪一侧都对。

锁定判断用的是扣除在途之前的误差。锁定只改控制器内部的副本，冲刺条件读到的仍是原始误差。

#6104 日志里的一次掉头，桌面端单笔上限 30°。左图是这段时间的定位点，箭头是七个刻各自读到的朝向：前 6 刻位置挪动不到 1 像素，朝向从 190° 顺时针转到 348°；转完之后的第 7 刻已经往北走了 2 像素。右图每个罗盘是一刻的账：黑箭头是读到的朝向，绿线是目标方向，浅绿扇区是 ±6.6° 死区；从朝向开始顺时针先画在途（黄），再接本刻发出的量（蓝，白线分笔）。黄和蓝加起来最多走到绿线，这就是”在途夹在 0 和误差之间”的几何含义。前三刻误差在 150° 以上，锁定右转；第 4 刻误差降到 106°，解锁。各刻的数据：

误差 167° 进入锁定，3.710 那刻降到 106° 解锁。前两刻发出 160°，第二刻时朝向读数还一点没动，在途扣掉了 70°，指令只按剩下的部分算；之后读数追上来，在途逐刻消掉，只补了 7.4° 和 8° 两个零头。整个掉头约 1.1 s，最后误差 2°，没有过冲。

朝向角速度与毛刺抑制

朝向读数来自小地图箭头的识别，每刻一个。毛刺是这个读数序列里孤立的一帧错值：前后几刻都正常，中间一刻突然跳到很远的角度，下一刻又跳回来，画成随时间变化的曲线，像曲线上扎出来的一根刺。角色在两刻之间转不了那么多，这一帧反映的是识别读错，角色的实际朝向没变。拿它算误差，控制器会发出一条大转向，把本来对准的角色转歪，下一刻读数恢复后再转回来。判断依据是角速度：两次读数之间算出的转动快到角色做不到，就把这一刻当作毛刺，不按它转向，这就是毛刺抑制。

角速度 $\omega$ 的单位是每 100 ms 的度数（#3744「朝向角速度时间归一化」）：

$h$ 是本刻读到的朝向，$t$ 是本刻的时刻（ms）；$h_{\text{ref}}$ 是参考朝向，$t_{\text{ref}}$ 是记下它的时刻；$\mathrm{wrap}$ 与拐角里相同，把差换算到 $(-180°,180°]$。分母用实际经过的毫秒数，两刻隔 300 ms 时转了 30°，算出来是每 100 ms 10°，和每刻隔 100 ms、每刻转 10° 的结果一样。

参考值按下面的规则更新：

• $|\mathrm{wrap}(h-h_{\text{ref}})|\le 0.05°$：算作没转，$\omega =0$，参考值保留。静止时读数的微小抖动不算转动。
• 超过 0.05°：按上式算 $\omega$，再把参考值换成本刻的 $h$ 和 $t$。参考值保留了几刻，这几刻的转动就一起除以这几刻的总时长。
• 参考值记下之后已经过了 4 刻以上：$\omega$ 记 0，参考值照样换成本刻读数。时效按刻数计（#4809 起，替换了 #3744 的 400 ms）。参考值过期的含义是错过了几次观测机会，截图慢只会把这些机会拉长，次数不变；按墙钟时间设上限，恰好在最需要角速度的慢循环上把它丢掉。

示意序列，每刻 100 ms。左边罗盘：黑箭头是本刻读数，灰虚线是参考值，蓝弧是 $\Delta h=\mathrm{wrap}(h-h_{\text{ref}})$，浅灰短箭头是之前各刻的读数。右边是本刻的计算，下面的条是 $|\omega |$，竖线是上限 60。第 1、2 刻读数只抖了 0.03°、0.04°，参考值留在第 0 刻。第 3 刻转到 40°，$\Delta h$ 相对第 0 刻算，是 30°，间隔 3 刻 = 300 ms，$\omega =10$。第 4 刻转了 30°，$\omega =30$。第 5 刻是一帧毛刺，读数错成 235°，$\Delta h=165°$，$\omega =165$ 超过 60，这一刻不发转向；参考值照规则换成了这个错的读数，第 6 刻读数回到 95° 时，相对 235° 又算出 $\Delta h=-140°$，再抑制一刻。第 7 刻恢复正常。一帧读错会让转向停两刻。

#4939 删掉阻尼项之后，角速度只用于毛刺抑制：$|\omega |>60$（每 100 ms 60°，即 600°/s）视为读数毛刺，SteeringController::Update 一进来就返回空指令，这一刻不发转向，掉头锁定也不更新，只打 “SteeringController glitch-suppressed.”。在途转角账在调用控制器之前结算，照常进行。

#6104 日志 2621 个转向刻里 $\omega \ne 0$ 的 1232 刻，纵轴取对数。中位数 2.7，99% 在 36.2 以下。最大的 55.2 出现在一次起步掉头：前两刻共发出 160°（70 + 90），第 4 到第 5 刻之间读数在 140 ms 里转了 77.3°，折合 552°/s。整份日志没有一刻 $|\omega |$ 超过 60，毛刺抑制一次也没触发；实测最快的转动离上限还差 4.8。

末端纠正收尾之后清零角速度和在途转角账。收尾里的转镜头绕开了转向控制器，在途转角账认不出这些转动，清掉重新起算。

批次

ApplySteering 先做几项检查：角度为 0、处于静默期、绝对值小于后端的最小发送量、未到最小间隔，任一成立就不发。随后按单笔上限 $c$ 拆批。控制器给的本刻指令记作 $\theta$，批次数：

$\lceil x\rceil$ 是向上取整，$|\theta |$ 刚好是 $c$ 的整数倍时不多出一批。有最小发送间隔的后端（Linux，16 ms）再取 $n\leftarrow \max \left(1,\min \left(n,\lfloor \Delta t/16\rfloor \right)\right)$，$\Delta t$ 是这一刻距上一刻的毫秒数；一刻 150 ms 时这一项是 9，3 批的上限先起作用。

本刻总量夹到 $\mathrm{clamp}(\theta ,-nc,nc)$，然后逐批发出：每批发 $\mathrm{clamp}(\text{剩余},-c,c)$，剩余小于后端的最小发送量、或某批被拒时停止。各批的发送耗时求和，记为延迟检测的 Steer 阶段，被拒的那批也算在内。漏算的部分会落到 Other 阶段头上。

四个罗盘各是一刻的拆批：黑箭头是当前朝向，绿线是指令要转到的方向，蓝弧是本刻发出的量（白线分批），浅灰弧是本刻发不完、留给下一刻的部分。① 桌面 90°：$\lceil 90/30\rceil =3$，三批各 30°。② 桌面 40°：$\lceil 40/30\rceil =2$，第一批 30°，第二批发剩下的 10°。③ Linux 90°：$\lceil 90/18\rceil =5$ 夹到 3，本刻最多 $3\times 18=54°$，剩 36°；这 36° 不记任何账，下一刻控制器按新的误差重新算。④ ADB 90°：单笔上限就是 90°，一批发完。

#5285「转向批次按请求角度分配以提高灵活性」之前，批次数按本刻时长分配（当时是 刻间隔 / 100）。一次大角度掉头一刻只发一批，要拖约 1.7 s，角色一直在走，转身扫出一段 3.5 m 的弧，撞上旁边的东西。现在批次按指令要求的角度分配，单刻上限仍在，每一刻都还是一个观测点：185° 的转向分三刻发成 90 + 90 + 5。

90 + 90 + 5 是跨三刻的序列。控制器单刻指令本身不超过 90°，各后端单刻实际能发的量：

最后的 5° 落在 6.6° 死区内，通常不会单独发出。上限 3 批让每一刻都还是一个观测点：某一帧朝向读错，最多多转一刻的量，下一次定位就能纠正。

在途转角账

每刻实际发出的转向记一笔在途转角账。账上记着已经发出、朝向读数还没体现的度数，以及起算的参考朝向。一次转向要几刻才完成，控制器却每刻重新决策，没有这笔累计，同一个误差会在落地之前被反复下发。

每刻结算：

const bool drops_turn_sends = motion_controller_->SteeringDropsTurnSends();
if (drops_turn_sends) {
    std::erase_if(steering_rate.in_flight, [&](const SteeringRateState::InFlightTurn& turn) {
        return std::chrono::duration_cast<std::chrono::milliseconds>(now - turn.sent_at).count() >= pending_lifetime_ms(turn.delta_deg);
    });
    if (steering_rate.pending_turn_deg != 0.0) {
        if (steering_rate.in_flight.empty()) {
            steering_rate.pending_turn_deg = 0.0;
        }
        else {
            const double landed = NaviMath::NormalizeAngle(current_heading - steering_rate.pending_ref_heading_deg);
            const double owed = std::abs(steering_rate.pending_turn_deg);
            double negative_sent_deg = 0.0;
            double positive_sent_deg = 0.0;
            for (const SteeringRateState::InFlightTurn& turn : steering_rate.in_flight) {
                (turn.delta_deg < 0.0 ? negative_sent_deg : positive_sent_deg) += turn.delta_deg;
            }
            steering_rate.pending_turn_deg =
                std::clamp(std::clamp(steering_rate.pending_turn_deg - landed, -owed, owed), negative_sent_deg, positive_sent_deg);
        }
    }
}
else if (steering_rate.pending_turn_deg != 0.0) {
    const int64_t pending_age_ms = std::chrono::duration_cast<std::chrono::milliseconds>(now - steering_rate.cmd_at).count();
    if (pending_age_ms >= pending_lifetime_ms(steering_rate.cmd_delta_deg)) {
        steering_rate.pending_turn_deg = 0.0;
    }
    else {
        const double landed = NaviMath::NormalizeAngle(current_heading - steering_rate.pending_ref_heading_deg);
        const double owed = std::abs(steering_rate.pending_turn_deg);
        steering_rate.pending_turn_deg = std::clamp(steering_rate.pending_turn_deg - landed, -owed, owed);
    }
}

记账上的待转角为 $p$，上一刻读到的朝向为 $h_{\text{prev}}$。两条分支都先算两刻之间朝向实际转过的量，再从账上扣掉：

结算完参考朝向换成本刻读数，所以 $\Delta h$ 总是相邻两刻之间的变化。夹到 $\pm |p|$ 让 $|p|$ 只减不增：朝待转方向转了多少就扣多少；往反方向转时 $p-\Delta h$ 的绝对值变大，被夹回 $|p|$，账不变；转过头时 $p-\Delta h$ 变号，最多到 $-|p|$。

控制器从误差 $e$ 里扣掉 $\mathrm{clamp}(p,\min (0,e),\max (0,e))$ 再算指令（见控制律）。本刻实际发出 $\delta$ 之后记账：

两条分支的区别在作废规则：

• drops_turn_sends 只有 ADB 后端为真，ADB 的一次滑动可能被游戏整笔吞掉。ADB 每刻发出的量单独排一笔 $({\delta }_j,t_j)$，$t_j$ 是这笔的发送时刻；每笔按自己的寿命判断，$t-t_j\ge T({\delta }_j)$ 就移出队列，队列空了 $p$ 直接清零。被吞掉的一笔到了自己的寿命就过期，后面再往哪边发什么都不影响它。扣完 $\Delta h$ 之后再按方向夹一次：

  $$p\leftarrow \mathrm{clamp}(p,S^{-},S^{+}),S^{-}=\sum _{{\delta }_j<0}{\delta }_j,S^{+}=\sum _{{\delta }_j>0}{\delta }_j$$

  $S^{-}$ 是队列里反向各笔之和，$S^{+}$ 是正向各笔之和，$p$ 不会超出队列里还没过期的各笔能凑出的范围。

• ADB 的发送时刻在调用 ApplySteering 之前才取，寿命从真正发送的时刻算起。同一刻里前面可能做过重规划，从这一刻的开头算的话，这段耗时就可能超过一整个寿命。

• 桌面和 Linux 只有一个时钟，每次发送都把它重置为这一刻的开头，寿命按最近一次发出的 $\delta$ 算；到期时整笔 $p$ 一起作废。

一笔的寿命：

$c$ 是后端的单笔上限。600 ms 盖住最坏的截图到定位滞后加一笔的偏航时间，320°/s 是实机测得的单条指令偏航速度。一刻发了几批时转得更远，超出第一笔的部分按这个速度加时间。过了寿命还没兑现，就当这次拖动被游戏吞掉，作废待转角；继续挂着会一直压住转向，等一个不会来的转动。

桌面端一刻转 90° 时寿命 787.5 ms，Linux 一刻最多 54° 时 712.5 ms，ADB 一刻最多 90° 等于单笔上限，恒为 600 ms，各后端的曲线见输入后端的右图。走路时转速约减半，寿命加倍；按慢跑算的寿命会在转身中途到期，控制环又把这个转角发一遍。

演变：#4939（08-11）固定 600 ms → #5027（08-16）走路加倍 → #5285（08-27）按 320°/s 加长 → #6097（09-29）每笔单独排队、从发送时刻起算 → #6142（10-01）逐笔排队只留给 ADB，正反两向分别夹；桌面和 Linux 回到单一时钟。#6097 之前只有一个时钟，到期时整笔待转角一起作废，每次新发送还会刷新这个时钟。#4939 引入时按实机测得的约 100°/s 偏航速度估算，一笔封顶指令约 300 ms 落地，寿命取它的两倍。

旧版单一时钟的问题在一份 #6097 之前的 PlayCover 日志里能看到（ADB 后端，单笔 20°，每度 5.0）：

上表第 2 到 7 刻逐刻回放，按当时的规则（单笔 20°，单一时钟）重算。左边罗盘：黑箭头是本刻朝向，灰箭头是上一刻朝向，紫弧是两刻之间实际转过的 $\Delta h$，绿线和浅绿扇区是目标方向 ± 死区，黄弧是账上的 $p$，蓝弧是本刻发出的量（白线分笔）。右边按一刻里的顺序列出 ① 结算、② 控制、③ 发出与记账；底部的条是结算时距最近一次发送的时间，竖线是寿命 $T$。

• 第 2 刻：账上为空。误差 −105.4°，还没按前进，原地上限 70°，发 3 × −20。$p=-60$，寿命 $T(-60)=600+40/320\times 1000=725$ ms。
• 第 3 刻：距上次发送 1278 ms，超过 725 ms，$p$ 整笔作废。控制器看到的误差还是 −102.5°，又发 −60。
• 第 4 刻：距上次发送 697 ms，没过期。朝向转了 $\Delta h=-37.8°$，$p=-60+37.8=-22.2$。误差 −57.7° 扣掉 −22.2 剩 −35.5，发 −20、−15.5，$p=-22.2+(-35.5)=-57.7$，时钟重置，寿命 648.6 ms。
• 第 5 刻：又转了 −54.7°，$p$ 剩 −3.0。误差 −4.0 扣掉 −3.0 只剩 −1.0，在死区里，不发。
• 第 6 刻：距第 4 刻 949 ms，超过 648.6 ms，剩下的 −3.0 作废。朝向已经转过头，误差 +19.8°，反向发 +19.8。
• 第 7 刻：朝向往反方向动了 −1.5°，$p-\Delta h=21.3$ 被夹回 $|p|=19.8$，账不增加。误差 17.3° 小于 $p$，扣除量夹到 17.3，剩 0，不发。

第 3 刻的待转角作废是按日志数值反推的：间隔 1278 ms 超过当时的寿命（600 + 40 / 320 × 1000 = 725 ms），−60 的待转角整笔清零，于是同一个转角又发了一遍，两刻后过冲 20°。这里寿命按设计起了作用：第 2 刻三笔共 −60，1278 ms 里朝向只动了 −12.9，当作被吞掉处理是对的。少兑现的那部分和 #6097 标题里的”增益、丢步”对得上，对应的改动是单笔 20° → 90°、每度 5.0 → 3.0、两端停留 8 / 30 → 100 / 100 ms。

#6097 的在途记账改的是另一种情形。旧版只有一个时钟，每次新发送都会刷新它，被吞掉的一笔就跟着后面的发送一直挂在账上，压住之后的转向。改成每笔单独排队之后，被吞掉的那笔到了自己的寿命就过期，后面再发什么都影响不到它。按每笔各自的时钟算，上表第 3 刻的结果一样：第 2 刻那三笔各自也已经超过 725 ms。

#6142「在途转向逐笔寿命只用于 ADB」做了两处收窄。一是逐笔排队只留给会吞掉滑动的 ADB，桌面和 Linux 的转向指令不会丢，回到每次发送都刷新的单一时钟。二是 ADB 的上下界按方向分开算。#6097 的版本把队列里各笔相加，再夹到 0 和这个和之间。队列里有一笔 +40 还没落地、又发出一笔 −30 时，和是 +10，范围缩成 [0, +10]；等 +40 落地，待转角算出来是 −10，被夹成 0，刚发出的反向转动从待转角里消失了，控制环会把这个反向转角再发一遍。按方向分开时范围是 [−30, +40]，−10 保留下来。

左列是 #6097 的夹法，右列是 #6142。黄弧是队列里的两笔，−30 接在 +40 后面画；黑弧是账上的 $p$；浅蓝扇区是 $p$ 允许的范围；紫弧是 +40 兑现的 $\Delta h$。上排是发出 −30 的那一刻，两版的 $p$ 都是 $+40+(-30)=+10$，#6097 的范围是 $[\min (0,\sum {\delta }_j),\max (0,\sum {\delta }_j)]=[0,+10]$，#6142 是 $[S^{-},S^{+}]=[-30,+40]$。下排是 +40 兑现之后：两版都先算 $\mathrm{clamp}(10-40,-10,10)=-10$，实际还没执行的是那笔 −30，按 $\pm |p|$ 夹完账上留下 −10。#6097 再夹到 $[0,+10]$ 得 0，−30 从账上消失，控制器会把这段反向转角再发一次；#6142 的范围包含 −10，保留下来。+40 那笔虽然已经兑现，还没到寿命，仍在队列里，所以下排的上界还是 +40。

参数演变

控制参数逐提交核对的变化：

Kp 的轨迹是 0.68 → 0.3 → 0.6 → 0.45 → 1.0。#4939 把已发出未兑现的转角直接从误差里扣掉，标题称阻尼项冗余并删除，Kp 同时升到 1.0。

前进键闭环

前进键只在按下的那一刻发一次按下事件，这一下被吞掉的话，角色朝向正确却站着不动，要等几秒后停滞时钟到点、恢复阶梯接手才会发现。前进键闭环每刻检查一次：

• 本刻有没有进展：$d=|P-P_{\text{prev}}|$ 是本刻位置到上一刻位置的距离（地图像素），$d>0.25$ 算动了。动了、本刻发出了转向、或者本来就没按前进，三者有一个成立就算有进展。原地转身的刻在发转向，刹车到点时没按前进，都算有进展，不会触发重发。转向只看本刻发出的量，前几刻发出、本刻才兑现的转动不算进展。
• 原地计数 $m$：有进展时清零，没进展加一。恢复阶梯在跑时也清零，那时移动键归恢复管。
• $m\ge 3$ 时重发前进键，WARN “Forward hold produced no motion; re-sending it.”，补发次数 $k$ 加一，$m$ 清零重新数。
• $k$ 只在有进展时清零。

按刻数计，截图慢时等待不会被拉长；3 刻已经超过单次丢帧或刹车稳定所需的时间。走路时窗口放宽到 6 刻。走路时一刻的位移低于定位量化步 0.25，直线行走也会读成没动；阈值负责过滤量化噪声，所以放宽窗口，阈值保持不变。

$k\ge 2$ 时提前放恢复阶梯进来，不必等停滞时钟到 3500 ms。第一次重发对应按键被吞的情况，值得再试；第二次之后角色仍然纹丝不动，说明按键已经送达、角色被挡住了，再等停滞时钟只会让角色多顶几秒墙。恢复接手后 $k$ 保留：清掉的话，下一刻恢复条件就不成立了，恢复阶梯第一步还没走完就会被关掉。

#6104 日志 06:41 那一趟起步的第 3 到 14 刻（桌面端），之后卡在 (912.12, 263.02) 的就是这一段，见卡死与恢复。左边是地图俯视，单位是地图像素：空心圈是上一刻的位置，虚线圆是它周围半径 0.25 的范围，实心点是本刻位置（动了画绿色，没动画红色），黑箭头是朝向，绿线是目标方向。右边是本刻的判定和两个计数，底部的条是停滞时钟。

• 第 3 刻发了 13.9° 转向，算有进展。第 4、5 刻朝向还在转，那是前几刻发出的转向在兑现；本刻没发、位置没动，原地计数数到 2。
• 第 6 刻挪了 0.83 像素，又发了 −13.3°，两个计数清零；第 7 刻发了 −8.4°，仍然清零。
• 第 8 到 10 刻没动也没发，第 10 刻计数到 3，重发前进键，补发次数 1。
• 第 11 到 13 刻还是没动，第 13 刻第二次重发，补发次数 2。
• 第 14 刻开头检查恢复条件，补发次数已到 2，恢复阶梯接手，先起跳一次。这时停滞时钟才 1.2 s 左右，按 3500 ms 的门槛还要再等约 2.3 s。

#6104 日志里前进键重发共 27 次。

冲刺与走路

冲刺条件

const bool heading_aligned_for_sprint = std::abs(heading_error) < kAutoSprintMaxHeadingErrorDeg;          // 25
const bool corridor_turn_calm =
    !nav_run_result.has_corridor_heading || nav_run_result.upcoming_turn_deg < kAutoSprintMaxUpcomingTurnDeg; // 40
const double sprint_remaining = nav_run_result.has_corridor_heading && std::isfinite(nav_run_result.remaining_to_anchor)
                                    ? nav_run_result.remaining_to_anchor : route.along_track_remaining;
const bool has_strict_arrival_braking_room =
    !target_requires_strict_arrival || route.waypoint_distance > arrival_distance + kStrictArrivalSprintBrakeDistance; // 6.0

冲刺需要同时满足：

这组条件只在角色已经对准走廊、扫描范围内没有急弯时允许冲刺。条件里没有净空项：桥上的净空接近 0，带净空项会把冲刺完全锁死；朝向对齐和前方转角两条已经能防止冲进拐角。

前方是严判点时，只要求留出制动余量：在判定圈 + 6.0 之外照常冲刺，长直线跑向严判点时仍能冲刺，到余量处再刹住。

条件一直满足时每 1.5 s 重按一次。每次冲刺：

1. 处于抑制状态时直接返回。
2. 开启 ADB 的 60 ms 静默期，其他后端没有静默期。
3. 调后端的冲刺输入：桌面右键按 30 ms，Linux 按 Shift 30 ms，ADB 点按冲刺键 50 ms。
4. 游戏会在冲刺时自己退出走路，所以清掉走路状态，日志 “Walk mode cleared by sprint (the game leaves walking on its own).”。
5. INFO “Sprint state armed.”。

每刻的判定结果（allow_sprint）打一行 DEBUG，便于事后对照：

TickNavigate sprint gate. [allow_sprint=false] [heading_aligned_for_sprint=false] [corridor_turn_calm=true] [startup_grace_elapsed=false] [has_strict_arrival_braking_room=true] [sprint_remaining=79.008362] [param_.sprint_threshold=16.000000]

这一行来自起步第一刻：误差 105°，起步未满 3 s，两条都没过。

左图取自 #6104 日志里的一趟，从右侧起点出发，到左下角结束。每一小段轨迹按这一刻被哪条条件拦住上色，几条同时不满足时取图例里靠前的那条。前 3 s 是起步宽限；每个拐角前约 8.0 处扫描段碰到拐角，条件不再满足，过了拐角才恢复；最后 16.0 剩余距离不够，不再冲刺。直线段上大多是浅蓝：几何条件都满足，在等 1.5 s 冷却。冷却在路点推进时清零，14 次冲刺里有 9 次发在路点推进的那一刻。“冷却”一项由允许冲刺的时刻和路点推进时刻反推，日志里没有单独输出。右图是单刻判定的几何：朝向在 ±25° 扇区内，沿走廊往前 8.0 的扫描段没有 ≥ 40° 的拐角，离锚点的走廊距离大于 16.0，锚点是严判点时还要在判定圈 + 6.0 之外。

提示点附近

离最近的采集、交互点，或前方还没经过的 DIG、滑索点不超过 8.0 时进入冲刺抑制；已经站上滑索架时不再算上索点。进入时若正在冲刺且按着前进，松开前进键 60 ms 再按下，把冲刺打断，INFO “Sprint cancelled near collect point (dropped to walking speed).”。这一机制来自 #3690「异步检测 COLLECT」。路线上没有需要减速接近的点时，这段逻辑完全不碰冲刺。

走路

#5027「新增游戏走路模式切换」加入走路。走路时速度和转速都减半，用于接近需要停准的点。

触发条件，任一即可：

• WaitFind phase 一律走路。FIND 的接近段移动连续，修正只跟着每刻的识别框，跑起来容易冲过头。
• 当前点有 walk_approach 特性，或是要做末端纠正的点，走路接近让滑行距离和到点后走回去的距离都减半。

走路开关在每刻最开头、按 phase 分派之前更新。任何 phase、任何提前返回的分支都先经过这一步，条件不再成立时，下一刻就会关掉走路。

步行带的进带与退带：

在这些点附近走路，交互提示能停留足够长的时间供识别和按键。进出分开做迟滞，因为每次按键都会翻转游戏里的走路状态。滑索的步行带比普通提示点大：步行带太小时，刚切换走路的下一帧就可能出现上索提示，角色立刻停下。DIG 在 2.25 处验收，普通 3.0 的步行带只留 0.75 用来减速，所以 DIG 提前到 5.0 开始走路，挖掘的验收位置保持 2.25。

DIG 单独按到 DIG 点的距离判断：更近的采集点可能还在自己的步行带外，稍远、但已经进入更大步行带的挖掘点照样要走路。跨过进带或退带时打 INFO “Walk mode boundary crossed.”。

阻断条件，任一成立就切回慢跑：

• 不在 Navigate phase；
• 定位无效；
• 附近没有目标点；
• 正在恢复（恢复阶梯或跨层逃逸）；
• 起步位移未确认，且该点没有 walk_at_startup 特性。连续挖掘会重置起步确认，DIG 带这个特性，短腿从起步就走路；等确认位移再切换时，人可能已经进了到达圈。

末端纠正带 settle_walking 特性的点进圈后也请求走路，收尾后切回慢跑。走路换来的是接近段和收尾的精度，到点就还回去，跳跃、冲刺这些动作照旧在慢跑态下执行。

几个带之间的关系由 static_assert 锁住：各类进带小于退带；步行带小于冲刺抑制带 8.0；提示触发带 3.0 小于滑索进带 5.0；DIG 进带大于严判前视 2.0 + 0.25。

左图是 #6104 日志里的一次滑索接近，三道圈以滑索站位点为圆心。角色沿走廊一路按冲刺；进 8.0 的那一刻（离站位点 7.62）松前进键打断冲刺；进 5.0 的那一刻（4.19）按走路键；走到 2.08 起跳上索，进入滑索流程时走路状态一并释放。圆点都画在触发那一刻所用的定位上。右图是迟滞：进带在内圈，退带在外圈，人在两圈之间的环里来回晃时保持上一刻的状态，不按键。DIG 的两道圈和滑索相同；采集、交互点的圈是 3.0 / 4.5，画在判定圈的图里。

走路状态是进程级的全局变量。上一轮遗留的走路状态会在下一轮开始时恢复成慢跑，WARN “Walk mode belief survived the previous run; restoring jogging before navigating.”。走路时速度和转速都减半，在途转角账寿命和前进键重发窗口都加倍。

桌面端按 Ctrl 切换；ADB 由 #6068「ADB 摇杆轻推走路模式」实现，摇杆只推到半径的 0.25。

输入后端

选择

控制器类型为 adb、playcover、native_android 时用 ADB 后端，linux 用 Linux 后端，其余用桌面后端。

三个后端都支持边走边转。冲刺会让游戏退出走路，ADB 冲刺之后把摇杆推回满行程。ADB 的其他按钮：跳 (1166, 475)，攻击 (1030, 551)，交互 (1080, 390)，滑索上 (1099, 526)，滑索下 (1166, 411)，各用独立的触点编号。

平台支持的来源：#1999（ADB、PlayCover）、#2367「支持后台寻路」、#5114（Linux 控制器）、#5451「适配 PlayCover 多指触控」。

ADB 视角滑动

ADB 的一次转向是一次单指滑动，以 1280 × 720 为坐标系：

• 起点中心 (640, 264)，即横向居中、纵向比屏幕中心高 96。每次滑动横向最多 270 像素，纵向按边距 32 限在上 232、下 423 以内；超出的部分拆成多次滑动依次发出，任一次失败，这次转向返回失败（#6142）。
• 以中心横向对称起落：起点 = 中心 − 位移 / 2，终点 = 起点 + 位移。这样滑动万一被当成点击，落点也离屏幕中心最近，碰不到两侧的任务追踪和按钮。
• 横向 270 的上限也来自对称起落：位移越长，按下点越靠左，过长时按下点会落进左侧的摇杆区域，那一次拖动推动的是摇杆，镜头保持不动。270 = 90° × 3.0，正好是灵敏度系数为 1 时一刻的最大转角，按下点最左在 x = 505。
• 每次滑动的时序：按下，停 100 ms；分 6 步移动，步间停 10 ms，最后一步之后不停；停 100 ms；抬起。睡眠合计 250 ms，另有 8 次控制器往返（按下、6 次移动、抬起）。

两端各停 100 ms：游戏逐帧采样触点，与按下或抬起同一帧的位移会整步丢失，两端的停留要盖过负载高时的一帧。

左图是 #6097 前后一次滑动的时序。旧版两端停 8 ms 和 30 ms，睡眠合计 88 ms，那份 PlayCover 日志里实测每笔 124 到 176 ms，往返开销约 36 到 88 ms。按同样的开销推算，新版每笔约 290 到 340 ms，这个数没有实测。右图是一刻发出的总转角对应的在途寿命，实线为慢跑，虚线为走路。

#6097 把单笔上限从 20° 放到 90°，每度从 5.0 改到 3.0。旧版一刻最多 3 × 20° = 60°，新版一刻就能发 90°，灵敏度系数不超过 1 时只要一次滑动；两端停留加长到 100 ms，对应标题里的”丢步”。

两个边界情况：

• 配置里的 swipe_duration_ms = 70 只在构造时赋值、出现在初始化日志里，滑动逻辑不读它。
• 90° × 3.0 = 270 像素，灵敏度系数大于 1 时，一刻的 90° 要拆成 2 到 3 次滑动。系数取上限 2.5 时是 675 像素，拆成 270 + 270 + 135，光睡眠就有 750 ms。#6142 之前横向不拆，系数超过 607 / 270 ≈ 2.25 时一次滑动会被屏幕边界截断，上报给灵敏度估计的却是截断前的量；现在整量发出，上报的与实发的一致。

ADB 摇杆

虚拟摇杆原点 (198, 552)，半径 72。按下时在原点按下，停 16 ms，再分 4 步每步 16 ms 拖到目标点，共约 80 ms。走路时只推半径的 0.25，即 18 像素，斜向再除以 √2；切换走路时若触点按着，立即重新拖到新半径。释放后停 max(延时, 32) ms。

静默期

ADB 在移动指令之后 60 ms 内不发转向：摇杆状态刚变时，游戏还没受理视角拖动，这段时间里的转向会被吞掉。动作真正改变（或强制设置）时开启，冲刺时也开启，原地停住时清除。静默期里 ApplySteering 返回未发出，所以不记在途转角账。FIND 的步进间隔必须长于静默期，由 static_assert 锁住。

延迟与灵敏度

每刻耗时

每刻在工作做完之后固定休眠 33 ms，周期是本刻工作耗时加 33 ms。刻间隔按”本刻开始到上刻开始”计。

两份日志的累计分布。左为 macOS 上的 PlayCover，1132 刻：定位本身中位 35 ms，截图加定位 124 ms，刻间隔 200 ms。右为 #6104 日志（Windows），2621 刻：定位 84 ms，截图加定位 141 ms，刻间隔 186 ms。两边的刻间隔都远长于 33 ms 的休眠，大头在截图和定位上。

延迟检测

#4958（08-12）「新增寻路延迟异常提示」在机器过慢时提示用户。参数：

慢刻比例。刻间隔超过 280 ms 的刻叫慢刻。一个窗里有 $n$ 刻，其中 $x$ 刻是慢刻，样本比例是

直接拿 $\hat{p}>0.5$ 判慢不可靠，刻数少时运气成分很大：假设这台机器真实的慢刻比例只有 40%，8 刻里碰巧出现 5 刻以上慢刻的概率仍有 17%，这时 $\hat{p}=62.5\%$。检测器要回答的是：根据这 $n$ 刻，真实比例 $p$ 最低可能是多少。连这个最低值都过半，才算有把握说过半的刻都超线。

Wilson 下界。真实比例为 $p$ 时，每刻是不是慢刻相当于抛一枚正面概率为 $p$ 的硬币，$x$ 服从二项分布。刻数不太少时，$\hat{p}$ 近似服从正态分布，均值是 $p$，标准差是 $\sqrt{p(1-p)/n}$。一个候选的 $p$ 如果离观测到的 $\hat{p}$ 不超过 $z$ 个标准差，就认为它和观测相容：

两边平方，整理成关于 $p$ 的二次不等式：

满足它的 $p$ 落在两个根之间，这一段就是 Wilson 得分区间⁠^[3]。较小的根是下界：

$z=2.326$ 是标准正态分布单侧 1% 的分位点，真实比例低于 $L$ 的可能性约为 1%。$L>0.5$ 的窗记为慢窗。

教科书上更常见的 Wald 区间 $\hat{p}\pm z\sqrt{\hat{p}(1-\hat{p})/n}$ 把标准差里的 $p$ 直接换成 $\hat{p}$。8 刻全慢时 $\hat{p}=1$，Wald 区间宽度为 0，等于 8 刻就断定比例恰好是 100%。Wilson 区间的标准差按候选的 $p$ 计算，同样 8 刻全慢，下界是 0.60，刻数少时区间自然变宽。

代码就是上面 $L$ 的公式，centre 是分子的前两项，margin 是根号那一项：

double WilsonLowerBound(int64_t hits, int64_t total, double z)
{
    if (total <= 0) {
        return 0.0;
    }
    const double n = static_cast<double>(total);
    const double p = static_cast<double>(hits) / n;
    const double z2 = z * z;
    const double centre = p + z2 / (2.0 * n);
    const double margin = z * std::sqrt(p * (1.0 - p) / n + z2 / (4.0 * n * n));
    return std::max(0.0, (centre - margin) / (1.0 + z2 / n));
}

换算成慢刻数。判据 $L>0.5$ 可以化成只含 $x$ 的不等式。$L>0.5$ 说明 0.5 落在区间下方：0.5 和观测不相容，并且 $\hat{p}>0.5$。把 $p=0.5$ 代进相容条件再取反：

右边有直观的含义：每刻慢不慢各占一半时，$x$ 的均值是 $n/2$，标准差是 $\sqrt{n\times 0.5\times 0.5}=\sqrt{n}/2$，门槛就是均值往上 $z$ 个标准差。各刻数下的门槛：

假设机器处在临界状态，每刻慢的概率恰好 50%，一窗里的慢刻数服从上图的二项分布。虚线是上表的门槛，红色柱是会被判成慢窗的情形，14 刻的窗合计 0.65%，45 刻的窗合计 0.80%，都在 1% 以内。门槛超出一半的部分 $1.163\sqrt{n}$ 比 $n/2$ 增长得慢，所以刻数越多，所需比例越接近一半。

健康机器 110 ms 一刻，5 s 约 45 刻，要 31 刻超线；慢到 350 ms 一刻时约 14 刻，要 12 刻超线。实际触发点因此比 280 ms 高出约 100 ms。

窗口与计数：

• 只收刻序号与上一刻连续的样本。刻序号断开说明中间有刻走了跳跃、攀爬、换层、丢定位这些分支，间隔里混着它们的耗时。只有走完整个常规导航刻的才计入，语义节点、恢复、丢定位的刻在前面就返回了。
• 窗口从第一个计入的样本开始计时，满 5 s 且至少 8 刻才结算。
• 出现正常窗时计数清零，历史一起清空，提示里报的中位数因此正好来自判慢所依据的那几窗。
• 连续 3 个慢窗后报一次，之后不再判。日志 “Navigation tick latency looks abnormal.”，带刻间隔中位数、各阶段中位数、慢刻比例和样本数；同时发通知 navigation.latency_slow。

连续慢窗数 $c$ 每结算一窗更新一次，到 3 时报告：

各窗的刻互不重叠，把各窗看作相互独立来估算，临界状态的机器连续 3 窗都被判慢的概率不超过 $0.01^3=10^{-6}$。

各阶段：Screencap、ImagePrep、Locate 来自定位，Steer 是转向各批发送耗时之和，Other = 本刻计算耗时 − 截图定位 − 转向。判定只看整刻间隔，各阶段耗时只用来说明时间花在哪。

左图黑色阶梯是各刻数下判慢所需的最低慢刻比例，红色区域为慢窗。散点是两份日志按检测器规则切出的窗：#6104 日志 106 窗，一个慢窗都没有；PlayCover 日志 56 窗，11 个判慢，都在左上角刻数很少的窗里，最多连着 2 个，所以两份日志都没有报。右图是真实超线比例固定时，Wilson 下界随刻数的变化：比例 75% 时要 20 刻左右才过线，60% 时 60 刻也过不了。

#6097 之后 ADB 一次转向滑动约 0.3 s，发了转向的刻单靠 Steer 阶段就接近 280 ms。一段路大部分刻都在转向时，ADB 上可能误报。检测器写于 #6097 之前，当时一次滑动约 0.15 s。这一条是推断，没有日志验证。

灵敏度检测

游戏的视角灵敏度是玩家设置，同一条指令在不同玩家那里转出不同的角度。检测器比对发出的转向和实测的朝向变化，估计实际转到了指令的多少倍。

两版模型：

• #4969（08-12）「新增转向灵敏度异常提示」：6 刻滞后，按 12 s 真实时间切窗、每窗累计指令至少 150°，过半窗口倍率超过 1.2 时报中位数。这一版只报转过头：转不到位有太多正常原因，指令被吞、贴墙转不动、掉帧都会让倍率偏低，从倍率上分不出是哪种。
• #5583（09-08）「灵敏度判决落地后自动缩放转向量」：整体重写为 12 刻分布滞后的岭回归⁠^[4]，加入偏慢判定，判决成立后自动缩放转向量。下面描述的是这一版。

模型。记号：第 $t$ 刻发出的转向指令为 $u_t$（度），第 $t$ 刻读到的朝向为 $h_t$，两刻之间的朝向变化为 $y_t=\mathrm{wrap}(h_t-h_{t-1})$。

一条指令不会在下一刻就转完：游戏要过几帧才把视角转过去，截图本身也有延迟，转量摊在后面几刻里。设指令发出后的第 $k$ 刻兑现它的 $g_k$ 倍，本刻看到的朝向变化就是之前各条指令在这一刻兑现的份额之和：

${\epsilon }_t$ 是识别误差之类的噪声，$g_k$ 是第 $k$ 阶滞后的增益，这种模型叫分布滞后模型。一条指令 $u$ 前后总共兑现 ${\sum }_k{g}_{k}u$，所以倍率是

灵敏度正常时 $r=1$。逐刻拿 $y_t$ 除以上一刻的指令，量到的只是 $g_1$，#6104 日志里 $g_1$ 只有 0.03；12 阶一起拟合，才能把摊开的转量加回来。

每记一行，就是记下 ${\mathbf{x}}_t=(u_{t-1},u_{t-2},\dots ,u_{t-12})$ 和 $y_t$。$n$ 行叠起来写成矩阵：

$X$ 有 $n$ 行 12 列，$\mathbf{g}=(g_1,\dots ,g_{12}{)}^{\top }$ 是要求的未知数。

记行规则：

• 刻序号连续、滞后链满 12 刻时记一行。攒不满说明账刚断过，这刻不进方程。

• 跳过一刻、那刻没发转向、两刻相隔不超过 600 ms 时，两刻并成一行。跳过的第 $t-1$ 刻没有单独记行，它的方程照样成立，而且 $u_{t-1}=0$。两刻的方程相加：

  $$\mathrm{wrap}(h_t-h_{t-2})=y_t+y_{t-1}=\sum _{k=1}^{12}{g}_k(u_{t-k}+u_{t-k-1})$$

  未知数还是同一组 $g_k$，第 $k$ 列换成两刻各自对齐后的指令之和。代码里 row[i] 是 $g_{i+1}$ 的系数；跳过那刻的 $u_{t-1}=0$ 在这一行记完之后由 PushLag(0.0) 补进滞后链。

else if (linked && gap_ticks == 1 && gap_ms <= config_.bridge_max_gap_ms) {
    if (chain_len_ >= kLagCount) {
        LagVector row = cmd_lags_;
        for (int i = 1; i < kLagCount; ++i) {
            row[i] += cmd_lags_[i - 1];
        }
        const double heading_delta = NormalizeDeg(heading - prev_heading_deg_);
        total_.Add(row, heading_delta, issued_delta_deg);
        run_.Add(row, heading_delta, issued_delta_deg);
    }
    PushLag(0.0);
}

• 其他情况滞后链清零；定位降级时也清零。
• 所有偏航输出都从同一个出口走，出口按当下的系数折回度数累加。出口的累计和本刻上报的指令差 0.5° 以上，说明别的路径发过转向，之前的滞后链对不上号，作废。

#6104 日志 06:46 那一趟的第 20 到 29 刻，逐刻往 $X$ 里记行。每行 12 格是这一刻之前 12 刻发出的指令（度），$k=1$ 是上一刻，最右一列是本行的 $y$。每过一刻整排右移一格，同一条指令在矩阵里沿斜线往下走，12 刻后从右边出去：第 22 刻发出的约 20° 在第 23 刻落在 $k=1$，第 24 刻落在 $k=2$，这一刻朝向转了 17°。带 * 的第 22、27 刻是两刻并成的一行，第 21、26 刻没有单独记行，格子里的 a+b 是两刻各自对齐后的指令。左侧罗盘对比实测的 $y$ 和用最下一行 ${\hat{g}}_k$ 算出的预测 $\hat{y}$：单行的预测和实测能差出 10°，回归要的是全部 1470 行的残差平方和最小，单行有偏差很正常。

求解。最小二乘取让所有行残差平方和最小的 $\mathbf{g}$：

对每个 $g_k$ 求偏导并令其为 0，得到正规方程 $X^{\top }X\mathbf{g}=X^{\top }\mathbf{y}$。岭回归在左边加一项 $\lambda I$：

这等价于在残差平方和上再加罚项 $\lambda \Vert \mathbf{g}{\Vert }^2$。寻路时指令常常连着几刻同向、大小相近，相邻两列几乎一样，$g_k$ 和 $g_{k+1}$ 之间怎么分配都拟合得差不多，$X^{\top }X$ 接近奇异，单个 $g_k$ 会解得大正大负。罚项在这些分法里挑系数平方和最小的那个；倍率只看 $\sum g_k$，分法变化对它影响很小。

$\lambda$ 按矩阵自身的尺度取：

$\mathrm{tr}(X^{\top }X)/12$ 是对角线的平均值，即每列指令平方和的平均，$\lambda$ 取它的千分之一。样本数翻倍、或者指令幅度翻倍时，$X^{\top }X$、$X^{\top }\mathbf{y}$ 和 $\lambda$ 按同一个倍数放大，$\hat{\mathbf{g}}$ 不变，正则化的相对强度始终一样。

累加量。检测器不存样本，只存三个累加量，每记一行加一次：

合计 144 + 12 + 1 个数，占用的内存和跑了多少刻无关。全程和当前线路各有一份。求解时用 Gauss-Jordan 消元同时解两组方程，系数矩阵都是 $A=X^{\top }X+\lambda I$：

第一组给出增益，倍率估计 $\hat{r}={\sum }_k{\hat{g}}_k$；第二组用在下面的标准误差上。

残差与标准误差。残差平方和展开后只用到三个累加量，不用回放样本：

噪声方差的估计：

分母减 12，是因为拟合 12 个系数用掉了 12 个自由度：只有 12 行时总能找到一组 $\mathbf{g}$ 把每行都拟合得严丝合缝，RSS 为 0，噪声却依然存在。

$\hat{r}$ 是 12 个 ${\hat{g}}_k$ 之和。噪声让每个 ${\hat{g}}_k$ 都有波动，而且它们相互关联。普通最小二乘里 $\hat{\mathbf{g}}$ 的协方差矩阵是 ${\sigma }^2(X^{\top }X{)}^{-1}$，求和的方差等于这个矩阵所有元素之和，即 $1^{\top }\mathrm{Cov}(\hat{\mathbf{g}})1$。检测器用 $A$ 代替 $X^{\top }X$：

$1^{\top }{A}^{-1}1$ 正好是第二组方程的解 $\mathbf{w}$ 各分量之和，所以和 $\hat{\mathbf{g}}$ 一起解。岭回归估计的精确协方差是 ${\sigma }^2{A}^{-1}{X}^{\top }X{A}^{-1}={\sigma }^2(A^{-1}-\lambda A^{-2})$，比 ${\sigma }^2{A}^{-1}$ 略小；$\lambda$ 只有对角线均值的千分之一，两者几乎相等，检测器的写法让 SE 略偏大，判决略偏保守。

SE 随样本数大约按 $1/\sqrt{n}$ 缩小：#6104 日志里 $\mathrm{SE}\cdot \sqrt{n}$ 从 500 样本时的 0.82 降到 1534 样本时的 0.73。

判决。偏快的条件：

偏慢的条件：

此外还要没有任何线路单独读出正常值，见下文。$\hat{r}\pm 3\mathrm{SE}$ 是倍率的置信区间，整个区间都落在判决线外才判。真实倍率恰好在判决线上时，估计值靠噪声越过 3 倍标准误差的概率约 0.13%。

const double margin = config_.sigma_margin * estimate->se;
const bool too_fast = estimate->ratio - margin > config_.overshoot_ratio && estimate->ratio <= config_.max_ratio;
const bool too_slow = estimate->ratio + margin < config_.undershoot_ratio && estimate->ratio >= config_.min_ratio && !normal_run_seen_
                      && !RunReadsNormal();

偏慢的判决要更小心。卡墙时指令很大、朝向不动，一段卡墙就能把全程估计压到一半，所以判偏慢还要求没有任何一条线路单独读出正常值。累加量有全程和当前线路两份；任何一条线路单独攒到 50 个样本且倍率高于 0.833，就否决偏慢。

判决在累计样本数到 $500\times 2^j$（500、1000、2000……）时各做一次，每条线路结束时样本够 500 也做一次。要多少样本才判得出来：把 $\mathrm{SE}\approx c/\sqrt{n}$ 代进偏快条件，

按 #6104 日志的 $c\approx 0.73$ 估算，并假设噪声水平和这份日志相当：倍率 1.5 时要 53 个样本，1.35 时要 212 个，都在第一次判决（500 样本）时成立；1.25 时要 1903 个，到 2000 样本那次才成立。

蓝点是 #6104 日志里检测器记下的 15 次估计：500、1000 两次是定时判决，其余 13 次在线路结束时。竖线是 ±3 SE，全部落在两条虚线判决线之间，所以没有判。红、橙两条实线是把 $\mathrm{SE}=0.73/\sqrt{n}$ 代进判决条件得到的界，估计值高过红线才判偏快，低过橙线才判偏慢：500 样本时要高过约 1.30，2000 样本时要高过约 1.25。样本越多，界越贴近判决线。

落地。判决只触发一次，乘在偏航和俯仰上的系数取倍率的倒数，一直保持到进程退出：

校正后发 $u$ 度，实际转过 $\hat{r}\cdot s\cdot u=u$ 度。转过头时 $s<1$，缩小转向量；转不到位时 $s>1$，放大转向量。日志 “Turn sensitivity corrected.”，通知 navigation.sensitivity_corrected。之后累加量清零从头再估，日志里能看出校正后的倍率是否回到 1。

用 #6104 日志的 22 趟、1470 刻样本，按同样的岭回归离线重估 12 阶增益。转量主要落在第 2、3 刻（按中位刻间隔 186 ms 折算约 0.4 到 0.6 s），第 4 刻之后基本归零。累计倍率 0.968 ± 0.019，日志里检测器同期的估计是 0.978 ± 0.019，都在正常带 [0.83, 1.20] 内。第 1 阶增益只有 0.03：指令发出后的下一刻，朝向几乎还没动。

卡死与恢复

NavMesh 只记录静态地形。路上的箱子、设备、矮墙边缘、模型碰撞比网格宽出来的那一截，未纳入白名单的实体规划层都看不见：路线是通的，角色却顶在原地。跟随层只会沿走廊一直推，把这种情况交给恢复阶梯处理。

阶梯有四档，按锚点计次，整体受 30 s 硬时钟约束：

跳是首选的反应：矮的障碍跳过去就能沿原来的精确路线接着走。同一锚点跳满 2 次（kRecoveryJumpAttemptsBeforeDetour）还脱不了身，才退到 NavMesh 绕障。

#6104 日志的 22 趟里，恢复跳共 26 次，虚拟禁区 9 个。

触发

const bool should_try_recovery =
    session_->phase() == NaviPhase::Navigate && (stalled_ms >= kObstacleRecoveryMinTriggerMs || forward_hold_futile)
    && (effective_progress > kNoProgressMinDistance || waypoint.RequiresStrictArrival()) && !runtime_state_.cross_tier_escape.active;

四个条件：

1. 处于 Navigate phase。滑索、FIND、TRANSFER、TRIGGER 的等待 phase 都在阶梯之外。
2. 普通停滞时钟 ≥ 3500 ms，或前进键重发 2 次仍然原地不动（forward_hold_futile，见前进键闭环）。
3. 有效进展 > 3.0，也就是离锚点还有 3.0 以上；严判点不受这条限制。3.0 以内的停滞交给无进展超时。
4. 不在跨层逃逸中。逃逸走的是一条固定走廊，有自己的失败判据。

第 3 条用的距离和停滞时钟是同一个信号。走廊跟随时，这个距离是走廊上剩下的真实距离；串行路点只是沿途的一个记号，可能就在角色身边一个像素外，整段路却还在前头。拿串行路点的距离来判，贴着它卡住的角色会被当成”已经到了”，到达需要的起步动作做不出来，恢复也不会启动。

第 2 条的前进无效计数是停滞时钟正在收集的同一种证据，来得更早也更强：朝向对准了、没在转向、前进键重发两次位置读数都没变。再等停滞时钟走满只是继续往障碍上撞，所以它也能打开阶梯。

触发之后先解析当前锚点（规则见锚点）。恢复回合和升级计数都挂在锚点序号上，锚点变了就重开一轮。换锚点时还会丢掉设备探测器已经存下的结果：那个结果是在对付上一个锚点时看到的，画面早于路线重新编号。第一个锚点不丢，这时还没对付过别的锚点，探测器从停滞开始就在为它预热。

阶梯

满足触发条件、且距上一个恢复刻已过 3500 ms 冷却的刻，才是一个恢复刻；一个回合的第一刻没有冷却。一个恢复刻里按顺序执行：

flowchart LR
    subgraph G2a [恢复刻]
        direction TB
        T{"硬时钟<br/>> 30 s？"} -->|ZIPLINE 点| Z(["退索走路"])
        T -->|其他点| F(["dynamic_recovery_timeout"])
        T -->|否| D["搬走挡路设备<br/>每锚点 1 次"]
        D -->|脱出| R(["ResumeAfterEscape"])
        D --> J["前跳 500 ms<br/>重新取位"]
        J -->|脱出| R
        J --> E{"本锚点<br/>已跳 ≥ 2 次？"}
        E -->|否| W(["等下一个恢复刻"])
        E -->|是| UP(["转升级"])
    end
    subgraph G2b [升级]
        direction TB
        G{"绕障 < 3 次<br/>且不在唯一通路旁？"} -->|是| V["虚拟禁区<br/>重规划"]
        V -->|成功| N(["沿新路线继续"])
        V -->|失败| U["物理脱困"]
        G -->|否| U
        U -->|找到方向| N
        U -->|找不到| W2(["等下一个恢复刻"])
    end
    G2a --> G2b

1. 硬时钟超时。硬时钟停滞超过 30000 ms 时，ZIPLINE 点先丢掉整条滑索链改走路，其余点以 dynamic_recovery_timeout 失败。退索会把硬时钟归零，再超时时当前点已经是步行点，那一次才判失败。卡在索边收不拢时先退索走路，给步行一次机会，这个分支也不会反复进入。
2. 冷却。距上一个恢复刻不足 3500 ms 时什么都不做。
3. 搬走挡路设备。本锚点还没试过时执行，见搬走挡路设备。设备搬完人仍然卡着，同一刻继续往下走。
4. 跳。每个恢复刻都跳，见跳。
5. 升级。本锚点的跳计数到 2 之后，同一刻继续：
   • 卡死朝向取走廊航向，没有走廊时取路线航向。
   • 附近有标为唯一通路的圆形禁区（距离 ≤ 圆半径 + 1.0 + 1.5）时跳过绕障。
   • 绕障次数 < 3 时做虚拟禁区重规划。成功就切回 Navigate 继续走；失败打 WARN “Dynamic recovery detour attempt failed; switching to physical unstick.”。
   • 绕障失败、次数用完或被跳过时，同一刻做物理脱困。
6. 以上都没有结论时睡 33 ms，等下一刻。

跳在每个恢复刻都执行，新的一次停滞总是先试着跳出去；同一锚点跳失败 2 次后，后面的档位才打开。绕障在前方放一块圆形虚拟禁区再重规划，这个圆在整趟导航里一直把路线挡在这块地方之外。已经证明会封住唯一通路的地方跳过绕障，直接物理脱困。

阶梯的档位按恢复刻叠加，每一刻都从设备和跳开始。卡在同一个锚点上、每档都没脱出时的节奏：

恢复刻之间至少隔 3500 ms，实际间隔取决于触发条件何时再次成立。绕障成功会换上新路线，普通停滞时钟随之清零；前进无效计数在换路线时保留，角色转向或挪动才清，处在等待 phase 时每刻都清。#6104 日志里的两次脱困正好是这两种情形：06:31 那次，跳 #3 在新路线换上 0.24 s 后就发出，此时停滞时钟刚清零，打开阶梯的只能是前进无效计数；06:41 那次，新路线换上后停滞时钟从 0 重新攒到 3.5 s，才有跳 #3。

脱出检查。恢复回合开始时记下卡死点位置。之后的每一刻，在阶梯之前先检查：离卡死点 ≥ 2.0，或定位区变了，就判定脱出，日志 “Dynamic recovery escaped obstacle.”，进 ResumeAfterEscape。跳和搬走挡路设备的脱出判据在各自动作完成后当场再查一遍。

#6104 日志 06:41 那一趟，起步 2 s 后卡在 (912.12, 263.02)，绕障的目标是前方的滑索上架点。右下的停滞时钟取自每刻的走廊日志；恢复刻不经过那条日志，图上表现为平台。事件顺序：

第三个圆和收缩前的 ② 大小、位置都一样，两次规划的差别只在起点：卡死点出发时目标面不可达，挪开 1.58 之后就规划通了。

搬走挡路设备

路上放置的设备挡路时，可以交互把它拿起来挪开。这一档共 11 张模板，后台扫描器由采集点扫描器泛化而来。

探测。后台扫描交互按钮所在的区域，ROI 直接读 Pipeline 里交互按钮检查用的那一个，配置只有 JSON 一处。阈值 0.65，低于 Pipeline 默认的 0.7：探测只决定子任务值不值得跑，子任务动手之前还会按自己的阈值再查一遍。

探测从停滞的第一刻就开始喂，到第一个恢复刻时结果已经存好，读取不花时间。停滞时钟重新起跑的边沿会丢掉旧结果，等待 phase 的每一刻也会丢掉（#6228「语义动作期间清掉顶墙计数与设备命中」）。

执行：

1. 探测没命中，返回”未尝试”，直接去跳。面前没有可交互的东西，跳是更快的办法。
2. 重按前进，跑子任务。前进键在子任务期间一直按着：子任务把设备拿起来，角色要在它放下之前走出设备底下，否则设备又落回原处挡路。
3. 重新取位。取不到就返回”需要新定位”，这一刻结束。拿旧坐标往下走的话，后面的跳会从旧位置量位移，报出一次没发生过的脱出。
4. 用和跳一样的脱出判据判断。没脱出时日志 “Device handled but the agent is still pinned; continuing to the jump.”，同一刻接着跳。

除”未尝试”之外，其余结果都跑过子任务，都消耗次数。每个锚点只有 1 次：子任务自己的超时就可能花掉 30 s 硬时钟里的约 15 s，剩下的时间还要留给跳、绕障和物理脱困。

子任务里交互后的等待取 1000 ms。PR 里的实测：交互后 0.79 s 时按钮的识别置信度只有 0.53 到 0.65，到 1.28 s 才升到 0.97。

跳

1. 跳计数加 1，发出日志 “Dynamic recovery jump pulse issued.”。
2. 前跳，睡 500 ms，松前进键。
3. 重新取位。取位失败、黑屏或位置无效时，发出日志 WARN “Dynamic recovery waiting for post-jump local tracking fix.”，等下一刻。
4. 判断脱出：

const bool jump_made_progress = jump_waypoint_distance + kNoProgressDistanceEpsilon < route.waypoint_distance;
const bool jump_moved_forward = jump_displacement >= kDynamicRecoveryResetDistance * 0.5 && jump_made_progress;
if (jump_zone_changed || jump_displacement >= kDynamicRecoveryResetDistance || jump_moved_forward) {
    LogInfo << "Dynamic recovery jump escaped obstacle." << VAR(jump_zone_changed) << VAR(jump_displacement)
            << VAR(jump_moved_forward);
    return ResumeAfterEscape("recovery_jump_escape");
}

三种情况算跳出去了：换了定位区；位移 ≥ 2.0；位移 ≥ 1.0 且离当前路点近了 0.5 以上。第三条接受位移不到 2.0、但确实朝路点前进了的跳。日志样例：

Dynamic recovery jump escaped obstacle. [jump_zone_changed=false] [jump_displacement=2.499300] [jump_moved_forward=true]

5. 没跳出去时重新解析锚点。跳完人可能落到了另一段路线上：锚点变了，恢复回合在新位置重开，升级计数重置，跳计数记为 1。

虚拟禁区

#5576 之后，绕障这一档的做法是在卡死点前方放一个圆形禁区，再重规划到锚点。

#5576 里的原理图，俯视，纵坐标向下增大。起点到终点的直线（虚线）穿过一处障碍，NavMesh 里没有这块障碍，规划器照直线出路线，角色朝上走到叉号处卡死（y 1847.0）。恢复阶梯沿卡死朝向在前方 3.0 处放一个 $r=2.0$ 的圆形禁区（圆心 y 1844.0），圆内的格从可走集合里拿掉，再规划一次，新路线（红线）贴着圆边绕到终点。图里的终点对应恢复流程里的锚点。障碍有一部分在圆外，圆是对障碍大小的估计。

原理是把卡死当成一次障碍观测。NavMesh 上没有的障碍，规划器看不见，每次重规划都给出同一条穿过它的路线；角色卡住的位置和朝向说明障碍大致在卡死点正前方。在那里盖一个圆，规划器把圆内的格当成不可走，新路线就绕开这块区域。圆的大小靠估计：盖小了，角色会在圆边上再卡一次，这次卡死说明障碍比圆大，新圆长一档，旧圆保留；盖大了，可能把整条窄路封死，规划失败时半径减半再试，仍失败就把这处记为唯一通路，交给物理脱困。standoff 距离把角色所在的格留在圆外，重规划才有起点；锚点净空把锚点留在圆外，重规划才有终点。

圆心。卡死朝向 $h$ 按罗盘角计（0 朝上、顺时针），地图纵坐标向下增大，方向向量是 $\mathbf{v}=(\sin h,-\cos h)$。记卡死点为 $S$，半径为 $r$ 的圆，圆心取在

圆的近边离卡死点正好 1.0，卡死点本身不在禁区里。朝向的口径与物理脱困的 PlanUnstickTarget 相同。

同样来自 #5576，俯视。左：路宽 12 的道路上，角色朝 0°（向上，$\mathbf{v}=(0,-1)$）卡死，$C=S+(2.0+1.0)\mathbf{v}$，圆心前移 3.0。圆的近边离卡死点 1.0，角色所在的格留在圆外，重规划有起点。圆两侧到路边各剩 3.33 和 4.67。右：把各档半径画在同一个卡死点上。半径按 2.0、3.5、5.0 生长，圆心跟着前移，近边始终在卡死点前 1.0 处。$r=5.0$ 时左侧只剩 0.33；上限 6.5 的直径 13 超过路宽 12，整条路被封死，这时规划失败，进入下面的失败处理。

半径分四步定：

1. 生长。从 $r=2.0$ 开始，先算一个试探圆心 $C(2.0)$。逐个检查已有禁区，第 $i$ 个的圆心为 $C_i$、半径为 $r_i$。同一定位区、没标唯一通路、并且试探圆心落在它外扩一档的范围内：

   $$|C(2.0)-C_i|\le r_i+1.5$$

   就把半径提到比它大一档，封顶 6.5：

   $$r\leftarrow \max (r,\min (r_i+1.5,6.5))$$

   在已有禁区的边缘又卡死，说明障碍比那个禁区大，新禁区在它的半径上加一档。旧禁区原样保留，两者的并集仍然盖住最初的卡死点。

2. 锚点上限。记卡死点到锚点的距离为 $D$。锚点正好在前方时圆心离锚点最近，两者相距 $D-(r+1.0)$。按这个最坏情形，要求锚点留在圆外、并且离圆边至少 1.0：

   $$D-(r+1.0)\ge r+1.0⟺r\le \frac{D-2.0}{2}$$

   锚点在 6.0 处时上限 2.0；$D<4.0$ 时上限低于下限 1.0，不放禁区。锚点太近时禁区会盖住锚点本身，重规划没有终点。

3. 让出当前位置。卡死点和当前位置可能不同（物理脱困之后放的圆，卡死点是脱困前的位置）。记当前位置为 $P$，当前位置落在圆内时规划起点就在禁区里。半径逐次减半，圆心跟着按新半径重算，直到当前位置落在圆外：

   $$|P-C(r)|<r⟹r\leftarrow \frac{r}{2}$$

4. 下限。$r<1.0$ 时放弃，日志 “Virtual no-go skipped: no room for a disc between here and the anchor.”。