docs: 更新 README.md

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

.gitea/workflows/deploy.yml

@@ -10,12 +10,15 @@ jobs:
     steps:
       - name: Deploy
         run: |
+          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
@@ -27,19 +30,6 @@ jobs:
             rm -rf /tmp/camtalk-deploy
           fi
 
-          # 始终从宿主机同步最新的 .env（通过 docker 桥接，绕过 CI 容器文件系统限制）
-          docker run --rm \
-            -v /opt/camtalk/.env:/host.env:ro \
-            -v /root/camtalk:/deploy \
-            alpine cp /host.env /deploy/.env 2>/dev/null || true
-          if [ ! -f /root/camtalk/.env ]; then
-            echo "=============================================="
-            echo " 错误: 无法从 /opt/camtalk/.env 同步环境变量"
-            echo " 请在服务器上执行: cp /opt/camtalk/.env /root/camtalk/.env"
-            echo "=============================================="
-            exit 1
-          fi
-
           chmod +x /root/camtalk/deploy.sh
           /root/camtalk/deploy.sh build
           /root/camtalk/deploy.sh restart

.gitignore

@@ -24,4 +24,7 @@ Thumbs.db
 
 # ---- Obsidian ----
 .obsidian/
-.claudian/sessions/conv-1781943335504-q62bzosye.meta.json
+.claudian/
+修改过程笔记/
+学习复盘/
+docs/follow-up/

CLAUDE.md

@@ -1,124 +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/PATCH/DELETE /api/conversations/:id` — 对话详情/改标题/删除
-- `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`
-
-## 前端组件结构
-
-| 组件 | 职责 |
-|------|------|
-| `LandingPage` | 未登录时的着陆页，内嵌 LoginModal 登录/注册弹窗 |
-| `AuthPage` | 登录/注册表单（备用） |
-| `CameraManager` | 摄像头流采集 |
-| `MicManager` | 麦克风音频采集 |
-| `EdgeProcessor` | VAD + 关键帧检测（Canvas 像素比较） |
-| `WebSocketManager` | WebSocket 连接生命周期管理 |
-| `ChatPanel` | 消息展示、流式回复、文本输入、场景选择 |
-| `VideoPreview` | 摄像头画面预览 |
-| `SessionSidebar` | 左侧抽屉式对话列表（搜索、重命名、删除、时间分组） |
-| `ConfigPanel` | 右侧抽屉式配置面板（主题、TTS、语言、场景、登出） |
-| `Toast` | 轻量通知提示 |
-
-核心 Hook：`useVisionSession()` 封装一次完整的视觉对话会话。`useSessionList()` 管理对话列表 CRUD（通过 REST API）。
-
-## 后端模块结构
-
-| 模块 | 职责 |
-|------|------|
-| 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/` 设计文档，代码与文档不一致时优先更新文档

README.md

@@ -1,181 +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]
-        B5[Auth 模块]
-        B6[Store 层]
+    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 | MiMo ASR（默认） / Deepgram |
-| LLM | DashScope qwen3-vl-plus（默认，通过 eino-ext OpenAI ChatModel 接入） |
-| TTS | MiMo TTS（默认） / OpenAI 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
-│       │   ├── AuthPage/       # 登录/注册表单
 │       │   ├── CameraManager/  # 摄像头流采集
-│       │   ├── MicManager/     # 麦克风音频采集
-│       │   ├── EdgeProcessor/  # VAD + 关键帧检测
-│       │   ├── WebSocketManager/ # WS 连接管理
-│       │   ├── ChatPanel/      # 消息展示
-│       │   ├── VideoPreview/   # 摄像头画面预览
+│       │   ├── MicManager/     # 麦克风音频采集 + VAD
+│       │   ├── WebSocketManager/ # WS 连接生命周期
+│       │   ├── ChatPanel/      # 消息展示 + 流式回复
 │       │   ├── SessionSidebar/ # 对话历史侧边栏
-│       │   ├── ConfigPanel/    # 配置面板
-│       │   └── Toast/          # 通知提示
+│       │   └── ConfigPanel/    # 配置面板（主题/TTS/语言/场景）
 │       ├── hooks/              # 自定义 Hooks
-│       │   ├── useVisionSession.ts  # 核心会话 Hook
+│       │   ├── useVisionSession.ts  # 核心会话 Hook (~500 行)
 │       │   ├── useSessionList.ts    # 对话列表管理
 │       │   └── useObservationMode.ts # 观察模式
 │       ├── lib/                # 工具库
-│       │   ├── websocket.ts    # WebSocket 连接管理
-│       │   ├── api.ts          # REST API 客户端
-│       │   ├── auth.tsx        # 认证上下文（JWT 管理）
-│       │   ├── audio.ts        # 音频编码
-│       │   ├── ttsPlayer.ts    # TTS 播放器
-│       │   ├── i18n/           # 国际化（zh-CN/en-US/ja-JP）
-│       │   └── 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 提示词与场景
 │       │   ├── stt/            # STT 服务（MiMo/Deepgram）
 │       │   └── tts/            # TTS 服务（MiMo/OpenAI）
-│       ├── eino/               # Eino Graph 编排层（7 节点 DAG）
-│       ├── orchestrator/       # Orchestrator 接口
-│       ├── session/            # 会话管理（三级存储：Memory/Redis/PG）
-│       ├── store/              # 持久化层（Repository 接口 + PG/内存实现）
-│       ├── auth/               # 认证（JWT、bcrypt、中间件）
 │       ├── ws/                 # WebSocket Handler
 │       ├── api/                # REST API（Auth/Conversation）
-│       ├── config/             # 配置管理
-│       ├── models/             # 数据模型
-│       ├── errors/             # 错误码
-│       └── logger/             # 日志
-├── migrations/                 # 数据库迁移（嵌入式 SQL）
-├── docs/                       # 设计文档
-└── CLAUDE.md                   # Claude Code 指引
+│       ├── 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.25
+- **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/02-接口文档.md](docs/02-接口文档.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) | 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 全链路追踪、日志级别 |
+
+### 功能文档
+
+| 文档 | 内容 |
+|------|------|
 | [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) | 采样策略、端云协同、模型分级 |
-| [08-功能创意](docs/08-功能创意.md) | 功能创意与规划 |
-| [对话历史技术设计](docs/conversation-history-technical-design.md) | 对话历史功能的前端技术方案 |
+| [09-情景切换](docs/09-情景切换.md) | 情景模式设计与实现 |
+| [12-自定义情景](docs/12-自定义情景.md) | 用户自定义情景功能（规划中） |
 
-## License
 
-[MIT](LICENSE) © XEngineers
+## 🐛 问题反馈
+
+遇到问题？请提交 [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

@@ -31,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

@@ -20,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"
 )
@@ -202,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")
@@ -222,7 +243,7 @@ func main() {
 
 	// Auth REST 端点
 	authHandler := api.NewAuthHandler(authService, tokenMgr)
-	authHandler.RegisterRoutes(apiGroup)
+	authHandler.RegisterRoutes(apiGroup, limiter)
 
 	// Conversation REST 端点
 	convHandler := api.NewConversationHandler(sessionMgr, tokenMgr, msgRepo)
@@ -244,7 +265,7 @@ func main() {
 	}
 
 	// WebSocket
-	r.GET("/ws", ws.ServeWS(sessionMgr, orch, cfg, tokenMgr, userScenarioRepo))
+	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

@@ -60,6 +60,21 @@ auth:
   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/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/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/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 {
@@ -48,19 +40,19 @@ func (e *EinoOrchestrator) ProcessQuery(
 	req models.WsQuery,
 	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,
@@ -75,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,
@@ -90,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,
@@ -107,7 +99,7 @@ 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)
 
 	// 创建 State 并从 input 复制元数据
@@ -125,7 +117,7 @@ func (e *EinoOrchestrator) ProcessQuery(
 	// 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,
@@ -143,7 +135,7 @@ 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
@@ -159,7 +151,7 @@ func (e *EinoOrchestrator) ProcessQuery(
 			Role:    "user",
 			Content: userText,
 		}); err != nil {
-			log.Errorw("追加用户消息到历史失败", "session", sessionID, "error", err)
+			log.Errorw("append user message failed", "error", err)
 		}
 	}
 
@@ -169,15 +161,12 @@ func (e *EinoOrchestrator) ProcessQuery(
 			Role:    "assistant",
 			Content: output.FullResponse,
 		}); err != nil {
-			log.Errorw("追加助手消息到历史失败", "session", sessionID, "error", err)
+			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

@@ -99,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
 }
 

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,9 +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 节点。
@@ -24,7 +24,7 @@ func NewHistoryLambda(
 	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)
@@ -48,7 +48,7 @@ func NewHistoryLambda(
 		if userID != "" && scenarioRepo != nil {
 			scenarios, err := scenarioRepo.FindByUserID(ctx, userID)
 			if err != nil {
-				log.Warnw("加载用户自建情景失败", "user_id", userID, "error", err)
+				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))
@@ -58,7 +58,7 @@ func NewHistoryLambda(
 						customGreetings[s.ID] = s.Greeting
 					}
 				}
-				log.Debugw("加载用户自建情景", "user_id", userID, "count", len(scenarios))
+				log.Debugw("loaded user scenarios", "user_id", userID, "count", len(scenarios))
 			}
 		}
 
@@ -78,7 +78,7 @@ func NewHistoryLambda(
 		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{
@@ -121,8 +121,7 @@ func NewHistoryLambda(
 			})
 		}
 
-		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/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/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

