Update documentation for Realtime Agent Studio with enhanced content and structure

- Revised site name and description for clarity and detail. - Updated navigation structure to better reflect the organization of content. - Improved changelog entries for better readability and consistency. - Migrated assistant configuration and prompt guidelines to new documentation paths. - Enhanced core concepts section to clarify the roles and capabilities of assistants and engines. - Streamlined workflow documentation to provide clearer guidance on configuration and usage.
2026-03-09 05:38:43 +08:00
parent 65ae2287d5
commit b300b469dc
34 changed files with 1776 additions and 2981 deletions
--- a/docs/content/concepts/index.md
+++ b/docs/content/concepts/index.md
@@ -1,296 +1,49 @@
-# 核心概念
+# 核心概念

-本章节介绍 Realtime Agent Studio 中的核心概念，帮助你更好地理解和使用平台。
+本章节只解释 Realtime Agent Studio 的关键心智模型，不重复环境部署或助手构建的操作细节。

 ---

-## 概念总览
+## 先建立这三个概念

-```mermaid
-flowchart TB
-    subgraph Platform["RAS 平台"]
-        Assistant[助手 Assistant]
-        
-        subgraph Resources["资源库"]
-            LLM[LLM 模型]
-            ASR[ASR 模型]
-            TTS[TTS 声音]
-            KB[知识库]
-        end
-        
-        subgraph Engine["交互引擎"]
-            Pipeline[Pipeline引擎]
-            Multimodal[Realtime引擎]
-        end
-        
-        Session[会话 Session]
-    end
+### 1. 助手是“对外提供能力的配置单元”

-    Assistant --> LLM
-    Assistant --> ASR
-    Assistant --> TTS
-    Assistant --> KB
-    Assistant --> Engine
-    Engine --> Session
-```
+助手决定了一个实时 AI 入口对外表现成什么角色：它使用什么提示词、哪些模型、能访问哪些知识和工具、会话如何开始以及运行时如何被覆盖。
+
+- [助手概念](assistants.md) — 统一理解助手、会话、动态变量与能力边界
+- [配置选项](assistants/configuration.md) — 了解界面层和运行时配置项如何分工
+- [提示词指南](assistants/prompts.md) — 学会定义助手的角色、任务、风格与约束
+- [测试调试](assistants/testing.md) — 理解如何验证助手行为和定位问题
+
+### 2. 引擎是“承载实时交互的运行时”
+
+RAS 同时提供 Pipeline 引擎与 Realtime 引擎。它们都能驱动实时助手，但在延迟、可控性、成本和可替换性上各有取舍。
+
+- [引擎概览](engines.md) — 两类引擎的能力边界与选择建议
+- [Pipeline 引擎](pipeline-engine.md) — VAD/ASR/TD/LLM/TTS 串联的可组合链路
+- [Realtime 引擎](realtime-engine.md) — 面向端到端实时模型的低延迟交互路径
+
+### 3. 工作流是“把复杂业务拆成步骤和分支的方法”
+
+当单一提示词不足以稳定处理多步骤、多条件、多工具的业务流程时，应使用工作流来显式编排节点、路由和回退策略。
+
+- [工作流](../customization/workflows.md) — 了解何时需要工作流、它由哪些部分组成、如何设计可维护的流程

 ---

-## 助手 (Assistant)
+## 本章节不负责什么

-**助手**是 RAS 的核心实体，代表一个可对话的 AI 智能体。
+以下内容属于“如何搭建和使用”，不在本章节展开说明：

-### 助手配置
+- 助手搭建、模型/知识库/工具/工作流配置：从 [助手概览](assistants.md) 进入构建链路
+- 部署与环境变量：见 [环境与部署](../getting-started/index.md)
+- 第一个助手的最短操作路径：见 [快速开始](../quickstart/index.md)
+- 事件格式与接入协议：见 [API 参考](../api-reference/index.md)

-每个助手包含以下配置：
+## 建议阅读顺序

