# Flight Intent v1 + 伴飞桥 — 实施计划

本文档与 [`FLIGHT_INTENT_SCHEMA_v1.md`](FLIGHT_INTENT_SCHEMA_v1.md) 配套，描述从协议闭环到 ROS/PX4 可控的**分阶段交付**。顺序建议按阶段 0→4；各阶段内任务可并行处已标注。

---

## 目标与验收标准

| 维度 | 验收标准 |
|------|-----------|
| **协议** | 云端下发的 `flight_intent` 满足 v1：含 `wait`、`takeoff` 可选高度、`trace_id`；L1–L3 校验可自动化 |
| **语音客户端** | 能解析并记录完整 `actions`；在 `ROCKET_CLOUD_EXECUTE_FLIGHT=1` 时通过 Socket/桥 执行或与桥约定本地执行 `wait` |
| **桥** | 顺序执行 `actions`，每步有超时/失败策略；可对接 MAVROS（或既定 ROS 2 栈）驱动 PX4 |
| **安全** | 执行前 L4 门禁、执行中可中断、急停路径明确 |
| **回归** | SITL 或台架可重复跑通「起飞 → 悬停 → wait → 降落」等示例 |

---

## 阶段 0：对齐与基线（约 0.5～1 天）

- [ ] 全员精读 `FLIGHT_INTENT_SCHEMA_v1.md`，冻结 **v1 白名单**（`type` / `args` 键）。
- [ ] 确认伴飞侧技术选型：**ROS 2 + MAVROS**（或 `px4_ros_com`）与默认 **AUTO vs Offboard** 策略（写入桥 YAML，不写进 JSON）。
- [ ] 盘点现有 **Socket 服务**：是否即「桥」或仅转发；是否需新进程 `flight_intent_bridge`。
- [ ] 建立 **trace_id** 在日志中的格式（云端 / 语音 / 桥统一）。

**产出**：架构一页纸（谁消费 WebSocket、谁连 PX4）、桥配置模板路径约定。

---

## 阶段 1：协议与云端（可与阶段 2 并行，约 2～4 天）

- [ ] **Schema 校验**：服务端对 `flight_intent` 做 L1–L3（必要时 L4 占位）；非法则 `routing=error` 或产品协议兜底。
- [ ] **LLM 提示词**：只允许 §3.7 中 `type` 与允许键；强调 **时长必须用 `wait`**，禁止用 `summary` 控机。
- [ ] **示例与回归用例**：固定 JSON golden（§7.1～§7.3 + 边界：首步 `wait`、`seconds` 超界、多余 `args` 键）。
- [ ] **可选 `trace_id`**：服务端生成或在 bundle 层透传。

**产出**：校验测试集、提示词 MR、发布说明（对客户端可见的字段变更）。

---

## 阶段 2：语音客户端（`voice_drone_assistant`）（约 3～5 天）

可与阶段 1、3 部分并行。

- [x] **Pydantic**：`voice_drone/core/flight_intent.py`（v2）按 v1 文档收紧动作与 `args`。
- [x] **`parse_flight_intent_dict`**：等价 L1–L3 + 首步禁止 `wait`；白名单、`goto.frame`、`wait.seconds`、`takeoff.relative_altitude_m`。
- [x] **`main_app`**：`ROCKET_CLOUD_EXECUTE_FLIGHT=1` 时在后台线程 **`_run_cloud_flight_intent_sequence`** 顺序执行；`wait` 用 `time.sleep`；`goto` **单轴** 映射 Socket `Command`；`return_home` 已入 `Command`；**含 `takeoff` 的序列**在 offboard 完成后继续后续步（不再丢失）。
- [x] **日志**：序列开始时打印 `trace_id`；`takeoff` 打相对高度提示（offboard 是否消费须自行接参数）。
- [x] **单测**：`tests/test_flight_intent.py`（无完整依赖时 goto 用例自动 skip）。

**产出**：MR 合并后，本地无 PX4 也能跑通解析与 mock 执行。

---

## 阶段 3：伴飞桥 + ROS/PX4（约 5～10 天，视现网复用程度）

- [x] **进程边界（首版）**：独立 ROS1 节点，订阅 `std_msgs/String` JSON；见 **`docs/FLIGHT_BRIDGE_ROS1.md`**、`scripts/run_flight_intent_bridge_ros1.sh`。
- [x] **执行器（首版）**：`voice_drone/flight_bridge/ros1_mavros_executor.py` 单线程顺序执行；`takeoff/goto` 带超时；`land/rtl` 等待 disarm 超时。
- [x] **翻译实现（首版 / MAVROS）**：
  - `takeoff` / `hover` / `wait` / `goto`：`/mavros/setpoint_raw/local`（Offboard）+ `set_mode` / `arming`。
  - `land` / `return_home`：`AUTO.LAND` / `AUTO.RTL`。
- [ ] **安全**：L4（电量、围栏、急停 topic）；`wait` 中异常策略。
- [ ] **回执**：result topic / 与 `main.py` 的 topic 串联。
- [ ] **ROS2 / 仅 TCP 无 ROS**：按需另起接口。

**产出（当前）**：ROS1 桥可 `rostopic pub` 联调；**待** launch、与语音侧发布 JSON、SITL CI。

---

## 阶段 4：联调、硬化与发布（约 3～7 天）

- [ ] **端到端**：真机或 SITL：语音 → 云 → 客户端 → 桥 → PX4，带 `trace_id` 串 log。
- [ ] **压测与失败注入**：断 WebSocket、桥崩溃重启、Offboard 丢失等（预期行为写进运维文档）。
- [ ] **配置与门禁**：默认关闭实飞执行；仅生产镜像打开；参数与围栏双人复核。
- [ ] **文档**：更新 `PROJECT_GUIDE.md` 中「飞控路径」链接到本文与 SCHEMA。

**产出**：发布 checklist、已知限制列表（如某机型仅支持 AUTO 等）。

---

## 依赖与风险

| 风险 | 缓解 |
|------|------|
| Socket 协议与 `Command` 无法表达多步 | **推荐**由桥消费**完整** `flight_intent` JSON，客户端只负责下发一份；少步经 Socket 逐条 |
| Offboard 与 AUTO 混用冲突 | 桥配置单一「主策略」；`goto` 仅在 Offboard 就绪时接受 |
| LLM 仍产出非法 JSON | L2 硬拒绝 + 提示词回归 + golden 测试 |
| 排期膨胀 | 先交付 **AUTO 模式族 + wait + land**，再迭代复杂 `goto` |

---

## 建议里程碑（日历为估算）

| 里程碑 | 内容 |
|--------|------|
| **M1** | 阶段 0–1 完成：云校验 + 提示词 + golden |
| **M2** | 阶段 2 完成：客户端 strict 模型 + `wait` + 执行路径单一数据源 |
| **M3** | 阶段 3 完成：桥 + SITL 跑通 §7.2 |
| **M4** | 阶段 4：联调签字 + 生产策略 |

---

## 文档索引

| 文档 | 用途 |
|------|------|
| [`FLIGHT_INTENT_SCHEMA_v1.md`](FLIGHT_INTENT_SCHEMA_v1.md) | 字段、校验、桥分层、ROS 参考 |
| [`PROJECT_GUIDE.md`](PROJECT_GUIDE.md) | 仓库总览与运行方式 |
| 本文 | 任务拆解、顺序、验收 |

---

**版本**：2026-04-07；随 SCHEMA v1 修订同步更新本计划中的阶段勾选与工期估算。