精简仓库结构并增强任务链路：归档双目可选后端、新增LOS判据与自定义返航

归档 legacy/：stereo_yolo/stereo_ranger/target_tracker 三包 + 175 条测试 + demo/配置/权重/三份规格；运行链路不再依赖，默认 pytest 446 条，归档测试按需运行。

目标有效性第二判据改为 LOS 运动学一致性（pod_bridge/los_consistency.py），删除 require_vision；pod_locked() 叠加该判据，状态机随之后退重搜。

自定义返航（task_runner/return_home.py）：保持转场高度回起飞点 → 恢复初始航向 → 垂直降落，不再爬 RTL_RETURN_ALT；未起飞/无起飞点/超时/异常仍退回 PX4 原生 RTL。

任务链安全兜底：主循环异常→紧急返航、stop 幂等、landing_stop 保留遥测、in_air 流复用+超时、解锁/起飞与吊舱识别仅执行一次、rtl_timeout 上限。

入口共享件拆到 utils/sitl_support.py；pod_sitl_test.py→l1_sitl_test.py；删除旧架构 test.py；相机脚本移入 tools/。

新增 .gitignore 并剔除历史误跟踪的 59 个 .pyc；requirements 按实际依赖重写；文档全面对齐，新增 legacy/README.md 与 tools/README.md。

docs/树莓派4B部署注意事项.md