-| 配置项 | 说明 |
-|-------|------|
-| **名称** | 助手的显示名称 |
-| **指令配置** | 使用提示词指令定义助手角色、行为、限制 |
-| **语音设置** | 包括语音识别模型，语音合成模型 |
-| **交互设置** | 包括用户打断机器人的灵敏度，检测用户语句结束的灵敏度 |
-| **工具配置** | 配置助手可调用的外部工具 |
-| **知识配置** | 关联的知识库（用于 RAG） |
-| **Webhooks** | 用于订阅助手的活动 |
+1. 先读 [助手概念](assistants.md)，明确你要配置的对象到底是什么
+2. 再读 [引擎概览](engines.md)，决定应该选择 Pipeline 还是 Realtime
+3. 如果场景涉及多步骤流程，再读 [工作流](../customization/workflows.md)
+4. 最后回到 [快速开始](../quickstart/index.md) 或 [助手概览](assistants.md) 开始具体配置

---
-
-## 会话 (Session)
-
-**会话**代表一次完整的对话交互，从用户连接到断开。
-
-### 会话状态
-
-```mermaid
-stateDiagram-v2
-    [*] --> Connecting: WebSocket 连接
-    Connecting --> Started: session.started
-    Started --> Active: 对话中
-    Active --> Active: 多轮对话
-    Active --> Stopped: session.stop
-    Stopped --> [*]: 连接关闭
-```
-
-### 会话数据
-
-每个会话记录包含：
-
- **基本信息** - ID、时长、时间戳
- **音频数据** - 用户和助手的音频记录
- **转写文本** - ASR 识别结果
- **LLM 交互** - 输入输出和工具调用
- **元数据** - 渠道、来源、自定义变量
-
---
-
-## Pipeline引擎 vs Realtime引擎
-
-RAS 支持两种引擎架构，适用于不同场景。
-
-### 管线式引擎 (Pipeline)
-
-将语音交互拆分为多个环节，包含 **VAD（声音活动检测）**、**ASR（语音识别）**、**TD（回合检测）**、**LLM（大语言模型）**、**TTS（语音合成）**。外部服务可选 **OpenAI**、**SiliconFlow**、**DashScope**、**本地模型**。LLM 与实时交互引擎均可连接**工具**（Webhook、客户端工具、内建工具）。
-
-```
-用户语音 → [VAD] → [ASR] → [TD] → 文本 → [LLM] → 回复 → [TTS] → 助手语音
-```
-
-**优点：**
-
- 灵活选择各环节供应商（OpenAI、SiliconFlow、DashScope、本地模型）
- 可独立优化 VAD、ASR、TD、LLM、TTS 每个环节
- 成本可控
-
-**缺点：**
-
- 延迟较高（累加延迟）
- 需要协调多个服务
-
-### 实时交互引擎 (Realtime)
-
-实时交互引擎可连接 **OpenAI Realtime**、**Gemini Live**、**Doubao 实时交互引擎** 等，同样可连接工具。使用端到端模型直接处理：
-
-```
-用户语音 → [Realtime Model] → 助手语音
-```
-
-**优点：**
-
- 更低延迟
- 更自然的语音
- 架构简单
-
-**缺点：**
-
- 依赖特定供应商
- 成本较高
- 可定制性有限
-
-### 选择建议
-
-| 场景 | 推荐引擎 |
-|------|---------|
-| 成本敏感 | 管线式 |
-| 延迟敏感 | 多模态 |
-| 需要特定 ASR/TTS | 管线式 |
-| 追求最自然体验 | 多模态 |
-
---
-
-## 智能打断 (Barge-in)
-
-**智能打断**是指用户在助手说话时可以随时插话，系统能够：
-
-1. 检测用户开始说话
-2. 立即停止 TTS 播放
-3. 处理用户新的输入
-
-### 打断检测方式
-
-| 方式 | 说明 |
-|------|------|
-| **VAD** | Voice Activity Detection，检测到声音活动即打断 |
-| **语义** | 基于语音内容判断是否有意义的打断 |
-| **混合** | VAD + 语义结合，减少误触发 |
-
-### 打断流程
-
-```mermaid
-sequenceDiagram
-    participant User as 用户
-    participant Engine as 引擎
-    participant TTS as TTS
-
-    Note over Engine,TTS: 助手正在播放回复
-    Engine->>User: 音频流...
-    User->>Engine: 开始说话 (VAD 触发)
-    Engine->>Engine: 打断判断
-    Engine->>TTS: 停止合成
-    Engine->>User: output.audio.interrupted
-    Note over Engine: 处理新输入
-```
-
-## 用户语句端点（EoU End-of-Utterance）
-
-**用户语句端点（EoU）** 指系统判断「用户已经说完」的时刻。在管线式引擎中，只有检测到 EoU 后，才会把当前轮次的转写文本送给 LLM 并触发回复，避免用户短暂停顿时就误判为说完。
-
-### 检测方式
-
-EoU 基于 **VAD（声音活动检测）** 的输出：在用户**连续静音**达到设定时长后触发一次 EoU。若静音期间用户再次说话，静音计时会重置，因此句间短暂停顿不会触发 EoU，只有用户真正停止说话后才触发。
-
-| 概念 | 说明 |
-|------|------|
-| **静音阈值** | 连续静音超过该时长（毫秒）即判定为 EoU，对应配置如 `vad_eou_threshold_ms`（默认约 800ms） |
-| **最短语音** | 若语音过短（如杂音），不触发 EoU，避免误判 |
-| **一次一轮** | 每轮用户输入只产生一次 EoU，之后需重新检测语音再静音才会再次触发 |
-
-### 在管线中的位置
-
-```
-用户语音 → [VAD] → [EoU 检测] → 静音达阈值 → 文本送 LLM → 回复 → [TTS]
-```
-
-助手配置中的 **「检测用户语句结束的灵敏度」** 即对应 EoU 的静音阈值：阈值越小，越容易判定为「说完」，响应更快但易在用户思考或短暂停顿时误触发；阈值越大，更稳但响应会稍慢。
-
---
-
-## 工具调用 (Tool Calling)
-
-助手可以通过**工具**扩展能力，访问外部系统或执行特定操作。
-
-### 工具类型
-
-管线式引擎中的 LLM 与实时交互引擎均可连接**工具**，包括：
-
-| 类型 | 说明 | 示例 |
-|------|------|------|
-| **Webhook** | 调用外部 HTTP API | 查询订单、预约日程 |
-| **客户端工具** | 由客户端执行的操作 | 获取客户端地理位置、请求用户同意、打开客户端相机 |
-| **内建工具** | 平台提供的工具 | 代码执行、计算器 |
-
-### 工具调用流程
-
-```mermaid
-sequenceDiagram
-    participant User as 用户
-    participant LLM as LLM
-    participant Tool as 工具
-
-    User->>LLM: "帮我查一下订单状态"
-    LLM->>LLM: 决定调用工具
-    LLM->>Tool: get_order_status(order_id)
-    Tool-->>LLM: {status: "已发货"}
-    LLM->>User: "您的订单已发货"
-```
-
---
-
-## 知识库 (Knowledge Base)
-
-**知识库**让助手能够基于私有文档回答问题，实现 RAG（检索增强生成）。
-
-### 工作原理
-
-```mermaid
-flowchart LR
-    subgraph Indexing["索引阶段"]
-        Doc[文档] --> Chunk[分块]
-        Chunk --> Embed[向量化]
-        Embed --> Store[(向量数据库)]
-    end
-
-    subgraph Query["查询阶段"]
-        Q[用户问题] --> QEmbed[问题向量化]
-        QEmbed --> Search[相似度搜索]
-        Store --> Search
-        Search --> Context[相关上下文]
-        Context --> LLM[LLM 生成回答]
-    end
-```
-
-### 支持的文档格式
-
- PDF
- Word (.docx)
- Markdown
- 纯文本
- HTML
-
---
-
-## 动态变量
-
-**动态变量**允许在运行时向助手注入上下文信息。
-
-### 使用方式
-
-在系统提示词中使用 `{{variable}}` 占位符：
-
-```
-你是{{company_name}}的客服助手。
-当前用户是{{customer_name}}，会员等级为{{tier}}。
-```
-
-连接时通过 `dynamicVariables` 传入：
-
-```json
-{
-  "type": "session.start",
-  "metadata": {
-    "dynamicVariables": {
-      "company_name": "ABC 公司",
-      "customer_name": "张三",
-      "tier": "VIP"
-    }
-  }
-}
-```
-
---
-
-## 下一步
-
- [快速开始](../quickstart/index.md) - 创建第一个助手
- [助手配置](../assistants/configuration.md) - 详细配置说明
- [WebSocket 协议](../api-reference/websocket.md) - API 接口详情