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/getting-started/index.md
+++ b/docs/content/getting-started/index.md
@@ -1,12 +1,12 @@
-# 安装部署
+# 环境与部署

-本章节介绍如何安装和配置 Realtime Agent Studio (RAS) 开发环境。
+本页属于“快速开始”中的环境与部署路径，只负责把服务跑起来、说明配置入口和部署方式。首次创建助手请转到 [创建第一个助手](../quickstart/index.md)。

 ---

-## 系统组件
+## 先理解部署对象

-RAS 由三个核心服务组成：
+Realtime Agent Studio（RAS）通常由三个核心服务组成：

 ```mermaid
 flowchart LR
@@ -26,47 +26,32 @@ flowchart LR
    Engine <--> API
 ```

-| 组件 | 端口 | 说明 |
-|------|------|------|
-| **Web 前端** | 3000 | React + TypeScript 管理控制台 |
-| **API 服务** | 8080 | Python FastAPI 后端 |
-| **Engine 服务** | 8000 | 实时对话引擎（WebSocket） |
+| 组件 | 默认端口 | 负责什么 |
+|------|----------|----------|
+| **Web 前端** | 3000 | 管理控制台与调试界面 |
+| **API 服务** | 8080 | 资源管理、配置持久化、历史数据 |
+| **Engine 服务** | 8000 | 实时会话、事件流和音频流 |

---
+## 选择你的安装方式

-## 快速安装
+### 方式一：Docker Compose

-### 方式一：Docker Compose（推荐）
-
-最快捷的启动方式，适合快速体验和生产部署。
+适合希望尽快跑通一套完整环境的团队。

 ```bash
-# 1. 克隆项目
+# 仓库目录示例沿用当前代码仓库 slug
+# 你本地实际目录名可以不同
 git clone https://github.com/your-org/AI-VideoAssistant.git
 cd AI-VideoAssistant

-# 2. 启动服务
 docker-compose up -d
-
-# 3. 访问控制台
-open http://localhost:3000
 ```

-!!! tip "首次启动"
-    首次启动需要构建镜像，可能需要几分钟时间。
-
 ### 方式二：本地开发

-适合需要修改代码的开发者。
+适合需要分别调试前端、API 和 Engine 的开发者。

-#### 1. 克隆项目
-
-```bash
-git clone https://github.com/your-org/AI-VideoAssistant.git
-cd AI-VideoAssistant
-```
-
-#### 2. 启动 API 服务
+#### 启动 API 服务

 ```bash
 cd api
@@ -76,7 +61,7 @@ pip install -r requirements.txt
 uvicorn main:app --host 0.0.0.0 --port 8080 --reload
 ```

-#### 3. 启动 Engine 服务
+#### 启动 Engine 服务

 ```bash
 cd engine
@@ -86,7 +71,7 @@ pip install -r requirements.txt
 python main.py
 ```

-#### 4. 启动 Web 前端
+#### 启动 Web 前端

 ```bash
 cd web
@@ -94,97 +79,37 @@ npm install
 npm run dev
 ```

-访问 `http://localhost:3000`
+## 基础验证

---
+完成安装后，至少确认以下入口可访问：

-## 验证安装
+| 服务 | 地址 | 用途 |
+|------|------|------|
+| Web | `http://localhost:3000` | 打开控制台 |
+| API | `http://localhost:8080/docs` | 查看管理接口 |
+| Engine | `http://localhost:8000/health` | 检查实时引擎健康状态 |

-### 检查服务状态
+如果你需要更完整的环境变量、配置文件和部署说明，请继续阅读本章节其他页面：

-| 服务 | URL | 预期结果 |
-|------|-----|---------|
-| Web | http://localhost:3000 | 看到登录/控制台页面 |
-| API | http://localhost:8080/docs | 看到 Swagger 文档 |
-| Engine | http://localhost:8000/health | 返回 `{"status": "ok"}` |
+- [环境要求](requirements.md)
+- [配置说明](configuration.md)
+- [部署概览](../deployment/index.md)
+- [Docker 部署](../deployment/docker.md)

-### 测试 WebSocket 连接
+## 目录结构（阅读导向）

-```javascript
-const ws = new WebSocket('ws://localhost:8000/ws?assistant_id=test');
-ws.onopen = () => console.log('Connected!');
-ws.onerror = (e) => console.error('Error:', e);
+```text
+repo/
+├── web/      # 管理控制台
+├── api/      # 控制面与管理接口
+├── engine/   # 实时交互引擎
+├── docker/   # 部署编排与镜像配置
+└── docs/     # 当前文档站点
 ```

---
+## 遇到问题时去哪里

-## 目录结构
+- 需要“快速判断往哪看”：先看 [常见问题](../resources/faq.md)
+- 需要“按步骤排查”：直接看 [故障排查](../resources/troubleshooting.md)
+- 已经跑通环境，准备创建助手：回到 [快速开始](../quickstart/index.md)

-```
-AI-VideoAssistant/
-├── web/                    # React 前端
-│   ├── src/
-│   │   ├── components/     # UI 组件
-│   │   ├── pages/          # 页面
-│   │   ├── stores/         # Zustand 状态
-│   │   └── api/            # API 客户端
-│   └── package.json
-├── api/                    # FastAPI 后端
-│   ├── app/
-│   │   ├── routers/        # API 路由
-│   │   ├── models/         # 数据模型
-│   │   └── services/       # 业务逻辑
-│   └── requirements.txt
-├── engine/                 # 实时交互引擎
-│   ├── app/
-│   │   ├── pipeline/       # 管线引擎
-│   │   └── multimodal/     # 多模态引擎
-│   └── requirements.txt
-├── docker/                 # Docker 配置
-│   └── docker-compose.yml
-└── docs/                   # 文档
-```
-
---
-
-## 常见问题
-
-### 端口被占用
-
-```bash
-# 查看端口占用
-# Linux/Mac
-lsof -i :3000
-
-# Windows
-netstat -ano | findstr :3000
-```
-
-修改对应服务的端口配置后重启。
-
-### Docker 构建失败
-
-```bash
-# 清理 Docker 缓存
-docker system prune -a
-
-# 重新构建
-docker-compose build --no-cache
-```
-
-### Python 依赖安装失败
-
-确保使用 Python 3.10+：
-
-```bash
-python --version  # 需要 3.10+
-```
-
---
-
-## 下一步
-
- [环境要求](requirements.md) - 详细的软件版本要求
- [配置说明](configuration.md) - 环境变量配置指南
- [快速开始](../quickstart/index.md) - 创建第一个助手
- [Docker 部署](../deployment/docker.md) - 镜像构建与编排