hhs
032de796c8
## 主要变更 ### 文档重构（减少 1199 行，-23%） - 01-架构设计.md: 503→369 行 (-27%)，删除 DDL/配置示例，精简鉴权/存储描述 - 02-接口文档.md: 1313→570 行 (-57%)，删除 Go 接口/Orchestrator 实现/配置管理 - 07-成本控制.md: 65→59 行 (-9%)，代码块替换为文件引用 ### 文档编号规范化 - 08-功能创意.md → 删除（内容整合到 README.md "功能扩展方向"） - 10-Eino框架与编排设计.md → 08-Eino框架与编排设计.md - 情景切换.md → 09-情景切换.md - 12-鉴权体系.md → 10-鉴权体系.md - 13-令牌桶限流.md → 11-令牌桶限流.md ### 交叉引用更新 - 01-架构设计.md: 更新对鉴权体系/令牌桶限流的引用为新编号 - README.md: 更新文档索引表、推荐阅读顺序、新增功能扩展方向 ### 删除过时文档 - 09-技术名词解释.md（内容已整合到 03-技术选型.md） - 10-Eino重构方案.md（历史记录，已完成） - 11-Eino框架技术文档.md（已合并到 08） - 情景切换功能完整文档.md（已规范化为 09） ## 重构原则 - 架构文档聚焦系统结构，移除实现细节 - 接口文档保留纯契约，删除内部实现 - 编号连续（01-11），语义清晰 - 通过交叉引用连接相关文档，避免重复
74 lines
4.1 KiB
Markdown
74 lines
4.1 KiB
Markdown
# CLAUDE.md
|
||
|
||
CamTalk — 多模态实时 AI 视觉对话助手（摄像头 + 麦克风 + 视觉 + 语音 AI）
|
||
|
||
> **文档优先原则：** 开发前先读 `docs/` 设计文档，以文档为准；若代码与文档不一致，优先更新文档（尤其接口文档）。详细设计见 `docs/01-13` 系列文档。**注意**：`docs/Eino/` 框架文档内容庞大（~75 个文件），仅在需要了解 Eino Graph/节点/Callback 等框架细节时才读取。
|
||
|
||
## 架构
|
||
|
||
三层系统：前端（React + Vite）→ Go 网关（Gin + WebSocket + Eino Graph AI 编排）→ AI 服务（DashScope LLM, MiMo STT/TTS）
|
||
|
||
**AI 编排流水线**（Eino Graph 7 节点 DAG）：`STT → History → ChatModel → Msg2Str → Splitter → TTS → Done`。LLM token 通过 Callback 实时推送，TTS 逐句并行合成。
|
||
|
||
**会话存储**（TieredManager）：L1 Memory → L2 Redis → L3 PostgreSQL 三级存储，30 分钟 TTL，Redis 故障自动降级。
|
||
|
||
**鉴权**：JWT 双 token 轮转（Access 120min + Refresh 7d），重放攻击检测（DB hash 校验），Redis 缓存装饰器。
|
||
|
||
## 技术栈
|
||
|
||
前端：React 18 + TypeScript + Vite，VAD（@ricky0123/vad-web），ONNX Runtime
|
||
后端：Go 1.25+, Gin, WebSocket, Viper, Zap, CloudWeGo Eino Graph
|
||
AI：DashScope qwen3-vl-plus, MiMo ASR/TTS（可切换 Deepgram/OpenAI TTS）
|
||
存储：PostgreSQL 15 + Redis 7
|
||
|
||
## 快速启动
|
||
|
||
```bash
|
||
# 前端：npm run dev（Vite，代理 /ws 和 /api 到 :8080）
|
||
# 后端：go run ./cmd/server（监听 :8080）
|
||
# 生产：./deploy.sh up（4 容器：frontend/backend/postgres/redis）
|
||
```
|
||
|
||
核心环境变量（`.env.example`）：`CAMTALK_AI_LLM_API_KEY`, `CAMTALK_AI_STT_API_KEY`, `CAMTALK_AUTH_JWT_SECRET`, `CAMTALK_STORAGE_DSN`
|
||
|
||
配置优先级：环境变量 > `config.{APP_ENV}.yaml` > `config.yaml`
|
||
环境切换：`APP_ENV=dev|prod`（dev 默认，prod 启用限流 + 严格 CORS）
|
||
|
||
## 协议与 API
|
||
|
||
**WebSocket**：`ws://localhost:8080/ws?token=<jwt>&conversation_id=<uuid>`
|
||
- 客户端：`query`（图像/音频 Base64）, `config`, `interrupt`, `ping`
|
||
- 服务端：`connected`, `stt_result`, `llm_chunk`, `llm_done`, `tts_audio`, `error`, `pong`
|
||
- 心跳：客户端 30s ping，服务端 60s 超时断连；重连：指数退避 1s→30s
|
||
- 实现：`CamTalkWebSocket` 单例（`frontend/src/lib/websocket.ts`），订阅模式，自动重连
|
||
|
||
**REST API**：`/api/auth/*`（注册/登录/刷新/登出），`/api/conversations/*`（CRUD + 消息分页），`/api/health`
|
||
|
||
**错误码**：`INVALID_MESSAGE`, `SESSION_NOT_FOUND`, `RATE_LIMITED`, `IMAGE_TOO_LARGE`, `LLM_TIMEOUT`, `STT/TTS/LLM_ERROR`, `INVALID_TOKEN`, 等
|
||
|
||
## 关键文件路径
|
||
|
||
**后端核心**：
|
||
- `backend/internal/eino/` — Graph 定义、节点、Callback、Adapter、State
|
||
- `backend/internal/session/tiered.go` — 三级会话存储
|
||
- `backend/internal/store/` — Repository 实现（PG + 内存 + Redis 缓存）
|
||
- `backend/internal/ws/handler.go` — WebSocket 连接管理
|
||
- `backend/migrations/` — SQL 迁移文件
|
||
|
||
**前端核心**：
|
||
- `frontend/src/hooks/useVisionSession.ts` — 核心会话 Hook（~500 行）
|
||
- `frontend/src/lib/websocket.ts` — WebSocket 客户端单例
|
||
- `frontend/src/lib/auth.tsx` — JWT 自动刷新 + AuthProvider
|
||
- `frontend/src/lib/api.ts` — REST 客户端（401 拦截 + token 刷新）
|
||
- `frontend/src/lib/ttsPlayer.ts` — 流式 TTS 音频播放队列
|
||
- `frontend/vite.config.ts` — VAD 模型文件自动复制 + 代理配置
|
||
|
||
## 编码规范
|
||
|
||
- **Go**：标准规范，`context.Context` 超时控制，`sync.RWMutex` 并发保护，`json:"snake_case"` 标签，编译期接口检查 `var _ Interface = (*Impl)(nil)`
|
||
- **TypeScript**：严格模式，接口定义数据模型，WebSocket 消息用可辨识联合类型（`type` 字段区分）
|
||
- **CORS**：禁止后端代码/配置文件配置 CORS，统一由代理层处理（开发环境 Vite proxy，生产环境 Nginx）
|
||
- **提交信息**：Conventional Commits，中文描述（如 `feat: 添加 WebSocket 心跳`）
|
||
- **禁止自动 push**：除非用户明确要求
|
||
- **文档优先**：开发前先读 `docs/` 设计文档，代码与文档不一致时优先更新文档
|