@@ -6,7 +6,7 @@ import (
 
 	"github.com/redis/go-redis/v9"
 
-	"github.com/hhs/camtalk/internal/logger"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // Redis key 前缀。
@@ -83,7 +83,8 @@ func (r *CachedUserRepository) SaveRefreshToken(ctx context.Context, userID, tok
 	pipe.Set(ctx, key, userID, ttl)
 	pipe.SAdd(ctx, userRefreshKey(userID), tokenHash)
 	if _, err := pipe.Exec(ctx); err != nil {
-		logger.Log.Warnw("Redis cache write failed for refresh token", "error", err)
+		log := trace.FromContext(ctx)
+		log.Warnw("redis cache write failed for refresh token", "error", err)
 		// 降级：DB 已写入成功，Redis 失败不影响正确性
 	}
 	return nil
@@ -100,7 +101,8 @@ func (r *CachedUserRepository) FindRefreshToken(ctx context.Context, tokenHash s
 	}
 	// redis.Nil 表示 key 不存在，其他错误记录日志后降级到 DB
 	if err != redis.Nil {
-		logger.Log.Warnw("Redis cache read failed for refresh token", "error", err)
+		log := trace.FromContext(ctx)
+		log.Warnw("redis cache read failed for refresh token", "error", err)
 	}
 
 	// 降级到 DB
@@ -139,7 +141,8 @@ func (r *CachedUserRepository) DeleteRefreshToken(ctx context.Context, tokenHash
 		pipe.SRem(ctx, userRefreshKey(userID), tokenHash)
 	}
 	if _, err := pipe.Exec(ctx); err != nil {
-		logger.Log.Warnw("Redis cache delete failed for refresh token", "error", err)
+		log := trace.FromContext(ctx)
+		log.Warnw("redis cache delete failed for refresh token", "error", err)
 	}
 	return nil
 }
@@ -159,7 +162,8 @@ func (r *CachedUserRepository) DeleteUserRefreshTokens(ctx context.Context, user
 		}
 		keys = append(keys, userKey)
 		if err := r.rdb.Del(ctx, keys...).Err(); err != nil {
-			logger.Log.Warnw("Redis cache batch delete failed for user refresh tokens", "error", err, "userID", userID)
+			log := trace.FromContext(ctx)
+			log.Warnw("redis cache batch delete failed for user refresh tokens", "error", err, "user_id", 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

@@ -10,6 +10,7 @@ import (
 	"github.com/jackc/pgx/v5/pgxpool"
 
 	"github.com/hhs/camtalk/internal/models"
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // UserScenarioRepository 用户自建情景仓储接口。
@@ -35,6 +36,8 @@ func NewPostgresUserScenarioRepo(pool *pgxpool.Pool) UserScenarioRepository {
 
 // 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)
@@ -69,13 +72,18 @@ func (r *PostgresUserScenarioRepo) Create(ctx context.Context, scenario *models.
 	).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
@@ -100,13 +108,18 @@ func (r *PostgresUserScenarioRepo) FindByID(ctx context.Context, id string) (*mo
 		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
@@ -131,13 +144,18 @@ func (r *PostgresUserScenarioRepo) FindByIDAndUserID(ctx context.Context, id, us
 		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
@@ -147,6 +165,7 @@ func (r *PostgresUserScenarioRepo) FindByUserID(ctx context.Context, userID stri
 
 	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()
@@ -167,19 +186,25 @@ func (r *PostgresUserScenarioRepo) FindByUserID(ctx context.Context, userID stri
 			&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
@@ -205,34 +230,47 @@ func (r *PostgresUserScenarioRepo) Update(ctx context.Context, scenario *models.
 		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"
@@ -14,11 +15,12 @@ import (
 	"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。
@@ -42,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 包调用）。
@@ -94,19 +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, scenarioRepo store.UserScenarioRepository) 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
 
 	return func(c *gin.Context) {
-		serveWS(c, sessionMgr, orch, upgrader, heartbeatInterval, heartbeatTimeout, version, tokenMgr, scenarioRepo)
+		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, tokenMgr *auth.TokenManager, scenarioRepo store.UserScenarioRepository) {
+	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,20 +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)
 			}
 
 			// 创建可取消的 context
-			ctx, cancel := context.WithCancel(context.Background())
+			processCtx, cancel := context.WithCancel(queryCtx)
 			client.mu.Lock()
 			client.cancelFuncs[msg.RequestID] = cancel
 			client.mu.Unlock()
@@ -257,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, 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)
 				}
 			}()
 
@@ -284,7 +321,8 @@ func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orche
 			if msg.Payload.Scenario != nil {
 				scenarioID = *msg.Payload.Scenario
 			}
-			logger.Log.Infow("config updated", "session", sessionID, "scenario", scenarioID)
+			log := trace.FromContext(ctx)
+			log.Infow("config updated", "scenario", scenarioID)
 
 			// 如果切换了情景（非自由对话），返回首句引导
 			if scenarioID != "" && scenarioID != "free_chat" {
@@ -336,7 +374,8 @@ func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orche
 			}
 
 		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)
@@ -364,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"
@@ -148,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)
 
@@ -221,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)
@@ -332,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")
@@ -591,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
@@ -642,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.up.sql

@@ -5,18 +5,19 @@ 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) NOT NULL,
+    icon VARCHAR(20) DEFAULT '✨',
+    description VARCHAR(100),
     prompt TEXT NOT NULL,
-    greeting VARCHAR(200),
+    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 (char_length(description) >= 5 AND char_length(description) <= 100),
-    CONSTRAINT check_prompt_length CHECK (char_length(prompt) >= 50 AND char_length(prompt) <= 2000)
+    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 创建索引，加速查询
@@ -25,12 +26,15 @@ 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 '用户自建情景表';
-COMMENT ON COLUMN user_scenarios.id IS '情景唯一标识';
-COMMENT ON COLUMN user_scenarios.user_id IS '所属用户 ID，外键关联 users 表';
-COMMENT ON COLUMN user_scenarios.name IS '情景名称，如"创意写作导师"';
-COMMENT ON COLUMN user_scenarios.icon IS 'Emoji 图标，如"🎨"';
-COMMENT ON COLUMN user_scenarios.description IS '简短描述，显示在情景卡片上';
-COMMENT ON COLUMN user_scenarios.prompt IS '角色 System Prompt，定义 AI 行为';
-COMMENT ON COLUMN user_scenarios.greeting IS '首句引导，可选';
-COMMENT ON COLUMN user_scenarios.language IS '默认语言，如 zh-CN、en-US';
+-- 表和列注释
+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,9 +4,8 @@ set -euo pipefail
 PROJECT_DIR="$(cd "$(dirname "$0")" && pwd)"
 cd "$PROJECT_DIR"
 
-# .env 存放于项目目录，供 docker compose env_file 读取
-#（act_runner 容器内无法访问 /opt/camtalk，需放在项目目录下）
-ENV_FILE="$PROJECT_DIR/.env"
+# .env 固定路径（act_runner 容器已挂载 /opt/camtalk）
+ENV_FILE="/opt/camtalk/.env"
 
 # 颜色输出
 GREEN='\033[0;32m'
@@ -16,28 +15,14 @@ info()  { echo -e "${GREEN}[INFO]${NC} $*"; }
 
 # .env 检查：首次部署时从 .env.example 复制模板，提示用户填写
 check_env() {
-  if [ -f "$ENV_FILE" ]; then
-    return 0
+  if [ ! -f "$ENV_FILE" ]; then
+    echo "=============================================="
+    echo " 错误: 未找到环境变量文件"
+    echo " 路径: $ENV_FILE"
+    echo " 模板参考: backend/.env.example"
+    echo "=============================================="
+    exit 1
   fi
-
-  # 如果项目目录没有 .env，尝试从 /opt/camtalk/.env 复制（兼容旧部署）
-  local legacy_env="/opt/camtalk/.env"
-  if [ -f "$legacy_env" ]; then
-    cp "$legacy_env" "$ENV_FILE"
-    info "已从 $legacy_env 复制环境变量文件"
-    return 0
-  fi
-
-  echo "=============================================="
-  echo " 错误: 未找到环境变量文件"
-  echo ""
-  echo " 请在以下任一位置创建 .env 文件："
-  echo "   1. $ENV_FILE"
-  echo "   2. $legacy_env（运行本脚本时会自动复制）"
-  echo ""
-  echo " 模板参考: backend/.env.example"
-  echo "=============================================="
-  exit 1
 }
 
 check_env

docker-compose.yml

@@ -18,8 +18,10 @@ services:
       dockerfile: Dockerfile
     container_name: camtalk-backend
     env_file:
-      - .env
+      - /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}
@@ -38,7 +40,7 @@ services:
     image: docker.m.daocloud.io/library/postgres:15-alpine
     container_name: camtalk-postgres
     env_file:
-      - .env
+      - /opt/camtalk/.env
     environment:
       POSTGRES_DB: camtalk
     volumes:
@@ -57,7 +59,7 @@ services:
     image: docker.m.daocloud.io/library/redis:7-alpine
     container_name: camtalk-redis
     env_file:
-      - .env
+      - /opt/camtalk/.env
     command: >
       sh -c '
       if [ -n "$$CAMTALK_REDIS_PASSWORD" ]; then

docs/01-架构设计.md

@@ -199,36 +199,35 @@ graph LR
 | 模块 | 职责 |
 |------|------|
 | WebSocket Handler | 管理客户端连接生命周期，JWT 认证，conversation_id 恢复，单播消息推送 |
-| Session Manager | 维护用户会话状态、对话历史。三级存储（Memory → Redis → PostgreSQL），30 分钟 TTL，Write-Through 到 PG |
-| Eino 编排层 | 基于 CloudWeGo Eino Graph 的声明式 AI 编排。7 节点 DAG（STT→History→ChatModel→Msg2Str→Splitter→TTS→Done），Stream 模式调用，Callback 实现 LLM token 实时推送 |
-| AI Orchestrator | `EinoOrchestrator` 适配器，包装 Eino Graph 实现 `Orchestrator` 接口。context 取消 + 超时控制 |
+| Session Manager | 维护用户会话状态、对话历史，三级存储架构，30 分钟 TTL |
+| Eino 编排层 | 基于 CloudWeGo Eino Graph 的声明式 AI 编排，7 节点 DAG 流水线，Stream 模式调用 |
+| AI Orchestrator | EinoOrchestrator 适配器，包装 Eino Graph 实现 Orchestrator 接口 |
 | AI Service Layer | AI 服务抽象层，多 provider 支持（Deepgram/MiMo/OpenAI 等） |
-| Auth | 用户认证与授权。JWT (HS256) 双 token 轮转，bcrypt 密码哈希，Gin 中间件 |
-| Store | 持久化存储层。UserRepository / MessageRepository / SessionRepository，内存 + PostgreSQL 双实现 |
+| Auth | 用户认证与授权，JWT 双 token 轮转，bcrypt 密码哈希 |
+| Store | 持久化存储层，Repository 接口与实现（内存 + PostgreSQL） |
 | REST API | 健康检查、认证、对话管理端点 |
 | Logger | Zap 结构化日志 |
 | Models | 数据模型定义 |
-| Migrations | 数据库版本化迁移，嵌入式 SQL 文件自动执行 |
+| Migrations | 数据库版本化迁移 |
 | Model Router | 根据请求类型选择 AI 模型（待实现） |
-| Rate Limiter | 令牌桶限流（待实现） |
+| Rate Limiter | 令牌桶限流，详见 [11-令牌桶限流.md](./11-令牌桶限流.md) |
 
 ## 前端组件
 
 | 组件 | 职责 |
 |------|------|
-| LandingPage | 未登录时的着陆页（营销展示），内嵌 LoginModal 登录/注册弹窗 |
-| AuthPage | 登录/注册表单（备用，已被 LandingPage + LoginModal 替代） |
+| LandingPage | 未登录时的着陆页，内嵌 LoginModal 登录/注册弹窗 |
 | CameraManager | 摄像头流采集 |
 | MicManager | 麦克风音频采集 |
-| EdgeProcessor | VAD + 关键帧检测（Canvas 像素比较） |
-| WebSocketManager | WS 连接生命周期管理 |
+| EdgeProcessor | VAD + 关键帧检测 |
+| WebSocketManager | WebSocket 连接生命周期管理 |
 | ChatPanel | 消息展示、流式回复、文本输入、场景选择 |
 | VideoPreview | 摄像头画面预览 |
-| SessionSidebar | 左侧抽屉式对话列表（搜索、重命名、删除、时间分组） |
-| ConfigPanel | 右侧抽屉式配置面板（主题、TTS 开关、detail level、语言、场景、登出） |
-| Toast | 轻量通知提示（3 秒自动消失） |
+| SessionSidebar | 左侧对话列表（搜索、重命名、删除、时间分组） |
+| ConfigPanel | 右侧配置面板（主题、TTS 开关、detail level、语言、场景、登出） |
+| Toast | 轻量通知提示 |
 
-核心 Hook：`useVisionSession()` 封装一次完整的视觉对话会话（摄像头、VAD、WebSocket、消息状态、认证、场景模式）。`useSessionList()` 通过 REST API 管理对话列表 CRUD（列表、创建、删除、重命名、加载消息）。
+核心 Hook：`useVisionSession()` 封装完整的视觉对话会话（摄像头、VAD、WebSocket、消息状态、认证、场景模式）。`useSessionList()` 通过 REST API 管理对话列表 CRUD。
 
 ### 前端会话状态模型（三态）
 
@@ -310,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-自定义情景.md

@@ -1,24 +1,8 @@
-# 自建情景功能完整文档
+# 自建情景功能
 
-**最后更新**: 2026-06-21  
-**开发者**: Claude Code + cfy  
-**状态**: ✅ 开发完成（80%），待测试验证
+## 概述
 
----
-
-## 📊 总体进度
-
-**当前状态**: ✅ **Phase 1-4 已完成**  
-**完成度**: 🟢 **80%** (4/5 Phases)  
-**剩余**: Phase 5 测试验证
-
----
-
-## 一、功能概述
-
-### 核心功能
-
-用户可以创建自己的情景，而不仅限于系统预置的 5 种情景：
+用户可以创建自己的情景，而不仅限于系统预置的 5 种情景。
 
 **系统预置情景**（不可修改）：
 - 💬 自由对话
@@ -34,7 +18,7 @@
 - 📖 历史学家
 - ... （用户自由创建）
 
-### 用户旅程
+**用户旅程**：
 
 ```
 1. 用户点击"创建情景"按钮
@@ -59,29 +43,32 @@
 8. AI 按照用户设定的 Prompt 扮演角色
 ```
 
-**权限隔离**: 每个用户只能看到和管理自己创建的情景，通过 `user_id` 实现数据隔离。
+**核心特性**：完整 CRUD 操作（创建/查看/编辑/删除），通过 `user_id` 实现用户数据完全隔离，Eino Graph 管线深度集成（动态加载自建情景 Prompt），中文/英文/日文全覆盖，Modal 对话框 + 图标选择器 + Prompt 编写指南，创建后立即可用无需刷新。
 
----
+## 技术架构
 
-## 二、技术实现架构
+### 数据流
 
-### 2.1 数据流图
+**创建情景**：
 
 ```
-【创建情景】
 用户填写表单 → POST /api/scenarios → Handler 验证
 → Repository.Create → PostgreSQL 插入 → 返回情景对象
+```
 
-【AI 对话使用自建情景】
+**AI 对话使用自建情景**：
+
+```
 WebSocket 连接 → ServeWS 获取 userID
 → Eino Graph 初始化 → nodes_history 查询 user_scenarios
 → GetScenarioPrompt(customScenarios) → 构建 System Prompt
 → LLM 生成回复
 ```
 
-### 2.2 Eino 框架集成
+### Eino 框架集成
+
+**数据传递链路**：
 
-**数据传递链路**:
 ```
 JWT Token → userID
     ↓
@@ -100,19 +87,20 @@ llm.GetScenarioPrompt(scenarioID, language, customScenarios)
 LLM 使用自建情景 Prompt
 ```
 
-**关键修改文件**:
-1. `backend/internal/eino/state.go` — PipelineState 添加 `UserID`
-2. `backend/internal/eino/types.go` — PipelineInput 添加 `UserID`
-3. `backend/internal/eino/graph.go` — 接受 `scenarioRepo` 参数
-4. `backend/internal/eino/adapter.go` — 设置 UserID
-5. `backend/internal/eino/nodes_history.go` — 查询自建情景
-6. `backend/internal/ws/handler.go` — 首句引导支持自建情景
+**关键修改文件**：
 
----
+| 文件 | 变更说明 |
+|------|----------|
+| `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` | 首句引导支持自建情景 |
 
-## 三、数据模型设计
+## 数据模型
 
-### 3.1 数据库表结构
+### 数据库表结构
 
 **表名**: `user_scenarios`
 
@@ -128,7 +116,7 @@ CREATE TABLE user_scenarios (
     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),
@@ -141,16 +129,19 @@ 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）
 
-### 3.2 后端数据模型
+| 字段 | 说明 |
+|------|------|
+| `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
@@ -178,7 +169,7 @@ type CreateUserScenarioRequest struct {
 }
 ```
 
-### 3.3 前端数据结构
+### 前端数据结构
 
 ```typescript
 // frontend/src/lib/api/scenarios.ts
@@ -212,11 +203,9 @@ export interface ExtendedScenario {
 }
 ```
 
----
+## REST API
 
-## 四、REST API 设计
-
-### 4.1 API 端点
+### API 端点
 
 | 方法 | 路径 | 说明 | 权限 |
 |------|------|------|------|
@@ -226,9 +215,10 @@ export interface ExtendedScenario {
 | PATCH | `/api/scenarios/:id` | 更新情景 | 需登录 |
 | DELETE | `/api/scenarios/:id` | 删除情景 | 需登录 |
 
-### 4.2 API 示例
+### API 示例
+
+**创建情景**：
 
-#### 创建情景
 ```http
 POST /api/scenarios
 Authorization: Bearer <access_token>
@@ -244,36 +234,36 @@ Content-Type: application/json
 }
 ```
 
-**响应**: 201 Created
+响应 201 Created：
+
 ```json
 {
   "id": "uuid-xxx",
   "user_id": "uuid-user",
   "name": "创意写作导师",
-  "icon": "✨",
-  ...
+  "icon": "✨"
 }
 ```
 
-#### 获取列表
+**获取列表**：
+
 ```http
 GET /api/scenarios
 Authorization: Bearer <access_token>
 ```
 
-**响应**: 200 OK
+响应 200 OK：
+
 ```json
 {
-  "scenarios": [...],
+  "scenarios": [],
   "total": 3
 }
 ```
 
----
+## 前端实现
 
-## 五、前端实现
-
-### 5.1 组件结构
+### 组件结构
 
 ```
 frontend/src/
@@ -291,21 +281,21 @@ frontend/src/
         └── scenarios.ts        # API 调用封装
 ```
 
-### 5.2 核心 Hook
+### 核心 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,
@@ -315,9 +305,10 @@ export function useScenarios(token: string | null) {
 }
 ```
 
-### 5.3 创建情景表单
+### 创建情景表单
+
+**表单字段**：
 
-**表单字段**:
 - 名称（必填，2-50 字符）
 - 图标（可选，24 个预设 emoji）
 - 描述（可选，最多 100 字符）
@@ -325,175 +316,15 @@ export function useScenarios(token: string | null) {
 - 首句引导（可选，最多 500 字符）
 - 语言（可选，默认 zh-CN）
 
-**表单验证**:
+**表单验证**：
+
 - 实时字符计数
 - 长度限制提示
 - 必填项高亮
 
----
+## 使用指南
 
-## 六、实施进度
-
-### ✅ Phase 1: 后端基础（100% 完成）
-
-**1.1 数据库迁移** ✅
-- 文件: `backend/migrations/004_user_scenarios.up.sql`
-- 创建 `user_scenarios` 表
-- 添加索引和约束
-
-**1.2 数据模型** ✅
-- 文件: `backend/internal/models/user_scenario.go`
-- 定义 `UserScenario` 结构体
-- 定义请求/响应模型
-
-**1.3 Repository 层** ✅
-- 文件: `backend/internal/store/user_scenario_repository.go`
-- 实现 `UserScenarioRepository` 接口
-- CRUD 操作 + 权限校验
-
-**1.4 REST API** ✅
-- 文件: `backend/internal/api/user_scenario_handler.go`
-- 5 个 HTTP 端点（创建/列表/详情/更新/删除）
-- 输入验证和错误处理
-
-### ✅ Phase 2: 后端集成（100% 完成）
-
-**2.1 Prompt 加载逻辑** ✅
-- 修改: `backend/internal/ai/llm/scenarios.go`
-- `GetScenarioPrompt` 支持自建情景
-- `GetScenarioGreeting` 支持自建情景
-
-**2.2 Eino 框架集成** ✅
-- 修改 7 个文件，完整数据链路
-- PipelineState 添加 UserID
-- nodes_history 查询用户自建情景
-- 动态构建 System Prompt
-
-### ✅ Phase 3: 前端 UI（100% 完成）
-
-**3.1 API 封装** ✅
-- 文件: `frontend/src/lib/api/scenarios.ts`
-- 5 个 API 调用函数
-
-**3.2 Hook 封装** ✅
-- 文件: `frontend/src/hooks/useScenarios.ts`
-- `useScenarios` Hook
-- 合并系统预置 + 自建情景
-
-**3.3 组件实现** ✅
-- `CreateScenarioModal` — 创建对话框
-- `EditScenarioModal` — 编辑对话框
-- `ConfigPanel` 改造 — 分组显示 + 编辑/删除
-
-**3.4 i18n 支持** ✅
-- 中文/英文/日文翻译（+40 条）
-
-**3.5 样式实现** ✅
-- Modal、表单、图标选择器样式
-
-### ✅ Phase 4: 前端集成（100% 完成）
-
-**4.1 主应用集成** ✅
-- 文件: `frontend/src/App.tsx`
-- 集成 `useScenarios` Hook
-- 渲染 Modal 组件
-- 情景选择联动
-
-**4.2 编译验证** ✅
-- 前端: 669.96 kB JS + 55.80 kB CSS
-- 后端: 48MB 二进制
-
-### ⏳ Phase 5: 测试验证（待进行）
-
-**5.1 后端测试**
-- [ ] 数据库迁移验证
-- [ ] REST API CRUD 测试
-- [ ] 权限隔离测试
-- [ ] Eino Graph 自建情景加载测试
-
-**5.2 前端测试**
-- [ ] 创建情景表单验证
-- [ ] 编辑情景数据预填充
-- [ ] 删除情景二次确认
-- [ ] 情景列表实时更新
-
-**5.3 集成测试**
-- [ ] 创建自建情景后立即可用
-- [ ] 切换到自建情景显示首句引导
-- [ ] AI 对话使用自建 Prompt
-- [ ] 多用户并发隔离
-
----
-
-## 七、已完成文件清单
-
-### 新增文件（13 个）
-
-**后端（5 个）**:
-1. `backend/migrations/004_user_scenarios.up.sql`
-2. `backend/migrations/004_user_scenarios.down.sql`
-3. `backend/internal/models/user_scenario.go`
-4. `backend/internal/store/user_scenario_repository.go`
-5. `backend/internal/api/user_scenario_handler.go`
-
-**前端（5 个）**:
-6. `frontend/src/lib/api/scenarios.ts`
-7. `frontend/src/hooks/useScenarios.ts`
-8. `frontend/src/components/CreateScenarioModal/index.tsx`
-9. `frontend/src/components/EditScenarioModal/index.tsx`
-
-**文档（3 个）**:
-10. `docs/自建情景功能设计方案.md`
-11. `docs/自建情景功能-权限隔离说明.md`
-12. `docs/自建情景功能实施进度.md`
-13. `docs/自建情景功能完整文档.md` (本文件)
-
-### 修改文件（14 个）
-
-**后端（8 个）**:
-1. `backend/cmd/server/main.go` — 注册 API 路由 + 传递 scenarioRepo
-2. `backend/internal/ai/llm/scenarios.go` — Prompt/Greeting 加载支持自建
-3. `backend/internal/eino/state.go` — 添加 UserID 字段
-4. `backend/internal/eino/types.go` — PipelineInput 添加 UserID
-5. `backend/internal/eino/graph.go` — 接受并传递 scenarioRepo
-6. `backend/internal/eino/adapter.go` — 复制 UserID 到 State
-7. `backend/internal/eino/nodes_history.go` — 加载自建情景
-8. `backend/internal/ws/handler.go` — 首句引导支持自建情景
-
-**前端（6 个）**:
-9. `frontend/src/App.tsx` — 集成自建情景管理
-10. `frontend/src/components/ConfigPanel/index.tsx` — 分组显示 + 编辑/删除
-11. `frontend/src/lib/i18n/zh-CN.ts` — 新增翻译
-12. `frontend/src/lib/i18n/en-US.ts` — 新增翻译
-13. `frontend/src/lib/i18n/ja-JP.ts` — 新增翻译
-14. `frontend/src/App.css` — 新增样式
-
----
-
-## 八、问题解决记录
-
-### 8.1 CORS 错误
-
-**问题**: 前端直接访问 `http://localhost:8080` 触发 CORS  
-**解决**: 将 `API_BASE` 改为空字符串，使用 Vite 代理
-
-### 8.2 验证规则不一致
-
-**问题**: 后端要求 `description` 必填，`prompt` 最小 50 字符  
-**解决**: 统一为 `description` 可选，`prompt` 最小 10 字符
-
-### 8.3 数据库约束错误
-
-**问题**: 空字符串 `""` 不满足 `char_length >= 1` 约束  
-**解决**: 
-1. 更新约束允许 `description IS NULL`
-2. Repository 使用 `NULLIF($5, '')` 将空字符串转为 NULL
-
----
-
-## 九、测试指南
-
-### 9.1 后端 API 测试
+### 后端 API 测试
 
 ```bash
 # 1. 注册用户
@@ -528,9 +359,8 @@ curl -X DELETE http://localhost:8080/api/scenarios/<id> \
   -H "Authorization: Bearer $TOKEN"
 ```
 
-### 9.2 前端功能测试
+### 前端功能测试
 
-**操作步骤**:
 1. 刷新浏览器（Cmd+Shift+R）
 2. 登录账户
 3. 打开设置面板（右上角齿轮）
@@ -543,72 +373,53 @@ curl -X DELETE http://localhost:8080/api/scenarios/<id> \
 10. 编辑情景，验证数据预填充
 11. 删除情景，验证二次确认
 
----
+## 安全与限制
 
-## 十、功能亮点
-
-✅ **完整的 CRUD** — 创建、查看、编辑、删除自建情景  
-✅ **权限隔离** — 用户数据完全隔离，无法互相访问  
-✅ **Eino 深度集成** — 在 Graph Pipeline 中动态加载自建情景  
-✅ **多语言支持** — 中文、英文、日文全覆盖  
-✅ **优雅的 UI** — Modal 对话框 + 图标选择器 + Prompt 编写指南  
-✅ **实时生效** — 创建后立即可用，无需刷新  
-✅ **表单验证** — 字符计数、长度限制、必填项提示  
-
----
-
-## 十一、安全与限制
-
-### 11.1 用户配额
+### 用户配额
 
 ```go
 const MaxScenariosPerUser = 20  // 每个用户最多 20 个自建情景
 ```
 
-### 11.2 权限控制
+### 权限控制
 
 - 只能查看/编辑/删除自己的情景
 - 系统预置情景不可编辑/删除
 - 后端验证 `user_id` 匹配
 
-### 11.3 数据验证
+### 数据验证
 
-**后端**:
-- 名称: 2-50 字符
-- 描述: 可选，最多 100 字符
-- Prompt: 10-2000 字符
-- 首句: 可选，最多 500 字符
+**后端**：
+
+- 名称：2-50 字符
+- 描述：可选，最多 100 字符
+- Prompt：10-2000 字符
+- 首句引导：可选，最多 500 字符
+
+**前端**：
 
-**前端**:
 - 实时字符计数
 - 超长提示
 - 必填项高亮
 
----
+## 未来优化方向
 
-## 十二、未来优化方向
+**V1.1**：
 
-### V1.1 功能（推荐）
 - Prompt 模板库
 - 实时预览效果
 - 导入导出功能
 - 情景搜索和筛选
 
-### V2.0 功能（长期）
+**V2.0**：
+
 - 情景市场
 - 情景分享链接
 - AI 辅助优化 Prompt
 - 协作编辑（团队情景）
 
----
-
-## 十三、参考资料
+## 参考资料
 
 - [CLAUDE.md](../CLAUDE.md) — 项目开发指南
 - [02-接口文档.md](./02-接口文档.md) — WebSocket 和 REST API
 - [自建情景功能-权限隔离说明.md](./自建情景功能-权限隔离说明.md) — 安全设计
-
----
-
-**开发完成日期**: 2026-06-21  
-**下一步行动**: 启动服务进行人工测试验证

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/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. **可复用性**，把最常用的能力和实现进行封装，提供给开发者开箱即用的工具使用。
-
-组件的抽象可以让大模型应用开发形成比较固定的范式，降低认知复杂度，增强共同协作的效率。让组件的封装让开发者可以专注于业务逻辑的实现，避免重复造轮子，以快速构建高质量的大模型应用。

docs/Eino/docs/core_modules/components/agentic_chat_template_guide.md

@@ -1,322 +0,0 @@
----
-Description: ""
-date: "2026-03-03"
-lastmod: ""
-tags: []
-title: AgenticChatTemplate 使用说明[Beta]
-weight: 11
----
-
-> 💡
-> 本功能在 [v0.9](https://github.com/cloudwego/eino/releases/tag/v0.9.0-alpha.2) 版本开始提供。
-
-## **基本介绍**
-
-Prompt 组件是一个用于处理和格式化提示模板的组件，其中 AgenticChatTemplate 是专为 AgenticMessage 定义组件抽象，定义与用法与现存的 ChatTemplate 抽象基本相同。它的主要作用是将用户提供的变量值填充到预定义的消息模板中，生成用于与语言模型交互的标准消息格式。这个组件可用于以下场景：
-
-- 构建结构化的系统提示
-- 处理多轮对话的模板 (包括 history)
-- 实现可复用的提示模式
-
-## **组件定义**
-
-### **接口定义**
-
-> 代码位置：[https://github.com/cloudwego/eino/tree/main/components/prompt/interface.go](https://github.com/cloudwego/eino/tree/main/components/prompt/interface.go)
-
-```go
-type AgenticChatTemplate interface {
-    Format(ctx context.Context, vs map[string]any, opts ...Option) ([]*schema.AgenticMessage, error)
-}
-```
-
-#### **Format 方法**
-
-- 功能：将变量值填充到消息模板中
-- 参数：
-  - ctx：上下文对象，用于传递请求级别的信息，同时也用于传递 Callback Manager
-  - vs：变量值映射，用于填充模板中的占位符
-  - opts：可选参数，用于配置格式化行为
-- 返回值：
-  - `[]*schema.AgenticMessage`：格式化后的消息列表
-  - error：格式化过程中的错误信息
-
-### **内置模板化方式**
-
-Prompt 组件内置支持三种模板化方式：
-
-1. FString 格式 (schema.FString)
-
-   - 使用 `{variable}` 语法进行变量替换
-   - 简单直观，适合基础文本替换场景
-   - 示例：`"你是一个{role}，请帮我{task}。"`
-2. GoTemplate 格式 (schema.GoTemplate)
-
-   - 使用 Go 标准库的 text/template 语法
-   - 支持条件判断、循环等复杂逻辑
-   - 示例：`"{{if .expert}}作为专家{{end}}请{{.action}}"`
-3. Jinja2 格式 (schema.Jinja2)
-
-   - 使用 Jinja2 模板语法
-   - 示例：`"{% if level == 'expert' %}以专家的角度{% endif %}分析{{topic}}"`
-
-### **公共 Option**
-
-AgenticChatTemplate 与 ChatTemplate 共用一组公共 Option 。
-
-## **使用方式**
-
-AgenticChatTemplate 一般用于 AgenticModel 之前做上下文准备的。
-
-### 创建方法
-
-- `prompt.FromAgenticMessages()`
-  - 用于把多个 message 变成一个 agentic chat template。
-- `schema.AgenticMessage{}`
-  - schema.AgenticMessage 是实现了 Format 接口的结构体，因此可直接构建 `schema.AgenticMes``sa``ge{}` 作为 template
-- `schema.DeveloperAgenticMessage()`
-  - 此方法是构建 role 为 "developer" 的 message 快捷方法
-- `schema.SystemAgenticMessage()`
-  - 此方法是构建 role 为 "system" 的 message 快捷方法
-- `schema.UserAgenticMessage()`
-  - 此方法是构建 role 为 "user" 的 message 快捷方法
-- `schema.FunctionToolResultAgenticMessage()`
-  - 此方法是构建 role 为 "user" 的 tool call message 快捷方法
-- `schema.AgenticMessagesPlaceholder()`
-  - 可用于把一个 `[]*schema.AgenticMessage` 插入到 message 列表中，常用于插入历史对话
-
-### **单独使用**
-
-```go
-import (
-    "github.com/cloudwego/eino/components/prompt"
-    "github.com/cloudwego/eino/schema"
-)
-
-// 创建模板
-template := prompt.FromAgenticMessages(schema.FString,
-    schema.SystemAgenticMessage("你是一个{role}。"),
-    schema.AgenticMessagesPlaceholder("history_key", false),
-    schema.UserAgenticMessage("请帮我{task}")
-)
-
-// 准备变量
-variables := map[string]any{
-    "role": "专业的助手",
-    "task": "写一首诗",
-    "history_key": []*schema.AgenticMessage{
-       {
-          Role: schema.AgenticRoleTypeUser,
-          ContentBlocks: []*schema.ContentBlock{
-             schema.NewContentBlock(&schema.UserInputText{Text: "告诉我油画是什么?"}),
-          },
-       },
-       {
-          Role: schema.AgenticRoleTypeAssistant,
-          ContentBlocks: []*schema.ContentBlock{
-             schema.NewContentBlock(&schema.AssistantGenText{Text: "油画是xxx"}),
-          },
-       },
-    },
-}
-
-// 格式化模板
-messages, err := template.Format(context.Background(), variables)
-```
-
-### **在编排中使用**
-
-```go
-import (
-    "github.com/cloudwego/eino/components/prompt"
-    "github.com/cloudwego/eino/schema"
-    "github.com/cloudwego/eino/compose"
-)
-
-// 在 Chain 中使用
-chain := compose.NewChain[map[string]any, []*schema.AgenticMessage]()
-chain.AppendAgenticChatTemplate(template)
-
-// 编译并运行
-runnable, err := chain.Compile()
-if err != nil {
-    return err
-}
-result, err := runnable.Invoke(ctx, variables)
-
-// 在 Graph 中使用
-graph := compose.NewGraph[map[string]any, []*schema.AgenticMessage]()
-graph.AddAgenticChatTemplateNode("template_node", template)
-```
-
-### 从前驱节点的输出中获取数据
-
-在 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.AgenticMessage) (str string, err error) {
-    // your logic
-    return
-}), compose.WithOutputKey("your_output_key"))
-```
-
-把前驱节点的输出转成 map[string]any 并设置好 key 后，在后置的 AgenticChatTemplate 节点中使用该 key 对应的 value。
-
-## **Option 和 Callback 使用**
-
-### **Callback 使用示例**
-
-```go
-import (
-    "context"
-
-    callbackHelper "github.com/cloudwego/eino/utils/callbacks"
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/components/prompt"
-)
-
-// 创建 callback handler
-handler := &callbackHelper.AgenticPromptCallbackHandler{
-    OnStart: func(ctx context.Context, info *callbacks.RunInfo, input *prompt.AgenticCallbackInput) context.Context {
-        fmt.Printf("开始格式化模板，变量: %v\n", input.Variables)
-        return ctx
-    },
-    OnEnd: func(ctx context.Context, info *callbacks.RunInfo, output *prompt.AgenticCallbackOutput) context.Context {
-        fmt.Printf("模板格式化完成，生成消息数量: %d\n", len(output.Result))
-        return ctx
-    },
-}
-
-// 使用 callback handler
-helper := callbackHelper.NewHandlerHelper().
-    AgenticPrompt(handler).
-    Handler()
-
-// 在运行时使用
-runnable, err := chain.Compile()
-if err != nil {
-    return err
-}
-result, err := runnable.Invoke(ctx, variables, compose.WithCallbacks(helper))
-```
-
-## **自行实现参考**
-
-### Option **机制**
-
-若有需要，组件实现者可实现自定义 prompt option：
-
-```go
-import (
-    "github.com/cloudwego/eino/components/prompt"
-)
-
-// 定义 Option 结构体
-type MyPromptOptions struct {
-    StrictMode bool
-    DefaultValues map[string]string
-}
-
-// 定义 Option 函数
-func WithStrictMode(strict bool) prompt.Option {
-    return prompt.WrapImplSpecificOptFn(func(o *MyPromptOptions) {
-        o.StrictMode = strict
-    })
-}
-
-func WithDefaultValues(values map[string]string) prompt.Option {
-    return prompt.WrapImplSpecificOptFn(func(o *MyPromptOptions) {
-        o.DefaultValues = values
-    })
-}
-```
-
-### **Callback 处理**
-
-Prompt 实现需要在适当的时机触发回调，以下结构是组件定义好的：
-
-> 代码位置：[github.com/cloudwego/eino/tree/main/components/prompt/agentic_callback_extra.go](http://github.com/cloudwego/eino/tree/main/components/prompt/agentic_callback_extra.go)
-
-```go
-// AgenticCallbackInput is the input for the callback.
-type AgenticCallbackInput struct {
-    // Variables is the variables for the callback.
-    Variables map[string]any
-    // Templates is the agentic templates for the callback.
-    Templates []schema.AgenticMessagesTemplate
-    // Extra is the extra information for the callback.
-    Extra map[string]any
-}
-
-// AgenticCallbackOutput is the output for the callback.
-type AgenticCallbackOutput struct {
-    // Result is the agentic result for the callback.
-    Result []*schema.AgenticMessage
-    // Templates is the agentic templates for the callback.
-    Templates []schema.AgenticMessagesTemplate
-    // Extra is the extra information for the callback.
-    Extra map[string]any
-}
-```
-
-### **完整实现示例**
-
-```go
-type MyPrompt struct {
-    templates []schema.AgenticMessagesTemplate
-    formatType schema.FormatType
-    strictMode bool
-    defaultValues map[string]string
-}
-
-func NewMyPrompt(config *MyPromptConfig) (*MyPrompt, error) {
-    return &MyPrompt{
-        templates: config.Templates,
-        formatType: config.FormatType,
-        strictMode: config.DefaultStrictMode,
-        defaultValues: config.DefaultValues,
-    }, nil
-}
-
-func (p *MyPrompt) Format(ctx context.Context, vs map[string]any, opts ...prompt.Option) ([]*schema.AgenticMessage, error) {
-    // 1. 处理 Option
-    options := &MyPromptOptions{
-        StrictMode: p.strictMode,
-        DefaultValues: p.defaultValues,
-    }
-    options = prompt.GetImplSpecificOptions(options, opts...)
-    
-    // 2. 获取 callback manager
-    cm := callbacks.ManagerFromContext(ctx)
-    
-    // 3. 开始格式化前的回调
-    ctx = cm.OnStart(ctx, info, &prompt.AgenticCallbackInput{
-        Variables: vs,
-        Templates: p.templates,
-    })
-    
-    // 4. 执行格式化逻辑
-    messages, err := p.doFormat(ctx, vs, options)
-    
-    // 5. 处理错误和完成回调
-    if err != nil {
-        ctx = cm.OnError(ctx, info, err)
-        return nil, err
-    }
-    
-    ctx = cm.OnEnd(ctx, info, &prompt.AgenticCallbackOutput{
-        Result: messages,
-        Templates: p.templates,
-    })
-    
-    return messages, nil
-}
-
-func (p *MyPrompt) doFormat(ctx context.Context, vs map[string]any, opts *MyPromptOptions) ([]*schema.AgenticMessage, error) {
-    // 实现自己定义逻辑
-    return messages, nil
-}
-```

docs/Eino/docs/core_modules/components/agentic_tools_node_guide.md

@@ -1,378 +0,0 @@
----
-Description: ""
-date: "2026-03-03"
-lastmod: ""
-tags: []
-title: AgenticToolsNode&Tool 使用说明[Beta]
-weight: 12
----
-
-> 💡
-> 本功能在 [v0.9](https://github.com/cloudwego/eino/releases/tag/v0.9.0-alpha.2) 版本开始提供。
-
-## **基本介绍**
-
-`Tool` 在 eino 框架中的定义是“AgenticModel 能够选择调用的外部能力”，包括本地函数，MCP server tool 等。
-
-`AgenticToolsNode` 是 eino 框架指定的“Tool 执行器”，执行工具的方法定义如下：
-
-> 代码位置：[https://github.com/cloudwego/eino/tree/main/compose/agentic_tools_node.go](https://github.com/cloudwego/eino/tree/main/compose/agentic_tools_node.go)
-
-```go
-func (a *AgenticToolsNode) Invoke(ctx context.Context, input *schema.AgenticMessage, opts ...ToolsNodeOption) ([]*schema.AgenticMessage, error) {}
-
-func (a *AgenticToolsNode) Stream(ctx context.Context, input *schema.AgenticMessage,
-    opts ...ToolsNodeOption) (*schema.StreamReader[[]*schema.AgenticMessage], error) {}
-```
-
-AgenticToolsNode 与 ToolsNode 复用同一套配置，用法相同，如配置执行时序、异常处理、入参处理、middleware 扩展等。
-
-> 代码位置：[https://github.com/cloudwego/eino/tree/main/compose/tool_node.go](https://github.com/cloudwego/eino/tree/main/compose/tool_node.go)
-
-```go
-type ToolsNodeConfig struct {
-    // Tools specify the list of tools can be called which are BaseTool but must implement InvokableTool or StreamableTool.
-    Tools []tool.BaseTool
-
-    // UnknownToolsHandler handles tool calls for non-existent tools when LLM hallucinates.
-    // This field is optional. When not set, calling a non-existent tool will result in an error.
-    // When provided, if the LLM attempts to call a tool that doesn't exist in the Tools list,
-    // this handler will be invoked instead of returning an error, allowing graceful handling of hallucinated tools.
-    // Parameters:
-    //   - ctx: The context for the tool call
-    //   - name: The name of the non-existent tool
-    //   - input: The tool call input generated by llm
-    // Returns:
-    //   - string: The response to be returned as if the tool was executed
-    //   - error: Any error that occurred during handling
-    UnknownToolsHandler func(ctx context.Context, name, input string) (string, error)
-
-    // ExecuteSequentially determines whether tool calls should be executed sequentially (in order) or in parallel.
-    // When set to true, tool calls will be executed one after another in the order they appear in the input message.
-    // When set to false (default), tool calls will be executed in parallel.
-    ExecuteSequentially bool
-
-    // ToolArgumentsHandler allows handling of tool arguments before execution.
-    // When provided, this function will be called for each tool call to process the arguments.
-    // Parameters:
-    //   - ctx: The context for the tool call
-    //   - name: The name of the tool being called
-    //   - arguments: The original arguments string for the tool
-    // Returns:
-    //   - string: The processed arguments string to be used for tool execution
-    //   - error: Any error that occurred during preprocessing
-    ToolArgumentsHandler func(ctx context.Context, name, arguments string) (string, error)
-
-    // ToolCallMiddlewares configures middleware for tool calls.
-    // Each element can contain Invokable and/or Streamable middleware.
-    // Invokable middleware only applies to tools implementing InvokableTool interface.
-    // Streamable middleware only applies to tools implementing StreamableTool interface.
-    ToolCallMiddlewares []ToolMiddleware
-}
-```
-
-AgenticToolsNode 如何“决策”应该执行哪个 Tool？它不决策，而是依据输入的 `*schema.AgenticMessage` 来执行。AgenticModel 生成要调用的 FunctionToolCall（包含 ToolName，Argument 等），放到 *schema.AgenticMessage 中传给 AgenticToolsNode。AgenticToolsNode 针对每个 FunctionToolCall 实际执行一次调用。
-
-如果配置了 ExecuteSequentially，则 AgenticToolsNode 会按照 []*ContentBlock 中的先后顺序来执行工具。
-
-每个 FunctionToolCall 调用完成后的结果，又会封装为 *schema.AgenticMessage，作为 AgenticToolsNode 输出的一部分。
-
-```go
-// https://github.com/cloudwego/eino/tree/main/schema/agentic_message.go
-
-type AgenticMessage struct {
-    // role should be 'assistant' for tool call message
-    Role AgenticRoleType
-
-    // ContentBlocks is the list of content blocks.
-    ContentBlocks []*ContentBlock
-
-     // other fields...
-}
-
-type ContentBlock struct {
-    Type ContentBlockType
-
-    // FunctionToolCall contains the invocation details for a user-defined tool.
-    FunctionToolCall *FunctionToolCall
-
-    // FunctionToolResult contains the result returned from a user-defined tool call.
-    FunctionToolResult *FunctionToolResult
-
-    // other fields...
-}
-
-// FunctionToolCall is the function call in a message.
-// It's used in assistant message.
-type FunctionToolCall struct {
-    // CallID is the unique identifier for the tool call.
-    CallID string
-
-    // Name specifies the function tool invoked.
-    Name string
-
-    // Arguments is the JSON string arguments for the function tool call.
-    Arguments string
-}
-
-// FunctionToolResult is the function call result in a message.
-// It's used in user message.
-type FunctionToolResult struct {
-    // CallID is the unique identifier for the tool call.
-    CallID string
-
-    // Name specifies the function tool invoked.
-    Name string
-
-    // Result is the function tool result returned by the user
-    Result string
-}
-```
-
-## **Tool 定义**
-
-### **接口定义**
-
-Tool 组件提供了三个层次的接口：
-
-> 代码位置：[https://github.com/cloudwego/eino/components/tool/interface.go](https://github.com/cloudwego/eino/components/tool/interface.go)
-
-```go
-// BaseTool get tool info for ChatModel intent recognition.
-type BaseTool interface {
-    Info(ctx context.Context) (*schema.ToolInfo, error)
-}
-
-// InvokableTool the tool for ChatModel intent recognition and ToolsNode execution.
-type InvokableTool interface {
-    BaseTool
-    InvokableRun(ctx context.Context, argumentsInJSON string, opts ...Option) (string, error)
-}
-
-// StreamableTool the stream tool for ChatModel intent recognition and ToolsNode execution.
-type StreamableTool interface {
-    BaseTool
-    StreamableRun(ctx context.Context, argumentsInJSON string, opts ...Option) (*schema.StreamReader[string], error)
-}
-```
-
-#### **Info 方法**
-
-- 功能：获取工具的描述信息
-- 参数：
-  - ctx：上下文对象
-- 返回值：
-  - `*schema.ToolInfo`：工具的描述信息
-  - error：获取信息过程中的错误
-
-#### **InvokableRun 方法**
-
-- 功能：同步执行工具
-- 参数：
-  - ctx：上下文对象，用于传递请求级别的信息，同时也用于传递 Callback Manager
-  - `argumentsInJSON`：JSON 格式的参数字符串
-  - opts：工具执行的选项
-- 返回值：
-  - string：执行结果
-  - error：执行过程中的错误
-
-#### **StreamableRun 方法**
-
-- 功能：以流式方式执行工具
-- 参数：
-  - ctx：上下文对象，用于传递请求级别的信息，同时也用于传递 Callback Manager
-  - `argumentsInJSON`：JSON 格式的参数字符串
-  - opts：工具执行的选项
-- 返回值：
-  - `*schema.StreamReader[string]`：流式执行结果
-  - error：执行过程中的错误
-
-### **ToolInfo 结构体**
-
-> 代码位置：[https://github.com/cloudwego/eino/components/tool/interface.go](https://github.com/cloudwego/eino/components/tool/interface.go)
-
-```go
-type ToolInfo struct {
-    // 工具的唯一名称，用于清晰地表达其用途
-    Name string
-    // 用于告诉模型如何/何时/为什么使用这个工具
-    // 可以在描述中包含少量示例
-    Desc string
-    // 工具接受的参数定义
-    // 可以通过两种方式描述：
-    // 1. 使用 ParameterInfo：schema.NewParamsOneOfByParams(params)
-    // 2. 使用 JSONSchema：schema.NewParamsOneOfByJSONSchema(jsonschema)
-    *ParamsOneOf
-}
-```
-
-### **公共 Option**
-
-Tool 组件使用 ToolOption 来定义可选参数， AgenticToolsNode 没有抽象公共的 option。每个具体的实现可以定义自己的特定 Option，通过 WrapToolImplSpecificOptFn 函数包装成统一的 ToolOption 类型。
-
-## **使用方式**
-
-ToolsNode 通常不会被单独使用，一般用于编排之中接在 AgenticModel 之后。
-
-```go
-import (
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-)
-
-// 创建工具节点
-toolsNode := compose.NewAgenticToolsNode([]tool.Tool{
-    searchTool,    // 搜索工具
-    weatherTool,   // 天气查询工具
-    calculatorTool, // 计算器工具
-})
-
-// Mock LLM 输出作为输入
-input := &schema.AgenticMessage{
-    Role: schema.AgenticRoleTypeAssistant,
-    ContentBlocks: []*schema.ContentBlock{
-       {
-          Type: schema.ContentBlockTypeFunctionToolCall,
-          FunctionToolCall: &schema.FunctionToolCall{
-             CallID:    "1",
-             Name:      "get_weather",
-             Arguments: `{"city": "深圳", "date": "tomorrow"}`,
-          },
-       },
-    },
-}
-
-toolMessages, err := toolsNode.Invoke(ctx, input)
-```
-
-### **在编排中使用**
-
-```go
-import (
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-)
-
-// 创建工具节点
-toolsNode := compose.NewAgenticToolsNode([]tool.Tool{
-    searchTool,    // 搜索工具
-    weatherTool,   // 天气查询工具
-    calculatorTool, // 计算器工具
-})
-
-// 在 Chain 中使用
-chain := compose.NewChain[*schema.AgenticMessage, []*schema.AgenticMessage]()
-chain.AppendAgenticToolsNode(toolsNode)
-
-// graph 中
-graph := compose.NewGraph[*schema.AgenticMessage, []*schema.AgenticMessage]()
-graph.AddAgenticToolsNode(toolsNode)
-```
-
-## **Option 机制**
-
-自定义 Tool 可根据自己需要实现特定的 Option：
-
-```go
-import "github.com/cloudwego/eino/components/tool"
-
-// 定义 Option 结构体
-type MyToolOptions struct {
-    Timeout time.Duration
-    MaxRetries int
-    RetryInterval time.Duration
-}
-
-// 定义 Option 函数
-func WithTimeout(timeout time.Duration) tool.Option {
-    return tool.WrapImplSpecificOptFn(func(o *MyToolOptions) {
-        o.Timeout = timeout
-    })
-}
-```
-
-## **Option 和 Callback 使用**
-
-### **Callback 使用示例**
-
-```go
-import (
-    "context"
-
-    callbackHelper "github.com/cloudwego/eino/utils/callbacks"
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/components/tool"
-)
-
-// 创建 callback handler
-handler := &callbackHelper.ToolCallbackHandler{
-    OnStart: func(ctx context.Context, info *callbacks.RunInfo, input *tool.CallbackInput) context.Context {
-       fmt.Printf("开始执行工具，参数: %s\n", input.ArgumentsInJSON)
-       return ctx
-    },
-    OnEnd: func(ctx context.Context, info *callbacks.RunInfo, output *tool.CallbackOutput) context.Context {
-       fmt.Printf("工具执行完成，结果: %s\n", output.Response)
-       return ctx
-    },
-    OnEndWithStreamOutput: func(ctx context.Context, info *callbacks.RunInfo, output *schema.StreamReader[*tool.CallbackOutput]) context.Context {
-       fmt.Println("工具开始流式输出")
-       go func() {
-          defer output.Close()
-
-          for {
-             chunk, err := output.Recv()
-             if errors.Is(err, io.EOF) {
-                return
-             }
-             if err != nil {
-                return
-             }
-             fmt.Printf("收到流式输出: %s\n", chunk.Response)
-          }
-       }()
-       return ctx
-    },
-}
-
-// 使用 callback handler
-helper := callbackHelper.NewHandlerHelper().
-    Tool(handler).
-    Handler()
- 
-/*** compose a chain
-* chain := NewChain
-* chain.appendxxx().
-*       appendxxx().
-*       ...
-*/
-
-// 在运行时使用
-runnable, err := chain.Compile()
-if err != nil {
-    return err
-}
-result, err := runnable.Invoke(ctx, input, compose.WithCallbacks(helper))
-```
-
-## 如何获取 ToolCallID
-
-在 tool 函数体、tool callback handler 中，都可以通过 `compose.GetToolCallID(ctx)` 函数获取当前 Tool 的 ToolCallID。
-
-## **已有实现**
-
-1. Google Search Tool: 基于 Google 搜索的工具实现 [Tool - Googlesearch](/zh/docs/eino/ecosystem_integration/tool/tool_googlesearch)
-2. duckduckgo search tool: 基于 duckduckgo 搜索的工具实现 [Tool - DuckDuckGoSearch](/zh/docs/eino/ecosystem_integration/tool/tool_duckduckgo_search)
-3. MCP: 把 mcp server 作为 tool[Eino Tool - MCP](/zh/docs/eino/ecosystem_integration/tool/tool_mcp)
-
-## **工具实现方式**
-
-工具的实现方式有多种，可以参考如下方式：
-
-- 基于 HTTP API 的 tool 实现： [如何使用 openapi 创建 tool/function call ?](/zh/docs/eino/usage_guide/how_to_guide/openapi_tool_creation)
-- 基于 gRPC 的 tool 实现： [如何使用 proto3 创建 tool/function call ? ](/zh/docs/eino/usage_guide/how_to_guide/proto3_tool_creation)
-- 基于 thrift 的 tool 实现： [如何使用 thrift idl 创建 tool/function call ? ](/zh/docs/eino/usage_guide/how_to_guide/thrift_idl_tool_creation)
-- 基于本地函数的工具实现： [如何创建一个 tool ?](/zh/docs/eino/core_modules/components/tools_node_guide/how_to_create_a_tool)
-- ……

docs/Eino/docs/core_modules/components/chat_model_guide.md

@@ -1,538 +0,0 @@
----
-Description: ""
-date: "2026-03-24"
-lastmod: ""
-tags: []
-title: ChatModel 使用说明
-weight: 8
----
-
-## 基本介绍
-
-Model 组件是一个用于与大语言模型交互的组件。它的主要作用是将用户的输入消息发送给语言模型，并获取模型的响应。这个组件在以下场景中发挥重要作用：
-
-- 自然语言对话
-- 文本生成和补全
-- 工具调用的参数生成
-- 多模态交互（文本、图片、音频等）
-
-## 组件定义
-
-### 接口定义
-
-> 代码位置：eino/components/model/interface.go
-
-```go
-type BaseChatModel 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)
-}
-
-type ToolCallingChatModel interface {
-    BaseChatModel
-
-    // WithTools returns a new ToolCallingChatModel instance with the specified tools bound.
-    // This method does not modify the current instance, making it safer for concurrent use.
-    WithTools(tools []*schema.ToolInfo) (ToolCallingChatModel, error)
-}
-```
-
-#### Generate 方法
-
-- 功能：生成完整的模型响应
-- 参数：
-  - ctx：上下文对象，用于传递请求级别的信息，同时也用于传递 Callback Manager
-  - input：输入消息列表
-  - opts：可选参数，用于配置模型行为
-- 返回值：
-  - `*schema.Message`：模型生成的响应消息
-  - error：生成过程中的错误信息
-
-#### Stream 方法
-
-- 功能：以流式方式生成模型响应
-- 参数：与 Generate 方法相同
-- 返回值：
-  - `*schema.StreamReader[*schema.Message]`：模型响应的流式读取器
-  - error：生成过程中的错误信息
-
-#### WithTools 方法
-
-- 功能：为模型绑定可用的工具
-- 参数：
-  - tools：工具信息列表
-- 返回值：
-  - ToolCallingChatModel: 绑定了 tools 后的 chatmodel
-  - error：绑定过程中的错误信息
-
-### Message 结构体
-
-> 代码位置：eino/schema/message.go
-
-```go
-type Message struct {
-    // Role 表示消息的角色（system/user/assistant/tool）
-    Role RoleType
-    // Content 是消息的文本内容
-    Content string
-    // MultiContent 是多模态内容，支持文本、图片、音频等
-    // Deprecated: 已废弃，使用UserInputMultiContent替代
-  ~~  MultiContent []ChatMessagePart~~
-    // UserInputMultiContent 用来存储用户输入的多模态数据，支持文本、图片、音频、视频、文件
-    // 使用此字段时限制模型角色为User
-    UserInputMultiContent []MessageInputPart
-    // AssistantGenMultiContent 用来承接模型输出的多模态数据，支持文本、图片、音频、视频
-    // 使用此字段时限制模型角色为Assistant
-    AssistantGenMultiContent []MessageOutputPart
-    // Name 是消息的发送者名称
-    Name string
-    // ToolCalls 是 assistant 消息中的工具调用信息
-    ToolCalls []ToolCall
-    // ToolCallID 是 tool 消息的工具调用 ID
-    ToolCallID string
-    // ResponseMeta 包含响应的元信息
-    ResponseMeta *ResponseMeta
-    // Extra 用于存储额外信息
-    Extra map[string]any
-}
-```
-
-Message 结构体是模型交互的基本结构，支持：
-
-- 多种角色：system（系统）、user（用户）、assistant（ai）、tool（工具）
-- 多模态内容：文本、图片、音频、视频、文件
-- 工具调用：支持模型调用外部工具和函数
-- 元信息：包含响应原因、token 使用统计等
-
-### 公共 Option
-
-Model 组件提供了一组公共 Option 用于配置模型行为：
-
-> 代码位置：eino/components/model/option.go
-
-```go
-type Options struct {
-    // Temperature 控制输出的随机性
-    Temperature *float32
-    // MaxTokens 控制生成的最大 token 数量
-    MaxTokens *int
-    // Model 指定使用的模型名称
-    Model *string
-    // TopP 控制输出的多样性
-    TopP *float32
-    // Stop 指定停止生成的条件
-    Stop []string
-}
-```
-
-可以通过以下方式设置 Option：
-
-```go
-// 设置温度
-WithTemperature(temperature float32) Option
-
-// 设置最大 token 数
-WithMaxTokens(maxTokens int) Option
-
-// 设置模型名称
-WithModel(name string) Option
-
-// 设置 top_p 值
-WithTopP(topP float32) Option
-
-// 设置停止词
-WithStop(stop []string) Option
-
-// WithTools is the option to set tools for the model.
-func WithTools(tools []*schema.ToolInfo) Option {
-        if tools == nil {
-                tools = []*schema.ToolInfo{}
-        }
-        return Option{
-                apply: func(opts *Options) {
-                        opts.Tools = tools
-                },
-        }
-}
-
-// WithToolChoice sets the tool choice for the model. It also allows for providing a list of
-// tool names to constrain the model to a specific subset of the available tools.
-func WithToolChoice(toolChoice schema.ToolChoice, allowedToolNames ...string) Option {
-        return Option{
-                apply: func(opts *Options) {
-                        opts.ToolChoice = &toolChoice
-                        opts.AllowedToolNames = allowedToolNames
-                },
-        }
-}
-```
-
-## 使用方式
-
-### 单独使用
-
-```go
-import (
-    "context"
-    "fmt"
-    "io"
-
-    "github.com/cloudwego/eino-ext/components/model/openai"
-    "github.com/cloudwego/eino/components/model"
-    "github.com/cloudwego/eino/schema"
-)
-
-// 初始化模型 (以openai为例)
-cm, err := openai.NewChatModel(ctx, &openai.ChatModelConfig{
-    // 配置参数
-})
-
-// 准备输入消息
-messages := []*schema.Message{
-    {
-       Role:    schema.System,
-       Content: "你是一个有帮助的助手。",
-    },
-    {
-       Role:    schema.User,
-       Content: "你好！",
-    },
-}
-
-// 生成响应
-response, err := cm.Generate(ctx, messages, model.WithTemperature(0.8))
-
-// 响应处理
-fmt.Print(response.Content)
-
-// 流式生成
-streamResult, err := cm.Stream(ctx, messages)
-
-defer streamResult.Close()
-
-for {
-    chunk, err := streamResult.Recv()
-    if err == io.EOF {
-       break
-    }
-    if err != nil {
-       // 错误处理
-    }
-    // 响应片段处理
-    fmt.Print(chunk.Content)
-}
-```
-
-### 在编排中使用
-
-```go
-import (
-    "github.com/cloudwego/eino/schema"
-    "github.com/cloudwego/eino/compose"
-)
-
-/*** 初始化ChatModel
-* cm, err := xxx
-*/
-
-// 在 Chain 中使用
-c := compose.NewChain[[]*schema.Message, *schema.Message]()
-c.AppendChatModel(cm)
-
-
-// 在 Graph 中使用
-g := compose.NewGraph[[]*schema.Message, *schema.Message]()
-g.AddChatModelNode("model_node", cm)
-```
-
-## Option 和 Callback 使用
-
-### Option 使用示例
-
-```go
-import "github.com/cloudwego/eino/components/model"
-
-// 使用 Option
-response, err := cm.Generate(ctx, messages,
-    model.WithTemperature(0.7),
-    model.WithMaxTokens(2000),
-    model.WithModel("gpt-4"),
-)
-```
-
-### Callback 使用示例
-
-```go
-import (
-    "context"
-    "fmt"
-
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/components/model"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-    callbacksHelper "github.com/cloudwego/eino/utils/callbacks"
-)
-
-// 创建 callback handler
-handler := &callbacksHelper.ModelCallbackHandler{
-    OnStart: func(ctx context.Context, info *callbacks.RunInfo, input *model.CallbackInput) context.Context {
-       fmt.Printf("开始生成，输入消息数量: %d\n", len(input.Messages))
-       return ctx
-    },
-    OnEnd: func(ctx context.Context, info *callbacks.RunInfo, output *model.CallbackOutput) context.Context {
-       fmt.Printf("生成完成，Token 使用情况: %+v\n", output.TokenUsage)
-       return ctx
-    },
-    OnEndWithStreamOutput: func(ctx context.Context, info *callbacks.RunInfo, output *schema.StreamReader[*model.CallbackOutput]) context.Context {
-        fmt.Println("开始接收流式输出")
-        defer output.Close()
-    
-        for {
-            chunk, err := output.Recv()
-            if errors.Is(err, io.EOF) {
-                break
-            }
-            if err != nil {
-                fmt.Printf("流读取错误: %v\n", err)
-                return
-            }
-            if chunk == nil || chunk.Message == nil {
-                continue
-            }
-    
-            // 仅在模型输出包含 ToolCall 时打印
-            if len(chunk.Message.ToolCalls) > 0 {
-                for _, tc := range chunk.Message.ToolCalls {
-                    fmt.Printf("检测到 ToolCall，arguments: %s\n", tc.Function.Arguments)
-                }
-            }
-        }
-    
-        return ctx
-    },
-}
-
-// 使用 callback handler
-helper := callbacksHelper.NewHandlerHelper().
-    ChatModel(handler).
-    Handler()
-
-/*** compose a chain
-* chain := NewChain
-* chain.appendxxx().
-*       appendxxx().
-*       ...
-*/
-
-// 在运行时使用
-runnable, err := chain.Compile()
-if err != nil {
-    return err
-}
-result, err := runnable.Invoke(ctx, messages, compose.WithCallbacks(helper))
-```
-
-## **已有实现**
-
-[ChatModel](/zh/docs/eino/ecosystem_integration/chat_model)
-
-## 自行实现参考
-
-实现自定义的 ChatModel 组件时，需要注意以下几点：
-
-1. 注意要实现公共的 option
-2. 注意实现 callback 机制
-3. 在流式输出时记得完成输出后要 close writer
-
-### Option 机制
-
-自定义 ChatModel 如果需要公共 Option 以外的 Option，可以利用组件抽象的工具函数实现自定义的 Option，例如：
-
-```go
-import (
-    "time"
-
-    "github.com/cloudwego/eino/components/model"
-)
-
-// 定义 Option 结构体
-type MyChatModelOptions struct {
-    Options    *model.Options
-    RetryCount int
-    Timeout    time.Duration
-}
-
-// 定义 Option 函数
-func WithRetryCount(count int) model.Option {
-    return model.WrapImplSpecificOptFn(func(o *MyChatModelOptions) {
-       o.RetryCount = count
-    })
-}
-
-func WithTimeout(timeout time.Duration) model.Option {
-    return model.WrapImplSpecificOptFn(func(o *MyChatModelOptions) {
-       o.Timeout = timeout
-    })
-}
-```
-
-### Callback 处理
-
-ChatModel 实现需要在适当的时机触发回调，以下结构由 ChatModel 组件定义：
-
-```go
-import (
-    "github.com/cloudwego/eino/schema"
-)
-
-// 定义回调输入输出
-type CallbackInput struct {
-    Messages    []*schema.Message
-    Model       string
-    Temperature *float32
-    MaxTokens   *int
-    Extra       map[string]any
-}
-
-type CallbackOutput struct {
-    Message    *schema.Message
-    TokenUsage *schema.TokenUsage
-    Extra      map[string]any
-}
-```
-
-### 完整实现示例
-
-```go
-import (
-    "context"
-    "errors"
-    "net/http"
-    "time"
-
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/components/model"
-    "github.com/cloudwego/eino/schema"
-)
-
-type MyChatModel struct {
-    client     *http.Client
-    apiKey     string
-    baseURL    string
-    model      string
-    timeout    time.Duration
-    retryCount int
-}
-
-type MyChatModelConfig struct {
-    APIKey string
-}
-
-func NewMyChatModel(config *MyChatModelConfig) (*MyChatModel, error) {
-    if config.APIKey == "" {
-       return nil, errors.New("api key is required")
-    }
-
-    return &MyChatModel{
-       client: &http.Client{},
-       apiKey: config.APIKey,
-    }, nil
-}
-
-func (m *MyChatModel) Generate(ctx context.Context, messages []*schema.Message, opts ...model.Option) (*schema.Message, error) {
-    // 1. 处理选项
-    options := &MyChatModelOptions{
-       Options: &model.Options{
-          Model: &m.model,
-       },
-       RetryCount: m.retryCount,
-       Timeout:    m.timeout,
-    }
-    options.Options = model.GetCommonOptions(options.Options, opts...)
-    options = model.GetImplSpecificOptions(options, opts...)
-
-    // 2. 开始生成前的回调
-    ctx = callbacks.OnStart(ctx, &model.CallbackInput{
-       Messages: messages,
-       Config: &model.Config{
-          Model: *options.Options.Model,
-       },
-    })
-
-    // 3. 执行生成逻辑
-    response, err := m.doGenerate(ctx, messages, options)
-
-    // 4. 处理错误和完成回调
-    if err != nil {
-       ctx = callbacks.OnError(ctx, err)
-       return nil, err
-    }
-
-    ctx = callbacks.OnEnd(ctx, &model.CallbackOutput{
-       Message: response,
-    })
-
-    return response, nil
-}
-
-func (m *MyChatModel) Stream(ctx context.Context, messages []*schema.Message, opts ...model.Option) (*schema.StreamReader[*schema.Message], error) {
-    // 1. 处理选项
-    options := &MyChatModelOptions{
-       Options: &model.Options{
-          Model: &m.model,
-       },
-       RetryCount: m.retryCount,
-       Timeout:    m.timeout,
-    }
-    options.Options = model.GetCommonOptions(options.Options, opts...)
-    options = model.GetImplSpecificOptions(options, opts...)
-
-    // 2. 开始流式生成前的回调
-    ctx = callbacks.OnStart(ctx, &model.CallbackInput{
-       Messages: messages,
-       Config: &model.Config{
-          Model: *options.Options.Model,
-       },
-    })
-
-    // 3. 创建流式响应
-    // Pipe产生一个StreamReader和一个StreamWrite，向StreamWrite中写入可以从StreamReader中读到，二者并发安全。
-    // 实现中异步向StreamWrite中写入生成内容，返回StreamReader作为返回值
-    // ***StreamReader是一个数据流，仅可读一次，组件自行实现Callback时，既需要通过OnEndWithCallbackOutput向callback传递数据流，也需要向返回一个数据流，需要对数据流进行一次拷贝
-    // 考虑到此种情形总是需要拷贝数据流，OnEndWithCallbackOutput函数会在内部拷贝并返回一个未被读取的流
-    // 以下代码演示了一种流处理方式，处理方式不唯一
-    sr, sw := schema.Pipe[*model.CallbackOutput](1)
-
-    // 4. 启动异步生成
-    go func() {
-       defer sw.Close()
-
-       // 流式写入
-       m.doStream(ctx, messages, options, sw)
-    }()
-
-    // 5. 完成回调
-    _, nsr := callbacks.OnEndWithStreamOutput(ctx, sr)
-
-    return schema.StreamReaderWithConvert(nsr, func(t *model.CallbackOutput) (*schema.Message, error) {
-       return t.Message, nil
-    }), nil
-}
-
-func (m *MyChatModel)  WithTools(tools []*schema.ToolInfo) (model.ToolCallingChatModel, error) {
-    // 实现工具绑定逻辑
-    return nil, nil
-}
-
-func (m *MyChatModel) doGenerate(ctx context.Context, messages []*schema.Message, opts *MyChatModelOptions) (*schema.Message, error) {
-    // 实现生成逻辑
-    return nil, nil
-}
-
-func (m *MyChatModel) doStream(ctx context.Context, messages []*schema.Message, opts *MyChatModelOptions, sr *schema.StreamWriter[*model.CallbackOutput]) {
-    // 流式生成文本写入sr中
-    return
-}
-```

docs/Eino/docs/core_modules/components/chat_template_guide.md

@@ -1,302 +0,0 @@
----
-Description: ""
-date: "2025-11-20"
-lastmod: ""
-tags: []
-title: ChatTemplate 使用说明
-weight: 7
----
-
-## **基本介绍**
-
-Prompt 组件是一个用于处理和格式化提示模板的组件。它的主要作用是将用户提供的变量值填充到预定义的消息模板中，生成用于与语言模型交互的标准消息格式。这个组件可用于以下场景：
-
-- 构建结构化的系统提示
-- 处理多轮对话的模板 (包括 history)
-- 实现可复用的提示模式
-
-## **组件定义**
-
-### **接口定义**
-
-> 代码位置：eino/components/prompt/interface.go
-
-```go
-type ChatTemplate interface {
-    Format(ctx context.Context, vs map[string]any, opts ...Option) ([]*schema.Message, error)
-}
-```
-
-#### **Format 方法**
-
-- 功能：将变量值填充到消息模板中
-- 参数：
-  - ctx：上下文对象，用于传递请求级别的信息，同时也用于传递 Callback Manager
-  - vs：变量值映射，用于填充模板中的占位符
-  - opts：可选参数，用于配置格式化行为
-- 返回值：
-  - `[]*schema.Message`：格式化后的消息列表
-  - error：格式化过程中的错误信息
-
-### **内置模板化方式**
-
-Prompt 组件内置支持三种模板化方式：
-
-1. FString 格式 (schema.FString)
-
-   - 使用 `{variable}` 语法进行变量替换
-   - 简单直观，适合基础文本替换场景
-   - 示例：`"你是一个{role}，请帮我{task}。"`
-2. GoTemplate 格式 (schema.GoTemplate)
-
-   - 使用 Go 标准库的 text/template 语法
-   - 支持条件判断、循环等复杂逻辑
-   - 示例：`"{{if .expert}}作为专家{{end}}请{{.action}}"`
-3. Jinja2 格式 (schema.Jinja2)
-
-   - 使用 Jinja2 模板语法
-   - 示例：`"{% if level == 'expert' %}以专家的角度{% endif %}分析{{topic}}"`
-
-### **公共 Option**
-
-Prompt 组件使用 Option 来定义可选参数， ChatTemplate 没有公共的 option 抽象。每个具体的实现可以定义自己的特定 Option，通过 WrapImplSpecificOptFn 函数包装成统一的 Option 类型。
-
-## **使用方式**
-
-ChatTemplate 一般用于 ChatModel 之前做上下文准备的。
-
-### 创建方法
-
-- `prompt.FromMessages()`
-  - 用于把多个 message 变成一个 chat template。
-- `schema.Message{}`
-  - schema.Message 是实现了 Format 接口的结构体，因此可直接构建 `schema.Message{}` 作为 template
-- `schema.SystemMessage()`
-  - 此方法是构建 role 为 "system" 的 message 快捷方法
-- `schema.AssistantMessage()`
-  - 此方法是构建 role 为 "assistant" 的 message 快捷方法
-- `schema.UserMessage()`
-  - 此方法是构建 role 为 "user" 的 message 快捷方法
-- `schema.ToolMessage()`
-  - 此方法是构建 role 为 "tool" 的 message 快捷方法
-- `schema.MessagesPlaceholder()`
-  - 可用于把一个 `[]*schema.Message` 插入到 message 列表中，常用于插入历史对话
-
-### **单独使用**
-
-```go
-import (
-    "github.com/cloudwego/eino/components/prompt"
-    "github.com/cloudwego/eino/schema"
-)
-
-// 创建模板
-template := prompt.FromMessages(schema.FString,
-    schema.SystemMessage("你是一个{role}。"),
-    schema.MessagesPlaceholder("history_key", false),
-    &schema.Message{
-        Role:    schema.User,
-        Content: "请帮我{task}。",
-    },
-)
-
-// 准备变量
-variables := map[string]any{
-    "role": "专业的助手",
-    "task": "写一首诗",
-    "history_key": []*schema.Message{{Role: schema.User, Content: "告诉我油画是什么?"}, {Role: schema.Assistant, Content: "油画是xxx"}},
-}
-
-// 格式化模板
-messages, err := template.Format(context.Background(), variables)
-```
-
-### **在编排中使用**
-
-```go
-import (
-    "github.com/cloudwego/eino/components/prompt"
-    "github.com/cloudwego/eino/schema"
-    "github.com/cloudwego/eino/compose"
-)
-
-// 在 Chain 中使用
-chain := compose.NewChain[map[string]any, []*schema.Message]()
-chain.AppendChatTemplate(template)
-
-// 编译并运行
-runnable, err := chain.Compile()
-if err != nil {
-    return err
-}
-result, err := runnable.Invoke(ctx, variables)
-
-// 在 Graph 中使用
-graph := compose.NewGraph[map[string]any, []*schema.Message]()
-graph.AddChatTemplateNode("template_node", template)
-```
-
-### 从前驱节点的输出中获取数据
-
-在 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"))
-```
-
-把前驱节点的输出转成 map[string]any 并设置好 key 后，在后置的 ChatTemplate 节点中使用该 key 对应的 value。
-
-## **Option 和 Callback 使用**
-
-### **Callback 使用示例**
-
-```go
-import (
-    "context"
-
-    callbackHelper "github.com/cloudwego/eino/utils/callbacks"
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/components/prompt"
-)
-
-// 创建 callback handler
-handler := &callbackHelper.PromptCallbackHandler{
-    OnStart: func(ctx context.Context, info *callbacks.RunInfo, input *prompt.CallbackInput) context.Context {
-        fmt.Printf("开始格式化模板，变量: %v\n", input.Variables)
-        return ctx
-    },
-    OnEnd: func(ctx context.Context, info *callbacks.RunInfo, output *prompt.CallbackOutput) context.Context {
-        fmt.Printf("模板格式化完成，生成消息数量: %d\n", len(output.Result))
-        return ctx
-    },
-}
-
-// 使用 callback handler
-helper := callbackHelper.NewHandlerHelper().
-    Prompt(handler).
-    Handler()
-
-// 在运行时使用
-runnable, err := chain.Compile()
-if err != nil {
-    return err
-}
-result, err := runnable.Invoke(ctx, variables, compose.WithCallbacks(helper))
-```
-
-## **自行实现参考**
-
-### Option **机制**
-
-若有需要，组件实现者可实现自定义 prompt option：
-
-```go
-import (
-    "github.com/cloudwego/eino/components/prompt"
-)
-
-// 定义 Option 结构体
-type MyPromptOptions struct {
-    StrictMode bool
-    DefaultValues map[string]string
-}
-
-// 定义 Option 函数
-func WithStrictMode(strict bool) prompt.Option {
-    return prompt.WrapImplSpecificOptFn(func(o *MyPromptOptions) {
-        o.StrictMode = strict
-    })
-}
-
-func WithDefaultValues(values map[string]string) prompt.Option {
-    return prompt.WrapImplSpecificOptFn(func(o *MyPromptOptions) {
-        o.DefaultValues = values
-    })
-}
-```
-
-### **Callback 处理**
-
-Prompt 实现需要在适当的时机触发回调，以下结构是组件定义好的：
-
-> 代码位置：eino/components/prompt/callback_extra.go
-
-```go
-// 定义回调输入输出
-type CallbackInput struct {
-    Variables map[string]any
-    Templates []schema.MessagesTemplate
-    Extra map[string]any
-}
-
-type CallbackOutput struct {
-    Result []*schema.Message
-    Templates []schema.MessagesTemplate
-    Extra map[string]any
-}
-```
-
-### **完整实现示例**
-
-```go
-type MyPrompt struct {
-    templates []schema.MessagesTemplate
-    formatType schema.FormatType
-    strictMode bool
-    defaultValues map[string]string
-}
-
-func NewMyPrompt(config *MyPromptConfig) (*MyPrompt, error) {
-    return &MyPrompt{
-        templates: config.Templates,
-        formatType: config.FormatType,
-        strictMode: config.DefaultStrictMode,
-        defaultValues: config.DefaultValues,
-    }, nil
-}
-
-func (p *MyPrompt) Format(ctx context.Context, vs map[string]any, opts ...prompt.Option) ([]*schema.Message, error) {
-    // 1. 处理 Option
-    options := &MyPromptOptions{
-        StrictMode: p.strictMode,
-        DefaultValues: p.defaultValues,
-    }
-    options = prompt.GetImplSpecificOptions(options, opts...)
-    
-    // 2. 获取 callback manager
-    cm := callbacks.ManagerFromContext(ctx)
-    
-    // 3. 开始格式化前的回调
-    ctx = cm.OnStart(ctx, info, &prompt.CallbackInput{
-        Variables: vs,
-        Templates: p.templates,
-    })
-    
-    // 4. 执行格式化逻辑
-    messages, err := p.doFormat(ctx, vs, options)
-    
-    // 5. 处理错误和完成回调
-    if err != nil {
-        ctx = cm.OnError(ctx, info, err)
-        return nil, err
-    }
-    
-    ctx = cm.OnEnd(ctx, info, &prompt.CallbackOutput{
-        Result: messages,
-        Templates: p.templates,
-    })
-    
-    return messages, nil
-}
-
-func (p *MyPrompt) doFormat(ctx context.Context, vs map[string]any, opts *MyPromptOptions) ([]*schema.Message, error) {
-    // 实现自己定义逻辑
-    return messages, nil
-}
-```

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

