精简仓库结构并增强任务链路：归档双目可选后端、新增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。

utils/README.md

@@ -1,51 +1,57 @@
-# utils —— reference-c++ 的 Python 移植 + 双目链路新实现
+# utils —— Python 实现（运行链路）
 
-将 `reference-c++/` 下的 `target_tracker`（多目标追踪过滤器）与
-`visual_track_control`（视觉跟踪控制律）移植为 Python，**两包互不依赖**
-（唯一的数据转换点在胶水层 demo）。
+> **架构现状（2026-10-20）**：运行链路是「光电吊舱 → `pod_bridge` → `task_runner` → PX4」。
+> 双目 + YOLO 那套可选感知后端（`stereo_yolo` / `target_tracker` / `stereo_ranger`）
+> **已整体归档到仓库根的 `legacy/`**，默认不参与 pytest 收集；接回方式见 `legacy/README.md`。
 
-另有双目链路新实现（非 C++ 移植、按规格实现）：
-- `stereo_ranger`（双目稀疏目标测距），规格 `docs/双目测距技术路线.md`；
-- `stereo_yolo`（双目 YOLO 检测前端），规格 `docs/双目YOLO目标识别需求说明.md`，
-  输出直接作为 stereo_ranger 的输入（仅复用其 `types.py` 纯值类型）。
+本目录包含：
 
-Python 侧定位为 **C++ 实现的先验验证**：构件划分与语义按规格冻结，便于逐构件
-移植对照；`stereo_yolo` 的 C++ 移植注记见其包 README。
+- **运行链路**：`pod_bridge`（吊舱桥接）+ `task_runner`（任务编排）+ `visual_track_control`
+  （控制律原语，被前两者复用）
+- **入口共享件**：`sitl_support.py`（时钟/遥测订阅/连接准备/`RATE_*`）
+- **测试**：`tests/`（446 条）、`conftest.py`、`pytest.ini`
+
+`visual_track_control` 是 `reference-c++/visual_track_control` 的逐构件 Python 移植
+（语义对齐、含行为修复）；`target_tracker` 的移植版已随归档移入 `legacy/utils/`。
 
 ## 目录结构
 
 ```
 utils/
-├── target_tracker/            # 包 1：卡尔曼滤波多目标追踪（无第三方硬依赖，仅 numpy）
+├── pod_bridge/                # 吊舱 ↔ PX4 桥接（**运行链路核心**）
+│   ├── bridge.py              #   PodBridge：L1/L2 切换、目标门控、链路维持
+│   ├── los_consistency.py     #   目标有效性第二判据（LOS 运动学一致性）
+│   ├── ground_link.py         #   地面站 UDP 坐标注入 + 命令队列
+│   ├── guidance.py            #   L2 地理引导律
+│   ├── protocol.py            #   表2-1/2-2/3/4 帧编解码
+│   ├── pod_serial.py          #   串口链路（115200 8N1）
+│   ├── px4_gateway.py         #   MAVSDK 遥测 + offboard 网关
+│   ├── virtual_pod.py         #   虚拟吊舱（SITL/台架）
+│   └── {run_bridge,listen_pod,pod_console,sim_fc,verify_px4}.py   # 台架工具
+├── task_runner/               # 任务级编排
+│   ├── state_machine.py       #   WAIT→ARM_TAKEOFF→GOTO→SEARCH→TRACK→RTL
+│   ├── runner.py              #   编排器（快照采集/动作/异常兜底）
+│   ├── return_home.py         #   自定义返航（回起飞点→恢复航向→垂直降落）
+│   ├── pod_control.py         #   吊舱识别/锁定指令
+│   └── log.py                 #   事件 JSONL + 遥测 CSV + 简报
+├── visual_track_control/      # 控制律 + MAVSDK 网关（运行链路复用）
 │   └── README.md              # 接口清单 + C++ 差异
-├── visual_track_control/      # 包 2：三通道控制律 + MAVSDK offboard 网关
-│   └── README.md              # 接口清单 + C++ 差异
-├── stereo_ranger/             # 包 3：双目稀疏目标测距（纯标准库，无第三方依赖）
-│   └── README.md              # 接口清单 + 与规格的偏差
-├── stereo_yolo/               # 包 4：双目 YOLO 检测前端（真模型需 ultralytics）
-│   └── README.md              # 接口清单 + C++ 移植注记
-├── demo_track_control.py      # 胶水层集成演示（模拟检测 → 追踪 → 控制律 → 发送）
-├── demo_stereo_ranger.py      # 双目测距演示（合成框对，六场景，无硬件）
-├── demo_stereo_yolo.py        # 检测前端演示（真模型 + 合成素材 → 测距联调）
-├── assets/stereo_yolo/        # demo 占位素材（AI 合成图，可整体替换为真实素材）
-├── config/track_control.json  # 控制律配置（拷贝自 reference-c++）
-├── config/stereo_ranger.json  # 双目测距配置（占位值，待标定回填）
-├── config/stereo_yolo.json    # 检测前端配置（不存内参，几何参数唯一来源见上）
-├── tests/                     # pytest 测试
-│   ├── target_tracker/        # 28 条（对应 C++ 测试文件）
-│   ├── visual_track_control/  # 81 条（对应 C++ 测试文件）
-│   ├── stereo_ranger/         # 111 条（规格 §11.4 构件级 + 全流程）
-│   └── stereo_yolo/           # 36 条（假检测器驱动，无模型/素材/硬件）
-├── conftest.py                # 保证可从任意工作目录导入各包
-└── pytest.ini                 # 收集 *_test.py 命名（与 C++ 测试文件名对齐）；
-                               # importlib 导入模式避免跨包同名测试文件冲突
+├── config/                    # 配置 JSON（pod_bridge.json 为主线）
+├── tests/                     # pytest（446 条）
+│   ├── pod_bridge/            #   208 条（协议/桥接/引导/注入/节流/LOS）
+│   ├── task_runner/           #   122 条（状态机/编排器/返航/日志/吊舱控制）
+│   ├── visual_track_control/  #   86 条（对应 C++ gtest + L1 增量）
+│   └── ground_station/        #   30 条（页面与日志解读）
+├── conftest.py                # 把 utils/ 插进 sys.path + fake_mavsdk fixture
+├── pytest.ini                 # 收集 *_test.py + importlib 导入模式
+└── sitl_support.py            # 入口共用：时钟/遥测订阅/连接准备/速率常量
 ```
 
 ## 环境
 
 conda env `pytorch`（`D:\program file\conda\envs\pytorch`），Python 3.12，
