Files

- 修复心跳 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：同步更新技术栈、模块结构、存储策略描述

2026-06-14 08:52:36 +08:00

5.0 KiB

Raw Blame History

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指引。

项目概述

CamTalk 是一款多模态实时 AI 视觉对话助手。用户通过摄像头和麦克风与 AI 交互，AI 理解视觉场景和语音输入后，以文字和语音形式给出自然回应。项目目前处于设计文档阶段，源代码正在逐步构建。

文档优先原则： 执行任何开发任务前，先读取 docs/ 下的相关设计文档（架构、接口、技术选型等），以文档为最高依据。代码实现应与文档一致；若有偏差，优先更新文档（尤其是接口文档）。

架构

三层系统：

浏览器客户端（React 18 + TypeScript, Vite）—— 媒体采集、边缘预处理（VAD 通过 @ricky0123/vad-web、关键帧检测通过 Canvas 像素比较）、UI 渲染。核心 Hook：useVisionSession()
Go 网关（Gin, gorilla/websocket, Viper, Zap）—— WebSocket 服务器、会话管理、AI 编排。每个 WebSocket 连接一个 goroutine。
云端 AI 服务 —— 通过 OpenAI 兼容接口可灵活切换。默认：GPT-4o（LLM）、Deepgram（STT）、OpenAI TTS。仅通过 Go 网关访问，浏览器不直连。

关键模式：LLM 文本流和 TTS 音频流并行推送给客户端，以最小化感知延迟。

存储：MVP 阶段使用进程内存（MemoryManager），Redis 实现已就绪可通过配置切换，PostgreSQL 为规划中。Repository 接口模式（HistoryRepository、UsageRepository），MVP 用内存实现。

技术栈

层级	技术
前端	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

构建与运行命令

# 前端
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 ./...                 # 静态分析

基础设施：MVP 使用进程内存管理会话状态。Redis 已实现可通过配置切换，PostgreSQL 为规划中。

WebSocket 协议

端点：ws://localhost:8080/ws

所有消息为 JSON 文本帧，统一信封格式 {type, request_id?, timestamp?}。完整契约见 docs/03-接口文档.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/sessions — 创建会话（可选，MVP 在 WS 连接时自动创建）
DELETE /api/sessions/{id} — 销毁会话

错误码

INVALID_MESSAGE、SESSION_NOT_FOUND、RATE_LIMITED、IMAGE_TOO_LARGE、AUDIO_TOO_SHORT、LLM_TIMEOUT、LLM_ERROR、STT_ERROR、TTS_ERROR、INTERNAL_ERROR

前端组件结构

组件	职责
`CameraManager`	摄像头流采集
`MicManager`	麦克风音频采集
`EdgeProcessor`	VAD + 关键帧检测（Canvas 像素比较）
`WebSocketManager`	WebSocket 连接生命周期管理
`ChatPanel`	消息展示
`VideoPreview`	摄像头画面预览

后端模块结构

模块	职责
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	按用户的令牌桶速率限制（规划中）

编码规范

Go：遵循标准 Go 规范。所有 AI 调用使用 context.Context 做取消/超时。并发 map 访问使用 sync.RWMutex。结构体标签用 json:"snake_case"。
TypeScript：严格模式。所有数据模型用接口定义。WebSocket 消息类型用可辨识联合类型（type 字段）。
提交信息：Conventional Commits 格式，描述用中文。示例：feat: 添加 WebSocket 连接管理、fix: 修复心跳超时判断、docs: 更新接口文档
禁止自动 push：除非用户明确要求。
文档优先：实现功能前先读取 docs/ 下的相关设计文档。实现与文档不一致时，优先更新 docs/ 下的接口文档。

5.0 KiB Raw Blame History Unescape Escape