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/)

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/)

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 模式

固定使用 CustomLLM 模式：火山 RTC 回调本后端的 /api/chat_callback，再由本后端调用方舟 LLM。

关键环境变量（backend/.env）

CUSTOM_ACCESS_KEY_ID / CUSTOM_SECRET_KEY: 火山引擎凭证
CUSTOM_RTC_APP_ID / CUSTOM_RTC_APP_KEY: RTC 应用配置
CUSTOM_LLM_URL: 回调地址（默认本地，生产用 ngrok 公网地址）
LOCAL_LLM_API_KEY / LOCAL_LLM_MODEL: 本地回调调用方舟的凭证
CUSTOM_ASR_APP_ID / CUSTOM_TTS_APP_ID: 语音识别/合成配置
CUSTOM_AVATAR_*: 数字人配置（可选）

2.6 KiB Raw Blame History Unescape Escape