feat: harden public OpenAI API contracts

docs-developer/realtime-protocol.mdx

@@ -6,7 +6,7 @@ icon: radio
 
 # Realtime 兼容协议设计
 
-> 当前实现版本为 `Interactive Media Realtime Extensions v1`。OpenAI 兼容接口与现有 `/api/webrtc/offer`、`/ws/voice`、`/ws/stream`、RTVI 消息并行提供；RTVI 不是待删除的迁移接口。
+> 当前公开协议为 `OpenAI-compatible subset v1`，扩展版本为 `Interactive Media Realtime Extensions v1`。完整兼容矩阵见 [OpenAI 兼容范围](/openai-compatibility)。OpenAI 兼容接口与现有 `/api/webrtc/offer`、`/ws/voice`、`/ws/stream`、RTVI 消息并行提供；RTVI 不是待删除的迁移接口。
 
 ## 设计目标
 
@@ -40,6 +40,8 @@ Realtime 协议适配层
 
 普通兼容客户端不声明扩展能力时，服务端不会发送 `x.interactive_media.*` 事件。它仍可使用音频、文本、图片、转写、回复流、打断和函数调用，但不会获得工作流节点、动态变量、连续视频等项目专属状态。
 
+客户端和服务端事件的机器可校验版本分别保存在 `backend/contracts/openai-realtime-client-events.schema.json` 与 `backend/contracts/openai-realtime-server-events.schema.json`。所有服务端事件含唯一 `event_id`；错误事件中的 `error.event_id` 指向触发错误的客户端事件。
+
 ## 接口概览
 
 假设服务地址为 `https://api.example.com`：
@@ -507,6 +509,7 @@ Qwen Realtime provider 只允许在 provider 会话首次配置前选择 PTT 或
 {
   "event_id": "evt_capabilities_001",
   "type": "x.interactive_media.capabilities.update",
+  "version": "1",
   "capabilities": [
     "workflow_events",
     "dynamic_variables",
@@ -522,6 +525,7 @@ Qwen Realtime provider 只允许在 provider 会话首次配置前选择 PTT 或
 {
   "event_id": "evt_server_001",
   "type": "x.interactive_media.capabilities.updated",
+  "version": "1",
   "capabilities": [
     "workflow_events",
     "dynamic_variables",
@@ -532,7 +536,7 @@ Qwen Realtime provider 只允许在 provider 会话首次配置前选择 PTT 或
 }
 ```
 
-服务端只发送已接受能力对应的扩展事件。扩展版本与 OpenAI Realtime Core 独立演进。
+服务端只发送已接受能力对应的扩展事件。所有扩展事件使用字符串 `version: "1"`；扩展版本与 OpenAI Realtime Core 独立演进。
 
 ### 扩展事件目录
 
@@ -555,6 +559,7 @@ Qwen Realtime provider 只允许在 provider 会话首次配置前选择 PTT 或
 {
   "event_id": "evt_variables_001",
   "type": "x.interactive_media.session.variables.update",
+  "version": "1",
   "update_id": "update_001",
   "variables": {
     "user_name": "王先生",
@@ -567,6 +572,7 @@ Qwen Realtime provider 只允许在 provider 会话首次配置前选择 PTT 或
 {
   "event_id": "evt_server_002",
   "type": "x.interactive_media.session.variables.updated",
+  "version": "1",
   "update_id": "update_001",
   "status": "accepted"
 }
@@ -578,6 +584,7 @@ Qwen Realtime provider 只允许在 provider 会话首次配置前选择 PTT 或
 {
   "event_id": "evt_server_003",
   "type": "x.interactive_media.workflow.node_active",
+  "version": "1",
   "nodeId": "collect_materials"
 }
 ```
@@ -588,6 +595,7 @@ Qwen Realtime provider 只允许在 provider 会话首次配置前选择 PTT 或
 {
   "event_id": "evt_server_004",
   "type": "x.interactive_media.call.ended",
+  "version": "1",
   "reason": "assistant_completed"
 }
 ```
@@ -625,13 +633,13 @@ Qwen Realtime provider 只允许在 provider 会话首次配置前选择 PTT 或
 
 | code | 含义 |
 | --- | --- |
-| `authentication_failed` | API Key 或临时令牌无效 |
-| `assistant_not_found` | 助手不存在、未发布或不可访问 |
-| `session_field_locked` | 客户端尝试覆盖服务端锁定配置 |
-| `unsupported_event` | 当前协议版本不支持该事件 |
-| `capability_not_enabled` | 未协商或无权使用某项扩展 |
-| `response_in_progress` | 已有活动回复且当前请求不能并发执行 |
-| `tool_result_timeout` | Client 工具未在规定时间内返回 |
+| `invalid_api_key` | API Key 或临时令牌无效 |
+| `invalid_model` | 助手不存在、格式错误或不适用于当前运行时 |
+| `immutable_session_field` | 客户端尝试覆盖服务端锁定配置 |
+| `invalid_event` | 事件名或事件字段不符合当前 schema |
+| `extension_not_negotiated` | 使用了尚未协商的扩展能力 |
+| `input_audio_buffer_not_committed` | 手动音频缓冲尚未提交 |
+| `input_audio_buffer_too_large` | 音频超过单次缓冲上限 |
 | `internal_error` | 运行时出现不可恢复错误 |
 
 错误只终止相关事件；只有鉴权失败、协议严重错误或运行时不可恢复时才关闭整个连接。