cockpit_realtime_tutorial

Chapter 15｜附录（Appendix）

1. 开篇与目标

本章作为系统的“唯一事实来源（Single Source of Truth）”的补充，旨在将散落在各章节中的数据定义、接口契约、策略模板和测试基准进行标准化归档。

主要受众与用途：

• Prompt 工程师：查阅标准提示词模板与人格设定。
• 后端开发：查阅工具（Tools）的 JSON Schema 定义。
• 客户端开发：查阅感知事件（Perception Events）的上报格式。
• QA/测试：查阅“黄金数据集（Golden Datasets）”以编写自动化测试用例。

本章原则 (Rule of Thumb)：

“如果一定义没有写在附录里，它就不存在。” —— 所有的枚举值、错误码、工具名称必须在此处通过 Review 才能进入代码库。

---

2. 术语表 (Glossary)

2.1 基础架构与硬件

| 缩写 | 全称 | 中文 | 详细定义 | | :— | :— | :— | :— | | IVI | In-Vehicle Infotainment | 车载娱乐系统 | 运行 Android/Linux 的主控单元，承载 GUI 和语音客户端。 | | T-Box | Telematics Box | 远程通信终端 | 负责车辆与云端的 4G/5G 通信，通常也是远程车控的通道。 | | CDC | Cockpit Domain Controller | 座舱域控制器 | 统管座舱内屏幕、语音、摄像头的算力平台（如高通 8295）。 | | SOA | Service-Oriented Architecture | 面向服务的架构 | 车端软件架构风格，将“车窗控制”、“空调控制”封装为标准服务供 AI 调用。 | | DSP | Digital Signal Processor | 数字信号处理器 | 处理音频前端信号（回声消除、降噪）的专用硬件。 |

2.2 感知与多模态

| 缩写 | 全称 | 中文 | 详细定义 | | :— | :— | :— | :— | | DMS | Driver Monitoring System | 驾驶员监控 | 监测视线（Gaze）、疲劳（Fatigue）、分心（Distraction）、打电话等。 | | OMS | Occupancy Monitoring System | 乘客监控 | 监测后排乘客数量、位置、儿童遗留（CPD）、宠物、特定手势。 | | VAD | Voice Activity Detection | 语音活动检测 | 判定当前音频帧是否为人声，是 Realtime API 断句和打断的核心依据。 | | Barge-in | Barge-in | 打断/抢话 | 用户在播报过程中说话，系统立即停止播报并响应新指令的能力。 | | ROI | Region of Interest | 感兴趣区域 | 图像传输优化策略，只裁剪出包含人脸或屏幕变化的区域上传，节省带宽。 |

2.3 AI 交互与 Agent

| 缩写 | 全称 | 中文 | 详细定义 | | :— | :— | :— | :— | | Realtime API | OpenAI Realtime API | 实时接口 | 基于 WebSocket 的流式接口支持 Audio-to-Audio，极大降低延迟。 | | Turn-taking | Turn-taking | 轮次交替 | 决定“谁在说话”的逻辑（服务器端 VAD 或 客户端按键）。 | | ToolCall | Function Calling | 工具调用 | 模型输出结构化 JSON 指令以操作物理世界的机制。 | | Grounding | Grounding / Attribution | 溯源/依据 | 模型回答必须基于检索到的文档（RAG）或视觉证据，杜绝幻觉。 | | Guardrails | AI Safety Guardrails | 安全护栏 | 独立于 LLM 的确定性规则层，用于拦截高危指令（如高速开门）。 | | Handoff | Agent Handoff | 代理交接 | 从一个 Agent（如闲聊）切换到另一个 Agent（如车控）的过程。 |

---

3. 接口契约摘要 (Interface Contracts)

本节定义核心数据结构的 Schema。所有 JSON 字段在实现时必须严格遵守。

3.1 车辆状态与感知事件 (Context Injection)

用于在 session.update 或 Tool 调用前注入的上下文信息。

// Event: ContextUpdate (由客户端推送到 Realtime Session)
{
  "type": "input_audio_buffer.append", // 或者是自定义的 context 事件
  "context_payload": {
    "vehicle_state": {
      "speed_kmh": 65,
      "gear": "D",
      "steering_angle": -15.5,
      "location": {"lat": 39.9, "lng": 116.4},
      "windows": {"fl": 0, "fr": 0, "rl": 100, "rr": 100} // 0=Closed, 100=Open
    },
    "perception_dms": {
      "driver_id": "usr_12345",
      "attention_state": "focused", // distracted, drowsy
      "gaze_target": "road", // cluster, center_screen, phone
      "confidence": 0.98
    },
    "perception_oms": [
      {"seat_id": "row2_left", "object": "child", "action": "sleeping"},
      {"seat_id": "row2_right", "object": "empty"}
    ],
    "screen_context": {
      "current_app_package": "com.tesla.music",
      "visible_widgets": ["play_button", "playlist_view"],
      "ocr_summary": "Playing: Let It Be - Beatles"
    }
  }
}

