docs: clarify realtime interaction positioning and capability status

README.md

@@ -0,0 +1,57 @@
+# AI Video Assistant
+
+基于 [Pipecat](https://github.com/pipecat-ai/pipecat) 的实时交互服务层。通过配置助手，将 **ASR → LLM → TTS 管线**或**端到端 Realtime 语音模型**与轮次检测、打断、工具、工作流和可选视觉能力组合起来，向业务应用提供实时会话服务。管理界面负责配置、预览和排查；对外接入使用 OpenAI Realtime 兼容子集，提供 WebSocket 和 WebRTC 两种通道。
+
+这里的 `assistant:<id>` 代表服务端配置好的完整助手，不是底层模型 ID。OpenAI Realtime **协议兼容**也不意味着已接入 OpenAI Realtime **模型**。公开协议是有明确边界的 [OpenAI-compatible subset v1](docs-developer/openai-compatibility.mdx)，并非完整 OpenAI API。
+
+> 当前仓库尚未提供 LICENSE 文件。开源发布前需要确定并添加许可证。
+
+## 项目组成
+
+| 层次 | 职责 |
+| --- | --- |
+| 接入层 | `/v1/realtime` WebSocket、`/v1/realtime/calls` WebRTC；另有 `/v1/responses` 文本接口。 |
+| 运行层 | Pipecat 管理媒体传输、Pipeline 或 Realtime 模型、轮次与打断；助手配置决定提示词、工作流、工具和模型资源。 |
+| 配置层 | Web 界面维护助手、模型资源、知识库和工具，并提供调试、测试与历史记录。 |
+
+旧的 `/ws/voice`、`/ws/stream` 和 `/api/webrtc/offer` 仍供平台界面及特定集成使用，采用管理员鉴权与不同的消息格式；第三方新接入应先阅读[接入方式](docs-user/access.mdx)。
+
+## 当前能力
+
+以下状态以仓库实现为准；具体模型服务是否可用仍取决于所填凭证、协议兼容性和实际联调。
+
+| 状态 | 能力 |
+| --- | --- |
+| 已实现 | Pipeline 模式接入受支持的 ASR、LLM、TTS；Pipecat 轮次检测、打断；Prompt、Workflow 和部分外部 Agent；WebRTC/WebSocket 实时会话。 |
+| 已实现 | 对外 OpenAI Realtime 兼容子集，以及 Pipeline 助手的 `/v1/responses` 文本接口；具体事件和字段见[兼容矩阵](docs-developer/openai-compatibility.mdx)。 |
+| 已实现但有条件 | 端到端 Realtime 模型目前有 StepFun StepAudio 与 Qwen Audio 运行适配；工具、视觉和轮次控制依助手模式及 Provider 能力而异。 |
+| 未实现 | OpenAI Realtime 和 Gemini Live 的**底层模型运行适配**；任意 VAD/EOU 模型即插即用；WebSocket 连续视频、SIP、Realtime 断线续传、完整 OpenAI API 兼容。 |
+
+模型资源目录中的 `openai-realtime`、`gemini-realtime` 及对应示例资源目前是**未接通的占位项**：可以看到或配置资源，不代表语音会话能运行。完整状态和建议收敛项见[能力状态](docs-user/status.mdx)。
+
+## 本地启动
+
+需要 Docker Compose。以下命令启动本地开发环境；API 容器启动时会执行数据库迁移并同步接口定义：
+
+```bash
+docker compose up -d
+```
+
+打开管理界面 `http://localhost:3030`；后端健康检查为 `http://localhost:8000/health`，接口文档为 `http://localhost:8000/docs`。首次语音测试前需在「组件库 / 模型资源」中填写真实服务连接，并创建助手绑定。可选的 `make db-seed` 需要本机安装 `make` 和 `uv`，用于初始化示例数据；其中的 `replace-me` 是占位密钥。该命令也会更新示例助手绑定，已有数据的环境不要把它当作常规升级命令。
+
+从管理界面创建 Prompt 助手时，可以选择：
+
+1. **Pipeline**：绑定受支持的 ASR、LLM、TTS，并配置 VAD、轮次结束与打断。
+2. **Realtime**：绑定已接通的 StepFun 或 Qwen Audio 资源；轮次控制主要使用 Provider 的设置。
+3. 保存后通过助手语音预览验证整条链路，再按[公开接入方式](docs-user/access.mdx)连接业务客户端。
+
+浏览器麦克风在 localhost 或 HTTPS 环境下使用；公网 WebRTC 通常还需要 TURN。部署说明见 [deploy/README.md](deploy/README.md)。
+
+## 文档
+
+- [用户文档概览](docs-user/index.mdx)：产品定位与使用路径。
+- [配置第一个助手](docs-user/quickstart.mdx)：模型资源、助手与语音预览。
+- [功能与配置](docs-user/features.mdx)：助手模式、模型、轮次、视觉和工具的适用范围。
+- [能力状态与收敛建议](docs-user/status.mdx)：已实现、未实现及建议移除的占位内容。
+- [开发者快速开始](docs-developer/index.mdx)、[Realtime 协议](docs-developer/realtime-protocol.mdx)、[Responses 接口](docs-developer/responses-api.mdx)：接口细节与契约。
+- [后端说明](backend/README.md)：实现和本地开发；[开发计划](docs-developer/development-plan.mdx)：生产化待办。

backend/README.md

@@ -1,189 +1,63 @@
-# AI Video Assistant — 后端引擎
+# 后端运行时
 
-参考 [dograh](../dograh),用 **pipecat** 作语音引擎的自建后端。目标是逐步长成
-类 dograh 平台,但**同时支持 WebRTC 和 WS 两种音频输出**。
+本目录提供 FastAPI 接入层、助手与模型资源管理，以及以 Pipecat 为核心的实时会话运行时。项目定位和完整能力状态见[仓库 README](../README.md)与[用户文档](../docs-user/status.mdx)。当前依赖版本以 [requirements.txt](requirements.txt) 为准。
 
-## 双输出架构(核心)
-
-pipecat 把"管线"和"输出方式"解耦:同一条 `STT→LLM→TTS` 管线可挂不同 transport。
-
-```
-                                ┌─────────────────────────────────┐
-  浏览器 ──WebRTC──► /ws/voice ──┤                                 │
-                                │  run_pipeline(transport, cfg):  │
-  自定义/话务 ─WS──► /ws/stream ─┤  input→STT→LLM→TTS→output       │
-                                └─────────────────────────────────┘
-```
-
-- **WebRTC**(`/ws/voice`):浏览器,低延迟,带 NAT 穿透。`SmallWebRTCTransport`
-- **WS**(`/ws/stream`):裸音频流,服务端/话务/自定义客户端,无 ICE/TURN。`FastAPIWebsocketTransport`
-
-加第三种输出(如 Twilio 电话)= 在 `services/pipecat/transports.py` 再加一个 `build_xxx_transport` + serializer,管线一行不用改。
-
-## 目录结构(对齐 dograh 的 `api/`,便于生长)
-
-```
-ai-video-backend/
-├── app.py                       # FastAPI 入口,挂路由 + CORS
-├── settings.py                  # 读 .env,仅存数据库/CORS/TURN 等运行设置
-├── models.py                    # AssistantConfig(对齐前端 AssistantForm)
-├── routes/                      # 一个文件一组端点(对齐 dograh routes/)
-│   ├── health.py
-│   ├── voice_webrtc.py          # WebRTC 信令
-│   └── voice_ws.py              # WS 裸音频流
-├── services/
-│   └── pipecat/                 # 引擎(对齐 dograh services/pipecat/)
-│       ├── service_factory.py   # 建 STT/LLM/TTS(按 interface_type 分发)
-│       ├── transports.py        # transport 工厂(加输出方式在此)
-│       └── pipeline.py          # 管线拼装与运行(transport 无关)
-├── Dockerfile
-├── requirements.txt
-└── .env.example
-
-# 平台长大后会再加(对齐 dograh):
-#   db/        SQLAlchemy 模型 + 会话(助手/对话/向量)
-#   schemas/   pydantic 请求响应
-#   tasks/     后台任务(转写、报表)—— 配 redis
-#   services/storage.py  录音存储 —— 配 minio
-```
-
-## 国产栈(全走 OpenAI 兼容,换栈只改 .env)
-
-| 类型 | 默认 | 接入 |
-|------|------|------|
-| LLM  | DeepSeek | 云端直连,只需 key |
-| STT  | SenseVoice / FunASR | 本地 OpenAI 兼容转写服务 |
-| TTS  | CosyVoice | 本地 OpenAI 兼容 TTS 服务 |
-
-### 讯飞 ASR / TTS / SuperTTS
-
-讯飞鉴权直接存入对应 `ModelResource.secrets`，接口参数存入 `ModelResource.values`：
-
-- 普通语音识别：`interface_type=xfyun-asr`
-- 普通语音合成：`interface_type=xfyun-tts`
-- 超拟人语音合成：`interface_type=xfyun-super-tts`
-- `values.apiUrl` 保存讯飞 WebSocket URL，音色、语速等可选参数也放在 `values`
-- `secrets` 分别保存 `appId`、`apiKey`、`apiSecret`
-
-## 接口定义驱动的模型注册表
-
-LLM、ASR、TTS、Embedding、Realtime 使用同一套两层结构：
+## 请求如何进入运行时
 
 ```text
-assistant_model_bindings -> model_resources -> interface_definitions
+业务客户端 ── /v1/realtime WebSocket 或 /v1/realtime/calls WebRTC ──┐
+管理界面   ── /api/webrtc/offer、/ws/voice 或 /ws/stream ──────────┤
+                                                               ▼
+                                                 协议适配 / Pipecat transport
+                                                               ▼
+                                               助手配置 + Pipeline 或 Realtime 模型
 ```
 
-- `interface_definitions`: 定义具体接入协议、能力和动态表单字段。
-- `model_resources`: 每条资源自带 `values/secrets`，不复用供应商账号。
-- `assistant_model_bindings`: 助手按能力选择模型资源。
+- **Pipeline**：ASR → LLM／外部 Agent → TTS；Pipecat 负责媒体帧、用户轮次、打断和服务编排。Pipeline 的 VAD 使用 Silero，轮次结束可选静音等待或 Local Smart Turn。
+- **Realtime**：端到端语音模型负责识别、生成和合成。当前 `create_realtime_service()` 只接通 `stepfun-realtime` 与 `qwen-audio-realtime`。轮次控制主要来自 Provider 配置。
+- **公开接口**：`/v1/realtime`、`/v1/realtime/calls`、`/v1/realtime/client_secrets`、`/v1/responses` 和 `/v1/models`。字段、事件和传输限制以[兼容矩阵](../docs-developer/openai-compatibility.mdx)为准。
+- **既有通道**：`/api/webrtc/offer`、`/ws/voice`、`/ws/stream` 仍供管理界面和已有集成使用；它们使用管理员鉴权，不采用公开 Realtime JSON 事件协议。
 
-`interface_type` 是具体协议，例如 `xfyun-asr`、`xfyun-tts`、
-`xfyun-super-tts`，后端严格按它选择服务实现，不根据模型 ID 或 URL 猜测。
+## 模型资源与能力边界
 
-API：
+`interface_definitions` 定义协议类型和表单字段，`model_resources` 保存每个资源的连接参数与凭证，`assistant_model_bindings` 决定助手使用哪些资源。运行时按 `interface_type` 创建服务，不根据 URL 或模型名自动推断协议。
 
-- `/api/interface-definitions`: 前端读取字段定义并动态生成 Dialog。
-- `/api/model-resources`: 统一模型资源 CRUD，敏感字段逐项打码。
+| 类型 | 当前运行状态 |
+| --- | --- |
+| `openai-llm`、`openai-asr`、`openai-tts` 及已接通的讯飞接口 | Pipeline 可用；具体 Provider 仍需联调。 |
+| `stepfun-realtime`、`qwen-audio-realtime` | Realtime 可用；具体功能按 Provider 能力限制。 |
+| `openai-realtime`、`gemini-realtime` | **未接通运行时**。接口定义和种子资源仍在目录中，不能据此宣称模型可用。 |
+| 任意独立 VAD／EOU 模型 | **未实现**。目前是内置 Pipeline 策略或 Realtime Provider 自身的设置。 |
 
-## 本地运行(用 uv,Python 3.12)
+后两项是[建议收敛的占位内容](../docs-user/status.mdx)：在适配完成前，宜隐藏或标记不可用；移除已有资源定义前需考虑数据库记录。
+
+## 主要目录
+
+| 路径 | 用途 |
+| --- | --- |
+| `routes/openai_realtime.py`、`routes/openai_responses.py` | 公开 Realtime 与 Responses 入口。 |
+| `routes/voice_webrtc.py`、`routes/voice_ws.py` | 管理界面和旧通道入口。 |
+| `services/pipecat/pipeline.py` | Pipecat 会话编排。 |
+| `services/pipecat/service_factory.py`、`services/pipecat/turn_config.py` | 模型服务与 Pipeline 轮次策略。 |
+| `services/interface_catalog.py` | 接口定义目录。 |
+| `db/models.py`、`migrations/` | SQLAlchemy 数据模型与 Alembic 迁移。 |
+| `contracts/` | OpenAPI 与 Realtime 事件契约快照。 |
+
+## 本地运行与验证
+
+在仓库根目录启动 Docker 开发环境：
 
 ```bash
-cd ai-video/backend
-uv venv                       # 按 .python-version 用 3.12
-
-# 阶段 A:只验证存储/CRUD(不装 pipecat,秒级)
-uv pip install fastapi "uvicorn[standard]" sqlalchemy asyncpg greenlet python-dotenv pydantic loguru
-# 阶段 B:做语音时再装全量(含 pipecat,需 3.10+)
-# uv pip install -r requirements.txt
-
-cp .env.example .env          # 只放数据库/CORS/TURN;模型 key 在模型资源里维护
-# 起 Postgres:在 ai-video/ 下 docker compose up -d postgres
-cd ..
-make db-migrate               # 首次或表结构变更后执行 Alembic 迁移
-cd backend
-uv run --with-requirements requirements.txt uvicorn app:app --reload --port 8000
+docker compose up -d
 ```
 
-> pipecat 相关代码用**惰性导入**,所以阶段 A 不装 pipecat 也能启动并跑 `/api/*` 与 `/health`;
-> 只有真正连 `/ws/voice`、`/ws/stream` 时才需要全量依赖。
->
-> 交互式 API 文档:启动后访问 http://localhost:8000/docs(手动戳 CRUD、定 schema 用)。
+API 容器启动时会执行 Alembic 迁移并同步接口定义。本机单独运行后端时，可用 `make db-init` 完成这两步；它需要本机安装 `uv`。需要演示助手和模型资源时，另运行 `make db-seed`；种子密钥是占位值，不能直接用于真实模型调用。`make db-seed` 还会更新示例助手的模型绑定，不要在已有生产配置上当作常规升级命令运行。
 
-## 数据库迁移
-
-表结构由 Alembic 管理，SQLAlchemy 模型在 `db/models.py`，迁移文件在
-`migrations/versions/`。
+后端地址是 `http://localhost:8000`，交互式 HTTP API 文档是 `/docs`。本地开发也可在 `backend/` 目录使用 `uv run --with-requirements requirements.txt uvicorn app:app --reload --port 8000`，需先准备数据库和环境变量。完整部署与 TURN 配置见[部署说明](../deploy/README.md)。
 
 ```bash
-cd ai-video
-make db-migrate                 # 升级到最新版
-make db-revision msg="add xxx"  # 根据模型差异生成迁移
-make db-current                 # 查看当前库版本
+make test-backend
+make contract-check
 ```
 
-`interface_definitions` 的默认数据由 `services/interface_catalog.py` 维护，并通过
-启动时同步或 `make db-sync-interface-definitions` 写入数据库；模型资源、知识库和助手示例数据继续走 `db/seed_*.sql`。
-
-## Docker(ai-video/docker-compose.yaml)—— 调试主路径
-
-api 服务挂了源码 + `--reload`,前端用 npm dev + HMR,改代码都即时生效。
-
-```bash
-cd ai-video
-docker compose up                 # 前台起 pg + api(:8000)+ ui(:3030),日志直出
-docker compose up -d              # 后台起;看日志 docker compose logs -f api
-docker compose down               # 停止全部
-
-# 知识库依赖 RustFS；默认 compose 会一起启动。Redis 仍是可选服务。
-docker compose up -d postgres rustfs api ui
-docker compose --profile data up -d redis
-# 可选:公网部署(WebRTC 需 TURN)
-docker compose --profile remote up -d
-```
-
-> 首次 `up` 会构建 api 镜像(装全量 `requirements.txt`,含 pipecat,较慢)。
-> 之后改 Python 代码靠 `--reload` 热更新,不用重建;只有改 `requirements.txt` 才 `docker compose build api`。
-
-## 极简知识库 MVP
-
-知识库入口为前端「组件 / 知识库」。使用前先在「组件 / 模型」配置并启用
-一个 Embedding 资源，然后：
-
-1. 创建知识库并选择 Embedding 模型。
-2. 上传 PDF、DOCX、TXT、Markdown、CSV、JSON 或 HTML，或者直接添加文字。
-3. 文档状态会从 `pending` 变为 `processing`，最终进入 `ready` 或 `failed`。
-4. 失败记录会保留，可在页面重试；完成后可预览分块并使用「检索测试」验证召回。
-5. 在提示词助手的 pipeline 模式下选择知识库。每轮 LLM 推理前会自动检索并注入相关片段。
-
-当前后台处理使用 FastAPI 进程内任务，适合 MVP。服务重启时未完成任务会转为失败，
-可在页面重试；需要多实例或高吞吐时再迁移到 Redis/ARQ worker。
-
-## Prompt 动态变量
-
-提示词助手的 Pipeline 与 Realtime 模式都支持在开场白和系统提示词中使用
-`{{ variable_name }}`。Pipeline 模式还支持在 HTTP 工具的 URL、Header 和 Body
-中引用变量。助手页维护变量类型、默认值和必填规则；调试面板在每次通话开始前
-传入会话值。Realtime 会把渲染后的提示词作为模型 instructions。
-
-内置系统变量包括 `system__conversation_id`、`system__time`、
-`system__agent_turns` 和 `system__conversation_history`。客户端不能提交
-`system__*` 或 `secret__*`。HTTP 工具的密钥变量必须在工具的服务端密钥配置中
-以 `secret__` 开头声明，而且只能用于 Header。
-
-HTTP 工具可通过“响应变量赋值”把 JSON 路径写回普通会话变量，例如：
-
-```json
-{"order_status": "response.order.status"}
-```
-
-后续轮次会使用新值重新渲染系统提示词。上线前执行 `make db-migrate`，应用
-`20260712_0007` 迁移。
-
-## 待联调 / TODO
-
-- [ ] 联调 Pipecat 1.3.0 语音链路与各 OpenAI 兼容服务
-- [ ] 起本地 SenseVoice / CosyVoice 的 OpenAI 兼容服务
-- [x] `realtime` 模式(StepFun StepAudio Realtime)
-- [x] `realtime` 模式(Alibaba Cloud Qwen-Audio 3.0 Realtime MVP)
-- [x] 前端 `DebugVoicePanel` 接 `/ws/voice`(参考 dograh `useWebSocketRTC.tsx`)
-- [ ] 加 DB 后:助手配置入库(目前随请求内联)
+开发计划中的生产可观测性、并发保护和可靠性工作尚未全部完成，见[单租户生产化计划](../docs-developer/development-plan.mdx)。

docs-developer/index.mdx

@@ -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`

docs-developer/integrations.mdx

@@ -41,6 +41,8 @@ icon: plug
 
 ## 实时语音通道
 
+以下是管理界面语音预览和既有自定义客户端使用的平台通道，需要管理员鉴权；它们不是对外的 OpenAI Realtime 兼容协议。新业务客户端优先参照[Realtime 兼容协议设计](/realtime-protocol)，使用 `/v1/realtime` WebSocket 或 `/v1/realtime/calls` WebRTC。
+
 | 通道 | 地址 | 适用场景 |
 | --- | --- | --- |
 | WebRTC 信令 | `ws(s)://<host>/ws/voice` | 浏览器低延迟语音与视频输入。 |

docs-developer/realtime-protocol.mdx

@@ -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` 指向触发错误的客户端事件。
 

docs-user/access.mdx

@@ -0,0 +1,27 @@
+---
+title: 接入方式
+description: 区分公开 Realtime 接口、Responses 文本接口和平台调试通道。
+icon: plug
+---
+
+# 接入方式
+
+新业务客户端使用 `/v1/` 下的公开接口。请求中的 `model` 是 `assistant:<助手 ID>`；底层模型、凭证、提示词和工具由服务端助手配置决定。
+
+| 用途 | 接口 | 鉴权与数据 |
+| --- | --- | --- |
+| 浏览器或移动端实时音频 | `POST /v1/realtime/client_secrets`、`POST /v1/realtime/calls` | 业务后端用长期 Key 签发短期令牌；客户端用 WebRTC 媒体轨道传音频、DataChannel 传事件。 |
+| 服务端或自定义客户端实时会话 | `/v1/realtime?model=assistant:<id>` WebSocket | 使用 Bearer Key；JSON 文本帧承载事件，音频为 Base64 PCM16。 |
+| Pipeline 助手的文本调用 | `POST /v1/responses` | 长期 Bearer Key；支持 JSON 或 SSE、多轮 `previous_response_id`。 |
+| 查询可调用助手 | `GET /v1/models` | 长期 Bearer Key；返回助手 ID 和其 `responses`／`realtime` 能力。 |
+
+公开 Realtime 接口是 **OpenAI-compatible subset v1**，并附有可协商的 `x.interactive_media.*` 扩展。客户端可更新的会话字段有限；助手身份、模型、提示词、音色和工具等以服务端配置为准。WebSocket 暂只支持指定格式的音频与图片项，不支持连续视频；连续摄像头输入使用协商后的 WebRTC 视频轨道。
+
+## 管理界面和旧通道
+
+| 通道 | 当前用途 | 与公开接口的区别 |
+| --- | --- | --- |
+| `/api/webrtc/offer`、`/ws/voice` | 管理界面 WebRTC 预览和现有集成 | 使用管理员鉴权及平台信令／RTVI 消息。 |
+| `/ws/stream` | 裸音频 WebSocket、内部调试和既有自定义客户端 | 使用管理员鉴权；先发启动 JSON，之后传二进制音频帧，不是 OpenAI Realtime JSON 事件协议。 |
+
+这些通道目前仍在使用。文档建议移除的是**把它们写成第三方首选公开接口的旧表述**，不是立即删除端点。接入前请以开发者文档中的 `openai-compatibility.mdx`、`realtime-protocol.mdx` 和 `responses-api.mdx` 为字段及事件依据。

docs-user/docs.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://mintlify.com/docs.json",
-  "name": "AI 视频助手 · 用户文档",
+  "name": "AI Video Assistant · 实时交互层",
   "theme": "mint",
   "colors": {
     "primary": "#1b2741",
@@ -46,7 +46,7 @@
     "groups": [
       {
         "group": "产品",
-        "pages": ["index", "features"]
+        "pages": ["index", "quickstart", "features", "access", "status"]
       }
     ]
   }

docs-user/features.mdx

@@ -1,32 +1,50 @@
 ---
 title: 核心功能
-description: 项目的主要能力与配置关系。
-icon: bot
+description: 助手模式、模型、轮次、视觉、工具和知识库的适用范围。
+icon: sliders-horizontal
 ---
 
-# 核心功能
+# 功能与配置
 
-## 助手配置
+以下“已实现”指仓库有对应运行路径；实际服务还需要有效凭证，并受模型提供方能力约束。[能力状态](/status)列出尚未接通和建议移除的占位内容。
 
-助手是运行时入口，支持提示词、工作流和外部托管三类大脑：
+## 选择助手和运行模式
 
-| 类型 | 用途 |
-| --- | --- |
-| `prompt` | 用提示词驱动的基础对话，可绑定工具。 |
-| `workflow` | 用节点图编排对话流程。 |
-| `dify` / `fastgpt` / `opencode` | 将对话处理交给外部 Agent 服务。 |
+| 助手类型 | Pipeline | Realtime | 说明 |
+| --- | --- | --- | --- |
+| Prompt | 已实现 | 已实现，有 Provider 限制 | 提示词驱动，可绑定模型及受支持的工具。 |
+| Workflow | 已实现 | 已实现，有 Provider 限制 | 用节点编排对话、状态和动作。 |
+| Dify / FastGPT / OpenCode | 已实现 | 未实现 | 对话处理交给外部 Agent，语音输入输出仍由平台管线处理。 |
 
-其中 `prompt` 和 `workflow` 支持 `pipeline` 与 `realtime`；外部托管 Agent 仅支持 `pipeline`。
+创建助手时，**Pipeline** 需要分别绑定 ASR、LLM、TTS；外部 Agent 助手将 LLM 环节交给外部服务。**Realtime** 绑定一个端到端语音模型资源。模型资源按 `interface_type` 选择适配，填写一个看似兼容的 URL 不会自动生成新的运行适配。
 
-## 模型与知识库
+## 模型和交互效果
 
-模型资源按具体协议注册，而不是按厂商名称猜测。当前支持 OpenAI 兼容的 LLM、ASR、TTS、Embedding、Realtime，也支持讯飞 ASR/TTS/SuperTTS、StepFun Realtime，以及 Dify、FastGPT、OpenCode Agent。
+| 配置 | 当前状态 | 适用范围 |
+| --- | --- | --- |
+| OpenAI 兼容 LLM、ASR、TTS | 已实现 | Pipeline；具体兼容性仍需连接测试和语音预览。 |
+| 讯飞 ASR、TTS、SuperTTS | 已实现 | Pipeline。 |
+| StepFun StepAudio、Qwen Audio Realtime | 已实现 | Realtime；不同 Provider 的工具与轮次能力不相同。 |
+| OpenAI Realtime、Gemini Live 底层模型 | 未实现 | 资源定义和示例存在，但语音运行适配尚未接通。 |
+| 独立 VAD / EOU 模型替换 | 未实现 | Pipeline 当前使用内置 Silero VAD 与 Local Smart Turn；可以调参数、选策略，不能任意选择模型。 |
 
-知识库可绑定一个 Embedding 模型资源。助手引用知识库后，需先解绑才能删除该知识库。
+Pipeline 的“高级交互配置”可以调整 VAD 阈值、开始／停止确认时间、打断检测方式，以及静音等待或 Smart Turn 轮次结束策略。Realtime 模式的 VAD、Smart Turn 等由所选 Provider 的资源设置和会话能力决定；同名参数不保证跨 Provider 行为相同。
 
-## 工具与历史
+## 视觉、知识库和工具
 
-- 可复用工具分为 System、HTTP、Client 和 MCP；结束对话属于 System 类别。
-- HTTP 工具的 URL、请求头、参数和密钥独立管理。
-- Prompt 助手和 Workflow Agent 节点可开启内置系统工具：结束对话、更新状态、跳过本轮、请求人工接管；Workflow 还提供确定性的 Update State 节点。
-- 历史记录保留会话、通道、运行模式及消息序列，便于排查对话。
+| 能力 | 当前状态 | 使用条件 |
+| --- | --- | --- |
+| WebRTC 摄像头输入 | 已实现，有条件 | 助手开启视觉、客户端协商视频轨道，运行时按需获取画面；不是任意 Live 模型的连续视频理解。 |
+| Realtime 协议图片项 | 已实现，有条件 | 目前仅 Pipeline 模式及已授权视觉的助手支持；Realtime 模式明确拒绝。 |
+| 知识库检索 | 已实现，有条件 | 需要 Embedding 模型和已处理的文档，主要用于 Pipeline 的 Prompt／Workflow。 |
+| System、HTTP、Client、MCP 工具 | 已实现，有条件 | Pipeline 和 Workflow 按配置执行；Prompt Realtime 的工具能力取决于 Provider 声明。 |
+| 会话与消息历史 | 已实现 | 可在管理界面查看通道、运行模式和消息，辅助排查。 |
+
+Prompt Realtime 中，Qwen Audio 已声明部分 HTTP、MCP、Client 和内置工具能力；StepFun Prompt Realtime 尚未声明工具能力。保存助手前，界面和服务端会校验不兼容项。外部 Agent 的上下文、知识库和工具通常由对应服务管理。
+
+## 配置建议
+
+- 需要明确控制 ASR、LLM、TTS、VAD 和轮次结束策略时，先选 Pipeline。
+- 需要端到端语音模型时，先选已接通的 StepFun 或 Qwen Audio，再验证该 Provider 的打断与工具行为。
+- 需要摄像头时，使用 WebRTC，并在助手中启用视觉；WebSocket 不传连续视频。
+- 需要业务客户端集成时，先查看[接入方式](/access)及公开协议的兼容范围。

docs-user/index.mdx

@@ -1,22 +1,38 @@
 ---
 title: 产品概览
-description: 面向实时语音交互的助手管理与集成平台。
-icon: video
+description: 了解实时交互服务层的定位、组成和当前边界。
+icon: radio
 ---
 
 # 产品概览
 
-在一个界面中配置模型、知识库、工具和助手，并通过 WebRTC 或 WebSocket 接入实时语音对话。
+AI Video Assistant 是基于 Pipecat 的实时交互服务层。你可以将语音识别、大模型、语音合成，或端到端 Realtime 语音模型绑定到助手，再配置轮次、打断、提示词、工具和工作流，通过 WebSocket 或 WebRTC 接入业务应用。
 
-## 平台组成
+管理界面用于配置和预览。业务客户端调用的是服务端已配置的助手：公开接口中的 `assistant:<id>` 指完整助手，并非底层模型 ID。对外接口遵循 **OpenAI-compatible subset v1**，只覆盖文档列出的字段和事件。
 
-- **助手**：定义提示词、运行模式、模型绑定及可选工作流。
-- **组件库**：统一维护模型资源、知识库和可复用工具。
-- **语音引擎**：Pipecat 管线支持浏览器 WebRTC 与裸 WebSocket 音频流。
+## 从配置到接入
 
-> 凭证只保存在模型资源或助手的服务端配置中；接口返回会自动打码。
+1. 在「组件库 / 模型资源」填写模型服务地址和凭证。
+2. 创建 Prompt、Workflow 或外部 Agent 助手，选择 Pipeline 或可用的 Realtime 运行模式。
+3. 通过语音预览检查延迟、打断、轮次和回复效果。
+4. 使用公开 Realtime WebRTC/WebSocket 接口接入业务客户端；Pipeline 助手还可使用 Responses 文本接口。
 
-## 下一步
+详见[功能与配置](/features)及[接入方式](/access)。
 
-- [核心功能](/features)：了解助手类型、模型、知识库与工具。
-- 本地启动与对接见仓库中的 `docs-developer/`（独立开发者文档站点）。
+## 两种运行模式
+
+| 模式 | 组合方式 | 当前轮次控制 |
+| --- | --- | --- |
+| Pipeline | ASR → LLM／外部 Agent → TTS | 使用 Pipecat 的 VAD、静音或 Smart Turn 策略，可配置打断。 |
+| Realtime | 端到端语音模型负责识别、生成和合成 | 主要由所选 Provider 的轮次检测能力决定；不等同于 Pipeline 的独立 VAD/EOU 配置。 |
+
+两种模式可通过同一套公开 Realtime 接口调用，但功能受助手类型、模型适配和客户端通道限制。当前运行适配的端到端模型类型是 **StepFun StepAudio** 与 **Qwen Audio Realtime**。模型资源目录中出现 OpenAI Realtime 或 Gemini Live，不表示其底层模型适配已经实现。
+
+## 阅读指引
+
+- [配置第一个助手](/quickstart)：从模型资源到语音预览。
+- [功能与配置](/features)：选择助手、模型、轮次、视觉和工具。
+- [接入方式](/access)：区分公开协议与管理界面使用的通道。
+- [能力状态](/status)：逐项查看已实现、未实现和建议收敛的内容。
+
+本地启动、请求字段和事件协议见仓库根目录 `README.md` 与 `docs-developer/`。能力状态以当前仓库实现为准；具体第三方模型仍需用自己的凭证实测。

docs-user/quickstart.mdx

@@ -0,0 +1,30 @@
+---
+title: 配置第一个助手
+description: 从模型资源到语音预览，验证第一条实时会话链路。
+icon: rocket
+---
+
+# 配置第一个助手
+
+本页从已启动的管理界面开始。首次本地部署可在仓库根目录运行 `docker compose up -d`；API 容器启动时会迁移数据库并同步模型接口定义。界面地址为 `http://localhost:3030`。可选的 `make db-seed` 需要本机安装 `make` 和 `uv`，用于加入演示数据；种子资源中的 `replace-me` 密钥不能用于真实调用，也不要在已有助手数据的环境中当作常规升级命令使用。
+
+## 1. 配置模型资源
+
+进入「组件库 / 模型资源」，选择接口类型并填写服务地址、模型 ID 和凭证。语音 Pipeline 至少需要 ASR、LLM、TTS；端到端 Realtime 模式目前选择 StepFun StepAudio 或 Qwen Audio。保存前使用“测试连接”，然后再通过语音预览验证整条链路。单项连接成功不代表音频格式、轮次和工具行为均已可用。
+
+如果目录中看到 OpenAI Realtime 或 Gemini Live，请先查看[能力状态](/status)：这两种底层模型当前尚未接通运行时。
+
+## 2. 创建助手
+
+进入「创建助手」，先选择 Prompt 类型，并按需求选运行模式：
+
+- **Pipeline**：分别绑定 ASR、LLM、TTS；填写系统提示词，按需要设置开场白、打断和高级轮次策略。
+- **Realtime**：绑定一个已接通的 Realtime 资源；音色、VAD 或 Smart Turn 设置以该 Provider 的资源字段和实际能力为准。
+
+保存后从助手详情页打开语音预览。第一次验证建议只检查听取用户语音、生成回复、播放语音和打断；确认基本链路后再添加知识库、视觉、工具或 Workflow。
+
+## 3. 接入业务客户端
+
+语音预览通过后，按[接入方式](/access)选择公开 WebRTC 或 WebSocket。浏览器麦克风需要 localhost 或 HTTPS；公网 WebRTC 通常还要配置 TURN。公开接口以 `assistant:<助手 ID>` 选择助手，第三方客户端不直接提交底层模型密钥。
+
+如果会话启动失败，先检查模型资源的真实凭证、所选 `interface_type` 是否有运行适配、助手绑定是否完整，再查看管理界面的会话历史和后端日志。

docs-user/status.mdx

@@ -0,0 +1,45 @@
+---
+title: 能力状态
+description: 已实现、未实现与建议收敛的项目内容。
+icon: list-checks
+---
+
+# 能力状态
+
+本页的“已实现”表示当前仓库存在对应代码路径，并不替代真实 Provider、弱网或并发环境下的验收。“未实现”表示不能因配置界面、种子数据或开发计划中出现名称就视为可用。“建议移除”是待评估的收敛项，尚未删除。
+
+## 已实现或有条件可用
+
+| 能力 | 状态 | 边界 |
+| --- | --- | --- |
+| Pipecat Pipeline：ASR → LLM／外部 Agent → TTS | 已实现 | 需要匹配的模型接口、有效凭证和实际联调。 |
+| Pipecat Pipeline 的 Silero VAD、静音结束、Local Smart Turn、打断 | 已实现 | 可调整参数与策略；模型实现目前固定。 |
+| StepFun StepAudio、Qwen Audio Realtime | 已实现 | Provider 的轮次、工具与视觉能力各不相同。 |
+| Prompt、Workflow、Dify／FastGPT／OpenCode 助手 | 已实现 | 外部 Agent 只支持 Pipeline；公开 `/v1/models` 当前不列出 OpenCode。 |
+| OpenAI Realtime 兼容子集的 WebSocket／WebRTC | 已实现 | 是对外协议适配，不代表所有 OpenAI 字段或底层 OpenAI 模型可用。 |
+| Responses 文本接口 | 已实现 | 面向可通过该接口调用的 Pipeline 助手。 |
+| WebRTC 可选摄像头与视觉处理 | 有条件可用 | 需要助手授权视觉、客户端协商视频轨道，并受运行模式限制。 |
+| 工具和知识库 | 有条件可用 | 受助手模式、模型 Provider 与资源配置限制。 |
+| 会话与消息历史 | 已实现 | 可在管理界面查看，辅助排查。 |
+
+## 未实现或尚未承诺
+
+| 能力 | 当前情况 |
+| --- | --- |
+| OpenAI Realtime、Gemini Live 底层模型适配 | 资源目录和种子数据存在，但 Realtime 运行时只创建 StepFun、Qwen Audio 服务。 |
+| 任意 VAD、EOU 模型作为独立资源接入 | 目前只有内置 Pipeline 策略及部分 Provider 自身的轮次配置。 |
+| 任意原生音视频 Live 模型接入 | 当前摄像头能力以 WebRTC 视频轨道和按需画面处理为主，不能据此宣称通用 Live 模型支持。 |
+| 完整 OpenAI API、`/v1/chat/completions` | 公开协议只承诺兼容矩阵中列出的子集。 |
+| WebSocket 连续视频、SIP、Realtime 断线续传 | 当前公开协议不支持；可参考开发计划评估。 |
+| 多租户、RBAC、完整生产可观测性与可靠性 | 开发计划中仍有待办，当前定位为单租户 MVP。 |
+
+## 建议移除或收敛，尚未执行
+
+| 对象 | 建议 | 原因 |
+| --- | --- | --- |
+| `openai-realtime`、`gemini-realtime` 可选资源定义与示例资源 | 在运行适配完成前，从可用列表和默认种子中移除，或明确置为“未接通”。已有数据库记录需先评估迁移。 | 当前可配置，但启动语音会话时会遇到不支持的接口类型。 |
+| 把 `/ws/voice`、`/ws/stream` 写作第三方首选入口的旧说明 | 从对外接入主线移到“平台调试／既有通道”说明。 | 它们与 `/v1/realtime` 的鉴权、消息格式和兼容承诺不同。 |
+| 将“Realtime 协议兼容”写作“OpenAI Realtime 模型已接入”的措辞 | 从功能列表中删除混用表述，分别列对外协议和底层 Provider。 | 两种能力由不同代码实现，当前完成度不同。 |
+| 将“视频输入”写作“通用 Live 模型能力”的措辞 | 改为“WebRTC 可选视频轨道和有条件的视觉处理”。 | WebSocket 连续视频与通用 Live 模型适配尚未实现。 |
+
+以上是文档和产品目录的收敛建议，不是删除正在使用的管理界面接口。接口、数据或资源定义的实际移除需要单独处理兼容性和已有数据。

frontend/README.md

@@ -1,36 +1,25 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# 管理界面
 
-## Getting Started
+这是实时交互服务层的配置与调试界面，用于管理助手、模型资源、知识库、工具，以及语音预览、测试和历史记录。项目定位、公开接口与能力状态见[仓库 README](../README.md)和[用户文档](../docs-user/index.mdx)。
 
-First, run the development server:
+## 本地开发
+
+推荐在仓库根目录运行 `docker compose up -d`，界面地址为 `http://localhost:3030`，后端为 `http://localhost:8000`。如需单独运行前端：
 
 ```bash
+cd frontend
+npm ci
 npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+单独运行时 Next.js 默认监听 `http://localhost:3000`。浏览器默认连接 `http://localhost:8000`；需要其他后端地址时设置 `NEXT_PUBLIC_API_BASE_URL`。后端及数据库仍需单独启动。
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+## 检查
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+```bash
+npm run lint
+npm run test:contracts
+npm run build
+```
 
-## Learn More
-
-To learn more about Next.js, take a look at the following resources:
-
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
-
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+界面中的“Realtime 模型资源”列表包含尚未接通运行时的占位类型；实际可运行的类型与功能限制见[能力状态](../docs-user/status.mdx)。