code-test-drone/工作进度.md

工作进度

更新日期：2026-10-13 项目：无人机视觉目标追踪与控制系统 （reference-c++/ C++ 参考实现 ＋ utils/ Python 移植与新实现）

本文只记「做完了什么 / 卡在哪 / 下一步怎么走」。 架构全貌与必须遵守的铁律见 .workbuddy/memory/ARCHITECTURE.md； 「预定流程」全链路的操作指南与待办清单见 预定流程-操作指南.md； 权威规格见 docs/ 下各技术路线 md（代码注释用 §章节号 反向引用）。

---

1. 已完成工作

1.1 C++ → Python 移植（2 个模块）

C++ 源工程	Python 目标包	状态
reference-c++/target_tracker	utils/target_tracker	✅ 完成（28 条用例）
reference-c++/visual_track_control	utils/visual_track_control	✅ 完成（81 条 + L1 增量 5 条 = 86）

• 逐构件对照移植：测试断言逐条搬运（EXPECT_DOUBLE_EQ → 精确 ==， EXPECT_NEAR → pytest.approx）。
• 两包互不依赖，唯一转换点在胶水层 utils/demo_track_control.py。
• MAVLink 部分改为 MAVSDK 语义映射（offboard API，非字节透传）， 三分支映射保留 C++ A2 回归语义。
• 行为修复项（C1/C2/C4、A1/A2/A4、S6）已在测试文件头注明对应章节。

1.2 双目链路新实现（非移植，按规格新写）

Python 包	规格来源	状态
utils/stereo_ranger（稀疏目标测距）	docs/双目测距技术路线.md	✅ 完成（111 条）
utils/stereo_yolo（双目 YOLO 检测前端）	docs/双目YOLO目标识别需求说明.md	✅ 完成（36 条）

• stereo_ranger 按规格五步流程实现，纯标准库，无第三方依赖； 越界即有效性门、视差域权威，偏差项已在其包 README 记录。
• stereo_yolo 推理口径为 ultralytics 直跑 .pt，letterbox/解码/NMS/坐标回映均在库内完成； 输出直接作为 stereo_ranger 的输入（仅复用其 types.py 纯值类型）。

1.3 吊舱 ↔ PX4 桥接与 L1 航向伺服（utils/pod_bridge）

• 协议桥接（09-22 起）：protocol（表2/表3 解析）、px4_gateway（offboard 速度闭环）、 pod_serial、guidance（L2 地理引导）、run_bridge.py --dry-run 干跑入口。
• L1 航向伺服（10-09 落地，路线 A1）：吊舱角度直入——β/α 直接吃吊舱角度 （配置双路 beta_from_frame / beta_from_off_target；本版未装电机，恒用脱靶量路径）， 复用 TrackingControlLaw 的无距离降级路径；bridge.set_heading_servo_enabled() 支持运行时 L1/L2 切换（切换即 reset 清积分，防输出跳变）。
• 硬件结论（厂商答复 + 实测）：本吊舱不允许二次开发；无激光 → 表4 永不出， 目标坐标改走地面注入；0x0F 自动锁定是常驻模式（0x0E 只停当次，0x08 才退出识别）； bit2 锁定位目标丢失后不复位，必须加第二判据（我方视觉）。
• S1 台架标定已完成（10-09）：beta_sign=+1、alpha_sign=-1 已回填 pod_bridge.json，并有标定回归测试守护（test_deployed_config_has_calibrated_signs）。
• 配套工具：virtual_pod（模拟吊舱，无电机语义）、verify_px4（仅飞控验证，增量④）、 pod_sitl_test.py（L1 SITL 全流程）。

1.4 预定流程全链路（utils/task_runner，10-12 落地）

「地面给坐标 → 天空解锁/接受坐标引导/追踪打击」全链路，已在 PX4 SITL 端到端跑通（约 1m24s）：

模块	文件	作用
任务状态机	utils/task_runner/state_machine.py	6 状态纯逻辑转移：WAIT→ARM_TAKEOFF→GOTO(L2)→TRACK(L1)→APPROACH→RTL
编排器	utils/task_runner/runner.py	状态机驱动 + 快照采集 + 状态动作（起飞/切律/返航）
日志模块	utils/task_runner/log.py	事件 JSONL + 遥测 CSV 双层结构化日志
吊舱控制	utils/task_runner/pod_control.py	真机吊舱识别/锁定指令（0x07/0x0F/0x0E/0x08）
地面注入	utils/pod_bridge/ground_link.py	UDP 接收地面站坐标（超龄判无效，替代表4）
SITL 入口	task_runner_sitl.py	仿真全流程（VirtualPod + 虚拟目标）
真机入口	task_runner_real.py	真串口吊舱 + UDP 注入 + 吊舱控制
地面站	ground_station/	坐标注入 + 状态可视化（Flask）