@@ -1,308 +0,0 @@
----
-Description: ""
-date: "2025-11-20"
-lastmod: ""
-tags: []
-title: Document Loader 使用说明
-weight: 1
----
-
-## **基本介绍**
-
-Document Loader 是一个用于加载文档的组件。它的主要作用是从不同来源（如网络 URL、本地文件等）加载文档内容，并将其转换为标准的文档格式。这个组件在处理需要从各种来源获取文档内容的场景中发挥重要作用，比如:
-
-- 从网络 URL 加载网页内容
-- 读取本地 PDF、Word 等格式的文档
-
-## **组件定义**
-
-### **接口定义**
-
-> 代码位置：eino/components/document/interface.go
-
-```go
-type Loader interface {
-    Load(ctx context.Context, src Source, opts ...LoaderOption) ([]*schema.Document, error)
-}
-```
-
-#### **Load 方法**
-
-- 功能：从指定的数据源加载文档
-- 参数：
-  - ctx：上下文对象，用于传递请求级别的信息，同时也用于传递 Callback Manager
-  - src：文档来源，包含文档的 URI 信息
-  - opts：加载选项，用于配置加载行为
-- 返回值：
-  - `[]*schema.Document`：加载的文档列表
-  - error：加载过程中的错误信息
-
-### **Source 结构体**
-
-```go
-type Source struct {
-    URI string
-}
-```
-
-Source 结构体定义了文档的来源信息：
-
-- URI：文档的统一资源标识符，可以是网络 URL 或本地文件路径
-
-### **Document 结构体**
-
-```go
-type Document struct {
-    // ID 是文档的唯一标识符
-    ID string
-    // Content 是文档的内容
-    Content string
-    // MetaData 用于存储文档的元数据信息
-    MetaData map[string]any
-}
-```
-
-Document 结构体是文档的标准格式，包含以下重要字段：
-
-- ID：文档的唯一标识符，用于在系统中唯一标识一个文档
-- Content：文档的实际内容
-- MetaData：文档的元数据，可以存储如下信息：
-  - 文档的来源信息
-  - 文档的向量表示（用于向量检索）
-  - 文档的分数（用于排序）
-  - 文档的子索引（用于分层检索）
-  - 其他自定义元数据
-
-### **公共选项**
-
-Loader 组件使用 `LoaderOption` 来定义加载选项。Loader 目前没有公共的 Option，每个具体的实现可以定义自己的特定选项，通过 `WrapLoaderImplSpecificOptFn` 函数包装成统一的 `LoaderOption` 类型。
-
-## **使用方式**
-
-### **单独使用**
-
-> 代码位置：eino-ext/components/document/loader/file/examples/fileloader
-
-```go
-import (
-    "github.com/cloudwego/eino/components/document"
-    "github.com/cloudwego/eino-ext/components/document/loader/file"
-)
-
-// 初始化 loader (以file loader为例)
-loader, _ := file.NewFileLoader(ctx, &file.FileLoaderConfig{
-    // 配置参数
-    UseNameAsID: true,
-})
-
-// 加载文档
-filePath := "../../testdata/test.md"
-docs, _ := loader.Load(ctx, document.Source{
-    URI: filePath,
-})
-
-log.Printf("doc content: %v", docs[0].Content)
-```
-
-### **在编排中使用**
-
-```go
-// 在 Chain 中使用
-chain := compose.NewChain[string, []*schema.Document]()
-chain.AppendLoader(loader)
-
-// 编译并运行
-runnable, _ := chain.Compile()
-
-result, _ := runnable.Invoke(ctx, input)
-
-// 在 Graph 中使用
-graph := compose.NewGraph[string, []*schema.Document]()
-graph.AddLoaderNode("loader_node", loader)
-```
-
-## **Option 和 Callback 使用**
-
-### **Callback 使用示例**
-
-> 代码位置：eino-ext/components/document/loader/file/examples/fileloader
-
-```go
-import (
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/components/document"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-    callbacksHelper "github.com/cloudwego/eino/utils/callbacks"
-
-    "github.com/cloudwego/eino-ext/components/document/loader/file"
-)
-
-// 创建 callback handler
-handler := &callbacksHelper.LoaderCallbackHandler{
-    OnStart: func(ctx context.Context, info *callbacks.RunInfo, input *document.LoaderCallbackInput) context.Context {
-       log.Printf("start loading docs...: %s\n", input.Source.URI)
-       return ctx
-    },
-    OnEnd: func(ctx context.Context, info *callbacks.RunInfo, output *document.LoaderCallbackOutput) context.Context {
-       log.Printf("complete loading docs，total loaded docs: %d\n", len(output.Docs))
-       return ctx
-    },
-    // OnError
-}
-
-// 使用 callback handler
-helper := callbacksHelper.NewHandlerHelper().
-    Loader(handler).
-    Handler()
-
-chain := compose.NewChain[document.Source, []*schema.Document]()
-chain.AppendLoader(loader)
-// 在运行时使用
-run, _ := chain.Compile(ctx)
-
-outDocs, _ := run.Invoke(ctx, document.Source{
-    URI: filePath,
-}, compose.WithCallbacks(helper))
-
-log.Printf("doc content: %v", outDocs[0].Content)
-```
-
-## **已有实现**
-
-1. File Loader: 用于加载本地文件系统中的文档 [Loader - local file](/zh/docs/eino/ecosystem_integration/document/loader_local_file)
-2. Web Loader: 用于加载网络 URL 指向的文档 [Loader - web url](/zh/docs/eino/ecosystem_integration/document/loader_web_url)
-3. S3 Loader: 用于加载存储在 S3 兼容存储系统中的文档 [Loader - amazon s3](/zh/docs/eino/ecosystem_integration/document/loader_amazon_s3)
-
-## **自行实现参考**
-
-自行实现 loader 组件时，需要注意 option 机制和 callback 的处理。
-
-### option **机制**
-
-自定义 Loader 需要实现自己的 Option 参数机制：
-
-```go
-// 定义选项结构体
-type MyLoaderOptions struct {
-    Timeout time.Duration
-    RetryCount int
-}
-
-// 定义选项函数
-func WithTimeout(timeout time.Duration) document.LoaderOption {
-    return document.WrapLoaderImplSpecificOptFn(func(o *MyLoaderOptions) {
-        o.Timeout = timeout
-    })
-}
-
-func WithRetryCount(count int) document.LoaderOption {
-    return document.WrapLoaderImplSpecificOptFn(func(o *MyLoaderOptions) {
-        o.RetryCount = count
-    })
-}
-```
-
-### **Callback 处理**
-
-Loader 实现需要在适当的时机触发回调：
-
-> 代码位置：eino/components/document/callback_extra_loader.go
-
-```go
-// 这是由loader组件定义的回调输入输出, 在实现时需要满足参数的含义
-type LoaderCallbackInput struct {
-    Source Source
-    Extra map[string]any
-}
-
-type LoaderCallbackOutput struct {
-    Source Source
-    Docs []*schema.Document
-    Extra map[string]any
-}
-```
-
-### **完整实现示例**
-
-```go
-import (
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/components/document"
-    "github.com/cloudwego/eino/schema"
-)
-
-func NewCustomLoader(config *Config) (*CustomLoader, error) {
-    return &CustomLoader{
-       timeout:    config.DefaultTimeout,
-       retryCount: config.DefaultRetryCount,
-    }, nil
-}
-
-type CustomLoader struct {
-    timeout    time.Duration
-    retryCount int
-}
-
-type Config struct {
-    DefaultTimeout    time.Duration
-    DefaultRetryCount int
-}
-
-func (l *CustomLoader) Load(ctx context.Context, src document.Source, opts ...document.LoaderOption) ([]*schema.Document, error) {
-    // 1. 处理 option
-    options := &customLoaderOptions{
-       Timeout:    l.timeout,
-       RetryCount: l.retryCount,
-    }
-    options = document.GetLoaderImplSpecificOptions(options, opts...)
-    var err error
-
-    // 2. 处理错误，并进行错误回调方法
-    defer func() {
-       if err != nil {
-          callbacks.OnError(ctx, err)
-       }
-    }()
-
-    // 3. 开始加载前的回调
-    ctx = callbacks.OnStart(ctx, &document.LoaderCallbackInput{
-       Source: src,
-    })
-
-    // 4. 执行加载逻辑
-    docs, err := l.doLoad(ctx, src, options)
-
-    if err != nil {
-       return nil, err
-    }
-
-    ctx = callbacks.OnEnd(ctx, &document.LoaderCallbackOutput{
-       Source: src,
-       Docs:   docs,
-    })
-
-    return docs, nil
-}
-
-func (l *CustomLoader) doLoad(ctx context.Context, src document.Source, opts *customLoaderOptions) ([]*schema.Document, error) {
-    // 实现文档加载逻辑
-    // 1. 加载文档内容
-    // 2. 构造 Document 对象，注意可在 MetaData 中保存文档来源等重要信息
-    return []*schema.Document{{
-       Content: "Hello World",
-    }}, nil
-}
-```
-
-### **注意事项**
-
-- MetaData 是文档的重要组成部分，用于保存文档的各种元信息
-- 文档加载失败时返回有意义的错误信息，便于做错误的排查
-
-## 其他参考文档
-
-- [[🚧]Eino: Document Transformer 使用说明](/zh/docs/eino/core_modules/components/document_transformer_guide)
-- [[🚧]Eino: Embedding 使用说明](/zh/docs/eino/core_modules/components/embedding_guide)
-- [[🚧]Eino: Indexer 使用说明](/zh/docs/eino/core_modules/components/indexer_guide)
-- [[🚧]Eino: Retriever 使用说明](/zh/docs/eino/core_modules/components/retriever_guide)

