cockpit_realtime_tutorial

车舱场景语音实时对话机器人设计文档（Realtime + Agents SDK）

文档类型：系统设计 / 架构设计（中文）
目标读者：车载/座舱/语音/多模态算法、后端、客户端、测试、产品、合规
最后更新：2025-12-28
技术基座：
- OpenAI Realtime API：低延迟、多模态（音频/图像/文本）输入输出，支持语音到语音；可通过 WebRTC/WebSocket/SIP 连接；会话状态与事件流驱动。:contentReference[oaicite:0]{index=0}
- OpenAI Agents SDK：面向“任务编排/工具调用/多代理模式”的代码优先 SDK，与语音 Agent 方案结合使用。:contentReference[oaicite:1]{index=1}

文件组织（目录结构）

约定：每章一个文件；章节编号与文件名一一对应。后续如需拆分子系统，可在 chapters/ 下做二级目录，但本版本先保持扁平结构。

index.md（本文件）：全局目录、阅读指南、章节结构
chapter1.md：范围与需求（What / Why）
chapter2.md：用户体验与对话交互（UX / Conversation）
chapter3.md：系统总体架构（System Architecture）
chapter4.md：Realtime 会话层设计（语音实时对话）
chapter5.md：Agents SDK 编排与多代理设计（Orchestration）
chapter6.md：RAG 检索与知识系统（Knowledge）
chapter7.md：多模态感知输入（DMS/OMS/7V/屏幕读取/音频）
chapter8.md：车控 ToolCall（座椅加热/音乐等）与权限治理
chapter9.md：GUI Agent（车载 App 点餐/购物/预约）
chapter10.md：安全、隐私与合规（Safety & Compliance）
chapter11.md：性能、实时性与降级策略（Latency & Fallback）
chapter12.md：可观测性、评测与 A/B（Observability & Eval）
chapter13.md：部署与运维（车端/边缘/云端）
chapter14.md：测试计划与验收标准（Test & Acceptance）
chapter15.md：附录（术语/接口摘要/对话样例/威胁清单）

阅读指南建议阅读顺序）

chapter1 → chapter2：先对齐目标、边界、体验原则
chapter3 → chapter5：再落地架构与编排（Realtime + Agents）
chapter6 → chapter9：最后细化 RAG、多模态、车控、GUI 自动化
chapter10 → chapter14：安全合规、性能、监控、测试与上线
chapter15：查阅工具接口与样例

章节目录（Chapters & Sections）

说明：以下为“每章详细 section list”。每个章节文件建议按同名 Heading 落地；如需裁剪，优先保留：需求、架构、关键流程、接口契约、风险与验收。

Chapter 1｜范围与需求（Scope & Requirements）

1.1 背景与问题定义

1.1.1 车舱语音实时对话的价值（安全、效率、舒适）
1.1.2 与传统语音助手的差异（实时、连续、可打断、多模态）
1.1.3 本系统在座舱域的位置（与 IVI、语音前端、感知域、车控域关系）

1.2 目标与非目标（Goals / Non-goals）

1.2.1 目标清单（“可用/好用/可控/可运营”）
1.2.2 非目标边界（不做的事，避免范围膨胀）
1.2.3 成功指标（北极星指标 + 分项指标）

1.3 关键业务场景（Use Cases）

1.3.1 车控：座椅加热/空调/车窗/音乐/导航
1.3.2 信息问答：手册、保养、保险、故障灯、常见问题（RAG）
1.3.3 车内服务：点餐/购物/预约（GUI Agent）
1.3.4 安全相关：驾驶专注、分心提醒、风险对话限制（DMS）
1.3.5 多人多轮：主驾/副驾/后排多乘客并发

1.4 外部约束与假设（Constraints）

1.4.1 车规网络、域控算力、功耗与带宽限制
1.4.2 语音链路：AEC/NS/VAD 的既有方案约束
1.4.3 摄像头来源：DMS、OMS（后排鱼眼）、7V 环视等
1.4.4 中控屏读取能力边界（像素流/可访问性树/日志）

1.5 需求列表（Functional Requirements）

