# 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 部分并行。

- [ ] **Pydantic**：`FlightIntentPayload` / `FlightIntentAction` 按文档收紧；`args` 用 discriminated union 或分类型模型。
- [ ] **`_validate_flight_intent`**（或等价）：白名单、`goto.frame`、`wait.seconds` 范围、`takeoff.relative_altitude_m`。
- [ ] **`main_app` 执行路径**：在 `ROCKET_CLOUD_EXECUTE_FLIGHT=1` 时：
  - 对 **`wait`**：本地 `asyncio.sleep` / 线程计时 + 可取消；或 **仅转发** 给桥（若桥统一执行整段 `actions`，客户端可只发包）。
  - 补齐 **`goto` / `return_home` / `takeoff`（非关键词起飞）** 与 Socket 或「整包 intent」的映射策略（二选一写死，避免双轨混乱）。
- [ ] **日志**：打印 `trace_id`、逐步 `action` 索引与结果。
- [ ] **单测**：解析 + 校验 + 小粒度映射。

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

---

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

- [ ] **进程边界**：定 API（ROS Topic 服务 / 同机 TCP JSON / 二者兼有）。
- [ ] **执行器**：单队列顺序执行 §10.3 行为表；每步 **超时**、**完成判定**（订阅 `vehicle_status` / `local_position` 等）。
- [ ] **翻译实现**：
  - `takeoff` / `land` / `return_home` / `hover`：`VehicleCmd` / SetMode 等。
  - `goto`：Offboard setpoint 路径 **或** 航点 mission（与阶段 0 选型一致）；`body_ned` → NED 旋转在桥内完成。
  - `wait`：仅本地计时 + 遥测巡检。
- [ ] **安全**：L4（解锁、定位、电量、围栏）；急停清空队列；`wait` 中异常触发 RTL/LAND（产品定）。
- [ ] **回执**：`flight_intent/result` 或日志结构化事件（success / rejected / aborted + 步号 + reason）。

**产出**：桥包 + launch 示例；SITL 录屏或自动化脚本一条 command 跑通示例 §7.2。

---

## 阶段 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 修订同步更新本计划中的阶段勾选与工期估算。