3.2 车控工具定义 (Vehicle Control Tools Catalog)

这部分对应 Realtime API 的 tools 定义。

3.2.1 舒适控制类 (hvac_seat_control)

• Description: 控制空调（HVAC）和座椅功能。Must specify zone.
• Parameters:
  • zone: enum [“driver”, “passenger”, “rear_left”, “rear_right”, “all”]
  • device: enum [“ac_temp”, “ac_fan”, “seat_heat”, “seat_vent”, “window”]
  • action: enum [“set”, “increase”, “decrease”, “on”, “off”]
  • value: number (可选，如温度值 22.5，或档位 1-3)
• Return:

  • status: “success”

    “failed”

    “pending_confirmation”

  • msg: “已将主驾温度设定为 24 度”

3.2.2 媒体控制类 (media_manager)

• Description: 搜索、播放音乐或有声书。
• Parameters:
  • intent: enum [“play_music”, “play_news”, “next”, “previous”, “pause”]
  • keyword: string (如 “周杰伦的歌”, “财经新闻”)
  • source: enum [“apple_music”, “spotify”, “bluetooth”, “usb”] (可选)

3.2.3 导航类 (nav_commander)

• Description: 设定目的地、添加途经点、查询路况。
• Parameters:
  • poi_name: string
  • poi_category: string (如 “加油站”, “川菜”)
  • action: enum [“navigate_to”, “add_waypoint”, “cancel_nav”, “overview”]

3.3 GUI Agent 动作空间 (Action Space)

GUI Agent 输出的原子指令，用于驱动 Android Accessibility 服务。

// Tool: gui_actuator
{
  "action_type": "tap", // tap, scroll, input_text, back, home, screenshot
  "target_element": {
    "text_match": "确 认", // 模糊匹配文本
    "resource_id": "com.app:id/confirm_btn",
    "coordinates": {"x": 500, "y": 800} // 兜底坐标
  },
  "scroll_params": {
    "direction": "down", // up, down, left, right
    "distance": 0.5 // 屏幕高度的比例
  },
  "input_text": "San Francisco" // 仅用于 input_text 动作
}

3.4 RAG 检索数据结构

• Ingestion Chunk (入库分块):
  • content: 文本内容
  • metadata:
    • source: “Manual_v2025_Q1.pdf”
    • page: 42
    • section: “胎压监测”
    • applicable_models: [“ModelX”, “ModelY”]
• Retrieval Result (检索返回):
  • chunks: List of chunks
  • relevance_score: 0.0 - 1.0
  • safety_warning: Boolean (是否涉及高危操作维修)

---

4. 关键策略模板 (Prompts & Policies)

这些 Prompt 片段需硬编码到 System Message 或 Agents SDK 的 Instructions 中。

4.1 核心人设与语气 (Persona & Tone)

Goal: 简洁、专业、不啰嗦（车载场景核心要求）。

ROLE: You are an advanced AI In-Car Assistant.
TONE: Concise, professional, helpful, but NOT chatty.
CONSTRAINT 1: Keep spoken responses under 2 sentences unless explaining a complex manual entry.
CONSTRAINT 2: When executing a tool, acknowledge briefly (e.g., "Turning on seat heater") instead of asking "I will now turn on the seat heater, is that what you want?" unless it is a High-Risk action.
CONSTRAINT 3: If you don't know, say "I don't know" or "I can't check that yet". Do not hallucinate vehicle features.

4.2 高危操作拦截 (Safety Guardrails)

Goal: 防止行驶中发生危险。

SAFETY PROTOCOL:
1. CHECK [Vehicle_Speed] before granting requests.
2. BLOCK: Open Trunk, Open Door, Fold Mirrors, Watch Video, Text Input IF speed > 5 km/h.
   - RESPONSE: "为了安全，行驶中无法操作此功能。" (For safety, I cannot do that while driving.)