1.5.1 实时语音对话（可打断、低延迟、端到）
1.5.2 RAG 检索（多知识源、可追溯引用）
1.5.3 多模态输入（音频 + 图像/视频帧 + 屏幕）
1.5.4 车控 ToolCall（安全门禁、回滚、限流）
1.5.5 GUI Agent（可视化操作、回放、失败恢复）
1.5.6 多用户身份与权限（主驾优先级、儿童模式等）

1.6 非功能需求（NFR）

1.6.1 延迟预算（端到端、分段预算）
1.6.2 可靠性（断网/弱网/服务降级）
1.6.3 可扩展性（新车型/新 App/新工具接入）
1.6.4 安全与隐私（合规、脱敏、最小化采集）
1.6.5 可观测性（trace、录音、工具调用审计）

1.7 风险清单与里程碑

1.7.1 技术风险（误触发、误控车、GUI 不稳定）
1.7.2 产品风险（干扰驾驶、幻觉、不可解释）
1.7.3 里程碑（PoC → Beta → SOP → 量产）

Chapter 2｜用户体验与对话交互（UX & Conversation Design）

2.1 体验原则（Experience Principles）

2.1.1 驾驶优先：打扰、可中止、可确认
2.1.2 低认知负担：短句、结构化、一步到位
2.1.3 可控可解释：关键动作必须确认 + 可撤销

2.2 语音交互模型

2.2.1 唤醒词/免唤醒/方向盘按键策略
2.2.2 可打断（barge-in）与半双工/全双工策略
2.2.3 多说话人（主驾/副驾/后排）仲裁与优先级

2.3 多模态对话策略

2.3.1 “看见再回答”：摄像头/屏幕信息如何进入对话
2.3.2 视觉证据的表达（“我看到屏幕上…”的措辞规范）
2.3.3 误识别与纠错（让用户更正/二次确认）

2.4 安全确认与行动策略（Action Policy）

2.4.1 高风险动作分级（强制确认/二次确认/口令）
2.4.2 反悔与撤销（Undo）与安全停止（Stop）
2.4.3 动作前解释（Why）与动作后回执（What happened）

2.5 多轮任务流（Task Flows）

2.5.1 车控任务流模板（询问缺参→确认→执行→回执）
2.5.2 点餐/购物/预约任务流模板（筛→比价→下单→支付）
2.5.3 RAG 问答流模板（检索→引用→总结→追问）

2.6 失败体验设计

2.6.1 弱网/断网提示与替代方案
2.6.2 工具调用失败（重试/回滚/转人工）
2.6.3 GUI 操作失败（截图求证/回放/让用户接管）

2.7 语音与人格（Tone & Voice）

2.7.1 车载语气规范（简洁、克制、少拟人化）
2.7.2 禁用话术（避免诱导、避免过度自信）
2.7.3 多语言与方言策略（可选）

Chapter 3｜系统总体架构（System Architecture）

3.1 架构概览（分层 + 数据流）

3.1.1 车端：音频前端/感知输入/车控网关/GUI 控制器
3.1.2 边缘/云：会话编排/检索服务/日志与评测
3.1.3 OpenAI：Realtime 会话、模型推理、工具调用接口（概念层）

3.2 核心组件与职责（Component Responsibilities）

3.2.1 Realtime Session Manager（会话生命周期）
3.2.2 Agent Orchestrator（Agents SDK 运行时）
3.2.3 RAG Service（检索、重排、引用）
3.2.4 Perception Adapter（DMS/OMS/7V/屏幕采样适配）
3.2.5 Vehicle Control Gateway（车控工具与权限）
3.2.6 GUI Automation Runtime（车载 App 自动化执行器）
3.2.7 Observability Pipeline（全链路日志与审计）

3.3 关键数据对象（Key Data Models）

3.3.1 会话上下文（Session State）
3.3.2 乘员与身份（Occupant Profile）
3.3.3 车辆状态（Vehicle State）
3.3.4 任务状态机（Task State / Steps）
3.3.5 工具调用记录（Tool Invocation Record）

3.4 端到端主链路（E2E Flows）