1.5 测试

483 条用例全部通过（实测，2026-10-13）：

测试组	用例数	覆盖内容
tests/stereo_ranger	111	规格 §11.4 构件级 + 全流程
tests/visual_track_control	86	对应 C++ gtest + L1 角度直入增量
tests/pod_bridge	173	协议/网关/桥接/L1 + virtual_pod/ground_link
tests/task_runner	49	状态机/编排器/日志/吊舱控制
tests/stereo_yolo	36	假检测器驱动
tests/target_tracker	28	对应 C++ gtest 用例
合计	483	较 09-15（256）新增 227

• stereo_ranger / stereo_yolo 测试不需要真实图像、模型权重或硬件。
• ⚠ codegraph 报告 AssociateDetections / SelectPrimary 等“无测试”属调用图误报，勿据此判断。

1.6 仿真 / 演示

脚本	内容	结果
utils/demo_track_control.py --speedup 10	模拟检测 → 追踪 → 控制律 → 发送，20 Hz 时间线	✅
utils/demo_stereo_ranger.py	合成框对，六场景	✅
utils/demo_stereo_yolo.py	真模型推理 + 合成素材五场景	✅
task_runner_sitl.py（PX4 SITL）	预定流程全链路 6 状态 + 地面站联动	✅ 端到端跑通（10-12，约 1m24s）

• SITL 集成脚本：test.py（视觉闭环早前版本）/ pod_sitl_test.py（L1 吊舱版）已就位； 当前全流程实跑走 task_runner_sitl.py。

1.7 文档与索引

• docs/ 现有 10 份：双目测距技术路线、双目 YOLO 需求说明、视觉跟踪控制律技术路线、 视觉追踪技术路线、物理追踪思路、吊舱解算验证方案（模拟飞控喂表3）、树莓派 4B 部署注意事项、 双目相机模组到位作业指导、L1 航向伺服实现方案、光电吊舱控制协议 G 版-PB（docx）。
• 根目录：预定流程.md（需求）+ 预定流程-操作指南.md（操作指南与待办，链路权威）。
• .workbuddy/memory/ARCHITECTURE.md + MEMORY.md：完整架构参考与精简铁律。
• .codegraph/ 索引 140 文件 / 2337 节点，可直接 codegraph 查询。
• 相机标定已起步：根目录 camera.py（棋盘格采集脚本）+ stereo_calib_params.npz（未入库）。

---

2. 未完成工作

2.1 真机增量验证（P0，实飞前必须）

按 预定流程-操作指南.md §2.4 逐级进行，每级过了再进下一级： ② 串口回环 → ③ 仅吊舱干跑（验 β→yaw_rate 符号/量级）→ ④ 仅飞控（verify_px4）→ ⑤ 地面联调（task_runner_real.py）。

2.2 数值参数未标定（阻塞飞行决策）

• 预定流程链路：switch_radius_m / center_threshold_deg / center_hold_s / takeoff_altitude_m 与 heading.gain、guidance.speed_kp/yaw_kp 均为占位 （beta_sign/alpha_sign 已按 S1 标定回填）；标定回填前不得实飞。
• utils/config/stereo_ranger.json 几何参数为占位；解禁路径见 docs/双目相机模组到位作业指导.md P0→P6（已起步标定采图，未走完）。

2.3 任务级状态机规格对齐

• 「预定流程」版状态机（6 态）已实现并 SITL 跑通；
• 但 docs/物理追踪思路.md 引用的 S5~S8 版规格（docs/状态机设计.md 等）仍缺失， 两套状态集是否对齐/合并需总项目侧确认（见 §3.1）。

3. 阻塞项与风险

3.1 本仓库缺失 4 份被引用的上游规格

docs/物理追踪思路.md 引用了下列文档，但它们在本仓库不存在（应在总项目或飞控工程侧）：

