diff --git a/CLAUDE.md b/CLAUDE.md
index 060d6c5..9780660 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,294 +1,73 @@
 # CLAUDE.md
 
-本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指引。
+CamTalk — 多模态实时 AI 视觉对话助手（摄像头 + 麦克风 + 视觉 + 语音 AI）
 
-## 项目概述
-
-CamTalk 是一款多模态实时 AI 视觉对话助手。用户通过摄像头和麦克风与 AI 交互，AI 理解视觉场景和语音输入后，以文字和语音形式给出自然回应。
-
-> **文档优先原则：** 执行任何开发任务前，先读取 `docs/` 下的相关设计文档（架构、接口、技术选型等），以文档为最高依据。代码实现应与文档一致；若有偏差，优先更新文档（尤其是接口文档）。`docs/Eino/` 下有完整的 Eino 框架文档（~75 个 markdown 文件），可作为参考。
-
-**核心设计文档：**
-
-| 文档 | 内容 |
-|------|------|
-| `docs/01-架构设计.md` | 三层架构、技术栈、数据库设计、部署方案 |
-| `docs/02-接口文档.md` | WebSocket 协议、REST API、AI 服务层、编排器、配置管理 |
-| `docs/03-技术选型.md` | AI 服务栈、持久化层、前端边缘处理选型 |
-| `docs/04-用户故事.md` | 用户场景与优先级 |
-| `docs/05-语音交互.md` | VAD → STT → LLM → TTS 全链路 |
-| `docs/06-视觉理解.md` | 帧采样、关键帧检测、多模态输入 |
-| `docs/07-成本控制.md` | 采样策略、端云协同、模型分级 |
-| `docs/08-功能创意.md` | 功能创意与规划 |
-| `docs/09-技术名词解释.md` | 术语定义（VAD/STT/TTS/Token/JWT 等） |
-| `docs/10-Eino重构方案.md` | Eino Graph 迁移方案与决策记录 |
-| `docs/11-Eino框架技术文档.md` | Eino 框架使用指南 |
-| `docs/12-鉴权体系设计.md` | JWT 双 token 轮转详细设计 |
-| `docs/13-令牌桶限流设计.md` | 令牌桶限流详细设计（需同步实现） |
+> **文档优先原则：** 开发前先读 `docs/` 设计文档，以文档为准；若代码与文档不一致，优先更新文档（尤其接口文档）。详细设计见 `docs/01-13` 系列文档。**注意**：`docs/Eino/` 框架文档内容庞大（~75 个文件），仅在需要了解 Eino Graph/节点/Callback 等框架细节时才读取。
 
 ## 架构
 
-三层系统：
+三层系统：前端（React + Vite）→ Go 网关（Gin + WebSocket + Eino Graph AI 编排）→ AI 服务（DashScope LLM, MiMo STT/TTS）
 
-1. **浏览器客户端**（React 18 + TypeScript, Vite）—— 媒体采集、边缘预处理（VAD 通过 `@ricky0123/vad-web`、关键帧检测通过 Canvas 像素比较）、UI 渲染。核心 Hook：`useVisionSession()`
-2. **Go 网关**（Gin, gorilla/websocket, Viper, Zap）—— WebSocket 服务器、会话管理、AI 编排（基于 CloudWeGo Eino Graph）。每个 WebSocket 连接一个 goroutine。
-3. **云端 AI 服务** —— 通过 OpenAI 兼容接口可灵活切换。默认：DashScope qwen3-vl-plus（LLM）、MiMo ASR（STT）、MiMo TTS（TTS）。仅通过 Go 网关访问，浏览器不直连。
+**AI 编排流水线**（Eino Graph 7 节点 DAG）：`STT → History → ChatModel → Msg2Str → Splitter → TTS → Done`。LLM token 通过 Callback 实时推送，TTS 逐句并行合成。
 
-**关键模式**：AI 编排基于 Eino Graph 声明式 DAG（6 节点线性流水线：`START → STT → History → ChatModel → Msg2Str → Splitter → TTS → Done → END`），LLM token 通过 Callback 实时推送，TTS 逐句合成并行推送，最小化感知延迟。
+**会话存储**（TieredManager）：L1 Memory → L2 Redis → L3 PostgreSQL 三级存储，30 分钟 TTL，Redis 故障自动降级。
 
-### Eino Graph 节点详解
-
-| 节点 | 类型 | 文件 | 职责 |
-|------|------|------|------|
-| STT | `InvokableLambda` | `backend/internal/eino/nodes_stt.go` | 语音识别或文本直通（text-only 跳过 STT） |
-| History | `InvokableLambda` | `backend/internal/eino/nodes_history.go` | 构建 System Prompt + 对话历史 + 用户输入 + 图像 |
-| ChatModel | ChatModel 节点 | `backend/internal/eino/graph.go` | 调用 DashScope qwen3-vl-plus（OpenAI 兼容协议） |
-| Msg2Str | `TransformableLambda` | `backend/internal/eino/nodes_splitter.go` | 将 ChatModel 流式 Message 转为字符串流 |
-| Splitter | `TransformableLambda` | `backend/internal/eino/nodes_splitter.go` | 按句子分隔符（`。！？\n.!?`）拆分文本流 |
-| TTS | `TransformableLambda` | `backend/internal/eino/nodes_tts.go` | 逐句合成语音并推送 `tts_audio` |
-| Done | `InvokableLambda` | `backend/internal/eino/nodes_done.go` | 发送 `llm_done`、收集最终输出 |
-
-**跨节点状态**：`PipelineState`（`backend/internal/eino/state.go`），通过 `context.WithValue` 在节点间传递 FullResponse、TranscribedText、TokenUsage、SessionID、RequestID。
-
-**Callback**：`BuildCallbackHandler`（`backend/internal/eino/callback.go`）挂载到 ChatModel 的 `OnEndWithStreamOutput`，每收到一个 LLM token 立即通过 `sender.SendLLMChunk()` 推送到客户端。
-
-**适配器**：`EinoOrchestrator`（`backend/internal/eino/adapter.go`）包装 Graph，实现 `orchestrator.Orchestrator` 接口，负责解码 Base64 图像/音频、构建输入、注入上下文、运行流式推理、持久化消息。
-
-### 会话存储（TieredManager）
-
-三级存储：**L1 Memory → L2 Redis → L3 PostgreSQL**（`backend/internal/session/tiered.go`）
-
-- **读路径**：L1 命中直接返回；未命中尝试 L2 Redis → 回填 L1；L3 通过 L1 的 `FindByID` 降级读取
-- **写路径**：L1 同步写入 → L2 同步写（失败 soft-warn）→ L3 异步 goroutine 写（使用 `context.Background()` 防止请求取消丢失）
-- **降级**：后台协程每 30 秒 ping Redis，Redis 不可用时自动跳过 L2 操作；恢复后自动重新启用
-- **TTL**：Session 默认 30 分钟，MaxHistory 20 条；L1 后台协程每分钟清理过期 session
-
-Repository 接口模式：`UserRepository`、`MessageRepository`、`SessionRepository`，均有 PostgreSQL 和内存双实现。
-
-### 鉴权
-
-JWT 双 token 轮转认证（HMAC-SHA256）：
-- Access Token：默认 120 分钟 TTL，Bearer header 传递
-- Refresh Token：默认 7 天 TTL，带 jti（UUID），Hash 存储在 Redis/PostgreSQL
-- 轮转：Refresh 时旧 token hash 删除，新 pair 生成；若 JWT 有效但 DB hash 缺失 → 判定为重放攻击 → 吊销该用户所有 refresh token
-- `CachedUserRepository`（`backend/internal/store/cached_user.go`）：装饰器模式，Redis 缓存 refresh token hash，Read-Through / Write-Through，Redis 故障软降级
+**鉴权**：JWT 双 token 轮转（Access 120min + Refresh 7d），重放攻击检测（DB hash 校验），Redis 缓存装饰器。
 
 ## 技术栈
 
-| 层级 | 技术 |
-|------|------|
-| 前端 | React 18, TypeScript, Vite, @ricky0123/vad-web, onnxruntime-web |
-| 后端 | Go 1.25+ (go.mod 最低要求; Dockerfile 构建用 golang:1.26-alpine), Gin, gorilla/websocket, Viper, Zap |
-| AI 编排 | CloudWeGo Eino Graph（声明式 DAG 编排） |
-| LLM | DashScope qwen3-vl-plus（默认，通过 eino-ext OpenAI ChatModel 接入） |
-| STT | MiMo ASR（默认） / Deepgram |
-| TTS | MiMo TTS（默认） / OpenAI TTS |
-| 存储 | PostgreSQL 15 + Redis 7（通过 TieredManager 三级存储） |
+前端：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
-# 前端
-cd frontend && npm install
-npm run dev          # Vite 开发服务器（含 /ws、/api 代理到 localhost:8080）
-npm run build        # 生产构建（tsc -b && vite build）
-npm run lint         # ESLint 检查（flat config, TypeScript strict）
-
-# 后端
-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 ./...                 # 静态分析
-
-# Docker 部署（生产环境）
-./deploy.sh build            # 构建所有镜像
-./deploy.sh up               # 启动 4 个服务
-./deploy.sh restart          # down + up
-./deploy.sh logs [service]   # 查看日志
-./deploy.sh status           # 查看服务状态
+# 前端：npm run dev（Vite，代理 /ws 和 /api 到 :8080）
+# 后端：go run ./cmd/server（监听 :8080）
+# 生产：./deploy.sh up（4 容器：frontend/backend/postgres/redis）
 ```
 
-> **注意**：前端目前没有测试基础设施（无 vitest 配置、无测试文件）。后端使用 `testing` + `testify`（assert/require/mock）测试，编译期接口检查 `var _ Interface = (*Impl)(nil)`。
+核心环境变量（`.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）
 
-项目通过 `APP_ENV` 环境变量控制配置文件加载：
+## 协议与 API
 
