# 客户端上报：PX4 载具上下文（`session.start.client.px4`）

云端 LLM 需要知道**你在控哪一类 PX4 载具、当前能力边界**，才能把口语「往前十米、返航、降落」消歧成稳定的高层 `flight_intent`，避免把固定翼/VTL 按多旋翼瞎猜。

本字段**全部可选**；不传则 `vehicle_class` 在模型侧按 `unknown` 处理，summary 里会更保守。建议在机端能取到的情况下**至少上报 `vehicle_class`，其次 `mav_type`**。

---

## 1. 建议优先级

| 优先级 | 字段 | 说明 |
|--------|------|------|
| P0 | `vehicle_class` | 粗粒度机型，见 §3 |
| P1 | `mav_type` | `HEARTBEAT.mav_type`，与机载一致 |
| P2 | `home_position_valid`、`rtl_available` | 影响「返航」是否可信 |
| P2 | `offboard_capable` | 影响含 Offboard/机载接管的语义 |
| P3 | `current_nav_state` | 当前 NAV_STATE / 可读模式名，消解「继续飞」等 |
| P3 | `default_setpoint_frame` | `goto` 默认用 `local_ned` 还是 `body_ned` 等 |
| P4 | `px4_version`、`airframe_id`、`cruise_alt_m_agl`、`extras` | 排障、高度尺度、自定义 |

---

## 2. JSON 示例（`session.start` 片段）

```json
{
  "type": "session.start",
  "proto_version": "1.0",
  "transport_profile": "text_uplink",
  "session_id": "...",
  "auth_token": "...",
  "client": {
    "device_id": "drone-01",
    "locale": "zh-CN",
    "capabilities": {
      "playback_sample_rate_hz": 24000,
      "prefer_tts_codec": "pcm_s16le"
    },
    "px4": {
      "vehicle_class": "multicopter",
      "mav_type": 2,
      "px4_version": "1.14.3",
      "airframe_id": "px4_generic_quad",
      "default_setpoint_frame": "local_ned",
      "offboard_capable": true,
      "mission_capable": true,
      "rtl_available": true,
      "home_position_valid": true,
      "current_nav_state": "POSITION",
      "cruise_alt_m_agl": 30.0,
      "extras": {
        "gps_ok": true,
        "ekf_ok": true
      }
    }
  }
}
```

服务端在 `session.ready.server_caps` 中带 `accepts_px4_vehicle_profile: true` 表示会消费该块并注入系统提示词。

---

## 3. `vehicle_class` 枚举（字符串）

与 PX4 常见机架大类对齐，客户端任选其一（**小写 + 下划线**）：

| 值 | 典型 PX4 / MAV 场景 |
|----|---------------------|
| `multicopter` | 四旋翼、六旋翼等 |
| `fixed_wing` | 固定翼 |
| `vtol_standard` | 标准尾座/倾转等 VTOL |
| `vtol_tailsitter` | 尾座 VTOL |
| `rover` | 地面车 |
| `boat` | 水面艇 |
| `submarine` | 水下（若业务用到） |
| `other` | 其它或少见构型 |
| `unknown` | 未知（默认） |

---

## 4. `mav_type`（可选，整数）

可直接填 **MAVLink `HEARTBEAT` 的 `mav_type` 原值**，便于与 QGC / MAVSDK 对齐。常见示例（完整表见 [MAV_TYPE](https://mavlink.io/en/messages/common.html#MAV_TYPE)）：

| 值 | 含义 |
|----|------|
| 1 | 固定翼 |
| 2 | 四旋翼（quad） |
| 3 | 六旋翼 |
| 10 | 地面车 |
| 11 | 水面船 |
| 19 | 双足/仿人（少见） |
| 20 | 尾座 VTOL |
| 21 | 六旋翼同轴等 |
| 22 | 三旋翼 |

若同时提供 `vehicle_class` 与 `mav_type`，模型以二者**一致性强**为前提；明显冲突时以 **`mav_type` 为准**（可在 `extras` 里注明数据来源）。

---

## 5. `default_setpoint_frame`

口语「前/右/上」在未说明坐标系时，云端生成 `goto` 会**优先用此字段**：

- **`local_ned`**（默认）：北东地局部系，与多数 Offboard 位置设定一致。
- **`body_ned` / `body`**：机体系前右下 —— 仅当机端确实按体轴解析相对位移时填写。

---

## 6. `extras`

任意 JSON 对象，原样进入 LLM 上下文（控制「电池低」「室内无 GPS」「仅限 mission」等）。建议键名短、值可机器生成。

---

## 7. 与 MAVROS / ROS2 的对应关系（实现提示）

- `mav_type`、`current_nav_state`：可由 MAVROS `/mavros/state` 或 `px4_msgs` 等价话题映射得到。  
- `home_position_valid`：`HOME_POSITION` 已设置或与 `RTL` 可用逻辑一致即可。  
- `offboard_capable`： companion 侧已验证能 **≥2Hz** 维持 Offboard 再置 `true`（见 PX4 Offboard 文档）。

本文不规定机端如何执行 JSON；执行栈仍以贵方 MAVROS / 自研 bridge 为准。