Update documentation and configuration for Realtime Agent Studio

- Revised mkdocs.yml to reflect the new site name and description, enhancing clarity for users. - Added a changelog.md to document important changes and updates for the project. - Introduced a roadmap.md to outline development plans and progress for future releases. - Expanded index.md with a comprehensive overview of the platform, including core features and installation instructions. - Enhanced concepts documentation with detailed explanations of assistants, engines, and their configurations. - Updated configuration documentation to provide clear guidance on environment setup and service configurations. - Added extra JavaScript for improved user experience in the documentation site.
2026-03-02 23:35:22 +08:00
parent 80fff09b76
commit 4c05131536
15 changed files with 2529 additions and 236 deletions
--- a/docs/content/concepts/index.md
+++ b/docs/content/concepts/index.md
@@ -0,0 +1,284 @@
+# 核心概念
+
+本章节介绍 Realtime Agent Studio 中的核心概念，帮助你更好地理解和使用平台。
+
+---
+
+## 概念总览
+
+```mermaid
+flowchart TB
+    subgraph Platform["RAS 平台"]
+        Assistant[助手 Assistant]
+        
+        subgraph Resources["资源库"]
+            LLM[LLM 模型]
+            ASR[ASR 模型]
+            TTS[TTS 声音]
+            KB[知识库]
+        end
+        
+        subgraph Engine["交互引擎"]
+            Pipeline[管线式引擎]
+            Multimodal[多模态引擎]
+        end
+        
+        Session[会话 Session]
+    end
+
+    Assistant --> LLM
+    Assistant --> ASR
+    Assistant --> TTS
+    Assistant --> KB
+    Assistant --> Engine
+    Engine --> Session
+```
+
+---
+
+## 助手 (Assistant)
+
+**助手**是 RAS 的核心实体，代表一个可对话的 AI 智能体。
+
+### 助手配置
+
+每个助手包含以下配置：
+
+| 配置项 | 说明 |
+|-------|------|
+| **名称** | 助手的显示名称 |
+| **系统提示词** | 定义助手角色、行为、限制 |
+| **LLM 模型** | 选择用于生成回复的大语言模型 |
+| **ASR 模型** | 选择用于语音识别的模型 |
+| **TTS 声音** | 选择用于语音合成的音色 |
+| **工具** | 配置助手可调用的外部工具 |
+| **知识库** | 关联的知识库（用于 RAG） |
+
+### 助手生命周期
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: 创建
+    Draft --> Draft: 编辑配置
+    Draft --> Published: 发布
+    Published --> Draft: 取消发布
+    Published --> Published: 更新配置
+    Published --> [*]: 删除
+```
+
+---
+
+## 会话 (Session)
+
+**会话**代表一次完整的对话交互，从用户连接到断开。
+
+### 会话状态
+
+```mermaid
+stateDiagram-v2
+    [*] --> Connecting: WebSocket 连接
+    Connecting --> Started: session.started
+    Started --> Active: 对话中
+    Active --> Active: 多轮对话
+    Active --> Stopped: session.stop
+    Stopped --> [*]: 连接关闭
+```
+
+### 会话数据
+
+每个会话记录包含：
+
+- **基本信息** - ID、时长、时间戳
+- **音频数据** - 用户和助手的音频记录
+- **转写文本** - ASR 识别结果
+- **LLM 交互** - 输入输出和工具调用
+- **元数据** - 渠道、来源、自定义变量
+
+---
+
+## 管线式引擎 vs 多模态引擎
+
+RAS 支持两种引擎架构，适用于不同场景。
+
+### 管线式引擎 (Pipeline)
+
+将语音交互拆分为三个独立环节：
+
+```
+用户语音 → [ASR] → 文本 → [LLM] → 回复 → [TTS] → 助手语音
+```
+
+**优点：**
+
+- 灵活选择各环节供应商
+- 可独立优化每个环节
+- 成本可控
+
+**缺点：**
+
+- 延迟较高（累加延迟）
+- 需要协调多个服务
+
+### 多模态引擎 (Multimodal)
+
+使用端到端模型直接处理：
+
+```
+用户语音 → [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: 处理新输入
+```
+
+---
+
+## 工具调用 (Tool Calling)
+
+助手可以通过**工具**扩展能力，访问外部系统或执行特定操作。
+
+### 工具类型
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| **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 接口详情