3.4.1 语音→意图→工具→回执（车控）
3.4.2 语音→RAG→回答（知识问答）
3.4.3 语音→GUI→结果确认（点餐/预约）
3.4.4 多模态：摄像头/屏幕→对话补充证据

3.5 安全边界与信任域（Trust Boundaries）

3.5.1 车控与支付的隔离策略
3.5.2 车端/云端职责划分与最小权限
3.5.3 数据留存与匿名化边界

Chapter 4｜Realtime 会话层设计（OpenAI Realtime API）

聚焦“低延迟语音对话”的连接、事件、打断、音频策略与会话状态管理。Realtime 支持多模态输入输出，并可通过 WebRTC/WebSocket/SIP 建链。:contentReference[oaicite:2]{index=2}

4.1 接入方式选型

4.1.1 WebRTC vs WebSocket：适用场景、优缺点与选型
4.1.2 车端媒体栈与 SDP/ICE 适配（概念层）
4.1.3 SIP/呼叫中心模式（如需）与扩展点

4.2 会话生命周期（Session Lifecycle）

4.2.1 建链与配置下发（voice、VAD、turn-taking、工具列表）
4.2.2 事件流：输入、生成、工具调用、错误
4.2.3 会话重连与恢复（断点续聊策略）
4.2.4 客户端临时密钥/短期凭证策略（避免泄露主 Key）:contentReference[oaicite:3]{index=3}

4.3 音频链路设计

4.3.1 AEC/NS/VAD 与 Realtime 的协同策略
4.3.2 流式 ASR（可选）与语音到语音（S2S）策略
4.3.3 播放队、回声控制与音量 ducking
4.3.4 打断（barge-in）实现：何时停止 TTS、何时保留上下文

4.4 多模态输入注入策略

4.4.1 摄像头帧采样节奏（事件触发 vs 周期采样）
4.4.2 屏幕读取结果的结构化注入（UI 树/文本/截图）
4.4.3 证据标注：时间戳、来源、可信度、隐私等级

4.5 工具调用与实时对话的协调

4.5.1 工具调用时机（先说后做 / 先做后说 / 边说边做）
4.5.2 工具执行中的“语音占用”与进度播报
4.5.3 工具返回结构：可口语化总结 + 机器可读结果

4.6 错误处理与限流

4.6.1 过载保护（音频/图像输入限频）
4.6.2 异常事件分类（网络/媒体/模型/工具）
4.6.3 重试与退避（实时链路特殊规则）

Chapter 5｜Agents SDK 编排与多代理设计（Orchestration）

聚焦“任务拆解、路由、工具治理、长任务状态机”，以 Agents SDK 的代码优先方式实现可维护工作流与模式。:contentReference[oaicite:4]{index=4}

5.1 代理体系结构（Agent Topology）

5.1.1 单代理 vs 多代理：适用条件与复杂度
5.1.2 推荐拓扑：Supervisor + 专家代理（RAG/车控/GUI/安全）
5.1.3 Handoff（交接）与“控制权”管理

5.2 路由与意图识别（Routing）

5.2.1 车控意图路由
5.2.2 知识问答路由（RAG）
5.2.3 App 服务路由（GUI）
5.2.4 安全策略路由（驾驶中限制）

5.3 状态管理与记忆（State & Memory）

5.3.1 会话短期记忆（本次旅程）
5.3.2 车主偏好（长期记忆/用户画像）与隐私
5.3.3 任务状态机（可恢复、可回放）

5.4 工具编排模式（Common Patterns）

5.4.1 Deterministic flow（可控流程）
5.4.2 Planner-Executor（计划-执行）
5.4.3 反思/校验（Verifier）在高风险动作中的使用
5.4.4 并行工具与竞速（并发检索/并发比价）

5.5 安全护栏（Guardrails）

5.5.1 工具白名单与参数校验
5.5.2 高风险动作的强制确认策略
5.5.3 事实性与引用要求（RAG 必须引用）

5.6 与 Realtime 的耦合点

5.6.1 Realtime 的事件流如何驱动 Agent
5.6.2 语音流中的中间意图（partial）如何处理
5.6.3 工具执行回执如何回到语音输出

