64 lines
2.5 KiB
Markdown
64 lines
2.5 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
RTC AIGC Demo — 基于火山引擎 RTC SDK 的实时 AI 语音对话演示应用，前后端分离架构。前端 React + TypeScript，后端 Python FastAPI。
|
||
|
||
## 常用命令
|
||
|
||
### 前端 (frontend/)
|
||
```bash
|
||
cd frontend
|
||
npm install # 安装依赖
|
||
npm run dev # 开发服务器 (localhost:3000)
|
||
npm run build # 生产构建
|
||
npm run eslint # ESLint 检查并修复
|
||
npm run stylelint # LESS 样式检查
|
||
npm run prettier # 代码格式化
|
||
npm run test # 运行测试
|
||
```
|
||
|
||
### 后端 (backend/)
|
||
```bash
|
||
cd backend
|
||
cp .env.example .env # 首次需复制环境变量配置
|
||
uv sync # 安装依赖（使用 uv 包管理器）
|
||
uv run uvicorn server:app --host 0.0.0.0 --port 3001 --reload # 启动开发服务器
|
||
```
|
||
|
||
## 架构
|
||
|
||
### 前后端通信
|
||
- 前端默认连接 `http://localhost:3001`（配置在 `frontend/src/config/index.ts` 的 `AIGC_PROXY_HOST`）
|
||
- 后端 FastAPI 入口：`backend/server.py`
|
||
|
||
### 前端核心模块
|
||
- **状态管理**: Redux Toolkit，两个 slice：`store/slices/room.ts`（房间状态）、`store/slices/device.ts`（设备状态）
|
||
- **RTC 封装**: `src/lib/RtcClient.ts` 封装 `@volcengine/rtc` SDK
|
||
- **API 层**: `src/app/api.ts` 定义 `getScenes`、`StartVoiceChat`、`StopVoiceChat` 接口
|
||
- **页面结构**: `pages/MainPage/` 包含 Room（通话中）和 Antechamber（通话前）两个主要区域
|
||
- **路径别名**: `@/` → `src/`（通过 craco + tsconfig paths 配置）
|
||
- **UI 组件库**: Arco Design
|
||
- **CSS**: LESS
|
||
|
||
### 后端核心模块
|
||
- **场景配置**: `config/custom_scene.py` — 从环境变量构建场景配置，自动生成 RoomId/UserId/Token
|
||
- **API 代理**: `/proxy` 端点转发请求到火山引擎 RTC OpenAPI（含请求签名）
|
||
- **LLM 集成**: `services/local_llm_service.py` — Ark SDK 对接，SSE 流式响应
|
||
- **请求签名**: `security/signer.py`
|
||
- **Token 生成**: `security/rtc_token.py`
|
||
|
||
### LLM 模式
|
||
通过 `CUSTOM_LLM_MODE` 环境变量切换：
|
||
- `ArkV3`: 直接使用火山方舟 LLM
|
||
- `CustomLLM`: 自定义 LLM 回调（`/api/chat_callback` 端点）
|
||
|
||
### 关键环境变量（backend/.env）
|
||
- `CUSTOM_ACCESS_KEY_ID` / `CUSTOM_SECRET_KEY`: 火山引擎凭证
|
||
- `CUSTOM_RTC_APP_ID` / `CUSTOM_RTC_APP_KEY`: RTC 应用配置
|
||
- `CUSTOM_LLM_MODE` + 对应 LLM 配置
|
||
- `CUSTOM_ASR_APP_ID` / `CUSTOM_TTS_APP_ID`: 语音识别/合成配置
|
||
- `CUSTOM_AVATAR_*`: 数字人配置（可选）
|