被引文档	被引内容	影响
docs/状态机设计.md	S6/S7/S8 切换守卫、§4.2 目标丢失转移、§7 策略接口	S5~S8 版状态机与「预定流程」版对齐
docs/感知与避障设计.md	标定流程、稳定锁定、雷达关联、降级原则	阻塞 S8 障碍接管与雷达联动
docs/系统架构设计.md	数据流、控制单出口、时间与控制周期	影响状态机与控制律的接线方式
docs/需求分析.md	FR-034/FR-044/FR-051、NFR-007	需求追溯无法本地闭环

另 docs/开发进度.md（总项目开发进度）亦被引用，本仓库没有。

3.2 C++ 侧未复跑

reference-c++/target_tracker 与 visual_track_control 下均无 build/ 目录， 未构建、未执行 ctest。C++ 测试用例文件齐全（11 个）， 需先 cmake .. && make && ctest。若以 Python 侧为验证基准，此点可暂不处理。

3.3 环境不一致（可立即修）

utils/README.md 声明 conda env pytorch（D:\program file\conda\envs\pytorch）， 但实测该环境 pytest 缺失；全部测试通过隔离 venv （C:\Users\yimiao\.workbuddy\binaries\python\envs\drone-test，基于该 conda 解释器 --system-site-packages 仅加装 pytest）完成，未改动 conda 环境。 建议择机 pip install pytest 回填，使 README 与实际一致。

3.4 真机安全红线

标定回填前不得实飞；S3 起必须：不装桨 / 空旷场地 / RC 随时可切手动 / 有人值守。

3.5 帧周期算力不可外推

stereo_yolo 实测帧周期 25~35 ms 为台架开发机数据，与 30 fps 预算同量级， 结论不可外推到机载平台。

---

4. 下一步（建议顺序）

1. 真机增量验证 ②~⑤——对齐 预定流程-操作指南.md §2.4，③ 干跑优先， 先把 β→yaw_rate 符号/量级钉死。
2. 占位参数标定回填——状态机 4 项 + L1/L2 增益。
3. P1：摄像头接真视频流；TaskStateConfig 外置 JSON；地面站与 runner 实时打通。
4. P2：.gitignore 补齐（logs/、__pycache__/、.codegraph/ 等）；conda 回填 pytest； C++ cmake && ctest。
5. 相机模组到位后按作业指导走 P0→P6；确认 §3.1 四份上游规格可获取位置。

---

5. 验证命令（实测所用）

# Python 全部测试（483 条）
cd "D:/ProgramData/code_drone-test/utils"
"C:/Users/yimiao/.workbuddy/binaries/python/envs/drone-test/Scripts/python.exe" -m pytest -q

# 三个演示
"C:/Users/yimiao/.workbuddy/binaries/python/envs/drone-test/Scripts/python.exe" demo_track_control.py --speedup 10
"C:/Users/yimiao/.workbuddy/binaries/python/envs/drone-test/Scripts/python.exe" demo_stereo_ranger.py
"C:/Users/yimiao/.workbuddy/binaries/python/envs/drone-test/Scripts/python.exe" demo_stereo_yolo.py

# SITL 全流程 / 地面站联动 / 真机：见 预定流程-操作指南.md §五「一键命令汇总」

---

6. 一页状态汇总

工作项	状态	备注
C++ target_tracker → Python	✅ 完成	28 条用例
C++ visual_track_control → Python	✅ 完成	86 条（含 L1 增量）
stereo_ranger 双目测距	✅ 完成	111 条；几何参数待标定
stereo_yolo 检测前端	✅ 完成	36 条；真实素材待联调
三路 demo 仿真验证	✅ 完成	—
pod_bridge 桥接 + L1 航向伺服	✅ 完成（10-09）	S1 符号已标定；增益待标
预定流程全链路（task_runner）	✅ SITL 跑通（10-12）	已提交 ded17d7
真机增量验证 ②~⑤	❌ 未开始	P0；实飞前必须
状态机/L1/L2 占位参数标定	❌ 未开始	回填前不得实飞
S5~S8 版状态机（物理追踪思路）	⚠ 规格缺失	待对齐（§3.1）
相机模组标定 P0~P6	⏳ 起步	camera.py 采集中
C++ 侧构建与 ctest	⚠ 未执行	无 build 目录
conda 环境回填 pytest	⚠ 待办	测试现走隔离 venv