-- **本地开发**（默认）：`APP_ENV=dev` → 加载 `config/config.dev.yaml`
-  - Debug 日志、关闭限流、允许所有 CORS
-  - 使用 `backend/.env` 中的远程 Redis/PostgreSQL 地址
+**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`），订阅模式，自动重连
 
-- **生产部署**：`APP_ENV=prod` → 加载 `config/config.prod.yaml`
-  - Info/JSON 日志、启用限流、严格 CORS 白名单
-  - Docker Compose 自动设置，使用容器内网地址
+**REST API**：`/api/auth/*`（注册/登录/刷新/登出），`/api/conversations/*`（CRUD + 消息分页），`/api/health`
 
-**配置优先级**：环境变量 > config.{env}.yaml > config.yaml > 默认值
+**错误码**：`INVALID_MESSAGE`, `SESSION_NOT_FOUND`, `RATE_LIMITED`, `IMAGE_TOO_LARGE`, `LLM_TIMEOUT`, `STT/TTS/LLM_ERROR`, `INVALID_TOKEN`, 等
 
-**手动切换环境**（测试用）：
-```bash
-cd backend
-APP_ENV=prod go run ./cmd/server  # 本地测试生产配置
-APP_ENV=dev go run ./cmd/server   # 显式指定开发配置
-```
+## 关键文件路径
 
-## 配置系统
+**后端核心**：
+- `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 迁移文件
 
-配置文件：`backend/config/config.yaml`（基础配置），可被 `config/config.{env}.yaml` 覆盖。
-
-**优先级（从低到高）**：默认值 → `config.yaml` → `config.{env}.yaml`（由 `APP_ENV` 环境变量决定加载哪个 env 特定文件）→ `.env` 文件 → 环境变量
-
-**主要 `CAMTALK_` 环境变量**（模板见 `backend/.env.example`）：
-
-| 变量 | 用途 |
-|------|------|
-| `APP_ENV` | 运行环境（dev/prod），决定加载 `config.{env}.yaml` |
-| `CAMTALK_AI_STT_API_KEY` | STT API Key |
-| `CAMTALK_AI_LLM_API_KEY` | LLM API Key |
-| `CAMTALK_AI_TTS_API_KEY` | TTS API Key |
-| `CAMTALK_AUTH_JWT_SECRET` | JWT 签名密钥 |
-| `CAMTALK_STORAGE_DSN` | PostgreSQL 连接串 |
-| `CAMTALK_STORAGE_REDIS_ENABLED` | 启用 Redis（true/false） |
-| `CAMTALK_STORAGE_PERSISTENCE_ENABLED` | 启用 PostgreSQL（true/false） |
-| `CAMTALK_REDIS_ADDR` | Redis 地址 |
-| `CAMTALK_REDIS_PASSWORD` | Redis 密码 |
-
-**最小启动**（至少需要一个 AI 服务的 API Key）：
-```bash
-CAMTALK_AI_LLM_API_KEY=sk-xxx CAMTALK_AI_STT_API_KEY=xxx go run ./cmd/server
-```
-
-## Docker 部署
-
-`docker-compose.yml` 定义 4 个服务（`camtalk-net` 桥接网络）：
-
-| 服务 | 镜像/构建 | 端口 | 说明 |
-|------|----------|------|------|
-| `frontend` | 构建 `./frontend/Dockerfile`（node:22-alpine → nginx:stable-alpine） | 9000:80 | React SPA，反向代理 /api 和 /ws 到 backend |
-| `backend` | 构建 `./backend/Dockerfile`（golang:1.26-alpine → alpine:3.20） | 内部 8080 | Go 网关，静态链接二进制 `-ldflags="-s -w"` |
-| `postgres` | `postgres:15-alpine` | 内部 5432 | 数据库 `camtalk`，挂载 `./backend/migrations/` 到 initdb |
-| `redis` | `redis:7-alpine` | 内部 6379 | 会话缓存，AOF 持久化 |
-
-后端容器依赖 postgres + redis 健康检查通过后启动。所有服务 `restart: unless-stopped`。密钥通过 `--env-file /opt/camtalk/.env` 注入。
-
-**前端 nginx 特殊配置**：设置 `Cross-Origin-Opener-Policy` 和 `Cross-Origin-Embedder-Policy` 头（`SharedArrayBuffer` 需要，ONNX WASM 推理依赖）。
-
-## CI/CD
-
-使用 **Gitea Actions**（`.gitea/workflows/deploy.yml`），自托管 runner（标签 `aliyun`）。
-
-触发条件：push 到 `main` 或 `v2` 分支。流程：rsync 代码到 `/root/camtalk`，执行 `deploy.sh build` → `deploy.sh restart`。
-
-## 数据库迁移
-
-嵌入式 SQL 迁移系统（`backend/internal/store/migrate.go`），SQL 文件在 `backend/migrations/`：
-
-| 迁移 | 内容 |
-|------|------|
-| `001_users` | `users` 表（UUID PK）+ `refresh_tokens` 表（FK → users） |
-| `002_messages` | `messages` 表（BIGSERIAL PK, session_id UUID, 游标分页索引） |
-| `003_sessions` | `sessions` 表（UUID PK, user_id UUID, config JSONB, 时间排序索引） |
-
-迁移文件通过 Go 1.16+ `//go:embed` 嵌入二进制，启动时自动执行。通过 `schema_migrations` 表追踪版本，已应用的迁移跳过。同时挂载到 PostgreSQL 容器的 `/docker-entrypoint-initdb.d` 作为备用初始化路径。
-
-## WebSocket 协议
-
-端点：`ws://localhost:8080/ws?token=<access_token>&conversation_id=<uuid>`
-
-所有消息为 JSON 文本帧，统一信封格式 `{type, request_id?, timestamp?}`。完整契约见 `docs/02-接口文档.md`。
-
-**认证**：WebSocket 连接通过 query param `token`（Access Token）认证，不走 HTTP `Authorization` header。服务端在升级时校验 JWT，失败返回 401。
-
-**客户端 → 服务端**：`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。
-
-**前端 WebSocket 实现**：`CamTalkWebSocket` 单例类（`frontend/src/lib/websocket.ts`），基于订阅模式（`onMessage`/`onStatusChange` 返回取消订阅函数），自动处理心跳和重连。
-
-## REST API（辅助）
-
-- `GET /api/health` — 健康检查（版本、运行时间、活跃会话数）
-- `POST /api/auth/register` — 注册
-- `POST /api/auth/login` — 登录
-- `POST /api/auth/refresh` — 刷新 Token
-- `POST /api/auth/logout` — 登出
-- `GET /api/conversations` — 对话列表
-- `POST /api/conversations` — 创建对话
-- `GET/PATCH/DELETE /api/conversations/:id` — 对话详情/改标题/删除
-- `GET /api/conversations/:id/messages` — 获取对话消息（游标分页）
-- `POST/DELETE /api/sessions` — 会话管理
-
-## 错误码
-
-`INVALID_MESSAGE`、`SESSION_NOT_FOUND`、`RATE_LIMITED`、`IMAGE_TOO_LARGE`、`AUDIO_TOO_SHORT`、`LLM_TIMEOUT`、`LLM_ERROR`、`STT_ERROR`、`TTS_ERROR`、`INTERNAL_ERROR`、`USERNAME_TAKEN`、`INVALID_CREDENTIALS`、`INVALID_TOKEN`、`INVALID_INPUT`
-
-## 前端组件结构
-
-| 组件 | 职责 |
-|------|------|
-| `LandingPage` | 未登录时的着陆页，内嵌 LoginModal 登录/注册弹窗 |
-| `AuthPage` | 登录/注册表单（备用） |
-| `CameraManager` | 摄像头流采集（`useCamera` hook：640x480, facingMode: environment） |
-| `MicManager` | 麦克风音频采集（`useMicrophone` hook：16kHz 单声道） |
-| `EdgeProcessor` | VAD（`useVAD` hook：@ricky0123/vad-web）+ 关键帧检测（Canvas 像素比较，160x120 降采样） |
-| `WebSocketManager` | WebSocket 连接生命周期管理（桥接 `wsClient` 单例到 React 状态） |
-| `ChatPanel` | 消息展示、流式回复、文本输入、场景选择（5 种场景卡片） |
-| `VideoPreview` | 摄像头画面预览（forwardRef `<video>`） |
-| `SessionSidebar` | 左侧抽屉式对话列表（搜索、重命名、删除、时间分组） |
-| `ConfigPanel` | 右侧抽屉式配置面板（主题、TTS、语言、场景、登出） |
-| `Toast` | 轻量通知提示（3 秒自动消失） |
-
-核心 Hook：
-- `useVisionSession()` — 封装一次完整的视觉对话会话（~500 行），管理摄像头、麦克风、VAD、WebSocket、消息状态、TTS 播放、两种模式（dialogue / observation）
-- `useSessionList()` — 对话列表 CRUD（通过 REST API），乐观更新
-- `useObservationMode()` — 定期帧差异检测（5 秒间隔），相似度 < 0.85 时触发回调
-
-关键 lib 文件：
-- `frontend/src/lib/websocket.ts` — `CamTalkWebSocket` 单例，心跳 + 指数退避重连
-- `frontend/src/lib/auth.tsx` — `AuthProvider` 上下文，JWT 解码 + 自动刷新调度（exp 前 60 秒）
-- `frontend/src/lib/api.ts` — REST 客户端，自动 Bearer header，并发安全 401 拦截 + token 刷新 + 重试
-- `frontend/src/lib/ttsPlayer.ts` — `TTSPlayer` 类，流式 TTS 音频逐句排队播放
-- `frontend/src/lib/scenarios.ts` — 5 种对话场景定义（free_chat, interviewer, english_teacher, debate, interpreter）
-- `frontend/src/lib/i18n/` — 国际化，3 种语言（zh-CN 默认/fallback, en-US, ja-JP），扁平常量 map
-- `frontend/src/lib/storage.ts` — localStorage 封装（config, tokens, user info）
-- `frontend/src/lib/audio.ts` — 音频编码工具（浏览器采集 → Base64 PCM）
-- `frontend/src/lib/sampling.ts` — 混合采样策略（定时低频 + 事件高频，实现见 `docs/07-成本控制.md`）
-- `frontend/src/lib/errors.ts` — 错误码到用户友好文案的映射
-- `frontend/src/lib/toast.ts` — Toast 全局状态管理（error/warning/info，3 秒自动消失）
-- `frontend/src/types/index.ts` — 所有 TypeScript 类型定义（WebSocket 消息可辨识联合类型、场景、配置等）
-
-## Vite 构建细节
-
-`frontend/vite.config.ts` 包含：
-- 自定义 `serve-vad-assets` 插件，在开发/构建时自动从 `node_modules` 复制 VAD 模型文件（`silero_vad_legacy.onnx`、`silero_vad_v5.onnx`、`vad.worklet.bundle.min.js`）和 ONNX Runtime WASM 文件到 `public/`。开发服务器中间件确保 `.wasm` 和 `.mjs` 文件返回正确的 MIME type。
-- 开发代理：`/ws` → `ws://localhost:8080`、`/api` → `http://localhost:8080`，前端开发时无需配置额外环境变量。
-
-## 后端模块结构
-
-| 模块 | 职责 |
-|------|------|
-| WebSocket Handler | 连接管理、JWT 认证（query param token）、消息分发（query/config/interrupt/ping） |
-| Session Manager | 会话状态、对话历史（三级存储：Memory/Redis/PostgreSQL，30 分钟 TTL） |
-| Eino 编排层 | 基于 Eino Graph 的声明式 AI 编排（6 节点线性 DAG + Callback） |
-| AI Orchestrator | `EinoOrchestrator` 适配器，包装 Graph 实现 `Orchestrator` 接口 |
-| AI Service Layer | AI 服务抽象层（STT/TTS 多 provider 接口，LLM 通过 eino-ext ChatModel） |
-| Auth | JWT 双 token 轮转认证，bcrypt 密码哈希，Gin 中间件 |
-| Store | 持久化存储层（UserRepository/MessageRepository/SessionRepository，PG + 内存 + Redis 缓存装饰器） |
-| REST API | 健康检查、认证、对话管理（Gin 路由组） |
-| Models | 数据模型 + WebSocket 消息类型定义 |
-| Migrations | 嵌入式 SQL 版本化迁移 |
-| Rate Limiter | 按用户的令牌桶速率限制（`docs/13-令牌桶限流设计.md`，`backend/internal/ratelimit/`，实现中） |
-
-测试模式：后端使用 `testing` + `testify`（`assert`、`require`、`mock`）。mock 模式包括：`mockSender`（实现 `orchestrator.Sender` 接口）、`httptest.Server`（模拟 AI 服务 HTTP API）、`MockOrchestrator`（模拟完整编排管道）。WebSocket 集成测试使用 `httptest.Server` + `gorilla/websocket.Dialer`。
+**前端核心**：
+- `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**：遵循标准 Go 规范。所有 AI 调用使用 `context.Context` 做取消/超时。并发 map 访问使用 `sync.RWMutex`。结构体标签用 `json:"snake_case"`。编译期接口检查 `var _ Interface = (*Impl)(nil)`。
-- **TypeScript**：严格模式（`strict: true`）。所有数据模型用接口定义。WebSocket 消息类型用可辨识联合类型（`type` 字段）。`verbatimModuleSyntax: true`（强制 `import type`）。未使用变量以 `_` 前缀忽略。
-- **CORS 处理**：禁止在后端代码和配置文件（`config/*.yaml`）中进行任何 CORS 配置。跨域由代理层统一处理：开发环境通过 `frontend/vite.config.ts` 中的 proxy 配置（`/ws`、`/api` 代理到 `localhost:8080`），生产环境通过 Nginx 反向代理（`frontend/nginx.conf`）。
-- **提交信息**：Conventional Commits 格式，描述用中文。示例：`feat: 添加 WebSocket 连接管理`、`fix: 修复心跳超时判断`、`docs: 更新接口文档`
-- **禁止自动 push**：除非用户明确要求。
-- **文档优先**：实现功能前先读取 `docs/` 下的相关设计文档。实现与文档不一致时，优先更新 `docs/` 下的接口文档。
+- **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/` 设计文档，代码与文档不一致时优先更新文档
diff --git a/backend/internal/eino/graph.go b/backend/internal/eino/graph.go
index 8bf3a13..378e76b 100644
--- a/backend/internal/eino/graph.go
+++ b/backend/internal/eino/graph.go
@@ -97,7 +97,7 @@ func NewPipelineGraph(
 		return nil, err
 	}
 
-	log.Infow("Eino Graph 编译成功", "nodes", 6)
+	log.Infow("Eino Graph 编译成功", "nodes", 7)
 	return &PipelineGraph{Runnable: runnable}, nil
 }
 
diff --git a/docs/01-架构设计.md b/docs/01-架构设计.md
index bd45dd1..d23b8f4 100644
--- a/docs/01-架构设计.md
+++ b/docs/01-架构设计.md
@@ -199,36 +199,35 @@ graph LR
 | 模块 | 职责 |
 |------|------|
 | WebSocket Handler | 管理客户端连接生命周期，JWT 认证，conversation_id 恢复，单播消息推送 |
-| Session Manager | 维护用户会话状态、对话历史。三级存储（Memory → Redis → PostgreSQL），30 分钟 TTL，Write-Through 到 PG |
-| Eino 编排层 | 基于 CloudWeGo Eino Graph 的声明式 AI 编排。7 节点 DAG（STT→History→ChatModel→Msg2Str→Splitter→TTS→Done），Stream 模式调用，Callback 实现 LLM token 实时推送 |
-| AI Orchestrator | `EinoOrchestrator` 适配器，包装 Eino Graph 实现 `Orchestrator` 接口。context 取消 + 超时控制 |
+| Session Manager | 维护用户会话状态、对话历史，三级存储架构，30 分钟 TTL |
+| Eino 编排层 | 基于 CloudWeGo Eino Graph 的声明式 AI 编排，7 节点 DAG 流水线，Stream 模式调用 |
+| AI Orchestrator | EinoOrchestrator 适配器，包装 Eino Graph 实现 Orchestrator 接口 |
 | AI Service Layer | AI 服务抽象层，多 provider 支持（Deepgram/MiMo/OpenAI 等） |
-| Auth | 用户认证与授权。JWT (HS256) 双 token 轮转，bcrypt 密码哈希，Gin 中间件 |
-| Store | 持久化存储层。UserRepository / MessageRepository / SessionRepository，内存 + PostgreSQL 双实现 |
+| Auth | 用户认证与授权，JWT 双 token 轮转，bcrypt 密码哈希 |
+| Store | 持久化存储层，Repository 接口与实现（内存 + PostgreSQL） |
 | REST API | 健康检查、认证、对话管理端点 |
 | Logger | Zap 结构化日志 |
 | Models | 数据模型定义 |
-| Migrations | 数据库版本化迁移，嵌入式 SQL 文件自动执行 |
+| Migrations | 数据库版本化迁移 |
 | Model Router | 根据请求类型选择 AI 模型（待实现） |
-| Rate Limiter | 令牌桶限流。详细设计见 [令牌桶限流设计](./13-令牌桶限流设计.md) |
+| Rate Limiter | 令牌桶限流，详见 [11-令牌桶限流.md](./11-令牌桶限流.md) |
 
 ## 前端组件
 
 | 组件 | 职责 |
 |------|------|
-| LandingPage | 未登录时的着陆页（营销展示），内嵌 LoginModal 登录/注册弹窗 |
-| AuthPage | 登录/注册表单（备用，已被 LandingPage + LoginModal 替代） |
+| LandingPage | 未登录时的着陆页，内嵌 LoginModal 登录/注册弹窗 |
 | CameraManager | 摄像头流采集 |
 | MicManager | 麦克风音频采集 |
-| EdgeProcessor | VAD + 关键帧检测（Canvas 像素比较） |
-| WebSocketManager | WS 连接生命周期管理 |
+| EdgeProcessor | VAD + 关键帧检测 |
+| WebSocketManager | WebSocket 连接生命周期管理 |
 | ChatPanel | 消息展示、流式回复、文本输入、场景选择 |
 | VideoPreview | 摄像头画面预览 |
-| SessionSidebar | 左侧抽屉式对话列表（搜索、重命名、删除、时间分组） |
-| ConfigPanel | 右侧抽屉式配置面板（主题、TTS 开关、detail level、语言、场景、登出） |
-| Toast | 轻量通知提示（3 秒自动消失） |
+| SessionSidebar | 左侧对话列表（搜索、重命名、删除、时间分组） |
+| ConfigPanel | 右侧配置面板（主题、TTS 开关、detail level、语言、场景、登出） |
+| Toast | 轻量通知提示 |
 
-核心 Hook：`useVisionSession()` 封装一次完整的视觉对话会话（摄像头、VAD、WebSocket、消息状态、认证、场景模式）。`useSessionList()` 通过 REST API 管理对话列表 CRUD（列表、创建、删除、重命名、加载消息）。
+核心 Hook：`useVisionSession()` 封装完整的视觉对话会话（摄像头、VAD、WebSocket、消息状态、认证、场景模式）。`useSessionList()` 通过 REST API 管理对话列表 CRUD。
 
 ### 前端会话状态模型（三态）
 
@@ -310,188 +309,56 @@ erDiagram
     }
 ```
 
-### 表结构
-
-```sql
--- 用户表
-CREATE TABLE users (
-    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    username      VARCHAR(64) NOT NULL UNIQUE,
-    password_hash VARCHAR(256) NOT NULL,
-    created_at    TIMESTAMPTZ DEFAULT now(),
-    updated_at    TIMESTAMPTZ DEFAULT now()
-);
-
--- 会话表
-CREATE TABLE sessions (
-    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    user_id    UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    title      VARCHAR(128) DEFAULT '新对话',
-    config     JSONB DEFAULT '{}',
-    created_at TIMESTAMPTZ DEFAULT now(),
-    updated_at TIMESTAMPTZ DEFAULT now()
-);
-
--- 消息表
-CREATE TABLE messages (
-    id          BIGSERIAL PRIMARY KEY,
-    session_id  UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
-    role        VARCHAR(16) NOT NULL,
-    content     TEXT NOT NULL,
-    tokens_used INTEGER DEFAULT 0,
-    created_at  TIMESTAMPTZ DEFAULT now()
-);
-
--- 刷新令牌表
-CREATE TABLE refresh_tokens (
-    id          BIGSERIAL PRIMARY KEY,
-    user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    token_hash  VARCHAR(256) NOT NULL UNIQUE,
-    expires_at  TIMESTAMPTZ NOT NULL,
-    created_at  TIMESTAMPTZ DEFAULT now()
-);
-```
+系统采用关系型数据库存储持久化数据，包括用户账户、对话会话、消息记录和刷新令牌。数据库表定义详见 `backend/migrations/` 目录下的 SQL 迁移文件。
 
 ### 存储策略
 
-| 场景 | 存储方案 | 说明 |
-|------|---------|------|
-| 默认 | Memory（进程内） | 零依赖，快速启动。MemoryManager 支持 Write-Through 到 PG |
-| 持久化 | Memory + PostgreSQL | 通过 `storage.persistence.enabled: true` 启用，MemoryManager 注入 PG Repository |
-| 多实例 | Redis（独立） | 通过配置切换到 RedisManager，适合多实例部署 |
-| 三级存储 | TieredManager | L1 Memory → L2 Redis → L3 PostgreSQL，自动降级 |
+系统采用**三级存储架构**（TieredManager）实现会话状态管理，平衡性能与可靠性：
 
-**三级存储架构**（`TieredManager`）：
+- **L1 Memory**：进程内缓存，提供微秒级读写性能
+- **L2 Redis**：分布式缓存层，支持多实例部署，提供毫秒级访问
+- **L3 PostgreSQL**：持久化存储层，确保数据可靠性
 
-```
-TieredManager
-├── L1: Memory（进程内缓存，微秒级读写）
-├── L2: Redis（分布式缓存，毫秒级读写）
-└── L3: PostgreSQL（持久化存储，冷数据）
-```
-
-- **读取路径**：L1 → L2 → L3，逐级回源，命中后向上回填
-- **写入路径**：L1 → L2（同步） → L3（异步）
-- **健康检查**：后台 goroutine 每 30 秒 ping Redis，故障时自动降级为 L1+L3 模式
-- **冷热分离**：L1/L2 存"热数据"（当前对话上下文），L3 存"冷数据"（历史记录）
+会话数据按 TTL（默认 30 分钟）在三级存储间流转，支持 Redis 故障时自动降级到 Memory + PostgreSQL 模式。配置灵活，可根据部署规模选择单级（Memory）、双级（Memory + PostgreSQL）或完整三级存储方案。
 
 ## 认证设计
 
-采用 **JWT 双 token 轮转认证机制**，结合 bcrypt 密码哈希和 Refresh Token Rotation 安全策略。详细设计见 [鉴权体系设计](./12-鉴权体系设计.md)。
+系统采用 **JWT 双 token 轮转认证机制**，结合 bcrypt 密码哈希和 Refresh Token Rotation 安全策略。
 
-### 核心组件
-
-| 组件 | 职责 |
-|------|------|
-| TokenManager | JWT 生成与验证（HS256 算法） |
-| AuthService | 认证业务逻辑（注册/登录/刷新/登出） |
-| AuthMiddleware | Gin 中间件，校验 access_token 并注入用户信息 |
-| PasswordUtil | bcrypt 密码哈希（cost=10） |
-
-### 认证流程
-
-```mermaid
-sequenceDiagram
-    participant C as 客户端
-    participant G as Go 网关
-    participant DB as PostgreSQL
-
-    Note over C,DB: 注册流程
-    C->>G: POST /api/auth/register {username, password}
-    G->>G: bcrypt hash 密码
-    G->>DB: INSERT users
-    G->>G: 生成 access_token + refresh_token
-    G->>DB: 存 SHA256(refresh_token)
-    G-->>C: {user, access_token, refresh_token}
-
-    Note over C,DB: 登录流程
-    C->>G: POST /api/auth/login {username, password}
-    G->>DB: 查 users by username
-    G->>G: bcrypt.CompareHashAndPassword
-    G->>G: 生成 token pair
-    G->>DB: 存 SHA256(refresh_token)
-    G-->>C: {user, access_token, refresh_token}
-
-    Note over C,DB: Token 刷新（轮转）
-    C->>G: POST /api/auth/refresh {refresh_token}
-    G->>G: 校验签名和过期
-    G->>DB: 验证 hash 存在
-    G->>DB: 撤销旧 refresh_token
-    G->>G: 生成新 token pair
-    G->>DB: 存新 refresh_token hash
-    G-->>C: {access_token, refresh_token}
-```
-
-### Token 策略
-
-- **access_token**：15 分钟有效，用于 API 认证和 WebSocket 连接
-- **refresh_token**：7 天有效，用于刷新 access_token
-- **Refresh Token Rotation**：每次 refresh 都生成新的 token pair，旧 refresh_token 立即失效
-- **复用检测**：检测到已删除的 refresh_token 被复用时，吊销该用户的所有 refresh_token
-
-### 安全机制
-
-1. **密码安全**：bcrypt 算法（cost=10），自动生成盐值，防彩虹表攻击
-2. **Token 安全**：
-   - access_token 短有效期（15 分钟），降低泄露风险
-   - refresh_token 使用 SHA256 哈希存储，不存储原始 token
-   - Refresh Token Rotation 防重放攻击
-   - 复用检测 + 自动吊销机制
-3. **传输安全**：HTTPS 强制，CORS 限制，HttpOnly Cookie 存储 refresh_token
-4. **防攻击策略**：
-   - 防暴力破解：可选速率限制
-   - 防枚举攻击：统一错误信息
-   - 防 Token 泄露：复用检测 + 自动吊销
-
-### WebSocket 认证
-
-连接地址：`ws://host/ws?token=<access_token>&conversation_id=<uuid>`
-
-- HTTP Upgrade 前校验 token
-- 校验失败返回 401 Unauthorized
-- 校验成功后，user_id 和 username 注入到连接上下文
-
-### 配置
-
-```yaml
-auth:
-  jwt_secret: ""           # JWT 签名密钥（必须通过 CAMTALK_AUTH_JWT_SECRET 环境变量设置）
-  access_ttl: 15           # access_token 有效期（分钟）
-  refresh_ttl: 10080       # refresh_token 有效期（分钟，7天）
-```
-
-> **安全要求**：`JWT_SECRET` **必须**通过环境变量设置，不能写入配置文件。生产环境使用 `openssl rand -hex 32` 生成随机密钥。
+核心机制包括：双 token 轮转（access_token 15 分钟 + refresh_token 7 天）、密码安全（bcrypt cost=10）、token 安全（SHA256 哈希存储、复用检测）、WebSocket 连接认证（基于 access_token 的 HTTP Upgrade 校验）等。认证流程、安全机制、配置要求等详细设计见 [10-鉴权体系.md](./10-鉴权体系.md)。
 
 ## 部署架构
 
+系统采用分层部署架构，支持单实例和多实例水平扩展：
+
 ```mermaid
 graph TB
     User["用户浏览器"] --> Nginx
-
+    
     subgraph Nginx["Nginx 反向代理"]
         Static["/ → 前端静态资源"]
         API["/api/* → Go Gateway"]
         WS_Proxy["/ws → Go Gateway"]
     end
-
+    
     subgraph Gateway_Pool["Go Gateway 实例"]
         G1["Gateway-1"]
         G2["Gateway-2"]
         GN["Gateway-N"]
     end
-
+    
     Nginx --> G1
     Nginx --> G2
     Nginx --> GN
-
+    
     G1 --> Redis
     G2 --> Redis
     GN --> Redis
-
+    
     G1 --> PG_DB["PostgreSQL"]
     G2 --> PG_DB
     GN --> PG_DB
-
+    
     G1 --> AI_Services["AI Services（外部 API）"]
     G2 --> AI_Services
     GN --> AI_Services
diff --git a/docs/02-接口文档.md b/docs/02-接口文档.md
index f355545..ce591a9 100644
--- a/docs/02-接口文档.md
+++ b/docs/02-接口文档.md
@@ -2,7 +2,7 @@
 
 ## 概述
 
-前后端通信接口定义。以 WebSocket 承载实时对话，REST 端点支撑基础运维。持久化通过 PostgreSQL 实现，MemoryManager 支持 Write-Through 模式。
+前后端通信接口契约。WebSocket 承载实时对话，REST API 支撑基础运维。
 
 **设计原则**：
 - WebSocket 为主：所有对话数据走 WebSocket
@@ -50,8 +50,6 @@ interface WsMessage {
 
 #### `query` — 发起一次视觉对话
 
-用户说完话后，客户端同时发送当前图像帧和语音片段。也支持文本输入模式（手动输入文字时跳过语音识别）：
-
 ```typescript
 interface QueryMessage {
   type: "query";
@@ -63,10 +61,6 @@ interface QueryMessage {
 }
 ```
 
-> 为什么图像和音频放在同一条消息里？因为 VAD 检测到用户说完话时，需要同时捕获"此刻的画面"和"说的话"，拆成两条消息会增加时序同步的复杂度。
->
-> **文本输入模式**：当用户关闭麦克风后，可通过对话框手动输入文字。此时 `text` 字段携带用户输入，`audio` 为空字符串，服务端跳过 STT 直接使用 `text` 进行 LLM 推理。
-
 #### `config` — 更新会话配置
 
 ```typescript
@@ -105,124 +99,82 @@ interface PingMessage {
 ```typescript
 interface ConnectedMessage {
   type: "connected";
-  session_id: string;         // 服务端生成的会话 ID
-  conversation_id: string;    // 同 session_id，便于前端统一使用
-  server_version: string;     // 服务端版本号，如 "0.1.0"
+  session_id: string;
+  conversation_id: string;
+  config: {
+    tts_enabled: boolean;
+    detail_level: "low" | "high";
+    language: string;
+    scenario: string;
+  };
 }
 ```
 
 #### `stt_result` — 语音识别结果
 
 ```typescript
-interface STTResultMessage {
+interface SttResultMessage {
   type: "stt_result";
   request_id: string;
-  text: string;        // 识别出的用户语音文本
-  is_final: boolean;   // 是否为最终结果
+  text: string;          // 识别出的文本
+  is_final: boolean;     // 当前实现始终为 true
 }
 ```
 
-#### `llm_chunk` — LLM 流式输出片段
+#### `llm_chunk` — LLM 流式响应片段
 
 ```typescript
-interface LLMChunkMessage {
+interface LlmChunkMessage {
   type: "llm_chunk";
   request_id: string;
-  delta: string;       // 本次增量文本
-  role: "assistant";
+  content: string;       // 当前 token 片段
 }
 ```
 
-#### `llm_done` — LLM 输出完成
+#### `llm_done` — LLM 响应完成
 
 ```typescript
-interface LLMDoneMessage {
+interface LlmDoneMessage {
   type: "llm_done";
   request_id: string;
-  full_text: string;     // 完整回复文本
-  tokens_used: {
-    prompt: number;
-    completion: number;
-    total: number;
-  };
-  model: string;         // 实际使用的模型名
-  latency_ms: number;    // 端到端延迟（毫秒）
+  full_text: string;     // 完整响应文本
 }
 ```
 
-#### `tts_audio` — TTS 音频流片段
+#### `tts_audio` — TTS 音频片段
+
+音频流式推送，每个消息携带一个句子的音频数据。
 
 ```typescript
-interface TTSAudioMessage {
+interface TtsAudioMessage {
   type: "tts_audio";
   request_id: string;
-  audio: string;         // Base64 编码的音频片段
-  mime_type: string;     // "audio/mp3"
-  is_last: boolean;      // 当前句子的音频是否完整（每句结束时为 true）
-  final: boolean;        // 整轮 TTS 是否结束（所有句子合成完毕后为 true）
+  audio: string;         // Base64 编码的音频数据
+  format: string;        // 音频格式
+  sample_rate: number;   // 采样率（Hz）
+  sequence: number;      // 句子序号，从 0 开始递增
+  is_final: boolean;     // 是否为最后一个句子
 }
 ```
 
-**字段语义**：
+**音频格式约束**：
 
-- `is_last`: 每个句子合成完毕后为 `true`，前端收到此信号即可将该句子加入播放队列。每句 TTS 音频由一次独立的 API 调用生成，对应一个 `tts_audio` 消息。
-- `final`: 所有句子合成完毕后为 `true`（此时 `audio` 为空字符串），用于前端判断本轮 TTS 已全部到齐。
-
-**音频格式规范**（前端播放依赖此约定）：
-
-| 属性 | 值 | 说明 |
-|------|------|------|
-| 编码 | `audio/mp3`（MP3） | 浏览器 `<audio>` 原生支持 |
-| 采样率 | 24kHz | OpenAI TTS 默认 |
-| 声道 | 单声道 | 语音不需要立体声 |
-| 传输 | Base64 编码的 MP3 片段 | 每个 `tts_audio` 消息携带一个句子的音频 |
-| 切片粒度 | 按句子切分 | LLM 输出中按 `。！？\n` 等标点切分，每个句子独立合成 |
-
-**流式播放时序**：`tts_audio` 消息按句子顺序到达，前端应按序排队播放，不要等全部到齐再播。
-
-**前端播放实现要点**：
-
-1. **排队播放**：收到 `is_last: true` 时，将该句子的音频片段拼接为 Blob URL 并加入播放队列。第一句到达即开始播放，后续句子在 `onended` 回调中自动衔接。
-2. **错误容错**：单个句子播放失败时跳过，继续播放队列中下一个，不中断整个回复。
-3. **打断清理**：收到 `interrupt` 消息或用户触发打断时，清空播放队列并释放所有 Blob URL。
-4. **类型锁定**：`mime_type` 字段固定为 `"audio/mp3"`，前端解码时直接使用，无需运行时判断。
-
-```typescript
-// 前端播放器伪代码
-class AudioPlayer {
-  private sentenceChunks: string[] = [];  // 当前句子的音频片段缓冲
-  private queue: string[] = [];           // 已就绪的句子 Blob URL 队列
-
-  enqueue(base64: string, isLast: boolean) {
-    this.sentenceChunks.push(base64);
-    if (isLast) {
-      const url = decodeBase64Audio(this.sentenceChunks.join(""), "audio/mp3");
-      this.sentenceChunks = [];
-      this.queue.push(url);
-      if (this.queue.length === 1) this.playNext();
-    }
-  }
-
-  private playNext() {
-    if (this.queue.length === 0) return;
-    const audio = new Audio(this.queue.shift()!);
-    audio.onended = () => { URL.revokeObjectURL(audio.src); this.playNext(); };
-    audio.onerror = () => { URL.revokeObjectURL(audio.src); this.playNext(); };
-    audio.play();
-  }
-
-  clear() { this.queue.forEach(url => URL.revokeObjectURL(url)); this.queue = []; this.sentenceChunks = []; }
-}
-```
+| 字段 | 值 | 说明 |
+|------|-----|------|
+| `format` | `"pcm"` | 线性 PCM，小端序 |
+| `sample_rate` | `24000` | 24kHz 采样率 |
+| 位深度 | 16-bit | 单声道 |
+| 句子划分 | 按标点符号（。！？；：）分割 | 服务端按句分割 LLM 响应，并行合成 |
 
 #### `error` — 错误通知
 
 ```typescript
 interface ErrorMessage {
   type: "error";
-  request_id?: string;
-  code: string;          // 错误码，见下方错误码表
+  request_id?: string;   // 关联的请求 ID，全局错误时为空
+  code: string;          // 错误码，见下文错误码表
   message: string;       // 人类可读的错误描述
+  details?: any;         // 可选的详细错误信息
 }
 ```
 
@@ -234,1214 +186,372 @@ interface PongMessage {
 }
 ```
 
-### 消息流时序
+### 连接管理
 
-**语音模式**（麦克风开启）：
-
-```
-Client                          Server
-  |                               |
-  |-- query {image, audio} ------>|
-  |<-- stt_result {text} ---------|  (语音识别)
-  |                               |
-  |<-- llm_chunk {delta: "这"} ---|  (LLM 流式输出)
-  |<-- llm_chunk {delta: "是一"} -|
-  |<-- llm_chunk {delta: "朵花"} -|
-  |<-- llm_done {full_text} ------|
-  |                               |
-  |<-- tts_audio {audio} ---------|  (TTS 音频流)
-  |<-- tts_audio {is_last: true} -|  (句子完成)
-  |<-- tts_audio {final: true} ---|  (TTS 全部结束)
-```
-
-**文本输入模式**（麦克风关闭，手动输入文字）：
-
-```
-Client                          Server
-  |                               |
-  |-- query {image, text} ------->|  (跳过 STT)
-  |<-- stt_result {text} ---------|  (回显用户文本)
-  |                               |
-  |<-- llm_chunk {delta: "好的"} -|  (LLM 流式输出)
-  |<-- llm_chunk {delta: "，我"} -|
-  |<-- llm_done {full_text} ------|
-  |                               |
-  |<-- tts_audio {audio} ---------|  (TTS 音频流)
-  |<-- tts_audio {is_last: true} -|  (句子完成)
-  |<-- tts_audio {final: true} ---|  (TTS 全部结束)
-```
+- **心跳机制**：客户端每 30 秒发送 `ping`，服务端回复 `pong`；60 秒无活动则服务端断开连接
+- **重连策略**：客户端断线后指数退避重连（1s → 2s → 4s → ... → 最大 30s）
+- **并发控制**：同一连接同时只能有一个活跃的 `query` 请求；新请求到来时自动取消旧请求
 
 ---
 
 ## 二、REST API
 
-### 通用约定
+所有 REST 端点均使用 JSON 格式。
 
-#### 认证方式
+### 2.1 健康检查
 
-采用 **JWT 双 token 轮转认证机制**。详细设计见 [鉴权体系设计](./12-鉴权体系设计.md)。
+#### `GET /api/health`
 
-**Token 类型**：
-- **access_token**：短期令牌（15 分钟），用于 API 认证和 WebSocket 连接
-- **refresh_token**：长期令牌（7 天），用于刷新 access_token
-
-**请求头格式**：
-```
-Authorization: Bearer <access_token>
-```
-
-**认证流程**：
-1. 用户登录后获取 access_token + refresh_token
-2. 请求受保护接口时携带 access_token
-3. access_token 过期时，使用 refresh_token 刷新获取新的 token pair
-4. refresh_token 采用轮转机制，每次刷新后旧 token 失效
-
-**WebSocket 认证**：
-- 连接地址：`ws://host/ws?token=<access_token>&conversation_id=<uuid>`
-- HTTP Upgrade 前校验 token
-- 校验失败返回 401 Unauthorized
-
-#### 错误响应格式
-
-所有错误响应统一结构：
-
-```typescript
-interface ApiError {
-  code: string;     // 机器可读错误码
-  message: string;  // 人类可读描述
-}
-```
-
-示例：
+检查服务健康状态。
 
+**响应**：
 ```json
 {
-  "code": "USERNAME_TAKEN",
-  "message": "username already taken"
-}
-```
-
-#### 输入校验规则
-
-| 字段 | 规则 |
-|------|------|
-| `username` | 3-64 字符，仅允许字母、数字、下划线 |
-| `password` | 8-72 字符 |
-
----
-
-### 认证接口（`/api/auth`）
-
-#### 注册
-
-```
-POST /api/auth/register
-Content-Type: application/json
-```
-
-**请求体**：
-
-```typescript
-interface RegisterRequest {
-  username: string;  // 3-64 字符
-  password: string;  // 8-72 字符
-}
-```
-
-**成功响应** `201 Created`：
-
-```typescript
-interface AuthResponse {
-  user: {
-    id: string;          // UUID
-    username: string;
-    created_at: string;  // ISO 8601
-  };
-  access_token: string;   // JWT，15 分钟有效
-  refresh_token: string;  // JWT，7 天有效
-}
-```
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 400 | `INVALID_INPUT` | 用户名/密码不符合校验规则 |
-| 409 | `USERNAME_TAKEN` | 用户名已存在 |
-
-#### 登录
-
-```
-POST /api/auth/login
-Content-Type: application/json
-```
-
-**请求体**：
-
-```typescript
-interface LoginRequest {
-  username: string;
-  password: string;
-}
-```
-
-**成功响应** `200 OK`：同 `AuthResponse` 结构。
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 400 | `INVALID_INPUT` | 请求参数缺失或格式错误 |
-| 401 | `INVALID_CREDENTIALS` | 用户名或密码错误 |
-
-#### 刷新 Token（Refresh Token Rotation）
-
-```
-POST /api/auth/refresh
-Content-Type: application/json
-```
-
-**请求体**：
-
-```typescript
-interface RefreshRequest {
-  refresh_token: string;  // 之前签发的 refresh_token
-}
-```
-
-**成功响应** `200 OK`：同 `AuthResponse` 结构（返回新的 access_token + refresh_token，旧 refresh_token 失效——Token 轮转）。
-
-**安全机制**：
-- **Token 轮转**：每次 refresh 都会生成新的 token pair，旧 refresh_token 立即失效
-- **复用检测**：如果检测到已删除的 refresh_token 被复用，立即吊销该用户的所有 refresh_token
-- **强制重新登录**：吊销后，该用户所有设备都需要重新登录
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | refresh_token 无效或已过期 |
-
-**前端集成示例**：
-
-```typescript
-// axios 响应拦截器
-api.interceptors.response.use(
-  (response) => response,
-  async (error) => {
-    const originalRequest = error.config;
-
-    // 如果是 401 且不是 refresh 请求，尝试刷新 token
-    if (error.response?.status === 401 && !originalRequest._retry) {
-      originalRequest._retry = true;
-
-      try {
-        const refreshToken = getRefreshToken();
-        const response = await api.post('/api/auth/refresh', {
-          refresh_token: refreshToken,
-        });
-
-        const { access_token, refresh_token } = response.data;
-        setAccessToken(access_token);
-        setRefreshToken(refresh_token);
-
-        // 重试原始请求
-        originalRequest.headers.Authorization = `Bearer ${access_token}`;
-        return api(originalRequest);
-      } catch (refreshError) {
-        // 刷新失败，跳转登录页
-        clearTokens();
-        window.location.href = '/login';
-        return Promise.reject(refreshError);
-      }
-    }
-
-    return Promise.reject(error);
+  "status": "healthy",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "dependencies": {
+    "database": "healthy",
+    "redis": "healthy"
   }
-);
+}
 ```
 
-#### 登出
+### 2.2 认证 API
 
+#### `POST /api/auth/register` — 用户注册
+
+**请求**：
+```json
+{
+  "username": "alice",
+  "email": "alice@example.com",
+  "password": "SecurePass123!"
+}
+```
+
+**响应**（200 OK）：
+```json
+{
+  "user": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "username": "alice",
+    "email": "alice@example.com",
+    "created_at": "2024-01-15T10:30:00Z"
+  },
+  "access_token": "eyJhbGc...",
+  "refresh_token": "eyJhbGc...",
+  "expires_in": 7200
+}
+```
+
+**错误**：
+- `400 INVALID_INPUT`: 参数验证失败
+- `409 USER_EXISTS`: 用户名或邮箱已存在
+
+#### `POST /api/auth/login` — 用户登录
+
+**请求**：
+```json
+{
+  "username": "alice",
+  "password": "SecurePass123!"
+}
+```
+
+**响应**（200 OK）：
+```json
+{
+  "user": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "username": "alice",
+    "email": "alice@example.com"
+  },
+  "access_token": "eyJhbGc...",
+  "refresh_token": "eyJhbGc...",
+  "expires_in": 7200
+}
+```
+
+**错误**：
+- `400 INVALID_INPUT`: 参数缺失
+- `401 INVALID_CREDENTIALS`: 用户名或密码错误
+
+#### `POST /api/auth/refresh` — 刷新 Access Token
+
+**请求头**：
+```
+Authorization: Bearer <refresh_token>
+```
+
+**响应**（200 OK）：
+```json
+{
+  "access_token": "eyJhbGc...",
+  "refresh_token": "eyJhbGc...",
+  "expires_in": 7200
+}
+```
+
+**错误**：
+- `401 INVALID_TOKEN`: Refresh Token 无效或过期
+
+#### `POST /api/auth/logout` — 用户登出
+
+**请求头**：
 ```
-POST /api/auth/logout
-Content-Type: application/json
 Authorization: Bearer <access_token>
 ```
 
-**请求体**：
-
-```typescript
-interface LogoutRequest {
-  refresh_token: string;  // 要废弃的 refresh_token
+**响应**（200 OK）：
+```json
+{
+  "message": "Logged out successfully"
 }
 ```
 
-**成功响应** `204 No Content`（无响应体）。
+### 2.3 对话管理 API
 
-**错误响应**：
+所有端点均需 JWT 认证（`Authorization: Bearer <access_token>`）。
 
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | access_token 无效或已过期 |
-
----
-
-### 对话接口（`/api/conversations`）
-
-> 以下所有接口均需认证（`Authorization: Bearer <access_token>`），省略不重复标注。
-
-#### 对话列表
-
-```
-GET /api/conversations?page=1&size=20
-```
+#### `GET /api/conversations` — 获取对话列表
 
 **查询参数**：
+- `page`: 页码，从 1 开始，默认 1
+- `page_size`: 每页条数，默认 20，最大 100
 
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `page` | int | 1 | 页码，从 1 开始 |
-| `size` | int | 20 | 每页条数，最大 50 |
-
-**成功响应** `200 OK`：
-
-```typescript
-interface ConversationListResponse {
-  conversations: ConversationSummary[];
-  total: number;
-  page: number;
-  size: number;
-}
-
-interface ConversationSummary {
-  id: string;            // 对话 ID（即 session_id）
-  title: string;         // 对话标题（首条消息前 20 字）
-  last_message: string;  // 最后一条消息内容预览
-  message_count: number; // 消息总数
-  updated_at: string;    // ISO 8601，最后活跃时间
+**响应**（200 OK）：
+```json
+{
+  "conversations": [
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440000",
+      "title": "关于植物的对话",
+      "created_at": "2024-01-15T10:30:00Z",
+      "updated_at": "2024-01-15T11:45:00Z",
+      "message_count": 12
+    }
+  ],
+  "total": 42,
+  "page": 1,
+  "page_size": 20
 }
 ```
 
-#### 创建对话
+#### `POST /api/conversations` — 创建新对话
 
-```
-POST /api/conversations
-Content-Type: application/json
-```
-
-**请求体**（可选，全部有默认值）：
-
-```typescript
-interface CreateConversationRequest {
-  config?: {
-    tts_enabled?: boolean;         // 默认 true
-    detail_level?: "low" | "high"; // 默认 "low"
-    language?: string;             // 默认 "zh-CN"
-  };
+**请求**：
+```json
+{
+  "title": "新的对话"
 }
 ```
 
-**成功响应** `201 Created`：
-
-```typescript
-interface ConversationDetail {
-  id: string;
-  title: string;
-  config: {
-    tts_enabled: boolean;
-    detail_level: "low" | "high";
-    language: string;
-  };
-  created_at: string;
-}
-```
-
-#### 获取对话详情
-
-```
-GET /api/conversations/:id
-```
-
-**成功响应** `200 OK`：同 `ConversationDetail` 结构。
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 404 | `SESSION_NOT_FOUND` | 对话不存在或不属于当前用户 |
-
-#### 更新对话标题
-
-```
-PATCH /api/conversations/:id
-Content-Type: application/json
-```
-
-**请求体**：
-
-```typescript
-interface UpdateTitleRequest {
-  title: string;  // 1-100 字符
-}
-```
-
-**成功响应** `200 OK`：
-
+**响应**（201 Created）：
 ```json
 {
   "id": "550e8400-e29b-41d4-a716-446655440000",
-  "title": "新的自定义标题"
+  "title": "新的对话",
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-15T10:30:00Z",
+  "message_count": 0
 }
 ```
 
-**错误响应**：
+#### `GET /api/conversations/:id` — 获取对话详情
 
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 400 | `INVALID_INPUT` | title 为空或超长 |
-| 404 | `SESSION_NOT_FOUND` | 对话不存在或不属于当前用户 |
-
-#### 删除对话
-
-```
-DELETE /api/conversations/:id
+**响应**（200 OK）：
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "title": "关于植物的对话",
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-15T11:45:00Z",
+  "message_count": 12
+}
 ```
 
-**成功响应** `204 No Content`（无响应体）。
+**错误**：
+- `404 NOT_FOUND`: 对话不存在或无权访问
 
-#### 获取对话消息
+#### `PATCH /api/conversations/:id` — 更新对话
 
+**请求**：
+```json
+{
+  "title": "修改后的标题"
+}
 ```
-GET /api/conversations/:id/messages?limit=50&before=<message_id>
+
+**响应**（200 OK）：
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "title": "修改后的标题",
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-01-15T12:00:00Z",
+  "message_count": 12
+}
 ```
 
+#### `DELETE /api/conversations/:id` — 删除对话
+
+**响应**（204 No Content）：无响应体
+
+**错误**：
+- `404 NOT_FOUND`: 对话不存在或无权访问
+
+#### `GET /api/conversations/:id/messages` — 获取对话消息
+
 **查询参数**：
+- `page`: 页码，从 1 开始，默认 1
+- `page_size`: 每页条数，默认 50，最大 100
 
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `limit` | int | 50 | 返回条数，最大 100 |
-| `before` | int64 | — | 游标分页：返回此 message_id 之前的消息（不含） |
-
-**成功响应** `200 OK`：
-
-```typescript
-interface MessagesResponse {
-  messages: StoredMessage[];
-  has_more: boolean;
-}
-
-interface StoredMessage {
-  id: number;           // 自增 ID，用于游标分页
-  role: "user" | "assistant";
-  content: string;
-  tokens_used: number;
-  created_at: string;   // ISO 8601
+**响应**（200 OK）：
+```json
+{
+  "messages": [
+    {
+      "id": "660e8400-e29b-41d4-a716-446655440000",
+      "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
+      "role": "user",
+      "content": "这是什么植物？",
+      "image_url": "/api/images/abc123.jpg",
+      "created_at": "2024-01-15T10:30:00Z"
+    },
+    {
+      "id": "770e8400-e29b-41d4-a716-446655440000",
+      "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
+      "role": "assistant",
+      "content": "这是一株向日葵...",
+      "created_at": "2024-01-15T10:30:15Z"
+    }
+  ],
+  "total": 12,
+  "page": 1,
+  "page_size": 50
 }
 ```
 
-**分页用法**：首次请求不带 `before`，获取最新消息。滚动到顶部时，取当前列表最小的 `id` 作为 `before` 参数请求更早的消息。
+**消息字段说明**：
+- `role`: `"user"` 或 `"assistant"`
+- `image_url`: 仅 `user` 消息可能包含，指向存储的图像
+- `content`: 消息文本内容
 
 ---
 
-### 健康检查
+## 三、错误码表
 
-```
-GET /api/health
-```
-
-无需认证。
-
-**成功响应** `200 OK`：
+所有错误均使用以下格式：
 
 ```json
 {
-  "status": "ok",
-  "version": "0.1.0",
-  "uptime_seconds": 3600,
-  "active_sessions": 42
+  "code": "ERROR_CODE",
+  "message": "Human-readable error description",
+  "details": {}
 }
 ```
 
+### WebSocket 错误码
+
+| 错误码 | 说明 | HTTP 状态码（若适用）|
+|--------|------|---------------------|
+| `INVALID_MESSAGE` | 消息格式错误或缺少必填字段 | - |
+| `SESSION_NOT_FOUND` | 会话不存在 | - |
+| `RATE_LIMITED` | 请求频率过高 | 429 |
+| `IMAGE_TOO_LARGE` | 图像超过大小限制（5MB）| - |
+| `AUDIO_TOO_LARGE` | 音频超过大小限制（10MB）| - |
+| `STT_ERROR` | 语音识别服务错误 | - |
+| `LLM_ERROR` | LLM 服务错误 | - |
+| `LLM_TIMEOUT` | LLM 响应超时（60 秒）| - |
+| `TTS_ERROR` | 语音合成服务错误 | - |
+| `CONCURRENT_REQUEST` | 同一连接已有进行中的请求 | - |
+| `INTERNAL_ERROR` | 服务器内部错误 | 500 |
+
+### REST API 错误码
+
+| 错误码 | 说明 | HTTP 状态码 |
+|--------|------|-------------|
+| `INVALID_INPUT` | 请求参数验证失败 | 400 |
+| `INVALID_TOKEN` | JWT Token 无效或过期 | 401 |
+| `INVALID_CREDENTIALS` | 用户名或密码错误 | 401 |
+| `UNAUTHORIZED` | 未认证或认证失败 | 401 |
+| `FORBIDDEN` | 无权访问资源 | 403 |
+| `NOT_FOUND` | 资源不存在 | 404 |
+| `USER_EXISTS` | 用户名或邮箱已存在 | 409 |
+| `RATE_LIMITED` | 请求频率过高 | 429 |
+| `INTERNAL_ERROR` | 服务器内部错误 | 500 |
+| `SERVICE_UNAVAILABLE` | 依赖服务不可用 | 503 |
+
 ---
 
-### 预留端点（待实现）
+## 四、数据模型
 
-| 端点 | 方法 | 用途 |
-|------|------|------|
-| `/api/usage` | GET | 查询用量统计 |
-| `/api/users/{id}/preferences` | GET/PUT | 用户偏好管理 |
-
----
-
-## 三、AI 服务层接口
-
-Go 网关内部与外部 AI 服务（STT、LLM、TTS）的调用契约。通过 OpenAI 兼容接口可灵活切换到其他服务商。
-
-### STT 服务接口
-
-语音识别：接收前端采集的音频，返回识别文本。
-
-```go
-// Service 语音识别服务契约。
-type Service interface {
-    // Recognize 识别一段完整音频，返回最终文本。
-    Recognize(ctx context.Context, audio []byte, opts Options) (string, error)
-}
-
-// Options 语音识别参数。
-type Options struct {
-    Encoding   string // "pcm_s16le" — 前端 VAD 输出格式
-    SampleRate int    // 16000 — 前端麦克风采样率
-    Language   string // "zh-CN"
-}
-```
-
-**已实现 Provider**：
-
-| Provider | 连接方式 | 说明 |
-|----------|---------|------|
-| MiMo ASR（默认） | HTTP POST OpenAI 兼容 `/chat/completions` | 国产替代，PCM 自动转 WAV，支持 zh/en/auto |
-| Deepgram | WebSocket `wss://api.deepgram.com/v1/listen` | 流式识别，延迟极低，模型 nova-2 |
-
-### LLM 服务接口
-
-多模态推理通过 Eino 框架的 `eino-ext/components/model/openai` ChatModel 组件实现，替代了原有的手动 `llm.Service` 接口。
-
-**Eino ChatModel 配置**：
-
-```go
-chatModel, _ := openaiImpl.NewChatModel(ctx, &openaiImpl.ChatModelConfig{
-    APIKey:  cfg.AI.LLM.APIKey,
-    Model:   cfg.AI.LLM.Model,       // 默认 "qwen3-vl-plus"
-    BaseURL: cfg.AI.LLM.Endpoint,     // 默认 DashScope OpenAI 兼容接口
-    Timeout: time.Duration(cfg.AI.LLM.Timeout) * time.Second,
-})
-```
-
-**ChatModel 接口**（Eino 组件标准接口）：
-
-```go
-type BaseChatModel interface {
-    Generate(ctx, []*schema.Message, ...Option) (*schema.Message, error)
-    Stream(ctx, []*schema.Message, ...Option) (*schema.StreamReader[*schema.Message], error)
-}
-```
-
-CamTalk 使用 `Stream()` 模式，通过 Eino Graph 的 Stream 调用触发，token 级流式输出通过 Callback `OnEndWithStreamOutput` 推送到客户端。
-
-**接入约定**：
-- 端点：通过 `ai.llm.endpoint` 配置，支持任何 OpenAI 兼容接口
-- 默认模型：`qwen3-vl-plus`（DashScope），通过 `ai.llm.model` 配置切换
-- 图片传入：History 节点构建 `schema.Message.UserInputMultiContent`，使用 `Base64Data` + `MIMEType` 格式
-- 流式响应：Eino 框架原生 `StreamReader` 支持
-- 超时：通过 `ChatModelConfig.Timeout` 控制
-- 系统提示词：History 节点根据语言和场景（scenario）动态构建
-
-**保留的类型定义**（`ai/llm/llm.go`）：
-
-```go
-// Request / Chunk / TokenUsage 类型定义仍保留在 ai/llm 包中，
-// 供 prompt.go 和 scenarios.go 使用。LLM 推理本身通过 eino-ext ChatModel 执行。
-```
-
-### TTS 服务接口
-
-语音合成：接收文本流，输出音频 chunk 流。
-
-```go
-// Service 语音合成服务契约。
-type Service interface {
-    // SynthesizeStream 流式合成。
-    // textStream 接收句子级文本（由 Orchestrator 的句子切分器产出），
-    // 返回的 channel 持续输出 MP3 音频 chunk。
-    SynthesizeStream(ctx context.Context, textStream <-chan string, opts Options) (<-chan Chunk, error)
-}
-
-// Options 合成参数。
-type Options struct {
-    Voice      string  // 语音名称
-    Speed      float64 // 1.0 为正常语速
-    OutputFmt  string  // "mp3"
-    SampleRate int     // 24000
-}
-```
-
-**已实现 Provider**：
-
-| Provider | 端点 | 说明 |
-|----------|------|------|
-| MiMo TTS（默认） | `POST /chat/completions` | 国产替代，base64 音频响应 |
-| OpenAI TTS | `POST /audio/speech` | 逐句合成，返回 MP3 流 |
-
----
-
-## 四、AI 编排器（Orchestrator）
-
-### 编排架构：Eino Graph 声明式编排
-
-AI 编排层基于 [CloudWeGo Eino](https://github.com/cloudwego/eino) 框架的 `compose.Graph` 实现，替代了原有的手写 goroutine 管道。Eino Graph 是一个声明式的有向无环图（DAG）编排器，支持类型安全的流式数据传递和 Callback AOP 机制。
-
-**核心矛盾**：LLM 流式输出逐 token，TTS 需要完整句子才能合成。解法：**Eino TransformableLambda 句子切分 + Stream 模式管道**。
-
-```
-LLM 流式输出:  "这" "是一" "朵红色" "的花。" "它看起" "来很美" "丽。"
-                ↓
-        ┌── 句子检测器（按 。！？\n 切分）──┐
-        ↓                                 ↓
-  句子1: "这是一朵红色的花。"          句子2: "它看起来很美丽。"
-        ↓                                 ↓
-     TTS 合成                          TTS 合成
-        ↓                                 ↓
-  音频 chunk → 推送前端             音频 chunk → 推送前端
-```
-
-**时序保证**：
-- `llm_chunk` 通过 Callback `OnEndWithStreamOutput` 实时推送，一定先于对应句子的 `tts_audio` 到达客户端
-- 用户先看到文字，紧接着听到语音（感知延迟 < 0.5 秒）
-
-### Graph 拓扑
-
-```
-START → STT → History → ChatModel → Msg2Str → Splitter → TTS → Done → END
-```
-
-| 节点 | Lambda 类型 | 输入 → 输出 | 职责 |
-|------|------------|------------|------|
-| STT | InvokableLambda | `PipelineInput → STTOutput` | 语音识别（文本模式跳过），发送 `stt_result`，写入 State |
-| History | InvokableLambda | `STTOutput → []*schema.Message` | 组装系统提示词 + 对话历史 + 多模态图像消息 |
-| ChatModel | ChatModel（原生） | `[]*schema.Message → StreamReader[*Message]` | Eino 原生 LLM 流式推理 |
-| Msg2Str | TransformableLambda | `StreamReader[*Message] → StreamReader[string]` | 提取 LLM 输出文本 |
-| Splitter | TransformableLambda | `StreamReader[string] → StreamReader[string]` | 按句子分隔符切分，逐句输出 |
-| TTS | TransformableLambda | `StreamReader[string] → StreamReader[struct{}]` | 逐句调用 TTS 服务，推送 `tts_audio` |
-| Done | InvokableLambda | `struct{} → PipelineOutput` | 发送 `llm_done`，返回最终输出 |
-
-**依赖版本**：
-- `github.com/cloudwego/eino v0.9.9`
-- `github.com/cloudwego/eino-ext/components/model/openai v0.1.13`
-
-### Orchestrator 接口
-
-```go
-type Orchestrator interface {
-    ProcessQuery(ctx context.Context, sessionID string, req models.WsQuery,
-        history []models.Message, sender Sender) error
-}
-
-type Sender interface {
-    SendSTTResult(result models.WsSTTResult) error
-    SendLLMChunk(chunk models.WsLLMChunk) error
-    SendLLMDone(done models.WsLLMDone) error
-    SendTTSAudio(audio models.WsTTSAudio) error
-    SendError(err models.WsError) error
-}
-```
-
-WS Handler 通过 `Orchestrator` 接口与编排层交互，不感知 Eino 实现细节。
-
-### EinoOrchestrator 执行流程
-
-`EinoOrchestrator` 实现 `Orchestrator` 接口，包装 Eino Graph：
-
-1. 设置活跃请求，获取会话配置
-2. Base64 解码音频/图片
-3. 构建 `PipelineInput`
-4. 注入 context 值（Sender、RequestID、SessionID、PipelineState、StartTime）
-5. 追加用户消息到历史
-6. 调用 `graph.Runnable.Stream(ctx, input, callbacks)` — Stream 模式触发整条链路惰性执行
-7. 消费 `StreamReader[PipelineOutput]` 直到 EOF
-8. 追加助手消息到历史
-
-### Callback 机制
-
-LLM token 推送通过 Eino Callback 实现，而非在 Lambda 节点中硬编码：
-
-```go
-// 构建 typed callback handler
-handler := callbacks.NewHandlerHelper().ChatModel(&modelCallbackHandler{}).Handler()
-
-// 运行时传入（不在 Compile 时注册）
-streamReader, err := runnable.Stream(ctx, input, compose.WithCallbacks(handler))
-```
-
-**OnEndWithStreamOutput** 回调：
-- 接收 ChatModel 的 `StreamReader[*schema.Message]`
-- 逐 chunk 推送 `llm_chunk` 到客户端
-- 累积完整回复到 `PipelineState`
-- 记录 token 用量
-
-### State 机制
-
-`PipelineState` 是 Graph 级别的线程安全状态，通过 `compose.WithGenLocalState` 注册：
-
-```go
-type PipelineState struct {
-    FullResponse    strings.Builder  // LLM 完整回复（Callback 累积）
-    TranscribedText string           // STT 识别文本
-    TokenUsage      *TokenUsage      // Token 用量
-    SessionID       string
-    RequestID       string
-    ImageData       []byte
-    Scenario        string
-    Language        string
-    TTSEnabled      bool
-}
-```
-
-各节点通过 `stateFromCtx(ctx)` 读写 State，实现跨节点数据共享。
-
-### 并发控制
-
-- 每个 `ProcessQuery` 调用在独立 goroutine 中运行
-- `context.WithTimeout` 确保总超时
-- `interrupt` 消息触发 `cancel()`，Eino Graph 内部所有流式节点中断
-- 同一 session 内同时只允许一个活跃请求，新请求自动取消上一个
-- `PipelineState` 使用 `sync.Mutex` 保护并发写入
-
-### 错误处理与降级
-
-| 故障点 | 处理策略 | 客户端表现 |
-|--------|---------|-----------|
-| STT 失败 | 发送 `STT_ERROR`，Graph 终止 | 回退到纯文本模式 |
-| LLM 超时 | 发送 `LLM_TIMEOUT`，取消下游 | 提示用户重试 |
-| LLM 部分输出后失败 | 已推送的 `llm_chunk` 保留，发送 `error` 通知中断 | 显示已收到的部分文字 |
-| TTS 失败 | 静默跳过，`llm_done` 正常发送 | 只有文字回复，无语音 |
-| interrupt 打断 | cancel context，Graph 内所有流中断 | 前端清空播放队列 |
-
----
-
-## 五、Session Manager
-
-WebSocket Handler 和 AI Orchestrator 之间的会话管理层。负责维护会话生命周期、对话上下文和配置状态。
-
-### 数据结构
-
-**Memory 存储**（默认）：
-
-```
-MemoryManager
-├── sessions: map[string]*sessionEntry
-│   ├── session     models.Session
-│   ├── history     []models.Message
-│   ├── activeReqID string
-│   └── lastActive  time.Time
-├── msgRepo:  MessageRepository  (Write-Through, 可选)
-└── sessRepo: SessionRepository  (Write-Through, 可选)
-```
-
-**Redis 存储**（可选）：
-
-```
-session:{id}:meta    → Hash   （会话元数据）
-session:{id}:history → List   （对话历史）
-user:{id}:sessions   → Set    （用户会话索引）
-```
-
-### TTL 策略
-
-| 场景 | TTL | 说明 |
-|------|-----|------|
-| 创建时 | 30 分钟 | `EXPIRE` 设置 |
-| 每次收到消息 | 重置 30 分钟 | `EXPIRE` 刷新 |
-| WebSocket 断开 | 不主动删 | 等自然过期，支持重连恢复 |
-| 超过 30 分钟无活动 | 自动过期 | 自动清理 |
-| 显式销毁（REST API） | 立即删除 | |
-
-### 接口定义
-
-```go
-type Manager interface {
-    // Create 创建新会话，关联 user_id，返回 session ID。
-    Create(ctx context.Context, userID string, config models.SessionConfig) (string, error)
-
-    // Get 获取会话（含 config）。不存在返回 ErrSessionNotFound。
-    Get(ctx context.Context, sessionID string) (*models.Session, error)
-
-    // UpdateConfig 更新会话配置（config 消息触发）。
-    UpdateConfig(ctx context.Context, sessionID string, patch models.SessionConfigPatch) error
-
-    // UpdateTitle 更新对话标题。
-    UpdateTitle(ctx context.Context, sessionID string, title string) error
-
-    // ListByUser 获取用户的对话列表（分页）。
-    ListByUser(ctx context.Context, userID string, page, size int) ([]ConversationSummary, int, error)
-
-    // GetHistory 获取最近 N 轮对话历史（供 Orchestrator 构建 LLM 上下文）。
-    GetHistory(ctx context.Context, sessionID string, limit int) ([]models.Message, error)
-
-    // AppendMessage 追加一条对话消息，同时刷新 TTL。首条 user 消息自动更新标题。
-    AppendMessage(ctx context.Context, sessionID string, msg models.Message) error
-
-    // SetActiveRequest 标记当前正在处理的请求 ID（interrupt 用）。
-    SetActiveRequest(ctx context.Context, sessionID string, requestID string) error
-
-    // GetActiveRequestID 获取当前活跃请求 ID。
-    GetActiveRequestID(ctx context.Context, sessionID string) (string, error)
-
-    // ClearActiveRequest 清除活跃请求标记（请求完成或中断后）。
-    ClearActiveRequest(ctx context.Context, sessionID string) error
-
-    // Touch 刷新 TTL（心跳时调用）。
-    Touch(ctx context.Context, sessionID string) error
-
-    // Destroy 显式销毁会话（REST API DELETE）。
-    Destroy(ctx context.Context, sessionID string) error
-
-    // ActiveCount 返回当前活跃会话数（健康检查用）。
-    ActiveCount() int
-}
-
-// ConversationSummary 对话列表项。
-type ConversationSummary struct {
-    ID           string    `json:"id"`
-    Title        string    `json:"title"`
-    LastMessage  string    `json:"last_message"`
-    MessageCount int       `json:"message_count"`
-    UpdatedAt    time.Time `json:"updated_at"`
-}
-```
-
-### Write-Through 机制
-
-MemoryManager 支持注入 `MessageRepository` 和 `SessionRepository`，实现写穿持久化：
-
-```go
-opts := []session.Option{}
-if msgRepo != nil {
-    opts = append(opts, session.WithMessageRepository(msgRepo))
-}
-if sessRepo != nil {
-    opts = append(opts, session.WithSessionRepository(sessRepo))
-}
-sessionMgr = session.NewMemoryManager(30*time.Minute, 20, opts...)
-```
-
-- `Create` 时同时写入 PG sessions 表
-- `AppendMessage` 时同时写入 PG messages 表
-- `Get` 时如果内存中不存在，尝试从 PG 恢复
-
-### 自动标题生成
-
-首条 user 消息时，如果 title 仍为 "新对话"，自动更新为消息内容前 20 个字符。
-
----
-
-## 六、存储层接口
-
-通过 Repository 接口隔离存储层，内存和 PostgreSQL 均已实现。
-
-### UserRepository
-
-```go
-type UserRepository interface {
-    Create(ctx context.Context, username, passwordHash string) (string, error)
-    FindByUsername(ctx context.Context, username string) (*User, error)
-    FindByID(ctx context.Context, id string) (*User, error)
-    SaveRefreshToken(ctx context.Context, userID, tokenHash string, expiresAt time.Time) error
-    FindRefreshToken(ctx context.Context, tokenHash string) (string, error)
-    DeleteRefreshToken(ctx context.Context, tokenHash string) error
-    DeleteUserRefreshTokens(ctx context.Context, userID string) error
-}
-```
-
-### MessageRepository
-
-```go
-type MessageRepository interface {
-    SaveMessage(ctx context.Context, sessionID string, msg models.Message, tokensUsed int) error
-    GetMessages(ctx context.Context, sessionID string, limit int, beforeID int64) ([]StoredMessage, error)
-    GetLastMessage(ctx context.Context, sessionID string) (*StoredMessage, error)
-    GetMessageCount(ctx context.Context, sessionID string) (int, error)
-    GetSessionMessageStats(ctx context.Context, sessionIDs []string) (map[string]int, error)
-}
-```
-
-### SessionRepository
-
-```go
-type SessionRepository interface {
-    Save(ctx context.Context, session models.Session) error
-    FindByID(ctx context.Context, id string) (*models.Session, error)
-    FindByUser(ctx context.Context, userID string, page, size int) ([]models.Session, int, error)
-    UpdateTitle(ctx context.Context, id string, title string) error
-    UpdateConfig(ctx context.Context, id string, config models.SessionConfig) error
-    Touch(ctx context.Context, id string) error
-    Delete(ctx context.Context, id string) error
-}
-```
-
-### 依赖注入
-
-```go
-// 存储层初始化
-if cfg.Storage.Persistence.Enabled {
-    pool, _ := store.NewPostgresPool(ctx, cfg.Storage.Persistence.DSN)
-    userRepo = store.NewPgUserRepository(pool)
-    msgRepo = store.NewPgMessageRepository(pool)
-    sessRepo = store.NewPgSessionRepository(pool)
-}
-
-// Session Manager 初始化（支持三级存储自动降级）
-if cfg.Storage.Redis.Enabled {
-    sessionMgr = session.NewTieredManager(30*time.Minute, 20, redisClient,
-        session.WithMessageRepository(msgRepo),
-        session.WithSessionRepository(sessRepo),
-    )
-} else if cfg.Storage.Persistence.Enabled {
-    sessionMgr = session.NewMemoryManager(30*time.Minute, 20,
-        session.WithMessageRepository(msgRepo),
-        session.WithSessionRepository(sessRepo),
-    )
-} else {
-    sessionMgr = session.NewMemoryManager(30*time.Minute, 20)
-}
-
-// Eino Graph 初始化
-pipelineGraph, _ := eino.NewPipelineGraph(ctx, cfg, sttService, ttsService, sessionMgr)
-orchestrator := eino.NewEinoOrchestrator(pipelineGraph, sessionMgr, cfg.AI.LLM.Model)
-```
-
----
-
-## 七、配置管理
-
-使用 Viper 加载配置，支持 YAML 文件 + 环境变量覆盖。**环境变量优先级高于配置文件**。
-
-### 配置文件位置
-
-```
-backend/config/config.yaml        # 默认加载
-backend/config/config.dev.yaml    # 开发环境
-backend/config/config.prod.yaml   # 生产环境
-```
-
-加载顺序：`config.yaml` → `config.{APP_ENV}.yaml` → 环境变量（前缀 `CAMTALK_`）。
-
-### 配置结构体
-
-```go
-type Config struct {
-    App      AppConfig      `mapstructure:"app"`
-    Server   ServerConfig   `mapstructure:"server"`
-    Session  SessionConfig  `mapstructure:"session"`
-    Redis    RedisConfig    `mapstructure:"redis"`
-    AI       AIConfig       `mapstructure:"ai"`
-    Storage  StorageConfig  `mapstructure:"storage"`
-    Auth     AuthConfig     `mapstructure:"auth"`
-    Log      LogConfig      `mapstructure:"log"`
-}
-
-type AppConfig struct {
-    Env     string `mapstructure:"env"`     // "dev" | "prod"，默认 "dev"
-    Version string `mapstructure:"version"` // 由编译时注入
-}
-
-type ServerConfig struct {
-    Host              string   `mapstructure:"host"`               // 默认 "0.0.0.0"
-    Port              int      `mapstructure:"port"`               // 默认 8080
-    ReadTimeout       int      `mapstructure:"read_timeout"`       // 秒，默认 30
-    WriteTimeout      int      `mapstructure:"write_timeout"`      // 秒，默认 30
-    HeartbeatInterval int      `mapstructure:"heartbeat_interval"` // 秒，默认 30
-    HeartbeatTimeout  int      `mapstructure:"heartbeat_timeout"`  // 秒，默认 60
-    ShutdownTimeout   int      `mapstructure:"shutdown_timeout"`   // 秒，默认 10
-    AllowedOrigins    []string `mapstructure:"allowed_origins"`    // 空表示允许所有
-}
-
-type SessionConfig struct {
-    TTL        int `mapstructure:"ttl"`         // 分钟，默认 30
-    MaxHistory int `mapstructure:"max_history"`  // 条数，默认 20
-}
-
-type RedisConfig struct {
-    Addr     string `mapstructure:"addr"`      // "localhost:6379"
-    Password string `mapstructure:"password"`
-    DB       int    `mapstructure:"db"`        // 默认 0
-}
-
-type AIConfig struct {
-    STT STTConfig `mapstructure:"stt"`
-    LLM LLMConfig `mapstructure:"llm"`
-    TTS TTSConfig `mapstructure:"tts"`
-}
-
-type STTConfig struct {
-    Provider          string `mapstructure:"provider"`             // "mimo" | "deepgram"
-    APIKey            string `mapstructure:"api_key"`
-    Model             string `mapstructure:"model"`                // 默认 "mimo-v2.5-asr"
-    Endpoint          string `mapstructure:"endpoint"`
-    Timeout           int    `mapstructure:"timeout"`              // 秒，默认 5
-    HTTPClientTimeout int    `mapstructure:"http_client_timeout"`  // 秒，默认 30
-}
-
-type LLMConfig struct {
-    Provider          string `mapstructure:"provider"`             // "dashscope" / "openai"
-    APIKey            string `mapstructure:"api_key"`
-    Model             string `mapstructure:"model"`                // 默认 "qwen3-vl-plus"
-    Endpoint          string `mapstructure:"endpoint"`
-    Timeout           int    `mapstructure:"timeout"`              // 秒，默认 30
-    HTTPClientTimeout int    `mapstructure:"http_client_timeout"`  // 秒，默认 60
-}
-
-type TTSConfig struct {
-    Provider          string  `mapstructure:"provider"`             // "mimo" | "openai"
-    APIKey            string  `mapstructure:"api_key"`
-    Model             string  `mapstructure:"model"`                // 默认 "mimo-v2.5-tts"
-    Voice             string  `mapstructure:"voice"`                // 默认 "mimo_default"
-    Speed             float64 `mapstructure:"speed"`                // 默认 1.0
-    Endpoint          string  `mapstructure:"endpoint"`
-    Timeout           int     `mapstructure:"timeout"`              // 秒，默认 5
-    HTTPClientTimeout int     `mapstructure:"http_client_timeout"`  // 秒，默认 30
-    OutputFormat      string  `mapstructure:"output_format"`        // 默认 "mp3"
-    SampleRate        int     `mapstructure:"sample_rate"`          // 默认 24000
-}
-
-type StorageConfig struct {
-    Driver string `mapstructure:"driver"` // "memory" | "postgres"
-    DSN    string `mapstructure:"dsn"`
-}
-
-type AuthConfig struct {
-    JWTSecret  string `mapstructure:"jwt_secret"`   // 必须通过 CAMTALK_AUTH_JWT_SECRET 设置
-    AccessTTL  int    `mapstructure:"access_ttl"`   // 分钟，默认 15
-    RefreshTTL int    `mapstructure:"refresh_ttl"`  // 分钟，默认 10080（7 天）
-}
-
-type LogConfig struct {
-    Level  string `mapstructure:"level"`  // "debug" | "info" | "warn" | "error"，默认 "info"
-    Format string `mapstructure:"format"` // "json" | "console"
-}
-```
-
-### 配置文件示例
-
-```yaml
-app:
-  env: dev
-
-server:
-  host: "0.0.0.0"
-  port: 8080
-  read_timeout: 30
-  write_timeout: 30
-  heartbeat_interval: 30
-  heartbeat_timeout: 60
-  shutdown_timeout: 10
-
-session:
-  ttl: 30
-  max_history: 20
-
-redis:
-  addr: "localhost:6379"
-  password: ""
-  db: 0
-
-ai:
-  stt:
-    provider: mimo
-    model: mimo-v2.5-asr
-    endpoint: "https://api.xiaomimimo.com/v1"
-    timeout: 5
-    http_client_timeout: 30
-  llm:
-    provider: dashscope
-    model: qwen3-vl-plus
-    endpoint: "https://dashscope.aliyuncs.com/compatible-mode/v1"
-    timeout: 30
-    http_client_timeout: 60
-  tts:
-    provider: mimo
-    model: mimo-v2.5-tts
-    voice: mimo_default
-    speed: 1.0
-    endpoint: "https://token-plan-cn.xiaomimimo.com/v1"
-    timeout: 5
-    http_client_timeout: 30
-    output_format: mp3
-    sample_rate: 24000
-
-storage:
-  redis:
-    enabled: true
-  persistence:
-    enabled: true
-    driver: postgres
-
-auth:
-  access_ttl: 15
-  refresh_ttl: 10080
-
-log:
-  level: info
-  format: console
-```
-
-### 环境变量覆盖规则
-
-前缀 `CAMTALK_` + 路径大写用 `_` 连接：
-
-| 配置项 | 环境变量 |
-|--------|---------|
-| `server.port` | `CAMTALK_SERVER_PORT` |
-| `redis.addr` | `CAMTALK_REDIS_ADDR` |
-| `ai.stt.api_key` | `CAMTALK_AI_STT_API_KEY` |
-| `ai.llm.api_key` | `CAMTALK_AI_LLM_API_KEY` |
-| `ai.tts.api_key` | `CAMTALK_AI_TTS_API_KEY` |
-| `storage.driver` | `CAMTALK_STORAGE_DRIVER` |
-| `storage.dsn` | `CAMTALK_STORAGE_DSN` |
-| `auth.jwt_secret` | `CAMTALK_AUTH_JWT_SECRET` |
-| `log.level` | `CAMTALK_LOG_LEVEL` |
-
-> API Key 和密码**只通过环境变量注入**，不写入配置文件，避免泄露到版本控制。
-
-### 启动命令
-
-```bash
-# 开发环境
-CAMTALK_AI_LLM_API_KEY=sk-xxx \
-CAMTALK_AI_STT_API_KEY=xxx \
-go run ./cmd/server
-
-# 生产环境
-CAMTALK_APP_ENV=prod \
-CAMTALK_STORAGE_DRIVER=postgres \
-CAMTALK_STORAGE_DSN="postgres://user:pass@db:5432/camtalk?sslmode=disable" \
-CAMTALK_AUTH_JWT_SECRET="$(openssl rand -hex 32)" \
-./bin/camtalk
-```
-
----
-
-## 八、数据模型
-
-### Go 后端模型
-
-```go
-type Session struct {
-    ID        string        `json:"session_id"`
-    UserID    string        `json:"user_id"`
-    Title     string        `json:"title"`
-    CreatedAt time.Time     `json:"created_at"`
-    UpdatedAt time.Time     `json:"updated_at"`
-    Config    SessionConfig `json:"config"`
-}
-
-type SessionConfig struct {
-    TTSEnabled  bool   `json:"tts_enabled"`
-    DetailLevel string `json:"detail_level"` // "low" | "high"
-    Language    string `json:"language"`
-    Scenario    string `json:"scenario"`     // "free_chat" | "interviewer" | "english_teacher" | "debate" | "interpreter"
-}
-
-type Message struct {
-    Role    string `json:"role"`    // "user" | "assistant"
-    Content string `json:"content"`
-}
-
-type User struct {
-    ID           string    `json:"id"`
-    Username     string    `json:"username"`
-    PasswordHash string    `json:"-"`
-    CreatedAt    time.Time `json:"created_at"`
-    UpdatedAt    time.Time `json:"updated_at"`
-}
-
-type StoredMessage struct {
-    ID         int64     `json:"id"`
-    SessionID  string    `json:"-"`
-    Role       string    `json:"role"`
-    Content    string    `json:"content"`
-    TokensUsed int       `json:"tokens_used"`
-    CreatedAt  time.Time `json:"created_at"`
-}
-```
-
-### TypeScript 前端模型
+### 用户（User）
 
 ```typescript
-interface SessionConfig {
-  ttsEnabled: boolean;
-  detailLevel: "low" | "high";
-  language: string;
-  scenario: string;
-}
-
-interface ChatMessage {
-  role: "user" | "assistant";
-  content: string;
-  imageUrl?: string;
-  timestamp: number;
-  tokensUsed?: number;
-}
-
-interface AuthTokens {
-  accessToken: string;
-  refreshToken: string;
-}
-
 interface User {
-  id: string;
-  username: string;
-  created_at: string;
+  id: string;              // UUID
+  username: string;        // 用户名，唯一
+  email: string;           // 邮箱，唯一
+  created_at: string;      // ISO 8601 时间戳
+  updated_at: string;      // ISO 8601 时间戳
 }
-
-// WebSocket 消息联合类型
-type ServerMessage =
-  | ConnectedMessage
-  | STTResultMessage
-  | LLMChunkMessage
-  | LLMDoneMessage
-  | TTSAudioMessage
-  | ErrorMessage
-  | PongMessage;
-
-type ClientMessage =
-  | QueryMessage
-  | ConfigMessage
-  | InterruptMessage
-  | PingMessage;
 ```
 
----
-
-## 九、错误码
-
-| 错误码 | HTTP 状态码 | 含义 | 客户端处理建议 |
-|--------|-----------|------|--------------|
-| `INVALID_MESSAGE` | — | 消息格式不合法（WS） | 检查 JSON 结构，不重试 |
-| `SESSION_NOT_FOUND` | 404 | 会话/对话不存在或已过期 | 重新建立连接或刷新列表 |
-| `RATE_LIMITED` | 429 | 请求频率超限 | 延迟后重试，提示用户稍等 |
-| `IMAGE_TOO_LARGE` | — | 图像超过 4MB 限制（WS） | 降低分辨率或压缩质量 |
-| `AUDIO_TOO_SHORT` | — | 音频片段 < 250ms（WS） | 忽略，等待下次语音输入 |
-| `LLM_TIMEOUT` | — | LLM 推理超时 >10s（WS） | 提示用户重试 |
-| `LLM_ERROR` | — | LLM 服务异常（WS） | 提示用户重试 |
-| `STT_ERROR` | — | 语音识别失败（WS） | 回退到纯文本输入模式 |
-| `TTS_ERROR` | — | 语音合成失败（WS） | 静默回退到纯文本回复 |
-| `INTERNAL_ERROR` | 500 | 服务端内部错误 | 提示用户重试 |
-| `USERNAME_TAKEN` | 409 | 用户名已被注册 | 提示换一个用户名 |
-| `INVALID_CREDENTIALS` | 401 | 用户名或密码错误 | 提示检查输入 |
-| `INVALID_TOKEN` | 401 | JWT 无效或已过期 | 尝试 refresh，失败则重新登录 |
-| `INVALID_INPUT` | 400 | 请求参数校验失败 | 检查字段规则后重试 |
-
----
-
-## 十、连接管理
-
-**心跳机制**：客户端每 30 秒发送应用层 `{type: "ping"}` 消息，服务端回复 `{type: "pong"}` 并刷新心跳计时器。超过 60 秒无 `ping`，服务端判定连接断开并清理会话资源。
-
-**重连策略**（指数退避 + 抖动）：
+### 对话（Conversation）
 
 ```typescript
-function reconnect(attempt: number) {
-  const delay = Math.min(1000 * Math.pow(2, attempt), 30000); // 最大 30s
-  const jitter = Math.random() * 1000;
-  setTimeout(() => connect(), delay + jitter);
+interface Conversation {
+  id: string;              // UUID
+  user_id: string;         // 所属用户 ID
+  title: string;           // 对话标题
+  created_at: string;      // ISO 8601 时间戳
+  updated_at: string;      // ISO 8601 时间戳
+  message_count: number;   // 消息数量
 }
-// attempt: 0 → 1s, 1 → 2s, 2 → 4s, 3 → 8s, ... 最大 30s
 ```
 
-### 跨域处理
+### 消息（Message）
 
-采用 **Nginx 同源反代**方案，前后端统一到同一域名，浏览器层面不存在跨域问题。
+```typescript
+interface Message {
+  id: string;              // UUID
+  conversation_id: string; // 所属对话 ID
+  role: "user" | "assistant";
+  content: string;         // 消息文本内容
+  image_url?: string;      // 可选，用户消息的关联图像 URL
+  created_at: string;      // ISO 8601 时间戳
+}
+```
 
-**开发环境**：前端 WebSocket 地址基于 `window.location.host` 动态构建，通过 Vite `server.proxy` 转发到后端 `http://localhost:8080`。
+### JWT Token 载荷
+
+**Access Token**（有效期 120 分钟）：
+```json
+{
+  "user_id": "550e8400-e29b-41d4-a716-446655440000",
+  "username": "alice",
+  "type": "access",
+  "exp": 1705318200,
+  "iat": 1705311000
+}
+```
+
+**Refresh Token**（有效期 7 天）：
+```json
+{
+  "user_id": "550e8400-e29b-41d4-a716-446655440000",
+  "type": "refresh",
+  "exp": 1705915800,
+  "iat": 1705311000
+}
+```
+
+---
+
+## 附录：版本历史
+
+- **v1.0**（2024-01-15）：初始版本，定义 WebSocket 协议和 REST API
+- **v1.1**（2024-01-20）：新增文本输入模式（`query.text` 字段）
+- **v1.2**（2024-01-25）：新增场景模式配置（`config.scenario` 字段）
+- **v2.0**（2026-06-21）：重构为纯接口契约规范，移除实现细节
diff --git a/docs/03-技术选型.md b/docs/03-技术选型.md
index fce53c7..f7865a4 100644
--- a/docs/03-技术选型.md
+++ b/docs/03-技术选型.md
@@ -4,7 +4,16 @@
 
 本文档记录项目中各项技术的**选型过程、替代方案对比和决策理由**。技术选型没有"绝对正确"，只有"更适合"。
 
-**定位**：本文档记录各项技术的选型过程和决策理由。
+各技术选型章节包含关键术语解释，帮助快速理解技术概念。
+
+### 后端核心技术栈
+
+| 名词 | 解释 |
+|------|------|
+| **Go (Golang)** | 高并发后端语言，Google 开发，杀手锏是 goroutine——极轻量协程，一个程序可轻松开几万个，每个只占几 KB 内存，适合管理大量 WebSocket 长连接 |
+| **gorilla/websocket** | Go WebSocket 库，Go 标准库无内置 WebSocket 支持，此库是社区最成熟的选择，处理了协议握手、帧解析等底层细节 |
+| **Viper** | Go 配置管理库，读取 JSON/YAML/TOML 配置，支持环境变量覆盖，方便开发/测试/生产环境用不同配置 |
+| **Zap** | Go 结构化日志库，Uber 开源，输出 JSON 格式日志，方便工具搜索分析，性能远超标准库 log |
 
 ```
 技术选型
@@ -34,6 +43,18 @@
 
 ## 一、AI 编排框架选型
 
+### 关键术语
+
+| 名词 | 解释 |
+|------|------|
+| **Eino** | 字节跳动开源的 Go AI 应用开发框架（CloudWeGo Eino），提供 Graph DAG 编排、组件抽象（ChatModel/Tool 等）、流式处理和 Callback AOP 机制 |
+| **compose.Graph** | Eino 的 DAG 编排器，声明式有向无环图，节点可以是 Lambda、ChatModel、ToolsNode 等，边定义数据流向 |
+| **Lambda** | Graph 中的可组合函数单元，四种模式：InvokableLambda（同步）、StreamableLambda（流式输出）、CollectableLambda（流式输入）、TransformableLambda（双向流式） |
+| **StreamReader** | Eino 的流式数据抽象 `schema.StreamReader[T]`，类似 io.Reader 的语义，`Recv()` 读取一帧，`io.EOF` 表示流结束 |
+| **Callback** | Eino 的 AOP 机制，类似中间件的钩子，支持节点生命周期回调（OnStart/OnEnd/OnError/OnEndWithStreamOutput） |
+
+> 更多 Eino 相关概念详见 [10-Eino框架与编排设计.md](10-Eino框架与编排设计.md)
+
 ### 候选方案对比
 
 | 框架 | 语言 | 特点 | CamTalk 适用性 |
@@ -74,6 +95,14 @@ github.com/cloudwego/eino-ext/components/model/openai v0.1.13  # OpenAI 兼容 C
 
 ## 二、AI 服务栈选型
 
+### 关键术语
+
+| 名词 | 解释 |
+|------|------|
+| **多模态 LLM** | 能读文字又能看图片的大语言模型，如 GPT-4o（OpenAI）、Claude Sonnet（Anthropic），给照片+问题能"看懂"照片再回答 |
+| **STT** | Speech-to-Text，语音转文字。流式识别延迟可低于 500ms |
+| **TTS** | Text-to-Speech，文字转语音。支持流式——边生成边读，不必等全部生成完 |
+
 ### STT（语音识别）
 
 | 方案 | 延迟 | 成本 | 特点 |
@@ -106,7 +135,15 @@ LLM 通过 Eino 框架的 `eino-ext/components/model/openai` ChatModel 组件接
 
 ---
 
-## 二、持久化层选型
+## 三、持久化层选型
+
+### 关键术语
+
+| 名词 | 解释 |
+|------|------|
+| **PostgreSQL** | 关系型数据库，支持 JSONB（JSON 二进制格式，可建索引）、窗口函数、CTE 等高级特性 |
+| **Redis** | 内存 KV 数据库，数据放在内存里，读写微秒级。支持 TTL 过期自动清理 |
+| **MVCC** | Multi-Version Concurrency Control，多版本并发控制，PostgreSQL 用此实现高并发读写而不阻塞 |
 
 ### 数据特征分析
 
@@ -220,7 +257,19 @@ Go Gateway (TieredManager)
 
 ---
 
-## 二、前端边缘处理层选型
+## 四、前端边缘处理层选型
+
+### 关键术语
+
+| 名词 | 解释 |
+|------|------|
+| **React 18** | 组件化 UI 框架，Facebook 开源，把页面拆成组件搭积木拼装。18 版本支持并发渲染 |
+| **TypeScript** | 带类型的 JavaScript，在 JS 基础上增加类型声明，编译阶段就能发现类型错误 |
+| **Vite** | 前端构建工具，利用浏览器原生 ES Module，开发时毫秒级热更新（HMR），构建产物小 |
+| **WebSocket** | 浏览器与服务器的双向通道。HTTP 是"一问一答"，WebSocket 像打电话——接通后双方随时互发消息，适合实时对话场景 |
+| **ONNX Runtime Web** | 浏览器端 AI 推理引擎，微软定义的通用模型格式 ONNX 的运行引擎，可在浏览器中用 WASM 加速跑轻量模型（如 VAD、关键帧检测），零延迟、不耗服务器资源 |
+| **VAD** | Voice Activity Detection，语音活动检测，检测"人有没有在说话"。WebRTC 内置了高效的 VAD 算法 |
+| **MediaDevices API** | 浏览器摄像头/麦克风接口，`navigator.mediaDevices.getUserMedia()` 是浏览器音视频采集的唯一标准入口，无需插件 |
 
 ### 总览
 
@@ -270,7 +319,16 @@ vad-web 是"够用且最轻"的平衡点——直接包装浏览器原生 WebRTC
 
 ---
 
-## 四、认证与用户系统选型
+## 五、认证与用户系统选型
+
+### 关键术语
+
+| 名词 | 解释 |
+|------|------|
+| **JWT** | JSON Web Token，无状态 token，服务端不存 session，分布式友好 |
+| **HS256** | HMAC-SHA256，JWT 对称签名算法，用同一密钥签名和验证 |
+| **bcrypt** | 密码哈希算法，自适应 cost factor，抗暴力破解 |
+| **pgx** | Go 生态性能最优的 PostgreSQL 驱动，原生协议实现，内置连接池 pgxpool |
 
 ### 总览
 
diff --git a/docs/07-成本控制.md b/docs/07-成本控制.md
index 5e2213d..fa53f6f 100644
--- a/docs/07-成本控制.md
+++ b/docs/07-成本控制.md
@@ -26,14 +26,7 @@
 | 用户触发 | 高 | 低 | 只在用户提问时拍照 |
 | 本地预筛选 | 中 | 高 | 用轻量模型判断"是否值得问 LLM" |
 
-```typescript
-// 混合策略：定时低频 + 事件高频（sampling.ts）
-const IDLE_INTERVAL = 5000;    // 空闲 5 秒一帧
-const ACTIVE_INTERVAL = 1000;  // 用户说话时 1 秒一帧
-
-// SamplingController 根据 VAD 状态切换采样间隔
-// detail_level 通过 session config 静态配置，不随说话状态动态变化
-```
+**实现细节**：参见 `frontend/src/lib/sampling.ts` 中的 SamplingController，根据 VAD 状态在空闲模式（5s/帧）和活跃模式（1s/帧）之间切换。
 
 ## 策略二：端云协同——把计算推到边缘
 
@@ -55,7 +48,7 @@ const ACTIVE_INTERVAL = 1000;  // 用户说话时 1 秒一帧
   └── 代码/推理 → 更强模型（如 o1）
 ```
 
-> 当前 MVP 阶段使用单一模型（默认 DashScope qwen3-vl-plus），模型分级路由为未来优化方向。通过配置 `ai.llm.model` 可手动切换模型。LLM 通过 Eino 框架的 eino-ext ChatModel 组件接入，支持任何 OpenAI 兼容接口。
+> 当前 MVP 阶段使用单一模型（默认 DashScope qwen3-vl-plus），模型分级路由为未来优化方向。LLM 通过 Eino ChatModel 接入，支持任何 OpenAI 兼容接口。
 
 ## 策略四：缓存与复用（待实现）
 
diff --git a/docs/08-Eino框架与编排设计.md b/docs/08-Eino框架与编排设计.md
new file mode 100644
index 0000000..bcb48a5
--- /dev/null
+++ b/docs/08-Eino框架与编排设计.md
@@ -0,0 +1,527 @@
+# CamTalk Eino 框架与编排设计
+
+> 创建日期：2026-06-19  
+> 状态：已实施  
+> 合并自：`10-Eino重构方案.md` + `11-Eino框架技术文档.md`
+
+## 1. 概述
+
+### 1.1 为什么选择 Eino
+
+[CloudWeGo Eino](https://github.com/cloudwego/eino) 是字节跳动 CloudWeGo 团队开源的 AI 应用开发框架，提供基于图（Graph）的编排能力、组件抽象和流式处理支持。
+
+CamTalk 使用 Eino 替代原有的手写 goroutine 管道，实现 STT → LLM → TTS 的声明式编排。
+
+**技术选型对比：**
+
+| 维度 | 手写 goroutine（旧方案） | Eino Graph（新方案） |
+|------|------------------------|---------------------|
+| 编排方式 | 手动 `go func()` + `sync.WaitGroup` | 声明式 DAG，类型安全 |
+| 流式处理 | 自定义 `chan` 传递 | `StreamReader` + `Pipe`，自动转换 |
+| 错误处理 | 各节点独立处理，不一致 | Graph 级别统一错误传播 |
+| 回调/AOP | 日志散落各处 | `callbacks.Handler` 统一注入 |
+| 配置灵活性 | Pipeline 创建时固定 | 每请求 `Option` 动态注入 |
+| 可测试性 | 需启动 goroutine | `Graph.Invoke()` 直接测试 |
+| 扩展性 | 修改 Pipeline 代码 | 添加节点 + 边，无侵入 |
+| 并发安全 | 手动 `sync` | State 自动加锁 |
+
+**选择 Eino 的核心理由：**
+1. Go 原生，泛型支持，编译时类型检查
+2. 原生流式处理（`StreamReader`），适合 LLM token 级推送
+3. Graph 支持分支、并行、循环，满足当前和未来需求
+4. Callback 机制实现 AOP（日志、指标、消息推送）
+5. eino-ext 提供 OpenAI ChatModel 实现，直接对接 DashScope
+
+### 1.2 旧方案的问题
+
+当前后端 AI 编排层（`internal/orchestrator/pipeline.go`）为手写 goroutine 管道存在以下问题：
+
+1. **编排逻辑硬编码**：STT→LLM→TTS 流程写死，扩展困难
+2. **并发控制粗糙**：手动 goroutine 调度，缺乏结构化流式传递
+3. **无回调/AOP 机制**：日志、指标、追踪散落各处
+4. **配置耦合**：模型名、TTS 参数等硬编码在结构体
+5. **错误处理不一致**：TTS 错误静默吞掉，STT/LLM 错误通过 Sender 发送
+
+### 1.3 核心依赖版本
+
+```go
+github.com/cloudwego/eino v0.9.9
+github.com/cloudwego/eino-ext/components/model/openai v0.1.13
+```
+
+## 2. Eino 核心概念
+
+### 2.1 Lambda
+
+Lambda 是 Graph 中的可组合函数单元，支持四种模式：
+
+| 模式 | 函数签名 | 构造方法 | 说明 |
+|------|---------|---------|------|
+| Invoke | `I → O` | `compose.InvokableLambda()` | 同步调用 |
+| Stream | `I → StreamReader[O]` | `compose.StreamableLambda()` | 流式输出 |
+| Collect | `StreamReader[I] → O` | `compose.CollectableLambda()` | 流式输入 |
+| Transform | `StreamReader[I] → StreamReader[O]` | `compose.TransformableLambda()` | 双向流式 |
+
+**返回类型**：所有 Lambda 构造函数返回 `*compose.Lambda`。
+
+### 2.2 Graph
+
+Graph 是有向无环图（DAG）编排器，支持：
+- **节点**：Lambda、ChatModel、ToolsNode 等
+- **边**：`g.AddEdge(from, to)` 定义数据流向
+- **分支**：`g.AddBranch()` 条件路由
+- **State**：`compose.WithGenLocalState()` 跨节点共享状态
+
+```go
+g := compose.NewGraph[PipelineInput, PipelineOutput]()
+g.AddLambdaNode("stt", sttLambda)
+g.AddChatModelNode("llm", chatModel)
+g.AddEdge(compose.START, "stt")
+g.AddEdge("stt", "llm")
+g.AddEdge("llm", compose.END)
+
+runnable, err := g.Compile(ctx)
+output, err := runnable.Invoke(ctx, input)   // 同步调用
+stream, err := runnable.Stream(ctx, input)    // 流式调用
+```
+
+### 2.3 ChatModel
+
+ChatModel 是 LLM 组件抽象，接口定义：
+
+```go
+type BaseChatModel interface {
+    Generate(ctx, []*schema.Message, ...Option) (*schema.Message, error)
+    Stream(ctx, []*schema.Message, ...Option) (*schema.StreamReader[*schema.Message], error)
+}
+```
+
+CamTalk 使用 `eino-ext/components/model/openai` 实现，通过 `BaseURL` 对接 DashScope：
+
+```go
+chatModel, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
+    APIKey:  cfg.AI.LLM.APIKey,
+    Model:   cfg.AI.LLM.Model,
+    BaseURL: cfg.AI.LLM.Endpoint, // "https://dashscope.aliyuncs.com/compatible-mode/v1"
+})
+```
+
+### 2.4 StreamReader
+
+`schema.StreamReader[T]` 是 Eino 的流式数据抽象：
+- `sr.Recv()` 读取一帧，`io.EOF` 表示流结束
+- `schema.Pipe[T](bufSize)` 创建 `StreamReader` + `StreamWriter` 对
+- 框架自动处理 `T ↔ StreamReader[T]` 的转换（装箱/concat）
+
+### 2.5 Callback
+
+Callback 是 Eino 的 AOP 机制，支持节点生命周期钩子：
+
+```go
+type Handler interface {
+    OnStart(ctx, *RunInfo, CallbackInput) context.Context
+    OnEnd(ctx, *RunInfo, CallbackOutput) context.Context
+    OnError(ctx, *RunInfo, error) context.Context
+    OnStartWithStreamInput(ctx, *RunInfo, *StreamReader[CallbackInput]) context.Context
+    OnEndWithStreamOutput(ctx, *RunInfo, *StreamReader[CallbackOutput]) context.Context
+}
+```
+
+CamTalk 使用 `utils/callbacks.NewHandlerHelper()` 构建 typed handler：
+- `ModelCallbackHandler.OnEndWithStreamOutput`：逐 token 推送 `llm_chunk`
+
+### 2.6 State
+
+Graph 全局状态，通过 `WithGenLocalState` 注册：
+
+```go
+type PipelineState struct {
+    FullResponse    strings.Builder
+    TranscribedText string
+    TokenUsage      *TokenUsage
+}
+
+g := compose.NewGraph[I, O](compose.WithGenLocalState(func(ctx context.Context) *PipelineState {
+    return &PipelineState{}
+}))
+```
+
+节点通过 `compose.ProcessState` 读写 State。
+
+## 3. CamTalk Graph 设计
+
+### 3.1 拓扑结构
+
+```
+START → STT → History → ChatModel → Splitter → TTS → Done → END
+```
+
+| 节点 | 类型 | 输入 → 输出 | 职责 |
+|------|------|------------|------|
+| STT | InvokableLambda | `PipelineInput → STTOutput` | 语音识别，写入 State |
+| History | InvokableLambda | `STTOutput → []*schema.Message` | 组装提示词和历史 |
+| ChatModel | ChatModel（原生） | `[]*schema.Message → StreamReader[*Message]` | LLM 流式推理 |
+| Splitter | TransformableLambda | `StreamReader[string] → StreamReader[[]string]` | 句子切分 |
+| TTS | InvokableLambda | `[]string → struct{}` | 语音合成，推送音频 |
+| Done | InvokableLambda | `struct{} → PipelineOutput` | 发送 llm_done |
+
+### 3.2 数据类型定义
+
+```go
+// Graph 统一输入
+type PipelineInput struct {
+    AudioData    []byte // base64 解码后的音频（可选）
+    ImageData    []byte // base64 解码后的图像（可选）
+    Text         string // 直接文本输入（可选，跳过 STT）
+    SessionID    string
+    RequestID    string
+    Language     string // zh / en
+    Scenario     string // free_chat, interviewer, etc.
+}
+
+// Graph 统一输出
+type PipelineOutput struct {
+    TranscribedText string // STT 结果
+    FullResponse    string // LLM 完整回复
+}
+
+// Pipeline State（跨节点共享）
+type PipelineState struct {
+    FullResponse    strings.Builder
+    TranscribedText string
+    TokenUsage      *TokenUsage
+}
+```
+
+### 3.3 流式模式
+
+Graph 使用 **Stream 模式**调用：
+- 内部所有节点以 Transform 模式运行
+- ChatModel 的 `Stream()` 方法实现真正的 token 级流式
+- 适配器消费 `StreamReader[PipelineOutput]` 触发整条链路
+
+### 3.4 消息推送机制
+
+| 消息 | 推送方式 | 时机 |
+|------|---------|------|
+| `stt_result` | Lambda 内部直接调用 Sender | STT 完成后 |
+| `llm_chunk` | Callback `OnEndWithStreamOutput` | ChatModel 逐 token |
+| `tts_audio` | Lambda 内部直接调用 Sender | TTS 逐句合成 |
+| `llm_done` | Lambda 内部直接调用 Sender | Done 节点执行时 |
+
+**Context 注入**：Sender、RequestID、SessionID、PipelineState 通过 `context.WithValue` 传递。
+
+### 3.5 多模态支持
+
+History 节点将图片构建为 `schema.Message.UserInputMultiContent`：
+
+```go
+systemMsg.UserInputMultiContent = []schema.MessageInputPart{
+    {
+        Type: schema.ChatMessagePartTypeImageURL,
+        Image: &schema.MessageInputImage{
+            MessagePartCommon: schema.MessagePartCommon{
+                Base64Data: &base64Str,
+                MIMEType:   "image/jpeg",
+            },
+            Detail: schema.ImageURLDetailAuto,
+        },
+    },
+}
+```
+
+## 4. 实现要点
+
+### 4.1 目录结构
+
+```
+backend/internal/eino/
+├── types.go           # PipelineInput/Output、STTOutput、TokenUsage
+├── state.go           # PipelineState（跨节点状态）
+├── callback.go        # Callback handler（LLM token 推送）
+├── graph.go           # Graph 构建与编译
+├── adapter.go         # EinoOrchestrator（Orchestrator 接口适配器）
+├── nodes_stt.go       # STT Lambda
+├── nodes_history.go   # 历史组装 Lambda
+├── nodes_splitter.go  # 句子分割 Transform Lambda
+├── nodes_tts.go       # TTS Lambda
+├── nodes_done.go      # Done Lambda
+└── graph_test.go      # 单元测试
+```
+
+### 4.2 关键节点实现
+
+#### STT Lambda（可选跳过）
+
+```go
+func sttLambda(sttSvc stt.Service) func(ctx context.Context, input PipelineInput) (STTOutput, error) {
+    return func(ctx context.Context, input PipelineInput) (STTOutput, error) {
+        // 文本模式：跳过 STT
+        if input.Text != "" {
+            return STTOutput{Text: input.Text, Language: input.Language}, nil
+        }
+        
+        // 调用 STT 服务
+        result, err := sttSvc.Recognize(ctx, input.AudioData, stt.Options{
+            Language: input.Language,
+        })
+        if err != nil {
+            return STTOutput{}, fmt.Errorf("STT error: %w", err)
+        }
+        
+        return STTOutput{Text: result.Text, Language: result.Language}, nil
+    }
+}
+```
+
+#### Splitter Transform Lambda（句子切分）
+
+```go
+func splitterLambda() func(ctx, *schema.StreamReader[*schema.Message]) (*schema.StreamReader[[]string], error) {
+    return func(ctx context.Context, stream *schema.StreamReader[*schema.Message]) (*schema.StreamReader[[]string], error) {
+        sr, sw := schema.Pipe[[]string](8)
+        
+        go func() {
+            defer sw.Close()
+            var buffer []rune
+            
+            for {
+                chunk, err := stream.Recv()
+                if err != nil {
+                    if err == io.EOF {
+                        if len(buffer) > 0 {
+                            sw.Send([]string{string(buffer)}, nil)
+                        }
+                        return
+                    }
+                    sw.Send(nil, err)
+                    return
+                }
+                
+                for _, r := range chunk.Content {
+                    buffer = append(buffer, r)
+                    if isSentenceDelimiter(r) {
+                        sw.Send([]string{string(buffer)}, nil)
+                        buffer = buffer[:0]
+                    }
+                }
+            }
+        }()
+        
+        return sr, nil
+    }
+}
+```
+
+#### TTS Lambda（并行合成）
+
+```go
+func ttsLambda(ttsSvc tts.Service, sender orchestrator.Sender) func(ctx, []string) (struct{}, error) {
+    return func(ctx context.Context, sentences []string) (struct{}, error) {
+        for _, sentence := range sentences {
+            if sentence == "" {
+                continue
+            }
+            
+            // 调用 TTS 服务
+            audioData, err := ttsSvc.Synthesize(ctx, sentence, tts.Options{})
+            if err != nil {
+                // TTS 失败不中断流程，仅记录日志
+                log.Warn("TTS synthesis failed", zap.Error(err))
+                continue
+            }
+            
+            // 推送音频到客户端
+            sender.SendTTSAudio(orchestrator.TTSAudioPayload{
+                Audio:  audioData,
+                Format: "mp3",
+            })
+        }
+        
+        return struct{}{}, nil
+    }
+}
+```
+
+### 4.3 Callback 集成
+
+```go
+// ModelCallbackHandler 用于 LLM token 推送
+type ModelCallbackHandler struct {
+    sender orchestrator.Sender
+}
+
+func (h *ModelCallbackHandler) OnEndWithStreamOutput(
+    ctx context.Context,
+    info *callbacks.RunInfo,
+    output *schema.StreamReader[*schema.Message],
+) context.Context {
+    // 逐 token 推送到客户端
+    for {
+        msg, err := output.Recv()
+        if err == io.EOF {
+            break
+        }
+        if err != nil {
+            return ctx
+        }
+        
+        h.sender.SendLLMChunk(orchestrator.LLMChunkPayload{
+            Content: msg.Content,
+        })
+    }
+    
+    return ctx
+}
+```
+
+### 4.4 按请求动态配置
+
+```go
+// 运行时 Option：每请求可变
+func WithModelName(name string) compose.Option {
+    return compose.WithChatModelOption(model.WithModel(name))
+}
+
+func WithTemperature(temp float32) compose.Option {
+    return compose.WithChatModelOption(model.WithTemperature(temp))
+}
+
+// WebSocket Handler 中的调用
+func (c *Client) handleQuery(req QueryRequest) {
+    opts := []compose.Option{}
+    
+    if req.Model != "" {
+        opts = append(opts, WithModelName(req.Model))
+    }
+    
+    output, err := c.pipeline.Stream(ctx, PipelineInput{...}, opts...)
+}
+```
+
+### 4.5 注意事项
+
+#### 值类型 vs 指针类型
+Graph 泛型参数必须使用值类型（`PipelineInput`/`PipelineOutput`），所有 Lambda 的输入输出也使用值类型。框架在 Transform 模式下会自动处理 `T` 和 `StreamReader[T]` 的转换。
+
+#### Callback 运行时传入
+Callback 通过 `Stream()` 的 option 传入，不在 `Compile()` 时注册：
+
+```go
+streamReader, err := runnable.Stream(ctx, input, compose.WithCallbacks(handler))
+```
+
+#### eino-ext 与 DashScope 兼容性
+eino-ext OpenAI ChatModel 通过 `BaseURL` 对接 DashScope 兼容接口。需注意：
+- 多模态图片使用 `Base64Data` + `MIMEType` 格式
+- `Timeout` 控制单次请求超时
+- 流式输出通过 `Stream()` 方法获取 `StreamReader[*schema.Message]`
+
+#### 框架自动类型转换
+Eino 框架在编排场景中自动处理以下转换：
+- **T → StreamReader[T]**：将完整值装箱为单帧流（非流式 → 假流式）
+- **StreamReader[T] → T**：将流 concat 为完整值（流式 → 非流式）
+
+这使得不同流式模式的节点可以无缝连接。
+
+## 5. 测试策略
+
+### 5.1 单元测试
+
+```go
+func TestPipelineGraph_WithTextInput(t *testing.T) {
+    mockLLM := &mockChatModel{responses: []string{"你好！"}}
+    mockSender := &mockSender{}
+    
+    graph, err := NewPipelineGraph(ctx, &GraphOption{
+        ChatModel: mockLLM,
+        Sender:    mockSender,
+    })
+    require.NoError(t, err)
+    
+    output, err := graph.Invoke(ctx, PipelineInput{
+        Text:      "你好",
+        SessionID: "test-session",
+    })
+    require.NoError(t, err)
+    assert.Equal(t, "你好！", output.FullResponse)
+    assert.True(t, mockSender.LLMDoneSent)
+}
+
+func TestPipelineGraph_WithAudioInput(t *testing.T) {
+    mockSTT := &mockSTT{text: "你好"}
+    mockLLM := &mockChatModel{responses: []string{"你好！"}}
+    mockTTS := &mockTTS{audio: []byte("fake-audio")}
+    mockSender := &mockSender{}
+    
+    graph, _ := NewPipelineGraph(ctx, &GraphOption{
+        ChatModel:  mockLLM,
+        STTService: mockSTT,
+        TTSService: mockTTS,
+        Sender:     mockSender,
+    })
+    
+    output, err := graph.Invoke(ctx, PipelineInput{
+        AudioData: []byte("fake-audio-data"),
+        SessionID: "test-session",
+    })
+    require.NoError(t, err)
+    assert.True(t, mockSender.TTSAudioSent)
+}
+```
+
+### 5.2 集成测试
+
+- 启动真实 OpenAI API 调用（使用测试 key）
+- 验证 WebSocket 消息序列：`stt_result` → `llm_chunk` × N → `llm_done` → `tts_audio` × N
+- 验证 interrupt 取消功能
+- 验证多并发请求隔离
+
+## 6. 未来扩展路径
+
+基于 Eino Graph 的重构完成后，可无缝扩展：
+
+1. **ReAct Agent**：Graph 添加 Branch 节点，实现 LLM → Tool → LLM 循环
+2. **多模态理解**：添加视觉分析 Lambda 节点（图像描述 → 上下文注入）
+3. **Model Router**：Graph 前置分支节点，按场景/成本路由不同 LLM
+4. **Rate Limiter**：通过 Callback 的 OnStart 实现令牌桶
+5. **Checkpoint/Resume**：利用 Eino 的 CheckpointStore 实现断点续传
+6. **Multi-Agent**：利用 ADK 的 Supervisor/SequentialAgent 编排复杂对话流程
+
+## 附录：关键 Eino API 参考
+
+```go
+// 构建 Graph
+g := compose.NewGraph[I, O](opts...)
+g.AddChatModelNode(key, chatModel)
+g.AddLambdaNode(key, lambda, opts...)
+g.AddEdge(from, to)
+g.AddBranch(from, branchFunc, mapping)
+
+// 编译
+runnable, err := g.Compile(ctx, opts...)
+
+// 执行四种模式
+output, err := runnable.Invoke(ctx, input, opts...)
+stream, err := runnable.Stream(ctx, input, opts...)
+output, err := runnable.Collect(ctx, inputStream, opts...)
+stream, err := runnable.Transform(ctx, inputStream, opts...)
+
+// Lambda 四种构造器
+lambda := compose.InvokableLambda(fn)      // I → O
+lambda := compose.StreamableLambda(fn)     // I → StreamReader[O]
+lambda := compose.CollectableLambda(fn)    // StreamReader[I] → O
+lambda := compose.TransformableLambda(fn)  // StreamReader[I] → StreamReader[O]
+
+// Stream 操作
+sr, sw := schema.Pipe[T](bufSize)
+sw.Send(chunk, err)
+chunk, err := sr.Recv()
+sw.Close()
+
+// Option
+compose.WithCallbacks(handler)
+compose.WithCallbacks(handler).DesignateNode("node_key")
+compose.WithChatModelOption(model.WithTemperature(0.7))
+compose.WithGenLocalState(genFunc)
+```
diff --git a/docs/08-功能创意.md b/docs/08-功能创意.md
deleted file mode 100644
index 5cf4036..0000000
--- a/docs/08-功能创意.md
+++ /dev/null
@@ -1,5 +0,0 @@
-1.视频录制
-2.对话翻译
-3.对话总结
-4.手动对话功能
-5.视频框大小可调整，可最小化然后拖动
\ No newline at end of file
diff --git a/docs/09-情景切换.md b/docs/09-情景切换.md
new file mode 100644
index 0000000..259504e
--- /dev/null
+++ b/docs/09-情景切换.md
@@ -0,0 +1,352 @@
+# 情景切换功能
+
+**状态**: ✅ 已完成
+
+---
+
+## 功能概述
+
+情景切换功能允许用户选择不同的对话场景，AI 会根据选择的情景扮演不同的角色：
+
+| 情景 | AI 角色 | 主要功能 |
+|------|---------|---------|
+| 🎯 模拟面试官 | 资深面试官 | 提出面试问题，评估候选人能力，给出反馈 |
+| 📚 英语老师 | 英语外教 | 全英文对话，纠正语法错误，引导深入交流 |
+| ⚔️ 辩论对手 | 辩论选手 | 站在反方立场，用逻辑和证据反驳观点 |
+| 🌐 同声翻译 | 翻译员 | 实时中英互译，口语化翻译，无额外解释 |
+| 💬 自由对话 | 视觉助手 | 通用视觉对话助手（默认） |
+
+### 核心特性
+
+1. **情景首句引导**：切换情景后，AI 自动发送第一句话引导用户进入角色
+2. **情景提示卡片**：对话顶部显示当前情景模式的蓝色提示卡片
+3. **增强 System Prompt**：每个情景有详细的角色定位、交互规则和约束
+4. **多语言支持**：完整支持中文、英文、日文界面
+
+---
+
+## 技术实现
+
+### 后端实现
+
+#### 1. 情景 Prompt 定义
+
+**文件**: `backend/internal/ai/llm/scenarios.go`
+
+- 扩展 `scenarioPrompt` 结构体，新增首句引导字段（GreetingZH/EN/JA）
+- 增强所有情景的 System Prompt（添加角色定位、交互规则、约束）
+- 新增函数 `GetScenarioGreeting(scenarioID, language string) string`
+
+**示例 Prompt**（模拟面试官）：
+
+```go
+"interviewer": {
+    ZH: `你是一位资深面试官。你通过摄像头观察面试者...
+
+【角色定位】
+- 你是面试官，不是助手或顾问
+- 你的目标是评估候选人的能力
+- 保持专业、客观、礼貌
+
+【交互规则】
+1. 每次只问一个问题，等用户回答后再追问
+2. 问题要有层次：自我介绍 → 专业问题 → 情景题
+3. 对用户的回答给出简短点评，然后追问
+...`,
+    GreetingZH: "你好！我是今天的面试官。让我们先从自我介绍开始...",
+}
+```
+
+#### 2. 首句引导推送
+
+**文件**: `backend/internal/ws/handler.go`
+
+在处理 `config` 消息时，如果切换到非自由对话情景，自动返回首句引导：
+
+```go
+case "config":
+    // ... 更新配置 ...
+    
+    // 如果切换了情景（非自由对话），返回首句引导
+    if scenarioID != "" && scenarioID != "free_chat" {
+        greeting := llm.GetScenarioGreeting(scenarioID, sess.Config.Language)
+        if greeting != "" {
+            // 发送 llm_chunk 和 llm_done 消息
+            // 追加到历史记录
+        }
+    }
+```
+
+#### 3. State 初始化
+
+**文件**: `backend/internal/eino/adapter.go`
+
+从 `PipelineInput` 复制元数据到 `PipelineState`，确保情景配置正确传递到所有节点：
+
+```go
+state := genLocalState(ctx)
+state.SessionID = input.SessionID
+state.RequestID = input.RequestID
+state.ImageData = input.ImageData
+state.Scenario = input.Scenario      // 关键：复制情景配置
+state.Language = input.Language
+state.DetailLevel = sess.Config.DetailLevel
+state.TTSEnabled = input.TTSEnabled
+ctx = WithPipelineState(ctx, state)
+```
+
+---
+
+### 前端实现
+
+#### 1. 情景提示卡片
+
+**文件**: `frontend/src/components/ChatPanel/index.tsx`
+
+在对话列表顶部（非空状态 + 非自由对话模式）添加情景提示卡片：
+
+```tsx
+{messages.length > 0 && !isFreeChat && (
+  <div className="chat-panel__scenario-hint">
+    <div className="scenario-hint-card">
+      <span className="scenario-hint-card__icon">
+        {scenarios.find(s => s.id === activeScenario)?.icon}
+      </span>
+      <div className="scenario-hint-card__text">
+        <strong>{t(scenarios.find(s => s.id === activeScenario)?.nameKey || "")}</strong>
+        <p>{t(`scenario.${activeScenario}.hint`)}</p>
+      </div>
+    </div>
+  </div>
+)}
+```
+
+**显示效果**：
+- 蓝色渐变背景（135deg 从蓝到紫）
+- 左侧大图标 + 右侧标题和说明
+- 最大宽度 520px，响应式布局
+- 柔和阴影和半透明边框
+
+#### 2. WebSocket 消息发送
+
+**文件**: `frontend/src/hooks/useVisionSession.ts`
+
+发送 config 消息时包含 `scenario` 字段：
+
+```typescript
+send({
+  type: "config",
+  payload: {
+    tts_enabled: config.ttsEnabled,
+    detail_level: config.detailLevel,
+    language: config.language,
+    scenario: config.scenario,  // 情景配置
+  },
+});
+```
+
+#### 3. 样式实现
+
+**文件**: `frontend/src/App.css`
+
+情景提示卡片样式：
+
+```css
+.scenario-hint-card {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 12px 16px;
+  border-radius: var(--radius-sm);
+  background: linear-gradient(135deg, rgba(59, 130, 246, 0.08) 0%, rgba(99, 102, 241, 0.08) 100%);
+  border: 1px solid rgba(59, 130, 246, 0.2);
+  box-shadow: 0 2px 8px rgba(59, 130, 246, 0.06);
+}
+```
+
+#### 4. 多语言翻译
+
+**文件**: `frontend/src/lib/i18n/{zh-CN,en-US,ja-JP}.ts`
+
+新增翻译 key：
+
+```typescript
+"scenario.interviewer.hint": "AI 会扮演面试官，逐步提出专业问题并点评你的回答",
+"scenario.englishTeacher.hint": "AI 会用英语对话，纠正语法错误并引导深入交流",
+"scenario.debate.hint": "AI 会站在反方立场，用逻辑和证据反驳你的观点",
+"scenario.interpreter.hint": "AI 会实时翻译你的话（中英互译），无解释评论",
+```
+
+---
+
+## 数据流
+
+### WebSocket 协议
+
+**客户端 → 服务端**（config 消息）：
+
+```json
+{
+  "type": "config",
+  "payload": {
+    "tts_enabled": true,
+    "detail_level": "low",
+    "language": "zh-CN",
+    "scenario": "interviewer"
+  }
+}
+```
+
+**服务端 → 客户端**（首句引导）：
+
+```json
+// llm_chunk
+{
+  "type": "llm_chunk",
+  "request_id": "scenario_greeting",
+  "delta": "你好！我是今天的面试官...",
+  "role": "assistant"
+}
+
+// llm_done
+{
+  "type": "llm_done",
+  "request_id": "scenario_greeting",
+  "full_text": "你好！我是今天的面试官...",
+  "tokens_used": {"prompt": 0, "completion": 0, "total": 0}
+}
+```
+
+### System Prompt 构建流程
+
+```
+sess.Config.Scenario = "interviewer"
+  ↓
+PipelineInput.Scenario = "interviewer"
+  ↓
+PipelineState.Scenario = "interviewer" (adapter.go 复制)
+  ↓
+nodes_history.go 读取 state.Scenario
+  ↓
+scenarioPrompt := llm.GetScenarioPrompt("interviewer", "zh-CN")
+  ↓
+systemPrompt := llm.BuildSystemPrompt(language, detailLevel, scenarioPrompt)
+  ↓
+messages[0] = {Role: "system", Content: systemPrompt}
+  ↓
+ChatModel 接收到情景 Prompt
+  ↓
+LLM 按情景角色生成回复
+```
+
+---
+
+## 使用指南
+
+### 快速验证
+
+1. **打开浏览器** → http://localhost:5173
+2. **登录系统**
+3. **切换情景** → 右侧配置面板 → 对话情景 → 模拟面试官
+4. **观察现象**：
+   - ✨ AI 立即说："你好！我是今天的面试官。让我们先从自我介绍开始..."
+   - ✨ 对话框顶部显示蓝色提示卡片
+5. **验证效果** → 发送："你是谁？"
+   - ✅ **正确回复**："我是今天的面试官..."
+   - ❌ **错误回复**："我是通义千问..."
+
+### 功能测试清单
+
+| 测试项 | 操作步骤 | 预期结果 |
+|--------|---------|---------|
+| **首句引导** | 切换到"模拟面试官" | AI 自动说："你好！我是今天的面试官..." |
+| **情景生效** | 问 "你是谁？" | AI 回答："我是今天的面试官..." |
+| **提示卡片** | 发送一条消息后查看顶部 | 显示蓝色卡片："🎯 模拟面试官 \| AI 会扮演面试官..." |
+| **语言联动** | 切换到"英语老师" | 语言自动切换到 en-US，AI 用英语回复 |
+| **持久化** | 切换情景后刷新页面 | 情景配置保持，首句仍在历史中 |
+| **多情景** | 依次测试所有情景 | 每个情景 AI 回复风格明显不同 |
+
+---
+
+## 故障排查
+
+### 如果情景不生效
+
+1. **检查后端日志**：
+   ```bash
+   grep "config updated" /tmp/camtalk_server.log | tail -5
+   grep "历史组装完成" /tmp/camtalk_server.log | tail -5
+   ```
+   
+   - 如果 `scenario=` 是空的，说明前端未发送或后端未接收
+   - 如果 `scenario=interviewer` 正确，但 AI 回复仍是通用的，可能是 LLM 模型问题
+
+2. **检查前端 WebSocket 消息**（浏览器 DevTools → Network → WS）：
+   ```json
+   {
+     "type": "config",
+     "payload": {
+       "scenario": "interviewer"  // 确认存在
+     }
+   }
+   ```
+
+3. **检查会话配置是否保存**：
+   - 切换情景后，LocalStorage 中应该有 `camtalk_config`
+   - 内容应包含 `"scenario": "interviewer"`
+
+4. **清除缓存重试**：
+   ```bash
+   # 浏览器：清除 LocalStorage
+   # 后端：重启服务
+   # 前端：刷新页面
+   ```
+
+---
+
+## 后续优化建议
+
+### P2（强烈推荐）
+
+1. **情景切换时创建新会话**
+   - 避免历史对话干扰新情景
+   - 弹窗确认："切换情景会创建新会话，当前对话将保存。是否继续？"
+   - 实现难度：⭐⭐
+   - 用户价值：⭐⭐⭐⭐
+
+2. **进一步增强 System Prompt**
+   - 增加示例对话（Few-shot Prompting）
+   - 增加"禁止事项"列表
+   - 实现难度：⭐
+   - 效果提升：⭐⭐⭐
+
+### P3（可选）
+
+1. **情景专属 UI 主题色**
+   - 面试官 → 深蓝色
+   - 英语老师 → 绿色
+   - 辩论 → 红色
+   - 翻译 → 紫色
+
+2. **切换动画与音效**
+   - 切换时播放短音效
+   - 聊天面板淡出淡入动画
+
+---
+
+## 修改文件清单
+
+### 后端（3 个文件）
+
+- `backend/internal/eino/adapter.go` — 修复 State 初始化
+- `backend/internal/ws/handler.go` — 添加首句引导
+- `backend/internal/ai/llm/scenarios.go` — 增强 Prompt + 首句
+
+### 前端（5 个文件）
+
+- `frontend/src/hooks/useVisionSession.ts` — 修复 scenario 发送
+- `frontend/src/components/ChatPanel/index.tsx` — 添加提示卡片
+- `frontend/src/App.css` — 卡片样式
+- `frontend/src/lib/i18n/zh-CN.ts` — 中文翻译
+- `frontend/src/lib/i18n/en-US.ts` — 英文翻译
+- `frontend/src/lib/i18n/ja-JP.ts` — 日文翻译
diff --git a/docs/09-技术名词解释.md b/docs/09-技术名词解释.md
deleted file mode 100644
index 97732c7..0000000
--- a/docs/09-技术名词解释.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# 技术名词解释
-
-对架构文档中技术选型表里出现的所有关键名词的简明解释。
-
----
-
-## 前端相关
-
-| 名词 | 一句话 | 展开 |
-|------|--------|------|
-| **React 18** | 组件化 UI 框架 | Facebook 开源，把页面拆成组件搭积木拼装。18 版本支持并发渲染。 |
-| **TypeScript** | 带类型的 JavaScript | 在 JS 基础上增加类型声明，编译阶段就能发现类型错误。 |
-| **Vite** | 前端构建工具 | 利用浏览器原生 ES Module，开发时毫秒级热更新（HMR），构建产物小。 |
-| **WebSocket** | 浏览器与服务器的双向通道 | HTTP 是"一问一答"，WebSocket 像打电话——接通后双方随时互发消息，适合实时对话场景。 |
-| **ONNX Runtime Web** | 浏览器端 AI 推理引擎 | 微软定义的通用模型格式 ONNX 的运行引擎，可在浏览器中用 WASM 加速跑轻量模型（如 VAD、关键帧检测），零延迟、不耗服务器资源。 |
-| **VAD** | 语音活动检测 | Voice Activity Detection，检测"人有没有在说话"。WebRTC 内置了高效的 VAD 算法，本项目用 @ricky0123/vad-web 包装。 |
-| **MediaDevices API** | 浏览器摄像头/麦克风接口 | `navigator.mediaDevices.getUserMedia()` 是浏览器音视频采集的唯一标准入口，无需插件。 |
-
-## 后端相关
-
-| 名词 | 一句话 | 展开 |
-|------|--------|------|
-| **Go (Golang)** | 高并发后端语言 | Google 开发，杀手锏是 goroutine——极轻量协程，一个程序可轻松开几万个，每个只占几 KB 内存，适合管理大量 WebSocket 长连接。 |
-| **gorilla/websocket** | Go WebSocket 库 | Go 标准库无内置 WebSocket 支持，此库是社区最成熟的选择，处理了协议握手、帧解析等底层细节。 |
-| **Redis** | 内存 KV 数据库 | 数据放在内存里，读写微秒级。本项目用于会话状态和对话上下文缓存，支持 TTL 过期自动清理。多 Gateway 实例通过 Redis 共享状态。 |
-| **Viper** | Go 配置管理 | 读取 JSON/YAML/TOML 配置，支持环境变量覆盖，方便开发/测试/生产环境用不同配置。 |
-| **Zap** | Go 结构化日志 | Uber 开源，输出 JSON 格式日志，方便工具搜索分析，性能远超标准库 log。 |
-
-## AI 服务相关
-
-| 名词 | 一句话 | 展开 |
-|------|--------|------|
-| **多模态 LLM** | 能读文字又能看图片的大语言模型 | GPT-4o（OpenAI）/ Claude Sonnet（Anthropic），给照片+问题能"看懂"照片再回答。 |
-| **STT** | 语音转文字 | Speech-to-Text。Deepgram 流式识别延迟 <500ms。备选 FunASR（阿里开源，可自部署）。 |
-| **TTS** | 文字转语音 | Text-to-Speech。OpenAI TTS 音质接近真人。Edge TTS 免费。支持流式——边生成边读，不必等全部生成完。 |
-| **GPT-4o-mini** | 轻量分类模型 | 又快又便宜的小模型，用于模型路由——先用小模型判断问题复杂度，简单问题走小模型省 API 费用。 |
-
-## AI 编排框架相关
-
-| 名词 | 一句话 | 展开 |
-|------|--------|------|
-| **Eino** | 字节跳动开源的 Go AI 应用开发框架 | CloudWeGo Eino，提供 Graph DAG 编排、组件抽象（ChatModel/Tool 等）、流式处理（StreamReader）和 Callback AOP 机制。CamTalk 用它替代手写 goroutine 管道。 |
-| **compose.Graph** | Eino 的 DAG 编排器 | 声明式有向无环图，节点可以是 Lambda、ChatModel、ToolsNode 等，边定义数据流向。支持分支（AddBranch）、并行和循环。 |
-| **Lambda** | Graph 中的可组合函数单元 | 四种模式：InvokableLambda（同步）、StreamableLambda（流式输出）、CollectableLambda（流式输入）、TransformableLambda（双向流式）。 |
-| **StreamReader** | Eino 的流式数据抽象 | `schema.StreamReader[T]`，类似 io.Reader 的语义，`Recv()` 读取一帧，`io.EOF` 表示流结束。`schema.Pipe[T]()` 创建 StreamReader + StreamWriter 对。 |
-| **Callback** | Eino 的 AOP 机制 | 类似中间件的钩子，支持节点生命周期回调（OnStart/OnEnd/OnError/OnEndWithStreamOutput）。CamTalk 用它实现 LLM token 实时推送到客户端。 |
-| **ChatModel** | Eino 的 LLM 组件抽象 | 统一接口 `Generate()` 和 `Stream()`，eino-ext 提供 OpenAI 兼容实现，通过 BaseURL 可对接 DashScope 等兼容接口。 |
-| **eino-ext** | Eino 的组件扩展库 | 提供具体组件实现：OpenAI ChatModel、各种 Tool Backend 等。CamTalk 使用 `eino-ext/components/model/openai`。 |
-| **PipelineState** | Graph 级别的共享状态 | 通过 `compose.WithGenLocalState` 注册，每请求独立实例，线程安全（sync.Mutex），跨节点共享数据（如 LLM 完整回复、Token 用量）。 |
diff --git a/docs/10-Eino重构方案.md b/docs/10-Eino重构方案.md
deleted file mode 100644
index a00b15b..0000000
--- a/docs/10-Eino重构方案.md
+++ /dev/null
@@ -1,810 +0,0 @@
-# CamTalk 后端 AI 编排层 Eino 重构方案
-
-> 创建日期：2026-06-19
-> 状态：已实施（实施记录见 [12-Eino重构实施记录](12-Eino重构实施记录.md)）
-
-## 1. 背景与目标
-
-### 1.1 现状问题
-
-当前后端 AI 编排层（`internal/orchestrator/pipeline.go`）为手写 goroutine 管道：
-
-```
-STT → LLM(Stream) ──→ Splitter → TTS(Stream) → Sender
-                     └→ Sender(LLMChunk)
-```
-
-存在以下问题：
-
-1. **编排逻辑硬编码**：STT→LLM→TTS 流程写死在 `ProcessQuery()` 中，扩展新流程（如视觉分析链路、多轮工具调用）需要重写 goroutine 调度
-2. **并发控制粗糙**：手动 `go func()` + `sync.WaitGroup`，缺乏结构化的流式数据传递
-3. **无回调/AOP 机制**：日志、指标、追踪散落在各处，无法统一注入
-4. **配置耦合**：模型名、TTS 参数等硬编码在 Pipeline 结构体，无法按请求动态切换
-5. **错误处理不一致**：TTS 错误被静默吞掉，STT/LLM 错误通过 Sender 发送，缺乏统一模式
-
-### 1.2 重构目标
-
-| 目标 | 说明 |
-|------|------|
-| 用 Eino Graph 替换手写 Pipeline | 声明式编排，类型安全，可组合 |
-| 流式处理原生支持 | 利用 Eino 的 Transform/Stream 模式，替代手动 goroutine |
-| 统一回调机制 | 通过 Eino Callback 实现日志、指标、追踪的 AOP |
-| 按请求动态配置 | 利用 Eino Option 机制，支持每请求切换模型/参数 |
-| 保持 API 兼容 | WebSocket 协议、REST API、Session 管理不变 |
-| 渐进式迁移 | 可分阶段实施，新旧编排器并存 |
-
-## 2. Eino 编排模型选择
-
-### 2.1 为什么选 Graph 而非 Chain 或 Workflow
-
-| 编排模式 | 适用场景 | CamTalk 适用性 |
-|----------|----------|----------------|
-| **Chain** | 线性流水线 | ❌ LLM 和 TTS 需要并行执行，非纯线性 |
-| **Workflow** | DAG + 字段映射 | ⚠️ 不支持循环，未来 ReAct Agent 需要循环 |
-| **Graph** | 任意有向图，支持分支/并行/循环 | ✅ 完美匹配，支持当前并行需求和未来扩展 |
-
-**选择 Graph**，理由：
-- LLM Stream 输出需要同时分发给 TTS 和客户端（多下游分支）
-- 未来需要支持 ReAct Agent 循环（Graph + Branch）
-- 支持 Pregel 执行引擎，兼容未来有状态节点
-
-### 2.2 Graph 拓扑设计
-
-```
-        ┌─────────────────────────────────────────┐
-        │            CamTalk Pipeline Graph        │
-        │                                          │
-  START │                                          │ END
-    │   │                                          ▲
-    ▼   │                                          │
- ┌──────┴──────┐                                   │
- │  STT Node   │  (Lambda: audio → text)           │
- │  (可选跳过)  │                                   │
- └──────┬──────┘                                   │
-        │ text                                     │
-        ▼                                          │
- ┌──────────────┐                                  │
- │ History Node │  (Lambda: 组装对话历史)           │
- └──────┬───────┘                                  │
-        │ []*schema.Message                        │
-        ▼                                          │
- ┌──────────────┐      ┌────────────────┐          │
- │ LLM Node     │─────→│ Sentence Split │───┐      │
- │ (ChatModel)  │stream│ Node (Lambda)  │   │      │
- └──────┬───────┘      └────────────────┘   │      │
-        │ stream                              │      │
-        ▼                                    ▼      │
- ┌──────────────┐                   ┌──────────────┐│
- │ Chunk Sender │                   │  TTS Node    ││
- │ Node (Lambda)│                   │  (Lambda)    ││
- └──────────────┘                   └──────┬───────┘│
-                                           │        │
-                                           ▼        │
-                                  ┌──────────────┐  │
-                                  │Audio Sender  │──┘
-                                  │Node (Lambda) │
-                                  └──────────────┘
-```
-
-**关键设计决策：**
-
-- STT 作为起始 Lambda 节点（非 Eino 原生组件，需封装）
-- LLM 使用 Eino 原生 ChatModel 组件（`eino-ext` 的 OpenAI 实现）
-- LLM 输出通过 Graph 的多下游边分发：一条到 Chunk Sender（推文字），一条到 Sentence Split → TTS（推语音）
-- TTS 封装为 Lambda 节点
-- 所有 Sender 操作封装为 Lambda 节点，注入 `Sender` 依赖
-
-## 3. 详细设计
-
-### 3.1 数据类型定义
-
-```go
-// internal/eino/types.go
-
-// Graph 统一输入
-type PipelineInput struct {
-    AudioData    []byte // base64 解码后的音频（可选）
-    ImageData    []byte // base64 解码后的图像（可选）
-    Text         string // 直接文本输入（可选，跳过 STT）
-    SessionID    string
-    RequestID    string
-    Language     string // zh / en
-    Scenario     string // free_chat, interviewer, etc.
-}
-
-// Graph 统一输出
-type PipelineOutput struct {
-    TranscribedText string // STT 结果
-    FullResponse    string // LLM 完整回复
-}
-
-// STT 节点输出
-type STTOutput struct {
-    Text     string
-    Language string
-}
-
-// LLM 节点输入（组装好的对话历史）
-type LLMInput struct {
-    Messages []*schema.Message
-}
-
-// 句子分割中间类型
-type SentenceChunk struct {
-    Sentence string
-    IsLast   bool
-}
-
-// TTS 节点输出
-type TTSAudioChunk struct {
-    AudioData  []byte
-    Format     string
-    Sentence   string
-    IsLast     bool
-}
-```
-
-### 3.2 Eino Graph 构建
-
-```go
-// internal/eino/graph.go
-
-package eino
-
-import (
-    "context"
-    "github.com/cloudwego/eino/components/model"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-)
-
-// GraphOption 图级别配置
-type GraphOption struct {
-    ChatModel    model.ToolCallingChatModel // Eino 原生 ChatModel
-    STTService   stt.Service                // 现有 STT 接口
-    TTSService   tts.Service                // 现有 TTS 接口
-    SessionMgr   session.Manager            // 会话管理
-    Sender       orchestrator.Sender        // WS 消息推送
-    PromptCfg    *PromptConfig              // 提示词配置
-}
-
-// NewPipelineGraph 构建编排图
-func NewPipelineGraph(ctx context.Context, opt *GraphOption) (compose.Runnable[PipelineInput, PipelineOutput], error) {
-    g := compose.NewGraph[PipelineInput, PipelineOutput]()
-
-    // 1. STT 节点（Lambda）
-    sttNode := compose.InvokableLambda(sttLambda(opt.STTService))
-    g.AddLambdaNode("stt", sttNode)
-
-    // 2. 历史组装节点（Lambda）
-    historyNode := compose.InvokableLambda(historyLambda(opt.SessionMgr, opt.PromptCfg))
-    g.AddLambdaNode("history", historyNode)
-
-    // 3. LLM 节点（ChatModel，原生流式）
-    g.AddChatModelNode("llm", opt.ChatModel)
-
-    // 4. 句子分割节点（Transform Lambda：stream → stream）
-    splitterNode := compose.TransformableLambda(splitterLambda())
-    g.AddLambdaNode("splitter", splitterNode)
-
-    // 5. LLM Chunk 推送节点（Transform Lambda）
-    chunkSenderNode := compose.TransformableLambda(chunkSenderLambda(opt.Sender))
-    g.AddLambdaNode("chunk_sender", chunkSenderNode)
-
-    // 6. TTS 节点（Collect Lambda：stream → non-stream）
-    ttsNode := compose.CollectableLambda(ttsLambda(opt.TTSService, opt.Sender))
-    g.AddLambdaNode("tts", ttsNode)
-
-    // 7. 完成通知节点（Invokable Lambda）
-    doneNode := compose.InvokableLambda(doneLambda(opt.Sender))
-    g.AddLambdaNode("done", doneNode)
-
-    // === 边连接 ===
-
-    // START → STT
-    g.AddEdge(compose.START, "stt")
-    // STT → History
-    g.AddEdge("stt", "history")
-    // History → LLM
-    g.AddEdge("history", "llm")
-
-    // LLM 输出分发到两个下游（利用 Graph 多下游边）
-    // LLM → Chunk Sender（推送原始 token）
-    g.AddEdge("llm", "chunk_sender")
-    // LLM → Splitter → TTS（句子级语音合成）
-    g.AddEdge("llm", "splitter")
-    g.AddEdge("splitter", "tts")
-
-    // Chunk Sender 和 TTS 都汇入 Done
-    g.AddEdge("chunk_sender", "done")
-    g.AddEdge("tts", "done")
-
-    // Done → END
-    g.AddEdge("done", compose.END)
-
-    // 编译
-    return g.Compile(ctx,
-        compose.WithGraphName("camtalk_pipeline"),
-        compose.WithMaxRunSteps(50),
-    )
-}
-```
-
-### 3.3 节点实现
-
-#### 3.3.1 STT Lambda
-
-```go
-// internal/eino/nodes_stt.go
-
-func sttLambda(sttSvc stt.Service) func(ctx context.Context, input PipelineInput) (STTOutput, error) {
-    return func(ctx context.Context, input PipelineInput) (STTOutput, error) {
-        // 文本模式：跳过 STT
-        if input.Text != "" {
-            return STTOutput{Text: input.Text, Language: input.Language}, nil
-        }
-
-        if len(input.AudioData) == 0 {
-            return STTOutput{}, fmt.Errorf("no audio data provided")
-        }
-
-        // 调用现有 STT 服务
-        result, err := sttSvc.Recognize(ctx, input.AudioData, stt.Options{
-            Language: input.Language,
-        })
-        if err != nil {
-            return STTOutput{}, fmt.Errorf("STT error: %w", err)
-        }
-
-        return STTOutput{
-            Text:     result.Text,
-            Language: result.Language,
-        }, nil
-    }
-}
-```
-
-#### 3.3.2 历史组装 Lambda
-
-```go
-// internal/eino/nodes_history.go
-
-func historyLambda(sessionMgr session.Manager, promptCfg *PromptConfig) func(ctx context.Context, input STTOutput) ([]*schema.Message, error) {
-    return func(ctx context.Context, input STTOutput) ([]*schema.Message, error) {
-        sessionID := getSessionID(ctx) // 从 context 或 state 获取
-
-        history, err := sessionMgr.GetHistory(ctx, sessionID)
-        if err != nil {
-            return nil, fmt.Errorf("get history error: %w", err)
-        }
-
-        // 构建系统提示词
-        systemPrompt := promptCfg.BuildSystemPrompt(input.Language, getScenario(ctx))
-
-        messages := []*schema.Message{
-            {Role: schema.System, Content: systemPrompt,
-             MultiContent: buildVisionContent(getImageData(ctx))},
-        }
-
-        // 追加历史消息
-        for _, msg := range history {
-            messages = append(messages, &schema.Message{
-                Role:    schema.Role(msg.Role),
-                Content: msg.Content,
-            })
-        }
-
-        // 追加当前用户输入
-        messages = append(messages, &schema.Message{
-            Role:    schema.User,
-            Content: input.Text,
-        })
-
-        // 保存用户消息到历史
-        _ = sessionMgr.AppendMessage(ctx, sessionID, models.Message{
-            Role:    "user",
-            Content: input.Text,
-        })
-
-        return messages, nil
-    }
-}
-```
-
-#### 3.3.3 句子分割 Transform Lambda
-
-```go
-// internal/eino/nodes_splitter.go
-
-func splitterLambda() func(ctx context.Context, stream *schema.StreamReader[*schema.Message]) (*schema.StreamReader[SentenceChunk], error) {
-    return func(ctx context.Context, stream *schema.StreamReader[*schema.Message]) (*schema.StreamReader[SentenceChunk], error) {
-        sr, sw := schema.Pipe[SentenceChunk](8)
-
-        go func() {
-            defer sw.Close()
-            var buffer []rune
-
-            for {
-                chunk, err := stream.Recv()
-                if err != nil {
-                    if err.Error() == "EOF" {
-                        // 流结束，发送剩余缓冲
-                        if len(buffer) > 0 {
-                            sw.Send(SentenceChunk{Sentence: string(buffer), IsLast: true}, nil)
-                        }
-                        return
-                    }
-                    sw.Send(SentenceChunk{}, err)
-                    return
-                }
-
-                for _, r := range chunk.Content {
-                    buffer = append(buffer, r)
-                    if isSentenceDelimiter(r) {
-                        sw.Send(SentenceChunk{Sentence: string(buffer), IsLast: false}, nil)
-                        buffer = buffer[:0]
-                    }
-                }
-            }
-        }()
-
-        return sr, nil
-    }
-}
-```
-
-#### 3.3.4 TTS Collect Lambda
-
-```go
-// internal/eino/nodes_tts.go
-
-func ttsLambda(ttsSvc tts.Service, sender orchestrator.Sender) func(ctx context.Context, stream *schema.StreamReader[SentenceChunk]) (struct{}, error) {
-    return func(ctx context.Context, stream *schema.StreamReader[SentenceChunk]) (struct{}, error) {
-        for {
-            chunk, err := stream.Recv()
-            if err != nil {
-                if err.Error() == "EOF" {
-                    break
-                }
-                return struct{}{}, err
-            }
-
-            if chunk.Sentence == "" {
-                continue
-            }
-
-            // 调用 TTS 服务
-            audioData, err := ttsSvc.Synthesize(ctx, chunk.Sentence, tts.Options{
-                // 从 Option 或 Config 获取
-            })
-            if err != nil {
-                // TTS 失败不中断流程，仅记录日志
-                log.Warn("TTS synthesis failed", zap.Error(err),
-                    zap.String("sentence", chunk.Sentence))
-                continue
-            }
-
-            // 推送音频到客户端
-            sender.SendTTSAudio(orchestrator.TTSAudioPayload{
-                Audio:     audioData,
-                Format:    "mp3",
-                IsLast:    chunk.IsLast,
-            })
-        }
-
-        return struct{}{}, nil
-    }
-}
-```
-
-#### 3.3.5 Chunk Sender Transform Lambda
-
-```go
-// internal/eino/nodes_sender.go
-
-func chunkSenderLambda(sender orchestrator.Sender) func(ctx context.Context, stream *schema.StreamReader[*schema.Message]) (*schema.StreamReader[*schema.Message], error) {
-    return func(ctx context.Context, stream *schema.StreamReader[*schema.Message]) (*schema.StreamReader[*schema.Message], error) {
-        sr, sw := schema.Pipe[*schema.Message](8)
-
-        go func() {
-            defer sw.Close()
-            for {
-                msg, err := stream.Recv()
-                if err != nil {
-                    if err.Error() == "EOF" {
-                        return
-                    }
-                    sw.Send(nil, err)
-                    return
-                }
-
-                // 推送 LLM 文本 chunk 到客户端
-                sender.SendLLMChunk(orchestrator.LLMChunkPayload{
-                    Content: msg.Content,
-                })
-
-                // 透传给下游
-                sw.Send(msg, nil)
-            }
-        }()
-
-        return sr, nil
-    }
-}
-```
-
-#### 3.3.6 Done Lambda
-
-```go
-// internal/eino/nodes_done.go
-
-func doneLambda(sender orchestrator.Sender) func(ctx context.Context, input struct{}) (PipelineOutput, error) {
-    return func(ctx context.Context, input struct{}) (PipelineOutput, error) {
-        // 通知客户端 LLM 回复完成
-        sender.SendLLMDone(orchestrator.LLMDonePayload{})
-
-        // 保存助手消息到历史
-        // 注意：完整回复需要从某处收集，可通过 State 机制实现
-        return PipelineOutput{}, nil
-    }
-}
-```
-
-### 3.4 State 机制（收集完整回复）
-
-由于 LLM 输出被分发到两个下游，完整回复文本需要通过 Graph State 收集：
-
-```go
-// internal/eino/state.go
-
-type PipelineState struct {
-    FullResponse strings.Builder
-    SessionID    string
-    RequestID    string
-}
-
-func genLocalState(ctx context.Context) *PipelineState {
-    return &PipelineState{}
-}
-
-// 在构建 Graph 时注册 State
-func NewPipelineGraph(ctx context.Context, opt *GraphOption) (compose.Runnable[PipelineInput, PipelineOutput], error) {
-    g := compose.NewGraph[PipelineInput, PipelineOutput](
-        compose.WithGenLocalState(genLocalState),
-    )
-
-    // ... 添加节点 ...
-
-    // Chunk Sender 的 StatePostHandler 累积完整回复
-    g.AddLambdaNode("chunk_sender", chunkSenderNode,
-        compose.WithStatePostHandler(func(ctx context.Context, output *schema.Message, state *PipelineState) *schema.Message {
-            state.FullResponse.WriteString(output.Content)
-            return output
-        }),
-    )
-
-    // Done 节点的 StatePreHandler 读取完整回复
-    g.AddLambdaNode("done", doneNode,
-        compose.WithStatePreHandler(func(ctx context.Context, input struct{}, state *PipelineState) struct{} {
-            // 将完整回复存入 state 供 done 节点使用
-            return input
-        }),
-    )
-
-    // ...
-}
-```
-
-### 3.5 Callback 集成（日志/指标/追踪）
-
-```go
-// internal/eino/callback.go
-
-type MetricsCallback struct {
-    logger   *zap.Logger
-    metrics  *MetricsCollector // Prometheus 等
-}
-
-func (m *MetricsCallback) OnStart(ctx context.Context, info *compose.RunInfo, input compose.CallbackInput) context.Context {
-    m.logger.Debug("node started",
-        zap.String("node", info.Name),
-        zap.String("graph", info.GraphName))
-    return ctx
-}
-
-func (m *MetricsCallback) OnEnd(ctx context.Context, info *compose.RunInfo, output compose.CallbackOutput) context.Context {
-    m.logger.Debug("node completed",
-        zap.String("node", info.Name))
-    return ctx
-}
-
-func (m *MetricsCallback) OnError(ctx context.Context, info *compose.RunInfo, err error) context.Context {
-    m.logger.Error("node failed",
-        zap.String("node", info.Name),
-        zap.Error(err))
-    m.metrics.IncrementError(info.Name)
-    return ctx
-}
-
-// 注册到 Graph
-func NewPipelineGraph(ctx context.Context, opt *GraphOption) (compose.Runnable[PipelineInput, PipelineOutput], error) {
-    // ...
-    callback := &MetricsCallback{logger: opt.Logger, metrics: opt.Metrics}
-
-    return g.Compile(ctx,
-        compose.WithCallbacks(callback), // 全局回调
-        compose.WithCallbacks(llmCallback).DesignateNode("llm"), // LLM 专用回调
-    )
-}
-```
-
-### 3.6 按请求动态配置
-
-```go
-// internal/eino/options.go
-
-// 运行时 Option：每请求可变
-func WithModelName(name string) compose.Option {
-    return compose.WithChatModelOption(model.WithModel(name))
-}
-
-func WithTemperature(temp float32) compose.Option {
-    return compose.WithChatModelOption(model.WithTemperature(temp))
-}
-
-func WithTTSVoice(voice string) compose.Option {
-    return compose.WithCallbacks(&ttsVoiceCallback{voice: voice}).
-        DesignateNode("tts")
-}
-
-// WebSocket Handler 中的调用
-func (c *Client) handleQuery(req QueryRequest) {
-    opts := []compose.Option{}
-
-    // 根据请求配置动态注入
-    if req.Model != "" {
-        opts = append(opts, WithModelName(req.Model))
-    }
-    if req.TTSVoice != "" {
-        opts = append(opts, WithTTSVoice(req.TTSVoice))
-    }
-
-    output, err := c.pipeline.Invoke(ctx, PipelineInput{...}, opts...)
-}
-```
-
-### 3.7 ChatModel 适配（接入 eino-ext OpenAI）
-
-```go
-// internal/eino/chatmodel.go
-
-import (
-    openaiImpl "github.com/cloudwego/eino-ext/components/model/openai"
-)
-
-func NewChatModel(cfg *config.AIConfig) (model.ToolCallingChatModel, error) {
-    return openaiImpl.NewChatModel(context.Background(), &openaiImpl.ChatModelConfig{
-        APIKey:  cfg.LLM.APIKey,
-        Model:   cfg.LLM.Model,
-        BaseURL: cfg.LLM.BaseURL,
-    })
-}
-```
-
-## 4. 目录结构变更
-
-```
-backend/internal/
-├── eino/                    # 新增：Eino 编排层
-│   ├── graph.go             # Graph 构建与编译
-│   ├── types.go             # 数据类型定义
-│   ├── state.go             # Graph State 定义
-│   ├── options.go           # 运行时 Option
-│   ├── callback.go          # 回调实现（日志/指标）
-│   ├── chatmodel.go         # ChatModel 适配器
-│   ├── nodes_stt.go         # STT Lambda 节点
-│   ├── nodes_history.go     # 历史组装 Lambda 节点
-│   ├── nodes_splitter.go    # 句子分割 Transform Lambda
-│   ├── nodes_tts.go         # TTS Collect Lambda 节点
-│   ├── nodes_sender.go      # Chunk Sender Transform Lambda
-│   ├── nodes_done.go        # 完成通知 Lambda 节点
-│   └── graph_test.go        # 集成测试
-├── orchestrator/            # 保留：兼容层（Phase 1）
-│   ├── orchestrator.go      # 接口定义（不变）
-│   ├── pipeline.go          # 旧实现（Phase 3 移除）
-│   ├── splitter.go          # 被 eino/nodes_splitter.go 替代
-│   ├── sender.go            # Sender 接口（不变，被 eino 层引用）
-│   └── eino_adapter.go      # 新增：Eino 编排器适配为 Orchestrator 接口
-├── ai/                      # 保留：AI 服务接口不变
-│   ├── llm/                 # 保留接口，实现被 eino-ext 替代
-│   ├── stt/                 # 完全保留
-│   └── tts/                 # 完全保留
-└── ws/                      # 保留：WebSocket Handler
-    └── handler.go           # 切换到 Eino 编排器
-```
-
-## 5. 分阶段实施计划
-
-### Phase 1：基础设施（预计 2-3 天）
-
-| 任务 | 文件 | 说明 |
-|------|------|------|
-| 引入 Eino 依赖 | `go.mod` | `go get github.com/cloudwego/eino/...` |
-| 引入 eino-ext OpenAI | `go.mod` | `go get github.com/cloudwego/eino-ext/...` |
-| 定义数据类型 | `eino/types.go` | PipelineInput/Output、中间类型 |
-| 定义 State | `eino/state.go` | PipelineState |
-| 实现 ChatModel 适配器 | `eino/chatmodel.go` | 包装 eino-ext OpenAI |
-| 编写 Callback 框架 | `eino/callback.go` | 日志 + 指标回调 |
-
-### Phase 2：节点实现与 Graph 构建（预计 3-4 天）
-
-| 任务 | 文件 | 说明 |
-|------|------|------|
-| STT Lambda | `eino/nodes_stt.go` | 包装现有 stt.Service |
-| 历史组装 Lambda | `eino/nodes_history.go` | 对话历史 + 提示词 |
-| 句子分割 Transform | `eino/nodes_splitter.go` | 重写 splitter.go 为 Eino Lambda |
-| TTS Collect Lambda | `eino/nodes_tts.go` | 包装现有 tts.Service |
-| Chunk Sender Transform | `eino/nodes_sender.go` | LLM token 推送 |
-| Done Lambda | `eino/nodes_done.go` | 完成通知 |
-| Graph 构建 | `eino/graph.go` | 组装所有节点 |
-| 单元测试 | `eino/graph_test.go` | Mock 各节点测试图结构 |
-
-### Phase 3：集成与切换（预计 2-3 天）
-
-| 任务 | 文件 | 说明 |
-|------|------|------|
-| Eino 适配器 | `orchestrator/eino_adapter.go` | 将 Eino Graph 包装为现有 Orchestrator 接口 |
-| WS Handler 切换 | `ws/handler.go` | 使用新的 Eino 编排器 |
-| main.go 依赖注入 | `cmd/server/main.go` | 构建 ChatModel + Graph |
-| 集成测试 | `eino/graph_test.go` | 端到端测试 |
-| 性能对比 | - | 延迟、内存、CPU 对比 |
-
-### Phase 4：清理与增强（预计 1-2 天）
-
-| 任务 | 说明 |
-|------|------|
-| 移除旧 Pipeline | 删除 `orchestrator/pipeline.go`、`splitter.go` |
-| 更新文档 | 更新架构文档、接口文档 |
-| 启用 ReAct Agent（可选） | 基于 Graph Branch 实现工具调用循环 |
-| 动态配置完善 | 按请求切换模型、TTS 参数 |
-
-## 6. 风险与缓解
-
-| 风险 | 影响 | 缓解措施 |
-|------|------|----------|
-| Eino 框架不稳定（v0.x） | 生产故障 | 锁定版本，保留旧 Pipeline 可回退 |
-| 流式处理延迟增加 | 用户体验下降 | 性能对比测试，必要时绕过 Eino 直接调用 |
-| LLM 输出多下游分发丢失数据 | TTS 无输入 | 充分测试 Stream Copy 机制，添加监控 |
-| 学习曲线 | 开发效率 | 先从简单 Chain 开始，逐步过渡到 Graph |
-| eino-ext OpenAI 不兼容现有 API | 功能回退 | 验证 BaseURL 和参数映射，必要时自定义适配器 |
-
-## 7. 测试策略
-
-### 7.1 单元测试
-
-```go
-// eino/graph_test.go
-
-func TestPipelineGraph_WithTextInput(t *testing.T) {
-    // Mock STT, LLM, TTS, Sender
-    mockLLM := &mockChatModel{responses: []string{"你好！"}}
-    mockSender := &mockSender{}
-
-    graph, err := NewPipelineGraph(ctx, &GraphOption{
-        ChatModel: mockLLM,
-        Sender:    mockSender,
-        // ...
-    })
-    require.NoError(t, err)
-
-    output, err := graph.Invoke(ctx, PipelineInput{
-        Text:      "你好",
-        SessionID: "test-session",
-    })
-    require.NoError(t, err)
-    assert.Equal(t, "你好！", output.FullResponse)
-    assert.True(t, mockSender.LLMDoneSent)
-}
-
-func TestPipelineGraph_WithAudioInput(t *testing.T) {
-    mockSTT := &mockSTT{text: "你好"}
-    mockLLM := &mockChatModel{responses: []string{"你好！"}}
-    mockTTS := &mockTTS{audio: []byte("fake-audio")}
-    mockSender := &mockSender{}
-
-    graph, _ := NewPipelineGraph(ctx, &GraphOption{
-        ChatModel:  mockLLM,
-        STTService: mockSTT,
-        TTSService: mockTTS,
-        Sender:     mockSender,
-    })
-
-    output, err := graph.Invoke(ctx, PipelineInput{
-        AudioData: []byte("fake-audio-data"),
-        SessionID: "test-session",
-    })
-    require.NoError(t, err)
-    assert.True(t, mockSender.TTSAudioSent)
-}
-```
-
-### 7.2 集成测试
-
-- 启动真实 OpenAI API 调用（使用测试 key）
-- 验证 WebSocket 消息序列：`stt_result` → `llm_chunk` × N → `llm_done` → `tts_audio` × N
-- 验证 interrupt 取消功能
-- 验证多并发请求隔离
-
-## 8. 依赖清单
-
-```go
-// go.mod 新增
-require (
-    github.com/cloudwego/eino v0.4.x          // 核心框架
-    github.com/cloudwego/eino-ext v0.1.x      // 组件实现
-)
-```
-
-## 9. 未来扩展路径
-
-基于 Eino Graph 的重构完成后，可无缝扩展：
-
-1. **ReAct Agent**：Graph 添加 Branch 节点，实现 LLM → Tool → LLM 循环
-2. **多模态理解**：添加视觉分析 Lambda 节点（图像描述 → 上下文注入）
-3. **Model Router**：Graph 前置分支节点，按场景/成本路由不同 LLM
-4. **Rate Limiter**：通过 Callback 的 OnStart 实现令牌桶
-5. **Checkpoint/Resume**：利用 Eino 的 CheckpointStore 实现断点续传
-6. **Multi-Agent**：利用 ADK 的 Supervisor/SequentialAgent 编排复杂对话流程
-
----
-
-## 附录 A：Eino vs 现有实现对比
-
-| 维度 | 现有实现 | Eino 重构后 |
-|------|----------|------------|
-| 编排方式 | 手写 goroutine + channel | 声明式 Graph，类型安全 |
-| 流式处理 | 手动 channel 传递 | StreamReader + Pipe，自动转换 |
-| 错误处理 | 各节点独立处理 | 统一 Callback OnError |
-| 日志/追踪 | 散落在各处 | AOP Callback 注入 |
-| 配置灵活性 | Pipeline 创建时固定 | 每请求 Option 动态注入 |
-| 可测试性 | 需要启动 goroutine | Graph.Invoke 直接测试 |
-| 扩展性 | 修改 Pipeline 代码 | 添加节点 + 边，无需改已有逻辑 |
-| 并发安全 | 手动 sync | State 自动加锁 |
-
-## 附录 B：关键 Eino API 参考
-
-```go
-// 构建 Graph
-g := compose.NewGraph[I, O](opts...)
-g.AddChatModelNode(key, chatModel)
-g.AddLambdaNode(key, lambda, opts...)
-g.AddEdge(from, to)
-g.AddBranch(from, branchFunc, mapping)
-
-// 编译
-runnable, err := g.Compile(ctx, opts...)
-
-// 执行四种模式
-output, err := runnable.Invoke(ctx, input, opts...)
-stream, err := runnable.Stream(ctx, input, opts...)
-output, err := runnable.Collect(ctx, inputStream, opts...)
-stream, err := runnable.Transform(ctx, inputStream, opts...)
-
-// Lambda 四种构造器
-lambda := compose.InvokableLambda(fn)      // I → O
-lambda := compose.StreamableLambda(fn)     // I → StreamReader[O]
-lambda := compose.CollectableLambda(fn)    // StreamReader[I] → O
-lambda := compose.TransformableLambda(fn)  // StreamReader[I] → StreamReader[O]
-
-// Stream 操作
-sr, sw := schema.Pipe[T](bufSize)
-sw.Send(chunk, err)
-chunk, err := sr.Recv()
-sw.Close()
-
-// Option
-compose.WithCallbacks(handler)
-compose.WithCallbacks(handler).DesignateNode("node_key")
-compose.WithChatModelOption(model.WithTemperature(0.7))
-compose.WithGenLocalState(genFunc)
-```
diff --git a/docs/10-鉴权体系.md b/docs/10-鉴权体系.md
new file mode 100644
index 0000000..db0feb9
--- /dev/null
+++ b/docs/10-鉴权体系.md
@@ -0,0 +1,1110 @@
+# 鉴权体系设计
+
+## 概述
+
+CamTalk 采用 JWT 双 token 轮转认证机制，结合 bcrypt 密码哈希和 Refresh Token Rotation 安全策略，实现安全可靠的用户认证体系。
+
+**设计原则**：
+- **安全性**：access_token 短有效期（15 分钟），refresh_token 支持轮转防重放
+- **可靠性**：Refresh Token Rotation 机制，检测复用时自动吊销用户所有令牌
+- **可扩展性**：Repository 接口隔离存储层，支持内存和 PostgreSQL 双实现
+
+## 整体架构
+
+```mermaid
+graph TB
+    subgraph Client["客户端"]
+        Browser["浏览器"]
+    end
+
+    subgraph AuthModule["Auth 模块"]
+        Service["AuthService<br/>Register / Login / Refresh / Logout"]
+        TokenMgr["TokenManager<br/>JWT 生成与验证"]
+        Middleware["AuthMiddleware<br/>Gin 中间件"]
+        Password["PasswordUtil<br/>bcrypt 哈希"]
+    end
+
+    subgraph Storage["存储层"]
+        UserRepo["UserRepository<br/>用户数据"]
+        TokenStore["RefreshToken 存储<br/>SHA256 哈希"]
+    end
+
+    Browser -->|"POST /api/auth/*"| Service
+    Service --> TokenMgr
+    Service --> Password
+    Service --> UserRepo
+    Service --> TokenStore
+    Middleware -->|"校验 access_token"| TokenMgr
+    Middleware -->|"写入 user_id/username"| GinContext["Gin Context"]
+```
+
+## 核心组件
+
+### 1. JWT 令牌管理（TokenManager）
+
+**文件位置**：`backend/internal/auth/jwt.go`
+
+#### Claims 结构
+
+```go
+type Claims struct {
+    UserID    string `json:"user_id"`
+    Username  string `json:"username"`
+    TokenType string `json:"token_type"` // "access" | "refresh"
+    jwt.RegisteredClaims
+}
+```
+
+**字段说明**：
+- `UserID`：用户唯一标识（UUID）
+- `Username`：用户名
+- `TokenType`：令牌类型，用于区分 access 和 refresh token
+- `RegisteredClaims`：JWT 标准声明（ExpiresAt, IssuedAt, Issuer, ID）
+
+#### TokenManager 配置
+
+```go
+type TokenManager struct {
+    secret     []byte        // JWT 签名密钥（HS256）
+    accessTTL  time.Duration // access_token 有效期（默认 15 分钟）
+    refreshTTL time.Duration // refresh_token 有效期（默认 7 天）
+}
+
+func NewTokenManager(secret string, accessTTL, refreshTTL time.Duration) *TokenManager
+```
+
+#### 令牌生成
+
+```go
+func (tm *TokenManager) GeneratePair(userID, username string) (access, refresh string, err error)
+```
+
+**生成逻辑**：
+1. **access_token**：
+   - 签名算法：HS256
+   - 有效期：15 分钟
+   - 包含：UserID, Username, TokenType="access", ExpiresAt, IssuedAt, Issuer="camtalk"
+
+2. **refresh_token**：
+   - 签名算法：HS256
+   - 有效期：7 天
+   - 包含：UserID, Username, TokenType="refresh", ID=UUID（用于 DB 关联）, ExpiresAt, IssuedAt, Issuer="camtalk"
+
+#### 令牌验证
+
+```go
+func (tm *TokenManager) ValidateAccess(tokenStr string) (*Claims, error)
+func (tm *TokenManager) ValidateRefresh(tokenStr string) (*Claims, error)
+```
+
+**验证逻辑**：
+1. 解析 JWT，验证签名算法为 HMAC
+2. 验证签名是否有效
+3. 验证令牌是否过期
+4. 验证 TokenType 是否匹配（access 或 refresh）
+5. 返回 Claims 或错误
+
+#### Token 哈希
+
+```go
+func HashToken(token string) string
+```
+
+**用途**：对 refresh_token 做 SHA256 哈希后存储到数据库，避免直接存储原始 token。
+
+### 2. 密码处理（PasswordUtil）
+
+**文件位置**：`backend/internal/auth/password.go`
+
+#### 密码哈希
+
+```go
+func HashPassword(password string) (string, error)
+```
+
+**实现**：
+- 算法：bcrypt
+- Cost：10（2^10 次迭代）
+- 返回：base64 编码的哈希字符串
+
+#### 密码验证
+
+```go
+func CheckPassword(hashedPassword, password string) error
+```
+
+**实现**：
+- 使用 `bcrypt.CompareHashAndPassword` 验证
+- 返回 nil 表示匹配，否则返回错误
+
+### 3. 认证服务（AuthService）
+
+**文件位置**：`backend/internal/auth/service.go`
+
+#### 接口定义
+
+```go
+type Service interface {
+    Register(ctx context.Context, req RegisterRequest) (*AuthResponse, error)
+    Login(ctx context.Context, req LoginRequest) (*AuthResponse, error)
+    Refresh(ctx context.Context, req RefreshRequest) (*AuthResponse, error)
+    Logout(ctx context.Context, userID, refreshToken string) error
+}
+```
+
+#### 注册流程（Register）
+
+```go
+func (s *authService) Register(ctx context.Context, req RegisterRequest) (*AuthResponse, error)
+```
+
+**流程**：
+1. 检查用户名是否已存在（`FindByUsername`）
+2. 如果存在，返回 `ErrUsernameTaken`
+3. 使用 bcrypt 哈希密码（`HashPassword`）
+4. 创建用户记录（`Create`）
+5. 生成 access_token + refresh_token（`GeneratePair`）
+6. 保存 refresh_token 的 SHA256 哈希到数据库（`SaveRefreshToken`）
+7. 返回 `AuthResponse`
+
+**错误处理**：
+- `ErrUsernameTaken`：用户名已存在
+- 数据库错误：透传底层错误
+
+#### 登录流程（Login）
+
+```go
+func (s *authService) Login(ctx context.Context, req LoginRequest) (*AuthResponse, error)
+```
+
+**流程**：
+1. 根据用户名查找用户（`FindByUsername`）
+2. 如果用户不存在，返回 `ErrInvalidCredentials`
+3. 验证密码（`CheckPassword`）
+4. 如果密码错误，返回 `ErrInvalidCredentials`
+5. 生成 access_token + refresh_token（`GeneratePair`）
+6. 保存 refresh_token 的 SHA256 哈希到数据库（`SaveRefreshToken`）
+7. 返回 `AuthResponse`
+
+**错误处理**：
+- `ErrInvalidCredentials`：用户名或密码错误（统一错误信息，防止枚举攻击）
+
+#### 刷新令牌流程（Refresh）— Refresh Token Rotation
+
+```go
+func (s *authService) Refresh(ctx context.Context, req RefreshRequest) (*AuthResponse, error)
+```
+
+**流程**：
+1. 验证 refresh_token 的签名和有效期（`ValidateRefresh`）
+2. 计算 refresh_token 的 SHA256 哈希（`HashToken`）
+3. 在数据库中查找该哈希（`FindRefreshToken`）
+4. **如果哈希不存在**：
+   - JWT 校验已通过但 DB 中不存在 → token 已被 rotation 删除
+   - 这是 **token 复用行为**，属于安全风险
+   - 吊销该用户的所有 refresh_token（`DeleteUserRefreshTokens`）
+   - 返回 `ErrRefreshTokenUsed`
+5. 验证 token 归属的用户与 claims 一致
+6. 删除旧的 refresh_token 哈希（`DeleteRefreshToken`）
+7. 生成新的 access_token + refresh_token（`GeneratePair`）
+8. 保存新的 refresh_token 哈希到数据库（`SaveRefreshToken`）
+9. 查询用户信息（`FindByID`）
+10. 返回 `AuthResponse`
+
+**安全机制**：
+- **Token 轮转**：每次 refresh 都会生成新的 token pair，旧 refresh_token 立即失效
+- **复用检测**：如果检测到已删除的 refresh_token 被复用，立即吊销该用户的所有 refresh_token
+- **强制重新登录**：吊销后，该用户所有设备都需要重新登录
+
+#### 登出流程（Logout）
+
+```go
+func (s *authService) Logout(ctx context.Context, userID, refreshToken string) error
+```
+
+**流程**：
+1. 计算 refresh_token 的 SHA256 哈希（`HashToken`）
+2. 从数据库删除该哈希（`DeleteRefreshToken`）
+
+### 4. Gin 中间件（AuthMiddleware）
+
+**文件位置**：`backend/internal/auth/middleware.go`
+
+```go
+func AuthMiddleware(tokenMgr *TokenManager) gin.HandlerFunc
+```
+
+**功能**：
+1. 从请求头提取 `Authorization: Bearer <token>`
+2. 验证 access_token（`ValidateAccess`）
+3. 如果验证失败，返回 401 Unauthorized
+4. 如果验证成功，将 `user_id` 和 `username` 写入 Gin Context
+5. 调用 `c.Next()` 继续处理请求
+
+**错误响应**：
+```json
+{
+  "code": "INVALID_TOKEN",
+  "message": "missing authorization header"
+}
+```
+
+```json
+{
+  "code": "INVALID_TOKEN",
+  "message": "invalid authorization format"
+}
+```
+
+```json
+{
+  "code": "INVALID_TOKEN",
+  "message": "invalid or expired token"
+}
+```
+
+**Context Key**：
+- `ContextKeyUserID = "user_id"`
+- `ContextKeyUsername = "username"`
+
+**使用示例**：
+```go
+// 在路由中使用中间件
+authorized := r.Group("/api")
+authorized.Use(auth.AuthMiddleware(tokenMgr))
+{
+    authorized.GET("/conversations", handler.ListConversations)
+    authorized.POST("/conversations", handler.CreateConversation)
+}
+```
+
+## 数据模型
+
+### 用户表（users）
+
+```sql
+CREATE TABLE users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    username VARCHAR(64) UNIQUE NOT NULL,
+    password_hash VARCHAR(255) NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+```
+
+### Refresh Token 表（refresh_tokens）
+
+```sql
+CREATE TABLE refresh_tokens (
+    token_hash VARCHAR(64) PRIMARY KEY,  -- SHA256 哈希
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+CREATE INDEX idx_refresh_tokens_user_id ON refresh_tokens(user_id);
+CREATE INDEX idx_refresh_tokens_expires_at ON refresh_tokens(expires_at);
+```
+
+## Repository 接口
+
+### UserRepository
+
+```go
+type UserRepository interface {
+    // Create 创建用户，返回用户 ID
+    Create(ctx context.Context, username, passwordHash string) (string, error)
+
+    // FindByUsername 根据用户名查找用户
+    FindByUsername(ctx context.Context, username string) (*User, error)
+
+    // FindByID 根据 ID 查找用户
+    FindByID(ctx context.Context, id string) (*User, error)
+
+    // SaveRefreshToken 保存 refresh_token 哈希
+    SaveRefreshToken(ctx context.Context, userID, tokenHash string, expiresAt time.Time) error
+
+    // FindRefreshToken 根据 token 哈希查找用户 ID
+    FindRefreshToken(ctx context.Context, tokenHash string) (string, error)
+
+    // DeleteRefreshToken 删除指定的 refresh_token
+    DeleteRefreshToken(ctx context.Context, tokenHash string) error
+
+    // DeleteUserRefreshTokens 删除用户的所有 refresh_token（用于检测复用时吊销）
+    DeleteUserRefreshTokens(ctx context.Context, userID string) error
+}
+```
+
+## 前端集成
+
+### Token 存储
+
+**推荐方案**：
+- `access_token`：存储在内存中（JavaScript 变量）
+- `refresh_token`：存储在 `httpOnly` Cookie 中（防止 XSS 攻击）
+
+**备选方案**（开发环境）：
+- 两者都存储在 `localStorage`（便于调试，但存在 XSS 风险）
+
+### 请求拦截器
+
+```typescript
+// axios 请求拦截器
+api.interceptors.request.use((config) => {
+  const accessToken = getAccessToken();
+  if (accessToken) {
+    config.headers.Authorization = `Bearer ${accessToken}`;
+  }
+  return config;
+});
+
+// axios 响应拦截器
+api.interceptors.response.use(
+  (response) => response,
+  async (error) => {
+    const originalRequest = error.config;
+
+    // 如果是 401 且不是 refresh 请求，尝试刷新 token
+    if (error.response?.status === 401 && !originalRequest._retry) {
+      originalRequest._retry = true;
+
+      try {
+        const refreshToken = getRefreshToken();
+        const response = await api.post('/api/auth/refresh', {
+          refresh_token: refreshToken,
+        });
+
+        const { access_token, refresh_token } = response.data;
+        setAccessToken(access_token);
+        setRefreshToken(refresh_token);
+
+        // 重试原始请求
+        originalRequest.headers.Authorization = `Bearer ${access_token}`;
+        return api(originalRequest);
+      } catch (refreshError) {
+        // 刷新失败，跳转登录页
+        clearTokens();
+        window.location.href = '/login';
+        return Promise.reject(refreshError);
+      }
+    }
+
+    return Promise.reject(error);
+  }
+);
+```
+
+### WebSocket 认证
+
+```typescript
+// 建立 WebSocket 连接时传递 access_token
+const wsUrl = `ws://${window.location.host}/ws?token=${accessToken}&conversation_id=${conversationId}`;
+const ws = new WebSocket(wsUrl);
+
+// 连接失败时（401），触发 token 刷新
+ws.onerror = (error) => {
+  console.error('WebSocket connection failed');
+  // 可能需要刷新 token 后重连
+};
+```
+
+## 安全考虑
+
+### 1. 密码安全
+
+- **bcrypt 算法**：使用 bcrypt 进行密码哈希，cost factor 为 10
+- **盐值自动生成**：bcrypt 自动生成随机盐值，无需手动管理
+- **防彩虹表**：每个密码的哈希值都不同，即使密码相同
+
+### 2. Token 安全
+
+- **短期 access_token**：15 分钟有效期，降低泄露风险
+- **Refresh Token Rotation**：每次 refresh 都生成新 token，旧 token 立即失效
+- **复用检测**：检测到已删除的 refresh_token 被复用时，吊销该用户的所有 token
+- **SHA256 哈希存储**：数据库只存储 refresh_token 的哈希值，不存储原始 token
+
+### 3. 传输安全
+
+- **HTTPS 强制**：生产环境必须使用 HTTPS
+- **同源反代**：通过 Nginx 反向代理（生产）或 Vite proxy（开发）统一前后端到同一域名，浏览器层面无跨域问题
+- **HttpOnly Cookie**：refresh_token 存储在 httpOnly Cookie 中，防止 XSS 攻击
+
+### 4. 防攻击策略
+
+- **防暴力破解**：可选的速率限制（`RATE_LIMITED` 错误码）
+- **防枚举攻击**：登录失败时统一返回 `INVALID_CREDENTIALS`，不区分用户名不存在还是密码错误
+- **防重放攻击**：Refresh Token Rotation 确保每个 refresh_token 只能使用一次
+- **防 Token 泄露**：检测到 token 复用时，立即吊销该用户的所有 token
+
+## 配置说明
+
+### 配置文件
+
+```yaml
+auth:
+  jwt_secret: ""           # JWT 签名密钥（必须通过环境变量设置）
+  access_ttl: 15           # access_token 有效期（分钟）
+  refresh_ttl: 10080       # refresh_token 有效期（分钟，7天）
+```
+
+### 环境变量
+
+| 环境变量 | 说明 | 示例 |
+|---------|------|------|
+| `CAMTALK_AUTH_JWT_SECRET` | JWT 签名密钥（必须） | `$(openssl rand -hex 32)` |
+| `CAMTALK_AUTH_ACCESS_TTL` | access_token 有效期（分钟） | `15` |
+| `CAMTALK_AUTH_REFRESH_TTL` | refresh_token 有效期（分钟） | `10080` |
+
+**安全要求**：
+- `JWT_SECRET` **必须**通过环境变量设置，不能写入配置文件
+- 生产环境使用 `openssl rand -hex 32` 生成随机密钥
+- 密钥长度建议至少 32 字节（256 位）
+
+## 错误码
+
+| 错误码 | HTTP 状态码 | 含义 | 客户端处理 |
+|--------|-----------|------|-----------|
+| `USERNAME_TAKEN` | 409 | 用户名已存在 | 提示换一个用户名 |
+| `INVALID_CREDENTIALS` | 401 | 用户名或密码错误 | 提示检查输入 |
+| `INVALID_TOKEN` | 401 | JWT 无效或已过期 | 尝试 refresh，失败则重新登录 |
+
+## 测试用例
+
+### 单元测试
+
+**文件位置**：`backend/internal/auth/jwt_test.go`, `backend/internal/auth/service_test.go`
+
+**测试覆盖**：
+- Token 生成和验证
+- Token 过期处理
+- Refresh Token Rotation
+- Token 复用检测和吊销
+- 密码哈希和验证
+- 边界条件和错误处理
+
+### 集成测试
+
+**测试场景**：
+- 注册 → 登录 → 访问受保护资源
+- Token 刷新流程
+- Token 过期后自动刷新
+- 并发刷新 token（竞态条件）
+- Token 复用检测和吊销
+
+## 监控指标
+
+### 关键指标
+
+- **登录成功率**：登录成功次数 / 登录总次数
+- **Token 刷新率**：refresh 请求次数 / 总请求数
+- **Token 复用检测**：检测到 token 复用的次数（安全事件）
+- **认证延迟**：JWT 验证的平均耗时
+
+### 告警规则
+
+- **Token 复用检测**：任何 token 复用事件都应触发告警
+- **异常登录失败率**：短时间内大量登录失败可能表示暴力破解攻击
+- **Token 刷新失败率**：refresh 失败率突然上升可能表示系统问题
+
+## 扩展点
+
+### 1. 多设备管理
+
+当前实现支持同一用户在多个设备上登录（每个设备独立的 refresh_token）。可以扩展为：
+- 设备列表管理
+- 单设备登录（踢出其他设备）
+- 设备信任等级
+
+### 2. OAuth 第三方登录
+
+可以扩展 AuthService 支持 OAuth 2.0：
+- Google、GitHub 等第三方登录
+- 绑定/解绑第三方账号
+- 统一的用户身份管理
+
+### 3. 双因素认证（2FA）
+
+可以扩展为：
+- TOTP（基于时间的一次性密码）
+- SMS 验证码
+- 邮箱验证
+
+### 4. 会话管理
+
+可以扩展为：
+- 活跃会话列表
+- 远程登出其他会话
+- 会话过期策略
+
+## 实际实现要点
+
+### 1. 模块结构
+
+**后端核心文件**：
+
+```
+backend/internal/auth/
+├── jwt.go          — TokenManager: JWT 生成/验证，Token 哈希
+├── password.go     — bcrypt 密码哈希/验证
+├── service.go      — AuthService: 注册/登录/刷新/登出业务逻辑
+└── middleware.go   — AuthMiddleware: Gin 中间件，提取并验证 access_token
+
+backend/internal/store/
+├── user.go         — UserRepository 接口定义
+├── user_pg.go      — PgUserRepository: PostgreSQL 实现
+├── user_mem.go     — MemUserRepository: 内存实现（测试用）
+└── cached_user.go  — CachedUserRepository: Redis 缓存装饰器
+```
+
+**前端核心文件**：
+
+```
+frontend/src/lib/
+├── auth.tsx        — AuthProvider: 认证状态管理 + 自动刷新
+├── api.ts          — HTTP 客户端 + 401 拦截器 + 重试机制
+└── storage.ts      — localStorage 封装（token + 用户信息持久化）
+```
+
+### 2. JWT 生成与验证实现
+
+**TokenManager 初始化**（`backend/cmd/server/main.go`）：
+
+```go
+tokenMgr := auth.NewTokenManager(
+    cfg.Auth.JWTSecret,           // 从环境变量读取
+    time.Duration(cfg.Auth.AccessTTL) * time.Minute,   // 默认 120 分钟
+    time.Duration(cfg.Auth.RefreshTTL) * time.Minute,  // 默认 10080 分钟（7天）
+)
+```
+
+**Token 生成逻辑**（`backend/internal/auth/jwt.go:49-86`）：
+
+- **access_token**：
+  - Claims: `UserID`, `Username`, `TokenType="access"`, `ExpiresAt`, `IssuedAt`, `Issuer="camtalk"`
+  - 签名算法：`jwt.SigningMethodHS256`
+  - 有效期：从配置读取（默认 120 分钟）
+
+- **refresh_token**：
+  - Claims: 同 access_token + `ID=uuid.New().String()`（用于 DB 关联）
+  - `TokenType="refresh"`
+  - 有效期：从配置读取（默认 10080 分钟）
+
+**Token 验证逻辑**（`backend/internal/auth/jwt.go:113-128`）：
+
+1. 使用 `jwt.ParseWithClaims` 解析 token
+2. 验证签名方法为 HMAC
+3. 验证签名是否有效（使用 secret）
+4. 验证 token 是否过期（自动检查 `ExpiresAt`）
+5. 验证 `TokenType` 是否匹配（access 或 refresh）
+
+**Token 哈希**（`backend/internal/auth/jwt.go:130-134`）：
+
+```go
+func HashToken(token string) string {
+    h := sha256.Sum256([]byte(token))
+    return hex.EncodeToString(h[:])
+}
+```
+
+用于将 refresh_token 哈希后存入数据库，避免明文存储。
+
+### 3. Refresh Token Rotation 实现
+
+**核心流程**（`backend/internal/auth/service.go:156-211`）：
+
+```go
+func (s *authService) Refresh(ctx context.Context, req RefreshRequest) (*AuthResponse, error) {
+    // 1. 验证 JWT 签名和有效期
+    claims, err := s.tokenMgr.ValidateRefresh(req.RefreshToken)
+    if err != nil {
+        return nil, ErrRefreshTokenUsed
+    }
+
+    // 2. 计算 token 的 SHA256 哈希
+    tokenHash := HashToken(req.RefreshToken)
+
+    // 3. 在 DB 中查找该 hash
+    userID, err := s.userRepo.FindRefreshToken(ctx, tokenHash)
+    if err != nil {
+        if errors.Is(err, store.ErrRefreshTokenNotFound) {
+            // 复用检测：JWT 有效但 DB 中不存在 → 已被 rotation 删除
+            // 吊销该用户的所有 refresh token
+            _ = s.userRepo.DeleteUserRefreshTokens(ctx, claims.UserID)
+            return nil, ErrRefreshTokenUsed
+        }
+        return nil, err
+    }
+
+    // 4. 验证 user_id 一致性
+    if userID != claims.UserID {
+        return nil, ErrRefreshTokenUsed
+    }
+
+    // 5. 删除旧 refresh token（rotation）
+    _ = s.userRepo.DeleteRefreshToken(ctx, tokenHash)
+
+    // 6. 生成新的 token pair
+    access, refresh, err := s.tokenMgr.GeneratePair(claims.UserID, claims.Username)
+    if err != nil {
+        return nil, err
+    }
+
+    // 7. 保存新 refresh token
+    if err := s.saveRefreshToken(ctx, claims.UserID, refresh); err != nil {
+        return nil, err
+    }
+
+    // 8. 返回新 token
+    return &AuthResponse{...}, nil
+}
+```
+
+**安全机制**：
+- 每次刷新都删除旧 token（第 5 步）
+- 如果检测到已删除的 token 被复用（第 3 步），立即吊销该用户的所有 refresh token
+- 强制所有设备重新登录
+
+### 4. PostgreSQL Repository 实现
+
+**PgUserRepository**（`backend/internal/store/user_pg.go`）：
+
+使用 `pgx/v5` 作为 PostgreSQL 驱动，连接池为 `*pgxpool.Pool`。
+
+**关键实现**：
+
+```go
+// 保存 refresh token（INSERT）
+func (r *PgUserRepository) SaveRefreshToken(ctx context.Context, userID, tokenHash string, expiresAt time.Time) error {
+    _, err := r.pool.Exec(ctx,
+        `INSERT INTO refresh_tokens (user_id, token_hash, expires_at) VALUES ($1, $2, $3)`,
+        userID, tokenHash, expiresAt,
+    )
+    return err
+}
+
+// 查找 refresh token（SELECT + 过期时间校验）
+func (r *PgUserRepository) FindRefreshToken(ctx context.Context, tokenHash string) (string, error) {
+    var userID string
+    err := r.pool.QueryRow(ctx,
+        `SELECT user_id FROM refresh_tokens WHERE token_hash = $1 AND expires_at > NOW()`,
+        tokenHash,
+    ).Scan(&userID)
+    if errors.Is(err, pgx.ErrNoRows) {
+        return "", ErrRefreshTokenNotFound
+    }
+    return userID, err
+}
+
+// 删除单个 refresh token（DELETE）
+func (r *PgUserRepository) DeleteRefreshToken(ctx context.Context, tokenHash string) error {
+    _, err := r.pool.Exec(ctx,
+        `DELETE FROM refresh_tokens WHERE token_hash = $1`,
+        tokenHash,
+    )
+    return err
+}
+
+// 删除用户的所有 refresh token（批量 DELETE，用于吊销）
+func (r *PgUserRepository) DeleteUserRefreshTokens(ctx context.Context, userID string) error {
+    _, err := r.pool.Exec(ctx,
+        `DELETE FROM refresh_tokens WHERE user_id = $1`,
+        userID,
+    )
+    return err
+}
+```
+
+**错误处理**：
+- `pgx.ErrNoRows` → 转换为业务错误 `ErrUserNotFound` / `ErrRefreshTokenNotFound`
+- 其他错误透传
+
+### 5. Redis 缓存装饰器实现
+
+**CachedUserRepository**（`backend/internal/store/cached_user.go`）：
+
+采用装饰器模式，为 `UserRepository` 的 refresh token 操作增加 Redis 缓存层。
+
+**缓存策略**：
+
+```go
+// Redis Key 设计
+const (
+    refreshTokenPrefix = "auth:refresh:"      // auth:refresh:{token_hash} → user_id
+    userRefreshPrefix  = "auth:user_refresh:" // auth:user_refresh:{user_id} → Set<token_hash>
+)
+```
+
+**写路径（Write-Through）**：
+
+```go
+func (r *CachedUserRepository) SaveRefreshToken(ctx, userID, tokenHash, expiresAt) error {
+    // 1. 先写 DB
+    if err := r.inner.SaveRefreshToken(ctx, userID, tokenHash, expiresAt); err != nil {
+        return err
+    }
+
+    // 2. 写 Redis（SET + SADD），TTL 为 token 剩余有效期
+    ttl := time.Until(expiresAt)
+    pipe := r.rdb.Pipeline()
+    pipe.Set(ctx, "auth:refresh:"+tokenHash, userID, ttl)
+    pipe.SAdd(ctx, "auth:user_refresh:"+userID, tokenHash)
+    _, _ = pipe.Exec(ctx)  // Redis 失败不影响正确性
+    return nil
+}
+```
+
+**读路径（Read-Through）**：
+
+```go
+func (r *CachedUserRepository) FindRefreshToken(ctx, tokenHash) (string, error) {
+    // 1. 先查 Redis
+    userID, err := r.rdb.Get(ctx, "auth:refresh:"+tokenHash).Result()
+    if err == nil {
+        return userID, nil  // 缓存命中
+    }
+
+    // 2. Redis miss，降级到 DB
+    userID, err = r.inner.FindRefreshToken(ctx, tokenHash)
+    if err != nil {
+        return "", err
+    }
+
+    // 3. 异步回填 Redis
+    go func() {
+        pipe := r.rdb.Pipeline()
+        pipe.Set(bgCtx, key, userID, r.backfillTTL)
+        pipe.SAdd(bgCtx, "auth:user_refresh:"+userID, tokenHash)
+        _, _ = pipe.Exec(bgCtx)
+    }()
+
+    return userID, nil
+}
+```
+
+**删除路径（双删）**：
+
+```go
+func (r *CachedUserRepository) DeleteRefreshToken(ctx, tokenHash) error {
+    // 1. 先从 Redis 获取 user_id
+    userID, _ := r.rdb.Get(ctx, "auth:refresh:"+tokenHash).Result()
+
+    // 2. 删 DB
+    if err := r.inner.DeleteRefreshToken(ctx, tokenHash); err != nil {
+        return err
+    }
+
+    // 3. 删 Redis（DEL + SREM）
+    pipe := r.rdb.Pipeline()
+    pipe.Del(ctx, "auth:refresh:"+tokenHash)
+    if userID != "" {
+        pipe.SRem(ctx, "auth:user_refresh:"+userID, tokenHash)
+    }
+    _, _ = pipe.Exec(ctx)
+    return nil
+}
+```
+
+**降级策略**：
+- Redis 操作失败时记录日志，但不阻断主流程
+- DB 是唯一真实数据源，Redis 仅用于加速
+
+### 6. Gin 中间件实现
+
+**AuthMiddleware**（`backend/internal/auth/middleware.go:18-54`）：
+
+```go
+func AuthMiddleware(tokenMgr *TokenManager) gin.HandlerFunc {
+    return func(c *gin.Context) {
+        // 1. 提取 Authorization header
+        authHeader := c.GetHeader("Authorization")
+        if authHeader == "" {
+            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
+                "code": "INVALID_TOKEN",
+                "message": "missing authorization header",
+            })
+            return
+        }
+
+        // 2. 解析 Bearer token
+        parts := strings.SplitN(authHeader, " ", 2)
+        if len(parts) != 2 || !strings.EqualFold(parts[0], "Bearer") {
+            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
+                "code": "INVALID_TOKEN",
+                "message": "invalid authorization format",
+            })
+            return
+        }
+
+        // 3. 验证 access token
+        claims, err := tokenMgr.ValidateAccess(parts[1])
+        if err != nil {
+            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
+                "code": "INVALID_TOKEN",
+                "message": "invalid or expired token",
+            })
+            return
+        }
+
+        // 4. 将用户信息写入 Gin Context
+        c.Set("user_id", claims.UserID)
+        c.Set("username", claims.Username)
+
+        c.Next()
+    }
+}
+```
+
+**使用方式**（在路由注册时）：
+
+```go
+authorized := r.Group("/api")
+authorized.Use(auth.AuthMiddleware(tokenMgr))
+{
+    authorized.GET("/conversations", handler.ListConversations)
+    authorized.POST("/conversations", handler.CreateConversation)
+}
+```
+
+**获取用户信息**（在 handler 中）：
+
+```go
+func (h *Handler) ListConversations(c *gin.Context) {
+    userID := c.GetString("user_id")       // 从 context 获取
+    username := c.GetString("username")
+    // ...
+}
+```
+
+### 7. 前端集成实现
+
+**AuthProvider**（`frontend/src/lib/auth.tsx`）：
+
+采用 React Context + 自动 token 刷新机制。
+
+**初始化流程**（`useEffect`）：
+
+```typescript
+useEffect(() => {
+    const init = async () => {
+        const storedAccess = loadAccessToken();
+        const storedRefresh = loadRefreshToken();
+        const storedUser = loadUser();
+
+        if (!storedAccess || !storedRefresh || !storedUser) {
+            setIsLoading(false);
+            return;
+        }
+
+        // 检查 access token 是否过期
+        const payload = parseJwtPayload(storedAccess);
+        const nowSec = Math.floor(Date.now() / 1000);
+
+        if (payload?.exp && payload.exp > nowSec) {
+            // access token 仍然有效
+            setUser(storedUser);
+            setAccessToken(storedAccess);
+            scheduleRefresh(storedAccess);  // 安排自动刷新
+        } else {
+            // access token 过期，尝试 refresh
+            const res = await api.refreshToken(storedRefresh);
+            if (res.data) {
+                persistAuth(res.data.user, res.data.access_token, res.data.refresh_token);
+                scheduleRefresh(res.data.access_token);
+            } else {
+                clearAuth();
+            }
+        }
+        setIsLoading(false);
+    };
+
+    init();
+}, []);
+```
+
+**自动刷新机制**（`scheduleRefresh`）：
+
+```typescript
+const scheduleRefresh = useCallback((access: string) => {
+    clearRefreshTimer();
+    const payload = parseJwtPayload(access);
+    if (!payload?.exp) return;
+
+    const nowSec = Math.floor(Date.now() / 1000);
+    // 提前 60 秒刷新（REFRESH_BUFFER_SEC）
+    const delayMs = Math.max((payload.exp - nowSec - 60) * 1000, 5000);
+
+    refreshTimerRef.current = setTimeout(async () => {
+        const rt = loadRefreshToken();
+        if (!rt) return;
+        const res = await api.refreshToken(rt);
+        if (res.data) {
+            persistAuth(res.data.user, res.data.access_token, res.data.refresh_token);
+            scheduleRefresh(res.data.access_token);  // 递归安排下次刷新
+        } else {
+            clearAuth();
+            setUser(null);
+            setAccessToken(null);
+        }
+    }, delayMs);
+}, [clearRefreshTimer, persistAuth]);
+```
+
+**401 拦截器**（`frontend/src/lib/api.ts:104-109`）：
+
+```typescript
+// 在 request 函数中
+if (res.status === 401 && !_retry && !isPublicPath(path) && authCallbacks) {
+    const refreshed = await refreshWithLock();  // 并发保护
+    if (refreshed) {
+        return request<T>(path, options, true);  // 重试一次
+    }
+}
+```
+
+**并发刷新保护**（`refreshWithLock`）：
+
+```typescript
+let refreshPromise: Promise<boolean> | null = null;
+
+async function refreshWithLock(): Promise<boolean> {
+    if (!refreshPromise) {
+        refreshPromise = doRefresh().finally(() => {
+            refreshPromise = null;
+        });
+    }
+    return refreshPromise;  // 多个 401 共享同一个 refresh Promise
+}
+```
+
+**Token 存储**（`frontend/src/lib/storage.ts`）：
+
+当前实现使用 `localStorage` 存储 token（开发环境方便调试）：
+
+```typescript
+const ACCESS_TOKEN_KEY = "camtalk:access_token";
+const REFRESH_TOKEN_KEY = "camtalk:refresh_token";
+const USER_KEY = "camtalk:user";
+
+export function saveAccessToken(token: string): void {
+    localStorage.setItem(ACCESS_TOKEN_KEY, token);
+}
+
+export function loadAccessToken(): string | null {
+    return localStorage.getItem(ACCESS_TOKEN_KEY);
+}
+
+// refresh token 和 user 信息同理
+```
+
+**安全建议**：生产环境应改用 `httpOnly` Cookie 存储 refresh token，防止 XSS 攻击。
+
+### 8. 配置示例
+
+**环境变量**（`backend/.env.example`）：
+
+```bash
+# 运行环境
+APP_ENV=dev  # dev / prod
+
+# JWT 认证（必须）
+CAMTALK_AUTH_JWT_SECRET=your-jwt-secret-here  # 建议使用 openssl rand -hex 32 生成
+
+# PostgreSQL（必须）
+CAMTALK_STORAGE_DSN=postgres://camtalk:password@localhost:5432/camtalk?sslmode=disable
+
+# Redis（可选，启用缓存时必须）
+CAMTALK_STORAGE_REDIS_ENABLED=true
+CAMTALK_REDIS_ADDR=localhost:6379
+CAMTALK_REDIS_PASSWORD=your-redis-password
+
+# AI 服务 API Key（必须）
+CAMTALK_AI_STT_API_KEY=sk-your-stt-key
+CAMTALK_AI_LLM_API_KEY=sk-your-llm-key
+CAMTALK_AI_TTS_API_KEY=sk-your-tts-key
+```
+
+**配置文件**（`backend/config/config.yaml`）：
+
+```yaml
+auth:
+  # jwt_secret 通过环境变量 CAMTALK_AUTH_JWT_SECRET 设置
+  access_ttl: 120              # Access Token 过期时间（分钟）
+  refresh_ttl: 10080          # Refresh Token 过期时间（分钟），7 天
+```
+
+**生产环境配置**（`backend/config/config.prod.yaml`）：
+
+```yaml
+ratelimit:
+  enabled: true               # 生产环境启用限流
+  login:
+    capacity: 5               # 突发容量：允许连续 5 次登录尝试
+    rate: 0.1                 # 填充速率：每 10 秒补充 1 次
+```
+
+### 9. 启动流程
+
+**后端初始化**（`backend/cmd/server/main.go` 简化版）：
+
+```go
+// 1. 加载配置
+cfg := loadConfig()
+
+// 2. 初始化 DB 连接池
+pgPool := connectPostgreSQL(cfg.Storage.DSN)
+
+// 3. 创建 Repository
+pgUserRepo := store.NewPgUserRepository(pgPool)
+
+// 4. 如果启用 Redis，包装为缓存装饰器
+var userRepo store.UserRepository = pgUserRepo
+if cfg.Storage.Redis.Enabled {
+    rdb := redis.NewClient(&redis.Options{...})
+    userRepo = store.NewCachedUserRepository(pgUserRepo, rdb, 24*time.Hour)
+}
+
+// 5. 创建 TokenManager
+tokenMgr := auth.NewTokenManager(
+    cfg.Auth.JWTSecret,
+    time.Duration(cfg.Auth.AccessTTL) * time.Minute,
+    time.Duration(cfg.Auth.RefreshTTL) * time.Minute,
+)
+
+// 6. 创建 AuthService
+authSvc := auth.NewAuthService(tokenMgr, userRepo)
+
+// 7. 注册路由
+r := gin.New()
+authHandler := handler.NewAuthHandler(authSvc)
+r.POST("/api/auth/register", authHandler.Register)
+r.POST("/api/auth/login", authHandler.Login)
+r.POST("/api/auth/refresh", authHandler.Refresh)
+
+authorized := r.Group("/api")
+authorized.Use(auth.AuthMiddleware(tokenMgr))
+{
+    authorized.POST("/api/auth/logout", authHandler.Logout)
+    authorized.GET("/api/conversations", ...)
+}
+```
+
+**前端初始化**（`frontend/src/main.tsx`）：
+
+```tsx
+import { AuthProvider } from './lib/auth';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <AuthProvider>
+      <App />
+    </AuthProvider>
+  </React.StrictMode>
+);
+```
+
+## 参考资料
+
+- [JWT 规范](https://tools.ietf.org/html/rfc7519)
+- [bcrypt 算法](https://en.wikipedia.org/wiki/Bcrypt)
+- [OWASP 认证备忘录](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)
+- [Refresh Token Rotation](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/)
diff --git a/docs/11-Eino框架技术文档.md b/docs/11-Eino框架技术文档.md
deleted file mode 100644
index 0995b97..0000000
--- a/docs/11-Eino框架技术文档.md
+++ /dev/null
@@ -1,246 +0,0 @@
-# CamTalk Eino 框架技术文档
-
-> 创建日期：2026-06-19
-> 状态：已实施
-
-## 1. 框架简介
-
-[CloudWeGo Eino](https://github.com/cloudwego/eino) 是字节跳动 CloudWeGo 团队开源的 AI 应用开发框架，提供基于图（Graph）的编排能力、组件抽象和流式处理支持。
-
-CamTalk 使用 Eino 替代原有的手写 goroutine 管道，实现 STT → LLM → TTS 的声明式编排。
-
-## 2. 技术选型
-
-### 2.1 为什么选 Eino
-
-| 维度 | 手写 goroutine（旧方案） | Eino Graph（新方案） |
-|------|------------------------|---------------------|
-| 编排方式 | 手动 `go func()` + `sync.WaitGroup` | 声明式 DAG，类型安全 |
-| 流式处理 | 自定义 `chan` 传递 | `StreamReader` + `Pipe`，自动转换 |
-| 错误处理 | 各节点独立处理，不一致 | Graph 级别统一错误传播 |
-| 回调/AOP | 日志散落各处 | `callbacks.Handler` 统一注入 |
-| 配置灵活性 | Pipeline 创建时固定 | 每请求 `Option` 动态注入 |
-| 可测试性 | 需启动 goroutine | `Graph.Invoke()` 直接测试 |
-| 扩展性 | 修改 Pipeline 代码 | 添加节点 + 边，无侵入 |
-| 并发安全 | 手动 `sync` | State 自动加锁 |
-
-### 2.2 Eino vs 其他编排框架
-
-| 框架 | 特点 | CamTalk 适用性 |
-|------|------|---------------|
-| **Eino** | Go 原生、类型安全、流式原生 | ✅ 完美匹配 |
-| LangChain Go | 生态丰富但较重 | ❌ 过度抽象 |
-| 自研编排 | 完全可控 | ❌ 维护成本高 |
-
-**选择 Eino 的核心理由**：
-1. Go 原生，泛型支持，编译时类型检查
-2. 原生流式处理（`StreamReader`），适合 LLM token 级推送
-3. Graph 支持分支、并行、循环，满足当前和未来需求
-4. Callback 机制实现 AOP（日志、指标、消息推送）
-5. eino-ext 提供 OpenAI ChatModel 实现，直接对接 DashScope
-
-### 2.3 核心依赖版本
-
-```
-github.com/cloudwego/eino v0.9.9
-github.com/cloudwego/eino-ext/components/model/openai v0.1.13
-```
-
-## 3. Eino 核心概念
-
-### 3.1 Lambda
-
-Lambda 是 Graph 中的可组合函数单元，支持四种模式：
-
-| 模式 | 函数签名 | 构造方法 | 说明 |
-|------|---------|---------|------|
-| Invoke | `I → O` | `compose.InvokableLambda()` | 同步调用 |
-| Stream | `I → StreamReader[O]` | `compose.StreamableLambda()` | 流式输出 |
-| Collect | `StreamReader[I] → O` | `compose.CollectableLambda()` | 流式输入 |
-| Transform | `StreamReader[I] → StreamReader[O]` | `compose.TransformableLambda()` | 双向流式 |
-
-**返回类型**：所有 Lambda 构造函数返回 `*compose.Lambda`。
-
-### 3.2 Graph
-
-Graph 是有向无环图（DAG）编排器，支持：
-- **节点**：Lambda、ChatModel、ToolsNode 等
-- **边**：`g.AddEdge(from, to)` 定义数据流向
-- **分支**：`g.AddBranch()` 条件路由
-- **State**：`compose.WithGenLocalState()` 跨节点共享状态
-
-```go
-g := compose.NewGraph[PipelineInput, PipelineOutput]()
-g.AddLambdaNode("stt", sttLambda)
-g.AddChatModelNode("llm", chatModel)
-g.AddEdge(compose.START, "stt")
-g.AddEdge("stt", "llm")
-g.AddEdge("llm", compose.END)
-
-runnable, err := g.Compile(ctx)
-output, err := runnable.Invoke(ctx, input)   // 同步调用
-stream, err := runnable.Stream(ctx, input)    // 流式调用
-```
-
-### 3.3 ChatModel
-
-ChatModel 是 LLM 组件抽象，接口定义：
-
-```go
-type BaseChatModel interface {
-    Generate(ctx, []*schema.Message, ...Option) (*schema.Message, error)
-    Stream(ctx, []*schema.Message, ...Option) (*schema.StreamReader[*schema.Message], error)
-}
-```
-
-CamTalk 使用 `eino-ext/components/model/openai` 实现，通过 `BaseURL` 对接 DashScope：
-
-```go
-chatModel, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
-    APIKey:  cfg.AI.LLM.APIKey,
-    Model:   cfg.AI.LLM.Model,
-    BaseURL: cfg.AI.LLM.Endpoint, // "https://dashscope.aliyuncs.com/compatible-mode/v1"
-})
-```
-
-### 3.4 StreamReader
-
-`schema.StreamReader[T]` 是 Eino 的流式数据抽象：
-- `sr.Recv()` 读取一帧，`io.EOF` 表示流结束
-- `schema.Pipe[T](bufSize)` 创建 `StreamReader` + `StreamWriter` 对
-- 框架自动处理 `T ↔ StreamReader[T]` 的转换（装箱/concat）
-
-### 3.5 Callback
-
-Callback 是 Eino 的 AOP 机制，支持节点生命周期钩子：
-
-```go
-type Handler interface {
-    OnStart(ctx, *RunInfo, CallbackInput) context.Context
-    OnEnd(ctx, *RunInfo, CallbackOutput) context.Context
-    OnError(ctx, *RunInfo, error) context.Context
-    OnStartWithStreamInput(ctx, *RunInfo, *StreamReader[CallbackInput]) context.Context
-    OnEndWithStreamOutput(ctx, *RunInfo, *StreamReader[CallbackOutput]) context.Context
-}
-```
-
-CamTalk 使用 `utils/callbacks.NewHandlerHelper()` 构建 typed handler：
-- `ModelCallbackHandler.OnEndWithStreamOutput`：逐 token 推送 `llm_chunk`
-
-### 3.6 State
-
-Graph 全局状态，通过 `WithGenLocalState` 注册：
-
-```go
-type PipelineState struct {
-    FullResponse    strings.Builder
-    TranscribedText string
-    TokenUsage      *TokenUsage
-}
-
-g := compose.NewGraph[I, O](compose.WithGenLocalState(func(ctx context.Context) *PipelineState {
-    return &PipelineState{}
-}))
-```
-
-节点通过 `compose.ProcessState` 读写 State。
-
-## 4. CamTalk Graph 设计
-
-### 4.1 拓扑
-
-```
-START → STT → History → ChatModel → Splitter → TTS → Done → END
-```
-
-| 节点 | 类型 | 输入 → 输出 | 职责 |
-|------|------|------------|------|
-| STT | InvokableLambda | `PipelineInput → STTOutput` | 语音识别，写入 State |
-| History | InvokableLambda | `STTOutput → []*schema.Message` | 组装提示词和历史 |
-| ChatModel | ChatModel（原生） | `[]*schema.Message → StreamReader[*Message]` | LLM 流式推理 |
-| Splitter | TransformableLambda | `StreamReader[string] → StreamReader[[]string]` | 句子切分 |
-| TTS | InvokableLambda | `[]string → struct{}` | 语音合成，推送音频 |
-| Done | InvokableLambda | `struct{} → PipelineOutput` | 发送 llm_done |
-
-### 4.2 流式模式
-
-Graph 使用 **Stream 模式**调用：
-- 内部所有节点以 Transform 模式运行
-- ChatModel 的 `Stream()` 方法实现真正的 token 级流式
-- 适配器消费 `StreamReader[PipelineOutput]` 触发整条链路
-
-### 4.3 消息推送机制
-
-| 消息 | 推送方式 | 时机 |
-|------|---------|------|
-| `stt_result` | Lambda 内部直接调用 Sender | STT 完成后 |
-| `llm_chunk` | Callback `OnEndWithStreamOutput` | ChatModel 逐 token |
-| `tts_audio` | Lambda 内部直接调用 Sender | TTS 逐句合成 |
-| `llm_done` | Lambda 内部直接调用 Sender | Done 节点执行时 |
-
-**Context 注入**：Sender、RequestID、SessionID、PipelineState 通过 `context.WithValue` 传递。
-
-### 4.4 多模态支持
-
-History 节点将图片构建为 `schema.Message.UserInputMultiContent`：
-
-```go
-systemMsg.UserInputMultiContent = []schema.MessageInputPart{
-    {
-        Type: schema.ChatMessagePartTypeImageURL,
-        Image: &schema.MessageInputImage{
-            MessagePartCommon: schema.MessagePartCommon{
-                Base64Data: &base64Str,
-                MIMEType:   "image/jpeg",
-            },
-            Detail: schema.ImageURLDetailAuto,
-        },
-    },
-}
-```
-
-## 5. 目录结构
-
-```
-backend/internal/eino/
-├── types.go           # PipelineInput/Output、STTOutput、TokenUsage
-├── state.go           # PipelineState（跨节点状态）
-├── callback.go        # Callback handler（LLM token 推送）
-├── graph.go           # Graph 构建与编译
-├── adapter.go         # EinoOrchestrator（Orchestrator 接口适配器）
-├── nodes_stt.go       # STT Lambda
-├── nodes_history.go   # 历史组装 Lambda
-├── nodes_splitter.go  # 句子分割 Transform Lambda
-├── nodes_tts.go       # TTS Lambda
-├── nodes_done.go      # Done Lambda
-└── graph_test.go      # 单元测试
-```
-
-## 6. 注意事项
-
-### 6.1 值类型 vs 指针类型
-
-Graph 泛型参数必须使用值类型（`PipelineInput`/`PipelineOutput`），所有 Lambda 的输入输出也使用值类型。框架在 Transform 模式下会自动处理 `T` 和 `StreamReader[T]` 的转换。
-
-### 6.2 Callback 运行时传入
-
-Callback 通过 `Stream()` 的 option 传入，不在 `Compile()` 时注册：
-
-```go
-streamReader, err := runnable.Stream(ctx, input, compose.WithCallbacks(handler))
-```
-
-### 6.3 eino-ext 与 DashScope 兼容性
-
-eino-ext OpenAI ChatModel 通过 `BaseURL` 对接 DashScope 兼容接口。需注意：
-- 多模态图片使用 `Base64Data` + `MIMEType` 格式
-- `Timeout` 控制单次请求超时
-- 流式输出通过 `Stream()` 方法获取 `StreamReader[*schema.Message]`
-
-### 6.4 框架自动类型转换
-
-Eino 框架在编排场景中自动处理以下转换：
-- **T → StreamReader[T]**：将完整值装箱为单帧流（非流式 → 假流式）
-- **StreamReader[T] → T**：将流 concat 为完整值（流式 → 非流式）
-
-这使得不同流式模式的节点可以无缝连接。
diff --git a/docs/13-令牌桶限流设计.md b/docs/11-令牌桶限流.md
similarity index 59%
rename from docs/13-令牌桶限流设计.md
rename to docs/11-令牌桶限流.md
index 21acc45..608dcc0 100644
--- a/docs/13-令牌桶限流设计.md
+++ b/docs/11-令牌桶限流.md
@@ -492,6 +492,321 @@ type SlidingWindowLimiter struct {
 - **限流触发率突增**：可能表示异常流量或攻击
 - **单用户持续被限流**：可能表示客户端 bug（死循环请求）
 
+## 实际实现要点
+
+### 文件结构
+
+```
+backend/internal/ratelimit/
+├── limiter.go              # Limiter 接口定义
+├── bucket.go               # 内存令牌桶实现 (MemoryLimiter + TokenBucket)
+├── bucket_test.go          # 内存令牌桶单元测试（11 个测试用例）
+├── redis_bucket.go         # Redis 令牌桶实现（Lua 脚本）
+├── redis_bucket_test.go    # Redis 令牌桶单元测试
+└── middleware.go           # Gin 中间件实现
+```
+
+### TokenBucket 实现细节
+
+**核心数据结构**（`bucket.go:12-18`）：
+
+```go
+type TokenBucket struct {
+    capacity   int           // 桶容量
+    rate       float64       // 每秒填充令牌数
+    tokens     float64       // 当前令牌数（浮点数支持小数令牌）
+    lastRefill time.Time     // 上次填充时间
+    mu         sync.Mutex    // 保护并发访问
+}
+```
+
+**并发安全**（`bucket.go:31-56`）：
+- 每个桶内部使用 `sync.Mutex` 保护 `tokens` 和 `lastRefill` 字段
+- `allow()` 方法的"读取-计算-回写"操作原子执行
+- 桶 map 使用 `sync.RWMutex` 保护，读多写少优化（`bucket.go:62`）
+- 双重检查锁（`bucket.go:106-113`）：先尝试读锁获取桶，不存在时升级写锁创建
+
+**内存回收机制**（`bucket.go:132-161`）：
+- 后台 goroutine 每 10 分钟扫描一次（`cleanup()` 方法）
+- 删除超过 10 分钟无活动的桶（`lastRefill` 超时判断）
+- 通过 `done` channel 和 `sync.Once` 保证优雅停止
+
+**惰性创建**（`bucket.go:95-121`）：
+- 用户首次请求时才创建桶，避免预分配内存
+- `getOrCreateBucket()` 使用读写锁分离，优化热路径性能
+
+### Gin 中间件实现
+
+**实际代码**（`middleware.go:12-42`）：
+
+```go
+func Middleware(limiter Limiter, keyFunc func(*gin.Context) string) gin.HandlerFunc {
+    return func(c *gin.Context) {
+        if limiter == nil {
+            c.Next()
+            return
+        }
+
+        key := keyFunc(c)
+        if key == "" {
+            // key 为空时跳过限流
+            c.Next()
+            return
+        }
+
+        allowed, retryAfter := limiter.Allow(c.Request.Context(), key)
+
+        if !allowed {
+            // 设置 Retry-After header（秒）
+            c.Header("Retry-After", fmt.Sprintf("%d", int(retryAfter.Seconds()+0.5)))
+
+            c.JSON(http.StatusTooManyRequests, gin.H{
+                "code":    "RATE_LIMITED",
+                "message": fmt.Sprintf("too many requests, retry after %s", retryAfter.Round(1)),
+            })
+            c.Abort()
+            return
+        }
+
+        c.Next()
+    }
+}
+```
+
+**设计要点**：
+- `nil` limiter 自动跳过限流（支持配置关闭）
+- 空 key 跳过限流（支持匿名端点）
+- `retryAfter` 向上取整到秒（符合 HTTP 标准）
+- `c.Abort()` 阻止后续 handler 执行
+
+### WebSocket 限流接入
+
+**实际接入点**（`internal/ws/handler.go:230-240`）：
+
+```go
+case "query":
+    // ... 解析消息 ...
+
+    // 限流检查
+    if limiter != nil {
+        key := fmt.Sprintf("%s:query", userID)
+        allowed, retryAfter := limiter.Allow(context.Background(), key)
+        if !allowed {
+            logger.Log.Warnw("rate limited", "user_id", userID, "retry_after", retryAfter)
+            errors.SendWSError(client, errors.CodeRateLimited, msg.RequestID,
+                fmt.Errorf("rate limited, retry after %s", retryAfter.Round(time.Second)))
+            continue
+        }
+    }
+
+    // ... 继续处理 query ...
+```
+
+**设计要点**：
+- key 格式：`userID:query`（用户级限流）
+- 拒绝时发送 `RATE_LIMITED` 错误到客户端
+- 记录警告日志（便于监控告警）
+- 不阻塞其他消息类型（`ping`/`config`/`interrupt` 不限流）
+
+### 配置加载与依赖注入
+
+**配置文件路径**：
+- 基础配置：`backend/config/config.yaml`
+- 开发环境：`backend/config/config.dev.yaml`
+- 生产环境：`backend/config/config.prod.yaml`
+
+**实际配置示例**（`config.yaml:63-76`）：
+
+```yaml
+ratelimit:
+  enabled: false              # 是否启用限流
+  # WebSocket query 消息限流（核心，控制 AI 成本）
+  query:
+    capacity: 10              # 突发容量：允许连续发 10 个 query
+    rate: 0.2                 # 填充速率：每 5 秒补充 1 个令牌
+  # REST API 登录限流（防暴力破解）
+  login:
+    capacity: 5               # 突发容量：允许连续 5 次登录尝试
+    rate: 0.1                 # 填充速率：每 10 秒补充 1 次
+  # REST API 注册限流
+  register:
+    capacity: 3               # 突发容量：允许连续 3 次注册
+    rate: 0.05                # 填充速率：每 20 秒补充 1 次
+```
+
+**依赖注入实现**（`cmd/server/main.go:200-214`）：
+
+```go
+// 初始化限流器
+var limiter ratelimit.Limiter
+if cfg.RateLimit.Enabled {
+    if rdb != nil {
+        // 多实例：使用 Redis 令牌桶
+        limiter = ratelimit.NewRedisLimiter(rdb, cfg.RateLimit)
+        logger.Log.Info("rate limiter initialized with Redis backend")
+    } else {
+        // 单实例：使用内存令牌桶
+        limiter = ratelimit.NewMemoryLimiter(cfg.RateLimit)
+        logger.Log.Info("rate limiter initialized with in-memory backend")
+    }
+    defer limiter.Stop()
+} else {
+    logger.Log.Info("rate limiter disabled")
+}
+```
+
+**自动选择策略**：
+1. 配置关闭（`enabled: false`）→ `limiter = nil`（完全跳过限流）
+2. Redis 可用 → `NewRedisLimiter`（分布式一致）
+3. Redis 不可用 → `NewMemoryLimiter`（单实例零依赖）
+
+**注入到模块**：
+
+```go
+// WebSocket Handler
+r.GET("/ws", ws.ServeWS(sessionMgr, orch, cfg, tokenMgr, limiter))
+
+// REST API
+authHandler.RegisterRoutes(apiGroup, limiter)
+```
+
+### 实际测试用例
+
+**内存令牌桶测试**（`bucket_test.go`，11 个用例）：
+
+| 测试用例 | 验证内容 |
+|---------|---------|
+| `TestTokenBucket_Allow_FirstRequest` | 首次请求通过 |
+| `TestTokenBucket_Allow_ConsumeUntilEmpty` | 连续消耗至桶空 |
+| `TestTokenBucket_Allow_RetryAfterCorrect` | `retryAfter` 计算准确性 |
+| `TestTokenBucket_Allow_RefillAfterWait` | 等待后令牌补充 |
+| `TestTokenBucket_Allow_CapacityLimit` | 桶容量上限限制 |
+| `TestTokenBucket_Allow_ConcurrentSafe` | 100 并发请求正确性 |
+| `TestTokenBucket_Allow_ZeroCapacity` | 边界：`capacity=0` |
+| `TestTokenBucket_Allow_ZeroRate` | 边界：`rate=0` |
+| `TestMemoryLimiter_Allow_DifferentKeys` | 不同用户隔离 |
+| `TestMemoryLimiter_Cleanup` | 不活跃桶自动清理 |
+| `TestMemoryLimiter_Stop` | 多次 `Stop()` 不 panic |
+
+**中间件测试**（`middleware_test.go`，7 个用例）：
+
+| 测试用例 | 验证内容 |
+|---------|---------|
+| `TestMiddleware_Allow` | 允许时正常响应 |
+| `TestMiddleware_Deny` | 拒绝时返回 429 + `Retry-After` header |
+| `TestMiddleware_NilLimiter` | `nil` limiter 放行 |
+| `TestMiddleware_EmptyKey` | 空 key 放行 |
+| `TestMiddleware_KeyFunc` | `keyFunc` 正确提取 key |
+| `TestMiddleware_RetryAfterRounding` | `retryAfter` 向上取整 |
+
+**并发安全性验证**（`bucket_test.go:83-107`）：
+
+```go
+func TestTokenBucket_Allow_ConcurrentSafe(t *testing.T) {
+    bucket := newTokenBucket(100, 10.0)
+    var wg sync.WaitGroup
+    successCount := 0
+    var mu sync.Mutex
+
+    // 100 个并发请求
+    for i := 0; i < 100; i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            allowed, _ := bucket.allow()
+            if allowed {
+                mu.Lock()
+                successCount++
+                mu.Unlock()
+            }
+        }()
+    }
+
+    wg.Wait()
+
+    // 应该正好 100 个成功（桶容量为 100）
+    assert.Equal(t, 100, successCount)
+}
+```
+
+### Redis Lua 脚本实现
+
+**实际脚本**（`redis_bucket.go:15-53`）：
+
+```lua
+-- KEYS[1] = 限流 key
+-- ARGV[1] = capacity（桶容量）
+-- ARGV[2] = rate（每秒填充数）
+-- ARGV[3] = now（当前时间戳，秒，浮点）
+-- ARGV[4] = ttl（key 过期时间，秒）
+
+local key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local rate = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local ttl = tonumber(ARGV[4])
+
+local data = redis.call('HMGET', key, 'tokens', 'last_refill')
+local tokens = tonumber(data[1]) or capacity
+local last_refill = tonumber(data[2]) or now
+
+-- 计算新令牌
+local elapsed = math.max(0, now - last_refill)
+tokens = math.min(capacity, tokens + elapsed * rate)
+
+local allowed = 0
+local retry_after = 0
+
+if tokens >= 1 then
+    tokens = tokens - 1
+    allowed = 1
+else
+    if rate == 0 then
+        retry_after = 86400  -- 24小时
+    else
+        retry_after = (1 - tokens) / rate
+    end
+end
+
+-- 回写状态
+redis.call('HMSET', key, 'tokens', tokens, 'last_refill', now)
+redis.call('EXPIRE', key, ttl)
+
+return {allowed, tostring(retry_after)}
+```
+
+**设计要点**：
+- 使用 Hash 存储两个字段：`tokens`（当前令牌数）+ `last_refill`（上次填充时间）
+- 原子性：整个脚本在 Redis 单线程中执行，无竞态条件
+- 自动过期：每次操作设置 TTL（默认 10 分钟），无需手动清理
+- 与内存实现算法一致（便于单元测试验证行为等价性）
+
+### 编译期接口检查
+
+**接口契约**（`bucket.go:172`，`middleware_test.go:31`）：
+
+```go
+// 确保 MemoryLimiter 实现了 Limiter 接口
+var _ Limiter = (*MemoryLimiter)(nil)
+
+// 确保 mockLimiter 实现了 Limiter 接口
+var _ Limiter = (*mockLimiter)(nil)
+```
+
+编译器会在类型不匹配时报错，避免运行时接口错误。
+
+### 环境变量覆盖
+
+配置文件中的 `ratelimit` 配置可通过环境变量覆盖：
+
+```bash
+export CAMTALK_RATELIMIT_ENABLED=true
+export CAMTALK_RATELIMIT_QUERY_CAPACITY=20
+export CAMTALK_RATELIMIT_QUERY_RATE=0.5
+```
+
+环境变量优先级高于配置文件（Viper 配置绑定）。
+
 ## 参考资料
 
 - [Token Bucket 算法](https://en.wikipedia.org/wiki/Token_bucket)
diff --git a/docs/12-鉴权体系设计.md b/docs/12-鉴权体系设计.md
deleted file mode 100644
index e59d231..0000000
--- a/docs/12-鉴权体系设计.md
+++ /dev/null
@@ -1,544 +0,0 @@
-# 鉴权体系设计
-
-## 概述
-
-CamTalk 采用 JWT 双 token 轮转认证机制，结合 bcrypt 密码哈希和 Refresh Token Rotation 安全策略，实现安全可靠的用户认证体系。
-
-**设计原则**：
-- **安全性**：access_token 短有效期（15 分钟），refresh_token 支持轮转防重放
-- **可靠性**：Refresh Token Rotation 机制，检测复用时自动吊销用户所有令牌
-- **可扩展性**：Repository 接口隔离存储层，支持内存和 PostgreSQL 双实现
-
-## 整体架构
-
-```mermaid
-graph TB
-    subgraph Client["客户端"]
-        Browser["浏览器"]
-    end
-
-    subgraph AuthModule["Auth 模块"]
-        Service["AuthService<br/>Register / Login / Refresh / Logout"]
-        TokenMgr["TokenManager<br/>JWT 生成与验证"]
-        Middleware["AuthMiddleware<br/>Gin 中间件"]
-        Password["PasswordUtil<br/>bcrypt 哈希"]
-    end
-
-    subgraph Storage["存储层"]
-        UserRepo["UserRepository<br/>用户数据"]
-        TokenStore["RefreshToken 存储<br/>SHA256 哈希"]
-    end
-
-    Browser -->|"POST /api/auth/*"| Service
-    Service --> TokenMgr
-    Service --> Password
-    Service --> UserRepo
-    Service --> TokenStore
-    Middleware -->|"校验 access_token"| TokenMgr
-    Middleware -->|"写入 user_id/username"| GinContext["Gin Context"]
-```
-
-## 核心组件
-
-### 1. JWT 令牌管理（TokenManager）
-
-**文件位置**：`backend/internal/auth/jwt.go`
-
-#### Claims 结构
-
-```go
-type Claims struct {
-    UserID    string `json:"user_id"`
-    Username  string `json:"username"`
-    TokenType string `json:"token_type"` // "access" | "refresh"
-    jwt.RegisteredClaims
-}
-```
-
-**字段说明**：
-- `UserID`：用户唯一标识（UUID）
-- `Username`：用户名
-- `TokenType`：令牌类型，用于区分 access 和 refresh token
-- `RegisteredClaims`：JWT 标准声明（ExpiresAt, IssuedAt, Issuer, ID）
-
-#### TokenManager 配置
-
-```go
-type TokenManager struct {
-    secret     []byte        // JWT 签名密钥（HS256）
-    accessTTL  time.Duration // access_token 有效期（默认 15 分钟）
-    refreshTTL time.Duration // refresh_token 有效期（默认 7 天）
-}
-
-func NewTokenManager(secret string, accessTTL, refreshTTL time.Duration) *TokenManager
-```
-
-#### 令牌生成
-
-```go
-func (tm *TokenManager) GeneratePair(userID, username string) (access, refresh string, err error)
-```
-
-**生成逻辑**：
-1. **access_token**：
-   - 签名算法：HS256
-   - 有效期：15 分钟
-   - 包含：UserID, Username, TokenType="access", ExpiresAt, IssuedAt, Issuer="camtalk"
-
-2. **refresh_token**：
-   - 签名算法：HS256
-   - 有效期：7 天
-   - 包含：UserID, Username, TokenType="refresh", ID=UUID（用于 DB 关联）, ExpiresAt, IssuedAt, Issuer="camtalk"
-
-#### 令牌验证
-
-```go
-func (tm *TokenManager) ValidateAccess(tokenStr string) (*Claims, error)
-func (tm *TokenManager) ValidateRefresh(tokenStr string) (*Claims, error)
-```
-
-**验证逻辑**：
-1. 解析 JWT，验证签名算法为 HMAC
-2. 验证签名是否有效
-3. 验证令牌是否过期
-4. 验证 TokenType 是否匹配（access 或 refresh）
-5. 返回 Claims 或错误
-
-#### Token 哈希
-
-```go
-func HashToken(token string) string
-```
-
-**用途**：对 refresh_token 做 SHA256 哈希后存储到数据库，避免直接存储原始 token。
-
-### 2. 密码处理（PasswordUtil）
-
-**文件位置**：`backend/internal/auth/password.go`
-
-#### 密码哈希
-
-```go
-func HashPassword(password string) (string, error)
-```
-
-**实现**：
-- 算法：bcrypt
-- Cost：10（2^10 次迭代）
-- 返回：base64 编码的哈希字符串
-
-#### 密码验证
-
-```go
-func CheckPassword(hashedPassword, password string) error
-```
-
-**实现**：
-- 使用 `bcrypt.CompareHashAndPassword` 验证
-- 返回 nil 表示匹配，否则返回错误
-
-### 3. 认证服务（AuthService）
-
-**文件位置**：`backend/internal/auth/service.go`
-
-#### 接口定义
-
-```go
-type Service interface {
-    Register(ctx context.Context, req RegisterRequest) (*AuthResponse, error)
-    Login(ctx context.Context, req LoginRequest) (*AuthResponse, error)
-    Refresh(ctx context.Context, req RefreshRequest) (*AuthResponse, error)
-    Logout(ctx context.Context, userID, refreshToken string) error
-}
-```
-
-#### 注册流程（Register）
-
-```go
-func (s *authService) Register(ctx context.Context, req RegisterRequest) (*AuthResponse, error)
-```
-
-**流程**：
-1. 检查用户名是否已存在（`FindByUsername`）
-2. 如果存在，返回 `ErrUsernameTaken`
-3. 使用 bcrypt 哈希密码（`HashPassword`）
-4. 创建用户记录（`Create`）
-5. 生成 access_token + refresh_token（`GeneratePair`）
-6. 保存 refresh_token 的 SHA256 哈希到数据库（`SaveRefreshToken`）
-7. 返回 `AuthResponse`
-
-**错误处理**：
-- `ErrUsernameTaken`：用户名已存在
-- 数据库错误：透传底层错误
-
-#### 登录流程（Login）
-
-```go
-func (s *authService) Login(ctx context.Context, req LoginRequest) (*AuthResponse, error)
-```
-
-**流程**：
-1. 根据用户名查找用户（`FindByUsername`）
-2. 如果用户不存在，返回 `ErrInvalidCredentials`
-3. 验证密码（`CheckPassword`）
-4. 如果密码错误，返回 `ErrInvalidCredentials`
-5. 生成 access_token + refresh_token（`GeneratePair`）
-6. 保存 refresh_token 的 SHA256 哈希到数据库（`SaveRefreshToken`）
-7. 返回 `AuthResponse`
-
-**错误处理**：
-- `ErrInvalidCredentials`：用户名或密码错误（统一错误信息，防止枚举攻击）
-
-#### 刷新令牌流程（Refresh）— Refresh Token Rotation
-
-```go
-func (s *authService) Refresh(ctx context.Context, req RefreshRequest) (*AuthResponse, error)
-```
-
-**流程**：
-1. 验证 refresh_token 的签名和有效期（`ValidateRefresh`）
-2. 计算 refresh_token 的 SHA256 哈希（`HashToken`）
-3. 在数据库中查找该哈希（`FindRefreshToken`）
-4. **如果哈希不存在**：
-   - JWT 校验已通过但 DB 中不存在 → token 已被 rotation 删除
-   - 这是 **token 复用行为**，属于安全风险
-   - 吊销该用户的所有 refresh_token（`DeleteUserRefreshTokens`）
-   - 返回 `ErrRefreshTokenUsed`
-5. 验证 token 归属的用户与 claims 一致
-6. 删除旧的 refresh_token 哈希（`DeleteRefreshToken`）
-7. 生成新的 access_token + refresh_token（`GeneratePair`）
-8. 保存新的 refresh_token 哈希到数据库（`SaveRefreshToken`）
-9. 查询用户信息（`FindByID`）
-10. 返回 `AuthResponse`
-
-**安全机制**：
-- **Token 轮转**：每次 refresh 都会生成新的 token pair，旧 refresh_token 立即失效
-- **复用检测**：如果检测到已删除的 refresh_token 被复用，立即吊销该用户的所有 refresh_token
-- **强制重新登录**：吊销后，该用户所有设备都需要重新登录
-
-#### 登出流程（Logout）
-
-```go
-func (s *authService) Logout(ctx context.Context, userID, refreshToken string) error
-```
-
-**流程**：
-1. 计算 refresh_token 的 SHA256 哈希（`HashToken`）
-2. 从数据库删除该哈希（`DeleteRefreshToken`）
-
-### 4. Gin 中间件（AuthMiddleware）
-
-**文件位置**：`backend/internal/auth/middleware.go`
-
-```go
-func AuthMiddleware(tokenMgr *TokenManager) gin.HandlerFunc
-```
-
-**功能**：
-1. 从请求头提取 `Authorization: Bearer <token>`
-2. 验证 access_token（`ValidateAccess`）
-3. 如果验证失败，返回 401 Unauthorized
-4. 如果验证成功，将 `user_id` 和 `username` 写入 Gin Context
-5. 调用 `c.Next()` 继续处理请求
-
-**错误响应**：
-```json
-{
-  "code": "INVALID_TOKEN",
-  "message": "missing authorization header"
-}
-```
-
-```json
-{
-  "code": "INVALID_TOKEN",
-  "message": "invalid authorization format"
-}
-```
-
-```json
-{
-  "code": "INVALID_TOKEN",
-  "message": "invalid or expired token"
-}
-```
-
-**Context Key**：
-- `ContextKeyUserID = "user_id"`
-- `ContextKeyUsername = "username"`
-
-**使用示例**：
-```go
-// 在路由中使用中间件
-authorized := r.Group("/api")
-authorized.Use(auth.AuthMiddleware(tokenMgr))
-{
-    authorized.GET("/conversations", handler.ListConversations)
-    authorized.POST("/conversations", handler.CreateConversation)
-}
-```
-
-## 数据模型
-
-### 用户表（users）
-
-```sql
-CREATE TABLE users (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    username VARCHAR(64) UNIQUE NOT NULL,
-    password_hash VARCHAR(255) NOT NULL,
-    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-```
-
-### Refresh Token 表（refresh_tokens）
-
-```sql
-CREATE TABLE refresh_tokens (
-    token_hash VARCHAR(64) PRIMARY KEY,  -- SHA256 哈希
-    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
-    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-
-CREATE INDEX idx_refresh_tokens_user_id ON refresh_tokens(user_id);
-CREATE INDEX idx_refresh_tokens_expires_at ON refresh_tokens(expires_at);
-```
-
-## Repository 接口
-
-### UserRepository
-
-```go
-type UserRepository interface {
-    // Create 创建用户，返回用户 ID
-    Create(ctx context.Context, username, passwordHash string) (string, error)
-
-    // FindByUsername 根据用户名查找用户
-    FindByUsername(ctx context.Context, username string) (*User, error)
-
-    // FindByID 根据 ID 查找用户
-    FindByID(ctx context.Context, id string) (*User, error)
-
-    // SaveRefreshToken 保存 refresh_token 哈希
-    SaveRefreshToken(ctx context.Context, userID, tokenHash string, expiresAt time.Time) error
-
-    // FindRefreshToken 根据 token 哈希查找用户 ID
-    FindRefreshToken(ctx context.Context, tokenHash string) (string, error)
-
-    // DeleteRefreshToken 删除指定的 refresh_token
-    DeleteRefreshToken(ctx context.Context, tokenHash string) error
-
-    // DeleteUserRefreshTokens 删除用户的所有 refresh_token（用于检测复用时吊销）
-    DeleteUserRefreshTokens(ctx context.Context, userID string) error
-}
-```
-
-## 前端集成
-
-### Token 存储
-
-**推荐方案**：
-- `access_token`：存储在内存中（JavaScript 变量）
-- `refresh_token`：存储在 `httpOnly` Cookie 中（防止 XSS 攻击）
-
-**备选方案**（开发环境）：
-- 两者都存储在 `localStorage`（便于调试，但存在 XSS 风险）
-
-### 请求拦截器
-
-```typescript
-// axios 请求拦截器
-api.interceptors.request.use((config) => {
-  const accessToken = getAccessToken();
-  if (accessToken) {
-    config.headers.Authorization = `Bearer ${accessToken}`;
-  }
-  return config;
-});
-
-// axios 响应拦截器
-api.interceptors.response.use(
-  (response) => response,
-  async (error) => {
-    const originalRequest = error.config;
-
-    // 如果是 401 且不是 refresh 请求，尝试刷新 token
-    if (error.response?.status === 401 && !originalRequest._retry) {
-      originalRequest._retry = true;
-
-      try {
-        const refreshToken = getRefreshToken();
-        const response = await api.post('/api/auth/refresh', {
-          refresh_token: refreshToken,
-        });
-
-        const { access_token, refresh_token } = response.data;
-        setAccessToken(access_token);
-        setRefreshToken(refresh_token);
-
-        // 重试原始请求
-        originalRequest.headers.Authorization = `Bearer ${access_token}`;
-        return api(originalRequest);
-      } catch (refreshError) {
-        // 刷新失败，跳转登录页
-        clearTokens();
-        window.location.href = '/login';
-        return Promise.reject(refreshError);
-      }
-    }
-
-    return Promise.reject(error);
-  }
-);
-```
-
-### WebSocket 认证
-
-```typescript
-// 建立 WebSocket 连接时传递 access_token
-const wsUrl = `ws://${window.location.host}/ws?token=${accessToken}&conversation_id=${conversationId}`;
-const ws = new WebSocket(wsUrl);
-
-// 连接失败时（401），触发 token 刷新
-ws.onerror = (error) => {
-  console.error('WebSocket connection failed');
-  // 可能需要刷新 token 后重连
-};
-```
-
-## 安全考虑
-
-### 1. 密码安全
-
-- **bcrypt 算法**：使用 bcrypt 进行密码哈希，cost factor 为 10
-- **盐值自动生成**：bcrypt 自动生成随机盐值，无需手动管理
-- **防彩虹表**：每个密码的哈希值都不同，即使密码相同
-
-### 2. Token 安全
-
-- **短期 access_token**：15 分钟有效期，降低泄露风险
-- **Refresh Token Rotation**：每次 refresh 都生成新 token，旧 token 立即失效
-- **复用检测**：检测到已删除的 refresh_token 被复用时，吊销该用户的所有 token
-- **SHA256 哈希存储**：数据库只存储 refresh_token 的哈希值，不存储原始 token
-
-### 3. 传输安全
-
-- **HTTPS 强制**：生产环境必须使用 HTTPS
-- **同源反代**：通过 Nginx 反向代理（生产）或 Vite proxy（开发）统一前后端到同一域名，浏览器层面无跨域问题
-- **HttpOnly Cookie**：refresh_token 存储在 httpOnly Cookie 中，防止 XSS 攻击
-
-### 4. 防攻击策略
-
-- **防暴力破解**：可选的速率限制（`RATE_LIMITED` 错误码）
-- **防枚举攻击**：登录失败时统一返回 `INVALID_CREDENTIALS`，不区分用户名不存在还是密码错误
-- **防重放攻击**：Refresh Token Rotation 确保每个 refresh_token 只能使用一次
-- **防 Token 泄露**：检测到 token 复用时，立即吊销该用户的所有 token
-
-## 配置说明
-
-### 配置文件
-
-```yaml
-auth:
-  jwt_secret: ""           # JWT 签名密钥（必须通过环境变量设置）
-  access_ttl: 15           # access_token 有效期（分钟）
-  refresh_ttl: 10080       # refresh_token 有效期（分钟，7天）
-```
-
-### 环境变量
-
-| 环境变量 | 说明 | 示例 |
-|---------|------|------|
-| `CAMTALK_AUTH_JWT_SECRET` | JWT 签名密钥（必须） | `$(openssl rand -hex 32)` |
-| `CAMTALK_AUTH_ACCESS_TTL` | access_token 有效期（分钟） | `15` |
-| `CAMTALK_AUTH_REFRESH_TTL` | refresh_token 有效期（分钟） | `10080` |
-
-**安全要求**：
-- `JWT_SECRET` **必须**通过环境变量设置，不能写入配置文件
-- 生产环境使用 `openssl rand -hex 32` 生成随机密钥
-- 密钥长度建议至少 32 字节（256 位）
-
-## 错误码
-
-| 错误码 | HTTP 状态码 | 含义 | 客户端处理 |
-|--------|-----------|------|-----------|
-| `USERNAME_TAKEN` | 409 | 用户名已存在 | 提示换一个用户名 |
-| `INVALID_CREDENTIALS` | 401 | 用户名或密码错误 | 提示检查输入 |
-| `INVALID_TOKEN` | 401 | JWT 无效或已过期 | 尝试 refresh，失败则重新登录 |
-
-## 测试用例
-
-### 单元测试
-
-**文件位置**：`backend/internal/auth/jwt_test.go`, `backend/internal/auth/service_test.go`
-
-**测试覆盖**：
-- Token 生成和验证
-- Token 过期处理
-- Refresh Token Rotation
-- Token 复用检测和吊销
-- 密码哈希和验证
-- 边界条件和错误处理
-
-### 集成测试
-
-**测试场景**：
-- 注册 → 登录 → 访问受保护资源
-- Token 刷新流程
-- Token 过期后自动刷新
-- 并发刷新 token（竞态条件）
-- Token 复用检测和吊销
-
-## 监控指标
-
-### 关键指标
-
-- **登录成功率**：登录成功次数 / 登录总次数
-- **Token 刷新率**：refresh 请求次数 / 总请求数
-- **Token 复用检测**：检测到 token 复用的次数（安全事件）
-- **认证延迟**：JWT 验证的平均耗时
-
-### 告警规则
-
-- **Token 复用检测**：任何 token 复用事件都应触发告警
-- **异常登录失败率**：短时间内大量登录失败可能表示暴力破解攻击
-- **Token 刷新失败率**：refresh 失败率突然上升可能表示系统问题
-
-## 扩展点
-
-### 1. 多设备管理
-
-当前实现支持同一用户在多个设备上登录（每个设备独立的 refresh_token）。可以扩展为：
-- 设备列表管理
-- 单设备登录（踢出其他设备）
-- 设备信任等级
-
-### 2. OAuth 第三方登录
-
-可以扩展 AuthService 支持 OAuth 2.0：
-- Google、GitHub 等第三方登录
-- 绑定/解绑第三方账号
-- 统一的用户身份管理
-
-### 3. 双因素认证（2FA）
-
-可以扩展为：
-- TOTP（基于时间的一次性密码）
-- SMS 验证码
-- 邮箱验证
-
-### 4. 会话管理
-
-可以扩展为：
-- 活跃会话列表
-- 远程登出其他会话
-- 会话过期策略
-
-## 参考资料
-
-- [JWT 规范](https://tools.ietf.org/html/rfc7519)
-- [bcrypt 算法](https://en.wikipedia.org/wiki/Bcrypt)
-- [OWASP 认证备忘录](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)
-- [Refresh Token Rotation](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/)
diff --git a/docs/README.md b/docs/README.md
index 00b707d..8b6be47 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,28 +8,36 @@ CamTalk 是一款多模态实时 AI 视觉对话助手。用户通过摄像头
 |------|------|
 | [01-架构设计](01-架构设计.md) | 系统架构、技术栈、模块设计、数据库、部署架构（含 Mermaid 图） |
 | [02-接口文档](02-接口文档.md) | WebSocket 协议、REST API、AI 服务层、Eino 编排器、Session Manager、配置管理、数据模型、错误码 |
-| [03-技术选型](03-技术选型.md) | 各技术的选型对比与决策理由（含 Eino 框架选型） |
+| [03-技术选型](03-技术选型.md) | 各技术的选型对比与决策理由（含 Eino 框架选型、关键技术术语） |
 | [04-用户故事](04-用户故事.md) | P0/P1/P2 用户故事、验收标准 |
 | [05-语音交互](05-语音交互.md) | VAD → STT → LLM → TTS 全链路、延迟优化 |
 | [06-视觉理解](06-视觉理解.md) | 帧采样策略、图像编码、多模态 LLM 输入机制 |
 | [07-成本控制](07-成本控制.md) | 智能采样、端云协同、模型分级、缓存复用 |
-| [08-功能创意](08-功能创意.md) | 未来功能创意清单 |
-| [09-技术名词解释](09-技术名词解释.md) | 前端/后端/AI 服务/Eino 框架技术名词简明解释 |
-| [10-Eino重构方案](10-Eino重构方案.md) | Eino Graph 替换手写 goroutine 管道的设计方案 |
-| [11-Eino框架技术文档](11-Eino框架技术文档.md) | Eino 框架在 CamTalk 中的使用指南（Graph、Lambda、Callback、State） |
-| [12-鉴权体系设计](12-鉴权体系设计.md) | JWT 双 token 轮转认证、bcrypt 密码哈希、Refresh Token Rotation、安全机制 |
-| [13-令牌桶限流设计](13-令牌桶限流设计.md) | 令牌桶限流算法、内存/Redis 双实现、Gin 中间件、WebSocket query 限流、配置设计 |
+| [08-Eino框架与编排设计](08-Eino框架与编排设计.md) | Eino 框架核心概念、Graph 设计、节点实现、测试策略 |
+| [09-情景切换](09-情景切换.md) | 多情景 AI 角色扮演系统（面试官、英语老师、辩论对手、翻译员、自由对话） |
+| [10-鉴权体系](10-鉴权体系.md) | JWT 双 token 轮转认证、bcrypt 密码哈希、Refresh Token Rotation、安全机制 |
+| [11-令牌桶限流](11-令牌桶限流.md) | 令牌桶限流算法、内存/Redis 双实现、Gin 中间件、WebSocket query 限流 |
 
 
 ## 推荐阅读顺序
 
 1. **01-架构设计** — 理解三层架构、技术栈和模块全貌
 2. **02-接口文档** — 前后端通信契约，实现时的最高依据
-3. **03-技术选型** — 了解为什么选这些技术（含 Eino 框架）
+3. **03-技术选型** — 了解为什么选这些技术（含 Eino 框架、关键技术术语）
 4. **04-用户故事** — 明确功能优先级
 5. **05~07** — 各技术领域的详细设计
-6. **09-技术名词解释** — 遇到不熟悉的名词时查阅
-7. **10~12** — Eino 重构相关（方案、框架文档、实施记录）
-8. **12-鉴权体系设计** — 认证授权机制详细设计（JWT、bcrypt、Refresh Token Rotation）
-9. **13-令牌桶限流设计** — 速率限制设计（令牌桶算法、成本控制、防暴力破解）
+6. **08-Eino框架与编排设计** — Eino 框架核心概念、Graph 编排、节点实现
+7. **09-情景切换** — 多情景 AI 角色扮演系统
+8. **10-鉴权体系** — 认证授权机制详细设计
+9. **11-令牌桶限流** — 速率限制设计
+
+## 功能扩展方向
+
+以下是未来可能的功能创意和扩展方向：
+
+1. **视频录制** — 支持录制对话过程中的视频画面
+2. **对话翻译** — 实时多语言翻译能力
+3. **对话总结** — 自动生成对话摘要和关键点
+4. **手动对话功能** — 支持用户手动触发对话而非自动 VAD
+5. **视频框自定义** — 视频框大小可调整，支持最小化和拖动
 
diff --git a/docs/情景切换功能完整文档.md b/docs/情景切换功能完整文档.md
deleted file mode 100644
index f031465..0000000
--- a/docs/情景切换功能完整文档.md
+++ /dev/null
@@ -1,664 +0,0 @@
-# 情景切换功能实现与修复完整文档
-
-**项目**: CamTalk 多模态实时 AI 视觉对话助手  
-**功能**: 情景切换（模拟面试官、英语老师、辩论对手、同声翻译）  
-**日期**: 2026-06-20  
-**状态**: ✅ 已完成并修复
-
----
-
-## 目录
-
-1. [功能概述](#功能概述)
-2. [实施内容](#实施内容)
-3. [Bug 修复记录](#bug-修复记录)
-4. [测试验证](#测试验证)
-5. [部署指南](#部署指南)
-6. [技术细节](#技术细节)
-7. [后续优化建议](#后续优化建议)
-
----
-
-## 功能概述
-
-### 什么是情景切换？
-
-情景切换功能允许用户选择不同的对话场景，AI 会根据选择的情景扮演不同的角色：
-
-| 情景 | AI 角色 | 主要功能 |
-|------|---------|---------|
-| 🎯 模拟面试官 | 资深面试官 | 提出面试问题，评估候选人能力，给出反馈 |
-| 📚 英语老师 | 英语外教 | 全英文对话，纠正语法错误，引导深入交流 |
-| ⚔️ 辩论对手 | 辩论选手 | 站在反方立场，用逻辑和证据反驳观点 |
-| 🌐 同声翻译 | 翻译员 | 实时中英互译，口语化翻译，无额外解释 |
-| 💬 自由对话 | 视觉助手 | 通用视觉对话助手（默认） |
-
-### 核心功能
-
-1. **情景首句引导**：切换情景后，AI 自动发送第一句话引导用户进入角色
-2. **情景提示卡片**：对话顶部显示当前情景模式的蓝色提示卡片
-3. **增强 System Prompt**：每个情景有详细的角色定位、交互规则和约束
-4. **多语言支持**：完整支持中文、英文、日文界面
-
----
-
-## 实施内容
-
-### 后端实现
-
-#### 1. 情景 Prompt 定义
-
-**文件**: `backend/internal/ai/llm/scenarios.go`
-
-**变更内容**：
-- 扩展 `scenarioPrompt` 结构体，新增首句引导字段（GreetingZH/EN/JA）
-- 增强所有情景的 System Prompt（添加角色定位、交互规则、约束）
-- 新增函数 `GetScenarioGreeting(scenarioID, language string) string`
-
-**示例 Prompt**（面试官）：
-```go
-"interviewer": {
-    ZH: `你是一位资深面试官。你通过摄像头观察面试者...
-
-【角色定位】
-- 你是面试官，不是助手或顾问
-- 你的目标是评估候选人的能力
-- 保持专业、客观、礼貌
-
-【交互规则】
-1. 每次只问一个问题，等用户回答后再追问
-2. 问题要有层次：自我介绍 → 专业问题 → 情景题
-3. 对用户的回答给出简短点评，然后追问
-...`,
-    GreetingZH: "你好！我是今天的面试官。让我们先从自我介绍开始...",
-}
-```
-
-#### 2. 首句引导推送
-
-**文件**: `backend/internal/ws/handler.go`
-
-**变更内容**：
-在处理 `config` 消息时，如果切换到非自由对话情景，自动返回首句引导：
-
-```go
-case "config":
-    // ... 更新配置 ...
-    
-    // 如果切换了情景（非自由对话），返回首句引导
-    if scenarioID != "" && scenarioID != "free_chat" {
-        greeting := llm.GetScenarioGreeting(scenarioID, sess.Config.Language)
-        if greeting != "" {
-            // 发送 llm_chunk 和 llm_done 消息
-            // 追加到历史记录
-        }
-    }
-```
-
-**效果**：用户切换情景后，AI 立即自动说出首句，无需等待用户发送消息。
-
-#### 3. State 初始化修复（关键 Bug 修复）
-
-**文件**: `backend/internal/eino/adapter.go`
-
-**问题**：`genLocalState()` 创建的是空 State，所有字段都是零值，导致 `state.Scenario = ""`
-
-**修复**：
-```go
-// ✅ 修复：从 input 复制元数据到 state
-state := genLocalState(ctx)
-state.SessionID = input.SessionID
-state.RequestID = input.RequestID
-state.ImageData = input.ImageData
-state.Scenario = input.Scenario      // ⬅️ 关键修复
-state.Language = input.Language
-state.DetailLevel = sess.Config.DetailLevel
-state.TTSEnabled = input.TTSEnabled
-ctx = WithPipelineState(ctx, state)
-```
-
----
-
-### 前端实现
-
-#### 1. 情景提示卡片
-
-**文件**: `frontend/src/components/ChatPanel/index.tsx`
-
-**变更内容**：
-在对话列表顶部（非空状态 + 非自由对话模式）添加情景提示卡片：
-
-```tsx
-{messages.length > 0 && !isFreeChat && (
-  <div className="chat-panel__scenario-hint">
-    <div className="scenario-hint-card">
-      <span className="scenario-hint-card__icon">
-        {scenarios.find(s => s.id === activeScenario)?.icon}
-      </span>
-      <div className="scenario-hint-card__text">
-        <strong>{t(scenarios.find(s => s.id === activeScenario)?.nameKey || "")}</strong>
-        <p>{t(`scenario.${activeScenario}.hint`)}</p>
-      </div>
-    </div>
-  </div>
-)}
-```
-
-**显示效果**：
-- 蓝色渐变背景（135deg 从蓝到紫）
-- 左侧大图标 + 右侧标题和说明
-- 最大宽度 520px，响应式布局
-- 柔和阴影和半透明边框
-
-#### 2. WebSocket 消息修复（关键 Bug 修复）
-
-**文件**: `frontend/src/hooks/useVisionSession.ts`
-
-**问题**：发送 config 消息时缺少 `scenario` 字段，导致后端无法接收到情景切换信息
-
-**修复位置 1**（连接成功时发送初始配置）：
-```typescript
-// ✅ 修复：添加 scenario 字段
-send({
-  type: "config",
-  payload: {
-    tts_enabled: config.ttsEnabled,
-    detail_level: config.detailLevel,
-    language: config.language,
-    scenario: config.scenario,  // ⬅️ 关键修复
-  },
-});
-```
-
-**修复位置 2**（updateConfig 函数）：
-```typescript
-// ✅ 修复：添加 scenario 字段
-send({
-  type: "config",
-  payload: {
-    tts_enabled: next.ttsEnabled,
-    detail_level: next.detailLevel,
-    language: next.language,
-    scenario: next.scenario,  // ⬅️ 关键修复
-  },
-});
-```
-
-#### 3. 样式实现
-
-**文件**: `frontend/src/App.css`
-
-新增情景提示卡片样式：
-```css
-.scenario-hint-card {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  padding: 12px 16px;
-  border-radius: var(--radius-sm);
-  background: linear-gradient(135deg, rgba(59, 130, 246, 0.08) 0%, rgba(99, 102, 241, 0.08) 100%);
-  border: 1px solid rgba(59, 130, 246, 0.2);
-  box-shadow: 0 2px 8px rgba(59, 130, 246, 0.06);
-}
-```
-
-#### 4. 多语言翻译
-
-**文件**: `frontend/src/lib/i18n/{zh-CN,en-US,ja-JP}.ts`
-
-新增翻译 key：
-```typescript
-"scenario.interviewer.hint": "AI 会扮演面试官，逐步提出专业问题并点评你的回答",
-"scenario.englishTeacher.hint": "AI 会用英语对话，纠正语法错误并引导深入交流",
-"scenario.debate.hint": "AI 会站在反方立场，用逻辑和证据反驳你的观点",
-"scenario.interpreter.hint": "AI 会实时翻译你的话（中英互译），无解释评论",
-```
-
----
-
-## Bug 修复记录
-
-### Bug #1：后端 State 未初始化 Scenario
-
-**严重性**: 🔴 Critical（核心功能完全失效）
-
-**症状**：
-- 切换到任何情景后，AI 仍使用默认通用助手 Prompt
-- AI 回答："我是通义千问，阿里巴巴集团研发的超大规模语言模型..."
-- 完全不遵循情景角色设定
-
-**根因**：
-`backend/internal/eino/adapter.go` 中，`genLocalState()` 创建的是空 State：
-```go
-❌ ctx = WithPipelineState(ctx, genLocalState(ctx))
-```
-
-导致 `state.Scenario = ""`（空字符串），`nodes_history.go` 读取到空值后使用默认 Prompt。
-
-**数据流分析**：
-```
-input.Scenario = "interviewer" 
-  ↓
-❌ state.Scenario = ""  (未初始化！)
-  ↓
-nodes_history.go 读取到 ""
-  ↓
-llm.GetScenarioPrompt("", "zh-CN") 返回 ""
-  ↓
-使用默认 Prompt → AI 回答 "我是通义千问..."
-```
-
-**修复**：
-从 `PipelineInput` 复制元数据到 `PipelineState`：
-```go
-✅ state := genLocalState(ctx)
-   state.Scenario = input.Scenario  // 关键修复
-   state.Language = input.Language
-   state.ImageData = input.ImageData
-   // ... 复制其他字段
-   ctx = WithPipelineState(ctx, state)
-```
-
----
-
-### Bug #2：前端未发送 scenario 字段
-
-**严重性**: 🔴 Critical（前后端数据流断层）
-
-**症状**：
-- 后端日志显示：`config updated scenario=""`
-- 会话配置中 scenario 未更新，始终为默认值 `free_chat`
-- WebSocket 消息缺少 scenario 字段
-
-**根因**：
-`frontend/src/hooks/useVisionSession.ts` 发送 config 消息时缺少 `scenario` 字段：
-```typescript
-❌ send({
-  type: "config",
-  payload: {
-    tts_enabled: config.ttsEnabled,
-    detail_level: config.detailLevel,
-    language: config.language,
-    // 缺少 scenario: config.scenario
-  },
-});
-```
-
-**修复**：
-在两处发送 config 的地方添加 `scenario` 字段（第 128 行和第 168 行）。
-
----
-
-### 完整数据流（修复后）
-
-```
-用户切换情景到"模拟面试官"
-  ↓
-前端 updateConfig({scenario: "interviewer"})
-  ↓
-✅ 发送 WebSocket: {type: "config", payload: {scenario: "interviewer"}}
-  ↓
-后端 handler.go 接收并保存
-  ↓
-sess.Config.Scenario = "interviewer"
-  ↓
-用户发送消息 "你是谁？"
-  ↓
-buildPipelineInput() → input.Scenario = "interviewer"
-  ↓
-✅ adapter.go 复制：state.Scenario = input.Scenario
-  ↓
-nodes_history.go 读取 state.Scenario = "interviewer"
-  ↓
-llm.GetScenarioPrompt("interviewer", "zh-CN")
-  ↓
-返回："你是一位资深面试官..."
-  ↓
-llm.BuildSystemPrompt(..., scenarioPrompt)
-  ↓
-注入到 ChatModel System Message
-  ↓
-LLM 生成回复："我是今天的面试官..."
-  ↓
-✅ 情景生效！
-```
-
----
-
-## 测试验证
-
-### 编译验证
-
-✅ **后端**：
-```bash
-cd backend && go build -o /tmp/camtalk_fix ./cmd/server
-# 产物：48MB，无编译错误
-```
-
-✅ **前端**：
-```bash
-cd frontend && npm run lint
-# ESLint 检查通过（无新增错误）
-```
-
----
-
-### 功能测试清单
-
-| 测试项 | 操作步骤 | 预期结果 | 验证方法 |
-|--------|---------|---------|---------|
-| **首句引导** | 切换到"模拟面试官" | AI 自动说："你好！我是今天的面试官..." | 观察聊天框 |
-| **情景生效** | 问 "你是谁？" | AI 回答："我是今天的面试官..." | 观察回复内容 |
-| **提示卡片** | 发送一条消息后查看顶部 | 显示蓝色卡片："🎯 模拟面试官 \| AI 会扮演面试官..." | 观察 UI |
-| **语言联动** | 切换到"英语老师" | 语言自动切换到 en-US，AI 用英语回复 | 观察配置和回复 |
-| **持久化** | 切换情景后刷新页面 | 情景配置保持，首句仍在历史中 | 刷新浏览器 |
-| **多情景** | 依次测试所有情景 | 每个情景 AI 回复风格明显不同 | 对比回复 |
-
----
-
-### 日志验证
-
-**查看日志**：
-```bash
-tail -f /tmp/camtalk_server.log | grep -E "config updated|历史组装完成"
-```
-
-**修复前**（Bug）：
-```
-config updated session=xxx scenario=""           ← ❌ 空字符串
-历史组装完成 ... scenario=free_chat               ← ❌ 始终是默认值
-```
-
-**修复后**（正常）：
-```
-config updated session=xxx scenario=interviewer  ← ✅ 正确接收
-历史组装完成 ... scenario=interviewer            ← ✅ 正确传递
-```
-
----
-
-## 部署指南
-
-### 部署步骤
-
-#### 1. 停止旧服务（如果正在运行）
-
-```bash
-# 查找并停止占用 8080 端口的进程
-lsof -ti:8080 | xargs kill -9
-```
-
-#### 2. 启动后端
-
-```bash
-cd backend
-go run ./cmd/server
-# 或编译后运行
-# go build -o camtalk ./cmd/server && ./camtalk
-```
-
-**验证后端启动**：
-```bash
-curl http://localhost:8080/api/health
-# 预期输出：{"status":"ok","version":"dev","uptime_seconds":10,"active_sessions":0}
-```
-
-#### 3. 启动前端（如已运行则刷新浏览器）
-
-```bash
-cd frontend
-npm run dev
-# 访问 http://localhost:5173
-```
-
-**前端无需重启**：Vite 会自动热更新（HMR），只需刷新浏览器页面即可。
-
----
-
-### 快速验证
-
-1. **打开浏览器** → http://localhost:5173
-2. **登录系统**
-3. **切换情景** → 右侧配置面板 → 对话情景 → 模拟面试官
-4. **观察现象**：
-   - ✨ AI 立即说："你好！我是今天的面试官。让我们先从自我介绍开始..."
-   - ✨ 对话框顶部显示蓝色提示卡片
-5. **验证效果** → 发送："你是谁？"
-   - ✅ **正确回复**："我是今天的面试官..."
-   - ❌ **错误回复**："我是通义千问..."
-
----
-
-## 技术细节
-
-### Eino 框架 State 机制
-
-项目使用 **CloudWeGo Eino** 框架进行 AI 编排，State 在节点间共享数据：
-
-```go
-// 1. 定义 State 结构
-type PipelineState struct {
-    Scenario string  // 必须显式赋值
-    ...
-}
-
-// 2. 注册 State 生成函数
-g := compose.NewGraph[I, O](
-    compose.WithGenLocalState(genLocalState),
-)
-
-// 3. 节点通过 stateFromCtx(ctx) 读取
-state := stateFromCtx(ctx)
-scenario := state.Scenario
-```
-
-**关键点**：`genLocalState` 只是创建空结构体，**必须在调用 Graph 前手动赋值**！
-
----
-
-### WebSocket 协议
-
-**客户端 → 服务端**（config 消息）：
-```json
-{
-  "type": "config",
-  "payload": {
-    "tts_enabled": true,
-    "detail_level": "low",
-    "language": "zh-CN",
-    "scenario": "interviewer"
-  }
-}
-```
-
-**服务端 → 客户端**（首句引导）：
-```json
-// llm_chunk
-{
-  "type": "llm_chunk",
-  "request_id": "scenario_greeting",
-  "delta": "你好！我是今天的面试官...",
-  "role": "assistant"
-}
-
-// llm_done
-{
-  "type": "llm_done",
-  "request_id": "scenario_greeting",
-  "full_text": "你好！我是今天的面试官...",
-  "tokens_used": {"prompt": 0, "completion": 0, "total": 0}
-}
-```
-
----
-
-### System Prompt 构建流程
-
-```
-sess.Config.Scenario = "interviewer"
-  ↓
-PipelineInput.Scenario = "interviewer"
-  ↓
-PipelineState.Scenario = "interviewer" (adapter.go 复制)
-  ↓
-nodes_history.go 读取 state.Scenario
-  ↓
-scenarioPrompt := llm.GetScenarioPrompt("interviewer", "zh-CN")
-  ↓
-返回："你是一位资深面试官。你通过摄像头观察面试者..."
-  ↓
-systemPrompt := llm.BuildSystemPrompt(language, detailLevel, scenarioPrompt)
-  ↓
-messages[0] = {Role: "system", Content: systemPrompt}
-  ↓
-ChatModel 接收到情景 Prompt
-  ↓
-LLM 按情景角色生成回复
-```
-
----
-
-## 后续优化建议
-
-### P2（强烈推荐）
-
-1. **情景切换时创建新会话**
-   - 避免历史对话干扰新情景
-   - 弹窗确认："切换情景会创建新会话，当前对话将保存。是否继续？"
-   - 实现难度：⭐⭐
-   - 用户价值：⭐⭐⭐⭐
-
-2. **进一步增强 System Prompt**
-   - 增加示例对话（Few-shot Prompting）
-   - 增加"禁止事项"列表
-   - 实现难度：⭐
-   - 效果提升：⭐⭐⭐
-
-### P3（可选）
-
-1. **情景专属 UI 主题色**
-   - 面试官 → 深蓝色
-   - 英语老师 → 绿色
-   - 辩论 → 红色
-   - 翻译 → 紫色
-
-2. **切换动画与音效**
-   - 切换时播放短音效
-   - 聊天面板淡出淡入动画
-
----
-
-## 修改文件清单
-
-### 后端（3 个文件）
-
-- ✅ `backend/internal/eino/adapter.go` — 修复 State 初始化
-- ✅ `backend/internal/ws/handler.go` — 添加首句引导
-- ✅ `backend/internal/ai/llm/scenarios.go` — 增强 Prompt + 首句
-
-### 前端（5 个文件）
-
-- ✅ `frontend/src/hooks/useVisionSession.ts` — 修复 scenario 发送
-- ✅ `frontend/src/components/ChatPanel/index.tsx` — 添加提示卡片
-- ✅ `frontend/src/App.css` — 卡片样式
-- ✅ `frontend/src/lib/i18n/zh-CN.ts` — 中文翻译
-- ✅ `frontend/src/lib/i18n/en-US.ts` — 英文翻译
-- ✅ `frontend/src/lib/i18n/ja-JP.ts` — 日文翻译
-
----
-
-## 经验教训
-
-1. **数据流完整性验证**
-   - 从用户输入 → WebSocket → 后端逻辑 → LLM → 回复
-   - 每个环节都需要日志验证
-
-2. **框架封装层的隐式约定**
-   - Eino State 需要显式初始化
-   - 不能依赖零值或默认值
-
-3. **端到端测试的重要性**
-   - 单元测试通过 ≠ 功能正常工作
-   - 必须包含实际对话验证
-
-4. **前后端协议同步**
-   - WebSocket 消息字段必须对齐
-   - 代码 review 需要覆盖完整数据流
-
----
-
-## 提交信息
-
-```bash
-git add backend/internal/eino/adapter.go \
-        backend/internal/ws/handler.go \
-        backend/internal/ai/llm/scenarios.go \
-        frontend/src/hooks/useVisionSession.ts \
-        frontend/src/components/ChatPanel/index.tsx \
-        frontend/src/App.css \
-        frontend/src/lib/i18n/*.ts \
-        docs/情景切换功能完整文档.md
-
-git commit -m "feat: 实现情景切换功能 + 修复两个关键 Bug
-
-功能实现：
-- 后端：添加情景首句引导（面试官/英语老师/辩论/翻译）
-- 后端：增强所有情景的 System Prompt（角色定位+规则+约束）
-- 前端：对话顶部添加情景提示卡片（蓝色渐变+图标+说明）
-- i18n：完整支持中英日三语
-
-Bug 修复：
-- Bug #1: adapter.go 未初始化 PipelineState.Scenario
-  根因：genLocalState() 创建空 State，未从 input 复制元数据
-  影响：所有情景均失效，AI 使用默认 Prompt
-  修复：从 PipelineInput 复制 Scenario 等字段到 State
-
-- Bug #2: useVisionSession.ts 未发送 scenario 字段
-  根因：config 消息 payload 缺少 scenario 字段
-  影响：后端无法接收到情景切换信息
-  修复：在两处发送 config 的地方添加 scenario 字段
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-## 附录：故障排查
-
-### 如果情景仍然不生效
-
-1. **检查后端日志**：
-   ```bash
-   grep "config updated" /tmp/camtalk_server.log | tail -5
-   grep "历史组装完成" /tmp/camtalk_server.log | tail -5
-   ```
-   
-   - 如果 `scenario=` 是空的，说明前端未发送或后端未接收
-   - 如果 `scenario=interviewer` 正确，但 AI 回复仍是通用的，可能是 LLM 模型问题
-
-2. **检查前端 WebSocket 消息**（浏览器 DevTools → Network → WS）：
-   ```json
-   {
-     "type": "config",
-     "payload": {
-       "scenario": "interviewer"  // 确认存在
-     }
-   }
-   ```
-
-3. **检查会话配置是否保存**：
-   - 切换情景后，LocalStorage 中应该有 `camtalk_config`
-   - 内容应包含 `"scenario": "interviewer"`
-
-4. **清除缓存重试**：
-   ```bash
-   # 浏览器：清除 LocalStorage
-   # 后端：重启服务
-   # 前端：刷新页面
-   ```
-
----
-
-**文档版本**: 1.0  
-**最后更新**: 2026-06-20  
-**维护人员**: CamTalk 开发团队