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:
hhs
2026-06-14 08:52:36 +08:00
parent a6ce6d9c4f
commit 6e0c67e1cb
8 changed files with 171 additions and 170 deletions

View File

@@ -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-4oLLM、DeepgramSTT、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-4oLLM、DeepgramSTT、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/Redis30 分钟 TTL |
| AI Orchestrator | STT→LLM→TTS 流式并行管道编排 |
| AI Service Layer | AI 服务抽象层STT/LLM/TTS 多 provider |
| REST API | 健康检查、会话管理Gin 路由) |
| Models | 数据模型定义 |
| Model Router | 按请求选择 AI 模型(规划中) |
| Rate Limiter | 按用户的令牌桶速率限制(规划中) |
## 编码规范