docs: 文档与代码一致性检查与修复
- 修复心跳 Bug:应用层 ping 不更新 lastPong,60 秒后连接会被错误断开 - 03-接口文档:audio/mpeg→audio/mp3、STTConfig/TTSConfig 补充 Model 字段、 APP_ENV 环境变量名修正、配置搜索路径补充、.env 加载说明、Vite proxy 说明修正 - 02-系统架构:补充 ConfigPanel/Toast 组件、Model Router/Rate Limiter 标注规划中、 补充 Gin 框架、MVP 存储改为 Memory、AI 服务 provider 更新、Orchestrator 伪代码对齐 - 04-技术选型:新增 AI 服务栈选型章节(STT/LLM/TTS)、PostgreSQL 标注规划中 - 06-语音交互:VAD 参数名修正、STT 改为一次性识别描述、音频编码格式补充 - 07-视觉理解:关键帧检测代码改为 TypeScript、分辨率修正、阈值逻辑统一 - 08-成本控制:变量名修正、未实现功能标注规划中、对话历史裁剪策略补充 - CLAUDE.md:同步更新技术栈、模块结构、存储策略描述
This commit is contained in:
36
CLAUDE.md
36
CLAUDE.md
@@ -12,24 +12,23 @@ CamTalk 是一款多模态实时 AI 视觉对话助手。用户通过摄像头
|
||||
|
||||
三层系统:
|
||||
|
||||
1. **浏览器客户端**(React 18 + TypeScript, Vite)—— 媒体采集、边缘预处理(VAD 通过 `@ricky0123/vad-web`、关键帧检测通过 ONNX Runtime Web)、UI 渲染。核心 Hook:`useVisionSession()`
|
||||
2. **Go 网关**(gorilla/websocket, Redis, Viper, Zap)—— WebSocket 服务器、会话管理、模型路由、AI 编排、速率限制。每个 WebSocket 连接一个 goroutine。
|
||||
3. **云端 AI 服务** —— GPT-4o(LLM)、Deepgram(STT)、OpenAI TTS。仅通过 Go 网关访问,浏览器不直连。
|
||||
1. **浏览器客户端**(React 18 + TypeScript, Vite)—— 媒体采集、边缘预处理(VAD 通过 `@ricky0123/vad-web`、关键帧检测通过 Canvas 像素比较)、UI 渲染。核心 Hook:`useVisionSession()`
|
||||
2. **Go 网关**(Gin, gorilla/websocket, Viper, Zap)—— WebSocket 服务器、会话管理、AI 编排。每个 WebSocket 连接一个 goroutine。
|
||||
3. **云端 AI 服务** —— 通过 OpenAI 兼容接口可灵活切换。默认:GPT-4o(LLM)、Deepgram(STT)、OpenAI TTS。仅通过 Go 网关访问,浏览器不直连。
|
||||
|
||||
**关键模式**:LLM 文本流和 TTS 音频流并行推送给客户端,以最小化感知延迟。
|
||||
|
||||
**存储**:冷热分离 —— Redis 存实时会话状态,PostgreSQL 存对话历史和用量统计(MVP 后引入)。Repository 接口模式(`HistoryRepository`、`UsageRepository`),MVP 用内存实现。
|
||||
**存储**:MVP 阶段使用进程内存(`MemoryManager`),Redis 实现已就绪可通过配置切换,PostgreSQL 为规划中。Repository 接口模式(`HistoryRepository`、`UsageRepository`),MVP 用内存实现。
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 层级 | 技术 |
|
||||
|------|------|
|
||||
| 前端 | React 18, TypeScript, Vite, ONNX Runtime Web, @ricky0123/vad-web |
|
||||
| 后端 | Go, gorilla/websocket, Redis, Viper, Zap |
|
||||
| LLM | GPT-4o(主), Claude Sonnet(备) |
|
||||
| STT | Deepgram(主), FunASR(自部署备选) |
|
||||
| TTS | OpenAI TTS(主), Edge TTS(免费替代) |
|
||||
| 模型路由 | GPT-4o-mini 用于轻量分类 |
|
||||
| 前端 | React 18, TypeScript, Vite, @ricky0123/vad-web |
|
||||
| 后端 | Go, Gin, gorilla/websocket, Viper, Zap |
|
||||
| LLM | GPT-4o(默认,通过 OpenAI 兼容接口可切换) |
|
||||
| STT | Deepgram(默认) / MiMo ASR |
|
||||
| TTS | OpenAI TTS(默认) / MiMo TTS |
|
||||
|
||||
## 构建与运行命令
|
||||
|
||||
@@ -50,7 +49,7 @@ go test -run TestName ./path # 运行单个测试
|
||||
go vet ./... # 静态分析
|
||||
```
|
||||
|
||||
基础设施:Redis 为会话状态必需。PostgreSQL 为 MVP 可选(内存回退)。
|
||||
基础设施:MVP 使用进程内存管理会话状态。Redis 已实现可通过配置切换,PostgreSQL 为规划中。
|
||||
|
||||
## WebSocket 协议
|
||||
|
||||
@@ -80,7 +79,7 @@ go vet ./... # 静态分析
|
||||
|------|------|
|
||||
| `CameraManager` | 摄像头流采集 |
|
||||
| `MicManager` | 麦克风音频采集 |
|
||||
| `EdgeProcessor` | VAD + 关键帧检测(ONNX Runtime) |
|
||||
| `EdgeProcessor` | VAD + 关键帧检测(Canvas 像素比较) |
|
||||
| `WebSocketManager` | WebSocket 连接生命周期管理 |
|
||||
| `ChatPanel` | 消息展示 |
|
||||
| `VideoPreview` | 摄像头画面预览 |
|
||||
@@ -89,11 +88,14 @@ go vet ./... # 静态分析
|
||||
|
||||
| 模块 | 职责 |
|
||||
|------|------|
|
||||
| WebSocket Hub | 连接管理、广播/定向推送 |
|
||||
| Session Manager | 会话状态、对话历史(Redis + TTL) |
|
||||
| Model Router | 按请求选择 AI 模型(规则引擎 + 成本阈值) |
|
||||
| AI Orchestrator | 并行/串行 AI 调用编排,context 超时控制 |
|
||||
| Rate Limiter | 按用户的令牌桶速率限制 |
|
||||
| WebSocket Handler | 连接管理、单播消息推送 |
|
||||
| Session Manager | 会话状态、对话历史(Memory/Redis,30 分钟 TTL) |
|
||||
| AI Orchestrator | STT→LLM→TTS 流式并行管道编排 |
|
||||
| AI Service Layer | AI 服务抽象层(STT/LLM/TTS 多 provider) |
|
||||
| REST API | 健康检查、会话管理(Gin 路由) |
|
||||
| Models | 数据模型定义 |
|
||||
| Model Router | 按请求选择 AI 模型(规划中) |
|
||||
| Rate Limiter | 按用户的令牌桶速率限制(规划中) |
|
||||
|
||||
## 编码规范
|
||||
|
||||
|
||||
Reference in New Issue
Block a user