docs: clarify realtime interaction positioning and capability status

2026-09-24 02:49:46 +08:00
parent 2649d64b55
commit 56b574d987
12 changed files with 288 additions and 231 deletions
@@ -12,10 +12,9 @@ icon: rocket

 ```bash
 docker compose up -d
-make db-seed
 ```

-首次启动会构建后端镜像。启动后访问：
+首次启动会构建后端镜像；API 容器会执行数据库迁移并同步接口定义。需要演示助手和模型资源时，可额外运行 `make db-seed`（本机需有 `make` 和 `uv`）。种子密钥是占位值，该命令也会更新示例助手绑定，不要在已有配置的环境中当作常规升级命令。启动后访问：

 - 前端：`http://localhost:3030`
 - 后端健康检查：`http://localhost:8000/health`
@@ -41,6 +41,8 @@ icon: plug

 ## 实时语音通道

+以下是管理界面语音预览和既有自定义客户端使用的平台通道，需要管理员鉴权；它们不是对外的 OpenAI Realtime 兼容协议。新业务客户端优先参照[Realtime 兼容协议设计](/realtime-protocol)，使用 `/v1/realtime` WebSocket 或 `/v1/realtime/calls` WebRTC。
+
 | 通道 | 地址 | 适用场景 |
 | --- | --- | --- |
 | WebRTC 信令 | `ws(s)://<host>/ws/voice` | 浏览器低延迟语音与视频输入。 |
@@ -38,7 +38,7 @@ Realtime 协议适配层
 | OpenAI Realtime Core | 保持标准事件名称、字段含义和生命周期，不改变标准事件语义 | 任意 OpenAI Realtime 兼容客户端 |
 | `x.interactive_media.*` Extensions | 所有项目扩展均有命名空间和能力协商 | 了解 Interactive Media 扩展的客户端 |

-普通兼容客户端不声明扩展能力时，服务端不会发送 `x.interactive_media.*` 事件。它仍可使用音频、文本、图片、转写、回复流、打断和函数调用，但不会获得工作流节点、动态变量、连续视频等项目专属状态。
+普通兼容客户端不声明扩展能力时，服务端不会发送 `x.interactive_media.*` 事件。它仍可使用音频、文本、转写、回复流、打断和函数调用；图片输入仅在已授权视觉的 Pipeline 助手中可用。工作流节点、动态变量和连续视频等项目专属状态需要相应扩展能力。

 客户端和服务端事件的机器可校验版本分别保存在 `backend/contracts/openai-realtime-client-events.schema.json` 与 `backend/contracts/openai-realtime-server-events.schema.json`。所有服务端事件含唯一 `event_id`；错误事件中的 `error.event_id` 指向触发错误的客户端事件。