Chapter 6｜RAG 检索与知识系统设计（RAG & Knowledge）

6.1 知识范围与数据源

6.1.1 车辆用户手册、功能说明、故障码与提示灯
6.1.2 车机 App 帮助中心、权益/套餐说明
6.1.3 服务生态：餐饮/电商/出行/酒店/票务（可插拔）
6.1.4 实时数据：车辆状态、导航/路况（只做“事实源”，不入库）

6.2 数据处理流水线（Ingestion Pipeline）

6.2.1 文档采集、清洗、版本管理
6.2.2 分块策略（章节/语义块/表格）
6.2.3 元数据（车型、年份、市场、语言、版本、适用条件）

6.3 检索架构（Retrieval Architecture）

6.3.1 向量检索 + 关键词检索的混合策略
6.3.2 重排（Rerank）与去重
6.3.3 引用生成（Citations）与可追溯性

6.4 车载场景优化

6.4.1 延迟优化：本地缓存、边缘索引、热数据预取
6.4.2 弱网/离线：本地“救急知识包”
6.4.3 多语言与地区差异（法规/配置差异）

6.5 RAG 与多模态融合

6.5.1 “屏幕看到的设置页”→ 定位到手册章节
6.5.2 “告警灯/仪表提示”→ 故障解释与建议
6.5.3 视觉证据与文本证据的冲突处理

6.6 防幻觉机制

6.6.1 无证据不结论（Answer with evidence）
6.6.2 不确定性表达模板（可读且不吓人）
6.6.3 召回不足时的追问策略

Chapter 7｜多模态感知输入设计（DMS / OMS / 7V / 屏幕读取 / 音频）

7.1 输入源清单与信号定义

7.1.1 音频：麦克风阵列、声学事件（鸣笛/警报）
7.1.2 DMS：驾驶员视线/头姿/疲劳/分心事件
7.1.3 OMS：后排鱼眼（乘员数量、童/宠物、姿态）
7.1.4 7V：环视/侧后/前视等（按车型配置可选）
7.1.5 中控屏读取：截图、OCR（可选）、可访问性树、系统日志

7.2 采样、触发与带宽预算

7.2.1 周期采样（低频）与事件触发（高价值）
7.2.2 优先级队列（安全相关 > 任务相关 > 体验相关）
7.2.3 画面脱敏与区域裁剪（仅发送必要 ROI）

7.3 感知到语义的中间层（Perception Adapter）

7.3.1 统一事件协议（PerceptionEvent）
7.3.2 置信度与冲突合并
7.3.3 时间同步（车端时钟、帧时间戳）

7.4 屏幕读取（Screen Reading）方案

7.4.1 三种路径：UI 树 > 文本日志 > 像素截图
7.4.2 权限与隔离：只读、不可越权
7.4.3 内容归一化：控件语义、焦点、可点击性

7.5 驾驶安全联动策略

7.5.1 DMS 触发“对话降噪”（减少输出/缩短回答）
7.5.2 高风险路况：限制 GUI 操作与复杂任务
7.5.3 儿童/后排模式：OMS 决策策略

7.6 数据最小化与隐私

7.6.1 默认不上传原始视频（只上传事件/摘要）
7.6.2 用户授权与可撤回
7.6.3 留存策略与匿名化

Chapter 8｜车控 ToolCall 设计（Vehicle Control Tools）

8.1 工具目录与分级（Tool Catalog）

8.1.1 舒适性：座椅加热/通风/空调/氛围灯
8.1.2 娱乐：音乐播放/音量/频道/收藏
8.1.3 车窗/门锁（如允许）与更高风险动作分级
8.1.4 导航/电话（可选）

8.2 车控网关（Vehicle Control Gateway）

8.2.1 统一 API：抽象不同车型/供应商差异
8.2.2 幂等性与回滚（Undo/Cancel）
8.2.3 限流与熔断（防抖、防刷）

8.3 权限与安全策略（Authorization）

8.3.1 主驾/副驾/后排的权限矩阵
8.3.2 驾驶状态与车速门禁（行驶中限制）
8.3.3 二次确认与口令（高风险动作）
8.3.4 审计日志：谁在何时让系统做了什么

