125 lines
6.6 KiB
Markdown
125 lines
6.6 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指引。
|
||
|
||
## 项目概述
|
||
|
||
CamTalk 是一款多模态实时 AI 视觉对话助手。用户通过摄像头和麦克风与 AI 交互，AI 理解视觉场景和语音输入后，以文字和语音形式给出自然回应。
|
||
|
||
> **文档优先原则：** 执行任何开发任务前，先读取 `docs/` 下的相关设计文档（架构、接口、技术选型等），以文档为最高依据。代码实现应与文档一致；若有偏差，优先更新文档（尤其是接口文档）。
|
||
|
||
## 架构
|
||
|
||
三层系统：
|
||
|
||
1. **浏览器客户端**（React 18 + TypeScript, Vite）—— 媒体采集、边缘预处理（VAD 通过 `@ricky0123/vad-web`、关键帧检测通过 Canvas 像素比较）、UI 渲染。核心 Hook：`useVisionSession()`
|
||
2. **Go 网关**（Gin, gorilla/websocket, Viper, Zap）—— WebSocket 服务器、会话管理、AI 编排（基于 CloudWeGo Eino Graph）。每个 WebSocket 连接一个 goroutine。
|
||
3. **云端 AI 服务** —— 通过 OpenAI 兼容接口可灵活切换。默认：DashScope qwen3-vl-plus（LLM）、MiMo ASR（STT）、MiMo TTS（TTS）。仅通过 Go 网关访问，浏览器不直连。
|
||
|
||
**关键模式**：AI 编排基于 Eino Graph 声明式 DAG（`START → STT → History → ChatModel → Msg2Str → Splitter → TTS → Done → END`），LLM token 通过 Callback 实时推送，TTS 逐句合成并行推送，最小化感知延迟。
|
||
|
||
**存储**：三级存储架构（TieredManager）—— L1 Memory → L2 Redis → L3 PostgreSQL，自动降级。Repository 接口模式（UserRepository、MessageRepository、SessionRepository），PostgreSQL + 内存双实现。
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 前端 | React 18, TypeScript, Vite, @ricky0123/vad-web |
|
||
| 后端 | Go, Gin, gorilla/websocket, Viper, Zap |
|
||
| AI 编排 | CloudWeGo Eino Graph（声明式 DAG 编排） |
|
||
| LLM | DashScope qwen3-vl-plus（默认，通过 eino-ext OpenAI ChatModel 接入） |
|
||
| STT | MiMo ASR（默认） / Deepgram |
|
||
| TTS | MiMo TTS（默认） / OpenAI TTS |
|
||
|
||
## 构建与运行命令
|
||
|
||
```bash
|
||
# 前端
|
||
cd frontend && npm install
|
||
npm run dev # Vite 开发服务器
|
||
npm run build # 生产构建
|
||
npm run lint # ESLint 检查
|
||
npm run test # Vitest 测试
|
||
|
||
# 后端
|
||
cd backend && go mod download
|
||
go run ./cmd/server # 启动网关，监听 :8080
|
||
go build -o bin/camtalk ./cmd/server
|
||
go test ./... # 运行所有测试
|
||
go test -run TestName ./path # 运行单个测试
|
||
go vet ./... # 静态分析
|
||
```
|
||
|
||
基础设施：三级存储架构（L1 Memory → L2 Redis → L3 PostgreSQL），通过配置控制启用层级。
|
||
|
||
## WebSocket 协议
|
||
|
||
端点：`ws://localhost:8080/ws?token=<access_token>&conversation_id=<uuid>`
|
||
|
||
所有消息为 JSON 文本帧，统一信封格式 `{type, request_id?, timestamp?}`。完整契约见 `docs/02-接口文档.md`。
|
||
|
||
**客户端 → 服务端**：`query`（图像 Base64 + 音频 Base64）、`config`、`interrupt`、`ping`
|
||
**服务端 → 客户端**：`connected`、`stt_result`、`llm_chunk`、`llm_done`、`tts_audio`、`error`、`pong`
|
||
|
||
**心跳**：客户端每 30 秒 ping，服务端 60 秒无 ping 断开连接。
|
||
**重连**：指数退避 + 抖动 —— 1s, 2s, 4s, 8s… 最大 30s。
|
||
|
||
## REST API（辅助）
|
||
|
||
- `GET /api/health` — 健康检查（版本、运行时间、活跃会话数）
|
||
- `POST /api/auth/register` — 注册
|
||
- `POST /api/auth/login` — 登录
|
||
- `POST /api/auth/refresh` — 刷新 Token
|
||
- `POST /api/auth/logout` — 登出
|
||
- `GET /api/conversations` — 对话列表
|
||
- `POST /api/conversations` — 创建对话
|
||
- `GET/PATCH/DELETE /api/conversations/:id` — 对话详情/改标题/删除
|
||
- `GET /api/conversations/:id/messages` — 获取对话消息
|
||
|
||
## 错误码
|
||
|
||
`INVALID_MESSAGE`、`SESSION_NOT_FOUND`、`RATE_LIMITED`、`IMAGE_TOO_LARGE`、`AUDIO_TOO_SHORT`、`LLM_TIMEOUT`、`LLM_ERROR`、`STT_ERROR`、`TTS_ERROR`、`INTERNAL_ERROR`、`USERNAME_TAKEN`、`INVALID_CREDENTIALS`、`INVALID_TOKEN`、`INVALID_INPUT`
|
||
|
||
## 前端组件结构
|
||
|
||
| 组件 | 职责 |
|
||
|------|------|
|
||
| `LandingPage` | 未登录时的着陆页，内嵌 LoginModal 登录/注册弹窗 |
|
||
| `AuthPage` | 登录/注册表单（备用） |
|
||
| `CameraManager` | 摄像头流采集 |
|
||
| `MicManager` | 麦克风音频采集 |
|
||
| `EdgeProcessor` | VAD + 关键帧检测（Canvas 像素比较） |
|
||
| `WebSocketManager` | WebSocket 连接生命周期管理 |
|
||
| `ChatPanel` | 消息展示、流式回复、文本输入、场景选择 |
|
||
| `VideoPreview` | 摄像头画面预览 |
|
||
| `SessionSidebar` | 左侧抽屉式对话列表（搜索、重命名、删除、时间分组） |
|
||
| `ConfigPanel` | 右侧抽屉式配置面板（主题、TTS、语言、场景、登出） |
|
||
| `Toast` | 轻量通知提示 |
|
||
|
||
核心 Hook：`useVisionSession()` 封装一次完整的视觉对话会话。`useSessionList()` 管理对话列表 CRUD（通过 REST API）。
|
||
|
||
## 后端模块结构
|
||
|
||
| 模块 | 职责 |
|
||
|------|------|
|
||
| WebSocket Handler | 连接管理、JWT 认证、单播消息推送 |
|
||
| Session Manager | 会话状态、对话历史（三级存储：Memory/Redis/PostgreSQL，30 分钟 TTL） |
|
||
| Eino 编排层 | 基于 Eino Graph 的声明式 AI 编排（7 节点 DAG，Stream 模式，Callback AOP） |
|
||
| AI Orchestrator | `EinoOrchestrator` 适配器，包装 Graph 实现 `Orchestrator` 接口 |
|
||
| AI Service Layer | AI 服务抽象层（STT/TTS 多 provider，LLM 通过 eino-ext ChatModel） |
|
||
| Auth | JWT 双 token 轮转认证，bcrypt 密码哈希 |
|
||
| Store | 持久化存储层（UserRepository/MessageRepository/SessionRepository，内存 + PostgreSQL） |
|
||
| REST API | 健康检查、认证、对话管理（Gin 路由） |
|
||
| Models | 数据模型定义 |
|
||
| Migrations | 数据库版本化迁移（嵌入式 SQL） |
|
||
| Model Router | 按请求选择 AI 模型（规划中） |
|
||
| Rate Limiter | 按用户的令牌桶速率限制（规划中） |
|
||
|
||
## 编码规范
|
||
|
||
- **Go**：遵循标准 Go 规范。所有 AI 调用使用 `context.Context` 做取消/超时。并发 map 访问使用 `sync.RWMutex`。结构体标签用 `json:"snake_case"`。
|
||
- **TypeScript**：严格模式。所有数据模型用接口定义。WebSocket 消息类型用可辨识联合类型（`type` 字段）。
|
||
- **提交信息**：Conventional Commits 格式，描述用中文。示例：`feat: 添加 WebSocket 连接管理`、`fix: 修复心跳超时判断`、`docs: 更新接口文档`
|
||
- **禁止自动 push**：除非用户明确要求。
|
||
- **文档优先**：实现功能前先读取 `docs/` 下的相关设计文档。实现与文档不一致时，优先更新 `docs/` 下的接口文档。
|