docs: 更新 README.md

Reviewed-on: http://8.161.227.145:3000/XEngineers/CamTalk/pulls/211

.gitea/workflows/deploy.yml

@@ -8,14 +8,28 @@ jobs:
   deploy:
     runs-on: aliyun
     steps:
-      - name: Checkout
-        uses: "http://8.161.227.145:3000/huanghaosheng/checkout@releases/v4"
-
-      - name: Install Docker CLI
-        run: apk add --no-cache docker-cli docker-cli-compose
-
-      - name: Build and Deploy
+      - name: Deploy
         run: |
-          chmod +x deploy.sh
-          ./deploy.sh build
-          ./deploy.sh restart
+          sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories
+          apk add --no-cache rsync docker-cli docker-cli-compose
+          GIT_URL="http://8.161.227.145:3000/XEngineers/CamTalk.git"
+          if [ -d /root/camtalk/.git ]; then
+            cd /root/camtalk
+            git fetch "$GIT_URL" ${GITHUB_REF_NAME} --depth=1
+            git reset --hard FETCH_HEAD
+          else
+            rm -rf /tmp/camtalk-deploy
+            git clone --depth=1 --branch ${GITHUB_REF_NAME} \
+              http://8.161.227.145:3000/XEngineers/CamTalk.git /tmp/camtalk-deploy
+            mkdir -p /root/camtalk
+            rsync -a --delete \
+              --exclude='.env' \
+              --exclude='pgdata' \
+              --exclude='redisdata' \
+              /tmp/camtalk-deploy/ /root/camtalk/
+            rm -rf /tmp/camtalk-deploy
+          fi
+
+          chmod +x /root/camtalk/deploy.sh
+          /root/camtalk/deploy.sh build
+          /root/camtalk/deploy.sh restart

.gitignore

@@ -24,3 +24,7 @@ Thumbs.db
 
 # ---- Obsidian ----
 .obsidian/
+.claudian/
+修改过程笔记/
+学习复盘/
+docs/follow-up/

CLAUDE.md

@@ -1,123 +1,128 @@
 # CLAUDE.md
 
-本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指引。
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## 项目概述
+CamTalk — 多模态实时 AI 视觉对话助手（摄像头 + 麦克风 + 视觉 + 语音 AI）
 
-CamTalk 是一款多模态实时 AI 视觉对话助手。用户通过摄像头和麦克风与 AI 交互，AI 理解视觉场景和语音输入后，以文字和语音形式给出自然回应。
+> **文档优先原则：** 开发前先读 `docs/` 设计文档，以文档为准；若代码与文档不一致，优先更新文档（尤其接口文档）。详细设计见 `docs/01-13` 系列文档。**注意**：`docs/Eino/` 框架文档内容庞大（~75 个文件），仅在需要了解 Eino Graph/节点/Callback 等框架细节时才读取。
 
-> **文档优先原则：** 执行任何开发任务前，先读取 `docs/` 下的相关设计文档（架构、接口、技术选型等），以文档为最高依据。代码实现应与文档一致；若有偏差，优先更新文档（尤其是接口文档）。
+## 常用命令
+
+```bash
+# === 前端（frontend/ 目录）===
+npm run dev          # Vite 开发服务器（http://localhost:5173，代理 /ws 和 /api 到 :8080）
+npm run build        # 生产构建（tsc -b && vite build，输出到 dist/）
+npm run lint         # ESLint 代码检查
+npm run preview      # 预览生产构建
+
+# === 后端（backend/ 目录）===
+go run ./cmd/server  # 启动服务（监听 :8080，启动时自动执行数据库迁移）
+golangci-lint run    # Go 代码检查
+
+# 后端测试
+go test ./...                     # 单元测试
+go test -tags=integration ./...   # 集成测试（需要 PostgreSQL）
+go test -v -run TestXxx ./path/   # 运行单个测试
+
+# === Docker 部署 ===
+./deploy.sh build    # 构建 Docker 镜像
+./deploy.sh up       # 启动服务（4 容器：frontend/backend/postgres/redis）
+./deploy.sh down     # 停止服务
+./deploy.sh logs     # 查看日志（可加服务名：./deploy.sh logs backend）
+./deploy.sh status   # 查看服务状态
+```
 
 ## 架构
 
-三层系统：
+三层系统：前端（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（`START → STT → History → ChatModel → Msg2Str → Splitter → TTS → Done → END`），LLM token 通过 Callback 实时推送，TTS 逐句合成并行推送，最小化感知延迟。
+**会话存储**（TieredManager）：L1 Memory → L2 Redis → L3 PostgreSQL 三级存储，30 分钟 TTL，Redis 故障自动降级。
 
-**存储**：三级存储架构（TieredManager）—— L1 Memory → L2 Redis → L3 PostgreSQL，自动降级。Repository 接口模式（UserRepository、MessageRepository、SessionRepository），PostgreSQL + 内存双实现。
+**鉴权**：JWT 双 token 轮转（Access 120min + Refresh 7d），重放攻击检测（DB hash 校验），Redis 缓存装饰器。
 
 ## 技术栈
 
-| 层级 | 技术 |
+前端：React 18 + TypeScript + Vite，VAD（@ricky0123/vad-web），ONNX Runtime，国际化（zh-CN / en-US / ja-JP）
+后端：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
+CI/CD：Gitea Actions（`.gitea/workflows/deploy.yml`），push main/v2 自动构建部署到自建 aliyun runner
+前端测试：**暂无**（package.json 无 test 脚本，无测试框架配置）
+
+## 配置体系
+
+配置优先级：**环境变量 > `config.{APP_ENV}.yaml` > `config.yaml` > 代码默认值**
+
+配置文件位于 `backend/config/`：
+- `config.yaml` — 基础配置（dev 默认值）
+- `config.dev.yaml` — 开发环境覆盖（可选）
+- `config.prod.yaml` — 生产环境覆盖（可选）
+
+环境切换：`APP_ENV=dev|prod`（dev 默认，prod 启用限流 + 严格 CORS + Release 模式）
+
+敏感信息（API Key、JWT Secret、数据库密码）**只能通过环境变量或 `.env` 文件注入**，不写入 YAML 配置文件。核心环境变量（参考 `backend/.env.example`）：
+
+| 变量 | 说明 |
 |------|------|
-| 前端 | React 18, TypeScript, Vite, @ricky0123/vad-web |
-| 后端 | Go, 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 |
+| `CAMTALK_AI_LLM_API_KEY` | LLM API Key（DashScope） |
+| `CAMTALK_AI_STT_API_KEY` | STT API Key（MiMo/Deepgram） |
+| `CAMTALK_AI_TTS_API_KEY` | TTS API Key（MiMo/OpenAI） |
+| `CAMTALK_AUTH_JWT_SECRET` | JWT 签名密钥 |
+| `CAMTALK_STORAGE_DSN` | PostgreSQL 连接字符串 |
+| `CAMTALK_REDIS_ADDR` | Redis 地址 |
+| `CAMTALK_REDIS_PASSWORD` | Redis 密码 |
 
-## 构建与运行命令
+## 数据库迁移
 
-```bash
-# 前端
-cd frontend && npm install
-npm run dev          # Vite 开发服务器
-npm run build        # 生产构建
-npm run lint         # ESLint 检查
-npm run test         # Vitest 测试
+迁移 SQL 文件位于 `backend/migrations/`（`001_*.up.sql` 等），通过 Go `//go:embed` 嵌入二进制（见 `backend/migrations/embed.go`）。应用启动时**自动执行**未应用的迁移，无需手动运行迁移命令。迁移通过 `schema_migrations` 表追踪执行状态。
 
-# 后端
-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 ./...                 # 静态分析
-```
+回滚脚本为同目录下的 `*.down.sql` 文件，需手动执行。
 
-基础设施：三级存储架构（L1 Memory → L2 Redis → L3 PostgreSQL），通过配置控制启用层级。
+## 协议与 API
 
-## WebSocket 协议
+**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`），订阅模式，自动重连
+- WebSocket 地址自动从当前页面协议/主机推导，也可通过 `VITE_WS_URL` 环境变量显式指定（如 `wss://api.example.com/ws`）
 
-端点：`ws://localhost:8080/ws?token=<access_token>&conversation_id=<uuid>`
+**REST API**：`/api/auth/*`（注册/登录/刷新/登出），`/api/conversations/*`（CRUD + 消息分页），`/api/scenarios/*`（用户自定义情景 CRUD），`/api/health`
 
-所有消息为 JSON 文本帧，统一信封格式 `{type, request_id?, timestamp?}`。完整契约见 `docs/02-接口文档.md`。
+**错误码**：`INVALID_MESSAGE`, `SESSION_NOT_FOUND`, `RATE_LIMITED`, `IMAGE_TOO_LARGE`, `LLM_TIMEOUT`, `STT/TTS/LLM_ERROR`, `INVALID_TOKEN` 等
 
-**客户端 → 服务端**：`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。
+**后端核心**：
+- `backend/cmd/server/main.go` — 入口，依赖注入与启动流程（存储→AI 服务→Graph→路由→Server）
+- `backend/internal/eino/` — Eino Graph 编排层（graph.go 构建、adapter.go 适配、callback.go 推送、state.go 状态、nodes_*.go 各节点实现）
+- `backend/internal/session/tiered.go` — 三级会话存储（TieredManager）
+- `backend/internal/store/` — 持久化层（Repository 接口 + PG 实现 + Redis 缓存装饰器）
+  - Repository 模式：接口定义在 `user.go`/`session.go`/`message.go`，PG 实现在 `*_pg.go`，Redis 缓存装饰器在 `cached_user.go`
+- `backend/internal/ws/handler.go` — WebSocket 连接管理（升级→认证→收发循环→清理）
+- `backend/internal/ai/` — AI 服务抽象层（llm/stt/tts 各子目录，统一 `Service` 接口）
+- `backend/internal/auth/` — JWT/bcrypt/中间件
+- `backend/internal/ratelimit/` — 令牌桶限流（内存/Redis 两种后端）
+- `backend/migrations/` — 嵌入式 SQL 迁移文件（embed.go + *.sql）
 
-## 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/PUT/PATCH/DELETE /api/conversations/:id` — 对话 CRUD
-- `GET /api/conversations/:id/messages` — 获取对话消息
-
-## 错误码
-
-`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`
-
-## 前端组件结构
-
-| 组件 | 职责 |
-|------|------|
-| `AuthPage` | 登录/注册表单 |
-| `CameraManager` | 摄像头流采集 |
-| `MicManager` | 麦克风音频采集 |
-| `EdgeProcessor` | VAD + 关键帧检测（Canvas 像素比较） |
-| `WebSocketManager` | WebSocket 连接生命周期管理 |
-| `ChatPanel` | 消息展示、流式回复、文本输入、场景选择 |
-| `VideoPreview` | 摄像头画面预览 |
-| `SessionSidebar` | 左侧抽屉式对话列表 |
-| `ConfigPanel` | 右侧抽屉式配置面板 |
-| `Toast` | 轻量通知提示 |
-
-核心 Hook：`useVisionSession()` 封装一次完整的视觉对话会话。
-
-## 后端模块结构
-
-| 模块 | 职责 |
-|------|------|
-| WebSocket Handler | 连接管理、JWT 认证、单播消息推送 |
-| Session Manager | 会话状态、对话历史（三级存储：Memory/Redis/PostgreSQL，30 分钟 TTL） |
-| Eino 编排层 | 基于 Eino Graph 的声明式 AI 编排（7 节点 DAG，Stream 模式，Callback AOP） |
-| AI Orchestrator | `EinoOrchestrator` 适配器，包装 Graph 实现 `Orchestrator` 接口 |
-| AI Service Layer | AI 服务抽象层（STT/TTS 多 provider，LLM 通过 eino-ext ChatModel） |
-| Auth | JWT 双 token 轮转认证，bcrypt 密码哈希 |
-| Store | 持久化存储层（UserRepository/MessageRepository/SessionRepository，内存 + PostgreSQL） |
-| REST API | 健康检查、认证、对话管理（Gin 路由） |
-| Models | 数据模型定义 |
-| Migrations | 数据库版本化迁移（嵌入式 SQL） |
-| Model Router | 按请求选择 AI 模型（规划中） |
-| Rate Limiter | 按用户的令牌桶速率限制（规划中） |
+**前端核心**：
+- `frontend/src/hooks/useVisionSession.ts` — 核心会话 Hook（~500 行，编排整个采集→发送→接收→播放流程）
+- `frontend/src/lib/websocket.ts` — WebSocket 客户端单例（心跳/重连/订阅模式）
+- `frontend/src/lib/auth.tsx` — AuthProvider（JWT 自动刷新 + React Context）
+- `frontend/src/lib/api.ts` — REST 客户端（401 拦截 + token 刷新）
+- `frontend/src/lib/ttsPlayer.ts` — 流式 TTS 音频播放队列
+- `frontend/src/lib/i18n/` — 国际化（zh-CN / en-US / ja-JP）
+- `frontend/src/components/` — UI 组件（LandingPage/CameraManager/MicManager/WebSocketManager/ChatPanel/SessionSidebar/ConfigPanel/VideoPreview 等）
+- `frontend/vite.config.ts` — VAD 模型文件自动复制 + ONNX WASM MIME 处理 + 代理配置
 
 ## 编码规范
 
-- **Go**：遵循标准 Go 规范。所有 AI 调用使用 `context.Context` 做取消/超时。并发 map 访问使用 `sync.RWMutex`。结构体标签用 `json:"snake_case"`。
-- **TypeScript**：严格模式。所有数据模型用接口定义。WebSocket 消息类型用可辨识联合类型（`type` 字段）。
-- **提交信息**：Conventional Commits 格式，描述用中文。示例：`feat: 添加 WebSocket 连接管理`、`fix: 修复心跳超时判断`、`docs: 更新接口文档`
-- **禁止自动 push**：除非用户明确要求。
-- **文档优先**：实现功能前先读取 `docs/` 下的相关设计文档。实现与文档不一致时，优先更新 `docs/` 下的接口文档。
+- **Go**：标准规范，`context.Context` 超时控制，`sync.RWMutex` 并发保护，`json:"snake_case"` 标签，编译期接口检查 `var _ Interface = (*Impl)(nil)`
+- **TypeScript**：严格模式，接口定义数据模型，WebSocket 消息用可辨识联合类型（`type` 字段区分）
+- **存储层模式**：Repository 接口 + PostgreSQL 实现 + Redis 缓存装饰器（`CachedUserRepository` 包装模式）
+- **CORS**：禁止后端代码/配置文件配置 CORS，统一由代理层处理（开发环境 Vite proxy，生产环境 Nginx）
+- **提交信息**：Conventional Commits，中文描述（如 `feat: 添加 WebSocket 心跳`）
+- **禁止自动 push**：除非用户明确要求
+- **文档优先**：开发前先读 `docs/` 设计文档，代码与文档不一致时优先更新文档

CamTalk-演讲稿.md

@@ -1,116 +0,0 @@
-## CamTalk — 多模态实时 AI 视觉对话助手 · 演讲稿
-
-> 面向面试官，预计 10-15 分钟。建议配合架构图或项目文档做演示。
-
----
-
-### 开场（约 1 分钟）
-
-各位好，今天我想和大家分享一个我主导设计和开发的项目——**CamTalk**，一个多模态实时 AI 视觉对话助手。
-
-简单来说，用户打开浏览器，对着摄像头，用语音提问，AI 就能同时"看到"画面、"听到"语音，然后用文字和语音自然地回应。整个过程不需要打字，就像一个面对面的助手。
-
-做这个项目的初衷其实很直接——现在的大模型已经具备多模态能力，但大多数产品还是"上传一张图、输入一段文字"的交互方式。我认为真正的多模态交互应该是**无感的**——用户只需要说话，AI 自己去理解视觉场景，就像两个人面对面聊天一样。
-
----
-
-### 系统架构（约 3 分钟）
-
-CamTalk 采用三层架构：**前端做轻量预处理，后端做智能编排，云端 AI 服务按需调用**。
-
-**前端**是 React 18 加 TypeScript，跑在浏览器里。它负责三件事：摄像头和麦克风的采集，边缘侧的预处理——比如语音活动检测和关键帧过滤，以及 UI 渲染。通过 WebSocket 与后端通信。
-
-**后端**是 Go 写的网关服务，用 Gin 框架做 HTTP 路由，gorilla/websocket 处理长连接。它是整个系统的"大脑"，负责会话管理、AI 编排，以及和各家 AI 服务的对接。每个 WebSocket 连接对应一个 goroutine，天然适合这种长连接场景。
-
-**AI 服务层**是可插拔的。LLM 默认用 GPT-4o，通过 OpenAI 兼容接口可以随时切换成通义千问等国产模型。语音识别默认 Deepgram，语音合成默认 OpenAI TTS，同时也支持小米的 MiMo 系列作为备选。
-
-有人可能会问：为什么不直接让前端调用 AI API？这里有三点考虑。第一是**安全性**，API Key 不应该暴露在客户端。第二是**统一管控**，速率限制、成本监控、模型路由这些逻辑集中在网关层更好维护。第三是**可扩展性**，未来加缓存、做负载均衡、多实例部署，都在网关层解决。
-
-部署方面，我们设计了 Nginx 做同源反向代理，前端静态资源和后端 API 在同一个域名下，天然解决跨域问题。Go 网关可以水平扩展，通过 Redis 共享会话状态。目前也已经配置好了 Docker Compose 一键部署方案，包含前端、后端和 PostgreSQL 三个容器。
-
----
-
-### 核心交互流程（约 3 分钟）
-
-我想重点讲一下一次完整的交互流程，因为它串起了整个系统最核心的技术挑战。
-
-用户对着摄像头说了一句话，比如"这是什么花"。首先是**前端**的 VAD——语音活动检测模块——在浏览器端实时检测用户何时开始说话、何时说完。这一步完全在端侧完成，用的是 @ricky0123/vad-web，基于 WebRTC VAD 算法。好处是：用户不说话时不需要上传任何音频，节省约 70% 的无效带宽。
-
-VAD 检测到语音结束后，前端会同时做两件事：把音频编码成 PCM 格式，以及从摄像头捕获当前画面，一起通过 WebSocket 发给后端。
-
-后端收到后，启动一个 **AI 编排管道**（我们叫它 Orchestrator）。第一步，把音频发给 STT 服务做语音识别，拿到文字结果。第二步，把识别出的文字、摄像头画面以及对话历史，一起打包发给多模态 LLM 做推理。LLM 以流式方式逐 token 输出。第三步，也是最关键的优化——我们不等待 LLM 输出完再调用 TTS，而是做**句子级切分**：LLM 每输出一个完整句子，就立即送入 TTS 合成并推送给客户端。
-
-所以客户端的体验是这样的：文字一个 token 一个 token 地出现，几乎同时语音就开始播放了。用户**先看到文字、紧接着听到语音**，感知延迟可以控制在 0.5 秒以内。整个端到端的目标延迟是 1.5 到 2 秒。
-
-这个"LLM 文本流和 TTS 音频流并行推送"的设计，是我们降低感知延迟最关键的手段。
-
----
-
-### 成本控制（约 2 分钟）
-
-做实时多模态应用，成本是最容易失控的地方。我在设计之初就把成本控制作为架构级别的考量。
-
-最直观的例子是视觉链路：如果按 1fps 全量发送画面给 LLM，一个用户每天用 10 分钟，一天就是 60 万帧的 token 消耗，1000 个用户时成本完全不可控。
-
-我们的核心策略叫**端云协同**——把适合的计算前置到客户端。
-
-在视觉侧，我们做了三个优化：一是降低采样频率，空闲时 5 秒一帧，用户说话时 1 秒一帧；二是关键帧过滤，通过 Canvas 像素比较计算帧间相似度，画面没有显著变化就不发送；三是只在用户提问时捕获画面，而不是持续上传视频流。
-
-在语音侧，VAD 在浏览器端检测，只上传有效语音片段，环境噪音和静默时段完全不消耗带宽。
-
-在推理侧，我们规划了模型分级策略——简单识别类问题走 GPT-4o-mini，深度分析走 GPT-4o，复杂推理走 o1。同时对话历史做了裁剪，前端保留最近 10 轮，后端保留 20 轮，限制每轮的固定 token 开销。
-
-这些策略综合下来，预估月成本可以从无优化的约 5000 美元降到 300 到 500 美元，降幅大约 90%。
-
----
-
-### 工程设计与取舍（约 2 分钟）
-
-除了技术实现，我想分享几个设计上的取舍。
-
-**存储方案的分阶段设计**。MVP 阶段我们用进程内存存会话状态，快速验证核心功能。但代码层面我们已经通过 Repository 接口模式做了抽象——HistoryRepository、UsageRepository 这些接口定义好了，底层实现可以是 Memory、Redis 或 PostgreSQL，通过配置切换。目前 Redis 实现已经就绪，PostgreSQL 的 schema 也设计好了，包括 sessions、messages、usage_daily 三张表。这种渐进式设计让我们既能快速交付，又为后续扩展留好了空间。
-
-**文档驱动开发**。项目里有一套完整的设计文档，涵盖架构、接口协议、技术选型、成本控制等。我们遵循"文档优先"原则——实现功能前先写设计文档，实现和文档不一致时优先更新文档。这在团队协作中特别重要，接口契约清晰，前后端可以并行开发。
-
-**WebSocket 协议的可靠性设计**。客户端每 30 秒发心跳，服务端 60 秒没收到心跳就断开。断线后用指数退避加抖动重连——1 秒、2 秒、4 秒、8 秒，最大 30 秒。消息用统一信封格式，所有消息都带 type 字段做类型分发。
-
----
-
-### 用户故事与产品规划（约 2 分钟）
-
-最后讲一下产品层面的思考。用户故事我按 P0 到 P2 分了三个优先级。
-
-P0 是 MVP 必做的四个场景：AI 识别画面中的物体、语音对话无需打字、AI 能看到摄像头画面、AI 用语音回答。这四个跑通了，核心价值就成立了。
-
-P1 是体验增强：AI 主动观察画面变化并提示重要事件、识别画面中的文字做 OCR、以及多轮对话的上下文记忆。
-
-P2 是进阶探索：比如视障用户的无障碍辅助——AI 实时描述周围环境并提示障碍物，画面中外语内容的实时翻译，以及"观察模式"和"对话模式"的切换。
-
-优先级判断用两个维度交叉评估：用户价值和实现成本。P0 是高价值且成本合理的，P1 是高价值但成本较高的，P2 是探索性的，验证后再投入。
-
-目前还有几个功能创意在规划中，包括视频录制、对话翻译、对话总结、手动对话输入，以及对话情景选择——比如面试官模式、英语老师模式、辩论赛模式等。
-
----
-
-### 总结（约 1 分钟）
-
-总结一下，CamTalk 这个项目有几个我比较满意的设计点。
-
-第一是**架构清晰**：三层分离，每层职责明确，前端做轻量预处理，后端做智能编排，AI 服务可插拔。
-
-第二是**体验导向**：从用户感知延迟倒推技术方案，流式并行推送、句子级切分、端侧 VAD 这些手段都是围绕"让对话像真人一样自然"这个目标设计的。
-
-第三是**成本意识**：从架构层面就融入了成本控制，端云协同、智能采样、模型分级，不是等功能做完再去优化成本。
-
-第四是**工程成熟度**：接口抽象、文档驱动、渐进式存储升级，为项目的长期演进留好了空间。
-
-以上就是 CamTalk 项目的整体介绍。谢谢大家，有什么问题我们可以一起讨论。
-
----
-
-> **附：讲解提示**
->
-> - 如果面试官追问技术深度，可以展开讲 Orchestrator 的管道实现细节（goroutine 并发、context 取消、句子切分算法）或 VAD 参数调优。
-> - 如果追问产品思维，可以展开讲用户故事的优先级判断逻辑，以及观察模式和对话模式的差异设计。
-> - 如果追问可扩展性，可以讲 Redis 共享会话、多 Gateway 水平扩展、模型路由器的规划。
-> - 如果追问成本数据，可以给出具体的 token 消耗计算过程和各种优化手段的量化效果。

README.md

@@ -1,167 +1,561 @@
 # CamTalk
 
-多模态实时 AI 视觉对话助手。用户通过摄像头和麦克风与 AI 交互，AI 理解视觉场景和语音输入后，以文字和语音形式给出自然回应。
+<div align="center">
 
-- **路演视频**：[哔哩哔哩弹幕网——七牛云第四批议题1](https://www.bilibili.com/video/BV1dDJK6cE5S/)
-- **线上体验**：http://8.161.227.145:9000
+**多模态实时 AI 视觉对话助手**
 
-> ⚠️ **注意**：由于线上地址使用 HTTP 协议，浏览器默认禁止在非 HTTPS 环境下调用摄像头和麦克风。需要按以下步骤配置 Chrome 浏览器：
+用户通过摄像头和麦克风与 AI 交互，AI 理解视觉场景和语音输入后，以文字和语音形式给出自然回应
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Go Version](https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go)](https://go.dev/)
+[![React](https://img.shields.io/badge/React-18-61DAFB?logo=react)](https://react.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript)](https://www.typescriptlang.org/)
+
+[路演视频](https://www.bilibili.com/video/BV1dDJK6cE5S/) • [在线体验](https://camtalk.goanchor.top) • [文档](docs/README.md)
+
+</div>
+
+---
+
+
+<!-- > ⚠️ **在线体验提示**：由于演示环境使用 HTTP 协议，需配置 Chrome 允许非 HTTPS 下访问摄像头/麦克风：
 >
-> 1. 在浏览器地址栏中输入 `chrome://flags/#unsafely-treat-insecure-origin-as-secure`，回车
-> 2. 将 **Insecure origins treated as secure** 选项设置为 **Enabled**（已启用）
-> 3. 在输入框中输入 `http://8.161.227.145:9000` 地址
-> 4. 点击右下角弹出的 **Relaunch** 按钮，自动重启浏览器
->
-> 重启后即可在该 HTTP 地址下正常调用摄像头和麦克风。
+> 1. 访问 `chrome://flags/#unsafely-treat-insecure-origin-as-secure`
+> 2. 启用该选项，并在输入框填入 `http://8.161.227.145:9000`
+> 3. 点击 **Relaunch** 重启浏览器
 
-![](docs/pictures/1.png)
+![CamTalk 界面截图](docs/pictures/1.png) -->
 
-## 架构
+## ✨ 核心特性
 
-三层系统，前端做轻量预处理，后端做智能编排，云端 AI 服务按需调用：
+- 🎥 **多模态理解**：摄像头视觉 + 麦克风语音双输入，AI 理解完整场景
+- 🗣️ **自然对话**：基于 VAD 的端到端语音交互，低延迟流式响应
+- 🚀 **实时推送**：LLM 文本流 + TTS 音频流并行推送，感知延迟 < 0.5 秒
+- 🎭 **情景模式**：自由对话、面试官、英语老师等多场景支持
+- 💾 **对话历史**：自动保存会话，支持搜索、重命名、删除、时间分组
+- 🔐 **安全认证**：JWT 双 token 轮转 + Refresh Token Rotation 防重放
+- 📊 **三级存储**：Memory → Redis → PostgreSQL 自动降级，保障可靠性
+- 🌐 **国际化**：支持中文、英文、日文界面
+
+## 🏗️ 系统架构
+
+CamTalk 采用**三层架构**：前端轻量预处理 → Go 网关智能编排 → 云端 AI 按需调用
 
 ```mermaid
 graph TB
-    subgraph client[浏览器客户端]
-        A1[媒体采集]
-        A2[VAD 语音检测]
-        A3[关键帧检测]
-        A4[UI 渲染]
+    subgraph Browser["🌐 浏览器客户端"]
+        UI["React UI 渲染"]
+        VAD["VAD 语音检测"]
+        Media["媒体采集"]
     end
 
-    subgraph gateway[Go 网关 :8080]
-        B1[WebSocket Handler]
-        B2[Session Manager]
-        B3[AI Orchestrator]
-        B4[REST API]
+    subgraph Gateway["⚙️ Go 网关 (Eino Graph)"]
+        WS["WebSocket Handler"]
+        Auth["JWT 认证"]
+        Session["会话管理 (三级存储)"]
+        Orch["AI 编排器 (7节点DAG)"]
     end
 
-    subgraph cloud[云端 AI 服务]
-        C1[STT 语音识别]
-        C2[LLM 多模态推理]
-        C3[TTS 语音合成]
+    subgraph AI["☁️ 云端 AI 服务"]
+        STT["STT (MiMo/Deepgram)"]
+        LLM["LLM (qwen3-vl-plus)"]
+        TTS["TTS (MiMo/OpenAI)"]
     end
 
-    client <-->|WebSocket| gateway
-    gateway <-->|HTTP| cloud
+    Browser <-->|"WebSocket<br/>(JWT + query/config)"| Gateway
+    Orch --> STT
+    Orch --> LLM
+    Orch --> TTS
 ```
 
-**关键模式**：LLM 文本流和 TTS 音频流并行推送，用户先看到文字、紧接着听到语音，感知延迟 < 0.5 秒。
+### AI 编排流水线（Eino Graph）
 
-## 技术栈
+基于 [CloudWeGo Eino](https://github.com/cloudwego/eino) 框架的声明式 7 节点 DAG：
 
-| 层级 | 技术 |
-|------|------|
-| 前端 | React 18, TypeScript, Vite, @ricky0123/vad-web |
-| 后端 | Go, Gin, gorilla/websocket, Viper, Zap |
-| STT | Deepgram（默认） / MiMo ASR |
-| LLM | GPT-4o（默认，通过 OpenAI 兼容接口可切换） |
-| TTS | OpenAI TTS（默认） / MiMo TTS |
+```
+START → STT → History → ChatModel → Msg2Str → Splitter → TTS → Done → END
+```
 
-## 项目结构
+**核心优势**：
+- **流式处理**：ChatModel 逐 token 推送，Callback AOP 机制实时转发客户端
+- **句子级 TTS**：Splitter 实时切分句子，TTS 逐句并行合成，无需等待完整回复
+- **类型安全**：Go 泛型 + 编译期检查，Graph 拓扑错误在编译时发现
+
+## 🛠️ 技术栈
+
+<table>
+<tr>
+<td><b>层级</b></td>
+<td><b>技术选型</b></td>
+<td><b>说明</b></td>
+</tr>
+<tr>
+<td><b>前端</b></td>
+<td>React 18 + TypeScript + Vite</td>
+<td>组件化开发，类型安全，快速热更新</td>
+</tr>
+<tr>
+<td><b>VAD</b></td>
+<td>@ricky0123/vad-web (ONNX Runtime)</td>
+<td>浏览器端语音活动检测，零延迟</td>
+</tr>
+<tr>
+<td><b>后端</b></td>
+<td>Go 1.25+ + Gin + gorilla/websocket</td>
+<td>高并发 goroutine，长连接管理</td>
+</tr>
+<tr>
+<td><b>AI 编排</b></td>
+<td>CloudWeGo Eino Graph</td>
+<td>声明式 DAG，Stream 模式，Callback AOP</td>
+</tr>
+<tr>
+<td><b>STT</b></td>
+<td>MiMo ASR（默认）/ Deepgram</td>
+<td>实时语音识别，多语言支持</td>
+</tr>
+<tr>
+<td><b>LLM</b></td>
+<td>DashScope qwen3-vl-plus</td>
+<td>多模态推理（通过 eino-ext OpenAI 接入）</td>
+</tr>
+<tr>
+<td><b>TTS</b></td>
+<td>MiMo TTS（默认）/ OpenAI TTS</td>
+<td>自然语音合成</td>
+</tr>
+<tr>
+<td><b>存储</b></td>
+<td>PostgreSQL 15 + Redis 7</td>
+<td>三级存储架构：Memory → Redis → PG</td>
+</tr>
+<tr>
+<td><b>认证</b></td>
+<td>JWT (HS256) + bcrypt</td>
+<td>双 token 轮转 + Refresh Token Rotation</td>
+</tr>
+<tr>
+<td><b>配置</b></td>
+<td>Viper + godotenv</td>
+<td>YAML + .env + 环境变量覆盖</td>
+</tr>
+<tr>
+<td><b>日志</b></td>
+<td>Zap</td>
+<td>高性能结构化日志 + Trace ID 追踪</td>
+</tr>
+</table>
+
+## 📁 项目结构
 
 ```
 CamTalk/
-├── frontend/                   # 浏览器客户端
+├── frontend/                   # 🌐 浏览器客户端
 │   └── src/
 │       ├── components/         # UI 组件
+│       │   ├── LandingPage/    # 登录着陆页 + LoginModal
 │       │   ├── CameraManager/  # 摄像头流采集
-│       │   ├── MicManager/     # 麦克风音频采集
-│       │   ├── EdgeProcessor/  # VAD + 关键帧检测
-│       │   ├── WebSocketManager/ # WS 连接管理
-│       │   ├── ChatPanel/      # 消息展示
-│       │   ├── VideoPreview/   # 摄像头画面预览
-│       │   ├── ConfigPanel/    # 配置面板
-│       │   └── Toast/          # 通知提示
+│       │   ├── MicManager/     # 麦克风音频采集 + VAD
+│       │   ├── WebSocketManager/ # WS 连接生命周期
+│       │   ├── ChatPanel/      # 消息展示 + 流式回复
+│       │   ├── SessionSidebar/ # 对话历史侧边栏
+│       │   └── ConfigPanel/    # 配置面板（主题/TTS/语言/场景）
 │       ├── hooks/              # 自定义 Hooks
-│       │   ├── useVisionSession.ts  # 核心会话 Hook
+│       │   ├── useVisionSession.ts  # 核心会话 Hook (~500 行)
+│       │   ├── useSessionList.ts    # 对话列表管理
 │       │   └── useObservationMode.ts # 观察模式
 │       ├── lib/                # 工具库
-│       │   ├── websocket.ts    # WebSocket 连接管理
-│       │   ├── audio.ts        # 音频编码
-│       │   ├── ttsPlayer.ts    # TTS 播放器
-│       │   └── sampling.ts     # 采样策略
+│       │   ├── websocket.ts    # WebSocket 单例（心跳/重连/订阅）
+│       │   ├── api.ts          # REST 客户端（401拦截+刷新）
+│       │   ├── auth.tsx        # AuthProvider（JWT 自动刷新）
+│       │   ├── ttsPlayer.ts    # TTS 流式播放队列
+│       │   └── i18n/           # 国际化（zh-CN/en-US/ja-JP）
 │       └── types/              # TypeScript 类型定义
-├── backend/                    # Go 网关
-│   ├── cmd/server/             # 入口
+├── backend/                    # ⚙️ Go 网关
+│   ├── cmd/server/             # 服务入口（main.go）
 │   └── internal/
+│       ├── eino/               # 🔥 Eino Graph 编排层（7节点DAG）
+│       │   ├── graph.go        # Graph 构建与编译
+│       │   ├── adapter.go      # EinoOrchestrator 适配器
+│       │   ├── callback.go     # LLM token 推送回调
+│       │   ├── state.go        # 跨节点状态管理
+│       │   └── nodes_*.go      # STT/History/Splitter/TTS/Done 节点
+│       ├── session/            # 会话管理（TieredManager 三级存储）
+│       ├── store/              # 持久化层（Repository 接口 + PG/内存实现）
+│       │   ├── user_pg.go      # PostgreSQL 实现
+│       │   └── cached_user.go  # Redis 缓存装饰器
+│       ├── auth/               # 认证（JWT/bcrypt/中间件）
 │       ├── ai/                 # AI 服务抽象层
-│       │   ├── llm/            # LLM 服务（OpenAI 兼容）
-│       │   ├── stt/            # STT 服务（Deepgram/MiMo）
-│       │   └── tts/            # TTS 服务（OpenAI/MiMo）
-│       ├── orchestrator/       # AI 编排器（STT→LLM→TTS 管道）
-│       ├── session/            # 会话管理（Memory/Redis）
+│       │   ├── llm/            # LLM 提示词与场景
+│       │   ├── stt/            # STT 服务（MiMo/Deepgram）
+│       │   └── tts/            # TTS 服务（MiMo/OpenAI）
 │       ├── ws/                 # WebSocket Handler
-│       ├── api/                # REST API
-│       ├── config/             # 配置管理
-│       ├── models/             # 数据模型
-│       ├── errors/             # 错误码
-│       └── logger/             # 日志
-├── docs/                       # 设计文档
-└── CLAUDE.md                   # Claude Code 指引
+│       ├── api/                # REST API（Auth/Conversation）
+│       ├── config/             # 配置管理（Viper）
+│       └── logger/             # 日志（Zap + Trace ID）
+├── migrations/                 # 📊 数据库迁移（嵌入式 SQL）
+├── docs/                       # 📚 设计文档
+│   ├── 01-架构设计.md
+│   ├── 02-接口文档.md
+│   ├── 08-Eino框架与编排设计.md
+│   ├── 10-鉴权体系.md
+│   └── 13-日志追踪.md
+├── deploy.sh                   # 🐳 部署脚本（Docker Compose）
+├── docker-compose.yml          # 容器编排配置
+└── CLAUDE.md                   # 🤖 Claude Code 开发指引
 ```
 
-## 快速开始
+## 🚀 快速开始
 
 ### 前置条件
 
-- Node.js >= 18
-- Go >= 1.24
+- **Node.js** >= 18
+- **Go** >= 1.25
+- **PostgreSQL** >= 15（可选 Docker）
+- **Redis** >= 7（可选，用于缓存加速）
 
-### 前端
+### 本地开发
+
+#### 1. 克隆项目
 
 ```bash
-cd frontend
-npm install
-npm run dev          # Vite 开发服务器 http://localhost:5173
+git clone https://github.com/yourusername/CamTalk.git
+cd CamTalk
 ```
 
-### 后端
+#### 2. 配置环境变量
+
+```bash
+# 复制环境变量模板
+cp backend/.env.example backend/.env
+
+# 编辑 .env 文件，填入以下必需配置：
+# - CAMTALK_AUTH_JWT_SECRET（使用 openssl rand -hex 32 生成）
+# - CAMTALK_STORAGE_DSN（PostgreSQL 连接字符串）
+# - CAMTALK_AI_LLM_API_KEY（DashScope API Key）
+# - CAMTALK_AI_STT_API_KEY（MiMo/Deepgram API Key）
+# - CAMTALK_AI_TTS_API_KEY（MiMo/OpenAI API Key）
+```
+
+#### 3. 启动后端
 
 ```bash
 cd backend
+
+# 安装依赖
 go mod download
-go run ./cmd/server  # 启动网关 :8080
-```
 
-### 配置
+# 运行数据库迁移（自动创建表）
+go run ./cmd/server migrate
 
-后端配置文件位于 `backend/config.yaml`，支持环境变量覆盖（前缀 `CAMTALK_`）。
-
-```bash
-# 最小启动（需要至少一个 AI 服务的 API Key）
-cd backend
-CAMTALK_AI_LLM_API_KEY=sk-xxx \
-CAMTALK_AI_STT_API_KEY=xxx \
+# 启动服务（监听 :8080）
 go run ./cmd/server
 ```
 
-配置优先级：环境变量 > `config.{env}.yaml` > `config.yaml` > `.env`
+#### 4. 启动前端
 
-## WebSocket 协议
+```bash
+cd frontend
 
-连接地址：`ws://localhost:8080/ws`
+# 安装依赖
+npm install
 
-所有消息为 JSON 文本帧，统一信封格式 `{type, request_id?, timestamp?}`。
+# 启动开发服务器（http://localhost:5173）
+npm run dev
+```
 
-**客户端 → 服务端**：`query`、`config`、`interrupt`、`ping`
-**服务端 → 客户端**：`connected`、`stt_result`、`llm_chunk`、`llm_done`、`tts_audio`、`error`、`pong`
+#### 5. 访问应用
 
-完整协议见 [docs/03-接口文档.md](docs/03-接口文档.md)。
+打开浏览器访问 [http://localhost:5173](http://localhost:5173)，注册账号后即可开始使用。
 
-## 文档
+#### 6. 代码检查与测试
+
+```bash
+# 安装 Go 代码检查工具
+go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+
+# 运行后端代码检查
+cd backend
+golangci-lint run
+
+# 后端单元测试
+go test ./...
+
+# 后端集成测试（需要 PostgreSQL）
+go test -tags=integration ./...
+
+# 前端代码检查
+cd frontend
+npm run lint
+
+# 前端测试
+npm test
+```
+
+### 远程部署
+
+#### 方式一：Docker Compose（推荐）
+
+```bash
+# 1. 克隆代码到服务器
+git clone https://github.com/yourusername/CamTalk.git
+cd CamTalk
+
+# 2. 配置环境变量
+cp backend/.env.example backend/.env
+# 编辑 .env 文件，填入生产环境配置
+
+# 3. 一键部署（frontend + backend + postgres + redis）
+./deploy.sh up
+
+# 4. 查看日志
+./deploy.sh logs
+
+# 5. 停止服务
+./deploy.sh down
+```
+
+部署完成后访问 [http://localhost:9000](http://localhost:9000)
+
+#### 方式二：手动部署
+
+```bash
+# 1. 构建前端
+cd frontend
+npm install
+npm run build  # 输出到 dist/
+
+# 2. 构建后端
+cd backend
+go build -o camtalk ./cmd/server
+
+# 3. 配置 Nginx
+# 参考 nginx.conf.example 配置反向代理
+
+# 4. 启动服务
+APP_ENV=prod ./camtalk
+
+# 5. 使用 systemd 管理（可选）
+sudo systemctl enable camtalk
+sudo systemctl start camtalk
+```
+
+#### 环境变量检查清单
+
+部署前确保已配置以下环境变量：
+
+- ✅ `CAMTALK_AUTH_JWT_SECRET`（使用 `openssl rand -hex 32` 生成）
+- ✅ `CAMTALK_STORAGE_DSN`（PostgreSQL 连接字符串）
+- ✅ `CAMTALK_AI_LLM_API_KEY`（DashScope API Key）
+- ✅ `CAMTALK_AI_STT_API_KEY`（STT 服务 API Key）
+- ✅ `CAMTALK_AI_TTS_API_KEY`（TTS 服务 API Key）
+- ✅ `APP_ENV=prod`（启用生产环境配置）
+
+### 配置优先级
+
+```
+环境变量 > config.{APP_ENV}.yaml > config.yaml > .env
+```
+
+通过 `APP_ENV=prod` 切换生产环境配置（启用限流 + 严格 CORS）
+
+## 📡 WebSocket 协议
+
+连接地址：`ws://localhost:8080/ws?token=<jwt>&conversation_id=<uuid>`
+
+所有消息为 JSON 文本帧，统一信封格式：
+
+```typescript
+interface BaseMessage {
+  type: string;
+  request_id?: string;
+  timestamp?: number;
+}
+```
+
+### 客户端 → 服务端
+
+| 消息类型 | 说明 | 示例 |
+|---------|------|------|
+| `query` | 发送视觉+语音查询 | `{type: "query", image: "base64...", audio: "base64..."}` |
+| `config` | 更新会话配置 | `{type: "config", scenario: "interviewer", language: "en"}` |
+| `interrupt` | 中断当前响应 | `{type: "interrupt", request_id: "xxx"}` |
+| `ping` | 心跳保活 | `{type: "ping"}` |
+
+### 服务端 → 客户端
+
+| 消息类型 | 说明 | 触发时机 |
+|---------|------|---------|
+| `connected` | 连接成功 | WebSocket 握手后 |
+| `stt_result` | STT 识别结果 | STT 节点完成 |
+| `llm_chunk` | LLM 文本增量 | ChatModel 逐 token（Callback） |
+| `llm_done` | LLM 推理完成 | Done 节点执行 |
+| `tts_audio` | TTS 音频片段 | TTS 节点逐句合成 |
+| `error` | 错误通知 | 任意节点失败 |
+| `pong` | 心跳响应 | 响应 `ping` |
+
+**心跳机制**：
+- 客户端每 30 秒发送 `ping`
+- 服务端 60 秒无消息自动断连
+- 断连后自动重连（指数退避 1s → 30s）
+
+完整协议定义见 [docs/02-接口文档.md](docs/02-接口文档.md)
+
+## 🔐 认证体系
+
+CamTalk 采用 **JWT 双 token 轮转 + Refresh Token Rotation** 安全机制：
+
+### 双 Token 设计
+
+| Token | 有效期 | 存储位置 | 用途 |
+|-------|-------|---------|------|
+| `access_token` | 120 分钟 | 前端内存（推荐）/ localStorage | 访问受保护资源 |
+| `refresh_token` | 7 天 | httpOnly Cookie（推荐）/ localStorage | 刷新 access_token |
+
+### Refresh Token Rotation
+
+每次刷新 token 时：
+1. 验证 `refresh_token` 签名和有效期
+2. 查询数据库中的 SHA256 哈希
+3. **如果哈希不存在** → 检测到 token 复用 → **吊销该用户所有 token**
+4. 删除旧 refresh_token，生成新 token pair
+5. 返回新 access_token + refresh_token
+
+**防重放攻击**：旧 refresh_token 立即失效，复用时触发全局吊销，强制所有设备重新登录。
+
+### REST API 端点
+
+- `POST /api/auth/register` — 用户注册
+- `POST /api/auth/login` — 用户登录
+- `POST /api/auth/refresh` — 刷新 token
+- `POST /api/auth/logout` — 登出（需认证）
+- `GET /api/conversations` — 获取对话列表（需认证）
+- `POST /api/conversations` — 创建对话（需认证）
+- `GET /api/health` — 健康检查
+
+详细设计见 [docs/10-鉴权体系.md](docs/10-鉴权体系.md)
+
+## 💾 三级存储架构
+
+**TieredManager** 实现会话状态的三级存储，平衡性能与可靠性：
+
+```
+┌─────────────┐
+│  L1 Memory  │ ← 微秒级读写，进程内缓存
+├─────────────┤
+│  L2 Redis   │ ← 毫秒级访问，跨实例共享
+├─────────────┤
+│ L3 PostgreSQL│ ← 持久化存储，数据可靠性
+└─────────────┘
+```
+
+**特性**：
+- ✅ **自动降级**：Redis 故障时自动切换到 Memory + PostgreSQL 模式
+- ✅ **灵活配置**：支持单级（Memory）、双级（Memory + PG）、完整三级
+- ✅ **TTL 管理**：会话默认 30 分钟过期，自动清理
+- ✅ **写穿透**：数据先写 L1，异步同步到 L2/L3
+
+## 📊 数据库设计
+
+系统使用 PostgreSQL 存储持久化数据：
+
+### 核心表
+
+| 表名 | 说明 | 关键字段 |
+|------|------|---------|
+| `users` | 用户账户 | `id (UUID)`, `username (UNIQUE)`, `password_hash (bcrypt)` |
+| `sessions` | 对话会话 | `id (UUID)`, `user_id (FK)`, `title`, `config (JSONB)` |
+| `messages` | 消息记录 | `id (BIGSERIAL)`, `session_id (FK)`, `role`, `content`, `tokens_used` |
+| `refresh_tokens` | 刷新令牌 | `token_hash (PK, SHA256)`, `user_id (FK)`, `expires_at` |
+
+**关系**：`users 1:N sessions 1:N messages`，`users 1:N refresh_tokens`
+
+**迁移管理**：使用嵌入式 SQL 文件（`backend/migrations/`），应用启动时自动执行。
+
+## 🛡️ 安全特性
+
+- 🔒 **密码安全**：bcrypt (cost=10) 哈希，自动生成盐值
+- 🔑 **Token 安全**：JWT HS256 签名，refresh_token SHA256 哈希存储
+- 🚫 **防重放攻击**：Refresh Token Rotation + 复用检测自动吊销
+- 🌐 **传输安全**：生产环境强制 HTTPS，开发环境 Vite proxy 同源代理
+- 🚦 **限流保护**：令牌桶算法（生产环境启用），防暴力破解
+- 🔍 **日志追踪**：全链路 Trace ID，请求/响应/错误统一记录
+
+## 🌍 部署架构
+
+```
+┌─────────────┐
+│   Nginx     │ ← 反向代理（静态资源 + API + WebSocket）
+└──────┬──────┘
+       │
+┌──────┴───────────────────┐
+│  Go Gateway 集群          │
+│  ├─ Gateway-1            │
+│  ├─ Gateway-2            │
+│  └─ Gateway-N            │
+└───┬────────────┬─────────┘
+    │            │
+┌───┴────┐  ┌───┴────────┐
+│ Redis  │  │ PostgreSQL │
+└────────┘  └────────────┘
+    │
+┌───┴────────────────────┐
+│  外部 AI 服务           │
+│  ├─ DashScope (LLM)   │
+│  ├─ MiMo (STT/TTS)    │
+│  └─ Deepgram (可选)    │
+└───────────────────────┘
+```
+
+**跨域策略**：Nginx 统一反代前后端到同一域名，无跨域问题。
+
+**水平扩展**：Gateway 无状态设计，会话状态存储在 Redis/PostgreSQL，支持多实例部署。
+
+## 📖 文档
+
+### 核心设计文档
 
 | 文档 | 内容 |
 |------|------|
-| [01-项目概述](docs/01-项目概述.md) | 项目目标与核心挑战 |
-| [02-系统架构](docs/02-系统架构.md) | 三层架构、技术栈、部署方案 |
-| [03-接口文档](docs/03-接口文档.md) | WebSocket 协议、REST API、配置管理 |
-| [04-技术选型](docs/04-技术选型.md) | AI 服务栈、持久化层、前端边缘处理选型 |
-| [05-用户故事](docs/05-用户故事.md) | 用户场景与优先级 |
-| [06-语音交互](docs/06-语音交互.md) | VAD → STT → LLM → TTS 全链路 |
-| [07-视觉理解](docs/07-视觉理解.md) | 帧采样、关键帧检测、多模态输入 |
-| [08-成本控制](docs/08-成本控制.md) | 采样策略、端云协同、模型分级 |
+| [01-架构设计](docs/01-架构设计.md) | 三层架构、技术栈、数据库设计、部署方案 |
+| [02-接口文档](docs/02-接口文档.md) | WebSocket 协议、REST API、AI 服务层、编排器、配置管理 |
+| [08-Eino框架与编排设计](docs/08-Eino框架与编排设计.md) | Eino Graph 7 节点 DAG、节点实现、流式处理、Callback AOP |
+| [10-鉴权体系](docs/10-鉴权体系.md) | JWT 双 token 轮转、Refresh Token Rotation、密码安全、中间件 |
+| [11-令牌桶限流](docs/11-令牌桶限流.md) | 限流算法、配置策略、生产环境保护 |
+| [13-日志追踪](docs/13-日志追踪.md) | Zap 日志、Trace ID 全链路追踪、日志级别 |
 
-## License
+### 功能文档
 
-[MIT](LICENSE) © XEngineers
+| 文档 | 内容 |
+|------|------|
+| [03-技术选型](docs/03-技术选型.md) | AI 服务栈、持久化层、前端边缘处理选型 |
+| [04-用户故事](docs/04-用户故事.md) | 用户场景与优先级 |
+| [05-语音交互](docs/05-语音交互.md) | VAD → STT → LLM → TTS 全链路 |
+| [06-视觉理解](docs/06-视觉理解.md) | 帧采样、关键帧检测、多模态输入 |
+| [07-成本控制](docs/07-成本控制.md) | 采样策略、端云协同、模型分级 |
+| [09-情景切换](docs/09-情景切换.md) | 情景模式设计与实现 |
+| [12-自定义情景](docs/12-自定义情景.md) | 用户自定义情景功能（规划中） |
+
+
+## 🐛 问题反馈
+
+遇到问题？请提交 [Issue](https://github.com/yourusername/CamTalk/issues)，并提供以下信息：
+
+- 操作系统版本
+- Go / Node.js 版本
+- 错误日志（后端日志 + 浏览器控制台）
+- 复现步骤
+
+## 📝 版权声明
+
+MIT License © 2024 XEngineers
+
+---
+
+<div align="center">
+
+**Built with ❤️ using Go, React, and AI**
+
+[⬆️ 回到顶部](#camtalk)
+
+</div>

backend/.env.example

@@ -1,5 +1,7 @@
 # 运行环境
-# dev / prod，决定加载 config.dev.yaml 或 config.prod.yaml（可选）
+# dev：本地开发环境（debug 日志、关闭限流、允许所有 CORS）
+# prod：生产环境（info 日志、启用限流、严格 CORS 白名单）
+# 本地开发保持 dev，生产部署会被 docker-compose.yml 覆盖为 prod
 APP_ENV=dev
 
 # AI 服务 API Key

backend/.gitignore

@@ -4,8 +4,6 @@ bin/
 
 # 环境配置
 .env
-config.dev.yaml
-config.prod.yaml
 
 # 临时文件
 tmp/

backend/Dockerfile

@@ -8,11 +8,19 @@ ENV GOPROXY=https://goproxy.cn,https://goproxy.io,direct
 
 # 先复制依赖清单，利用 Docker 缓存层
 COPY go.mod go.sum ./
-RUN go mod download
+
+# --mount=type=cache 复用 Go module 缓存，依赖不变时跳过下载
+RUN --mount=type=cache,target=/go/pkg/mod \
+    go mod download
 
 # 复制源码并构建
 COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -o /camtalk ./cmd/server
+
+# 复用 module 缓存 + 编译缓存；-ldflags="-s -w" 裁剪符号表减小 ~30% 体积
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/root/.cache/go-build \
+    CGO_ENABLED=0 GOOS=linux \
+    go build -ldflags="-s -w" -o /camtalk ./cmd/server
 
 # ---- 运行阶段 ----
 FROM alpine:3.20
@@ -23,7 +31,7 @@ WORKDIR /app
 
 # 复制二进制和配置文件（敏感配置通过 docker-compose env_file 注入覆盖）
 COPY --from=builder /camtalk .
-COPY config.yaml .
+COPY config/ ./config/
 
 EXPOSE 8080
 

backend/cmd/server/main.go

@@ -10,6 +10,7 @@ import (
 	"time"
 
 	"github.com/gin-gonic/gin"
+	"github.com/jackc/pgx/v5/pgxpool"
 	"github.com/redis/go-redis/v9"
 
 	"github.com/hhs/camtalk/internal/api"
@@ -19,8 +20,10 @@ import (
 	"github.com/hhs/camtalk/internal/config"
 	eino "github.com/hhs/camtalk/internal/eino"
 	"github.com/hhs/camtalk/internal/logger"
+	"github.com/hhs/camtalk/internal/ratelimit"
 	"github.com/hhs/camtalk/internal/session"
 	"github.com/hhs/camtalk/internal/store"
+	"github.com/hhs/camtalk/internal/trace"
 	"github.com/hhs/camtalk/internal/ws"
 	migrations "github.com/hhs/camtalk/migrations"
 )
@@ -54,6 +57,7 @@ func main() {
 	var userRepo store.UserRepository
 	var msgRepo store.MessageRepository
 	var sessRepo store.SessionRepository
+	var pool *pgxpool.Pool // 数据库连接池
 
 	// L3: PostgreSQL（冷数据持久化层）
 	dsn := cfg.Storage.Persistence.DSN
@@ -65,7 +69,8 @@ func main() {
 			logger.Log.Fatalw("storage.persistence.dsn is required when persistence is enabled",
 				"hint", "set CAMTALK_STORAGE_DSN environment variable")
 		}
-		pool, err := store.NewPostgresPool(ctx, dsn)
+		var err error
+		pool, err = store.NewPostgresPool(ctx, dsn)
 		if err != nil {
 			logger.Log.Fatalw("failed to connect to postgres", "error", err)
 		}
@@ -86,9 +91,10 @@ func main() {
 	}
 
 	// L2: Redis（热数据分布式会话层）
+	var rdb *redis.Client
 	var redisMgr *session.RedisManager
 	if cfg.Storage.Redis.Enabled {
-		rdb := redis.NewClient(&redis.Options{
+		rdb = redis.NewClient(&redis.Options{
 			Addr:     cfg.Redis.Addr,
 			Password: cfg.Redis.Password,
 			DB:       cfg.Redis.DB,
@@ -102,9 +108,12 @@ func main() {
 			time.Duration(cfg.Session.TTL)*time.Minute,
 			cfg.Session.MaxHistory,
 		)
+		// 包装 userRepo 为带 Redis 缓存的版本（refresh token 二级缓存）
+		userRepo = store.NewCachedUserRepository(userRepo, rdb, time.Duration(cfg.Auth.RefreshTTL)*time.Minute)
 		logger.Log.Infow("L2 Redis storage initialized",
 			"addr", cfg.Redis.Addr,
-			"db", cfg.Redis.DB)
+			"db", cfg.Redis.DB,
+			"cached_user_repo", true)
 	}
 
 	// 初始化 Session Manager（三级存储）
@@ -177,7 +186,11 @@ func main() {
 	}
 
 	// 初始化 Eino Graph + Orchestrator
-	pipelineGraph, err := eino.NewPipelineGraph(ctx, cfg, sttService, ttsService, sessionMgr)
+	var userScenarioRepo store.UserScenarioRepository
+	if pool != nil {
+		userScenarioRepo = store.NewPostgresUserScenarioRepo(pool)
+	}
+	pipelineGraph, err := eino.NewPipelineGraph(ctx, cfg, sttService, ttsService, sessionMgr, userScenarioRepo)
 	if err != nil {
 		logger.Log.Fatalw("failed to create eino pipeline graph", "error", err)
 	}
@@ -191,13 +204,32 @@ func main() {
 	)
 	authService := auth.NewAuthService(tokenMgr, userRepo)
 
+	// 初始化限流器
+	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")
+	}
+
 	// Gin 模式
 	if cfg.App.Env == "prod" {
 		gin.SetMode(gin.ReleaseMode)
 	}
 
 	r := gin.New()
-	r.Use(gin.Recovery())
+	r.Use(trace.TraceMiddleware())    // 第一层：生成 trace ID
+	r.Use(trace.GinLogger())          // 第二层：记录请求
+	r.Use(trace.GinRecovery())        // 第三层：panic 恢复
 
 	// REST API
 	apiGroup := r.Group("/api")
@@ -211,14 +243,29 @@ func main() {
 
 	// Auth REST 端点
 	authHandler := api.NewAuthHandler(authService, tokenMgr)
-	authHandler.RegisterRoutes(apiGroup)
+	authHandler.RegisterRoutes(apiGroup, limiter)
 
 	// Conversation REST 端点
 	convHandler := api.NewConversationHandler(sessionMgr, tokenMgr, msgRepo)
 	convHandler.RegisterRoutes(apiGroup)
 
+	// UserScenario REST 端点
+	if pool != nil {
+		userScenarioRepo := store.NewPostgresUserScenarioRepo(pool)
+		userScenarioHandler := api.NewUserScenarioHandler(userScenarioRepo)
+		scenarioGroup := apiGroup.Group("/scenarios")
+		scenarioGroup.Use(auth.AuthMiddleware(tokenMgr))
+		{
+			scenarioGroup.GET("", userScenarioHandler.List)
+			scenarioGroup.POST("", userScenarioHandler.Create)
+			scenarioGroup.GET("/:id", userScenarioHandler.Get)
+			scenarioGroup.PATCH("/:id", userScenarioHandler.Update)
+			scenarioGroup.DELETE("/:id", userScenarioHandler.Delete)
+		}
+	}
+
 	// WebSocket
-	r.GET("/ws", ws.ServeWS(sessionMgr, orch, cfg, tokenMgr))
+	r.GET("/ws", ws.ServeWS(sessionMgr, orch, cfg, tokenMgr, limiter, userScenarioRepo))
 
 	// HTTP Server
 	srv := &http.Server{

backend/config/config.dev.yaml

@@ -0,0 +1,68 @@
+# CamTalk 开发环境配置
+# 通过 APP_ENV=dev 加载此文件，覆盖 config.yaml 中的配置
+
+server:
+  host: "0.0.0.0"
+  port: 8080
+  heartbeat_interval: 30
+  heartbeat_timeout: 60
+  allowed_origins: []         # 开发环境允许所有来源
+
+session:
+  ttl: 30                     # 开发环境会话较短，方便测试过期逻辑
+  max_history: 20
+
+ai:
+  stt:
+    provider: mimo            # 与生产环境一致
+    model: mimo-v2.5-asr
+    endpoint: "https://api.xiaomimimo.com/v1"
+    timeout: 10               # 开发环境超时较长，方便调试
+    http_client_timeout: 30
+  llm:
+    provider: dashscope       # 与生产环境一致
+    model: qwen3-vl-plus
+    endpoint: "https://dashscope.aliyuncs.com/compatible-mode/v1"
+    timeout: 60               # 开发环境 LLM 超时较长
+    http_client_timeout: 120
+  tts:
+    provider: mimo            # 与生产环境一致
+    model: mimo-v2.5-tts
+    voice: mimo_default
+    speed: 1.0
+    endpoint: "https://token-plan-cn.xiaomimimo.com/v1"
+    timeout: 10
+    http_client_timeout: 30
+    output_format: mp3
+    sample_rate: 24000
+
+storage:
+  redis:
+    enabled: true             # 开发环境启用 Redis，测试三级存储
+  persistence:
+    enabled: true             # 开发环境启用持久化
+
+redis:
+  addr: "localhost:6379"      # 本地 Redis
+  password: ""
+  db: 0
+
+auth:
+  access_ttl: 120             # 开发环境 Access Token 2 小时，方便调试
+  refresh_ttl: 10080          # 7 天
+
+ratelimit:
+  enabled: false              # 开发环境关闭限流，方便测试
+  query:
+    capacity: 10
+    rate: 0.2
+  login:
+    capacity: 5
+    rate: 0.1
+  register:
+    capacity: 3
+    rate: 0.05
+
+log:
+  level: debug                # 开发环境 debug 日志
+  format: console             # 控制台格式，易读

backend/config/config.prod.yaml

@@ -0,0 +1,71 @@
+# CamTalk 生产环境配置
+# 通过 APP_ENV=prod 加载此文件，覆盖 config.yaml 中的配置
+
+server:
+  host: "0.0.0.0"
+  port: 8080
+  read_timeout: 30
+  write_timeout: 30
+  shutdown_timeout: 15        # 生产环境优雅关闭时间稍长
+  heartbeat_interval: 30
+  heartbeat_timeout: 60
+
+session:
+  ttl: 60                     # 生产环境会话 1 小时
+  max_history: 20
+
+ai:
+  stt:
+    provider: mimo            # 生产环境推荐 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            # 生产环境推荐 MiMo TTS
+    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             # 生产环境必须启用 Redis
+  persistence:
+    enabled: true             # 生产环境必须启用持久化
+    driver: postgres
+
+redis:
+  addr: "redis:6379"          # Docker Compose 内部服务名
+  password: ""                # 密码通过 CAMTALK_REDIS_PASSWORD 环境变量设置
+  db: 0
+
+auth:
+  access_ttl: 120             # 生产环境 Access Token 2 小时
+  refresh_ttl: 10080          # Refresh Token 7 天
+
+ratelimit:
+  enabled: true               # 生产环境启用限流
+  query:
+    capacity: 10              # 允许突发 10 个请求
+    rate: 0.2                 # 每 5 秒恢复 1 个令牌
+  login:
+    capacity: 5               # 防暴力破解
+    rate: 0.1                 # 每 10 秒恢复 1 次
+  register:
+    capacity: 3               # 防批量注册
+    rate: 0.05                # 每 20 秒恢复 1 次
+
+log:
+  level: info                 # 生产环境 info 级别
+  format: json                # JSON 格式，便于日志收集和分析

backend/config/config.yaml

@@ -57,9 +57,24 @@ redis:
 
 auth:
   # jwt_secret 通过环境变量 CAMTALK_AUTH_JWT_SECRET 设置
-  access_ttl: 15              # Access Token 过期时间（分钟）
+  access_ttl: 120              # Access Token 过期时间（分钟）
   refresh_ttl: 10080          # Refresh Token 过期时间（分钟），7 天
 
+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 次
+
 log:
   level: info                 # debug / info / warn / error
   format: console             # console / json

backend/go.mod

@@ -3,6 +3,7 @@ module github.com/hhs/camtalk
 go 1.25.0
 
 require (
+	github.com/alicebob/miniredis/v2 v2.38.0
 	github.com/cloudwego/eino v0.9.9
 	github.com/cloudwego/eino-ext/components/model/openai v0.1.13
 	github.com/gin-gonic/gin v1.10.0
@@ -11,6 +12,7 @@ require (
 	github.com/gorilla/websocket v1.5.3
 	github.com/jackc/pgx/v5 v5.10.0
 	github.com/joho/godotenv v1.5.1
+	github.com/oklog/ulid/v2 v2.1.1
 	github.com/redis/go-redis/v9 v9.20.1
 	github.com/spf13/viper v1.21.0
 	github.com/stretchr/testify v1.11.1
@@ -68,6 +70,7 @@ require (
 	github.com/ugorji/go/codec v1.2.12 // indirect
 	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
 	github.com/yargevad/filepathx v1.0.0 // indirect
+	github.com/yuin/gopher-lua v1.1.1 // indirect
 	go.uber.org/atomic v1.11.0 // indirect
 	go.uber.org/multierr v1.10.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect

backend/go.sum

@@ -1,4 +1,6 @@
 github.com/airbrake/gobrake v3.6.1+incompatible/go.mod h1:wM4gu3Cn0W0K7GUuVWnlXZU11AGBXMILnrdOU8Kn00o=
+github.com/alicebob/miniredis/v2 v2.38.0 h1:nZAzCR+Lj+Vxk4ZXzm2NuKq2O33RXj1XxJ2e2uP9jiw=
+github.com/alicebob/miniredis/v2 v2.38.0/go.mod h1:TcL7YfarKPGDAthEtl5NBeHZfeUQj6OXMm/+iu5cLMM=
 github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk=
 github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg=
 github.com/bitly/go-simplejson v0.5.0/go.mod h1:cXHtHw4XUPsvGaxgjIAn8PhEWG9NfngEKAMDJEczWVA=
@@ -127,9 +129,12 @@ github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9G
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/nikolalohinski/gonja v1.5.3 h1:GsA+EEaZDZPGJ8JtpeGN78jidhOlxeJROpqMT9fTj9c=
 github.com/nikolalohinski/gonja v1.5.3/go.mod h1:RmjwxNiXAEqcq1HeK5SSMmqFJvKOfTfXhkJv6YBtPa4=
+github.com/oklog/ulid/v2 v2.1.1 h1:suPZ4ARWLOJLegGFiZZ1dFAkqzhMjL3J1TzI+5wHz8s=
+github.com/oklog/ulid/v2 v2.1.1/go.mod h1:rcEKHmBBKfef9DhnvX7y1HZBYxjXb0cP5ExxNsTT1QQ=
 github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
 github.com/onsi/ginkgo v1.8.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
 github.com/onsi/gomega v1.5.0/go.mod h1:ex+gbHU/CVuBBDIJjb2X0qEXbFg53c61hWP/1CpauHY=
+github.com/pborman/getopt v0.0.0-20170112200414-7148bc3a4c30/go.mod h1:85jBQOZwpVEaDAr341tbn15RS4fCAsIst0qp7i8ex1o=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
 github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
@@ -190,6 +195,8 @@ github.com/x-cray/logrus-prefixed-formatter v0.5.2 h1:00txxvfBM9muc0jiLIEAkAcIMJ
 github.com/x-cray/logrus-prefixed-formatter v0.5.2/go.mod h1:2duySbKsL6M18s5GU7VPsoEPHyzalCE06qoARUCeBBE=
 github.com/yargevad/filepathx v1.0.0 h1:SYcT+N3tYGi+NvazubCNlvgIPbzAk7i7y2dwg3I5FYc=
 github.com/yargevad/filepathx v1.0.0/go.mod h1:BprfX/gpYNJHJfc35GjRRpVcwWXS89gGulUIU5tK3tA=
+github.com/yuin/gopher-lua v1.1.1 h1:kYKnWBjvbNP4XLT3+bPEwAXJx262OhaHDWDVOPjL46M=
+github.com/yuin/gopher-lua v1.1.1/go.mod h1:GBR0iDaNXjAgGg9zfCvksxSRnQx76gclCIb7kdAd1Pw=
 github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
 github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
 go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=

backend/internal/ai/llm/scenarios.go

@@ -2,54 +2,147 @@ package llm
 
 import "strings"
 
-// scenarioPrompt 定义单个情景的多语言 system prompt。
+// scenarioPrompt 定义单个情景的多语言 system prompt 和首句引导。
 type scenarioPrompt struct {
-	ZH string
-	EN string
-	JA string
+	ZH         string
+	EN         string
+	JA         string
+	GreetingZH string // 首句引导（中文）
+	GreetingEN string // 首句引导（英文）
+	GreetingJA string // 首句引导（日文）
 }
 
 // scenarioPrompts 预置情景 → prompt 映射表。
 // key 为情景 ID（与前端 Scenario.id 对齐）。
 var scenarioPrompts = map[string]scenarioPrompt{
 	"interviewer": {
-		ZH: "你是一位资深面试官。你通过摄像头观察面试者，并根据他们的背景和表现提出面试问题。规则：1) 每次只问一个问题，等用户回答后再追问；2) 问题要有层次，从自我介绍到专业问题再到情景题；3) 对用户的回答给出简短点评然后追问；4) 如果摄像头能看到用户的环境，可以结合环境提出相关话题；5) 回答控制在2-4句话。",
+		ZH: `你是一位资深面试官。你通过摄像头观察面试者，并根据他们的背景和表现提出面试问题。
+
+【角色定位】
+- 你是面试官，不是助手或顾问
+- 你的目标是评估候选人的能力
+- 保持专业、客观、礼貌
+
+【交互规则】
+1. 每次只问一个问题，等用户回答后再追问
+2. 问题要有层次：自我介绍 → 专业问题 → 情景题 → 反问环节
+3. 对用户的回答给出简短点评（优点+不足），然后追问
+4. 如果摄像头能看到用户的环境，可以结合环境提出相关话题
+5. 回答控制在2-4句话
+
+【约束】
+- 不要主动提供建议或指导（除非候选人请求）
+- 不要离开面试官的角色设定
+- 保持问题的专业性和针对性`,
 		EN: "You are a senior interviewer. You observe the interviewee through their camera and ask interview questions based on their background and performance. Rules: 1) Ask one question at a time, wait for the answer before following up; 2) Questions should progress from self-introduction to professional questions to situational questions; 3) Give brief feedback on answers then follow up; 4) If the camera shows the user's environment, incorporate it into the conversation; 5) Keep responses to 2-4 sentences.",
 		JA: "あなたはベテラン面接官です。カメラで面接者を見て、バックグラウンドと実績に基づいて面接質問をします。ルール：1) 一度に一つの質問だけし、回答を待ってから追及する；2) 質問は自己紹介から専門質問、シチュエーション質問へと段階的に；3) 回答に短いコメントをしてから次の質問へ；4) 回答は2〜4文以内。",
+		GreetingZH: "你好！我是今天的面试官。让我们先从自我介绍开始，请简单介绍一下你自己和你应聘的岗位。",
+		GreetingEN: "Hello! I'm your interviewer today. Let's start with a self-introduction. Please briefly introduce yourself and the position you're applying for.",
+		GreetingJA: "こんにちは！本日の面接官です。まず自己紹介から始めましょう。あなた自身と応募職種について簡単に教えてください。",
 	},
 	"english_teacher": {
 		ZH: "You are a friendly and patient English tutor. Speak in English with the user. Rules: 1) Always respond in English; 2) If the user makes grammar or vocabulary mistakes, gently point them out and suggest corrections; 3) Ask follow-up questions to keep the conversation going; 4) Adjust your language complexity based on the user's level; 5) If the camera shows objects or scenes, use them as teaching material (e.g., 'I can see a bookshelf behind you. What's your favorite book?'); 6) Keep responses to 3-5 sentences.",
 		EN: "You are a friendly and patient English tutor. Speak in English with the user. Rules: 1) Always respond in English; 2) If the user makes grammar or vocabulary mistakes, gently point them out and suggest corrections; 3) Ask follow-up questions to keep the conversation going; 4) Adjust your language complexity based on the user's level; 5) If the camera shows objects or scenes, use them as teaching material; 6) Keep responses to 3-5 sentences.",
 		JA: "You are a friendly and patient English tutor. Speak in English with the user. Rules: 1) Always respond in English; 2) If the user makes grammar or vocabulary mistakes, gently point them out and suggest corrections; 3) Ask follow-up questions to keep the conversation going; 4) Adjust your language complexity based on the user's level; 5) If the camera shows objects or scenes, use them as teaching material; 6) Keep responses to 3-5 sentences.",
+		GreetingZH: "Hi! I'm your English tutor. Let's practice English together! What would you like to talk about today?",
+		GreetingEN: "Hi! I'm your English tutor. Let's practice English together! What would you like to talk about today?",
+		GreetingJA: "Hi! I'm your English tutor. Let's practice English together! What would you like to talk about today?",
 	},
 	"debate": {
-		ZH: "你是一位辩论赛对手。用户提出一个观点，你需要站在反方进行反驳。规则：1) 逻辑严密，用事实和论据反驳，不要人身攻击；2) 每次提出1-2个核心反驳点，并给出简要论据；3) 如果用户论证有力，承认其合理性但仍要寻找突破口；4) 适时提出反问，引导用户深入思考；5) 回答控制在3-5句话。",
+		ZH: `你是一位辩论赛对手。用户提出一个观点，你需要站在反方进行反驳。
+
+【角色定位】
+- 你是辩论对手，不是评委或顾问
+- 你的目标是通过逻辑论证反驳对方观点
+- 保持理性、严谨、尊重对手
+
+【交互规则】
+1. 逻辑严密，用事实和论据反驳，不要人身攻击
+2. 每次提出1-2个核心反驳点，并给出简要论据
+3. 如果用户论证有力，承认其合理性但仍要寻找突破口
+4. 适时提出反问，引导用户深入思考
+5. 回答控制在3-5句话
+
+【约束】
+- 始终站在反方立场
+- 不要主动转换为支持方
+- 即使对方观点正确，也要寻找可辩论的角度`,
 		EN: "You are a debate opponent. The user presents a viewpoint, and you argue against it. Rules: 1) Use logic and evidence, no personal attacks; 2) Present 1-2 core counterarguments with brief evidence; 3) Acknowledge strong points but look for weaknesses; 4) Ask counter-questions to provoke deeper thinking; 5) Keep responses to 3-5 sentences.",
 		JA: "あなたはディベートの相手です。ユーザーが提示した观点に対して反論します。ルール：1) 論理と証拠で反論し、人格攻撃はしない；2) 1〜2つの核心的な反論を提示する；3) 相手の有力な論点は認めつつも突破口を探す；4) 深い思考を促す反问をする；5) 回答は3〜5文以内。",
+		GreetingZH: "你好！我是你的辩论对手。请提出一个你坚信的观点，我会站在反方立场与你辩论，帮你锻炼逻辑思维。",
+		GreetingEN: "Hello! I'm your debate opponent. Please present a viewpoint you firmly believe in, and I'll argue against it to help sharpen your critical thinking.",
+		GreetingJA: "こんにちは！あなたのディベート相手です。あなたが信じる观点を提示してください。反対の立場から論じて、論理的思考を鍛えます。",
 	},
 	"interpreter": {
 		ZH: "你是一名同声翻译员。将用户说的话实时翻译为目标语言。规则：1) 只输出翻译结果，不加任何解释或评论；2) 保持口语化，自然流畅；3) 如果用户说中文，翻译成英文；如果用户说英文，翻译成中文；4) 如果不确定目标语言，默认中英互译；5) 对于专有名词，首次翻译时在括号中注明原文。",
 		EN: "You are a simultaneous interpreter. Translate what the user says in real-time. Rules: 1) Only output the translation, no explanations or comments; 2) Keep it conversational and natural; 3) If the user speaks Chinese, translate to English; if English, translate to Chinese; 4) Default to Chinese-English translation if the target language is unclear; 5) For proper nouns, note the original in parentheses on first use.",
 		JA: "あなたは同時通訳者です。ユーザーの発言をリアルタイムで翻訳します。ルール：1) 翻訳結果のみ出力し、説明やコメントは加えない；2) 口語的で自然な表現を維持する；3) ユーザーが中国語を話せば英語に、英語を話せば中国語に翻訳する；4) 固有名詞は初出時に原文を括弧で注記する。",
+		GreetingZH: "我是你的同声翻译。请开始说话，我会实时将中文翻译成英文，或将英文翻译成中文。",
+		GreetingEN: "I'm your simultaneous interpreter. Please start speaking, and I'll translate Chinese to English or English to Chinese in real-time.",
+		GreetingJA: "私はあなたの同時通訳者です。お話しください。中国語を英語に、または英語を中国語にリアルタイムで翻訳します。",
 	},
 }
 
 // GetScenarioPrompt 根据情景 ID 和语言获取对应的 system prompt。
+// 支持系统预置情景和用户自建情景。
+// customScenarios: 用户自建情景映射表（scenarioID → prompt），可为 nil
 // 返回空字符串表示无此情景（使用默认 prompt）。
-func GetScenarioPrompt(scenarioID, language string) string {
+func GetScenarioPrompt(scenarioID, language string, customScenarios map[string]string) string {
 	if scenarioID == "" || scenarioID == "free_chat" {
 		return ""
 	}
-	p, ok := scenarioPrompts[scenarioID]
-	if !ok {
+
+	// 1. 优先查找系统预置情景
+	if p, ok := scenarioPrompts[scenarioID]; ok {
+		switch {
+		case strings.HasPrefix(language, "zh"):
+			return p.ZH
+		case strings.HasPrefix(language, "ja"):
+			return p.JA
+		default:
+			return p.EN
+		}
+	}
+
+	// 2. 查找用户自建情景
+	if customScenarios != nil {
+		if customPrompt, ok := customScenarios[scenarioID]; ok {
+			return customPrompt
+		}
+	}
+
+	// 3. 默认空字符串
+	return ""
+}
+
+// GetScenarioGreeting 根据情景 ID 和语言获取对应的首句引导。
+// 支持系统预置情景和用户自建情景。
+// customGreetings: 用户自建情景的首句引导映射表（scenarioID → greeting），可为 nil
+// 返回空字符串表示无此情景或不需要引导（自由对话）。
+func GetScenarioGreeting(scenarioID, language string, customGreetings map[string]string) string {
+	if scenarioID == "" || scenarioID == "free_chat" {
 		return ""
 	}
-	switch {
-	case strings.HasPrefix(language, "zh"):
-		return p.ZH
-	case strings.HasPrefix(language, "ja"):
-		return p.JA
-	default:
-		return p.EN
+
+	// 1. 优先查找系统预置情景
+	if p, ok := scenarioPrompts[scenarioID]; ok {
+		switch {
+		case strings.HasPrefix(language, "zh"):
+			return p.GreetingZH
+		case strings.HasPrefix(language, "ja"):
+			return p.GreetingJA
+		default:
+			return p.GreetingEN
+		}
 	}
+
+	// 2. 查找用户自建情景
+	if customGreetings != nil {
+		if customGreeting, ok := customGreetings[scenarioID]; ok {
+			return customGreeting
+		}
+	}
+
+	// 3. 默认空字符串
+	return ""
 }

backend/internal/ai/tts/mimo.go

@@ -11,6 +11,8 @@ import (
 	"strings"
 	"time"
 
+	"github.com/hhs/camtalk/internal/trace"
+	"github.com/hhs/camtalk/internal/util"
 	"go.uber.org/zap"
 )
 
@@ -108,7 +110,11 @@ func (m *MiMoService) SynthesizeStream(ctx context.Context, textStream <-chan st
 
 			audio, err := m.synthesize(ctx, text, voice)
 			if err != nil {
-				m.logger.Warnw("mimo tts: synthesize failed", "error", err, "text", text)
+				log := trace.FromContext(ctx)
+				log.Warnw("mimo tts: synthesize failed",
+					"error", err,
+					"text_len", len(text),
+					"text_preview", util.Truncate(text, 100))
 				// 静默跳过，不中断整个流
 				continue
 			}

backend/internal/ai/tts/openai.go

@@ -9,6 +9,8 @@ import (
 	"net/http"
 	"time"
 
+	"github.com/hhs/camtalk/internal/trace"
+	"github.com/hhs/camtalk/internal/util"
 	"go.uber.org/zap"
 )
 
@@ -81,7 +83,11 @@ func (o *OpenAIService) SynthesizeStream(ctx context.Context, textStream <-chan
 
 			audio, err := o.synthesize(ctx, text, voice, speed)
 			if err != nil {
-				o.logger.Warnw("tts: synthesize failed", "error", err, "text", text)
+				log := trace.FromContext(ctx)
+				log.Warnw("tts: synthesize failed",
+					"error", err,
+					"text_len", len(text),
+					"text_preview", util.Truncate(text, 100))
 				// 静默跳过，不中断整个流
 				continue
 			}

backend/internal/api/auth.go

@@ -8,6 +8,8 @@ import (
 
 	"github.com/hhs/camtalk/internal/auth"
 	apperr "github.com/hhs/camtalk/internal/errors"
+	"github.com/hhs/camtalk/internal/ratelimit"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // AuthHandler 提供认证相关的 REST 端点。
@@ -25,11 +27,26 @@ func NewAuthHandler(authService auth.Service, tokenMgr *auth.TokenManager) *Auth
 }
 
 // RegisterRoutes 注册认证相关路由到给定的路由组。
-func (h *AuthHandler) RegisterRoutes(rg *gin.RouterGroup) {
+func (h *AuthHandler) RegisterRoutes(rg *gin.RouterGroup, limiter ratelimit.Limiter) {
 	authGroup := rg.Group("/auth")
 	{
-		authGroup.POST("/register", h.Register)
-		authGroup.POST("/login", h.Login)
+		// 注册和登录端点添加限流中间件（按 IP 限流）
+		if limiter != nil {
+			authGroup.POST("/register",
+				ratelimit.Middleware(limiter, func(c *gin.Context) string {
+					return c.ClientIP() + ":register"
+				}),
+				h.Register)
+			authGroup.POST("/login",
+				ratelimit.Middleware(limiter, func(c *gin.Context) string {
+					return c.ClientIP() + ":login"
+				}),
+				h.Login)
+		} else {
+			authGroup.POST("/register", h.Register)
+			authGroup.POST("/login", h.Login)
+		}
+		// refresh 和 logout 不限流
 		authGroup.POST("/refresh", h.Refresh)
 		authGroup.POST("/logout", auth.AuthMiddleware(h.tokenMgr), h.Logout)
 	}
@@ -37,6 +54,9 @@ func (h *AuthHandler) RegisterRoutes(rg *gin.RouterGroup) {
 
 // Register POST /api/auth/register — 用户注册。
 func (h *AuthHandler) Register(c *gin.Context) {
+	log := trace.FromContext(c.Request.Context())
+	clientIP := c.ClientIP()
+
 	var req auth.RegisterRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{
@@ -56,15 +76,25 @@ func (h *AuthHandler) Register(c *gin.Context) {
 
 	resp, err := h.authService.Register(c.Request.Context(), req)
 	if err != nil {
+		log.Warnw("register failed",
+			"username", req.Username,
+			"client_ip", clientIP,
+			"error", err)
 		handleAuthError(c, err)
 		return
 	}
 
+	log.Infow("register success",
+		"username", req.Username,
+		"client_ip", clientIP)
 	c.JSON(http.StatusCreated, resp)
 }
 
 // Login POST /api/auth/login — 用户登录。
 func (h *AuthHandler) Login(c *gin.Context) {
+	log := trace.FromContext(c.Request.Context())
+	clientIP := c.ClientIP()
+
 	var req auth.LoginRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{
@@ -84,15 +114,24 @@ func (h *AuthHandler) Login(c *gin.Context) {
 
 	resp, err := h.authService.Login(c.Request.Context(), req)
 	if err != nil {
+		log.Warnw("login failed",
+			"username", req.Username,
+			"client_ip", clientIP,
+			"error", err)
 		handleAuthError(c, err)
 		return
 	}
 
+	log.Infow("login success",
+		"username", req.Username,
+		"client_ip", clientIP)
 	c.JSON(http.StatusOK, resp)
 }
 
 // Refresh POST /api/auth/refresh — 刷新令牌。
 func (h *AuthHandler) Refresh(c *gin.Context) {
+	log := trace.FromContext(c.Request.Context())
+
 	var req auth.RefreshRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{
@@ -112,15 +151,21 @@ func (h *AuthHandler) Refresh(c *gin.Context) {
 
 	resp, err := h.authService.Refresh(c.Request.Context(), req)
 	if err != nil {
+		log.Warnw("token refresh failed",
+			"client_ip", c.ClientIP(),
+			"error", err)
 		handleAuthError(c, err)
 		return
 	}
 
+	log.Infow("token refresh success",
+		"client_ip", c.ClientIP())
 	c.JSON(http.StatusOK, resp)
 }
 
 // Logout POST /api/auth/logout — 登出（需要认证）。
 func (h *AuthHandler) Logout(c *gin.Context) {
+	log := trace.FromContext(c.Request.Context())
 	userID := c.GetString(auth.ContextKeyUserID)
 
 	var req struct {
@@ -143,6 +188,9 @@ func (h *AuthHandler) Logout(c *gin.Context) {
 	}
 
 	if err := h.authService.Logout(c.Request.Context(), userID, req.RefreshToken); err != nil {
+		log.Errorw("logout failed",
+			"user_id", userID,
+			"error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"code":    apperr.CodeInternalError,
 			"message": "failed to logout",
@@ -150,6 +198,8 @@ func (h *AuthHandler) Logout(c *gin.Context) {
 		return
 	}
 
+	log.Infow("logout success",
+		"user_id", userID)
 	c.JSON(http.StatusOK, gin.H{
 		"message": "logged out successfully",
 	})
@@ -158,8 +208,8 @@ func (h *AuthHandler) Logout(c *gin.Context) {
 // validateCredentials 校验用户名和密码格式。
 // 返回空字符串表示校验通过，否则返回错误描述。
 func validateCredentials(username, password string) string {
-	if len(username) < 3 || len(username) > 64 {
-		return "username must be 3-64 characters"
+	if len(username) > 64 {
+		return "username must not exceed 64 characters"
 	}
 	if len(password) < 8 || len(password) > 72 {
 		return "password must be 8-72 characters"

backend/internal/api/auth_test.go

@@ -47,7 +47,7 @@ func newTestRouter(svc auth.Service) *gin.Engine {
 	r := gin.New()
 	tm := auth.NewTokenManager("test-secret", 15*time.Minute, 7*24*time.Hour)
 	h := api.NewAuthHandler(svc, tm)
-	h.RegisterRoutes(r.Group("/api"))
+	h.RegisterRoutes(r.Group("/api"), nil) // 测试时不启用限流
 	return r
 }
 
@@ -57,7 +57,7 @@ func newTestRouterWithToken(svc auth.Service) (*gin.Engine, *auth.TokenManager)
 	r := gin.New()
 	tm := auth.NewTokenManager("test-secret", 15*time.Minute, 7*24*time.Hour)
 	h := api.NewAuthHandler(svc, tm)
-	h.RegisterRoutes(r.Group("/api"))
+	h.RegisterRoutes(r.Group("/api"), nil) // 测试时不启用限流
 	return r, tm
 }
 

backend/internal/api/conversation.go

@@ -13,6 +13,7 @@ import (
 	"github.com/hhs/camtalk/internal/models"
 	"github.com/hhs/camtalk/internal/session"
 	"github.com/hhs/camtalk/internal/store"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // ConversationHandler 提供对话相关的 REST 端点。
@@ -47,6 +48,7 @@ func (h *ConversationHandler) RegisterRoutes(rg *gin.RouterGroup) {
 
 // List GET /api/conversations — 获取当前用户的对话列表。
 func (h *ConversationHandler) List(c *gin.Context) {
+	log := trace.FromContext(c.Request.Context())
 	userID := c.GetString(auth.ContextKeyUserID)
 
 	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
@@ -61,6 +63,9 @@ func (h *ConversationHandler) List(c *gin.Context) {
 
 	summaries, total, err := h.sessionMgr.ListByUser(c.Request.Context(), userID, page, size)
 	if err != nil {
+		log.Errorw("list conversations failed",
+			"user_id", userID,
+			"error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"code":    apperr.CodeInternalError,
 			"message": "failed to list conversations",
@@ -83,6 +88,7 @@ type CreateConversationRequest struct {
 
 // Create POST /api/conversations — 创建新对话。
 func (h *ConversationHandler) Create(c *gin.Context) {
+	log := trace.FromContext(c.Request.Context())
 	userID := c.GetString(auth.ContextKeyUserID)
 
 	var req CreateConversationRequest
@@ -95,6 +101,9 @@ func (h *ConversationHandler) Create(c *gin.Context) {
 
 	sessionID, err := h.sessionMgr.Create(c.Request.Context(), userID, cfg)
 	if err != nil {
+		log.Errorw("create conversation failed",
+			"user_id", userID,
+			"error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"code":    apperr.CodeInternalError,
 			"message": "failed to create conversation",
@@ -104,6 +113,9 @@ func (h *ConversationHandler) Create(c *gin.Context) {
 
 	sess, err := h.sessionMgr.Get(c.Request.Context(), sessionID)
 	if err != nil {
+		log.Errorw("retrieve created conversation failed",
+			"session_id", sessionID,
+			"error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"code":    apperr.CodeInternalError,
 			"message": "failed to retrieve created conversation",
@@ -111,6 +123,9 @@ func (h *ConversationHandler) Create(c *gin.Context) {
 		return
 	}
 
+	log.Infow("conversation created",
+		"conversation_id", sess.ID,
+		"user_id", userID)
 	c.JSON(http.StatusCreated, gin.H{
 		"id":          sess.ID,
 		"title":       sess.Title,
@@ -144,6 +159,7 @@ type UpdateTitleRequest struct {
 
 // UpdateTitle PATCH /api/conversations/:id — 更新对话标题。
 func (h *ConversationHandler) UpdateTitle(c *gin.Context) {
+	log := trace.FromContext(c.Request.Context())
 	sessionID := c.Param("id")
 
 	// 先校验归属
@@ -176,6 +192,9 @@ func (h *ConversationHandler) UpdateTitle(c *gin.Context) {
 			})
 			return
 		}
+		log.Errorw("update title failed",
+			"session_id", sessionID,
+			"error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"code":    apperr.CodeInternalError,
 			"message": "failed to update title",
@@ -190,6 +209,7 @@ func (h *ConversationHandler) UpdateTitle(c *gin.Context) {
 
 // Delete DELETE /api/conversations/:id — 删除对话。
 func (h *ConversationHandler) Delete(c *gin.Context) {
+	log := trace.FromContext(c.Request.Context())
 	sessionID := c.Param("id")
 
 	// 先校验归属
@@ -205,6 +225,9 @@ func (h *ConversationHandler) Delete(c *gin.Context) {
 			})
 			return
 		}
+		log.Errorw("delete conversation failed",
+			"session_id", sessionID,
+			"error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"code":    apperr.CodeInternalError,
 			"message": "failed to delete conversation",
@@ -221,6 +244,7 @@ func (h *ConversationHandler) Delete(c *gin.Context) {
 //   - limit: 返回消息数量上限，默认 50
 //   - before: 消息 ID 游标（用于分页），返回此 ID 之前的消息
 func (h *ConversationHandler) GetMessages(c *gin.Context) {
+	log := trace.FromContext(c.Request.Context())
 	sessionID := c.Param("id")
 
 	// 先校验归属
@@ -239,6 +263,9 @@ func (h *ConversationHandler) GetMessages(c *gin.Context) {
 	if h.msgRepo != nil {
 		messages, err := h.msgRepo.GetMessages(c.Request.Context(), sessionID, limit, beforeID)
 		if err != nil {
+			log.Errorw("get messages failed",
+				"session_id", sessionID,
+				"error", err)
 			c.JSON(http.StatusInternalServerError, gin.H{
 				"code":    apperr.CodeInternalError,
 				"message": "failed to get messages",
@@ -246,6 +273,9 @@ func (h *ConversationHandler) GetMessages(c *gin.Context) {
 			return
 		}
 		count, _ := h.msgRepo.GetMessageCount(c.Request.Context(), sessionID)
+		if messages == nil {
+			messages = []store.StoredMessage{}
+		}
 		c.JSON(http.StatusOK, gin.H{
 			"messages": messages,
 			"total":    count,
@@ -263,6 +293,9 @@ func (h *ConversationHandler) GetMessages(c *gin.Context) {
 			})
 			return
 		}
+		log.Errorw("get messages failed",
+			"session_id", sessionID,
+			"error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"code":    apperr.CodeInternalError,
 			"message": "failed to get messages",
@@ -284,6 +317,9 @@ func (h *ConversationHandler) GetMessages(c *gin.Context) {
 	}
 	messages := allMessages[start:]
 
+	if messages == nil {
+		messages = []models.Message{}
+	}
 	c.JSON(http.StatusOK, gin.H{
 		"messages": messages,
 		"total":    total,

backend/internal/api/session.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/hhs/camtalk/internal/models"
 	"github.com/hhs/camtalk/internal/session"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // SessionHandler 提供会话相关的 REST 端点。
@@ -27,6 +28,8 @@ type CreateSessionRequest struct {
 
 // CreateSession POST /api/sessions — 创建新会话。
 func (h *SessionHandler) CreateSession(c *gin.Context) {
+	log := trace.FromContext(c.Request.Context())
+
 	var req CreateSessionRequest
 	// 请求体可选，解析失败不报错（使用默认配置）
 	_ = c.ShouldBindJSON(&req)
@@ -38,6 +41,8 @@ func (h *SessionHandler) CreateSession(c *gin.Context) {
 
 	sessionID, err := h.sessionMgr.Create(c.Request.Context(), "", cfg)
 	if err != nil {
+		log.Errorw("create session failed",
+			"error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"code":    "INTERNAL_ERROR",
 			"message": "failed to create session",
@@ -48,6 +53,9 @@ func (h *SessionHandler) CreateSession(c *gin.Context) {
 	// 获取创建后的会话以返回 created_at
 	sess, err := h.sessionMgr.Get(c.Request.Context(), sessionID)
 	if err != nil {
+		log.Errorw("retrieve created session failed",
+			"session_id", sessionID,
+			"error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"code":    "INTERNAL_ERROR",
 			"message": "failed to retrieve created session",
@@ -55,6 +63,8 @@ func (h *SessionHandler) CreateSession(c *gin.Context) {
 		return
 	}
 
+	log.Infow("session created",
+		"session_id", sess.ID)
 	c.JSON(http.StatusCreated, gin.H{
 		"session_id": sess.ID,
 		"created_at": sess.CreatedAt,
@@ -63,6 +73,7 @@ func (h *SessionHandler) CreateSession(c *gin.Context) {
 
 // DestroySession DELETE /api/sessions/:id — 销毁会话。
 func (h *SessionHandler) DestroySession(c *gin.Context) {
+	log := trace.FromContext(c.Request.Context())
 	sessionID := c.Param("id")
 
 	err := h.sessionMgr.Destroy(c.Request.Context(), sessionID)
@@ -74,6 +85,9 @@ func (h *SessionHandler) DestroySession(c *gin.Context) {
 			})
 			return
 		}
+		log.Errorw("destroy session failed",
+			"session_id", sessionID,
+			"error", err)
 		c.JSON(http.StatusInternalServerError, gin.H{
 			"code":    "INTERNAL_ERROR",
 			"message": "failed to destroy session",
@@ -81,6 +95,8 @@ func (h *SessionHandler) DestroySession(c *gin.Context) {
 		return
 	}
 
+	log.Infow("session destroyed",
+		"session_id", sessionID)
 	c.Status(http.StatusNoContent)
 }
 

backend/internal/api/user_scenario_handler.go

@@ -0,0 +1,208 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/hhs/camtalk/internal/logger"
+	"github.com/hhs/camtalk/internal/models"
+	"github.com/hhs/camtalk/internal/store"
+)
+
+const (
+	MaxScenariosPerUser = 20   // 每个用户最多 20 个自建情景
+	MaxPromptLength     = 2000 // Prompt 最大长度
+)
+
+// UserScenarioHandler 用户情景 API Handler。
+type UserScenarioHandler struct {
+	repo store.UserScenarioRepository
+}
+
+// NewUserScenarioHandler 创建用户情景 Handler。
+func NewUserScenarioHandler(repo store.UserScenarioRepository) *UserScenarioHandler {
+	return &UserScenarioHandler{repo: repo}
+}
+
+// List 获取用户的所有自建情景。
+// GET /api/scenarios
+func (h *UserScenarioHandler) List(c *gin.Context) {
+	userID, exists := c.Get("user_id")
+	if !exists {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "未登录"})
+		return
+	}
+
+	scenarios, err := h.repo.FindByUserID(c.Request.Context(), userID.(string))
+	if err != nil {
+		logger.Log.Errorw("查询用户情景失败", "user_id", userID, "error", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "查询失败"})
+		return
+	}
+
+	if scenarios == nil {
+		scenarios = []*models.UserScenario{}
+	}
+
+	c.JSON(http.StatusOK, models.UserScenarioListResponse{
+		Scenarios: scenarios,
+		Total:     len(scenarios),
+	})
+}
+
+// Create 创建用户情景。
+// POST /api/scenarios
+func (h *UserScenarioHandler) Create(c *gin.Context) {
+	userID, exists := c.Get("user_id")
+	if !exists {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "未登录"})
+		return
+	}
+
+	var req models.CreateUserScenarioRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "参数错误: " + err.Error()})
+		return
+	}
+
+	// 检查用户是否已达上限
+	count, err := h.repo.CountByUserID(c.Request.Context(), userID.(string))
+	if err != nil {
+		logger.Log.Errorw("统计用户情景数量失败", "user_id", userID, "error", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "创建失败"})
+		return
+	}
+	if count >= MaxScenariosPerUser {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "已达创建上限（最多 20 个）"})
+		return
+	}
+
+	// 创建情景
+	scenario := &models.UserScenario{
+		UserID:      userID.(string),
+		Name:        req.Name,
+		Icon:        req.Icon,
+		Description: req.Description,
+		Prompt:      req.Prompt,
+		Greeting:    req.Greeting,
+		Language:    req.Language,
+	}
+
+	if err := h.repo.Create(c.Request.Context(), scenario); err != nil {
+		logger.Log.Errorw("创建用户情景失败", "user_id", userID, "error", err)
+		if err.Error() == "duplicate key value violates unique constraint" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "情景名称已存在"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "创建失败"})
+		return
+	}
+
+	logger.Log.Infow("创建用户情景成功", "user_id", userID, "scenario_id", scenario.ID)
+	c.JSON(http.StatusCreated, scenario)
+}
+
+// Get 获取单个情景详情。
+// GET /api/scenarios/:id
+func (h *UserScenarioHandler) Get(c *gin.Context) {
+	userID, exists := c.Get("user_id")
+	if !exists {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "未登录"})
+		return
+	}
+
+	scenarioID := c.Param("id")
+	scenario, err := h.repo.FindByIDAndUserID(c.Request.Context(), scenarioID, userID.(string))
+	if err != nil {
+		logger.Log.Errorw("查询用户情景失败", "user_id", userID, "scenario_id", scenarioID, "error", err)
+		c.JSON(http.StatusNotFound, gin.H{"error": "情景不存在或无权限"})
+		return
+	}
+
+	c.JSON(http.StatusOK, scenario)
+}
+
+// Update 更新用户情景。
+// PATCH /api/scenarios/:id
+func (h *UserScenarioHandler) Update(c *gin.Context) {
+	userID, exists := c.Get("user_id")
+	if !exists {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "未登录"})
+		return
+	}
+
+	scenarioID := c.Param("id")
+
+	// 查询并校验所有权
+	scenario, err := h.repo.FindByIDAndUserID(c.Request.Context(), scenarioID, userID.(string))
+	if err != nil {
+		logger.Log.Errorw("查询用户情景失败", "user_id", userID, "scenario_id", scenarioID, "error", err)
+		c.JSON(http.StatusNotFound, gin.H{"error": "情景不存在或无权限"})
+		return
+	}
+
+	var req models.UpdateUserScenarioRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "参数错误: " + err.Error()})
+		return
+	}
+
+	// 更新字段
+	if req.Name != nil {
+		scenario.Name = *req.Name
+	}
+	if req.Icon != nil {
+		scenario.Icon = *req.Icon
+	}
+	if req.Description != nil {
+		scenario.Description = *req.Description
+	}
+	if req.Prompt != nil {
+		scenario.Prompt = *req.Prompt
+	}
+	if req.Greeting != nil {
+		scenario.Greeting = *req.Greeting
+	}
+	if req.Language != nil {
+		scenario.Language = *req.Language
+	}
+
+	if err := h.repo.Update(c.Request.Context(), scenario); err != nil {
+		logger.Log.Errorw("更新用户情景失败", "user_id", userID, "scenario_id", scenarioID, "error", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "更新失败"})
+		return
+	}
+
+	logger.Log.Infow("更新用户情景成功", "user_id", userID, "scenario_id", scenarioID)
+	c.JSON(http.StatusOK, scenario)
+}
+
+// Delete 删除用户情景。
+// DELETE /api/scenarios/:id
+func (h *UserScenarioHandler) Delete(c *gin.Context) {
+	userID, exists := c.Get("user_id")
+	if !exists {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "未登录"})
+		return
+	}
+
+	scenarioID := c.Param("id")
+
+	// 查询并校验所有权
+	_, err := h.repo.FindByIDAndUserID(c.Request.Context(), scenarioID, userID.(string))
+	if err != nil {
+		logger.Log.Errorw("查询用户情景失败", "user_id", userID, "scenario_id", scenarioID, "error", err)
+		c.JSON(http.StatusNotFound, gin.H{"error": "情景不存在或无权限"})
+		return
+	}
+
+	if err := h.repo.Delete(c.Request.Context(), scenarioID); err != nil {
+		logger.Log.Errorw("删除用户情景失败", "user_id", userID, "scenario_id", scenarioID, "error", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "删除失败"})
+		return
+	}
+
+	logger.Log.Infow("删除用户情景成功", "user_id", userID, "scenario_id", scenarioID)
+	c.Status(http.StatusNoContent)
+}

backend/internal/auth/jwt.go

@@ -15,10 +15,17 @@ var (
 	ErrInvalidToken = errors.New("invalid or expired token")
 )
 
+// 令牌类型常量。
+const (
+	TokenTypeAccess  = "access"
+	TokenTypeRefresh = "refresh"
+)
+
 // Claims JWT 声明。
 type Claims struct {
-	UserID   string `json:"user_id"`
-	Username string `json:"username"`
+	UserID    string `json:"user_id"`
+	Username  string `json:"username"`
+	TokenType string `json:"token_type"`
 	jwt.RegisteredClaims
 }
 
@@ -45,8 +52,9 @@ func (tm *TokenManager) GeneratePair(userID, username string) (access, refresh s
 
 	// access token
 	accessClaims := &Claims{
-		UserID:   userID,
-		Username: username,
+		UserID:    userID,
+		Username:  username,
+		TokenType: TokenTypeAccess,
 		RegisteredClaims: jwt.RegisteredClaims{
 			ExpiresAt: jwt.NewNumericDate(now.Add(tm.accessTTL)),
 			IssuedAt:  jwt.NewNumericDate(now),
@@ -62,8 +70,9 @@ func (tm *TokenManager) GeneratePair(userID, username string) (access, refresh s
 	// refresh token（含唯一 token_id 用于 DB 关联）
 	tokenID := uuid.New().String()
 	refreshClaims := &Claims{
-		UserID:   userID,
-		Username: username,
+		UserID:    userID,
+		Username:  username,
+		TokenType: TokenTypeRefresh,
 		RegisteredClaims: jwt.RegisteredClaims{
 			ID:        tokenID,
 			ExpiresAt: jwt.NewNumericDate(now.Add(tm.refreshTTL)),
@@ -78,12 +87,26 @@ func (tm *TokenManager) GeneratePair(userID, username string) (access, refresh s
 
 // ValidateAccess 校验 access token 并返回 Claims。
 func (tm *TokenManager) ValidateAccess(tokenStr string) (*Claims, error) {
-	return tm.validate(tokenStr)
+	claims, err := tm.validate(tokenStr)
+	if err != nil {
+		return nil, err
+	}
+	if claims.TokenType != TokenTypeAccess {
+		return nil, ErrInvalidToken
+	}
+	return claims, nil
 }
 
 // ValidateRefresh 校验 refresh token 并返回 Claims。
 func (tm *TokenManager) ValidateRefresh(tokenStr string) (*Claims, error) {
-	return tm.validate(tokenStr)
+	claims, err := tm.validate(tokenStr)
+	if err != nil {
+		return nil, err
+	}
+	if claims.TokenType != TokenTypeRefresh {
+		return nil, ErrInvalidToken
+	}
+	return claims, nil
 }
 
 // validate 解析并校验 JWT。

backend/internal/auth/jwt_test.go

@@ -103,6 +103,44 @@ func TestValidateRefresh_ExpiredToken(t *testing.T) {
 	assert.ErrorIs(t, err, ErrInvalidToken)
 }
 
+func TestValidateAccess_RejectsRefreshToken(t *testing.T) {
+	tm := NewTokenManager("test-secret-key", 15*time.Minute, 7*24*time.Hour)
+
+	_, refresh, err := tm.GeneratePair("user-123", "alice")
+	require.NoError(t, err)
+
+	// refresh token 不能通过 access 校验
+	_, err = tm.ValidateAccess(refresh)
+	assert.ErrorIs(t, err, ErrInvalidToken)
+}
+
+func TestValidateRefresh_RejectsAccessToken(t *testing.T) {
+	tm := NewTokenManager("test-secret-key", 15*time.Minute, 7*24*time.Hour)
+
+	access, _, err := tm.GeneratePair("user-123", "alice")
+	require.NoError(t, err)
+
+	// access token 不能通过 refresh 校验
+	_, err = tm.ValidateRefresh(access)
+	assert.ErrorIs(t, err, ErrInvalidToken)
+}
+
+func TestGeneratePair_TokenTypesAreCorrect(t *testing.T) {
+	tm := NewTokenManager("test-secret-key", 15*time.Minute, 7*24*time.Hour)
+
+	access, refresh, err := tm.GeneratePair("user-123", "alice")
+	require.NoError(t, err)
+
+	// 通过 validate（不做类型检查）验证 token_type 字段
+	accessClaims, err := tm.validate(access)
+	require.NoError(t, err)
+	assert.Equal(t, TokenTypeAccess, accessClaims.TokenType)
+
+	refreshClaims, err := tm.validate(refresh)
+	require.NoError(t, err)
+	assert.Equal(t, TokenTypeRefresh, refreshClaims.TokenType)
+}
+
 func TestGeneratePair_TokenClaimsContainCorrectExpiry(t *testing.T) {
 	accessTTL := 15 * time.Minute
 	refreshTTL := 7 * 24 * time.Hour

backend/internal/auth/middleware.go

@@ -5,6 +5,8 @@ import (
 	"strings"
 
 	"github.com/gin-gonic/gin"
+
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // contextKey 用于在 Gin context 中存储 Claims 的 key。
@@ -17,8 +19,13 @@ const (
 // 校验成功后将 user_id 和 username 写入 Gin Context。
 func AuthMiddleware(tokenMgr *TokenManager) gin.HandlerFunc {
 	return func(c *gin.Context) {
+		log := trace.FromContext(c.Request.Context())
 		authHeader := c.GetHeader("Authorization")
 		if authHeader == "" {
+			log.Warnw("auth rejected",
+				"client_ip", c.ClientIP(),
+				"path", c.Request.URL.Path,
+				"reason", "missing authorization header")
 			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
 				"code":    "INVALID_TOKEN",
 				"message": "missing authorization header",
@@ -29,6 +36,10 @@ func AuthMiddleware(tokenMgr *TokenManager) gin.HandlerFunc {
 		// 提取 Bearer token
 		parts := strings.SplitN(authHeader, " ", 2)
 		if len(parts) != 2 || !strings.EqualFold(parts[0], "Bearer") {
+			log.Warnw("auth rejected",
+				"client_ip", c.ClientIP(),
+				"path", c.Request.URL.Path,
+				"reason", "invalid authorization format")
 			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
 				"code":    "INVALID_TOKEN",
 				"message": "invalid authorization format",
@@ -38,6 +49,11 @@ func AuthMiddleware(tokenMgr *TokenManager) gin.HandlerFunc {
 
 		claims, err := tokenMgr.ValidateAccess(parts[1])
 		if err != nil {
+			log.Warnw("auth rejected",
+				"client_ip", c.ClientIP(),
+				"path", c.Request.URL.Path,
+				"reason", "invalid or expired token",
+				"error", err)
 			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
 				"code":    "INVALID_TOKEN",
 				"message": "invalid or expired token",

backend/internal/auth/service.go

@@ -166,6 +166,9 @@ func (s *authService) Refresh(ctx context.Context, req RefreshRequest) (*AuthRes
 	userID, err := s.userRepo.FindRefreshToken(ctx, tokenHash)
 	if err != nil {
 		if errors.Is(err, store.ErrRefreshTokenNotFound) {
+			// JWT 校验已通过但 DB 中不存在 → token 已被 rotation 删除，属于复用行为
+			// 吊销该用户全部 refresh token，强制所有设备重新登录
+			_ = s.userRepo.DeleteUserRefreshTokens(ctx, claims.UserID)
 			return nil, ErrRefreshTokenUsed
 		}
 		return nil, err

backend/internal/auth/service_test.go

@@ -188,3 +188,48 @@ func TestLogout_Success(t *testing.T) {
 	})
 	assert.ErrorIs(t, err, auth.ErrRefreshTokenUsed)
 }
+
+// --- Refresh Token 复用检测 ---
+
+func TestRefresh_ReuseDetectedRevokesAllTokens(t *testing.T) {
+	svc, repo := newTestService(t)
+	ctx := context.Background()
+
+	// 注册，获得令牌对 A
+	regResp, err := svc.Register(ctx, auth.RegisterRequest{
+		Username: "eve",
+		Password: "password123",
+	})
+	require.NoError(t, err)
+	tokenPairA_refresh := regResp.RefreshToken
+
+	// 再次登录，获得令牌对 B
+	loginResp, err := svc.Login(ctx, auth.LoginRequest{
+		Username: "eve",
+		Password: "password123",
+	})
+	require.NoError(t, err)
+	tokenPairB_refresh := loginResp.RefreshToken
+
+	// 用令牌对 A 的 refresh token 正常刷新 → 成功
+	refreshResp, err := svc.Refresh(ctx, auth.RefreshRequest{
+		RefreshToken: tokenPairA_refresh,
+	})
+	require.NoError(t, err)
+	assert.NotEmpty(t, refreshResp.AccessToken)
+
+	// 用令牌对 A 的旧 refresh token 再次刷新 → 复用检测，应失败
+	_, err = svc.Refresh(ctx, auth.RefreshRequest{
+		RefreshToken: tokenPairA_refresh,
+	})
+	assert.ErrorIs(t, err, auth.ErrRefreshTokenUsed)
+
+	// 令牌对 B 的 refresh token 也应被吊销（全量吊销）
+	_, err = svc.Refresh(ctx, auth.RefreshRequest{
+		RefreshToken: tokenPairB_refresh,
+	})
+	assert.ErrorIs(t, err, auth.ErrRefreshTokenUsed)
+
+	// 确认 DB 中该用户已无 refresh token
+	_ = repo // repo 用于确认，但 MemUserRepository 无直接查询方法，通过 Refresh 失败已间接验证
+}

backend/internal/config/config.go

@@ -10,14 +10,15 @@ import (
 
 // Config 应用配置。
 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"`
-	Log      LogConfig      `mapstructure:"log"`
-	Auth     AuthConfig     `mapstructure:"auth"`
+	App       AppConfig       `mapstructure:"app"`
+	Server    ServerConfig    `mapstructure:"server"`
+	Session   SessionConfig   `mapstructure:"session"`
+	Redis     RedisConfig     `mapstructure:"redis"`
+	AI        AIConfig        `mapstructure:"ai"`
+	Storage   StorageConfig   `mapstructure:"storage"`
+	Log       LogConfig       `mapstructure:"log"`
+	Auth      AuthConfig      `mapstructure:"auth"`
+	RateLimit RateLimitConfig `mapstructure:"ratelimit"`
 }
 
 // SessionConfig 会话管理配置。
@@ -120,8 +121,22 @@ type AuthConfig struct {
 	RefreshTTL int    `mapstructure:"refresh_ttl"`  // Refresh Token 过期时间（分钟），默认 10080（7天）
 }
 
+// RateLimitConfig 限流配置。
+type RateLimitConfig struct {
+	Enabled  bool         `mapstructure:"enabled"`
+	Query    BucketConfig `mapstructure:"query"`
+	Login    BucketConfig `mapstructure:"login"`
+	Register BucketConfig `mapstructure:"register"`
+}
+
+// BucketConfig 令牌桶配置。
+type BucketConfig struct {
+	Capacity int     `mapstructure:"capacity"` // 桶容量（突发上限）
+	Rate     float64 `mapstructure:"rate"`     // 每秒填充令牌数
+}
+
 // Load 加载配置。优先级：环境变量 > config.{env}.yaml > config.yaml > 默认值。
-// workDir 为项目根目录或 backend 目录，用于定位 .env 和 config.yaml。
+// workDir 为项目根目录或 backend 目录，用于定位 .env 和 config/config.yaml。
 func Load(workDir string) (*Config, error) {
 	// 1. 加载 .env 文件（敏感信息）
 	envFile := filepath.Join(workDir, ".env")
@@ -130,7 +145,8 @@ func Load(workDir string) (*Config, error) {
 	v := viper.New()
 	v.SetConfigName("config")
 	v.SetConfigType("yaml")
-	v.AddConfigPath(workDir)
+	v.AddConfigPath(filepath.Join(workDir, "config")) // 配置文件在 config/ 目录下
+	v.AddConfigPath(workDir)                          // 兼容旧路径
 
 	// 2. 设置默认值（与 config.yaml 保持一致，仅作为兜底）
 	setDefaults(v)
@@ -218,6 +234,15 @@ func setDefaults(v *viper.Viper) {
 	// log
 	v.SetDefault("log.level", "info")
 	v.SetDefault("log.format", "console")
+
+	// ratelimit
+	v.SetDefault("ratelimit.enabled", false)
+	v.SetDefault("ratelimit.query.capacity", 10)
+	v.SetDefault("ratelimit.query.rate", 0.2)
+	v.SetDefault("ratelimit.login.capacity", 5)
+	v.SetDefault("ratelimit.login.rate", 0.1)
+	v.SetDefault("ratelimit.register.capacity", 3)
+	v.SetDefault("ratelimit.register.rate", 0.05)
 }
 
 // bindEnvVars 显式绑定敏感信息环境变量。

backend/internal/eino/adapter.go

@@ -8,20 +8,12 @@ import (
 
 	"github.com/cloudwego/eino/compose"
 
-	"github.com/hhs/camtalk/internal/logger"
 	"github.com/hhs/camtalk/internal/models"
 	"github.com/hhs/camtalk/internal/orchestrator"
 	"github.com/hhs/camtalk/internal/session"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
-// ctxKeySessionID sessionID 的 context key。
-type ctxKeySessionID struct{}
-
-// WithSessionID 将 sessionID 注入 context。
-func WithSessionID(ctx context.Context, sessionID string) context.Context {
-	return context.WithValue(ctx, ctxKeySessionID{}, sessionID)
-}
-
 // EinoOrchestrator 实现 orchestrator.Orchestrator 接口。
 // 将 Eino Graph 包装为现有接口，WS Handler 几乎不用改。
 type EinoOrchestrator struct {
@@ -46,22 +38,21 @@ func (e *EinoOrchestrator) ProcessQuery(
 	ctx context.Context,
 	sessionID string,
 	req models.WsQuery,
-	history []models.Message,
 	sender orchestrator.Sender,
 ) error {
-	log := logger.Log
+	log := trace.FromContext(ctx)
 	startTime := time.Now()
 
 	// 1. 设置活跃请求
 	if err := e.sessionMgr.SetActiveRequest(ctx, sessionID, req.RequestID); err != nil {
-		log.Errorw("设置活跃请求失败", "error", err)
+		return err
 	}
 	defer e.sessionMgr.ClearActiveRequest(ctx, sessionID)
 
 	// 2. 获取会话配置
 	sess, err := e.sessionMgr.Get(ctx, sessionID)
 	if err != nil {
-		log.Errorw("获取会话失败", "error", err)
+		log.Errorw("get session failed", "error", err)
 		sender.SendError(models.WsError{
 			Type:      "error",
 			RequestID: req.RequestID,
@@ -76,7 +67,7 @@ func (e *EinoOrchestrator) ProcessQuery(
 	if req.Text == "" && req.Audio != "" {
 		audioData, err = base64.StdEncoding.DecodeString(req.Audio)
 		if err != nil {
-			log.Errorw("音频解码失败", "error", err)
+			log.Errorw("audio decode failed", "error", err)
 			sender.SendError(models.WsError{
 				Type:      "error",
 				RequestID: req.RequestID,
@@ -91,7 +82,7 @@ func (e *EinoOrchestrator) ProcessQuery(
 	if req.Image != "" {
 		imageData, err = base64.StdEncoding.DecodeString(req.Image)
 		if err != nil {
-			log.Errorw("图片解码失败", "error", err)
+			log.Errorw("image decode failed", "error", err)
 			sender.SendError(models.WsError{
 				Type:      "error",
 				RequestID: req.RequestID,
@@ -108,22 +99,25 @@ func (e *EinoOrchestrator) ProcessQuery(
 	// 5. 注入 context 值（供 Callback 和 Lambda 节点使用）
 	ctx = WithSender(ctx, sender)
 	ctx = WithRequestID(ctx, req.RequestID)
-	ctx = WithSessionID(ctx, sessionID)
+	ctx = trace.WithSessionID(ctx, sessionID)
 	ctx = WithStartTime(ctx, startTime)
-	ctx = WithPipelineState(ctx, genLocalState(ctx))
 
-	// 6. 追加用户消息到历史
-	if req.Text != "" {
-		_ = e.sessionMgr.AppendMessage(ctx, sessionID, models.Message{
-			Role:    "user",
-			Content: req.Text,
-		})
-	}
+	// 创建 State 并从 input 复制元数据
+	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
+	state.UserID = input.UserID
+	ctx = WithPipelineState(ctx, state)
 
-	// 7. 调用 Graph（Stream 模式 + 运行时 Callback）
+	// 6. 调用 Graph（Stream 模式 + 运行时 Callback）
 	streamReader, err := e.graph.Runnable.Stream(ctx, input, e.callbacks)
 	if err != nil {
-		log.Errorw("Graph Stream 启动失败", "error", err)
+		log.Errorw("graph stream start failed", "error", err)
 		sender.SendError(models.WsError{
 			Type:      "error",
 			RequestID: req.RequestID,
@@ -133,7 +127,7 @@ func (e *EinoOrchestrator) ProcessQuery(
 		return err
 	}
 
-	// 8. 消费 StreamReader（触发整条链路执行，side effects 推送消息到客户端）
+	// 7. 消费 StreamReader（触发整条链路执行，side effects 推送消息到客户端）
 	var output PipelineOutput
 	for {
 		o, err := streamReader.Recv()
@@ -141,25 +135,38 @@ func (e *EinoOrchestrator) ProcessQuery(
 			if err == io.EOF {
 				break
 			}
-			log.Errorw("Graph Stream 消费错误", "error", err)
+			log.Errorw("graph stream consume error", "error", err)
 			break
 		}
 		output = o
 	}
 
+	// 8. 追加用户消息到历史（使用 STT 结果，兼容文本输入和语音输入）
+	userText := output.TranscribedText
+	if userText == "" {
+		userText = req.Text // fallback 到原始文本输入
+	}
+	if userText != "" {
+		if err := e.sessionMgr.AppendMessage(ctx, sessionID, models.Message{
+			Role:    "user",
+			Content: userText,
+		}); err != nil {
+			log.Errorw("append user message failed", "error", err)
+		}
+	}
+
 	// 9. 追加助手消息到历史
 	if output.FullResponse != "" {
-		_ = e.sessionMgr.AppendMessage(ctx, sessionID, models.Message{
+		if err := e.sessionMgr.AppendMessage(ctx, sessionID, models.Message{
 			Role:    "assistant",
 			Content: output.FullResponse,
-		})
+		}); err != nil {
+			log.Errorw("append assistant message failed", "error", err)
+		}
 	}
 
 	latency := time.Since(startTime).Milliseconds()
-	log.Infow("Eino 编排完成",
-		"request_id", req.RequestID,
-		"latency_ms", latency,
-		"session_id", sessionID)
+	log.Infow("eino pipeline completed", "latency_ms", latency)
 
 	return nil
 }

backend/internal/eino/callback.go

@@ -9,14 +9,13 @@ import (
 	"github.com/cloudwego/eino/schema"
 	callbacksHelper "github.com/cloudwego/eino/utils/callbacks"
 
-	"github.com/hhs/camtalk/internal/logger"
 	"github.com/hhs/camtalk/internal/models"
 	"github.com/hhs/camtalk/internal/orchestrator"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // context key 类型，避免与其他包冲突。
 type ctxKeySender struct{}
-type ctxKeyRequestID struct{}
 type ctxKeyState struct{}
 
 // WithSender 将 Sender 注入 context。
@@ -24,9 +23,9 @@ func WithSender(ctx context.Context, sender orchestrator.Sender) context.Context
 	return context.WithValue(ctx, ctxKeySender{}, sender)
 }
 
-// WithRequestID 将 requestID 注入 context。
+// WithRequestID 将 requestID 注入 context（使用 trace 包）。
 func WithRequestID(ctx context.Context, requestID string) context.Context {
-	return context.WithValue(ctx, ctxKeyRequestID{}, requestID)
+	return trace.WithRequestID(ctx, requestID)
 }
 
 // WithPipelineState 将 PipelineState 注入 context。
@@ -40,10 +39,9 @@ func senderFromCtx(ctx context.Context) orchestrator.Sender {
 	return s
 }
 
-// requestIDFromCtx 从 context 获取 requestID。
+// requestIDFromCtx 从 context 获取 requestID（使用 trace 包）。
 func requestIDFromCtx(ctx context.Context) string {
-	s, _ := ctx.Value(ctxKeyRequestID{}).(string)
-	return s
+	return trace.GetRequestID(ctx)
 }
 
 // stateFromCtx 从 context 获取 PipelineState。
@@ -62,7 +60,7 @@ func BuildCallbackHandler() callbacks.Handler {
 	return callbacksHelper.NewHandlerHelper().
 		ChatModel(&callbacksHelper.ModelCallbackHandler{
 			OnEndWithStreamOutput: func(ctx context.Context, info *callbacks.RunInfo, output *schema.StreamReader[*model.CallbackOutput]) context.Context {
-				log := logger.Log
+				log := trace.FromContext(ctx)
 				sender := senderFromCtx(ctx)
 				requestID := requestIDFromCtx(ctx)
 				state := stateFromCtx(ctx)

backend/internal/eino/graph.go

@@ -13,6 +13,7 @@ import (
 	"github.com/hhs/camtalk/internal/logger"
 	"github.com/hhs/camtalk/internal/models"
 	"github.com/hhs/camtalk/internal/session"
+	"github.com/hhs/camtalk/internal/store"
 )
 
 const (
@@ -42,6 +43,7 @@ func NewPipelineGraph(
 	sttService stt.Service,
 	ttsService tts.Service,
 	sessionMgr session.Manager,
+	scenarioRepo store.UserScenarioRepository,
 ) (*PipelineGraph, error) {
 	log := logger.Log
 
@@ -68,7 +70,7 @@ func NewPipelineGraph(
 	maxHistory := cfg.Session.MaxHistory
 
 	_ = g.AddLambdaNode(nodeSTT, NewSTTLambda(sttService))
-	_ = g.AddLambdaNode(nodeHistory, NewHistoryLambda(sessionMgr.GetHistory, maxHistory))
+	_ = g.AddLambdaNode(nodeHistory, NewHistoryLambda(sessionMgr.GetHistory, scenarioRepo, maxHistory))
 	_ = g.AddChatModelNode(nodeLLM, chatModel)
 	_ = g.AddLambdaNode(nodeMessageToString, NewMessageToStringLambda())
 	_ = g.AddLambdaNode(nodeSplitter, NewSplitterLambda())
@@ -97,7 +99,7 @@ func NewPipelineGraph(
 		return nil, err
 	}
 
-	log.Infow("Eino Graph 编译成功", "nodes", 6)
+	log.Infow("Eino Graph 编译成功", "nodes", 7)
 	return &PipelineGraph{Runnable: runnable}, nil
 }
 
@@ -112,5 +114,6 @@ func buildPipelineInput(req models.WsQuery, sessionID string, sess *models.Sessi
 		Language:   sess.Config.Language,
 		Scenario:   sess.Config.Scenario,
 		TTSEnabled: sess.Config.TTSEnabled,
+		UserID:     sess.UserID,
 	}
 }

backend/internal/eino/graph_test.go

@@ -13,6 +13,7 @@ import (
 	"github.com/hhs/camtalk/internal/ai/tts"
 	"github.com/hhs/camtalk/internal/models"
 	"github.com/hhs/camtalk/internal/orchestrator"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // --- Mock STT Service ---
@@ -176,7 +177,7 @@ func TestContextInjection(t *testing.T) {
 	sender := &mockSender{}
 	ctx = WithSender(ctx, sender)
 	ctx = WithRequestID(ctx, "req-123")
-	ctx = WithSessionID(ctx, "sess-456")
+	ctx = trace.WithSessionID(ctx, "sess-456")
 	ctx = WithStartTime(ctx, time.Now())
 	ctx = WithPipelineState(ctx, genLocalState(ctx))
 
@@ -214,7 +215,7 @@ func TestNewHistoryLambda_ReturnsNonNil(t *testing.T) {
 	fetcher := func(ctx context.Context, sessionID string, limit int) ([]models.Message, error) {
 		return nil, nil
 	}
-	lambda := NewHistoryLambda(fetcher, 10)
+	lambda := NewHistoryLambda(fetcher, nil, 10)
 	require.NotNil(t, lambda)
 }
 

backend/internal/eino/nodes_done.go

@@ -6,8 +6,8 @@ import (
 
 	"github.com/cloudwego/eino/compose"
 
-	"github.com/hhs/camtalk/internal/logger"
 	"github.com/hhs/camtalk/internal/models"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // ctxKeyStartTime 请求开始时间的 context key。
@@ -33,7 +33,7 @@ func latencyFromCtx(ctx context.Context) int64 {
 // 历史消息追加由适配器负责（避免重复写入）。
 func NewDoneLambda(defaultModel string) *compose.Lambda {
 	return compose.InvokableLambda(func(ctx context.Context, _ struct{}) (PipelineOutput, error) {
-		log := logger.Log
+		log := trace.FromContext(ctx)
 		sender := senderFromCtx(ctx)
 		state := stateFromCtx(ctx)
 
@@ -70,13 +70,11 @@ func NewDoneLambda(defaultModel string) *compose.Lambda {
 				}
 			}
 			if err := sender.SendLLMDone(done); err != nil {
-				log.Errorw("发送 llm_done 失败", "error", err)
+				log.Errorw("send llm_done failed", "error", err)
 			}
 		}
 
-		log.Infow("查询处理完成",
-			"request_id", requestID,
-			"response_length", len(fullResponse))
+		log.Infow("query processing completed", "response_length", len(fullResponse))
 
 		return PipelineOutput{
 			TranscribedText: transcribedText,

backend/internal/eino/nodes_history.go

@@ -8,8 +8,9 @@ import (
 	"github.com/cloudwego/eino/schema"
 
 	"github.com/hhs/camtalk/internal/ai/llm"
-	"github.com/hhs/camtalk/internal/logger"
 	"github.com/hhs/camtalk/internal/models"
+	"github.com/hhs/camtalk/internal/store"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // NewHistoryLambda 创建历史组装 Lambda 节点。
@@ -17,9 +18,13 @@ import (
 //
 // 从 PipelineState 读取请求元数据（SessionID、Scenario、ImageData 等），
 // 构建系统提示词，组装历史消息和当前用户输入（含多模态图片）。
-func NewHistoryLambda(historyFetcher func(ctx context.Context, sessionID string, limit int) ([]models.Message, error), maxHistory int) *compose.Lambda {
+func NewHistoryLambda(
+	historyFetcher func(ctx context.Context, sessionID string, limit int) ([]models.Message, error),
+	scenarioRepo store.UserScenarioRepository,
+	maxHistory int,
+) *compose.Lambda {
 	return compose.InvokableLambda(func(ctx context.Context, sttOut STTOutput) ([]*schema.Message, error) {
-		log := logger.Log
+		log := trace.FromContext(ctx)
 
 		// 从 State 读取请求元数据
 		state := stateFromCtx(ctx)
@@ -34,10 +39,31 @@ func NewHistoryLambda(historyFetcher func(ctx context.Context, sessionID string,
 		scenario := state.Scenario
 		detailLevel := state.DetailLevel
 		language := sttOut.Language
+		userID := state.UserID
 		state.mu.Unlock()
 
-		// 构建系统提示词
-		scenarioPrompt := llm.GetScenarioPrompt(scenario, language)
+		// 加载用户自建情景（如果有 userID 和 scenarioRepo）
+		var customScenarios map[string]string
+		var customGreetings map[string]string
+		if userID != "" && scenarioRepo != nil {
+			scenarios, err := scenarioRepo.FindByUserID(ctx, userID)
+			if err != nil {
+				log.Warnw("load user scenarios failed", "user_id", userID, "error", err)
+			} else if len(scenarios) > 0 {
+				customScenarios = make(map[string]string, len(scenarios))
+				customGreetings = make(map[string]string, len(scenarios))
+				for _, s := range scenarios {
+					customScenarios[s.ID] = s.Prompt
+					if s.Greeting != "" {
+						customGreetings[s.ID] = s.Greeting
+					}
+				}
+				log.Debugw("loaded user scenarios", "user_id", userID, "count", len(scenarios))
+			}
+		}
+
+		// 构建系统提示词（支持用户自建情景）
+		scenarioPrompt := llm.GetScenarioPrompt(scenario, language, customScenarios)
 		systemPrompt := llm.BuildSystemPrompt(language, detailLevel, scenarioPrompt)
 
 		// 构建 system message（仅文本，多模态内容只能放在 user 角色）
@@ -52,7 +78,7 @@ func NewHistoryLambda(historyFetcher func(ctx context.Context, sessionID string,
 		if historyFetcher != nil && sessionID != "" {
 			history, err := historyFetcher(ctx, sessionID, maxHistory)
 			if err != nil {
-				log.Warnw("获取历史消息失败，继续处理", "error", err, "request_id", requestID)
+				log.Warnw("fetch history failed, continuing", "error", err, "request_id", requestID)
 			} else {
 				for _, msg := range history {
 					messages = append(messages, &schema.Message{
@@ -95,8 +121,7 @@ func NewHistoryLambda(historyFetcher func(ctx context.Context, sessionID string,
 			})
 		}
 
-		log.Infow("历史组装完成",
-			"request_id", requestID,
+		log.Debugw("history assembled",
 			"message_count", len(messages),
 			"has_image", len(imageData) > 0,
 			"scenario", scenario)

backend/internal/eino/nodes_stt.go

@@ -8,8 +8,9 @@ import (
 	"github.com/cloudwego/eino/compose"
 
 	"github.com/hhs/camtalk/internal/ai/stt"
-	"github.com/hhs/camtalk/internal/logger"
 	"github.com/hhs/camtalk/internal/models"
+	"github.com/hhs/camtalk/internal/trace"
+	"github.com/hhs/camtalk/internal/util"
 )
 
 // NewSTTLambda 创建 STT Lambda 节点。
@@ -20,7 +21,7 @@ import (
 // 识别结果通过 Sender 发送 stt_result 到客户端。
 func NewSTTLambda(sttService stt.Service) *compose.Lambda {
 	return compose.InvokableLambda(func(ctx context.Context, input PipelineInput) (STTOutput, error) {
-		log := logger.Log
+		log := trace.FromContext(ctx)
 		sender := senderFromCtx(ctx)
 		requestID := requestIDFromCtx(ctx)
 
@@ -39,8 +40,9 @@ func NewSTTLambda(sttService stt.Service) *compose.Lambda {
 
 		// 文本输入模式：跳过 STT
 		if input.Text != "" {
-			log.Infow("使用文本输入，跳过 STT",
-				"request_id", requestID, "text", input.Text)
+			log.Debugw("text input mode, skipping stt",
+				"text_len", len(input.Text),
+				"text_preview", util.Truncate(input.Text, 50))
 
 			// 发送 stt_result 保持前端消息流一致性
 			if sender != nil {
@@ -50,7 +52,7 @@ func NewSTTLambda(sttService stt.Service) *compose.Lambda {
 					Text:      input.Text,
 					IsFinal:   true,
 				}); err != nil {
-					log.Errorw("发送 stt_result 失败", "error", err)
+					log.Errorw("send stt_result failed", "error", err)
 				}
 			}
 
@@ -73,8 +75,7 @@ func NewSTTLambda(sttService stt.Service) *compose.Lambda {
 			return STTOutput{}, fmt.Errorf("stt: no audio data provided")
 		}
 
-		log.Infow("开始语音识别",
-			"request_id", requestID, "audio_bytes", len(input.AudioData))
+		log.Debugw("stt recognition started", "audio_bytes", len(input.AudioData))
 
 		// 调用 STT 服务
 		text, err := sttService.Recognize(ctx, input.AudioData, stt.Options{
@@ -83,7 +84,7 @@ func NewSTTLambda(sttService stt.Service) *compose.Lambda {
 			Language:   input.Language,
 		})
 		if err != nil {
-			log.Errorw("语音识别失败", "error", err, "request_id", requestID)
+			log.Errorw("stt recognition failed", "error", err)
 			if sender != nil {
 				sender.SendError(models.WsError{
 					Type:      "error",
@@ -97,11 +98,13 @@ func NewSTTLambda(sttService stt.Service) *compose.Lambda {
 
 		// STT 返回空文本
 		if strings.TrimSpace(text) == "" {
-			log.Infow("语音识别结果为空", "request_id", requestID)
+			log.Infow("stt returned empty text")
 			text = "（未识别到语音）"
 		}
 
-		log.Infow("语音识别完成", "request_id", requestID, "text", text)
+		log.Debugw("stt recognition completed",
+			"text_len", len(text),
+			"text_preview", util.Truncate(text, 50))
 
 		// 发送 stt_result
 		if sender != nil {
@@ -111,7 +114,7 @@ func NewSTTLambda(sttService stt.Service) *compose.Lambda {
 				Text:      text,
 				IsFinal:   true,
 			}); err != nil {
-				log.Errorw("发送 stt_result 失败", "error", err)
+				log.Errorw("send stt_result failed", "error", err)
 			}
 		}
 

backend/internal/eino/nodes_tts.go

@@ -9,8 +9,8 @@ import (
 	"github.com/cloudwego/eino/schema"
 
 	"github.com/hhs/camtalk/internal/ai/tts"
-	"github.com/hhs/camtalk/internal/logger"
 	"github.com/hhs/camtalk/internal/models"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // NewTTSLambda 创建 TTS Transform Lambda 节点。
@@ -26,7 +26,7 @@ func NewTTSLambda(ttsService tts.Service, ttsVoice string, ttsSpeed float64, tts
 			defer sw.Close()
 			defer input.Close()
 
-			log := logger.Log
+			log := trace.FromContext(ctx)
 			sender := senderFromCtx(ctx)
 			requestID := requestIDFromCtx(ctx)
 
@@ -48,7 +48,7 @@ func NewTTSLambda(ttsService tts.Service, ttsVoice string, ttsSpeed float64, tts
 					if err == io.EOF {
 						break
 					}
-					log.Errorw("TTS: stream recv error", "error", err, "request_id", requestID)
+					log.Errorw("TTS: stream recv error", "error", err)
 					break
 				}
 				if sentence != "" {
@@ -61,7 +61,7 @@ func NewTTSLambda(ttsService tts.Service, ttsVoice string, ttsSpeed float64, tts
 				return
 			}
 
-			log.Infow("开始 TTS 合成", "request_id", requestID, "sentence_count", len(sentences))
+			log.Infow("开始 TTS 合成", "sentence_count", len(sentences))
 
 			// 将句子数组转为 channel
 			sentenceCh := make(chan string, len(sentences))
@@ -78,7 +78,7 @@ func NewTTSLambda(ttsService tts.Service, ttsVoice string, ttsSpeed float64, tts
 				SampleRate: ttsSampleRate,
 			})
 			if err != nil {
-				log.Errorw("TTS 合成启动失败（已跳过）", "error", err, "request_id", requestID)
+				log.Errorw("TTS 合成启动失败（已跳过）", "error", err)
 				sw.Send(struct{}{}, nil)
 				return
 			}
@@ -87,7 +87,7 @@ func NewTTSLambda(ttsService tts.Service, ttsVoice string, ttsSpeed float64, tts
 			for chunk := range ttsStream {
 				select {
 				case <-ctx.Done():
-					log.Infow("TTS 流被中断", "request_id", requestID)
+					log.Debugw("tts stream interrupted")
 					sw.Send(struct{}{}, ctx.Err())
 					return
 				default:
@@ -107,7 +107,7 @@ func NewTTSLambda(ttsService tts.Service, ttsVoice string, ttsSpeed float64, tts
 				}
 			}
 
-			log.Infow("TTS 合成完成", "request_id", requestID)
+			log.Infow("TTS 合成完成")
 			sw.Send(struct{}{}, nil)
 		}()
 

backend/internal/eino/state.go

@@ -23,6 +23,7 @@ type PipelineState struct {
 	DetailLevel string
 	Language    string
 	TTSEnabled  bool
+	UserID      string // 新增：用户 ID，用于加载自建情景
 }
 
 // genLocalState 创建每请求的 PipelineState 实例。

backend/internal/eino/types.go

@@ -12,6 +12,7 @@ type PipelineInput struct {
 	Language   string // zh / en
 	Scenario   string // free_chat, interviewer, etc.
 	TTSEnabled bool
+	UserID     string // 用户 ID，用于加载自建情景
 }
 
 // PipelineOutput Graph 统一输出。

backend/internal/models/user_scenario.go

@@ -0,0 +1,43 @@
+package models
+
+import "time"
+
+// UserScenario 用户自建情景。
+type UserScenario struct {
+	ID          string    `json:"id"`
+	UserID      string    `json:"user_id"`
+	Name        string    `json:"name"`
+	Icon        string    `json:"icon"`
+	Description string    `json:"description"`
+	Prompt      string    `json:"prompt"`
+	Greeting    string    `json:"greeting,omitempty"`
+	Language    string    `json:"language"`
+	CreatedAt   time.Time `json:"created_at"`
+	UpdatedAt   time.Time `json:"updated_at"`
+}
+
+// CreateUserScenarioRequest 创建用户情景请求。
+type CreateUserScenarioRequest struct {
+	Name        string `json:"name" binding:"required,min=2,max=50"`
+	Icon        string `json:"icon,omitempty"`
+	Description string `json:"description,omitempty" binding:"omitempty,max=100"`
+	Prompt      string `json:"prompt" binding:"required,min=10,max=2000"`
+	Greeting    string `json:"greeting,omitempty" binding:"omitempty,max=500"`
+	Language    string `json:"language,omitempty"`
+}
+
+// UpdateUserScenarioRequest 更新用户情景请求。
+type UpdateUserScenarioRequest struct {
+	Name        *string `json:"name,omitempty" binding:"omitempty,min=2,max=50"`
+	Icon        *string `json:"icon,omitempty"`
+	Description *string `json:"description,omitempty" binding:"omitempty,max=100"`
+	Prompt      *string `json:"prompt,omitempty" binding:"omitempty,min=10,max=2000"`
+	Greeting    *string `json:"greeting,omitempty" binding:"omitempty,max=500"`
+	Language    *string `json:"language,omitempty"`
+}
+
+// UserScenarioListResponse 用户情景列表响应。
+type UserScenarioListResponse struct {
+	Scenarios []*UserScenario `json:"scenarios"`
+	Total     int             `json:"total"`
+}

backend/internal/orchestrator/orchestrator.go

@@ -14,13 +14,11 @@ type Orchestrator interface {
 	// ctx 用于整体超时和中断控制。
 	// sessionID 用于会话管理和历史获取。
 	// req 包含图像和音频数据。
-	// history 是最近的对话历史。
 	// sender 用于向客户端推送消息。
 	ProcessQuery(
 		ctx context.Context,
 		sessionID string,
 		req models.WsQuery,
-		history []models.Message,
 		sender Sender,
 	) error
 }

backend/internal/ratelimit/bucket.go

@@ -0,0 +1,172 @@
+package ratelimit
+
+import (
+	"context"
+	"sync"
+	"time"
+
+	"github.com/hhs/camtalk/internal/config"
+)
+
+// TokenBucket 内存令牌桶，适用于单实例部署。
+type TokenBucket struct {
+	capacity   int       // 桶容量
+	rate       float64   // 每秒填充令牌数
+	tokens     float64   // 当前令牌数
+	lastRefill time.Time // 上次填充时间
+	mu         sync.Mutex
+}
+
+// newTokenBucket 创建令牌桶。
+func newTokenBucket(capacity int, rate float64) *TokenBucket {
+	return &TokenBucket{
+		capacity:   capacity,
+		rate:       rate,
+		tokens:     float64(capacity), // 初始满桶
+		lastRefill: time.Now(),
+	}
+}
+
+// allow 尝试消耗一个令牌。
+func (b *TokenBucket) allow() (bool, time.Duration) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	now := time.Now()
+	elapsed := now.Sub(b.lastRefill).Seconds()
+
+	// 补充令牌
+	newTokens := elapsed * b.rate
+	b.tokens = min(float64(b.capacity), b.tokens+newTokens)
+	b.lastRefill = now
+
+	// 尝试消耗一个令牌
+	if b.tokens >= 1 {
+		b.tokens -= 1
+		return true, 0
+	}
+
+	// 计算需要等待的时间
+	if b.rate == 0 {
+		// rate=0 时永远无法补充令牌
+		return false, 24 * time.Hour // 返回一个很大的值
+	}
+	retryAfter := time.Duration((1-b.tokens)/b.rate*1000) * time.Millisecond
+	return false, retryAfter
+}
+
+// MemoryLimiter 管理多个用户的令牌桶。
+type MemoryLimiter struct {
+	buckets  map[string]*TokenBucket
+	config   config.RateLimitConfig
+	mu       sync.RWMutex
+	stopOnce sync.Once
+	done     chan struct{}
+}
+
+// NewMemoryLimiter 创建内存限流器。
+func NewMemoryLimiter(cfg config.RateLimitConfig) *MemoryLimiter {
+	limiter := &MemoryLimiter{
+		buckets: make(map[string]*TokenBucket),
+		config:  cfg,
+		done:    make(chan struct{}),
+	}
+
+	// 启动后台清理 goroutine
+	go limiter.cleanup()
+
+	return limiter
+}
+
+// Allow 实现 Limiter 接口。
+func (l *MemoryLimiter) Allow(ctx context.Context, key string) (bool, time.Duration) {
+	bucket := l.getOrCreateBucket(key)
+	return bucket.allow()
+}
+
+// Stop 实现 Limiter 接口。
+func (l *MemoryLimiter) Stop() {
+	l.stopOnce.Do(func() {
+		close(l.done)
+	})
+}
+
+// getOrCreateBucket 获取或创建令牌桶。
+func (l *MemoryLimiter) getOrCreateBucket(key string) *TokenBucket {
+	// 先尝试读锁
+	l.mu.RLock()
+	bucket, exists := l.buckets[key]
+	l.mu.RUnlock()
+
+	if exists {
+		return bucket
+	}
+
+	// 需要创建新桶，升级为写锁
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	// 双重检查（可能其他 goroutine 已创建）
+	bucket, exists = l.buckets[key]
+	if exists {
+		return bucket
+	}
+
+	// 根据 key 确定配置（简化版：假设 key 格式为 "userID:action"）
+	cfg := l.getBucketConfig(key)
+	bucket = newTokenBucket(cfg.Capacity, cfg.Rate)
+	l.buckets[key] = bucket
+
+	return bucket
+}
+
+// getBucketConfig 根据 key 获取桶配置。
+func (l *MemoryLimiter) getBucketConfig(key string) config.BucketConfig {
+	// 简化实现：从 key 后缀判断动作类型
+	// 实际使用时调用方会传递正确的 key
+	// 默认使用 query 配置
+	return l.config.Query
+}
+
+// cleanup 定期清理不活跃的桶。
+func (l *MemoryLimiter) cleanup() {
+	ticker := time.NewTicker(10 * time.Minute)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ticker.C:
+			l.removeInactiveBuckets()
+		case <-l.done:
+			return
+		}
+	}
+}
+
+// removeInactiveBuckets 移除超过 10 分钟无活动的桶。
+func (l *MemoryLimiter) removeInactiveBuckets() {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	now := time.Now()
+	for key, bucket := range l.buckets {
+		bucket.mu.Lock()
+		inactive := now.Sub(bucket.lastRefill) > 10*time.Minute
+		bucket.mu.Unlock()
+
+		if inactive {
+			delete(l.buckets, key)
+		}
+	}
+}
+
+// min 返回两个 float64 中的较小值。
+func min(a, b float64) float64 {
+	if a < b {
+		return a
+	}
+	return b
+}
+
+// 编译期接口检查
+var _ Limiter = (*MemoryLimiter)(nil)

backend/internal/ratelimit/bucket_test.go

@@ -0,0 +1,203 @@
+package ratelimit
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/hhs/camtalk/internal/config"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestTokenBucket_Allow_FirstRequest(t *testing.T) {
+	bucket := newTokenBucket(5, 0.2)
+
+	allowed, retryAfter := bucket.allow()
+
+	assert.True(t, allowed)
+	assert.Equal(t, time.Duration(0), retryAfter)
+}
+
+func TestTokenBucket_Allow_ConsumeUntilEmpty(t *testing.T) {
+	bucket := newTokenBucket(3, 0.2)
+
+	// 连续消耗 3 个令牌
+	for i := 0; i < 3; i++ {
+		allowed, _ := bucket.allow()
+		assert.True(t, allowed, "request %d should be allowed", i+1)
+	}
+
+	// 第 4 个请求应被拒绝
+	allowed, retryAfter := bucket.allow()
+	assert.False(t, allowed)
+	assert.Greater(t, retryAfter, time.Duration(0))
+}
+
+func TestTokenBucket_Allow_RetryAfterCorrect(t *testing.T) {
+	bucket := newTokenBucket(1, 1.0) // 每秒 1 个令牌
+
+	// 消耗唯一的令牌
+	allowed, _ := bucket.allow()
+	require.True(t, allowed)
+
+	// 立即再次请求应被拒绝
+	allowed, retryAfter := bucket.allow()
+	assert.False(t, allowed)
+	// retryAfter 应约为 1 秒（允许一定误差）
+	assert.InDelta(t, 1000, retryAfter.Milliseconds(), 100)
+}
+
+func TestTokenBucket_Allow_RefillAfterWait(t *testing.T) {
+	bucket := newTokenBucket(2, 10.0) // 每秒 10 个令牌（每 100ms 一个）
+
+	// 消耗 2 个令牌
+	bucket.allow()
+	bucket.allow()
+
+	// 等待 150ms，应补充至少 1 个令牌
+	time.Sleep(150 * time.Millisecond)
+
+	allowed, _ := bucket.allow()
+	assert.True(t, allowed)
+}
+
+func TestTokenBucket_Allow_CapacityLimit(t *testing.T) {
+	bucket := newTokenBucket(3, 1.0)
+
+	// 等待足够长时间让桶"溢出"
+	time.Sleep(100 * time.Millisecond)
+
+	// 但最多只能消耗 capacity 个令牌
+	for i := 0; i < 3; i++ {
+		allowed, _ := bucket.allow()
+		assert.True(t, allowed, "request %d should be allowed", i+1)
+	}
+
+	// 第 4 个应被拒绝
+	allowed, _ := bucket.allow()
+	assert.False(t, allowed)
+}
+
+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)
+}
+
+func TestTokenBucket_Allow_ZeroCapacity(t *testing.T) {
+	bucket := newTokenBucket(0, 1.0)
+
+	allowed, retryAfter := bucket.allow()
+	assert.False(t, allowed)
+	assert.Greater(t, retryAfter, time.Duration(0))
+}
+
+func TestTokenBucket_Allow_ZeroRate(t *testing.T) {
+	bucket := newTokenBucket(1, 0.0)
+
+	// 第一个通过
+	allowed, _ := bucket.allow()
+	assert.True(t, allowed)
+
+	// 第二个被拒绝，且 retryAfter 应为无限大（实际上会很大）
+	allowed, retryAfter := bucket.allow()
+	assert.False(t, allowed)
+	// rate=0 时，retryAfter 理论上无限大，实际会是一个很大的值
+	assert.Greater(t, retryAfter, 1*time.Hour)
+}
+
+func TestMemoryLimiter_Allow_DifferentKeys(t *testing.T) {
+	cfg := config.RateLimitConfig{
+		Enabled: true,
+		Query:   config.BucketConfig{Capacity: 2, Rate: 1.0},
+	}
+	limiter := NewMemoryLimiter(cfg)
+	defer limiter.Stop()
+
+	ctx := context.Background()
+
+	// user1 消耗 2 个令牌
+	allowed, _ := limiter.Allow(ctx, "user1:query")
+	assert.True(t, allowed)
+	allowed, _ = limiter.Allow(ctx, "user1:query")
+	assert.True(t, allowed)
+
+	// user1 第 3 个被拒绝
+	allowed, _ = limiter.Allow(ctx, "user1:query")
+	assert.False(t, allowed)
+
+	// user2 应该不受影响
+	allowed, _ = limiter.Allow(ctx, "user2:query")
+	assert.True(t, allowed)
+}
+
+func TestMemoryLimiter_Cleanup(t *testing.T) {
+	cfg := config.RateLimitConfig{
+		Enabled: true,
+		Query:   config.BucketConfig{Capacity: 1, Rate: 1.0},
+	}
+	limiter := NewMemoryLimiter(cfg)
+	defer limiter.Stop()
+
+	ctx := context.Background()
+
+	// 创建一个桶
+	limiter.Allow(ctx, "user1:query")
+
+	// 验证桶已创建
+	limiter.mu.RLock()
+	initialCount := len(limiter.buckets)
+	limiter.mu.RUnlock()
+	assert.Equal(t, 1, initialCount)
+
+	// 手动触发清理（模拟 10 分钟后）
+	limiter.mu.Lock()
+	for _, bucket := range limiter.buckets {
+		bucket.mu.Lock()
+		bucket.lastRefill = time.Now().Add(-11 * time.Minute)
+		bucket.mu.Unlock()
+	}
+	limiter.mu.Unlock()
+
+	limiter.removeInactiveBuckets()
+
+	// 验证桶已被清理
+	limiter.mu.RLock()
+	finalCount := len(limiter.buckets)
+	limiter.mu.RUnlock()
+	assert.Equal(t, 0, finalCount)
+}
+
+func TestMemoryLimiter_Stop(t *testing.T) {
+	cfg := config.RateLimitConfig{
+		Enabled: true,
+		Query:   config.BucketConfig{Capacity: 1, Rate: 1.0},
+	}
+	limiter := NewMemoryLimiter(cfg)
+
+	// 多次调用 Stop 不应 panic
+	limiter.Stop()
+	limiter.Stop()
+}

backend/internal/ratelimit/limiter.go

@@ -0,0 +1,17 @@
+package ratelimit
+
+import (
+	"context"
+	"time"
+)
+
+// Limiter 速率限制器接口。
+type Limiter interface {
+	// Allow 判断 key 是否允许执行一次操作。
+	// key 通常为 "userID:action" 格式。
+	// 返回 (allowed, retryAfter)。retryAfter 表示需要等待的时间。
+	Allow(ctx context.Context, key string) (bool, time.Duration)
+
+	// Stop 停止限流器，清理资源（如后台 goroutine）。
+	Stop()
+}

backend/internal/ratelimit/middleware.go

@@ -0,0 +1,51 @@
+package ratelimit
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/hhs/camtalk/internal/trace"
+)
+
+// Middleware 返回 Gin 中间件，按 key 维度限流。
+// keyFunc 从请求中提取限流 key（如 IP、用户 ID）。
+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 {
+			log := trace.FromContext(c.Request.Context())
+			log.Warnw("rate limited",
+				"client_ip", c.ClientIP(),
+				"path", c.Request.URL.Path,
+				"limit_key", key,
+				"retry_after_sec", int(retryAfter.Seconds()+0.5))
+
+			// 设置 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()
+	}
+}

backend/internal/ratelimit/middleware_test.go

@@ -0,0 +1,196 @@
+package ratelimit
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// mockLimiter 用于测试的 mock 限流器。
+type mockLimiter struct {
+	allowFunc func(ctx context.Context, key string) (bool, time.Duration)
+}
+
+func (m *mockLimiter) Allow(ctx context.Context, key string) (bool, time.Duration) {
+	if m.allowFunc != nil {
+		return m.allowFunc(ctx, key)
+	}
+	return true, 0
+}
+
+func (m *mockLimiter) Stop() {}
+
+// 编译期接口检查
+var _ Limiter = (*mockLimiter)(nil)
+
+func TestMiddleware_Allow(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	limiter := &mockLimiter{
+		allowFunc: func(ctx context.Context, key string) (bool, time.Duration) {
+			return true, 0
+		},
+	}
+
+	router := gin.New()
+	router.Use(Middleware(limiter, func(c *gin.Context) string {
+		return "user1:test"
+	}))
+	router.GET("/test", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{"status": "ok"})
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	var resp map[string]interface{}
+	err := json.Unmarshal(w.Body.Bytes(), &resp)
+	require.NoError(t, err)
+	assert.Equal(t, "ok", resp["status"])
+}
+
+func TestMiddleware_Deny(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	limiter := &mockLimiter{
+		allowFunc: func(ctx context.Context, key string) (bool, time.Duration) {
+			return false, 5 * time.Second
+		},
+	}
+
+	router := gin.New()
+	router.Use(Middleware(limiter, func(c *gin.Context) string {
+		return "user1:test"
+	}))
+	router.GET("/test", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{"status": "ok"})
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	// 验证返回 429
+	assert.Equal(t, http.StatusTooManyRequests, w.Code)
+
+	// 验证 Retry-After header
+	assert.Equal(t, "5", w.Header().Get("Retry-After"))
+
+	// 验证响应体
+	var resp map[string]interface{}
+	err := json.Unmarshal(w.Body.Bytes(), &resp)
+	require.NoError(t, err)
+	assert.Equal(t, "RATE_LIMITED", resp["code"])
+	assert.Contains(t, resp["message"], "retry after")
+}
+
+func TestMiddleware_NilLimiter(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	router := gin.New()
+	router.Use(Middleware(nil, func(c *gin.Context) string {
+		return "user1:test"
+	}))
+	router.GET("/test", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{"status": "ok"})
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	// nil limiter 应该放行
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+func TestMiddleware_EmptyKey(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	limiter := &mockLimiter{
+		allowFunc: func(ctx context.Context, key string) (bool, time.Duration) {
+			// 不应该被调用
+			t.Error("Allow should not be called with empty key")
+			return false, 0
+		},
+	}
+
+	router := gin.New()
+	router.Use(Middleware(limiter, func(c *gin.Context) string {
+		return "" // 返回空 key
+	}))
+	router.GET("/test", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{"status": "ok"})
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	// 空 key 应该放行
+	assert.Equal(t, http.StatusOK, w.Code)
+}
+
+func TestMiddleware_KeyFunc(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	var capturedKey string
+	limiter := &mockLimiter{
+		allowFunc: func(ctx context.Context, key string) (bool, time.Duration) {
+			capturedKey = key
+			return true, 0
+		},
+	}
+
+	router := gin.New()
+	router.Use(Middleware(limiter, func(c *gin.Context) string {
+		// 从 query 参数提取 user_id
+		userID := c.Query("user_id")
+		return userID + ":test"
+	}))
+	router.GET("/test", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{"status": "ok"})
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/test?user_id=user123", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Equal(t, "user123:test", capturedKey)
+}
+
+func TestMiddleware_RetryAfterRounding(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	limiter := &mockLimiter{
+		allowFunc: func(ctx context.Context, key string) (bool, time.Duration) {
+			return false, 2500 * time.Millisecond // 2.5 秒
+		},
+	}
+
+	router := gin.New()
+	router.Use(Middleware(limiter, func(c *gin.Context) string {
+		return "user1:test"
+	}))
+	router.GET("/test", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{"status": "ok"})
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/test", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusTooManyRequests, w.Code)
+	// 2.5 秒向上取整为 3 秒
+	assert.Equal(t, "3", w.Header().Get("Retry-After"))
+}

backend/internal/ratelimit/redis_bucket.go

@@ -0,0 +1,132 @@
+package ratelimit
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"time"
+
+	"github.com/hhs/camtalk/internal/config"
+	"github.com/hhs/camtalk/internal/trace"
+	"github.com/redis/go-redis/v9"
+)
+
+// luaScript 是 Redis 令牌桶算法的 Lua 脚本。
+// 保证原子性：读取-计算-回写在一个事务中完成。
+const luaScript = `
+-- 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)}
+`
+
+// RedisLimiter Redis 令牌桶限流器。
+type RedisLimiter struct {
+	client *redis.Client
+	config config.RateLimitConfig
+	script *redis.Script
+}
+
+// NewRedisLimiter 创建 Redis 限流器。
+func NewRedisLimiter(client *redis.Client, cfg config.RateLimitConfig) *RedisLimiter {
+	return &RedisLimiter{
+		client: client,
+		config: cfg,
+		script: redis.NewScript(luaScript),
+	}
+}
+
+// Allow 实现 Limiter 接口。
+func (l *RedisLimiter) Allow(ctx context.Context, key string) (bool, time.Duration) {
+	log := trace.FromContext(ctx)
+	cfg := l.getBucketConfig(key)
+
+	now := float64(time.Now().UnixNano()) / 1e9 // 秒，浮点
+	ttl := 600                                    // key 过期时间 10 分钟
+
+	result, err := l.script.Run(ctx, l.client, []string{key},
+		cfg.Capacity, cfg.Rate, now, ttl).Result()
+
+	if err != nil {
+		log.Errorw("rate limit check failed", "key", key, "error", err)
+		// Redis 错误时降级：允许请求（fail-open 策略）
+		return true, 0
+	}
+
+	// 解析返回值
+	vals, ok := result.([]interface{})
+	if !ok || len(vals) != 2 {
+		return true, 0
+	}
+
+	allowed, _ := vals[0].(int64)
+	retryAfterStr, _ := vals[1].(string)
+	retryAfterSec, _ := strconv.ParseFloat(retryAfterStr, 64)
+
+	if allowed == 1 {
+		return true, 0
+	}
+
+	retryAfter := time.Duration(retryAfterSec*1000) * time.Millisecond
+	log.Warnw("rate limit triggered", "key", key, "retry_after_sec", retryAfterSec)
+	return false, retryAfter
+}
+
+// Stop 实现 Limiter 接口（Redis 不需要清理资源）。
+func (l *RedisLimiter) Stop() {
+	// Redis 客户端由外部管理，这里不需要操作
+}
+
+// getBucketConfig 根据 key 获取桶配置。
+func (l *RedisLimiter) getBucketConfig(key string) config.BucketConfig {
+	// 简化实现：默认使用 query 配置
+	return l.config.Query
+}
+
+// KeyPrefix 返回限流 key 的前缀。
+func KeyPrefix() string {
+	return "ratelimit:"
+}
+
+// FormatKey 格式化限流 key。
+func FormatKey(userID, action string) string {
+	return fmt.Sprintf("%s%s:%s", KeyPrefix(), userID, action)
+}
+
+// 编译期接口检查
+var _ Limiter = (*RedisLimiter)(nil)

backend/internal/ratelimit/redis_bucket_test.go

@@ -0,0 +1,228 @@
+package ratelimit
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/alicebob/miniredis/v2"
+	"github.com/hhs/camtalk/internal/config"
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// setupMiniRedis 创建一个内存 Redis 实例用于测试。
+func setupMiniRedis(t *testing.T) (*miniredis.Miniredis, *redis.Client) {
+	mr, err := miniredis.Run()
+	require.NoError(t, err)
+
+	client := redis.NewClient(&redis.Options{
+		Addr: mr.Addr(),
+	})
+
+	t.Cleanup(func() {
+		client.Close()
+		mr.Close()
+	})
+
+	return mr, client
+}
+
+func TestRedisLimiter_Allow_FirstRequest(t *testing.T) {
+	_, client := setupMiniRedis(t)
+
+	cfg := config.RateLimitConfig{
+		Enabled: true,
+		Query:   config.BucketConfig{Capacity: 5, Rate: 0.2},
+	}
+	limiter := NewRedisLimiter(client, cfg)
+
+	ctx := context.Background()
+	allowed, retryAfter := limiter.Allow(ctx, "user1:query")
+
+	assert.True(t, allowed)
+	assert.Equal(t, time.Duration(0), retryAfter)
+}
+
+func TestRedisLimiter_Allow_ConsumeUntilEmpty(t *testing.T) {
+	_, client := setupMiniRedis(t)
+
+	cfg := config.RateLimitConfig{
+		Enabled: true,
+		Query:   config.BucketConfig{Capacity: 3, Rate: 0.2},
+	}
+	limiter := NewRedisLimiter(client, cfg)
+
+	ctx := context.Background()
+	key := "user1:query"
+
+	// 连续消耗 3 个令牌
+	for i := 0; i < 3; i++ {
+		allowed, _ := limiter.Allow(ctx, key)
+		assert.True(t, allowed, "request %d should be allowed", i+1)
+	}
+
+	// 第 4 个请求应被拒绝
+	allowed, retryAfter := limiter.Allow(ctx, key)
+	assert.False(t, allowed)
+	assert.Greater(t, retryAfter, time.Duration(0))
+}
+
+func TestRedisLimiter_Allow_DifferentKeys(t *testing.T) {
+	_, client := setupMiniRedis(t)
+
+	cfg := config.RateLimitConfig{
+		Enabled: true,
+		Query:   config.BucketConfig{Capacity: 2, Rate: 1.0},
+	}
+	limiter := NewRedisLimiter(client, cfg)
+
+	ctx := context.Background()
+
+	// user1 消耗 2 个令牌
+	allowed, _ := limiter.Allow(ctx, "user1:query")
+	assert.True(t, allowed)
+	allowed, _ = limiter.Allow(ctx, "user1:query")
+	assert.True(t, allowed)
+
+	// user1 第 3 个被拒绝
+	allowed, _ = limiter.Allow(ctx, "user1:query")
+	assert.False(t, allowed)
+
+	// user2 应该不受影响
+	allowed, _ = limiter.Allow(ctx, "user2:query")
+	assert.True(t, allowed)
+}
+
+func TestRedisLimiter_Allow_RefillAfterWait(t *testing.T) {
+	_, client := setupMiniRedis(t)
+
+	cfg := config.RateLimitConfig{
+		Enabled: true,
+		Query:   config.BucketConfig{Capacity: 2, Rate: 10.0}, // 每秒 10 个令牌
+	}
+	limiter := NewRedisLimiter(client, cfg)
+
+	ctx := context.Background()
+	key := "user1:query"
+
+	// 消耗 2 个令牌
+	limiter.Allow(ctx, key)
+	limiter.Allow(ctx, key)
+
+	// 真实等待 150ms（Lua 脚本使用系统时间）
+	time.Sleep(150 * time.Millisecond)
+
+	// 应该补充了至少 1 个令牌
+	allowed, _ := limiter.Allow(ctx, key)
+	assert.True(t, allowed)
+}
+
+func TestRedisLimiter_Allow_CapacityLimit(t *testing.T) {
+	_, client := setupMiniRedis(t)
+
+	cfg := config.RateLimitConfig{
+		Enabled: true,
+		Query:   config.BucketConfig{Capacity: 3, Rate: 1.0},
+	}
+	limiter := NewRedisLimiter(client, cfg)
+
+	ctx := context.Background()
+	key := "user1:query"
+
+	// 真实等待让桶"溢出"
+	time.Sleep(100 * time.Millisecond)
+
+	// 但最多只能消耗 capacity 个令牌
+	for i := 0; i < 3; i++ {
+		allowed, _ := limiter.Allow(ctx, key)
+		assert.True(t, allowed, "request %d should be allowed", i+1)
+	}
+
+	// 第 4 个应被拒绝
+	allowed, _ := limiter.Allow(ctx, key)
+	assert.False(t, allowed)
+}
+
+func TestRedisLimiter_Allow_ZeroRate(t *testing.T) {
+	_, client := setupMiniRedis(t)
+
+	cfg := config.RateLimitConfig{
+		Enabled: true,
+		Query:   config.BucketConfig{Capacity: 1, Rate: 0.0},
+	}
+	limiter := NewRedisLimiter(client, cfg)
+
+	ctx := context.Background()
+	key := "user1:query"
+
+	// 第一个通过
+	allowed, _ := limiter.Allow(ctx, key)
+	assert.True(t, allowed)
+
+	// 第二个被拒绝，retryAfter 应该很大
+	allowed, retryAfter := limiter.Allow(ctx, key)
+	assert.False(t, allowed)
+	assert.Greater(t, retryAfter, 1*time.Hour)
+}
+
+func TestRedisLimiter_Allow_KeyTTL(t *testing.T) {
+	mr, client := setupMiniRedis(t)
+
+	cfg := config.RateLimitConfig{
+		Enabled: true,
+		Query:   config.BucketConfig{Capacity: 5, Rate: 1.0},
+	}
+	limiter := NewRedisLimiter(client, cfg)
+
+	ctx := context.Background()
+	key := "user1:query"
+
+	// 第一次请求
+	limiter.Allow(ctx, key)
+
+	// 验证 key 已设置 TTL
+	ttl := mr.TTL(key)
+	assert.Greater(t, ttl, time.Duration(0))
+	assert.LessOrEqual(t, ttl, 600*time.Second)
+}
+
+func TestRedisLimiter_Allow_FailOpen(t *testing.T) {
+	mr, client := setupMiniRedis(t)
+
+	cfg := config.RateLimitConfig{
+		Enabled: true,
+		Query:   config.BucketConfig{Capacity: 1, Rate: 1.0},
+	}
+	limiter := NewRedisLimiter(client, cfg)
+
+	ctx := context.Background()
+
+	// 关闭 Redis 模拟故障
+	mr.Close()
+
+	// 应该 fail-open（允许请求）
+	allowed, retryAfter := limiter.Allow(ctx, "user1:query")
+	assert.True(t, allowed)
+	assert.Equal(t, time.Duration(0), retryAfter)
+}
+
+func TestRedisLimiter_Stop(t *testing.T) {
+	_, client := setupMiniRedis(t)
+
+	cfg := config.RateLimitConfig{
+		Enabled: true,
+		Query:   config.BucketConfig{Capacity: 1, Rate: 1.0},
+	}
+	limiter := NewRedisLimiter(client, cfg)
+
+	// Stop 应该不会 panic（即使多次调用）
+	limiter.Stop()
+	limiter.Stop()
+}
+
+func TestFormatKey(t *testing.T) {
+	key := FormatKey("user123", "query")
+	assert.Equal(t, "ratelimit:user123:query", key)
+}

backend/internal/session/manager.go

@@ -18,6 +18,7 @@ type ConversationSummary struct {
 	Title        string    `json:"title"`
 	LastMessage  string    `json:"last_message"`
 	MessageCount int       `json:"message_count"`
+	CreatedAt    time.Time `json:"created_at"`
 	UpdatedAt    time.Time `json:"updated_at"`
 }
 

backend/internal/session/memory.go

@@ -142,11 +142,11 @@ func (m *MemoryManager) Create(ctx context.Context, userID string, config models
 	}
 	m.mu.Unlock()
 
-	// Write-Through：异步写 PG
+	// Write-Through：异步写 PG（使用 Background context，避免 HTTP 请求结束后 context 被取消）
 	if m.sessRepo != nil {
 		go func() {
 			cfgJSON, _ := json.Marshal(config)
-			if err := m.sessRepo.Save(ctx, store.SessionRecord{
+			if err := m.sessRepo.Save(context.Background(), store.SessionRecord{
 				ID: id, UserID: userID, Title: models.DefaultSessionTitle,
 				Config: cfgJSON, CreatedAt: now, UpdatedAt: now,
 			}); err != nil {
@@ -204,11 +204,11 @@ func (m *MemoryManager) UpdateConfig(ctx context.Context, sessionID string, patc
 	cfg := entry.session.Config
 	m.mu.Unlock()
 
-	// Write-Through：异步更新 PG
+	// Write-Through：异步更新 PG（使用 Background context）
 	if m.sessRepo != nil {
 		go func() {
 			cfgJSON, _ := json.Marshal(cfg)
-			if err := m.sessRepo.UpdateConfig(ctx, sessionID, cfgJSON); err != nil {
+			if err := m.sessRepo.UpdateConfig(context.Background(), sessionID, cfgJSON); err != nil {
 				logger.Log.Warnw("update session config in DB failed", "session", sessionID, "error", err)
 			}
 		}()
@@ -233,10 +233,10 @@ func (m *MemoryManager) UpdateTitle(ctx context.Context, sessionID string, title
 	entry.lastActive = time.Now()
 	m.mu.Unlock()
 
-	// Write-Through：异步更新 PG
+	// Write-Through：异步更新 PG（使用 Background context）
 	if m.sessRepo != nil {
 		go func() {
-			if err := m.sessRepo.UpdateTitle(ctx, sessionID, title); err != nil {
+			if err := m.sessRepo.UpdateTitle(context.Background(), sessionID, title); err != nil {
 				logger.Log.Warnw("update session title in DB failed", "session", sessionID, "error", err)
 			}
 		}()
@@ -271,6 +271,7 @@ func (m *MemoryManager) ListByUser(ctx context.Context, userID string, page, siz
 			list = append(list, ConversationSummary{
 				ID:        rec.ID,
 				Title:     rec.Title,
+				CreatedAt: rec.CreatedAt,
 				UpdatedAt: rec.UpdatedAt,
 			})
 			sessionIDs = append(sessionIDs, rec.ID)
@@ -320,6 +321,7 @@ func (m *MemoryManager) listByUserFromMemory(ctx context.Context, userID string,
 		summary := ConversationSummary{
 			ID:        entry.session.ID,
 			Title:     entry.session.Title,
+			CreatedAt: entry.session.CreatedAt,
 			UpdatedAt: entry.lastActive,
 		}
 		summary.MessageCount = len(entry.history)
@@ -394,8 +396,10 @@ func (m *MemoryManager) AppendMessage(_ context.Context, sessionID string, msg m
 	entry.history = append(entry.history, msg)
 
 	// 自动更新标题：首条 user 消息时，如果标题为默认值，自动更新为消息前 20 字符
+	titleUpdated := false
 	if msg.Role == "user" && entry.session.Title == models.DefaultSessionTitle {
 		entry.session.Title = generateTitle(msg.Content)
+		titleUpdated = true
 	}
 
 	// 超过上限时裁剪，保留最新的 maxHistory 条
@@ -406,13 +410,31 @@ func (m *MemoryManager) AppendMessage(_ context.Context, sessionID string, msg m
 	now := time.Now()
 	entry.lastActive = now
 	entry.session.UpdatedAt = now
+
+	// 复制标题（释放锁后安全使用）
+	persistTitle := entry.session.Title
 	m.mu.Unlock()
 
-	// Write-Through：异步写冷存储，不阻塞调用方
+	// Write-Through：消息同步写入 PostgreSQL（保证调用顺序 = 插入顺序，
+	// 避免用户消息和 AI 消息的异步 goroutine 执行顺序不确定导致排序错乱）
 	if m.msgRepo != nil {
+		if err := m.msgRepo.SaveMessage(context.Background(), sessionID, msg, 0); err != nil {
+			logger.Log.Warnw("persist message failed", "session", sessionID, "error", err)
+		}
+	}
+
+	// Write-Through：异步更新会话元数据（标题 + updated_at）到 PostgreSQL
+	if m.sessRepo != nil {
 		go func() {
-			if err := m.msgRepo.SaveMessage(context.Background(), sessionID, msg, 0); err != nil {
-				logger.Log.Warnw("persist message failed", "session", sessionID, "error", err)
+			if titleUpdated {
+				if err := m.sessRepo.UpdateTitle(context.Background(), sessionID, persistTitle); err != nil {
+					logger.Log.Warnw("persist session title failed", "session", sessionID, "error", err)
+				}
+			} else {
+				// 即使标题没变，也要刷新 updated_at（保证列表排序正确）
+				if err := m.sessRepo.Touch(context.Background(), sessionID); err != nil {
+					logger.Log.Warnw("touch session in DB failed", "session", sessionID, "error", err)
+				}
 			}
 		}()
 	}
@@ -540,10 +562,10 @@ func (m *MemoryManager) Destroy(ctx context.Context, sessionID string) error {
 	delete(m.sessions, sessionID)
 	m.mu.Unlock()
 
-	// Write-Through：异步删除 PG
+	// Write-Through：异步删除 PG（使用 Background context）
 	if m.sessRepo != nil {
 		go func() {
-			if err := m.sessRepo.Delete(ctx, sessionID); err != nil {
+			if err := m.sessRepo.Delete(context.Background(), sessionID); err != nil {
 				logger.Log.Warnw("delete session from DB failed", "session", sessionID, "error", err)
 			}
 		}()

backend/internal/session/redis.go

@@ -10,8 +10,9 @@ import (
 	"github.com/google/uuid"
 	"github.com/redis/go-redis/v9"
 
-	"github.com/hhs/camtalk/internal/logger"
 	"github.com/hhs/camtalk/internal/models"
+	"github.com/hhs/camtalk/internal/trace"
+	"github.com/hhs/camtalk/internal/util"
 )
 
 // RedisManager 基于 Redis 的 SessionManager 实现。
@@ -87,7 +88,8 @@ func (m *RedisManager) CreateWithID(ctx context.Context, id string, userID strin
 		return "", fmt.Errorf("redis create session: %w", err)
 	}
 
-	logger.Log.Debugw("redis session created", "session", id, "user_id", userID)
+	log := trace.FromContext(ctx)
+	log.Debugw("redis session created", "session_id", id, "user_id", userID)
 	return id, nil
 }
 
@@ -96,8 +98,11 @@ const placeholderHistoryMark = "__placeholder__"
 
 // Get 获取会话。
 func (m *RedisManager) Get(ctx context.Context, sessionID string) (*models.Session, error) {
+	log := trace.FromContext(ctx)
+
 	vals, err := m.rdb.HGetAll(ctx, metaKey(sessionID)).Result()
 	if err != nil {
+		log.Errorw("redis get session failed", "session_id", sessionID, "error", err)
 		return nil, fmt.Errorf("redis get session: %w", err)
 	}
 	if len(vals) == 0 {
@@ -115,6 +120,7 @@ func (m *RedisManager) Get(ctx context.Context, sessionID string) (*models.Sessi
 	sess.Config.DetailLevel = vals["config.detail_level"]
 	sess.Config.Language = vals["config.language"]
 
+	log.Debugw("redis session retrieved", "session_id", sessionID)
 	return sess, nil
 }
 
@@ -150,7 +156,9 @@ func (m *RedisManager) UpdateConfig(ctx context.Context, sessionID string, patch
 
 	// 刷新 TTL
 	m.rdb.Expire(ctx, metaKey(sessionID), m.ttl)
-	logger.Log.Debugw("redis session config updated", "session", sessionID)
+
+	log := trace.FromContext(ctx)
+	log.Debugw("redis session config updated", "session_id", sessionID)
 	return nil
 }
 
@@ -170,7 +178,9 @@ func (m *RedisManager) UpdateTitle(ctx context.Context, sessionID string, title
 	}
 
 	m.rdb.Expire(ctx, metaKey(sessionID), m.ttl)
-	logger.Log.Debugw("redis session title updated", "session", sessionID, "title", title)
+
+	log := trace.FromContext(ctx)
+	log.Debugw("redis session title updated", "session_id", sessionID, "title", title)
 	return nil
 }
 
@@ -285,7 +295,11 @@ func (m *RedisManager) GetHistory(ctx context.Context, sessionID string, limit i
 		}
 		var msg models.Message
 		if err := json.Unmarshal([]byte(raw), &msg); err != nil {
-			logger.Log.Warnw("invalid history entry", "session", sessionID, "raw", raw)
+			log := trace.FromContext(ctx)
+			log.Warnw("invalid history entry",
+				"session_id", sessionID,
+				"raw_len", len(raw),
+				"raw_preview", util.Truncate(raw, 100))
 			continue
 		}
 		msgs = append(msgs, msg)
@@ -436,7 +450,8 @@ func (m *RedisManager) Destroy(ctx context.Context, sessionID string) error {
 		m.rdb.SRem(ctx, userSessKey(userID), sessionID)
 	}
 
-	logger.Log.Debugw("redis session destroyed", "session", sessionID)
+	log := trace.FromContext(ctx)
+	log.Debugw("redis session destroyed", "session_id", sessionID)
 	return nil
 }
 

backend/internal/store/cached_user.go

@@ -0,0 +1,172 @@
+package store
+
+import (
+	"context"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+
+	"github.com/hhs/camtalk/internal/trace"
+)
+
+// Redis key 前缀。
+const (
+	refreshTokenPrefix = "auth:refresh:"      // auth:refresh:{token_hash} → user_id
+	userRefreshPrefix  = "auth:user_refresh:" // auth:user_refresh:{user_id} → Set of token_hash
+)
+
+// CachedUserRepository 装饰器，为 UserRepository 的 refresh token 操作增加 Redis 缓存。
+// 读路径：Redis miss → DB → 回填 Redis。
+// 写路径：同步双写 Redis + DB。
+// 删路径：同步双删 Redis + DB。
+// Redis 操作失败时降级到纯 DB，不阻断主流程。
+type CachedUserRepository struct {
+	inner       UserRepository
+	rdb         *redis.Client
+	backfillTTL time.Duration // DB 回填 Redis 时使用的默认 TTL
+}
+
+// NewCachedUserRepository 创建带 Redis 缓存的 UserRepository 装饰器。
+// backfillTTL: 从 DB 回填 Redis 时使用的 TTL（因 DB 接口不返回 expiresAt）。
+func NewCachedUserRepository(inner UserRepository, rdb *redis.Client, backfillTTL time.Duration) *CachedUserRepository {
+	if backfillTTL <= 0 {
+		backfillTTL = 24 * time.Hour
+	}
+	return &CachedUserRepository{
+		inner:       inner,
+		rdb:         rdb,
+		backfillTTL: backfillTTL,
+	}
+}
+
+// refreshTokenKey 生成 refresh token 的 Redis key。
+func refreshTokenKey(tokenHash string) string {
+	return refreshTokenPrefix + tokenHash
+}
+
+// userRefreshKey 生成用户 refresh token 集合的 Redis key。
+func userRefreshKey(userID string) string {
+	return userRefreshPrefix + userID
+}
+
+// --- 委托方法（不做缓存） ---
+
+func (r *CachedUserRepository) Create(ctx context.Context, username, passwordHash string) (string, error) {
+	return r.inner.Create(ctx, username, passwordHash)
+}
+
+func (r *CachedUserRepository) FindByUsername(ctx context.Context, username string) (*User, error) {
+	return r.inner.FindByUsername(ctx, username)
+}
+
+func (r *CachedUserRepository) FindByID(ctx context.Context, id string) (*User, error) {
+	return r.inner.FindByID(ctx, id)
+}
+
+// --- 缓存方法 ---
+
+// SaveRefreshToken Write-Through：先写 DB，再写 Redis。
+func (r *CachedUserRepository) SaveRefreshToken(ctx context.Context, userID, tokenHash string, expiresAt time.Time) error {
+	// 先写 DB
+	if err := r.inner.SaveRefreshToken(ctx, userID, tokenHash, expiresAt); err != nil {
+		return err
+	}
+
+	// 写 Redis（SET + SADD），设置 TTL 为 token 剩余有效期
+	ttl := time.Until(expiresAt)
+	if ttl <= 0 {
+		return nil
+	}
+
+	key := refreshTokenKey(tokenHash)
+	pipe := r.rdb.Pipeline()
+	pipe.Set(ctx, key, userID, ttl)
+	pipe.SAdd(ctx, userRefreshKey(userID), tokenHash)
+	if _, err := pipe.Exec(ctx); err != nil {
+		log := trace.FromContext(ctx)
+		log.Warnw("redis cache write failed for refresh token", "error", err)
+		// 降级：DB 已写入成功，Redis 失败不影响正确性
+	}
+	return nil
+}
+
+// FindRefreshToken Read-Through：先查 Redis，miss 时查 DB 并回填。
+func (r *CachedUserRepository) FindRefreshToken(ctx context.Context, tokenHash string) (string, error) {
+	key := refreshTokenKey(tokenHash)
+
+	// 查 Redis
+	userID, err := r.rdb.Get(ctx, key).Result()
+	if err == nil {
+		return userID, nil
+	}
+	// redis.Nil 表示 key 不存在，其他错误记录日志后降级到 DB
+	if err != redis.Nil {
+		log := trace.FromContext(ctx)
+		log.Warnw("redis cache read failed for refresh token", "error", err)
+	}
+
+	// 降级到 DB
+	userID, err = r.inner.FindRefreshToken(ctx, tokenHash)
+	if err != nil {
+		return "", err
+	}
+
+	// 回填 Redis（SET + SADD），TTL 使用保守默认值
+	go func() {
+		bgCtx := context.Background()
+		pipe := r.rdb.Pipeline()
+		pipe.Set(bgCtx, key, userID, r.backfillTTL)
+		pipe.SAdd(bgCtx, userRefreshKey(userID), tokenHash)
+		_, _ = pipe.Exec(bgCtx)
+	}()
+
+	return userID, nil
+}
+
+// DeleteRefreshToken 双删：先删 DB，再删 Redis。
+func (r *CachedUserRepository) DeleteRefreshToken(ctx context.Context, tokenHash string) error {
+	// 先从 Redis 获取 user_id（用于从集合中移除）
+	userID, _ := r.rdb.Get(ctx, refreshTokenKey(tokenHash)).Result()
+
+	// 删 DB
+	if err := r.inner.DeleteRefreshToken(ctx, tokenHash); err != nil {
+		return err
+	}
+
+	// 删 Redis
+	key := refreshTokenKey(tokenHash)
+	pipe := r.rdb.Pipeline()
+	pipe.Del(ctx, key)
+	if userID != "" {
+		pipe.SRem(ctx, userRefreshKey(userID), tokenHash)
+	}
+	if _, err := pipe.Exec(ctx); err != nil {
+		log := trace.FromContext(ctx)
+		log.Warnw("redis cache delete failed for refresh token", "error", err)
+	}
+	return nil
+}
+
+// DeleteUserRefreshTokens 批量清理：先从 Redis 获取集合，逐个删缓存，再删 DB。
+func (r *CachedUserRepository) DeleteUserRefreshTokens(ctx context.Context, userID string) error {
+	userKey := userRefreshKey(userID)
+
+	// 从 Redis 获取该用户所有 token hash
+	hashes, _ := r.rdb.SMembers(ctx, userKey).Result()
+
+	// 批量删除 Redis 缓存
+	if len(hashes) > 0 {
+		keys := make([]string, 0, len(hashes)+1)
+		for _, h := range hashes {
+			keys = append(keys, refreshTokenKey(h))
+		}
+		keys = append(keys, userKey)
+		if err := r.rdb.Del(ctx, keys...).Err(); err != nil {
+			log := trace.FromContext(ctx)
+			log.Warnw("redis cache batch delete failed for user refresh tokens", "error", err, "user_id", userID)
+		}
+	}
+
+	// 删 DB（无论 Redis 是否成功都执行）
+	return r.inner.DeleteUserRefreshTokens(ctx, userID)
+}

backend/internal/store/message_pg.go

@@ -8,6 +8,7 @@ import (
 	"github.com/jackc/pgx/v5/pgxpool"
 
 	"github.com/hhs/camtalk/internal/models"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // PgMessageRepository 基于 PostgreSQL 的 MessageRepository 实现。
@@ -21,14 +22,24 @@ func NewPgMessageRepository(pool *pgxpool.Pool) *PgMessageRepository {
 }
 
 func (r *PgMessageRepository) SaveMessage(ctx context.Context, sessionID string, msg models.Message, tokensUsed int) error {
+	log := trace.FromContext(ctx)
+
 	_, err := r.pool.Exec(ctx,
 		`INSERT INTO messages (session_id, role, content, tokens_used) VALUES ($1, $2, $3, $4)`,
 		sessionID, msg.Role, msg.Content, tokensUsed,
 	)
-	return err
+	if err != nil {
+		log.Errorw("save message failed", "session_id", sessionID, "role", msg.Role, "error", err)
+		return err
+	}
+
+	log.Debugw("message saved", "session_id", sessionID, "role", msg.Role, "tokens_used", tokensUsed)
+	return nil
 }
 
 func (r *PgMessageRepository) GetMessages(ctx context.Context, sessionID string, limit int, beforeID int64) ([]StoredMessage, error) {
+	log := trace.FromContext(ctx)
+
 	if limit <= 0 {
 		limit = 50
 	}
@@ -56,6 +67,7 @@ func (r *PgMessageRepository) GetMessages(ctx context.Context, sessionID string,
 		)
 	}
 	if err != nil {
+		log.Errorw("get messages failed", "session_id", sessionID, "error", err)
 		return nil, err
 	}
 
@@ -64,31 +76,39 @@ func (r *PgMessageRepository) GetMessages(ctx context.Context, sessionID string,
 		rows[i], rows[j] = rows[j], rows[i]
 	}
 
+	log.Debugw("messages retrieved", "session_id", sessionID, "count", len(rows))
 	return rows, nil
 }
 
 func (r *PgMessageRepository) queryMessages(ctx context.Context, query string, args ...any) ([]StoredMessage, error) {
+	log := trace.FromContext(ctx)
+
 	pgxRows, err := r.pool.Query(ctx, query, args...)
 	if err != nil {
+		log.Errorw("query messages failed", "error", err)
 		return nil, err
 	}
 	defer pgxRows.Close()
 
-	var messages []StoredMessage
+	messages := make([]StoredMessage, 0)
 	for pgxRows.Next() {
 		var m StoredMessage
 		if err := pgxRows.Scan(&m.ID, &m.SessionID, &m.Role, &m.Content, &m.TokensUsed, &m.CreatedAt); err != nil {
+			log.Errorw("scan message row failed", "error", err)
 			return nil, err
 		}
 		messages = append(messages, m)
 	}
 	if err := pgxRows.Err(); err != nil {
+		log.Errorw("iterate message rows failed", "error", err)
 		return nil, err
 	}
 	return messages, nil
 }
 
 func (r *PgMessageRepository) GetLastMessage(ctx context.Context, sessionID string) (*StoredMessage, error) {
+	log := trace.FromContext(ctx)
+
 	var m StoredMessage
 	err := r.pool.QueryRow(ctx,
 		`SELECT id, session_id, role, content, tokens_used, created_at
@@ -102,24 +122,34 @@ func (r *PgMessageRepository) GetLastMessage(ctx context.Context, sessionID stri
 		return nil, ErrMessageNotFound
 	}
 	if err != nil {
+		log.Errorw("get last message failed", "session_id", sessionID, "error", err)
 		return nil, err
 	}
+
+	log.Debugw("last message retrieved", "session_id", sessionID, "message_id", m.ID)
 	return &m, nil
 }
 
 func (r *PgMessageRepository) GetMessageCount(ctx context.Context, sessionID string) (int, error) {
+	log := trace.FromContext(ctx)
+
 	var count int
 	err := r.pool.QueryRow(ctx,
 		`SELECT COUNT(*) FROM messages WHERE session_id = $1`,
 		sessionID,
 	).Scan(&count)
 	if err != nil {
+		log.Errorw("get message count failed", "session_id", sessionID, "error", err)
 		return 0, err
 	}
+
+	log.Debugw("message count retrieved", "session_id", sessionID, "count", count)
 	return count, nil
 }
 
 func (r *PgMessageRepository) GetSessionMessageStats(ctx context.Context, sessionIDs []string) (map[string]SessionMessageStats, error) {
+	log := trace.FromContext(ctx)
+
 	if len(sessionIDs) == 0 {
 		return map[string]SessionMessageStats{}, nil
 	}
@@ -143,6 +173,7 @@ func (r *PgMessageRepository) GetSessionMessageStats(ctx context.Context, sessio
 		sessionIDs,
 	)
 	if err != nil {
+		log.Errorw("get session message stats failed", "session_count", len(sessionIDs), "error", err)
 		return nil, err
 	}
 	defer rows.Close()
@@ -152,12 +183,16 @@ func (r *PgMessageRepository) GetSessionMessageStats(ctx context.Context, sessio
 		var sid string
 		var stats SessionMessageStats
 		if err := rows.Scan(&sid, &stats.MessageCount, &stats.LastMessage); err != nil {
+			log.Errorw("scan message stats row failed", "error", err)
 			return nil, err
 		}
 		result[sid] = stats
 	}
 	if err := rows.Err(); err != nil {
+		log.Errorw("iterate message stats rows failed", "error", err)
 		return nil, err
 	}
+
+	log.Debugw("session message stats retrieved", "session_count", len(sessionIDs), "result_count", len(result))
 	return result, nil
 }

backend/internal/store/session_pg.go

@@ -6,6 +6,8 @@ import (
 
 	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgxpool"
+
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // PgSessionRepository 基于 PostgreSQL 的 SessionRepository 实现。
@@ -19,6 +21,8 @@ func NewPgSessionRepository(pool *pgxpool.Pool) *PgSessionRepository {
 }
 
 func (r *PgSessionRepository) Save(ctx context.Context, s SessionRecord) error {
+	log := trace.FromContext(ctx)
+
 	_, err := r.pool.Exec(ctx,
 		`INSERT INTO sessions (id, user_id, title, config, created_at, updated_at)
 		 VALUES ($1, $2, $3, $4, $5, $6)
@@ -28,10 +32,18 @@ func (r *PgSessionRepository) Save(ctx context.Context, s SessionRecord) error {
 		   updated_at = EXCLUDED.updated_at`,
 		s.ID, s.UserID, s.Title, s.Config, s.CreatedAt, s.UpdatedAt,
 	)
-	return err
+	if err != nil {
+		log.Errorw("save session failed", "session_id", s.ID, "error", err)
+		return err
+	}
+
+	log.Debugw("session saved", "session_id", s.ID, "user_id", s.UserID)
+	return nil
 }
 
 func (r *PgSessionRepository) FindByID(ctx context.Context, id string) (*SessionRecord, error) {
+	log := trace.FromContext(ctx)
+
 	var s SessionRecord
 	err := r.pool.QueryRow(ctx,
 		`SELECT id, user_id, title, config, created_at, updated_at
@@ -41,12 +53,17 @@ func (r *PgSessionRepository) FindByID(ctx context.Context, id string) (*Session
 		return nil, ErrSessionNotFound
 	}
 	if err != nil {
+		log.Errorw("find session failed", "session_id", id, "error", err)
 		return nil, err
 	}
+
+	log.Debugw("session found", "session_id", id)
 	return &s, nil
 }
 
 func (r *PgSessionRepository) FindByUser(ctx context.Context, userID string, page, size int) ([]SessionRecord, int, error) {
+	log := trace.FromContext(ctx)
+
 	if page <= 0 {
 		page = 1
 	}
@@ -60,6 +77,7 @@ func (r *PgSessionRepository) FindByUser(ctx context.Context, userID string, pag
 	if err := r.pool.QueryRow(ctx,
 		`SELECT COUNT(*) FROM sessions WHERE user_id = $1`, userID,
 	).Scan(&total); err != nil {
+		log.Errorw("count user sessions failed", "user_id", userID, "error", err)
 		return nil, 0, err
 	}
 
@@ -73,6 +91,7 @@ func (r *PgSessionRepository) FindByUser(ctx context.Context, userID string, pag
 		userID, size, offset,
 	)
 	if err != nil {
+		log.Errorw("find user sessions failed", "user_id", userID, "error", err)
 		return nil, 0, err
 	}
 	defer rows.Close()
@@ -81,66 +100,90 @@ func (r *PgSessionRepository) FindByUser(ctx context.Context, userID string, pag
 	for rows.Next() {
 		var s SessionRecord
 		if err := rows.Scan(&s.ID, &s.UserID, &s.Title, &s.Config, &s.CreatedAt, &s.UpdatedAt); err != nil {
+			log.Errorw("scan session row failed", "user_id", userID, "error", err)
 			return nil, 0, err
 		}
 		list = append(list, s)
 	}
 	if err := rows.Err(); err != nil {
+		log.Errorw("iterate session rows failed", "user_id", userID, "error", err)
 		return nil, 0, err
 	}
+
+	log.Debugw("user sessions found", "user_id", userID, "count", len(list), "total", total)
 	return list, total, nil
 }
 
 func (r *PgSessionRepository) UpdateTitle(ctx context.Context, id string, title string) error {
+	log := trace.FromContext(ctx)
+
 	tag, err := r.pool.Exec(ctx,
 		`UPDATE sessions SET title = $2, updated_at = NOW() WHERE id = $1`,
 		id, title,
 	)
 	if err != nil {
+		log.Errorw("update session title failed", "session_id", id, "error", err)
 		return err
 	}
 	if tag.RowsAffected() == 0 {
 		return ErrSessionNotFound
 	}
+
+	log.Debugw("session title updated", "session_id", id)
 	return nil
 }
 
 func (r *PgSessionRepository) UpdateConfig(ctx context.Context, id string, configJSON []byte) error {
+	log := trace.FromContext(ctx)
+
 	tag, err := r.pool.Exec(ctx,
 		`UPDATE sessions SET config = $2, updated_at = NOW() WHERE id = $1`,
 		id, configJSON,
 	)
 	if err != nil {
+		log.Errorw("update session config failed", "session_id", id, "error", err)
 		return err
 	}
 	if tag.RowsAffected() == 0 {
 		return ErrSessionNotFound
 	}
+
+	log.Debugw("session config updated", "session_id", id)
 	return nil
 }
 
 func (r *PgSessionRepository) Touch(ctx context.Context, id string) error {
+	log := trace.FromContext(ctx)
+
 	tag, err := r.pool.Exec(ctx,
 		`UPDATE sessions SET updated_at = NOW() WHERE id = $1`, id,
 	)
 	if err != nil {
+		log.Errorw("touch session failed", "session_id", id, "error", err)
 		return err
 	}
 	if tag.RowsAffected() == 0 {
 		return ErrSessionNotFound
 	}
+
+	log.Debugw("session touched", "session_id", id)
 	return nil
 }
 
 func (r *PgSessionRepository) Delete(ctx context.Context, id string) error {
+	log := trace.FromContext(ctx)
+
 	tag, err := r.pool.Exec(ctx,
 		`DELETE FROM sessions WHERE id = $1`, id,
 	)
 	if err != nil {
+		log.Errorw("delete session failed", "session_id", id, "error", err)
 		return err
 	}
 	if tag.RowsAffected() == 0 {
 		return ErrSessionNotFound
 	}
+
+	log.Debugw("session deleted", "session_id", id)
 	return nil
 }

backend/internal/store/user_pg.go

@@ -7,6 +7,8 @@ import (
 
 	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgxpool"
+
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // PgUserRepository 基于 PostgreSQL 的 UserRepository 实现。
@@ -20,18 +22,25 @@ func NewPgUserRepository(pool *pgxpool.Pool) *PgUserRepository {
 }
 
 func (r *PgUserRepository) Create(ctx context.Context, username, passwordHash string) (string, error) {
+	log := trace.FromContext(ctx)
+
 	var id string
 	err := r.pool.QueryRow(ctx,
 		`INSERT INTO users (username, password_hash) VALUES ($1, $2) RETURNING id`,
 		username, passwordHash,
 	).Scan(&id)
 	if err != nil {
+		log.Errorw("create user failed", "username", username, "error", err)
 		return "", err
 	}
+
+	log.Debugw("user created", "user_id", id, "username", username)
 	return id, nil
 }
 
 func (r *PgUserRepository) FindByUsername(ctx context.Context, username string) (*User, error) {
+	log := trace.FromContext(ctx)
+
 	var u User
 	err := r.pool.QueryRow(ctx,
 		`SELECT id, username, password_hash, created_at, updated_at FROM users WHERE username = $1`,
@@ -41,12 +50,17 @@ func (r *PgUserRepository) FindByUsername(ctx context.Context, username string)
 		return nil, ErrUserNotFound
 	}
 	if err != nil {
+		log.Errorw("find user by username failed", "username", username, "error", err)
 		return nil, err
 	}
+
+	log.Debugw("user found by username", "user_id", u.ID, "username", username)
 	return &u, nil
 }
 
 func (r *PgUserRepository) FindByID(ctx context.Context, id string) (*User, error) {
+	log := trace.FromContext(ctx)
+
 	var u User
 	err := r.pool.QueryRow(ctx,
 		`SELECT id, username, password_hash, created_at, updated_at FROM users WHERE id = $1`,
@@ -56,20 +70,33 @@ func (r *PgUserRepository) FindByID(ctx context.Context, id string) (*User, erro
 		return nil, ErrUserNotFound
 	}
 	if err != nil {
+		log.Errorw("find user by id failed", "user_id", id, "error", err)
 		return nil, err
 	}
+
+	log.Debugw("user found by id", "user_id", id)
 	return &u, nil
 }
 
 func (r *PgUserRepository) SaveRefreshToken(ctx context.Context, userID, tokenHash string, expiresAt time.Time) error {
+	log := trace.FromContext(ctx)
+
 	_, err := r.pool.Exec(ctx,
 		`INSERT INTO refresh_tokens (user_id, token_hash, expires_at) VALUES ($1, $2, $3)`,
 		userID, tokenHash, expiresAt,
 	)
-	return err
+	if err != nil {
+		log.Errorw("save refresh token failed", "user_id", userID, "error", err)
+		return err
+	}
+
+	log.Debugw("refresh token saved", "user_id", userID)
+	return nil
 }
 
 func (r *PgUserRepository) FindRefreshToken(ctx context.Context, tokenHash string) (string, error) {
+	log := trace.FromContext(ctx)
+
 	var userID string
 	err := r.pool.QueryRow(ctx,
 		`SELECT user_id FROM refresh_tokens WHERE token_hash = $1 AND expires_at > NOW()`,
@@ -79,23 +106,42 @@ func (r *PgUserRepository) FindRefreshToken(ctx context.Context, tokenHash strin
 		return "", ErrRefreshTokenNotFound
 	}
 	if err != nil {
+		log.Errorw("find refresh token failed", "error", err)
 		return "", err
 	}
+
+	log.Debugw("refresh token found", "user_id", userID)
 	return userID, nil
 }
 
 func (r *PgUserRepository) DeleteRefreshToken(ctx context.Context, tokenHash string) error {
+	log := trace.FromContext(ctx)
+
 	_, err := r.pool.Exec(ctx,
 		`DELETE FROM refresh_tokens WHERE token_hash = $1`,
 		tokenHash,
 	)
-	return err
+	if err != nil {
+		log.Errorw("delete refresh token failed", "error", err)
+		return err
+	}
+
+	log.Debugw("refresh token deleted")
+	return nil
 }
 
 func (r *PgUserRepository) DeleteUserRefreshTokens(ctx context.Context, userID string) error {
+	log := trace.FromContext(ctx)
+
 	_, err := r.pool.Exec(ctx,
 		`DELETE FROM refresh_tokens WHERE user_id = $1`,
 		userID,
 	)
-	return err
+	if err != nil {
+		log.Errorw("delete user refresh tokens failed", "user_id", userID, "error", err)
+		return err
+	}
+
+	log.Debugw("user refresh tokens deleted", "user_id", userID)
+	return nil
 }

backend/internal/store/user_scenario_repository.go

@@ -0,0 +1,276 @@
+package store
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"github.com/hhs/camtalk/internal/models"
+	"github.com/hhs/camtalk/internal/trace"
+)
+
+// UserScenarioRepository 用户自建情景仓储接口。
+type UserScenarioRepository interface {
+	Create(ctx context.Context, scenario *models.UserScenario) error
+	FindByID(ctx context.Context, id string) (*models.UserScenario, error)
+	FindByIDAndUserID(ctx context.Context, id, userID string) (*models.UserScenario, error)
+	FindByUserID(ctx context.Context, userID string) ([]*models.UserScenario, error)
+	Update(ctx context.Context, scenario *models.UserScenario) error
+	Delete(ctx context.Context, id string) error
+	CountByUserID(ctx context.Context, userID string) (int, error)
+}
+
+// PostgresUserScenarioRepo PostgreSQL 实现。
+type PostgresUserScenarioRepo struct {
+	pool *pgxpool.Pool
+}
+
+// NewPostgresUserScenarioRepo 创建 PostgreSQL 用户情景仓储。
+func NewPostgresUserScenarioRepo(pool *pgxpool.Pool) UserScenarioRepository {
+	return &PostgresUserScenarioRepo{pool: pool}
+}
+
+// Create 创建用户情景。
+func (r *PostgresUserScenarioRepo) Create(ctx context.Context, scenario *models.UserScenario) error {
+	log := trace.FromContext(ctx)
+
+	query := `
+		INSERT INTO user_scenarios (id, user_id, name, icon, description, prompt, greeting, language, created_at, updated_at)
+		VALUES ($1, $2, $3, $4, NULLIF($5, ''), $6, NULLIF($7, ''), $8, $9, $10)
+		RETURNING id, created_at, updated_at
+	`
+
+	now := time.Now()
+	scenario.CreatedAt = now
+	scenario.UpdatedAt = now
+
+	if scenario.ID == "" {
+		scenario.ID = uuid.New().String()
+	}
+	if scenario.Icon == "" {
+		scenario.Icon = "✨"
+	}
+	if scenario.Language == "" {
+		scenario.Language = "zh-CN"
+	}
+
+	err := r.pool.QueryRow(ctx, query,
+		scenario.ID,
+		scenario.UserID,
+		scenario.Name,
+		scenario.Icon,
+		scenario.Description,
+		scenario.Prompt,
+		scenario.Greeting,
+		scenario.Language,
+		scenario.CreatedAt,
+		scenario.UpdatedAt,
+	).Scan(&scenario.ID, &scenario.CreatedAt, &scenario.UpdatedAt)
+
+	if err != nil {
+		log.Errorw("create user scenario failed", "user_id", scenario.UserID, "name", scenario.Name, "error", err)
+		return fmt.Errorf("create user scenario: %w", err)
+	}
+
+	log.Debugw("user scenario created", "scenario_id", scenario.ID, "user_id", scenario.UserID, "name", scenario.Name)
+	return nil
+}
+
+// FindByID 根据 ID 查找情景。
+func (r *PostgresUserScenarioRepo) FindByID(ctx context.Context, id string) (*models.UserScenario, error) {
+	log := trace.FromContext(ctx)
+
+	query := `
+		SELECT id, user_id, name, icon, description, prompt, greeting, language, created_at, updated_at
+		FROM user_scenarios
+		WHERE id = $1
+	`
+
+	var scenario models.UserScenario
+	err := r.pool.QueryRow(ctx, query, id).Scan(
+		&scenario.ID,
+		&scenario.UserID,
+		&scenario.Name,
+		&scenario.Icon,
+		&scenario.Description,
+		&scenario.Prompt,
+		&scenario.Greeting,
+		&scenario.Language,
+		&scenario.CreatedAt,
+		&scenario.UpdatedAt,
+	)
+
+	if err == pgx.ErrNoRows {
+		return nil, fmt.Errorf("user scenario not found: %s", id)
+	}
+	if err != nil {
+		log.Errorw("find user scenario failed", "scenario_id", id, "error", err)
+		return nil, fmt.Errorf("find user scenario: %w", err)
+	}
+
+	log.Debugw("user scenario found", "scenario_id", id)
+	return &scenario, nil
+}
+
+// FindByIDAndUserID 根据 ID 和用户 ID 查找情景（权限校验）。
+func (r *PostgresUserScenarioRepo) FindByIDAndUserID(ctx context.Context, id, userID string) (*models.UserScenario, error) {
+	log := trace.FromContext(ctx)
+
+	query := `
+		SELECT id, user_id, name, icon, description, prompt, greeting, language, created_at, updated_at
+		FROM user_scenarios
+		WHERE id = $1 AND user_id = $2
+	`
+
+	var scenario models.UserScenario
+	err := r.pool.QueryRow(ctx, query, id, userID).Scan(
+		&scenario.ID,
+		&scenario.UserID,
+		&scenario.Name,
+		&scenario.Icon,
+		&scenario.Description,
+		&scenario.Prompt,
+		&scenario.Greeting,
+		&scenario.Language,
+		&scenario.CreatedAt,
+		&scenario.UpdatedAt,
+	)
+
+	if err == pgx.ErrNoRows {
+		return nil, fmt.Errorf("user scenario not found or no permission")
+	}
+	if err != nil {
+		log.Errorw("find user scenario by id and user failed", "scenario_id", id, "user_id", userID, "error", err)
+		return nil, fmt.Errorf("find user scenario: %w", err)
+	}
+
+	log.Debugw("user scenario found by id and user", "scenario_id", id, "user_id", userID)
+	return &scenario, nil
+}
+
+// FindByUserID 查找用户的所有情景。
+func (r *PostgresUserScenarioRepo) FindByUserID(ctx context.Context, userID string) ([]*models.UserScenario, error) {
+	log := trace.FromContext(ctx)
+
+	query := `
+		SELECT id, user_id, name, icon, description, prompt, greeting, language, created_at, updated_at
+		FROM user_scenarios
+		WHERE user_id = $1
+		ORDER BY created_at DESC
+	`
+
+	rows, err := r.pool.Query(ctx, query, userID)
+	if err != nil {
+		log.Errorw("find user scenarios failed", "user_id", userID, "error", err)
+		return nil, fmt.Errorf("find user scenarios: %w", err)
+	}
+	defer rows.Close()
+
+	var scenarios []*models.UserScenario
+	for rows.Next() {
+		var s models.UserScenario
+		err := rows.Scan(
+			&s.ID,
+			&s.UserID,
+			&s.Name,
+			&s.Icon,
+			&s.Description,
+			&s.Prompt,
+			&s.Greeting,
+			&s.Language,
+			&s.CreatedAt,
+			&s.UpdatedAt,
+		)
+		if err != nil {
+			log.Errorw("scan user scenario row failed", "user_id", userID, "error", err)
+			return nil, fmt.Errorf("scan user scenario: %w", err)
+		}
+		scenarios = append(scenarios, &s)
+	}
+
+	if err = rows.Err(); err != nil {
+		log.Errorw("iterate user scenarios failed", "user_id", userID, "error", err)
+		return nil, fmt.Errorf("iterate user scenarios: %w", err)
+	}
+
+	log.Debugw("user scenarios found", "user_id", userID, "count", len(scenarios))
+	return scenarios, nil
+}
+
+// Update 更新用户情景。
+func (r *PostgresUserScenarioRepo) Update(ctx context.Context, scenario *models.UserScenario) error {
+	log := trace.FromContext(ctx)
+
+	query := `
+		UPDATE user_scenarios
+		SET name = $1, icon = $2, description = $3, prompt = $4, greeting = $5, language = $6, updated_at = $7
+		WHERE id = $8 AND user_id = $9
+		RETURNING updated_at
+	`
+
+	scenario.UpdatedAt = time.Now()
+
+	err := r.pool.QueryRow(ctx, query,
+		scenario.Name,
+		scenario.Icon,
+		scenario.Description,
+		scenario.Prompt,
+		scenario.Greeting,
+		scenario.Language,
+		scenario.UpdatedAt,
+		scenario.ID,
+		scenario.UserID,
+	).Scan(&scenario.UpdatedAt)
+
+	if err == pgx.ErrNoRows {
+		return fmt.Errorf("user scenario not found or no permission")
+	}
+	if err != nil {
+		log.Errorw("update user scenario failed", "scenario_id", scenario.ID, "user_id", scenario.UserID, "error", err)
+		return fmt.Errorf("update user scenario: %w", err)
+	}
+
+	log.Debugw("user scenario updated", "scenario_id", scenario.ID, "user_id", scenario.UserID)
+	return nil
+}
+
+// Delete 删除用户情景。
+func (r *PostgresUserScenarioRepo) Delete(ctx context.Context, id string) error {
+	log := trace.FromContext(ctx)
+
+	query := `DELETE FROM user_scenarios WHERE id = $1`
+
+	result, err := r.pool.Exec(ctx, query, id)
+	if err != nil {
+		log.Errorw("delete user scenario failed", "scenario_id", id, "error", err)
+		return fmt.Errorf("delete user scenario: %w", err)
+	}
+
+	if result.RowsAffected() == 0 {
+		return fmt.Errorf("user scenario not found")
+	}
+
+	log.Debugw("user scenario deleted", "scenario_id", id)
+	return nil
+}
+
+// CountByUserID 统计用户的情景数量。
+func (r *PostgresUserScenarioRepo) CountByUserID(ctx context.Context, userID string) (int, error) {
+	log := trace.FromContext(ctx)
+
+	query := `SELECT COUNT(*) FROM user_scenarios WHERE user_id = $1`
+
+	var count int
+	err := r.pool.QueryRow(ctx, query, userID).Scan(&count)
+	if err != nil {
+		log.Errorw("count user scenarios failed", "user_id", userID, "error", err)
+		return 0, fmt.Errorf("count user scenarios: %w", err)
+	}
+
+	log.Debugw("user scenarios counted", "user_id", userID, "count", count)
+	return count, nil
+}

backend/internal/trace/context.go

@@ -0,0 +1,46 @@
+package trace
+
+import "context"
+
+type traceIDKey struct{}
+type requestIDKey struct{}
+type sessionIDKey struct{}
+
+// WithTraceID 将 trace ID 注入 context（连接级/会话级标识）
+func WithTraceID(ctx context.Context, traceID string) context.Context {
+	return context.WithValue(ctx, traceIDKey{}, traceID)
+}
+
+// GetTraceID 从 context 提取 trace ID
+func GetTraceID(ctx context.Context) string {
+	if v, ok := ctx.Value(traceIDKey{}).(string); ok {
+		return v
+	}
+	return ""
+}
+
+// WithRequestID 将 request ID 注入 context（单次请求/查询标识）
+func WithRequestID(ctx context.Context, requestID string) context.Context {
+	return context.WithValue(ctx, requestIDKey{}, requestID)
+}
+
+// GetRequestID 从 context 提取 request ID
+func GetRequestID(ctx context.Context) string {
+	if v, ok := ctx.Value(requestIDKey{}).(string); ok {
+		return v
+	}
+	return ""
+}
+
+// WithSessionID 将 session ID 注入 context（会话存储标识）
+func WithSessionID(ctx context.Context, sessionID string) context.Context {
+	return context.WithValue(ctx, sessionIDKey{}, sessionID)
+}
+
+// GetSessionID 从 context 提取 session ID
+func GetSessionID(ctx context.Context) string {
+	if v, ok := ctx.Value(sessionIDKey{}).(string); ok {
+		return v
+	}
+	return ""
+}

backend/internal/trace/eino_test.go

@@ -0,0 +1,42 @@
+package trace_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/cloudwego/eino/compose"
+	"github.com/hhs/camtalk/internal/trace"
+)
+
+func TestEinoContextPropagation(t *testing.T) {
+	ctx := context.Background()
+	testTraceID := "01J5TEST123456789"
+	ctx = trace.WithTraceID(ctx, testTraceID)
+
+	var capturedTraceID string
+
+	g := compose.NewGraph[string, string]()
+	g.AddLambdaNode("test_node", compose.InvokableLambda(
+		func(ctx context.Context, input string) (string, error) {
+			capturedTraceID = trace.GetTraceID(ctx)
+			return "ok", nil
+		},
+	))
+	g.AddEdge(compose.START, "test_node")
+	g.AddEdge("test_node", compose.END)
+
+	runnable, err := g.Compile(ctx)
+	if err != nil {
+		t.Fatalf("compile failed: %v", err)
+	}
+
+	_, err = runnable.Invoke(ctx, "test_input")
+	if err != nil {
+		t.Fatalf("invoke failed: %v", err)
+	}
+
+	if capturedTraceID != testTraceID {
+		t.Errorf("trace_id lost in Eino propagation: got %q, want %q",
+			capturedTraceID, testTraceID)
+	}
+}

backend/internal/trace/gin_logger.go

@@ -0,0 +1,63 @@
+package trace
+
+import (
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+// GinLogger 记录每个 HTTP 请求的 method/path/status/latency
+func GinLogger() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		start := time.Now()
+		path := c.Request.URL.Path
+		query := c.Request.URL.RawQuery
+
+		c.Next()
+
+		latency := time.Since(start).Milliseconds()
+		status := c.Writer.Status()
+		log := FromContext(c.Request.Context())
+
+		fields := []interface{}{
+			"method", c.Request.Method,
+			"path", path,
+			"status", status,
+			"latency_ms", latency,
+			"client_ip", c.ClientIP(),
+		}
+		if query != "" {
+			fields = append(fields, "query", query)
+		}
+		if errStr := c.Errors.String(); errStr != "" {
+			fields = append(fields, "errors", errStr)
+		}
+
+		switch {
+		case status >= 500:
+			log.Errorw("request completed", fields...)
+		case status >= 400:
+			log.Warnw("request completed", fields...)
+		default:
+			log.Infow("request completed", fields...)
+		}
+	}
+}
+
+// GinRecovery 自定义 panic 恢复中间件，使用 zap 记录
+func GinRecovery() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		defer func() {
+			if err := recover(); err != nil {
+				log := FromContext(c.Request.Context())
+				log.Errorw("panic recovered",
+					"error", err,
+					"path", c.Request.URL.Path,
+					"method", c.Request.Method,
+					"client_ip", c.ClientIP())
+				c.AbortWithStatus(500)
+			}
+		}()
+		c.Next()
+	}
+}

backend/internal/trace/id.go

@@ -0,0 +1,22 @@
+package trace
+
+import (
+	cryptorand "crypto/rand"
+	"sync"
+	"time"
+
+	"github.com/oklog/ulid/v2"
+)
+
+var entropyPool = sync.Pool{
+	New: func() interface{} {
+		return ulid.Monotonic(cryptorand.Reader, 0)
+	},
+}
+
+// GenerateTraceID 生成并发安全的 ULID trace ID
+func GenerateTraceID() string {
+	entropy := entropyPool.Get().(*ulid.MonotonicEntropy)
+	defer entropyPool.Put(entropy)
+	return ulid.MustNew(ulid.Timestamp(time.Now()), entropy).String()
+}

backend/internal/trace/logger.go

@@ -0,0 +1,25 @@
+package trace
+
+import (
+	"context"
+
+	"github.com/hhs/camtalk/internal/logger"
+	"go.uber.org/zap"
+)
+
+// FromContext 返回自动附加 trace_id/request_id/session_id 的 logger
+func FromContext(ctx context.Context) *zap.SugaredLogger {
+	log := logger.Log
+
+	if traceID := GetTraceID(ctx); traceID != "" {
+		log = log.With("trace_id", traceID)
+	}
+	if requestID := GetRequestID(ctx); requestID != "" {
+		log = log.With("request_id", requestID)
+	}
+	if sessionID := GetSessionID(ctx); sessionID != "" {
+		log = log.With("session_id", sessionID)
+	}
+
+	return log
+}

backend/internal/trace/middleware.go

@@ -0,0 +1,17 @@
+package trace
+
+import "github.com/gin-gonic/gin"
+
+// TraceMiddleware 为每个 HTTP 请求生成 trace ID 并注入 context
+func TraceMiddleware() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		traceID := GenerateTraceID()
+		ctx := WithTraceID(c.Request.Context(), traceID)
+		ctx = WithRequestID(ctx, traceID) // REST: trace_id == request_id
+
+		c.Request = c.Request.WithContext(ctx)
+		c.Header("X-Trace-ID", traceID) // 返回给客户端用于排查
+
+		c.Next()
+	}
+}

backend/internal/util/string.go

@@ -0,0 +1,9 @@
+package util
+
+// Truncate 截断字符串到指定长度，超出部分用 "..." 替换
+func Truncate(s string, maxLen int) string {
+	if len(s) <= maxLen {
+		return s
+	}
+	return s[:maxLen] + "..."
+}

backend/internal/ws/handler.go

@@ -3,6 +3,7 @@ package ws
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 	"net/http"
 	"sync"
 	"time"
@@ -10,13 +11,16 @@ import (
 	"github.com/gin-gonic/gin"
 	"github.com/gorilla/websocket"
 
+	"github.com/hhs/camtalk/internal/ai/llm"
 	"github.com/hhs/camtalk/internal/auth"
 	"github.com/hhs/camtalk/internal/config"
 	"github.com/hhs/camtalk/internal/errors"
-	"github.com/hhs/camtalk/internal/logger"
 	"github.com/hhs/camtalk/internal/models"
 	"github.com/hhs/camtalk/internal/orchestrator"
+	"github.com/hhs/camtalk/internal/ratelimit"
 	"github.com/hhs/camtalk/internal/session"
+	"github.com/hhs/camtalk/internal/store"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // newUpgrader 根据配置创建 WebSocket upgrader。
@@ -40,12 +44,12 @@ func newUpgrader(cfg *config.Config) websocket.Upgrader {
 
 // Client 代表一个 WebSocket 客户端连接。
 type Client struct {
-	conn          *websocket.Conn
-	sessionID     string
-	sessionMgr    session.Manager
-	orchestrator  orchestrator.Orchestrator
-	cancelFuncs   map[string]context.CancelFunc // requestID → cancel func
-	mu            sync.Mutex
+	conn         *websocket.Conn
+	sessionID    string
+	sessionMgr   session.Manager
+	orchestrator orchestrator.Orchestrator
+	cancelFuncs  map[string]context.CancelFunc // requestID → cancel func
+	mu           sync.Mutex
 }
 
 // SendJSON 向客户端发送 JSON 消息（公开以便 errors 包调用）。
@@ -92,21 +96,19 @@ func (w *WSClient) SendError(err models.WsError) error {
 }
 
 // ServeWS 处理 WebSocket 升级请求。
-func ServeWS(sessionMgr session.Manager, orch orchestrator.Orchestrator, cfg *config.Config, tokenMgr *auth.TokenManager) gin.HandlerFunc {
+func ServeWS(sessionMgr session.Manager, orch orchestrator.Orchestrator, cfg *config.Config, tokenMgr *auth.TokenManager, limiter ratelimit.Limiter, scenarioRepo store.UserScenarioRepository) gin.HandlerFunc {
 	upgrader := newUpgrader(cfg)
 	heartbeatInterval := time.Duration(cfg.Server.HeartbeatInterval) * time.Second
 	heartbeatTimeout := time.Duration(cfg.Server.HeartbeatTimeout) * time.Second
 	version := cfg.App.Version
 
-	maxHistory := cfg.Session.MaxHistory
-
 	return func(c *gin.Context) {
-		serveWS(c, sessionMgr, orch, upgrader, heartbeatInterval, heartbeatTimeout, version, maxHistory, tokenMgr)
+		serveWS(c, sessionMgr, orch, upgrader, heartbeatInterval, heartbeatTimeout, version, tokenMgr, limiter, scenarioRepo)
 	}
 }
 
 func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orchestrator,
-	upgrader websocket.Upgrader, heartbeatInterval, heartbeatTimeout time.Duration, version string, maxHistory int, tokenMgr *auth.TokenManager) {
+	upgrader websocket.Upgrader, heartbeatInterval, heartbeatTimeout time.Duration, version string, tokenMgr *auth.TokenManager, limiter ratelimit.Limiter, scenarioRepo store.UserScenarioRepository) {
 
 	// --- JWT 认证（upgrade 前完成，失败直接返回 HTTP 错误） ---
 	token := c.Query("token")
@@ -132,9 +134,20 @@ func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orche
 		}
 	}
 
+	// 生成连接级 trace ID（整个 WebSocket 生命周期使用）
+	ctx := c.Request.Context()
+	traceID := trace.GetTraceID(ctx)
+	if traceID == "" {
+		// 如果 REST 中间件未生成（不应发生），fallback 生成
+		traceID = trace.GenerateTraceID()
+		ctx = trace.WithTraceID(ctx, traceID)
+		c.Request = c.Request.WithContext(ctx)
+	}
+
 	conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
 	if err != nil {
-		logger.Log.Errorw("websocket upgrade failed", "error", err)
+		log := trace.FromContext(ctx)
+		log.Errorw("websocket upgrade failed", "error", err)
 		return
 	}
 	defer conn.Close()
@@ -143,13 +156,17 @@ func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orche
 	var sessionID string
 	if conversationID != "" {
 		sessionID = conversationID
-		logger.Log.Infow("resuming conversation", "session", sessionID, "user_id", userID)
+		ctx = trace.WithSessionID(ctx, sessionID)
+		log := trace.FromContext(ctx)
+		log.Infow("resuming conversation", "user_id", userID)
 	} else {
 		sessionID, err = sessionMgr.Create(context.Background(), userID, models.DefaultConfig())
 		if err != nil {
-			logger.Log.Errorw("create session failed", "error", err)
+			log := trace.FromContext(ctx)
+			log.Errorw("create session failed", "error", err)
 			return
 		}
+		ctx = trace.WithSessionID(ctx, sessionID)
 	}
 
 	client := &Client{
@@ -166,7 +183,8 @@ func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orche
 		SessionID:     sessionID,
 		ServerVersion: version,
 	})
-	logger.Log.Infow("client connected", "session", sessionID, "user_id", userID, "username", username)
+	log := trace.FromContext(ctx)
+	log.Infow("client connected", "user_id", userID, "username", username)
 
 	// 心跳检测
 	lastPong := time.Now()
@@ -184,7 +202,8 @@ func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orche
 			select {
 			case <-ticker.C:
 				if time.Since(lastPong) > heartbeatTimeout {
-					logger.Log.Warnw("heartbeat timeout", "session", sessionID)
+					log := trace.FromContext(ctx)
+					log.Warnw("heartbeat timeout")
 					conn.Close()
 					return
 				}
@@ -199,7 +218,8 @@ func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orche
 		_, message, err := conn.ReadMessage()
 		if err != nil {
 			if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseNormalClosure) {
-				logger.Log.Warnw("ws read error", "error", err)
+				log := trace.FromContext(ctx)
+				log.Warnw("ws read error", "error", err)
 			}
 			break
 		}
@@ -224,23 +244,36 @@ func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orche
 				errors.SendWSError(client, errors.CodeInvalidMessage, msg.RequestID, err)
 				continue
 			}
-			logger.Log.Infow("query received", "session", sessionID, "request", msg.RequestID)
+
+			// 注入 request ID 到 context
+			queryCtx := trace.WithRequestID(ctx, msg.RequestID)
+			log := trace.FromContext(queryCtx)
+			log.Infow("query received", "has_image", msg.Image != "", "has_audio", msg.Audio != "")
+
+			// 限流检查
+			if limiter != nil {
+				key := fmt.Sprintf("%s:query", userID)
+				allowed, retryAfter := limiter.Allow(context.Background(), key)
+				if !allowed {
+					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
+				}
+			}
 
 			// 刷新会话 TTL
 			if err := client.sessionMgr.Touch(context.Background(), sessionID); err != nil {
-				logger.Log.Warnw("touch session failed", "session", sessionID, "error", err)
+				log.Warnw("touch session failed", "error", err)
 			}
 
 			// 标记活跃请求
 			if err := client.sessionMgr.SetActiveRequest(context.Background(), sessionID, msg.RequestID); err != nil {
-				logger.Log.Warnw("set active request failed", "session", sessionID, "error", err)
+				log.Warnw("set active request failed", "error", err)
 			}
 
-			// 获取对话历史
-			history, _ := client.sessionMgr.GetHistory(context.Background(), sessionID, maxHistory)
-
 			// 创建可取消的 context
-			ctx, cancel := context.WithCancel(context.Background())
+			processCtx, cancel := context.WithCancel(queryCtx)
 			client.mu.Lock()
 			client.cancelFuncs[msg.RequestID] = cancel
 			client.mu.Unlock()
@@ -260,8 +293,9 @@ func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orche
 					_ = client.sessionMgr.ClearActiveRequest(context.Background(), sessionID)
 				}()
 
-				if err := client.orchestrator.ProcessQuery(ctx, sessionID, msg, history, sender); err != nil {
-					logger.Log.Errorw("process query failed", "session", sessionID, "request", msg.RequestID, "error", err)
+				if err := client.orchestrator.ProcessQuery(processCtx, sessionID, msg, sender); err != nil {
+					log := trace.FromContext(processCtx)
+					log.Errorw("process query failed", "error", err)
 				}
 			}()
 
@@ -282,10 +316,66 @@ func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orche
 				errors.SendWSError(client, errors.CodeInternalError, "", err)
 				continue
 			}
-			logger.Log.Infow("config updated", "session", sessionID)
+
+			scenarioID := ""
+			if msg.Payload.Scenario != nil {
+				scenarioID = *msg.Payload.Scenario
+			}
+			log := trace.FromContext(ctx)
+			log.Infow("config updated", "scenario", scenarioID)
+
+			// 如果切换了情景（非自由对话），返回首句引导
+			if scenarioID != "" && scenarioID != "free_chat" {
+				sess, err := client.sessionMgr.Get(context.Background(), sessionID)
+				if err == nil && sess != nil {
+					// 加载用户自建情景
+					var customGreetings map[string]string
+					if sess.UserID != "" && scenarioRepo != nil {
+						scenarios, err := scenarioRepo.FindByUserID(context.Background(), sess.UserID)
+						if err == nil && len(scenarios) > 0 {
+							customGreetings = make(map[string]string, len(scenarios))
+							for _, s := range scenarios {
+								if s.Greeting != "" {
+									customGreetings[s.ID] = s.Greeting
+								}
+							}
+						}
+					}
+
+					greeting := llm.GetScenarioGreeting(scenarioID, sess.Config.Language, customGreetings)
+					if greeting != "" {
+						// 发送首句作为 AI 消息
+						_ = client.SendJSON(models.WsLLMChunk{
+							Type:      "llm_chunk",
+							RequestID: "scenario_greeting",
+							Delta:     greeting,
+							Role:      "assistant",
+						})
+
+						doneMsg := models.WsLLMDone{
+							Type:      "llm_done",
+							RequestID: "scenario_greeting",
+							FullText:  greeting,
+							Model:     "",
+							LatencyMs: 0,
+						}
+						doneMsg.TokensUsed.Prompt = 0
+						doneMsg.TokensUsed.Completion = 0
+						doneMsg.TokensUsed.Total = 0
+						_ = client.SendJSON(doneMsg)
+
+						// 追加首句到历史记录
+						_ = client.sessionMgr.AppendMessage(context.Background(), sessionID, models.Message{
+							Role:    "assistant",
+							Content: greeting,
+						})
+					}
+				}
+			}
 
 		case "interrupt":
-			logger.Log.Infow("interrupt received", "session", sessionID)
+			log := trace.FromContext(ctx)
+			log.Infow("interrupt received")
 
 			// 获取活跃请求 ID 并取消
 			reqID, _ := client.sessionMgr.GetActiveRequestID(context.Background(), sessionID)
@@ -313,12 +403,14 @@ func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orche
 	// 取消所有活跃请求
 	client.mu.Lock()
 	for reqID, cancel := range client.cancelFuncs {
-		logger.Log.Infow("canceling active request on disconnect", "session", sessionID, "request", reqID)
+		log := trace.FromContext(ctx)
+		log.Infow("canceling active request on disconnect", "request", reqID)
 		cancel()
 	}
 	client.cancelFuncs = make(map[string]context.CancelFunc)
 	client.mu.Unlock()
 
 	// 断开连接时不销毁会话，让其自然过期（支持重连恢复）
-	logger.Log.Infow("client disconnected", "session", sessionID)
+	log = trace.FromContext(ctx)
+	log.Infow("client disconnected")
 }

backend/internal/ws/handler_test.go

@@ -8,11 +8,11 @@ import (
 	"testing"
 	"time"
 
+	"context"
 	"github.com/gin-gonic/gin"
 	"github.com/gorilla/websocket"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"context"
 
 	"github.com/hhs/camtalk/internal/auth"
 	"github.com/hhs/camtalk/internal/config"
@@ -48,7 +48,6 @@ func (m *MockOrchestrator) ProcessQuery(
 	ctx context.Context,
 	sessionID string,
 	req models.WsQuery,
-	history []models.Message,
 	sender orchestrator.Sender,
 ) error {
 	if m.Err != nil {
@@ -149,7 +148,7 @@ func setupTestServer(t *testing.T, orch orchestrator.Orchestrator) (*httptest.Se
 		Server:  config.ServerConfig{HeartbeatInterval: 30, HeartbeatTimeout: 60},
 		Session: config.SessionConfig{MaxHistory: 20},
 	}
-	r.GET("/ws", ServeWS(sessionMgr, orch, cfg, tokenMgr))
+	r.GET("/ws", ServeWS(sessionMgr, orch, cfg, tokenMgr, nil, nil))
 
 	srv := httptest.NewServer(r)
 
@@ -222,9 +221,9 @@ func TestWS_QueryFullFlow(t *testing.T) {
 	imageB64 := base64.StdEncoding.EncodeToString([]byte("fake-image-data"))
 
 	mock := &MockOrchestrator{
-		STTResult:  "你好，世界",
-		LLMDeltas:  []string{"你好", "，世界！"},
-		TTSAudios:  []string{base64.StdEncoding.EncodeToString([]byte("mp3-data-1")), base64.StdEncoding.EncodeToString([]byte("mp3-data-2"))},
+		STTResult: "你好，世界",
+		LLMDeltas: []string{"你好", "，世界！"},
+		TTSAudios: []string{base64.StdEncoding.EncodeToString([]byte("mp3-data-1")), base64.StdEncoding.EncodeToString([]byte("mp3-data-2"))},
 	}
 
 	srv, wsURL := setupTestServer(t, mock)
@@ -333,7 +332,7 @@ func TestWS_UnknownMessageType(t *testing.T) {
 	err := conn.WriteJSON(map[string]string{"type": "unknown_type"})
 	require.NoError(t, err)
 
- errMsg := readJSON(t, conn)
+	errMsg := readJSON(t, conn)
 	assert.Equal(t, "error", errMsg["type"])
 	assert.Equal(t, "INVALID_MESSAGE", errMsg["code"])
 	assert.Contains(t, errMsg["message"], "unknown message type")
@@ -592,7 +591,7 @@ func setupTestServerEx(t *testing.T, orch orchestrator.Orchestrator) (*httptest.
 		Server:  config.ServerConfig{HeartbeatInterval: 30, HeartbeatTimeout: 60},
 		Session: config.SessionConfig{MaxHistory: 20},
 	}
-	r.GET("/ws", ServeWS(sessionMgr, orch, cfg, tokenMgr))
+	r.GET("/ws", ServeWS(sessionMgr, orch, cfg, tokenMgr, nil, nil))
 
 	srv := httptest.NewServer(r)
 	return srv, tokenMgr, sessionMgr
@@ -643,7 +642,7 @@ func TestWS_AuthExpiredToken(t *testing.T) {
 		Server:  config.ServerConfig{HeartbeatInterval: 30, HeartbeatTimeout: 60},
 		Session: config.SessionConfig{MaxHistory: 20},
 	}
-	r.GET("/ws", ServeWS(sessionMgr, &MockOrchestrator{}, cfg, tokenMgr))
+	r.GET("/ws", ServeWS(sessionMgr, &MockOrchestrator{}, cfg, tokenMgr, nil, nil))
 	srv := httptest.NewServer(r)
 	defer srv.Close()
 

backend/migrations/001_users.up.sql

@@ -10,6 +10,14 @@ CREATE TABLE IF NOT EXISTS users (
 -- 用户名索引（用于登录查询）
 CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
 
+-- 表和列注释
+COMMENT ON TABLE users IS '用户表，存储系统所有注册用户的基本信息';
+COMMENT ON COLUMN users.id IS '用户唯一标识符 (UUID)';
+COMMENT ON COLUMN users.username IS '用户名，最大 64 字符，全局唯一';
+COMMENT ON COLUMN users.password_hash IS '密码哈希值，使用 bcrypt 算法（cost=10）';
+COMMENT ON COLUMN users.created_at IS '用户注册时间';
+COMMENT ON COLUMN users.updated_at IS '用户信息最后更新时间';
+
 -- Refresh Token 表
 CREATE TABLE IF NOT EXISTS refresh_tokens (
     id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -24,3 +32,11 @@ CREATE INDEX IF NOT EXISTS idx_refresh_tokens_token_hash ON refresh_tokens(token
 
 -- 用户 ID 索引（用于登出所有设备）
 CREATE INDEX IF NOT EXISTS idx_refresh_tokens_user_id ON refresh_tokens(user_id);
+
+-- 表和列注释
+COMMENT ON TABLE refresh_tokens IS 'Refresh Token 表，用于 JWT 双 token 机制的长期身份验证';
+COMMENT ON COLUMN refresh_tokens.id IS 'Token 唯一标识符 (UUID)';
+COMMENT ON COLUMN refresh_tokens.user_id IS '所属用户 ID，外键关联 users 表，用户删除时级联删除';
+COMMENT ON COLUMN refresh_tokens.token_hash IS 'Token 哈希值，使用 SHA-256 算法，十六进制编码 (64 字符)';
+COMMENT ON COLUMN refresh_tokens.expires_at IS 'Token 过期时间，默认有效期 7 天';
+COMMENT ON COLUMN refresh_tokens.created_at IS 'Token 创建时间';

backend/migrations/002_messages.up.sql

@@ -2,10 +2,12 @@
 CREATE TABLE IF NOT EXISTS messages (
     id          BIGSERIAL PRIMARY KEY,
     session_id  UUID NOT NULL,
-    role        VARCHAR(16) NOT NULL,  -- "user" | "assistant" | "system"
+    role        VARCHAR(10) NOT NULL,
     content     TEXT NOT NULL,
     tokens_used INTEGER NOT NULL DEFAULT 0,
-    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT check_tokens_non_negative CHECK (tokens_used >= 0)
 );
 
 -- 按会话查询消息（分页核心索引）
@@ -15,3 +17,12 @@ CREATE INDEX IF NOT EXISTS idx_messages_session_id_created_at
 -- 按会话查询最后一条消息
 CREATE INDEX IF NOT EXISTS idx_messages_session_id_id_desc
     ON messages(session_id, id DESC);
+
+-- 表和列注释
+COMMENT ON TABLE messages IS '消息表，存储所有会话的消息记录';
+COMMENT ON COLUMN messages.id IS '消息唯一标识符，自增序列';
+COMMENT ON COLUMN messages.session_id IS '所属会话 ID，关联 sessions 表';
+COMMENT ON COLUMN messages.role IS '消息角色，可选值: ''user'' (用户), ''assistant'' (AI 助手), ''system'' (系统)';
+COMMENT ON COLUMN messages.content IS '消息内容，无长度限制';
+COMMENT ON COLUMN messages.tokens_used IS '消息消耗的 token 数量，用于计费统计';
+COMMENT ON COLUMN messages.created_at IS '消息创建时间';

backend/migrations/003_sessions.up.sql

@@ -1,11 +1,22 @@
 CREATE TABLE IF NOT EXISTS sessions (
     id           UUID PRIMARY KEY,
     user_id      UUID NOT NULL,
-    title        VARCHAR(256) NOT NULL DEFAULT '新对话',
+    title        VARCHAR(100) NOT NULL DEFAULT '新对话',
     config       JSONB NOT NULL DEFAULT '{}',
     created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT check_title_length CHECK (char_length(title) >= 1 AND char_length(title) <= 100)
 );
 
 CREATE INDEX IF NOT EXISTS idx_sessions_user_id ON sessions (user_id);
 CREATE INDEX IF NOT EXISTS idx_sessions_user_updated ON sessions (user_id, updated_at DESC);
+
+-- 表和列注释
+COMMENT ON TABLE sessions IS '会话表，存储用户的对话会话信息';
+COMMENT ON COLUMN sessions.id IS '会话唯一标识符 (UUID)';
+COMMENT ON COLUMN sessions.user_id IS '所属用户 ID，关联 users 表';
+COMMENT ON COLUMN sessions.title IS '会话标题，默认为"新对话"，长度 1-100 字符';
+COMMENT ON COLUMN sessions.config IS '会话配置 (JSONB)，包含: tts_enabled (布尔), detail_level (''low''/''high''), language (语言代码), scenario (情景 ID)';
+COMMENT ON COLUMN sessions.created_at IS '会话创建时间';
+COMMENT ON COLUMN sessions.updated_at IS '会话最后更新时间';

backend/migrations/004_user_scenarios.down.sql

@@ -0,0 +1,6 @@
+-- 004_user_scenarios.down.sql
+-- 回滚用户自建情景表
+
+DROP INDEX IF EXISTS idx_user_scenarios_created_at;
+DROP INDEX IF EXISTS idx_user_scenarios_user_id;
+DROP TABLE IF EXISTS user_scenarios;

backend/migrations/004_user_scenarios.up.sql

@@ -0,0 +1,40 @@
+-- 004_user_scenarios.up.sql
+-- 用户自建情景表
+
+CREATE TABLE user_scenarios (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    name VARCHAR(50) NOT NULL,
+    icon VARCHAR(20) DEFAULT '✨',
+    description VARCHAR(100),
+    prompt TEXT NOT NULL,
+    greeting VARCHAR(500),
+    language VARCHAR(10) DEFAULT 'zh-CN',
+    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT unique_user_scenario UNIQUE(user_id, name),
+    CONSTRAINT check_name_length CHECK (char_length(name) >= 2 AND char_length(name) <= 50),
+    CONSTRAINT check_description_length CHECK (description IS NULL OR char_length(description) <= 100),
+    CONSTRAINT check_prompt_length CHECK (char_length(prompt) >= 10),
+    CONSTRAINT check_greeting_length CHECK (greeting IS NULL OR char_length(greeting) <= 500)
+);
+
+-- 为用户 ID 创建索引，加速查询
+CREATE INDEX idx_user_scenarios_user_id ON user_scenarios(user_id);
+
+-- 为创建时间创建索引，用于排序
+CREATE INDEX idx_user_scenarios_created_at ON user_scenarios(created_at DESC);
+
+-- 表和列注释
+COMMENT ON TABLE user_scenarios IS '用户自建情景表，存储用户创建的 AI 对话情景配置';
+COMMENT ON COLUMN user_scenarios.id IS '情景唯一标识符 (UUID)';
+COMMENT ON COLUMN user_scenarios.user_id IS '所属用户 ID，外键关联 users 表，用户删除时级联删除';
+COMMENT ON COLUMN user_scenarios.name IS '情景名称 (2-50 字符)，如"创意写作导师"';
+COMMENT ON COLUMN user_scenarios.icon IS 'Emoji 图标 (最多 20 字符)，支持复合 Emoji，如"🎨"';
+COMMENT ON COLUMN user_scenarios.description IS '简短描述 (最多 100 字符)，可选，显示在情景卡片上';
+COMMENT ON COLUMN user_scenarios.prompt IS '角色 System Prompt (最少 10 字符，无上限)，定义 AI 行为和对话风格';
+COMMENT ON COLUMN user_scenarios.greeting IS '首句引导 (最多 500 字符)，可选，AI 的开场白';
+COMMENT ON COLUMN user_scenarios.language IS '默认语言代码 (如 zh-CN、en-US、ja-JP)';
+COMMENT ON COLUMN user_scenarios.created_at IS '情景创建时间';
+COMMENT ON COLUMN user_scenarios.updated_at IS '情景最后更新时间';

deploy.sh

@@ -4,7 +4,7 @@ set -euo pipefail
 PROJECT_DIR="$(cd "$(dirname "$0")" && pwd)"
 cd "$PROJECT_DIR"
 
-# .env 固定路径（独立于项目目录，保证持久性）
+# .env 固定路径（act_runner 容器已挂载 /opt/camtalk）
 ENV_FILE="/opt/camtalk/.env"
 
 # 颜色输出
@@ -15,18 +15,13 @@ info()  { echo -e "${GREEN}[INFO]${NC} $*"; }
 
 # .env 检查：首次部署时从 .env.example 复制模板，提示用户填写
 check_env() {
-  local env_example="$PROJECT_DIR/backend/.env.example"
   if [ ! -f "$ENV_FILE" ]; then
-    mkdir -p "$(dirname "$ENV_FILE")"
-    if [ -f "$env_example" ]; then
-      cp "$env_example" "$ENV_FILE"
-      info "未找到 $ENV_FILE，已从 .env.example 复制模板"
-      echo "    请编辑 $ENV_FILE 填入实际配置后重新运行本脚本"
-      exit 0
-    else
-      echo "错误: $ENV_FILE 和 .env.example 均不存在，请手动创建"
-      exit 1
-    fi
+    echo "=============================================="
+    echo " 错误: 未找到环境变量文件"
+    echo " 路径: $ENV_FILE"
+    echo " 模板参考: backend/.env.example"
+    echo "=============================================="
+    exit 1
   fi
 }
 
@@ -98,4 +93,4 @@ case "${1:-}" in
   logs)    shift; cmd_logs "$@" ;;
   status)  cmd_status ;;
   *)       usage; exit 1 ;;
-esac
+esac

docker-compose.yml

@@ -20,6 +20,8 @@ services:
     env_file:
       - /opt/camtalk/.env
     environment:
+      # 运行环境（强制生产环境）
+      - APP_ENV=prod
       # 三级存储配置（敏感信息通过 env_file 注入）
       - CAMTALK_STORAGE_REDIS_ENABLED=${CAMTALK_STORAGE_REDIS_ENABLED:-true}
       - CAMTALK_STORAGE_PERSISTENCE_ENABLED=${CAMTALK_STORAGE_PERSISTENCE_ENABLED:-true}

docs/01-架构设计.md

@@ -199,35 +199,70 @@ graph LR
 | 模块 | 职责 |
 |------|------|
 | WebSocket Handler | 管理客户端连接生命周期，JWT 认证，conversation_id 恢复，单播消息推送 |
-| Session Manager | 维护用户会话状态、对话历史。Memory（默认）/ Redis（可切换），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 | 令牌桶限流（待实现） |
+| Rate Limiter | 令牌桶限流，详见 [11-令牌桶限流.md](./11-令牌桶限流.md) |
 
 ## 前端组件
 
 | 组件 | 职责 |
 |------|------|
-| AuthPage | 登录/注册表单 |
+| 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、消息状态、认证、场景模式）。
+核心 Hook：`useVisionSession()` 封装完整的视觉对话会话（摄像头、VAD、WebSocket、消息状态、认证、场景模式）。`useSessionList()` 通过 REST API 管理对话列表 CRUD。
+
+### 前端会话状态模型（三态）
+
+前端 UI 存在三个会话状态，由 `isConnected` 和 `isCameraOn` 联合决定：
+
+```
+┌──────────┐    startSession()    ┌──────────┐
+│  initial  │ ──────────────────→ │  video   │
+│  初始态    │                     │  视频通话  │
+└──────────┘                      └──────────┘
+      ↑                                │
+      │ stopSession()            stopVideo()
+      │                                │
+      │                                ▼
+      │                         ┌──────────┐
+      └──────────────────────── │ textOnly │
+                                │ 文字对话  │
+                                └──────────┘
+                                      │
+                                startSession()
+                                      │
+                                      ▼
+                                ┌──────────┐
+                                │  video   │
+                                └──────────┘
+```
+
+| 状态 | 条件 | WebSocket | 摄像头 | 消息 | 文字输入 |
+|------|------|-----------|--------|------|---------|
+| `initial` | `!isConnected && messages.length === 0` | 断开 | 关闭 | 空 | 可用（自动连接） |
+| `video` | `isConnected && isCameraOn` | 连接 | 开启 | 有 | 可用 |
+| `textOnly` | `isConnected && !isCameraOn` | 连接 | 关闭 | 保留 | 可用 |
+
+- **`stopVideo()`**：停止摄像头/麦克风/VAD，保持 WebSocket 连接和消息历史，用户可继续文字对话
+- **`stopSession()`**：完全断开 WebSocket、清空消息、重置状态，回到初始态
 
 ## 数据库设计
 
@@ -274,139 +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）或完整三级存储方案。
 
 ## 认证设计
 
-```mermaid
-sequenceDiagram
-    participant C as 客户端
-    participant G as Go 网关
-    participant DB as PostgreSQL
+系统采用 **JWT 双 token 轮转认证机制**，结合 bcrypt 密码哈希和 Refresh Token Rotation 安全策略。
 
-    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 分钟有效，refresh_token 7 天有效。refresh 时旧 token 失效（轮转），防止重放攻击。
-
-**WebSocket 认证**：连接地址 `ws://host/ws?token=<access_token>&conversation_id=<uuid>`。HTTP Upgrade 前校验 token，失败返回 401。
+核心机制包括：双 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

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 |
 
 ### 总览
 

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 兼容接口。
 
 ## 策略四：缓存与复用（待实现）
 

docs/08-Eino框架与编排设计.md

@@ -0,0 +1,523 @@
+# CamTalk Eino 框架与编排设计
+
+## 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)
+```

docs/08-功能创意.md

@@ -1,5 +0,0 @@
-1.视频录制
-2.对话翻译
-3.对话总结
-4.手动对话功能
-5.视频框大小可调整，可最小化然后拖动

docs/09-情景切换.md

@@ -0,0 +1,348 @@
+# 情景切换功能
+
+## 功能概述
+
+情景切换功能允许用户选择不同的对话场景，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` — 日文翻译

docs/09-技术名词解释.md

@@ -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 用量）。 |

docs/10-Eino重构方案.md

@@ -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)
-```

docs/11-Eino框架技术文档.md

@@ -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 为完整值（流式 → 非流式）
-
-这使得不同流式模式的节点可以无缝连接。

docs/11-令牌桶限流.md

@@ -0,0 +1,814 @@
+# 令牌桶限流设计
+
+## 概述
+
+CamTalk 采用令牌桶（Token Bucket）算法实现按用户维度的速率限制，核心目标是**控制 AI 调用成本**，同时为 REST API 提供防暴力破解保护。
+
+**设计原则**：
+- **成本优先**：主要限流对象是 WebSocket `query` 消息（每次触发 STT + LLM + TTS 完整调用链）
+- **用户隔离**：Per-user 维度限流，单用户超限不影响其他用户
+- **弹性突发**：令牌桶允许合理的突发请求，优于固定窗口的滑动限流
+- **存储适配**：内存 + Redis 双实现，单实例零依赖，多实例分布式一致
+
+## 整体架构
+
+```mermaid
+graph TB
+    subgraph Entry["入口层"]
+        WS["WebSocket Handler<br/>query 消息"]
+        REST["REST API<br/>login / register"]
+    end
+
+    subgraph LimiterModule["Rate Limiter 模块"]
+        Interface["Limiter 接口<br/>Allow(userID) → (bool, retryAfter)"]
+        MemBucket["TokenBucket<br/>内存令牌桶"]
+        RedisBucket["RedisTokenBucket<br/>Redis 令牌桶（Lua 脚本）"]
+        Middleware["RateLimitMiddleware<br/>Gin 中间件"]
+    end
+
+    subgraph Storage["存储层"]
+        MemSync["sync.RWMutex<br/>进程内 map"]
+        Redis["Redis<br/>分布式计数"]
+    end
+
+    WS -->|"限流检查"| Interface
+    REST -->|"中间件"| Middleware
+    Middleware --> Interface
+    Interface --> MemBucket
+    Interface --> RedisBucket
+    MemBucket --> MemSync
+    RedisBucket --> Redis
+```
+
+## 令牌桶算法
+
+### 原理
+
+令牌桶以固定速率向桶中添加令牌，桶有最大容量上限。每次请求消耗一个令牌，桶空时拒绝请求。
+
+```
+桶容量(capacity) = 允许的突发请求数上限
+填充速率(rate)   = 每秒补充的令牌数
+
+时间线示例（capacity=5, rate=0.2）：
+  t=0s   桶满 5 令牌 → 用户连续发 5 个 query 全部通过
+  t=0s   桶空 → 第 6 个 query 被拒绝，retryAfter=5s
+  t=5s   桶补充 1 令牌 → 可再发 1 个 query
+  t=10s  桶补充 1 令牌 → 可再发 1 个 query
+```
+
+### 算法公式
+
+```
+elapsed = now - lastRefill
+newTokens = elapsed * rate
+currentTokens = min(capacity, lastTokens + newTokens)
+
+if currentTokens >= 1:
+    currentTokens -= 1
+    allowed = true
+else:
+    allowed = false
+    retryAfter = (1 - currentTokens) / rate
+```
+
+## 核心组件
+
+### 1. Limiter 接口
+
+**文件位置**：`backend/internal/ratelimit/limiter.go`
+
+```go
+// Limiter 速率限制器接口。
+type Limiter interface {
+    // Allow 判断 key 是否允许执行一次操作。
+    // key 通常为 "userID:action" 格式。
+    // 返回 (allowed, retryAfter)。retryAfter 表示需要等待的时间。
+    Allow(ctx context.Context, key string) (bool, time.Duration)
+}
+```
+
+**设计要点**：
+- key 为字符串，不限定格式，由调用方决定维度（用户 ID、IP 地址等）
+- 返回 `retryAfter` 供客户端/服务端设置 `Retry-After` header
+- 接受 `context.Context` 支持超时和取消（Redis 实现需要）
+
+### 2. 内存令牌桶（TokenBucket）
+
+**文件位置**：`backend/internal/ratelimit/bucket.go`
+
+```go
+// TokenBucket 内存令牌桶，适用于单实例部署。
+type TokenBucket struct {
+    capacity   int           // 桶容量
+    rate       float64       // 每秒填充令牌数
+    tokens     float64       // 当前令牌数
+    lastRefill time.Time     // 上次填充时间
+    mu         sync.Mutex
+}
+
+// Limiter 管理多个用户的令牌桶。
+type Limiter struct {
+    buckets  map[string]*TokenBucket
+    config   Config
+    mu       sync.RWMutex
+    stopOnce sync.Once
+    done     chan struct{}
+}
+```
+
+**并发安全**：
+- 每个桶内部用 `sync.Mutex` 保护读写
+- 桶 map 用 `sync.RWMutex` 保护（读多写少场景）
+- 用户首次请求时惰性创建桶
+
+**内存回收**：
+- 后台 goroutine 定期扫描，清理超过 10 分钟无活动的桶
+- 避免长期运行后内存泄漏
+
+### 3. Redis 令牌桶（RedisTokenBucket）
+
+**文件位置**：`backend/internal/ratelimit/redis_bucket.go`
+
+使用 Redis Lua 脚本保证原子性，避免竞态条件：
+
+```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
+    retry_after = (1 - tokens) / rate
+end
+
+-- 回写状态
+redis.call('HMSET', key, 'tokens', tokens, 'last_refill', now)
+redis.call('EXPIRE', key, ttl)
+
+return {allowed, tostring(retry_after)}
+```
+
+**设计要点**：
+- 每个用户的限流状态存储为一个 Redis Hash（`tokens` + `last_refill`）
+- TTL 自动过期，无需手动清理
+- Lua 脚本保证"读取-计算-回写"原子执行
+
+### 4. Gin 中间件
+
+**文件位置**：`backend/internal/ratelimit/middleware.go`
+
+```go
+// RateLimitMiddleware 返回 Gin 中间件，按 key 维度限流。
+// keyFunc 从请求中提取限流 key（如 IP、用户 ID）。
+func RateLimitMiddleware(limiter Limiter, keyFunc func(*gin.Context) string) gin.HandlerFunc
+```
+
+**使用方式**：
+
+```go
+// 按 IP 限流（登录/注册，未登录用户无 userID）
+loginGroup.POST("/login",
+    ratelimit.Middleware(limiter, func(c *gin.Context) string {
+        return c.ClientIP() + ":login"
+    }),
+    authHandler.Login,
+)
+
+// 按用户 ID 限流（已认证的 API）
+authorized.POST("/conversations",
+    ratelimit.Middleware(limiter, func(c *gin.Context) string {
+        return c.GetString("user_id") + ":conversation"
+    }),
+    convHandler.Create,
+)
+```
+
+**错误响应**：
+
+REST API 返回 HTTP 429：
+
+```json
+{
+    "code": "RATE_LIMITED",
+    "message": "too many requests, retry after 5s"
+}
+```
+
+同时设置 `Retry-After` header：
+
+```
+HTTP/1.1 429 Too Many Requests
+Retry-After: 5
+```
+
+## 限流接入点
+
+### WebSocket query 消息（核心）
+
+在 `ws/handler.go` 的 `case "query"` 分支中，orchestrator 调用前检查：
+
+```go
+case "query":
+    // ... 解析消息 ...
+
+    // 限流检查
+    if limiter != nil {
+        allowed, retryAfter := limiter.Allow(ctx, userID+":query")
+        if !allowed {
+            errors.SendWSError(client, errors.CodeRateLimited, msg.RequestID,
+                fmt.Errorf("rate limited, retry after %s", retryAfter))
+            continue
+        }
+    }
+
+    // ... 继续处理 query ...
+```
+
+### REST API 登录/注册
+
+在 `api/auth.go` 的路由注册中添加中间件：
+
+```go
+func (h *AuthHandler) RegisterRoutes(rg *gin.RouterGroup, limiter ratelimit.Limiter) {
+    auth := rg.Group("/auth")
+    if limiter != nil {
+        auth.POST("/register",
+            ratelimit.Middleware(limiter, ipKeyFunc("register")),
+            h.Register,
+        )
+        auth.POST("/login",
+            ratelimit.Middleware(limiter, ipKeyFunc("login")),
+            h.Login,
+        )
+    } else {
+        auth.POST("/register", h.Register)
+        auth.POST("/login", h.Login)
+    }
+    auth.POST("/refresh", h.Refresh)
+    auth.POST("/logout", h.Logout)
+}
+```
+
+### 不限流的端点
+
+| 端点 | 原因 |
+|------|------|
+| `ping` / `pong` | 心跳保活，无 AI 调用成本 |
+| `config` | 配置更新，无 AI 调用成本 |
+| `interrupt` | 中断请求，取消操作不应被限流 |
+| `GET /api/health` | 健康检查，运维必需 |
+| `POST /api/auth/refresh` | Token 刷新，限流会导致用户被迫重新登录 |
+| `POST /api/auth/logout` | 登出，限流会导致用户无法正常退出 |
+| `GET /api/conversations` | 查询列表，无 AI 调用成本 |
+
+## 配置设计
+
+### 配置文件
+
+```yaml
+# backend/config/config.yaml 新增
+ratelimit:
+  enabled: true
+  # 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 次
+```
+
+### 配置结构体
+
+```go
+// config/config.go 新增
+
+type RateLimitConfig struct {
+    Enabled  bool          `mapstructure:"enabled"`
+    Query    BucketConfig  `mapstructure:"query"`
+    Login    BucketConfig  `mapstructure:"login"`
+    Register BucketConfig  `mapstructure:"register"`
+}
+
+type BucketConfig struct {
+    Capacity int     `mapstructure:"capacity"` // 桶容量（突发上限）
+    Rate     float64 `mapstructure:"rate"`     // 每秒填充令牌数
+}
+```
+
+### 默认值
+
+```go
+// setDefaults 新增
+v.SetDefault("ratelimit.enabled", false)
+v.SetDefault("ratelimit.query.capacity", 10)
+v.SetDefault("ratelimit.query.rate", 0.2)
+v.SetDefault("ratelimit.login.capacity", 5)
+v.SetDefault("ratelimit.login.rate", 0.1)
+v.SetDefault("ratelimit.register.capacity", 3)
+v.SetDefault("ratelimit.register.rate", 0.05)
+```
+
+### 参数选择建议
+
+| 场景 | capacity | rate | 含义 |
+|------|----------|------|------|
+| WebSocket query | 10 | 0.2 | 突发 10 个，之后每 5 秒 1 个 |
+| 登录 | 5 | 0.1 | 突发 5 次，之后每 10 秒 1 次 |
+| 注册 | 3 | 0.05 | 突发 3 次，之后每 20 秒 1 次 |
+
+> **调参原则**：capacity 决定"能忍多少次突发"，rate 决定"稳态下多久能再请求一次"。query 的 rate 建议根据 AI 调用成本和目标月预算反推。
+
+## 依赖注入
+
+### main.go 初始化
+
+```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()
+}
+```
+
+### 注入到各模块
+
+```go
+// WebSocket Handler —— 新增 limiter 参数
+r.GET("/ws", ws.ServeWS(sessionMgr, orch, cfg, tokenMgr, limiter))
+
+// Auth REST —— 新增 limiter 参数
+authHandler := api.NewAuthHandler(authService, tokenMgr)
+authHandler.RegisterRoutes(apiGroup, limiter)
+```
+
+## 错误码
+
+复用已有错误码 `RATE_LIMITED`（`backend/internal/errors/codes.go`）：
+
+| 传输层 | HTTP 状态码 | 错误格式 |
+|--------|-----------|---------|
+| REST API | 429 Too Many Requests | `{code: "RATE_LIMITED", message: "too many requests, retry after Xs"}` |
+| WebSocket | — | `{type: "error", code: "RATE_LIMITED", request_id: "...", message: "..."}` |
+
+## 文件结构
+
+```
+backend/internal/ratelimit/
+├── limiter.go          # Limiter 接口 + Config 类型定义
+├── bucket.go           # 内存令牌桶实现
+├── bucket_test.go      # 内存令牌桶单元测试
+├── redis_bucket.go     # Redis 令牌桶实现（Lua 脚本）
+├── redis_bucket_test.go# Redis 令牌桶单元测试
+└── middleware.go        # Gin 中间件
+```
+
+## 测试用例
+
+### 单元测试
+
+**内存令牌桶**（`bucket_test.go`）：
+- 首次请求通过
+- 连续消耗至桶空
+- 桶空后拒绝，返回正确 retryAfter
+- 等待后令牌补充，请求通过
+- 并发安全性（多个 goroutine 同时 Allow）
+- 桶容量边界（capacity=0, capacity=1）
+- 填充速率边界（rate=0, rate 极大值）
+- 不活跃桶的内存回收
+
+**Redis 令牌桶**（`redis_bucket_test.go`）：
+- 与内存实现行为一致性
+- Lua 脚本原子性
+- key TTL 自动过期
+- 并发安全性（多个客户端同时请求）
+
+### 集成测试
+
+- 限流关闭时不拦截请求
+- 限流开启后，REST API 登录超限返回 429
+- 限流开启后，WebSocket query 超限返回 `RATE_LIMITED` 错误
+- 单实例内存限流 vs 多实例 Redis 限流行为一致
+- 重启后内存限流重置，Redis 限流保持
+
+## 扩展点
+
+### 1. 多级限流
+
+可扩展为多级限流策略：
+
+```
+全局限流（全用户共享） → 用户级限流（当前实现） → 端点级限流（不同 API 不同限制）
+```
+
+### 2. 动态调参
+
+通过配置热更新或管理 API 动态调整限流参数，无需重启：
+
+```go
+// 预留接口
+type DynamicLimiter interface {
+    Limiter
+    UpdateConfig(action string, cfg BucketConfig) error
+}
+```
+
+### 3. 按用户等级差异化
+
+不同用户等级使用不同的限流参数：
+
+```yaml
+ratelimit:
+  query:
+    capacity: 10    # 免费用户
+    rate: 0.2
+  query_premium:
+    capacity: 30    # 付费用户
+    rate: 1.0
+```
+
+### 4. 滑动窗口限流
+
+令牌桶适合允许突发的场景。如果需要更平滑的限流，可增加滑动窗口实现：
+
+```go
+type SlidingWindowLimiter struct {
+    windowSize time.Duration
+    maxRequests int
+}
+```
+
+### 5. 分布式全局限流
+
+当前 Redis 实现是 Per-Instance 独立计数。如需全局精确限流，可改为 Redis 全局计数器（所有实例共享同一个 key）。
+
+## 监控指标
+
+### 关键指标
+
+- **限流触发率**：被拒绝请求数 / 总请求数
+- **各端点限流分布**：query / login / register 各自的触发率
+- **等待时长分布**：retryAfter 的 P50/P99
+- **桶状态**：各用户桶的平均令牌数（反映使用模式）
+
+### 告警规则
+
+- **限流触发率突增**：可能表示异常流量或攻击
+- **单用户持续被限流**：可能表示客户端 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(ctx, key)
+        if !allowed {
+            // 限流触发时自动记录 Warn 日志（在 limiter 内部使用 trace.FromContext）
+            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` 错误到客户端
+- 限流触发时 `RedisLimiter.Allow` 内部自动记录 Warn 日志（带 trace_id，详见 `docs/13-日志追踪.md`）
+- 不阻塞其他消息类型（`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)
+- [Redis Rate Limiting](https://redis.io/glossaries/rate-limiting/)
+- [Cloudflare - How we built rate limiting capable of scaling to millions of domains](https://blog.cloudflare.com/counting-things-a-lot-of-different-things/)

docs/12-Eino重构实施记录.md

@@ -1,204 +0,0 @@
-# CamTalk Eino 重构实施记录
-
-> 创建日期：2026-06-19
-> 状态：已完成
-
-## 1. 重构背景
-
-CamTalk 原 AI 编排层（`internal/orchestrator/pipeline.go`）使用手写 goroutine + WaitGroup + channel 实现 STT → LLM → TTS 流式管道，存在以下问题：
-
-1. **编排逻辑硬编码**：流程写死在 `ProcessQuery()` 中，扩展需重写 goroutine 调度
-2. **并发控制粗糙**：手动 `go func()` + `sync.WaitGroup`，缺乏结构化流式传递
-3. **无回调/AOP 机制**：日志、指标、追踪散落各处
-4. **配置耦合**：模型名、TTS 参数硬编码在 Pipeline 结构体
-5. **错误处理不一致**：TTS 错误被静默吞掉，缺乏统一模式
-
-**重构目标**：使用 Eino Graph 替换手写 Pipeline，实现声明式编排、统一回调、按请求动态配置，保持 WebSocket 协议和 REST API 不变。
-
-## 2. 整体架构变更
-
-### 2.1 重构前
-
-```
-WS Handler → Orchestrator.Pipeline.ProcessQuery()
-              ├→ goroutine: STT.Recognize()
-              ├→ goroutine: LLM.ChatStream() ──→ chan chunk ──→ Sender
-              └→ goroutine: Splitter → TTS.SynthesizeStream() ──→ chan audio ──→ Sender
-              WaitGroup.Wait()
-              Sender.SendLLMDone()
-```
-
-### 2.2 重构后
-
-```
-WS Handler → EinoOrchestrator.ProcessQuery()
-              ├→ Graph.Stream(ctx, input)
-              │   ├→ STT Lambda ─→ History Lambda ─→ ChatModel ─→ Splitter ─→ TTS ─→ Done
-              │   │                  (State 写入)    (Callback    (Transform)  (Invoke)  (Invoke)
-              │   │                                    流式推送)
-              │   └→ 消费 StreamReader（触发整条链路惰性执行）
-              └→ 追加助手消息到历史
-```
-
-### 2.3 关键设计决策
-
-| 决策 | 选择 | 理由 |
-|------|------|------|
-| Graph 调用模式 | Stream | ChatModel 需要真正的 token 级流式输出 |
-| LLM 组件 | eino-ext ChatModel | 原生 Eino 组件，直接对接 DashScope |
-| 消息推送 | Callback（LLM）+ Sender（其他） | LLM token 流式推送需要 Callback |
-| 值类型 vs 指针 | 值类型统一 | 避免框架类型转换不匹配 |
-| 历史追加 | 适配器负责 | Done 节点只负责发送 llm_done |
-
-## 3. 分阶段实施
-
-### Phase 1：基础设施（提交 `fd5c771`）
-
-**目标**：引入 Eino 依赖，创建基础类型和 Callback。
-
-**任务清单**：
-
-| 任务 | 文件 | 说明 |
-|------|------|------|
-| 引入 Eino 依赖 | `go.mod` | `eino v0.9.9` + `eino-ext/components/model/openai v0.1.13` |
-| 数据类型定义 | `eino/types.go` | `PipelineInput`、`PipelineOutput`、`STTOutput`、`TokenUsage` |
-| State 定义 | `eino/state.go` | `PipelineState` 含 `sync.Mutex` 并发保护 |
-| 消息推送 Callback | `eino/callback.go` | `BuildCallbackHandler()` 使用 `callbacks.NewHandlerHelper()` |
-
-**关键实现**：
-- `PipelineState` 使用 `strings.Builder` + `sync.Mutex` 累积 LLM 完整回复
-- Callback 通过 `ModelCallbackHandler.OnEndWithStreamOutput` 逐 token 推送 `llm_chunk`
-- Sender/RequestID/PipelineState 通过 `context.WithValue` 注入
-
-**验证**：`go build ./cmd/server` ✓
-
----
-
-### Phase 2：节点实现（提交 `fd5c771`）
-
-**目标**：实现 Graph 中的 5 个 Lambda 节点。
-
-**任务清单**：
-
-| 任务 | 文件 | Lambda 类型 | 输入 → 输出 |
-|------|------|------------|------------|
-| STT Lambda | `eino/nodes_stt.go` | InvokableLambda | `PipelineInput → STTOutput` |
-| 历史组装 Lambda | `eino/nodes_history.go` | InvokableLambda | `STTOutput → []*schema.Message` |
-| 句子分割 Lambda | `eino/nodes_splitter.go` | TransformableLambda | `StreamReader[string] → StreamReader[[]string]` |
-| TTS Lambda | `eino/nodes_tts.go` | InvokableLambda | `[]string → struct{}` |
-| Done Lambda | `eino/nodes_done.go` | InvokableLambda | `struct{} → PipelineOutput` |
-
-**关键实现**：
-- STT 节点将输入元数据写入 State，供下游节点读取
-- History 节点从 State 读取 SessionID/Scenario/ImageData，构建系统提示词 + 多模态消息
-- Splitter 使用 `TransformableLambda` 按句子分隔符切分，逐句输出给 TTS
-- TTS 节点调用 `ttsService.SynthesizeStream()`，逐 chunk 推送 `tts_audio`
-- Done 节点从 State 读取完整回复，发送 `llm_done`
-- 所有 Lambda 使用值类型（非指针），返回 `*compose.Lambda`
-
-**验证**：`go build ./internal/eino/...` ✓
-
----
-
-### Phase 3：Graph 构建与适配器（提交 `4b731b5`）
-
-**目标**：构建 Graph、实现适配器、切换 main.go。
-
-**任务清单**：
-
-| 任务 | 文件 | 说明 |
-|------|------|------|
-| Graph 构建 | `eino/graph.go` | `NewPipelineGraph()` 组装 6 个节点 + 边 + 编译 |
-| 适配器 | `eino/adapter.go` | `EinoOrchestrator` 实现 `orchestrator.Orchestrator` 接口 |
-| main.go 切换 | `cmd/server/main.go` | 移除旧 LLM + orchestrator，替换为 Eino |
-
-**Graph 拓扑**：
-```
-START → STT → History → ChatModel → Splitter → TTS → Done → END
-```
-
-**适配器职责**：
-1. 解码 base64 音频/图片
-2. 获取会话配置
-3. 注入 Sender/RequestID/SessionID/StartTime/State 到 context
-4. 追加用户消息到历史
-5. 调用 `graph.Stream(ctx, input, callbacks)` 触发惰性执行
-6. 消费 `StreamReader[PipelineOutput]`
-7. 追加助手消息到历史
-
-**关键实现**：
-- eino-ext ChatModel 配置：`BaseURL` 对接 DashScope，`Timeout` 控制请求超时
-- Callback 在运行时通过 `compose.WithCallbacks()` 传入，不在编译时注册
-- 元数据（SessionID/Scenario 等）通过 State 跨节点传递，不通过 Graph 边传递
-
-**变更文件**：
-- 修改 `state.go`：新增 SessionID/RequestID/ImageData 等字段
-- 修改 `nodes_stt.go`：写入元数据到 State
-- 修改 `nodes_history.go`：从 State 读取元数据（移除 HistoryInput 依赖）
-- 修改 `nodes_done.go`：移除历史追加（由适配器负责）
-
-**验证**：`go build ./cmd/server` ✓，`go vet ./...` ✓
-
----
-
-### Phase 4：清理与测试（提交 `4ffd845`）
-
-**目标**：删除旧代码，编写单元测试。
-
-**删除的文件**：
-
-| 文件 | 说明 |
-|------|------|
-| `orchestrator/pipeline.go` | 旧 STT→LLM→TTS 手写 goroutine 管道（-547 行） |
-| `orchestrator/splitter.go` | 旧句子切分器（-114 行） |
-| `orchestrator/pipeline_test.go` | 旧 Pipeline 测试（-309 行） |
-| `ai/llm/openai.go` | 旧 LLM OpenAI 实现（-548 行） |
-| `ai/llm/openai_test.go` | 旧 LLM 测试（-143 行） |
-
-**保留的文件**：
-
-| 文件 | 保留原因 |
-|------|---------|
-| `orchestrator/orchestrator.go` | Orchestrator 接口（ws/handler 依赖） |
-| `orchestrator/sender.go` | Sender 接口（eino/callback 依赖） |
-| `ai/llm/llm.go` | Request/Chunk/TokenUsage 类型定义 |
-| `ai/llm/prompt.go` | BuildSystemPrompt（eino/nodes_history 依赖） |
-| `ai/llm/scenarios.go` | GetScenarioPrompt（eino/nodes_history 依赖） |
-
-**新增测试**：`eino/graph_test.go`（13 个测试）
-
-| 测试 | 覆盖内容 |
-|------|---------|
-| `TestDetectImageMimeType` | JPEG/PNG/GIF/WebP/未知格式检测 |
-| `TestBuildPipelineInput` | 文本输入构建 |
-| `TestBuildPipelineInput_WithAudioData` | 音频+图片输入构建 |
-| `TestPipelineState_AppendAndGet` | State 文本追加和读取 |
-| `TestPipelineState_ConcurrentAccess` | State 并发安全（100 goroutine） |
-| `TestContextInjection` | Sender/RequestID/State 注入和提取 |
-| `TestLatencyFromCtx` | 延迟计算 |
-| `TestEinoOrchestrator_ImplementsInterface` | 接口实现检查 |
-| `TestNew*Lambda_ReturnsNonNil` | 5 个 Lambda 构造函数非空检查 |
-
-**验证**：`go build ./...` ✓，`go vet ./...` ✓，`go test ./...` ✓
-
-## 4. 代码变更统计
-
-| 阶段 | 提交 | 新增 | 删除 | 净变化 |
-|------|------|------|------|--------|
-| Phase 1 + 2 | `fd5c771` | +946 | -24 | +922 |
-| Phase 3 | `4b731b5` | +395 | -98 | +297 |
-| Phase 4 | `4ffd845` | +235 | -1661 | -1426 |
-| **合计** | | **+1576** | **-1783** | **-207** |
-
-重构后代码量净减少 207 行，同时获得了更好的可维护性、可测试性和可扩展性。
-
-## 5. 遗留事项
-
-| 事项 | 优先级 | 说明 |
-|------|--------|------|
-| eino-ext ChatModel DashScope 兼容性端到端验证 | 高 | 需要真实 API Key 验证流式输出和多模态 |
-| LLM 超时控制 | 中 | eino-ext ChatModel 的 `Timeout` 配置需验证 |
-| TTS 流式优化 | 中 | 当前 TTS 是 InvokableLambda，可改为 StreamableLambda |
-| ReAct Agent 扩展 | 低 | 基于 Graph Branch 实现工具调用循环 |
-| Model Router | 低 | 按场景/成本路由不同 LLM |
-| 指标监控 | 低 | 通过 Callback 接入 Prometheus |

docs/12-自定义情景.md

@@ -0,0 +1,425 @@
+# 自建情景功能
+
+## 概述
+
+用户可以创建自己的情景，而不仅限于系统预置的 5 种情景。
+
+**系统预置情景**（不可修改）：
+- 💬 自由对话
+- 🎯 模拟面试官
+- 📚 英语老师
+- ⚔️ 辩论对手
+- 🌐 同声翻译
+
+**用户自建情景**（可增删改）：
+- 🎨 创意写作导师
+- 🧘 心理咨询师
+- 👨‍🍳 私人厨师
+- 📖 历史学家
+- ... （用户自由创建）
+
+**用户旅程**：
+
+```
+1. 用户点击"创建情景"按钮
+   ↓
+2. 弹出创建对话框
+   ↓
+3. 填写表单：
+   - 情景名称（必填）
+   - 情景图标（可选）
+   - 简短描述（可选）
+   - 角色 Prompt（必填，最少 10 字）
+   - 首句引导（可选）
+   ↓
+4. 点击"创建"
+   ↓
+5. 情景保存到数据库
+   ↓
+6. 情景出现在选择列表中
+   ↓
+7. 用户切换到自建情景
+   ↓
+8. AI 按照用户设定的 Prompt 扮演角色
+```
+
+**核心特性**：完整 CRUD 操作（创建/查看/编辑/删除），通过 `user_id` 实现用户数据完全隔离，Eino Graph 管线深度集成（动态加载自建情景 Prompt），中文/英文/日文全覆盖，Modal 对话框 + 图标选择器 + Prompt 编写指南，创建后立即可用无需刷新。
+
+## 技术架构
+
+### 数据流
+
+**创建情景**：
+
+```
+用户填写表单 → POST /api/scenarios → Handler 验证
+→ Repository.Create → PostgreSQL 插入 → 返回情景对象
+```
+
+**AI 对话使用自建情景**：
+
+```
+WebSocket 连接 → ServeWS 获取 userID
+→ Eino Graph 初始化 → nodes_history 查询 user_scenarios
+→ GetScenarioPrompt(customScenarios) → 构建 System Prompt
+→ LLM 生成回复
+```
+
+### Eino 框架集成
+
+**数据传递链路**：
+
+```
+JWT Token → userID
+    ↓
+Session.UserID
+    ↓
+PipelineInput.UserID
+    ↓
+PipelineState.UserID
+    ↓
+nodes_history.go: scenarioRepo.FindByUserID(userID)
+    ↓
+构建 customScenarios map[string]string
+    ↓
+llm.GetScenarioPrompt(scenarioID, language, customScenarios)
+    ↓
+LLM 使用自建情景 Prompt
+```
+
+**关键修改文件**：
+
+| 文件 | 变更说明 |
+|------|----------|
+| `backend/internal/eino/state.go` | PipelineState 添加 `UserID` |
+| `backend/internal/eino/types.go` | PipelineInput 添加 `UserID` |
+| `backend/internal/eino/graph.go` | 接受 `scenarioRepo` 参数 |
+| `backend/internal/eino/adapter.go` | 设置 UserID |
+| `backend/internal/eino/nodes_history.go` | 查询自建情景 |
+| `backend/internal/ws/handler.go` | 首句引导支持自建情景 |
+
+## 数据模型
+
+### 数据库表结构
+
+**表名**: `user_scenarios`
+
+```sql
+CREATE TABLE user_scenarios (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    name VARCHAR(50) NOT NULL,
+    icon VARCHAR(10) DEFAULT '✨',
+    description VARCHAR(100),  -- 可选
+    prompt TEXT NOT NULL,
+    greeting VARCHAR(500),      -- 可选
+    language VARCHAR(10) DEFAULT 'zh-CN',
+    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT unique_user_scenario UNIQUE(user_id, name),
+    CONSTRAINT check_name_length CHECK (char_length(name) >= 2 AND char_length(name) <= 50),
+    CONSTRAINT check_description_length CHECK (description IS NULL OR char_length(description) <= 100),
+    CONSTRAINT check_prompt_length CHECK (char_length(prompt) >= 10 AND char_length(prompt) <= 2000),
+    CONSTRAINT check_greeting_length CHECK (greeting IS NULL OR char_length(greeting) <= 500)
+);
+
+CREATE INDEX idx_user_scenarios_user_id ON user_scenarios(user_id);
+CREATE INDEX idx_user_scenarios_created_at ON user_scenarios(created_at DESC);
+```
+
+**字段说明**:
+
+| 字段 | 说明 |
+|------|------|
+| `id` | 情景唯一标识 |
+| `user_id` | 所属用户，实现数据隔离 |
+| `name` | 情景名称（2-50 字符） |
+| `icon` | Emoji 图标（默认 ✨） |
+| `description` | 简短描述（可选，最多 100 字符） |
+| `prompt` | 角色 System Prompt（10-2000 字符） |
+| `greeting` | 首句引导（可选，最多 500 字符） |
+| `language` | 默认语言（zh-CN / en-US / ja-JP） |
+
+### 后端数据模型
+
+```go
+// backend/internal/models/user_scenario.go
+
+type UserScenario struct {
+    ID          string    `json:"id"`
+    UserID      string    `json:"user_id"`
+    Name        string    `json:"name"`
+    Icon        string    `json:"icon"`
+    Description string    `json:"description"`
+    Prompt      string    `json:"prompt"`
+    Greeting    string    `json:"greeting,omitempty"`
+    Language    string    `json:"language"`
+    CreatedAt   time.Time `json:"created_at"`
+    UpdatedAt   time.Time `json:"updated_at"`
+}
+
+type CreateUserScenarioRequest struct {
+    Name        string `json:"name" binding:"required,min=2,max=50"`
+    Icon        string `json:"icon,omitempty"`
+    Description string `json:"description,omitempty" binding:"omitempty,max=100"`
+    Prompt      string `json:"prompt" binding:"required,min=10,max=2000"`
+    Greeting    string `json:"greeting,omitempty" binding:"omitempty,max=500"`
+    Language    string `json:"language,omitempty"`
+}
+```
+
+### 前端数据结构
+
+```typescript
+// frontend/src/lib/api/scenarios.ts
+
+export interface UserScenario {
+  id: string;
+  user_id: string;
+  name: string;
+  icon: string;
+  description: string;
+  prompt: string;
+  greeting?: string;
+  language: string;
+  created_at: string;
+  updated_at: string;
+}
+
+// frontend/src/hooks/useScenarios.ts
+
+export interface ExtendedScenario {
+  id: string;
+  icon: string;
+  name: string;
+  nameKey?: string;
+  description?: string;
+  descKey?: string;
+  isCustom: boolean;
+  prompt?: string;
+  greeting?: string;
+  language?: string;
+}
+```
+
+## REST API
+
+### API 端点
+
+| 方法 | 路径 | 说明 | 权限 |
+|------|------|------|------|
+| GET | `/api/scenarios` | 获取用户的所有自建情景 | 需登录 |
+| POST | `/api/scenarios` | 创建新情景 | 需登录 |
+| GET | `/api/scenarios/:id` | 获取单个情景详情 | 需登录 |
+| PATCH | `/api/scenarios/:id` | 更新情景 | 需登录 |
+| DELETE | `/api/scenarios/:id` | 删除情景 | 需登录 |
+
+### API 示例
+
+**创建情景**：
+
+```http
+POST /api/scenarios
+Authorization: Bearer <access_token>
+Content-Type: application/json
+
+{
+  "name": "创意写作导师",
+  "icon": "✨",
+  "description": "帮助构思故事情节和写作技巧",
+  "prompt": "你是一位创意写作导师，帮助用户构思故事情节、人物设定和写作技巧...",
+  "greeting": "你好！我是你的创意写作导师。今天想聊聊什么故事创意呢？",
+  "language": "zh-CN"
+}
+```
+
+响应 201 Created：
+
+```json
+{
+  "id": "uuid-xxx",
+  "user_id": "uuid-user",
+  "name": "创意写作导师",
+  "icon": "✨"
+}
+```
+
+**获取列表**：
+
+```http
+GET /api/scenarios
+Authorization: Bearer <access_token>
+```
+
+响应 200 OK：
+
+```json
+{
+  "scenarios": [],
+  "total": 3
+}
+```
+
+## 前端实现
+
+### 组件结构
+
+```
+frontend/src/
+├── components/
+│   ├── CreateScenarioModal/
+│   │   └── index.tsx          # 创建情景对话框
+│   ├── EditScenarioModal/
+│   │   └── index.tsx          # 编辑情景对话框
+│   └── ConfigPanel/
+│       └── index.tsx          # 设置面板（改造）
+├── hooks/
+│   └── useScenarios.ts        # 情景管理 Hook
+└── lib/
+    └── api/
+        └── scenarios.ts        # API 调用封装
+```
+
+### 核心 Hook
+
+```typescript
+// useScenarios.ts
+
+export function useScenarios(token: string | null) {
+  const [allScenarios, setAllScenarios] = useState<ExtendedScenario[]>([]);
+
+  // 合并系统预置 + 用户自建
+  useEffect(() => {
+    const systemScenarios = scenarios.map(s => ({...s, isCustom: false}));
+    const customScenarios = customList.map(s => ({...s, isCustom: true}));
+    setAllScenarios([...systemScenarios, ...customScenarios]);
+  }, [customList]);
+
+  return {
+    allScenarios,
+    createScenario,
+    updateScenario,
+    deleteScenario,
+  };
+}
+```
+
+### 创建情景表单
+
+**表单字段**：
+
+- 名称（必填，2-50 字符）
+- 图标（可选，24 个预设 emoji）
+- 描述（可选，最多 100 字符）
+- Prompt（必填，10-2000 字符）
+- 首句引导（可选，最多 500 字符）
+- 语言（可选，默认 zh-CN）
+
+**表单验证**：
+
+- 实时字符计数
+- 长度限制提示
+- 必填项高亮
+
+## 使用指南
+
+### 后端 API 测试
+
+```bash
+# 1. 注册用户
+curl -X POST http://localhost:8080/api/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"username":"testuser","password":"test12345"}'
+
+# 2. 创建情景
+TOKEN="<access_token>"
+curl -X POST http://localhost:8080/api/scenarios \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "创意写作导师",
+    "icon": "✨",
+    "prompt": "你是一位创意写作导师...",
+    "language": "zh-CN"
+  }'
+
+# 3. 获取列表
+curl -X GET http://localhost:8080/api/scenarios \
+  -H "Authorization: Bearer $TOKEN"
+
+# 4. 更新情景
+curl -X PATCH http://localhost:8080/api/scenarios/<id> \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"高级写作导师"}'
+
+# 5. 删除情景
+curl -X DELETE http://localhost:8080/api/scenarios/<id> \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### 前端功能测试
+
+1. 刷新浏览器（Cmd+Shift+R）
+2. 登录账户
+3. 打开设置面板（右上角齿轮）
+4. 滚动到"我的情景"区域
+5. 点击"+ 创建新情景"
+6. 填写表单并提交
+7. 验证列表中出现新情景
+8. 切换到自建情景，验证首句引导
+9. 发送消息，验证 AI 使用自建 Prompt
+10. 编辑情景，验证数据预填充
+11. 删除情景，验证二次确认
+
+## 安全与限制
+
+### 用户配额
+
+```go
+const MaxScenariosPerUser = 20  // 每个用户最多 20 个自建情景
+```
+
+### 权限控制
+
+- 只能查看/编辑/删除自己的情景
+- 系统预置情景不可编辑/删除
+- 后端验证 `user_id` 匹配
+
+### 数据验证
+
+**后端**：
+
+- 名称：2-50 字符
+- 描述：可选，最多 100 字符
+- Prompt：10-2000 字符
+- 首句引导：可选，最多 500 字符
+
+**前端**：
+
+- 实时字符计数
+- 超长提示
+- 必填项高亮
+
+## 未来优化方向
+
+**V1.1**：
+
+- Prompt 模板库
+- 实时预览效果
+- 导入导出功能
+- 情景搜索和筛选
+
+**V2.0**：
+
+- 情景市场
+- 情景分享链接
+- AI 辅助优化 Prompt
+- 协作编辑（团队情景）
+
+## 参考资料
+
+- [CLAUDE.md](../CLAUDE.md) — 项目开发指南
+- [02-接口文档.md](./02-接口文档.md) — WebSocket 和 REST API
+- [自建情景功能-权限隔离说明.md](./自建情景功能-权限隔离说明.md) — 安全设计

docs/13-日志追踪.md

@@ -0,0 +1,544 @@
+# 日志追踪系统
+
+## 概述
+
+CamTalk 全链路日志追踪系统，通过统一的 trace ID 机制，将 REST API 和 WebSocket 两大入口的所有日志串联起来，实现分布式环境下的请求链路可观测性。
+
+**核心目标**：
+- 统一 trace ID 贯穿 REST/WebSocket 两大入口
+- 所有日志自动附加 trace_id/request_id/session_id
+- 保护用户隐私，敏感文本截断或降级
+- 支持按 trace_id 快速定位完整请求链路
+
+## Trace ID 作用域
+
+| 标识 | 作用域 | 生成时机 | 用途 |
+|-----|--------|---------|------|
+| `trace_id` | **连接级**（整个 WebSocket 生命周期）<br/>**请求级**（单次 REST 请求） | REST: 中间件生成<br/>WebSocket: 升级时生成 | 关联同一连接/请求的所有日志 |
+| `session_id` | 会话级（对话上下文存储） | ServeWS 时生成 | 标识会话存储 |
+| `request_id` | 查询级（单次 WebSocket 查询） | 客户端每次查询传入 | 区分同一连接的不同查询 |
+
+**WebSocket 场景示例**：用户打开页面建立 WebSocket，发起 3 次对话查询：
+
+```
+连接建立    trace_id=01J5AAA  session_id=uuid-123
+  ├─ 查询1  trace_id=01J5AAA  request_id=req-001  (问天气)
+  ├─ 查询2  trace_id=01J5AAA  request_id=req-002  (问新闻)
+  └─ 查询3  trace_id=01J5AAA  request_id=req-003  (问股票)
+```
+
+**REST 场景示例**：
+
+```
+POST /api/auth/login    trace_id=01J5BBB  request_id=01J5BBB
+GET  /api/conversations trace_id=01J5CCC  request_id=01J5CCC
+```
+
+## 核心组件
+
+```mermaid
+graph TB
+    subgraph trace包["trace 包"]
+        ID["id.go<br/>ULID 生成器"]
+        CTX["context.go<br/>context key 管理"]
+        LOG["logger.go<br/>context-aware logger"]
+        MW["middleware.go<br/>Gin trace 中间件"]
+    end
+    
+    subgraph logger包["logger 包"]
+        GINLOG["middleware.go<br/>Gin 请求日志"]
+        GINREC["GinRecovery<br/>panic 恢复"]
+    end
+    
+    subgraph 入口层["入口层"]
+        REST["REST API<br/>trace 中间件注入"]
+        WS["WebSocket<br/>ServeWS 注入"]
+    end
+    
+    subgraph 业务层["业务层"]
+        HANDLER["Handler"]
+        ADAPTER["Eino Adapter"]
+        NODES["Eino Nodes"]
+    end
+    
+    subgraph 存储层["存储层"]
+        PG["PostgreSQL<br/>session/user/message/scenario"]
+        REDIS["Redis<br/>session/cache/ratelimit"]
+    end
+    
+    ID --> MW
+    CTX --> LOG
+    LOG --> HANDLER
+    LOG --> ADAPTER
+    LOG --> NODES
+    LOG --> PG
+    LOG --> REDIS
+    MW --> REST
+    GINLOG --> REST
+    WS --> LOG
+```
+
+### trace/id.go — ULID 生成器
+
+使用 ULID（Universally Unique Lexicographically Sortable Identifier）作为 trace ID：
+- 时间排序：前 48 位是毫秒时间戳，天然按时间排序
+- 唯一性：后 80 位随机数，冲突概率极低
+- 并发安全：使用 `crypto/rand` + `sync.Pool` 复用 entropy 对象
+
+```go
+package trace
+
+import (
+    cryptorand "crypto/rand"
+    "sync"
+    "time"
+    "github.com/oklog/ulid/v2"
+)
+
+var entropyPool = sync.Pool{
+    New: func() interface{} {
+        return ulid.Monotonic(cryptorand.Reader, 0)
+    },
+}
+
+// GenerateTraceID 生成并发安全的 ULID trace ID
+func GenerateTraceID() string {
+    entropy := entropyPool.Get().(*ulid.MonotonicEntropy)
+    defer entropyPool.Put(entropy)
+    return ulid.MustNew(ulid.Timestamp(time.Now()), entropy).String()
+}
+```
+
+### trace/context.go — Context Key 管理
+
+统一管理所有 trace 相关的 context key：
+
+```go
+package trace
+
+import "context"
+
+type traceIDKey struct{}
+type requestIDKey struct{}
+type sessionIDKey struct{}
+
+// WithTraceID 将 trace ID 注入 context
+func WithTraceID(ctx context.Context, traceID string) context.Context {
+    return context.WithValue(ctx, traceIDKey{}, traceID)
+}
+
+func GetTraceID(ctx context.Context) string {
+    if v, ok := ctx.Value(traceIDKey{}).(string); ok {
+        return v
+    }
+    return ""
+}
+
+// 类似定义 WithRequestID/GetRequestID 和 WithSessionID/GetSessionID
+```
+
+### trace/logger.go — Context-Aware Logger
+
+自动从 context 提取 trace 字段并附加到日志：
+
+```go
+package trace
+
+import (
+    "context"
+    "github.com/hhs/camtalk/internal/logger"
+    "go.uber.org/zap"
+)
+
+// FromContext 返回自动附加 trace_id/request_id/session_id 的 logger
+func FromContext(ctx context.Context) *zap.SugaredLogger {
+    log := logger.Log
+    
+    if traceID := GetTraceID(ctx); traceID != "" {
+        log = log.With("trace_id", traceID)
+    }
+    if requestID := GetRequestID(ctx); requestID != "" {
+        log = log.With("request_id", requestID)
+    }
+    if sessionID := GetSessionID(ctx); sessionID != "" {
+        log = log.With("session_id", sessionID)
+    }
+    
+    return log
+}
+```
+
+**使用模式对比**：
+
+```go
+// Before: 手动传递字段
+logger.Log.Infow("message", "session", sessionID, "request", requestID)
+
+// After: 自动附加
+trace.FromContext(ctx).Infow("message")
+```
+
+### trace/middleware.go — Gin Trace 中间件
+
+为 REST 请求生成 trace ID 并注入 context：
+
+```go
+package trace
+
+import "github.com/gin-gonic/gin"
+
+// TraceMiddleware 为每个 HTTP 请求生成 trace ID 并注入 context
+func TraceMiddleware() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        traceID := GenerateTraceID()
+        ctx := WithTraceID(c.Request.Context(), traceID)
+        ctx = WithRequestID(ctx, traceID) // REST: trace_id == request_id
+        
+        c.Request = c.Request.WithContext(ctx)
+        c.Header("X-Trace-ID", traceID) // 返回给客户端用于排查
+        
+        c.Next()
+    }
+}
+```
+
+### logger/middleware.go — 请求日志与 Panic 恢复
+
+记录所有 HTTP 请求的 method/path/status/latency：
+
+```go
+package logger
+
+import (
+    "time"
+    "github.com/gin-gonic/gin"
+    "github.com/hhs/camtalk/internal/trace"
+)
+
+// GinLogger 记录每个 HTTP 请求的基础信息
+func GinLogger() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        start := time.Now()
+        path := c.Request.URL.Path
+        
+        c.Next()
+        
+        latency := time.Since(start).Milliseconds()
+        status := c.Writer.Status()
+        log := trace.FromContext(c.Request.Context())
+        
+        switch {
+        case status >= 500:
+            log.Errorw("request completed", "method", c.Request.Method, 
+                "path", path, "status", status, "latency_ms", latency)
+        case status >= 400:
+            log.Warnw("request completed", "method", c.Request.Method,
+                "path", path, "status", status, "latency_ms", latency)
+        default:
+            log.Infow("request completed", "method", c.Request.Method,
+                "path", path, "status", status, "latency_ms", latency)
+        }
+    }
+}
+
+// GinRecovery 自定义 panic 恢复中间件
+func GinRecovery() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        defer func() {
+            if err := recover(); err != nil {
+                log := trace.FromContext(c.Request.Context())
+                log.Errorw("panic recovered", "error", err,
+                    "path", c.Request.URL.Path, "method", c.Request.Method)
+                c.AbortWithStatus(500)
+            }
+        }()
+        c.Next()
+    }
+}
+```
+
+## 中间件注册顺序
+
+在 `cmd/server/main.go` 中，三层中间件按顺序注册：
+
+```go
+r := gin.New()
+r.Use(trace.TraceMiddleware())    // 第一层：生成 trace ID
+r.Use(logger.GinLogger())          // 第二层：记录请求
+r.Use(logger.GinRecovery())        // 第三层：panic 恢复
+```
+
+## 日志输出示例
+
+### REST 请求
+
+```json
+{
+  "level": "info",
+  "ts": 1718956800.123,
+  "msg": "login success",
+  "trace_id": "01J5A2B3C4D5E6F7G8H9J0K1M",
+  "request_id": "01J5A2B3C4D5E6F7G8H9J0K1M",
+  "username": "test_user"
+}
+```
+
+### WebSocket 查询链路（含存储层）
+
+```json
+// 1. 查询接收
+{"level":"info", "trace_id":"01J5XXX", "session_id":"abc-123", "request_id":"req-456", "msg":"query received"}
+
+// 2. 会话加载（Redis）
+{"level":"debug", "trace_id":"01J5XXX", "session_id":"abc-123", "request_id":"req-456", "msg":"redis session retrieved", "session_id":"abc-123"}
+
+// 3. STT 完成
+{"level":"debug", "trace_id":"01J5XXX", "session_id":"abc-123", "request_id":"req-456", "msg":"stt recognition completed", "text_len":45}
+
+// 4. LLM 完成
+{"level":"info", "trace_id":"01J5XXX", "session_id":"abc-123", "request_id":"req-456", "msg":"llm generation completed", "tokens":150}
+
+// 5. 消息持久化（PostgreSQL）
+{"level":"debug", "trace_id":"01J5XXX", "session_id":"abc-123", "request_id":"req-456", "msg":"message saved", "role":"user", "tokens_used":45}
+{"level":"debug", "trace_id":"01J5XXX", "session_id":"abc-123", "request_id":"req-456", "msg":"message saved", "role":"assistant", "tokens_used":150}
+
+// 6. Pipeline 完成
+{"level":"info", "trace_id":"01J5XXX", "session_id":"abc-123", "request_id":"req-456", "msg":"query processing completed", "latency_ms":2340}
+```
+
+### 限流触发场景
+
+```json
+{"level":"warn", "trace_id":"01J5YYY", "msg":"rate limit triggered", "key":"ratelimit:user-456:query", "retry_after_sec":2.5}
+```
+
+## 日志查询操作
+
+### 按 trace_id 查询完整链路
+
+**本地开发（文件日志）**：
+```bash
+# 查看完整链路
+grep 'trace_id":"01J5XXX"' backend.log | jq .
+
+# 查看链路时间线
+grep 'trace_id":"01J5XXX"' backend.log | jq -r '[.ts, .msg] | @tsv'
+```
+
+**Grafana Loki**：
+```logql
+{app="camtalk-backend"} 
+  |= "trace_id=01J5XXX" 
+  | json 
+  | line_format "{{.ts}} [{{.level}}] {{.msg}}"
+```
+
+### 查询慢请求（延迟 > 5s）
+
+```logql
+{app="camtalk-backend"} 
+  | json 
+  | msg="query processing completed" 
+  | latency_ms > 5000
+```
+
+### 查询数据库错误
+
+```logql
+{app="camtalk-backend"} 
+  | json 
+  | level="error" 
+  | msg=~".*failed" 
+  | line_format "{{.trace_id}} {{.msg}} {{.error}}"
+```
+
+### 查询 Redis 降级事件
+
+```logql
+{app="camtalk-backend"} 
+  | json 
+  | level="warn" 
+  | msg=~"redis.*failed"
+```
+
+### 查询错误率
+
+```logql
+sum(count_over_time({app="camtalk-backend"} | json | level="error" [5m]))
+```
+
+## 敏感内容处理规范
+
+### 完全禁止记录
+
+- 用户明文密码
+- JWT token 完整内容（仅记录 "token_present: true"）
+- API Key 完整值（仅记录前 8 字符 + "..."）
+
+### 截断后记录（最多 50 字符）
+
+- 用户输入文本 → `text_preview`
+- LLM 生成文本 → `text_preview`
+- STT 识别文本 → `text_preview`
+
+**示例**：
+```go
+log.Debugw("stt recognition completed",
+    "text_len", len(text),
+    "text_preview", util.Truncate(text, 50))
+```
+
+### 仅记录长度/大小
+
+- 图片数据 → `image_size_bytes`
+- 音频数据 → `audio_size_bytes`
+
+### 降级为 Debug 级别
+
+所有包含用户文本预览的日志，生产环境默认不输出。
+
+## 日志级别使用准则
+
+| 场景 | 级别 | 示例 |
+|-----|------|-----|
+| 请求生命周期里程碑 | Info | `"query received"`, `"pipeline completed"` |
+| 中间步骤详情 | Debug | `"stt recognition completed"`, `"history assembled"` |
+| 敏感内容相关 | Debug | 所有包含用户文本的日志 |
+| 预期内的失败 | Warn | `"login failed"`, `"rate limited"` |
+| 系统错误 | Error | `"database query failed"`, `"tts synthesis failed"` |
+| 严重故障 | Error + stack | `"panic recovered"` |
+
+## 存储层日志实现
+
+### PostgreSQL Repository 层
+
+所有数据库操作统一使用 `trace.FromContext(ctx)` 记录日志：
+
+**已实现文件**：
+- `backend/internal/store/session_pg.go` — 会话 CRUD
+- `backend/internal/store/user_pg.go` — 用户与 refresh token 操作
+- `backend/internal/store/message_pg.go` — 对话消息存储
+- `backend/internal/store/user_scenario_repository.go` — 用户自定义情景
+
+**日志策略**：
+
+```go
+func (r *PgSessionRepository) Save(ctx context.Context, s SessionRecord) error {
+    log := trace.FromContext(ctx)
+    
+    _, err := r.pool.Exec(ctx, ...)
+    if err != nil {
+        log.Errorw("save session failed", "session_id", s.ID, "error", err)
+        return err
+    }
+    
+    log.Debugw("session saved", "session_id", s.ID, "user_id", s.UserID)
+    return nil
+}
+```
+
+**NotFound 处理**：预期内的空结果不记录错误：
+
+```go
+if errors.Is(err, pgx.ErrNoRows) {
+    return nil, ErrSessionNotFound  // 不记录日志
+}
+if err != nil {
+    log.Errorw("find session failed", "session_id", id, "error", err)
+    return nil, err
+}
+```
+
+### Redis 服务层
+
+**已实现文件**：
+- `backend/internal/session/redis.go` — RedisManager（会话存储）
+- `backend/internal/store/cached_user.go` — CachedUserRepository（用户缓存装饰器）
+- `backend/internal/ratelimit/redis_bucket.go` — RedisLimiter（令牌桶限流器）
+
+**会话存储日志**（`redis.go`）：
+
+```go
+func (m *RedisManager) Get(ctx context.Context, sessionID string) (*models.Session, error) {
+    log := trace.FromContext(ctx)
+    
+    vals, err := m.rdb.HGetAll(ctx, metaKey(sessionID)).Result()
+    if err != nil {
+        log.Errorw("redis get session failed", "session_id", sessionID, "error", err)
+        return nil, fmt.Errorf("redis get session: %w", err)
+    }
+    
+    if len(vals) == 0 {
+        return nil, ErrSessionNotFound  // 不记录日志
+    }
+    
+    log.Debugw("redis session retrieved", "session_id", sessionID)
+    return session, nil
+}
+```
+
+**缓存降级日志**（`cached_user.go`）：
+
+```go
+if _, err := pipe.Exec(ctx); err != nil {
+    log := trace.FromContext(ctx)
+    log.Warnw("redis cache write failed for refresh token", "error", err)
+    // 降级：DB 已写入成功，Redis 失败不影响正确性
+}
+```
+
+**限流触发日志**（`redis_bucket.go`）：
+
+```go
+func (l *RedisLimiter) Allow(ctx context.Context, key string) (bool, time.Duration) {
+    log := trace.FromContext(ctx)
+    
+    result, err := l.script.Run(ctx, ...).Result()
+    if err != nil {
+        log.Errorw("rate limit check failed", "key", key, "error", err)
+        return true, 0  // fail-open 策略
+    }
+    
+    if allowed == 0 {
+        log.Warnw("rate limit triggered", "key", key, "retry_after_sec", retryAfterSec)
+        return false, retryAfter
+    }
+    
+    return true, 0
+}
+```
+
+**级别选择原则**：
+- **Error**：Redis 连接失败、Lua 脚本执行失败（影响功能）
+- **Warn**：缓存写入失败（可降级）、限流触发（预期内异常）
+- **Debug**：正常操作完成（避免 Info 级别噪音）
+
+## 编码规范
+
+1. **日志语言**：统一使用英文
+2. **结构化**：始终使用 `Infow`/`Errorw`/`Warnw`/`Debugw`
+3. **Context 传递**：使用 `trace.FromContext(ctx)` 而非直接引用 `logger.Log`
+4. **敏感内容**：禁止在 Info 及以上级别记录用户文本原文
+5. **错误日志**：采用"调用方记录"原则，底层函数 return wrapped error
+6. **级别约定**：
+   - `Debug`：内部状态跟踪、开发调试信息（数据库/缓存成功操作）
+   - `Info`：请求/连接生命周期、关键操作里程碑
+   - `Warn`：可降级异常（Redis 故障、限流触发）
+   - `Error`：影响用户的操作失败（数据库错误、Redis 连接失败）
+   - `Fatal`：仅启动阶段不可恢复错误
+7. **预期内的空结果**：`pgx.ErrNoRows`、`redis.Nil` 等不记录错误日志
+
+## 性能考量
+
+### FromContext 开销
+
+- 有 trace_id：~200-300 ns/op
+- 无 trace_id：~10-20 ns/op（仅返回全局 logger）
+- 1000 QPS 场景额外开销约 0.2ms，可接受
+
+### ULID 生成吞吐量
+
+- 单线程：~500k ops/s
+- 并发 8 线程：~2M ops/s
+
+**验收标准**：1000 QPS 下，trace 系统开销 < 1% CPU，< 0.5ms P99 延迟。

docs/13-结束视频保留对话设计方案.md

@@ -1,288 +0,0 @@
-# 结束视频后保留对话并支持继续文字聊天
-
-> 创建日期：2026-06-20
-> 状态：草案
-
-## 1. 背景与目标
-
-### 1.1 现状问题
-
-当前点击"结束对话"按钮会执行完整的 teardown 流程：
-
-1. 停止 VAD、麦克风、摄像头
-2. 断开 WebSocket 连接
-3. **清空所有聊天消息**（`setMessages([])`）
-4. **清空对话历史**（`historyRef.current = []`）
-5. 重置统计数据
-6. UI 切回初始界面（显示"开始视频通话"按钮）
-
-**问题**：用户想结束视频通话后，保留聊天记录并继续通过文字输入对话，但当前实现会丢失所有对话内容。
-
-### 1.2 目标
-
-| 目标 | 说明 |
-|------|------|
-| 结束视频后保留对话 | 点击"结束视频"后，聊天记录保持不变 |
-| 支持继续文字对话 | 视频结束后，用户可通过文字输入继续与 AI 对话 |
-| 可恢复视频 | 视频结束后，用户可随时重新开启视频 |
-| 完全结束可选 | 提供"结束会话"选项，彻底断开并清空 |
-
-## 2. 状态设计
-
-### 2.1 三态模型
-
-引入三个会话状态，替代当前的二态（初始/通话）模型：
-
-```
-┌──────────┐    startSession()    ┌──────────┐
-│  initial  │ ──────────────────→ │  video   │
-│  初始态    │                     │  视频通话  │
-└──────────┘                      └──────────┘
-      ↑                                │
-      │                          stopVideo()
-      │                                │
-      │                                ▼
-      │                         ┌──────────┐
-      │ stopSession()           │ textOnly │
-      └──────────────────────── │ 文字对话  │
-                                └──────────┘
-                                      │
-                                startSession()
-                                      │
-                                      ▼
-                                ┌──────────┐
-                                │  video   │
-                                │  视频通话  │
-                                └──────────┘
-```
-
-### 2.2 各状态属性
-
-| 状态 | WebSocket | 摄像头 | 麦克风 | VAD | 消息 | 文字输入 |
-|------|-----------|--------|--------|-----|------|---------|
-| `initial` | 断开 | 关闭 | 关闭 | 停止 | 空 | 可用（自动连接） |
-| `video` | 连接 | 开启 | 开启 | 运行 | 有 | 可用 |
-| `textOnly` | 连接 | 关闭 | 关闭 | 停止 | 保留 | 可用 |
-
-### 2.3 派生状态
-
-当前代码中 `isConnected` 是从 `connectionStatus === "connected"` 派生的布尔值。为支持三态，新增派生变量：
-
-```ts
-// 是否在会话中（video 或 textOnly）
-const hasSession = isConnected || (connectionStatus === "disconnected" && messages.length > 0);
-```
-
-> **注意**：`textOnly` 状态下 WebSocket 保持连接（`isConnected === true`），所以 `hasSession` 实际上主要靠 `isConnected` 判断。只有在 textOnly 状态下 WebSocket 异常断开时，`messages.length > 0` 才作为兜底。
-
-## 3. 详细设计
-
-### 3.1 `useVisionSession.ts` 改动
-
-#### 3.1.1 新增 `stopVideo` 回调
-
-只停止媒体流，保持 WebSocket 连接和消息：
-
-```ts
-/** 结束视频，保留聊天和连接 */
-const stopVideo = useCallback(async () => {
-  // 1. 停止观察模式
-  stopObserving();
-  setMode("dialogue");
-
-  // 2. 停止媒体流
-  await stopVAD();
-  stopMic();
-  stopCamera();
-
-  // 3. 停止 TTS 播放
-  ttsPlayerRef.current?.stop();
-  setIsAudioPlaying(false);
-
-  // 4. 重置处理状态（但保留消息和历史）
-  setCurrentReply("");
-  setIsProcessing(false);
-  setIsCameraOn(false);
-  setIsMicOn(false);
-
-  // 注意：以下不执行
-  // - disconnect()         → 保持 WebSocket 连接
-  // - setMessages([])      → 保留聊天记录
-  // - historyRef.current=[] → 保留对话历史
-  // - setStats(...)         → 保留统计数据
-}, [stopObserving, stopVAD, stopMic, stopCamera]);
-```
-
-#### 3.1.2 `stopSession` 保持不变
-
-`stopSession` 仍然执行完全 teardown（断开 + 清空），作为"结束会话"使用。
-
-#### 3.1.3 `return` 新增导出
-
-```ts
-return {
-  // ...existing...
-  stopVideo,   // 新增
-  // ...existing...
-};
-```
-
-### 3.2 `App.tsx` 改动
-
-#### 3.2.1 解构新增
-
-```ts
-const {
-  // ...existing...
-  stopVideo,  // 新增
-  // ...existing...
-} = useVisionSession(...)
-```
-
-#### 3.2.2 视频下方控制区改为三态
-
-当前代码（二态）：
-
-```tsx
-{!isConnected ? (
-  /* 初始态 */
-) : (
-  /* 通话态 */
-)}
-```
-
-改为三态：
-
-```tsx
-{!isConnected ? (
-  /* 初始态：开始按钮 + 设备选择 + 模式切换（不变） */
-) : isCameraOn ? (
-  /* 视频通话态：摄像头/麦克风/识别/打断 + "结束视频" 按钮 + 模式切换 */
-) : (
-  /* 文字对话态：
-     - "📹 视频已结束" 提示
-     - "📹 重新开始视频" 按钮
-     - "结束会话" 按钮
-  */
-)}
-```
-
-#### 3.2.3 按钮变化
-
-**视频通话态**（原"结束对话"改为"结束视频"）：
-
-```tsx
-<button className="btn btn--danger" onClick={stopVideo}>
-  {tr("controls.stopVideo")}
-</button>
-```
-
-**文字对话态**（新增）：
-
-```tsx
-<div className="video-controls__text-only">
-  <div className="video-ended-hint">
-    <span>📹 {tr("video.ended")}</span>
-    <span className="video-ended-hint__sub">{tr("video.ended.hint")}</span>
-  </div>
-  <div className="video-controls__toolbar">
-    <button className="btn btn--primary" onClick={startSession}>
-      {tr("controls.resumeVideo")}
-    </button>
-    <button className="btn btn--danger btn--outline" onClick={stopSession}>
-      {tr("controls.endSession")}
-    </button>
-  </div>
-</div>
-```
-
-#### 3.2.4 视频预览区
-
-当前已有逻辑：`{!isConnected && !stream && <placeholder>}`。关闭摄像头后 `stream` 为 null，自动显示占位符。**无需额外改动**。
-
-但在 `textOnly` 状态下 `isConnected` 为 true，所以需要额外判断：
-
-```tsx
-{(!isConnected || !isCameraOn) && !stream && (
-  <div className="video-placeholder">
-    <span className="video-placeholder__icon">📷</span>
-    <span className="video-placeholder__text">{tr("video.cameraOff")}</span>
-    <span className="video-placeholder__hint">{tr("video.cameraOff.hint")}</span>
-  </div>
-)}
-```
-
-#### 3.2.5 状态栏
-
-将 `isConnected && stats.queryCount > 0` 改为在 textOnly 状态下也显示：
-
-```tsx
-{isConnected && stats.queryCount > 0 && (
-  <span className="chat-panel-header__stats">
-    {stats.queryCount} {tr("statusbar.recognitions")}
-    {stats.totalTokens > 0 && ` · ${stats.totalTokens.toLocaleString()} ${tr("statusbar.tokens")}`}
-    {` · ${formatTime(elapsed)}`}
-  </span>
-)}
-```
-
-> `isConnected` 在 textOnly 状态下为 true（WebSocket 未断开），所以**无需改动**。
-
-### 3.3 i18n 新增
-
-| Key | zh-CN | en-US | ja-JP |
-|-----|-------|-------|-------|
-| `controls.stopVideo` | `结束视频` | `End Video` | `ビデオ終了` |
-| `controls.endSession` | `结束会话` | `End Session` | `セッション終了` |
-| `controls.resumeVideo` | `📹 重新开始视频` | `📹 Resume Video` | `📹 ビデオ再開` |
-| `video.ended` | `视频已结束` | `Video Ended` | `ビデオ終了` |
-| `video.ended.hint` | `您可以继续在下方输入文字对话` | `You can continue chatting below` | `下にテキストを入力して会話を続けることができます` |
-
-### 3.4 CSS 样式
-
-新增 `.video-controls__text-only` 和 `.video-ended-hint` 样式，复用现有 `.btn` 和 `.video-controls__toolbar` 样式。
-
-## 4. 边界情况处理
-
-### 4.1 textOnly 状态下 WebSocket 异常断开
-
-`sendTextMessage` 已有自动重连逻辑：检测到未连接时，先加入 `pendingMessagesRef`，再调用 `connect()`。重连成功后自动 flush 待发队列。**无需改动**。
-
-### 4.2 textOnly 状态下无摄像头画面
-
-`sendTextMessage` 中 `captureFrame()` 在无摄像头时返回 null，`dataUrlToBase64(null)` 返回空字符串。服务端 `PipelineInput.ImageData` 为空时，History 节点跳过图像构建多模态消息。**无需改动**。
-
-### 4.3 textOnly 状态下刷新页面
-
-消息通过 `localStorage` 持久化（`camtalk:session:<uuid>`），刷新后从 `localStorage` 恢复。但 WebSocket 断开，`isConnected` 为 false，UI 显示初始态。用户可点击"开始视频通话"或直接输入文字。**无需改动**。
-
-### 4.4 textOnly 状态下切换会话
-
-`selectSession` 会先 persist 当前会话消息，然后加载目标会话消息。切换后 `isConnected` 取决于目标会话的 WebSocket 状态。**无需改动**。
-
-### 4.5 textOnly 状态下 TTS 播放
-
-`stopVideo` 已调用 `ttsPlayerRef.current?.stop()` 停止播放。后续文字对话中如果 AI 回复触发 TTS，TTS 仍可正常播放（WebSocket 连接保持）。**无需改动**。
-
-## 5. 不改动的部分
-
-| 模块 | 原因 |
-|------|------|
-| `useVisionSession.stopSession` | 保持完全 teardown 行为不变 |
-| `sendTextMessage` | 已支持自动连接 + 无摄像头发送 |
-| `ChatPanel` 组件 | 文字输入框始终显示，无需改动 |
-| WebSocket Handler | 服务端无需感知客户端的 video/textOnly 状态 |
-| Session Manager | 会话管理不受影响 |
-| `useSessionList` | 会话列表管理不受影响 |
-
-## 6. 验证清单
-
-| 场景 | 预期结果 |
-|------|---------|
-| 视频通话中点击"结束视频" | 摄像头/麦克风关闭，消息保留，可继续打字 |
-| 文字对话态输入文字发送 | AI 正常回复（无图片），TTS 正常播放 |
-| 文字对话态点击"重新开始视频" | 摄像头/麦克风重新开启，恢复正常视频通话 |
-| 文字对话态点击"结束会话" | 清空消息，断开连接，回到初始态 |
-| 文字对话态刷新页面 | 消息从 localStorage 恢复，可继续打字 |
-| 文字对话态切换到其他会话 | 当前会话消息保存，加载目标会话消息 |
-| 文字对话态 WebSocket 异常断开 | 自动重连，重连后可继续发消息 |

docs/Eino/EiNO 项目实战.md

@@ -1,292 +0,0 @@
----
-tags: [eino, go, ai-agent, rag, tool-calling, project-theme]
-create time: 2026-05-05 14:30
----
-
-# EiNO 项目实战：个人知识助手
-
-## 概述
-
-基于字节跳动 EINO 框架（Go 语言），从零构建一个**个人知识助手 Agent**。该项目深度融合 **RAG（检索增强生成）** 与 **Tool Calling（工具调用）** 两大核心能力，采用 Supervisor 多 Agent 编排模式，帮助用户高效检索笔记、整理知识、发现关联。场景聚焦日常知识管理，不依赖外部基础设施，是入门 EINO 框架的理想项目。
-
-## 正文
-
-### 1. 项目背景
-
-> [!question] 思考：当你积累了上千篇笔记，某天想找一篇"半年前记过的 Go 并发模式"，只记得大概内容却忘了标题——你会怎么办？
-
-传统做法：逐个翻文件夹 → 搜关键词 → 翻了几分钟还是没找到。而一个智能知识助手可以：
-
-1. **听懂模糊描述**："那个讲 goroutine 泄漏排查的文章"→ 语义检索精准定位
-2. **整理碎片知识**："把最近关于 EINO 的笔记汇总成一篇综述"
-3. **发现隐藏关联**："这篇 RAG 笔记和那篇向量数据库笔记其实在讲同一件事"
-
-这个场景**天然适合 AI Agent**：检索知识库（RAG）+ 操作笔记（Tool Calling）+ 多步骤任务（ReAct）。
-
-**用 EINO 的原因**：
-- Go 原生协程，本地跑也轻量
-- 编译时类型检查，工具定义清晰、不易出错
-- ADK 内置 Supervisor / Plan-Execute / Interrupt 等模式，开箱即用
-
----
-
-### 2. 系统架构总览
-
-```mermaid
-graph TD
-    U["用户提问"] --> S["Supervisor Agent<br/>知识总管家"]
-
-    S --> R["Retrieval Agent<br/>知识检索专家"]
-    S --> W["Writer Agent<br/>内容处理专家"]
-    S --> O["Organizer Agent<br/>知识整理专家"]
-
-    R --> VDB["向量数据库<br/>笔记内容索引"]
-    R --> T1["Tool: 语义搜索<br/>相似笔记召回"]
-    R --> T2["Tool: 关键词搜索<br/>精确匹配"]
-
-    W --> T3["Tool: 创建笔记<br/>写入 Markdown"]
-    W --> T4["Tool: 摘要提取<br/>生成笔记摘要"]
-    W --> T5["Tool: 标签推荐<br/>自动打标签"]
-
-    O --> T6["Tool: 关联发现<br/>Wiki-link 推荐"]
-    O --> T7["Tool: 知识图谱<br/>关联关系查询"]
-
-    style S fill:#4A90D9,color:#fff
-    style VDB fill:#27AE60,color:#fff
-```
-
-> **Supervisor 模式**：Supervisor Agent 接收用户指令，根据意图路由——搜索类交给 Retrieval Agent、写作类交给 Writer Agent、整理类交给 Organizer Agent，最终汇总结果返回。
-
----
-
-### 3. RAG 模块设计
-
-RAG 负责从用户的笔记库中检索相关内容，让 Agent "读懂你的知识库"。
-
-#### 3.1 笔记索引管道
-
-```mermaid
-flowchart LR
-    A["Markdown 笔记库"] --> B["Document Loader<br/>按段落分块"]
-    B --> C["Embedding<br/>文本向量化"]
-    C --> D["Indexer<br/>写入向量库"]
-    D --> E["Hybrid Retriever<br/>混合检索"]
-    E --> F["Agent<br/>上下文注入"]
-```
-
-#### 3.2 核心代码：混合检索器
-
-```go
-// RetrieverService 混合检索：语义匹配 + 标签过滤
-type RetrieverService struct {
-    client   milvus.Client
-    embedder embedding.Embedder
-}
-
-func (s *RetrieverService) Retrieve(ctx context.Context, query string, tags []string) ([]*schema.Document, error) {
-    // 1. 将用户查询转为向量
-    vector, err := s.embedder.Embed(ctx, query)
-    if err != nil {
-        return nil, fmt.Errorf("embed query: %w", err)
-    }
-
-    // 2. 构建标量过滤：限定标签范围
-    //    例如: "tag in ['go', 'concurrency', 'eino']"
-    expr := buildTagFilterExpr(tags)
-
-    // 3. 混合检索：Top-K=5
-    results, err := s.client.Search(ctx, "notes_collection",
-        nil, expr,
-        []string{"content", "title", "tags"},
-        vector,
-        milvus.NewTopKMetricType(milvus.L2, 5),
-        milvus.NewSearchParam(16),
-    )
-    // ... 转换为 EINO Document 格式
-    return s.convertToDocs(results), nil
-}
-```
-
-> [!tip] 设计要点
-> 混合检索 = **语义相似度**（"我记得大概意思"） + **标签过滤**（"应该是 Go 相关的"）。相比纯关键词搜索，它能找到表述不同但意思相近的笔记——这正是知识管理中最常见的场景。
-
----
-
-### 4. Tool Calling 模块设计
-
-Agent 通过工具与笔记系统交互：搜索、创建、整理、发现关联。
-
-#### 4.1 工具清单
-
-| 工具 | 类型 | 描述 |
-|------|------|------|
-| `semantic_search` | 查询 | 语义搜索笔记，支持模糊自然语言描述 |
-| `keyword_search` | 查询 | 精确关键词 + 标签搜索 |
-| `create_note` | 写入 | 创建新笔记（Markdown + YAML frontmatter） |
-| `generate_summary` | 处理 | 为指定笔记生成摘要 |
-| `suggest_tags` | 处理 | 根据内容自动推荐标签 |
-| `find_related` | 查询 | 发现关联笔记，推荐 Wiki-link |
-
-#### 4.2 核心代码：定义工具
-
-```go
-// === 写笔记工具 ===
-type CreateNoteParams struct {
-    Title   string   `json:"title" desc:"笔记标题"`
-    Content string   `json:"content" desc:"Markdown 格式正文"`
-    Tags    []string `json:"tags" desc:"标签列表，如 ['go', 'eino']"`
-}
-
-func CreateNoteTool(vaultPath string) componenttool.BaseTool {
-    return &componenttool.Tool{
-        Name: "create_note",
-        Desc: "在知识库中创建一篇新的 Markdown 笔记",
-        Func: func(ctx context.Context, params *CreateNoteParams) (string, error) {
-            fullPath := filepath.Join(vaultPath, params.Title+".md")
-            content := buildMarkdownWithFrontmatter(params)
-            if err := os.WriteFile(fullPath, []byte(content), 0o644); err != nil {
-                return "", fmt.Errorf("write note: %w", err)
-            }
-            return fmt.Sprintf("笔记已创建: %s", fullPath), nil
-        },
-    }
-}
-
-// === 关联发现工具 ===
-type FindRelatedParams struct {
-    NoteTitle string `json:"note_title" desc:"目标笔记标题"`
-}
-
-func FindRelatedTool(retriever *RetrieverService) componenttool.BaseTool {
-    return &componenttool.Tool{
-        Name: "find_related",
-        Desc: "根据笔记内容，从知识库中发现与之关联的其他笔记，推荐 Wiki-link",
-        Func: func(ctx context.Context, params *FindRelatedParams) (string, error) {
-            noteContent := readNote(params.NoteTitle)
-            related, _ := retriever.Retrieve(ctx, noteContent, nil)
-            return formatWikiLinkSuggestions(related), nil
-        },
-    }
-}
-```
-
-> [!question] 思考：如果用户说"帮我把最近一周关于 EINO 的笔记整理成一篇综述"，Agent 需要依次调用哪些工具？顺序能否调换？
-
----
-
-### 5. Multi-Agent 编排：Supervisor 模式
-
-```go
-// === 构建 Supervisor，编排三个 Specialist Agent ===
-func BuildKnowledgeSupervisor(ctx context.Context) (*adk.Supervisor, error) {
-    // Retrieval Agent: 负责搜索和检索
-    retrievalAgent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-        Name:        "RetrievalAgent",
-        Instruction: "你是知识检索专家，擅长从笔记库中找到最相关的内容...",
-        Model:       model,
-        ToolsConfig: adk.ToolsConfig{
-            ToolsNodeConfig: compose.ToolsNodeConfig{
-                Tools: []componenttool.BaseTool{
-                    SemanticSearchTool(retriever),
-                    KeywordSearchTool(),
-                    FindRelatedTool(retriever),
-                },
-            },
-        },
-        MaxIterations: 10,
-    })
-
-    // Writer Agent: 负责创建和整理内容
-    writerAgent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-        Name:    "WriterAgent",
-        Model:   model,
-        ToolsConfig: adk.ToolsConfig{
-            ToolsNodeConfig: compose.ToolsNodeConfig{
-                Tools: []componenttool.BaseTool{
-                    CreateNoteTool(vaultPath),
-                    SummaryTool(model),
-                    SuggestTagsTool(model),
-                },
-            },
-        },
-        MaxIterations: 8,
-    })
-
-    // Organizer Agent: 负责关联发现和知识图谱
-    organizerAgent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-        // ... 配置 FindRelated 等整理工具
-        MaxIterations: 8,
-    })
-
-    return adk.NewSupervisor(ctx, &adk.SupervisorConfig{
-        Name:      "KnowledgeSupervisor",
-        Model:     model,
-        Instruction: "你是知识总管。根据用户意图路由任务...",
-        SubAgents: []adk.Agent{retrievalAgent, writerAgent, organizerAgent},
-    })
-}
-```
-
-```mermaid
-sequenceDiagram
-    participant U as 用户
-    participant S as Supervisor
-    participant R as Retrieval Agent
-    participant W as Writer Agent
-
-    U->>S: "帮我整理最近关于 EINO 的笔记，<br/>写一篇学习综述"
-
-    S->>S: 意图分类 → 检索 + 写作（复合任务）
-
-    S->>R: 委派检索任务
-    R->>R: Tool: semantic_search("EINO") → 找到 5 篇
-    R->>R: Tool: find_related → 发现 3 篇关联笔记
-    R->>S: 返回 8 篇笔记及其内容
-
-    S->>W: 委派写作任务（附检索结果）
-    W->>W: 基于 8 篇笔记撰写综述草稿
-    W->>W: Tool: suggest_tags → ["eino", "agent", "go"]
-    W->>S: 返回综述 + 推荐标签
-
-    S->>U: 📝 综述全文 + 🏷️ 推荐标签 + 🔗 关联笔记
-```
-
----
-
-### 6. 进阶拓展方向
-
-> [!info] 掌握了基础架构后，可以探索这些方向
-
-1. **会话式检索**：支持多轮追问——"上次那篇关于 goroutine 的"→"不是那篇，是讲泄漏排查的"→ Agent 结合上下文逐步缩小范围，像和人对话一样自然。
-
-2. **定时知识回顾**：用 Cron 触发 Agent，每周自动检索本周新增笔记 → 生成"本周知识地图"→ 推送回顾通知。类似间隔重复，但由 AI 驱动。
-
-3. **跨源增强**：当本地笔记不足时，Agent 可调用 `web_search` 工具获取外部信息作为补充，生成"本地知识 + 外部参考"的混合回答，并标注来源。
-
-4. **知识冲突检测**：当新笔记与已有笔记表述矛盾（如某篇写"Go defer 是栈顺序"，另一篇写"是队列顺序"），Agent 自动标记冲突，提醒用户核实。
-
-5. **MCP 集成**：将工具标准化为 MCP Server，让其他 AI 客户端（如 Claude Desktop、VS Code 插件）也能直接调用你的知识助手。
-
----
-
-### 7. 关键 EINO 概念速查
-
-| EINO 概念 | 本项目对应 |
-|-----------|-----------|
-| `ChatModelAgent` | RetrievalAgent / WriterAgent / OrganizerAgent |
-| `Supervisor` | KnowledgeSupervisor（多 Agent 总调度） |
-| `Tool / ToolsNode` | 语义搜索、创建笔记、摘要、标签、关联发现 |
-| `Retriever` | 混合检索器（语义 + 标签过滤） |
-| `Embedding` | 文本向量化 |
-| `Indexer` | 笔记内容写入向量库 |
-| `Document Loader` | Markdown 笔记按段落分块加载 |
-| `ChatTemplate` | System Prompt + 检索结果注入 |
-| `Interrupt / Resume` | 删改操作前的确认拦截（进阶） |
-| `Graph / Compile` | 编排所有节点、编译成可执行图 |
-
----
-
-## 关联笔记
-
-- [[EINO ADK 深入]]
-

docs/Eino/Eino 知识索引.md

@@ -1,245 +0,0 @@
----
-tags: [eino, llm-framework, golang, agent, ai]
-create time: 2026-04-29 21:30
----
-
-# Eino 知识索引
-
-## 概述
-
-Eino 是字节跳动（CloudWeGo）开源的大模型应用开发框架，基于 Go 语言。覆盖从组件定义、流程编排到 DevOps 工具链的全流程。本文档作为知识索引，列举 Eino 的关键概念与使用入口，后续可基于此构建知识问答。
-
----
-
-## 一、是什么 —— Eino 核心定位
-
-| 维度 | 说明 |
-|------|------|
-| **语言** | Go（强类型，编译时类型检查） |
-| **定位** | 大模型应用开发框架，覆盖全流程 |
-| **仓库** | [github.com/cloudwego/eino](https://github.com/cloudwego/eino) + [eino-ext](https://github.com/cloudwego/eino-ext) |
-| **特色** | 组件抽象 → 图编排 → ADK Agent → DevOps 工具链，层层递进 |
-| **适用场景** | 从简单对话到复杂 Multi-Agent 系统，均可应对 |
-
-> [!question] 思考：为什么选 Go 而不是 Python？强类型在大模型应用规模化后能带来什么收益？
-
----
-
-## 二、怎么分层 —— Eino 架构分层
-
-```mermaid
-graph TD
-    A["Eino 框架"] --> B["组件层 Components"]
-    A --> C["编排层 Orchestration"]
-    A --> D["ADK 层 Agent 开发套件"]
-    A --> E["工具层 DevOps"]
-
-    B --> B1["ChatModel"]
-    B --> B2["ChatTemplate"]
-    B --> B3["Tool / ToolsNode"]
-    B --> B4["Retriever"]
-    B --> B5["Document Loader"]
-    B --> B6["Embedding / Indexer"]
-    B --> B7["Lambda 自定义"]
-
-    C --> C1["Chain 链式"]
-    C --> C2["Graph 有向图"]
-    C --> C3["Workflow 字段映射"]
-    C --> C4["Stream 流处理"]
-    C --> C5["Callback 横切面"]
-
-    D --> D1["Agent 接口"]
-    D --> D2["ChatModelAgent ReAct"]
-    D --> D3["WorkflowAgents"]
-    D --> D4["Multi-Agent 范式"]
-    D --> D5["Middleware 中间件"]
-
-    E --> E1["Tracing 链路追踪"]
-    E --> E2["IDE 插件 / 可视化"]
-    E --> E3["Debug 调试"]
-```
-
----
-
-## 三、怎么用 —— 快速上手路径
-
-### 3.1 入门四步走
-
-| 步骤 | 主题 | 入口文档 |
-|------|------|----------|
-| **Step 1** | ChatModel 与 Message：学会调模型 | [[Eino/quick_start/chapter_01_chatmodel_and_message]] |
-| **Step 2** | ChatModelAgent + Runner + AgentEvent：学会跑 Agent | [[Eino/quick_start/chapter_02_chatmodelagent_runner_agentevent]] |
-| **Step 3** | Memory & Session：让 Agent 有记忆 | [[Eino/quick_start/chapter_03_memory_and_session]] |
-| **Step 4** | Tool & FileSystem：让 Agent 能干活 | [[Eino/quick_start/chapter_04_tool_and_filesystem]] |
-
-### 3.2 进阶专题
-
-| 主题 | 关键内容 | 入口文档 |
-|------|----------|----------|
-| **Middleware** | 横切面注入，PlanTask / Summarization / Skill 等内置中间件 | [[Eino/quick_start/chapter_05_middleware]] |
-| **Callback & Trace** | 执行过程可观测、可追踪 | [[Eino/quick_start/chapter_06_callback_and_trace]] |
-| **Interrupt & Resume** | Human-in-the-loop，断点续跑 | [[Eino/quick_start/chapter_07_interrupt_resume]] |
-| **Graph & Tool** | 低代码编排，图即是工具 | [[Eino/quick_start/chapter_08_graph_tool]] |
-| **A2UI Protocol** | Agent 生成 UI 协议 | [[chapter_10_a2ui_protocol]] |
-| **Skill Console** | 技能注册与管理 | [[Eino/quick_start/chapter_09_skill_console]] |
-
----
-
-## 四、关键概念清单
-
-### 4.1 组件 Component
-
-| 组件 | 职责 | 为什么需要 |
-|------|------|-----------|
-| **ChatModel** | 与大模型交互的核心接口 | 统一不同模型（OpenAI / Ark / Gemini）的调用方式 |
-| **ChatTemplate** | 构造 Prompt 模板 | 将变量注入系统/用户消息，结构化管理 |
-| **Tool / ToolsNode** | 可被模型调用的工具 | 让 LLM 从"只会说"变成"能执行" |
-| **Retriever** | 检索外部知识 | RAG 的核心，给模型注入上下文 |
-| **Document Loader** | 加载各类文档 | 将 PDF / Markdown / 网页等转为可处理文本 |
-| **Embedding / Indexer** | 向量化 + 索引 | 语义检索基础 |
-| **Lambda** | 自定义函数作为组件 | 当现有组件不满足需求时，自由扩展 |
-
-> [!question] 思考：Lambda 和 Tool 的区别是什么？什么场景用哪个？
-
-### 4.2 编排 Orchestration
-
-| 编排方式 | 特点 | 适用场景 |
-|----------|------|----------|
-| **Chain** | 简单的顺序执行，有向无环 | 线性 Pipeline |
-| **Graph** | 有向图（可含环），灵活分支控制 | ReAct Agent 等复杂路由 |
-| **Workflow** | 字段级别的数据映射与传递 | 抖音场景：字段粒度的图映射 |
-
-额外能力：
-- **Stream 流处理**：自动处理流式输入输出，支持流的复制、合并、拼接
-- **Callback 横切面**：在组件执行前后注入逻辑（日志、追踪、统计）
-- **编译时类型检查**：Graph Compile 时验证节点类型对齐，而非运行时才发现
-
-### 4.3 ADK —— Agent 开发套件
-
-#### Agent 接口（统一抽象）
-
-```go
-type Agent interface {
-    Name(ctx context.Context) string
-    Description(ctx context.Context) string
-    Run(ctx context.Context, input *AgentInput, options ...AgentRunOption) *AsyncIterator[*AgentEvent]
-}
-```
-
-三个核心要素：**身份（Name）** + **职责（Description）** + **标准化执行（Run → AsyncIterator）**
-
-#### Agent 类型全景
-
-```mermaid
-graph LR
-    A["Agent 接口"] --> B["ChatModelAgent\nReAct 模式"]
-    A --> C["WorkflowAgents\n流程编排"]
-    A --> D["Multi-Agent\n协作范式"]
-    A --> E["自定义 Agent\n实现接口"]
-
-    C --> C1["Sequential\n顺序执行"]
-    C --> C2["Parallel\n并发执行"]
-    C --> C3["Loop\n循环执行"]
-
-    D --> D1["Supervisor\n集中式协调"]
-    D --> D2["Plan-Execute\n规划-执行-反思"]
-    D --> D3["DeepAgents\n规划驱动集中协作"]
-```
-
-| Agent 类型 | 一句话描述 | 典型场景 |
-|------------|-----------|----------|
-| **ChatModelAgent** | 基于 ReAct 的思考-行动循环 | 需要模型自主决策和工具调用的场景 |
-| **SequentialAgent** | 按顺序依次执行子 Agent | ETL 流水线、CI/CD |
-| **ParallelAgent** | 多个子 Agent 并发执行 | 多源数据采集、多渠道推送 |
-| **LoopAgent** | 循环执行直到满足退出条件 | 数据同步、迭代优化 |
-| **Supervisor** | 中心调度，统一分配与汇总 | 科研项目管理、客服流程 |
-| **Plan-Execute** | Planner → Executor → Replanner 闭环 | Excel 处理、多步骤推理 |
-| **DeepAgents** | Main Agent + WriteTodos + TaskTool | 长流程阶段性管理、多角色协作 |
-
-#### Agent 协作机制
-
-| 机制 | 使用方式 | 适用场景 |
-|------|---------|----------|
-| **History** | 框架自动传递前序 Agent 输出 | Agent 间默认信息流 |
-| **Shared Session** | KV 存储，`GetSessionValue` / `AddSessionValue` | 跨 Agent 共享状态 |
-| **Transfer（移交）** | `NewTransferToAgentAction` 将任务移交子 Agent | 边界清晰的层级式分工 |
-| **ToolCall（工具调用）** | `NewAgentTool` 将 Agent 封装为 Tool | 仅需参数、无需完整上下文时 |
-
-#### 中断与恢复
-
-- Agent 运行时通过 `Interrupt Action` 主动中断
-- `CheckPointStore` 保存断点状态
-- `Resume` 方法携带新信息从断点恢复
-- 适用场景：需要外部输入、人工审批、长时等待
-
-#### Middleware 中间件体系
-
-| 内置中间件 | 功能 |
-|------------|------|
-| **PlanTask** | 任务规划与拆解 |
-| **Summarization** | 上下文摘要压缩 |
-| **ToolSearch** | 动态工具搜索与选择 |
-| **ToolReduction** | 工具调用结果精简 |
-| **Skill** | 技能注册与匹配 |
-| **FileSystem** | 文件读写能力注入 |
-| **PatchToolCalls** | 工具调用修正 |
-
----
-
-## 五、实战案例索引
-
-| 案例 | 核心知识点 | 入口文档 |
-|------|-----------|----------|
-| **ReAct Agent** | Graph 编排 + Tool 调用 | [[Eino/docs/overview/eino_open_source]] |
-| **Excel Agent** | Plan-Execute + Multi-Agent + CodeAgent | [[Eino/docs/overview/eino_adk_excel_agent]] |
-| **项目管理 Agent** | Supervisor + 中断恢复 + Transfer | [[Eino/docs/overview/eino_adk0_1]] |
-| **字节内部实践** | 豆包、抖音等真实场景 | [[Eino/docs/overview/bytedance_eino_practice]] |
-
----
-
-## 六、进阶对比与选型
-
-| 对比维度 | Eino | LangChain / LlamaIndex |
-|----------|------|------------------------|
-| **语言** | Go（强类型） | Python（动态类型） |
-| **类型安全** | 编译时校验 | 运行时才发现 |
-| **长期维护** | 类型系统天然可维护 | 动态语言大型项目维护成本高 |
-| **并发模型** | goroutine 原生并发 | asyncio / 多线程 |
-| **编排能力** | Graph + Workflow 双模式 | LCEL + Graph |
-| **Agent 框架** | ADK 统一抽象 + 多种范式 | LangGraph Agent |
-
-> [!question] 思考：Eino 的 Graph vs Agent，什么时候直接用 Graph，什么时候用 ADK Agent？
-
----
-
-## 七、版本演进速览
-
-| 版本 | 关键变化 |
-|------|----------|
-| **v0.1** | 首个开源版本，核心组件 + Chain/Graph |
-| **v0.2** | Callback 体系完善 |
-| **v0.3** | 小幅 break change |
-| **v0.4** | Compose 优化 |
-| **v0.5** | ADK 实现 |
-| **v0.6** | JSON Schema 优化 |
-| **v0.7** | Interrupt/Resume 重构 |
-| **v0.8** | ADK Middleware 体系 |
-
----
-
-## 八、外部资源
-
-- 项目主页：[https://www.cloudwego.io](https://www.cloudwego.io)
-- GitHub：[https://github.com/cloudwego/eino](https://github.com/cloudwego/eino)
-- 扩展库：[https://github.com/cloudwego/eino-ext](https://github.com/cloudwego/eino-ext)
-- 示例：[https://github.com/cloudwego/eino-examples](https://github.com/cloudwego/eino-examples)
-- 文档：[https://www.cloudwego.io/zh/docs/eino/](https://www.cloudwego.io/zh/docs/eino/)
-
----
-
-## 关联笔记
-
-- [[Eino/docs/overview/eino_open_source]] — 开源发布文
-- [[Eino/docs/overview/eino_adk0_1]] — ADK 设计模式详解
-- [[Eino/docs/overview/eino_adk_excel_agent]] — Excel Agent 实战
-- [[Eino/quick_start/README]] — 快速开始总览

docs/Eino/docs/core_modules/_index.md

@@ -1,22 +0,0 @@
----
-Description: ""
-date: "2025-07-21"
-lastmod: ""
-tags: []
-title: 核心模块
-weight: 4
----
-
-Eino 中的核心模块有如下几个部分：
-
-- **Components 组件**：[Eino: Components 组件](/zh/docs/eino/core_modules/components)
-
-Eino 抽象出来的大模型应用中常用的组件，例如 `ChatModel`、`Embedding`、`Retriever` 等，这是实现一个大模型应用搭建的积木，是应用能力的基础，也是复杂逻辑编排时的原子对象。
-
-- **Chain/Graph 编排**：[Eino: Chain/Graph 编排功能](/zh/docs/eino/core_modules/chain_and_graph_orchestration/chain_graph_introduction)
-
-多个组件混合使用来实现业务逻辑的串联，Eino 提供 Chain/Graph 的编排方式，把业务逻辑串联的复杂度封装在了 Eino 内部，提供易于理解的业务逻辑编排接口，提供统一的横切面治理能力。
-
-- **Flow 集成工具 (agents)**: [Eino: Flow 集成组件](/zh/docs/eino/core_modules/flow_integration_components)
-
-Eino 把最常用的大模型应用模式封装成简单、易用的工具，让通用场景的大模型应用开发极致简化，目前提供了 `ReAct Agent` 和 `Host Multi Agent`。

docs/Eino/docs/core_modules/chain_and_graph_orchestration/_index.md

@@ -1,57 +0,0 @@
----
-Description: ""
-date: "2025-07-21"
-lastmod: ""
-tags: []
-title: Chain & Graph & Workflow 编排功能
-weight: 2
----
-
-在大模型应用中，`Components` 组件是提供 『原子能力』的最小单元，比如：
-
-- `ChatModel` 提供了大模型的对话能力
-- `Embedding` 提供了基于语义的文本向量化能力
-- `Retriever` 提供了关联内容召回的能力
-- `ToolsNode` 提供了执行外部工具的能力
-
-> 详细的组件介绍可以参考: [Eino: Components 组件](/zh/docs/eino/core_modules/components)
-
-一个大模型应用，除了需要这些原子能力之外，还需要根据场景化的业务逻辑，**对这些原子能力进行组合、串联**，这就是 **『编排』**。
-
-大模型应用的开发有其自身典型的特征： 自定义的业务逻辑本身不会很复杂，几乎主要都是对『原子能力』的组合串联。
-
-传统代码开发过程中，业务逻辑用 “代码的执行逻辑” 来表达，迁移到大模型应用开发中时，最直接想到的方法就是 “自行调用组件，自行把结果作为下一组件的输入进行调用”。这样的结果，就是 `代码杂乱`、`很难复用`、`没有切面能力`……
-
-当开发者们追求代码『**优雅**』和『**整洁之道**』时，就发现把传统代码组织方式用到大模型应用中时有着巨大的鸿沟。
-
-Eino 的初衷是让大模型应用开发变得非常简单，就一定要让应用的代码逻辑 “简单” “直观” “优雅” “健壮”。
-
-Eino 对「编排」有着这样的洞察：
-
-- 编排要成为在业务逻辑之上的清晰的一层，**不能让业务逻辑融入到编排中**。
-- 大模型应用的核心是 “对提供原子能力的组件” 进行组合串联，**组件是编排的 “第一公民”**。
-- 抽象视角看编排：编排是在构建一张网络，数据则在这个网络中流动，网络的每个节点都对流动的数据有格式/内容的要求，一个能顺畅流动的数据网络，关键就是 “**上下游节点间的数据格式是否对齐**？”。
-- 业务场景的复杂度会反映在编排产物的复杂性上，只有**横向的治理能力**才能让复杂场景不失控。
-- 大模型是会持续保持高速发展的，大模型应用也是，只有**具备扩展能力的应用才拥有生命力**。
-
-于是，Eino 提供了 “基于 Graph 模型 (node + edge) 的，以**组件**为原子节点的，以**上下游类型对齐**为基础的编排” 的解决方案。
-
-具体来说，实现了如下特性：
-
-- 一切以 “组件” 为核心，规范了业务功能的封装方式，让**职责划分变得清晰**，让**复用**变成自然而然
-  - 详细信息参考：[Eino: Components 组件](/zh/docs/eino/core_modules/components)
-- 业务逻辑复杂度封装到组件内部，编排层拥有更全局的视角，让**逻辑层次变得非常清晰**
-- 提供了切面能力，callback 机制支持了基于节点的**统一治理能力**
-  - 详细信息参考：[Eino: Callback 用户手册](/zh/docs/eino/core_modules/chain_and_graph_orchestration/callback_manual)
-- 提供了 call option 的机制，**扩展性**是快速迭代中的系统最基本的诉求
-  - 详细信息参考：[Eino: CallOption 能力与规范](/zh/docs/eino/core_modules/chain_and_graph_orchestration/call_option_capabilities)
-- 提供了 “类型对齐” 的开发方式的强化，降低开发者心智负担，把 golang 的**类型安全**特性发挥出来
-  - 详细信息参考：[Eino: 编排的设计理念](/zh/docs/eino/core_modules/chain_and_graph_orchestration/orchestration_design_principles)
-- 提供了 “**流的自动转换**” 能力，让 “流” 在「编排系统的复杂性来源榜」中除名
-  - 详细信息参考：[Eino 流式编程要点](/zh/docs/eino/core_modules/chain_and_graph_orchestration/stream_programming_essentials)
-
-Graph 本身是强大且语义完备的，可以用这项底层几乎绘制出所有的 “数据流动网络”，比如 “分支”、“并行”、“循环”。
-
-但 Graph 并不是没有缺点的，基于 “点” “边” 模型的 Graph 在使用时，要求开发者要使用 `graph.AddXXXNode()` 和 `graph.AddEdge()` 两个接口来创建一个数据通道，强大但是略显复杂。
-
-而在现实的大多数业务场景中，往往仅需要 “按顺序串联” 即可，因此，Eino 封装了接口更易于使用的 `Chain`。Chain 是对 Graph 的封装，除了 “环” 之外，Chain 暴露了几乎所有 Graph 的能力。

docs/Eino/docs/core_modules/chain_and_graph_orchestration/call_option_capabilities.md

@@ -1,306 +0,0 @@
----
-Description: ""
-date: "2025-11-20"
-lastmod: ""
-tags: []
-title: CallOption 能力与规范
-weight: 6
----
-
-**CallOption**: 对 Graph 编译产物进行调用时，直接传递数据给特定的一组节点(Component、Implementation、Node)的渠道
-
-- 和 节点 Config 的区别： 节点 Config 是实例粒度的配置，也就是从实例创建到实例消除，Config 中的值一旦确定就不需要改变了
-- CallOption：是请求粒度的配置，不同的请求，其中的值是不一样的。更像是节点入参，但是这个入参是直接由 Graph 的入口直接传入，而不是上游节点传入。
-  - 举例：给一个 ChatModel 节点传入 Temperature 配置；给一个 Lambda 节点传入自定义 option。
-
-## 组件 CallOption 形态
-
-组件 CallOption 配置，有两个粒度：
-
-- 组件的抽象(Abstract/Interface)统一定义的 CallOption 配置【组件抽象 CallOption】
-- 组件的实现(Type/Implementation)定义的该类型组件专用的 CallOption 配置【组件实现 CallOption】
-
-以 ChatModel 这个 Component 为例，介绍 CallOption 的形态
-
-### Model 抽象与实现的目录
-
-```
-// 抽象所在代码位置
-eino/components/model
-├── interface.go
-├── option.go // Component 抽象粒度的 CallOption 入参
-
-// 抽象实现所在代码位置
-eino-ext/components/model
-├── claude
-│   ├── option.go // Component 的一种实现的 CallOption 入参
-│   └── chatmodel.go
-├── ollama
-│   ├── call_option.go // Component 的一种实现的 CallOption 入参
-│   ├── chatmodel.go
-```
-
-### Model 抽象
-
-如上所述，在定义组件的 CallOption 时，需要区分【组件抽象 CallOption】、【组件实现 CallOption】两种场景。 而是否要提供 【组件实现 CallOption】，则是由 组件抽象 来决定的。
-
-组件抽象提供的 CallOption 扩展能力如下（以 Model 为例，其他组件类似）：
-
-```go
-package model
-
-type ChatModel interface {
-    Generate(ctx context.Context, input []*schema.Message, opts ...Option) (*schema.Message, error)
-    Stream(ctx context.Context, input []*schema.Message, opts ...Option) (
-       *schema.StreamReader[*schema.Message], error)
-
-    // BindTools bind tools to the model.
-    // BindTools before requesting ChatModel generally.
-    // notice the non-atomic problem of BindTools and Generate.
-    BindTools(tools []*schema.ToolInfo) error
-}
-
-// 此结构体是【组件抽象CallOption】的统一定义。 组件的实现可根据自己的需要取用【组件抽象CallOption】的信息
-// Options is the common options for the model.
-type Options struct {
-    // Temperature is the temperature for the model, which controls the randomness of the model.
-    Temperature *float32
-    // MaxTokens is the max number of tokens, if reached the max tokens, the model will stop generating, and mostly return an finish reason of "length".
-    MaxTokens *int
-    // Model is the model name.
-    Model *string
-    // TopP is the top p for the model, which controls the diversity of the model.
-    TopP *float32
-    // Stop is the stop words for the model, which controls the stopping condition of the model.
-    Stop []string
-}
-
-// Option is the call option for ChatModel component.
-type Option struct {
-    // 此字段是为【组件抽象CallOption】服务的 apply 方法，例如 WithTemperature
-    // 如果组件抽象不想提供【组件抽象CallOption】，可不提供此字段，同时不提供 GetCommonOptions() 方法
-    apply func(opts *Options)
-    
-    // 此字段是为【组件实现CallOption】服务的 apply 方法。并假设 apply 方法为：func(*T)
-    // 如果组件抽象不想提供【组件实现CallOption】，可不提供此字段，同时不提供 GetImplSpecificOptions() 方法
-    implSpecificOptFn any
-}
-
-// WithTemperature is the option to set the temperature for the model.
-func WithTemperature(temperature float32) Option {
-    return Option{
-       apply: func(opts *Options) {
-          opts.Temperature = &temperature
-       },
-    }
-}
-
-// WithMaxTokens is the option to set the max tokens for the model.
-func WithMaxTokens(maxTokens int) Option {
-    return Option{
-       apply: func(opts *Options) {
-          opts.MaxTokens = &maxTokens
-       },
-    }
-}
-
-// WithModel is the option to set the model name.
-func WithModel(name string) Option {
-    return Option{
-       apply: func(opts *Options) {
-          opts.Model = &name
-       },
-    }
-}
-
-// WithTopP is the option to set the top p for the model.
-func WithTopP(topP float32) Option {
-    return Option{
-       apply: func(opts *Options) {
-          opts.TopP = &topP
-       },
-    }
-}
-
-// WithStop is the option to set the stop words for the model.
-func WithStop(stop []string) Option {
-    return Option{
-       apply: func(opts *Options) {
-          opts.Stop = stop
-       },
-    }
-}
-
-// GetCommonOptions extract model Options from Option list, optionally providing a base Options with default values.
-func GetCommonOptions(base *Options, opts ...Option) *Options {
-    if base == nil {
-       base = &Options{}
-    }
-
-    for i := range opts {
-       opt := opts[i]
-       if opt.apply != nil {
-          opt.apply(base)
-       }
-    }
-
-    return base
-}
-
-// 组件实现方基于此方法，封装自己的Option函数：func WithXXX(xxx string) Option{}
-func WrapImplSpecificOptFn[T any](optFn func(*T)) Option {
-    return Option{
-       implSpecificOptFn: optFn,
-    }
-}
-
-// GetImplSpecificOptions provides tool author the ability to extract their own custom options from the unified Option type.
-// T: the type of the impl specific options struct.
-// This function should be used within the tool implementation's InvokableRun or StreamableRun functions.
-// It is recommended to provide a base T as the first argument, within which the tool author can provide default values for the impl specific options.
-func GetImplSpecificOptions[T any](base *T, opts ...Option) *T {
-    if base == nil {
-       base = new(T)
-    }
-
-    for i := range opts {
-       opt := opts[i]
-       if opt.implSpecificOptFn != nil {
-          optFn, ok := opt.implSpecificOptFn.(func(*T))
-          if ok {
-             optFn(base)
-          }
-       }
-    }
-
-    return base
-}
-```
-
-### Claude 实现
-
-[https://github.com/cloudwego/eino-ext/blob/main/components/model/claude/option.go](https://github.com/cloudwego/eino-ext/blob/main/components/model/claude/option.go)
-
-```go
-package claude
-
-import (
-    "github.com/cloudwego/eino/components/model"
-)
-
-type options struct {
-    TopK *int32
-}
-
-func WithTopK(k int32) model.Option {
-    return model.WrapImplSpecificOptFn(func(o *options) {
-       o.TopK = &k
-    })
-}
-```
-
-[https://github.com/cloudwego/eino-ext/blob/main/components/model/claude/claude.go](https://github.com/cloudwego/eino-ext/blob/main/components/model/claude/claude.go)
-
-```go
-func (c *claude) genMessageNewParams(input []*schema.Message, opts ...model.Option) (anthropic.MessageNewParams, error) {
-    if len(input) == 0 {
-       return anthropic.MessageNewParams{}, fmt.Errorf("input is empty")
-    }
-
-    commonOptions := model.GetCommonOptions(&model.Options{
-       Model:       &c.model,
-       Temperature: c.temperature,
-       MaxTokens:   &c.maxTokens,
-       TopP:        c.topP,
-       Stop:        c.stopSequences,
-    }, opts...)
-    claudeOptions := model.GetImplSpecificOptions(&options{TopK: c.topK}, opts...)
-    
-    // omit mulple lines...
-    return nil, nil 
-}
-```
-
-## 编排中的 CallOption
-
-[https://github.com/cloudwego/eino/blob/main/compose/runnable.go](https://github.com/cloudwego/eino/blob/main/compose/runnable.go)
-
-Graph 编译产物是 Runnable
-
-```go
-type Runnable[I, O any] interface {
-    Invoke(ctx context.Context, input I, opts ...Option) (output O, err error)
-    Stream(ctx context.Context, input I, opts ...Option) (output *schema.StreamReader[O], err error)
-    Collect(ctx context.Context, input *schema.StreamReader[I], opts ...Option) (output O, err error)
-    Transform(ctx context.Context, input *schema.StreamReader[I], opts ...Option) (output *schema.StreamReader[O], err error)
-}
-```
-
-Runnable 各方法均接收 compose.Option 列表。
-
-[https://github.com/cloudwego/eino/blob/main/compose/graph_call_options.go](https://github.com/cloudwego/eino/blob/main/compose/graph_call_options.go)
-
-包括 graph run 整体的配置，各类组件的配置，特定 Lambda 的配置等。
-
-```go
-// Option is a functional option type for calling a graph.
-type Option struct {
-    options []any
-    handler []callbacks.Handler
-
-    paths []*NodePath
-
-    maxRunSteps int
-}
-
-// DesignateNode set the key of the node which will the option be applied to.
-// notice: only effective at the top graph.
-// e.g.
-//
-//  embeddingOption := compose.WithEmbeddingOption(embedding.WithModel("text-embedding-3-small"))
-//  runnable.Invoke(ctx, "input", embeddingOption.DesignateNode("my_embedding_node"))
-func (o Option) DesignateNode(key ...string) Option {
-    nKeys := make([]*NodePath, len(key))
-    for i, k := range key {
-       nKeys[i] = NewNodePath(k)
-    }
-    return o.DesignateNodeWithPath(nKeys...)
-}
-
-// DesignateNodeWithPath sets the path of the node(s) to which the option will be applied to.
-// You can make the option take effect in the subgraph by specifying the key of the subgraph.
-// e.g.
-// DesignateNodeWithPath({"sub graph node key", "node key within sub graph"})
-func (o Option) DesignateNodeWithPath(path ...*NodePath) Option {
-    o.paths = append(o.paths, path...)
-    return o
-}
-
-// WithEmbeddingOption is a functional option type for embedding component.
-// e.g.
-//
-//  embeddingOption := compose.WithEmbeddingOption(embedding.WithModel("text-embedding-3-small"))
-//  runnable.Invoke(ctx, "input", embeddingOption)
-func WithEmbeddingOption(opts ...embedding.Option) Option {
-    return withComponentOption(opts...)
-}
-```
-
-compose.Option 可以按需分配给 Graph 中不同的节点。
-
-<a href="/img/eino/graph_runnable_after_compile.png" target="_blank"><img src="/img/eino/graph_runnable_after_compile.png" width="100%" /></a>
-
-```go
-// 所有节点都生效的 call option
-compiledGraph.Invoke(ctx, input, WithCallbacks(handler))
-
-// 只对特定类型节点生效的 call option
-compiledGraph.Invoke(ctx, input, WithChatModelOption(WithTemperature(0.5))
-compiledGraph.Invoke(ctx, input, WithToolOption(WithXXX("xxx"))
-
-// 只对特定节点生效的 call option
-compiledGraph.Invoke(ctx, input, WithCallbacks(handler).DesignateNode("node_1"))
-
-// 只对特定内部嵌套图或其中节点生效的 Call option
-compiledGraph.Invoke(ctx, input, WithCallbacks(handler).DesignateNodeWithPath(NewNodePath("1", "2"))
-```

docs/Eino/docs/core_modules/chain_and_graph_orchestration/callback_manual.md

@@ -1,738 +0,0 @@
----
-Description: ""
-date: "2026-03-02"
-lastmod: ""
-tags: []
-title: Callback 用户手册
-weight: 5
----
-
-## 解决的问题
-
-Component（包括 Lambda）、Graph 编排共同解决“把业务逻辑定义出来”的问题。而 logging, tracing, metrics, 上屏展示等横切面性质的功能，需要有机制把功能注入到 Component（包括 Lambda）、Graph 中。
-
-另一方面，用户可能想拿到某个具体 Component 实现的执行过程中的中间信息，比如 VikingDBRetriever 额外给出查询的 DB Name，ArkChatModel 额外给出请求的 temperature 等参数。需要有机制把中间状态透出。
-
-Callbacks 支持“**横切面功能注入**”和“**中间状态透出**”，具体是：用户提供、注册“function”（Callback Handler），Component 和 Graph 在固定的“时机”（或者说切面、位点）回调这些 function，给出对应的信息。
-
-## 核心概念
-
-核心概念串起来，就是：Eino 中的 Component 和 Graph 等**实体**，在固定的**时机** (Callback Timing)，回调用户提供的 **function** (Callback Handler)，并把**自己是谁** (RunInfo)，以及**当时发生了什么** (Callback Input & Output) 传出去。
-
-### 触发实体
-
-Component（包括官方定义的组件类型和 Lambda），Graph Node（以及 Chain/Workflow Node），Graph 自身（以及 Chain/Workflow）。这三类实体，都有横切面功能注入、中间状态透出的需求，因此都会触发 callback。具体见下面的“[触发方式](/zh/docs/eino/core_modules/chain_and_graph_orchestration/callback_manual)”一节。
-
-### 触发时机
-
-```go
-// CallbackTiming enumerates all the timing of callback aspects.
-type CallbackTiming = callbacks.CallbackTiming
-
-const (
-    TimingOnStart CallbackTiming = iota // 进入并开始执行
-    TimingOnEnd // 成功完成即将 return
-    TimingOnError // 失败并即将 return err 
-    TimingOnStartWithStreamInput // OnStart，但是输入是 StreamReader
-    TimingOnEndWithStreamOutput // OnEnd，但是输出是 StreamReader
-)
-```
-
-不同的触发实体，在不同场景下，是触发 OnStart 还是 OnStartWithStreamInput  (OnEnd/OnEndWithStreamOutput 同理），具体的规则，详见下面的“[触发方式](/zh/docs/eino/core_modules/chain_and_graph_orchestration/callback_manual)”一节。
-
-### Callback Handler
-
-```go
-type Handler interface {
-    OnStart(ctx context.Context, info *RunInfo, input CallbackInput) context.Context
-    OnEnd(ctx context.Context, info *RunInfo, output CallbackOutput) context.Context
-    OnError(ctx context.Context, info *RunInfo, err error) context.Context
-    OnStartWithStreamInput(ctx context.Context, info *RunInfo,
-       input *schema.StreamReader[CallbackInput]) context.Context
-    OnEndWithStreamOutput(ctx context.Context, info *RunInfo,
-       output *schema.StreamReader[CallbackOutput]) context.Context
-}
-```
-
-一个 Handler 是一个实现了上面 5 个方法（对应 5 个触发时机）的结构体。每个方法都会接收三个信息：
-
-- Context: 用于**接收同一个 Handler 的前序触发时机**可能设置的定制信息。
-- RunInfo: 触发回调的实体元信息。
-- Input/Output/InputStream/OutputStream: 触发回调时的业务信息。
-
-并都会返回新的 Context：用于**同一个 Handler 的不同触发时机之间**传递信息。
-
-如果一个 Handler，不想关注所有的 5 个触发时机，只想关注一部分，比如只关注 OnStart，建议使用 `NewHandlerBuilder().OnStartFn(...).Build()`。如果不想关注所有的组件类型，只想关注特定组件，比如 ChatModel，建议使用 `NewHandlerHelper().ChatModel(...).Handler()`，可以只接收 ChatModel 的回调并拿到一个具体类型的 CallbackInput/CallbackOutput。具体见“[Handler 实现方式](/zh/docs/eino/core_modules/chain_and_graph_orchestration/callback_manual)”一节。
-
-不同 Handler 之间，触发顺序**没有**保证。
-
-### RunInfo
-
-描述了触发 Callback 的实体自身的元信息。
-
-```go
-// RunInfo contains information about the running component that triggers callbacks.
-type RunInfo struct {
-    Name      string               // the 'Name' with semantic meaning for the running component, specified by end-user
-    Type      string               // the specific implementation 'Type' of the component, e.g. 'OpenAI'
-    Component components.Component // the component abstract type, e.g. 'ChatModel'
-}
-```
-
-- Name：有业务含义的名称，需用户指定，不指定就是空字符串。对不同的触发实体：
-  - Component：在 Graph 中时，用 Node Name。在 Graph 外单独的使用时，用户手动设置。详见“注入 RunInfo” 和 “单独使用 Component”
-  - Graph Node：用 Node Name `func WithNodeName(n string) GraphAddNodeOpt`
-  - Graph 自身：
-    - 顶层图用 Graph Name `func WithGraphName(graphName string) GraphCompileOption`
-    - 内部嵌套图，会用加入到上级图时添加的 Node Name
-- Type：组件具体实现来规定：
-  - 有接口的 Component：如果实现了 Typer 接口，用 GetType() 方法的结果。否则用反射获取 Struct/Func 名。
-  - Lambda：如果用 `func WithLambdaType(t string) LambdaOpt` 指定了 Type，用这个，否则是空字符串。
-  - Graph Node：用内部 Component/Lambda/Graph 的值。
-  - Graph 自身：空字符串。
-- Component:
-  - 有接口的 Component：是啥接口，就是啥
-  - Lambda：固定值 Lambda
-  - Graph Node: 用内部的 Component/Lambda/Graph 的值。
-  - Graph 自身：固定值 Graph / Chain / Workflow. （之前曾有 StateGraph / StateChain ，现已整合到 Graph / Chain 中）
-
-### Callback Input & Output
-
-本质是任意类型，因为不同的 Component 的输入输出、内部状态完全不同。
-
-```go
-type CallbackInput any
-type CallbackOutput any
-```
-
-具体到某个组件，有更具体的类型，比如 Chat Model
-
-```go
-// CallbackInput is the input for the model callback.
-type CallbackInput struct {
-    // Messages is the messages to be sent to the model.
-    Messages []*schema.Message
-    // Tools is the tools to be used in the model.
-    Tools []*schema.ToolInfo
-    // Config is the config for the model.
-    Config *Config
-    // Extra is the extra information for the callback.
-    Extra map[string]any
-}
-
-// CallbackOutput is the output for the model callback.
-type CallbackOutput struct {
-    // Message is the message generated by the model.
-    Message *schema.Message
-    // Config is the config for the model.
-    Config *Config
-    // TokenUsage is the token usage of this request.
-    TokenUsage *TokenUsage
-    // Extra is the extra information for the callback.
-    Extra map[string]any
-}
-```
-
-在 Chat Model 的具体实现，比如 OpenAI Chat Model 中，建议组件作者向 Callback Handler 中传入具体的 Input/Output 类型，而不是 Any。这样可以透出更具体的、定制化的中间状态信息。
-
-如果是 Graph Node 来触发 Callback，因为 Node 拿不到组件内部中间状态信息，只能拿到组件接口中规定的输入和输出，所以给 Callback Handler 的只能是这些。对 Chat Model，就是 []*schema.Message 和 *schema.Message。
-
-Graph 自身触发 Callback 时，输入输出就是 Graph 整体的输入和输出。
-
-## 注入 Handler
-
-Handler 需要注入到 Context 中才能被触发。
-
-### 全局注入 Handler
-
-通过 `callbacks.AppendGlobalHandlers` 注入全局的 Handler。注入后，所有的触发回调行为，都会自动触发这些全局的 Handler。典型的场景是 tracing，logging 等全局一致、业务场景无关的功能。
-
-不是并发安全的。建议在服务初始化时注入一次。
-
-### 向 Graph 中注入 Handler
-
-通过 `compose.WithCallbacks` 在 graph 运行时注入 Handler，这些 Handler 会在 graph 的本次运行整体上生效，包括 Graph 内各 Node 和 Graph 自身（以及各内嵌的 graph）。
-
-通过 `compose.WithCallbacks(...).DesignateNode(...)` 向顶层 Graph 的某个 Node 注入 Handler。当这个 Node 自身是个内嵌的 Graph 时，会注入到这个内嵌 Graph 自身和其内部的各 Node。
-
-通过 `compose.WithCallbacks(...).DesignateNodeWithPath(...)` 向内部嵌套的 Graph 的某个 Node 注入 Handler。
-
-### 在 Graph 外注入 Handler
-
-不想使用 Graph，但却想使用 Callback，则：
-
-通过 `InitCallbacks(ctx context.Context, info *RunInfo, handlers ...Handler)` 获取一个新的 Context 并注入 Handlers 以及 RunInfo。
-
-### Handler 继承
-
-与子 Context 继承父 Context 中的所有 Values 相同，子 Context 也会继承父 Context 中的所有 Handlers。举个例子，Graph 运行时传入的 Context 中如果已经有了 Handler，则这些 Handlers 都会被整个 Graph 的这次运行继承和生效。
-
-## 注入 RunInfo
-
-RunInfo 也需要注入到 Context 中，才会在触发回调时给到 Handler。
-
-### Graph 托管 RunInfo
-
-Graph 会为内部所有的 Node 自动注入 RunInfo。机制是每个 Node 的运行，都是一个新的子 Context，Graph 向这个新的 Context 中注入对应 Node 的 RunInfo。
-
-### 在 Graph 外注入 RunInfo
-
-不想使用 Graph，但却想使用 Callback，则：
-
-通过 `InitCallbacks(ctx context.Context, info *RunInfo, handlers ...Handler)` 获取一个新的 Context 并注入 Handlers 以及 RunInfo。
-
-通过 `ReuseHandlers(ctx context.Context, info *RunInfo)` 来获取一个新的 Context，复用之前 Context 中的 Handler，并设置新的 RunInfo。
-
-## 触发方式
-
-<a href="/img/eino/graph_node_callback_run_place.png" target="_blank"><img src="/img/eino/graph_node_callback_run_place.png" width="100%" /></a>
-
-### 组件实现内部触发(Component Callback)
-
-在组件实现的代码中，调用 callbacks 包中的 `OnStart(), OnEnd(), OnError(), OnStartWithStreamInput(), ``OnEndWithStreamOutput``()`。以 Ark 的 ChatModel 实现为例，在 Generate 方法中：
-
-```go
-func (cm *ChatModel) Generate(ctx context.Context, in []*schema.Message, opts ...fmodel.Option) (
-    outMsg *schema.Message, err error) {
-
-    defer func() {
-       if err != nil {
-          _ = callbacks.OnError(ctx, err)
-       }
-    }()
-
-    // omit multiple lines... instantiate req conf
-        
-    ctx = callbacks.OnStart(ctx, &fmodel.CallbackInput{
-       Messages:   in,
-       Tools:      append(cm.rawTools), // join tool info from call options
-       ToolChoice: nil,                 // not support in api
-       Config:     reqConf,
-    })
-
-    // omit multiple lines... invoke Ark chat API and get the response
-    
-    _ = callbacks.OnEnd(ctx, &fmodel.CallbackOutput{
-       Message:    outMsg,
-       Config:     reqConf,
-       TokenUsage: toModelCallbackUsage(outMsg.ResponseMeta),
-    })
-
-    return outMsg, nil
-}
-```
-
-在 Stream 方法中：
-
-```go
-func (cm *ChatModel) Stream(ctx context.Context, in []*schema.Message, opts ...fmodel.Option) ( // byted_s_too_many_lines_in_func
-    outStream *schema.StreamReader[*schema.Message], err error) {
-
-    defer func() {
-       if err != nil {
-          _ = callbacks.OnError(ctx, err)
-       }
-    }()
-    
-    // omit multiple lines... instantiate req conf
-
-    ctx = callbacks.OnStart(ctx, &fmodel.CallbackInput{
-       Messages:   in,
-       Tools:      append(cm.rawTools), // join tool info from call options
-       ToolChoice: nil,                 // not support in api
-       Config:     reqConf,
-    })
-    
-    // omit multiple lines... make request to Ark API and convert response stream to StreamReader[model.*CallbackOutput]
-
-    _, sr = callbacks.OnEndWithStreamOutput(ctx, sr)
-
-    return schema.StreamReaderWithConvert(sr,
-       func(src *fmodel.CallbackOutput) (*schema.Message, error) {
-          if src.Message == nil {
-             return nil, schema.ErrNoValue
-          }
-
-          return src.Message, nil
-       },
-    ), nil
-}
-```
-
-可以看到 Generate 调用时，触发的是 OnEnd，而 Stream 调用时，触发的是 OneEndWithStreamOutput：
-
-组件实现内部触发 Callbacks 时:
-
-- **当组件输入为 StreamReader 时，触发 OnStartWithStreamInput，否则触发 OnStart**
-- **当组件输出为 StreamReader 时，触发 OnEndWithStreamOutput，否则触发 OnEnd**
-
-内部实现了 callback 触发的组件，应当实现 Checker 接口，IsCallbacksEnabled 返回 true，向外部传达“我内部实现了 callback 触发”的信息：
-
-```go
-// Checker tells callback aspect status of component's implementation
-// When the Checker interface is implemented and returns true, the framework will not start the default aspect.
-// Instead, the component will decide the callback execution location and the information to be injected.
-type Checker interface {
-    IsCallbacksEnabled() bool
-}
-```
-
-如果一个组件实现，没有实现 Checker 接口，或者 IsCallbacksEnabled 返回  false，可以认为该组件内部没有触发回调，需要 Graph Node 来负责注入和触发（在 Graph 内使用时）。
-
-### Graph Node 触发(Node Callback)
-
-当一个 Component 被编排入 Graph 时，成为一个 Node。这时，如果 Component 自身会触发 callback，Node 就复用 Component 的 callback 处理。否则，Node 会在 Component 外面埋上 callback handler 触发点位。这些点位与 Component 自身的流式范式对应。比如一个 ChatModelNode，会在 Generate 方法外面埋上 OnStart/OnEnd/OnError，同时会在 Stream 方法外面埋上 OnStart/OnEndWithStreamOutput/OnError。
-
-在 Graph 运行时，各组件会以 Invoke 或 Transform 范式运行，又会根据组件具体实现的业务流式范式，调用对应的组件方法。比如 Graph 以 Invoke 运行，Chat Model Node 会以 Invoke 运行，调用 Generate 方法。而当 Graph 以 Stream 运行，Chat Model Node 会以 Transform 运行，但 Chat Model 的业务流式范式中没有 Transform，会自动降级成调用 Stream 方法。因此：
-
-**Graph Node 具体触发哪个位点（OnStart 还是 OnStartWithStreamInput），取决于组件实现的业务流式范式和 Graph 运行方式两个因素。**
-
-关于 Eino 流式编程的详细介绍，参见 [Eino 流式编程要点](/zh/docs/eino/core_modules/chain_and_graph_orchestration/stream_programming_essentials)
-
-### Graph 自身触发(Graph Callback)
-
-Graph 在自身的开始、结束、err 的时机触发 Callback Handler。如果 Graph 以 Invoke 形式调用，触发 OnStart/OnEnd/OnError。如果以 Stream/Collect/Transform 形式调用，触发 OnStartWithStreamInput/OnEndWithStreamOutput/OnError。这是因为 **Graph 内部会始终以 Invoke 或 Transform 执行**。参见 [Eino 流式编程要点](/zh/docs/eino/core_modules/chain_and_graph_orchestration/stream_programming_essentials)
-
-值得注意的是：graph 也是 component 的一种，因此 graph callback 也是 component callback 的一种特殊形式。根据 Node Callback 的定义，当 Node 内部的 component 实现了对触发时机的感知和处理时，Node 会直接复用 Component 的实现，不会再实现 Node Callback。这意味着当一个 graph 通过 AddGraphNode 的方式加入到另外一个 Graph 中作为一个 Node 时，这个 Node 会复用内部 graph 的 graph callback。
-
-## 解析 Callback Input & Output
-
-从上文得知，Callback Input & Output 的底层是 Any，只是不同组件类型在具体触发回调时，可能会传入自己特定的类型。并且 Callback Handler 的接口定义中，各方法的入参也是 Any 类型的 Callback Input & Output。
-
-因此，具体的 Handler 实现中，需要做两个事情：
-
-1. 根据 RunInfo 判断当前触发回调的是哪个组件类型，比如 RunInfo.Component == "ChatModel"，或者 RunInfo.Type == "xxx Chat Model"。
-2. 把 any 类型的 Callback Input & Output 转成对应的具体类型，以 RunInfo.Component == "ChatModel" 为例：
-
-```go
-// ConvCallbackInput converts the callback input to the model callback input.
-func ConvCallbackInput(src callbacks.CallbackInput) *CallbackInput {
-    switch t := src.(type) {
-    case *CallbackInput: // when callback is triggered within component implementation, the input is usually already a typed *model.CallbackInput
-       return t
-    case []*schema.Message: // when callback is injected by graph node, not the component implementation itself, the input is the input of Chat Model interface, which is []*schema.Message
-       return &CallbackInput{
-          Messages: t,
-       }
-    default:
-       return nil
-    }
-}
-
-// ConvCallbackOutput converts the callback output to the model callback output.
-func ConvCallbackOutput(src callbacks.CallbackOutput) *CallbackOutput {
-    switch t := src.(type) {
-    case *CallbackOutput: // when callback is triggered within component implementation, the output is usually already a typed *model.CallbackOutput
-       return t
-    case *schema.Message: // when callback is injected by graph node, not the component implementation itself, the output is the output of Chat Model interface, which is *schema.Message
-       return &CallbackOutput{
-          Message: t,
-       }
-    default:
-       return nil
-    }
-}
-```
-
-如果 Handler 里面需要增加 switch case 来判断 RunInfo.Component，并且对每一个 case，需要调对应的转换函数把 Any 转成具体类型，确实有些复杂。为了减少写胶水代码的重复劳动，我们提供了两种实现 Handler 的便捷工具函数。
-
-## Handler 实现方式
-
-除了直接实现 Handler 接口外，Eino 提供了两种 Handler 的便捷实现工具。
-
-### HandlerHelper
-
-如果用户的  Handler 只关注特定类型的组件，比如 ReactAgent 的场景，只关注 ChatModel 和 Tool，建议使用 HandlerHelper 来快速创建具体类型的 Callback Handler：
-
-```go
-import ucb "github.com/cloudwego/eino/utils/callbacks"
-
-handler := ucb.NewHandlerHelper().ChatModel(modelHandler).Tool(toolHandler).Handler()
-```
-
-其中 modelHandler 是 Chat Model 组件对 callback handler 的进一步封装：
-
-```go
-// from package utils/callbacks
-
-// ModelCallbackHandler is the handler for the model callback.
-type ModelCallbackHandler struct {
-    OnStart               func(ctx context.Context, runInfo *callbacks.RunInfo, input *model.CallbackInput) context.Context
-    OnEnd                 func(ctx context.Context, runInfo *callbacks.RunInfo, output *model.CallbackOutput) context.Context
-    OnEndWithStreamOutput func(ctx context.Context, runInfo *callbacks.RunInfo, output *schema.StreamReader[*model.CallbackOutput]) context.Context
-    OnError               func(ctx context.Context, runInfo *callbacks.RunInfo, err error) context.Context
-}
-```
-
-上面的 ModelCallbackHandler，封装了三个操作：
-
-1. 不再需要判断 RunInfo.Component 来选择属于 ChatModel 触发的回调，而是已经自动做了过滤。
-2. 只要求实现 Chat Model 这个组件支持的触发时机，这里去掉了不支持的 OnStartWithStreamInput。同时，如果用户只关注 Chat Model 支持的四个时机的某几个，比如只有 OnStart，也可以只实现 OnStart。
-3. Input / Output 不再是 Any 类型，而是已经转化好的 model.CallbackInput, model.CallbackOutput。
-
-HandlerHelper 支持全部的官方组件，目前的列表是：ChatModel, ChatTemplate, Retriever, Indexer, Embedding, Document.Loader, Document.Transformer, Tool, ToolsNode.
-
-针对 Lambda，Graph，Chain 这些输入输出类型不确定的“组件”，也可以使用 HandlerHelper，但是只能做到上面的第 1 点，即按照组件类型做自动的过滤，2、3 点依然需要用户自己实现：
-
-```go
-import ucb "github.com/cloudwego/eino/utils/callbacks"
-
-handler := ucb.NewHandlerHelper().Lambda(callbacks.Handler).Graph(callbacks.Handler)...Handler()
-```
-
-这时，NewHandlerHelper().Lambda() 需要传入 callbacks.Handler 可以用下面的 HandlerBuilder 来实现。
-
-### HandlerBuilder
-
-如果用户的 Handler 需要关注多个组件类型，但却只需要关注部分的触发时机，可以使用 HandlerBuilder：
-
-```go
-import "github.com/cloudwego/eino/callbacks"
-
-handler := callbacks.NewHandlerBuilder().OnStartFn(fn)...Build()
-```
-
-## 最佳实践
-
-### 在 Graph 中使用
-
-- 积极使用 Global Handlers，注册始终生效的 Handlers。
-
-```go
-package main
-
-import (
-        "context"
-        "log"
-
-        "github.com/cloudwego/eino/callbacks"
-        "github.com/cloudwego/eino/compose"
-)
-
-func main() {
-        // Build a simple global handler
-        handler := callbacks.NewHandlerBuilder().
-                OnStartFn(func(ctx context.Context, info *callbacks.RunInfo, input callbacks.CallbackInput) context.Context {
-                        log.Printf("[Global Start] component=%s name=%s input=%T", info.Component, info.Name, input)
-                        return ctx
-                }).
-                OnEndFn(func(ctx context.Context, info *callbacks.RunInfo, output callbacks.CallbackOutput) context.Context {
-                        log.Printf("[Global End] component=%s name=%s output=%T", info.Component, info.Name, output)
-                        return ctx
-                }).
-                OnErrorFn(func(ctx context.Context, info *callbacks.RunInfo, err error) context.Context {
-                        log.Printf("[Global Error] component=%s name=%s err=%v", info.Component, info.Name, err)
-                        return ctx
-                }).
-                Build()
-
-        // Register as global callbacks (applies to all subsequent runs)
-        callbacks.AppendGlobalHandlers(handler)
-
-        // Example graph usage; the global handler will be invoked automatically
-        g := compose.NewGraph[string, string]()
-        // ... add nodes/edges ...
-        r, _ := g.Compile(context.Background())
-        _, _ = r.Invoke(context.Background(), "hello") // triggers global callbacks
-}
-```
-
-- 通过 WithHandlers option 在运行时注入 Handler，通过 DesignateNode 或 DesignateNodeByPath 指定生效的 Node / 嵌套的内部 Graph / 内部 Graph 的 Node。
-
-```go
-package main
-
-import (
-        "context"
-
-        "github.com/cloudwego/eino/callbacks"
-        "github.com/cloudwego/eino/compose"
-        "github.com/cloudwego/eino/components/prompt"
-        "github.com/cloudwego/eino/schema"
-)
-
-func main() {
-        ctx := context.Background()
-
-        top := compose.NewGraph[map[string]any, []*schema.Message]()
-        sub := compose.NewGraph[map[string]any, []*schema.Message]()
-        _ = sub.AddChatTemplateNode("tmpl_nested", prompt.FromMessages(schema.FString, schema.UserMessage("Hello, {name}!")))
-        _ = sub.AddEdge(compose.START, "tmpl_nested")
-        _ = sub.AddEdge("tmpl_nested", compose.END)
-        _ = top.AddGraphNode("sub_graph", sub)
-        _ = top.AddEdge(compose.START, "sub_graph")
-        _ = top.AddEdge("sub_graph", compose.END)
-        r, _ := top.Compile(ctx)
-
-        optGlobal := compose.WithCallbacks(
-                callbacks.NewHandlerBuilder().OnEndFn(func(ctx context.Context, _ *callbacks.RunInfo, _ callbacks.CallbackOutput) context.Context { return ctx }).Build(),
-        )
-        optNode := compose.WithCallbacks(
-                callbacks.NewHandlerBuilder().OnStartFn(func(ctx context.Context, _ *callbacks.RunInfo, _ callbacks.CallbackInput) context.Context { return ctx }).Build(),
-        ).DesignateNode("sub_graph")
-        optNested := compose.WithChatTemplateOption(
-                prompt.WrapImplSpecificOptFn(func(_ *struct{}) {}),
-        ).DesignateNodeWithPath(
-                compose.NewNodePath("sub_graph", "tmpl_nested"),
-        )
-
-        _, _ = r.Invoke(ctx, map[string]any{"name": "Alice"}, optGlobal, optNode, optNested)
-}
-```
-
-### 在 Graph 外使用
-
-这个场景是：不使用 Graph/Chain/Workflow 等编排能力，单独用代码去调用 ChatModel/Tool/Lambda 等各种组件，且希望这些组件能成功触发 Callback Handlers。
-
-此场景需要用户解决的问题是：手动设置正确的 RunInfo 和 Handlers，因为没有 Graph 来帮助用户自动设置 RunInfo 和 Handlers 了。
-
-完整示例：
-
-```go
-package main
-
-import (
-        "context"
-
-        "github.com/cloudwego/eino/callbacks"
-        "github.com/cloudwego/eino/compose"
-)
-
-func innerLambda(ctx context.Context, input string) (string, error) {
-        // 作为 ComponentB 的实现方：进入组件时补默认 RunInfo（Name 无法给默认值）
-        ctx = callbacks.EnsureRunInfo(ctx, "Lambda", compose.ComponentOfLambda)
-        ctx = callbacks.OnStart(ctx, input)
-        out := "inner:" + input
-        ctx = callbacks.OnEnd(ctx, out)
-        return out, nil
-}
-
-func outerLambda(ctx context.Context, input string) (string, error) {
-        // 作为 ComponentA 的实现方：进入组件时补默认 RunInfo
-        ctx = callbacks.EnsureRunInfo(ctx, "Lambda", compose.ComponentOfLambda)
-        ctx = callbacks.OnStart(ctx, input)
-
-        // 推荐：调用前替换 RunInfo，确保内层组件拿到正确的 name/type/component
-        ctxInner := callbacks.ReuseHandlers(ctx,
-                &callbacks.RunInfo{Name: "ComponentB", Type: "Lambda", Component: compose.ComponentOfLambda},
-        )
-        out1, _ := innerLambda(ctxInner, input) // 内层 RunInfo.Name = "ComponentB"
-
-        // 未替换：框架清空 RunInfo，只能靠 EnsureRunInfo 补默认值（Name 为空）
-        out2, _ := innerLambda(ctx, input) // 内层 RunInfo.Name == ""
-
-        final := out1 + "|" + out2
-        ctx = callbacks.OnEnd(ctx, final)
-        return final, nil
-}
-
-func main() {
-        // 在 graph 外单独使用组件：初始化 RunInfo 与 Handlers
-        h := callbacks.NewHandlerBuilder().Build()
-        ctx := callbacks.InitCallbacks(context.Background(),
-                &callbacks.RunInfo{Name: "ComponentA", Type: "Lambda", Component: compose.ComponentOfLambda},
-                h,
-        )
-
-        _, _ = outerLambda(ctx, "ping")
-}
-```
-
-对上面的样例代码做下说明：
-
-- 初始化：在 graph/chain 外使用组件时，用 InitCallbacks 设置首个 RunInfo 与 Handlers ，让后续组件执行能拿到完整回调上下文。
-- 内部调用：在组件 A 内部调用组件 B 前，用 ReuseHandlers 替换 RunInfo （保留原有 handlers），确保 B 的回调拿到正确的 Type/Component/Name 。
-- 不替换的后果：Eino 在一组 Callbacks 完整触发后，会清空当前 ctx 中的 RunInfo，此时因为 RunInfo 为空，Eino 就不再会触发 Callbacks；组件 B 的开发者只能在自身实现里用 EnsureRunInfo 补 Type/Component 的默认值，来确保 RunInfo 非空且大致正确，从而能成功触发 Callbacks。但无法给出合理 Name ，因此 RunInfo.Name 会是空字符串。
-
-### 组件嵌套使用
-
-场景：在一个组件，比如 Lambda 内，手动调用另外一个组件，比如 ChatModel。
-
-这时，如果外层的组件的 ctx 中有 callback handler，因为这个 ctx 也会传入内部的组件，所以内部的组件也会收到同样的 callback handler。
-
-按“是否希望内部组件触发 callback”区分：
-
-1. 希望触发：基本等同于上面一小节的情况，建议通过 `ReuseHandlers` 来手动为内部组件设置 `RunInfo`。
-
-```go
-package main
-
-import (
-        "context"
-
-        "github.com/cloudwego/eino/callbacks"
-        "github.com/cloudwego/eino/components"
-        "github.com/cloudwego/eino/components/model"
-        "github.com/cloudwego/eino/compose"
-        "github.com/cloudwego/eino/schema"
-)
-
-// 外层 Lambda，在内部手动调用 ChatModel
-func OuterLambdaCallsChatModel(cm model.BaseChatModel) *compose.Lambda {
-        return compose.InvokableLambda(func(ctx context.Context, input string) (string, error) {
-                // 1) 复用外层 handlers，并为内部组件显式设置 RunInfo
-                innerCtx := callbacks.ReuseHandlers(ctx, &callbacks.RunInfo{
-                        Type:      "InnerCM",                          // 可自定义
-                        Component: components.ComponentOfChatModel,    // 标注组件类型
-                        Name:      "inner-chat-model",                 // 可自定义
-                })
-
-                // 2) 构造输入消息
-                msgs := []*schema.Message{{Role: schema.User, Content: input}}
-
-                // 3) 调用 ChatModel（内部会触发相应的回调）
-                out, err := cm.Generate(innerCtx, msgs)
-                if err != nil {
-                        return "", err
-                }
-                return out.Content, nil
-        })
-}
-```
-
-上面的代码假设了“内部的 ChatModel 的 Generate 方法内部，已经调用了 OnStart，OnEnd，OnError 这些方法”。如果没有，则需要在外部组件内部“替内部组件”调用这些方法：
-
-```go
-func OuterLambdaCallsChatModel(cm model.BaseChatModel) *compose.Lambda {
-        return compose.InvokableLambda(func(ctx context.Context, input string) (string, error) {
-                // 复用外层 handlers，并为内部组件显式设置 RunInfo
-                ctx = callbacks.ReuseHandlers(ctx, &callbacks.RunInfo{
-                        Type:      "InnerCM",
-                        Component: components.ComponentOfChatModel,
-                        Name:      "inner-chat-model",
-                })
-
-                // 构造输入消息
-                msgs := []*schema.Message{{Role: schema.User, Content: input}}
-
-                // 显式触发 OnStart
-                ctx = callbacks.OnStart(ctx, msgs)
-
-                // 调用 ChatModel
-                resp, err := cm.Generate(ctx, msgs)
-                if err != nil {
-                        // 显式触发 OnError
-                        ctx = callbacks.OnError(ctx, err)
-                        return "", err
-                }
-
-                // 显式触发 OnEnd
-                ctx = callbacks.OnEnd(ctx, resp)
-
-                return resp.Content, nil
-        })
-}
-```
-
-1. 不希望触发：这里假定内部组件实现了 `IsCallbacksEnabled()` 且返回 true，并且在内部调用了 `EnsureRunInfo`。这时默认内部 callbacks 会触发。如不希望触发，最简单的办法是去掉 ctx 中的 handler，比如为内部组件传一个新的 ctx:
-
-   ```go
-   package main
-
-   import (
-           "context"
-
-           "github.com/cloudwego/eino/components/model"
-           "github.com/cloudwego/eino/compose"
-           "github.com/cloudwego/eino/schema"
-   )
-
-   func OuterLambdaNoCallbacks(cm model.BaseChatModel) *compose.Lambda {
-           return compose.InvokableLambda(func(ctx context.Context, input string) (string, error) {
-                   // 使用一个全新的 ctx，不复用外层的 handlers
-                   innerCtx := context.Background()
-
-                   msgs := []*schema.Message{{Role: schema.User, Content: input}}
-                   out, err := cm.Generate(innerCtx, msgs)
-                   if err != nil {
-                           return "", err
-                   }
-                   return out.Content, nil
-           })
-   }
-   ```
-
-   1. 但有时用户可能希望“只不触发某个特定的 callback handlers，但是还触发其他的 callback handlers”。建议的使用姿势是在这个 callback handler 中加代码，按 RunInfo 过滤掉内部组件：
-
-```go
-package main
-
-import (
-        "context"
-        "log"
-
-        "github.com/cloudwego/eino/callbacks"
-        "github.com/cloudwego/eino/components"
-        "github.com/cloudwego/eino/compose"
-)
-
-// 一个按 RunInfo 过滤的 handler：对内部 ChatModel（Type=InnerCM，Name=inner-chat-model）不做任何处理
-func newSelectiveHandler() callbacks.Handler {
-        return callbacks.
-                NewHandlerBuilder().
-                OnStartFn(func(ctx context.Context, info *callbacks.RunInfo, input callbacks.CallbackInput) context.Context {
-                        if info != nil && info.Component == components.ComponentOfChatModel &&
-                                info.Type == "InnerCM" && info.Name == "inner-chat-model" {
-                                // 过滤目标：内部 ChatModel，直接返回，不做处理
-                                return ctx
-                        }
-                        log.Printf("[OnStart] %s/%s (%s)", info.Type, info.Name, info.Component)
-                        return ctx
-                }).
-                OnEndFn(func(ctx context.Context, info *callbacks.RunInfo, output callbacks.CallbackOutput) context.Context {
-                        if info != nil && info.Component == components.ComponentOfChatModel &&
-                                info.Type == "InnerCM" && info.Name == "inner-chat-model" {
-                                // 过滤目标：内部 ChatModel，直接返回，不做处理
-                                return ctx
-                        }
-                        log.Printf("[OnEnd] %s/%s (%s)", info.Type, info.Name, info.Component)
-                        return ctx
-                }).
-                Build()
-}
-
-// 组合示例：外层调用希望触发，特定 handler 通过 RunInfo 过滤掉内部 ChatModel
-func Example(cm model.BaseChatModel) (compose.Runnable[string, string], error) {
-        handler := newSelectiveHandler()
-
-        chain := compose.NewChain[string, string]().
-                AppendLambda(OuterLambdaCallsChatModel(cm)) // 内部会 ReuseHandlers + RunInfo
-
-        return chain.Compile(
-                context.Background(),
-                // 挂载 handler（也可结合全局 handlers）
-                compose.WithCallbacks(handler),
-        )
-}
-```
-
-### Handler 内读写 input & output
-
-Input & output 在 graph 中流转时，是直接变量赋值。如下图所示，NodeA.Output, NodeB.Input, NodeC.Input, 以及各个 Handler 中拿到的 input & output，如果是结构体指针或 Map 等引用类型，则都是同一份数据。因此，无论在 Node 内还是 Handler 内，都不建议修改 Input & Output，会产生并发问题：即使同步情况下，Node B 和 Node C 有并发，导致内部的 handler1 和 handler2 有并发。存在异步处理逻辑时，并发的可能场景更多。
-
-<a href="/img/eino/eino_callback_start_end_place.png" target="_blank"><img src="/img/eino/eino_callback_start_end_place.png" width="60%" /></a>
-
-在流传递的场景，所有下游节点和 handler 中的输入流，都是 StreamReader.Copy(n) 得到的流，可相互独立的读取流。但是，流中的每个 chunk，是直接变量赋值，如果 chunk 是结构体指针或 Map 等引用类型，各个 Copy 后的流读到的是同一份数据。因此，在 Node 和 Handler 内，同样不建议修改流的 chunk，有并发问题。
-
-<a href="/img/eino/eino_callback_stream_place.png" target="_blank"><img src="/img/eino/eino_callback_stream_place.png" width="100%" /></a>
-
-### Handler 间传递信息
-
-同一个 Handler 的不同时机之间，可通过 ctx 传递信息，如 OnStart 中通过 context.WithValue 返回一个新的 context，在 OnEnd 中从 context 中再取出这个 value。
-
-不同 Handler 之间，没有执行顺序的保证，因此不建议通过上面的机制在不同 Handler 间传递信息。本质上是无法保证某一个 Handler 返回的 context，一定会进入下一个 Handler 的函数执行中。
-
-如果需要在不同 Handler 之间传递信息，建议的方式是在最外层的 context（如 graph 执行时传入的 context）中，设置一个全局的、请求维度的变量作为公共信息的存取空间，在各个 Handler 中按需读取和更新这个公共变量。用户需要自行保证这个公共变量的并发安全。
-
-### 流切记要 Close
-
-以存在 ChatModel 这种具有真流输出的节点为例，当存在 Callback 切面时，ChatModel 的输出流：
-
-- 既要被下游节点作为输入来消费，又要被 Callback 切面来消费
-- 一个流中的一个帧(Chunk)，只能被一个消费方消费到，即流不是广播模型
-
-所以此时需要将流进行复制，其复制关系如下：
-
-<a href="/img/eino/graph_stream_chunk_copy.png" target="_blank"><img src="/img/eino/graph_stream_chunk_copy.png" width="100%" /></a>
-
-- 如果其中一个 Callback n 没有 Close 对应的流，可能导致原始 Stream 无法 Close 和释放资源。

docs/Eino/docs/core_modules/chain_and_graph_orchestration/chain_graph_introduction.md

@@ -1,675 +0,0 @@
----
-Description: ""
-date: "2026-01-20"
-lastmod: ""
-tags: []
-title: Chain/Graph 编排介绍
-weight: 1
----
-
-> 本文所有代码样例都在：[https://github.com/cloudwego/eino-examples/tree/main/compose](https://github.com/cloudwego/eino-examples/tree/main/compose)
-
-## Graph 编排
-
-### Graph
-
-```go
-package main
-
-import (
-    "context"
-    "fmt"
-    "io"
-
-    "github.com/cloudwego/eino/components/model"
-    "github.com/cloudwego/eino/components/prompt"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-)
-
-const (
-    nodeOfModel  = "model"
-    nodeOfPrompt = "prompt"
-)
-
-func main() {
-    ctx := context.Background()
-    g := compose.NewGraph[map[string]any, *schema.Message]()
-
-    pt := prompt.FromMessages(
-       schema.FString,
-       schema.UserMessage("what's the weather in {location}?"),
-    )
-
-    _ = g.AddChatTemplateNode(nodeOfPrompt, pt)
-    _ = g.AddChatModelNode(nodeOfModel, &mockChatModel{}, compose.WithNodeName("ChatModel"))
-    _ = g.AddEdge(compose.START, nodeOfPrompt)
-    _ = g.AddEdge(nodeOfPrompt, nodeOfModel)
-    _ = g.AddEdge(nodeOfModel, compose.END)
-
-    r, err := g.Compile(ctx)
-    if err != nil {
-       panic(err)
-    }
-
-    in := map[string]any{"location": "beijing"}
-    ret, err := r.Invoke(ctx, in)
-    fmt.Println("invoke result: ", ret)
-
-    // stream
-    s, err := r.Stream(ctx, in)
-    if err != nil {
-       panic(err)
-    }
-
-    defer s.Close()
-    for {
-       chunk, err := s.Recv()
-       if err != nil {
-          if err == io.EOF {
-             break
-          }
-          panic(err)
-       }
-
-       fmt.Println("stream chunk: ", chunk)
-    }
-}
-
-type mockChatModel struct{}
-
-func (m *mockChatModel) Generate(ctx context.Context, input []*schema.Message, opts ...model.Option) (*schema.Message, error) {
-    return schema.AssistantMessage("the weather is good", nil), nil
-}
-
-func (m *mockChatModel) Stream(ctx context.Context, input []*schema.Message, opts ...model.Option) (*schema.StreamReader[*schema.Message], error) {
-    sr, sw := schema.Pipe[*schema.Message](0)
-    go func() {
-       defer sw.Close()
-       sw.Send(schema.AssistantMessage("the weather is", nil), nil)
-       sw.Send(schema.AssistantMessage("good", nil), nil)
-    }()
-    return sr, nil
-}
-
-func (m *mockChatModel) BindTools(tools []*schema.ToolInfo) error {
-    panic("implement me")
-}
-```
-
-### ToolCallAgent
-
-```bash
-go get github.com/cloudwego/eino-ext/components/model/openai@latest
-go get github.com/cloudwego/eino@latest
-```
-
-```go
-package main
-
-import (
-    "context"
-    "os"
-
-    "github.com/cloudwego/eino-ext/components/model/openai"
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/components/prompt"
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-
-    "github.com/cloudwego/eino-examples/internal/gptr"
-    "github.com/cloudwego/eino-examples/internal/logs"
-)
-
-func main() {
-
-    openAIBaseURL := os.Getenv("OPENAI_BASE_URL")
-    openAIAPIKey := os.Getenv("OPENAI_API_KEY")
-    modelName := os.Getenv("MODEL_NAME")
-
-    ctx := context.Background()
-
-    callbacks.AppendGlobalHandlers(&loggerCallbacks{})
-
-    // 1. create an instance of ChatTemplate as 1st Graph Node
-    systemTpl := `你是一名房产经纪人，结合用户的薪酬和工作，使用 user_info API，为其提供相关的房产信息。邮箱是必须的`
-    chatTpl := prompt.FromMessages(schema.FString,
-       schema.SystemMessage(systemTpl),
-       schema.MessagesPlaceholder("message_histories", true),
-       schema.UserMessage("{user_query}"),
-    )
-
-    modelConf := &openai.ChatModelConfig{
-       BaseURL:     openAIBaseURL,
-       APIKey:      openAIAPIKey,
-       ByAzure:     true,
-       Model:       modelName,
-       Temperature: gptr.Of(float32(0.7)),
-       APIVersion:  "2024-06-01",
-    }
-
-    // 2. create an instance of ChatModel as 2nd Graph Node
-    chatModel, err := openai.NewChatModel(ctx, modelConf)
-    if err != nil {
-       logs.Errorf("NewChatModel failed, err=%v", err)
-       return
-    }
-
-    // 3. create an instance of tool.InvokableTool for Intent recognition and execution
-    userInfoTool := utils.NewTool(
-       &schema.ToolInfo{
-          Name: "user_info",
-          Desc: "根据用户的姓名和邮箱，查询用户的公司、职位、薪酬信息",
-          ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{
-             "name": {
-                Type: "string",
-                Desc: "用户的姓名",
-             },
-             "email": {
-                Type: "string",
-                Desc: "用户的邮箱",
-             },
-          }),
-       },
-       func(ctx context.Context, input *userInfoRequest) (output *userInfoResponse, err error) {
-          return &userInfoResponse{
-             Name:     input.Name,
-             Email:    input.Email,
-             Company:  "Bytedance",
-             Position: "CEO",
-             Salary:   "9999",
-          }, nil
-       })
-
-    info, err := userInfoTool.Info(ctx)
-    if err != nil {
-       logs.Errorf("Get ToolInfo failed, err=%v", err)
-       return
-    }
-
-    // 4. bind ToolInfo to ChatModel. ToolInfo will remain in effect until the next BindTools.
-    err = chatModel.BindForcedTools([]*schema.ToolInfo{info})
-    if err != nil {
-       logs.Errorf("BindForcedTools failed, err=%v", err)
-       return
-    }
-
-    // 5. create an instance of ToolsNode as 3rd Graph Node
-    toolsNode, err := compose.NewToolNode(ctx, &compose.ToolsNodeConfig{
-       Tools: []tool.BaseTool{userInfoTool},
-    })
-    if err != nil {
-       logs.Errorf("NewToolNode failed, err=%v", err)
-       return
-    }
-
-    const (
-       nodeKeyOfTemplate  = "template"
-       nodeKeyOfChatModel = "chat_model"
-       nodeKeyOfTools     = "tools"
-    )
-
-    // 6. create an instance of Graph
-    // input type is 1st Graph Node's input type, that is ChatTemplate's input type: map[string]any
-    // output type is last Graph Node's output type, that is ToolsNode's output type: []*schema.Message
-    g := compose.NewGraph[map[string]any, []*schema.Message]()
-
-    // 7. add ChatTemplate into graph
-    _ = g.AddChatTemplateNode(nodeKeyOfTemplate, chatTpl)
-
-    // 8. add ChatModel into graph
-    _ = g.AddChatModelNode(nodeKeyOfChatModel, chatModel)
-
-    // 9. add ToolsNode into graph
-    _ = g.AddToolsNode(nodeKeyOfTools, toolsNode)
-
-    // 10. add connection between nodes
-    _ = g.AddEdge(compose.START, nodeKeyOfTemplate)
-
-    _ = g.AddEdge(nodeKeyOfTemplate, nodeKeyOfChatModel)
-
-    _ = g.AddEdge(nodeKeyOfChatModel, nodeKeyOfTools)
-
-    _ = g.AddEdge(nodeKeyOfTools, compose.END)
-
-    // 9. compile Graph[I, O] to Runnable[I, O]
-    r, err := g.Compile(ctx)
-    if err != nil {
-       logs.Errorf("Compile failed, err=%v", err)
-       return
-    }
-
-    out, err := r.Invoke(ctx, map[string]any{
-       "message_histories": []*schema.Message{},
-       "user_query":        "我叫 zhangsan, 邮箱是 zhangsan@bytedance.com, 帮我推荐一处房产",
-    })
-    if err != nil {
-       logs.Errorf("Invoke failed, err=%v", err)
-       return
-    }
-    logs.Infof("Generation: %v Messages", len(out))
-    for _, msg := range out {
-       logs.Infof("    %v", msg)
-    }
-}
-
-type userInfoRequest struct {
-    Name  string `json:"name"`
-    Email string `json:"email"`
-}
-
-type userInfoResponse struct {
-    Name     string `json:"name"`
-    Email    string `json:"email"`
-    Company  string `json:"company"`
-    Position string `json:"position"`
-    Salary   string `json:"salary"`
-}
-
-type loggerCallbacks struct{}
-
-func (l *loggerCallbacks) OnStart(ctx context.Context, info *callbacks.RunInfo, input callbacks.CallbackInput) context.Context {
-    logs.Infof("name: %v, type: %v, component: %v, input: %v", info.Name, info.Type, info.Component, input)
-    return ctx
-}
-
-func (l *loggerCallbacks) OnEnd(ctx context.Context, info *callbacks.RunInfo, output callbacks.CallbackOutput) context.Context {
-    logs.Infof("name: %v, type: %v, component: %v, output: %v", info.Name, info.Type, info.Component, output)
-    return ctx
-}
-
-func (l *loggerCallbacks) OnError(ctx context.Context, info *callbacks.RunInfo, err error) context.Context {
-    logs.Infof("name: %v, type: %v, component: %v, error: %v", info.Name, info.Type, info.Component, err)
-    return ctx
-}
-
-func (l *loggerCallbacks) OnStartWithStreamInput(ctx context.Context, info *callbacks.RunInfo, input *schema.StreamReader[callbacks.CallbackInput]) context.Context {
-    return ctx
-}
-
-func (l *loggerCallbacks) OnEndWithStreamOutput(ctx context.Context, info *callbacks.RunInfo, output *schema.StreamReader[callbacks.CallbackOutput]) context.Context {
-    return ctx
-}
-```
-
-### Graph with state
-
-Graph 可以有 graph 自身的“全局”状态，在创建 Graph 时传入 WithGenLocalState Option 开启此功能：
-
-```go
-// compose/generic_graph.go
-
-// type GenLocalState[S any] func(ctx context.Context) (state S)
-
-func WithGenLocalState[S any](gls GenLocalState[S]) NewGraphOption {
-    // --snip--
-}
-```
-
-Add node 时添加 Pre/Post Handler 来处理 State：
-
-```go
-// compose/graph_add_node_options.go
-
-// type StatePreHandler[I, S any] func(ctx context.Context, in I, state S) (I, error)
-// type StatePostHandler[O, S any] func(ctx context.Context, out O, state S) (O, error)
-
-func WithStatePreHandler[I, S any](pre StatePreHandler[I, S]) GraphAddNodeOpt {
-    // --snip--
-}
-
-func WithStatePostHandler[O, S any](post StatePostHandler[O, S]) GraphAddNodeOpt {
-    // --snip--
-}
-```
-
-在 Node 内部，用 `ProcessState`，传入一个读写 State 的 函数：
-
-```go
-// flow/agent/react/react.go
-
-var msg *schema.Message
-err = compose.ProcessState[*state](ctx, func(_ context.Context, state *state) error {
-    for i := range msgs {
-       if msgs[i] != nil && msgs[i].ToolCallID == state.ReturnDirectlyToolCallID {
-          msg = msgs[i]
-          return nil
-       }
-    }
-    return nil
-})
-```
-
-完整使用例子：
-
-```go
-package main
-
-import (
-    "context"
-    "errors"
-    "io"
-    "runtime/debug"
-    "strings"
-    "unicode/utf8"
-
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-    "github.com/cloudwego/eino/utils/safe"
-
-    "github.com/cloudwego/eino-examples/internal/logs"
-)
-
-func main() {
-    ctx := context.Background()
-
-    const (
-       nodeOfL1 = "invokable"
-       nodeOfL2 = "streamable"
-       nodeOfL3 = "transformable"
-    )
-
-    type testState struct {
-       ms []string
-    }
-
-    gen := func(ctx context.Context) *testState {
-       return &testState{}
-    }
-
-    sg := compose.NewGraph[string, string](compose.WithGenLocalState(gen))
-
-    l1 := compose.InvokableLambda(func(ctx context.Context, in string) (out string, err error) {
-       return "InvokableLambda: " + in, nil
-    })
-
-    l1StateToInput := func(ctx context.Context, in string, state *testState) (string, error) {
-       state.ms = append(state.ms, in)
-       return in, nil
-    }
-
-    l1StateToOutput := func(ctx context.Context, out string, state *testState) (string, error) {
-       state.ms = append(state.ms, out)
-       return out, nil
-    }
-
-    _ = sg.AddLambdaNode(nodeOfL1, l1,
-       compose.WithStatePreHandler(l1StateToInput),   compose.WithStatePostHandler(l1StateToOutput))
-
-    l2 := compose.StreamableLambda(func(ctx context.Context, input string) (output *schema.StreamReader[string], err error) {
-       outStr := "StreamableLambda: " + input
-
-       sr, sw := schema.Pipe[string](utf8.RuneCountInString(outStr))
-
-       // nolint: byted_goroutine_recover
-       go func() {
-          for _, field := range strings.Fields(outStr) {
-             sw.Send(field+" ", nil)
-          }
-          sw.Close()
-       }()
-
-       return sr, nil
-    })
-
-    l2StateToOutput := func(ctx context.Context, out string, state *testState) (string, error) {
-       state.ms = append(state.ms, out)
-       return out, nil
-    }
-
-    _ = sg.AddLambdaNode(nodeOfL2, l2, compose.WithStatePostHandler(l2StateToOutput))
-
-    l3 := compose.TransformableLambda(func(ctx context.Context, input *schema.StreamReader[string]) (
-       output *schema.StreamReader[string], err error) {
-
-       prefix := "TransformableLambda: "
-       sr, sw := schema.Pipe[string](20)
-
-       go func() {
-
-          defer func() {
-             panicErr := recover()
-             if panicErr != nil {
-                err := safe.NewPanicErr(panicErr, debug.Stack())
-                logs.Errorf("panic occurs: %v\n", err)
-             }
-
-          }()
-
-          for _, field := range strings.Fields(prefix) {
-             sw.Send(field+" ", nil)
-          }
-
-          for {
-             chunk, err := input.Recv()
-             if err != nil {
-                if err == io.EOF {
-                   break
-                }
-                // TODO: how to trace this kind of error in the goroutine of processing sw
-                sw.Send(chunk, err)
-                break
-             }
-
-             sw.Send(chunk, nil)
-
-          }
-          sw.Close()
-       }()
-
-       return sr, nil
-    })
-
-    l3StateToOutput := func(ctx context.Context, out string, state *testState) (string, error) {
-       state.ms = append(state.ms, out)
-       logs.Infof("state result: ")
-       for idx, m := range state.ms {
-          logs.Infof("    %vth: %v", idx, m)
-       }
-       return out, nil
-    }
-
-    _ = sg.AddLambdaNode(nodeOfL3, l3, compose.WithStatePostHandler(l3StateToOutput))
-
-    _ = sg.AddEdge(compose.START, nodeOfL1)
-
-    _ = sg.AddEdge(nodeOfL1, nodeOfL2)
-
-    _ = sg.AddEdge(nodeOfL2, nodeOfL3)
-
-    _ = sg.AddEdge(nodeOfL3, compose.END)
-
-    run, err := sg.Compile(ctx)
-    if err != nil {
-       logs.Errorf("sg.Compile failed, err=%v", err)
-       return
-    }
-
-    out, err := run.Invoke(ctx, "how are you")
-    if err != nil {
-       logs.Errorf("run.Invoke failed, err=%v", err)
-       return
-    }
-    logs.Infof("invoke result: %v", out)
-
-    stream, err := run.Stream(ctx, "how are you")
-    if err != nil {
-       logs.Errorf("run.Stream failed, err=%v", err)
-       return
-    }
-
-    for {
-
-       chunk, err := stream.Recv()
-       if err != nil {
-          if errors.Is(err, io.EOF) {
-             break
-          }
-          logs.Infof("stream.Recv() failed, err=%v", err)
-          break
-       }
-
-       logs.Tokenf("%v", chunk)
-    }
-    stream.Close()
-
-    sr, sw := schema.Pipe[string](1)
-    sw.Send("how are you", nil)
-    sw.Close()
-
-    stream, err = run.Transform(ctx, sr)
-    if err != nil {
-       logs.Infof("run.Transform failed, err=%v", err)
-       return
-    }
-
-    for {
-
-       chunk, err := stream.Recv()
-       if err != nil {
-          if errors.Is(err, io.EOF) {
-             break
-          }
-          logs.Infof("stream.Recv() failed, err=%v", err)
-          break
-       }
-
-       logs.Infof("%v", chunk)
-    }
-    stream.Close()
-}
-```
-
-## Chain
-
-> Chain 可以视为是 Graph 的简化封装
-
-```go
-package main
-
-import (
-    "context"
-    "fmt"
-    "log"
-    "math/rand"
-    "os"
-
-    "github.com/cloudwego/eino-ext/components/model/openai"
-    "github.com/cloudwego/eino/components/prompt"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-
-    "github.com/cloudwego/eino-examples/internal/gptr"
-    "github.com/cloudwego/eino-examples/internal/logs"
-)
-
-func main() {
-    openAPIBaseURL := os.Getenv("OPENAI_BASE_URL")
-    openAPIAK := os.Getenv("OPENAI_API_KEY")
-    modelName := os.Getenv("MODEL_NAME")
-
-    ctx := context.Background()
-    // build branch func
-    const randLimit = 2
-    branchCond := func(ctx context.Context, input map[string]any) (string, error) { // nolint: byted_all_nil_return
-       if rand.Intn(randLimit) == 1 {
-          return "b1", nil
-       }
-
-       return "b2", nil
-    }
-
-    b1 := compose.InvokableLambda(func(ctx context.Context, kvs map[string]any) (map[string]any, error) {
-       logs.Infof("hello in branch lambda 01")
-       if kvs == nil {
-          return nil, fmt.Errorf("nil map")
-       }
-
-       kvs["role"] = "cat"
-       return kvs, nil
-    })
-
-    b2 := compose.InvokableLambda(func(ctx context.Context, kvs map[string]any) (map[string]any, error) {
-       logs.Infof("hello in branch lambda 02")
-       if kvs == nil {
-          return nil, fmt.Errorf("nil map")
-       }
-
-       kvs["role"] = "dog"
-       return kvs, nil
-    })
-
-    // build parallel node
-    parallel := compose.NewParallel()
-    parallel.
-       AddLambda("role", compose.InvokableLambda(func(ctx context.Context, kvs map[string]any) (string, error) {
-          // may be change role to others by input kvs, for example (dentist/doctor...)
-          role, ok := kvs["role"].(string)
-          if !ok || role == "" {
-             role = "bird"
-          }
-
-          return role, nil
-       })).
-       AddLambda("input", compose.InvokableLambda(func(ctx context.Context, kvs map[string]any) (string, error) {
-          return "你的叫声是怎样的？", nil
-       }))
-
-    modelConf := &openai.ChatModelConfig{
-       BaseURL:     openAPIBaseURL,
-       APIKey:      openAPIAK,
-       ByAzure:     true,
-       Model:       modelName,
-       Temperature: gptr.Of(float32(0.7)),
-       APIVersion:  "2024-06-01",
-    }
-
-    // create chat model node
-    cm, err := openai.NewChatModel(context.Background(), modelConf)
-    if err != nil {
-       log.Panic(err)
-       return
-    }
-
-    rolePlayerChain := compose.NewChain[map[string]any, *schema.Message]()
-    rolePlayerChain.
-       AppendChatTemplate(prompt.FromMessages(schema.FString, schema.SystemMessage(`You are a {role}.`), schema.UserMessage(`{input}`))).
-       AppendChatModel(cm)
-
-    // =========== build chain ===========
-    chain := compose.NewChain[map[string]any, string]()
-    chain.
-       AppendLambda(compose.InvokableLambda(func(ctx context.Context, kvs map[string]any) (map[string]any, error) {
-          // do some logic to prepare kv as input val for next node
-          // just pass through
-          logs.Infof("in view lambda: %v", kvs)
-          return kvs, nil
-       })).
-       AppendBranch(compose.NewChainBranch(branchCond).AddLambda("b1", b1).AddLambda("b2", b2)). // nolint: byted_use_receiver_without_nilcheck
-       AppendPassthrough().
-       AppendParallel(parallel).
-       AppendGraph(rolePlayerChain).
-       AppendLambda(compose.InvokableLambda(func(ctx context.Context, m *schema.Message) (string, error) {
-          // do some logic to check the output or something
-          logs.Infof("in view of messages: %v", m.Content)
-          return m.Content, nil
-       }))
-
-    // compile
-    r, err := chain.Compile(ctx)
-    if err != nil {
-       log.Panic(err)
-       return
-    }
-
-    output, err := r.Invoke(context.Background(), map[string]any{})
-    if err != nil {
-       log.Panic(err)
-       return
-    }
-
-    logs.Infof("output is : %v", output)
-}
-```

docs/Eino/docs/core_modules/chain_and_graph_orchestration/checkpoint_interrupt.md

@@ -1,441 +0,0 @@
----
-Description: ""
-date: "2026-03-24"
-lastmod: ""
-tags: []
-title: Interrupt & CheckPoint使用手册
-weight: 7
----
-
-> 💡
-> 注意：v0.3.26 版本中因为代码编写错误导致 CheckPoint 的序列化内容产生 break，新接入 CheckPoint 使用 v0.3.26 以后的版本，建议直接使用最新。
->
-> eino 提供了兼容分支，使用了 checkpoint 且版本低于 v0.3.26 的业务在升级 eino 时可以先升级到兼容分支，老数据淘汰后再升级到主干。
->
-> 因为兼容分支会引入额外的性能开销并且一般来说业务 agent checkpoint 有不太长的有效期，所以分支没有合入主干。
-
-## 介绍
-
-使用 Interrupt & CheckPoint 功能，可以实现在指定位置暂停 Graph 执行并在之后断点续传，如果是 StateGraph，还可以在断点续传前修改 State。
-
-> 💡
-> 断点续传仅能复原输入和运行时各节点产生的数据，需要确保 Graph 编排完全相同，以及重新完整传入 CallOption（没有特殊情况应当保持一致，除非依赖 CallOption 在 Resume 时传递数据等）。
-
-## 使用静态 Interrupt
-
-静态 Interrupt 支持在指定 Node 执行前或执行后暂停 Graph，Compile 时传入 WithInterruptAfterNodes 与 WithInterruptBeforeNodes Option 来设置 Interrupt：
-
-```go
-import (
-    "github.com/cloudwego/eino/compose"
-)
-
-func main() {
-    g := NewGraph[string, string]()
-    err := g.AddLambdaNode("node1", compose.InvokableLambda(func(ctx **context**._Context_, input string) (output string, err error) {/*invokable func*/})
-    if err != nil {/* error handle */}
-    err = g.AddLambdaNode("node2", compose.InvokableLambda(func(ctx **context**._Context_, input string) (output string, err error) {/*invokable func*/})
-    if err != nil {/* error handle */}
-    
-    /** other graph composed code
-    xxx 
-    */
-    
-    err = g.Compile(ctx, compose.WithInterruptAfterNodes([]string{"node1"}), compose.WithInterruptBeforeNodes([]string{"node2"}))
-    if err != nil {/* error handle */}
-}
-```
-
-> 💡
-> 目前仅支持 Compile 时设置静态断点，如果需要请求时设置，欢迎提出~
-
-可以从运行返回的 error 中获得本次运行是否 Interrupt 以及 Interrupt 信息：
-
-```go
-// compose/checkpoint.go
-
-**type **InterruptInfo **struct **{
-    State             any
-    BeforeNodes       []string
-    AfterNodes        []string
-    RerunNodes        []string
-    RerunNodesExtra   **map**[string]any
-    SubGraphs         **map**[string]*InterruptInfo
-    InterruptContexts []*InterruptCtx
-}
-
-func ExtractInterruptInfo(err error) (info *InterruptInfo, existed bool) {}
-```
-
-例如：
-
-```go
-import "github.com/cloudwego/eino/compse"
-
-/***graph compose code
-* g := NewGraph
-* xxx
-* runner := g.Compile
-*/
-
-result, err := runner.Invoke(ctx, input)
-if info, ok := ExtractInterruptInfo(err); ok {
-    // handler info
-}
-if err != nil {
-    // handle error
-}
-```
-
-> 💡
-> Interrupt 时 output 为空值，没有意义。
-
-## 使用 CheckPoint
-
-CheckPoint 记录 Graph 运行状态，使用 CheckPoint 可以在 Interrupt 后恢复运行。
-
-### 实现 CheckPointerStore
-
-CheckPointStore 是一个 key 类型为 string、value 类型为[]byte 的 KV 存储接口，我们没有提供封装和默认实现，需要用户自行实现，用来存储 checkpoint。
-
-```go
-// compose/checkpoint.go
-
-type CheckpointStore interface {
-    Get(ctx **context**._Context_, key string) (value []byte, existed bool,err error)
-    Set(ctx **context**._Context_, key string, value []byte) (err error)
-}
-```
-
-### 注册序列化方法
-
-CheckPoint 的保存和读取涉及对 Graph 节点输入输出以及 State 的序列化和反序列化，在仅使用简单类型或 eino 内置类型（比如 Message 或 Document）时，用户无需额外操作；当引入自定义 struct 时，需要提前注册类型，Eino 提供了注册方法 `schema.``RegisterName`：
-
-```go
-package main
-
-import "github.com/cloudwego/eino/schema"
-
-type MyState struct {
-        Counter int
-        Note    string
-}
-
-func init() {
-        // Register the type with a stable name for serialization/persistence.
-        // Use the pointer form if you persist pointers to this type.
-        // It's recommended to register types within the `init()` function 
-        // within the same file your type is declared.
-        schema.RegisterName[*MyState]("my_state_v1")
-}
-```
-
-注册后的类型在序列化时将被额外记录类型信息，因此在反序列化时，即使不指明类型（比如反序列化到 interface{}），Eino 也可以反序列化出正确的类型。注册方法中的 key 唯一标识了这个类型，一旦确定了 key 需要保证其不能改变，否则已持久化的 checkpoint 将不能被正确恢复。
-
-> 💡
-> 结构体的未导出字段无法访问，因此不会被存储/恢复
-
-默认情况下，会使用 eino 内置的序列化功能，此时，如果注册的类型实现了 json Marshaler 和 Unmarshaler，此类型的序列化和反序列化会使用自定义方法。
-
-```
-// encoding/json
-
-type Marshaler interface {
-    MarshalJSON() ([]byte, error)
-}
-
-type Unmarshaler interface {
-    UnmarshalJSON([]byte) error
-}
-```
-
-Eino 同时提供了将序列化方式改为 gob 的选项：
-
-```go
-r, err := compose.NewChain[*AgentInput, Message]().
-    AppendLambda(compose.InvokableLambda(func(ctx context.Context, input *AgentInput) ([]Message, error) {
-       return a.genModelInput(ctx, instruction, input)
-    })).
-    AppendChatModel(a.model).
-    Compile(ctx, compose.WithGraphName(a.name),
-       compose.WithCheckPointStore(store),
-       compose.WithSerializer(&gobSerializer{}))
-```
-
-用户可以按偏好选择，选择后不建议轻易变更，历史数据不兼容。
-
-### 开启 CheckPoint
-
-创建 CheckPointStore 后在 Compile Graph 时作为 Option 传入，把 CheckPointer 绑定到 Graph：
-
-```go
-import (
-    "github.com/cloudwego/eino/compose"
-)
-
-func main() {
-    /** graph composed code
-    xxx 
-    */
-    
-    err = g.Compile(ctx, compose.WithCheckPointStore(store), compose.WithInterruptBeforeNodes([]string{"node2"}))
-    if err != nil {/* error handle */}
-}
-```
-
-之后可以在请求时通过 CallOption 引入 CheckPoint：
-
-```
-// compose/checkpoint.go
-
-func WithCheckPointID(checkPointID string) Option
-```
-
-Checkpoint id 会被作为 CheckPointStore 的 key 使用，graph 运行时会检查 CheckPointStore 是否存在此 id，如果存在则从 checkpoint 中恢复运行；interrupt 是会把 graph 状态保存到此 id 中。
-
-## 动态 Interrupt
-
-节点返回特殊错误可以动态地触发 Interrupt：
-
-### 在 eino v0.7.0 之前
-
-```
-// eino/compose/interrupt.go
-
-// emit a plain interrupt signal
-var InterruptAndRerun = errors.New("interrupt and rerun")
-
-// emit an interrupt signal with extra info
-**func **NewInterruptAndRerunErr(extra any) error
-```
-
-Eino Graph 接收到节点返回此错误后会发生 interrupt，恢复运行时，会再次运行此节点，再次运行前会调用 StateModifier 修改 state（如果已配置）。
-
-这种情况下，再次运行节点时输入会替换为空值，而不是原本的输入，如果再次运行时需要仍需要原本输入，需要提前保存到 State 中。
-
-### 在 eino v0.7.0 及之后
-
-增加了对“保存本地状态”、“透出内部中断信号”、“并行中断”的支持：
-
-```
-// eino/compose/interrupt.go
-
-// emit an interrupt signal with user-facing info
-func Interrupt(ctx context.Context, info any) error
-
-// emit an interrupt signal with user-facing info AS WELL AS
-// persistent LOCALLY-DEFINED state
-func StatefulInterrupt(ctx context.Context, info any, state any) error
-
-// emit an interrupt signal WRAPPING other interrupt signals 
-// emitted from inner processes, 
-// such as ToolsNode wrapping Tools.
-func CompositeInterrupt(ctx context.Context, info any, state any, errs ...error)
-```
-
-详细设计参见：[Eino human-in-the-loop 框架：技术架构指南](/zh/docs/eino/core_modules/eino_adk/agent_hitl)
-
-## 外部主动 Interrupt
-
-有时，我们希望能在 Graph 外部主动触发中断，保存现场，之后择机恢复。这些场景可能包括实例优雅退出等。这时，可以通过调用 `WithGraphInterrupt` 获取一个 ctx 和一个 interrupt function。其中 ctx 用于传递给 `graph.Invoke()` 等运行方法，interrupt function 用于在用户希望主动中断时调用：
-
-```go
-// from compose/graph_call_options.go
-
-_// WithGraphInterrupt creates a context with graph cancellation support._
-_// When the returned context is used to invoke a graph or workflow, calling the interrupt function will trigger an interrupt._
-_// The graph will wait for current tasks to complete by default._
-**func **WithGraphInterrupt(parent context.Context) (ctx context.Context, interrupt **func**(opts ...GraphInterruptOption)) {}
-```
-
-在主动调用 interrupt function 时，可以传递超时等参数：
-
-```go
-// from compose/graph_call_options.go
-
-_// WithGraphInterruptTimeout specifies the max waiting time before generating an interrupt._
-_// After the max waiting time, the graph will force an interrupt. Any unfinished tasks will be re-run when the graph is resumed._
-**func **WithGraphInterruptTimeout(timeout time.Duration) GraphInterruptOption {
-    **return func**(o *graphInterruptOptions) {
-       o.timeout = &timeout
-    }
-}
-```
-
-当外部触发中断时，节点内部没有机会保存局部状态（包括节点的 input），所以 eino 会自动保存被外部中断的节点的 input，在下次执行时自动恢复。非外部触发中断的场景，节点内部发起中断时，保存 input 是每个节点的职责，可通过保存到 graph state 中或使用 `compose.StatefulInterrupt` 保存局部状态。
-
-## 流式传输中的 CheckPoint
-
-流式传输在保存 CheckPoint 时需要拼接数据流，因此需要注册拼接方法：
-
-```go
-// compose/stream_concat.go
-func RegisterStreamChunkConcatFunc[T any](fn func([]T) (T, error))
-
-// example
-type TestStruct struct {
-    Body string
-}
-
-// RegisterStreamChunkConcatFunc非线程安全，需要在初始化阶段使用
-RegisterStreamChunkConcatFunc(func(ss []TestStruct)(TestStruct, error){
-    ret := TestStruct{Body:""}
-    for i := range ss {
-        ret.Body += ss[i].Body
-    }
-    return ret, nil
-})
-```
-
-eino 默认提供了*schema.Message、[]*schema.Message 和 string 的 concat 方法。
-
-## 嵌套图中的 Interrupt&CheckPoint
-
-父图传入 CheckPointer 的前提下，AddGraphNode 时使用 WithGraphCompileOptions 传入 InterruptNodes 可以开启子图的 Interrupt&CheckPoint，父图未设置 CheckPointer 时会在 Compile 时报错。
-
-```go
-/* graph compose code
-xxx
-*/
-g.AddGraphNode("node1", subGraph, WithGraphCompileOptions(
-    WithInterruptAfterNodes([]string{"node2"}),
-))
-    
-g.Compile(ctx, WithCheckPointStore(cp))
-```
-
-如果在子图中 interrupt，resume 时修改的 state 应为子图 state。TODO，说明下 StateModifier 中 Path 使用
-
-## 恢复
-
-恢复：Interrupt 并保存 checkpoint 后，后续的 graph 运行。
-
-### 在 eino v0.7.0 之前
-
-通过修改 State 来影响恢复时的行为。
-
-```go
-// compose/checkpoint.go
-
-type StateModifier func(ctx context.Context, path NodePath, state any) error
-func WithStateModifier(sm StateModifier) GraphCompileOption
-```
-
-StateModifier 在 Graph 恢复运行时生效，可以在运行前修改 State，path 在嵌套图中生效，非嵌套视为空数组。
-
-```go
-/* graph compose and compile
-xxx
-*/
-
-// first run interrupt
-id := GenUUID()
-_, err := runner.Invoke(ctx, input, WithCheckPointID(id))
-
-// resume from id
-_, err = runner.Invoke(ctx, input/*unused*/, 
-    WithCheckPointID(id),
-    WithStateModifier(func(ctx context.Context, path NodePath, state any) error{
-        state.(*testState).Field1 = "hello"
-        return nil
-    }),
-)
-```
-
-> 💡
-> Resume 时 input 不会被读取，此时 input 传空即可。
-
-### 在 eino v0.7.0 及之后
-
-除了 StateModifier 之外，还可以选择性的恢复某个中断点，以及直接给指定的“中断点位”传递“恢复数据”：
-
-```go
-// specifically resume particular interrupt point(s), 
-// without specifying resume data
-func Resume(ctx context.Context, interruptIDs ...string) context.Context
-
-// specifically resume one interrupt point, with custom resume data
-func ResumeWithData(ctx context.Context, interruptID string, data any) context.Context
-
-// specifically resume multiple interrupt points, each with custom resume data
-func BatchResumeWithData(ctx context.Context, resumeData map[string]any) context.Context
-```
-
-其中，`InterruptID` 是从 interrupt error 中获取的：
-
-```go
-interruptInfo, isInterrupt := ExtractInterruptInfo(err)
-if isInterrupt {
-    // maybe multiple interrupt points exist here,
-    // we only take the first one for illustration purpose
-    interruptID = interruptInfo.InterruptContexts[0].ID
-}
-```
-
-`resumeData` 是发生中断的点位定义的类型，比如一个 Tool 发生了中断并要求用户“审批”是否执行这个 Tool，自定义了一个 `ApprovalResult` 作为 resumeData：
-
-```go
-func (i InvokableApprovableTool) InvokableRun(ctx context.Context, argumentsInJSON string,
-   opts ...tool.Option) (string, error) {
-
-   toolInfo, err := i.Info(ctx)
-   if err != nil {
-      return "", err
-   }
-
-   wasInterrupted, _, storedArguments := compose.GetInterruptState[string](ctx)
-   if !wasInterrupted { // initial invocation, interrupt and wait for approval
-      return "", compose.StatefulInterrupt(ctx, &ApprovalInfo{
-         ToolName:        toolInfo.Name,
-         ArgumentsInJSON: argumentsInJSON,
-         ToolCallID:      compose.GetToolCallID(ctx),
-      }, argumentsInJSON)
-   }
-
-   isResumeTarget, hasData, data := compose.GetResumeContext[*ApprovalResult](ctx)
-   if !isResumeTarget { // was interrupted but not explicitly resumed, reinterrupt and wait for approval again
-      return "", compose.StatefulInterrupt(ctx, &ApprovalInfo{
-         ToolName:        toolInfo.Name,
-         ArgumentsInJSON: storedArguments,
-         ToolCallID:      compose.GetToolCallID(ctx),
-      }, storedArguments)
-   }
-   if !hasData {
-      return "", fmt.Errorf("tool '%s' resumed with no data", toolInfo.Name)
-   }
-
-   if data.Approved {
-      return i.InvokableTool.InvokableRun(ctx, storedArguments, opts...)
-   }
-
-   if data.DisapproveReason != nil {
-      return fmt.Sprintf("tool '%s' disapproved, reason: %s", toolInfo.Name, *data.DisapproveReason), nil
-   }
-
-   return fmt.Sprintf("tool '%s' disapproved", toolInfo.Name), nil
-}
-```
-
-# 例子
-
-### 在 eino v0.7.0 之前
-
-[https://github.com/cloudwego/eino-examples/tree/main/compose/graph/react_with_interrupt](https://github.com/cloudwego/eino-examples/tree/main/compose/graph/react_with_interrupt)
-
-### 在 eino v0.7.0 之后
-
-[https://github.com/cloudwego/eino/blob/main/compose/resume_test.go](https://github.com/cloudwego/eino/blob/main/compose/resume_test.go)
-
-其中
-
-`TestInterruptStateAndResumeForRootGraph`: 简单动态中断
-
-`TestInterruptStateAndResumeForSubGraph`: 子图中断
-
-`TestInterruptStateAndResumeForToolInNestedSubGraph`: 嵌套子图内部 tool 中断
-
-`TestMultipleInterruptsAndResumes`: 并行中断
-
-`TestReentryForResumedTools`: ReAct Agent 内 tool 中断，恢复后多次循环执行
-
-`TestGraphInterruptWithinLambda`: Lambda 节点内包含独立 Graph 且内部中断

docs/Eino/docs/core_modules/chain_and_graph_orchestration/orchestration_design_principles.md

@@ -1,477 +0,0 @@
----
-Description: ""
-date: "2026-03-09"
-lastmod: ""
-tags: []
-title: 编排的设计理念
-weight: 2
----
-
-大模型应用编排框架的主流语言是 python，这门语言以其灵活性著称，灵活性给 sdk 的开发带来便利，但同时也给 sdk 的使用者带来了心智负担。
-
-基于 golang 的 eino 则是 `静态类型` ，在 Compile 时做类型检查，避免了 python 等动态语言的运行时类型问题。
-
-## 以上下游 `类型对齐` 为基本准则
-
-eino 的最基础编排方式为 graph，以及简化的封装 chain。不论是哪种编排方式，其本质都是 `逻辑节点` + `上下游关系` 。在编排的产物运行时，都是从一个逻辑节点运行，然后下一步运行和这个节点相连的下一个节点。
-
-这之间蕴含了一个基本假设：**前一个运行节点的输出值，可以作为下一个节点的输入值。**
-
-在 golang 中，要实现这个假设，有两个基本方案：
-
-1. 把不同节点的输入输出都变成一种更泛化的类型，例如 `any` 、`map[string]any` 等。
-   1. 采用泛化成 any 的方案，但对应的代价是: 开发者在写代码时，需要显式转换成具体类型才能使用。这会极大增加开发者的心智负担，因此最终放弃此方案。
-   2. langchain 的方案可以看做是全程传递 `map[string]any`，各个逻辑节点根据自己的需要，用对应的 key 去取对应的 value。在 langchaingo 的实现中，即是按照这种方式实现，但同样，golang 中的 any 要被使用依然要使用 `类型断言` 才可使用。这种方案在开发者使用时依然有很大的心智负担。
-2. 每一个节点的输入输出类型保持开发者的预期，在 Compile 阶段保证上下游的类型是一致的。
-
-方案 2 即是 eino 最终选定的方案。这种方案是编排时最容易被理解的，整个过程就像是 `搭积木` 一样，每一个积木突出的部分和凹陷的部分有各自的规格，仅有规格匹配了才能成为上下游关系。
-
-就如下图：
-
-<a href="/img/eino/edge_type_validate.png" target="_blank"><img src="/img/eino/edge_type_validate.png" width="100%" /></a>
-
-对于一个编排而言，只有下游能识别和处理上游的输出，这个编排才能正常运行。 这个基本假设在 eino 中被清晰地表达了出来，让开发者在用 eino 做编排时，能够有十足的信心清楚编排的逻辑是如何运行和流转的，而不是从一系列的 any 中去猜测传过来的值是否正确。
-
-### graph 中的类型对齐
-
-#### edge
-
-在 graph 中，一个节点的输出将顺着 `边(edge)` 流向下一节点，因此，用边连接的节点间必须要类型对齐。
-
-如下图：
-
-> 这是一个模拟 ① 直接和大模型对话 ② 使用 RAG 模式 的场景，最后结果可用于对比两种模式的效果
-
-<a href="/img/eino/input_output_type_validate.png" target="_blank"><img src="/img/eino/input_output_type_validate.png" width="100%" /></a>
-
-图中绿色的部分，就是普通的 Edge 连接，其要求上游的输出必须能 `assign` 给下游，可以接收的类型有：
-
-① 上下游类型相同: 例如上游输出 *schema.Message 下游输入也是 *schema.Message
-
-② 下游接收接口，上游实现了该接口: 例如上游结构体实现了 Format() 接口，下游接收的是一个 interface{ Format() }。特殊情况是下游是 any（空接口），上游一定实现了 any，因此一定可以连接。
-
-③  上游是  interface，下游是具体类型:  当下游具体类型 implements 上游的 interface 类型时，有可能可以，有可能不行，在 compile 时无法确定，只有在运行时，等上游的具体类型确定了，才能最终确定。时，详细描述可见: [Eino: 编排的设计理念](/zh/docs/eino/core_modules/chain_and_graph_orchestration/orchestration_design_principles)
-
-图中黄色的部分，则是 eino 提供的另一个类型转换的机制，即: 若下游接收的类型是 `map[string]any`，但是上游输出的类型并不是 map[string]any，可以使用 `graph.AddXXXNode(node_key, xxx, compose.WithOutputKey("outkey")` 的方式将上游输出的类型转化为 map[string]any，其中 map 的 key 是 option 中指定的 OutputKey。 一般在多条边汇聚到某一个节点时，这种机制使用起来较为方便。
-
-同理，若上游是 `map[string]any` ，但是下游输入的类型并不是 map[string]any，则可以使用 `graph.AddXXXNode(node_key, xxx, compose.WithInputKey("inkey")` 来获取上游输出的其中一个 key 的 value，作为下游的输入。
-
-#### branch
-
-如果一个节点后面连接了多个 edge，则每条 edge 的下游节点都会运行一次。branch 则是另一种机制： 一个 branch 后接了 n 个节点，但仅会运行 condition 返回的那个 node key 对应的节点。同一个 branch 后的节点，必须要类型对齐。
-
-如下图:
-
-> 这是一个模拟 react agent 的运行逻辑
-
-<a href="/img/eino/branch_to_draw_loop.png" target="_blank"><img src="/img/eino/branch_to_draw_loop.png" width="100%" /></a>
-
-可以看到，一个 branch 本身拥有一个 `condition`, 这个 function 的输入必须和上游类型对齐。同时，一个 branch 后所接的各个节点，也必须和 condition 一样，要能接收上游的输出。
-
-### chain 中的类型对齐
-
-#### chain
-
-从抽象角度看，chain 就是一个 `链条`，如下所示：
-
-<a href="/img/eino/what_is_chain.png" target="_blank"><img src="/img/eino/what_is_chain.png" width="100%" /></a>
-
-逻辑节点的类型可以分为 3 类：
-
-- 可编排组件 (例如 chat model、 chat template、 retriever、 lambda、graph 等等)
-- branch 节点
-- parallel 节点
-
-可以看到，在 chain 的视角下，不论是简单的节点(eg： chat model) 还是复杂的节点 (eg: graph、branch、parallel)，都是一样的，在运行过程中，一步的执行就是一个节点的运行。
-
-也因此，chain 的上下游节点间，类型必须是对齐的，如下：
-
-```go
-func TestChain() {
-    chain := compose.NewChain[map[string]interface,string]()
-    
-    nodeTemplate := &fakeChatTemplate{} // input: map[string]any, output: []*schema.Message
-    
-    nodeHistoryLambda := &fakeLambda{} // input: []*schema.Message, output: []*schema.Message
-    
-    nodeChatModel := &fakeChatModel{} // input: []*schema.Message, output: *schema.Message
-    
-    nodeConvertResLambda := &fakeLambda{} // input: *schema.Message, output: string
-    
-    chain.
-        AppendChatTemplate(nodeTemplate).
-        AppendLambda(nodeHistoryLambda).
-        AppendChatModel(nodeChatModel).
-        AppendLambda(nodeConvertResLambda)
-}
-```
-
-上面的逻辑用图来表示如下：
-
-<a href="/img/eino/nodes_type_validate.png" target="_blank"><img src="/img/eino/nodes_type_validate.png" width="100%" /></a>
-
-若上下游的类型没有对齐，chain 会在 chain.Compile() 时返回错误。而 graph 会在 graph.AddXXXNode() 时就报错。
-
-#### parallel
-
-parallel 在 chain 中是一类特殊的节点，从 chain 的角度看 parallel 和其他的节点没啥区别。在 parallel 内部，其基本拓扑结构如下：
-
-<a href="/img/eino/same_type_of_parallel.png" target="_blank"><img src="/img/eino/same_type_of_parallel.png" width="100%" /></a>
-
-graph 中的多 edge 形成的结构其中一种就是这个，这里的基本假设是： 一个 parallel 的每一条边上有且仅有一个节点。当然，这一个节点也可以是 graph。但注意，目前框架没有直接提供在 parallel 中嵌套 branch 或 parallel 的能力。
-
-在 parallel 中的每个节点，由于其上游节点是同一个，因此他们都要和上游节点的输出类型对齐，比如图中上游节点输出了 `*schema.Message` ，则每个节点都要能接收这个类型。接收的方式和 graph 中的一致，通常可以用 `相同类型` 、`接口定义` 、`any`、`input key option` 的方式。
-
-parallel 节点的输出一定是一个 `map[string]any`，其中的 key 则是在 `parallel.AddXXX(output_key, xxx, opts...)` 时指定的 output_key，value 是节点内部的实际输出。
-
-一个 parallel 的构建例子如下：
-
-```go
-func TestParallel() {
-    chain := compose.NewChain[map[string]any, map[string]*schema.Message]()
-    
-    parallel := compose.NewParallel()
-    model01 := &fakeChatModel{} // input: []*schema.Message, output: *schema.Message
-    model02 := &fakeChatModel{} // input: []*schema.Message, output: *schema.Message
-    model03 := &fakeChatModel{} // input: []*schema.Message, output: *schema.Message
-    
-    parallel.
-        AddChatModel("outkey_01", model01).
-        AddChatModel("outkey_02", model02).
-        AddChatModel("outkey_03", model03)
-    
-    lambdaNode := &fakeLambdaNode{} // input: map[string]any, output: map[string]*schema.Message
-    
-    chain.
-        AppendParallel(parallel).
-        AppendLambda(lambdaNode)
-}
-```
-
-一个 parallel 在 chain 中的视角如下：
-
-> 图中是模拟同一个提问，由不同的大模型去回答，结果可用于对比效果
-
-<a href="/img/eino/graph_as_chain_node.png" target="_blank"><img src="/img/eino/graph_as_chain_node.png" width="100%" /></a>
-
-> 需要注意的是，这个结构只是逻辑上的视角，由于 chain 本身也是用 graph 实现的，parallel 在底层 graph 中会平铺到图中。
-
-#### branch
-
-chain 的 branch 和 graph 中的 branch 类似，branch 中的所有节点都要和上游节点的类型对齐，此处不再赘述。chain branch 的特殊之处是，branch 的所有可能的分支节点，都会连到 chain 中的同一个节点，或者都会连到 END。
-
-### Workflow 中的类型对齐
-
-Workflow 的类型对齐的维度，由整体的 Input & Output 改成了字段级别。具体可分为：
-
-- 上游输出的整体，类型对齐到下游的某个具体字段。
-- 上游输出的某个具体字段，类型对齐到下游的整体。
-- 上游输出的某个具体字段，类型对齐到下游输入的某个具体字段。
-
-原理和规则与整体的类型对齐相同。
-
-### StateHandler 的类型对齐
-
-StatePreHandler: 输入类型需要对齐对应节点的非流式输入类型。
-
-```go
-// input 类型为 []*schema.Message，对齐 ChatModel 的非流式输入类型
-preHandler := func(ctx context.Context, input []*schema.Message, state *state) ([]*schema.Message, error) {
-    // your handler logic
-}
-
-AddChatModelNode("xxx", model, WithStatePreHandler(preHandler))
-```
-
-StatePostHandler: 输入类型需要对齐对应节点的非流式输出类型。
-
-```go
-// input 类型为 *schema.Message，对齐 ChatModel 的非流式输出类型
-postHandler := func(ctx context.Context, input *schema.Message, state *state) (*schema.Message, error) {
-    // your handler logic
-}
-
-AddChatModelNode("xxx", model, WithStatePostHandler(postHandler))
-```
-
-StreamStatePreHandler: 输入类型需要对齐对应节点的流式输入类型。
-
-```go
-// input 类型为 *schema.StreamReader[[]*schema.Message]，对齐 ChatModel 的流式输入类型
-preHandler := func(ctx context.Context, input *schema.StreamReader[[]*schema.Message], state *state) (*schema.StreamReader[[]*schema.Message], error) {
-    // your handler logic
-}
-
-AddChatModelNode("xxx", model, WithStreamStatePreHandler(preHandler))
-```
-
-StreamStatePostHandler: 输入类型需要对齐对应节点的流式输出类型。
-
-```go
-// input 类型为 *schema.StreamReader[*schema.Message]，对齐 ChatModel 的流式输出类型
-postHandler := func(ctx context.Context, input *schema.StreamReader[*schema.Message], state *state) (*schema.StreamReader[*schema.Message], error) {
-    // your handler logic
-}
-
-AddChatModelNode("xxx", model, WithStreamStatePostHandler(postHandler))
-```
-
-### invoke 和 stream 下的类型对齐方式
-
-在 Eino 中，编排的结果是 graph 或 chain，若要运行，则需要使用 `Compile()` 来生成一个 `Runnable` 接口。
-
-Runnable 的一个重要作用就是提供了 「Invoke」、「Stream」、「Collect」、「Transform」 四种调用方式。
-
-> 上述几种调用方式的介绍以及详细的 Runnable 介绍可以查看: [Eino 流式编程要点](/zh/docs/eino/core_modules/chain_and_graph_orchestration/stream_programming_essentials)
-
-假设我们有一个 `Graph[[]*schema.Message, []*schema.Message]`，里面有一个 ChatModel 节点，一个 Lambda 节点，Compile 之后是一个 `Runnable[[]*schema.Message, []*schema.Message]`。
-
-```go
-package main
-
-import (
-    "context"
-    "io"
-    "testing"
-
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-    "github.com/stretchr/testify/assert"
-)
-
-func TestTypeMatch(t *testing.T) {
-    ctx := context.Background()
-
-    g1 := compose.NewGraph[[]*schema.Message, string]()
-    _ = g1.AddChatModelNode("model", &mockChatModel{})
-    _ = g1.AddLambdaNode("lambda", compose.InvokableLambda(func(_ context.Context, msg *schema.Message) (string, error) {
-       return msg.Content, nil
-    }))
-    _ = g1.AddEdge(compose.START, "model")
-    _ = g1.AddEdge("model", "lambda")
-    _ = g1.AddEdge("lambda", compose.END)
-
-    runner, err := g1.Compile(ctx)
-    assert.NoError(t, err)
-
-    c, err := runner.Invoke(ctx, []*schema.Message{
-       schema.UserMessage("what's the weather in beijing?"),
-    })
-    assert.NoError(t, err)
-    assert.Equal(t, "the weather is good", c)
-
-    s, err := runner.Stream(ctx, []*schema.Message{
-       schema.UserMessage("what's the weather in beijing?"),
-    })
-    assert.NoError(t, err)
-
-    var fullStr string
-    for {
-       chunk, err := s.Recv()
-       if err != nil {
-          if err == io.EOF {
-             break
-          }
-          panic(err)
-       }
-
-       fullStr += chunk
-    }
-    assert.Equal(t, c, fullStr)
-}
-```
-
-当我们以 Stream 方式调用上面编译好的 Runnable 时，model 节点会输出 `*schema.StreamReader[*Message]`，但是 lambda 节点是 InvokableLambda，只接收非流式的 `*schema.Message` 作为输入。这也符合类型对齐规则，因为 Eino 框架会自动把流式的 Message 拼接成完整的 Message。
-
-在 stream 模式下，拼接帧 是一个非常常见的操作，拼接时，会先把 `*StreamReader[T] ` 中的所有元素取出来转成 `[]T`，再尝试把 `[]T` 拼接成一个完整的 `T`。框架内已经内置支持了如下类型的拼接:
-
-- `*schema.Message`:  详情见 `schema.``ConcatMessages``()`
-- `string`: 实现逻辑等同于 `+=`
-- `[]*schema.Message`: 详情见 `compose.concatMessageArray()`
-- `Map`: 把相同 key 的 val 进行合并，合并逻辑同上，若存在无法合并的类型，则失败 (ps: 不是覆盖)
-- 其他 slice：只有当 slice 中只有一个元素是非零值时，才能合并。
-
-对其他场景，或者当用户想用定制逻辑覆盖掉上面的默认行为时，开发者可自行实现 concat 方法，并使用 `compose.RegisterStreamChunkConcatFunc()` 注册到全局的拼接函数中。
-
-示例如下：
-
-```go
-// 假设我们自己的结构体如下
-type tStreamConcatItemForTest struct {
-    s string
-}
-
-// 实现一个拼接的方法
-func concatTStreamForTest(items []*tStreamConcatItemForTest) (*tStreamConcatItemForTest, error) {
-    var s string
-    for _, item := range items {
-        s += item.s
-    }
-
-    return &tStreamConcatItemForTest{s: s}, nil
-}
-
-func Init() {
-    // 注册到全局的拼接方法中
-    compose.RegisterStreamChunkConcatFunc(concatTStreamForTest)
-}
-```
-
-### 类型对齐在运行时检查的场景
-
-eino 的 Graph 类型对齐检查，会在 `err = graph.AddEdge("node1", "node2")` 时检查两个节点类型是否匹配，也就能在 `构建 graph 的过程`，或 `Compile 的过程` 发现类型不匹配的错误，这适用于 [Eino: 编排的设计理念](/zh/docs/eino/core_modules/chain_and_graph_orchestration/orchestration_design_principles) 中所列举的 ① ② ③ 条规则。
-
-当上游节点的输出为 `interface` 时，若下游节点类型实现了该 `interface`，则上游有可能可以转成下游类型 (类型断言)，但只能在 `运行过程` 才能清楚能否转换成功，该场景的类型检查移到了运行过程中。
-
-其结构可见下图：
-
-<a href="/img/eino/input_type_output_type_in_edge.png" target="_blank"><img src="/img/eino/input_type_output_type_in_edge.png" width="100%" /></a>
-
-这种场景适用于开发者能自行处理好上下游类型对齐的情况，可根据不同类型选择下游执行节点。
-
-## 带有明确倾向性的设计选择
-
-### 外部变量只读原则
-
-Eino 的 Graph 中的数据在 Node、Branch、Handler 间流转时，一律是变量赋值，不是 Copy。当 Input 是引用类型，如 Struct 指针、map、slice 时，在 Node、Branch、Handler 内部对 Input 的修改，会对外部有副作用，可能导致并发问题。因此，Eino 遵循外部变量只读原则：Node、Branch、Handler 内部不对 Input 做修改，如需修改，先自行 Copy。
-
-这个原则对 StreamReader 中的 Chunk 同样生效。
-
-### 扇入与合并
-
-**扇入**：多个上游的数据汇入到下游，一起作为下游的输入。需要明确定义多个上游的输出，如何**合并（Merge）**起来。
-
-默认情况下，首先要求多个上游输出的**实际类型**必须相同且为 Map，且相互间 key 不可重复。其次：
-
-- 在非流式场景下，合并后成为一个 Map，包含所有上游的所有键值对。
-- 在流式场景下，将类型相同的多个上游 StreamReader 合并为一个 StreamReader。实际 Recv 时效果为从多个上游 StreamReader 中公平读取。
-
-在 AddNode 时，可以通过添加 WithOutputKey 这个 Option 来把节点的输出转成 Map：
-
-```go
-// 这个节点的输出，会从 string 改成 map[string]any，
-// 且 map 中只有一个元素，key 是 your_output_key，value 是实际的的节点输出的 string
-graph.AddLambdaNode("your_node_key", compose.InvokableLambda(func(ctx context.Context, input []*schema.Message) (str string, err error) {
-    // your logic
-    return
-}), compose.WithOutputKey("your_output_key"))
-```
-
-也可以通过注册 Merge 方法来实现任意类型的 merge：
-
-```go
-// eino/compose/values_merge.go
-func RegisterValuesMergeFunc[T any](fn func([]T) (T, error))
-```
-
-Workflow 可以做到多个上游的多个输出字段映射到下游节点的不同字段。这并不属于合并场景，而是点对点的字段映射。事实上，eino workflow 目前不支持“多个上游字段同时映射到相同的下游字段”。
-
-### 流式处理
-
-Eino 认为，组件应当只需要实现业务场景中真实的流式范式，比如 ChatModel 不需要实现 Collect。因此，在编排场景中，Eino 自动帮助所有的节点**补全缺失的流式范式**。
-
-以 Invoke 方式运行 Graph，内部各节点均以 Invoke 范式运行，以 Stream, Collect 或 Transform 方式运行 Graph，内部各节点均以 Transform 范式运行。
-
-**自动拼接(Concatenate)**：Stream chunk 拼接为完整内容的场景，优先使用用户注册的自定义拼接函数，其次执行框架提供的默认行为，包括 Message, Message 数组，String，Map 和 Struct 及 Struct 指针。
-
-**自动流化(Box)**：需要将非流式的 T 变成 StreamReader[T] 的场景，框架自动执行。
-
-**自动合并(Merge)**：见上文“扇入与合并”环节。
-
-**自动复制(Copy)**：在需要做流的复制的场景自动进行流的复制，包括一个流扇出到多个下游节点，一个流进入一个或多个 callback handler。
-
-最后，Eino 要求所有编排元素能够感知和处理流。包括 branch，state handler，callback handler，passthrough，lambda 等。
-
-关于 Eino 对流的处理能力，详见 [Eino 流式编程要点](/zh/docs/eino/core_modules/chain_and_graph_orchestration/stream_programming_essentials)。
-
-### 全局状态
-
-**State**：在 NewGraph 时通过 `compose.WithGenLocalState` 传入 State 的创建方法。这个请求维度的全局状态在一次请求的各环节可读写使用。
-
-Eino 推荐用 `StatePreHandler` 和  `StatePostHandler`，功能定位是：
-
-- StatePreHandler：在每个节点执行前读写 State，以及按需替换节点的 Input。输入需对齐节点的非流式输入类型。
-- StatePostHandler：在每个节点执行后读写 State，以及按需替换节点的 Output。输入需对齐节点的非流式输出类型。
-
-针对流式场景，使用对应的 `StreamStatePreHandler` 和 `StreamStatePostHandler`，输入需分别对齐节点的流式输入和流式输出类型。
-
-这些 state handlers 位于节点外部，通过对 Input 或 Output 的修改影响节点，从而保证了节点的“状态无关”特性。
-
-如果需要在节点内部读写 State，Eino 提供了 `ProcessState[S any](ctx context.Context`**, **`handler func(context.Context`**, **`S) error) error` 函数。
-
-Eino 框架会在所有读写 State 的位置加锁。
-
-### 回调注入
-
-Eino 编排框架认为，进入编排的组件，可能内部埋入了 Callback 切面，也可以没有。这个信息由组件是否实现了 `Checker` 接口，以及接口中 `IsCallbacksEnabled` 方法的返回值来判断。
-
-- 当 `IsCallbacksEnabled` 返回 true 时，Eino 编排框架使用组件实现内部的 Callback 切面。
-- 否则，自动在组件实现外部包上 Callback 切面，（只能）上报 input 和 output。
-
-无论哪种，都会自动推断出 RunInfo。
-
-同时，对 Graph 整体，也一定会注入 Callback 切面，RunInfo 为 Graph 自身。
-
-关于 Eino 的 Callback 能力完整说明，见 [Eino: Callback 用户手册](/zh/docs/eino/core_modules/chain_and_graph_orchestration/callback_manual)。
-
-### Option 分配
-
-Eino 支持各种维度的 Call Option 分配方式：
-
-- 默认全局，即分配到所有节点，包括嵌套的内部图。
-- 可添加某个组件类型的 Option，这时默认分配到该类型的所有节点，比如 AddChatModelOption。定义了独有 Option 类型的 Lambda，也可以这样把 Option 指定到自身。
-- 可指定任意个具体的节点，使用 `DesignateNode(key ...string)`.
-- 可指定任意深度的嵌套图，或者其中的任意个具体的节点，使用 `DesignateNodeWithPath(path ...*NodePath)`.
-
-关于 Eino 的 Call Option 能力完整说明，见 [Eino: CallOption 能力与规范](/zh/docs/eino/core_modules/chain_and_graph_orchestration/call_option_capabilities)。
-
-### 图嵌套
-
-图编排产物 `Runnable` 与 Lambda 的接口形式非常相似。因此编译好的图可以简单的封装为 Lambda，并以 Lambda 节点的形式嵌套进其他图中。
-
-另一种方式，在编译前，Graph，Chain，Workflow 等都可以直接通过 AddGraph 的方式嵌套进其他图中。两个方式的差异是：
-
-- Lambda 的方式，在 trace 上会多一级 Lambda 节点。其他 Callback handler 视角看也会多一层。
-- Lambda 的方式，需要通过 Lambda 的 Option 来承接 CallOption，无法通过 DesignateNodeWithPath。
-- Lambda 的方式，内部图需事先编译。直接 AddGraph，则内部图随上级图一起编译。
-
-## 内部机制
-
-### 执行时序
-
-以一个添加了 StatePreHandler、StatePostHandler、InputKey、OutputKey，且内部没有实现 Callback 切面的 InvokableLambda（输入为 string，输出为 int）为例，在图中的流式执行完整时序如下：
-
-<a href="/img/eino/graph_node_run_wrapper.png" target="_blank"><img src="/img/eino/graph_node_run_wrapper.png" width="100%" /></a>
-
-在 workflow 的场景中，字段映射发生在两个位置：
-
-- 在节点执行后的 StatePostHandler 以及“流复制”步骤后，每个下游需要的字段会分别抽取出来。
-- 在节点执行前的“合并”步骤之后、StatePreHandler 之前，会将抽取出来的上游字段值转换为当前节点的输入。
-
-### 运行引擎
-
-`NodeTriggerMode == AnyPredecessor` 时，图以 pregel 引擎执行，对应的拓扑结构是有向有环图。特点是：
-
-- 当前执行中的一个或多个节点，所有的后序节点，作为一个 SuperStep，整体一起执行。这时，这些新的节点，会成为“当前”节点。
-- 支持 Branch，支持图中有环，但是可能需要人为添加 passthrough 节点，来确保 SuperStep 中的节点符合预期，如下图：
-
-<a href="/img/eino/graph_steps_in_graph2.png" target="_blank"><img src="/img/eino/graph_steps_in_graph2.png" width="100%" /></a>
-
-上图中 Node 4 和 Node 5 按规则被放在一起执行，大概率不符合预期。需要改成：
-
-<a href="/img/eino/graph_steps_in_graph.png" target="_blank"><img src="/img/eino/graph_steps_in_graph.png" width="100%" /></a>
-
-`NodeTriggerMode == AllPredecessor` 时，图以 dag 引擎执行，对应的拓扑结构是有向无环图。特点是：
-
-- 每个节点有确定的前序节点，当所有前序节点都完成后，本节点才具备运行条件。
-- 不支持图中有环，因为会打破“每个节点有确定的前序节点”这一假定。
-- 支持 Branch。在运行时，将 Branch 未选中的节点记为已跳过，不影响 AllPredecessor 的语义。
-
-> 💡
-> 设置 NodeTriggerMode = AllPredecessor 后，节点会在所有前驱就绪后执行，但并不是立即执行，而是依然遵循 SuperStep——在一批节点全部执行完成后再运行新的可运行节点。
->
-> 如果在 Compile 时传入 compose.WithEagerExecution()，则就绪的节点会立刻运行。
->
-> 在 Eino v0.4.0 版本及之后的版本中，设置 NodeTriggerMode = AllPredecessor 后会默认开启 EagerExecution。
-
-总结起来，pregel 模式灵活强大但有额外的心智负担，dag 模式清晰简单但场景受限。在 Eino 框架中，Chain 是 pregel 模式，Workflow 是 dag 模式，Graph 则都支持，可由用户从 pregel 和 dag 中选择。

docs/Eino/docs/core_modules/chain_and_graph_orchestration/stream_programming_essentials.md

@@ -1,222 +0,0 @@
----
-Description: ""
-date: "2026-01-30"
-lastmod: ""
-tags: []
-title: Eino 流式编程要点
-weight: 4
----
-
-> 💡
-> 建议先看：[Eino: 基础概念介绍](/zh/docs/eino/overview) [Eino: 编排的设计理念](/zh/docs/eino/core_modules/chain_and_graph_orchestration/orchestration_design_principles)
-
-## 编排流式概述
-
-<a href="/img/eino/eino_component_runnable.png" target="_blank"><img src="/img/eino/eino_component_runnable.png" width="100%" /></a>
-
-编排流式的 Graph 时，需要考虑的几个关键要素：
-
-- 组件/Lambda 中包含哪几种 Lambda 算子： 从 Invoke、Stream、Collect、Transform 中任选
-- 编排拓扑图中，上下游节点的输入、输出是否同为流或同为非流。
-- 如果上下游节点的流类型无法匹配。 需要借助 流化、合包 两个操作
-  - 流化(Streaming)：将 T 流化成单 Chunk 的 Stream[T]
-  - 合包(Concat)：将 Stream[T] 合并成一个完整的 T。Stream[T] 中的每一“帧”是这个完整 T 的一部分。
-
-## Eino 流式编程的内涵
-
-- 有的组件，天然支持分“帧”来输出，每次输出一个完整出参的一部分，即“流式”输出。流式输出完成后，需要下游把这些“帧”拼接（concat）成完整的出参。典型的例子，是 LLM。
-- 有的组件，天然支持分“帧”来输入，接收到不完整的入参时，就能开始有意义的业务处理，甚至完成业务处理的过程。比如 react agent 中用来判断是调 tool 还是结束运行的 branch 里面，拿到 LLM 的流式输出，从第一个帧里面就可以通过判断 message 是否包含 tool call 来做出决策。
-- 因此，一个组件，从入参角度看，有“非流式”入参和“流式”入参两种，从出参角度看，有“非流式”出参和“流式”出参两种。
-- 组合起来，有四种可能的流式编程范式
-
-<table>
-<tr><td>函数名</td><td>模式说明</td><td>交互模式名称</td><td>Lambda 构造方法</td><td>说明</td></tr>
-<tr><td>Invoke</td><td>输入非流式、输出非流式</td><td>Ping-Pong 模式</td><td>compose.InvokableLambda()</td><td></td></tr>
-<tr><td>Stream</td><td>输入非流式、输出流式</td><td>Server-Streaming 模式</td><td>compose.StreamableLambda()</td><td></td></tr>
-<tr><td>Collect</td><td>输入流式、输出非流式</td><td>Client-Streaming</td><td>compose.CollectableLambda()</td><td></td></tr>
-<tr><td>Transform</td><td>输入流式、输出流式</td><td>Bidirectional-Streaming</td><td>compose.TransformableLambda()</td><td></td></tr>
-</table>
-
-## 单个组件角度的流式
-
-Eino 是个 "component first" 的框架，组件可以独立使用。定组件接口的时候，需要考虑流式编程的问题吗？简单的答案是不需要。复杂的答案是“以业务真实场景为准”。
-
-### 组件自身的业务范式
-
-一个典型的组件，比如 Chat Model，Retriever 等，根据实际的业务语义定接口就行，如果实际上支持某种流式的范式，就实现那一种流式范式，如果实际上某种流式范式没有真正的业务场景，那就不需要实现。比如
-
-- Chat Model，除了 Invoke 这种非流式的范式外，还天然支持 Stream 这种流式范式，因此 Chat Model 的接口中，实现了 Generate 和 Stream 两个接口。但是 Collect 和 Transform 没有对应的真实业务场景，所以就没有实现相应的接口：
-
-```go
-type ChatModel interface {
-    Generate(ctx context.Context, input []*schema.Message, opts ...Option) (*schema.Message, error)
-    Stream(ctx context.Context, input []*schema.Message, opts ...Option) (
-       *schema.StreamReader[*schema.Message], error)
-    // other methods omitted...
-}
-```
-
-- Retriever，除了 Invoke 这种非流式的范式外，另外三种流式范式都没有真实的业务场景，因此只实现了 Retrieve 一个接口：
-
-```go
-type Retriever interface {
-    Retrieve(ctx context.Context, query string, opts ...Option) ([]*schema.Document, error)
-}
-```
-
-### 组件具体支持的范式
-
-<table>
-<tr><td>组件名称</td><td>是否实现 Invoke</td><td>是否实现 Stream</td><td>是否实现 Collect</td><td>是否实现 Transform</td></tr>
-<tr><td>Chat model</td><td>yes</td><td>yes</td><td>no</td><td>no</td></tr>
-<tr><td>Chat template</td><td>yes</td><td>no</td><td>no</td><td>no</td></tr>
-<tr><td>Retriever</td><td>yes</td><td>no</td><td>no</td><td>no</td></tr>
-<tr><td>Indexer</td><td>yes</td><td>no</td><td>no</td><td>no</td></tr>
-<tr><td>Embedder</td><td>yes</td><td>no</td><td>no</td><td>no</td></tr>
-<tr><td>Document Loader</td><td>yes</td><td>no</td><td>no</td><td>no</td></tr>
-<tr><td>Document Transformer</td><td>yes</td><td>no</td><td>no</td><td>no</td></tr>
-<tr><td>Tool</td><td>yes</td><td>yes</td><td>no</td><td>no</td></tr>
-</table>
-
-Eino 官方组件中，除了 Chat Model 和 Tool 额外支持 stream 外，其他所有组件都只支持 invoke。组件具体介绍参见：[[更新中]Eino: Components 抽象&实现](/zh/docs/eino/core_modules/components)
-
-Collect 和 Transform 两种流式范式，目前只在编排场景有用到。
-
-## 多个组件编排角度的流式
-
-### 组件在编排中的流式范式
-
-一个组件，单独使用时，入参和出参的流式范式是框定的，不可能超出组件定义的接口范围。
-
-- 比如 Chat Model，入参只可能是非流式的 []Message，出参则可能是非流式的 Message 或者流式的 StreamReader[Message]，因为 Chat Model 只实现了 Invoke 和 Stream 两个范式。
-
-但是，一个组件，一旦处在多个组件组合使用的“编排”场景中，它的入参和出参就没那么固定了，而是取决于这个组件在编排场景中的“上游输出”和“下游输入”。比如 React Agent 的典型编排示意图：
-
-<a href="/img/eino/chatmodel_to_tool.png" target="_blank"><img src="/img/eino/chatmodel_to_tool.png" width="100%" /></a>
-
-上图中，如果 Tool 是个 StreamableTool，也就是输出是 StreamReader[Message]，则 Tool -> ChatModel 就可能是流式的输出。但是 Chat Model 并没有接收流式输入的业务场景，也没有对应的接口。这时 Eino 框架会自动帮助 ChatModel 补足接收流式输入的能力：
-
-<a href="/img/eino/chatmodel_tool_loop.png" target="_blank"><img src="/img/eino/chatmodel_tool_loop.png" width="100%" /></a>
-
-上面的 Concat message stream 是 Eino 框架自动提供的能力，即使不是 message，是任意的 T，只要满足特定的条件，Eino 框架都会自动去做这个 StreamReader[T] 到 T 的转化，这个条件是：**在编排中，当一个组件的上游输出是 StreamReader[T]，但是组件只提供了 T 作为输入的业务接口时，框架会自动将 StreamReader[T] concat 成 T，再输入给这个组件。**
-
-> 💡
-> 框架自动将 StreamReader[T] concat 成 T 的过程，可能需要用户提供一个 Concat function。详见 [Eino: 编排的设计理念](/zh/docs/eino/core_modules/chain_and_graph_orchestration/orchestration_design_principles) 中关于“合并帧”的章节。
-
-另一方面，考虑一个相反的例子。还是 React Agent，这次是一个更完整的编排示意图：
-
-<a href="/img/eino/tool_model_react.png" target="_blank"><img src="/img/eino/tool_model_react.png" width="100%" /></a>
-
-在上图中，branch 接收 chat model 输出的 message，并根据 message 中是否包含 tool call，来选择直接结束 agent 本次运行并将 message 输出，还是调用 Tool 并将调用结果再次给 Chat Model 循环处理。由于这个 Branch 可以通过 message stream 的首个帧就完成逻辑判断，因此我们给这个 Branch 定义的是 Collect 接口，即流式输入，非流式输出：
-
-```go
-compose.NewStreamGraphBranch(func(ctx context.Context, sr *schema.StreamReader[*schema.Message]) (endNode string, err error) {
-    msg, err := sr.Recv()
-    if err != nil {
-       return "", err
-    }
-    defer sr.Close()
-
-    if len(msg.ToolCalls) == 0 {
-       return compose._END_, nil
-    }
-
-    return nodeKeyTools, nil
-}
-```
-
-ReactAgent 有两个接口，Generate 和 Stream，分别实现了 Invoke 和 Stream 的流式编程范式。当一个 ReactAgent 以 Stream 的方式被调用时，Chat Model 的输出是 StreamReader[Message]，因此 Branch 的输入是 StreamReader[Message]，符合这个 Branch condition 的函数签名定义，不需要做任何的转换就可以运行。
-
-但是，当这个 ReactAgent 以 Generate 的方式被调用时，Chat Model 的输出是 Message，因此 Branch 的输入也会是 Message，不符合 Branch Condition 的 StreamReader[Message] 的函数签名定义。这时，Eino 框架会自动将 Message 装箱成 StreamReader[Message]，再传给 Branch，而这个 StreamReader 里面只会有一个帧。
-
-> 💡
-> 这种只有一个帧的流，俗称“假流”，因为它并没有带来流式的实际好处即“首包延迟低”，而是仅仅为了满足流式出入参接口签名的要求而做的简单装箱。
-
-总结起来，就是：**在编排中，当一个组件的上游输出是 T，但是组件只提供了 StreamReader[T] 作为输入的业务接口时，框架会自动将 T 装箱成 StreamReader[T] 的单帧流，再输入给这个组件。**
-
-### 编排辅助元素的流式范式
-
-上面提到的 Branch，并不是一个可单独使用的组件，而是只在编排场景中才有意义的“编排辅助元素”，类似的仅编排场景有意义的“组件”，还有一些，详见下图：
-
-<table>
-<tr><td>组件名称</td><td>使用场景</td><td>是否实现 Invoke</td><td>是否实现 Stream</td><td>是否实现 Collect</td><td>是否实现 Transform</td></tr>
-<tr><td>Branch</td><td>根据上游输出，在一组下游 Node 中动态选择一个<li>只能在接收到完整入参后才能判断的，实现 Invoke</li><li>可以在接收部分帧后做判断的，实现 Collect</li><li>两者只能实现一个</li></td><td>yes</td><td>no</td><td>yes</td><td>no</td></tr>
-<tr><td>StatePreHandler</td><td>Graph中，进入 Node 前修改 State 或/与 Input。可支持流式。</td><td>yes</td><td>no</td><td>no</td><td>yes</td></tr>
-<tr><td>StatePostHandler</td><td>Graph中，Node 完成后修改 State 或/与 Output。可支持流式</td><td>yes</td><td>no</td><td>no</td><td>yes</td></tr>
-<tr><td>Passthrough</td><td>在并行情况下，为了打平每个并行分支的 Node 个数，可以给 Node 个数少的分支加 Passthrough 节点。Passthrough 节点的输入输出相同，跟随上游节点的输出或跟随下游节点的输入（预期应当相同）。</td><td>yes</td><td>no</td><td>no</td><td>yes</td></tr>
-<tr><td>Lambda</td><td>封装官方组件未定义的业务逻辑。业务逻辑是哪种范式，就选择对应的那种流式范式来实现。</td><td>yes</td><td>yes</td><td>yes</td><td>yes</td></tr>
-</table>
-
-另外还有一种只有编排场景才有意义的“组件”，就是把编排产物作为一个整体来看待，比如编排后的 Chain，Graph。这些整体的编排产物，既可以作为“组件”来单独调用，也可以作为节点加入到更上级的编排产物中。
-
-## 编排整体角度的流式
-
-### 编排产物的“业务”范式
-
-既然整体的编排产物，可以被看做一个“组件”，那从组件的视角可以提出问题：编排产物这个“组件”，有没有像 Chat Model 等组件那样的，符合“业务场景”的接口范式？答案是既“有”也“没有”。
-
-- “没有”：整体而言，Graph，Chain 等编排产物，自身是没有业务属性的，只为抽象的编排服务的，因此也就没有符合业务场景的接口范式。同时，编排需要支持各种范式的业务场景。所以，Eino 中代表编排产物的 Runnable[I, O] 接口，不做选择也无法选择，提供了所有流式范式的方法：
-
-```go
-type Runnable[I, O any] interface {
-    Invoke(ctx context.Context, input I, opts ...Option) (output O, err error)
-    Stream(ctx context.Context, input I, opts ...Option) (output *schema.StreamReader[O], err error)
-    Collect(ctx context.Context, input *schema.StreamReader[I], opts ...Option) (output O, err error)
-    Transform(ctx context.Context, input *schema.StreamReader[I], opts ...Option) (output *schema.StreamReader[O], err error)
-}
-```
-
-- “有”：具体而言，某一个具体的 Graph、Chain，一定是承载了具体的业务逻辑的，因此也就一定有适合那个特定业务场景的流式范式。比如类似 React Agent 的 Graph，匹配的业务场景是 Invoke 和 Stream，因此这个 Graph 在调用时，符合逻辑的调用方式是 Invoke 和 Stream。虽然编排产物本身接口 Runnable[I, O] 中有 Collect 和 Transform 的方法，但是正常的业务场景不需要使用。
-
-### 编排产物内部各组件在运行时的范式
-
-从另一个角度看，既然编排产物整体可以被看做“组件”，那“组件”必然有自己的内部实现，比如 ChatModel 的内部实现逻辑，可能是把入参的 []Message 转化成各个模型的 API request，之后调用模型的 API，获取 response 后再转化成出参的 Message。那么类比的话，Graph 这个“组件”的内部实现是什么？是数据在 Graph 内部各个组件间以用户指定的流转方向和流式范式来流转。其中，“流转方向”不在当前讨论范围内，而各组件运行时的流式范式，则由 Graph 整体的触发方式决定，具体来说：
-
-如果用户通过 **Invoke** 来调用 Graph，则 Graph 内部所有组件都以 Invoke 范式来调用。如果某个组件，没有实现 Invoke 范式，则 Eino 框架自动根据组件实现了的流式范式，封装出 Invoke 调用范式，优先顺位如下：
-
-- 若组件实现了 Stream，则将 Stream 封装成 Invoke，即自动 concat 输出流。
-
-<a href="/img/eino/invoke_outside_stream_inside.png" target="_blank"><img src="/img/eino/invoke_outside_stream_inside.png" width="100%" /></a>
-
-- 否则，若组件实现了 Collect，则将 Collect 封装成 Invoke，即非流式入参转单帧流。
-
-<a href="/img/eino/invoke_outside_collect_inside.png" target="_blank"><img src="/img/eino/invoke_outside_collect_inside.png" width="100%" /></a>
-
-- 如果都没实现，则必须实现 Transform，将 Transform 封装成 Invoke，即入参转单帧流，出参 concat。
-
-<a href="/img/eino/invoke_outside_transform_inside.png" target="_blank"><img src="/img/eino/invoke_outside_transform_inside.png" width="100%" /></a>
-
-如果用户通过 **Stream/Collect/Transform** 来调用 Graph，则 Graph 内部所有组件都以 Transform 范式来调用。如果某个组件，没有实现 Transform 范式，则 Eino 框架自动根据组件实现了的流式范式，封装出 Transform 调用范式，优先顺位如下：
-
-- 若组件实现了 Stream，则将 Stream 封装成 Transform，即自动 concat 输入流。
-
-<a href="/img/eino/transform_inside_stream_inside.png" target="_blank"><img src="/img/eino/transform_inside_stream_inside.png" width="100%" /></a>
-
-- 否则，若组件实现了 Collect，则将 Collect 封装成 Transform，即非流式出参转单帧流。
-
-<a href="/img/eino/transform_outside_stream_inside.png" target="_blank"><img src="/img/eino/transform_outside_stream_inside.png" width="100%" /></a>
-
-- 如果都没实现，则必须实现 Invoke，将 Invoke 封装成 Transform，即入参流 concat，出参转单帧流
-
-<a href="/img/eino/transform_outside_invoke_inside.png" target="_blank"><img src="/img/eino/transform_outside_invoke_inside.png" width="100%" /></a>
-
-结合上面穷举的各种案例，Eino 框架对 T 和 Stream[T] 的自动转换，可以总结为：
-
-- **T -> Stream[T]: 将完整的 T 装箱为单帧的 Stream[T]。非流式变假流式。**
-- **Stream[T] -> T: 将 Stream[T] Concat 为完整的 T。当 Stream[T] 不是单帧流时，可能需要提供针对 T 的 Concat 方法。**
-
-看了上面的实现原理，可能会有疑问，为什么对 graph 的 Invoke，会要求所有内部组件都以 Invoke 调用？以及为什么对 graph 的 Stream/Collect/Transform，会要求所有内部组件都以 Transform 调用？毕竟，可以举出一些反例：
-
-- A, B 两个组件编排为一个 Chain，以 Invoke 调用。其中 A 的业务接口实现了 Stream，B 的业务接口实现了 Collect。这时 graph 内部组件的调用范式有两个选择：
-  - A 以 stream 调用，B 以 collect 调用，整体的 Chain 依然是 Invoke 语义，同时保留了真流式的内部语义。即 A 的输出流不需要做 Concat，可以实时的输入到 B 中。
-  - 目前 Eino 的实现，A、B 都以 Invoke 调用，需要把 A 的输出流 Concat，并把 B 的输入做成假流式。失去了真流式的内部语义。
-- A，B 两个组件编排为一个 Chain，以 Collect 调用。其中 A 实现了 Transform 和 Collect，B 实现了 Invoke。两个选择：
-  - A 以 Collect 调用，B 以 Invoke 调用：整体还是 Collect 的语义，不需要框架做任何的自动转化和装箱操作。
-  - 目前 Eino 的实现，A、B 都以 Transform 调用，由于 A 的业务接口里实现了 Transform，因此 A 的输出和 B 的输入都可能是真流式，而 B 的业务接口里只实现了 Invoke，根据上面的分析，B 的入参会需要由真流式 concat 成非流式。这时就需要用户额外提供 B 的入参的 concat 函数，这本可以避免。
-
-上面两个例子，都可以找到一个明确的、与 Eino 的约定不同的，但却更优的流式调用路径。但是，当泛化到任意的编排场景时，很难找到一个明确定义的、与 Eino 的约定不同的、却总是更优的普适的规则。比如，A->B->C，以 Collect 语义调用，是 A->B 的时候 Collect，还是 B->C 的时候 Collect？潜在的因素有 A、B、C 具体实现的业务接口，可能还有“尽量多的使用真流式”的判断，也许还有哪个参数实现了 Concat，哪个没有实现。如果是更复杂的 Graph，需要考虑的因素会快速增加。在这种情况下，即使框架能定义出一套明确的、更优的普适规则，也很难解释清楚，理解和使用成本会很高，很可能已经超过了这个新规则实际带来的好处。
-
-综上，我们可以说，Eino 编排产物内部各组件在运行时的范式，是 **By Design** 的，明确如下：
-
-- **整体以 Invoke 调用，内部各组件均以 Invoke 调用，不存在任何流式的过程。**
-- **整体以 Stream/Collect/Transform 调用，内部各组件均以 Transform 调用，当出现 Stream[T] -> T 的 concat 过程时，可能需要额外提供 T 的 concat function。**

docs/Eino/docs/core_modules/chain_and_graph_orchestration/workflow_orchestration_framework.md

@@ -1,732 +0,0 @@
----
-Description: ""
-date: "2026-03-02"
-lastmod: ""
-tags: []
-title: Workflow 编排框架
-weight: 3
----
-
-## 什么是 Eino Workflow
-
-是一套编排的 API，与 Graph API 在架构上处于同一层：
-
-```mermaid
-flowchart LR
-  E[Eino compose engine]
-  G[Graph API]
-  W[Workflow API]
-  C[Chain API]
-  E --> G
-  E --> W
-  G --> C
-```
-
-本质特点是：
-
-- 与 Graph API 具有同等级别的能力，都是编排“围绕大模型的信息流”的合适框架工具。
-  - 在节点类型、流处理、callback、option、state、interrupt & checkpoint 等方面保持一致。
-  - 实现 AnyGraph 接口，可以在 AddGraphNode 时作为子图加入上级 Graph/Chain/Workflow。
-  - 也可以把其他 Graph/Chain/Workflow 添加为自己的子图。
-- 字段级别映射能力：节点的输入可以由任意前驱节点的任意输出字段组合而成。
-  - 原生支持 struct，map 以及任意嵌套层级的 struct 和 map 之间的相互映射。
-- 控制流与数据流分离：Graph 的 Edge 是既决定执行顺序，又决定数据传递。Workflow 中可以一起传递，也可以分开传递。
-- 不支持环（即类似 react agent 的 chatmodel->toolsNode->chatmodel 的环路）。NodeTriggerMode 固定为 AllPredecessor。
-
-## 为什么用 Workflow
-
-### 灵活的输入输出类型
-
-例如需要编排两个 lambda 节点，里面是两个“现存的业务函数 f1, f2”，输入输出类型都是符合业务场景的特定结构体，各自不一样：
-
-<a href="/img/eino/workflow_existing_biz_func.png" target="_blank"><img src="/img/eino/workflow_existing_biz_func.png" width="100%" /></a>
-
-Workflow 编排时，将 f1 的输出字段 F1，直接映射到 f2 的输入字段 F3，同时保留 f1,f2 的原始函数签名。达到的效果是：**每个节点是“业务场景决定输入输出”，不需要考虑“谁给我输入，以及谁用我的输出”**。
-
-Graph 编排时，因为“类型对齐”的要求，如果 f1 -> f2，则 f1 的输出类型和 f2 的输入类型需要对齐，需要二选一：
-
-- 定义一个新的 common struct，把 f1 的输出类型和 f2 的输入类型都改成这个 common struct。有成本，可能入侵业务逻辑。
-- f1 的输出类型和 f2 的输入类型都改成 map。丢失了强类型对齐的特性。
-
-### 控制流和数据流分离
-
-看下面这个场景：
-
-<a href="/img/eino/workflow_data_control_separate.png" target="_blank"><img src="/img/eino/workflow_data_control_separate.png" width="100%" /></a>
-
-节点 D 同时引用了 A、B、C 的某些输出字段。其中 A-D 的这条虚线，是单纯的“数据流”，不传递“控制”信息，即 A 执行完成与否，不决定 D 是否开始执行。
-
-节点 D 到 E 之间的粗箭头，代表节点 E 不引用节点 D 的任何输出，是单纯的“控制流”，不传递“数据”。即 D 执行完成与否，决定 E 是否开始执行，但是 D 的输出不影响 E 的输入。
-
-图中其他的线，是控制流与数据流合一的。
-
-需要注意的是，数据流能传递的前提，是一定有一条控制流存在，比如 A->D 的数据流，依赖 A->branch->B->D 或者 A->branch->C->D 的控制流存在。即数据流只能引用前驱节点的输出。
-
-例如这个“跨节点”传递特定数据的场景：
-
-<a href="/img/eino/workflow_cross_node_pass_data.png" target="_blank"><img src="/img/eino/workflow_cross_node_pass_data.png" width="100%" /></a>
-
-上图中，chat template 节点的输入可以是非常明确的：
-
-`map[string]any{"prompt": "prompt from START", "context": "retrieved context"}`
-
-相对的，如果使用 Graph 或者 Chain API，需要二选一：
-
-- 用 OutputKey 转换节点输出类型（START 节点没法加，所以得额外加 passthrough 节点），ChatTemplate 节点的输入会包含 START 和 retriever 的全量输出（而不是真正需要的某几个字段）.
-- START 节点的 prompt 放到 state 里面，ChatTemplate 从 state 中读。额外引入了 state。
-
-## 如何使用 Workflow
-
-### 最简单的 workflow
-
-START -> node -> END
-
-<a href="/img/eino/workflow_simple.png" target="_blank"><img src="/img/eino/workflow_simple.png" width="100%" /></a>
-
-```go
-// creates and invokes a simple workflow with only a Lambda node.
-// Since all field mappings are ALL to ALL mappings
-// (by using AddInput without field mappings),
-// this simple workflow is equivalent to a Graph: START -> lambda -> END.
-func main() {
-    // create a Workflow, just like creating a Graph
-    wf := compose.NewWorkflow[int, string]()
-
-    // add a lambda node to the Workflow, just like adding the lambda to a Graph
-    wf.AddLambdaNode("lambda", compose.InvokableLambda(
-       func(ctx context.Context, in int) (string, error) {
-          return strconv.Itoa(in), nil
-       })).
-       // add an input to this lambda node from START.
-       // this means mapping all output of START to the input of the lambda.
-       // the effect of AddInput is to set both a control dependency
-       // and a data dependency.
-       AddInput(compose.START)
-
-    // obtain the compose.END of the workflow for method chaining
-    wf.End().
-       // add an input to compose.END,
-       // which means 'using ALL output of lambda node as output of END'.
-       AddInput("lambda")
-
-    // compile the Workflow, just like compiling a Graph
-    run, err := wf.Compile(context.Background())
-    if err != nil {
-       logs.Errorf("workflow compile error: %v", err)
-       return
-    }
-
-    // invoke the Workflow, just like invoking a Graph
-    result, err := run.Invoke(context.Background(), 1)
-    if err != nil {
-       logs.Errorf("workflow run err: %v", err)
-       return
-    }
-
-    logs.Infof("%v", result)
-}
-```
-
-[Eino example 链接](https://github.com/cloudwego/eino-examples/blob/main/compose/workflow/1_simple/main.go)
-
-核心的几个 API：
-
-- `func NewWorkflow[I, O any](opts ...NewGraphOption) *Workflow[I, O]`
-  - 构建一个新的 Workflow。
-  - 与 `NewGraph` 签名完全一致。
-- `func (wf *Workflow[I, O]) AddChatModelNode(key string, chatModel model.BaseChatModel, opts ...GraphAddNodeOpt) *WorkflowNode `
-  - 向 Workflow 中添加一个新的节点。
-  - 可添加的节点类型与 Graph 完全一致。
-  - 与 Graph 的 AddXXXNode 的差异是，Workflow 不会立刻返回 error，而是在最终 Compile 的时候统一处理和返回 error。
-  - AddXXXNode 拿到的是一个 WorkflowNode，后续向 Node 上添加字段映射等操作，直接用 Method Chaining 来做
-- `func (n *WorkflowNode) AddInput(fromNodeKey string, inputs ...*FieldMapping) *WorkflowNode`
-  - 给一个 WorkflowNode 添加输入字段映射
-  - 返回 WorkflowNode，可继续 Method Chaining。
-- `(wf *Workflow[I, O]) Compile(ctx context.Context, opts ...GraphCompileOption) (Runnable[I, O], error)`
-  - Compile 一个 Workflow。
-  - 与 Compile  Graph 的签名完全一致。
-
-### 字段映射
-
-START（输入 struct）-> [并行 lambda1, lambda2] -> END（输出 map）。
-
-我们举一个“计算 string 中字符出现次数的”例子。workflow 整体输入一个 eino 的 Message 和一个 sub string，将 Message.Content 给一个计数器 c1，将 Message.ReasoningContent 给另一个计数器 c2，并行分别计算 sub string 的出现次数，再分别映射到 END：
-
-<a href="/img/eino/workflow_char_counter.png" target="_blank"><img src="/img/eino/workflow_char_counter.png" width="100%" /></a>
-
-上图中，workflow 整体的输入是 message 结构体，c1, c2 两个 lambda 的输入都是 counter 结构体，输出都是 int，workflow 整体输出是 map[string]any. 代码如下：
-
-```go
-// demonstrates the field mapping ability of eino workflow.
-func main() {
-    type counter struct {
-       FullStr string // exported because we will do field mapping for this field
-       SubStr  string // exported because we will do field mapping for this field
-    }
-
-    // wordCounter is a lambda function that count occurrences of SubStr within FullStr
-    wordCounter := func(ctx context.Context, c counter) (int, error) {
-       return strings.Count(c.FullStr, c.SubStr), nil
-    }
-
-    type message struct {
-       *schema.Message        // exported because we will do field mapping for this field
-       SubStr          string // exported because we will do field mapping for this field
-    }
-
-    // create a workflow just like a Graph
-    wf := compose.NewWorkflow[message, map[string]any]()
-
-    // add lambda c1 just like in Graph
-    wf.AddLambdaNode("c1", compose.InvokableLambda(wordCounter)).
-       AddInput(compose.START, // add an input from START, specifying 2 field mappings
-          // map START's SubStr field to lambda c1's SubStr field
-          compose.MapFields("SubStr", "SubStr"),
-          // map START's Message's Content field to lambda c1's FullStr field
-          compose.MapFieldPaths([]string{"Message", "Content"}, []string{"FullStr"}))
-
-    // add lambda c2 just like in Graph
-    wf.AddLambdaNode("c2", compose.InvokableLambda(wordCounter)).
-       AddInput(compose.START, // add an input from START, specifying 2 field mappings
-          // map START's SubStr field to lambda c1's SubStr field
-          compose.MapFields("SubStr", "SubStr"),
-          // map START's Message's ReasoningContent field to lambda c1's FullStr field
-          compose.MapFieldPaths([]string{"Message", "ReasoningContent"}, []string{"FullStr"}))
-
-    wf.End(). // Obtain the compose.END for method chaining
-       // add an input from c1,
-       // mapping full output of c1 to the map key 'content_count'
-       AddInput("c1", compose.ToField("content_count")).
-       // also add an input from c2,
-       // mapping full output of c2 to the map key 'reasoning_content_count'
-       AddInput("c2", compose.ToField("reasoning_content_count"))
-
-    // compile the workflow just like compiling a Graph
-    run, err := wf.Compile(context.Background())
-    if err != nil {
-       logs.Errorf("workflow compile error: %v", err)
-       return
-    }
-
-    // invoke the workflow just like invoking a Graph
-    result, err := run.Invoke(context.Background(), message{
-       Message: &schema.Message{
-          Role:             schema.Assistant,
-          Content:          "Hello world!",
-          ReasoningContent: "I need to say something meaningful",
-       },
-       SubStr: "o", // would like to count the occurrences of 'o'
-    })
-    if err != nil {
-       logs.Errorf("workflow run err: %v", err)
-       return
-    }
-
-    logs.Infof("%v", result)
-}
-```
-
-[Eino example 代码链接](https://github.com/cloudwego/eino-examples/blob/main/compose/workflow/2_field_mapping/main.go)
-
-这个例子的主要信息是 `AddInput` 方法可以传递 0-n 个字段映射规则，同时可以多次调用 `AddInput`。这意味着：
-
-- 节点可以从一个前驱节点的输出中引用任意多个字段。
-- 节点可以从任意多个前驱节点中引用字段。
-- 一个映射，可以是“整体到字段”，可以是“字段到整体”，也可以是“整体到整体”，也可以是嵌套字段间的映射。
-- 上面不同的类型，有不同的 API 来表达这个映射：
-  - 顶层字段到顶层字段：`MapFields(string, string)`
-  - 全部输出到顶层字段：`ToField(string)`
-  - 顶层字段到全部输入：`FromField(string)`
-  - 嵌套字段到嵌套字段：`MapFieldPaths(FieldPath, FieldPath)`，只要上游或下游有一方是嵌套的，就需要用
-  - 全部输出到嵌套字段：`ToFieldPath(FieldPath)`
-  - 嵌套字段到全部输入：`FromFieldPath(FieldPath)`
-  - 全部输出到全部输入：直接使用 `AddInput`，不需要传 `FieldMapping`
-
-## 进阶功能
-
-### 只有数据流，没有控制流
-
-想象一个简单的场景：START -> 加法节点 -> 乘法节点 -> END。其中“乘法节点”是将 START 的一个字段和加法节点的结果相乘：
-
-<a href="/img/eino/workflow_calculator.png" target="_blank"><img src="/img/eino/workflow_calculator.png" width="100%" /></a>
-
-上图中，乘法节点在加法节点之后执行，即“乘法节点”被“加法节点”控制。但 START 节点不直接控制“乘法节点”，仅仅把数据传了过去。在代码中通过 `AddInputWithOptions(fromNode, fieldMappings, WithNoDirectDependency)` 来指定纯数据流：
-
-```go
-func main() {
-    type calculator struct {
-       Add      []int
-       Multiply int
-    }
-
-    adder := func(ctx context.Context, in []int) (out int, err error) {
-       for _, i := range in {
-          out += i
-       }
-       return out, nil
-    }
-
-    type mul struct {
-       A int
-       B int
-    }
-
-    multiplier := func(ctx context.Context, m mul) (int, error) {
-       return m.A * m.B, nil
-    }
-
-    wf := compose.NewWorkflow[calculator, int]()
-
-    wf.AddLambdaNode("adder", compose.InvokableLambda(adder)).
-       AddInput(compose.START, compose.FromField("Add"))
-
-    wf.AddLambdaNode("mul", compose.InvokableLambda(multiplier)).
-       AddInput("adder", compose.ToField("A")).
-       AddInputWithOptions(compose.START, []*compose.FieldMapping{compose.MapFields("Multiply", "B")},
-          // use WithNoDirectDependency to declare a 'data-only' dependency,
-          // in this case, START node's execution status will not determine whether 'mul' node can execute.
-          // START node only passes one field of its output to 'mul' node.
-          compose.WithNoDirectDependency())
-
-    wf.End().AddInput("mul")
-
-    runner, err := wf.Compile(context.Background())
-    if err != nil {
-       logs.Errorf("workflow compile error: %v", err)
-       return
-    }
-
-    result, err := runner.Invoke(context.Background(), calculator{
-       Add:      []int{2, 5},
-       Multiply: 3,
-    })
-    if err != nil {
-       logs.Errorf("workflow run err: %v", err)
-       return
-    }
-
-    logs.Infof("%d", result)
-}
-```
-
-[Eino examples 代码链接](https://github.com/cloudwego/eino-examples/blob/main/compose/workflow/3_data_only/main.go)
-
-这个例子中新引入的 API：
-
-```go
-func (n *WorkflowNode) AddInputWithOptions(fromNodeKey string, inputs []*FieldMapping, opts ...WorkflowAddInputOpt) *WorkflowNode {
-    return n.addDependencyRelation(fromNodeKey, inputs, getAddInputOpts(opts))
-}
-```
-
-以及新的 Option：
-
-```go
-func WithNoDirectDependency() WorkflowAddInputOpt {
-    return func(opt *workflowAddInputOpts) {
-       opt.noDirectDependency = true
-    }
-}
-```
-
-组合起来，可以给节点添加纯“数据依赖关系”。
-
-### 只有控制流，没有数据流
-
-想象一个“依次竞拍，但报价保密”的场景：START -> 竞拍者 1 -> 是否达标 -> 竞拍者 2 -> END：
-
-<a href="/img/eino/workflow_auction.png" target="_blank"><img src="/img/eino/workflow_auction.png" width="100%" /></a>
-
-在上图中，普通连线是“控制 + 数据”，虚线是“只有数据”，加粗线是“只有控制”。逻辑是：输入一个初始价格，竞拍者 1 给出报价 1，分支判断是否足够高，如果足够高则直接结束，否则把初始价格再给到竞拍者 2，给出报价 2，最后将报价 1、2 汇总输出。
-
-当竞拍者 1 给出报价后，发布公告”竞拍者完成竞拍“。注意 bidder1->announcer 是粗实线，“只有控制”，因为发布公告的时候需要对金额保密！
-
-分支出来的两条加粗线，都是“只有控制”，因为无论 bidder2 还是 END，都不依赖分支给出数据。在代码中通过 `AddDependency(fromNode)` 来指定纯控制流：
-
-```go
-func main() {
-    bidder1 := func(ctx context.Context, in float64) (float64, error) {
-       return in + 1.0, nil
-    }
-
-    bidder2 := func(ctx context.Context, in float64) (float64, error) {
-       return in + 2.0, nil
-    }
-
-    announcer := func(ctx context.Context, in any) (any, error) {
-        logs.Infof("bidder1 had lodged his bid!")
-        return nil, nil
-    }
-    
-    wf := compose.NewWorkflow[float64, map[string]float64]()
-    
-    wf.AddLambdaNode("b1", compose.InvokableLambda(bidder1)).
-        AddInput(compose.START)
-    
-    // just add a node to announce bidder1 had lodged his bid!
-    // It should be executed strictly after bidder1, so we use `AddDependency("b1")`.
-    // Note that `AddDependency()` will only form control relationship,
-    // but not data passing relationship.
-    wf.AddLambdaNode("announcer", compose.InvokableLambda(announcer)).
-        AddDependency("b1")
-    
-    // add a branch just like adding branch in Graph.
-    wf.AddBranch("b1", compose.NewGraphBranch(func(ctx context.Context, in float64) (string, error) {
-        if in > 5.0 {
-           return compose.END, nil
-        }
-        return "b2", nil
-    }, map[string]bool{compose.END: true, "b2": true}))
-    
-    wf.AddLambdaNode("b2", compose.InvokableLambda(bidder2)).
-        // b2 executes strictly after b1 (through branch dependency),
-        // but does not rely on b1's output,
-        // which means b2 depends on b1 conditionally,
-        // but no data passing between them.
-        AddInputWithOptions(compose.START, nil, compose.WithNoDirectDependency())
-
-    wf.End().AddInput("b1", compose.ToField("bidder1")).
-       AddInput("b2", compose.ToField("bidder2"))
-
-    runner, err := wf.Compile(context.Background())
-    if err != nil {
-       logs.Errorf("workflow compile error: %v", err)
-       return
-    }
-
-    result, err := runner.Invoke(context.Background(), 3.0)
-    if err != nil {
-       logs.Errorf("workflow run err: %v", err)
-       return
-    }
-
-    logs.Infof("%v", result)
-}
-```
-
-[Eino examples 代码链接](https://github.com/cloudwego/eino-examples/blob/main/compose/workflow/4_control_only_branch/main.go)
-
-这个例子中引入的新 API：
-
-```go
-func (n *WorkflowNode) AddDependency(fromNodeKey string) *WorkflowNode {
-    return n.addDependencyRelation(fromNodeKey, nil, &workflowAddInputOpts{dependencyWithoutInput: _true_})
-}
-```
-
-可以通过 AddDependency 来给节点指定纯“控制依赖关系”。
-
-### 分支（Branch）
-
-在上面的例子中，我们用与 Graph API 几乎完全相同的方式添加了一个 branch：
-
-```go
-// add a branch just like adding branch in Graph.
-    wf.AddBranch("b1", compose.NewGraphBranch(func(ctx context.Context, in float64) (string, error) {
-       if in > 5.0 {
-          return compose.END, nil
-       }
-       return "b2", nil
-    }, map[string]bool{compose.END: true, "b2": true}))
-```
-
-branch 语义与 Graph 的 AllPredecessor 模式下的 branch 语义相同：
-
-- 有且只有一个'fromNode'，即一个 branch 的前置控制节点只能有一个。
-- 可单选(NewGraphBranch)，可多选(NewGraphMultiBranch)。
-- Branch 选中的分支，可执行。未选中的分支，标记为 skip。
-- 一个节点，只有在所有入边都完成（成功或 skip），且至少有一条边成功时，这个节点才可以执行。（如上面例子中的 END）
-- 如果一个节点的所有入边都是 skip，则这个节点的所有出边自动标为 skip。
-
-同时，workflow branch 与 graph branch 有一个核心差异：
-
-- Graph branch 始终是“控制和数据合一的”，branch 下游节点的输入，一定是 branch fromNode 的输出。
-- Workflow branch 始终是“只有控制的”，branch 下游节点的输入，自行通过 AddInputWithOptions 的方式指定。
-
-涉及到的新 API：
-
-```go
-func (wf *Workflow[I, O]) AddBranch(fromNodeKey string, branch *GraphBranch) *WorkflowBranch {
-    wb := &WorkflowBranch{
-       fromNodeKey: fromNodeKey,
-       GraphBranch: branch,
-    }
-
-    wf.workflowBranches = append(wf.workflowBranches, wb)
-    return wb
-}
-```
-
-与 Graph.AddBranch 签名几乎完全相同，可以给 workflow 添加一个分支。
-
-### 静态值（Static Values）
-
-让我们修改下上面的“竞拍”例子，给竞拍者 1 和竞拍者 2 分别给一个“预算”的静态配置：
-
-<a href="/img/eino/workflow_auction_static_values_en.png" target="_blank"><img src="/img/eino/workflow_auction_static_values_en.png" width="100%" /></a>
-
-budget1 和 budget2 会分别以“静态值”的形式注入到 bidder1 和 bidder2 的 input 中。使用 `SetStaticValue` 方法给 workflow 节点配置静态值：
-
-```go
-func main() {
-    type bidInput struct {
-       Price  float64
-       Budget float64
-    }
-
-    bidder := func(ctx context.Context, in bidInput) (float64, error) {
-       if in.Price >= in.Budget {
-          return in.Budget, nil
-       }
-
-       return in.Price + rand.Float64()*in.Budget, nil
-    }
-
-    wf := compose.NewWorkflow[float64, map[string]float64]()
-
-    wf.AddLambdaNode("b1", compose.InvokableLambda(bidder)).
-       AddInput(compose.START, compose.ToField("Price")).
-       // set 'Budget' field to 3.0 for b1
-       SetStaticValue([]string{"Budget"}, 3.0)
-
-    // add a branch just like adding branch in Graph.
-    wf.AddBranch("b1", compose.NewGraphBranch(func(ctx context.Context, in float64) (string, error) {
-       if in > 5.0 {
-          return compose.END, nil
-       }
-       return "b2", nil
-    }, map[string]bool{compose.END: true, "b2": true}))
-
-    wf.AddLambdaNode("b2", compose.InvokableLambda(bidder)).
-       // b2 executes strictly after b1, but does not rely on b1's output,
-       // which means b2 depends on b1, but no data passing between them.
-       AddDependency("b1").
-       AddInputWithOptions(compose.START, []*compose.FieldMapping{compose.ToField("Price")}, compose.WithNoDirectDependency()).
-       // set 'Budget' field to 4.0 for b2
-       SetStaticValue([]string{"Budget"}, 4.0)
-
-    wf.End().AddInput("b1", compose.ToField("bidder1")).
-       AddInput("b2", compose.ToField("bidder2"))
-
-    runner, err := wf.Compile(context.Background())
-    if err != nil {
-       logs.Errorf("workflow compile error: %v", err)
-       return
-    }
-
-    result, err := runner.Invoke(context.Background(), 3.0)
-    if err != nil {
-       logs.Errorf("workflow run err: %v", err)
-       return
-    }
-
-    logs.Infof("%v", result)
-}
-```
-
-[Eino examples 代码链接](https://github.com/cloudwego/eino-examples/blob/main/compose/workflow/5_static_values/main.go)
-
-这里涉及到的新 API：
-
-```go
-func (n *WorkflowNode) SetStaticValue(path FieldPath, value any) *WorkflowNode {
-    n.staticValues[path.join()] = value
-    return n
-}
-```
-
-通过这个方法给 Workflow 节点的指定字段上设置静态值。
-
-### 流式效果
-
-回到之前的“字符计数”例子，如果我们的 workflow 的输入不再是单个 message，而是一个 message 流，并且我们的计数函数可以对流中的每个 message chunk 分别计数并返回“计数流”：
-
-<a href="/img/eino/workflow_stream.png" target="_blank"><img src="/img/eino/workflow_stream.png" width="100%" /></a>
-
-我们对之前的例子做一些修改：
-
-- InvokableLambda 改成 TransformableLambda，从而可以消费流，并产生流。
-- 把输入里面的 SubStr 改成静态值，注入到 c1 和 c2 中。
-- Workflow 的整体输入改成 *schema.Message。
-- 以 Transform 方式来调用 workflow，并传入包含 2 个 *schema.Message 的流。
-
-完成后的代码：
-
-```go
-// demonstrates the stream field mapping ability of eino workflow.
-// It's modified from 2_field_mapping.
-func main() {
-    type counter struct {
-       FullStr string // exported because we will do field mapping for this field
-       SubStr  string // exported because we will do field mapping for this field
-    }
-
-    // wordCounter is a transformable lambda function that
-    // count occurrences of SubStr within FullStr, for each trunk.
-    wordCounter := func(ctx context.Context, c *schema.StreamReader[counter]) (
-       *schema.StreamReader[int], error) {
-       var subStr, cachedStr string
-       return schema.StreamReaderWithConvert(c, func(co counter) (int, error) {
-          if len(co.SubStr) > 0 {
-             // static values will not always come in the first chunk,
-             // so before the static value (SubStr) comes in,
-             // we need to cache the full string
-             subStr = co.SubStr
-             fullStr := cachedStr + co.FullStr
-             cachedStr = ""
-             return strings.Count(fullStr, subStr), nil
-          }
-
-          if len(subStr) > 0 {
-             return strings.Count(co.FullStr, subStr), nil
-          }
-          cachedStr += co.FullStr
-          return 0, schema.ErrNoValue
-       }), nil
-    }
-
-    // create a workflow just like a Graph
-    wf := compose.NewWorkflow[*schema.Message, map[string]int]()
-
-    // add lambda c1 just like in Graph
-    wf.AddLambdaNode("c1", compose.TransformableLambda(wordCounter)).
-       AddInput(compose.START, // add an input from START, specifying 2 field mappings
-          // map START's Message's Content field to lambda c1's FullStr field
-          compose.MapFields("Content", "FullStr")).
-       // we can set static values even if the input will be stream
-       SetStaticValue([]string{"SubStr"}, "o")
-
-    // add lambda c2 just like in Graph
-    wf.AddLambdaNode("c2", compose.TransformableLambda(wordCounter)).
-       AddInput(compose.START, // add an input from START, specifying 2 field mappings
-          // map START's Message's ReasoningContent field to lambda c1's FullStr field
-          compose.MapFields("ReasoningContent", "FullStr")).
-       SetStaticValue([]string{"SubStr"}, "o")
-
-    wf.End(). // Obtain the compose.END for method chaining
-       // add an input from c1,
-       // mapping full output of c1 to the map key 'content_count'
-       AddInput("c1", compose.ToField("content_count")).
-       // also add an input from c2,
-       // mapping full output of c2 to the map key 'reasoning_content_count'
-       AddInput("c2", compose.ToField("reasoning_content_count"))
-
-    // compile the workflow just like compiling a Graph
-    run, err := wf.Compile(context.Background())
-    if err != nil {
-       logs.Errorf("workflow compile error: %v", err)
-       return
-    }
-
-    // call the workflow using Transform just like calling a Graph with Transform
-    result, err := run.Transform(context.Background(),
-       schema.StreamReaderFromArray([]*schema.Message{
-          {
-             Role:             schema.Assistant,
-             ReasoningContent: "I need to say something meaningful",
-          },
-          {
-             Role:    schema.Assistant,
-             Content: "Hello world!",
-          },
-       }))
-    if err != nil {
-       logs.Errorf("workflow run err: %v", err)
-       return
-    }
-
-    var contentCount, reasoningCount int
-    for {
-       chunk, err := result.Recv()
-       if err != nil {
-          if err == io.EOF {
-             result.Close()
-             break
-          }
-
-          logs.Errorf("workflow receive err: %v", err)
-          return
-       }
-
-       logs.Infof("%v", chunk)
-
-       contentCount += chunk["content_count"]
-       reasoningCount += chunk["reasoning_content_count"]
-    }
-
-    logs.Infof("content count: %d", contentCount)
-    logs.Infof("reasoning count: %d", reasoningCount)
-}
-```
-
-[Eino examples 代码链接](https://github.com/cloudwego/eino-examples/blob/main/compose/workflow/6_stream_field_map/main.go)
-
-基于上面这个例子，我们总结出 workflow 流式的一些特点：
-
-- 依然是 100% 的 Eino stream：四种范式(invoke, stream, collect, transform)，由 Eino 框架自动转换、复制、拼接、合并。
-- 字段映射的配置，不需要特殊处理流：无论实际的输入输出是不是流，AddInput 的写法都一样，Eino 框架负责处理基于流的映射。
-- 静态值，不需要特殊处理流：即使实际输入是个流，也可以一样的方式 SetStaticValue。Eino 框架会把静态值放在 input stream 中，但不一定是第一个读到的 chunk。
-
-### 字段映射各场景
-
-#### 类型对齐
-
-Workflow 遵循与 Graph 同一套类型对齐规则，只是对齐的粒度由完整的输入输出对齐，变为了映射成对的字段间的类型对齐。具体为：
-
-- 类型完全相同，在 Compile 时会校验通过，一定能对齐。
-- 类型不同，但上游可以 Assign 到下游（比如上游具体类型，下游 Any），在 Compile 时会校验通过，一定能对齐。
-- 上游无法 Assign 到下游（比如上游 int，下游 string），在 Compile 时会报错。
-- 上游可能能 Assign 到下游（比如上游 Any，下游 int），在 Compile 时无法确定，会推迟到执行时，取出上游的实际类型，再判断。此时如果判断上游不能 Assign 到下游，则会抛出 error。
-
-#### Merge 的各场景
-
-Merge 是指一个节点的输入映射自多个 `FieldMapping` 的情况。
-
-- 映射到多个不同的字段：支持
-- 映射到一个相同的字段：不支持
-- 映射到整体，同时也有映射到字段：冲突，不支持
-
-#### 嵌套的 map[string]any
-
-比如这个映射：`ToFieldPath([]string{"a","b"})`，目标节点的输入类型是 `map[string]any`，映射时的顺序是：
-
-1. 第一级“a”，此时的结果是 `map[string]any{"a": nil}`
-2. 第二级“b”，此时的结果是 `map[string]any{"a": map[string]any{"b": x}}`
-
-可以看到，在第二级的时候，Eino 框架自动把 any 替换为了实际的 `map[string]any`
-
-#### CustomExtractor
-
-有些场景，标准的字段映射语义无法支持，比如上游是 []int，想取出第一个元素映射到下游，此时我们用 `WithCustomExtractor` ：
-
-```go
-t.Run("custom extract from array element", func(t *testing.T) {
-    wf := NewWorkflow[[]int, map[string]int]()
-    wf.End().AddInput(_START_, ToField("a", WithCustomExtractor(func(input any) (any, error) {
-       return input.([]int)[0], nil
-    })))
-    r, err := wf.Compile(context.Background())
-    assert.NoError(t, err)
-    result, err := r.Invoke(context.Background(), []int{1, 2})
-    assert.NoError(t, err)
-    assert.Equal(t, map[string]int{"a": 1}, result)
-})
-```
-
-当使用 WithCustomExtractor 时，一切 Compile 时的类型对齐校验都无法进行，只能推迟到执行时校验。
-
-### 一些约束
-
-- Map Key 的限制：只支持 string，或者 string alias（能 convert 到 string 的类型）。
-- 不支持的 CompileOption：
-  - `WithNodeTriggerMode`，因为固定为 `AllPredecessor`。
-  - `WithMaxRunSteps`，因为不会有环。
-- 如果映射来源是 Map Key，要求 Map 中必须有这个 key。但如果映射来源是 Stream，Eino 无法判断 stream 中的所有帧中是否至少有一次出现这个 key，因此 Stream 时无法校验。
-- 如果映射来源字段或者目标字段属于 struct ，则要求这些字段必须是导出的，因为内部使用了反射。
-- 映射来源是 nil：一般情况下支持，只有当映射目标不可能是 nil 时报错，比如目标是基础类型（int 等）。
-
-## 实际应用
-
-### Coze-Studio 工作流
-
-[Coze-Studio](https://github.com/coze-dev/coze-studio) 开源版的工作流引擎是基于 Eino Workflow 编排框架。参见：[11. 新增工作流节点类型（后端）](https://github.com/coze-dev/coze-studio/wiki/11.-%E6%96%B0%E5%A2%9E%E5%B7%A5%E4%BD%9C%E6%B5%81%E8%8A%82%E7%82%B9%E7%B1%BB%E5%9E%8B%EF%BC%88%E5%90%8E%E7%AB%AF%EF%BC%89)

docs/Eino/docs/core_modules/components/_index.md

@@ -1,75 +0,0 @@
----
-Description: ""
-date: "2026-01-20"
-lastmod: ""
-tags: []
-title: Components 组件
-weight: 1
----
-
-大模型应用开发和传统应用开发最显著的区别在于大模型所具备的两大核心能力：
-
-- **基于语义的文本处理能力**：能够理解和生成人类语言，处理非结构化的内容语义关系
-- **智能决策能力**：能够基于上下文进行推理和判断，做出相应的行为决策
-
-这两项核心能力催生了三种主要的应用模式：
-
-1. **直接对话模式**：处理用户输入并生成相应回答
-2. **知识处理模式**：对文本文档进行语义化处理、存储和检索
-3. **工具调用模式**：基于上下文做出决策并调用相应工具
-
-这些模式高度概括了当前大模型应用的主要场景，为我们提供了抽象和标准化的基础。基于此，Eino 将这些常用能力抽象为可复用的「组件」（Components）
-
-组件抽象和这几种模式关系对应如下：
-
-**对话处理类组件：**
-
-1. 模板化处理和大模型交互参数的组件抽象： `ChatTemplate`、`AgenticChatTemplate`
-
-   > 详见 [Eino: ChatTemplate 使用说明](/zh/docs/eino/core_modules/components/chat_template_guide)、[Eino: AgenticChatTemplate 使用说明[Beta]](/zh/docs/eino/core_modules/components/agentic_chat_template_guide)
-   >
-2. 直接和大模型交互的组件抽象： `ChatModel`、`AgenticModel`
-
-   > 详见 [Eino: ChatModel 使用说明](/zh/docs/eino/core_modules/components/chat_model_guide)、[Eino: AgenticModel 使用说明[Beta]](/zh/docs/eino/core_modules/components/agentic_chat_model_guide)
-   >
-
-**文本语义处理类组件：**
-
-1. 获取和处理文本文档的组件抽象： `Document.Loader` 、`Document.Transformer`
-
-   > 详见 [Eino: Document Loader 使用说明](/zh/docs/eino/core_modules/components/document_loader_guide)、[Eino: Document Transformer 使用说明](/zh/docs/eino/core_modules/components/document_transformer_guide)
-   >
-2. 文本文档语义化处理的组件抽象： `Embedding`
-
-   > 详见 [Eino: Embedding 使用说明](/zh/docs/eino/core_modules/components/embedding_guide)
-   >
-3. Embedding 之后将数据索引进行存储的组件抽象： `Indexer`
-
-   > 详见 [Eino: Indexer 使用说明](/zh/docs/eino/core_modules/components/indexer_guide)
-   >
-4. 将语义相关文本文档进行索引和召回的组件抽象： `Retriever`
-
-   > 详见 [Eino: Retriever 使用说明](/zh/docs/eino/core_modules/components/retriever_guide)
-   >
-
-**决策执行类组件**：
-
-1. 大模型能够做决策并调用工具的组件抽象：`ToolsNode`、`AgenticToolsNode`
-
-   > 详见 [Eino: ToolsNode&Tool 使用说明](/zh/docs/eino/core_modules/components/tools_node_guide)、[Eino: AgenticToolsNode&Tool 使用说明[Beta]](/zh/docs/eino/core_modules/components/agentic_tools_node_guide)
-   >
-
-**自定义组件：**
-
-1. 用户自定义代码逻辑的组件抽象：`Lambda`
-
-   > 详见 [Eino: Lambda 使用说明](/zh/docs/eino/core_modules/components/lambda_guide)
-   >
-
-组件是大模型应用能力的提供者，是大模型应用构建过程中的砖和瓦，组件抽象的优劣决定了大模型应用开发的复杂度，Eino 的组件抽象秉持着以下设计原则：
-
-1. **模块化和标准化**，将一系列功能相同的能力抽象成统一的模块，组件间职能明确、边界清晰，支持灵活地组合。
-2. **可扩展性**，接口的设计保持尽可能小的模块能力约束，让组件的开发者能方便地实现自定义组件的开发。
-3. **可复用性**，把最常用的能力和实现进行封装，提供给开发者开箱即用的工具使用。
-
-组件的抽象可以让大模型应用开发形成比较固定的范式，降低认知复杂度，增强共同协作的效率。让组件的封装让开发者可以专注于业务逻辑的实现，避免重复造轮子，以快速构建高质量的大模型应用。