docs/Eino/docs/core_modules/components/document_loader_guide/document_parser_interface_guide.md

@@ -1,268 +0,0 @@
----
-Description: ""
-date: "2025-07-21"
-lastmod: ""
-tags: []
-title: Document Parser 接口使用说明
-weight: 1
----
-
-## **基本介绍**
-
-Document Parser 是一个用于解析文档内容的工具包。它不是一个独立的组件，而是作为 Document Loader 的内部工具，用于将不同格式的原始内容解析成标准的文档格式。Parser 支持：
-
-- 解析不同格式的文档内容（如文本、PDF、Markdown 等）
-- 根据文件扩展名自动选择合适的解析器 (eg：ExtParser)
-- 为解析后的文档添加元数据信息
-
-## **接口定义**
-
-### **Parser 接口**
-
-> 代码位置：eino/components/document/parser/interface.go
-
-```go
-import (
-    "github.com/cloudwego/eino/schema"
-)
-
-// Parser is a document parser, can be used to parse a document from a reader.
-type Parser interface {
-    Parse(ctx context.Context, reader io.Reader, opts ...Option) ([]*schema.Document, error)
-}
-```
-
-#### **Parse 方法**
-
-- 功能：从 Reader 中解析文档内容
-- 参数：
-  - ctx：上下文对象
-  - reader：提供原始内容的 Reader
-  - opts：解析选项
-- 返回值：
-  - `[]*schema.Document`：解析后的文档列表
-  - error：解析过程中的错误
-
-### **公共 Option 定义**
-
-```go
-type Options struct {
-    // URI 表示文档的来源
-    URI string
-
-    // ExtraMeta 会被合并到每个解析出的文档的元数据中
-    ExtraMeta map[string]any
-}
-```
-
-提供了两个基础的选项函数：
-
-- WithURI：设置文档的 URI，在 ExtParser 中用于选择解析器
-- WithExtraMeta：设置额外的元数据
-
-## **内置解析器**
-
-### **TextParser**
-
-最基础的文本解析器，将输入内容直接作为文档内容：
-
-> 代码位置：eino-examples/components/document/parser/textparser
-
-```go
-import "github.com/cloudwego/eino/components/document/parser"
-
-textParser := parser.TextParser{}
-docs, _ := textParser.Parse(ctx, strings.NewReader("hello world"))
-
-logs.Infof("text content: %v", docs[0].Content)
-```
-
-### **ExtParser**
-
-基于文件扩展名的解析器，可以根据文件扩展名自动选择合适的解析器：
-
-> 代码位置：eino-examples/components/document/parser/extparser
-
-```go
-package main
-
-import (
-    "context"
-    "os"
-
-    "github.com/cloudwego/eino-ext/components/document/parser/html"
-    "github.com/cloudwego/eino-ext/components/document/parser/pdf"
-    "github.com/cloudwego/eino/components/document/parser"
-
-    "github.com/cloudwego/eino-examples/internal/gptr"
-    "github.com/cloudwego/eino-examples/internal/logs"
-)
-
-func main() {
-    ctx := context.Background()
-
-    textParser := parser.TextParser{}
-
-    htmlParser, _ := html.NewParser(ctx, &html.Config{
-       Selector: gptr.Of("body"),
-    })
-
-    pdfParser, _ := pdf.NewPDFParser(ctx, &pdf.Config{})
-
-    // 创建扩展解析器
-    extParser, _ := parser.NewExtParser(ctx, &parser.ExtParserConfig{
-       // 注册特定扩展名的解析器
-       Parsers: map[string]parser.Parser{
-          ".html": htmlParser,
-          ".pdf":  pdfParser,
-       },
-       // 设置默认解析器，用于处理未知格式
-       FallbackParser: textParser,
-    })
-
-    // 使用解析器
-    filePath := "./testdata/test.html"
-    file, _ := os.Open(filePath)
-    
-    docs, _ := extParser.Parse(ctx, file,
-       // 必须提供 URI ExtParser 选择正确的解析器进行解析
-       parser.WithURI(filePath),
-       parser.WithExtraMeta(map[string]any{
-          "source": "local",
-       }),
-    )
-
-    for idx, doc := range docs {
-       logs.Infof("doc_%v content: %v", idx, doc.Content)
-    }
-}
-```
-
-### 其他实现
-
-- pdf parser, 用于提取和 parse pdf 格式的文件: [[🚧]Parser - pdf](/zh/docs/eino/ecosystem_integration/document/parser_pdf)
-- html parser, 用于提取和 parse html 格式的内容:  [[🚧]Parser - html](/zh/docs/eino/ecosystem_integration/document/parser_html)
-
-## **在 Document Loader 中使用**
-
-Parser 主要在 Document Loader 中使用，用于解析加载的文档内容。以下是一些典型的使用场景：
-
-### **文件加载器**
-
-> 代码位置：eino-ext/components/document/loader/file/examples/fileloader
-
-```go
-import (
-    "github.com/cloudwego/eino/components/document"
-    "github.com/cloudwego/eino/schema"
-    "github.com/cloudwego/eino-ext/components/document/loader/file"
-)
-
-// 使用 FileLoader 加载本地文件
-ctx := context.Background()
-
-log.Printf("===== call File Loader directly =====")
-// 初始化 loader (以file loader为例)
-loader, err := file.NewFileLoader(ctx, &file.FileLoaderConfig{
-    // 配置参数
-    UseNameAsID: true,
-    Parser:      &parser.TextParser{}, // 使用 TextParser 作为默认解析器, 可自定义，例如使用 parser.NewExtParser() 创建不同文件类型的解析器
-})
-if err != nil {
-    log.Fatalf("file.NewFileLoader failed, err=%v", err)
-}
-
-// 加载文档
-filePath := "../../testdata/test.md"
-docs, err := loader.Load(ctx, document.Source{
-    URI: filePath,
-})
-if err != nil {
-    log.Fatalf("loader.Load failed, err=%v", err)
-}
-
-log.Printf("doc content: %v", docs[0].Content)
-log.Printf("Extension: %s\n", docs[0].MetaData[file._MetaKeyExtension_]) // 输出: Extension: .txt
-log.Printf("Source: %s\n", docs[0].MetaData[file._MetaKeySource_])       // 输出: Source: ./document.txt
-```
-
-## **自定义解析器实现**
-
-### option **机制**
-
-自定义解析器可以定义自己的 option：
-
-```go
-// options
-// 定制实现自主定义的 option 结构体
-type options struct {
-    Encoding string
-    MaxSize  int64
-}
-
-// WithEncoding
-// 定制实现自主定义的 Option 方法
-func WithEncoding(encoding string) parser.Option {
-    return parser.WrapImplSpecificOptFn(func(o *options) {
-       o.Encoding = encoding
-    })
-}
-
-func WithMaxSize(size int64) parser.Option {
-    return parser.WrapImplSpecificOptFn(func(o *options) {
-       o.MaxSize = size
-    })
-}
-```
-
-### **完整实现示例**
-
-> 代码位置：eino-examples/components/document/parser/customparser/custom_parser.go
-
-```go
-import (
-    "github.com/cloudwego/eino/components/document/parser"
-    "github.com/cloudwego/eino/schema"
-)
-
-type Config struct {
-    DefaultEncoding string
-    DefaultMaxSize  int64
-}
-
-type CustomParser struct {
-    defaultEncoding string
-    defaultMaxSize  int64
-}
-
-func NewCustomParser(config *Config) (*CustomParser, error) {
-    return &CustomParser{
-       defaultEncoding: config.DefaultEncoding,
-       defaultMaxSize:  config.DefaultMaxSize,
-    }, nil
-}
-
-func (p *CustomParser) Parse(ctx context.Context, reader io.Reader, opts ...parser.Option) ([]*schema.Document, error) {
-    // 1. 处理通用选项
-    commonOpts := parser.GetCommonOptions(&parser.Options{}, opts...)
-    _ = commonOpts
-
-    // 2. 处理特定选项
-    myOpts := &options{
-       Encoding: p.defaultEncoding,
-       MaxSize:  p.defaultMaxSize,
-    }
-    myOpts = parser.GetImplSpecificOptions(myOpts, opts...)
-    _ = myOpts
-    // 3. 实现解析逻辑
-
-    return []*schema.Document{{
-       Content: "Hello World",
-    }}, nil
-}
-```
-
-### **注意事项**
-
-1. 注意对公共 option 抽象的处理
-2. 注意 metadata 的设置和传递

docs/Eino/docs/core_modules/components/document_transformer_guide.md

@@ -1,279 +0,0 @@
----
-Description: ""
-date: "2025-07-21"
-lastmod: ""
-tags: []
-title: Document Transformer 使用说明
-weight: 3
----
-
-## **基本介绍**
-
-Document Transformer 是一个用于文档转换和处理的组件。它的主要作用是对输入的文档进行各种转换操作，如分割、过滤、合并等，从而得到满足特定需求的文档。这个组件可用于以下场景中：
-
-- 将长文档分割成小段落以便于处理
-- 根据特定规则过滤文档内容
-- 对文档内容进行结构化转换
-- 提取文档中的特定部分
-
-## **组件定义**
-
-### **接口定义**
-
-> 代码位置：eino/components/document/interface.go
-
-```go
-type Transformer interface {
-    Transform(ctx context.Context, src []*schema.Document, opts ...TransformerOption) ([]*schema.Document, error)
-}
-```
-
-#### **Transform 方法**
-
-- 功能：对输入的文档进行转换处理
-- 参数：
-  - ctx：上下文对象，用于传递请求级别的信息，同时也用于传递 Callback Manager
-  - src：待处理的文档列表
-  - opts：可选参数，用于配置转换行为
-- 返回值：
-  - `[]*schema.Document`：转换后的文档列表
-  - error：转换过程中的错误信息
-
-### **Document 结构体**
-
-```go
-type Document struct {
-    // ID 是文档的唯一标识符
-    ID string    
-    // Content 是文档的内容
-    Content string
-    // MetaData 用于存储文档的元数据信息
-    MetaData map[string]any
-}
-```
-
-Document 结构体是文档的标准格式，包含以下重要字段：
-
-- ID：文档的唯一标识符，用于在系统中唯一标识一个文档
-- Content：文档的实际内容
-- MetaData：文档的元数据，可以存储如下信息：
-  - 文档的来源信息
-  - 文档的向量表示（用于向量检索）
-  - 文档的分数（用于排序）
-  - 文档的子索引（用于分层检索）
-  - 其他自定义元数据
-
-### **公共 Option**
-
-Transformer 组件使用 TransformerOption 来定义可选参数，目前没有公共的 option。每个具体的实现可以定义自己的特定 Option，通过 WrapTransformerImplSpecificOptFn 函数包装成统一的 TransformerOption 类型。
-
-## **使用方式**
-
-### **单独使用**
-
-> 代码位置：eino-ext/components/document/transformer/splitter/markdown/examples/headersplitter
-
-```go
-import (
-    "github.com/cloudwego/eino/schema"
-    "github.com/cloudwego/eino-ext/components/document/transformer/splitter/markdown"
-)
-
-// 初始化 transformer (以 markdown 为例)
-transformer, _ := markdown.NewHeaderSplitter(ctx, &markdown.HeaderConfig{
-    // 配置参数
-    Headers: map[string]string{
-       "##": "",
-    },
-})
-
-markdownDoc := &schema.Document{
-    Content: "## Title 1\nHello Word\n## Title 2\nWord Hello",
-}
-// 转换文档
-transformedDocs, _ := transformer.Transform(ctx, []*schema.Document{markdownDoc})
-
-for idx, doc := range transformedDocs {
-    log.Printf("doc segment %v: %v", idx, doc.Content)
-}
-```
-
-### **在编排中使用**
-
-```go
-// 在 Chain 中使用
-chain := compose.NewChain[[]*schema.Document, []*schema.Document]()
-chain.AppendDocumentTransformer(transformer)
-
-// 在 Graph 中使用
-graph := compose.NewGraph[[]*schema.Document, []*schema.Document]()
-graph.AddDocumentTransformerNode("transformer_node", transformer)
-```
-
-## **Option 和 Callback 使用**
-
-### **Callback 使用示例**
-
-> 代码位置：eino-ext/components/document/transformer/splitter/markdown/examples/headersplitter
-
-```go
-import (
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/components/document"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-    callbacksHelper "github.com/cloudwego/eino/utils/callbacks"
-
-    "github.com/cloudwego/eino-ext/components/document/transformer/splitter/markdown"
-)
-
-// 创建 callback handler
-handler := &callbacksHelper.TransformerCallbackHandler{
-    OnStart: func(ctx context.Context, info *callbacks.RunInfo, input *document.TransformerCallbackInput) context.Context {
-       log.Printf("input access, len: %v, content: %s\n", len(input.Input), input.Input[0].Content)
-       return ctx
-    },
-    OnEnd: func(ctx context.Context, info *callbacks.RunInfo, output *document.TransformerCallbackOutput) context.Context {
-       log.Printf("output finished, len: %v\n", len(output.Output))
-       return ctx
-    },
-    // OnError
-}
-
-// 使用 callback handler
-helper := callbacksHelper.NewHandlerHelper().
-    Transformer(handler).
-    Handler()
-
-chain := compose.NewChain[[]*schema.Document, []*schema.Document]()
-chain.AppendDocumentTransformer(transformer)
-
-// 在运行时使用
-run, _ := chain.Compile(ctx)
-
-outDocs, _ := run.Invoke(ctx, []*schema.Document{markdownDoc}, compose.WithCallbacks(helper))
-
-for idx, doc := range outDocs {
-    log.Printf("doc segment %v: %v", idx, doc.Content)
-}
-```
-
-## **已有实现**
-
-1. Markdown Header Splitter: 基于 Markdown 标题进行文档分割 [Splitter - markdown](/zh/docs/eino/ecosystem_integration/document/splitter_markdown)
-2. Text Splitter: 基于文本长度或分隔符进行文档分割 [Splitter - semantic](/zh/docs/eino/ecosystem_integration/document/splitter_semantic)
-3. Document Filter: 基于规则过滤文档内容 [Splitter - recursive](/zh/docs/eino/ecosystem_integration/document/splitter_recursive)
-
-## **自行实现参考**
-
-实现自定义的 Transformer 组件时，需要注意以下几点：
-
-1. option 的处理
-2. callback 的处理
-
-### **Option 机制**
-
-自定义 Transformer 需要实现自己的 Option 机制：
-
-```go
-// 定义 Option 结构体
-type MyTransformerOptions struct {
-    ChunkSize int
-    Overlap int
-    MinChunkLength int
-}
-
-// 定义 Option 函数
-func WithChunkSize(size int) document.TransformerOption {
-    return document.WrapTransformerImplSpecificOptFn(func(o *MyTransformerOptions) {
-        o.ChunkSize = size
-    })
-}
-
-func WithOverlap(overlap int) document.TransformerOption {
-    return document.WrapTransformerImplSpecificOptFn(func(o *MyTransformerOptions) {
-        o.Overlap = overlap
-    })
-}
-```
-
-### **Callback 处理**
-
-Transformer 实现需要在适当的时机触发回调：
-
-```go
-// 这是由 transformer 定义的回调输入输出，自行组件在实现时需要满足结构的含义
-type TransformerCallbackInput struct {
-    Input []*schema.Document
-    Extra map[string]any
-}
-
-type TransformerCallbackOutput struct {
-    Output []*schema.Document
-    Extra map[string]any
-}
-```
-
-### **完整实现示例**
-
-```go
-type MyTransformer struct {
-    chunkSize int
-    overlap int
-    minChunkLength int
-}
-
-func NewMyTransformer(config *MyTransformerConfig) (*MyTransformer, error) {
-    return &MyTransformer{
-        chunkSize: config.DefaultChunkSize,
-        overlap: config.DefaultOverlap,
-        minChunkLength: config.DefaultMinChunkLength,
-    }, nil
-}
-
-func (t *MyTransformer) Transform(ctx context.Context, src []*schema.Document, opts ...document.TransformerOption) ([]*schema.Document, error) {
-    // 1. 处理 Option
-    options := &MyTransformerOptions{
-        ChunkSize: t.chunkSize,
-        Overlap: t.overlap,
-        MinChunkLength: t.minChunkLength,
-    }
-    options = document.GetTransformerImplSpecificOptions(options, opts...)
-    
-    // 2. 开始转换前的回调
-    ctx = callbacks.OnStart(ctx, info, &document.TransformerCallbackInput{
-        Input: src,
-    })
-    
-    // 3. 执行转换逻辑
-    docs, err := t.doTransform(ctx, src, options)
-    
-    // 4. 处理错误和完成回调
-    if err != nil {
-        ctx = callbacks.OnError(ctx, info, err)
-        return nil, err
-    }
-    
-    ctx = callbacks.OnEnd(ctx, info, &document.TransformerCallbackOutput{
-        Output: docs,
-    })
-    
-    return docs, nil
-}
-
-func (t *MyTransformer) doTransform(ctx context.Context, src []*schema.Document, opts *MyTransformerOptions) ([]*schema.Document, error) {
-    // 实现文档转换逻辑
-    return docs, nil
-}
-```
-
-### **注意事项**
-
-- 转换后的文档需要注意对 metadata 的处理，注意保留原 metadata，以及新增自定义的 metadata
-
-## 其他参考文档
-
-- [[🚧]Eino: Embedding 使用说明](/zh/docs/eino/core_modules/components/embedding_guide)
-- [[🚧]Eino: Indexer 使用说明](/zh/docs/eino/core_modules/components/indexer_guide)
-- [[🚧]Eino: Retriever 使用说明](/zh/docs/eino/core_modules/components/retriever_guide)
-- [[🚧]Eino: Document Loader 使用说明](/zh/docs/eino/core_modules/components/document_loader_guide)

docs/Eino/docs/core_modules/components/embedding_guide.md