8.4 参数校验与安全边界（Validation）

8.4.1 参数范围与单位（温度、档位）
8.4.2 组合约束（例如：儿童座椅在用时的限制）
8.4.3 失败回退：默认保持现状 + 提示用户手动

8.5 用户可感知回执（User Feedback）

8.5.1 执行前复述
8.5.2 执行后确认（状态读回）
8.5.3 异常解释与替代建议

Chapter 9｜GUI Agent：车载 App 自动化（点餐/购物/预约）

9.1 目标与边界

9.1.1 为什么用 GUI Agent（生态异构、缺少统一 API）
9.1.2 明确边界：不绕过登录/支付安全、不做灰产行为
9.1.3 人机协同：关键步骤必须让用户确认

9.2 GUI Agent 运行时架构

9.2.1 输入：屏幕读取（UI 树/截图）+ 用户语音
9.2.2 输出：点击/滑动/输入/返回/切换 Tab
9.2.3 回放与可追溯（step-by-step trace）

9.3 App 适配策略（App Adaptation）

9.3.1 通用能力：搜索、筛选、排序、加入购物车
9.3.2 业务插件：外卖/电商/挂号/洗车/充电
9.3.3 组件识别：按钮、列表、弹窗、验证码提示

9.4 任务分解与对话（Conversation + UI）

9.4.1 缺参补齐：地址/时间/人数/口味偏好
9.4.2 多方案对比：3 个候选 + 解释差异
9.4.3 最终确认：金额、配送费、预约时间、取消政策

9.5 支付与敏感信息处理

9.5.1 输入法与密码：必须用户接管
9.5.2 订单提交前的强制复核
9.5.3 订单结果读回与失败补救

9.6 稳定性与失败恢复

9.6.1 UI 变化：元素找不到时的重试策略
9.6.2 异常弹窗：权限、定位、网络、升级提示
9.6.3 超时与“交还控制权”机制

Chapter 10｜安全、隐私与合规（Safety, Privacy, Compliance）

10.1 威胁建模（Threat Model）

10.1.1 误控车风险
10.1.2 诱导下单/错误下单风险
10.1.3 隐私泄露（音视频、位置、账号）

10.2 数据治理（Data Governance）

10.2.1 采集最小化与目的限定
10.2.2 脱敏与匿名化（车牌、人脸、联系人）
10.2.3 留存周期与用户删除权

10.3 驾驶安全策略（Driver Safety）

10.3.1 DMS 驱动的对话限制（分心时缩短/拒绝复杂任务）
10.3.2 高风险动作与行驶状态联动
10.3.3 事故/紧急事件优先级（中断所有非关键任务）

10.4 内容安全与政策

10.4.1 不当内容处理（暴力、仇恨、成人等）
10.4.2 违法/高危指令拒绝与引导
10.4.3 免责声明与边界表达（尤其是维修/医疗/法律）

10.5 审计与可追溯

10.5.1 工具调用审计（谁、何时、做了什么）
10.5.2 GUI 步骤审计（截图 hash / UI 树快照）
10.5.3 事后分析与复盘流程

Chapter 11｜性能、实时性与降级策略（Latency & Resilience）

11.1 延迟预算与指标体系

11.1.1 端到端延迟定义（用户开口→系统回应）
11.1.2 分段指标：采集、编码、传输、推理、合成、播放
11.1.3 体验指标首字延迟、可打断响应、卡顿率

11.2 性能优化策略

11.2.1 语音：分段输出、短句优先
11.2.2 多模态：只发 ROI、只在需要时发帧
11.2.3 RAG：缓存、预取、索引分层

11.3 弱网/断网/不可用降级

11.3.1 本地兜底：固定指令、车控离线集
11.3.2 RAG 离线知识包（车主手册精简版）
11.3.3 GUI 任务降级为“语音引导人工操作”

11.4 可靠性工程

11.4.1 重试策略（区分可重试/不可重试）
11.4.2 熔断与隔离（GUI 与车控隔离）
11.4.3 灾备与多区域（如云端依赖）