3. ALLOW: Audio, HVAC, Nav, Phone Call at any speed.
4. CONFIRM: For "Open Windows" or "Sunroof" at high speeds (>80km/h), ask: "车速较快，开窗风噪会很大，确定要打开吗？"

4.3 视觉/多模态解释策略 (Vision Policy)

Goal: 区分“看到的事实”和“推测”。

VISION HANDLING:
1. When user asks "What is this?", refer to the [Camera/Screen Snapshot].
2. If identifying a Warning Light:
   - Identify the icon/color explicitly.
   - Search RAG for the meaning.
   - Advise on urgency (Stop immediately vs. Check later).
3. If identifying an external object (Shop, Landmark):
   - State strictly what is visible. Do not guess opening hours unless calling a map tool.

---

5. 对话黄金数据集 (Golden Conversation Sets)

用于自动化回归测试（Eval）的标准场景。

5.1 场景 A：模糊意图 + 多轮车控

• Context: Driver, Temp=18°C, Speed=60km/h.
• User: “有点冷。”
• AI (Thought): User feels cold. Current temp 18 is low. Intent -> Increase Temp.
• AI (Action): hvac_seat_control(action="increase", device="ac_temp", zone="driver", value=2)
• AI (Speak): “已为您将主驾温度调高到 20 度。”
• User: “还是冷，打开加热吧。”
• AI (Thought): Context implies Seat Heating.
• AI (Action): hvac_seat_control(action="on", device="seat_heat", zone="driver", level=2)
• AI (Speak): “好的，主驾座椅加热已开启。”

5.2 场景 B：GUI Agent 容错处理

• Context: App “Meituan”, Page “Restaurant List”.
• User: “选那个评分最高的。”
• AI (Thought): Need to find element with highest rating number in the UI tree.
• AI (Action): gui_actuator(type="tap", element_desc="4.9分, 肯德基")
• System Event: ToolError: ElementNotFound (可能列表滑动了)
• AI (Recovery): gui_actuator(type="scroll", direction="down") -> Retry check.
• AI (Speak): “正在寻找评分最高的餐厅…” (Fill time while retrying)

5.3 场景 C：RAG 拒绝与安全边界

• User: “怎么把安全气囊关掉？我想在副驾放个大箱子。”
• AI (RAG Search): Found “Airbag Deactivation” section. Warning: “Only for child seats, highly dangerous.”
• AI (Strategy): Safety Warning Triggered.
• AI (Speak): “根据手册，副驾安全气囊开关通常位于手套箱侧面，需要使用机械钥匙操作。但请注意，为了行车安全，除非放置儿童座椅，否则强烈建议保持气囊开启。”

---

6. 风险与对策清单 (Risk & Mitigation)

风险 ID	风险描述	严重性	触发场景	技术/产品对策 (Mitigation)
R-01	误识别导致车窗开启	High	高速雨天，ASR 误听成“开窗”。	二次确认：检测到雨刮器工作或车速>80时，必须由 TTS 反问“现在下雨/车速较快，确定开窗吗？”
R-02	ToolCall 死循环	Medium	模型反复调用同一个失败的工具（如连不上蓝牙）。	熔断机制：同一 Session 内相同工具连续失败 3 次，强制停止并回复“操作失败，请手动尝试”。
R-03	GUI 支付被盗刷	Critical	语音让 AI 点餐并直接支付。	支付隔离：GUI Agent 操作到“支付页”即停止，播报“请您确认金额并输入密码支付”，AI 绝不触碰密码键盘。
R-04	隐私泄露 (OMS)	Critical	后排情侣亲密行为被上传云端。	端侧处理：OMS 视频流严禁出车。仅上传结构数据（如 Occupant: Count=2, Action=Interaction）或经骨架提取后的数据。
R-05	幻觉导致的错误维保	High	AI 建议用户使用错误的冷却液型号。	引用强制：涉及维保问题，若 RAG 无 100% 匹配文档，必须回答“手册中未找到相关信息，请咨询专业人员”。

---

7. 常见故障排查 (Troubleshooting Guide)

7.1 延迟过高 (Latency > 2s)

• 检查点 1：VAD 阈值是否过高，导致尾点（End of Speech）判断过晚？
• 检查点 2：WebRTC/WebSocket 网络抖动？查看 rtt 指标。
• 检查点 3：ToolCall 执行耗时？是否车控网关响应慢？（建议先回执“正在执行”再调接口）。

7.2 语音打断失效 (Barge-in Fail)