@@ -1,273 +0,0 @@
----
-Description: ""
-date: "2025-07-21"
-lastmod: ""
-tags: []
-title: Embedding 使用说明
-weight: 2
----
-
-## **基本介绍**
-
-Embedding 组件是一个用于将文本转换为向量表示的组件。它的主要作用是将文本内容映射到向量空间，使得语义相似的文本在向量空间中的距离较近。这个组件在以下场景中发挥重要作用：
-
-- 文本相似度计算
-- 语义搜索
-- 文本聚类分析
-
-## **组件定义**
-
-### **接口定义**
-
-```go
-type Embedder interface {
-    EmbedStrings(ctx context.Context, texts []string, opts ...Option) ([][]float64, error)
-}
-```
-
-#### **EmbedStrings 方法**
-
-- 功能：将一组文本转换为向量表示
-- 参数：
-  - ctx：上下文对象，用于传递请求级别的信息，同时也用于传递 Callback Manager
-  - texts：待转换的文本列表
-  - opts：转换选项，用于配置转换行为
-- 返回值：
-  - `[][]float64`：文本对应的向量表示列表，每个向量的维度由具体的实现决定
-  - error：转换过程中的错误信息
-
-### **公共 Option**
-
-Embedding 组件使用 EmbeddingOption 来定义可选参数，下方是抽象出的公共 option。每个具体的实现可以定义自己的特定 Option，通过 WrapEmbeddingImplSpecificOptFn 函数包装成统一的 EmbeddingOption 类型。
-
-```go
-type Options struct {
-    // Model 是用于生成向量的模型名称
-    Model *string
-}
-```
-
-可以通过以下方式设置选项：
-
-```go
-// 设置模型名称
-WithModel(model string) Option
-```
-
-## **使用方式**
-
-### **单独使用**
-
-> 代码位置：eino-ext/components/embedding/openai/examples/embedding
-
-```go
-import "github.com/cloudwego/eino-ext/components/embedding/openai"
-
-embedder, _ := openai.NewEmbedder(ctx, &openai.EmbeddingConfig{
-    APIKey:     accessKey,
-    Model:      "text-embedding-3-large",
-    Dimensions: &defaultDim,
-    Timeout:    0,
-})
-
-vectorIDs, _ := embedder.EmbedStrings(ctx, []string{"hello", "how are you"})
-```
-
-### **在编排中使用**
-
-> 代码位置：eino-ext/components/embedding/openai/examples/embedding
-
-```go
-// 在 Chain 中使用
-chain := compose.NewChain[[]string, [][]float64]()
-chain.AppendEmbedding(embedder)
-
-// 在 Graph 中使用
-graph := compose.NewGraph[[]string, [][]float64]()
-graph.AddEmbeddingNode("embedding_node", embedder)
-```
-
-## **Option 和 Callback 使用**
-
-### **Option 使用示例**
-
-```go
-// 使用选项 (以独立使用组件为例)
-vectors, err := embedder.EmbedStrings(ctx, texts,
-    embedding.WithModel("text-embedding-3-small"),
-)
-```
-
-### **Callback 使用示例**
-
-> 代码位置：eino-ext/components/embedding/openai/examples/embedding
-
-```go
-import (
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/components/embedding"
-    "github.com/cloudwego/eino/compose"
-    callbacksHelper "github.com/cloudwego/eino/utils/callbacks"
-    "github.com/cloudwego/eino-ext/components/embedding/openai"
-)
-
-handler := &callbacksHelper.EmbeddingCallbackHandler{
-    OnStart: func(ctx context.Context, runInfo *callbacks.RunInfo, input *embedding.CallbackInput) context.Context {
-       log.Printf("input access, len: %v, content: %s\n", len(input.Texts), input.Texts)
-       return ctx
-    },
-    OnEnd: func(ctx context.Context, runInfo *callbacks.RunInfo, output *embedding.CallbackOutput) context.Context {
-       log.Printf("output finished, len: %v\n", len(output.Embeddings))
-       return ctx
-    },
-}
-
-callbackHandler := callbacksHelper.NewHandlerHelper().Embedding(handler).Handler()
-
-chain := compose.NewChain[[]string, [][]float64]()
-chain.AppendEmbedding(embedder)
-
-// 编译并运行
-runnable, _ := chain.Compile(ctx)
-vectors, _ = runnable.Invoke(ctx, []string{"hello", "how are you"},
-    compose.WithCallbacks(callbackHandler))
-
-log.Printf("vectors in chain: %v", vectors)
-```
-
-## **已有实现**
-
-1. OpenAI Embedding: 使用 OpenAI 的文本嵌入模型生成向量 [Embedding - OpenAI](/zh/docs/eino/ecosystem_integration/embedding/embedding_openai)
-2. ARK Embedding: 使用 ARK 平台的模型生成向量 [Embedding - ARK](/zh/docs/eino/ecosystem_integration/embedding/embedding_ark)
-
-## **自行实现参考**
-
-实现自定义的 Embedding 组件时，需要注意以下几点：
-
-1. 注意处理公共 option
-2. 注意实现 callback 机制
-
-### **Option 机制**
-
-自定义 Embedding 需要实现自己的 Option 机制：
-
-```go
-// 定义 Option 结构体
-type MyEmbeddingOptions struct {
-    BatchSize int
-    MaxRetries int
-    Timeout time.Duration
-}
-
-// 定义 Option 函数
-func WithBatchSize(size int) embedding.Option {
-    return embedding.WrapEmbeddingImplSpecificOptFn(func(o *MyEmbeddingOptions) {
-        o.BatchSize = size
-    })
-}
-```
-
-### **Callback 处理**
-
-Embedder 实现需要在适当的时机触发回调。框架已经定义了标准的回调输入输出结构体：
-
-```go
-// CallbackInput 是 embedding 回调的输入
-type CallbackInput struct {
-    // Texts 是待转换的文本列表
-    Texts []string
-    // Config 是生成向量的配置信息
-    Config *Config
-    // Extra 是回调的额外信息
-    Extra map[string]any
-}
-
-// CallbackOutput 是 embedding 回调的输出
-type CallbackOutput struct {
-    // Embeddings 是生成的向量列表
-    Embeddings [][]float64
-    // Config 是生成向量的配置信息
-    Config *Config
-    // TokenUsage 是 token 使用情况
-    TokenUsage *TokenUsage
-    // Extra 是回调的额外信息
-    Extra map[string]any
-}
-
-// TokenUsage 是 token 使用情况
-type TokenUsage struct {
-    // PromptTokens 是提示词的 token 数量
-    PromptTokens int
-    // CompletionTokens 是补全的 token 数量
-    CompletionTokens int
-    // TotalTokens 是总的 token 数量
-    TotalTokens int
-}
-```
-
-### **完整实现示例**
-
-```go
-type MyEmbedder struct {
-    model string
-    batchSize int
-}
-
-func NewMyEmbedder(config *MyEmbedderConfig) (*MyEmbedder, error) {
-    return &MyEmbedder{
-        model: config.DefaultModel,
-        batchSize: config.DefaultBatchSize,
-    }, nil
-}
-
-func (e *MyEmbedder) EmbedStrings(ctx context.Context, texts []string, opts ...embedding.Option) ([][]float64, error) {
-    // 1. 处理选项
-    options := &MyEmbeddingOptions{
-        Options: &embedding.Options{},
-        BatchSize: e.batchSize,
-    }
-    options.Options = embedding.GetCommonOptions(options.Options, opts...)
-    options = embedding.GetImplSpecificOptions(options.Options, opts...)
-    
-    // 2. 获取 callback manager
-    cm := callbacks.ManagerFromContext(ctx)
-    
-    // 3. 开始生成前的回调
-    ctx = cm.OnStart(ctx, info, &embedding.CallbackInput{
-        Texts: texts,
-        Config: &embedding.Config{
-            Model: e.model,
-        },
-    })
-    
-    // 4. 执行向量生成逻辑
-    vectors, tokenUsage, err := e.doEmbed(ctx, texts, options)
-    
-    // 5. 处理错误和完成回调
-    if err != nil {
-        ctx = cm.OnError(ctx, info, err)
-        return nil, err
-    }
-    
-    ctx = cm.OnEnd(ctx, info, &embedding.CallbackOutput{
-        Embeddings: vectors,
-        Config: &embedding.Config{
-            Model: e.model,
-        },
-        TokenUsage: tokenUsage,
-    })
-    
-    return vectors, nil
-}
-
-func (e *MyEmbedder) doEmbed(ctx context.Context, texts []string, opts *MyEmbeddingOptions) ([][]float64, *TokenUsage, error) {
-    // 实现逻辑
-    return vectors, tokenUsage, nil
-}
-```
-
-## 其他参考文档
-
-- [Eino: Document Loader 使用说明](/zh/docs/eino/core_modules/components/document_loader_guide)
-- [Eino: Indexer 使用说明](/zh/docs/eino/core_modules/components/indexer_guide)
-- [Eino: Retriever 使用说明](/zh/docs/eino/core_modules/components/retriever_guide)

docs/Eino/docs/core_modules/components/indexer_guide.md

@@ -1,446 +0,0 @@
----
-Description: ""
-date: "2026-01-20"
-lastmod: ""
-tags: []
-title: Indexer 使用说明
-weight: 5
----
-
-## **基本介绍**
-
-Indexer 组件是一个用于存储和索引文档的组件。它的主要作用是将文档及其向量表示存储到后端存储系统中，并提供高效的检索能力。这个组件在以下场景中发挥重要作用：
-
-- 构建向量数据库，以用于语义关联搜索
-
-## **组件定义**
-
-### **接口定义**
-
-> 代码位置：eino/components/indexer/interface.go
-
-```go
-type Indexer interface {
-    Store(ctx context.Context, docs []*schema.Document, opts ...Option) (ids []string, err error)
-}
-```
-
-#### **Store 方法**
-
-- 功能：存储文档并建立索引
-- 参数：
-  - ctx：上下文对象，用于传递请求级别的信息，同时也用于传递 Callback Manager
-  - docs：待存储的文档列表
-  - opts：存储选项，用于配置存储行为
-- 返回值：
-  - ids：存储成功的文档 ID 列表
-  - error：存储过程中的错误信息
-
-### **公共 Option**
-
-Indexer 组件使用 IndexerOption 来定义可选参数，Indexer 定义了如下的公共 option。另外，每个具体的实现可以定义自己的特定 Option，通过 WrapIndexerImplSpecificOptFn 函数包装成统一的 IndexerOption 类型。
-
-```go
-type Options struct {
-    // SubIndexes 是要建立索引的子索引列表
-    SubIndexes []string   
-    // Embedding 是用于生成文档向量的组件
-    Embedding embedding.Embedder
-}
-```
-
-可以通过以下方式设置选项：
-
-```go
-// 设置子索引
-WithSubIndexes(subIndexes []string) Option
-// 设置向量生成组件
-WithEmbedding(emb embedding.Embedder) Option
-```
-
-## **使用方式**
-
-### **单独使用**
-
-#### VikingDB 示例
-
-```go
-import (
-    "github.com/cloudwego/eino/schema"
-    "github.com/cloudwego/eino-ext/components/indexer/volc_vikingdb"
-)
-
-collectionName := "eino_test"
-
-/*
- * 下面示例中提前构建了一个名为 eino_test 的数据集 (collection)，字段配置为:
- * 字段名称       字段类型         向量维度
- * ID            string
- * vector         vector       1024
- * sparse_vector    sparse_vector
- * content        string
- * extra_field_1    string
- *
- * component 使用时注意:
- * 1. ID / vector / sparse_vector / content 的字段名称与类型与上方配置一致
- * 2. vector 向量维度需要与 ModelName 对应的模型所输出的向量维度一致
- * 3. 部分模型不输出稀疏向量，此时 UseSparse 需要设置为 false，collection 可以不设置 sparse_vector 字段
- */
-
-cfg := &volc_vikingdb.IndexerConfig{
-    // https://api-vikingdb.volces.com （华北）
-    // https://api-vikingdb.mlp.cn-shanghai.volces.com（华东）
-    // https://api-vikingdb.mlp.ap-mya.byteplus.com（海外-柔佛）
-    Host:              "api-vikingdb.volces.com",
-    Region:            "cn-beijing",
-    AK:                ak,
-    SK:                sk,
-    Scheme:            "https",
-    ConnectionTimeout: 0,
-    Collection:        collectionName,
-    EmbeddingConfig: volc_vikingdb.EmbeddingConfig{
-       UseBuiltin: true,
-       ModelName:  "bge-m3",
-       UseSparse:  true,
-    },
-    AddBatchSize: 10,
-}
-
-volcIndexer, _ := volc_vikingdb.NewIndexer(ctx, cfg)
-
-doc := &schema.Document{
-    ID:      "mock_id_1",
-    Content: "A ReAct prompt consists of few-shot task-solving trajectories, with human-written text reasoning traces and actions, as well as environment observations in response to actions",
-}
-volc_vikingdb.SetExtraDataFields(doc, map[string]interface{}{"extra_field_1": "mock_ext_abc"})
-volc_vikingdb.SetExtraDataTTL(doc, 1000)
-
-docs := []*schema.Document{doc}
-resp, _ := volcIndexer.Store(ctx, docs)
-
-fmt.Printf("vikingDB store success, docs=%v, resp ids=%v\n", docs, resp)
-```
-
-#### Milvus 示例
-
-```go
-package main
-
-import (
-        "github.com/cloudwego/eino/schema"
-        "github.com/milvus-io/milvus/client/v2/milvusclient"
-        "github.com/cloudwego/eino-ext/components/indexer/milvus2"
-)
-
-// 创建索引器
-indexer, err := milvus2.NewIndexer(ctx, &milvus2.IndexerConfig{
-        ClientConfig: &milvusclient.ClientConfig{
-                Address:  addr,
-                Username: username,
-                Password: password,
-        },
-        Collection:   "my_collection",
-        Dimension:    1024, // 与 embedding 模型维度匹配
-        MetricType:   milvus2.COSINE,
-        IndexBuilder: milvus2.NewHNSWIndexBuilder().WithM(16).WithEfConstruction(200),
-        Embedding:    emb,
-})
-
-// 索引文档
-docs := []*schema.Document{
-        {
-                ID:      "doc1",
-                Content: "EINO is a framework for building AI applications",
-        },
-}
-ids, err := indexer.Store(ctx, docs)
-```
-
-#### ElasticSearch 7 示例
-
-```go
-import (
-        "github.com/cloudwego/eino/components/embedding"
-        "github.com/cloudwego/eino/schema"
-        elasticsearch "github.com/elastic/go-elasticsearch/v7"
-        "github.com/cloudwego/eino-ext/components/indexer/es7"
-)
-
-client, _ := elasticsearch.NewClient(elasticsearch.Config{
-        Addresses: []string{"http://localhost:9200"},
-        Username:  username,
-        Password:  password,
-})
-
-// 创建 ES 索引器组件
-indexer, _ := es7.NewIndexer(ctx, &es7.IndexerConfig{
-        Client:    client,
-        Index:     indexName,
-        BatchSize: 10,
-        DocumentToFields: func(ctx context.Context, doc *schema.Document) (field2Value map[string]es7.FieldValue, err error) {
-                return map[string]es7.FieldValue{
-                        fieldContent: {
-                                Value:    doc.Content,
-                                EmbedKey: fieldContentVector, // 对文档内容进行向量化并保存到 "content_vector" 字段
-                        },
-                        fieldExtraLocation: {
-                                Value: doc.MetaData[docExtraLocation],
-                        },
-                }, nil
-        },
-        Embedding: emb,
-})
-
-// 索引文档
-docs := []*schema.Document{
-        {
-                ID:      "doc1",
-                Content: "EINO is a framework for building AI applications",
-        },
-}
-ids, err := indexer.Store(ctx, docs)
-```
-
-#### OpenSearch 2 示例
-
-```go
-package main
-
-import (
-        "github.com/cloudwego/eino/schema"
-        opensearch "github.com/opensearch-project/opensearch-go/v2"
-        "github.com/cloudwego/eino-ext/components/indexer/opensearch2"
-)
-
-client, err := opensearch.NewClient(opensearch.Config{
-        Addresses: []string{"http://localhost:9200"},
-        Username:  username,
-        Password:  password,
-})
-
-// 创建 opensearch 索引器组件
-indexer, _ := opensearch2.NewIndexer(ctx, &opensearch2.IndexerConfig{
-        Client:    client,
-        Index:     "your_index_name",
-        BatchSize: 10,
-        DocumentToFields: func(ctx context.Context, doc *schema.Document) (map[string]opensearch2.FieldValue, error) {
-                return map[string]opensearch2.FieldValue{
-                        "content": {
-                                Value:    doc.Content,
-                                EmbedKey: "content_vector",
-                        },
-                }, nil
-        },
-        Embedding: emb,
-})
-
-// 索引文档
-docs := []*schema.Document{
-        {
-                ID:      "doc1",
-                Content: "EINO is a framework for building AI applications",
-        },
-}
-ids, err := indexer.Store(ctx, docs)
-```
-
-### **在编排中使用**
-
-```go
-// 在 Chain 中使用
-chain := compose.NewChain[[]*schema.Document, []string]()
-chain.AppendIndexer(indexer)
-
-// 在 Graph 中使用
-graph := compose.NewGraph[[]*schema.Document, []string]()
-graph.AddIndexerNode("indexer_node", indexer)
-```
-
-## **Option 和 Callback 使用**
-
-### **Option 使用示例**
-
-```go
-// 使用选项 (单独使用时)
-ids, err := indexer.Store(ctx, docs,
-    // 设置子索引
-    indexer.WithSubIndexes([]string{"kb_1", "kb_2"}),
-    // 设置向量生成组件
-    indexer.WithEmbedding(embedder),
-)
-```
-
-### **Callback 使用示例**
-
-> 代码位置：eino-ext/components/indexer/volc_vikingdb/examples/builtin_embedding
-
-```go
-import (
-    "context"
-    "fmt"
-    "log"
-    "os"
-
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/components/indexer"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-    callbacksHelper "github.com/cloudwego/eino/utils/callbacks"
-
-    "github.com/cloudwego/eino-ext/components/indexer/volc_vikingdb"
-)
-
-handler := &callbacksHelper.IndexerCallbackHandler{
-    OnStart: func(ctx context.Context, info *callbacks.RunInfo, input *indexer.CallbackInput) context.Context {
-       log.Printf("input access, len: %v, content: %s\n", len(input.Docs), input.Docs[0].Content)
-       return ctx
-    },
-    OnEnd: func(ctx context.Context, info *callbacks.RunInfo, output *indexer.CallbackOutput) context.Context {
-       log.Printf("output finished, len: %v, ids=%v\n", len(output.IDs), output.IDs)
-       return ctx
-    },
-    // OnError
-}
-
-// 使用 callback handler
-helper := callbacksHelper.NewHandlerHelper().
-    Indexer(handler).
-    Handler()
-
-chain := compose.NewChain[[]*schema.Document, []string]()
-chain.AppendIndexer(volcIndexer)
-
-// 在运行时使用
-run, _ := chain.Compile(ctx)
-
-outIDs, _ := run.Invoke(ctx, docs, compose.WithCallbacks(helper))
-
-fmt.Printf("vikingDB store success, docs=%v, resp ids=%v\n", docs, outIDs)
-```
-
-## **已有实现**
-
-- Volc VikingDB Indexer: 基于火山引擎 VikingDB 实现的向量数据库索引器 [Indexer - VikingDB](/zh/docs/eino/ecosystem_integration/indexer/indexer_volc_vikingdb)
-- Milvus v2.5+ Indexer: 基于 Milvus 实现的向量数据库索引器 [Indexer - Milvus 2 (v2.5+)](/zh/docs/eino/ecosystem_integration/indexer/indexer_milvusv2)
-- Milvus v2.4- Indexer: 基于 Milvus 实现的向量数据库索引器 [Indexer - Milvus (v2.4-)](/zh/docs/eino/ecosystem_integration/indexer/indexer_milvus)
-- Elasticsearch 8 Indexer: 基于 ES8 实现的通用搜索引擎索引器 [Indexer - ElasticSearch 8](/zh/docs/eino/ecosystem_integration/indexer/indexer_es8)
-- ElasticSearch 7 Indexer: 基于 ES7 实现的通用搜索引擎索引器 [Indexer - Elasticsearch 7 ](/zh/docs/eino/ecosystem_integration/indexer/indexer_elasticsearch7)
-- OpenSearch 3 Indexer: 基于 OpenSearch 3 实现的通用搜索引擎索引器 [Indexer - OpenSearch 3](/zh/docs/eino/ecosystem_integration/indexer/indexer_opensearch3)
-- OpenSearch 2 Indexer: 基于 OpenSearch 2 实现的通用搜索引擎索引器 [Indexer - OpenSearch 2](/zh/docs/eino/ecosystem_integration/indexer/indexer_opensearch2)
-
-## **自行实现参考**
-
-实现自定义的 Indexer 组件时，需要注意以下几点：
-
-1. 注意对公共 option 的处理以及组件实现级的 option 处理
-2. 注意对 callback 的处理
-
-### **Option 机制**
-
-自定义 Indexer 可根据需要实现自己的 Option：
-
-```go
-// 定义 Option 结构体
-type MyIndexerOptions struct {
-    BatchSize int
-    MaxRetries int
-}
-
-// 定义 Option 函数
-func WithBatchSize(size int) indexer.Option {
-    return indexer.WrapIndexerImplSpecificOptFn(func(o *MyIndexerOptions) {
-        o.BatchSize = size
-    })
-}
-```
-
-### **Callback 处理**
-
-Indexer 实现需要在适当的时机触发回调。框架已经定义了标准的回调输入输出结构体：
-
-```go
-// CallbackInput 是 indexer 回调的输入
-type CallbackInput struct {
-    // Docs 是待索引的文档列表
-    Docs []*schema.Document
-    // Extra 是回调的额外信息
-    Extra map[string]any
-}
-
-// CallbackOutput 是 indexer 回调的输出
-type CallbackOutput struct {
-    // IDs 是索引器返回的文档 ID 列表
-    IDs []string
-    // Extra 是回调的额外信息
-    Extra map[string]any
-}
-```
-
-### **完整实现示例**
-
-```go
-type MyIndexer struct {
-    batchSize int
-    embedder embedding.Embedder
-}
-
-func NewMyIndexer(config *MyIndexerConfig) (*MyIndexer, error) {
-    return &MyIndexer{
-        batchSize: config.DefaultBatchSize,
-        embedder: config.DefaultEmbedder,
-    }, nil
-}
-
-func (i *MyIndexer) Store(ctx context.Context, docs []*schema.Document, opts ...indexer.Option) ([]string, error) {
-    // 1. 处理选项
-    options := &indexer.Options{},
-    options = indexer.GetCommonOptions(options, opts...)
-    
-    // 2. 获取 callback manager
-    cm := callbacks.ManagerFromContext(ctx)
-    
-    // 3. 开始存储前的回调
-    ctx = cm.OnStart(ctx, info, &indexer.CallbackInput{
-        Docs: docs,
-    })
-    
-    // 4. 执行存储逻辑
-    ids, err := i.doStore(ctx, docs, options)
-    
-    // 5. 处理错误和完成回调
-    if err != nil {
-        ctx = cm.OnError(ctx, info, err)
-        return nil, err
-    }
-    
-    ctx = cm.OnEnd(ctx, info, &indexer.CallbackOutput{
-        IDs: ids,
-    })
-    
-    return ids, nil
-}
-
-func (i *MyIndexer) doStore(ctx context.Context, docs []*schema.Document, opts *indexer.Options) ([]string, error) {
-    // 实现文档存储逻辑 (注意处理公共option的参数)
-    // 1. 如果设置了 Embedding 组件，生成文档的向量表示
-    if opts.Embedding != nil {
-        // 提取文档内容
-        texts := make([]string, len(docs))
-        for j, doc := range docs {
-            texts[j] = doc.Content
-        }
-        // 生成向量
-        vectors, err := opts.Embedding.EmbedStrings(ctx, texts)
-        if err != nil {
-            return nil, err
-        }
-        // 将向量存储到文档的 MetaData 中
-        for j, doc := range docs {
-            doc.WithVector(vectors[j])
-        }
-    }
-    
-    // 2. 其他自定义逻辑
-    return ids, nil
-}
-```

docs/Eino/docs/core_modules/components/lambda_guide.md