Chapter 12｜可观测性、评测与持续迭代（Observability & Evals）

12.1 日志与链路追踪（Tracing）

12.1.1 会话级 trace（事件流、延迟、错误）
12.1.2 工具调用 trace（输入/输出/耗时/结果码）
12.1.3 GUI trace（每步动作 + UI 快照）

12.2 指标面板（Metrics）

12.2.1 语音指标：打断成功率、识别错误、静音率
12.2.2 RAG 指标：命中率、引用覆盖率、无证据回答率
12.2.3 车控指标：误触发率、撤销率、失败率
12.2.4 GUI 指标：任务成功率、平均步数、超时率

12.3 离线评测与回放（Eval & Replay）

12.3.1 场景集与黄金答案（含引用）
12.3.2 录音/截图回放框架（脱敏后）
12.3.3 回归测试与门禁

12.4 在线实验（A/B）

12.4.1 路由策略 A/B
12.4.2 提示词/工具策略 A/B
12.4.3 安全阈值（DMS）参数 A/B

12.5 运营闭环

12.5.1 用户反馈收集与归因
12.5.2 缺陷分级与修复 SLA
12.5.3 数据驱动的知识更新（RAG 文档版本）

Chapter 13｜部署与运维（Deployment & Ops）

13.1 部署形态

13.1.1 车端部署（语音前端、车控网关、屏幕读取）
13.1.2 边缘部署（检索缓存、策略下发）
13.1.3 云端部署（编排、知识、观测、评测）

13.2 密钥与配置管理

13.2.1 车端安全存储与轮换
13.2.2 会话临时凭证发放（服务端签发）
13.2.3 动态配置（车型能力矩阵、工具开关）

13.3 版本管理与灰度

13.3.1 模型/提示词/工具版本化
13.3.2 灰度策略与回滚
13.3.3 兼容性：新旧车机 OS / App 版本

13.4 运维与应急

13.4.1 事故处理流程（误控车/误下单/隐私事件）
13.4.2 告警体系（延迟、失败率、异常峰值）
13.4.3 远程诊断与现场复现

Chapter 14｜测试计划与验收标准（Test & Acceptance）

14.1 测试范围与策略

14.1.1 单元测试（工具参数校验、状态机）
14.1.2 集成测试（Realtime 事件流、Agent 编排）
14.1.3 端到端测试（车控、RAG、GUI）
14.1.4 车规场景测试（噪声、回声、方言、车速变化）

14.2 场景用例库（Scenario Suite）

14.2.1 车控核心用例
14.2.2 RAG 问答核心用例（含引用校验）
14.2.3 GUI 点餐/购物/预约用例
14.2.4 DMS/OMS 发限制用例

14.3 验收指标（Acceptance Criteria）

14.3.1 延迟门槛
14.3.2 成功率门槛
14.3.3 误控车/误下单上限
14.3.4 隐私与合规检查项通过率

14.4 上线前检查清单（Go-Live Checklist）

14.4.1 安全开关与回滚预案
14.4.2 监控与告警就绪
14.4.3 数据留存与脱敏验证
14.4.4 紧急停止与人工接管路径演练

Chapter 15｜附录（Appendix）

15.1 术语表

DMS/OMS/7V、IVI、AEC/NS/VAD、RAG、ToolCall、GUI Agent 等

15.2 接口摘要（Contract Summary）

15.2.1 工具清单（车控工具、检索工具、GUI 工具）
15.2.2 事件协议（PerceptionEvent、ToolResult、AuditEvent）
15.2.3 错误码与重试建议

15.3 提示词与策略模板（不放大段代码）

15.3.1 车控确认模板
15.3.2 RAG 引用模板
15.3.3 GUI 步骤确认模板
15.3.4 安全拒绝模板

15.4 样例对话（Conversation Examples）

15.4.1 行驶中：座椅加热 + 音
15.4.2 仪表提示灯：解释 + 建议
15.4.3 点餐：筛选 + 下单前确认
15.4.4 DMS 分心：限制复杂任务

15.5 风险与对策清单（One-page）

高风险动作清单
数据敏感分级
常见故障与排查路径