@@ -1,4 +1,4 @@
-# pod_bridge 移交树莓派 4B 部署注意事项
+# pod_bridge 移交树莓派 4B 部署注意事项
 
 > 目标平台:树莓派 4B + **Raspberry Pi OS 官方镜像(64 位,Bookworm / Trixie)**。
 > (2026-09-23 由 Ubuntu 24.04 换回官方镜像:Ubuntu 镜像上串口配置与
@@ -48,7 +48,7 @@ pytest      # 仅上机自测需要,部署运行可省
 
 - **mavsdk 4.x 是全新原生 API 重写,与经典 gRPC API 完全不兼容**(2026-09-24
   树莓派实测):没有 `mavsdk.offboard` / `System` / `telemetry`,本仓库全部
-  飞控代码(Px4Gateway / MavsdkCommandGateway / test.py)都是经典 API,
+  飞控代码(Px4Gateway / MavsdkCommandGateway / 各入口脚本)都是经典 API,
   装 4.x 直接 `LegacyModuleError`。**必须锁 `mavsdk<4`**(最新 3.17.4,
   aarch64 官方 wheel `manylinux2014_aarch64`,PyPI 已核对);
   32 位 armv7l 支持不稳定——这是必须 64 位镜像的主因。
@@ -66,7 +66,7 @@ pytest      # 仅上机自测需要,部署运行可省
 
 - 连接串写法(`pod_bridge.json` 的 `px4.connection_string`):
   - Pi 串口直连飞控 TELEM:`serial:///dev/ttyUSB0:57600`(波特率按飞控侧设置);
-  - 经数传/仿真:`udp://:14540`。
+  - 经数传/仿真:`udpin://0.0.0.0:14540`(本机 SITL 实测可用;`udp://:14540` 亦可,语义为监听该端口)。
 - PX4 侧需确认 TELEM 口已配 MAVLink 且 offboard 心跳未被占用。
 
 ## 4. 串口硬件(吊舱侧,最容易翻车)
@@ -251,26 +251,28 @@ python -m pod_bridge.sim_fc /dev/ttyAMA0 --detect person --auto-lock \
 
 | 受影响项 | 后果 |
 |---|---|
-| `guidance.py` 地理位置引导律 | **永久刹车**。桥接层 `bridge.py:169` 的 `target_valid` 依赖表4;表4 恒缺 → `_latest_target` 恒 None → `GuidanceLaw.update()` 每周期走 `_brake("载机位置或目标不可用/超龄")`。安全方向正确(降级刹车、不会乱飞),但**吊舱表4 这条引导路径在本设备上等于不存在** |
-| 目标距离/坐标来源 | 必须改由**我方自有链路**提供:`stereo_yolo` 检测 → `stereo_ranger` 双目视距。吊舱只当作"稳定指向 + 表2-2 脱靶量"的伺服/传感器用 |
+| `guidance.py` 地理位置引导律 | **表4 路径在本设备上恒不可用**(`target_valid` 恒假)。**现行做法:坐标走地面站 UDP 注入**(`ground_link` → `ground_target_fn`),`guidance` 吃注入坐标;表4 仅作回退 |
+| 目标距离/坐标来源 | **坐标 = 地面站注入**(已落地)。**距离尚未接入**:规划由激光雷达提供(低算力);~~`stereo_yolo` 检测 → `stereo_ranger` 双目视距~~ 因 Pi 4 跑不动实时 YOLO,**暂不接入** |
 | `--auto-unlock`(§10.1) | **必然误触发,已实测禁用**:`last_tgt_s` 恒 None 被当成超时。见 §10.1 |
 | 后续选型 | 若要保留吊舱侧目标定位,只能换**带激光测距的吊舱型号**(且需确认激光能接入吊舱解算链路) |
 
-#### 架构该怎么办(分叉已选边)
+#### 架构该怎么办(2026-10-19 已定稿)
 
-既然距离无法回灌、表4 不会有,目标地理坐标就**必须由我方自己解算**:
+既然距离无法回灌、表4 不会有,目标地理坐标就**必须来自吊舱之外**。当时的设想是
+"双目自算坐标";实际实现改成了更简单的分工:
 
 ```
-stereo_yolo 检测 → stereo_ranger 双目视距(斜距/前向距离)
-                → 载机 GPS + 姿态(表3 我方已有) + 吊舱框架角(表2-2)
-                → **我方自己算出目标经纬度**,再喂给 guidance.py
+目标**坐标**  ← 地面站 UDP 注入(ground_link)     ← 已落地
+目标**方位**  ← 吊舱表2-2 脱靶量(角度直入 L1)     ← 已落地
+目标**距离**  ← 待接激光雷达(串口,低算力)        ← 未接
 ```
 
 吊舱在本设备上退化为:**伺服稳定指向 + 表2-2 脱靶量/框架角传感器**。
 它仍然很有用(稳像、跟得住、给得出视场角),只是不再提供坐标。
 
-> 这意味着 `guidance.py` 的输入要从"吊舱表4"换成"我方自算的目标经纬度",
-> `bridge.py:169` 的 `target_valid` 判据也要跟着改。**动手前先对齐方案再实现。**
+> ~~下文"stereo_yolo → stereo_ranger 自算经纬度再喂 guidance"的方案~~ 已被上述
+> 分工取代:`guidance.py` 的输入改为**注入坐标**(已实现),不需要我方自算经纬度。
+> 距离接入后,只影响控制律的 `distance_valid` 分支,不影响坐标来源。
 
 > 复测命令(`--json` 后是**输出产物路径**,非预置输入文件,建议给绝对路径):
 > ```
@@ -298,7 +300,9 @@ SEC 秒重复一次(与"假锁定"形成持续震荡:解锁 → 自动锁定 →
 2. 表4 超时(需先确认表4 存在);
 3. 锁定持续超过 T 秒且**从未**收到表4 → 判为假锁定,解锁一次并告警(不循环);
 4. 脱靶量恒为 0 持续 T 秒 —— 居中跟踪时也会为 0,**误杀风险高**,不推荐;
-5. 由我方视觉链路(stereo_yolo / target_tracker)交叉验证 —— 最可靠,待集成。
+5. ~~由我方视觉链路(stereo_yolo / target_tracker)交叉验证~~ → **已实行为 LOS 运动学一致性**
+   (`pod_bridge/los_consistency.py`,2026-10-19):无电机、刚性固连 → 机头转 Δψ 时脱靶量
+   必变 ≈−Δψ,不动即判丢。无需额外传感器;局限是只证"角度是活的",不证"是那个目标"。
 
 飞行期的正确行为是**刹车保护**(现有 `target_stale_ms` 已覆盖),与"解锁以便重新
 搜索"是两件事,不要混为一谈。