@@ -1,226 +0,0 @@
----
-Description: ""
-date: "2025-11-20"
-lastmod: ""
-tags: []
-title: Lambda 使用说明
-weight: 4
----
-
-## **基本介绍**
-
-Lambda 是 Eino 中最基础的组件类型，它允许用户在工作流中嵌入自定义的函数逻辑。Lambda 组件底层是由输入输出是否流所形成的 4 种运行函数组成，对应 4 种交互模式: Invoke、Stream、Collect、Transform。
-
-用户构建 Lambda 时可实现其中的一种或多种，框架会根据一定的规则进行转换，详细介绍可见: [Eino: 概述](/zh/docs/eino/overview) (见 Runnable 小节)
-
-## **组件定义及实现**
-
-Lambda 组件的核心是 `Lambda` 结构体，它包装了用户提供的 Lambda 函数，用户可通过构建方法创建一个 Lambda 组件：
-
-> 代码位置：eino/compose/types_lambda.go
-
-```go
-type Lambda struct {
-    executor *composableRunnable
-}
-```
-
-Lambda 支持的四种函数类型定义如下，即用户提供的 Lambda 函数需要满足这些函数签名：
-
-```go
-type Invoke[I, O, TOption any] func(ctx context.Context, input I, opts ...TOption) (output O, err error)
-
-type Stream[I, O, TOption any] func(ctx context.Context, input I, opts ...TOption) (output *schema.StreamReader[O], err error)
-
-type Collect[I, O, TOption any] func(ctx context.Context, input *schema.StreamReader[I], opts ...TOption) (output O, err error)
-
-type Transform[I, O, TOption any] func(ctx context.Context, input *schema.StreamReader[I], opts ...TOption) (output *schema.StreamReader[O], err error)
-```
-
-## 使用方式
-
-> 示例中的代码参考： [https://github.com/cloudwego/eino-examples/blob/main/components/lambda](https://github.com/cloudwego/eino-examples/blob/main/components/lambda)
-
-### 构建方法
-
-从 Eino 的组件接口的统一规范来看，一个组件的可调用方法需要有 3 个入参 和 2 个出参： func (ctx, input, ...option) (output, error), 但在使用 Lambda 的场景中，常希望通过提供一个简单的函数实现来添加一个 Lambda 节点，因此构建方法分成 3 种：
-
-- 仅提供一种已选定输入输出是否为流的交互函数
-  - 不带自定义 Option
-  - 使用自定义 Option
-- 从 4 中交互函数中自定义 n(n<=4) 种的函数： AnyLambda
-
-#### 不带自定义 Option
-
-- InvokableLambda
-
-```go
-// input 和 output 类型为自定义的任何类型
-lambda := compose.InvokableLambda(func(ctx context.Context, input string) (output string, err error) {
-    // some logic
-})
-```
-
-- StreamableLambda
-
-```go
-// input 可以是任意类型，output 必须是 *schema.StreamReader[O]，其中 O 可以是任意类型
-lambda := compose.StreamableLambda(func(ctx context.Context, input string) (output *schema.StreamReader[string], err error) {
-    // some logic
-})
-```
-
-- CollectableLambda
-
-```go
-// input 必须是 *schema.StreamReader[I]，其中 I 可以是任意类型，output 可以是任意类型
-lambda := compose.CollectableLambda(func(ctx context.Context, input *schema.StreamReader[string]) (output string, err error) {
-    // some logic
-})
-```
-
-- TransformableLambda
-
-```go
-// input 和 output 必须是 *schema.StreamReader[I]，其中 I 可以是任意类型
-lambda := compose.TransformableLambda(func(ctx context.Context, input *schema.StreamReader[string]) (output *schema.StreamReader[string], err error) {
-    // some logic
-})
-```
-
-- 四种 Lambda 方法的构造方法中，具有如下几个相同的 Option 选项
-- compose.WithLambdaType():  修改 Lambda 组件的 Component 类型，默认是：Lambda
-- compose.WithLambdaCallbackEnable(): 关闭 Lambda 组件默认 在 Graph 中开启的 Node Callback
-
-#### 使用自定义 Option
-
-每一种交互方式都对应了一个构建方法，以下以 Invoke 为例：
-
-```go
-type Options struct {
-    Field1 string
-}
-type MyOption func(*Options)
-
-lambda := compose.InvokableLambdaWithOption(
-    func(ctx context.Context, input string, opts ...MyOption) (output string, err error) {
-        // 处理 opts
-        // some logic
-    }
-)
-```
-
-#### AnyLambda
-
-AnyLambda 允许同时实现多种交互模式的 Lambda 函数类型：
-
-```go
-type Options struct {
-    Field1 string
-}
-
-type MyOption func(*Options)
-
-// input 和 output 类型为自定义的任何类型
-lambda, err := compose.AnyLambda(
-    // Invoke 函数
-    func(ctx context.Context, input string, opts ...MyOption) (output string, err error) {
-        // some logic
-    },
-    // Stream 函数
-    func(ctx context.Context, input string, opts ...MyOption) (output *schema.StreamReader[string], err error) {
-        // some logic
-    },
-    // Collect 函数
-    func(ctx context.Context, input *schema.StreamReader[string], opts ...MyOption) (output string, err error) {
-        // some logic
-    },
-    // Transform 函数
-    func(ctx context.Context, input *schema.StreamReader[string], opts ...MyOption) (output *schema.StreamReader[string], err error) {
-        // some logic
-    },
-)
-```
-
-### **编排中使用**
-
-#### Graph 中使用
-
-在 Graph 中可以通过 AddLambdaNode 添加 Lambda 节点：
-
-```go
-graph := compose.NewGraph[string, *MyStruct]()
-graph.AddLambdaNode(
-    "node1",
-    compose.InvokableLambda(func(ctx context.Context, input string) (*MyStruct, error) {
-        // some logic
-    }),
-)
-```
-
-#### Chain 中使用
-
-在 Chain 中可以通过 AppendLambda 添加 Lambda 节点：
-
-```go
-chain := compose.NewChain[string, string]()
-chain.AppendLambda(compose.InvokableLambda(func(ctx context.Context, input string) (string, error) {
-    // some logic
-}))
-```
-
-### 两个内置的 Lambda
-
-#### ToList
-
-ToList 是一个内置的 Lambda，用于将单个输入元素转换为包含该元素的切片（数组）：
-
-```go
-// 创建一个 ToList Lambda
-lambda := compose.ToList[*schema.Message]()
-
-// 在 Chain 中使用
-chain := compose.NewChain[[]*schema.Message, []*schema.Message]()
-chain.AppendChatModel(chatModel)  // chatModel 返回 *schema.Message
-chain.AppendLambda(lambda)        // 将 *schema.Message 转换为 []*schema.Message
-```
-
-#### MessageParser
-
-MessageParser 是一个内置的 Lambda，用于将 JSON 消息（通常由 LLM 生成）解析为指定的结构体：
-
-```go
-// 定义解析目标结构体
-type MyStruct struct {
-    ID int `json:"id"`
-}
-
-// 创建解析器
-parser := schema.NewMessageJSONParser[*MyStruct](&schema.MessageJSONParseConfig{
-    ParseFrom: schema.MessageParseFromContent,
-    ParseKeyPath: "", // 如果仅需要 parse 子字段，可用 "key.sub.grandsub"
-})
-
-// 创建解析 Lambda
-parserLambda := compose.MessageParser(parser)
-
-// 在 Chain 中使用
-chain := compose.NewChain[*schema.Message, *MyStruct]()
-chain.AppendLambda(parserLambda)
-
-// 使用示例
-runner, err := chain.Compile(context.Background())
-parsed, err := runner.Invoke(context.Background(), &schema.Message{
-    Content: `{"id": 1}`,
-})
-// parsed.ID == 1
-```
-
-MessageParser 支持从消息内容（Content）或工具调用结果（ToolCall）中解析数据，这在意图识别等场景中常用：
-
-```go
-// 从工具调用结果解析
-parser := schema.NewMessageJSONParser[*MyStruct](&schema.MessageJSONParseConfig{
-    ParseFrom: schema.MessageParseFromToolCall,
-})
-```

docs/Eino/docs/core_modules/components/retriever_guide.md

@@ -1,446 +0,0 @@
----
-Description: ""
-date: "2026-01-30"
-lastmod: ""
-tags: []
-title: Retriever 使用说明
-weight: 6
----
-
-## **基本介绍**
-
-Retriever 组件是一个用于从各种数据源检索文档的组件。它的主要作用是根据用户的查询（query）从文档库中检索出最相关的文档。这个组件在以下场景中特别有用：
-
-- 基于向量相似度的文档检索
-- 基于关键词的文档搜索
-- 知识库问答系统 (rag)
-
-## **组件定义**
-
-### **接口定义**
-
-> 代码位置：eino/components/retriever/interface.go
-
-```go
-type Retriever interface {
-    Retrieve(ctx context.Context, query string, opts ...Option) ([]*schema.Document, error)
-}
-```
-
-#### **Retrieve 方法**
-
-- 功能：根据查询检索相关文档
-- 参数：
-  - ctx：上下文对象，用于传递请求级别的信息，同时也用于传递 Callback Manager
-  - query：查询字符串
-  - opts：检索选项，用于配置检索行为
-- 返回值：
-  - `[]*schema.Document`：检索到的文档列表
-  - error：检索过程中的错误信息
-
-### **Document 结构体**
-
-```go
-type Document struct {
-    // ID 是文档的唯一标识符
-    ID string
-    // Content 是文档的内容
-    Content string
-    // MetaData 用于存储文档的元数据信息
-    MetaData map[string]any
-}
-```
-
-### **公共 Option**
-
-Retriever 组件使用 RetrieverOption 来定义可选参数， 以下是 Retriever 组件需要实现的公共 option。另外，每个具体的实现可以定义自己的特定 Option，通过 WrapRetrieverImplSpecificOptFn 函数包装成统一的 RetrieverOption 类型。
-
-```go
-type Options struct {
-    // Index 是检索器使用的索引，不同检索器中的索引可能有不同含义
-    Index *string
-    
-    // SubIndex 是检索器使用的子索引，不同检索器中的子索引可能有不同含义
-    SubIndex *string
-    
-    // TopK 是检索的文档数量上限
-    TopK *int
-    
-    // ScoreThreshold 是文档相似度的阈值，例如 0.5 表示文档的相似度分数必须大于 0.5
-    ScoreThreshold *float64
-    
-    // Embedding 是用于生成查询向量的组件
-    Embedding embedding.Embedder
-    
-    // DSLInfo 是用于检索的 DSL 信息，仅在 viking 类型的检索器中使用
-    DSLInfo map[string]interface{}
-}
-```
-
-可以通过以下方式设置选项：
-
-```go
-// 设置索引
-WithIndex(index string) Option
-
-// 设置子索引
-WithSubIndex(subIndex string) Option
-
-// 设置检索文档数量上限
-WithTopK(topK int) Option
-
-// 设置相似度阈值
-WithScoreThreshold(threshold float64) Option
-
-// 设置向量生成组件
-WithEmbedding(emb embedding.Embedder) Option
-
-// 设置 DSL 信息（仅用于 viking 类型检索器）
-WithDSLInfo(dsl map[string]any) Option
-```
-
-## **使用方式**
-
-### **单独使用**
-
-#### VikingDB 示例
-
-> 代码位置：eino-ext/components/retriever/volc_vikingdb/examples/builtin_embedding
-
-```go
-import (
-    "github.com/cloudwego/eino/components/retriever"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-
-    "github.com/cloudwego/eino-ext/components/retriever/volc_vikingdb"
-)
-
-collectionName := "eino_test"
-indexName := "test_index_1"
-
-/*
- * 下面示例中提前构建了一个名为 eino_test 的数据集 (collection)，并在此数据集上构建了一个名为 test_index_1 的 hnsw-hybrid 索引 (index)
- * 数据集字段配置为:
- * 字段名称       字段类型         向量维度
- * ID            string
- * vector         vector       1024
- * sparse_vector    sparse_vector
- * content        string
- * extra_field_1    string
- *
- * component 使用时注意:
- * 1. ID / vector / sparse_vector / content 的字段名称与类型与上方配置一致
- * 2. vector 向量维度需要与 ModelName 对应的模型所输出的向量维度一致
- * 3. 部分模型不输出稀疏向量，此时 UseSparse 需要设置为 false，collection 可以不设置 sparse_vector 字段
- */
-
-cfg := &volc_vikingdb.RetrieverConfig{
-    // https://api-vikingdb.volces.com （华北）
-    // https://api-vikingdb.mlp.cn-shanghai.volces.com（华东）
-    // https://api-vikingdb.mlp.ap-mya.byteplus.com（海外-柔佛）
-    Host:              "api-vikingdb.volces.com",
-    Region:            "cn-beijing",
-    AK:                ak,
-    SK:                sk,
-    Scheme:            "https",
-    ConnectionTimeout: 0,
-    Collection:        collectionName,
-    Index:             indexName,
-    EmbeddingConfig: volc_vikingdb.EmbeddingConfig{
-       UseBuiltin:  true,
-       ModelName:   "bge-m3",
-       UseSparse:   true,
-       DenseWeight: 0.4,
-    },
-    Partition:      "", // 对应索引中的【子索引划分字段】, 未设置时至空即可
-    TopK:           of(10),
-    ScoreThreshold: of(0.1),
-    FilterDSL:      nil, // 对应索引中的【标量过滤字段】，未设置时至空即可，表达式详见 https://www.volcengine.com/docs/84313/1254609
-}
-
-volcRetriever, _ := volc_vikingdb.NewRetriever(ctx, cfg)
-
-
-query := "tourist attraction"
-docs, _ := volcRetriever.Retrieve(ctx, query)
-
-log.Printf("vikingDB retrieve success, query=%v, docs=%v", query, docs)
-```
-
-#### Milvus 示例
-
-```go
-import (
-        "github.com/cloudwego/eino-ext/components/retriever/milvus2"
-        "github.com/cloudwego/eino-ext/components/retriever/milvus2/search_mode"
-)
-
-// 创建 retriever
-retriever, err := milvus2.NewRetriever(ctx, &milvus2.RetrieverConfig{
-        ClientConfig: &milvusclient.ClientConfig{
-                Address:  addr,
-                Username: username,
-                Password: password,
-        },
-        Collection: "my_collection",
-        TopK:       10,
-        SearchMode: search_mode.NewApproximate(milvus2.COSINE),
-        Embedding:  emb,
-})
-
-// 检索文档
-documents, err := retriever.Retrieve(ctx, "search query")
-```
-
-#### ElasticSearch 7 示例
-
-```go
-import (
-        "github.com/cloudwego/eino/schema"
-        elasticsearch "github.com/elastic/go-elasticsearch/v7"
-
-        "github.com/cloudwego/eino-ext/components/retriever/es7"
-        "github.com/cloudwego/eino-ext/components/retriever/es7/search_mode"
-)
-
-client, _ := elasticsearch.NewClient(elasticsearch.Config{
-        Addresses: []string{"http://localhost:9200"},
-        Username:  username,
-        Password:  password,
-})
-
-// 创建带有稠密向量相似度搜索的检索器
-retriever, _ := es7.NewRetriever(ctx, &es7.RetrieverConfig{
-        Client:     client,
-        Index:      "my_index",
-        TopK:       10,
-        SearchMode: search_mode.DenseVectorSimilarity(search_mode.DenseVectorSimilarityTypeCosineSimilarity, "content_vector"),
-        Embedding:  emb,
-})
-
-// 检索文档
-docs, _ := retriever.Retrieve(ctx, "search query")
-```
-
-#### OpenSearch 2 示例
-
-```go
-package main
-
-import (
-        "github.com/cloudwego/eino/schema"
-        opensearch "github.com/opensearch-project/opensearch-go/v2"
-
-        "github.com/cloudwego/eino-ext/components/retriever/opensearch2"
-        "github.com/cloudwego/eino-ext/components/retriever/opensearch2/search_mode"
-)
-
-client, err := opensearch.NewClient(opensearch.Config{
-        Addresses: []string{"http://localhost:9200"},
-})
-
-// 创建检索器组件
-retriever, _ := opensearch2.NewRetriever(ctx, &opensearch2.RetrieverConfig{
-        Client: client,
-        Index:  "your_index_name",
-        TopK:   5,
-        // 选择搜索模式
-        SearchMode: search_mode.Approximate(&search_mode.ApproximateConfig{
-                VectorField: "content_vector",
-                K:           5,
-        }),
-        ResultParser: func(ctx context.Context, hit map[string]interface{}) (*schema.Document, error) {
-                // 解析 hit map 为 Document
-                id, _ := hit["_id"].(string)
-                source := hit["_source"].(map[string]interface{})
-                content, _ := source["content"].(string)
-                return &schema.Document{ID: id, Content: content}, nil
-        },
-        Embedding: emb,
-})
-
-// 检索文档
-docs, err := retriever.Retrieve(ctx, "search query")
-```
-
-### **在编排中使用**
-
-```go
-// 在 Chain 中使用
-chain := compose.NewChain[string, []*schema.Document]()
-chain.AppendRetriever(retriever)
-
-// 在 Graph 中使用
-graph := compose.NewGraph[string, []*schema.Document]()
-graph.AddRetrieverNode("retriever_node", retriever)
-```
-
-## **Option 和 Callback 使用**
-
-### **Callback 使用示例**
-
-> 代码位置：eino-ext/components/retriever/volc_vikingdb/examples/builtin_embedding
-
-```go
-import (
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/components/retriever"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-    callbacksHelper "github.com/cloudwego/eino/utils/callbacks"
-    "github.com/cloudwego/eino-ext/components/retriever/volc_vikingdb"
-)
-
-// 创建 callback handler
-handler := &callbacksHelper.RetrieverCallbackHandler{
-    OnStart: func(ctx context.Context, info *callbacks.RunInfo, input *retriever.CallbackInput) context.Context {
-       log.Printf("input access, content: %s\n", input.Query)
-       return ctx
-    },
-    OnEnd: func(ctx context.Context, info *callbacks.RunInfo, output *retriever.CallbackOutput) context.Context {
-       log.Printf("output finished, len: %v\n", len(output.Docs))
-       return ctx
-    },
-    // OnError
-}
-
-// 使用 callback handler
-helper := callbacksHelper.NewHandlerHelper().
-    Retriever(handler).
-    Handler()
-
-chain := compose.NewChain[string, []*schema.Document]()
-chain.AppendRetriever(volcRetriever)
-
-// 在运行时使用
-run, _ := chain.Compile(ctx)
-
-outDocs, _ := run.Invoke(ctx, query, compose.WithCallbacks(helper))
-
-log.Printf("vikingDB retrieve success, query=%v, docs=%v", query, outDocs)
-```
-
-## **已有实现**
-
-- Volc VikingDB Retriever: 基于火山引擎 VikingDB 的检索实现 [Retriever - VikingDB](/zh/docs/eino/ecosystem_integration/retriever/retriever_volc_vikingdb)
-- Milvus v2.5+ Retriever: 基于 Milvus 实现的向量数据库检索器 [Retriever - Milvus 2 (v2.5+) ](/zh/docs/eino/ecosystem_integration/retriever/retriever_milvusv2)
-- Milvus v2.4- Retriever: 基于 Milvus 实现的向量数据库检索器 [Retriever - Milvus (v2.4-)](/zh/docs/eino/ecosystem_integration/retriever/retriever_milvus)
-- Elasticsearch 8 Retriever: 基于 ES8 实现的通用搜索引擎检索器 [Retriever - Elasticsearch 8](/zh/docs/eino/ecosystem_integration/retriever/retriever_es8)
-- ElasticSearch 7 Retriever: 基于 ES7 实现的通用搜索引擎检索器 [Retriever - Elasticsearch 7](/zh/docs/eino/ecosystem_integration/retriever/retriever_elasticsearch7)
-- OpenSearch 3 Retriever: 基于 OpenSearch 3 实现的通用搜索引擎检索器 [Retriever - OpenSearch 3](/zh/docs/eino/ecosystem_integration/retriever/retriever_opensearch3)
-- OpenSearch 2 Retriever: 基于 OpenSearch 2 实现的通用搜索引擎检索器 [Retriever - OpenSearch 2](/zh/docs/eino/ecosystem_integration/retriever/retriever_opensearch2)
-
-## **自行实现参考**
-
-实现自定义的 Retriever 组件时，需要注意以下几点：
-
-1. 注意 option 机制的处理，及处理公共的 option.
-2. 注意处理 callback
-3. 注意需要注入特定的 metadata，以便后续节点使用
-
-### **option 机制**
-
-Retriever 组件提供了一组公共选项，实现时需要正确处理这些选项：
-
-```go
-// 使用 GetCommonOptions 处理公共 option
-func (r *MyRetriever) Retrieve(ctx context.Context, query string, opts ...retriever.Option) ([]*schema.Document, error) {
-    // 1. 初始化及读取 option
-    options := &retriever.Options{ // 可设置default值
-        Index: &r.index,
-        TopK: &r.topK,
-        Embedding: r.embedder,
-    }
-    options = retriever.GetCommonOptions(options, opts...)
-    
-    // ...
-}
-```
-
-### **Callback 处理**
-
-Retriever 实现需要在适当的时机触发回调，以下结构体是 retriever 组件定义好的结构：
-
-```go
-// 定义回调输入输出
-type CallbackInput struct {
-    Query string
-    TopK int
-    Filter string
-    ScoreThreshold *float64
-    Extra map[string]any
-}
-
-type CallbackOutput struct {
-    Docs []*schema.Document
-    Extra map[string]any
-}
-```
-
-### **完整实现示例**
-
-```go
-type MyRetriever struct {
-    embedder embedding.Embedder
-    index string
-    topK int
-}
-
-func NewMyRetriever(config *MyRetrieverConfig) (*MyRetriever, error) {
-    return &MyRetriever{
-        embedder: config.Embedder,
-        index: config.Index,
-        topK: config.DefaultTopK,
-    }, nil
-}
-
-func (r *MyRetriever) Retrieve(ctx context.Context, query string, opts ...retriever.Option) ([]*schema.Document, error) {
-    // 1. 处理选项
-    options := &retriever.Options{
-        Index: &r.index,
-        TopK: &r.topK,
-        Embedding: r.embedder,
-    }
-    options = retriever.GetCommonOptions(options, opts...)
-    
-    // 2. 获取 callback manager
-    cm := callbacks.ManagerFromContext(ctx)
-    
-    // 3. 开始检索前的回调
-    ctx = cm.OnStart(ctx, info, &retriever.CallbackInput{
-        Query: query,
-        TopK: *options.TopK,
-    })
-    
-    // 4. 执行检索逻辑
-    docs, err := r.doRetrieve(ctx, query, options)
-    
-    // 5. 处理错误和完成回调
-    if err != nil {
-        ctx = cm.OnError(ctx, info, err)
-        return nil, err
-    }
-    
-    ctx = cm.OnEnd(ctx, info, &retriever.CallbackOutput{
-        Docs: docs,
-    })
-    
-    return docs, nil
-}
-
-func (r *MyRetriever) doRetrieve(ctx context.Context, query string, opts *retriever.Options) ([]*schema.Document, error) {
-    // 1. 如果设置了 Embedding，生成查询的向量表示 (注意公共option的逻辑处理)
-    var queryVector []float64
-    if opts.Embedding != nil {
-        vectors, err := opts.Embedding.EmbedStrings(ctx, []string{query})
-        if err != nil {
-            return nil, err
-        }
-        queryVector = vectors[0]
-    }
-    
-    // 2. 其他逻辑
-    return docs, nil
-}
-```

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

@@ -1,717 +0,0 @@
----
-Description: ""
-date: "2026-03-03"
-lastmod: ""
-tags: []
-title: ToolsNode&Tool 使用说明
-weight: 9
----
-
-## **基本介绍**
-
-`Tool` 在 eino 框架中的定义是“ChatModel 能够选择调用的外部能力”，包括本地函数，MCP server tool 等。
-
-`ToolsNode` 是 eino 框架指定的”Tool 执行器“，无论是 Graph 内还是 Agent 中，Tool 的执行都要通过 ToolsNode：
-
-```go
-// compose/tool_node.go
-
-// run tools using `Invoke`
-func (tn *ToolsNode) Invoke(ctx context.Context, input *schema.Message,
-    opts ...ToolsNodeOption) ([]*schema.Message, error)
-    
-// run tools using `Stream`
-func (tn *ToolsNode) Stream(ctx context.Context, input *schema.Message,
-    opts ...ToolsNodeOption) (*schema.StreamReader[[]*schema.Message], error)
-```
-
-给 ToolsNode 配置一个 Tool 列表以及一些配套策略：
-
-```go
-// compose/tool_node.go
-
-type ToolsNodeConfig struct {
-    Tools []tool.BaseTool
-
-    UnknownToolsHandler func(ctx context.Context, name, input string) (string, error)
-
-    ExecuteSequentially bool
-
-    ToolArgumentsHandler func(ctx context.Context, name, arguments string) (string, error)
-
-    ToolCallMiddlewares []ToolMiddleware
-}
-```
-
-这样 ToolsNode 就“能够执行配置的 Tool”，并获得一些扩展能力，如执行时序、异常处理、入参处理、middleware 扩展等。
-
-ToolsNode 如何“决策”应该执行哪个 Tool？它不决策，而是依据输入的 `*schema.Message` 来执行：
-
-```go
-// schema/message.go
-
-type Message struct {
-    // role should be 'assistant' for tool call message
-    Role RoleType `json:"role"`
-
-    // here each `ToolCall` is generated by ChatModel and to be executed by ToolsNode
-    ToolCalls []ToolCall `json:"tool_calls,omitempty"`
-    
-    // other fields...
-}
-
-// ToolCall is the tool call in a message.
-// It's used in Assistant Message when there are tool calls should be made.
-type ToolCall struct {
-    // Index is used when there are multiple tool calls in a message.
-    // In stream mode, it's used to identify the chunk of the tool call for merging.
-    Index *int `json:"index,omitempty"`
-    // ID is the id of the tool call, it can be used to identify the specific tool call.
-    ID string `json:"id"`
-    // Type is the type of the tool call, default is "function".
-    Type string `json:"type"`
-    // Function is the function call to be made.
-    Function FunctionCall `json:"function"`
-
-    // Extra is used to store extra information for the tool call.
-    Extra map[string]any `json:"extra,omitempty"`
-}
-
-// FunctionCall is the function call in a message.
-// It's used in Assistant Message.
-type FunctionCall struct {
-    // Name is the name of the function to call, it can be used to identify the specific function.
-    Name string `json:"name,omitempty"`
-    // Arguments is the arguments to call the function with, in JSON format.
-    Arguments string `json:"arguments,omitempty"`
-}
-```
-
-ChatModel(LLM) 生成要调用的 []ToolCall（包含 ToolName，Argument 等），放到 *schema.Message 中传给 ToolsNode。ToolsNode 针对每个 ToolCall 实际执行一次调用。
-
-如果配置了 ExecuteSequentially，则 ToolsNode 会按照 []ToolCall 中的先后顺序来执行工具。
-
-每个 ToolCall 调用完成后的结果，又会封装为 *schema.Message，作为 ToolsNode 输出的一部分。
-
-## Tool 定义
-
-### **接口定义**
-
-Tool 组件提供了两类接口：**标准工具接口**和**增强型工具接口**。
-
-> 代码位置：eino/components/tool/interface.go
-
-#### **标准工具接口**
-
-标准工具接口返回字符串类型的结果：
-
-```go
-// 基础工具接口，提供工具信息
-type BaseTool interface {
-    Info(ctx context.Context) (*schema.ToolInfo, error)
-}
-
-// 可调用的工具接口，支持同步调用
-type InvokableTool interface {
-    BaseTool
-    InvokableRun(ctx context.Context, argumentsInJSON string, opts ...Option) (string, error)
-}
-
-// 支持流式输出的工具接口
-type StreamableTool interface {
-    BaseTool
-    StreamableRun(ctx context.Context, argumentsInJSON string, opts ...Option) (*schema.StreamReader[string], error)
-}
-```
-
-#### **增强型工具接口（Enhanced Tool）**
-
-增强型工具接口支持返回结构化的多模态结果（`*schema.ToolResult`），可以包含文本、图片、音频、视频和文件等多种类型的内容：
-
-```go
-// EnhancedInvokableTool 是支持返回结构化多模态结果的工具接口
-// 与返回字符串的 InvokableTool 不同，此接口返回 *schema.ToolResult
-// 可以包含文本、图片、音频、视频和文件
-type EnhancedInvokableTool interface {
-    BaseTool
-    InvokableRun(ctx context.Context, toolArgument *schema.ToolArgument, opts ...Option) (*schema.ToolResult, error)
-}
-
-// EnhancedStreamableTool 是支持返回结构化多模态结果的流式工具接口
-// 提供流式读取器以逐步访问多模态内容
-type EnhancedStreamableTool interface {
-    BaseTool
-    StreamableRun(ctx context.Context, toolArgument *schema.ToolArgument, opts ...Option) (*schema.StreamReader[*schema.ToolResult], error)
-}
-```
-
-### **增强型工具相关数据结构**
-
-> 代码位置：eino/schema/message.go
-
-#### **ToolArgument - 工具输入参数**
-
-```go
-// ToolArgument 包含工具调用的输入信息
-type ToolArgument struct {
-    // TextArgument 包含 JSON 格式的工具调用参数
-    TextArgument string
-}
-```
-
-#### **ToolResult - 工具输出结果**
-
-```go
-// ToolResult 表示工具执行的结构化多模态输出
-// 当工具需要返回不仅仅是简单字符串时使用，
-// 例如图片、文件或其他结构化数据
-type ToolResult struct {
-    // Parts 包含多模态输出部分。每个部分可以是不同类型的内容，
-    // 如文本、图片或文件
-    Parts []ToolOutputPart `json:"parts,omitempty"`
-}
-```
-
-#### **ToolOutputPart - 输出内容部分**
-
-```go
-// ToolPartType 定义工具输出部分的内容类型
-type ToolPartType string
-
-const (
-    ToolPartTypeText  ToolPartType = "text"   // 文本
-    ToolPartTypeImage ToolPartType = "image"  // 图片
-    ToolPartTypeAudio ToolPartType = "audio"  // 音频
-    ToolPartTypeVideo ToolPartType = "video"  // 视频
-    ToolPartTypeFile  ToolPartType = "file"   // 文件
-)
-
-// ToolOutputPart 表示工具执行输出的一部分
-type ToolOutputPart struct {
-    Type  ToolPartType     `json:"type"`            // 内容类型
-    Text  string           `json:"text,omitempty"`  // 文本内容
-    Image *ToolOutputImage `json:"image,omitempty"` // 图片内容
-    Audio *ToolOutputAudio `json:"audio,omitempty"` // 音频内容
-    Video *ToolOutputVideo `json:"video,omitempty"` // 视频内容
-    File  *ToolOutputFile  `json:"file,omitempty"`  // 文件内容
-    Extra map[string]any   `json:"extra,omitempty"` // 扩展信息
-}
-
-// 多媒体内容结构体，都包含 URL 或 Base64 数据以及 MIME 类型信息
-type ToolOutputImage struct { MessagePartCommon }
-type ToolOutputAudio struct { MessagePartCommon }
-type ToolOutputVideo struct { MessagePartCommon }
-type ToolOutputFile  struct { MessagePartCommon }
-```
-
-### **方法说明**
-
-#### **Info 方法**
-
-- 功能：获取工具的描述信息
-- 参数：
-  - ctx：上下文对象
-- 返回值：
-  - `*schema.ToolInfo`：工具的描述信息
-  - error：获取信息过程中的错误
-
-#### **InvokableRun 方法（标准工具）**
-
-- 功能：同步执行工具
-- 参数：
-  - ctx：上下文对象，用于传递请求级别的信息，同时也用于传递 Callback Manager
-  - `argumentsInJSON`：JSON 格式的参数字符串
-  - opts：工具执行的选项
-- 返回值：
-  - string：执行结果
-  - error：执行过程中的错误
-
-#### **InvokableRun 方法（增强型工具）**
-
-- 功能：同步执行工具，返回多模态结果
-- 参数：
-  - ctx：上下文对象
-  - `toolArgument`：包含 JSON 格式参数的 `*schema.ToolArgument`
-  - opts：工具执行的选项
-- 返回值：
-  - `*schema.ToolResult`：包含多模态内容的执行结果
-  - error：执行过程中的错误
-
-#### **StreamableRun 方法（标准工具）**
-
-- 功能：以流式方式执行工具
-- 参数：
-  - ctx：上下文对象
-  - `argumentsInJSON`：JSON 格式的参数字符串
-  - opts：工具执行的选项
-- 返回值：
-  - `*schema.StreamReader[string]`：流式执行结果
-  - error：执行过程中的错误
-
-#### **StreamableRun 方法（增强型工具）**
-
-- 功能：以流式方式执行工具，返回多模态结果流
-- 参数：
-  - ctx：上下文对象
-  - `toolArgument`：包含 JSON 格式参数的 `*schema.ToolArgument`
-  - opts：工具执行的选项
-- 返回值：
-  - `*schema.StreamReader[*schema.ToolResult]`：流式多模态执行结果
-  - error：执行过程中的错误
-
-### **ToolInfo 结构体**
-
-> 代码位置：eino/schema/tool.go
-
-```go
-type ToolInfo struct {
-    // 工具的唯一名称，用于清晰地表达其用途
-    Name string
-    // 用于告诉模型如何/何时/为什么使用这个工具
-    // 可以在描述中包含少量示例
-    Desc string
-    // 工具接受的参数定义
-    // 可以通过两种方式描述：
-    // 1. 使用 ParameterInfo：schema.NewParamsOneOfByParams(params)
-    // 2. 使用 OpenAPIV3：schema.NewParamsOneOfByOpenAPIV3(openAPIV3)
-    *ParamsOneOf
-}
-```
-
-### **公共 Option**
-
-Tool 组件使用 ToolOption 来定义可选参数， ToolsNode 没有抽象公共的 option。每个具体的实现可以定义自己的特定 Option，通过 WrapToolImplSpecificOptFn 函数包装成统一的 ToolOption 类型。
-
-## **使用方式**
-
-### **标准工具使用**
-
-```go
-import (
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-)
-
-// 创建工具节点
-toolsNode := compose.NewToolNode([]tool.Tool{
-    searchTool,    // 搜索工具
-    weatherTool,   // 天气查询工具
-    calculatorTool, // 计算器工具
-})
-
-// Mock LLM 输出作为输入
-input := &schema.Message{
-    Role: schema.Assistant,
-    ToolCalls: []schema.ToolCall{
-       {
-          Function: schema.FunctionCall{
-             Name:      "weather",
-             Arguments: `{"city": "深圳", "date": "tomorrow"}`,
-          },
-       },
-    },
-}
-
-toolMessages, err := toolsNode.Invoke(ctx, input)
-```
-
-### **增强型工具使用**
-
-增强型工具适用于需要返回多模态内容的场景，如返回图片、音频、视频或文件等。
-
-#### **方式一：使用 InferEnhancedTool 自动推断**
-
-```go
-import (
-    "context"
-    
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/schema"
-)
-
-// 定义输入参数结构体
-type ImageSearchInput struct {
-    Query string `json:"query" jsonschema:"description=搜索关键词"`
-}
-
-// 创建增强型工具
-imageSearchTool, err := utils.InferEnhancedTool(
-    "image_search",
-    "搜索并返回相关图片",
-    func(ctx context.Context, input *ImageSearchInput) (*schema.ToolResult, error) {
-        // 执行图片搜索逻辑...
-        imageURL := "https://example.com/image.png"
-        
-        return &schema.ToolResult{
-            Parts: []schema.ToolOutputPart{
-                {Type: schema.ToolPartTypeText, Text: "找到以下图片："},
-                {
-                    Type: schema.ToolPartTypeImage,
-                    Image: &schema.ToolOutputImage{
-                        MessagePartCommon: schema.MessagePartCommon{
-                            URL: &imageURL,
-                        },
-                    },
-                },
-            },
-        }, nil
-    },
-)
-```
-
-#### **方式二：使用 NewEnhancedTool 手动创建**
-
-```go
-import (
-    "context"
-    
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/schema"
-)
-
-type FileGeneratorInput struct {
-    FileName string `json:"file_name"`
-    Content  string `json:"content"`
-}
-
-// 手动定义 ToolInfo
-toolInfo := &schema.ToolInfo{
-    Name: "file_generator",
-    Desc: "生成并返回文件",
-    ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{
-        "file_name": {Type: "string", Desc: "文件名"},
-        "content":   {Type: "string", Desc: "文件内容"},
-    }),
-}
-
-// 创建增强型工具
-fileGenTool := utils.NewEnhancedTool[*FileGeneratorInput](
-    toolInfo,
-    func(ctx context.Context, input *FileGeneratorInput) (*schema.ToolResult, error) {
-        fileURL := "https://example.com/files/" + input.FileName
-        
-        return &schema.ToolResult{
-            Parts: []schema.ToolOutputPart{
-                {Type: schema.ToolPartTypeText, Text: "文件已生成：" + input.FileName},
-                {
-                    Type: schema.ToolPartTypeFile,
-                    File: &schema.ToolOutputFile{
-                        MessagePartCommon: schema.MessagePartCommon{
-                            URL:      &fileURL,
-                            MIMEType: "text/plain",
-                        },
-                    },
-                },
-            },
-        }, nil
-    },
-)
-```
-
-#### **方式三：实现 EnhancedInvokableTool 接口**
-
-```go
-import (
-    "context"
-    
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/schema"
-)
-
-type MyEnhancedTool struct {
-    info *schema.ToolInfo
-}
-
-func (t *MyEnhancedTool) Info(ctx context.Context) (*schema.ToolInfo, error) {
-    return t.info, nil
-}
-
-func (t *MyEnhancedTool) InvokableRun(ctx context.Context, toolArgument *schema.ToolArgument, opts ...tool.Option) (*schema.ToolResult, error) {
-    // 解析参数
-    // toolArgument.TextArgument 包含 JSON 格式的参数
-    
-    // 执行工具逻辑...
-    
-    return &schema.ToolResult{
-        Parts: []schema.ToolOutputPart{
-            {Type: schema.ToolPartTypeText, Text: "执行结果"},
-        },
-    }, nil
-}
-```
-
-#### **增强型流式工具**
-
-```go
-import (
-    "context"
-    
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/schema"
-)
-
-type StreamInput struct {
-    Query string `json:"query"`
-}
-
-// 创建增强型流式工具
-streamTool, err := utils.InferEnhancedStreamTool(
-    "stream_search",
-    "流式搜索工具",
-    func(ctx context.Context, input *StreamInput) (*schema.StreamReader[*schema.ToolResult], error) {
-        results := []*schema.ToolResult{
-            {Parts: []schema.ToolOutputPart{{Type: schema.ToolPartTypeText, Text: "搜索中..."}}},
-            {Parts: []schema.ToolOutputPart{{Type: schema.ToolPartTypeText, Text: "找到结果"}}},
-        }
-        return schema.StreamReaderFromArray(results), nil
-    },
-)
-```
-
-### **在编排中使用**
-
-```go
-import (
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-)
-
-// 创建工具节点
-toolsNode, _ := compose.NewToolNode(ctx, &compose.ToolsNodeConfig{
-       Tools: []tool.BaseTool{
-          searchTool,     // 搜索工具
-          weatherTool,    // 天气查询工具
-          calculatorTool, // 计算器工具
-       },
-    })
-
-// 在 Chain 中使用
-chain := compose.NewChain[*schema.Message, []*schema.Message]()
-chain.AppendToolsNode(toolsNode)
-
-// graph 中
-graph := compose.NewGraph[*schema.Message, []*schema.Message]()
-graph.AddToolsNode("tools", toolsNode)
-```
-
-> **注意**：当工具同时实现了标准接口和增强型接口时，ToolsNode 会优先使用增强型接口。
-
-## **Option 机制**
-
-自定义 Tool 可根据自己需要实现特定的 Option：
-
-```go
-import "github.com/cloudwego/eino/components/tool"
-
-// 定义 Option 结构体
-type MyToolOptions struct {
-    Timeout time.Duration
-    MaxRetries int
-    RetryInterval time.Duration
-}
-
-// 定义 Option 函数
-func WithTimeout(timeout time.Duration) tool.Option {
-    return tool.WrapImplSpecificOptFn(func(o *MyToolOptions) {
-        o.Timeout = timeout
-    })
-}
-```
-
-## **Middleware 机制**
-
-ToolsNode 支持通过 Middleware 对工具调用进行拦截和增强。Middleware 分为四种类型：
-
-```go
-// compose/tool_node.go
-
-// ToolMiddleware 组合了 invokable 和 streamable 工具调用的中间件钩子
-type ToolMiddleware struct {
-    // Invokable 用于非流式标准工具调用
-    Invokable InvokableToolMiddleware
-    
-    // Streamable 用于流式标准工具调用
-    Streamable StreamableToolMiddleware
-    
-    // EnhancedInvokable 用于非流式增强型工具调用
-    EnhancedInvokable EnhancedInvokableToolMiddleware
-    
-    // EnhancedStreamable 用于流式增强型工具调用
-    EnhancedStreamable EnhancedStreamableToolMiddleware
-}
-```
-
-### **Middleware 使用示例**
-
-```go
-import (
-    "context"
-    "fmt"
-    
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-)
-
-// 创建带 Middleware 的 ToolsNode
-toolsNode, err := compose.NewToolNode(ctx, &compose.ToolsNodeConfig{
-    Tools: []tool.BaseTool{myEnhancedTool},
-    ToolCallMiddlewares: []compose.ToolMiddleware{
-        {
-            // 标准工具中间件
-            Invokable: func(next compose.InvokableToolEndpoint) compose.InvokableToolEndpoint {
-                return func(ctx context.Context, input *compose.ToolInput) (*compose.ToolOutput, error) {
-                    fmt.Printf("调用标准工具: %s\n", input.Name)
-                    return next(ctx, input)
-                }
-            },
-            // 增强型工具中间件
-            EnhancedInvokable: func(next compose.EnhancedInvokableToolEndpoint) compose.EnhancedInvokableToolEndpoint {
-                return func(ctx context.Context, input *compose.ToolInput) (*compose.EnhancedInvokableToolOutput, error) {
-                    fmt.Printf("调用增强型工具: %s\n", input.Name)
-                    output, err := next(ctx, input)
-                    if err != nil {
-                        return nil, err
-                    }
-                    fmt.Printf("增强型工具返回 %d 个内容部分\n", len(output.Result.Parts))
-                    return output, nil
-                }
-            },
-        },
-    },
-})
-```
-
-## **Option 和 Callback 使用**
-
-### **Callback 使用示例**
-
-```go
-import (
-    "context"
-
-    callbackHelper "github.com/cloudwego/eino/utils/callbacks"
-    "github.com/cloudwego/eino/callbacks"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/components/tool"
-)
-
-// 创建 callback handler
-handler := &callbackHelper.ToolCallbackHandler{
-    OnStart: func(ctx context.Context, info *callbacks.RunInfo, input *tool.CallbackInput) context.Context {
-       fmt.Printf("开始执行工具，参数: %s\n", input.ArgumentsInJSON)
-       return ctx
-    },
-    OnEnd: func(ctx context.Context, info *callbacks.RunInfo, output *tool.CallbackOutput) context.Context {
-       fmt.Printf("工具执行完成，结果: %s\n", output.Response)
-       return ctx
-    },
-    OnEndWithStreamOutput: func(ctx context.Context, info *callbacks.RunInfo, output *schema.StreamReader[*tool.CallbackOutput]) context.Context {
-       fmt.Println("工具开始流式输出")
-       go func() {
-          defer output.Close()
-
-          for {
-             chunk, err := output.Recv()
-             if errors.Is(err, io.EOF) {
-                return
-             }
-             if err != nil {
-                return
-             }
-             fmt.Printf("收到流式输出: %s\n", chunk.Response)
-          }
-       }()
-       return ctx
-    },
-}
-
-// 使用 callback handler
-helper := callbackHelper.NewHandlerHelper().
-    Tool(handler).
-    Handler()
- 
-/*** compose a chain
-* chain := NewChain
-* chain.appendxxx().
-*       appendxxx().
-*       ...
-*/
-
-// 在运行时使用
-runnable, err := chain.Compile()
-if err != nil {
-    return err
-}
-result, err := runnable.Invoke(ctx, input, compose.WithCallbacks(helper))
-```
-
-## 如何获取 ToolCallID
-
-在 tool 函数体、tool callback handler 中，都可以通过 `compose.GetToolCallID(ctx)` 函数获取当前 Tool 的 ToolCallID。
-
-## **已有实现**
-
-1. Google Search Tool: 基于 Google 搜索的工具实现 [Tool - Googlesearch](/zh/docs/eino/ecosystem_integration/tool/tool_googlesearch)
-2. duckduckgo search tool: 基于 duckduckgo 搜索的工具实现 [Tool - DuckDuckGoSearch](/zh/docs/eino/ecosystem_integration/tool/tool_duckduckgo_search)
-3. MCP: 把 mcp server 作为 tool[Tool - MCP](/zh/docs/eino/ecosystem_integration/tool/tool_mcp)
-
-### v0.5.x->0.6.x
-
-鉴于以下两点考虑：
-
-1. 各大模型厂商 API、MCP Tool 协议约定使用 JSONSchema 来描述工具 input/output schema。
-2. Eino 引用的 getkin/kin-openapi@v0.118.0 有安全问题，且 kin-openapi 安全版本有不兼容更新。
-
-Eino 移除了 OpenAPI schema 3.0 相关的所有定义与方法，转为使用 JSONSchema 2020-12。具体移除及增加的定义与方法详见 [https://github.com/cloudwego/eino/discussions/397](https://github.com/cloudwego/eino/discussions/397) 。
-
-升级后，部分 eino-ext module 可能报错“_undefined: schema.NewParamsOneOfByOpenAPIV3_”等问题，升级报错的 eino-ext module 到最新版本即可。
-
-如果 schema 改造比较复杂，可以使用  [https://github.com/cloudwego/eino/discussions/397](https://github.com/cloudwego/eino/discussions/397) 中提供的工具方法辅助转换。
-
-### **v0.6.x 新增增强型工具（Enhanced Tool）**
-
-新增 `EnhancedInvokableTool` 和 `EnhancedStreamableTool` 接口，支持返回结构化的多模态结果。
-
-**主要变更：**
-
-1. **新增工具接口**：
-
-- `EnhancedInvokableTool`：接收 `*schema.ToolArgument`，返回 `*schema.ToolResult`
-- `EnhancedStreamableTool`：接收 `*schema.ToolArgument`，返回 `*schema.StreamReader[*schema.ToolResult]`
-
-1. **新增工具辅助函数**（`components/tool/utils/`）：
-
-- `InferEnhancedTool`：从函数自动推断创建增强型工具
-- `InferEnhancedStreamTool`：从函数自动推断创建增强型流式工具
-- `NewEnhancedTool`：手动创建增强型工具
-- `NewEnhancedStreamTool`：手动创建增强型流式工具
-
-1. **新增数据结构**（`schema/message.go`）：
-
-- `ToolPartType`：工具输出内容类型枚举（text、image、audio、video、file）
-- `ToolArgument`：工具输入参数结构体
-- `ToolResult`：工具多模态输出结果结构体
-- `ToolOutputPart`：工具输出内容部分
-- `ToolOutputImage/Audio/Video/File`：各类多媒体输出结构体
-
-1. **ToolsNode 增强**：
-
-- 新增 `EnhancedInvokableToolMiddleware` 和 `EnhancedStreamableToolMiddleware`
-- 支持增强型工具和标准工具混合使用
-- 当工具同时实现两种接口时，优先使用增强型接口
-
-1. **Callback 增强**：
-
-- `CallbackOutput` 新增 `ToolOutput *schema.ToolResult` 字段，用于增强型工具的多模态输出
-
-**使用场景：**
-
-增强型工具适用于需要返回富媒体内容的场景，例如：
-
-- 图片搜索工具返回搜索到的图片
-- 文件生成工具返回生成的文件
-- 音视频处理工具返回处理后的媒体文件
-- 多模态 AI Agent 场景

docs/Eino/docs/core_modules/components/tools_node_guide/how_to_create_a_tool.md

@@ -1,680 +0,0 @@
----
-Description: ""
-date: "2026-03-03"
-lastmod: ""
-tags: []
-title: 如何创建一个 tool ?
-weight: 1
----
-
-## **Tool 的基本结构**
-
-一个 agent 要调用 tool，需要有两步：① 大模型根据 tool 的功能和参数需求构建调用参数 ② 实际调用 tool
-
-这两个基本步骤也就要求了 tool 需要包含两个部分：
-
-- tool 的功能介绍和调用这个 tool 所需要的参数信息
-- 调用这个 tool 的接口
-
-在 Eino 中，BaseTool 接口要求任何一个 tool 都要有 Info() 接口返回 tool 信息，如下：
-
-```go
-type BaseTool interface {
-    Info(ctx context.Context) (*schema.ToolInfo, error)
-}
-```
-
-### **标准工具接口**
-
-根据一个 tool 被调用后的返回结构是否是流式的，可以分为 InvokableTool 和 StreamableTool，也同样是以接口方式定义：
-
-```go
-type InvokableTool interface {
-    BaseTool
-
-    // InvokableRun call function with arguments in JSON format
-    InvokableRun(ctx context.Context, argumentsInJSON string, opts ...Option) (string, error)
-}
-
-type StreamableTool interface {
-    BaseTool
-
-    StreamableRun(ctx context.Context, argumentsInJSON string, opts ...Option) (*schema.StreamReader[string], error)
-}
-```
-
-### **增强型工具接口（Enhanced Tool）**
-
-除了标准工具接口外，Eino 还提供了增强型工具接口，支持返回结构化的多模态结果。增强型工具适用于需要返回图片、音频、视频、文件等富媒体内容的场景：
-
-```go
-// EnhancedInvokableTool 是支持返回结构化多模态结果的工具接口
-// 与返回字符串的 InvokableTool 不同，此接口返回 *schema.ToolResult
-// 可以包含文本、图片、音频、视频和文件
-type EnhancedInvokableTool interface {
-    BaseTool
-    InvokableRun(ctx context.Context, toolArgument *schema.ToolArgument, opts ...Option) (*schema.ToolResult, error)
-}
-
-// EnhancedStreamableTool 是支持返回结构化多模态结果的流式工具接口
-type EnhancedStreamableTool interface {
-    BaseTool
-    StreamableRun(ctx context.Context, toolArgument *schema.ToolArgument, opts ...Option) (*schema.StreamReader[*schema.ToolResult], error)
-}
-```
-
-#### **增强型工具相关数据结构**
-
-```go
-// ToolArgument 包含工具调用的输入信息
-type ToolArgument struct {
-    TextArgument string  // JSON 格式的工具调用参数
-}
-
-// ToolResult 表示工具执行的结构化多模态输出
-type ToolResult struct {
-    Parts []ToolOutputPart `json:"parts,omitempty"`
-}
-
-// ToolPartType 定义工具输出部分的内容类型
-type ToolPartType string
-
-const (
-    ToolPartTypeText  ToolPartType = "text"   // 文本
-    ToolPartTypeImage ToolPartType = "image"  // 图片
-    ToolPartTypeAudio ToolPartType = "audio"  // 音频
-    ToolPartTypeVideo ToolPartType = "video"  // 视频
-    ToolPartTypeFile  ToolPartType = "file"   // 文件
-)
-
-// ToolOutputPart 表示工具执行输出的一部分
-type ToolOutputPart struct {
-    Type  ToolPartType     `json:"type"`
-    Text  string           `json:"text,omitempty"`
-    Image *ToolOutputImage `json:"image,omitempty"`
-    Audio *ToolOutputAudio `json:"audio,omitempty"`
-    Video *ToolOutputVideo `json:"video,omitempty"`
-    File  *ToolOutputFile  `json:"file,omitempty"`
-    Extra map[string]any   `json:"extra,omitempty"`
-}
-```
-
-## **ToolInfo 的表示方式**
-
-在大模型的 function call 调用过程中，由大模型生成需要调用的 function call 的参数，这就要求大模型能理解生成的参数是否符合约束。在 Eino 中，根据开发者的使用习惯和领域标准两方面因素，提供了 `params map[string]*ParameterInfo` 和 `*jsonschema.Schema` 两种参数约束的表达方式。
-
-### **方式 1 - map[string]*ParameterInfo**
-
-在很多开发者的直观习惯中，对于参数的描述方式可以用一个 map 来表示，key 即为参数名，value 则是这个参数的详细约束。Eino 中定义了 ParameterInfo 来表示一个参数的描述，如下：
-
-```go
-// 结构定义详见: https://github.com/cloudwego/eino/blob/main/schema/tool.go
-type ParameterInfo struct {
-    Type DataType    // The type of the parameter.
-    ElemInfo *ParameterInfo    // The element type of the parameter, only for array.
-    SubParams map[string]*ParameterInfo    // The sub parameters of the parameter, only for object.
-    Desc string    // The description of the parameter.
-    Enum []string    // The enum values of the parameter, only for string.
-    Required bool    // Whether the parameter is required.
-}
-```
-
-比如，一个表示 User 的参数可以表示为：
-
-```go
-map[string]*schema.ParameterInfo{
-    "name": &schema.ParameterInfo{
-        Type: schema.String,
-        Required: true,
-    },
-    "age": &schema.ParameterInfo{
-        Type: schema.Integer,
-    },
-    "gender": &schema.ParameterInfo{
-        Type: schema.String,   
-        Enum: []string{"male", "female"},
-    },
-}
-```
-
-这样的表示方式非常简单直观，当参数由开发者通过编码的方式手动维护时常用。
-
-### **方式 2 - JSON Schema**
-
-另一种常用于表示参数约束的方式是 JSON Schema（[https://json-schema.org/draft/2020-12](https://json-schema.org/draft/2020-12%EF%BC%89%E3%80%82)[）。](https://json-schema.org/draft/2020-12%EF%BC%89%E3%80%82)
-
-JSON Schema 的标准中对参数的约束方式非常丰富。在实际的使用中，一般不由开发者自行构建此结构体，而是使用一些方法来生成。
-
-#### **使用 GoStruct2ParamsOneOf 生成**
-
-Eino 提供了在结构体中通过 go tag 描述参数约束的方式，并提供了 GoStruct2ParamsOneOf 方法来生成一个 struct 的参数约束，其函数签名如下：
-
-```go
-func GoStruct2ParamsOneOf[T any](opts ...Option) (*schema.ParamsOneOf, error)
-```
-
-其中从 T 中提取参数的字段名称和描述，提取时所用的 Tag 如下：
-
-- `jsonschema_description:"xxx"` [推荐] 或者 `jsonschema:"description=xxx"`
-  - description 中一般会有逗号，且 tag 中逗号是不同字段的分隔符，且不可被转义，强烈推荐使用 jsonschema_description 这个单独的 Tag 标签
-- `jsonschema:"enum=xxx,enum=yyy,enum=zzz"`
-- `jsonschema:"required"`
-- `json:"xxx,omitempty"` => 可用 json tag 的 omitempty 代表非 required
-
-使用 `utils.WithSchemaModifier` 实现自定义的解析方法，可参考如下例子：
-
-```go
-package main
-
-import (
-    "context"
-    "github.com/cloudwego/eino/components/tool/utils"
-)
-
-type User struct {
-    Name   string `json:"name" jsonschema_description:"the name of the user" jsonschema:"required"`
-    Age    int    `json:"age" jsonschema_description:"the age of the user"`
-    Gender string `json:"gender" jsonschema:"enum=male,enum=female"`
-}
-
-func main() {
-    params, err := utils.GoStruct2ParamsOneOf[User]()
-}
-```
-
-这个方法一般不由开发者调用，往往直接使用 `utils.GoStruct2ToolInfo()` 来构建 ToolInfo，或者直接用 `utils.InferTool()` 直接构建 tool，可详见下方把 "本地函数转为 tool" 部分。
-
-## **实现 Tool 的方式**
-
-### **方式 1 - 直接实现接口**
-
-由于 tool 的定义都是接口，因此最直接实现一个 tool 的方式即实现接口。
-
-#### **实现标准工具接口**
-
-以 InvokableTool 为例：
-
-```go
-type AddUser struct{}
-
-func (t *AddUser) Info(_ context.Context) (*schema.ToolInfo, error) {
-    return &schema.ToolInfo{
-        Name: "add_user",
-        Desc: "add user",
-        ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{
-            // omit，参考上文中构建 params 约束的方式
-        }),
-    }, nil
-}
-
-func (t *AddUser) InvokableRun(_ context.Context, argumentsInJSON string, _ ...tool.Option) (string, error) {
-    input := &AddUser{}
-    // 1. 反序列化 argumentsInJSON，处理 option 等
-    err := json.Unmarshal([]byte(argumentsInJSON), input)
-    // 2. 处理业务逻辑
-    // 3. 把结果序列化为 string 并返回
-
-    return `{"msg": "ok"}`, nil
-}
-```
-
-由于大模型给出的 function call 参数始终是一个 string，对应到 Eino 框架中，tool 的调用参数入参也就是一个序列化成 string 的 json。因此，这种方式需要开发者自行处理参数的反序列化，并且调用的结果也用 string 的方式返回。
-
-#### **实现增强型工具接口**
-
-当需要返回多模态内容（如图片、音频、视频、文件等）时，可以实现 EnhancedInvokableTool 接口：
-
-```go
-type ImageSearchTool struct{}
-
-func (t *ImageSearchTool) Info(_ context.Context) (*schema.ToolInfo, error) {
-    return &schema.ToolInfo{
-        Name: "image_search",
-        Desc: "搜索并返回相关图片",
-        ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{
-            "query": {
-                Type:     schema.String,
-                Desc:     "搜索关键词",
-                Required: true,
-            },
-        }),
-    }, nil
-}
-
-func (t *ImageSearchTool) InvokableRun(_ context.Context, toolArgument *schema.ToolArgument, _ ...tool.Option) (*schema.ToolResult, error) {
-    // 1. 解析参数（toolArgument.TextArgument 包含 JSON 格式的参数）
-    var input struct {
-        Query string `json:"query"`
-    }
-    json.Unmarshal([]byte(toolArgument.TextArgument), &input)
-    
-    // 2. 执行搜索逻辑...
-    imageURL := "https://example.com/image.png"
-    
-    // 3. 返回多模态结果
-    return &schema.ToolResult{
-        Parts: []schema.ToolOutputPart{
-            {Type: schema.ToolPartTypeText, Text: "找到以下图片："},
-            {
-                Type: schema.ToolPartTypeImage,
-                Image: &schema.ToolOutputImage{
-                    MessagePartCommon: schema.MessagePartCommon{
-                        URL: &imageURL,
-                    },
-                },
-            },
-        },
-    }, nil
-}
-```
-
-### **方式 2 - 把本地函数转为 tool**
-
-在开发过程中，我们经常需要把一个本地函数封装成 Eino 的 tool，比如我们代码中本身已经有了一个 AddUser 的方法，但为了让大模型可以自主决策如何调用这个方法，我们要把这个方法变成一个 tool 并 bind 到大模型上。
-
-Eino 中提供了 NewTool 的方法来把一个函数转成 tool，同时，针对为参数约束通过结构体的 tag 来表示的场景提供了 InferTool 的方法，让构建的过程更加简单。
-
-下方方法的示例可以参考 `cloudwego/eino/components/tool/utils/invokable_func_test.go` 和 `cloudwego/eino/components/tool/utils/streamable_func_test.go` 中的单元测试。
-
-#### **标准工具：使用 NewTool 方法**
-
-当一个函数满足下面这种函数签名时，就可以用 NewTool 把其变成一个 InvokableTool：
-
-```go
-type InvokeFunc[T, D any] func(ctx context.Context, input T) (output D, err error)
-```
-
-NewTool 的方法如下：
-
-```go
-// 代码见: github.com/cloudwego/eino/components/tool/utils/invokable_func.go
-func NewTool[T, D any](desc *schema.ToolInfo, i InvokeFunc[T, D], opts ...Option) tool.InvokableTool
-```
-
-同理 NewStreamTool 可创建 StreamableTool。
-
-以 AddUser 为例，就可以用如下的方式构建：
-
-```go
-import (
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/schema"
-)
-
-type User struct {
-    Name   string `json:"name"`
-    Age    int    `json:"age"`
-    Gender string `json:"gender"`
-}
-
-type Result struct {
-    Msg string `json:"msg"`
-}
-
-func AddUser(ctx context.Context, user *User) (*Result, error) {
-    // some logic
-}
-
-func createTool() tool.InvokableTool {
-    addUserTool := utils.NewTool(&schema.ToolInfo{
-        Name: "add_user",
-        Desc: "add user",
-        ParamsOneOf: schema.NewParamsOneOfByParams(
-            map[string]*schema.ParameterInfo{
-                "name": &schema.ParameterInfo{
-                    Type: schema.String,
-                    Required: true,
-                },
-                "age": &schema.ParameterInfo{
-                    Type: schema.Integer,
-                },
-                "gender": &schema.ParameterInfo{
-                    Type: schema.String,   
-                    Enum: []string{"male", "female"},
-                },
-            },
-        ),
-    }, AddUser)
-    
-    return addUserTool
-}
-```
-
-#### **标准工具：使用 InferTool 方法**
-
-从 NewTool 中可以看出，构建一个 tool 的过程需要分别传入 ToolInfo 和 InvokeFunc，其中，ToolInfo 中包含 ParamsOneOf 的部分，这代表着函数的入参约束，同时，InvokeFunc 的函数签名中也有 input 的参数，这就意味着：ParamsOneOf 的部分和 InvokeFunc 的 input 参数需要保持一致。
-
-当一个函数完全由开发者自行实现的时候，就需要开发者手动维护 input 参数和 ParamsOneOf 以保持一致。更优雅的解决方法是 "参数约束直接维护在 input 参数类型定义中"，可参考上方 GoStruct2ParamsOneOf 的介绍。
-
-当参数约束信息包含在 input 参数类型定义中时，就可以使用 InferTool 来实现，函数签名如下：
-
-```go
-func InferTool[T, D any](toolName, toolDesc string, i InvokeFunc[T, D], opts ...Option) (tool.InvokableTool, error)
-```
-
-以 AddUser 为例:
-
-```go
-import (
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/schema"
-)
-
-type User struct {
-    Name   string `json:"name" jsonschema:"required,description=the name of the user"`
-    Age    int    `json:"age" jsonschema:"description=the age of the user"`
-    Gender string `json:"gender" jsonschema:"enum=male,enum=female"`
-}
-
-type Result struct {
-    Msg string `json:"msg"`
-}
-
-func AddUser(ctx context.Context, user *User) (*Result, error) {
-    // some logic
-}
-
-func createTool() (tool.InvokableTool, error) {
-    return utils.InferTool("add_user", "add user", AddUser)
-}
-```
-
-#### **增强型工具：使用 NewEnhancedTool 方法**
-
-当需要返回多模态结果时，可以使用 NewEnhancedTool 方法：
-
-```go
-type EnhancedInvokeFunc[T any] func(ctx context.Context, input T) (output *schema.ToolResult, err error)
-
-func NewEnhancedTool[T any](desc *schema.ToolInfo, i EnhancedInvokeFunc[T], opts ...Option) tool.EnhancedInvokableTool
-```
-
-示例：
-
-```go
-import (
-    "context"
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/schema"
-)
-
-type ImageSearchInput struct {
-    Query string `json:"query"`
-}
-
-func searchImages(ctx context.Context, input *ImageSearchInput) (*schema.ToolResult, error) {
-    // 执行图片搜索逻辑...
-    imageURL := "https://example.com/image.png"
-    
-    return &schema.ToolResult{
-        Parts: []schema.ToolOutputPart{
-            {Type: schema.ToolPartTypeText, Text: "找到以下图片："},
-            {
-                Type: schema.ToolPartTypeImage,
-                Image: &schema.ToolOutputImage{
-                    MessagePartCommon: schema.MessagePartCommon{
-                        URL: &imageURL,
-                    },
-                },
-            },
-        },
-    }, nil
-}
-
-func createEnhancedTool() tool.EnhancedInvokableTool {
-    return utils.NewEnhancedTool(&schema.ToolInfo{
-        Name: "image_search",
-        Desc: "搜索并返回相关图片",
-        ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{
-            "query": {Type: schema.String, Desc: "搜索关键词", Required: true},
-        }),
-    }, searchImages)
-}
-```
-
-#### **增强型工具：使用 InferEnhancedTool 方法**
-
-类似于 InferTool，InferEnhancedTool 可以从函数签名自动推断参数约束：
-
-```go
-func InferEnhancedTool[T any](toolName, toolDesc string, i EnhancedInvokeFunc[T], opts ...Option) (tool.EnhancedInvokableTool, error)
-```
-
-示例：
-
-```go
-import (
-    "context"
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/schema"
-)
-
-type ImageSearchInput struct {
-    Query string `json:"query" jsonschema:"required" jsonschema_description:"搜索关键词"`
-}
-
-func searchImages(ctx context.Context, input *ImageSearchInput) (*schema.ToolResult, error) {
-    imageURL := "https://example.com/image.png"
-    
-    return &schema.ToolResult{
-        Parts: []schema.ToolOutputPart{
-            {Type: schema.ToolPartTypeText, Text: "找到以下图片："},
-            {
-                Type: schema.ToolPartTypeImage,
-                Image: &schema.ToolOutputImage{
-                    MessagePartCommon: schema.MessagePartCommon{
-                        URL: &imageURL,
-                    },
-                },
-            },
-        },
-    }, nil
-}
-
-func createEnhancedTool() (tool.EnhancedInvokableTool, error) {
-    return utils.InferEnhancedTool("image_search", "搜索并返回相关图片", searchImages)
-}
-```
-
-#### **增强型流式工具：使用 InferEnhancedStreamTool 方法**
-
-对于需要流式返回多模态内容的场景，可以使用 InferEnhancedStreamTool：
-
-```go
-func InferEnhancedStreamTool[T any](toolName, toolDesc string, s EnhancedStreamFunc[T], opts ...Option) (tool.EnhancedStreamableTool, error)
-```
-
-示例：
-
-```go
-import (
-    "context"
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/schema"
-)
-
-type StreamSearchInput struct {
-    Query string `json:"query" jsonschema:"required"`
-}
-
-func streamSearch(ctx context.Context, input *StreamSearchInput) (*schema.StreamReader[*schema.ToolResult], error) {
-    results := []*schema.ToolResult{
-        {Parts: []schema.ToolOutputPart{{Type: schema.ToolPartTypeText, Text: "搜索中..."}}},
-        {Parts: []schema.ToolOutputPart{{Type: schema.ToolPartTypeText, Text: "找到结果"}}},
-    }
-    return schema.StreamReaderFromArray(results), nil
-}
-
-func createEnhancedStreamTool() (tool.EnhancedStreamableTool, error) {
-    return utils.InferEnhancedStreamTool("stream_search", "流式搜索工具", streamSearch)
-}
-```
-
-#### **增强型工具：使用 InferOptionableEnhancedTool 方法**
-
-当需要自定义 option 参数时，可以使用 InferOptionableEnhancedTool：
-
-```go
-func InferOptionableEnhancedTool[T any](toolName, toolDesc string, i OptionableEnhancedInvokeFunc[T], opts ...Option) (tool.EnhancedInvokableTool, error)
-```
-
-示例：
-
-```go
-import (
-    "context"
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/schema"
-)
-
-type ImageSearchOption struct {
-    MaxResults int
-    Quality    string
-}
-
-func WithMaxResults(n int) tool.Option {
-    return tool.WrapImplSpecificOptFn(func(o *ImageSearchOption) {
-        o.MaxResults = n
-    })
-}
-
-type ImageSearchInput struct {
-    Query string `json:"query" jsonschema:"required"`
-}
-
-func searchImagesWithOption(ctx context.Context, input *ImageSearchInput, opts ...tool.Option) (*schema.ToolResult, error) {
-    baseOption := &ImageSearchOption{MaxResults: 10, Quality: "high"}
-    option := tool.GetImplSpecificOptions(baseOption, opts...)
-    
-    // 使用 option.MaxResults 和 option.Quality 执行搜索...
-    imageURL := "https://example.com/image.png"
-    
-    return &schema.ToolResult{
-        Parts: []schema.ToolOutputPart{
-            {Type: schema.ToolPartTypeText, Text: fmt.Sprintf("返回 %d 张图片：", option.MaxResults)},
-            {
-                Type: schema.ToolPartTypeImage,
-                Image: &schema.ToolOutputImage{
-                    MessagePartCommon: schema.MessagePartCommon{URL: &imageURL},
-                },
-            },
-        },
-    }, nil
-}
-
-func createOptionableEnhancedTool() (tool.EnhancedInvokableTool, error) {
-    return utils.InferOptionableEnhancedTool("image_search", "搜索图片", searchImagesWithOption)
-}
-```
-
-#### **使用 InferOptionableTool 方法（标准工具）**
-
-Option 机制是 Eino 提供的一种在运行时传递动态参数的机制，详情可以参考 Eino: CallOption 能力与规范，这套机制在自定义 tool 中同样适用。
-
-当开发者要实现一个需要自定义 option 参数时则可使用 InferOptionableTool 这个方法，相比于 InferTool 对函数签名的要求，这个方法的签名增加了一个 option 参数，签名如下：
-
-```go
-func InferOptionableTool[T, D any](toolName, toolDesc string, i OptionableInvokeFunc[T, D], opts ...Option) (tool.InvokableTool, error)
-```
-
-示例如下（改编自 `cloudwego/eino/components/tool/utils/invokable_func_test.go`）：
-
-```go
-import (
-    "fmt"
-    "context"
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/schema"
-)
-
-type UserInfoOption struct {
-    Field1 string
-}
-
-func WithUserInfoOption(s string) tool.Option {
-    return tool.WrapImplSpecificOptFn(func(t *UserInfoOption) {
-        t.Field1 = s
-    })
-}
-
-func updateUserInfoWithOption(_ context.Context, input *User, opts ...tool.Option) (output *UserResult, err error) {
-    baseOption := &UserInfoOption{
-        Field1: "test_origin",
-    }
-    // handle option
-    option := tool.GetImplSpecificOptions(baseOption, opts...)
-    return &Result{
-        Msg:  option.Field1,
-    }, nil
-}
-
-func useInInvoke() {
-    ctx := context.Background()
-    tl, _ := utils.InferOptionableTool("invoke_infer_optionable_tool", "full update user info", updateUserInfoWithOption)
-
-    content, _ := tl.InvokableRun(ctx, `{"name": "bruce lee"}`, WithUserInfoOption("hello world"))
-
-    fmt.Println(content) // Msg is "hello world", because WithUserInfoOption change the UserInfoOption.Field1
-}
-```
-
-### **方式 3 - 使用 eino-ext 中提供的 tool**
-
-除了自定义的各种 tool 需要自行实现外，eino-ext 项目中还有很多通用的 tool 实现，可以实现开箱即用，比如 Tool - Googlesearch、Tool - DuckDuckGoSearch、wikipedia、httprequest 等等，可以参考 [https://github.com/cloudwego/eino-ext/tree/main/components/tool](https://github.com/cloudwego/eino-ext/tree/main/components/tool) 中的各种实现。
-
-### **方式 4 - 使用 MCP 协议**
-
-MCP（Model Context Protocol）是一个开放的模型上下文协议，现在越来越多的工具和平台都在基于这套协议把自身的能力暴露给大模型调用，eino 可以把基于 MCP 提供的可调用工具作为 tool，这将极大扩充 tool 的种类。
-
-在 Eino 中使用 MCP 提供的 tool 非常方便：
-
-```go
-import (
-    "fmt"
-    "log"
-    "context"
-    "github.com/mark3labs/mcp-go/client"
-    mcpp "github.com/cloudwego/eino-ext/components/tool/mcp"
-)
-
-func getMCPTool(ctx context.Context) []tool.BaseTool {
-        cli, err := client.NewSSEMCPClient("http://localhost:12345/sse")
-        if err != nil {
-                log.Fatal(err)
-        }
-        err = cli.Start(ctx)
-        if err != nil {
-                log.Fatal(err)
-        }
-
-        initRequest := mcp.InitializeRequest{}
-        initRequest.Params.ProtocolVersion = mcp.LATEST_PROTOCOL_VERSION
-        initRequest.Params.ClientInfo = mcp.Implementation{
-                Name:    "example-client",
-                Version: "1.0.0",
-        }
-
-        _, err = cli.Initialize(ctx, initRequest)
-        if err != nil {
-                log.Fatal(err)
-        }
-
-        tools, err := mcpp.GetTools(ctx, &mcpp.Config{Cli: cli})
-        if err != nil {
-                log.Fatal(err)
-        }
-
-        return tools
-}
-```
-
-代码参考：[https://github.com/cloudwego/eino-ext/blob/main/components/tool/mcp/examples/mcp.go](https://github.com/cloudwego/eino-ext/blob/main/components/tool/mcp/examples/mcp.go)
-
-## **工具类型选择指南**
-
-> **注意**：当工具同时实现了标准接口和增强型接口时，ToolsNode 会优先使用增强型接口。

docs/Eino/docs/core_modules/devops/_index.md

@@ -1,10 +0,0 @@
----
-Description: ""
-date: "2025-07-21"
-lastmod: ""
-tags: []
-title: 应用开发工具链
-weight: 5
----
-
-🚀  Eino 是 Go AI 集成组件的研发框架，提供了 AI 应用相关的常用组件以及集成组件编排能力，为了更好的辅助开发者使用 Eino，我们提供了 「Eino Dev 插件」 ，现在就安装插件 ( [EinoDev 插件安装指南](/zh/docs/eino/core_modules/devops/ide_plugin_guide))，助你高效开发  🚀

docs/Eino/docs/core_modules/devops/ide_plugin_guide.md

@@ -1,91 +0,0 @@
----
-Description: ""
-date: "2025-01-20"
-lastmod: ""
-tags: []
-title: Eino Dev 插件安装指南
-weight: 1
----
-
-## 背景 & 简介
-
-> [Eino: 概述](/zh/docs/eino/overview)
-
-**Eino 是 Go AI 集成组件的研发框架**，提供常用的 **AI 组件**以及集成组件**编排能力**。为了更好的辅助开发者使用 Eino，我们提供了「**Eino Dev**」插件，助力 AI 应用高效开发  🚀。
-
-<a href="/img/eino/eino_dev_ability_introduction_page.png" target="_blank"><img src="/img/eino/eino_dev_ability_introduction_page.png" width="100%" /></a>
-
-## 如何安装
-
-### 版本安装依赖
-
-   <table>
-   <tr><td><strong>Plugin Version</strong></td><td><strong>GoLand IDE Version</strong></td><td><strong>VS Code Version</strong></td><td><strong>eino-ext/devops  Version</strong></td></tr>
-   <tr><td>1.1.0</td><td>2023.2+</td><td>1.97.x</td><td>0.1.0</td></tr>
-   <tr><td>1.0.7      </td><td>2023.2+</td><td>-</td><td>0.1.0</td></tr>
-   <tr><td>1.0.6      </td><td>2023.2+</td><td>-</td><td>0.1.0</td></tr>
-   <tr><td>1.0.5     </td><td>2023.2+</td><td>-</td><td>0.1.0</td></tr>
-   <tr><td>1.0.4</td><td>2023.2+</td><td>-</td><td>0.1.0</td></tr>
-   </table>
-
-**Plugin** **Version**：插件版本信息
-
-**Goland IDE Version**： Goland IDE 可支持的最小版本
-
-**VS Code Version**： VS Code 可支持的最小版本
-
-**Eino-Ext/devops  Version**： [eino-ext/devops](https://github.com/cloudwego/eino-ext/tree/main/devops) 调试模块对应的合适版本
-
-### 安装
-
-#### GoLand
-
-<table><tbody><tr>
-<td><li>进入 <strong>GoLand</strong>，点击<strong>设置</strong>，选择<strong> </strong><strong>Plugin</strong><strong>s</strong></li>
-<a href="/img/eino/eino_install_page.png" target="_blank"><img src="/img/eino/eino_install_page.png" width="100%" /></a>
-</td><td><li>在 <strong>Marketplace</strong> 中搜索 <strong>E</strong><strong>ino</strong><strong> Dev</strong> 插件并安装</li>
-<a href="/img/eino/eino_install_page_2_page.png" target="_blank"><img src="/img/eino/eino_install_page_2_page.png" width="100%" /></a>
-</td></tr></tbody></table>
-
-#### VS Code
-
-- 在 VS Code 中点击「Extension 图标」，进入插件市场，搜索 Eino Dev，安装即可
-
-<a href="/img/eino/eino_dev_plugin_vscode.png" target="_blank"><img src="/img/eino/eino_dev_plugin_vscode.png" width="100%" /></a>
-
-## 功能简介
-
-> 💡
-> **插件安装完毕** ✅，**接下来就可以体验插件提供的调试与编排能力了** ～
-
-<table><tbody><tr>
-<td><li>Goland</li>
-右侧边栏找到「<strong>Eino Dev</strong>」图标并点击：
-<a href="/img/eino/eino_dev_ide_plugin_guide_2.png" target="_blank"><img src="/img/eino/eino_dev_ide_plugin_guide_2.png" width="100%" /></a>
-</td><td><li>VS Code</li>
-在底部找到「<strong>Eino Dev</strong>」并点击：
-<a href="/img/eino/eino_dev_ide_plugin_guide_1.png" target="_blank"><img src="/img/eino/eino_dev_ide_plugin_guide_1.png" width="100%" /></a>
-
-</td></tr></tbody></table>
-
-### Graph 编排
-
-详情 👉：[Eino Dev 可视化编排插件功能指南](/zh/docs/eino/core_modules/devops/visual_orchestration_plugin_guide)
-
-<table><tbody><tr>
-<td>
-<a href="/img/eino/eino_orchestration_index_page.png" target="_blank"><img src="/img/eino/eino_orchestration_index_page.png" width="100%" /></a>
-</td><td>
-<a href="/img/eino/eino_orchestration_show_nodes_2_page.png" target="_blank"><img src="/img/eino/eino_orchestration_show_nodes_2_page.png" width="100%" /></a>
-</td></tr></tbody></table>
-
-### Graph 调试
-
-详情 👉：[Eino Dev 可视化调试插件功能指南](/zh/docs/eino/core_modules/devops/visual_debug_plugin_guide)
-
-<table><tbody><tr>
-<td>
-<a href="/img/eino/eino_debug_run_page.png" target="_blank"><img src="/img/eino/eino_debug_run_page.png" width="100%" /></a>
-</td><td>
-<a href="/img/eino/eino_debug_test_run_of_mock_data_page.png" target="_blank"><img src="/img/eino/eino_debug_test_run_of_mock_data_page.png" width="100%" /></a>
-</td></tr></tbody></table>

docs/Eino/docs/core_modules/devops/visual_debug_plugin_guide.md

@@ -1,400 +0,0 @@
----
-Description: ""
-date: "2025-11-20"
-lastmod: ""
-tags: []
-title: Eino Dev 可视化调试插件功能指南
-weight: 3
----
-
-## 简介
-
-> 💡
-> 使用该插件可以对使用 Eino 框架编写的编排产物（Graph，Chain）进行可视化调试，包括：
->
-> 1. 编排产物可视化渲染；
-> 2. 从可操作的任意节点开始，mock 输入进行调试。
-
-## 快速开始
-
-### 下载 eino-example
-
-> github 仓库：_[https://github.com/cloudwego/eino-examples](https://github.com/cloudwego/eino-examples)_
-
-```bash
-# HTTPS
-git clone https://github.com/cloudwego/eino-examples.git 
-
-# SSH
-git clone git@github.com:cloudwego/eino-examples.git
-```
-
-### 安装依赖
-
-在项目目录下依次执行以下指令
-
-```bash
-# 1. Pull latest devops repository 
-go get github.com/cloudwego/eino-ext/devops@latest
-
-# 2. Cleans and updates go.mod and go.sum
-go mod tidy
-```
-
-### 运行 Demo
-
-进入 `eino-examples/devops/debug/main.go`，运行 `main.go`。因为插件会同时在本地启动一个 HTTP 服务用于连接用户服务进程，所以会弹出接入网络警告，点击允许。
-
-<a href="/img/eino/eino_debug_enter_config_page.png" target="_blank"><img src="/img/eino/eino_debug_enter_config_page.png" width="100%" /></a>
-
-### 配置调试地址
-
-<table><tbody><tr>
-<td>
-1.点击左侧或正中间调试功能进入调试配置
-<a href="/img/eino/eino_debug_enter_page.png" target="_blank"><img src="/img/eino/eino_debug_enter_page.png" width="100%" /></a>
-</td><td>
-2.点击配置调试地址
-<a href="/img/eino/eino_debug_config_3_page.png" target="_blank"><img src="/img/eino/eino_debug_config_3_page.png" width="100%" /></a>
-</td></tr></tbody></table>
-
-<table><tbody><tr>
-<td>
-3.填入 127.0.0.1:52538
-<a href="/img/eino/eino_debug_config_2_page.png" target="_blank"><img src="/img/eino/eino_debug_config_2_page.png" width="100%" /></a>
-</td><td>
-4.点击确认进入调试界面，选择要调试的Graph
-<a href="/img/eino/eino_orchestration_index_2_page.png" target="_blank"><img src="/img/eino/eino_orchestration_index_2_page.png" width="100%" /></a>
-</td></tr></tbody></table>
-
-### 开始调试
-
-<table><tbody><tr>
-<td>
-1.点击「Test Run」从 start 节点开始执行
-<a href="/img/eino/eino_debug_enter_test_run_2_page.png" target="_blank"><img src="/img/eino/eino_debug_enter_test_run_2_page.png" width="100%" /></a>
-</td><td>
-2.输入 "hello eino"，点击确认
-<a href="/img/eino/eino_debug_run_input_mock_data_page.png" target="_blank"><img src="/img/eino/eino_debug_run_input_mock_data_page.png" width="100%" /></a>
-
-</td></tr></tbody></table>
-
-<table><tbody><tr>
-<td>
-3.在调试区域展示有各个节点的输入和输出
-<a href="/img/eino/eino_debug_test_run_detail_page.png" target="_blank"><img src="/img/eino/eino_debug_test_run_detail_page.png" width="100%" /></a>
-</td><td>
-4.点击 Input 和 Output 切换查看节点信息
-<a href="/img/eino/eino_debug_index_page.png" target="_blank"><img src="/img/eino/eino_debug_index_page.png" width="100%" /></a>
-</td></tr></tbody></table>
-
-## 功能一览
-
-### 本地或远程调试
-
-目标调试编排产物无论是运行在本地电脑还是在远程服务器，都可以通过配置 IP:Port ，主动连接到目标调试对象所在的服务器。
-
-<a href="/img/eino/eino_debug_run_config_page.png" target="_blank"><img src="/img/eino/eino_debug_run_config_page.png" width="100%" /></a>
-
-### 编排拓扑可视化
-
-支持 Graph 和 Chain 编排拓扑可视化。
-
-<a href="/img/eino/eino_debug_list_nodes_page.png" target="_blank"><img src="/img/eino/eino_debug_list_nodes_page.png" width="100%" /></a>
-
-### 从任意节点开始调试
-
-<a href="/img/eino/eino_debug_test_run_of_one_node_page.png" target="_blank"><img src="/img/eino/eino_debug_test_run_of_one_node_page.png" width="100%" /></a>
-
-### 查看节点执行结果
-
-每个节点执行结果都会按执行顺序展示在调试区域，包括：输入、输出、执行耗时
-
-<a href="/img/eino/eino_debug_run_detail_v2_page.png" target="_blank"><img src="/img/eino/eino_debug_run_detail_v2_page.png" width="100%" /></a>
-
-## 从零开始调试
-
-### 使用 Eino 进行编排
-
-插件支持对 Graph 和 Chain 的编排产物进行调试，假设你已经有编排代码如下
-
-```go
-func RegisterSimpleGraph(ctx context.Context) {
-    g := compose.NewGraph[string, string]()
-    _ = g.AddLambdaNode("node_1", compose.InvokableLambda(func(ctx context.Context, input string) (output string, err error) {
-       return input + " process by node_1,", nil
-    }))
-    _ = g.AddLambdaNode("node_2", compose.InvokableLambda(func(ctx context.Context, input string) (output string, err error) {
-       return input + " process by node_2,", nil
-    }))
-    _ = g.AddLambdaNode("node_3", compose.InvokableLambda(func(ctx context.Context, input string) (output string, err error) {
-       return input + " process by node_3,", nil
-    }))
-
-    _ = g.AddEdge(compose.START, "node_1")
-    _ = g.AddEdge("node_1", "node_2")
-    _ = g.AddEdge("node_2", "node_3")
-    _ = g.AddEdge("node_3", compose.END)
-
-    _, err := g.Compile(ctx)
-    if err != nil {
-       logs.Errorf("compile graph failed, err=%v", err)
-       return
-    }
-}
-```
-
-### 安装依赖
-
-在项目目录下依次执行以下指令
-
-```bash
-# 1. Pull latest devops repository 
-go get github.com/cloudwego/eino-ext/devops@latest
-
-# 2. Cleans and updates go.mod and go.sum
-go mod tidy
-```
-
-### 调用调试初始化函数
-
-因为调试需要在用户主进程中启动一个 HTTP 服务，以用作与本地调试插件交互，所以用户需要主动调用一次 _github.com/cloudwego/eino-ext/devops_ 中的 `Init()` 来启动调试服务。
-
-> 💡
-> 注意事项
->
-> 1. 确保目标调试的编排产物至少执行过一次 `Compile()`。
-> 2. `devops.Init()` 的执行必须要在调用 `Compile()` 之前。
-> 3. 用户需要保证 `devops.Init()` 执行后主进程不能退出。
-
-如在 `main()` 函数中增加调试服务启动代码
-
-```go
-// 1.调用调试服务初始化函数
-err := devops.Init(ctx)
-if err != nil {
-    logs.Errorf("[eino dev] init failed, err=%v", err)
-    return
-}
-
-// 2.编译目标调试的编排产物
-RegisterSimpleGraph(ctx)
-```
-
-### 运行用户进程
-
-在本地电脑或者远程环境中运行你的进程，并保证主进程不会退出。
-
-在 github.com/cloudwego/eino-examples/devops/debug/main.go 中，`main()` 代码如下
-
-```go
-func main() {
-    ctx := context.Background()
-    // Init eino devops server
-    err := devops.Init(ctx)
-    if err != nil {
-       logs.Errorf("[eino dev] init failed, err=%v", err)
-       return
-    }
-
-    // Register chain, graph and state_graph for demo use
-    chain.RegisterSimpleChain(ctx)
-    graph.RegisterSimpleGraph(ctx)
-    graph.RegisterSimpleStateGraph(ctx)
-
-    // Blocking process exits
-    sigs := make(chan os.Signal, 1)
-    signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
-    <-sigs
-
-    // Exit
-    logs.Infof("[eino dev] shutting down\n")
-}
-```
-
-### 配置调试地址
-
-- **IP**：用户进程所在服务器的 IP 地址。
-  - 用户进程运行在本地电脑，则填写 `127.0.0.1`；
-  - 用户进程运行在远程服务器上，则填写远程服务器的 IP 地址，兼容 IPv4 和 IPv6 。
-- **Port**：调试服务监听的端口，默认是 `52538`，可通过 「WithDevServerPort」 这一 option 方法进行修改
-
-> 💡
-> 注意事项
->
-> - 本地电脑调试：系统可能会弹出网络接入警告，允许接入即可。
-> - 远程服务器调试：需要你保证端口可访问。
-
-IP 和 Port 配置完成后，点击确认，调试插件会自动连接到目标调试服务器。如果成功连接，连接状态指示器会变成绿色。
-
-<a href="/img/eino/eino_debug_ip_port_show_page.png" target="_blank"><img src="/img/eino/eino_debug_ip_port_show_page.png" width="100%" /></a>
-
-### 选择目标调试编排产物
-
-确保你目标调试的编排产物至少执行过一次 `Compile()`。因为调试设计是面向编排产物实例，所以如果多次执行 `Compile()`，会在调试服务中注册多个编排产物，继而在选择列表中看到多个可调试目标。
-
-<a href="/img/eino/eino_debug_panel_3.png" target="_blank"><img src="/img/eino/eino_debug_panel_3.png" width="100%" /></a>
-
-### 开始调试
-
-调试支持从任意节点开始调试，包括 start 节点和其他中间节点。
-
-- 从 START 节点开始调试：直接点击 「Test Run」，然后输入 mock 的 input（如果 input 是复杂结构的话，会自动对 input 的结构进行推断）然后点击确定，开始执行你的 graph，每个 node 的结果会在下方显示。
-
-<a href="/img/eino/eino_debug_run_code_2.png" target="_blank"><img src="/img/eino/eino_debug_run_code_2.png" width="100%" /></a>
-
-<a href="/img/eino/eino_debug_run_input_mock_data_2_page.png" target="_blank"><img src="/img/eino/eino_debug_run_input_mock_data_2_page.png" width="100%" /></a>
-
-- 从任意的可操作节点开始调试：比如，从第二个节点开始执行。
-
-<a href="/img/eino/eino_debug_button_run_code.png" target="_blank"><img src="/img/eino/eino_debug_button_run_code.png" width="100%" /></a>
-
-<a href="/img/eino/eino_debug_run_of_mock_input_of_page.png" target="_blank"><img src="/img/eino/eino_debug_run_of_mock_input_of_page.png" width="100%" /></a>
-
-### 查看执行结果
-
-从 START 节点开始调试，点击 Test Run 后，在插件下方查看调试结果。
-
-<a href="/img/eino/eino_debug_test_run_result_page.png" target="_blank"><img src="/img/eino/eino_debug_test_run_result_page.png" width="100%" /></a>
-
-从任意的可操作节点进行调试，在插件下方查看调试结果。
-
-<a href="/img/eino/eino_debug_results.png" target="_blank"><img src="/img/eino/eino_debug_results.png" width="100%" /></a>
-
-## 高阶功能
-
-### 指定 interface 字段的实现类型
-
-对于 interface 类型的字段，会被默认渲染为 `{}` 。在 `{}` 中输入空格可唤出 interface 实现类型的列表，选中某个类型后，系统会生成一个特殊的结构体以表达 interface 的信息；该特殊结构体定义如下：
-
-```go
-{
-    "_value": {} // 按具体类型生成的 json value
-    "_eino_go_type": "*model.MyConcreteType" // Go 类型名
-}
-```
-
-> 💡
-> 系统内已经内置了一些常见的 interface 类型，如 `string`、`schema.Message` 等，可直接选择使用。如果需要自定义 interface 实现类型，可通过 `devops` 提供的 `AppendType` 方法进行注册。
-
-1. 假设你已经有编排代码如下，其中，graph 的输入定义为 `any`，`node_1` 的输入定义为 `*NodeInfo`;
-
-   ```go
-   type NodeInfo struct {
-       Message string
-   }
-
-   func RegisterGraphOfInterfaceType(ctx context.Context) {
-       // Define a graph that input parameter is any.
-       g := compose.NewGraph[any, string]()
-
-       _ = g.AddLambdaNode("node_1", compose.InvokableLambda(func(ctx context.Context, input *NodeInfo) (output string, err error) {
-          if input == nil {
-             return "", nil
-          }
-          return input.Message + " process by node_1,", nil
-       }))
-
-       _ = g.AddLambdaNode("node_2", compose.InvokableLambda(func(ctx context.Context, input string) (output string, err error) {
-          return input + " process by node_2,", nil
-       }))
-
-       _ = g.AddLambdaNode("node_3", compose.InvokableLambda(func(ctx context.Context, input string) (output string, err error) {
-          return input + " process by node_3,", nil
-       }))
-
-       _ = g.AddEdge(compose._START_, "node_1")
-
-       _ = g.AddEdge("node_1", "node_2")
-
-       _ = g.AddEdge("node_2", "node_3")
-
-       _ = g.AddEdge("node_3", compose._END_)
-
-       r, err := g.Compile(ctx)
-       if err != nil {
-          logs.Errorf("compile graph failed, err=%v", err)
-          return
-       }
-   }
-   ```
-2. 调试前，通过 `AppendType` 方法在 `Init()` 时注册自定义的 `*NodeInfo` 类型：
-
-   ```go
-   err := devops.Init(ctx, devops.AppendType(&graph.NodeInfo{}))
-   ```
-3. 调试过程中，在 Test Run 的 Json 输入框中，对于 interface 类型的字段，默认会呈现为 `{}`。可以通过在 `{}` 中键入一个空格，来查看所有内置的以及自定义注册的数据类型，并选择该 interface 的具体实现类型。
-
-<a href="/img/eino/eino_debug_run_code.png" target="_blank"><img src="/img/eino/eino_debug_run_code.png" width="100%" /></a>
-
-1. 在 `_value` 字段中补全调试节点输入。
-
-<a href="/img/eino/eino_debug_run_code_3.png" target="_blank"><img src="/img/eino/eino_debug_run_code_3.png" width="100%" /></a>
-
-1. 点击确认，查看调试结果。
-
-<a href="/img/eino/eino_debug_panel_2.png" target="_blank"><img src="/img/eino/eino_debug_panel_2.png" width="100%" /></a>
-
-#### map[string]any 调试
-
-这里再解释下输入类型为 map[string]any 时如何调试；如果某个节点的输入类型为 map[string]any，如下所示：
-
-```go
-func RegisterAnyInputGraph(ctx context.Context) {
-        g := compose.NewGraph[map[string]any, string]()
-
-        _ = g.AddLambdaNode("node_1", compose.InvokableLambda(func(ctx context.Context, input map[string]any) (output string, err error) {
-                for k, v := range input {
-                        switch v.(type) {
-                        case string:
-                                output += k + ":" + v.(string) + ","
-                        case int:
-                                output += k + ":" + fmt.Sprintf("%d", v.(int))
-                        default:
-                                return "", fmt.Errorf("unsupported type: %T", v)
-                        }
-                }
-
-                return output, nil
-        }))
-
-        _ = g.AddLambdaNode("node_2", compose.InvokableLambda(func(ctx context.Context, input string) (output string, err error) {
-                return input + " process by node_2,", nil
-        }))
-
-        _ = g.AddEdge(compose.START, "node_1")
-
-        _ = g.AddEdge("node_1", "node_2")
-
-        _ = g.AddEdge("node_2", compose.END)
-
-        r, err := g.Compile(ctx)
-        if err != nil {
-                logs.Errorf("compile graph failed, err=%v", err)
-                return
-        }
-
-        message, err := r.Invoke(ctx, map[string]any{"name": "bob", "score": 100})
-        if err != nil {
-                logs.Errorf("invoke graph failed, err=%v", err)
-                return
-        }
-
-        logs.Infof("eino any input graph output is: %v", message)
-}
-```
-
-调试过程中，在 Test Run 的 Json 输入框中，你需要输入以下格式的内容：
-
-```json
-{
-    "name": {
-       "_value": "alice",
-       "_eino_go_type": "string"
-    },
-    "score": {
-       "_value": "99",
-       "_eino_go_type": "int"
-    }
-}
-```