# 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_*`: 数字人配置（可选）