-依赖：numpy、mavsdk、pytest；stereo_ranger 仅标准库；stereo_yolo 只有真模型
-推理路径需要 ultralytics（在检测器内部延迟导入，测试与假检测器路径不受影响）。
+依赖：numpy、mavsdk(<4)、pytest、flask、pyserial
+（`opencv-python` 仅供 `tools/` 下的相机脚本；`ultralytics` 仅供已归档的双目链路）。
 
 ## 运行测试
 
@@ -54,51 +60,46 @@ cd utils
 "D:/program file/conda/envs/pytorch/python.exe" -m pytest -q
 ```
 
-256 条测试全部通过：109 条 C++ 移植用例（含 §9.4 六条硬验收、A1/A2/A4
-回归、PID anti-windup C1、超龄 C4、首拍限幅 S6）+ 111 条 stereo_ranger
-（合成框对驱动）+ 36 条 stereo_yolo（假检测器驱动）。
-stereo_ranger / stereo_yolo 测试均不需要真实图像、模型权重或硬件。
+**运行链路 446 条全部通过（2026-10-20）**：
 
-## 运行演示
+| 组 | 条数 |
+|---|---|
+| `pod_bridge` | 208 |
+| `task_runner` | 122 |
+| `visual_track_control`（含 §9.4 硬验收、A1/A2/A4、C1、C4、S6、L1 角度直入） | 86 |
+| `ground_station` | 30 |
+
+归档的可选后端 175 条（stereo_ranger 111 / stereo_yolo 36 / target_tracker 28）
+在 `legacy/` 下，按需运行：
 
 ```bash
