docs: 编写项目 README.md

- 项目简介与三层架构图 - 技术栈、项目结构树 - 快速开始指南（前端/后端启动、配置说明） - WebSocket 协议概览与文档索引
2026-06-14 09:15:05 +08:00
parent ca09a1fb72
commit 2db0e3b0b6
1 changed files with 135 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,137 @@
 # CamTalk

+多模态实时 AI 视觉对话助手。用户通过摄像头和麦克风与 AI 交互，AI 理解视觉场景和语音输入后，以文字和语音形式给出自然回应。
+
+## 架构
+
+三层系统，前端做轻量预处理，后端做智能编排，云端 AI 服务按需调用：
+
+```
+浏览器客户端                    Go 网关 :8080                    云端 AI 服务
+┌─────────────────┐          ┌─────────────────┐          ┌─────────────────┐
+│ 媒体采集         │          │ WebSocket Handler│          │ STT（语音识别）   │
+│ VAD 语音检测     │  WebSocket│ Session Manager  │   HTTP   │ LLM（多模态推理） │
+│ 关键帧检测       │ ◄──────► │ AI Orchestrator  │ ◄──────► │ TTS（语音合成）   │
+│ UI 渲染          │          │ REST API         │          │                 │
+└─────────────────┘          └─────────────────┘          └─────────────────┘
+```
+
+**关键模式**：LLM 文本流和 TTS 音频流并行推送，用户先看到文字、紧接着听到语音，感知延迟 < 0.5 秒。
+
+## 技术栈
+
+| 层级 | 技术 |
+|------|------|
+| 前端 | React 18, TypeScript, Vite, @ricky0123/vad-web |
+| 后端 | Go, Gin, gorilla/websocket, Viper, Zap |
+| STT | Deepgram（默认） / MiMo ASR |
+| LLM | GPT-4o（默认，通过 OpenAI 兼容接口可切换） |
+| TTS | OpenAI TTS（默认） / MiMo TTS |
+
+## 项目结构
+
+```
+CamTalk/
+├── frontend/                   # 浏览器客户端
+│   └── src/
+│       ├── components/         # UI 组件
+│       │   ├── CameraManager/  # 摄像头流采集
+│       │   ├── MicManager/     # 麦克风音频采集
+│       │   ├── EdgeProcessor/  # VAD + 关键帧检测
+│       │   ├── WebSocketManager/ # WS 连接管理
+│       │   ├── ChatPanel/      # 消息展示
+│       │   ├── VideoPreview/   # 摄像头画面预览
+│       │   ├── ConfigPanel/    # 配置面板
+│       │   └── Toast/          # 通知提示
+│       ├── hooks/              # 自定义 Hooks
+│       │   ├── useVisionSession.ts  # 核心会话 Hook
+│       │   └── useObservationMode.ts # 观察模式
+│       ├── lib/                # 工具库
+│       │   ├── websocket.ts    # WebSocket 连接管理
+│       │   ├── audio.ts        # 音频编码
+│       │   ├── ttsPlayer.ts    # TTS 播放器
+│       │   └── sampling.ts     # 采样策略
+│       └── types/              # TypeScript 类型定义
+├── backend/                    # Go 网关
+│   ├── cmd/server/             # 入口
+│   └── internal/
+│       ├── ai/                 # AI 服务抽象层
+│       │   ├── llm/            # LLM 服务（OpenAI 兼容）
+│       │   ├── stt/            # STT 服务（Deepgram/MiMo）
+│       │   └── tts/            # TTS 服务（OpenAI/MiMo）
+│       ├── orchestrator/       # AI 编排器（STT→LLM→TTS 管道）
+│       ├── session/            # 会话管理（Memory/Redis）
+│       ├── ws/                 # WebSocket Handler
+│       ├── api/                # REST API
+│       ├── config/             # 配置管理
+│       ├── models/             # 数据模型
+│       ├── errors/             # 错误码
+│       └── logger/             # 日志
+├── docs/                       # 设计文档
+└── CLAUDE.md                   # Claude Code 指引
+```
+
+## 快速开始
+
+### 前置条件
+
+- Node.js >= 18
+- Go >= 1.24
+
+### 前端
+
+```bash
+cd frontend
+npm install
+npm run dev          # Vite 开发服务器 http://localhost:5173
+```
+
+### 后端
+
+```bash
+cd backend
+go mod download
+go run ./cmd/server  # 启动网关 :8080
+```
+
+### 配置
+
+后端配置文件位于 `backend/config.yaml`，支持环境变量覆盖（前缀 `CAMTALK_`）。
+
+```bash
+# 最小启动（需要至少一个 AI 服务的 API Key）
+cd backend
+CAMTALK_AI_LLM_API_KEY=sk-xxx \
+CAMTALK_AI_STT_API_KEY=xxx \
+go run ./cmd/server
+```
+
+配置优先级：环境变量 > `config.{env}.yaml` > `config.yaml` > `.env`
+
+## WebSocket 协议
+
+连接地址：`ws://localhost:8080/ws`
+
+所有消息为 JSON 文本帧，统一信封格式 `{type, request_id?, timestamp?}`。
+
+**客户端 → 服务端**：`query`、`config`、`interrupt`、`ping`
+**服务端 → 客户端**：`connected`、`stt_result`、`llm_chunk`、`llm_done`、`tts_audio`、`error`、`pong`
+
+完整协议见 [docs/03-接口文档.md](docs/03-接口文档.md)。
+
+## 文档
+
+| 文档 | 内容 |
+|------|------|
+| [01-项目概述](docs/01-项目概述.md) | 项目目标与核心挑战 |
+| [02-系统架构](docs/02-系统架构.md) | 三层架构、技术栈、部署方案 |
+| [03-接口文档](docs/03-接口文档.md) | WebSocket 协议、REST API、配置管理 |
+| [04-技术选型](docs/04-技术选型.md) | AI 服务栈、持久化层、前端边缘处理选型 |
+| [05-用户故事](docs/05-用户故事.md) | 用户场景与优先级 |
+| [06-语音交互](docs/06-语音交互.md) | VAD → STT → LLM → TTS 全链路 |
+| [07-视觉理解](docs/07-视觉理解.md) | 帧采样、关键帧检测、多模态输入 |
+| [08-成本控制](docs/08-成本控制.md) | 采样策略、端云协同、模型分级 |
+
+## License
+
+[MIT](LICENSE) © XEngineers