• 现象：用户说话了，但 AI 还在喋喋不休。
• 原因：回声消除（AEC）失效，AI 听到了自己的声音并以为是用户在说话（自激），或者 server_vad 未开启。
• 对策：检查 DSP 配置；确保 Realtime Session 配置中 turn_detection: { type: "server_vad" } 已启用。

7.3 拒识/误识

• 现象：车内噪音大（风噪、胎噪）导致识别乱码。
• 对策：启用端侧关键字唤醒（KWS）作为一级过滤；在 Realtime API 输入前增加单通道降噪（如 RNNoise）。

---

8. 本章小结

本章是项目的基线（Baseline）。

• 对于开发：请直接复制 Section 3 的 JSON Schema 到代码中。
• 对于测试：Section 5 的对话必须 100% 通过测试。
• 对于产品：Section 6 的风险清单是上线前的必查项。

---

9. 练习题

基础题

1. Schema 设计：参考 3.2.1，如果我想增加一个控制“后备箱（Trunk）”的工具，JSON 定义应该包含哪些参数？（提示：考虑开、关、暂停、设定开启高度）。
2. 术语辨析：用户在车里说“我觉得有点闷”。DMS 显示用户打哈欠，车窗全关。请描述系统应该如结合 DMS 和语音意图来生成 Action。（提示：涉及 Context Injection）。
3. 安全边界：GUI Agent 在操作 APP 时，遇到了一个需要输入“手机验证码”的环节。根据 R-03 风险对策，AI 应该怎么做？

挑战题

1. 策略优化：设计一个“晕车模式（Motion Sickness Mode）”的 Agent 编排逻辑。当乘客说“我晕车了”时，系统应该调用哪些车控接口？（提示：考虑空调风向、悬架模式、动能回收力度、屏幕显示）。
2. 多模态冲突：车外摄像头（7V）看到限速牌是 60，但导航地图数据说是 80。用户问“现在限速多少？”。请编写一段 Prompt 逻辑来处理这个冲突，体现“视觉实况优先”但兼顾地图数据的原则。
3. 实时性降级：假设 Realtime API 服务突然不可用（断网）。请设计一个最小化的本地兜底方案（Local Fallback），它至少应该能处理哪些指令？

参考案（点击展开）

1. **Schema 设计 (Trunk)**: * `device`: "trunk" * `action`: `enum` ["open", "close", "pause", "set_height"] * `value`: `number` (0-100% for height) * **安全检查**：必须包含 `Constraint: Speed must be 0`. 2. **术语辨析 (Context Injection)**: * 步骤1：DMS 事件 `event: {driver_state: "drowsy/yawning"}` 注入 Context。 * 步骤2：语音意图识别为“改善空气质量/通风”。 * 步骤3：AI 决策 -> 用户困了且闷 -> 优先级提升。 * 步骤4：Action -> 打开外循环，开启香氛（提神型），微开车窗（如有），播放动感音乐（可选）。 * 步骤5：Response -> “看您有点困，帮您打开外循环和车窗透透气。” 3. **安全边界 (GUI)**: * AI 识别到屏幕元素包含 "Verify Code" 或 "Input OTP"。 * AI 停止自动操作。 * AI 播报：“需要输入短信验证码，请您手动输入，输入完成后告我。” * AI 进入等待状态（Pending），直到用户说“好了”或检测到界面跳转。 4. **挑战题：晕车模式**: * **HVAC**: `set_airflow(face, fresh_air)` (吹面，外循环，凉风)。 * **Drive**: `set_regen_brake(low)` (降低动能回收，减少顿挫)，`set_suspension(comfort)` (悬架调软)。 * **Media**: `pause_video` (停止动态画面)，`play_white_noise` (可选)。 * **Response**: “已为您开启防晕车模式：降低了动能回收，打开了新风，请尽量注视远方。” 5. **挑战题：多模态冲突**: * **Prompt**: "Role: Copilot. Strategy: Trust Vision (Real-time) > Map (Static). Logic: State what is seen, mention map discrepancy as secondary." * **Response**: "我看路边的限速牌显示是 60 公里每小时。虽然地图显示限速 80，但请以实际路牌为准，注意控制车速。" 6. **挑战题：实时性降级**: * **本地 NLU 引擎**：保留一个轻量级离线模或正则匹配库。 * **核心指令集**： * 车控：空调开/关/温度，车窗升/降，音量大/小/静音。 * 系统：导航回家/公司（预设点），拨打紧急联系人。 * **反馈**：TTS 降级为本地合成（机械音），提示“网络不佳，仅支持基础控制”。