-# mock 传输（本地记录指令，无实机）
-python utils/demo_track_control.py --speedup 10
-
-# MAVSDK 实发（需飞控/SITL 在 udp://:14540）
-python utils/demo_track_control.py --transport mavsdk
-
-# 双目测距（合成框对，离线，无相机/飞控）
-python utils/demo_stereo_ranger.py
-
-# 双目检测前端（真模型推理；需 ultralytics + models/yolo26n-drone.pt）
-python utils/demo_stereo_yolo.py
+cd legacy/utils && PYTHONPATH="../../utils" "D:/program file/conda/envs/pytorch/python.exe" -m pytest -q
 ```
 
-控制链路时间线 13 s（20 Hz）：正常跟踪 6 s（vx 从零渐变 → 逼近限速 3 m/s）→
-目标消失 4 s（Coast 预测，60 帧后轨道判亡）→ 判零速刹车 3 s。
+运行链路测试不需要硬件（FakePod / VirtualPod / FakePx4 注入）。
 
-双目测距演示六场景：逼近（三道有效性门 + 滤波）→ 远场域外（方位仍发布）→
-单目退化 → 非同帧拒收 → 一致性降级/判无效 → 多目标贪心配对。
+## 运行入口
 
-检测前端演示五场景：单图冒烟 → 合成双目对联调（真检测框喂 stereo_ranger，
-与解析式 D=F·B/Z 对照）→ 空场景 → 左右形状不一致拒收 → 帧周期计时。
-合成对用 AI 占位素材 `assets/stereo_yolo/drone_sky.png`（可整体替换为真实
-素材），本机实测 |ΔD|≈0.3 px、|Δy|≈0.2 px；帧周期 25~34 ms（640 输入，
-双实例并发，随机器负载波动），与 30 fps 预算 33.3 ms 同量级，结论不可外推
-到机载平台（§5 的算力预算另见平台工程文档）。
+入口脚本在仓库根（不在 utils 内）：
+
+```bash
+PY="D:/program file/conda/envs/pytorch/python.exe"
+"$PY" task_runner_sitl.py --conn udpin://0.0.0.0:14540      # 任务全流程 SITL
+"$PY" task_runner_real.py --port COM5 --conn udpin://0.0.0.0:14540 --target-type 1
+"$PY" l1_sitl_test.py --conn udpin://0.0.0.0:14540          # 仅 L1 控制律闭环
+"$PY" utils/pod_bridge/run_bridge.py --port COM5 --dry-run  # S2 台架干跑
+```
 
 ## 移植约定
 
-- MAVLink 部分改为 **MAVSDK 语义映射**（offboard API，非字节透传），三分支
-  映射保留 C++ A2 回归语义，详见包 2 README。
+- MAVLink 部分改为 **MAVSDK 语义映射**（offboard API，非字节透传），三分支映射保留
+  C++ A2 回归语义，详见 `visual_track_control/README.md`。
 - 测试逐条移植 C++ gtest 断言（`EXPECT_DOUBLE_EQ` → 精确 `==`，
-  `EXPECT_NEAR` → `pytest.approx`）；MAVSDK 部分因无 SITL/实机，仅 mock 验证。
+  `EXPECT_NEAR` → `pytest.approx`）。
 - 行为修复项（C1/C2/C4、A1/A2/A4、S6）在测试文件头注释中标注对应章节。
-- `stereo_ranger` 不是移植：按规格五步流程新实现，与规格的偏差（越界=有效性门、
-  视差域权威、补充 consistency_jump_px/isolation_gate_px 等）见其包 README；
-  ⚠ 全部数值为占位值，标定完成前不得作为飞行控制决策依据。
-- `stereo_yolo` 不是移植：推理口径为 ultralytics 直跑 `.pt`，letterbox、解码、
-  NMS、坐标回映均在库内完成；C++ 侧复现要点与接口契约硬约束（原生分辨率坐标、
-  左右预处理位级一致、`x1` 即框左边缘、无跨帧状态）见其包 README 的移植注记表。
-  ⚠ 占位素材 `assets/stereo_yolo/` 为 AI 合成图，真实双目素材到位后需重跑联调。
+- ⚠ 全部数值为占位值，标定完成前不得作为飞行控制决策依据。
+
+## 已归档内容
+
+`legacy/utils/` 下保留了原 `stereo_yolo` / `stereo_ranger` / `target_tracker` 三包、
+175 条测试、三个 demo、`stereo_*.json`、素材与 YOLO 权重；说明见 `legacy/README.md`。