docs: 更新 README.md

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

.gitignore

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

CLAUDE.md

@@ -1,9 +1,37 @@
 # CLAUDE.md
 
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
 CamTalk — 多模态实时 AI 视觉对话助手（摄像头 + 麦克风 + 视觉 + 语音 AI）
 
 > **文档优先原则：** 开发前先读 `docs/` 设计文档，以文档为准；若代码与文档不一致，优先更新文档（尤其接口文档）。详细设计见 `docs/01-13` 系列文档。**注意**：`docs/Eino/` 框架文档内容庞大（~75 个文件），仅在需要了解 Eino Graph/节点/Callback 等框架细节时才读取。
 
+## 常用命令
+
+```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）
@@ -16,57 +44,84 @@ CamTalk — 多模态实时 AI 视觉对话助手（摄像头 + 麦克风 + 视
 
 ## 技术栈
 
-前端：React 18 + TypeScript + Vite，VAD（@ricky0123/vad-web），ONNX Runtime
+前端：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 脚本，无测试框架配置）
 
-## 快速启动
+## 配置体系
 
-```bash
-# 前端：npm run dev（Vite，代理 /ws 和 /api 到 :8080）
-# 后端：go run ./cmd/server（监听 :8080）
-# 生产：./deploy.sh up（4 容器：frontend/backend/postgres/redis）
-```
+配置优先级：**环境变量 > `config.{APP_ENV}.yaml` > `config.yaml` > 代码默认值**
 
-核心环境变量（`.env.example`）：`CAMTALK_AI_LLM_API_KEY`, `CAMTALK_AI_STT_API_KEY`, `CAMTALK_AUTH_JWT_SECRET`, `CAMTALK_STORAGE_DSN`
+配置文件位于 `backend/config/`：
+- `config.yaml` — 基础配置（dev 默认值）
+- `config.dev.yaml` — 开发环境覆盖（可选）
+- `config.prod.yaml` — 生产环境覆盖（可选）
 
-配置优先级：环境变量 > `config.{APP_ENV}.yaml` > `config.yaml`
-环境切换：`APP_ENV=dev|prod`（dev 默认，prod 启用限流 + 严格 CORS）
+环境切换：`APP_ENV=dev|prod`（dev 默认，prod 启用限流 + 严格 CORS + Release 模式）
+
+敏感信息（API Key、JWT Secret、数据库密码）**只能通过环境变量或 `.env` 文件注入**，不写入 YAML 配置文件。核心环境变量（参考 `backend/.env.example`）：
+
+| 变量 | 说明 |
+|------|------|
+| `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 密码 |
+
+## 数据库迁移
+
+迁移 SQL 文件位于 `backend/migrations/`（`001_*.up.sql` 等），通过 Go `//go:embed` 嵌入二进制（见 `backend/migrations/embed.go`）。应用启动时**自动执行**未应用的迁移，无需手动运行迁移命令。迁移通过 `schema_migrations` 表追踪执行状态。
+
+回滚脚本为同目录下的 `*.down.sql` 文件，需手动执行。
 
 ## 协议与 API
 
 **WebSocket**：`ws://localhost:8080/ws?token=<jwt>&conversation_id=<uuid>`
-- 客户端：`query`（图像/音频 Base64）, `config`, `interrupt`, `ping`
-- 服务端：`connected`, `stt_result`, `llm_chunk`, `llm_done`, `tts_audio`, `error`, `pong`
+- 客户端消息：`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`）
 
-**REST API**：`/api/auth/*`（注册/登录/刷新/登出），`/api/conversations/*`（CRUD + 消息分页），`/api/health`
+**REST API**：`/api/auth/*`（注册/登录/刷新/登出），`/api/conversations/*`（CRUD + 消息分页），`/api/scenarios/*`（用户自定义情景 CRUD），`/api/health`
 
-**错误码**：`INVALID_MESSAGE`, `SESSION_NOT_FOUND`, `RATE_LIMITED`, `IMAGE_TOO_LARGE`, `LLM_TIMEOUT`, `STT/TTS/LLM_ERROR`, `INVALID_TOKEN`, 等
+**错误码**：`INVALID_MESSAGE`, `SESSION_NOT_FOUND`, `RATE_LIMITED`, `IMAGE_TOO_LARGE`, `LLM_TIMEOUT`, `STT/TTS/LLM_ERROR`, `INVALID_TOKEN` 等
 
 ## 关键文件路径
 
 **后端核心**：
-- `backend/internal/eino/` — Graph 定义、节点、Callback、Adapter、State
-- `backend/internal/session/tiered.go` — 三级会话存储
-- `backend/internal/store/` — Repository 实现（PG + 内存 + Redis 缓存）
-- `backend/internal/ws/handler.go` — WebSocket 连接管理
-- `backend/migrations/` — SQL 迁移文件
+- `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）
 
 **前端核心**：
-- `frontend/src/hooks/useVisionSession.ts` — 核心会话 Hook（~500 行）
-- `frontend/src/lib/websocket.ts` — WebSocket 客户端单例
-- `frontend/src/lib/auth.tsx` — JWT 自动刷新 + AuthProvider
+- `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/vite.config.ts` — VAD 模型文件自动复制 + 代理配置
+- `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**：标准规范，`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**：除非用户明确要求

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/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/cmd/server/main.go

@@ -23,6 +23,7 @@ import (
 	"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"
 )
@@ -226,7 +227,9 @@ func main() {
 	}
 
 	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")

backend/go.mod

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

backend/go.sum

@@ -129,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=

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

@@ -9,6 +9,7 @@ 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 端点。
@@ -53,6 +54,9 @@ func (h *AuthHandler) RegisterRoutes(rg *gin.RouterGroup, limiter ratelimit.Limi
 
 // 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{
@@ -72,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{
@@ -100,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{
@@ -128,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 {
@@ -159,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",
@@ -166,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",
 	})
@@ -174,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/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/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_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))
 

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/middleware.go

@@ -5,6 +5,8 @@ import (
 	"net/http"
 
 	"github.com/gin-gonic/gin"
+
+	"github.com/hhs/camtalk/internal/trace"
 )
 
 // Middleware 返回 Gin 中间件，按 key 维度限流。
@@ -26,6 +28,13 @@ func Middleware(limiter Limiter, keyFunc func(*gin.Context) string) gin.HandlerF
 		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)))
 

backend/internal/ratelimit/redis_bucket.go

@@ -7,6 +7,7 @@ import (
 	"time"
 
 	"github.com/hhs/camtalk/internal/config"
+	"github.com/hhs/camtalk/internal/trace"
 	"github.com/redis/go-redis/v9"
 )
 
@@ -72,6 +73,7 @@ func NewRedisLimiter(client *redis.Client, cfg config.RateLimitConfig) *RedisLim
 
 // 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 // 秒，浮点
@@ -81,6 +83,7 @@ func (l *RedisLimiter) Allow(ctx context.Context, key string) (bool, time.Durati
 		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
 	}
@@ -100,6 +103,7 @@ func (l *RedisLimiter) Allow(ctx context.Context, key string) (bool, time.Durati
 	}
 
 	retryAfter := time.Duration(retryAfterSec*1000) * time.Millisecond
+	log.Warnw("rate limit triggered", "key", key, "retry_after_sec", retryAfterSec)
 	return false, retryAfter
 }
 

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

@@ -15,12 +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。
@@ -134,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()
@@ -145,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{
@@ -168,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()
@@ -186,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
 				}
@@ -201,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
 		}
@@ -226,14 +244,18 @@ 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 {
-					logger.Log.Warnw("rate limited", "user_id", userID, "retry_after", retryAfter)
+					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
@@ -242,16 +264,16 @@ func serveWS(c *gin.Context, sessionMgr session.Manager, orch orchestrator.Orche
 
 			// 刷新会话 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()
@@ -271,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)
 				}
 			}()
 
@@ -298,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" {
@@ -350,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)
@@ -378,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, nil))
+	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, nil))
+	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, nil))
+	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 '情景最后更新时间';

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

@@ -1,9 +1,5 @@
 # CamTalk Eino 框架与编排设计
 
-> 创建日期：2026-06-19  
-> 状态：已实施  
-> 合并自：`10-Eino重构方案.md` + `11-Eino框架技术文档.md`
-
 ## 1. 概述
 
 ### 1.1 为什么选择 Eino

docs/09-情景切换.md

@@ -1,9 +1,5 @@
 # 情景切换功能
 
-**状态**: ✅ 已完成
-
----
-
 ## 功能概述
 
 情景切换功能允许用户选择不同的对话场景，AI 会根据选择的情景扮演不同的角色：

docs/10-鉴权体系.md

@@ -805,8 +805,9 @@ func (r *CachedUserRepository) DeleteRefreshToken(ctx, tokenHash) error {
 ```
 
 **降级策略**：
-- Redis 操作失败时记录日志，但不阻断主流程
+- Redis 操作失败时使用 `trace.FromContext(ctx)` 记录 Warn 日志（带 trace_id），但不阻断主流程
 - DB 是唯一真实数据源，Redis 仅用于加速
+- 详见 `docs/13-日志追踪.md` — 存储层日志实现
 
 ### 6. Gin 中间件实现
 

docs/11-令牌桶限流.md

@@ -360,7 +360,7 @@ if cfg.RateLimit.Enabled {
         logger.Log.Info("rate limiter initialized with Redis backend")
     } else {
         // 单实例：使用内存令牌桶
-        limiter = ratelimit.NewLimiter(cfg.RateLimit)
+        limiter = ratelimit.NewMemoryLimiter(cfg.RateLimit)
         logger.Log.Info("rate limiter initialized with in-memory backend")
     }
     defer limiter.Stop()
@@ -590,9 +590,9 @@ case "query":
     // 限流检查
     if limiter != nil {
         key := fmt.Sprintf("%s:query", userID)
-        allowed, retryAfter := limiter.Allow(context.Background(), key)
+        allowed, retryAfter := limiter.Allow(ctx, key)
         if !allowed {
-            logger.Log.Warnw("rate limited", "user_id", userID, "retry_after", retryAfter)
+            // 限流触发时自动记录 Warn 日志（在 limiter 内部使用 trace.FromContext）
             errors.SendWSError(client, errors.CodeRateLimited, msg.RequestID,
                 fmt.Errorf("rate limited, retry after %s", retryAfter.Round(time.Second)))
             continue
@@ -605,7 +605,7 @@ case "query":
 **设计要点**：
 - key 格式：`userID:query`（用户级限流）
 - 拒绝时发送 `RATE_LIMITED` 错误到客户端
-- 记录警告日志（便于监控告警）
+- 限流触发时 `RedisLimiter.Allow` 内部自动记录 Warn 日志（带 trace_id，详见 `docs/13-日志追踪.md`）
 - 不阻塞其他消息类型（`ping`/`config`/`interrupt` 不限流）
 
 ### 配置加载与依赖注入

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"
-    }
-}
-```

docs/Eino/docs/core_modules/devops/visual_orchestration_plugin_guide.md

@@ -1,114 +0,0 @@
----
-Description: ""
-date: "2025-12-03"
-lastmod: ""
-tags: []
-title: Eino Dev 可视化编排插件功能指南
-weight: 2
----
-
-## 简介
-
-> 💡
-> Goland 提供的 Eino 可视化编排插件, 在 GoLand 中可以通过组件拖拽实现 Graph 的编排生成代码，并支持导入导出
-
-## 初认插件
-
-### 插件功能介绍
-
-<a href="/img/eino/eino_orchestration_describtion_page.png" target="_blank"><img src="/img/eino/eino_orchestration_describtion_page.png" width="100%" /></a>
-
-## 编排组件介绍
-
-### 图 （ Graph ）
-
-- 与 Eino 中的 Graph 概念一致，指最终由插件侧生成的 Graph，可在以下界面添加 Graph。
-- 点击添加插件，则弹出创建对话框，根据字段说明补充配置信息，即可生成一个 Graph 编排对象。
-   <table><tbody><tr>
-   <td>
-      <a href="/img/eino/eino_orchestration_add_graph_2_page.png" target="_blank"><img src="/img/eino/eino_orchestration_add_graph_2_page.png" width="100%" /></a>
-   </td><td>
-      <a href="/img/eino/eino_orchestration_add_graph_config_deatil_page.png" target="_blank"><img src="/img/eino/eino_orchestration_add_graph_config_deatil_page.png" width="100%" /></a>
-   </td><td>
-      <a href="/img/eino/eino_orchestration_add_graph_page.png" target="_blank"><img src="/img/eino/eino_orchestration_add_graph_page.png" width="100%" /></a>
-   </td></tr></tbody></table>
-
-### 节点 （ Node ）
-
-- 与  Eino  中的  Node  一致，创建 Graph 完成后，通过界面右上角 AddNodes ，添加不同类型 Node 到画布。
-- 添加到 Graph 中 Node 插件会默认填写 NodeKey ，此外可展开 More config 为 Node 配置可选配置。
-   <table><tbody><tr>
-   <td>
-      <a href="/img/eino/eino_orchestration_show_nodes_page.png" target="_blank"><img src="/img/eino/eino_orchestration_show_nodes_page.png" width="100%" /></a>
-   </td><td>
-      <a href="/img/eino/eino_orchestration_add_nodes_page.png" target="_blank"><img src="/img/eino/eino_orchestration_add_nodes_page.png" width="100%" /></a>
-   </td><td>
-      <a href="/img/eino/eino_dev_chat_model_config2.png" target="_blank"><img src="/img/eino/eino_dev_chat_model_config2.png" width="100%" /></a>
-   </td></tr></tbody></table>
-
-### 组件 （ Component ）
-
-- Component 是组成 Node 的必要信息，不同的 Component 对应不同的 Node 类型，并且提供了内置的官方  Official Components  与  Custom Components  。
-- 完成添加  Node  操作后，可按需配置组件的 Runtime Config 信息。
-   <table><tbody><tr>
-   <td>
-      <a href="/img/eino/eino_orchestration_add_nodes_3_page.png" target="_blank"><img src="/img/eino/eino_orchestration_add_nodes_3_page.png" width="100%" /></a>
-   </td><td>
-      <a href="/img/eino/eino_dev_chat_model_config.png" target="_blank"><img src="/img/eino/eino_dev_chat_model_config.png" width="100%" /></a>
-   </td></tr></tbody></table>
-
-### 插槽 （ Slot ）
-
-- 不同类型的 Component 的生成会依赖其他组件，将其作为自身配置依赖的一部分，这部分依赖被称作插槽（ Slot ）。
-- 比如官方提供的 volc_vikingDB  组件，其依赖了 Embedding Component 作为插槽；再比如官方提供的 ToolsNode 组件，其依赖了多个 Tool  Component。
-   <table><tbody><tr>
-   <td>
-      <a href="/img/eino/eino_orchestration_add_slot_page.png" target="_blank"><img src="/img/eino/eino_orchestration_add_slot_page.png" width="100%" /></a>
-   </td><td>
-      <a href="/img/eino/eino_orchestration_node_add_slots__page.png" target="_blank"><img src="/img/eino/eino_orchestration_node_add_slots__page.png" width="100%" /></a>
-   </td></tr></tbody></table>
-
-## 开始编排
-
-### 初始化插件
-
-点击进入 Eino Dev 插件，会展示如下界面，可点击图中圈选框进入编排。
-
-<a href="/img/eino/eino_orchestration_enter_page.png" target="_blank"><img src="/img/eino/eino_orchestration_enter_page.png" width="100%" /></a>
-
-### 创建并编排 Graph
-
-- 界面左下角新增 Graph，在弹窗对话框填写 Graph 相关配置，生成 Graph 画布。
-- 按需从 AddNodes  选择合适的 Node 组件，添加的画布。
-- 依据业务编排逻辑将 Node 组件连接，完成 Graph 业务编排逻辑。
-
-<table><tbody><tr>
-<td>
-<a href="/img/eino/eino_dev_add_graph.png" target="_blank"><img src="/img/eino/eino_dev_add_graph.png" width="100%" /></a>
-</td><td>
-<a href="/img/eino/eino_dev_add_chatmodel.png" target="_blank"><img src="/img/eino/eino_dev_add_chatmodel.png" width="100%" /></a>
-</td><td>
-<a href="/img/eino/eino_orchestration_add_nodes_2_page.png" target="_blank"><img src="/img/eino/eino_orchestration_add_nodes_2_page.png" width="100%" /></a>
-</td><td>
-<a href="/img/eino/eino_orchestration_add_edges_page.png" target="_blank"><img src="/img/eino/eino_orchestration_add_edges_page.png" width="100%" /></a>
-</td></tr></tbody></table>
-
-- 点击 “Generate as code” 并选择合适文件夹，将编排的 Graph 生成代码并保存到指定路径。
-
-<table><tbody><tr>
-<td>
-<a href="/img/eino/eino_orchestration_generate_code.png" target="_blank"><img src="/img/eino/eino_orchestration_generate_code.png" width="100%" /></a>
-</td><td>
-<a href="/img/eino/eino_orchestration_gencode_page.png" target="_blank"><img src="/img/eino/eino_orchestration_gencode_page.png" width="100%" /></a>
-</td></tr></tbody></table>
-
-- 特别的当添加的 Component 为 Graph 类型时，添加的 嵌套 Graph 可展开做 Node 组件的配置，配置完成后，通过顶层面包屑路径跳回首页界面。
-
-<table><tbody><tr>
-<td>
-<a href="/img/eino/eino_orchestration_subgraph_show_page.png" target="_blank"><img src="/img/eino/eino_orchestration_subgraph_show_page.png" width="100%" /></a>
-</td><td>
-<a href="/img/eino/eino_orchestration_sub_graph_pos_page.png" target="_blank"><img src="/img/eino/eino_orchestration_sub_graph_pos_page.png" width="100%" /></a>
-</td></tr></tbody></table>
-
-##

docs/Eino/docs/core_modules/eino_adk/Eino_ADK_ChatModelAgentMiddleware/Middleware_PatchToolCalls.md

@@ -1,159 +0,0 @@
----
-Description: ""
-date: "2026-03-09"
-lastmod: ""
-tags: []
-title: PatchToolCalls
-weight: 8
----
-
-adk/middlewares/patchtoolcalls
-
-> 💡
-> PatchToolCalls 中间件用于修复消息历史中「悬空的工具调用」（dangling tool calls）问题。本中间件在 v0.8.0 版本引入。
-
-## 概述
-
-在多轮对话场景中，可能会出现 Assistant 消息包含工具调用（ToolCalls），但对话历史中缺少对应的 Tool 消息响应的情况。这种「悬空的工具调用」会导致某些模型 API 报错或产生异常行为。
-
-**常见场景：**
-
-- 用户在工具执行完成前发送了新消息，导致工具调用被中断
-- 会话恢复时，部分工具调用结果丢失
-- Human-in-the-loop 场景下，用户取消了工具执行
-
-PatchToolCalls 中间件会在每次模型调用前扫描消息历史，为缺少响应的工具调用自动插入占位符消息。
-
-## 快速开始
-
-```go
-import (
-    "context"
-    "github.com/cloudwego/eino/adk"
-    "github.com/cloudwego/eino/adk/middlewares/patchtoolcalls"
-)
-
-// 使用默认配置创建中间件
-mw, err := patchtoolcalls.New(ctx, nil)
-if err != nil {
-    // 处理错误
-}
-
-// 与 ChatModelAgent 一起使用
-agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    Model:       yourChatModel,
-    Middlewares: []adk.ChatModelAgentMiddleware{mw},
-})
-```
-
-## 配置项
-
-```go
-type Config struct {
-    // PatchedContentGenerator 自定义生成占位符消息内容的函数
-    // 可选，不设置时使用默认消息
-    PatchedContentGenerator func(ctx context.Context, toolName, toolCallID string) (string, error)
-}
-```
-
-<table>
-<tr><td>字段</td><td>类型</td><td>必填</td><td>说明</td></tr>
-<tr><td>PatchedContentGenerator</td><td><pre>func(ctx, toolName, toolCallID string) (string, error)</pre></td><td>否</td><td>自定义生成占位符消息内容的函数。参数包含工具名和调用 ID，返回要填充的内容</td></tr>
-</table>
-
-### 默认占位符消息
-
-如果不设置 `PatchedContentGenerator`，中间件会使用默认的占位符消息：
-
-**英文（默认）：**
-
-```
-Tool call {toolName} with id {toolCallID} was cancelled - another message came in before it could be completed.
-```
-
-**中文：**
-
-```
-工具调用 {toolName}（ID 为 {toolCallID}）已被取消——在其完成之前收到了另一条消息。
-```
-
-可通过 `adk.SetLanguage()` 切换语言。
-
-## 使用示例
-
-### 自定义占位符消息
-
-```go
-mw, err := patchtoolcalls.New(ctx, &patchtoolcalls.Config{
-    PatchedContentGenerator: func(ctx context.Context, toolName, toolCallID string) (string, error) {
-        return fmt.Sprintf("[系统提示] 工具 %s 的执行被跳过（调用ID: %s）", toolName, toolCallID), nil
-    },
-})
-```
-
-### 结合其他中间件使用
-
-```go
-// PatchToolCalls 通常应该放在中间件链的前面
-// 确保在其他中间件处理消息之前修复悬空的工具调用
-agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    Model: yourChatModel,
-    Middlewares: []adk.ChatModelAgentMiddleware{
-        patchToolCallsMiddleware,  // 先修复消息
-        summarizationMiddleware,   // 再进行摘要
-        reductionMiddleware,       // 最后进行裁剪
-    },
-})
-```
-
-## 工作原理
-
-<a href="/img/eino/N9ZzwvvuWhya0vbIzLEcMx6DnMP.png" target="_blank"><img src="/img/eino/N9ZzwvvuWhya0vbIzLEcMx6DnMP.png" width="100%" /></a>
-
-**处理逻辑：**
-
-1. 在 `BeforeModelRewriteState` 钩子中执行
-2. 遍历所有消息，查找包含 `ToolCalls` 的 Assistant 消息
-3. 对于每个 ToolCall，检查后续消息中是否存在对应的 Tool 消息（通过 `ToolCallID` 匹配）
-4. 如果找不到对应的 Tool 消息，则插入一个占位符消息
-5. 返回修复后的消息列表
-
-## 示例场景
-
-### 修复前的消息历史
-
-```
-[User]     "帮我查询天气"
-[Assistant] ToolCalls: [{id: "call_1", name: "get_weather"}, {id: "call_2", name: "get_location"}]
-[Tool]     "call_1: 晴天，25°C"
-[User]     "不用查位置了，直接告诉我北京的天气"   <- 用户中断
-```
-
-### 修复后的消息历史
-
-```
-[User]     "帮我查询天气"
-[Assistant] ToolCalls: [{id: "call_1", name: "get_weather"}, {id: "call_2", name: "get_location"}]
-[Tool]     "call_1: 晴天，25°C"
-[Tool]     "call_2: 工具调用 get_location（ID 为 call_2）已被取消..."  <- 自动插入
-[User]     "不用查位置了，直接告诉我北京的天气"
-```
-
-## 多语言支持
-
-占位符消息支持中英文，通过 `adk.SetLanguage()` 切换：
-
-```go
-import "github.com/cloudwego/eino/adk"
-
-adk.SetLanguage(adk.LanguageChinese)  // 中文
-adk.SetLanguage(adk.LanguageEnglish)  // 英文（默认）
-```
-
-## 注意事项
-
-> 💡
-> 此中间件仅在 `BeforeModelRewriteState` 钩子中修改本次运行的历史消息，不会影响实际存储的消息历史。修复只是临时的，仅用于本轮 agent 调用。
-
-- 建议将此中间件放在中间件链的**前面**，确保其他中间件处理的是完整的消息历史
-- 如果你的场景需要持久化修复后的消息，请在 `PatchedContentGenerator` 中实现相应逻辑

docs/Eino/docs/core_modules/eino_adk/Eino_ADK_ChatModelAgentMiddleware/Middleware_PlanTask.md

@@ -1,292 +0,0 @@
----
-Description: ""
-date: "2026-03-09"
-lastmod: ""
-tags: []
-title: PlanTask
-weight: 6
----
-
-# PlanTask 中间件
-
-adk/middlewares/plantask
-
-> 💡
-> 本中间件在 v0.8.0 版本引入。
-
-## 概述
-
-`plantask` 是一个任务管理中间件，让 Agent 可以创建和管理任务列表。中间件通过 `BeforeAgent` 钩子注入四个工具：
-
-- **TaskCreate**: 创建任务
-- **TaskGet**: 查看任务详情
-- **TaskUpdate**: 更新任务
-- **TaskList**: 列出所有任务
-
-主要用途：
-
-- 跟踪复杂任务的进度
-- 把大任务拆成小步骤
-- 管理任务间的依赖关系
-
----
-
-## 架构
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                              Agent                                      │
-│                                                                         │
-│  ┌───────────────────────────────────────────────────────────────────┐  │
-│  │  BeforeAgent: 注入任务工具                                         │  │
-│  │    - TaskCreate                                                    │  │
-│  │    - TaskGet                                                       │  │
-│  │    - TaskUpdate                                                    │  │
-│  │    - TaskList                                                      │  │
-│  └───────────────────────────────────────────────────────────────────┘  │
-│                                                                         │
-└─────────────────────────────────────────────────────────────────────────┘
-                                    │
-                                    ▼
-┌─────────────────────────────────────────────────────────────────────────┐
-│                             Backend                                     │
-│                                                                         │
-│  存储结构:                                                               │
-│    baseDir/                                                             │
-│    ├── .highwatermark    # ID 计数器                                    │
-│    ├── 1.json            # 任务 #1                                      │
-│    ├── 2.json            # 任务 #2                                      │
-│    └── ...                                                              │
-│                                                                         │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 配置
-
-```go
-type Config struct {
-    Backend Backend  // 存储后端，必填
-    BaseDir string   // 任务文件目录，必填
-}
-```
-
-- 注意这个 Backend 的实现，应该是 session 维度隔离的，不同的 session 对应不同的 Backend（任务列表）
-
----
-
-## Backend 接口
-
-```go
-type Backend interface {
-    LsInfo(ctx context.Context, req *LsInfoRequest) ([]FileInfo, error)
-    Read(ctx context.Context, req *ReadRequest) (string, error)
-    Write(ctx context.Context, req *WriteRequest) error
-    Delete(ctx context.Context, req *DeleteRequest) error
-}
-```
-
----
-
-## 任务结构
-
-```go
-type task struct {
-    ID          string         `json:"id"`          // 任务 ID
-    Subject     string         `json:"subject"`     // 标题
-    Description string         `json:"description"` // 描述
-    Status      string         `json:"status"`      // 状态
-    Blocks      []string       `json:"blocks"`      // 阻塞哪些任务
-    BlockedBy   []string       `json:"blockedBy"`   // 被哪些任务阻塞
-    ActiveForm  string         `json:"activeForm"`  // 进行时文案
-    Owner       string         `json:"owner"`       // 负责 agent
-    Metadata    map[string]any `json:"metadata"`    // 自定义数据
-}
-```
-
-### 状态
-
-<table>
-<tr><td>状态</td><td>说明</td></tr>
-<tr><td><pre>pending</pre></td><td>待处理（默认）</td></tr>
-<tr><td><pre>in_progress</pre></td><td>进行中</td></tr>
-<tr><td><pre>completed</pre></td><td>已完成</td></tr>
-<tr><td><pre>deleted</pre></td><td>删除（会删掉文件）</td></tr>
-</table>
-
-状态流转：`pending` → `in_progress` → `completed`，任何状态都可以直接 `deleted`。
-
----
-
-## 工具
-
-### TaskCreate
-
-创建任务。
-
-<table>
-<tr><td>参数</td><td>类型</td><td>必填</td><td>说明</td></tr>
-<tr><td><pre>subject</pre></td><td>string</td><td>是</td><td>标题</td></tr>
-<tr><td><pre>description</pre></td><td>string</td><td>是</td><td>描述</td></tr>
-<tr><td><pre>activeForm</pre></td><td>string</td><td>否</td><td>进行时文案，比如"正在运行测试"</td></tr>
-<tr><td><pre>metadata</pre></td><td>object</td><td>否</td><td>自定义数据</td></tr>
-</table>
-
-什么时候用：
-
-- 任务比较复杂，有 3 步以上
-- 用户给了一堆事情要做
-- 需要让用户看到进度
-
-什么时候不用：
-
-- 就一个简单任务
-- 三两下就能搞定的事
-
-### TaskGet
-
-查看任务详情。
-
-<table>
-<tr><td>参数</td><td>类型</td><td>必填</td><td>说明</td></tr>
-<tr><td><pre>taskId</pre></td><td>string</td><td>是</td><td>任务 ID</td></tr>
-</table>
-
-返回任务的完整信息：标题、描述、状态、依赖关系等。
-
-### TaskUpdate
-
-更新任务。
-
-<table>
-<tr><td>参数</td><td>类型</td><td>必填</td><td>说明</td></tr>
-<tr><td><pre>taskId</pre></td><td>string</td><td>是</td><td>任务 ID</td></tr>
-<tr><td><pre>subject</pre></td><td>string</td><td>否</td><td>新标题</td></tr>
-<tr><td><pre>description</pre></td><td>string</td><td>否</td><td>新描述</td></tr>
-<tr><td><pre>activeForm</pre></td><td>string</td><td>否</td><td>新的进行时文案</td></tr>
-<tr><td><pre>status</pre></td><td>string</td><td>否</td><td>新状态</td></tr>
-<tr><td><pre>addBlocks</pre></td><td>[]string</td><td>否</td><td>添加被阻塞的任务</td></tr>
-<tr><td><pre>addBlockedBy</pre></td><td>[]string</td><td>否</td><td>添加阻塞自己的任务</td></tr>
-<tr><td><pre>owner</pre></td><td>string</td><td>否</td><td>负责 agent</td></tr>
-<tr><td><pre>metadata</pre></td><td>object</td><td>否</td><td>自定义数据（设 null 删除）</td></tr>
-</table>
-
-注意：
-
-- `status: "deleted"` 会直接删掉任务文件
-- 加依赖时会检查循环依赖
-- 所有任务都完成后会自动清理
-
-### TaskList
-
-列出所有任务，不需要参数。
-
-返回每个任务的摘要：ID、状态、标题、负责 agent、依赖关系。
-
----
-
-## 使用示例
-
-```go
-ctx := context.Background()
-
-// plantask middleware 正常情况下应该 session 维度的
-// 不同的 session 对应不同的任务列表
-middleware, err := plantask.New(ctx, &plantask.Config{
-    Backend: myBackend,
-    BaseDir: "/tasks",
-})
-if err != nil {
-    return err
-}
-
-agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    Model:    myModel,
-    Handlers: []adk.ChatModelAgentMiddleware{middleware},
-})
-```
-
-### 典型流程
-
-```
-1. 收到复杂任务
-       │
-       ▼
-2. TaskCreate 创建任务
-   - #1: 分析需求
-   - #2: 写代码
-       │
-       ▼
-3. TaskUpdate 设置依赖
-   - #2 依赖 #1
-   - #3 依赖 #2
-       │
-       ▼
-4. TaskList 看看有啥任务
-       │
-       ▼
-5. TaskUpdate 开始干活
-   - #1 改成 in_progress
-       │
-       ▼
-6. 干完了 TaskUpdate
-   - #1 改成 completed
-       │
-       ▼
-7. 循环 4-6 直到全部完成
-       │
-       ▼
-8. 自动清理
-```
-
----
-
-## 依赖管理
-
-- **blocks**: 我完成了，这些任务才能开始
-- **blockedBy**: 这些任务完成了，我才能开始
-
-```
-Task #1 (blocks: ["2"])  ────►  Task #2 (blockedBy: ["1"])
-
-#1 完成后 #2 才能开始
-```
-
-循环依赖会报错：
-
-```
-#1 blocks #2
-#2 blocks #1  ← 不行，循环了
-```
-
----
-
-## 自动清理
-
-所有任务都 `completed` 后，会自动把任务文件都删掉。
-
----
-
-## 注意事项
-
-- 任务文件以 JSON 格式存储在 `BaseDir` 目录下，文件名为 `{id}.json`
-- `.highwatermark` 文件用于记录已分配的最大任务 ID，确保 ID 不重复
-- 所有工具操作都有互斥锁保护，并发安全
-- 工具的 description 里已经包含了详细的使用指南，Agent 会根据这些指南来使用工具
-
----
-
-## 多语言支持
-
-工具的 description 支持中英文切换，通过 `adk.SetLanguage()` 设置：
-
-```go
-// 使用中文 description
-adk.SetLanguage(adk.LanguageChinese)
-
-// 使用英文 description（默认）
-adk.SetLanguage(adk.LanguageEnglish)
-```
-
-这个设置是全局的，会影响所有 ADK 内置的 prompt 和工具 description。

docs/Eino/docs/core_modules/eino_adk/Eino_ADK_ChatModelAgentMiddleware/Middleware_Skill.md

@@ -1,439 +0,0 @@
----
-Description: ""
-date: "2026-03-24"
-lastmod: ""
-tags: []
-title: Skill
-weight: 3
----
-
-Skill Middleware 为 Eino ADK Agent 提供了 Skill 支持，使 Agent 能够动态发现和使用预定义的技能来更准确、高效地完成任务。
-
-# 什么是 Skill
-
-Skill 是包含指令、脚本和资源的文件夹，Agent 可以按需发现和使用这些 Skill 来扩展自身能力。 Skill 的核心是一个 `SKILL.md` 文件，包含元数据（至少需要 name 和 description）和指导 Agent 执行特定任务的说明。
-
-```
-my-skill/
-├── SKILL.md          # 必需：指令 + 元数据
-├── scripts/          # 可选：可执行代码
-├── references/       # 可选：参考文档
-└── assets/           # 可选：模板、资源
-```
-
-Skill 使用**渐进式展示（Progressive Disclosure）**来高效管理上下文：
-
-1. **发现（Discovery）**：启动时，Agent 仅加载每个可用 Skill 的名称和描述，足以判断何时可能需要使用该 Skill
-2. **激活****（Activation）**：当任务匹配某个 Skill 的描述时，Agent 将完整的 `SKILL.md` 内容读入上下文
-3. **执行（Execution）**：Agent 遵循指令执行任务，也可以根据需要加载其他文件或执行捆绑的代码这种方式让 Agent 保持快速响应，同时能够按需访问更多上下文。
-
-> 💡
-> Ref: [https://agentskills.io/home](https://agentskills.io/home)
-
-# 接口介绍
-
-## FrontMatter
-
-Skill 的元数据结构，用于在发现阶段快速展示 Skill 信息，避免加载完整内容：
-
-```go
-type FrontMatter struct {
-    Name        string      `yaml:"name"`
-    Description string      `yaml:"description"`
-    Context     ContextMode `yaml:"context"`
-    Agent       string      `yaml:"agent"`
-    Model       string      `yaml:"model"`
-}
-```
-
-<table>
-<tr><td>字段</td><td>类型</td><td>说明</td></tr>
-<tr><td><pre>Name</pre></td><td><pre>string</pre></td><td>Skill 的唯一标识符。Agent 通过此名称调用 Skill ，建议使用简短、有意义的名称（如 <pre>pdf-processing</pre>、<pre>web-research</pre>）。对应 SKILL.md 中 frontmatter 的 <pre>name</pre> 字段</td></tr>
-<tr><td><pre>Description</pre></td><td><pre>string</pre></td><td>Skill 的功能描述。这是 Agent 判断是否使用该 Skill 的关键依据，应清晰说明技 Skill 能适用的场景和能力。对应 SKILL.md 中 frontmatter 的 <pre>description</pre> 字段</td></tr>
-<tr><td><pre>Context</pre></td><td><pre>ContextMode</pre></td><td>上下文模式。可选值：<pre>fork_with_context</pre>（复制历史消息创建新 Agent 执行）、<pre>fork</pre>（隔离上下文创建新 Agent 执行）。留空表示内联模式（直接返回 Skill 内容）</td></tr>
-<tr><td><pre>Agent</pre></td><td><pre>string</pre></td><td>指定使用的 Agent 名称。配合 <pre>Context</pre> 字段使用，通过 <pre>AgentHub</pre> 获取对应的 Agent 工厂函数。留空时使用默认 Agent</td></tr>
-<tr><td><pre>Model</pre></td><td><pre>string</pre></td><td>指定使用的模型名称。通过 <pre>ModelHub</pre> 获取对应的模型实例。在 Context 模式下传递给 Agent 工厂；在内联模式下切换后续 ChatModel 调用使用的模型</td></tr>
-</table>
-
-### ContextMode 上下文模式
-
-```go
-const (
-    ContextModeFork            ContextMode = "fork"              // 隔离上下文
-    ContextModeForkWithContext ContextMode = "fork_with_context" // 复制历史消息
-)
-```
-
-<table>
-<tr><td>模式</td><td>说明</td></tr>
-<tr><td>内联（默认）</td><td>Skill 内容直接作为工具结果返回，由当前 Agent 继续处理</td></tr>
-<tr><td>ForkWithContext</td><td>创建新 Agent，复制当前对话历史，独立执行 Skill 任务后返回结果</td></tr>
-<tr><td>Fork</td><td>创建新 Agent，使用隔离的上下文（仅包含 Skill 内容），独立执行后返回结果</td></tr>
-</table>
-
-## Skill
-
-完整的 Skill 结构，包含元数据和实际指令内容：
-
-```go
-type Skill struct {
-    FrontMatter
-    Content       string
-    BaseDirectory string
-}
-```
-
-<table>
-<tr><td>字段</td><td>类型</td><td>说明</td></tr>
-<tr><td><pre>FrontMatter</pre></td><td><pre>FrontMatter</pre></td><td>嵌入的元数据结构，包含 <pre>Name</pre>、<pre>Description</pre>、<pre>Context</pre>、<pre>Agent</pre>、<pre>Model</pre></td></tr>
-<tr><td><pre>Content</pre></td><td><pre>string</pre></td><td>SKILL.md 文件中 frontmatter 之后的正文内容。包含 Skill 的详细指令、工作流程、示例等，Agent 激活 Skill 后会读取此内容</td></tr>
-<tr><td><pre>BaseDirectory</pre></td><td><pre>string</pre></td><td>Skill 目录的绝对路径。Agent 可以使用此路径访问 Skill 目录中的其他资源文件（如脚本、模板、参考文档等）</td></tr>
-</table>
-
-## Backend
-
-Skill 后端接口，定义了技能的检索方式。Backend 接口将技能的存储与使用解耦，提供以下优势：
-
-- **灵活的存储方式**：技能可以存储在本地文件系统、数据库、远程服务、云存储等任意位置
-- **可扩展性**：团队可以根据需求实现自定义 Backend，如从 Git 仓库动态加载、从配置中心获取等
-- **测试友好**：可以轻松创建 Mock Backend 进行单元测试
-
-```go
-type Backend interface {
-    List(ctx context.Context) ([]FrontMatter, error)
-    Get(ctx context.Context, name string) (Skill, error)
-}
-```
-
-<table>
-<tr><td>方法</td><td>说明</td></tr>
-<tr><td><pre>List</pre></td><td>列出所有可用技能的元数据。在 Agent 启动时调用，用于构建技能工具的描述信息，让 Agent 知道有哪些技能可用</td></tr>
-<tr><td><pre>Get</pre></td><td>根据名称获取完整的技能内容。当 Agent 决定使用某个技能时调用，返回包含详细指令的完整 Skill 结构</td></tr>
-</table>
-
-### **NewBackendFromFilesystem**
-
-基于 `filesystem.Backend` 接口的后端实现，在指定的目录下读取技能：
-
-```go
-type BackendFromFilesystemConfig struct {
-    Backend filesystem.Backend
-    BaseDir string
-}
-
-func NewBackendFromFilesystem(ctx context.Context, config *BackendFromFilesystemConfig) (Backend, error)
-```
-
-<table>
-<tr><td>字段</td><td>类型</td><td>必需</td><td>说明</td></tr>
-<tr><td>Backend</td><td><pre>filesystem.Backend</pre></td><td>是</td><td>文件系统后端实现，用于文件操作</td></tr>
-<tr><td>BaseDir</td><td><pre>string</pre></td><td>是</td><td>技能根目录的路径。会扫描此目录下的所有一级子目录，查找包含 <pre>SKILL.md</pre> 文件的目录作为技能</td></tr>
-</table>
-
-工作方式：
-
-- 扫描 `BaseDir` 下的一级子目录
-- 查找每个子目录中的 `SKILL.md` 文件
-- 解析 YAML frontmatter 获取元数据
-- 深层嵌套的 `SKILL.md` 文件会被忽略
-
-### **filesystem.Backend 实现**
-
-`filesystem.Backend` 接口有以下两种实现可供选择，详见 [Middleware: FileSystem](/zh/docs/eino/core_modules/eino_adk/eino_adk_chatmodelagentmiddleware/middleware_filesystem)
-
-## AgentHub 和 ModelHub
-
-当 Skill 使用 Context 模式（fork/isolate）时，需要配置 AgentHub 和 ModelHub：
-
-```go
-// AgentHubOptions contains options passed to AgentHub.Get when creating an agent for skill execution.
-type AgentHubOptions struct {
-    // Model is the resolved model instance when a skill specifies a "model" field in frontmatter.
-    // nil means the skill did not specify a model override; implementations should use their default.
-    Model model.ToolCallingChatModel
-}
-
-// AgentHub provides agent instances for context mode (fork/fork_with_context) execution.
-type AgentHub interface {
-    // Get returns an Agent by name. When name is empty, implementations should return a default agent.
-    // The opts parameter carries skill-level overrides (e.g., model) resolved by the framework.
-    Get(ctx context.Context, name string, opts *AgentHubOptions) (adk.Agent, error)
-}
-
-// ModelHub 提供模型实例
-type ModelHub interface {
-    Get(ctx context.Context, name string) (model.ToolCallingChatModel, error)
-}
-```
-
-### 
-
-## 初始化
-
-创建 Skill Middleware（推荐使用 `NewMiddleware`）：
-
-```go
-func NewMiddleware(ctx context.Context, config *Config) (adk.ChatModelAgentMiddleware, error)
-```
-
-Config 中配置为：
-
-```go
-type Config struct {
-    // Backend 技能后端实现，必填
-    Backend Backend
-    
-    // SkillToolName 技能工具名称，默认 "skill"
-    SkillToolName *string
-    
-    // AgentHub 提供 Agent 工厂函数，用于 Context 模式
-    // 当 Skill 使用 "context: fork" 或 "context: isolate" 时必填
-    AgentHub AgentHub
-    
-    // ModelHub 提供模型实例，用于 Skill 指定模型
-    ModelHub ModelHub
-    
-    // CustomSystemPrompt 自定义系统提示词
-    CustomSystemPrompt SystemPromptFunc
-    
-    // CustomToolDescription 自定义工具描述
-    CustomToolDescription ToolDescriptionFunc
-}
-```
-
-<table>
-<tr><td>字段</td><td>类型</td><td>必需</td><td>默认值</td><td>说明</td></tr>
-<tr><td><pre>Backend</pre></td><td><pre>Backend</pre></td><td>是</td><td><li></li></td><td>技能后端实现。负责技能的存储和检索，可使用内置的 <pre>LocalBackend</pre> 或自定义实现</td></tr>
-<tr><td><pre>SkillToolName</pre></td><td><pre>*string</pre></td><td>否</td><td><pre>"skill"</pre></td><td>技能工具的名称。Agent 通过此名称调用技能工具。如果你的 Agent 已有同名工具，可以通过此字段自定义名称避免冲突</td></tr>
-<tr><td><pre>AgentHub</pre></td><td><pre>AgentHub</pre></td><td>否</td><td><li></li></td><td>提供 Agent 工厂函数。当 Skill 使用 <pre>context: fork</pre> 或 <pre>context: isolate</pre> 时必填</td></tr>
-<tr><td><pre>ModelHub</pre></td><td><pre>ModelHub</pre></td><td>否</td><td><li></li></td><td>提供模型实例。当 Skill 指定 <pre>model</pre> 字段时使用</td></tr>
-<tr><td><pre>CustomSystemPrompt</pre></td><td><pre>SystemPromptFunc</pre></td><td>否</td><td>内置提示词</td><td>自定义系统提示词函数</td></tr>
-<tr><td><pre>CustomToolDescription</pre></td><td><pre>ToolDescriptionFunc</pre></td><td>否</td><td>内置描述</td><td>自定义工具描述函数</td></tr>
-</table>
-
-# 快速开始
-
-以从本地加载 pdf skill 为例， 完整代码见 [https://github.com/cloudwego/eino-examples/tree/main/adk/middlewares/skill](https://github.com/cloudwego/eino-examples/tree/main/adk/middlewares/skill)。
-
-- 在工作目录中创建 skills 目录：
-
-```go
-workdir/
-├── skills/
-│   └── pdf/
-│        ├── scripts
-│        │   └── analyze.py
-│        └── SKILL.md
-└── other files
-```
-
-- 创建本地 filesystem backend，基于 backend 创建 Skill middleware：
-
-```go
-import (
-    "github.com/cloudwego/eino/adk/middlewares/skill"
-    "github.com/cloudwego/eino-ext/adk/backend/local"
-)
-
-ctx := context.Background() 
-
-be, err := local.NewBackend(ctx, &local.Config{})
-if err != nil {
-    log.Fatal(err)
-}
-
-skillBackend, err := skill.NewBackendFromFilesystem(ctx, &skill.BackendFromFilesystemConfig{
-    Backend: be,
-    BaseDir: skillsDir,
-})
-if err != nil {
-    log.Fatalf("Failed to create skill backend: %v", err)
-}
-
-sm, err := skill.NewMiddleware(ctx, &skill.Config{
-    Backend: skillBackend,
-})
-```
-
-- 基于 backend 创建本地 Filesystem Middleware，供 agent 读取 skill 其他文件以及执行脚本：
-
-```go
-import (
-    "github.com/cloudwego/eino/adk/middlewares/filesystem"
-)
-
-fsm, err := filesystem.New(ctx, &filesystem.MiddlewareConfig{
-    Backend:        be,
-    StreamingShell: be,
-})
-```
-
-- 创建 Agent 并配置 middlewares
-
-```go
-agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    Name:        "LogAnalysisAgent",
-    Description: "An agent that can analyze logs",
-    Instruction: "You are a helpful assistant.",
-    Model:       cm,
-    Handlers:    []adk.ChatModelAgentMiddleware{fsm, sm},
-})
-```
-
-- 调用 Agent，观察结果
-
-```go
-runner := adk.NewRunner(ctx, adk.RunnerConfig{
-    Agent: agent,
-})
-
-input := fmt.Sprintf("Analyze the %s file", filepath.Join(workDir, "test.log"))
-log.Println("User: ", input)
-
-iterator := runner.Query(ctx, input)
-for {
-    event, ok := iterator.Next()
-    if !ok {
-       break
-    }
-    if event.Err != nil {
-       log.Printf("Error: %v\n", event.Err)
-       break
-    }
-
-    prints.Event(event)
-}
-```
-
-agent 输出：
-
-```yaml
-name: LogAnalysisAgent
-path: [{LogAnalysisAgent}]
-tool name: skill
-arguments: {"skill":"log_analyzer"}
-
-name: LogAnalysisAgent
-path: [{LogAnalysisAgent}]
-tool response: Launching skill: log_analyzer
-Base directory for this skill: /Users/bytedance/go/src/github.com/cloudwego/eino-examples/adk/middlewares/skill/workdir/skills/log_analyzer
-# SKILL.md content
-
-name: LogAnalysisAgent
-path: [{LogAnalysisAgent}]
-tool name: execute
-arguments:  {"command": "python3 /Users/bytedance/go/src/github.com/cloudwego/eino-examples/adk/middlewares/skill/workdir/skills/log_analyzer/scripts/analyze.py /Users/bytedance/go/src/github.com/cloudwego/eino-examples/adk/middlewares/skill/workdir/test.log"}
-
-name: LogAnalysisAgent
-path: [{LogAnalysisAgent}]
-tool response: Analysis Result for /Users/bytedance/go/src/github.com/cloudwego/eino-examples/adk/middlewares/skill/workdir/test.log:
-Total Errors: 2
-Total Warnings: 1
-
-Error Details:
-Line 3: [2024-05-20 10:02:15] ERROR: Database connection failed.
-Line 5: [2024-05-20 10:03:05] ERROR: Connection timed out.
-
-Warning Details:
-Line 2: [2024-05-20 10:01:23] WARNING: High memory usage detected.
-
-
-name: LogAnalysisAgent
-path: [{LogAnalysisAgent}]
-answer: Here's the analysis result of the log file:
-
-### Summary
-- **Total Errors**: 2  
-- **Total Warnings**: 1  
-
-### Detailed Entries
-#### Errors:
-1. Line 3: [2024-05-20 10:02:15] ERROR: Database connection failed.  
-2. Line5: [2024-05-2010:03:05] ERROR: Connection timed out.  
-
-#### Warnings:
-1. Line2: [2024-05-2010:01:23] WARNING: High memory usage detected.  
-
-The log file contains critical issues related to database connectivity and a warning about memory usage. Let me know if you need further analysis!
-```
-
-# 原理
-
-Skill middleware 向 Agent 增加 system prompt 与 skill tool，system prompt 内容如下，{tool_name} 为 skill 工具的工具名：
-
-```python
-# Skills System
-
-**How to Use Skills (Progressive Disclosure):**
-
-Skills follow a **progressive disclosure** pattern - you see their name and description above, but only read full instructions when needed:
-
-1. **Recognize when a skill applies**: Check if the user's task matches a skill's description
-2. **Read the skill's full instructions**: Use the '{tool_name}' tool to load skill
-3. **Follow the skill's instructions**: tool result contains step-by-step workflows, best practices, and examples
-4. **Access supporting files**: Skills may include helper scripts, configs, or reference docs - use absolute paths
-
-**When to Use Skills:**
-- User's request matches a skill's domain (e.g., "research X" -> web-research skill)
-- You need specialized knowledge or structured workflows
-- A skill provides proven patterns for complex tasks
-
-**Executing Skill Scripts:**
-Skills may contain Python scripts or other executable files. Always use absolute paths.
-
-**Example Workflow:**
-
-User: "Can you research the latest developments in quantum computing?"
-
-1. Check available skills -> See "web-research" skill
-2. Call '{tool_name}' tool to read the full skill instructions
-3. Follow the skill's research workflow (search -> organize -> synthesize)
-4. Use any helper scripts with absolute paths
-
-Remember: Skills make you more capable and consistent. When in doubt, check if a skill exists for the task!
-```
-
-Skill 工具接收需要加载 skill name，返回对应 SKILL.md 中的完整内容，在工具描述中告知 agent 所有可使用的 skill 的 name 和 description：
-
-```sql
-Execute a skill within the main conversation
-
-<skills_instructions>
-When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
-
-How to invoke:
-- Use this tool with the skill name only (no arguments)
-- Examples:
-  - `skill: pdf` - invoke the pdf skill
-  - `skill: xlsx` - invoke the xlsx skill
-  - `skill: ms-office-suite:pdf` - invoke using fully qualified name
-
-Important:
-- When a skill is relevant, you must invoke this tool IMMEDIATELY as your first action
-- NEVER just announce or mention a skill in your text response without actually calling this tool
-- This is a BLOCKING REQUIREMENT: invoke the relevant Skill tool BEFORE generating any other response about the task
-- Only use skills listed in <available_skills> below
-- Do not invoke a skill that is already running
-- Do not use this tool for built-in CLI commands (like /help, /clear, etc.)
-</skills_instructions>
-
-<available_skills>
-{{- range .Matters }}
-<skill>
-<name>
-{{ .Name }}
-</name>
-<description>
-{{ .Description }}
-</description>
-</skill>
-{{- end }}
-</available_skills>
-```
-
-运行举例：
-
-<a href="/img/eino/GzIObeN6roy2SAxpEXBcMqrRnYb.png" target="_blank"><img src="/img/eino/GzIObeN6roy2SAxpEXBcMqrRnYb.png" width="100%" /></a>
-
-> 💡
-> Skill Middleware 仅提供了如上图所示的加载 SKILL.md 能力，如果 Skill 需要 agent 具备读取文件、执行脚本等能力，需要用户另外为 agent 配置。

docs/Eino/docs/core_modules/eino_adk/Eino_ADK_ChatModelAgentMiddleware/Middleware_Summarization.md

@@ -1,210 +0,0 @@
----
-Description: ""
-date: "2026-03-09"
-lastmod: ""
-tags: []
-title: Summarization
-weight: 4
----
-
-## 概述
-
-Summarization 中间件会在对话的 token 数量超过配置阈值时，自动压缩对话历史。这有助于在长对话中保持上下文连续性，同时控制在模型的 token 限制范围内。
-
-> 💡
-> 本中间件在 v0.8.0 版本引入。
-
-## 快速开始
-
-```go
-import (
-    "context"
-    "github.com/cloudwego/eino/adk/middlewares/summarization"
-)
-
-// 使用最小配置创建中间件
-mw, err := summarization.New(ctx, &summarization.Config{
-    Model: yourChatModel,  // 必填：用于生成摘要的模型
-})
-if err != nil {
-    // 处理错误
-}
-
-// 与 ChatModelAgent 一起使用
-agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    Model:       yourChatModel,
-    Middlewares: []adk.ChatModelAgentMiddleware{mw},
-})
-```
-
-## 配置项
-
-<table>
-<tr><td>字段</td><td>类型</td><td>必填</td><td>默认值</td><td>说明</td></tr>
-<tr><td>Model</td><td>model.BaseChatModel</td><td>是</td><td><li></li></td><td>用于生成摘要的聊天模型</td></tr>
-<tr><td>ModelOptions</td><td>[]model.Option</td><td>否</td><td><li></li></td><td>传递给模型生成摘要时的选项</td></tr>
-<tr><td>TokenCounter</td><td>TokenCounterFunc</td><td>否</td><td>约 4 字符/token</td><td>自定义 token 计数函数</td></tr>
-<tr><td>Trigger</td><td>*TriggerCondition</td><td>否</td><td>190,000 tokens</td><td>触发摘要的条件</td></tr>
-<tr><td>UserInstruction</td><td>string</td><td>否</td><td>内置 prompt</td><td>自定义摘要指令</td></tr>
-<tr><td>TranscriptFilePath</td><td>string</td><td>否</td><td><li></li></td><td>完整对话记录文件路径</td></tr>
-<tr><td>GenModelInput</td><td>GenModelInputFunc</td><td>否</td><td><li></li></td><td>自定义摘要模型输入的预处理函数</td></tr>
-<tr><td>Finalize</td><td>FinalizeFunc</td><td>否</td><td><li></li></td><td>自定义最终消息的后处理函数</td></tr>
-<tr><td>Callback</td><td>CallbackFunc</td><td>否</td><td><li></li></td><td>在 Finalize 之后调用，用于观察状态变化（只读）</td></tr>
-<tr><td>EmitInternalEvents</td><td>bool</td><td>否</td><td>false</td><td>是否发送内部事件</td></tr>
-<tr><td>PreserveUserMessages</td><td>*PreserveUserMessages</td><td>否</td><td>Enabled: true</td><td>是否在摘要中保留原始用户消息</td></tr>
-</table>
-
-### TriggerCondition 结构
-
-```go
-type TriggerCondition struct {
-    // ContextTokens 当总 token 数量超过此阈值时触发摘要
-    ContextTokens int
-}
-```
-
-### PreserveUserMessages 结构
-
-```go
-type PreserveUserMessages struct {
-    // Enabled 是否启用保留用户消息功能
-    Enabled bool
-    
-    // MaxTokens 保留用户消息的最大 token 数
-    // 只保留最近的用户消息，直到达到此限制
-    // 默认为 TriggerCondition.ContextTokens 的 1/3
-    MaxTokens int
-}
-```
-
-### 配置示例
-
-**自定义 Token 阈值**
-
-```go
-mw, err := summarization.New(ctx, &summarization.Config{
-    Model: yourChatModel,
-    Trigger: &summarization.TriggerCondition{
-        ContextTokens: 100000,  // 在 100k tokens 时触发
-    },
-})
-```
-
-**自定义 Token 计数器**
-
-```go
-mw, err := summarization.New(ctx, &summarization.Config{
-    Model: yourChatModel,
-    TokenCounter: func(ctx context.Context, input *summarization.TokenCounterInput) (int, error) {
-        // 使用你的 tokenizer
-        return yourTokenizer.Count(input.Messages)
-    },
-})
-```
-
-**设置对话记录文件路径**
-
-```go
-mw, err := summarization.New(ctx, &summarization.Config{
-    Model:              yourChatModel,
-    TranscriptFilePath: "/path/to/transcript.txt",
-})
-```
-
-**自定义 Finalize 函数**
-
-```go
-mw, err := summarization.New(ctx, &summarization.Config{
-    Model: yourChatModel,
-    Finalize: func(ctx context.Context, originalMessages []adk.Message, summary adk.Message) ([]adk.Message, error) {
-        // 自定义逻辑构建最终消息
-        return []adk.Message{
-            schema.SystemMessage("你的系统提示词"),
-            summary,
-        }, nil
-    },
-})
-```
-
-**使用 Callback 观察状态变化****/存储**
-
-```go
-mw, err := summarization.New(ctx, &summarization.Config{
-    Model: yourChatModel,
-    Callback: func(ctx context.Context, before, after adk.ChatModelAgentState) error {
-        log.Printf("Summarization completed: %d messages -> %d messages", 
-            len(before.Messages), len(after.Messages))
-        return nil
-    },
-})
-```
-
-**控制用户消息保留**
-
-```go
-mw, err := summarization.New(ctx, &summarization.Config{
-    Model: yourChatModel,
-    PreserveUserMessages: &summarization.PreserveUserMessages{
-        Enabled:   true,
-        MaxTokens: 50000, // 保留最多 50k tokens 的用户消息
-    },
-})
-```
-
-## 工作原理
-
-```mermaid
-flowchart TD
-    A[BeforeModelRewriteState] --> B{Token 数量超过阈值?}
-    B -->|否| C[返回原始状态]
-    B -->|是| D[发送 BeforeSummarize 事件]
-    D --> E{有自定义 GenModelInput?}
-    E -->|是| F[调用 GenModelInput]
-    E -->|否| G[调用模型生成摘要]
-    F --> G
-    G --> H{有自定义 Finalize?}
-    H -->|是| I[调用 Finalize]
-    H -->|否| L{有自定义 Callback?}
-    I --> L
-    L -->|是| M[调用 Callback]
-    L -->|否| J[发送 AfterSummarize 事件]
-    M --> J
-    J --> K[返回新状态]
-
-    style A fill:#e3f2fd
-    style G fill:#fff3e0
-    style D fill:#e8f5e9
-    style J fill:#e8f5e9
-    style K fill:#c8e6c9
-    style C fill:#f5f5f5
-    style M fill:#fce4ec
-    style F fill:#fff3e0
-    style I fill:#fff3e0
-```
-
-## 内部事件
-
-当 EmitInternalEvents 设置为 true 时，中间件会在关键节点发送事件：
-
-<table>
-<tr><td>事件类型</td><td>触发时机</td><td>携带数据</td></tr>
-<tr><td>ActionTypeBeforeSummarize</td><td>生成摘要之前</td><td>原始消息列表</td></tr>
-<tr><td>ActionTypeAfterSummarize</td><td>完成总结之后</td><td>最终消息列表</td></tr>
-</table>
-
-**使用示例**
-
-```go
-mw, err := summarization.New(ctx, &summarization.Config{
-    Model:              yourChatModel,
-    EmitInternalEvents: true,
-})
-
-// 在你的事件处理器中监听事件
-```
-
-## 最佳实践
-
-1. **设置 TranscriptFilePath**：建议始终提供对话记录文件路径，以便模型在需要时可以参考原始对话。
-2. **调整 Token 阈值**：根据模型的上下文窗口大小调整 `Trigger.MaxTokens`。一般建议设置为模型限制的 80-90%。
-3. **自定义 Token 计数器**：在生产环境中，建议实现与模型 tokenizer 匹配的自定义 `TokenCounter`，以获得准确的计数。

docs/Eino/docs/core_modules/eino_adk/Eino_ADK_ChatModelAgentMiddleware/Middleware_ToolReduction.md

@@ -1,317 +0,0 @@
----
-Description: ""
-date: "2026-03-12"
-lastmod: ""
-tags: []
-title: Reduction
-weight: 5
----
-
-# Reduction 中间件
-
-adk/middlewares/reduction
-
-> 💡
-> 本中间件在 v0.8.0 版本引入。
-
-## 概述
-
-`reduction` 中间件用来控制工具结果占用的 token 数量，提供两种策略：
-
-1. **截断 (Truncation)**：工具返回时立即截断过长的输出，将完整内容保存到 Backend
-2. **清理 (Clear)**：总 token 超过阈值时，把旧的工具结果存到文件系统
-
----
-
-## 架构
-
-```
-Tool 调用返回结果
-                          │
-                          ▼
-┌─────────────────────────────────────────────────────────────┐
-│              WrapInvokableToolCall / WrapStreamableToolCall │
-│                                                             │
-│  Truncation 策略（可跳过）                                   │
-│    结果长度 > MaxLengthForTrunc?                            │
-│      是 → 截断内容，完整内容存到 Backend                    │
-│      否 → 原样返回                                          │
-└─────────────────────────────────────────────────────────────┘
-                          │
-                          ▼
-                    结果加入 Messages
-                          │
-                          ▼
-┌─────────────────────────────────────────────────────────────┐
-│                  BeforeModelRewriteState                    │
-│                                                             │
-│  Clear 策略（可跳过）                                        │
-│    总 token > MaxTokensForClear?                            │
-│      是 → 把旧的工具结果存到 Backend，替换成文件路径        │
-│      否 → 不处理                                            │
-└─────────────────────────────────────────────────────────────┘
-                          │
-                          ▼
-                     调用 Model
-```
-
----
-
-## 配置
-
-### Config 主配置
-
-```go
-type Config struct {
-    // Backend 存储后端，用于保存截断/清理的内容
-    // 当 SkipTruncation 为 false 时必填
-    Backend Backend
-
-    // SkipTruncation 跳过截断阶段
-    SkipTruncation bool
-
-    // SkipClear 跳过清理阶段
-    SkipClear bool
-
-    // ReadFileToolName 读取文件的工具名
-    // 内容卸载到文件后，agent 需要使用此工具读取
-    // 默认 "read_file"
-    ReadFileToolName string
-
-    // RootDir 保存内容的根目录
-    // 默认 "/tmp"
-    // 截断内容保存到 {RootDir}/trunc/{tool_call_id}
-    // 清理内容保存到 {RootDir}/clear/{tool_call_id}
-    RootDir string
-
-    // MaxLengthForTrunc 触发截断的最大长度
-    // 默认 50000
-    MaxLengthForTrunc int
-
-    // TokenCounter token 计数器
-    // 用于判断是否需要触发清理
-    // 默认使用 字符数/4 估算
-    TokenCounter func(ctx context.Context, msg []adk.Message, tools []*schema.ToolInfo) (int64, error)
-
-    // MaxTokensForClear 触发清理的 token 阈值
-    // 默认 30000
-    MaxTokensForClear int64
-
-    // ClearRetentionSuffixLimit 保留最近多少轮对话不清理
-    // 默认 1
-    ClearRetentionSuffixLimit int
-
-    // ClearPostProcess 清理完成后的回调
-    // 可用于保存或通知当前状态
-    ClearPostProcess func(ctx context.Context, state *adk.ChatModelAgentState) context.Context
-
-    // ToolConfig 针对特定工具的配置
-    // 优先级高于全局配置
-    ToolConfig map[string]*ToolReductionConfig
-}
-```
-
-### ToolReductionConfig 工具级配置
-
-```go
-type ToolReductionConfig struct {
-    // Backend 此工具使用的存储后端
-    Backend Backend
-
-    // SkipTruncation 跳过此工具的截断
-    SkipTruncation bool
-
-    // TruncHandler 自定义截断处理器
-    // 不设置时使用默认处理器
-    TruncHandler func(ctx context.Context, detail *ToolDetail) (*TruncResult, error)
-
-    // SkipClear 跳过此工具的清理
-    SkipClear bool
-
-    // ClearHandler 自定义清理处理器
-    // 不设置时使用默认处理器
-    ClearHandler func(ctx context.Context, detail *ToolDetail) (*ClearResult, error)
-}
-```
-
-### ToolDetail 工具详情
-
-```go
-type ToolDetail struct {
-    // ToolContext 工具元信息（工具名、调用 ID）
-    ToolContext *adk.ToolContext
-
-    // ToolArgument 输入参数
-    ToolArgument *schema.ToolArgument
-
-    // ToolResult 输出结果
-    ToolResult *schema.ToolResult
-}
-```
-
-### TruncResult 截断结果
-
-```go
-type TruncResult struct {
-    // NeedTrunc 是否需要截断
-    NeedTrunc bool
-
-    // ToolResult 截断后的工具结果
-    // NeedTrunc 为 true 时必填
-    ToolResult *schema.ToolResult
-
-    // NeedOffload 是否需要卸载到存储
-    NeedOffload bool
-
-    // OffloadFilePath 卸载文件路径
-    // NeedOffload 为 true 时必填
-    OffloadFilePath string
-
-    // OffloadContent 卸载内容
-    // NeedOffload 为 true 时必填
-    OffloadContent string
-}
-```
-
-### ClearResult 清理结果
-
-```go
-type ClearResult struct {
-    // NeedClear 是否需要清理
-    NeedClear bool
-
-    // ToolArgument 清理后的工具参数
-    // NeedClear 为 true 时必填
-    ToolArgument *schema.ToolArgument
-
-    // ToolResult 清理后的工具结果
-    // NeedClear 为 true 时必填
-    ToolResult *schema.ToolResult
-
-    // NeedOffload 是否需要卸载到存储
-    NeedOffload bool
-
-    // OffloadFilePath 卸载文件路径
-    // NeedOffload 为 true 时必填
-    OffloadFilePath string
-
-    // OffloadContent 卸载内容
-    // NeedOffload 为 true 时必填
-    OffloadContent string
-}
-```
-
----
-
-## 创建中间件
-
-### 基本用法
-
-```go
-import (
-    "context"
-    "github.com/cloudwego/eino/adk/middlewares/reduction"
-)
-
-// 使用默认配置
-middleware, err := reduction.New(ctx, &reduction.Config{
-    Backend: myBackend,  // 必填：存储后端
-})
-
-// 与 ChatModelAgent 一起使用
-agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    Model:       yourChatModel,
-    Middlewares: []adk.ChatModelAgentMiddleware{middleware},
-})
-```
-
-### 自定义配置
-
-```go
-config := &reduction.Config{
-    Backend:           myBackend,
-    RootDir:           "/data/agent",
-    MaxLengthForTrunc: 30000,
-    MaxTokensForClear: 100000,
-    ClearRetentionSuffixLimit: 2,
-    TokenCounter: myTokenCounter,
-    ClearPostProcess: func(ctx context.Context, state *adk.ChatModelAgentState) context.Context {
-        log.Printf("Clear completed, messages: %d", len(state.Messages))
-        return ctx
-    },
-    ToolConfig: map[string]*reduction.ToolReductionConfig{
-        "grep": {
-            Backend:        grepBackend,
-            SkipTruncation: false,
-        },
-        "read_file": {
-            Backend:   readFileBackend,
-            SkipClear: true,  // 读文件工具不需要清理
-        },
-    },
-}
-
-middleware, err := reduction.New(ctx, config)
-```
-
-### 仅使用截断策略
-
-```go
-middleware, err := reduction.New(ctx, &reduction.Config{
-    Backend:   myBackend,
-    SkipClear: true,  // 跳过清理阶段
-})
-```
-
-### 仅使用清理策略
-
-```go
-middleware, err := reduction.New(ctx, &reduction.Config{
-    Backend:        myBackend,
-    SkipTruncation: true,  // 跳过截断阶段
-})
-```
-
----
-
-## 工作原理
-
-### Truncation（截断）
-
-在 `WrapInvokableToolCall` / `WrapStreamableToolCall` 中处理：
-
-1. 工具返回结果
-2. 调用 TruncHandler 判断是否需要截断
-3. 如需截断，将完整内容存到 Backend
-4. 返回截断后的内容，包含提示文字告知 agent 完整内容的位置
-
-### Clear（清理）
-
-在 `BeforeModelRewriteState` 中处理：
-
-1. 用 TokenCounter 计算总 token
-2. 超过 MaxTokensForClear 才处理
-3. 从旧消息开始遍历，跳过已处理的和最近 ClearRetentionSuffixLimit 轮
-4. 对范围内的每个工具调用，调用 ClearHandler
-5. 需要清理的，写入 Backend，把消息里的结果替换成文件路径
-6. 调用 ClearPostProcess 回调
-
----
-
-## 多语言支持
-
-截断和清理的提示文字支持中英文，通过 `adk.SetLanguage()` 切换：
-
-```go
-adk.SetLanguage(adk.LanguageChinese)  // 中文
-adk.SetLanguage(adk.LanguageEnglish)  // 英文（默认）
-```
-
----
-
-## 注意事项
-
-- 当 `SkipTruncation` 为 false 时，`Backend` 必须设置
-- 默认 TokenCounter 用 `字符数 / 4` 估算，对于中文不精准，建议使用 `github.com/tiktoken-go/tokenizer` 替换
-- 已处理过的消息会打标记，不会重复处理
-- `ToolConfig` 中的配置优先级高于全局配置

docs/Eino/docs/core_modules/eino_adk/Eino_ADK_ChatModelAgentMiddleware/Middleware_ToolSearch.md

@@ -1,145 +0,0 @@
----
-Description: ""
-date: "2026-03-09"
-lastmod: ""
-tags: []
-title: ToolSearch
-weight: 7
----
-
-# ToolSearch 中间件
-
-adk/middlewares/dynamictool/toolsearch
-
-> 💡
-> 本中间件在 v0.8.0 版本引入。
-
-## 概述
-
-`toolsearch` 中间件实现动态工具选择。当工具库很大时，把所有工具都传给模型会撑爆上下文。这个中间件的做法是：
-
-1. 添加一个 `tool_search` 元工具，接受正则表达式搜索工具名
-2. 初始时隐藏所有动态工具
-3. 模型调用 `tool_search` 后，匹配的工具才会出现在后续调用中
-
----
-
-## 架构
-
-```
-Agent 初始化
-                                │
-                                ▼
-┌───────────────────────────────────────────┐
-│  BeforeAgent                                                          │
-│    - 注入 tool_search 工具                                              │
-│    - 把 DynamicTools 加到 Tools 列表                                    │
-└───────────────────────────────────────────┘
-                                │
-                                ▼
-┌────────────────────────────────────────────┐
-│  WrapModel                                                              │
-│    每次 Model 调用前：                                                    │
-│    1. 扫描消息历史，找到历史中所有 tool_search 的返回结果。                    │
-│    2. 全量 Tools 减去未被选中的 DynamicTools，作为本次 Model 调用的工具列表。   │
-└────────────────────────────────────────────┘
-                                │
-                                ▼
-                          Model 调用
-```
-
----
-
-## 配置
-
-```go
-type Config struct {
-    // 可动态搜索和加载的工具列表
-    DynamicTools []tool.BaseTool
-}
-```
-
----
-
-## tool_search 工具
-
-中间件注入的工具。
-
-**参数：**
-
-<table>
-<tr><td>参数</td><td>类型</td><td>必填</td><td>说明</td></tr>
-<tr><td><pre>regex_pattern</pre></td><td>string</td><td>是</td><td>匹配工具名的正则表达式</td></tr>
-</table>
-
-**返回：**
-
-```json
-{
-  "selectedTools": ["tool_a", "tool_b"]
-}
-```
-
----
-
-## 使用示例
-
-```go
-middleware, err := toolsearch.New(ctx, &toolsearch.Config{
-    DynamicTools: []tool.BaseTool{
-        weatherTool,
-        stockTool,
-        currencyTool,
-        // ... 很多工具
-    },
-})
-if err != nil {
-    return err
-}
-
-agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    Model:    myModel,
-    Handlers: []adk.ChatModelAgentMiddleware{middleware},
-})
-```
-
----
-
-## 工作原理
-
-### BeforeAgent
-
-1. 获取所有 DynamicTool
-2. 使用 DynamicTools 创建 `tool_search` 工具
-3. 把 `tool_search` 和所有 DynamicTools 加到 `runCtx.Tools`，此时 Agent 中的 Tools 为全量
-
-### WrapModel
-
-每次 Model 调用前：
-
-1. 遍历消息历史，找所有 `tool_search` 的返回结果
-2. 收集已选中的工具名
-3. 从全量工具中过滤掉未选中的 DynamicTools
-4. 用过滤后的工具列表调用 Model
-
-### 工具选择流程
-
-```
-第一轮：
-  Model 只能看到 tool_search
-  Model 调用 tool_search(regex_pattern="weather.*")
-  返回 {"selectedTools": ["weather_forecast", "weather_history"]}
-
-第二轮：
-  Model 能看到 tool_search + weather_forecast + weather_history
-  Model 调用 weather_forecast(...)
-```
-
----
-
-## 注意事项
-
-- DynamicTools 不能为空
-- 正则匹配的是工具名，不是描述
-- 选中的工具会一直保持可用，除非 tool_search 调用结果被删除或修改
-- 可以多次调用 tool_search，结果会累加

docs/Eino/docs/core_modules/eino_adk/Eino_ADK_ChatModelAgentMiddleware/_index.md

@@ -1,521 +0,0 @@
----
-Description: ""
-date: "2026-03-09"
-lastmod: ""
-tags: []
-title: ChatModelAgentMiddleware
-weight: 8
----
-
-## 概述
-
-## ChatModelAgentMiddleware 接口
-
-`ChatModelAgentMiddleware` 定义了自定义 `ChatModelAgent` 行为的接口。
-
-**重要说明：** 此接口专为 `ChatModelAgent` 及基于它构建的 Agent（如 `DeepAgent`）设计。
-
-> 💡
-> ChatModelAgentMiddleware 接口在 v0.8.0 版本引入
-
-### 为什么使用 ChatModelAgentMiddleware 而非 AgentMiddleware？
-
-<table>
-<tr><td>特性</td><td>AgentMiddleware (结构体)</td><td>ChatModelAgentMiddleware (接口)</td></tr>
-<tr><td>扩展性</td><td>封闭，用户无法添加新方法</td><td>开放，用户可实现自定义 handler</td></tr>
-<tr><td>Context 传播</td><td>回调只返回 error</td><td>所有方法返回 <pre>(context.Context, ..., error)</pre></td></tr>
-<tr><td>配置管理</td><td>分散在闭包中</td><td>集中在结构体字段中</td></tr>
-</table>
-
-### 接口定义
-
-```go
-type ChatModelAgentMiddleware interface {
-    // BeforeAgent 在每次 agent 运行前调用，允许修改 instruction 和 tools 配置
-    BeforeAgent(ctx context.Context, runCtx *ChatModelAgentContext) (context.Context, *ChatModelAgentContext, error)
-
-    // BeforeModelRewriteState 在每次模型调用前调用
-    // 返回的 state 会被持久化到 agent 内部状态并传递给模型
-    // 返回的 context 会传播到模型调用和后续 handler
-    BeforeModelRewriteState(ctx context.Context, state *ChatModelAgentState, mc *ModelContext) (context.Context, *ChatModelAgentState, error)
-
-    // AfterModelRewriteState 在每次模型调用后调用
-    // 输入的 state 包含模型响应作为最后一条消息
-    AfterModelRewriteState(ctx context.Context, state *ChatModelAgentState, mc *ModelContext) (context.Context, *ChatModelAgentState, error)
-
-    // WrapInvokableToolCall 用自定义行为包装工具的同步执行
-    // 如果不需要包装，返回原始 endpoint 和 nil error
-    // 仅对实现了 InvokableTool 的工具调用此方法
-    WrapInvokableToolCall(ctx context.Context, endpoint InvokableToolCallEndpoint, tCtx *ToolContext) (InvokableToolCallEndpoint, error)
-
-    // WrapStreamableToolCall 用自定义行为包装工具的流式执行
-    // 如果不需要包装，返回原始 endpoint 和 nil error
-    // 仅对实现了 StreamableTool 的工具调用此方法
-    WrapStreamableToolCall(ctx context.Context, endpoint StreamableToolCallEndpoint, tCtx *ToolContext) (StreamableToolCallEndpoint, error)
-
-    // WrapEnhancedInvokableToolCall 用自定义行为包装增强型工具的同步执行
-    WrapEnhancedInvokableToolCall(ctx context.Context, endpoint EnhancedInvokableToolCallEndpoint, tCtx *ToolContext) (EnhancedInvokableToolCallEndpoint, error)
-
-    // WrapEnhancedStreamableToolCall 用自定义行为包装增强型工具的流式执行
-    WrapEnhancedStreamableToolCall(ctx context.Context, endpoint EnhancedStreamableToolCallEndpoint, tCtx *ToolContext) (EnhancedStreamableToolCallEndpoint, error)
-
-    // WrapModel 用自定义行为包装聊天模型
-    // 如果不需要包装，返回原始 model 和 nil error
-    // 在请求时调用，每次模型调用前都会执行
-    WrapModel(ctx context.Context, m model.BaseChatModel, mc *ModelContext) (model.BaseChatModel, error)
-}
-```
-
-### 使用 BaseChatModelAgentMiddleware
-
-嵌入 `*BaseChatModelAgentMiddleware` 以获得默认的空操作实现：
-
-```go
-type MyHandler struct {
-    *adk.BaseChatModelAgentMiddleware
-}
-
-func (h *MyHandler) BeforeModelRewriteState(ctx context.Context, state *adk.ChatModelAgentState, mc *adk.ModelContext) (context.Context, *adk.ChatModelAgentState, error) {
-    return ctx, state, nil
-}
-```
-
----
-
-## 工具调用端点类型
-
-工具包装使用函数类型而非接口，更清晰地表达了包装的意图：
-
-```go
-// InvokableToolCallEndpoint 是同步工具调用的函数签名
-type InvokableToolCallEndpoint func(ctx context.Context, argumentsInJSON string, opts ...tool.Option) (string, error)
-
-// StreamableToolCallEndpoint 是流式工具调用的函数签名
-type StreamableToolCallEndpoint func(ctx context.Context, argumentsInJSON string, opts ...tool.Option) (*schema.StreamReader[string], error)
-
-// EnhancedInvokableToolCallEndpoint 是增强型同步工具调用的函数签名
-type EnhancedInvokableToolCallEndpoint func(ctx context.Context, toolArgument *schema.ToolArgument, opts ...tool.Option) (*schema.ToolResult, error)
-
-// EnhancedStreamableToolCallEndpoint 是增强型流式工具调用的函数签名
-type EnhancedStreamableToolCallEndpoint func(ctx context.Context, toolArgument *schema.ToolArgument, opts ...tool.Option) (*schema.StreamReader[*schema.ToolResult], error)
-```
-
-### 为什么使用分离的端点类型？
-
-之前的 `ToolCall` 接口同时包含 `InvokableRun` 和 `StreamableRun`，但大多数工具只实现其中一个。
-分离的端点类型使得：
-
-- 只有当工具实现相应接口时才调用对应的包装方法
-- wrapper 作者更清晰的契约
-- 关于实现哪个方法没有歧义
-
----
-
-## ChatModelAgentContext
-
-`ChatModelAgentContext` 包含在每次 `ChatModelAgent` 运行前传递给 handler 的运行时信息。
-
-```go
-type ChatModelAgentContext struct {
-    // Instruction 是当前 Agent 执行的指令
-    // 包括 agent 配置的指令、框架和 AgentMiddleware 追加的额外指令，
-    // 以及之前 BeforeAgent handler 应用的修改
-    Instruction string
-
-    // Tools 是当前为 Agent 执行配置的原始工具（无任何 wrapper 或 tool middleware）
-    // 包括 AgentConfig 中传入的工具、框架隐式添加的工具（如 transfer/exit 工具），
-    // 以及 middleware 已添加的其他工具
-    Tools []tool.BaseTool
-
-    // ReturnDirectly 是当前配置为使 Agent 直接返回的工具名称集合
-    ReturnDirectly map[string]bool
-}
-```
-
----
-
-## ChatModelAgentState
-
-`ChatModelAgentState` 表示对话过程中聊天模型 agent 的状态。这是 `ChatModelAgentMiddleware` 和 `AgentMiddleware` 回调的主要状态类型。
-
-```go
-type ChatModelAgentState struct {
-    // Messages 包含当前对话会话中的所有消息
-    Messages []Message
-}
-```
-
----
-
-## ToolContext
-
-`ToolContext` 提供被包装工具的元数据。在请求时创建，包含当前工具调用的信息。
-
-```go
-type ToolContext struct {
-    // Name 是工具名称
-    Name string
-
-    // CallID 是此特定工具调用的唯一标识符
-    CallID string
-}
-```
-
-### 使用示例：工具调用包装
-
-```go
-func (h *MyHandler) WrapInvokableToolCall(ctx context.Context, endpoint adk.InvokableToolCallEndpoint, tCtx *adk.ToolContext) (adk.InvokableToolCallEndpoint, error) {
-    return func(ctx context.Context, argumentsInJSON string, opts ...tool.Option) (string, error) {
-        log.Printf("Tool %s (call %s) starting with args: %s", tCtx.Name, tCtx.CallID, argumentsInJSON)
-        
-        result, err := endpoint(ctx, argumentsInJSON, opts...)
-        
-        if err != nil {
-            log.Printf("Tool %s failed: %v", tCtx.Name, err)
-            return "", err
-        }
-        
-        log.Printf("Tool %s completed with result: %s", tCtx.Name, result)
-        return result, nil
-    }, nil
-}
-```
-
----
-
-## ModelContext
-
-`ModelContext` 包含传递给 `WrapModel` 的上下文信息。在请求时创建，包含当前模型调用的工具配置。
-
-```go
-type ModelContext struct {
-    // Tools 是当前配置给 agent 的工具列表
-    // 在请求时填充，包含将发送给模型的工具
-    Tools []*schema.ToolInfo
-
-    // ModelRetryConfig 包含模型的重试配置
-    // 在请求时从 agent 的 ModelRetryConfig 填充
-    // 用于 EventSenderModelWrapper 适当地包装流错误
-    ModelRetryConfig *ModelRetryConfig
-}
-```
-
-### 使用示例：模型包装
-
-```go
-func (h *MyHandler) WrapModel(ctx context.Context, m model.BaseChatModel, mc *adk.ModelContext) (model.BaseChatModel, error) {
-    return &myModelWrapper{
-        inner: m,
-        tools: mc.Tools,
-    }, nil
-}
-
-type myModelWrapper struct {
-    inner model.BaseChatModel
-    tools []*schema.ToolInfo
-}
-
-func (w *myModelWrapper) Generate(ctx context.Context, msgs []*schema.Message, opts ...model.Option) (*schema.Message, error) {
-    log.Printf("Model called with %d tools", len(w.tools))
-    return w.inner.Generate(ctx, msgs, opts...)
-}
-
-func (w *myModelWrapper) Stream(ctx context.Context, msgs []*schema.Message, opts ...model.Option) (*schema.StreamReader[*schema.Message], error) {
-    return w.inner.Stream(ctx, msgs, opts...)
-}
-```
-
----
-
-## 运行时本地存储 API
-
-`SetRunLocalValue`、`GetRunLocalValue` 和 `DeleteRunLocalValue` 提供在当前 agent Run() 调用期间存储、获取和删除值的能力。
-
-```go
-// SetRunLocalValue 设置一个在当前 agent Run() 调用期间持久化的键值对
-// 值的作用域限于此特定执行，不会在不同的 Run() 调用或 agent 实例之间共享
-//
-// 存储在这里的值与中断/恢复周期兼容 - 它们会被序列化并在 agent 恢复时还原
-// 对于自定义类型，必须在 init() 函数中使用 schema.RegisterName[T]() 注册以确保正确序列化
-//
-// 此函数只能在 agent 执行期间从 ChatModelAgentMiddleware 内部调用
-// 如果在 agent 执行上下文之外调用，返回错误
-func SetRunLocalValue(ctx context.Context, key string, value any) error
-
-// GetRunLocalValue 获取在当前 agent Run() 调用期间设置的值
-// 值的作用域限于此特定执行，不会在不同的 Run() 调用或 agent 实例之间共享
-//
-// 通过 SetRunLocalValue 存储的值与中断/恢复周期兼容 - 它们会被序列化并在 agent 恢复时还原
-// 对于自定义类型，必须在 init() 函数中使用 schema.RegisterName[T]() 注册以确保正确序列化
-//
-// 此函数只能在 agent 执行期间从 ChatModelAgentMiddleware 内部调用
-// 如果找到值返回 (value, true, nil)，如果未找到返回 (nil, false, nil)，
-// 如果在 agent 执行上下文之外调用返回错误
-func GetRunLocalValue(ctx context.Context, key string) (any, bool, error)
-
-// DeleteRunLocalValue 删除在当前 agent Run() 调用期间设置的值
-//
-// 此函数只能在 agent 执行期间从 ChatModelAgentMiddleware 内部调用
-// 如果在 agent 执行上下文之外调用，返回错误
-func DeleteRunLocalValue(ctx context.Context, key string) error
-```
-
-### 使用示例：跨 handler 点共享数据
-
-```go
-func init() {
-    schema.RegisterName[*MyCustomData]("my_package.MyCustomData")
-}
-
-type MyCustomData struct {
-    Count int
-    Name  string
-}
-
-type MyHandler struct {
-    *adk.BaseChatModelAgentMiddleware
-}
-
-func (h *MyHandler) WrapInvokableToolCall(ctx context.Context, endpoint adk.InvokableToolCallEndpoint, tCtx *adk.ToolContext) (adk.InvokableToolCallEndpoint, error) {
-    return func(ctx context.Context, argumentsInJSON string, opts ...tool.Option) (string, error) {
-        result, err := endpoint(ctx, argumentsInJSON, opts...)
-        
-        data := &MyCustomData{Count: 1, Name: tCtx.Name}
-        if err := adk.SetRunLocalValue(ctx, "my_handler.last_tool", data); err != nil {
-            log.Printf("Failed to set run local value: %v", err)
-        }
-        
-        return result, err
-    }, nil
-}
-
-func (h *MyHandler) AfterModelRewriteState(ctx context.Context, state *adk.ChatModelAgentState, mc *adk.ModelContext) (context.Context, *adk.ChatModelAgentState, error) {
-    if val, found, err := adk.GetRunLocalValue(ctx, "my_handler.last_tool"); err == nil && found {
-        if data, ok := val.(*MyCustomData); ok {
-            log.Printf("Last tool was: %s (count: %d)", data.Name, data.Count)
-        }
-    }
-    return ctx, state, nil
-}
-```
-
----
-
-## SendEvent API
-
-`SendEvent` 允许在 agent 执行期间向事件流发送自定义 `AgentEvent`。
-
-```go
-// SendEvent 在 agent 执行期间向事件流发送自定义 AgentEvent
-// 允许 ChatModelAgentMiddleware 实现发出自定义事件，
-// 这些事件将被遍历 agent 事件流的调用者接收
-//
-// 此函数只能在 agent 执行期间从 ChatModelAgentMiddleware 内部调用
-// 如果在 agent 执行上下文之外调用，返回错误
-func SendEvent(ctx context.Context, event *AgentEvent) error
-```
-
----
-
-## State 类型（即将弃用）
-
-`State` 保存 agent 运行时状态，包括消息和用户可扩展存储。
-
-**⚠️ 弃用警告：** 此类型将在 v1.0.0 中设为未导出。请在 `ChatModelAgentMiddleware` 和 `AgentMiddleware` 回调中使用 `ChatModelAgentState`。不建议直接使用 `compose.ProcessState[*State]`，该用法将在 v1.0.0 中停止工作；请使用 handler API。
-
-```go
-type State struct {
-    Messages []Message
-    extra    map[string]any  // 未导出，通过 SetRunLocalValue/GetRunLocalValue 访问
-
-    // 以下为内部字段 - 请勿直接访问
-    // 为与现有 checkpoint 向后兼容而保持导出
-    ReturnDirectlyToolCallID string
-    ToolGenActions           map[string]*AgentAction
-    AgentName                string
-    RemainingIterations      int
-
-    internals map[string]any
-}
-```
-
----
-
-## 架构图
-
-下图展示了 `ChatModelAgentMiddleware` 在 `ChatModelAgent` 执行过程中的工作原理：
-
-```
-Agent.Run(input)
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────────────┐
-│  BeforeAgent(ctx, *ChatModelAgentContext)                               │
-│    输入: 当前 Instruction、Tools 等 Agent 运行环境                          │
-│    输出: 修改后的 Agent 运行环境                                         │
-│    作用: Run 开始时调用一次，修改整个 Run 生命周期的配置                   │
-└─────────────────────────────────────────────────────────────────────────┘
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────────────┐
-│                          ReAct Loop                                     │
-│  ┌───────────────────────────────────────────────────────────────────┐  │
-│  │                                                                   │  │
-│  │  ┌─────────────────────────────────────────────────────────────┐  │  │
-│  │  │  BeforeModelRewriteState(ctx, *ChatModelAgentState, *MC)    │  │  │
-│  │  │    输入: 消息历史等持久化状态，以及 Model 运行环境            │  │  │
-│  │  │    输出: 修改后的持久化状态，返回新 ctx                       │  │  │
-│  │  │    作用: 修改跨 iteration 的持久化状态（主要是消息列表）      │  │  │
-│  │  └─────────────────────────────────────────────────────────────┘  │  │
-│  │                            │                                      │  │
-│  │                            ▼                                      │  │
-│  │  ┌─────────────────────────────────────────────────────────────┐  │  │
-│  │  │  WrapModel(ctx, BaseChatModel, *ModelContext)               │  │  │
-│  │  │    输入: 被 wrap 的 ChatModel，以及 Model 运行环境           │  │  │
-│  │  │    输出: 包装后的 Model (洋葱模型)                           │  │  │
-│  │  │    作用: 修改单次 Model 请求的输入、输出和配置               │  │  │
-│  │  │                         │                                   │  │  │
-│  │  │                         ▼                                   │  │  │
-│  │  │                 ┌───────────────┐                           │  │  │
-│  │  │                 │    Model      │                           │  │  │
-│  │  │                 │ Generate/Stream│                          │  │  │
-│  │  │                 └───────────────┘                           │  │  │
-│  │  └─────────────────────────────────────────────────────────────┘  │  │
-│  │                            │                                      │  │
-│  │                            ▼                                      │  │
-│  │  ┌─────────────────────────────────────────────────────────────┐  │  │
-│  │  │  AfterModelRewriteState(ctx, *ChatModelAgentState, *MC)     │  │  │
-│  │  │    输入: 消息历史等持久化状态（含 Model 响应），             │  │  │
-│  │  │          以及 Model 运行环境                                │  │  │
-│  │  │    输出: 修改后的持久化状态                                  │  │  │
-│  │  │    作用: 修改跨 iteration 的持久化状态（主要是消息列表）     │  │  │
-│  │  └─────────────────────────────────────────────────────────────┘  │  │
-│  │                            │                                      │  │
-│  │                            ▼                                      │  │
-│  │                  ┌──────────────────┐                             │  │
-│  │                  │ Model 返回内容?   │                            │  │
-│  │                  └──────────────────┘                             │  │
-│  │                     │            │                                │  │
-│  │            最终响应 │            │ ToolCalls                      │  │
-│  │                     │            ▼                                │  │
-│  │                     │  ┌─────────────────────────────────────┐    │  │
-│  │                     │  │  WrapInvokableToolCall / WrapStream │    │  │
-│  │                     │  │  ableToolCall(ctx, endpoint, *TC)   │    │  │
-│  │                     │  │    输入: 被 wrap 的 Tool 以及       │    │  │
-│  │                     │  │          Tool 运行环境              │    │  │
-│  │                     │  │    输出: 包装后的 endpoint (洋葱模型)│    │  │
-│  │                     │  │    作用: 修改单次 Tool 请求的       │    │  │
-│  │                     │  │          输入、输出和配置           │    │  │
-│  │                     │  │                  │                  │    │  │
-│  │                     │  │                  ▼                  │    │  │
-│  │                     │  │          ┌─────────────┐            │    │  │
-│  │                     │  │          │ Tool.Run()  │            │    │  │
-│  │                     │  │          └─────────────┘            │    │  │
-│  │                     │  └─────────────────────────────────────┘    │  │
-│  │                     │            │                                │  │
-│  │                     │            │ (结果加入 Messages)            │  │
-│  │                     │            │                                │  │
-│  │                     │  ┌─────────┘                                │  │
-│  │                     │  │                                          │  │
-│  │                     │  └──────────► 继续循环                      │  │
-│  │                     │                                             │  │
-│  └─────────────────────┼─────────────────────────────────────────────┘  │
-│                        │                                                │
-│                        ▼                                                │
-│               循环直到完成或达到 maxIterations                           │
-└─────────────────────────────────────────────────────────────────────────┘
-                                  │
-                                  ▼
-                          Agent.Run() 结束
-```
-
-### Handler 方法说明
-
-<table>
-<tr><td>方法</td><td>输入</td><td>输出</td><td>作用范围</td></tr>
-<tr><td><pre>BeforeAgent</pre></td><td>Agent 运行环境 (<pre>*ChatModelAgentContext</pre>)</td><td>修改后的 Agent 运行环境</td><td>整个 Run 生命周期，仅调用一次</td></tr>
-<tr><td><pre>BeforeModelRewriteState</pre></td><td>持久化状态 + Model 运行环境</td><td>修改后的持久化状态</td><td>跨 iteration 的持久化状态（消息列表）</td></tr>
-<tr><td><pre>WrapModel</pre></td><td>被 wrap 的 ChatModel + Model 运行环境</td><td>包装后的 Model</td><td>单次 Model 请求的输入、输出和配置</td></tr>
-<tr><td><pre>AfterModelRewriteState</pre></td><td>持久化状态（含响应）+ Model 运行环境</td><td>修改后的持久化状态</td><td>跨 iteration 的持久化状态（消息列表）</td></tr>
-<tr><td><pre>WrapInvokableToolCall</pre></td><td>被 wrap 的 Tool + Tool 运行环境</td><td>包装后的 endpoint</td><td>单次 Tool 请求的输入、输出和配置</td></tr>
-<tr><td><pre>WrapStreamableToolCall</pre></td><td>被 wrap 的 Tool + Tool 运行环境</td><td>包装后的 endpoint</td><td>单次 Tool 请求的输入、输出和配置</td></tr>
-</table>
-
----
-
-## 执行顺序
-
-### Model 调用生命周期（从外到内的 wrapper 链）
-
-1. `AgentMiddleware.BeforeChatModel`（hook，在模型调用前运行）
-2. `ChatModelAgentMiddleware.BeforeModelRewriteState`（hook，可在模型调用前修改状态）
-3. `retryModelWrapper`（内部 - 失败时重试，如已配置）
-4. `eventSenderModelWrapper` 预处理（内部 - 准备事件发送）
-5. `ChatModelAgentMiddleware.WrapModel` 预处理（wrapper，在请求时包装，先注册的先运行）
-6. `callbackInjectionModelWrapper`（内部 - 如未启用则注入回调）
-7. `Model.Generate/Stream`
-8. `callbackInjectionModelWrapper` 后处理
-9. `ChatModelAgentMiddleware.WrapModel` 后处理（wrapper，先注册的后运行）
-10. `eventSenderModelWrapper` 后处理（内部 - 发送模型响应事件）
-11. `retryModelWrapper` 后处理（内部 - 处理重试逻辑）
-12. `ChatModelAgentMiddleware.AfterModelRewriteState`（hook，可在模型调用后修改状态）
-13. `AgentMiddleware.AfterChatModel`（hook，在模型调用后运行）
-
-### Tool 调用生命周期（从外到内）
-
-1. `eventSenderToolHandler`（内部 ToolMiddleware - 在所有处理后发送工具结果事件）
-2. `ToolsConfig.ToolCallMiddlewares`（ToolMiddleware）
-3. `AgentMiddleware.WrapToolCall`（ToolMiddleware）
-4. `ChatModelAgentMiddleware.WrapInvokableToolCall/WrapStreamableToolCall`（在请求时包装，先注册的在最外层）
-5. `Tool.InvokableRun/StreamableRun`
-
----
-
-## 迁移指南
-
-### 从 AgentMiddleware 迁移到 ChatModelAgentMiddleware
-
-**之前（AgentMiddleware）：**
-
-```go
-middleware := adk.AgentMiddleware{
-    BeforeChatModel: func(ctx context.Context, state *adk.ChatModelAgentState) error {
-        return nil
-    },
-}
-```
-
-**之后（ChatModelAgentMiddleware）：**
-
-```go
-type MyHandler struct {
-    *adk.BaseChatModelAgentMiddleware
-}
-
-func (h *MyHandler) BeforeModelRewriteState(ctx context.Context, state *adk.ChatModelAgentState, mc *adk.ModelContext) (context.Context, *adk.ChatModelAgentState, error) {
-    newCtx := context.WithValue(ctx, myKey, myValue)
-    return newCtx, state, nil
-}
-```
-
-### 从 compose.ProcessState[*State] 迁移
-
-**之前：**
-
-```go
-compose.ProcessState(ctx, func(_ context.Context, st *adk.State) error {
-    st.Extra["myKey"] = myValue
-    return nil
-})
-```
-
-**之后（使用 SetRunLocalValue/GetRunLocalValue）：**
-
-```go
-if err := adk.SetRunLocalValue(ctx, "myKey", myValue); err != nil {
-    return ctx, state, err
-}
-
-if val, found, err := adk.GetRunLocalValue(ctx, "myKey"); err == nil && found {
-}
-```

docs/Eino/docs/core_modules/eino_adk/Eino_ADK_ChatModelAgentMiddleware/filesystem_backend/_index.md

@@ -1,175 +0,0 @@
----
-Description: ""
-date: "2026-03-24"
-lastmod: ""
-tags: []
-title: FileSystem Backend
-weight: 1
----
-
-> 💡
-> Package: [github.com/cloudwego/eino/adk/filesystem](https://github.com/cloudwego/eino/tree/main/adk/filesystem)
-
-## 背景与目的
-
-在 AI Agent 场景中，Agent 往往需要与文件系统交互——读取文件内容、搜索代码、编辑配置、执行命令等。然而，不同的运行环境对文件系统的访问方式差异很大：
-
-- **本地开发环境**：直接操作本机文件系统，零配置即可使用
-- **云端沙箱环境**：通过远程 API 操作隔离的沙箱文件系统，需要认证和网络通信
-- **测试环境**：需要内存级别的模拟文件系统，无需真实磁盘 I/O
-- **自定义存储**：可能需要对接 OSS、数据库等非传统文件系统
-
-如果每种环境都各自实现一套文件操作逻辑，会导致 Middleware 和 Agent 代码与底层存储实现耦合，难以复用和测试。
-
-为了解决这一问题，Eino ADK 抽象出 `filesystem.Backend` 接口，作为**统一的文件系统操作协议**。它的设计目标是：
-
-1. **解耦存储与业务**：Middleware 只依赖 Backend 接口，不关心底层是本地磁盘、远程沙箱还是内存模拟
-2. **可插拔替换**：通过切换 Backend 实现，同一个 Agent 可以在不同环境中运行，无需修改任何业务代码
-3. **易于测试**：内置 `InMemoryBackend` 实现，方便在单元测试中模拟文件系统行为
-4. **可扩展性**：所有方法使用结构体参数，未来新增字段不会破坏已有实现的兼容性
-
-## Backend 接口
-
-```go
-type Backend interface {
-    // 列出指定路径下的文件和目录信息
-    LsInfo(ctx context.Context, req *LsInfoRequest) ([]FileInfo, error)
-    // 读取文件内容，支持按行分页（offset + limit）
-    Read(ctx context.Context, req *ReadRequest) (*FileContent, error)
-    // 在指定路径中搜索匹配 pattern 的内容，返回匹配列表
-    GrepRaw(ctx context.Context, req *GrepRequest) ([]GrepMatch, error)
-    // 根据 glob pattern 和路径查找匹配的文件
-    GlobInfo(ctx context.Context, req *GlobInfoRequest) ([]FileInfo, error)
-    // 写入或创建文件
-    Write(ctx context.Context, req *WriteRequest) error
-    // 替换文件中的字符串内容
-    Edit(ctx context.Context, req *EditRequest) error
-}
-```
-
-### 扩展接口
-
-除核心文件操作外，Backend 还可以选择性地实现 Shell 命令执行能力：
-
-```go
-// Shell 提供同步命令执行能力
-type Shell interface {
-    Execute(ctx context.Context, input *ExecuteRequest) (result *ExecuteResponse, err error)
-}
-
-// StreamingShell 提供流式命令执行能力，适用于长时间运行的命令
-type StreamingShell interface {
-    ExecuteStreaming(ctx context.Context, input *ExecuteRequest) (result *schema.StreamReader[*ExecuteResponse], err error)
-}
-```
-
-当 Backend 同时实现了 `Shell` 或 `StreamingShell` 接口时，Filesystem Middleware 会额外注册 `execute` 工具，允许 Agent 执行 shell 命令。
-
-### 核心数据类型
-
-<table>
-<tr><td>类型</td><td>描述</td></tr>
-<tr><td><pre>FileInfo</pre></td><td>文件/目录信息：路径、是否目录、大小、修改时间</td></tr>
-<tr><td><pre>FileContent</pre></td><td>文件内容 + 行号信息</td></tr>
-<tr><td><pre>GrepMatch</pre></td><td>搜索匹配结果：内容、路径、行号</td></tr>
-<tr><td><pre>ReadRequest</pre></td><td>读取请求：路径、offset（从第几行开始，1-based）、limit（读取行数）</td></tr>
-<tr><td><pre>GrepRequest</pre></td><td>搜索请求：pattern（支持正则）、路径、glob 过滤、文件类型过滤等</td></tr>
-<tr><td><pre>WriteRequest</pre></td><td>写入请求：路径、内容</td></tr>
-<tr><td><pre>EditRequest</pre></td><td>编辑请求：路径、旧字符串、新字符串、是否全部替换</td></tr>
-<tr><td><pre>ExecuteRequest</pre></td><td>命令执行请求：命令字符串、是否后台运行</td></tr>
-<tr><td><pre>ExecuteResponse</pre></td><td>命令执行结果：输出内容、退出码、是否被截断</td></tr>
-</table>
-
-## 内置实现：InMemoryBackend
-
-`InMemoryBackend` 是框架内置的 Backend 实现，将文件存储在内存 map 中，主要用于：
-
-- **单元测试**：无需真实文件系统即可测试 Agent 和 Middleware 的文件操作逻辑
-- **轻量场景**：不需要持久化的临时文件操作
-- **工具结果卸载**：Filesystem Middleware 的大型工具结果卸载功能默认使用 InMemoryBackend 存储
-
-```go
-import "github.com/cloudwego/eino/adk/filesystem"
-
-ctx := context.Background()
-backend := filesystem.NewInMemoryBackend()
-
-// 写入文件
-err := backend.Write(ctx, &filesystem.WriteRequest{
-    FilePath: "/example/test.txt",
-    Content:  "Hello, World!\nLine 2\nLine 3",
-})
-
-// 读取文件（支持分页）
-content, err := backend.Read(ctx, &filesystem.ReadRequest{
-    FilePath: "/example/test.txt",
-    Offset:   1,
-    Limit:    10,
-})
-
-// 列出目录
-files, err := backend.LsInfo(ctx, &filesystem.LsInfoRequest{
-    Path: "/example",
-})
-
-// 搜索内容（支持正则）
-matches, err := backend.GrepRaw(ctx, &filesystem.GrepRequest{
-    Pattern: "Hello",
-    Path:    "/example",
-})
-
-// 编辑文件
-err = backend.Edit(ctx, &filesystem.EditRequest{
-    FilePath:   "/example/test.txt",
-    OldString:  "Hello",
-    NewString:  "Hi",
-    ReplaceAll: false,
-})
-```
-
-特性：
-
-- 线程安全（基于 `sync.RWMutex`）
-- GrepRaw 支持正则匹配、大小写不敏感、上下文行数等高级选项
-- GrepRaw 内部采用并行处理（最多 10 个 worker）
-
-## 外部实现
-
-以下 Backend 实现位于 [eino-ext](https://github.com/cloudwego/eino-ext) 仓库：
-
-- **Local Backend** — 本地文件系统实现，直接操作本机磁盘，零配置开箱即用
-- **Ark Agentkit Sandbox Backend** — 火山引擎 Agentkit 远程沙箱实现，在隔离的云端环境中执行文件操作
-
-### 实现对比
-
-<table>
-<tr><td>特性</td><td>InMemory</td><td>Local</td><td>Agentkit Sandbox</td></tr>
-<tr><td>执行模型</td><td>内存</td><td>本地直接</td><td>远程沙箱</td></tr>
-<tr><td>网络依赖</td><td>无</td><td>无</td><td>需要</td></tr>
-<tr><td>配置复杂度</td><td>零配置</td><td>零配置</td><td>需要凭证</td></tr>
-<tr><td>持久化</td><td>否</td><td>是</td><td>是</td></tr>
-<tr><td>Shell 支持</td><td>否</td><td>支持（含流式）</td><td>支持</td></tr>
-<tr><td>适用场景</td><td>测试/临时</td><td>开发/本地环境</td><td>多租户/生产环境</td></tr>
-</table>
-
-## 自定义实现
-
-如需对接自定义存储（如 OSS、数据库等），只需实现 `Backend` 接口即可：
-
-```go
-type MyBackend struct {
-    // ...
-}
-
-func (b *MyBackend) LsInfo(ctx context.Context, req *filesystem.LsInfoRequest) ([]filesystem.FileInfo, error) {
-    // 自定义实现
-}
-
-func (b *MyBackend) Read(ctx context.Context, req *filesystem.ReadRequest) (*filesystem.FileContent, error) {
-    // 自定义实现
-}
-
-// ... 实现其余方法
-```
-
-如果需要支持命令执行，还可以额外实现 `Shell` 或 `StreamingShell` 接口。

docs/Eino/docs/core_modules/eino_adk/Eino_ADK_ChatModelAgentMiddleware/filesystem_backend/backend_ark_agentkit_sandbox.md

@@ -1,202 +0,0 @@
----
-Description: ""
-date: "2026-03-24"
-lastmod: ""
-tags: []
-title: Ark Agentkit Sandbox
-weight: 1
----
-
-## Agentkit Sandbox Backend
-
-Package: `github.com/cloudwego/eino-ext/adk/backend/agentkit`
-
-注意：如果 eino 版本是 v0.8.0 及以上，需要使用 ark agentkit backend 的[ adk/backend/agentkit/v0.2.1](https://github.com/cloudwego/eino-ext/releases/tag/adk%2Fbackend%2Fagentkit%2Fv0.2.1) 版本。
-
-### 概述
-
-Agentkit Sandbox Backend 是 EINO ADK FileSystem 的远程沙箱实现，通过火山引擎 Agentkit 服务在隔离的云端环境中执行文件系统操作。
-
-#### 核心特性
-
-- 安全隔离 - 所有操作在远程沙箱环境中执行
-- 会话管理 - 支持会话隔离与可配置的 TTL
-- 请求签名 - 自动使用 AK/SK 进行火山引擎 API 认证
-
-### 安装
-
-```bash
-go get github.com/cloudwego/eino-ext/adk/backend/agentkit
-```
-
-### 配置
-
-#### 环境变量
-
-```bash
-export VOLC_ACCESS_KEY_ID="your_access_key"
-export VOLC_SECRET_ACCESS_KEY="your_secret_key"
-export VOLC_TOOL_ID="your_tool_id"
-```
-
-#### Config 结构
-
-```go
-type Config struct {
-    // 必填
-    AccessKeyID     string  // 访问密钥 ID
-    SecretAccessKey string  // 访问密钥 Secret
-    ToolID          string  // 沙箱工具 ID
-
-    // 可选
-    UserSessionID    string        // 用户会话 ID，用于隔离
-    Region           Region        // 区域，默认 cn-beijing
-    SessionTTL       int           // 会话 TTL（60-86400 秒）
-    ExecutionTimeout int           // 命令执行超时
-    HTTPClient       *http.Client  // 自定义 HTTP 客户端
-}
-```
-
-### 快速开始
-
-#### 基本用法
-
-```go
-import (
-    "context"
-    "os"
-    "time"
-
-    "github.com/cloudwego/eino-ext/adk/backend/agentkit"
-    "github.com/cloudwego/eino/adk/filesystem"
-)
-
-func main() {
-    ctx := context.Background()
-
-    backend, err := agentkit.NewSandboxToolBackend(&agentkit.Config{
-        AccessKeyID:     os.Getenv("VOLC_ACCESS_KEY_ID"),
-        SecretAccessKey: os.Getenv("VOLC_SECRET_ACCESS_KEY"),
-        ToolID:          os.Getenv("VOLC_TOOL_ID"),
-        UserSessionID:   "session-" + time.Now().Format("20060102-150405"),
-        Region:          agentkit.RegionOfBeijing,
-    })
-    if err != nil {
-        panic(err)
-    }
-
-    // 写入文件
-    err = backend.Write(ctx, &filesystem.WriteRequest{
-        FilePath: "/home/gem/hello.txt",
-        Content:  "Hello, Sandbox!",
-    })
-
-    // 读取文件
-    fContent, err := backend.Read(ctx, &filesystem.ReadRequest{
-        FilePath: "/home/gem/hello.txt",
-    })
-    fmt.Println(fContent.Content)
-}
-```
-
-#### 与 Agent 集成
-
-```go
-import (
-    "github.com/cloudwego/eino/adk"
-    fsMiddleware "github.com/cloudwego/eino/adk/middlewares/filesystem"
-)
-
-// 创建 Backend
-backend, _ := agentkit.NewSandboxToolBackend(config)
-
-// 创建 Middleware
-middleware, _ := fsMiddleware.New(ctx, &fsMiddleware.Config{
-    Backend: backend,
-    Shell: backend,
-})
-
-// 创建 Agent
-agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    Name:        "SandboxAgent",
-    Description: "具有安全文件系统访问能力的 AI Agent",
-    Model:       chatModel,
-    Handlers:    []adk.ChatModelAgentMiddleware{middleware},
-})
-```
-
-### API 参考
-
-<table>
-<tr><td>方法</td><td>描述</td></tr>
-<tr><td>LsInfo</td><td>列出目录内容</td></tr>
-<tr><td>Read</td><td>读取文件内容（支持分页）</td></tr>
-<tr><td>Write</td><td>创建新文件（已存在则报错）</td></tr>
-<tr><td>Edit</td><td>替换文件内容</td></tr>
-<tr><td>GrepRaw</td><td>搜索文件内容</td></tr>
-<tr><td>GlobInfo</td><td>按模式查找文件</td></tr>
-<tr><td>Execute</td><td>执行 shell 命令</td></tr>
-</table>
-
-#### 示例
-
-```go
-// 列出目录
-files, _ := backend.LsInfo(ctx, &filesystem.LsInfoRequest{
-    Path: "/home/gem",
-})
-
-// 读取文件（分页）
-fcontent, _ := backend.Read(ctx, &filesystem.ReadRequest{
-    FilePath: "/home/gem/file.txt",
-    Offset:   0,
-    Limit:    100,
-})
-
-// 搜索内容
-matches, _ := backend.GrepRaw(ctx, &filesystem.GrepRequest{
-    Path:    "/home/gem",
-    Pattern: "keyword",
-    Glob:    "*.txt",
-})
-
-// 查找文件
-files, _ := backend.GlobInfo(ctx, &filesystem.GlobInfoRequest{
-    Path:    "/home/gem",
-    Pattern: "**/*.txt",
-})
-
-// 编辑文件
-backend.Edit(ctx, &filesystem.EditRequest{
-    FilePath:   "/home/gem/file.txt",
-    OldString:  "old",
-    NewString:  "new",
-    ReplaceAll: true,
-})
-
-// 执行命令
-result, _ := backend.Execute(ctx, &filesystem.ExecuteRequest{
-    Command: "ls -la /home/gem",
-})
-```
-
-### 与 Local Backend 对比
-
-<table>
-<tr><td>特性</td><td>Agentkit</td><td>Local</td></tr>
-<tr><td>执行模型</td><td>远程沙箱</td><td>本地直接</td></tr>
-<tr><td>网络依赖</td><td>需要</td><td>不需要</td></tr>
-<tr><td>配置复杂度</td><td>需要凭证</td><td>零配置</td></tr>
-<tr><td>安全模型</td><td>隔离沙箱</td><td>OS 权限</td></tr>
-<tr><td>适用场景</td><td>多租户/生产环境</td><td>开发/本地环境</td></tr>
-</table>
-
-### 常见问题
-
-**Q: 认证失败**
-
-检查环境变量、AK/SK 是否匹配、账户是否有 Ark Sandbox 权限。
-
-**Q: 请求超时**
-
-增加 ExecutionTimeout 或 HTTPClient.Timeout 配置。

docs/Eino/docs/core_modules/eino_adk/Eino_ADK_ChatModelAgentMiddleware/filesystem_backend/backend_本地文件系统.md

@@ -1,231 +0,0 @@
----
-Description: ""
-date: "2026-03-24"
-lastmod: ""
-tags: []
-title: 本地文件系统
-weight: 2
----
-
-## Local Backend
-
-Package: `github.com/cloudwego/eino-ext/adk/backend/local`
-
-注意：如果 eino 版本是 v0.8.0 及以上，需要使用 local backend 的 [adk/backend/local/v0.2.1](https://github.com/cloudwego/eino-ext/releases/tag/adk%2Fbackend%2Flocal%2Fv0.2.1) 版本。
-
-### 概述
-
-Local Backend 是 EINO ADK FileSystem 的本地文件系统实现，直接操作本机文件系统，提供原生性能和零配置体验。
-
-#### 核心特性
-
-- 零配置 - 开箱即用
-- 原生性能 - 直接文件系统访问，无网络开销
-- 路径安全 - 强制使用绝对路径
-- 流式执行 - 支持命令输出实时流
-- 命令验证 - 可选的安全验证钩子
-
-### 安装
-
-```bash
-go get github.com/cloudwego/eino-ext/adk/backend/local
-```
-
-### 配置
-
-```go
-type Config struct {
-    // 可选: 命令验证函数，用于 Execute() 安全控制
-    ValidateCommand func(string) error
-}
-```
-
-### 快速开始
-
-#### 基本用法
-
-```go
-import (
-    "context"
-
-    "github.com/cloudwego/eino-ext/adk/backend/local"
-    "github.com/cloudwego/eino/adk/filesystem"
-)
-
-func main() {
-    ctx := context.Background()
-
-    backend, err := local.NewBackend(ctx, &local.Config{})
-    if err != nil {
-        panic(err)
-    }
-
-    // 写入文件（必须是绝对路径）
-    err = backend.Write(ctx, &filesystem.WriteRequest{
-        FilePath: "/tmp/hello.txt",
-        Content:  "Hello, Local Backend!",
-    })
-
-    // 读取文件
-    fcontent, err := backend.Read(ctx, &filesystem.ReadRequest{
-        FilePath: "/tmp/hello.txt",
-    })
-    fmt.Println(fcontent.Content)
-}
-```
-
-#### 带命令验证
-
-```go
-func validateCommand(cmd string) error {
-    allowed := map[string]bool{"ls": true, "cat": true, "grep": true}
-    parts := strings.Fields(cmd)
-    if len(parts) == 0 || !allowed[parts[0]] {
-        return fmt.Errorf("command not allowed: %s", parts[0])
-    }
-    return nil
-}
-
-backend, _ := local.NewBackend(ctx, &local.Config{
-    ValidateCommand: validateCommand,
-})
-```
-
-#### 与 Agent 集成
-
-```go
-import (
-    "github.com/cloudwego/eino/adk"
-    fsMiddleware "github.com/cloudwego/eino/adk/middlewares/filesystem"
-)
-
-// 创建 Backend
-backend, _ := local.NewBackend(ctx, &local.Config{})
-
-// 创建 Middleware
-middleware, _ := fsMiddleware.New(ctx, &fsMiddleware.Config{
-    Backend: backend,
-    StreamingShell: backend,
-})
-
-// 创建 Agent
-agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    Name:        "LocalFileAgent",
-    Description: "具有本地文件系统访问能力的 AI Agent",
-    Model:       chatModel,
-    Handlers:    []adk.ChatModelAgentMiddleware{middleware},
-})
-```
-
-### API 参考
-
-<table>
-<tr><td>方法</td><td>描述</td></tr>
-<tr><td>LsInfo</td><td>列出目录内容</td></tr>
-<tr><td>Read</td><td>读取文件内容（支持分页，默认 200 行）</td></tr>
-<tr><td>Write</td><td>创建新文件（已存在则报错）</td></tr>
-<tr><td>Edit</td><td>替换文件内容</td></tr>
-<tr><td>GrepRaw</td><td>搜索文件内容（字面量匹配）</td></tr>
-<tr><td>GlobInfo</td><td>按模式查找文件</td></tr>
-<tr><td>Execute</td><td>执行 shell 命令</td></tr>
-<tr><td>ExecuteStreaming</td><td>流式执行命令</td></tr>
-</table>
-
-#### 示例
-
-```go
-// 列出目录
-files, _ := backend.LsInfo(ctx, &filesystem.LsInfoRequest{
-    Path: "/home/user",
-})
-
-// 读取文件（分页）
-fcontent, _ := backend.Read(ctx, &filesystem.ReadRequest{
-    FilePath: "/path/to/file.txt",
-    Offset:   0,
-    Limit:    50,
-})
-
-// 搜索内容（字面量匹配，非正则）
-matches, _ := backend.GrepRaw(ctx, &filesystem.GrepRequest{
-    Path:    "/home/user/project",
-    Pattern: "TODO",
-    Glob:    "*.go",
-})
-
-// 查找文件
-files, _ := backend.GlobInfo(ctx, &filesystem.GlobInfoRequest{
-    Path:    "/home/user",
-    Pattern: "**/*.go",
-})
-
-// 编辑文件
-backend.Edit(ctx, &filesystem.EditRequest{
-    FilePath:   "/tmp/file.txt",
-    OldString:  "old",
-    NewString:  "new",
-    ReplaceAll: true,
-})
-
-// 执行命令
-result, _ := backend.Execute(ctx, &filesystem.ExecuteRequest{
-    Command: "ls -la /tmp",
-})
-
-// 流式执行
-reader, _ := backend.ExecuteStreaming(ctx, &filesystem.ExecuteRequest{
-    Command: "tail -f /var/log/app.log",
-})
-for {
-    resp, err := reader.Recv()
-    if err == io.EOF {
-        break
-    }
-    fmt.Print(resp.Stdout)
-}
-```
-
-### 路径要求
-
-所有路径必须是绝对路径（以 `/` 开头）：
-
-```go
-// 正确
-backend.Read(ctx, &filesystem.ReadRequest{FilePath: "/home/user/file.txt"})
-
-// 错误
-backend.Read(ctx, &filesystem.ReadRequest{FilePath: "./file.txt"})
-```
-
-转换相对路径：
-
-```go
-absPath, _ := filepath.Abs("./relative/path")
-```
-
-### 与 Agentkit Backend 对比
-
-<table>
-<tr><td>特性</td><td>Local</td><td>Agentkit</td></tr>
-<tr><td>执行模型</td><td>本地直接</td><td>远程沙箱</td></tr>
-<tr><td>网络依赖</td><td>无</td><td>需要</td></tr>
-<tr><td>配置复杂度</td><td>零配置</td><td>需要凭证</td></tr>
-<tr><td>安全模型</td><td>OS 权限</td><td>隔离沙箱</td></tr>
-<tr><td>流式输出</td><td>支持</td><td>不支持</td></tr>
-<tr><td>平台支持</td><td>Unix/Linux/macOS</td><td>任意</td></tr>
-<tr><td>适用场景</td><td>开发/本地环境</td><td>多租户/生产环境</td></tr>
-</table>
-
-### 常见问题
-
-**Q: 为什么运行 grep 命令报错  ripgrep (rg) is not installed or not in PATH. Please install it: ****[https://github.com/BurntSushi/ripgrep#installation](https://github.com/BurntSushi/ripgrep#installation)**
-
-local 的 Grep 命令默认依赖** ripgrep **指令，如系统没有预装 ripgrep 则需要通过文档安装 ripgrep
-
-**Q: GrepRaw 支持正则吗？**
-
-支持正则匹配，GrepRaw 底层使用的是 ripgrep 命令做的 Grep 操作
-
-**Q: Windows 支持吗？**
-
-不支持，依赖 `/bin/sh`。

docs/Eino/docs/core_modules/eino_adk/Eino_ADK_ChatModelAgentMiddleware/middleware_agentsmd.md

@@ -1,280 +0,0 @@
----
-Description: ""
-date: "2026-03-24"
-lastmod: ""
-tags: []
-title: AgentsMD
-weight: 9
----
-
-## 概述
-
-`agentsmd` 是 Eino ADK 提供的一个中间件，用于在每次模型调用时**自动将 Agents.md 文件内容注入到模型输入消息中**。注入是瞬态的——内容在模型调用时动态添加，不会持久化到会话状态中，因此**不会被摘要/压缩中间件处理**。
-
-**核心价值**：通过 Agents.md 文件为 Agent 定义系统级的行为指令和上下文信息（类似 Claude Code 的 CLAUDE.md），无需手动管理 system prompt 的拼接。
-
-**包路径**：`github.com/cloudwego/eino/adk/middlewares/agentsmd`
-
----
-
-## 快速开始
-
-### 最小化示例
-
-```go
-package main
-
-import (
-        "context"
-        "fmt"
-
-        "github.com/cloudwego/eino/adk"
-        "github.com/cloudwego/eino/adk/middlewares/agentsmd"
-)
-
-func main() {
-        ctx := context.Background()
-
-        // 1. 准备 Backend（文件读取后端）
-        backend := NewLocalFileBackend("/path/to/project")
-
-        // 2. 创建 agentsmd 中间件
-        mw, err := agentsmd.New(ctx, &agentsmd.Config{
-                Backend:       backend,
-                AgentsMDFiles: []string{"/home/user/project/agents.md"},
-        })
-        if err != nil {
-                panic(err)
-        }
-
-        // 3. 将中间件配置到 Agent
-        // agent := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-        //     Middlewares: []adk.ChatModelAgentMiddleware{mw},
-        // })
-        _ = mw
-        fmt.Println("agentsmd middleware created successfully")
-}
-```
-
----
-
-## 配置详解
-
-### Config 结构体
-
-```go
-type Config struct {
-    // Backend 提供文件访问能力，用于加载 Agents.md 文件。
-    // 可以使用本地文件系统、远程存储或任何其他后端实现。
-    // 必填。
-    Backend Backend
-
-    // AgentsMDFiles 指定要加载的 Agents.md 文件路径的有序列表。
-    // 文件按照给定顺序加载和注入。
-    // 文件内部支持 @import 语法进行递归引入（最大深度 5）。
-    AgentsMDFiles []string
-
-    // AllAgentsMDMaxBytes 限制所有加载的 Agents.md 内容的总字节大小。
-    // 文件按顺序加载；一旦累计大小超过此限制，剩余文件将被跳过。
-    // 每个单独的文件始终完整加载。
-    // 0 表示无限制。
-    AllAgentsMDMaxBytes int
-
-    // OnLoadWarning 是一个可选的回调函数，在加载过程中发生非致命错误时调用
-    // （如文件未找到、循环 @import、深度超限等）。
-    // 如果为 nil，警告通过 log.Printf 输出。
-    //
-    // 注意：Backend.Read 的非 os.ErrNotExist 错误（如权限被拒、I/O 错误）
-    // 不会被视为警告，而是会中止加载过程。
-    OnLoadWarning func(filePath string, err error)
-}
-```
-
-### 配置参数说明
-
-<table>
-<tr><td>参数</td><td>类型</td><td>必填</td><td>默认值</td><td>说明</td></tr>
-<tr><td><pre>Backend</pre></td><td><pre>Backend</pre></td><td>是</td><td>-</td><td>文件读取后端，负责实际的文件 I/O</td></tr>
-<tr><td><pre>AgentsMDFiles</pre></td><td><pre>[]string</pre></td><td>是</td><td>-</td><td>要加载的 Agents.md 文件路径列表（至少一个）</td></tr>
-<tr><td><pre>AllAgentsMDMaxBytes</pre></td><td><pre>int</pre></td><td>否</td><td><pre>0</pre>（无限制）</td><td>所有文件的总字节数上限</td></tr>
-<tr><td><pre>OnLoadWarning</pre></td><td><pre>func(string, error)</pre></td><td>否</td><td><pre>log.Printf</pre></td><td>非致命错误的回调函数</td></tr>
-</table>
-
----
-
-## Backend 接口
-
-### 接口定义
-
-```go
-type Backend interface {
-    // Read 读取文件内容。
-    // 如果文件不存在，实现应返回包装了 os.ErrNotExist 的 error
-    // （以便 errors.Is(err, os.ErrNotExist) 返回 true）。
-    // 这样 loader 可以静默跳过缺失文件并通过 OnLoadWarning 通知。
-    // 其他错误（如权限被拒、I/O 错误）会中止加载过程。
-    Read(ctx context.Context, req *ReadRequest) (*FileContent, error)
-}
-```
-
-### 类型定义
-
-```go
-// ReadRequest 定义读取文件的请求参数
-type ReadRequest struct {
-    FilePath string // 文件路径
-    Offset   int    // 起始行号（1-based）
-}
-
-// FileContent 定义文件内容的返回结构
-type FileContent struct {
-    Content string // 文件的文本内容
-}
-```
-
----
-
-## @import 语法
-
-Agents.md 文件支持 `@import` 语法，可以递归引入其他文件。
-
-### 语法格式
-
-在 Agents.md 文件中，使用 `@路径/文件名` 引用其他文件：
-
-```markdown
-# 项目指令
-
-你是一个代码助手。
-
-请参考以下规范：
-@rules/code-style.md
-@rules/api-conventions.md
-```
-
-### 规则
-
-1. **路径解析**：相对路径基于当前文件所在目录解析，绝对路径直接使用
-2. **最大递归深度**：5 层（超过后跳过并触发 `OnLoadWarning`）
-3. **循环引用检测**：自动检测并跳过循环引用（触发 `OnLoadWarning`）
-4. **全局去重**：同一文件不会被重复加载
-5. **支持的文件扩展名**（路径中不含 `/` 时）：`.md`, `.txt`, `.mdx`, `.yaml`, `.yml`, `.json`, `.toml`
-6. **误报过滤**：不含 `/` 且扩展名不在允许列表中的 `@引用` 会被忽略（避免将 `@someone` 或 `@example.com` 识别为导入）
-
-### @import 目录结构示例
-
-```
-project/
-├── Agents.md               # 主入口文件
-├── rules/
-│   ├── code-style.md       # 代码风格规范
-│   ├── api-conventions.md  # API 规范
-│   └── testing.md          # 测试规范
-└── context/
-    └── architecture.md     # 架构说明
-```
-
----
-
-## 工作原理
-
-### 注入流程
-
-```
-用户消息 + 历史消息
-       │
-       ▼
-┌─────────────────────┐
-│  agentsmd 中间件     │
-│  (WrapModel)        │
-│                     │
-│  1. 加载 Agents.md  │
-│  2. 缓存到 RunLocal │
-│  3. 生成注入消息     │
-└─────────────────────┘
-       │
-       ▼
-┌─────────────────────────────────────┐
-│  注入后的消息序列                    │
-│                                     │
-│  [System]  系统提示词               │
-│  [User]    ← Agents.md 内容注入    │  ← 插入在第一条 User 消息之前
-│  [User]    用户历史消息 1           │
-│  [Assistant] 助手回复 1             │
-│  [User]    用户当前消息             │
-└─────────────────────────────────────┘
-       │
-       ▼
-     模型调用 (Generate / Stream)
-```
-
-### 关键机制
-
-1. **瞬态注入**：Agents.md 内容仅在模型调用时临时插入，不写入 `ChatModelAgentState`，因此不会被摘要/压缩中间件处理
-2. **Run 级别缓存**：同一次 Agent `Run()` 中，Agents.md 内容加载后会缓存在 `RunLocalValue` 中，后续的模型调用（如多轮工具调用）直接复用缓存，避免重复读取
-3. **插入位置**：内容作为 `User` 角色消息插入在第一条 User 消息之前；如果没有 User 消息，则追加到末尾
-4. **国际化**：格式化输出自动适配中英文（根据系统语言环境）
-
----
-
-## 注意事项
-
-### 中间件顺序
-
-**推荐将 ****agentsmd**** 中间件放在 summarization/compression 中间件之后。** 这样可以确保 Agents.md 内容：
-
-- 不会被摘要中间件压缩掉
-- 每次模型调用都能获得完整的指令内容
-
-```go
-Middlewares: []adk.ChatModelAgentMiddleware{
-    summarizationMiddleware, // 先摘要
-    agentsMDMiddleware,      // 后注入 Agents.md
-}
-```
-
-### 错误处理
-
-<table>
-<tr><td>场景</td><td>行为</td></tr>
-<tr><td>文件不存在 (<pre>os.ErrNotExist</pre>)</td><td>跳过该文件，触发 <pre>OnLoadWarning</pre></td></tr>
-<tr><td>循环 <pre>@import</pre></td><td>跳过循环文件，触发 <pre>OnLoadWarning</pre></td></tr>
-<tr><td><pre>@import</pre> 深度超过 5 层</td><td>跳过，触发 <pre>OnLoadWarning</pre></td></tr>
-<tr><td>累计大小超过 <pre>AllAgentsMDMaxBytes</pre></td><td>跳过后续文件，触发 <pre>OnLoadWarning</pre>（第一个文件始终完整加载）</td></tr>
-<tr><td>权限被拒 / I/O 错误</td><td><strong>中止加载，返回 error</strong></td></tr>
-<tr><td>所有文件内容为空</td><td>不注入，原样传递输入消息</td></tr>
-</table>
-
-### Backend 实现要求
-
-- 文件不存在时**必须**返回 `os.ErrNotExist` 包裹的错误（`fmt.Errorf("... : %w", os.ErrNotExist)`），否则 loader 无法区分"文件缺失"和"真正的 I/O 错误"
-- `Read` 方法应当是并发安全的
-
-### 性能考虑
-
-- 合理设置 `AllAgentsMDMaxBytes`，避免注入过多内容占用模型上下文窗口
-- Agents.md 内容在每次 `Run()` 中只加载一次（Run 级别缓存），但**每次新的 ****Run()**** 都会重新加载**，因此文件内容的修改会在下次 Run 时生效
-- 避免在 Agents.md 中 `@import` 过多文件，递归深度上限为 5 层
-
-### Agents.md 编写建议
-
-- 保持内容精炼，只包含对模型行为真正有影响的指令
-- 使用 `@import` 拆分关注点（代码规范、API 规范、架构说明等）
-- 避免在 Agents.md 中包含大量代码示例或数据，以免浪费上下文窗口
-- 文件内容会被包裹在 `<system-reminder>` 标签中传递给模型，模型会将其视为系统级指令
-
----
-
-## FAQ
-
-**Q: Agents.md 的内容会被保存到对话历史中吗？**
-A: 不会。内容是在模型调用时动态注入的，不会写入 `ChatModelAgentState`，因此对话历史中不会出现 Agents.md 的内容。
-
-**Q: 如果某个 Agents.md 文件不存在会怎样？**
-A: 该文件会被跳过，触发 `OnLoadWarning` 回调（默认 `log.Printf`），不会导致整体加载失败。
-
-**Q: @import 的路径是相对于什么目录？**
-A: 相对于当前文件所在目录。例如 `/project/Agents.md` 中的 `@rules/style.md` 会解析为 `/project/rules/style.md`。
-
-**Q: 多个文件中 @import 了同一个文件会重复加载吗？**
-A: 不会。loader 维护了全局去重 map，同一个文件路径只会被读取和注入一次。

docs/Eino/docs/core_modules/eino_adk/Eino_ADK_ChatModelAgentMiddleware/middleware_filesystem.md

@@ -1,187 +0,0 @@
----
-Description: ""
-date: "2026-03-24"
-lastmod: ""
-tags: []
-title: FileSystem
-weight: 2
----
-
-> 💡 Package: [github.com/cloudwego/eino/adk/middlewares/filesystem](https://github.com/cloudwego/eino/tree/main/adk/middlewares/filesystem)
-
-## 概述
-
-FileSystem Middleware 为 Agent 提供文件系统访问能力。它通过 [FileSystem Backend](/zh/docs/eino/core_modules/eino_adk/eino_adk_chatmodelagentmiddleware/filesystem_backend) 接口操作文件系统，自动向 Agent 注入一组文件操作工具及对应的 system prompt，使 Agent 能够直接进行文件读写、搜索、编辑等操作。
-
-核心功能：
-
-- **文件系统工具注入** — 自动注册 ls、read_file、write_file、edit_file、glob、grep 等工具
-- **Shell 命令执行** — 可选注入 execute 工具，支持同步和流式命令执行
-- **工具级别配置** — 每个工具均可独立配置名称、描述、自定义实现或禁用
-- **多语言提示词** — 工具描述和 system prompt 支持中英文切换
-
-## 创建中间件
-
-推荐使用 `New` 函数创建中间件（返回 `ChatModelAgentMiddleware`）：
-
-```go
-import "github.com/cloudwego/eino/adk/middlewares/filesystem"
-
-middleware, err := filesystem.New(ctx, &filesystem.MiddlewareConfig{
-    Backend: myBackend,
-    // 如果需要 shell 命令执行能力，设置 Shell 或 StreamingShell
-    Shell: myShell,
-})
-if err != nil {
-    // handle error
-}
-
-agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    // ...
-    Middlewares: []adk.ChatModelAgentMiddleware{middleware},
-})
-```
-
-> 💡
-> `New` 返回 `ChatModelAgentMiddleware`，提供更好的上下文传播能力（通过 `BeforeAgent` hook 在运行时修改 Agent 的 instruction 和 tools）。
-
-## MiddlewareConfig 配置项
-
-```go
-type MiddlewareConfig struct {
-    // Backend 提供文件系统操作
-    // 必填
-    Backend filesystem.Backend
-
-    // Shell 提供 shell 命令执行能力
-    // 如果设置，会注册 execute 工具
-    // 可选，与 StreamingShell 互斥
-    Shell filesystem.Shell
-
-    // StreamingShell 提供流式 shell 命令执行能力
-    // 如果设置，会注册流式 execute 工具（支持实时输出）
-    // 可选，与 Shell 互斥
-    StreamingShell filesystem.StreamingShell
-
-    // 以下为各工具的独立配置，均为可选
-    LsToolConfig        *ToolConfig  // ls 工具配置
-    ReadFileToolConfig  *ToolConfig  // read_file 工具配置
-    WriteFileToolConfig *ToolConfig  // write_file 工具配置
-    EditFileToolConfig  *ToolConfig  // edit_file 工具配置
-    GlobToolConfig      *ToolConfig  // glob 工具配置
-    GrepToolConfig      *ToolConfig  // grep 工具配置
-
-    // CustomSystemPrompt 覆盖默认的系统提示词
-    // 可选，默认 ToolsSystemPrompt
-    CustomSystemPrompt *string
-
-    // 以下字段已 Deprecated，请使用对应的 *ToolConfig.Desc 替代
-    // CustomLsToolDesc, CustomReadFileToolDesc, CustomGrepToolDesc,
-    // CustomGlobToolDesc, CustomWriteFileToolDesc, CustomEditToolDesc
-}
-```
-
-### ToolConfig
-
-每个工具均可通过 `ToolConfig` 独立配置：
-
-```go
-type ToolConfig struct {
-    // Name 覆盖工具名称
-    // 可选，不设置则使用默认名称（如 "ls"、"read_file" 等）
-    Name string
-
-    // Desc 覆盖工具描述
-    // 可选，不设置则使用默认描述
-    Desc *string
-
-    // CustomTool 提供自定义工具实现
-    // 如果设置，将使用此自定义实现替代基于 Backend 的默认实现
-    // 可选
-    CustomTool tool.BaseTool
-
-    // Disable 禁用此工具
-    // 如果为 true，该工具将不会被注册
-    // 可选，默认 false
-    Disable bool
-}
-```
-
-示例 — 自定义工具名称并禁用写入：
-
-```go
-middleware, err := filesystem.New(ctx, &filesystem.MiddlewareConfig{
-    Backend: myBackend,
-    ReadFileToolConfig: &filesystem.ToolConfig{
-        Name: "cat_file",  // 自定义名称
-    },
-    WriteFileToolConfig: &filesystem.ToolConfig{
-        Disable: true,  // 禁用写入工具
-    },
-})
-```
-
-## 注入的工具
-
-<table>
-<tr><td>工具</td><td>默认名称</td><td>描述</td><td>条件</td></tr>
-<tr><td>列出目录</td><td><pre>ls</pre></td><td>列出指定路径下的文件和目录</td><td>Backend 不为 nil 时注入</td></tr>
-<tr><td>读取文件</td><td><pre>read_file</pre></td><td>读取文件内容，支持按行分页（offset + limit）</td><td>Backend 不为 nil 时注入</td></tr>
-<tr><td>写入文件</td><td><pre>write_file</pre></td><td>创建或覆盖文件</td><td>Backend 不为 nil 时注入</td></tr>
-<tr><td>编辑文件</td><td><pre>edit_file</pre></td><td>替换文件中的字符串</td><td>Backend 不为 nil 时注入</td></tr>
-<tr><td>Glob 查找</td><td><pre>glob</pre></td><td>按 glob pattern 查找文件</td><td>Backend 不为 nil 时注入</td></tr>
-<tr><td>内容搜索</td><td><pre>grep</pre></td><td>按 pattern 搜索文件内容，支持多种输出模式</td><td>Backend 不为 nil 时注入</td></tr>
-<tr><td>命令执行</td><td><pre>execute</pre></td><td>执行 shell 命令</td><td>需配置 Shell 或 StreamingShell</td></tr>
-</table>
-
-每个工具均可通过对应的 `*ToolConfig` 禁用（`Disable: true`）或提供自定义实现（`CustomTool`）。
-
-## 多语言支持
-
-工具描述和内置提示词默认为英文。如需切换为中文，可通过 `adk.SetLanguage()` 设置：
-
-```go
-import "github.com/cloudwego/eino/adk"
-
-adk.SetLanguage(adk.LanguageChinese)  // 切换为中文
-adk.SetLanguage(adk.LanguageEnglish)  // 切换为英文（默认）
-```
-
-也可以通过 `ToolConfig.Desc` 或 `CustomSystemPrompt` 自定义各工具的说明文本。
-
-## [deprecated] 工具结果卸载
-
-> 💡
-> 该功能即将在 0.8.0 中 deprecate。请迁移到 Middleware: ToolReduction
-
-> 注意：工具结果卸载仅在旧的 `Config` + `NewMiddleware` 函数中可用。推荐的 `MiddlewareConfig` + `New` 不包含此功能，如需要请配合 ToolReduction middleware 使用。
-
-当工具调用结果过大（例如读取大文件、grep 命中大量内容），如果继续将完整结果放入对话上下文，会导致：
-
-- token 急剧增加
-- Agent 历史上下文污染
-- 推理效率变差
-
-为此，旧版 Middleware（`NewMiddleware`）提供了自动卸载机制：
-
-- 当结果大小超过阈值（默认 20,000 tokens）时，不直接返回全部内容给 LLM
-- 实际结果会保存到文件系统（Backend）
-- 上下文中仅包含摘要和文件路径（Agent 可再次调用 `read_file` 工具按需读取）
-
-该功能默认启用，可通过 `Config`（非 `MiddlewareConfig`）配置：
-
-```go
-type Config struct {
-    // ... Backend, Shell, StreamingShell, ToolConfig 等字段同 MiddlewareConfig
-
-    // 关闭自动卸载
-    WithoutLargeToolResultOffloading bool
-
-    // 自定义触发阈值（默认 20000 tokens）
-    LargeToolResultOffloadingTokenLimit int
-
-    // 自定义卸载文件生成路径
-    // 默认路径格式: /large_tool_result/{ToolCallID}
-    LargeToolResultOffloadingPathGen func(ctx context.Context, input *compose.ToolInput) (string, error)
-}
-```

docs/Eino/docs/core_modules/eino_adk/_index.md

@@ -1,10 +0,0 @@
----
-Description: ""
-date: "2025-08-06"
-lastmod: ""
-tags: []
-title: ADK - Agent Development Kit
-weight: 4
----
-
-

docs/Eino/docs/core_modules/eino_adk/adk_agent_callback.md

@@ -1,361 +0,0 @@
----
-Description: ""
-date: "2026-03-24"
-lastmod: ""
-tags: []
-title: Agent Callback
-weight: 9
----
-
-此功能为 ADK Agent 添加了回调（Callback）支持，类似于 compose 包中的回调机制。通过回调，用户可以观测 Agent 的执行生命周期，实现日志记录、追踪、监控等功能。
-
-> 💡
-> **提示**：cozeloop 的 adk trace 版本见 [https://github.com/cloudwego/eino-ext/releases/tag/callbacks%2Fcozeloop%2Fv0.2.0](https://github.com/cloudwego/eino-ext/releases/tag/callbacks%2Fcozeloop%2Fv0.2.0)
->
-> 务必同时使用支持 v0.8 的 trace callback handler 实现，才能正常使用 Agent trace 功能
-
-## 概述
-
-ADK Agent Callback 机制与 Eino compose 中的回调系统共享相同的基础设施：
-
-- 使用相同的 `callbacks.Handler` 接口
-- 使用相同的 `callbacks.RunInfo` 结构
-- 可以与其他组件回调（如 ChatModel、Tool 等）组合使用
-
-> 💡
-> 通过 Agent Callback，你可以在 Agent 执行的关键节点介入，实现 tracing、logging、metrics 等可观测性能力。本能力在 v0.8.0 版本引入。
-
-## 核心类型
-
-### ComponentOfAgent
-
-组件类型标识符，用于在回调中识别 Agent 相关事件：
-
-```go
-const ComponentOfAgent components.Component = "Agent"
-```
-
-在 `callbacks.RunInfo.Component` 中使用，用于过滤仅与 Agent 相关的回调事件。
-
-### AgentCallbackInput
-
-Agent 回调的输入类型，在 `OnStart` 回调中传递：
-
-```go
-type AgentCallbackInput struct {
-    // Input 包含新运行的 Agent 输入。恢复执行时为 nil。
-    Input *AgentInput
-    // ResumeInfo 包含从中断恢复时的信息。新运行时为 nil。
-    ResumeInfo *ResumeInfo
-}
-```
-
-<table>
-<tr><td>调用方式</td><td>字段值</td></tr>
-<tr><td><pre>Agent.Run()</pre></td><td><pre>Input</pre> 字段有值，<pre>ResumeInfo</pre> 为 nil</td></tr>
-<tr><td><pre>Agent.Resume()</pre></td><td><pre>ResumeInfo</pre> 字段有值，<pre>Input</pre> 为 nil</td></tr>
-</table>
-
-### AgentCallbackOutput
-
-Agent 回调的输出类型，在 `OnEnd` 回调中传递：
-
-```go
-type AgentCallbackOutput struct {
-    // Events 提供 Agent 事件流。每个 handler 接收独立的副本。
-    Events *AsyncIterator[*AgentEvent]
-}
-```
-
-> 💡
-> **重要**：`Events` 迭代器应**异步消费**，以避免阻塞 Agent 执行。每个回调 handler 接收独立的事件流副本，互不干扰。
-
-## API 使用
-
-### WithCallbacks
-
-添加回调 handler 以接收 Agent 生命周期事件的运行选项：
-
-```go
-func WithCallbacks(handlers ...callbacks.Handler) AgentRunOption
-```
-
-### 类型转换函数
-
-将通用回调类型转换为 Agent 专用类型：
-
-```go
-// 转换输入类型
-func ConvAgentCallbackInput(input callbacks.CallbackInput) *AgentCallbackInput
-
-// 转换输出类型
-func ConvAgentCallbackOutput(output callbacks.CallbackOutput) *AgentCallbackOutput
-```
-
-如果类型不匹配，函数返回 nil。
-
-## 使用示例
-
-### 方式一：使用 HandlerBuilder
-
-使用 `callbacks.NewHandlerBuilder()` 构建通用的 callback handler：
-
-```go
-import (
-    "github.com/cloudwego/eino/adk"
-    "github.com/cloudwego/eino/callbacks"
-)
-
-handler := callbacks.NewHandlerBuilder().
-    OnStartFn(func(ctx context.Context, info *callbacks.RunInfo, input callbacks.CallbackInput) context.Context {
-        if info.Component == adk.ComponentOfAgent {
-            agentInput := adk.ConvAgentCallbackInput(input)
-            if agentInput.Input != nil {
-                fmt.Printf("Agent %s started with new run\n", info.Name)
-            } else {
-                fmt.Printf("Agent %s resumed from interrupt\n", info.Name)
-            }
-        }
-        return ctx
-    }).
-    OnEndFn(func(ctx context.Context, info *callbacks.RunInfo, output callbacks.CallbackOutput) context.Context {
-        if info.Component == adk.ComponentOfAgent {
-            agentOutput := adk.ConvAgentCallbackOutput(output)
-            // 异步消费事件流
-            go func() {
-                for {
-                    event, ok := agentOutput.Events.Next()
-                    if !ok {
-                        break
-                    }
-                    // 处理事件...
-                    fmt.Printf("Event from %s: %+v\n", event.AgentName, event)
-                }
-            }()
-        }
-        return ctx
-    }).
-    Build()
-
-// 创建 Runner - 必须通过 Runner 执行 Agent，callback 才会生效
-runner := adk.NewRunner(ctx, adk.RunnerConfig{
-    Agent:           agent,
-    EnableStreaming: input.EnableStreaming,
-})
-
-iter := runner.Run(ctx, input.Messages, adk.WithCallbacks(handler))
-```
-
-> 💡
-> **重要提示**：上面的示例展示了正确的使用方式。必须通过 Runner 执行 Agent，AgentCallback 才会生效。直接使用 `agent.Run()` 时，callback 不会被触发。
-
-### 方式二：使用 HandlerHelper（推荐）
-
-使用 `template.HandlerHelper` 可以更方便地处理类型转换：
-
-```go
-import (
-    "github.com/cloudwego/eino/adk"
-    "github.com/cloudwego/eino/callbacks"
-    template "github.com/cloudwego/eino/utils/callbacks"
-)
-
-helper := template.NewHandlerHelper().
-    Agent(&template.AgentCallbackHandler{
-        OnStart: func(ctx context.Context, info *callbacks.RunInfo, input *adk.AgentCallbackInput) context.Context {
-            if input.Input != nil {
-                fmt.Printf("Agent %s started with input\n", info.Name)
-            } else {
-                fmt.Printf("Agent %s resumed\n", info.Name)
-            }
-            return ctx
-        },
-        OnEnd: func(ctx context.Context, info *callbacks.RunInfo, output *adk.AgentCallbackOutput) context.Context {
-            // 异步消费事件
-            go func() {
-                for {
-                    event, ok := output.Events.Next()
-                    if !ok {
-                        break
-                    }
-                    // 处理事件...
-                }
-            }()
-            return ctx
-        },
-    }).
-    Handler()
-
-// 创建 Runner - 必须通过 Runner 执行 Agent，callback 才会生效
-runner := adk.NewRunner(ctx, adk.RunnerConfig{
-    Agent:           agent,
-    EnableStreaming: input.EnableStreaming,
-})
-
-iter := runner.Run(ctx, input.Messages, adk.WithCallbacks(helper))
-```
-
-> 💡
-> **重要提示**：必须通过 Runner 执行 Agent，AgentCallback 才会生效。直接使用 `agent.Run()` 时，callback 不会被触发。
-
-> 💡
-> `HandlerHelper` 会自动进行类型转换，代码更简洁。同时支持组合多种组件的回调处理器。
-
-## Tracing 场景应用
-
-> 💡
-> **重要提示**：AgentCallback 必须通过 Runner 来执行才会生效。直接使用 Agent.Run() 时，callback 不会被触发，因为 callback 机制是在 flowAgent 层面实现的。请使用 adk.NewRunner() 创建 Runner 后，通过 Runner.Run() 或 Runner.Query() 来执行 Agent。
-
-Agent Callback 最常见的应用场景是实现分布式追踪（Tracing）。以下是使用 OpenTelemetry 实现 tracing 的示例：
-
-```go
-import (
-    "go.opentelemetry.io/otel"
-    "go.opentelemetry.io/otel/attribute"
-    "go.opentelemetry.io/otel/codes"
-    "go.opentelemetry.io/otel/trace"
-    
-    "github.com/cloudwego/eino/adk"
-    "github.com/cloudwego/eino/callbacks"
-)
-
-// 创建 Agent（以 ChatModelAgent 为例）
-agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    Name:        "my_agent",
-    Description: "A helpful assistant",
-    Model:       chatModel,
-})
-
-// 创建 Runner - 必须通过 Runner 执行 Agent，callback 才会生效
-runner := adk.NewRunner(ctx, adk.RunnerConfig{
-    Agent:           agent,
-    EnableStreaming: true,
-})
-
-tracer := otel.Tracer("my-agent-tracer")
-
-handler := callbacks.NewHandlerBuilder().
-    OnStartFn(func(ctx context.Context, info *callbacks.RunInfo, input callbacks.CallbackInput) context.Context {
-        // 创建 span
-        ctx, span := tracer.Start(ctx, info.Name,
-            trace.WithAttributes(
-                attribute.String("component", string(info.Component)),
-                attribute.String("type", info.Type),
-            ))
-        
-        // Agent 特定的属性
-        if info.Component == adk.ComponentOfAgent {
-            agentInput := adk.ConvAgentCallbackInput(input)
-            if agentInput != nil && agentInput.Input != nil {
-                span.SetAttributes(attribute.Bool("is_new_run", true))
-            } else {
-                span.SetAttributes(attribute.Bool("is_resume", true))
-            }
-        }
-        
-        return ctx
-    }).
-    OnEndFn(func(ctx context.Context, info *callbacks.RunInfo, output callbacks.CallbackOutput) context.Context {
-        span := trace.SpanFromContext(ctx)
-        span.End()
-        return ctx
-    }).
-    OnErrorFn(func(ctx context.Context, info *callbacks.RunInfo, err error) context.Context {
-        span := trace.SpanFromContext(ctx)
-        span.RecordError(err)
-        span.SetStatus(codes.Error, err.Error())
-        span.End()
-        return ctx
-    }).
-    Build()
-
-// 使用 Runner 执行 Agent，并传入 callback handler
-iter := runner.Query(ctx, "Hello, agent!", adk.WithCallbacks(handler))
-
-// 处理事件流
-for {
-    event, ok := iter.Next()
-    if !ok {
-        break
-    }
-    if event.Err != nil {
-        log.Error(event.Err)
-        break
-    }
-    // 处理事件...
-}
-```
-
-> 💡
-> **再次提醒**：必须通过 Runner 执行 Agent，callback 才会生效。直接使用 `agent.Run()` 时，即使传入了 `adk.WithCallbacks(handler)`，Agent 级别的 callback 也不会被触发。
-
-> 💡
-> **提示**：cozeloop 的 adk trace 版本见 [https://github.com/cloudwego/eino-ext/releases/tag/callbacks%2Fcozeloop%2Fv0.2.0](https://github.com/cloudwego/eino-ext/releases/tag/callbacks%2Fcozeloop%2Fv0.2.0)
-
-## Agent 类型标识
-
-内置 Agent 实现了 `components.Typer` 接口，返回其类型标识，该信息会填充到 `callbacks.RunInfo.Type` 字段中：
-
-<table>
-<tr><td>Agent 类型</td><td>GetType() 返回值</td></tr>
-<tr><td>ChatModelAgent</td><td><pre>"ChatModel"</pre></td></tr>
-<tr><td>workflowAgent (Sequential)</td><td><pre>"Sequential"</pre></td></tr>
-<tr><td>workflowAgent (Parallel)</td><td><pre>"Parallel"</pre></td></tr>
-<tr><td>workflowAgent (Loop)</td><td><pre>"Loop"</pre></td></tr>
-<tr><td>DeterministicTransfer Agent</td><td><pre>"DeterministicTransfer"</pre></td></tr>
-</table>
-
-## 回调行为说明
-
-### 回调调用时机
-
-<table><tbody><tr>
-<td>
-<strong>Run 方法</strong>1. 初始化回调上下文2. 处理输入3. 调用 <pre>OnStart</pre>4. 执行 Agent 逻辑5. 注册 <pre>OnEnd</pre>（在事件流创建时）</td><td>
-<strong>Resume 方法</strong>1. 构建 ResumeInfo2. 初始化回调上下文3. 调用 <pre>OnStart</pre>4. 恢复 Agent 执行5. 注册 <pre>OnEnd</pre>（在事件流创建时）</td></tr></tbody></table>
-
-### OnEnd 调用时机
-
-`OnEnd` 回调在**迭代器创建时**注册，而非在生成器关闭时。这允许 handler 在事件流式传输时消费事件。
-
-## 注意事项
-
-### 1. 异步消费事件流
-
-回调 handler 中的 `AgentCallbackOutput.Events` **必须**异步消费，否则会阻塞 Agent 执行：
-
-```go
-// ✅ 正确
-OnEnd: func(ctx context.Context, info *callbacks.RunInfo, output *adk.AgentCallbackOutput) context.Context {
-    go func() {
-        for {
-            event, ok := output.Events.Next()
-            if !ok {
-                break
-            }
-            // 处理事件
-        }
-    }()
-    return ctx
-}
-
-// ❌ 错误 - 会导致死锁
-OnEnd: func(ctx context.Context, info *callbacks.RunInfo, output *adk.AgentCallbackOutput) context.Context {
-    for {
-        event, ok := output.Events.Next()
-        if !ok {
-            break
-        }
-        // 处理事件
-    }
-    return ctx
-}
-```
-
-### 2. 无 OnError 回调
-
-由于 `Agent.Run()` 和 `Agent.Resume()` 方法签名不返回 error，Agent 回调**不支持** `OnError`。错误信息通过 `AgentEvent.Err` 字段在事件流中传递。
-
-### 3. 事件流复制机制
-
-当有多个回调 handler 时，每个 handler 接收独立的事件流副本，互不干扰。最后一个 handler 接收原始事件以减少内存分配。

docs/Eino/docs/core_modules/eino_adk/agent_collaboration.md

@@ -1,521 +0,0 @@
----
-Description: ""
-date: "2026-03-02"
-lastmod: ""
-tags: []
-title: Agent 协作
-weight: 4
----
-
-# Agent 协作
-
-概述文档已经对 Agent 协作提供了基础的说明，下面将结合代码，对协作与组合原语的设计与实现进行介绍：
-
-## 协作原语
-
-### Agent 间协作方式
-
-<table>
-<tr><td>协作方式</td><td>描述</td></tr>
-<tr><td> Transfer</td><td>直接将任务转让给另外一个 Agent，本 Agent 则执行结束后退出，不关心转让 Agent 的任务执行状态</td></tr>
-<tr><td>ToolCall(AgentAsTool)</td><td>将 Agent 当成 ToolCall 调用，等待 Agent 的响应，并可获取被调用Agent 的输出结果，进行下一轮处理</td></tr>
-</table>
-
-### AgentInput 的上下文策略
-
-<table>
-<tr><td>上下文策略</td><td>描述</td></tr>
-<tr><td>上游 Agent 全对话</td><td>获取本 Agent 的上游 Agent 的完整对话记录</td></tr>
-<tr><td>全新任务描述</td><td>忽略掉上游 Agent 的完整对话记录，给出一个全新的任务总结，作为子 Agent 的 AgentInput 输入</td></tr>
-</table>
-
-### 决策自主性
-
-<table>
-<tr><td>决策自主性</td><td>描述</td></tr>
-<tr><td>自主决策</td><td>在 Agent 内部，基于其可选的下游 Agent， 如需协助时，自主选择下游 Agent 进行协助。 一般来说，Agent 内部是基于 LLM 进行决策，不过即使是基于预设逻辑进行选择，从 Agent 外部看依然视为自主决策</td></tr>
-<tr><td>预设决策</td><td>事先预设好一个Agent 执行任务后的下一个 Agent。 Agent 的执行顺序是事先确定、可预测的</td></tr>
-</table>
-
-### 组合原语
-
-<table>
-<tr><td>类型</td><td>描述</td><td>运行模式</td><td>协作方式</td><td>上下文策略</td><td>决策自主性</td></tr>
-<tr><td><strong>SubAgents</strong></td><td>将用户提供的 agent 作为 父Agent，用户提供的 subAgents 列表作为 子Agents，组合而成可自主决策的 Agent，其中的 Name 和 Description 作为该 Agent 的名称标识和描述。<li>当前限定一个 Agent 只能有一个 父 Agent</li><li>可采用 SetSubAgents 函数，构建 「多叉树」 形式的 Multi-Agent</li><li>在这个「多叉树」中，AgentName 需要保持唯一</li></td><td><a href="/img/eino/eino_adk_self_driving.png" target="_blank"><img src="/img/eino/eino_adk_self_driving.png" width="100%" /></a></td><td>Transfer</td><td>上游 Agent 全对话</td><td>自主决策</td></tr>
-<tr><td><strong>Sequential</strong></td><td>将用户提供的 SubAgents 列表，组合成按照顺序依次执行的 Sequential Agent，其中的 Name 和 Description 作为 Sequential Agent 的名称标识和描述。Sequential Agent 执行时，将 SubAgents 列表，按照顺序依次执行，直至将所有 Agent 执行一遍后结束。</td><td><a href="/img/eino/eino_adk_sequential_controller.png" target="_blank"><img src="/img/eino/eino_adk_sequential_controller.png" width="100%" /></a></td><td>Transfer</td><td>上游 Agent 全对话</td><td>预设决策</td></tr>
-<tr><td><strong>Parallel</strong></td><td>将用户提供的 SubAgents 列表，组合成基于相同上下文，并发执行的 Parallel Agent，其中的 Name 和 Description 作为 Parallel Agent 的名称标识和描述。Parallel Agent 执行时，将 SubAgents 列表，并发执行，待所有 Agent 执行完成后结束。</td><td><a href="/img/eino/eino_adk_parallel_yet_another_2.png" target="_blank"><img src="/img/eino/eino_adk_parallel_yet_another_2.png" width="100%" /></a></td><td>Transfer</td><td>上游 Agent 全对话</td><td>预设决策</td></tr>
-<tr><td><strong>Loop</strong></td><td>将用户提供的 SubAgents 列表，按照数组顺序依次执行，循环往复，组合成 Loop Agent，其中的 Name 和 Description 作为 Loop Agent 的名称标识和描述。Loop Agent 执行时，将 SubAgents 列表，顺序执行，待所有 Agent 执行完成后结束。</td><td><a href="/img/eino/eino_adk_loop_exit.png" target="_blank"><img src="/img/eino/eino_adk_loop_exit.png" width="100%" /></a></td><td>Transfer</td><td>上游 Agent 全对话</td><td>预设决策</td></tr>
-<tr><td><strong>AgentAsTool</strong></td><td>将一个 Agent 转换成 Tool，被其他的 Agent 当成普通的 Tool 使用。一个 Agent 能否将其他 Agent 当成 Tool 进行调用，取决于自身的实现。adk 中提供的 ChatModelAgent 支持 AgentAsTool 的功能</td><td><a href="/img/eino/eino_collaboration_agent_as_tool_thumbnail.png" target="_blank"><img src="/img/eino/eino_collaboration_agent_as_tool_thumbnail.png" width="100%" /></a></td><td>ToolCall</td><td>全新任务描述</td><td>自主决策</td></tr>
-</table>
-
-## 上下文传递
-
-在构建多 Agent 系统时，让不同 Agent 之间高效、准确地共享信息至关重要。Eino ADK 提供了两种核心的上下文传递机制，以满足不同的协作需求： History 和 SessionValues。
-
-### History
-
-#### 概念
-
-History 对应【上游 Agent 全对话上下文策略】，多 Agent 系统中每一个 Agent 产生的 AgentEvent 都会被保存到 History 中，调用一个新 Agent 时 (Workflow/ Transfer) History 中的 AgentEvent 会被转换并拼接到 AgentInput 中。
-
-默认情况下，其他 Agent 的 Assistant 或 Tool Message，被转换为 User Message。这相当于在告诉当前的 LLM：“刚才， Agent_A 调用了 some_tool ，返回了 some_result 。现在，轮到你来决策了。”
-
-通过这种方式，其他 Agent 的行为被当作了提供给当前 Agent 的“外部信息”或“事实陈述”，而不是它自己的行为，从而避免了 LLM 的上下文混乱。
-
-<a href="/img/eino/eino_adk_message_event.png" target="_blank"><img src="/img/eino/eino_adk_message_event.png" width="100%" /></a>
-
-在 Eino ADK 中，当为一个 Agent 构建 AgentInput 时，它能看到的 History 是“所有在我之前产生的 AgentEvent”。
-
-值得一提的是 ParallelWorkflowAgent：并行的两个子 Agent（A，B），在并行执行过程中，相互不可见对方产生的 AgentEvent，因为并行的 A、B 没有谁是在另一个之前。
-
-#### RunPath
-
-History 中每个 AgentEvent 都是由“特定 Agent 在特定的执行序列中产生的”，也就是 AgentEvent 有自身的 RunPath。RunPath 的作用是传递出这个信息，在 eino 框架中不乘载其他功能。
-
-下面表格中给出各种编排模式下，Agent 执行时的具体 RunPath：
-
-<table>
-<tr><td>Example</td><td>RunPath</td></tr>
-<tr><td><a href="/img/eino/eino_adk_run_path_sub_agent.png" target="_blank"><img src="/img/eino/eino_adk_run_path_sub_agent.png" width="100%" /></a></td><td><li>Agent: [Agent]</li><li>SubAgent: [Agent, SubAgent]</li></td></tr>
-<tr><td><a href="/img/eino/eino_adk_run_path.png" target="_blank"><img src="/img/eino/eino_adk_run_path.png" width="100%" /></a></td><td><li>Agent: [Agent]</li><li>Agent（after function call）: [Agent]</li></td></tr>
-<tr><td><a href="/img/eino/eino_adk_collaboration_run_path_sequential.png" target="_blank"><img src="/img/eino/eino_adk_collaboration_run_path_sequential.png" width="100%" /></a></td><td><li>Agent1: [SequentialAgent, LoopAgent, Agent1]</li><li>Agent2: [SequentialAgent, LoopAgent, Agent1, Agent2]</li><li>Agent1: [SequentialAgent, LoopAgent, Agent1, Agent2, Agent1]</li><li>Agent2: [SequentialAgent, LoopAgent, Agent1, Agent2, Agent1, Agent2]</li><li>Agent3: [SequentialAgent, LoopAgent, Agent3]</li><li>Agent4: [SequentialAgent, LoopAgent, Agent3, ParallelAgent, Agent4]</li><li>Agent5: [SequentialAgent, LoopAgent, Agent3, ParallelAgent, Agent5]</li><li>Agent6: [SequentialAgent, LoopAgent, Agent3, ParallelAgent, Agent6]</li></td></tr>
-<tr><td><a href="/img/eino/eino_adk_run_path_deterministic.png" target="_blank"><img src="/img/eino/eino_adk_run_path_deterministic.png" width="100%" /></a></td><td><li>Agent: [Agent]</li><li>SubAgent: [Agent, SubAgent]</li><li>Agent: [Agent, SubAgent, Agent]</li></td></tr>
-</table>
-
-#### 自定义
-
-有些情况下在 Agent 运行前需要对 History 的内容进行调整，此时通过 AgentWithOptions 可以自定义 Agent 从 History 中生成  AgentInput 的方式：
-
-```go
-// github.com/cloudwego/eino/adk/flow.go
-
-type HistoryRewriter func(ctx context.Context, entries []*HistoryEntry) ([]Message, error)
-
-func WithHistoryRewriter(h HistoryRewriter) AgentOption
-```
-
-### SessionValues
-
-#### 概念
-
-SessionValues 是在一次运行中持续存在的全局临时 KV 存储，用于支持跨 Agent 的状态管理和数据共享，一次运行中的任何 Agent 可以在任何时间读写 SessionValues。
-
-Eino ADK 提供了多种方法供 Agent 运行时内部并发安全的读写 Session Values：
-
-```go
-// github.com/cloudwego/eino/adk/runctx.go
-
-// 获取全部 SessionValues
-func GetSessionValues(ctx context.Context) map[string]any
-// 批量设置 SessionValues
-func AddSessionValues(ctx context.Context, kvs map[string]any) 
-// 指定 key 获取 SessionValues 中的一个值，key 不存在时第二个返回值为 false，否则为 true
-func GetSessionValue(ctx context.Context, key string) (any, bool)
-// 设置单个 SessionValues
-func AddSessionValue(ctx context.Context, key string, value any)
-```
-
-需要注意的是，由于 SessionValues 机制基于 Context 来实现，而 Runner 运行会对 Context 重新初始化，因此在 Run 方法外通过 `AddSessionValues` 或 `AddSessionValue` 注入 SessionValues 是不生效的。
-
-如果您需要在 Agent 运行前就注入数据到 SessionValues 中，需要使用专用的 Option 来协助实现，用法如下：
-
-```go
-// github.com/cloudwego/eino/adk/call_option.go
-// WithSessionValues 在 Agent 运行前注入 SessionValues
-func WithSessionValues(v map[string]any) AgentRunOption
-
-// 用法：
-runner := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent})
-iterator := runner.Run(ctx, []adk.Message{schema.UserMessage("xxx")},
-    adk.WithSessionValues(map[string]any{
-       PlanSessionKey:      123,
-       UserInputSessionKey: []adk.Message{schema.UserMessage("yyy")},
-    }),
-)
-```
-
-## Transfer SubAgents
-
-### 概念
-
-Transfer 对应【Transfer 协作方式】，Agent 运行时产生带有包含 TransferAction 的 AgentEvent 后，Eino ADK 会调用 Action 指定的 Agent，被调用的 Agent 被称为子 Agent（SubAgent）。
-
-TransferAction 可以使用 `NewTransferToAgentAction` 快速创建：
-
-```go
-import "github.com/cloudwego/eino/adk"
-
-event := adk.NewTransferToAgentAction("dest agent name")
-```
-
-为了让 Eino ADK 在接受到 TransferAction 可以找到子 Agent 实例并运行，在运行前需要先调用 `SetSubAgents` 将可能的子 Agent 注册到 Eino ADK 中：
-
-```go
-// github.com/cloudwego/eino/adk/flow.go
-func SetSubAgents(ctx context.Context, agent Agent, subAgents []Agent) (Agent, error)
-```
-
-> 💡
-> Transfer 的含义是将任务**移交**给子 Agent，而不是委托或者分配，因此：
->
-> 1. 区别于 ToolCall，通过 Transfer 调用子 Agent，子 Agent 运行结束后，不会再调用父 Agent 总结内容或进行下一步操作。
-> 2. 调用子 Agent 时，子 Agent 的输入仍然是原始输入，父 Agent 的输出会作为上下文供子 Agent 参考。
-
-在触发 SetSubAgents 时，父子 Agent 双方都需要进行处理来完成初始化操作，Eino ADK 定义了 `OnSubAgents` 接口用于支持此功能：
-
-```go
-// github.com/cloudwego/eino/adk/interface.go
-type OnSubAgents interface {
-    OnSetSubAgents(ctx context.Context, subAgents []Agent) error
-    OnSetAsSubAgent(ctx context.Context, parent Agent) error
-    OnDisallowTransferToParent(ctx context.Context) error
-}
-```
-
-如果 Agent 实现了 `OnSubAgents` 接口，`SetSubAgents` 中会调用相应的方法向 Agent 注册，例如 `ChatModelAgent` 的实现
-
-### 示例
-
-接下来以一个多功能对话 Agent 演示 Transfer 能力，目标是搭建一个可以查询天气或者与用户对话的 Agent，Agent 结构如下：
-
-<a href="/img/eino/eino_adk_collaboration_example.png" target="_blank"><img src="/img/eino/eino_adk_collaboration_example.png" width="100%" /></a>
-
-三个 Agent 均使用 ChatModelAgent 实现：
-
-```go
-import (
-    "context"
-    "fmt"
-    "log"
-    "os"
-
-    "github.com/cloudwego/eino-ext/components/model/openai"
-    "github.com/cloudwego/eino/adk"
-    "github.com/cloudwego/eino/components/model"
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/compose"
-)
-
-func newChatModel() model.ToolCallingChatModel {
-    cm, err := openai.NewChatModel(context.Background(), &openai.ChatModelConfig{
-       APIKey: os.Getenv("OPENAI_API_KEY"),
-       Model:  os.Getenv("OPENAI_MODEL"),
-    })
-    if err != nil {
-       log.Fatal(err)
-    }
-    return cm
-}
-
-type GetWeatherInput struct {
-    City string `json:"city"`
-}
-
-func NewWeatherAgent() adk.Agent {
-    weatherTool, err := utils.InferTool(
-       "get_weather",
-       "Gets the current weather for a specific city.", // English description
-       func(ctx context.Context, input *GetWeatherInput) (string, error) {
-          return fmt.Sprintf(`the temperature in %s is 25°C`, input.City), nil
-       },
-    )
-    if err != nil {
-       log.Fatal(err)
-    }
-
-    a, err := adk.NewChatModelAgent(context.Background(), &adk.ChatModelAgentConfig{
-       Name:        "WeatherAgent",
-       Description: "This agent can get the current weather for a given city.",
-       Instruction: "Your sole purpose is to get the current weather for a given city by using the 'get_weather' tool. After calling the tool, report the result directly to the user.",
-       Model:       newChatModel(),
-       ToolsConfig: adk.ToolsConfig{
-          ToolsNodeConfig: compose.ToolsNodeConfig{
-             Tools: []tool.BaseTool{weatherTool},
-          },
-       },
-    })
-    if err != nil {
-       log.Fatal(err)
-    }
-    return a
-}
-
-func NewChatAgent() adk.Agent {
-    a, err := adk.NewChatModelAgent(context.Background(), &adk.ChatModelAgentConfig{
-       Name:        "ChatAgent",
-       Description: "A general-purpose agent for handling conversational chat.", // English description
-       Instruction: "You are a friendly conversational assistant. Your role is to handle general chit-chat and answer questions that are not related to any specific tool-based tasks.",
-       Model:       newChatModel(),
-    })
-    if err != nil {
-       log.Fatal(err)
-    }
-    return a
-}
-
-func NewRouterAgent() adk.Agent {
-    a, err := adk.NewChatModelAgent(context.Background(), &adk.ChatModelAgentConfig{
-       Name:        "RouterAgent",
-       Description: "A manual router that transfers tasks to other expert agents.",
-       Instruction: `You are an intelligent task router. Your responsibility is to analyze the user's request and delegate it to the most appropriate expert agent.If no Agent can handle the task, simply inform the user it cannot be processed.`,
-       Model:       newChatModel(),
-    })
-    if err != nil {
-       log.Fatal(err)
-    }
-    return a
-}
-```
-
-之后使用 Eino ADK 的 Transfer 能力搭建 Multi-Agent 并运行，ChatModelAgent 实现了 OnSubAgent 接口，在 adk.SetSubAgents 方法中会使用此接口向 ChatModelAgent 注册父/子 Agent，不需要用户处理 TransferAction 生成问题：
-
-```go
-import (
-    "context"
-    "fmt"
-    "log"
-    "os"
-
-    "github.com/cloudwego/eino/adk"
-)
-
-func main() {
-    weatherAgent := NewWeatherAgent()
-    chatAgent := NewChatAgent()
-    routerAgent := NewRouterAgent()
-
-    ctx := context.Background()
-    a, err := adk.SetSubAgents(ctx, routerAgent, []adk.Agent{chatAgent, weatherAgent})
-    if err != nil {
-       log.Fatal(err)
-    }
-
-    runner := adk.NewRunner(ctx, adk.RunnerConfig{
-       Agent: a,
-    })
-
-    // query weather
-    println("\n\n>>>>>>>>>query weather<<<<<<<<<")
-    iter := runner.Query(ctx, "What's the weather in Beijing?")
-    for {
-       event, ok := iter.Next()
-       if !ok {
-          break
-       }
-       if event.Err != nil {
-          log.Fatal(event.Err)
-       }
-       if event.Action != nil {
-          fmt.Printf("\nAgent[%s]: transfer to %+v\n\n======\n", event.AgentName, event.Action.TransferToAgent.DestAgentName)
-       } else {
-          fmt.Printf("\nAgent[%s]:\n%+v\n\n======\n", event.AgentName, event.Output.MessageOutput.Message)
-       }
-    }
-
-    // failed to route
-    println("\n\n>>>>>>>>>failed to route<<<<<<<<<")
-    iter = runner.Query(ctx, "Book me a flight from New York to London tomorrow.")
-    for {
-       event, ok := iter.Next()
-       if !ok {
-          break
-       }
-       if event.Err != nil {
-          log.Fatal(event.Err)
-       }
-       if event.Action != nil {
-          fmt.Printf("\nAgent[%s]: transfer to %+v\n\n======\n", event.AgentName, event.Action.TransferToAgent.DestAgentName)
-       } else {
-          fmt.Printf("\nAgent[%s]:\n%+v\n\n======\n", event.AgentName, event.Output.MessageOutput.Message)
-       }
-    }
-}
-```
-
-运行结果：
-
-```yaml
->>>>>>>>>query weather<<<<<<<<<
-Agent[RouterAgent]:
-assistant: 
-tool_calls:
-{Index:<nil> ID:call_SKNsPwKCTdp1oHxSlAFt8sO6 Type:function Function:{Name:transfer_to_agent Arguments:{"agent_name":"WeatherAgent"}} Extra:map[]}
-
-finish_reason: tool_calls
-usage: &{201 17 218}
-======
-Agent[RouterAgent]: transfer to WeatherAgent
-======
-Agent[WeatherAgent]:
-assistant: 
-tool_calls:
-{Index:<nil> ID:call_QMBdUwKj84hKDAwMMX1gOiES Type:function Function:{Name:get_weather Arguments:{"city":"Beijing"}} Extra:map[]}
-
-finish_reason: tool_calls
-usage: &{255 15 270}
-======
-Agent[WeatherAgent]:
-tool: the temperature in Beijing is 25°C
-tool_call_id: call_QMBdUwKj84hKDAwMMX1gOiES
-tool_call_name: get_weather
-======
-Agent[WeatherAgent]:
-assistant: The current temperature in Beijing is 25°C.
-finish_reason: stop
-usage: &{286 11 297}
-======
-
->>>>>>>>>failed to route<<<<<<<<<
-Agent[RouterAgent]:
-assistant: I'm unable to assist with booking flights. Please use a relevant travel service or booking platform to make your reservation.
-finish_reason: stop
-usage: &{206 23 229}
-======
-```
-
-OnSubAgents 的另外两个方法在 Agent  作为 SetSubAgents 中的子 Agent 时被调用：
-
-- OnSetAsSubAgent 用来注册向 Agent 注册其父 Agent 信息
-- OnDisallowTransferToParent 在 Agent 设置 WithDisallowTransferToParent option 时会被调用，用来告知 Agent 不要产生向父 Agent 的 TransferAction。
-
-```go
-adk.SetSubAgents(
-    ctx,
-    Agent1,
-    []adk.Agent{
-       adk.AgentWithOptions(ctx, Agent2, adk.WithDisallowTransferToParent()),
-    },
-)
-```
-
-### 静态配置 Transfer
-
-AgentWithDeterministicTransferTo 是一个 Agent Wrapper，在原 Agent 执行完后生成预设的 TransferAction，从而实现静态配置 Agent 跳转的能力：
-
-```go
-// github.com/cloudwego/eino/adk/flow.go
-
-type DeterministicTransferConfig struct {
-        Agent        Agent
-        ToAgentNames []string
-}
-
-func AgentWithDeterministicTransferTo(_ context.Context, config *DeterministicTransferConfig) Agent
-```
-
-在 Supervisor 模式中，子 Agent 执行完毕后固定回到 Supervisor，由 Supervisor 生成下一步任务目标。此时可以使用 AgentWithDeterministicTransferTo：
-
-<a href="/img/eino/eino_adk_deterministic_transfer.png" target="_blank"><img src="/img/eino/eino_adk_deterministic_transfer.png" width="100%" /></a>
-
-```go
-// github.com/cloudwego/eino/adk/prebuilt/supervisor.go
-
-type SupervisorConfig struct {
-        Supervisor adk.Agent
-        SubAgents  []adk.Agent
-}
-
-func NewSupervisor(ctx context.Context, conf *SupervisorConfig) (adk.Agent, error) {
-        subAgents := make([]adk.Agent, 0, len(conf.SubAgents))
-        supervisorName := conf.Supervisor.Name(ctx)
-        for _, subAgent := range conf.SubAgents {
-                subAgents = append(subAgents, adk.AgentWithDeterministicTransferTo(ctx, &adk.DeterministicTransferConfig{
-                        Agent:        subAgent,
-                        ToAgentNames: []string{supervisorName},
-                }))
-        }
-
-        return adk.SetSubAgents(ctx, conf.Supervisor, subAgents)
-}
-```
-
-## Workflow Agents
-
-WorkflowAgent 支持以代码中预设好的流程运行 Agents。Eino ADK 提供了三种基础 Workflow Agent：Sequential、Parallel、Loop，它们之间可以互相嵌套以完成更复杂的任务。
-
-默认情况下，Workflow 中每个 Agent 的输入由 History 章节中介绍的方式生成，可以通过 WithHistoryRewriter 自定 AgentInput 生成方式。
-
-当 Agent 产生 ExitAction Event 后，Workflow Agent 会立刻退出，无论之后有没有其他需要运行的 Agent。
-
-详解与用例参考请见：[Eino ADK: Workflow Agents](/zh/docs/eino/core_modules/eino_adk/agent_implementation/workflow)
-
-### SequentialAgent
-
-SequentialAgent 会按照你提供的顺序，依次执行一系列 Agent：
-
-<a href="/img/eino/eino_adk_sequential_agent.png" target="_blank"><img src="/img/eino/eino_adk_sequential_agent.png" width="100%" /></a>
-
-```go
-type SequentialAgentConfig struct {
-    Name        string
-    Description string
-    SubAgents   []Agent
-}
-
-func NewSequentialAgent(ctx context.Context, config *SequentialAgentConfig) (Agent, error)
-```
-
-### LoopAgent
-
-LoopAgent 基于 SequentialAgent 实现，在 SequentialAgent 运行完成后，再次从头运行：
-
-<a href="/img/eino/eino_adk_loop_definition.png" target="_blank"><img src="/img/eino/eino_adk_loop_definition.png" width="100%" /></a>
-
-```go
-type LoopAgentConfig struct {
-    Name        string
-    Description string
-    SubAgents   []Agent
-
-    MaxIterations int // 最大循环次数
-}
-
-func NewLoopAgent(ctx context.Context, config *LoopAgentConfig) (Agent, error)
-```
-
-### ParallelAgent
-
-ParallelAgent 会并发运行若干 Agent：
-
-<a href="/img/eino/eino_adk_parallel_agent.png" target="_blank"><img src="/img/eino/eino_adk_parallel_agent.png" width="100%" /></a>
-
-```go
-type ParallelAgentConfig struct {
-    Name        string
-    Description string
-    SubAgents   []Agent
-}
-
-func NewParallelAgent(ctx context.Context, config *ParallelAgentConfig) (Agent, error)
-```
-
-## AgentAsTool
-
-当 Agent 运行仅需要明确清晰的指令，而非完整运行上下文（History）时，该 Agent 可以转换为 Tool 进行调用:
-
-```go
-func NewAgentTool(_ context.Context, agent Agent, options ...AgentToolOption) tool.BaseTool
-```
-
-转换为 Tool 后，Agent 可以被支持 function calling 的 ChatModel 调用，也可以被所有基于 LLM 驱动的 Agent 调用，调用方式取决于 Agent 实现。
-
-消息历史隔离：作为 Tool 的 Agent，不会继承上级 Agent 的消息历史（History）。
-
-SessionValues 共享：但是，会共享上级 Agent 的 SessionValues，即读写同一个 KV map。
-
-内部事件透出：作为 Tool 的 Agent 也是 Agent，会产生 AgentEvent。这些内部的 AgentEvent，默认情况下，不会通过 `Runner` 返回的 `AsyncIterator` 透出。在部分业务场景中，如果需要像用户透出内部 AgentTool 的 AgentEvent，需要在 AgentTool 的上级 `ChatModelAgent` 的 `ToolsConfig` 中增加配置，开启内部事件透出：
-
-```go
-// from adk/chatmodel.go
-
-**type **ToolsConfig **struct **{
-    // other configurations...
-
-    _// EmitInternalEvents indicates whether internal events from agentTool should be emitted_
-_    // to the parent generator via a tool option injection at run-time._
-_    _EmitInternalEvents bool
-}
-```
-
-这些内部事件，不会进入上级 agent 的上下文（除了本来就会进入的最后一条 message），各种 AgentAction 也不会生效（InterruptAction 除外）。

docs/Eino/docs/core_modules/eino_adk/agent_extension.md

@@ -1,118 +0,0 @@
----
-Description: ""
-date: "2025-11-20"
-lastmod: ""
-tags: []
-title: Agent Runner 与扩展
-weight: 6
----
-
-# Agent Runner
-
-## 定义
-
-Runner 是 Eino ADK 中负责执行 Agent 的核心引擎。它的主要作用是管理和控制 Agent 的整个生命周期，如处理多 Agent 协作，保存传递上下文等，interrupt、callback 等切面能力也均依赖 Runner 实现。任何 Agent 都应通过 Runner 来运行。
-
-## Interrupt & Resume
-
-Agent Runner 提供运行时中断与恢复的功能，该功能允许一个正在运行的 Agent 主动中断其执行并保存当前状态，支持从中断点恢复执行。该功能常用于 Agent 处理流程中需要外部输入、长时间等待或可暂停等场景。
-
-下面将对一次中断到恢复过程中的三个关键点进行介绍：
-
-1. Interrupted Action：由 Agent 抛出中断事件，Agent Runner 拦截
-2. Checkpoint：Agent Runner 拦截事件后保存当前运行状态
-3. Resume：运行条件重新 ready 后，由 Agent Runner 从断点恢复运行
-
-### Interrupted Action
-
-在 Agent 的执行过程中，可以通过产生包含 Interrupted Action 的 AgentEvent 来主动中断 Runner 的运行。
-
-当 Event 中的 Interrupted 不为空时，Agent Runner 便会认为发生中断：
-
-```go
-// github.com/cloudwego/eino/adk/interface.go
-type AgentAction struct {
-    // other actions
-    Interrupted *InterruptInfo
-    // other actions
-}
-
-// github.com/cloudwego/eino/adk/interrupt.go
-type InterruptInfo struct {
-    Data any
-}
-```
-
-当中断发生时，可以通过 InterruptInfo 结构体附带自定义的中断信息。此信息：
-
-1. 会被传递给调用者，可以通过该信息向调用者说明中断原因等
-2. 如果后续需要恢复 Agent 运行，InterruptInfo 会在恢复时重新传递给中断的 Agent，Agent 可以依据该信息恢复运行
-
-```go
-// 例如 ChatModelAgent 中断时，会发送如下的 AgentEvent：
-h.Send(&AgentEvent{AgentName: h.agentName, Action: &AgentAction{
-    Interrupted: &InterruptInfo{
-       Data: &ChatModelAgentInterruptInfo{Data: data, Info: info},
-    },
-}})
-```
-
-### 状态持久化 (Checkpoint)
-
-当 Runner 捕获到这个带有 Interrupted Action 的 Event 时，会立即终止当前的执行流程。 如果：
-
-1. Runner 中设置了 CheckPointStore
-
-```go
-// github.com/cloudwego/eino/adk/runner.go
-type RunnerConfig struct {
-    // other fields
-    CheckPointStore CheckPointStore
-}
-
-// github.com/cloudwego/eino/adk/interrupt.go
-type CheckPointStore interface {
-    Set(ctx context.Context, key string, value []byte) error
-    Get(ctx context.Context, key string) ([]byte, bool, error)
-}
-```
-
-1. 调用 Runner 时通过 AgentRunOption WithCheckPointID 传入 CheckPointID
-
-```go
-// github.com/cloudwego/eino/adk/interrupt.go
-func WithCheckPointID(id string) _AgentRunOption_
-```
-
-Runner 在终止运行后会将当前运行状态（原始输入、对话历史等）以及 Agent 抛出的 InterruptInfo 以 CheckPointID 为 key 持久化到 CheckPointStore 中。
-
-> 💡
-> 为了保存 interface 中数据的原本类型，Eino ADK 使用 gob（[https://pkg.go.dev/encoding/gob](https://pkg.go.dev/encoding/gob)）序列化运行状态。因此在使用自定义类型时需要提前使用 gob.Register 或 gob.RegisterName 注册类型（更推荐后者，前者使用路径加类型名作为默认名字，因此类型的位置和名字均不能发生变更）。Eino 会自动注册框架内置的类型。
-
-### Resume
-
-运行中断，调用 Runner 的 Resume 接口传入中断时的 CheckPointID 可以恢复运行：
-
-```go
-// github.com/cloudwego/eino/adk/runner.go
-func (r *Runner) Resume(ctx context.Context, checkPointID string, opts ...AgentRunOption) (*AsyncIterator[*AgentEvent], error)
-```
-
-恢复 Agent 运行需要发生中断的 Agent 实现了 ResumableAgent 接口， Runner 从 CheckPointerStore 读取运行状态并恢复运行，其中 InterruptInfo 和上次运行配置的 EnableStreaming 会作为输入提供给 Agent：
-
-```go
-// github.com/cloudwego/eino/adk/interface.go
-type ResumableAgent interface {
-    Agent
-
-    Resume(ctx context.Context, info *ResumeInfo, opts ...AgentRunOption) *AsyncIterator[*AgentEvent]
-}
-
-// github.com/cloudwego/eino/adk/interrupt.go
-type ResumeInfo struct {
-    EnableStreaming bool
-    *_InterruptInfo_
-}
-```
-
-Resume 如果向 Agent 传入新信息，可以定义 AgentRunOption，在调用 Runner.Resume 时传入。

docs/Eino/docs/core_modules/eino_adk/agent_implementation/_index.md

@@ -1,12 +0,0 @@
----
-Description: ""
-date: "2025-11-20"
-lastmod: ""
-tags: []
-title: Agent 实现
-weight: 5
----
-
-用户可以通过实现 Agent 接口自定义 Agent。自定义 Agent 建议严格遵守上述规则，在应用、迭代、合作中可以带来便利。
-
-简单自定义 Agent 可以参考： [https://github.com/cloudwego/eino-examples/blob/main/adk/intro/custom/myagent.go](https://github.com/cloudwego/eino-examples/blob/main/adk/intro/custom/myagent.go)

docs/Eino/docs/core_modules/eino_adk/agent_implementation/chat_model.md

@@ -1,897 +0,0 @@
----
-Description: ""
-date: "2026-03-24"
-lastmod: ""
-tags: []
-title: ChatModelAgent
-weight: 1
----
-
-# ChatModelAgent 概述
-
-## Import Path
-
-`import ``github.com/cloudwego/eino/adk`
-
-## 什么是 ChatModelAgent
-
-`ChatModelAgent` 是 Eino ADK 中的一个核心预构建 的 Agent，它封装了与大语言模型（LLM）进行交互、并支持使用工具来完成任务的复杂逻辑。
-
-## ChatModelAgent ReAct 模式
-
-`ChatModelAgent` 内使用了 [ReAct](https://react-lm.github.io/) 模式，该模式旨在通过让 ChatModel 进行显式的、一步一步的“思考”来解决复杂问题。为 `ChatModelAgent` 配置了工具后，它在内部的执行流程就遵循了 ReAct 模式：
-
-- 调用 ChatModel（Reason）
-- LLM 返回工具调用请求（Action）
-- ChatModelAgent 执行工具（Act）
-- 它将工具结果返回给 ChatModel（Observation），然后开始新的循环，直到 ChatModel 判断不需要调用 Tool 结束。
-
-当没有配置工具时，`ChatModelAgent` 退化为一次 ChatModel 调用。
-
-<a href="/img/eino/eino_adk_chat_model_agent_view.png" target="_blank"><img src="/img/eino/eino_adk_chat_model_agent_view.png" width="100%" /></a>
-
-可以通过 ToolsConfig 为 ChatModelAgent 配置 Tool：
-
-```go
-// github.com/cloudwego/eino/adk/chatmodel.go
-
-type ToolsConfig struct {
-    compose.ToolsNodeConfig
-
-    // Names of the tools that will make agent return directly when the tool is called.
-    // When multiple tools are called and more than one tool is in the return directly list, only the first one will be returned.
-    ReturnDirectly map[string]bool
-    
-    // EmitInternalEvents indicates whether internal events from agentTool should be emitted
-    // to the parent generator via a tool option injection at run-time.
-    EmitInternalEvents bool
-}
-```
-
-ToolsConfig 复用了 Eino Graph ToolsNodeConfig，详细参考：[Eino: ToolsNode&Tool 使用说明](/zh/docs/eino/core_modules/components/tools_node_guide)。额外提供了 ReturnDirectly 配置，ChatModelAgent 调用配置在 ReturnDirectly 中的 Tool 后会直接退出。
-
-## ChatModelAgent 配置字段
-
-> 💡
-> 注意：GenModelInput 默认情况下，会通过 adk.GetSessionValues() 并以 F-String 的格式渲染 Instruction，如需关闭此行为，可定制 GenModelInput 方法。
-
-```go
-type ChatModelAgentConfig struct {
-    // Name of the agent. Better be unique across all agents.
-    Name string
-    // Description of the agent's capabilities.
-    // Helps other agents determine whether to transfer tasks to this agent.
-    Description string
-    // Instruction used as the system prompt for this agent.
-    // Optional. If empty, no system prompt will be used.
-    // Supports f-string placeholders for session values in default GenModelInput, for example:
-    // "You are a helpful assistant. The current time is {Time}. The current user is {User}."
-    // These placeholders will be replaced with session values for "Time" and "User".
-    Instruction string
-
-    Model model.ToolCallingChatModel
-
-    ToolsConfig ToolsConfig
-
-    // GenModelInput transforms instructions and input messages into the model's input format.
-    // Optional. Defaults to defaultGenModelInput which combines instruction and messages.
-    GenModelInput GenModelInput
-
-    // Exit defines the tool used to terminate the agent process.
-    // Optional. If nil, no Exit Action will be generated.
-    // You can use the provided 'ExitTool' implementation directly.
-    Exit tool.BaseTool
-
-    // OutputKey stores the agent's response in the session.
-    // Optional. When set, stores output via AddSessionValue(ctx, outputKey, msg.Content).
-    OutputKey string
-
-    // MaxIterations defines the upper limit of ChatModel generation cycles.
-    // The agent will terminate with an error if this limit is exceeded.
-    // Optional. Defaults to 20.
-    MaxIterations int
-    
-    // ModelRetryConfig configures retry behavior for the ChatModel.
-    // When set, the agent will automatically retry failed ChatModel calls
-    // based on the configured policy.
-    // Optional. If nil, no retry will be performed.
-    ModelRetryConfig *ModelRetryConfig
-}
-
-type ToolsConfig struct {
-    compose.ToolsNodeConfig
-
-    // Names of the tools that will make agent return directly when the tool is called.
-    // When multiple tools are called and more than one tool is in the return directly list, only the first one will be returned.
-    ReturnDirectly map[string]bool
-    
-    // EmitInternalEvents indicates whether internal events from agentTool should be emitted
-    // to the parent generator via a tool option injection at run-time.
-    EmitInternalEvents bool
-}
-
-type GenModelInput func(ctx context.Context, instruction string, input *AgentInput) ([]Message, error)
-```
-
-- `Name`：Agent 名称
-- `Description`：Agent 描述
-- `Instruction`：调用 ChatModel 时的 System Prompt，支持 f-string 渲染
-- `Model`：运行所使用的 ChatModel，要求支持工具调用
-- `ToolsConfig`：工具配置
-  - ToolsConfig 复用了 Eino Graph ToolsNodeConfig，详细参考：[Eino: ToolsNode&Tool 使用说明](/zh/docs/eino/core_modules/components/tools_node_guide)。
-  - ReturnDirectly：当 ChatModelAgent 调用配置在 ReturnDirectly 中的 Tool 后，将携带结果立刻退出，不会按照 react 模式返回 ChatModel。如果命中了多个 Tool，只有首个 Tool 会返回。Map key 为 Tool 名称。
-  - EmitInternalEvents：当通过 adk.AgentTool() 将一个 Agent 通过 ToolCall 的形式当成 SubAgent 时，默认情况下，这个 SubAgent 不会发送 AgentEvent，只将最终结果作为 ToolResult 返回。
-- `GenModelInput`：Agent 被调用时会使用该方法将 `Instruction` 和 `AgentInput` 转换为调用 ChatModel 的 Messages。Agent 提供了默认的 GenModelInput 方法：
-  1. 将 `Instruction` 作为 `System Message` 加到 `AgentInput.Messages` 前
-  2. 将 `SessionValues` 为 variables 渲染到步骤 1 的 message list 中
-
-> 💡
-> 默认的 `GenModelInput` 使用 pyfmt 渲染，message list 中的文本会被作为 pyfmt 模板，这意味着文本中的 '{' 与 '}' 都会被视为关键字，如果希望直接输入这两个字符，需要进行转义 '{{'、'}}'
-
-- `OutputKey`：配置后，ChatModelAgent 运行产生的最后一条 Message 将会以 `OutputKey` 为 key 设置到 `SessionValues` 中
-- `MaxIterations`：react 模式下 ChatModel 最大生成次数，超过时 Agent 会报错退出，默认值为 20
-- `Exit`：Exit 是一个特殊的 Tool，当模型调用这个工具并执行后，ChatModelAgent 将直接退出，效果与 `ToolsConfig.ReturnDirectly` 类似。ADK 提供了一个默认 ExitTool 实现供用户使用：
-
-```go
-type ExitTool struct{}
-
-func (et ExitTool) Info(_ context.Context) (*schema.ToolInfo, error) {
-    return ToolInfoExit, nil
-}
-
-func (et ExitTool) InvokableRun(ctx context.Context, argumentsInJSON string, _ ...tool.Option) (string, error) {
-    type exitParams struct {
-       FinalResult string `json:"final_result"`
-    }
-
-    params := &exitParams{}
-    err := sonic.UnmarshalString(argumentsInJSON, params)
-    if err != nil {
-       return "", err
-    }
-
-    err = SendToolGenAction(ctx, "exit", NewExitAction())
-    if err != nil {
-       return "", err
-    }
-
-    return params.FinalResult, nil
-}
-```
-
-- `ModelRetryConfig`: 配置后，ChatModel 请求过程中发生的各种错误（包括直接返回错误、流式响应过程中发生错误等），都会按照配置的策略选择是否以及何时进行重试。如果是流式响应过程中发生错误，则这一次流式响应依然会第一时间通过 AgentEvent 的形式返回出去。如果这次流式响应过程中的错误，按照配置的策略，会进行重试，则消费 AgentEvent 中的 message stream，会得到 `WillRetryError`。用户可以处理这个 error，做对应的上屏展示等处理，示例如下：
-
-```go
-iterator := agent.Run(ctx, input)
-for {
-    event, ok := iterator.Next()
-    if !ok {
-        break
-    }
-    
-    if event.Err != nil {
-        handleFinalError(event.Err)
-        break
-    }
-    
-    // Process streaming output
-    if event.Output != nil && event.Output.MessageOutput.IsStreaming {
-        stream := event.Output.MessageOutput.MessageStream
-        for {
-            msg, err := stream.Recv()
-            if err == io.EOF {
-                break  // Stream completed successfully
-            }
-            if err != nil {
-                // Check if this error will be retried (more streams coming)
-                var willRetry *adk.WillRetryError
-                if errors.As(err, &willRetry) {
-                    log.Printf("Attempt %d failed, retrying...", willRetry.RetryAttempt)
-                    break  // Wait for next event with new stream
-                }
-                // Original error - won't retry, agent will stop and the next AgentEvent probably will be an error
-                log.Printf("Final error (no retry): %v", err)
-                break
-            }
-            // Display chunk to user
-            displayChunk(msg)
-        }
-    }
-}
-```
-
-## ChatModelAgent Transfer
-
-`ChatModelAgent` 支持将其他 Agent 的元信息转为自身的 Tool ，经由 ChatModel 判断实现动态 Transfer：
-
-- `ChatModelAgent` 实现了 `OnSubAgents` 接口，使用 `SetSubAgents` 为 `ChatModelAgent` 设置子 Agents 后，`ChatModelAgent` 会增加一个 `Transfer Tool`，并且在 prompt 中指示 ChatModel 在需要 transfer 时调用这个 Tool 并以 transfer 目标 AgentName 作为 Tool 输入。
-
-```go
-const (
-    TransferToAgentInstruction = `Available other agents: %s
-
-Decision rule:
-- If you're best suited for the question according to your description: ANSWER
-- If another agent is better according its description: CALL '%s' function with their agent name
-
-When transferring: OUTPUT ONLY THE FUNCTION CALL`
-)
-
-func genTransferToAgentInstruction(ctx context.Context, agents []Agent) string {
-    var sb strings.Builder
-    for _, agent := range agents {
-       sb.WriteString(fmt.Sprintf("\n- Agent name: %s\n  Agent description: %s",
-          agent.Name(ctx), agent.Description(ctx)))
-    }
-
-    return fmt.Sprintf(TransferToAgentInstruction, sb.String(), TransferToAgentToolName)
-}
-```
-
-- `Transfer Tool` 运行会设置 Transfer Event，指定跳转到目标 Agent 上，完成后 ChatModelAgent 退出。
-- Agent Runner 接收到 Transfer Event 后，跳转到目标 Agent 上执行，完成 Transfer 操作
-
-## ChatModelAgent AgentAsTool
-
-当需要被调用的 Agent 不需要完整的运行上下文，仅需要明确清晰的入参即可正确运行时，该 Agent 可以转换为 Tool 交由 `ChatModelAgent` 判断调用：
-
-- ADK 中提供了工具方法，可以方便地将 Eino ADK Agent 转化为 Tool 供 ChatModelAgent 调用：
-
-```go
-// github.com/cloudwego/eino/adk/agent_tool.go    
-
-func NewAgentTool(_ context.Context, agent Agent, options ...AgentToolOption) tool.BaseTool
-```
-
-- 被转换为 Tool 后的 Agent 可以通过 `ToolsConfig` 直接注册在 ChatModelAgent 中
-
-```go
-bookRecommender := NewBookRecommendAgent()
-bookRecommendeTool := NewAgentTool(ctx, bookRecommender)
-
-a, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    // ...
-    ToolsConfig: adk.ToolsConfig{
-        ToolsNodeConfig: compose.ToolsNodeConfig{
-            Tools: []tool.BaseTool{bookRecommendeTool},
-        },
-    },
-})
-```
-
-## ChatModelAgent Middleware
-
-`ChatModelAgentMiddleware` 是 `ChatModelAgent` 的扩展机制，允许开发者在 Agent 执行的各个阶段注入自定义逻辑：
-
-<a href="/img/eino/TXVlwT7Iohh1EtbEeC6cIptxnZd.png" target="_blank"><img src="/img/eino/TXVlwT7Iohh1EtbEeC6cIptxnZd.png" width="100%" /></a>
-
-`ChatModelAgentMiddleware` 定义为 interface，开发者可以实现此 interface 并通过配置到 `ChatModelAgentConfig` 使其在 `ChatModelAgent` 中生效：
-
-```go
-type ChatModelAgentMiddleware interface {
-    // ...
-}
-
-a, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-    // ...
-    Handlers: []adk.ChatModelAgentMiddleware{
-        &MyMiddleware{},
-    },
-})
-```
-
-**使用 BaseChatModelAgentMiddleware**
-
-`BaseChatModelAgentMiddleware` 提供所有方法的默认空实现。通过嵌入它，可以只覆盖需要的方法：
-
-```go
-type MyMiddleware struct {
-    *adk.BaseChatModelAgentMiddleware
-    // 自定义字段
-    logger *log.Logger
-}
-
-// 只需覆盖需要的方法
-func (m *MyMiddleware) BeforeModelRewriteState(
-    ctx context.Context, 
-    state *adk.ChatModelAgentState, 
-    mc *adk.ModelContext,
-) (context.Context, *adk.ChatModelAgentState, error) {
-    m.logger.Printf("Messages count: %d", len(state.Messages))
-    return ctx, state, nil
-}
-```
-
-### BeforeAgent
-
-在每次 Agent 运行前调用，可用于修改指令和工具配置。ChatModelAgentContext 定义了 BeforeAgent 中可读写的内容：
-
-```go
-type ChatModelAgentContext struct {
-    // InstructionAgent 是当前 Agent 的指令
-    Instruction string
-    // Tools 是当前配置的原始工具列表
-    Tools []tool.BaseTool
-    // ReturnDirectly 配置调用后直接返回的工具名称集合
-    ReturnDirectly map[string]bool
-}
-
-type ChatModelAgentMiddleware interface {
-    // ...
-    BeforeAgent(ctx context.Context, runCtx *ChatModelAgentContext) (context.Context, *ChatModelAgentContext, error)
-    // ...
-}
-```
-
-例子：
-
-```go
-func (m *MyMiddleware) BeforeAgent(
-    ctx context.Context, 
-    runCtx *adk.ChatModelAgentContext,
-) (context.Context, *adk.ChatModelAgentContext, error) {
-    // 拷贝 runCtx，避免修改输入
-    nRunCtx := *runCtx
-    
-    // 修改指令
-    nRunCtx.Instruction += "\n\n请始终使用中文回复。"
-    
-    // 添加工具
-    nRunCtx.Tools = append(runCtx.Tools, myCustomTool)
-    
-    // 设置工具直接返回
-    nRunCtx.ReturnDirectly["my_tool"] = true
-    
-    return ctx, &nRunCtx, nil
-}
-```
-
-### BeforeModelRewriteState / AfterModelRewriteState
-
-在每次模型调用前/后调用，可用于检查和修改消息历史。ModelContext 定义了只读内容，ChatModelAgentState 定义了可读写内容：
-
-```go
-type ModelContext struct {
-    // Tools 包含当前配置给 Agent 的工具列表
-    // 在请求时填充，包含将要发送给模型的工具信息
-    Tools []*schema.ToolInfo
-
-    // ModelRetryConfig 包含模型的重试配置
-    // 从 Agent 的 ModelRetryConfig 填充
-    ModelRetryConfig *ModelRetryConfig
-}
-
-type ChatModelAgentState struct {
-    // Messages 包含当前会话中的所有消息
-    Messages []Message
-}
-
-type ChatModelAgentMiddleware interface {
-    BeforeModelRewriteState(ctx context.Context, state *ChatModelAgentState, mc *ModelContext) (context.Context, *ChatModelAgentState, error)
-    AfterModelRewriteState(ctx context.Context, state *ChatModelAgentState, mc *ModelContext) (context.Context, *ChatModelAgentState, error)
-}
-```
-
-例子：
-
-```go
-func (m *MyMiddleware) BeforeModelRewriteState(
-    ctx context.Context,
-    state *adk.ChatModelAgentState,
-    mc *adk.ModelContext,
-) (context.Context, *adk.ChatModelAgentState, error) {
-    // 拷贝 state，避免修改入参
-    nState := *state
-    
-    // 检查消息历史
-    if len(state.Messages) > 50 {
-        // 截断过旧的消息
-        nState.Messages = state.Messages[len(state.Messages)-50:]
-    }
-    return ctx, &nState, nil
-}
-
-func (m *MyMiddleware) AfterModelRewriteState(
-    ctx context.Context,
-    state *adk.ChatModelAgentState,
-    mc *adk.ModelContext,
-) (context.Context, *adk.ChatModelAgentState, error) {
-    // 模型响应是最后一条消息
-    lastMsg := state.Messages[len(state.Messages)-1]
-    m.logger.Printf("Model response: %s", lastMsg.Content)
-    return ctx, state, nil
-}
-```
-
-### WrapModel
-
-包装模型调用，可用于拦截和修改模型的输入输出：
-
-```go
-type ChatModelAgentMiddleware interface {
-    WrapModel(ctx context.Context, m model.BaseChatModel, mc *ModelContext) (model.BaseChatModel, error)
-}
-```
-
-例子：
-
-```go
-func (m *MyMiddleware) WrapModel(
-    ctx context.Context,
-    chatModel model.BaseChatModel,
-    mc *adk.ModelContext,
-) (model.BaseChatModel, error) {
-    return &loggingModel{
-        inner: chatModel,
-        logger: m.logger,
-    }, nil
-}
-
-type loggingModel struct {
-    inner  model.BaseChatModel
-    logger *log.Logger
-}
-
-func (m *loggingModel) Generate(ctx context.Context, msgs []*schema.Message, opts ...model.Option) (*schema.Message, error) {
-    m.logger.Printf("Input messages: %d", len(msgs))
-    resp, err := m.inner.Generate(ctx, msgs, opts...)
-    m.logger.Printf("Output: %v, error: %v", resp != nil, err)
-    return resp, err
-}
-
-func (m *loggingModel) Stream(ctx context.Context, msgs []*schema.Message, opts ...model.Option) (*schema.StreamReader[*schema.Message], error) {
-    return m.inner.Stream(ctx, msgs, opts...)
-}
-```
-
-### WrapInvokableToolCall / WrapStreamableToolCall
-
-包装工具调用，可用于拦截和修改工具的输入输出：
-
-```go
-// InvokableToolCallEndpoint 是工具调用的函数签名。
-// Middleware 开发者围绕这个 Endpoint 添加自定义逻辑。
-type InvokableToolCallEndpoint func(ctx context.Context, argumentsInJSON string, opts ...tool.Option) (string, error)
-
-// StreamableToolCallEndpoint 是流式工具调用的函数签名。
-// Middleware 开发者围绕这个 Endpoint 添加自定义逻辑。
-type StreamableToolCallEndpoint func(ctx context.Context, argumentsInJSON string, opts ...tool.Option) (*schema.StreamReader[string], error)
-
-type ToolContext struct {
-    // Name 说明了本次调用工具的名称
-    Name   string
-    // CallID 说明了本次调用工具的 ToolCallID
-    CallID string
-}
-
-type ChatModelAgentMiddleware interface {
-    WrapInvokableToolCall(ctx context.Context, endpoint InvokableToolCallEndpoint, tCtx *ToolContext) (InvokableToolCallEndpoint, error)
-    WrapStreamableToolCall(ctx context.Context, endpoint StreamableToolCallEndpoint, tCtx *ToolContext) (StreamableToolCallEndpoint, error)
-}
-```
-
-例子：
-
-```go
-func (m *MyMiddleware) WrapInvokableToolCall(
-    ctx context.Context,
-    endpoint adk.InvokableToolCallEndpoint,
-    tCtx *adk.ToolContext,
-) (adk.InvokableToolCallEndpoint, error) {
-    return func(ctx context.Context, argumentsInJSON string, opts ...tool.Option) (string, error) {
-        m.logger.Printf("Calling tool: %s (ID: %s)", tCtx.Name, tCtx.CallID)
-        start := time.Now()
-        
-        result, err := endpoint(ctx, argumentsInJSON, opts...)
-        
-        m.logger.Printf("Tool %s completed in %v", tCtx.Name, time.Since(start))
-        return result, err
-    }, nil
-}
-```
-
-# ChatModelAgent 使用示例
-
-## 场景说明
-
-创建一个图书推荐 Agent，Agent 将能够根据用户的输入推荐相关图书。
-
-## 代码实现
-
-### 步骤 1: 定义工具
-
-图书推荐 Agent 需要一个根据能够根据用户要求（题材、评分等）检索图书的工具 `book_search` 。
-
-利用 Eino 提供的工具方法可以方便地创建（可参考[如何创建一个 tool ?](/zh/docs/eino/core_modules/components/tools_node_guide/how_to_create_a_tool)）：
-
-```go
-import (
-    "context"
-    "log"
-
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/components/tool/utils"
-)
-
-type BookSearchInput struct {
-    Genre     string `json:"genre" jsonschema:"description=Preferred book genre,enum=fiction,enum=sci-fi,enum=mystery,enum=biography,enum=business"`
-    MaxPages  int    `json:"max_pages" jsonschema:"description=Maximum page length (0 for no limit)"`
-    MinRating int    `json:"min_rating" jsonschema:"description=Minimum user rating (0-5 scale)"`
-}
-
-type BookSearchOutput struct {
-    Books []string
-}
-
-func NewBookRecommender() tool.InvokableTool {
-    bookSearchTool, err := utils.InferTool("search_book", "Search books based on user preferences", func(ctx context.Context, input *BookSearchInput) (output *BookSearchOutput, err error) {
-       // search code
-       // ...
-       return &BookSearchOutput{Books: []string{"God's blessing on this wonderful world!"}}, nil
-    })
-    if err != nil {
-       log.Fatalf("failed to create search book tool: %v", err)
-    }
-    return bookSearchTool
-}
-```
-
-### 步骤 2: 创建 ChatModel
-
-Eino 提供了多种 ChatModel 封装（如 openai、gemini、doubao 等，详见 [Eino: ChatModel 使用说明](/zh/docs/eino/core_modules/components/chat_model_guide)），这里以 openai ChatModel 为例：
-
-```go
-import (
-    "context"
-    "fmt"
-    "log"
-    "os"
-
-    "github.com/cloudwego/eino-ext/components/model/openai"
-    "github.com/cloudwego/eino/components/model"
-)
-
-func NewChatModel() model.ToolCallingChatModel {
-    ctx := context.Background()
-    apiKey := os.Getenv("OPENAI_API_KEY")
-    openaiModel := os.Getenv("OPENAI_MODEL")
-
-    cm, err := openai.NewChatModel(ctx, &openai.ChatModelConfig{
-       APIKey: apiKey,
-       Model:  openaiModel,
-    })
-    if err != nil {
-       log.Fatal(fmt.Errorf("failed to create chatmodel: %w", err))
-    }
-    return cm
-}
-```
-
-### 步骤 3: 创建 ChatModelAgent
-
-除了配置 ChatModel 和工具外，还需要配置描述 Agent 功能用途的 Name 和 Description，以及指示 ChatModel 的 Instruction，Instruction 最终会作为 system message 被传递给 ChatModel。
-
-```go
-import (
-    "context"
-    "fmt"
-    "log"
-
-    "github.com/cloudwego/eino/adk"
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/compose"
-)
-
-func NewBookRecommendAgent() adk.Agent {
-    ctx := context.Background()
-
-    a, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-       Name:        "BookRecommender",
-       Description: "An agent that can recommend books",
-       Instruction: `You are an expert book recommender. Based on the user's request, use the "search_book" tool to find relevant books. Finally, present the results to the user.`,
-       Model:       NewChatModel(),
-       ToolsConfig: adk.ToolsConfig{
-          ToolsNodeConfig: compose.ToolsNodeConfig{
-             Tools: []tool.BaseTool{NewBookRecommender()},
-          },
-       },
-    })
-    if err != nil {
-       log.Fatal(fmt.Errorf("failed to create chatmodel: %w", err))
-    }
-
-    return a
-}
-```
-
-### 
-
-### 步骤 4: 通过 Runner 运行
-
-```go
-import (
-    "context"
-    "fmt"
-    "log"
-    "os"
-
-    "github.com/cloudwego/eino/adk"
-
-    "github.com/cloudwego/eino-examples/adk/intro/chatmodel/subagents"
-)
-
-func main() {
-    ctx := context.Background()
-    a := subagents.NewBookRecommendAgent()
-    runner := adk.NewRunner(ctx, adk.RunnerConfig{
-       Agent: a,
-    })
-    iter := runner.Query(ctx, "recommend a fiction book to me")
-    for {
-       event, ok := iter.Next()
-       if !ok {
-          break
-       }
-       if event.Err != nil {
-          log.Fatal(event.Err)
-       }
-       msg, err := event.Output.MessageOutput.GetMessage()
-       if err != nil {
-          log.Fatal(err)
-       }
-       fmt.Printf("\nmessage:\n%v\n======", msg)
-    }
-}
-```
-
-## 运行结果
-
-```yaml
-message:
-assistant: 
-tool_calls:
-{Index:<nil> ID:call_o2It087hoqj8L7atzr70EnfG Type:function Function:{Name:search_book Arguments:{"genre":"fiction","max_pages":0,"min_rating":0}} Extra:map[]}
-
-finish_reason: tool_calls
-usage: &{140 24 164}
-======
-
-
-message:
-tool: {"Books":["God's blessing on this wonderful world!"]}
-tool_call_id: call_o2It087hoqj8L7atzr70EnfG
-tool_call_name: search_book
-======
-
-
-message:
-assistant: I recommend the fiction book "God's blessing on this wonderful world!". It's a great choice for readers looking for an exciting story. Enjoy your reading!
-finish_reason: stop
-usage: &{185 31 216}
-======
-```
-
-# ChatModelAgent 中断与恢复
-
-## 介绍
-
-`ChatModelAgent` 使用了 Eino Graph 实现，因此在 agent 中可以复用 Eino Graph 的 Interrupt&Resume 能力。
-
-- Interrupt 时，通过在工具中返回特殊错误使 Graph 触发中断并向外抛出自定义信息，在恢复时 Graph 会重新运行此工具：
-
-```go
-// github.com/cloudwego/eino/adk/interrupt.go
-
-func NewInterruptAndRerunErr(extra any) error
-```
-
-- Resume 时，支持自定义 ToolOption，用于在恢复时传递额外信息到 Tool 中：
-
-```go
-import (
-    "github.com/cloudwego/eino/components/tool"
-)
-
-type askForClarificationOptions struct {
-    NewInput *string
-}
-
-func WithNewInput(input string) tool.Option {
-    return tool.WrapImplSpecificOptFn(func(t *askForClarificationOptions) {
-       t.NewInput = &input
-    })
-}
-```
-
-## 示例
-
-下面我们将基于上面【ChatModelAgent 使用示例】小节中的代码，为 `BookRecommendAgent` 增加一个工具 `ask_for_clarification`，当用户提供的信息不足以支持推荐时，Agent 将调用这个工具向用户询问更多信息，`ask_for_clarification` 使用了 Interrupt&Resume 能力来实现向用户“询问”。
-
-### 步骤 1 : 新增 Tool 支持中断
-
-```go
-import (
-    "context"
-    "log"
-
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/components/tool/utils"
-    "github.com/cloudwego/eino/compose"
-)
-
-type askForClarificationOptions struct {
-    NewInput *string
-}
-
-func WithNewInput(input string) tool.Option {
-    return tool.WrapImplSpecificOptFn(func(t *askForClarificationOptions) {
-       t.NewInput = &input
-    })
-}
-
-type AskForClarificationInput struct {
-    Question string `json:"question" jsonschema:"description=The specific question you want to ask the user to get the missing information"`
-}
-
-func NewAskForClarificationTool() tool.InvokableTool {
-    t, err := utils.InferOptionableTool(
-       "ask_for_clarification",
-       "Call this tool when the user's request is ambiguous or lacks the necessary information to proceed. Use it to ask a follow-up question to get the details you need, such as the book's genre, before you can use other tools effectively.",
-       func(ctx context.Context, input *AskForClarificationInput, opts ...tool.Option) (output string, err error) {
-          o := tool.GetImplSpecificOptions[askForClarificationOptions](nil, opts...)
-          if o.NewInput == nil {
-             return "", compose.NewInterruptAndRerunErr(input.Question)
-          }
-          return *o.NewInput, nil
-       })
-    if err != nil {
-       log.Fatal(err)
-    }
-    return t
-}
-```
-
-### 步骤 2: 添加 Tool 到 Agent 中
-
-```go
-func NewBookRecommendAgent() adk.Agent {
-    // xxx
-    a, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
-       // xxx
-       ToolsConfig: adk.ToolsConfig{
-          ToolsNodeConfig: compose.ToolsNodeConfig{
-             Tools: []tool.BaseTool{NewBookRecommender(), NewAskForClarificationTool()},
-          },
-          // Tool 内部通过 AgentTool() 调用 SubAgent 时，是否将这个 SubAgent 的 AgentEvent 输出
-          EmitInternalEvents: true,
-       },
-    })
-    // xxx
-}
-```
-
-### 步骤 3: Agent Runner 配置 CheckPointStore
-
-在 Runner 中配置 `CheckPointStore`（例子中使用最简单的 InMemoryStore），并在调用 Agent 时传入 `CheckPointID`，用于在恢复时使用。另外，在中断时，Graph 会将 `InterruptInfo` 放入 `Interrupted.Data` 中：
-
-```go
-func newInMemoryStore() compose.CheckPointStore {
-    return &inMemoryStore{
-       mem: map[string][]byte{},
-    }
-}
-
-func main() {
-    ctx := context.Background()
-    a := subagents.NewBookRecommendAgent()
-    runner := adk.NewRunner(ctx, adk.RunnerConfig{
-       EnableStreaming: true, // you can disable streaming here
-       Agent:           a,
-       CheckPointStore: newInMemoryStore(),
-    })
-    iter := runner.Query(ctx, "recommend a book to me", adk.WithCheckPointID("1"))
-    for {
-       event, ok := iter.Next()
-       if !ok {
-          break
-       }
-       if event.Err != nil {
-          log.Fatal(event.Err)
-       }
-       if event.Action != nil && event.Action.Interrupted != nil {
-          fmt.Printf("\ninterrupt happened, info: %+v\n", event.Action.Interrupted.Data.(*adk.ChatModelAgentInterruptInfo).RerunNodesExtra["ToolNode"])
-          continue
-       }
-       msg, err := event.Output.MessageOutput.GetMessage()
-       if err != nil {
-          log.Fatal(err)
-       }
-       fmt.Printf("\nmessage:\n%v\n======\n\n", msg)
-    }
-
-    scanner := bufio.NewScanner(os.Stdin)
-    fmt.Print("\nyour input here: ")
-    scanner.Scan()
-    fmt.Println()
-    nInput := scanner.Text()
-
-    iter, err := runner.Resume(ctx, "1", adk.WithToolOptions([]tool.Option{subagents.WithNewInput(nInput)}))
-    if err != nil {
-       log.Fatal(err)
-    }
-    for {
-       event, ok := iter.Next()
-       if !ok {
-          break
-       }
-
-       if event.Err != nil {
-          log.Fatal(event.Err)
-       }
-
-       prints.Event(event)
-    }
-}
-```
-
-### 运行结果
-
-运行后会发生中断
-
-```
-message:
-assistant: 
-tool_calls:
-{Index:<nil> ID:call_3HAobzkJvW3JsTmSHSBRftaG Type:function Function:{Name:ask_for_clarification Arguments:{"question":"Could you please specify the genre you're interested in and any preferences like maximum page length or minimum user rating?"}} Extra:map[]}
-
-finish_reason: tool_calls
-usage: &{219 37 256}
-======
-
-
-interrupt happened, info: &{ToolCalls:[{Index:<nil> ID:call_3HAobzkJvW3JsTmSHSBRftaG Type:function Function:{Name:ask_for_clarification Arguments:{"question":"Could you please specify the genre you're interested in and any preferences like maximum page length or minimum user rating?"}} Extra:map[]}] ExecutedTools:map[] RerunTools:[call_3HAobzkJvW3JsTmSHSBRftaG] RerunExtraMap:map[call_3HAobzkJvW3JsTmSHSBRftaG:Could you please specify the genre you're interested in and any preferences like maximum page length or minimum user rating?]}
-your input here:
-```
-
-stdin 输入后，从 CheckPointStore 取出之前中断状态，结合补全的输入，继续运行
-
-```
-new input is:
-recommend me a fiction book
-
-message:
-tool: recommend me a fiction book
-tool_call_id: call_3HAobzkJvW3JsTmSHSBRftaG
-tool_call_name: ask_for_clarification
-======
-
-
-message:
-assistant: 
-tool_calls:
-{Index:<nil> ID:call_3fC5OqPZLls11epXMv7sZGAF Type:function Function:{Name:search_book Arguments:{"genre":"fiction","max_pages":0,"min_rating":0}} Extra:map[]}
-
-finish_reason: tool_calls
-usage: &{272 24 296}
-======
-
-
-message:
-tool: {"Books":["God's blessing on this wonderful world!"]}
-tool_call_id: call_3fC5OqPZLls11epXMv7sZGAF
-tool_call_name: search_book
-======
-
-
-message:
-assistant: I recommend the fiction book "God's Blessing on This Wonderful World!" Enjoy your reading!
-finish_reason: stop
-usage: &{317 20 337}
-======
-```
-
-# 总结
-
-`ChatModelAgent` 是 ADK 核心 Agent 实现，充当应用程序 "思考" 的部分，利用 LLM 强大的功能进行推理、理解自然语言、作出决策、生成相应、进行工具交互。
-
-`ChatModelAgent` 的行为是非确定性的，通过 LLM 来动态的决定使用哪些工具，或转交控制权到其他 Agent 上。

docs/Eino/docs/core_modules/eino_adk/agent_implementation/deepagents.md

@@ -1,196 +0,0 @@
----
-Description: ""
-date: "2026-03-24"
-lastmod: ""
-tags: []
-title: DeepAgents
-weight: 5
----
-
-## DeepAgents 概述
-
-DeepAgents 是在 ChatModelAgent (详见：[Eino ADK: ChatModelAgent](/zh/docs/eino/core_modules/eino_adk/agent_implementation/chat_model))的基础上实现的一种开箱即用的 agent 方案。你无需自己去拼装提示词、工具或上下文管理，就可以立即获得一个可运行的 agent，并仍可使用 ChatModelAgent 的扩展能力来为 agent 增加业务功能，如添加自定义 tools 和 middleware 等。
-
-**包含内容：**
-
-- **规划能力** —— 通过 `write_todos` 进行任务拆解与进度跟踪
-- **文件系统** —— 提供 `read_file`、`write_file`、`edit_file`、`ls`、`glob`、`grep`，用于读取和写入上下文
-- **Shell 访问** —— 使用 `execute` 运行命令
-- **子 Agent** —— 通过 `task` 将工作委派给拥有独立上下文窗口的子智能体
-- **智能默认配置** —— 内置 Prompt，教模型如何高效使用这些工具
-- **上下文管理** —— 长对话历史自动摘要，大体量输出自动保存到文件
-  - SummarizationMiddleware、ReductionMiddleware 正在建设中
-
-### ImportPath
-
-Eino 版本需大于等于 v0.5.14
-
-```go
-import github.com/cloudwego/eino/adk/prebuilt/deep
-
-agent, err := deep.New(ctx, &deep.Config{})
-```
-
-### DeepAgents 结构
-
-DeepAgents 核心思想在于通过一个主 agent（MainAgent）来协调、规划、委派或自主执行任务。主 agent 利用其内置的 ChatModel 和一系列工具来与外部世界交互或将复杂任务分解给专门的子 agents（SubAgents）。
-
-<a href="/img/eino/A737bctqLoOzNrxbK8Hc5ccmnEb.png" target="_blank"><img src="/img/eino/A737bctqLoOzNrxbK8Hc5ccmnEb.png" width="100%" /></a>
-
-上图展示了 DeepAgents 的核心组件与它们之间的调用关系：
-
-- 主 Agent: 系统的入口和总指挥，接收初始任务，以 ReAct 方式调用工具完成任务并负责最终结果的呈现。
-- ChatModel (ToolCallingChatModel): 通常是一个具备工具调用能力的大语言模型，负责理解任务、推理、选择并调用工具。
-- Tools: MainAgent 可用的一系列能力的集合，包括：
-  - WriteTodos: 内置的规划工具，用于将复杂任务拆解为结构化的待办事项列表。
-  - TaskTool: 一个特殊的工具，作为调用子 Agent 的统一入口。
-  - BuiltinTools、CustomTools: DeepAgents 内置的通用工具以及用户根据业务需求自定义的各类工具。
-- SubAgents: 负责执行具体、独立的子任务，与 MainAgent 上下文独立。
-  - GeneralPurpose: 通用子 Agent，具有与 MainAgent 相同的 Tools（除了 TaskTool），用于在“干净”的上下文中执行子任务。
-  - CustomSubAgents: 用户根据业务需求自定义的各种子 Agent。
-
-### 内置能力
-
-#### Filesystem
-
-> 💡
-> 目前处于 alpha 状态
-
-创建 DeepAgents 时配置相关 Backend，DeepAgents 会自动加载相应工具：
-
-```
-type Config struct {
-    // ...
-    Backend filesystem.Backend
-    Shell filesystem.Shell
-    StreamingShell filesystem.StreamingShell
-    // ...
-}
-```
-
-<table>
-<tr><td>配置</td><td>功能</td><td>添加工具</td></tr>
-<tr><td>Backend</td><td>提供文件系统访问能力，可选</td><td>read_file, write_file, edit_file, glob, grep</td></tr>
-<tr><td>Shell</td><td>提供 Shell 能力，可选，与 StreamShell 互斥</td><td> execute</td></tr>
-<tr><td>StreamingShell</td><td>提供可以流式返回结果的 Shell 能力，可选，与 Shell 互斥</td><td>execute(streaming)</td></tr>
-</table>
-
-DeepAgents 内引用 filesystem middleware 来实现内置 filesystem，此 middleware 更详细的能力说明见：[Middleware: FileSystem](/zh/docs/eino/core_modules/eino_adk/eino_adk_chatmodelagentmiddleware/middleware_filesystem)
-
-### 任务拆解与规划
-
-WriteTodos 的 Description 描述了任务拆解、规划的原则，主 Agent 通过调用 WriteTodos 工具，在上下文中添加子任务列表来启发后续推理、执行过程：
-
-<a href="/img/eino/eino_adk_write_todos.png" target="_blank"><img src="/img/eino/eino_adk_write_todos.png" width="100%" /></a>
-
-1. 模型接收用户输入。
-2. 模型调用 WriteTodos 工具，参数为依照 WriteTodos Description 产生的任务列表。这次工具调用被添加到上下文中，供后续参考。
-3. 模型依照上下文中的 todos，调用 TaskTool 完成第一个 todo。
-4. 再次调用 WriteTodos ，更新 Todos 执行进度。
-
-> 💡
-> 对简单任务来说，每次都调用 WriteTodos 可能会起到反效果。WriteTodos Description 中添加了一些比较通用的正反例子来避免不调用或过度调用 WriteTodos。使用 DeepAgents 时，可以根据实际业务场景添加更多 prompt 来让 WriteTodos 在合适的时候被调用。
-
-> 💡
-> WriteTodos 会被默认添加到 Agent 中，配置 `WithoutWriteTodos=true` 可以关闭 WriteTodos。
-
-### 任务委派与 SubAgents 调用
-
-**TaskTool**
-
-所有子 Agent 会被绑定到 TaskTool 上，当主 Agent 分配子任务给子 Agent 处理时，它会调用 TaskTool，并指明需要哪个子代理及执行的任务。TaskTool 随后将任务路由到指定的子代理，并在其执行完毕后，将结果返回给主 Agent。TaskTool 的默认 Description 会说明调用子 Agent 的通用规则并拼接每个子 Agent 的 Description，开发者可以通过配置 `TaskToolDescriptionGenerator` 来自定义 TaskTool 的 Description。
-
-> 当用户配置了 Config.SubAgents 时，这些 Agent 会基于 ChatModelAgent AgentAsTool 的能力绑定到 TaskTool 上
-
-**上下文隔离**
-
-Agent 之间的上下文隔离：
-
-- 信息传递: 主 Agent 与子 Agent 之间不共享上下文。子 Agent 仅接收主 Agent 分配的子任务目标，不会接收整个任务的处理过程；主 Agent 仅接收子 Agent 的处理结果，不会接受子 Agent 的处理过程。
-- 避免污染: 这种隔离确保了子 Agent 的执行过程（如大量的工具调用和中间步骤）不会“污染”主代理的上下文，主代理只接收简洁、明确的最终答案。
-
-**general-purpose**
-
-DeepAgents 会默认增加一个子 Agent：general-purpose。general-purpose 具有和主 Agent 相同的 system prompt 和工具（除了 TaskTool），当任务没有专门的子 Agent 来解决时，主 Agent 可以调用 general-purpose 来隔离上下文。开发者可以通过配置 `WithoutGeneralSubAgent=true` 去掉此 Agent。
-
-### 与其他 Agent 对比
-
-- 对比 ReAct Agent
-
-  - 优势：DeepAgents 通过内置 WriteTodos 强化任务拆解与规划；同时隔离多 Agents 上下文，在大规模、多步骤任务中通常效果更优。
-  - 劣势：制定计划与调用子 Agent 会带来额外的模型请求，增加耗时与 token 成本；若任务拆分不合理，可能对效果产生反作用。
-- 对比 Plan-and-Execute
-
-  - 优势：DeepAgents 将 Plan/RePlan 作为工具供主 Agent 自由调用，可以在任务中跳过不必要的规划，整体上减少模型调用次数、降低耗时与成本。
-  - 劣势：任务规划与委派由一次模型调用完成，对模型能力要求更高，提示词调优也相对更困难。
-
-## DeepAgents 使用示例
-
-### 场景说明
-
-Excel Agent 是一个“看得懂 Excel 的智能助手”，它先把问题拆解成步骤，再一步步执行并校验结果。它能理解用户问题与上传的文件内容，提出可行的解决方案，并选择合适的工具（系统命令、生成并运行 Python 代码、网络查询等等）完成任务。
-
-在真实业务里，你可以把 Excel Agent 当成一位“Excel 专家 + 自动化工程师”。当你交付一个原始表格和目标描述，它会给出方案并完成执行：
-
-- **数据清理与格式化**：从一个包含大量数据的 Excel 文件中完成去重、空值处理、日期格式标准化操作。
-- **数据分析与报告生成**：从销售数据中提取每月的销售总额，聚合统计、透视，最终生成并导出图表报告。
-- **自动化预算计算**：根据不同部门的预算申请，自动计算总预算并生成部门预算分配表。
-- **数据匹配与合并**：将多个不同来源的客户信息表进行匹配合并，生成完整的客户信息数据库。
-
-用 DeepAgents 搭建的 Excel Agent 结构如下：
-
-<a href="/img/eino/eino_adk_excel_using_deep.png" target="_blank"><img src="/img/eino/eino_adk_excel_using_deep.png" width="100%" /></a>
-
-1. 在主 Agent 添加 ReadFile 工具，允许主 Agent 查看文件内容，辅助子任务制定
-2. 添加 Code 和 WebSearch 两个子 Agent：Code 可以编写 python 代码来操作 excel 表格；WebSearch 可以搜索信息并总结。
-
-### 代码实现
-
-[https://github.com/cloudwego/eino-examples/tree/main/adk/multiagent/deep](https://github.com/cloudwego/eino-examples/tree/main/adk/multiagent/deep)
-
-### 运行结果
-
-```yaml
-name: ExcelAgent
-path: [{ExcelAgent}]
-tool name: task
-arguments: {"subagent_type":"CodeAgent","description":"请帮我处理一个CSV文件操作任务。具体要求如下：1. 读取当前目录下的questions.csv文件；2. 提取该CSV文件中的第一列数据；3. 将提取出的第一列数据保存到一个新的CSV文件中，新文件命名为first_column.csv。请使用pandas库来完成这些操作，确保代码能够正确执行并处理可能出现的文件路径问题。"}
-
-name: ExcelAgent
-path: [{ExcelAgent}]
-tool name: python_runner
-arguments: {"code":"```python\nimport pandas as pd\nimport os\n\n# 获取当前工作目录并构建文件路径\nbase_dir = os.getcwd()\ninput_path = os.path.join(base_dir, 'questions.csv')\noutput_path = os.path.join(base_dir, 'first_column.csv')\n\ntry:\n    # 读取CSV文件\n    df = pd.read_csv(input_path)\n    # 提取第一列数据\n    first_column = df.iloc[:, 0]\n    # 保存为新CSV文件（不包含索引）\n    first_column.to_csv(output_path, index=False)\n    print(f\"成功将第一列数据保存至: {output_path}\")\nexcept FileNotFoundError:\n    print(f\"错误: 未找到文件 {input_path}\")\nexcept Exception as e:\n    print(f\"处理过程中发生错误: {str(e)}\")\n```"}
-
-name: ExcelAgent
-path: [{ExcelAgent}]
-tool response: 成功将第一列数据保存至: /Users/bytedance/go/src/github.com/cloudwego/eino-examples/adk/multiagent/deep/playground/262be931-532c-4d83-8cff-96c44b131973/first_column.csv
-
-
-name: ExcelAgent
-path: [{ExcelAgent}]
-answer: 任务已完成。已成功读取当前目录下的 `questions.csv` 文件，提取第一列数据，并将结果保存至 `first_column.csv`。具体输出路径如下：
-
-`/Users/bytedance/go/src/github.com/cloudwego/eino-examples/adk/multiagent/deep/playground/262be931-532c-4d83-8cff-96c44b131973/first_column.csv`
-
-代码已处理路径拼接和异常捕获（如文件不存在或格式错误），确保执行稳定性。
-
-name: ExcelAgent
-path: [{ExcelAgent}]
-tool response: 任务已完成。已成功读取当前目录下的 `questions.csv` 文件，提取第一列数据，并将结果保存至 `first_column.csv`。具体输出路径如下：
-
-`/Users/bytedance/go/src/github.com/cloudwego/eino-examples/adk/multiagent/deep/playground/262be931-532c-4d83-8cff-96c44b131973/first_column.csv`
-
-代码已处理路径拼接和异常捕获（如文件不存在或格式错误），确保执行稳定性。
-
-name: ExcelAgent
-path: [{ExcelAgent}]
-answer: 已成功将 `questions.csv` 表格中的第一列数据提取至新文件 `first_column.csv`，文件保存路径为
-：
-
-`/Users/bytedance/go/src/github.com/cloudwego/eino-examples/adk/multiagent/deep/playground/262be931-532c-4d83-8cff-96c4
-4b131973/first_column.csv`
-
-操作过程中已处理路径拼接和异常捕获（如文件不存在、格式错误等问题），确保数据
-提取完整性和文件生成稳定性。若需要调整文件路径或对数据格式有进一步要求，请随时告知
-。
-```

docs/Eino/docs/core_modules/eino_adk/agent_implementation/plan_execute.md

@@ -1,510 +0,0 @@
----
-Description: ""
-date: "2026-03-02"
-lastmod: ""
-tags: []
-title: Plan-Execute Agent
-weight: 4
----
-
-## Plan-Execute Agent 概述
-
-### Import Path
-
-`import ``github.com/cloudwego/eino/adk/prebuilt/planexecute`
-
-### 什么是 Plan-Execute Agent？
-
-Plan-Execute Agent 是 Eino ADK 中一种基于「规划-执行-反思」范式的多智能体协作框架，旨在解决复杂任务的分步拆解、执行与动态调整问题。它通过 **Planner（规划器）**、**Executor（执行器）**和 **Replanner（重规划器）** 三个核心智能体的协同工作，实现任务的结构化规划、工具调用执行、进度评估与动态 replanning，最终达成用户目标。
-
-<a href="/img/eino/eino_adk_plan_execute_steps.png" target="_blank"><img src="/img/eino/eino_adk_plan_execute_steps.png" width="100%" /></a>
-
-Plan-Execute Agent 适用于需要多步骤推理、工具集成或动态调整策略的场景（如研究分析、复杂问题解决、自动化工作流等），其核心优势在于：
-
-- **结构化规划**：将复杂任务拆解为清晰、可执行的步骤序列
-- **迭代执行**：基于工具调用完成单步任务，积累执行结果
-- **动态调整**：根据执行进度实时评估是否需要调整计划或终止任务
-- **模型与工具无关**：兼容任意支持工具调用的模型，可灵活集成外部工具
-
-### Plan-Execute Agent 结构
-
-Plan-Execute Agent 由三个核心智能体与一个协调器构成，基于 ADK 中提供的 ChatModelAgent 和 WorkflowAgents 能力共同完成构建：
-
-<a href="/img/eino/eino_adk_plan_execute_replan_architecture_overview.png" target="_blank"><img src="/img/eino/eino_adk_plan_execute_replan_architecture_overview.png" width="100%" /></a>
-
-#### 1. Planner
-
-- **核心功能**：根据用户目标生成初始任务计划（结构化步骤序列）
-- **实现方式**：
-  - 使用支持工具调用的模型（如 GPT-4），通过 `PlanTool` 生成符合 JSON Schema 的步骤列表
-  - 或直接使用支持结构化输出的模型，直接生成 `Plan` 格式结果
-- **输出**：`Plan` 对象（包含有序步骤列表），存储于 Session 中供后续流程使用
-
-```go
-// PlannerConfig provides configuration options for creating a planner agent.
-// There are two ways to configure the planner to generate structured Plan output:
-//  1. Use ChatModelWithFormattedOutput: A model already configured to output in the Plan format
-//  2. Use ToolCallingChatModel + ToolInfo: A model that will be configured to use tool calling
-//     to generate the Plan structure
-type PlannerConfig struct {
-    // ChatModelWithFormattedOutput is a model pre-configured to output in the Plan format.
-    // This can be created by configuring a model to output structured data directly.
-    // Can refer to https://github.com/cloudwego/eino-ext/blob/main/components/model/openai/examples/structured/structured.go.
-    ChatModelWithFormattedOutput model.BaseChatModel
-
-    // ToolCallingChatModel is a model that supports tool calling capabilities.
-    // When provided along with ToolInfo, the model will be configured to use tool calling
-    // to generate the Plan structure.
-    ToolCallingChatModel model.ToolCallingChatModel
-    // ToolInfo defines the schema for the Plan structure when using tool calling.
-    // If not provided, PlanToolInfo will be used as the default.
-    ToolInfo *schema.ToolInfo
-
-    // GenInputFn is a function that generates the input messages for the planner.
-    // If not provided, defaultGenPlannerInputFn will be used as the default.
-    GenInputFn GenPlannerInputFn
-
-    // NewPlan creates a new Plan instance for JSON.
-    // The returned Plan will be used to unmarshal the model-generated JSON output.
-    // If not provided, defaultNewPlan will be used as the default.
-    NewPlan NewPlan
-}
-```
-
-#### 2. Executor
-
-- **核心功能**：执行计划中的首个步骤，调用外部工具完成具体任务
-- **实现方式**：基于 `ChatModelAgent` 实现，配置工具集（如搜索、计算、数据库访问等）
-- **工作流**：
-  - 从 Session 中获取当前 `Plan` 和已执行步骤
-  - 提取计划中的第一个未执行步骤作为目标
-  - 调用工具执行该步骤，将结果存储于 Session
-- **关键能力**：支持多轮工具调用（通过 `MaxIterations` 控制），确保单步任务完成
-
-```go
-// ExecutorConfig provides configuration options for creating a executor agent.
-type ExecutorConfig struct {
-    // Model is the chat model used by the executor.
-    Model model.ToolCallingChatModel
-
-    // ToolsConfig is the tools configuration used by the executor.
-    ToolsConfig adk.ToolsConfig
-
-    // MaxIterations defines the upper limit of ChatModel generation cycles.
-    // The agent will terminate with an error if this limit is exceeded.
-    // Optional. Defaults to 20.
-    MaxIterations int
-
-    // GenInputFn is the function that generates the input messages for the Executor.
-    // Optional. If not provided, defaultGenExecutorInputFn will be used.
-    GenInputFn GenPlanExecuteInputFn
-}
-```
-
-#### 3. Replanner
-
-- **核心功能**：评估执行进度，决定继续执行（生成新计划）或终止任务（返回结果）
-- **实现方式**：基于工具调用模型，通过 `PlanTool`（生成新计划）或 `RespondTool`（返回结果）输出决策
-- **决策逻辑**：
-  - **继续执行**：若目标未达成，生成包含剩余步骤的新计划，更新 Session 中的 `Plan`
-  - **终止任务**：若目标已达成，调用 `RespondTool` 生成最终用户响应
-
-```go
-type ReplannerConfig struct {
-
-    // ChatModel is the model that supports tool calling capabilities.
-    // It will be configured with PlanTool and RespondTool to generate updated plans or responses.
-    ChatModel model.ToolCallingChatModel
-
-    // PlanTool defines the schema for the Plan tool that can be used with ToolCallingChatModel.
-    // If not provided, the default PlanToolInfo will be used.
-    PlanTool *schema.ToolInfo
-
-    // RespondTool defines the schema for the response tool that can be used with ToolCallingChatModel.
-    // If not provided, the default RespondToolInfo will be used.
-    RespondTool *schema.ToolInfo
-
-    // GenInputFn is the function that generates the input messages for the Replanner.
-    // if not provided, buildDefaultReplannerInputFn will be used.
-    GenInputFn GenPlanExecuteInputFn
-
-    // NewPlan creates a new Plan instance.
-    // The returned Plan will be used to unmarshal the model-generated JSON output from PlanTool.
-    // If not provided, defaultNewPlan will be used as the default.
-    NewPlan NewPlan
-}
-```
-
-#### 4. PlanExecuteAgent
-
-- **核心功能**：组合上述三个智能体，形成「规划 → 执行 → 重规划」的循环工作流
-- **实现方式**：通过 `SequentialAgent` 和 `LoopAgent` 组合：
-  - 外层 `SequentialAgent`：先执行 `Planner` 生成初始计划，再进入执行-重规划循环
-  - 内层 `LoopAgent`：循环执行 `Executor` 和 `Replanner`，直至任务完成或达到最大迭代次数
-
-```go
-// New creates a new plan execute agent with the given configuration.
-func New(ctx context.Context, cfg *PlanExecuteConfig) (adk.Agent, error)
-
-// Config provides configuration options for creating a plan execute agent.
-type Config struct {
-    Planner       adk.Agent
-    Executor      adk.Agent
-    Replanner     adk.Agent
-    MaxIterations int
-}
-```
-
-### Plan-Execute Agent 运行流程
-
-Plan-Execute Agent 的完整工作流程如下：
-
-1. **初始化**：用户输入目标任务，启动 `PlanExecuteAgent`
-2. **规划阶段**：
-   - `Planner` 接收用户目标，生成初始 `Plan`（步骤列表）
-   - `Plan` 存储于 Session（`PlanSessionKey`）
-3. **执行-重规划循环**（由 `LoopAgent` 控制）：
-   - **执行步骤**：`Executor` 从 `Plan` 中提取首个步骤，调用工具执行，结果存入 Session（`ExecutedStepsSessionKey`）
-   - **反思步骤**：`Replanner` 评估已执行步骤与结果：
-     - 若目标达成：调用 `RespondTool` 生成最终响应，退出循环
-     - 若需继续：生成新 `Plan` 并更新 Session，进入下一轮循环
-4. **终止条件**：任务完成（`Replanner` 返回结果）或达到最大迭代次数（`MaxIterations`）
-
-## Plan-Execute Agent 使用示例
-
-### 场景说明
-
-实现一个「调研」Agent：
-
-1. **Planner**：为调研目标规划详细步骤
-2. **Executor**：执行计划中的首个步骤，必要时使用搜索工具（duckduckgo）
-3. **Replanner**：评估执行结果，若信息不足则调整计划，否则生成最终总结
-
-### 代码实现
-
-#### 1. 初始化模型与工具
-
-```go
-// 初始化支持工具调用的 OpenAI 模型
-func newToolCallingModel(ctx context.Context) model.ToolCallingChatModel {
-    cm, err := openai.NewChatModel(ctx, &openai.ChatModelConfig{
-        APIKey: os.Getenv("OPENAI_API_KEY"),
-        Model:  "gpt-4o", // 需支持工具调用
-    })
-    if err != nil {
-        log.Fatalf("初始化模型失败: %v", err)
-    }
-    return cm
-}
-
-// 初始化搜索工具（用于 Executor 调用）
-func newSearchTool(ctx context.Context) tool.BaseTool {
-    config := &duckduckgo.Config{
-       MaxResults: 20, // Limit to return 20 results
-       Region:     duckduckgo._RegionWT_,
-       Timeout:    10 * time._Second_,
-    }
-    tool, err := duckduckgo.NewTextSearchTool(ctx, config)
-    if err != nil {
-       log.Fatalf("初始化搜索工具失败: %v", err)
-    }
-    return tool
-}
-```
-
-#### 2. 创建 Planner（规划器）
-
-```go
-func newPlanner(ctx context.Context, model model.ToolCallingChatModel) adk.Agent {
-    planner, err := planexecute.NewPlanner(ctx, &planexecute.PlannerConfig{
-        ToolCallingChatModel: model,                  // 使用工具调用模型生成计划
-        ToolInfo:             &planexecute.PlanToolInfo, // 默认 Plan 工具 schema
-    })
-    if err != nil {
-        log.Fatalf("创建 Planner 失败: %v", err)
-    }
-    return planner
-}
-```
-
-#### 3. 创建 Executor（执行器）
-
-```go
-func newExecutor(ctx context.Context, model model.ToolCallingChatModel) adk.Agent {
-    // 配置 Executor 工具集（仅包含搜索工具）
-    toolsConfig := adk.ToolsConfig{
-       ToolsNodeConfig: compose.ToolsNodeConfig{
-          Tools: []tool.BaseTool{newSearchTool(ctx)},
-       },
-    }
-    executor, err := planexecute.NewExecutor(ctx, &planexecute.ExecutorConfig{
-       Model:       model,
-       ToolsConfig: toolsConfig,
-       MaxIterations:     5, // ChatModel 最多运行 5 次
-    })
-    if err != nil {
-       log.Fatalf("创建 Executor 失败: %v", err)
-    }
-    return executor
-}
-```
-
-#### 4. 创建 Replanner（重规划器）
-
-```go
-func newReplanner(ctx context.Context, model model.ToolCallingChatModel) adk.Agent {
-    replanner, err := planexecute.NewReplanner(ctx, &planexecute.ReplannerConfig{
-       ChatModel: model, // 使用工具调用模型评估进度
-    })
-    if err != nil {
-       log.Fatalf("创建 Replanner 失败: %v", err)
-    }
-    return replanner
-}
-```
-
-#### 5. 组合为 PlanExecuteAgent
-
-```go
-func newPlanExecuteAgent(ctx context.Context) adk.Agent {
-    model := newToolCallingModel(ctx)
-
-    // 实例化三大核心智能体
-    planner := newPlanner(ctx, model)
-    executor := newExecutor(ctx, model)
-    replanner := newReplanner(ctx, model)
-
-    // 组合为 PlanExecuteAgent（固定 execute - replan 最大迭代 10 次）
-    planExecuteAgent, err := planexecute.NewPlanExecuteAgent(ctx, &planexecute.PlanExecuteConfig{
-       Planner:       planner,
-       Executor:      executor,
-       Replanner:     replanner,
-       MaxIterations: 10,
-    })
-    if err != nil {
-       log.Fatalf("组合 PlanExecuteAgent 失败: %v", err)
-    }
-    return planExecuteAgent
-}
-```
-
-#### 6. 运行与输出
-
-```go
-import (
-    "context"
-    "log"
-    "os"
-    "time"
-
-    "github.com/cloudwego/eino-ext/components/model/openai"
-    "github.com/cloudwego/eino-ext/components/tool/duckduckgo/v2"
-    "github.com/cloudwego/eino/adk"
-    "github.com/cloudwego/eino/adk/prebuilt/planexecute"
-    "github.com/cloudwego/eino/components/model"
-    "github.com/cloudwego/eino/components/tool"
-    "github.com/cloudwego/eino/compose"
-    "github.com/cloudwego/eino/schema"
-)
-
-func main() {
-    ctx := context.Background()
-    agent := newPlanExecuteAgent(ctx)
-
-    // 创建 Runner 执行智能体
-    runner := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent, EnableStreaming: true})
-
-    // 用户输入目标任务
-    userInput := []adk.Message{
-       schema.UserMessage("Research and summarize the latest developments in AI for healthcare in 2024, including key technologies, applications, and industry trends."),
-    }
-
-    // 执行并打印结果
-    events := runner.Run(ctx, userInput)
-    for {
-       event, ok := events.Next()
-       if !ok {
-          break
-       }
-       if event.Err != nil {
-          log.Printf("执行错误: %v", event.Err)
-          break
-       }
-       // 打印智能体输出（计划、执行结果、最终响应等）
-       if msg, err := event.Output.MessageOutput.GetMessage(); err == nil && msg.Content != "" {
-          log.Printf("\n=== Agent Output ===\n%s\n", msg.Content)
-       }
-    }
-}
-```
-
-### 运行结果
-
-```markdown
-2025/09/08 11:47:42 
-=== Agent:Planner Output ===
-{"steps":["Identify the most recent and credible sources for AI developments in healthcare in 2024, such as scientific journals, industry reports, news articles, and expert analyses.","Extract and compile the key technologies emerging or advancing in AI for healthcare in 2024, including machine learning models, diagnostic tools, robotic surgery, personalized medicine, and data management solutions.","Analyze the main applications of AI in healthcare during 2024, focusing on areas such as diagnostics, patient care, drug discovery, medical imaging, and healthcare administration.","Investigate current industry trends related to AI in healthcare for 2024, including adoption rates, regulatory changes, ethical considerations, funding landscape, and market forecasts.","Synthesize the gathered information into a comprehensive summary covering the latest developments in AI for healthcare in 2024, highlighting key technologies, applications, and industry trends with examples and implications."]}
-2025/09/08 11:47:47 
-=== Agent:Executor Output ===
-{"message":"Found 10 results successfully.","results":[{"title":"Artificial Intelligence in Healthcare: 2024 Year in Review","url":"https://www.researchgate.net/publication/389402322_Artificial_Intelligence_in_Healthcare_2024_Year_in_Review","summary":"The adoption of LLMs and text data types amongst various healthcare specialties, especially for education and administrative tasks, is unlocking new potential for AI applications in..."},{"title":"AI in Healthcare - Nature","url":"https://www.nature.com/collections/hacjaaeafj","summary":"\"AI in Healthcare\" encompasses the use of AI technologies to enhance various aspects of healthcare delivery, from diagnostics to treatment personalization, ultimately aiming to improve..."},{"title":"Evolution of artificial intelligence in healthcare: a 30-year ...","url":"https://www.frontiersin.org/journals/medicine/articles/10.3389/fmed.2024.1505692/full","summary":"Conclusion: This study reveals a sustained explosive growth trend in AI technologies within the healthcare sector in recent years, with increasingly profound applications in medicine. Additionally, medical artificial intelligence research is dynamically evolving with the advent of new technologies."},{"title":"The Impact of Artificial Intelligence on Healthcare: A Comprehensive ...","url":"https://onlinelibrary.wiley.com/doi/full/10.1002/hsr2.70312","summary":"This review analyzes the impact of AI on healthcare using data from the Web of Science (2014-2024), focusing on keywords like AI, ML, and healthcare applications."},{"title":"Artificial intelligence in healthcare (Review) - PubMed","url":"https://pubmed.ncbi.nlm.nih.gov/39583770/","summary":"Furthermore, the barriers and constraints that may impede the use of AI in healthcare are outlined, and the potential future directions of AI-augmented healthcare systems are discussed."},{"title":"Full article: Towards new frontiers of healthcare systems research ...","url":"https://www.tandfonline.com/doi/full/10.1080/20476965.2024.2402128","summary":"In this editorial, we begin by taking a quick look at the recent past of AI and its use in health. We then present the current landscape of AI research in health. We further discuss promising avenues for novel innovations in health systems research."},{"title":"AI in healthcare: New research shows promise and limitations of ...","url":"https://www.sciencedaily.com/releases/2024/10/241028164534.htm","summary":"Researchers have studied how well doctors used GPT-4 -- an artificial intelligence (AI) large language model system -- for diagnosing patients."},{"title":"Artificial Intelligence in Healthcare: 2024 Year in Review","url":"https://www.medrxiv.org/content/10.1101/2025.02.26.25322978v2","summary":"The adoption of LLMs and text data types amongst various healthcare specialties, especially for education and administrative tasks, is unlocking new potential for AI applications in healthcare."},{"title":"Investigating the Key Trends in Applying Artificial Intelligence to ...","url":"https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0322197","summary":"The findings of this review are useful for healthcare professionals to acquire deeper knowledge on the use of medical AI from design to implementation stage. However, a thorough assessment is essential to gather more insights into whether AI benefits outweigh its risks."},{"title":"Revolutionizing healthcare and medicine: The impact of modern ...","url":"https://pubmed.ncbi.nlm.nih.gov/39479277/","summary":"Wearable technology, the Internet of Medical Things, and sensor technologies have empowered individuals to take an active role in tracking and managing their health. These devices facilitate real-time data collection, enabling preventive and personalized care."}]}
-2025/09/08 11:47:52 
-=== Agent:Executor Output ===
-{"message":"Found 10 results successfully.","results":[{"title":"Generative AI in healthcare: Current trends and future outlook","url":"https://www.mckinsey.com/industries/healthcare/our-insights/generative-ai-in-healthcare-current-trends-and-future-outlook","summary":"The latest survey, conducted in the fourth quarter of 2024, found that 85 percent of respondents—healthcare leaders from payers, health systems, and healthcare services and technology (HST) groups—were exploring or had already adopted gen AI capabilities."},{"title":"AI in healthcare - statistics & facts | Statista","url":"https://www.statista.com/topics/10011/ai-in-healthcare/","summary":"Distribution of confidence in using a new technology and AI in healthcare among health professionals in Denmark, France, Germany, and the United Kingdom as of 2024"},{"title":"Medscape and HIMSS Release 2024 Report on AI Adoption in Healthcare","url":"https://www.prnewswire.com/news-releases/medscape-and-himss-release-2024-report-on-ai-adoption-in-healthcare-302324936.html","summary":"The full \"AI Adoption in Healthcare Report 2024\" is now available on both Medscape and HIMSS websites offering detailed analysis and insights into the current state of AI adoption in..."},{"title":"AI in Healthcare Market Size, Share | Growth Report [2025-2032]","url":"https://www.fortunebusinessinsights.com/industry-reports/artificial-intelligence-in-healthcare-market-100534","summary":"The global AI in healthcare market research report delivers an in-depth market analysis, highlighting essential elements such as an overview of advanced technologies, the regulatory landscape in key countries, and the challenges encountered in adopting and implementing AI-based solutions."},{"title":"Artificial Intelligence in Healthcare Market Size to Hit USD 613.81 Bn ...","url":"https://www.precedenceresearch.com/artificial-intelligence-in-healthcare-market","summary":"The global artificial intelligence (AI) in healthcare market size reached USD 26.69 billion in 2024 and is projected to hit around USD 613.81 billion by 2034, at a CAGR of 36.83%."},{"title":"AI In Healthcare Market Size, Share | Industry Report, 2033","url":"https://www.globalmarketstatistics.com/market-reports/artificial-intelligence-in-healthcare-market-12394","summary":"Market Size and Growth: The Artificial Intelligence in Healthcare Market Market size was USD 5011.24 Million in 2024, is projected to grow to USD 5762.41 Million by 2025 and exceed USD 8966.05 Million by 2033, with a CAGR of 21.4% from 2025-2033."},{"title":"AI in healthcare statistics: 62 findings from 18 research reports - Keragon","url":"https://www.keragon.com/blog/ai-in-healthcare-statistics","summary":"Bringing together the data — 12 data-driven insights from 6 different research reports — we revealed a range of concerns surrounding AI in healthcare. The key obstacles the data unpacked are misdiagnoses, transparency, data accuracy, and human oversight."},{"title":"AI in Healthcare Statistics By Market Share And Technology","url":"https://www.sci-tech-today.com/stats/ai-in-healthcare-statistics/","summary":"According to AI in Healthcare Statistics, the US will lead the global AI healthcare market in 2024, which is projected to reach USD 24.7 billion. In the same year, US healthcare AI..."},{"title":"Artificial Intelligence in Healthcare: 2024 Year in Review","url":"https://www.researchgate.net/publication/389402322_Artificial_Intelligence_in_Healthcare_2024_Year_in_Review","summary":"The adoption of LLMs and text data types amongst various healthcare specialties, especially for education and administrative tasks, is unlocking new potential for AI applications in..."},{"title":"19+ AI in Healthcare Statistics for 2024: Insights & Projections","url":"https://www.allaboutai.com/resources/ai-statistics/healthcare/","summary":"Discover 19+ AI in healthcare statistics for 2024, covering public perception, market trends, and revenue projections with expert insights."}]}
-2025/09/08 11:47:58 
-=== Agent:Executor Output ===
-{"message":"Found 10 results successfully.","results":[{"title":"Artificial Intelligence in Healthcare: 2024 Year in Review","url":"https://www.researchgate.net/publication/389402322_Artificial_Intelligence_in_Healthcare_2024_Year_in_Review","summary":"The adoption of LLMs and text data types amongst various healthcare specialties, especially for education and administrative tasks, is unlocking new potential for AI applications in..."},{"title":"Trustworthy AI in Healthcare Insights from IQVIA 2024 Report","url":"https://aipressroom.com/trustworthy-ai-healthcare-insights-iqvia-2024/","summary":"Discover how AI is advancing healthcare with trusted frameworks, real-world impact, and strategies for ethical, scalable adoption."},{"title":"The Impact of Artificial Intelligence on Healthcare: A Comprehensive ...","url":"https://onlinelibrary.wiley.com/doi/full/10.1002/hsr2.70312","summary":"This review analyzes the impact of AI on healthcare using data from the Web of Science (2014-2024), focusing on keywords like AI, ML, and healthcare applications."},{"title":"Generative AI in Healthcare: 2024's Breakthroughs and What's Next for ...","url":"https://www.signifyresearch.net/insights/generative-ai-news-round-up-december-2024/","summary":"As 2024 draws to a close, generative AI in healthcare has achieved remarkable milestones. This year has been defined by both groundbreaking innovation and insightful exploration, with AI transforming workflows in medical imaging and elevating patient care across digital health solutions."},{"title":"Generative AI in healthcare: Current trends and future outlook","url":"https://www.mckinsey.com/industries/healthcare/our-insights/generative-ai-in-healthcare-current-trends-and-future-outlook","summary":"The latest survey, conducted in the fourth quarter of 2024, found that 85 percent of respondents—healthcare leaders from payers, health systems, and healthcare services and technology (HST) groups—were exploring or had already adopted gen AI capabilities."},{"title":"Artificial Intelligence in Healthcare: 2024 Year in Review","url":"https://www.medrxiv.org/content/10.1101/2025.02.26.25322978v2","summary":"The adoption of LLMs and text data types amongst various healthcare specialties, especially for education and administrative tasks, is unlocking new potential for AI applications in healthcare."},{"title":"How AI is improving diagnostics and health outcomes","url":"https://www.weforum.org/stories/2024/09/ai-diagnostics-health-outcomes/","summary":"By leveraging the power of AI for diagnostics, we can improve health outcomes and contribute to a future where healthcare is more accessible and effective for everyone, particularly in the communities that need it the most."},{"title":"Artificial Intelligence in Healthcare: 2024 Developments and Lega","url":"https://natlawreview.com/article/healthy-ai-2024-year-review","summary":"This publication provides an overview of important developments at the intersection of AI, healthcare and the law in 2024."},{"title":"What's next in AI and healthcare? | McKinsey & Company","url":"https://www.mckinsey.com/featured-insights/themes/whats-next-in-ai-and-healthcare","summary":"In healthcare—with patient well-being and lives at stake—the advancement of AI seems particularly momentous. In an industry battling staffing shortages and increasing costs, health system leaders need to consider all possible solutions, including AI technologies."},{"title":"AI in Healthcare: An Expert Analysis on Driving Transformational ...","url":"https://www.historytools.org/ai/healthcare-ai","summary":"Artificial intelligence (AI) has emerged as a disruptive force across industries, but few sectors are seeing more dramatic change than healthcare. Fueled by vast data growth, urgent cost pressures and new technological capabilities, AI adoption in health is accelerating rapidly."}]}
-2025/09/08 11:48:01 
-=== Agent:Executor Output ===
-{"message":"Found 10 results successfully.","results":[{"title":"Deep Dive: AI 2024 | pharmaphorum","url":"https://pharmaphorum.com/digital/deep-dive-ai-2024","summary":"In this issue, we delve into the transformative impact of AI on healthcare and pharma, featuring insights on key AI trends from the floor of Frontiers Health, the ongoing battle against..."},{"title":"Artificial Intelligence - Healthcare IT News","url":"https://www.healthcareitnews.com/topics/artificial-intelligence","summary":"Dr. Ethan Goh, executive director of Stanford ARISE, the AI Research and Science Evaluation Network, describes a new study to explore models' diagnostic and management reasoning capabilities - and what that could mean for clinicians and patients."},{"title":"7 ways AI is transforming healthcare | World Economic Forum","url":"https://www.weforum.org/stories/2025/08/ai-transforming-global-health/","summary":"While healthcare lags in AI adoption, these game-changing innovations - from spotting broken bones to assessing ambulance needs - show what's possible."},{"title":"Artificial Intelligence (AI) in Health Care | NEJM Catalyst","url":"https://catalyst.nejm.org/browse/catalyst-topic/ai-in-healthcare","summary":"As AI technology rapidly evolves, health care professionals grapple with the ethical implications of data ownership, privacy concerns, and the actionable insights derived from AI."},{"title":"From Robots to Healthcare: The Real Story Behind 2024's AI Investments","url":"https://www.algorithm-research.com/post/from-robots-to-healthcare-the-real-story-behind-2024-s-ai-investments","summary":"AI continues to reshape industries across the globe, with capital flowing into areas that promise the highest long-term impact. According to the 2025 AI Index Report by Stanford University, global AI investments in 2024 reached new highs, but they were far from evenly distributed."},{"title":"2024 Medical Breakthroughs Revolutionizing Healthcare","url":"https://medicalnewscorner.com/2024-medical-breakthroughs-revolutionizing-healthcare/","summary":"The medical field is set for transformative advancements in 2024, with breakthroughs in gene editing, cancer treatment, artificial intelligence, telemedicine, mental health, and wearable technology, promising to enhance patient care and outcomes globally."},{"title":"Artificial Intelligence - JAMA Network","url":"https://jamanetwork.com/collections/44024/artificial-intelligence","summary":"Explore the latest in AI in medicine, including studies of how chatbots, large language models (LLMs), natural language processing, and machine learning are transforming medicine and health care."},{"title":"Ai医疗技术：2024年及以后的发展趋势-家医大健康","url":"https://www.familydoctor.cn/news/ai-yiliao-jishu-yihou-fazhanqushi-192483.html","summary":"本文深入探讨了新一代健康AI技术在2024年的发展前景，包括先进诊断工具和个性化治疗计划等创新应用。 文章指出，通过机器学习和深度学习技术的突破，AI将在疾病早期检测、患者数据实时分析和医疗资源优化分配方面发挥关键作用。"},{"title":"AI in Healthcare | Artificial intelligence in healthcare news","url":"https://aiin.healthcare/","summary":"AI in Healthcare is the leading source of information on the latest developments in the use of artificial intelligence in healthcare. We provide coverage of AI-powered medical devices, software, and algorithms, as well as the ethical and regulatory challenges surrounding the use of AI in healthcare."},{"title":"19+ AI in Healthcare Statistics for 2024: Insights & Projections","url":"https://www.allaboutai.com/resources/ai-statistics/healthcare/","summary":"Discover 19+ AI in healthcare statistics for 2024, covering public perception, market trends, and revenue projections with expert insights."}]}
-2025/09/08 11:48:08 
-=== Agent:Executor Output ===
-Here are some of the most recent and credible sources identified for AI developments in healthcare in 2024:
-
-Scientific Journals:
-- "Artificial Intelligence in Healthcare: 2024 Year in Review" (ResearchGate)
-- "AI in Healthcare - Nature" (nature.com collection)
-- "Evolution of artificial intelligence in healthcare: a 30-year study" (frontiersin.org)
-- "The Impact of Artificial Intelligence on Healthcare: A Comprehensive Review" (Wiley online library)
-- "Artificial intelligence in healthcare (Review)" (PubMed)
-- "Artificial Intelligence - JAMA Network" (jamanetwork.com collection)
-
-Industry Reports:
-- "Generative AI in healthcare: Current trends and future outlook" (McKinsey report, Q4 2024)
-- "Medscape and HIMSS Release 2024 Report on AI Adoption in Healthcare"
-- "AI in Healthcare Market Size, Share | Growth Report [2025-2032]" (Fortune Business Insights)
-- "Artificial Intelligence in Healthcare Market Size to Hit USD 613.81 Bn" (Precedence Research)
-
-News Articles:
-- "AI in healthcare: New research shows promise and limitations of GPT-4" (ScienceDaily, Oct 2024)
-- "Deep Dive: AI 2024" (pharmaphorum.com)
-- "Artificial Intelligence - Healthcare IT News"
-- "7 ways AI is transforming healthcare" (World Economic Forum, 2024)
-- "2024 Medical Breakthroughs Revolutionizing Healthcare" (medicalnewscorner.com)
-
-Expert Analyses:
-- "Trustworthy AI in Healthcare Insights from IQVIA 2024 Report"
-- "Generative AI in Healthcare: 2024's Breakthroughs and What's Next" (SignifyResearch)
-- "AI in Healthcare: An Expert Analysis on Driving Transformational Change"
-
-These sources cover a broad spectrum including peer-reviewed journals, authoritative market research reports, reputable news publications, and expert thought leadership on the latest AI innovations, applications, and trends in healthcare for 2024. Shall I proceed to extract and compile key technologies emerging or advancing in AI for healthcare in 2024 from these sources?
-2025/09/08 11:48:15 
-=== Agent:Replanner Output ===
-{"steps":["Extract and compile the key technologies emerging or advancing in AI for healthcare in 2024, focusing on machine learning models, diagnostic tools, robotic surgery, personalized medicine, and data management solutions.","Analyze the main applications of AI in healthcare during 2024, concentrating on diagnostics, patient care, drug discovery, medical imaging, and healthcare administration.","Investigate current industry trends related to AI in healthcare for 2024, including adoption rates, regulatory changes, ethical considerations, funding landscape, and market forecasts.","Synthesize the gathered information into a comprehensive summary covering the latest developments in AI for healthcare in 2024, highlighting key technologies, applications, and industry trends with examples and implications."]}
-2025/09/08 11:48:20 
-=== Agent:Executor Output ===
-{"message":"Found 10 results successfully.","results":[{"title":"Five Machine Learning Innovations Shaping Healthcare in 2024","url":"https://healthmanagement.org/c/artificial-intelligence/News/five-machine-learning-innovations-shaping-healthcare-in-2024","summary":"Discover 5 AI & ML trends transforming UK healthcare, from explainable AI to edge AI, enhancing patient care and operational efficiency."},{"title":"How AI is improving diagnostics and health outcomes","url":"https://www.weforum.org/stories/2024/09/ai-diagnostics-health-outcomes/","summary":"Effective and ethical AI solutions in diagnostics require collaboration. Artificial intelligence (AI) is transforming healthcare by improving diagnostic accuracy, enabling earlier disease detection and enhancing patient outcomes."},{"title":"The Impact of Artificial Intelligence on Healthcare: A Comprehensive ...","url":"https://onlinelibrary.wiley.com/doi/full/10.1002/hsr2.70312","summary":"The study aims to describe AI in healthcare, including important technologies like robotics, machine learning (ML), deep learning (DL), and natural language processing (NLP), and to investigate how these technologies are used in patient interaction, predictive analytics, and remote monitoring."},{"title":"Unveiling the potential of artificial intelligence in revolutionizing ...","url":"https://eurjmedres.biomedcentral.com/articles/10.1186/s40001-025-02680-7","summary":"The rapid advancement of Machine Learning (ML) and Deep Learning (DL) technologies has revolutionized healthcare, particularly in the domains of disease prediction and diagnosis."},{"title":"Trends in AI for Disease and Diagnostic Prediction: A Healthcare ...","url":"https://link.springer.com/chapter/10.1007/978-3-031-84404-1_5","summary":"This chapter explores the transformative impact of artificial intelligence (AI) on the healthcare system, particularly in enhancing the accuracy, efficiency, and speed of disease diagnostics. A key advantage of AI integration in healthcare lies in its capacity to..."},{"title":"Unleashing the potential of AI in modern healthcare: Machine learning ...","url":"https://www.researchgate.net/publication/385135063_Unleashing_the_potential_of_AI_in_modern_healthcare_Machine_learning_algorithms_and_intelligent_medical_robots","summary":"Overall, AI, through machine learning algorithms and intelligent medical robots, is revolutionizing healthcare by offering promising improvements in diagnostics, surgical precision,..."},{"title":"The impact of artificial intelligence on remote healthcare: Enhancing ...","url":"https://www.sciencedirect.com/science/article/pii/S2949866X24001230","summary":"Key applications of AI, such as AI-enabled diagnostic systems, predictive analytics, and teleconsultation platforms, are reviewed for their strengths in overcoming the limitations of the traditional models of remote healthcare."},{"title":"15 AI Tools Transforming Healthcare in 2025 | The Future of Medicine","url":"https://healthcarereaders.com/insights/top-ai-tools-in-healthcare","summary":"From predictive analytics to generative AI (GenAI), these technologies are improving patient outcomes while reducing costs. AI is not new to healthcare—predictive analytics and machine learning have been used for years in diagnostics, treatment planning, and patient monitoring."},{"title":"How AI Is Transforming Healthcare: Diagnosis, Treatment, and Beyond","url":"https://www.sciencenewstoday.org/how-ai-is-transforming-healthcare-diagnosis-treatment-and-beyond","summary":"In this sweeping journey into the AI-healthcare nexus, we will explore how artificial intelligence is reshaping diagnosis, revolutionizing treatment, enhancing patient care, and opening doors to possibilities once thought impossible."},{"title":"Top 10 AI in Healthcare Applications 2025 | Diagnosis to Patient Care","url":"https://www.guvi.in/blog/ai-in-healthcare-applications/","summary":"What is Artificial intelligence in Healthcare? AI in healthcare refers to the use of advanced algorithms and machine learning models that analyze complex medical data and support clinical decisions. It helps doctors identify patterns in imaging results, predict disease risks through patient records, and recommend treatment options tailored to individual needs. Top 10 Applications of AI in ..."}]}
-2025/09/08 11:48:28 
-=== Agent:Executor Output ===
-Key technologies emerging or advancing in AI for healthcare in 2024, based on recent findings, include:
-
-1. Machine Learning Models:
-- Advanced machine learning (ML) and deep learning (DL) technologies are revolutionizing disease prediction, diagnostics accuracy, and patient outcome improvements.
-- Innovations include explainable AI models that enhance transparency and trust in clinical decision-making.
-- Edge AI is gaining traction, enabling real-time data processing at healthcare facilities for faster diagnostics and response.
-
-2. Diagnostic Tools:
-- AI-enabled diagnostic systems are enhancing speed, accuracy, and early detection of diseases.
-- Integration of AI in medical imaging allows for better identification of abnormalities and tailored treatment plans.
-- Use of natural language processing (NLP) to analyze patient records and literature supports predictive analytics and diagnostics.
-
-3. Robotic Surgery:
-- Intelligent medical robots equipped with AI algorithms are improving surgical precision and reducing invasiveness.
-- AI facilitates real-time guidance and adaptive control during surgeries, increasing safety and effectiveness.
-
-4. Personalized Medicine:
-- AI models analyze individual patient data to recommend customized treatment plans.
-- Predictive analytics support identification of patient-specific risk factors and therapeutic responses.
-- AI-driven genomics and biomarker analysis accelerate personalized drug development.
-
-5. Data Management Solutions:
-- AI-powered data management platforms enable integration and analysis of large-scale heterogeneous healthcare data.
-- Predictive analytics and remote monitoring systems optimize patient care and hospital operations.
-- Secure and compliant AI solutions address privacy and ethical concerns in managing healthcare information.
-
-These technologies collectively contribute to enhancing diagnostics, treatment precision, patient care, and operational efficiency in healthcare settings in 2024. Would you like me to proceed with analyzing the main applications of AI in healthcare during 2024 next?
-2025/09/08 11:48:33 
-=== Agent:Replanner Output ===
-{"steps":["Analyze the main applications of AI in healthcare during 2024, concentrating on diagnostics, patient care, drug discovery, medical imaging, and healthcare administration.","Investigate current industry trends related to AI in healthcare for 2024, including adoption rates, regulatory changes, ethical considerations, funding landscape, and market forecasts.","Synthesize the gathered information into a comprehensive summary covering the latest developments in AI for healthcare in 2024, highlighting key technologies, applications, and industry trends with examples and implications."]}
-2025/09/08 11:48:39 
-=== Agent:Executor Output ===
-{"message":"Found 10 results successfully.","results":[{"title":"How AI is improving diagnostics and health outcomes","url":"https://www.weforum.org/stories/2024/09/ai-diagnostics-health-outcomes/","summary":"By leveraging the power of AI for diagnostics, we can improve health outcomes and contribute to a future where healthcare is more accessible and effective for everyone, particularly in the communities that need it the most."},{"title":"14 Top Use Cases for AI in Healthcare in 2024","url":"https://www.cake.ai/blog/top-ai-healthcare-use-cases","summary":"We will explore the 14 top use cases for AI in healthcare, demonstrating how these technologies are improving patient outcomes and streamlining operations from the front desk to the operating room."},{"title":"Artificial Intelligence (AI) Applications in Drug Discovery and Drug ...","url":"https://pubmed.ncbi.nlm.nih.gov/39458657/","summary":"In this review article, we will present a comprehensive overview of AI's applications in the pharmaceutical industry, covering areas such as drug discovery, target optimization, personalized medicine, drug safety, and more."},{"title":"Top 10 AI in Healthcare Applications 2025 | Diagnosis to Patient Care","url":"https://www.guvi.in/blog/ai-in-healthcare-applications/","summary":"Unravel the top 10 AI in healthcare applications transforming 2025, from diagnosis accuracy to patient care, drug discovery, monitoring, and cost reduction."},{"title":"AI in Healthcare: Enhancing Patient Care and Diagnosis","url":"https://www.park.edu/blog/ai-in-healthcare-enhancing-patient-care-and-diagnosis/","summary":"Below, we delve into the various applications of AI in healthcare and examine how it enhances patient care and diagnosis — along with the challenges and opportunities that lie ahead."},{"title":"Generative Artificial Intelligence in Healthcare: Applications ...","url":"https://www.mdpi.com/2673-7426/5/3/37","summary":"These generative AI models have shown widespread applications in clinical practice and research. Such applications range from medical documentation and diagnostics to patient communication and drug discovery."},{"title":"The Impact of Artificial Intelligence on Healthcare: A Comprehensive ...","url":"https://onlinelibrary.wiley.com/doi/full/10.1002/hsr2.70312","summary":"Core applications like remote monitoring and predictive analytics improve operational effectiveness and patient involvement. However, there are major obstacles to the mainstream implementation of AI in healthcare, including issues with data security and budget constraints."},{"title":"Reviewing Artificial Intelligence Applications in Healthcare ...","url":"https://worldscientificnews.com/reviewing-artificial-intelligence-applications-in-healthcare-diagnostics-benefits-challenges-and-future-directions/","summary":"Artificial intelligence (AI) transforms healthcare diagnostics by enabling faster, more accurate, cost-effective disease detection and treatment planning. This paper reviews AI's applications, benefits, challenges, and future directions in diagnostics."},{"title":"Artificial Intelligence in Healthcare: Transforming Diagnostics, Drug ...","url":"https://medtechnews.uk/research-reports/artificial-intelligence-in-healthcare-transforming-diagnostics-drug-discovery-and-ethical-considerations/","summary":"This report embarks on a detailed exploration of the diverse and expanding applications of AI in healthcare, with particular emphasis on its transformative contributions to disease diagnostics and the intricate, multi-stage process of drug discovery."},{"title":"AI in Healthcare Applications - admedica.com","url":"https://admedica.com/2024/12/23/real-world-applications-of-ai-in-healthcare/","summary":"From streamlining diagnostics to enhancing patient care, AI is making medical services faster, more accurate, and more personalized. Here's a closer look at how AI is being applied in healthcare, with real-world examples that highlight its impact."}]}
-2025/09/08 11:48:46 
-=== Agent:Executor Output ===
-In 2024, AI applications in healthcare are notably advancing across several main areas:
-
-1. Diagnostics:
-- AI-powered diagnostic tools are enabling faster, more accurate, and cost-effective disease detection and treatment planning.
-- Techniques such as machine learning and generative AI improve early detection of conditions and enhance health outcomes.
-- AI supports analysis of medical imaging and patient records for precise diagnostics.
-- Real-world implementations demonstrate improved accessibility and effectiveness, particularly benefiting underserved communities.
-
-2. Patient Care:
-- AI enhances personalized patient care through predictive analytics, remote monitoring, and data integration.
-- Generative AI assists in medical documentation and patient communication, improving care coordination.
-- AI-driven tools help in chronic disease management, patient monitoring, and decision support.
-- These technologies facilitate more tailored, responsive healthcare experiences.
-
-3. Drug Discovery:
-- AI expedites drug discovery processes including target optimization, safety assessment, and personalized medicine development.
-- Generative AI and machine learning models aid in identifying new drug candidates and predicting therapeutic responses.
-- AI contributes to reducing costs and timelines in pharmaceutical research.
-
-4. Medical Imaging:
-- AI integration in medical imaging allows better identification of abnormalities and supports customized treatment planning.
-- Enhanced imaging diagnostics rely on deep learning models interpreting complex data with a higher degree of precision.
-- These advances enable earlier disease detection and more effective interventions.
-
-5. Healthcare Administration:
-- AI applications streamline healthcare operations such as scheduling, resource allocation, and billing.
-- Predictive analytics optimize hospital workflows and patient flow management.
-- AI solutions improve operational efficiency and reduce administrative burdens on healthcare providers.
-
-Overall, these AI applications in 2024 are driving transformative changes in healthcare delivery by improving diagnostic accuracy, enhancing patient care personalization, accelerating drug development, refining medical imaging analysis, and optimizing administrative processes. Would you like me to proceed with investigating the current industry trends related to AI in healthcare for 2024 next?
-2025/09/08 11:48:49 
-=== Agent:Replanner Output ===
-{"steps":["Investigate current industry trends related to AI in healthcare for 2024, including adoption rates, regulatory changes, ethical considerations, funding landscape, and market forecasts.","Synthesize the gathered information into a comprehensive summary covering the latest developments in AI for healthcare in 2024, highlighting key technologies, applications, and industry trends with examples and implications."]}
-2025/09/08 11:48:55 
-=== Agent:Executor Output ===
-{"message":"Found 10 results successfully.","results":[{"title":"Ethical and legal considerations in healthcare AI: innovation and ...","url":"https://royalsocietypublishing.org/doi/10.1098/rsos.241873","summary":"Artificial intelligence (AI) is transforming healthcare by enhancing diagnostics, personalizing medicine and improving surgical precision. However, its integration into healthcare systems raises significant ethical and legal challenges."},{"title":"Ethical Considerations in AI-Enabled Healthcare","url":"https://link.springer.com/chapter/10.1007/978-3-031-80813-5_18","summary":"Integrating Artificial Intelligence (AI) in healthcare has revolutionized patient care and operational workflows, yet it introduces significant ethical considerations. This chapter explores the impact of AI on key ethical principles—beneficence, nonmaleficence, autonomy, and justice."},{"title":"Ethical implications of AI-driven clinical decision support systems on ...","url":"https://bmcmedethics.biomedcentral.com/articles/10.1186/s12910-024-01151-8","summary":"Artificial intelligence-driven Clinical Decision Support Systems (AI-CDSS) are increasingly being integrated into healthcare for various purposes, including resource allocation. While these systems promise improved efficiency and decision-making, they also raise significant ethical concerns."},{"title":"Ethical debates amidst flawed healthcare artificial intelligence ...","url":"https://www.nature.com/articles/s41746-024-01242-1","summary":"Healthcare AI faces an ethical dilemma between selective and equitable deployment, exacerbated by flawed performance metrics. These metrics inadequately capture real-world complexities and..."},{"title":"Ethical Implications in AI-Based Health Care Decision Making: A ...","url":"https://liebertpub.com/doi/abs/10.1089/aipo.2024.0007","summary":"This critical analysis explores the ethical implications of AI-based health care decision making, examining the existing literature, methodological approaches, and ethical frameworks."},{"title":"AI ethics in medical research: the 2024 Declaration of Helsinki","url":"https://www.thelancet.com/journals/lancet/article/PIIS0140-6736(24)02376-6/fulltext","summary":"The recent update to the World Medical Association's Declaration of Helsinki,1 adopted at the 75th World Medical Association General Assembly in October, 2024, signals yet another milestone in the ongoing effort to safeguard ethical standards in medical research involving human participants."},{"title":"Navigating ethical considerations in the use of artificial intelligence ...","url":"https://pubmed.ncbi.nlm.nih.gov/39545614/","summary":"Results: The review highlighted critical ethical challenges, such as data privacy and security, accountability for AI-driven decisions, transparency in AI decision-making, and maintaining the human touch in care."},{"title":"The 5 Biggest Ethical Issues with AI in Healthcare","url":"https://www.keragon.com/blog/ethical-issues-with-ai-in-healthcare","summary":"What are the ethical issues with AI in healthcare? Dive into complex debates and considerations surrounding the ethical use of healthcare AI."},{"title":"Frontiers | Ethical-legal implications of AI-powered healthcare in ...","url":"https://www.frontiersin.org/journals/artificial-intelligence/articles/10.3389/frai.2025.1619463/full","summary":"It argues that by prioritizing ethical considerations in the development and deployment of AI, medical professionals can enhance health outcomes and cultivate patient trust, thereby bridging the gap between technological advancements and nuanced healthcare realities (Collins et al., 2024)."},{"title":"(PDF) Ethical framework for artificial intelligence in healthcare ...","url":"https://www.researchgate.net/publication/381669447_Ethical_framework_for_artificial_intelligence_in_healthcare_research_A_path_to_integrity","summary":"This article sets out to introduce a detailed framework designed to steer governance and offer a systematic method for assuring that AI applications in healthcare research are developed and..."}]}
-2025/09/08 11:49:01 
-=== Agent:Executor Output ===
-{"message":"Found 10 results successfully.","results":[{"title":"Medscape and HIMSS Release 2024 Report on AI Adoption in Healthcare","url":"https://www.prnewswire.com/news-releases/medscape-and-himss-release-2024-report-on-ai-adoption-in-healthcare-302324936.html","summary":"The full \"AI Adoption in Healthcare Report 2024\" is now available on both Medscape and HIMSS websites offering detailed analysis and insights into the current state of AI adoption..."},{"title":"AI in Healthcare Statistics 2025: Overview of Trends","url":"https://docus.ai/blog/ai-healthcare-statistics","summary":"As we step into 2025, let's see how AI in healthcare statistics from 2024 are shaping trends in patient care, diagnostics, and innovation."},{"title":"AI in healthcare - statistics & facts | Statista","url":"https://www.statista.com/topics/10011/ai-in-healthcare/","summary":"Distribution of confidence in using a new technology and AI in healthcare among health professionals in Denmark, France, Germany, and the United Kingdom as of 2024"},{"title":"AI In Healthcare Stats 2025: Adoption, Accuracy & Market","url":"https://www.demandsage.com/ai-in-healthcare-stats/","summary":"Get insights into AI in healthcare stats, including adoption rate, performance accuracy, and the rapidly growing market valuation."},{"title":"HIMSS and Medscape Unveil Groundbreaking Report on AI Adoption at ...","url":"https://gkc.himss.org/news/himss-and-medscape-unveil-groundbreaking-report-ai-adoption-health-systems","summary":"The findings, highlighted in the Medscape & HIMSS AI Adoption by Health Systems Report 2024, reveal that 86% of respondents already leverage AI in their medical organizations, with 60% recognizing its ability to uncover health patterns and diagnoses beyond human detection."},{"title":"Adoption of artificial intelligence in healthcare: survey of health ...","url":"https://academic.oup.com/jamia/article/32/7/1093/8125015","summary":"To evaluate the current state of AI adoption in US healthcare systems, assess successes and barriers to implementation during the early generative AI era. This cross-sectional survey was conducted in Fall 2024, and included 67 health systems members of the Scottsdale Institute, a collaborative of US non-profit healthcare organizations."},{"title":"19+ AI in Healthcare Statistics for 2024: Insights & Projections","url":"https://www.allaboutai.com/resources/ai-statistics/healthcare/","summary":"Discover 19+ AI in healthcare statistics for 2024, covering public perception, market trends, and revenue projections with expert insights."},{"title":"AI in Healthcare Statistics By Market Share And Technology","url":"https://www.sci-tech-today.com/stats/ai-in-healthcare-statistics/","summary":"In the second quarter of 2024, the US held a dominant position with a 58% revenue share, reflecting its strong focus on AI development and deployment. Similarly, the rest of the world followed..."},{"title":"AI in healthcare statistics: 62 findings from 18 research reports - Keragon","url":"https://www.keragon.com/blog/ai-in-healthcare-statistics","summary":"⚪️ Consumer adoption of gen AI for health reasons has remained flat, with just 37% of consumers using it in 2024 versus 40% in 2023. Source: Deloitte Center for Health Solutions's' 2024 Health Care Consumer Survey"},{"title":"New AMA report highlights physician optimism about AI in health care","url":"https://www.medicaleconomics.com/view/new-ama-report-highlights-physician-optimism-about-ai-in-health-care","summary":"The adoption of artificial intelligence (AI) in health care nearly doubled in 2024 compared to 2023 — a reflection of growing enthusiasm and decreasing apprehension toward the technology, despite some lingering concerns, according to a new report from the American Medical Association (AMA)."}]}
-2025/09/08 11:49:04 
-=== Agent:Executor Output ===
-{"message":"Found 10 results successfully.","results":[{"title":"AI in Healthcare: Funding Resurgence for Biotech Startups in 2024","url":"https://techainews.digital/2024/12/12/ai-in-healthcare-funding-resurgence-for-biotech-startups-in-2024/","summary":"In summary, the funding landscape for AI-driven biotech and healthcare startups in 2024 is showing a marked revival after a challenging previous year. With an influx of capital reflecting strong investor interest, companies harnessing AI to revolutionize drug discovery and enhance healthcare processes are at the forefront of this resurgence."},{"title":"AI Healthcare Startups: Investment & Funding Trends","url":"https://www.delveinsight.com/blog/ai-healthcare-startups-funding-trends","summary":"Discover how AI healthcare startups are attracting billions in funding and reshaping the future of healthcare and pharma."},{"title":"How healthcare AI led a 'paradigm shift' in a $23B year for startups","url":"https://carta.com/data/industry-spotlight-healthcare-2024/","summary":"The rate of all new healthcare investments in which valuations were lower than that of the previous round declined slightly over the course of 2024, settling at 19% in the final quarter of the year. Still, down rounds remain a persistent aspect of the healthcare fundraising landscape."},{"title":"AI-Healthcare Startups Surge with Record Funding: A Look at 2025's ...","url":"https://opentools.ai/news/ai-healthcare-startups-surge-with-record-funding-a-look-at-2025s-promising-landscape","summary":"Notably, the landscape of AI-healthcare startup funding has demonstrated robust growth, amounting to $7.5 billion worldwide in 2024, with an additional $1.68 billion earmarked for early 2025."},{"title":"The State of the Funding Market for AI Companies: A 2024 - 2025 Outlook","url":"https://www.mintz.com/insights-center/viewpoints/2166/2025-03-10-state-funding-market-ai-companies-2024-2025-outlook","summary":"In 2024, these AI-driven companies captured a substantial share of venture capital funding. Overall, venture capital investment in healthcare rose to $23 billion, up from $20 billion in 2023, with nearly 30% of the 2024 funding directed toward AI-focused startups."},{"title":"2024 year-end market overview: Davids and Goliaths - Rock Health","url":"https://rockhealth.com/insights/2024-year-end-market-overview-davids-and-goliaths/","summary":"These dual trends—early-stage startup activity amidst big moves by large healthcare players—have created a David and Goliath dynamic in the healthcare innovation landscape. We see a future where David and Goliath can coexist, and even thrive together, to drive impactful change in healthcare."},{"title":"AI and TechBio Funding Lead the Charge: 2024 Digital Health Funding ...","url":"https://www.galengrowth.com/ai-and-techbio-funding-lead-the-charge-2024-digital-health-funding-resurgence/","summary":"Global digital health funding rebounded to $25.1 billion in 2024, marking a 5.5% year-on-year increase. Europe saw the highest regional growth, with funding surging by 27% from 2023, while the US retained its dominance, contributing $17.2 billion in funding."},{"title":"Healthcare venture capital investment amplified by AI in 2024: report","url":"https://www.healthcaredive.com/news/healthcare-venture-captial-funding-ai-boost-2024-silicon-valley-bank/736870/","summary":"Venture capital investment in healthcare increased in 2024, spurred by enthusiasm for artificial intelligence startups, according to a report by Silicon Valley Bank. Funding for U.S...."},{"title":"These 10 healthcare AI startups have pulled in the most cash","url":"https://pitchbook.com/news/articles/healthcare-ai-startups-vc-funding","summary":"As of Q3 2024, funding had surpassed 2023's total with $10.5 billion generated across 511 deals. These 10 healthcare AI startups have raised the most capital from VC investors, leading the space to new heights while capitalizing on the AI frenzy."},{"title":"AI Finance for Healthcare 2024 - byteplus.com","url":"https://www.byteplus.com/en/topic/394250","summary":"Explore AI finance trends in healthcare for 2024, including investment insights, market growth, and emerging technologies."}]}
-2025/09/08 11:49:05 
-=== Agent:Executor Output ===
-{"message":"Found 10 results successfully.","results":[{"title":"Artificial Intelligence in Healthcare Market Size to Hit USD 613.81 Bn ...","url":"https://www.precedenceresearch.com/artificial-intelligence-in-healthcare-market","summary":"The global artificial intelligence (AI) in healthcare market size reached USD 26.69 billion in 2024 and is projected to hit around USD 613.81 billion by 2034, at a CAGR of 36.83%."},{"title":"AI in Healthcare Market Size, Share | Growth Report [2025-2032]","url":"https://www.fortunebusinessinsights.com/industry-reports/artificial-intelligence-in-healthcare-market-100534","summary":"The global AI in healthcare market size was valued at $29.01 billion in 2024 & is projected to grow from $39.25 billion in 2025 to $504.17 billion by 2032"},{"title":"AI in Healthcare Statistics 2025: Overview of Trends","url":"https://docus.ai/blog/ai-healthcare-statistics","summary":"As we step into 2025, let's see how AI in healthcare statistics from 2024 are shaping trends in patient care, diagnostics, and innovation."},{"title":"Artificial Intelligence (AI) in Healthcare Market Size to","url":"https://www.globenewswire.com/news-release/2025/04/02/3054390/0/en/Artificial-Intelligence-AI-in-Healthcare-Market-Size-to-Hit-USD-613-81-Bn-by-2034.html","summary":"Ottawa, April 02, 2025 (GLOBE NEWSWIRE) -- According to Precedence Research, the artificial intelligence (AI) in healthcare market size was valued at USD 26.69 billion in 2024, calculated..."},{"title":"19+ AI in Healthcare Statistics for 2024: Insights & Projections","url":"https://www.allaboutai.com/resources/ai-statistics/healthcare/","summary":"Discover 19+ AI in healthcare statistics for 2024, covering public perception, market trends, and revenue projections with expert insights."},{"title":"AI in Healthcare Market Leads 37.66% Healthy CAGR by 2034","url":"https://www.towardshealthcare.com/insights/ai-in-healthcare-market","summary":"According to market projections, the AI in healthcare sector is expected to grow from USD 27.59 billion in 2024 to USD 674.19 billion by 2034, reflecting a CAGR of 37.66%."},{"title":"AI In Healthcare Market Size, Share | Industry Report, 2033","url":"https://www.globalmarketstatistics.com/market-reports/artificial-intelligence-in-healthcare-market-12394","summary":"Market Size and Growth: The Artificial Intelligence in Healthcare Market Market size was USD 5011.24 Million in 2024, is projected to grow to USD 5762.41 Million by 2025 and exceed USD 8966.05 Million by 2033, with a CAGR of 21.4% from 2025-2033."},{"title":"AI in Healthcare Market Outlook 2024-2033: Trends ... - LinkedIn","url":"https://www.linkedin.com/pulse/ai-healthcare-market-outlook-20242033-trends-nil8c","summary":"AI in Healthcare Market size was valued at USD 11.6 Billion in 2024 and is forecasted to grow at a CAGR of 24% from 2026 to 2033, reaching USD 64.5 Billion by 2033."},{"title":"AI In Healthcare Market Size to Reach $187.7 Billion by 2030 at CAGR 38 ...","url":"https://www.prnewswire.com/news-releases/ai-in-healthcare-market-size-to-reach-187-7-billion-by-2030-at-cagr-38-5---grand-view-research-inc-302439558.html","summary":"SAN FRANCISCO, April 28, 2025 /PRNewswire/ -- The global AI in healthcare market size is expected to reach USD 187.7 billion by 2030, registering a CAGR of 38.5% from 2024 to 2030,..."},{"title":"AI in Healthcare Market to Soar to USD 629 B by 2032 with 51.87% CAGR","url":"https://www.medboundtimes.com/medbound-blog/ai-healthcare-market-set-to-soar-to-usd629b","summary":"The global artificial intelligence in healthcare market was valued at USD 22.23 billion in 2024 and is projected to skyrocket to USD 629.09 billion by 2032, exhibiting a compound annual growth rate (CAGR) of 51.87% from 2025 to 2032, according to Data Bridge Market Research."}]}
-```
-
-## 总结
-
-Plan-Execute Agent 通过「规划-执行-反思」的闭环工作流，将复杂任务拆解为可执行步骤，结合工具调用与动态调整，有效提升了任务完成的可靠性与效率。其核心优势在于：
-
-- **结构化任务拆解**：降低复杂问题的认知负荷
-- **工具集成能力**：无缝对接外部工具（搜索、计算、数据库等）
-- **动态适应性**：根据执行反馈实时调整策略，应对不确定性
-
-通过 Eino ADK 提供的 `PlanExecuteAgent`，开发者可快速搭建具备复杂任务处理能力的智能体系统，适用于研究分析、自动化办公、智能客服等多种场景。
-
-## 常见问题
-
-### 报错 [NodeRunError] no tool call
-
-Planner / Replanner 必须通过工具调用生成计划，出现此报错时请检查：
-
-1. 所使用的模型是否支持强制工具调用（例如 openai tool_choice="required")
-2. 所使用的模型 eino-ext 封装是否升级到最新（例如旧版本 ark sdk 不支持强制工具调用）
-
-### 报错 [NodeRunError] unexpected tool call
-
-Replanner 注册的 ChatModel 不应该通过 WithTools 方法携带额外工具，如有该情况请清空工具
-
-### 报错 [NodeRunError] unmarshal plan error
-
-Planner / Replanner config 中基于 PlanTool 和 NewPlan 两个字段共同生成计划：
-
-- PlanTool 作为向模型提供的 Plan 描述
-- NewPlan 方法作为框架构建 plan 的 builder，用于将模型返回的 Plan unmarshal 到该 struct 上供后续步骤运行
-
-当出现该错误时，请检查 PlanTool 中提供的字段描述是否和 NewPlan 方法中返回的结构体字段匹配，对齐后重新运行即可。

docs/Eino/docs/core_modules/eino_adk/agent_implementation/supervisor.md

@@ -1,499 +0,0 @@
----
-Description: ""
-date: "2026-03-02"
-lastmod: ""
-tags: []
-title: Supervisor Agent
-weight: 3
----
-
-## Supervisor Agent 概述
-
-### Import Path
-
-`import ``github.com/cloudwego/eino/adk/prebuilt/supervisor`
-
-### 什么是 Supervisor Agent？
-
-Supervisor Agent 是一种中心化多 Agent 协作模式，由一个监督者（Supervisor Agent） 和多个子 Agent（SubAgents）组成。Supervisor 负责任务的分配、子 Agent 执行过程的监控，以及子 Agent 完成后的结果汇总与下一步决策；子 Agent 则专注于执行具体任务，并在完成后通过 WithDeterministicTransferTo 自动将任务控制权交回 Supervisor。
-
-<a href="/img/eino/eino_adk_supervisor_definition.png" target="_blank"><img src="/img/eino/eino_adk_supervisor_definition.png" width="100%" /></a>
-
-该模式适用于需要动态协调多个专业 Agent 完成复杂任务的场景，例如：
-
-- 科研项目管理（Supervisor 分配调研、实验、报告撰写任务给不同子 Agent）。
-- 客户服务流程（Supervisor 根据用户问题类型，分配给技术支持、售后、销售等子 Agent）。
-
-### Supervisor Agent 结构
-
-Supervisor 模式的核心结构如下：
-
-- **Supervisor Agent**：作为协作核心，具备任务分配逻辑（如基于规则或 LLM 决策），可通过 `SetSubAgents` 将子 Agent 纳入管理。
-- **SubAgents**：每个子 Agent 被 WithDeterministicTransferTo 增强，预设 `ToAgentNames` 为 Supervisor 名称，确保任务完成后自动转让回 Supervisor。
-
-### Supervisor Agent 特点
-
-1. **确定性回调**：子 Agent 执行完毕（未中断）后，通过 WithDeterministicTransferTo 自动触发 Transfer 事件，将任务控制权交回 Supervisor，避免协作流程中断。
-2. **中心化控制**：Supervisor 统一管理子 Agent，可根据子 Agent 的执行结果动态调整任务分配（如分配给其他子 Agent 或直接生成最终结果）。
-3. **松耦合扩展**：子 Agent 可独立开发、测试和替换，只需确保实现 Agent 接口并绑定到 Supervisor，即可接入协作流程。
-4. **支持中断与恢复**：若子 Agent 或 Supervisor 支持 `ResumableAgent` 接口，协作流程可在中断后恢复，保持任务上下文连续性。
-
-### Supervisor Agent 运行流程
-
-Supervisor 模式的典型协作流程如下：
-
-1. **任务启动**：Runner 触发 Supervisor 运行，输入初始任务（如“完成一份 LLM 发展历史报告”）。
-2. **任务分配**：Supervisor 根据任务需求，通过 Transfer 事件将任务转让给指定子 Agent（如“调研 Agent”）。
-3. **子 Agent 执行**：子 Agent 执行具体任务（如调研 LLM 关键里程碑），并生成执行结果事件。
-4. **自动回调**：子 Agent 完成后，WithDeterministicTransferTo 触发 Transfer 事件，将任务转让回 Supervisor。
-5. **结果处理**：Supervisor 接收子 Agent 的结果，决定下一步（如分配给“报告撰写 Agent”继续处理，或直接输出最终结果）。
-
-## Supervisor Agent 使用示例
-
-### 场景说明
-
-创建一个科研报告生成系统：
-
-- **Supervisor**：基于用户输入的研究主题，分配任务给“调研 Agent”和“撰写 Agent”，并汇总最终报告。
-- **调研 Agent**：负责生成研究计划（如 LLM 发展的关键阶段）。
-- **撰写 Agent**：负责根据调研计划撰写完整报告。
-
-### 代码实现
-
-#### 步骤 1：实现子 Agent
-
-首先创建两个子 Agent，分别负责调研和撰写任务：
-
-```go
-// 调研 Agent：生成研究计划
-func NewResearchAgent(model model.ToolCallingChatModel) adk.Agent {
-    agent, _ := adk.NewChatModelAgent(context.Background(), &adk.ChatModelAgentConfig{
-       Name:        "ResearchAgent",
-       Description: "Generates a detailed research plan for a given topic.",
-       Instruction: `
-You are a research planner. Given a topic, output a step-by-step research plan with key stages and milestones.
-Output ONLY the plan, no extra text.`,
-       Model: model,
-    })
-    return agent
-}
-
-// 撰写 Agent：根据研究计划撰写报告
-func NewWriterAgent(model model.ToolCallingChatModel) adk.Agent {
-    agent, _ := adk.NewChatModelAgent(context.Background(), &adk.ChatModelAgentConfig{
-       Name:        "WriterAgent",
-       Description: "Writes a report based on a research plan.",
-       Instruction: `
-You are an academic writer. Given a research plan, expand it into a structured report with details and analysis.
-Output ONLY the report, no extra text.`,
-       Model: model,
-    })
-    return agent
-}
-```
-
-#### 步骤 2：实现 Supervisor Agent
-
-创建 Supervisor Agent，定义任务分配逻辑（此处简化为基于规则：先分配给调研 Agent，再分配给撰写 Agent）：
-
-```go
-// Supervisor Agent：协调调研和撰写任务
-func NewReportSupervisor(model model.ToolCallingChatModel) adk.Agent {
-    agent, _ := adk.NewChatModelAgent(context.Background(), &adk.ChatModelAgentConfig{
-        Name:        "ReportSupervisor",
-        Description: "Coordinates research and writing to generate a report.",
-        Instruction: `
-You are a project supervisor. Your task is to coordinate two sub-agents:
-- ResearchAgent: generates a research plan.
-- WriterAgent: writes a report based on the plan.
-
-Workflow:
-1. When receiving a topic, first transfer the task to ResearchAgent.
-2. After ResearchAgent finishes, transfer the task to WriterAgent with the plan as input.
-3. After WriterAgent finishes, output the final report.`,
-        Model: model,
-    })
-    return agent
-}
-```
-
-#### 步骤 3：组合 Supervisor 与子 Agent
-
-使用 `NewSupervisor` 将 Supervisor 和子 Agent 组合：
-
-```go
-import (
-    "context"
-
-    "github.com/cloudwego/eino-ext/components/model/openai"
-    "github.com/cloudwego/eino/adk"
-    "github.com/cloudwego/eino/adk/prebuilt/supervisor"
-    "github.com/cloudwego/eino/components/model"
-    "github.com/cloudwego/eino/schema"
-)
-
-func main() {
-    ctx := context.Background()
-
-    // 1. 创建 LLM 模型（如 GPT-4o）
-    model, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
-       APIKey: "YOUR_API_KEY",
-       Model:  "gpt-4o",
-    })
-
-    // 2. 创建子 Agent 和 Supervisor
-    researchAgent := NewResearchAgent(model)
-    writerAgent := NewWriterAgent(model)
-    reportSupervisor := NewReportSupervisor(model)
-
-    // 3. 组合 Supervisor 与子 Agent
-    supervisorAgent, _ := supervisor.New(ctx, &supervisor.Config{
-       Supervisor: reportSupervisor,
-       SubAgents:  []adk.Agent{researchAgent, writerAgent},
-    })
-
-    // 4. 运行 Supervisor 模式
-    iter := supervisorAgent.Run(ctx, &adk.AgentInput{
-       Messages: []adk.Message{
-          schema.UserMessage("Write a report on the history of Large Language Models."),
-       },
-       EnableStreaming: true,
-    })
-
-    // 5. 消费事件流（打印结果）
-    for {
-       event, ok := iter.Next()
-       if !ok {
-          break
-       }
-       if event.Output != nil && event.Output.MessageOutput != nil {
-          msg, _ := event.Output.MessageOutput.GetMessage()
-          println("Agent[" + event.AgentName + "]:\n" + msg.Content + "\n===========")
-       }
-    }
-}
-```
-
-### 运行结果
-
-```markdown
-Agent[ReportSupervisor]:
-
-===========
-Agent[ReportSupervisor]:
-successfully transferred to agent [ResearchAgent]
-===========
-Agent[ResearchAgent]:
-1. **Scope Definition & Background Research**  
-   - Task: Define "Large Language Model" (LLM) for the report (e.g., size thresholds, key characteristics: transformer-based, large-scale pretraining, general-purpose).  
-   - Task: Identify foundational NLP/AI concepts pre-LLMs (statistical models, early neural networks, word embeddings) to contextualize origins.  
-   - Milestone: 3-day literature review of academic definitions, industry reports, and AI historiographies to finalize scope.  
-
-2. **Chronological Periodization**  
-   - Task: Divide LLM history into distinct eras (e.g., Pre-2017: Pre-transformer foundations; 2017-2020: Transformer revolution & early LLMs; 2020-Present: Scaling & mainstream adoption).  
-   - Task: Map key events, models, and breakthroughs per era (e.g., 2017: "Attention Is All You Need"; 2018: GPT-1/BERT; 2020: GPT-3; 2022: ChatGPT; 2023: Llama 2).  
-   - Milestone: 10-day timeline draft with annotated model releases, research papers, and technological shifts.  
-
-3. **Key Technical Milestones**  
-   - Task: Deep-dive into critical innovations (transformer architecture, pretraining-fine-tuning paradigm, scaling laws, in-context learning).  
-   - Task: Extract details from seminal papers (authors, institutions, methodologies, performance benchmarks).  
-   - Milestone: 1-week analysis of 5-7 foundational papers (e.g., Vaswani et al. 2017; Radford et al. 2018; Devlin et al. 2018) with technical summaries.  
-
-4. **Stakeholder Mapping**  
-   - Task: Identify key organizations (OpenAI, Google DeepMind, Meta AI, Microsoft Research) and academic labs (Stanford, Berkeley) driving LLM development.  
-   - Task: Document institutional contributions (e.g., OpenAI’s GPT series, Google’s BERT/PaLM, Meta’s Llama) and research priorities (open vs. closed models).  
-   - Milestone: 5-day stakeholder profile draft with org-specific timelines and model lineages.  
-
-5. **Technical Evolution & Innovation Trajectory**  
-   - Task: Analyze shifts in architecture (from RNNs/LSTMs to transformers), training paradigms (pretraining + fine-tuning → instruction tuning → RLHF), and compute scaling (parameters, data size, GPU usage over time).  
-   - Task: Link technical changes to performance improvements (e.g., GPT-1 (124M params) vs. GPT-4 (100B+ params): task generalization, emergent abilities).  
-   - Milestone: 1-week technical trajectory report with data visualizations (param scaling, benchmark scores over time).  
-
-6. **Impact & Societal Context**  
-   - Task: Research LLM impact on NLP tasks (translation, summarization, QA) and beyond (education, content creation, policy).  
-   - Task: Document cultural/industry shifts (rise of prompt engineering, "AI-native" products, public perception post-ChatGPT).  
-   - Milestone: 5-day impact analysis integrating case studies (e.g., GitHub Copilot, healthcare LLMs) and media/scholarly discourse.  
-
-7. **Challenges & Critiques (Historical Perspective)**  
-   - Task: Track historical limitations (pre-2020: data sparsity, task specificity; post-2020: bias, misinformation, energy use) and responses (e.g., 2019: BERT bias audits; 2023: EU AI Act).  
-   - Task: Cite key critiques (e.g., "On the Dangers of Stochastic Parrots," 2021) and industry/academic reactions.  
-   - Milestone: 5-day challenge timeline linking issues to their emergence and mitigation efforts.  
-
-8. **Synthesis & Narrative Drafting**  
-   - Task: Integrate chronological, technical, and societal data into a coherent narrative (origins → revolution → scaling → mainstream impact).  
-   - Task: Outline report structure (Abstract, Introduction, Era-by-Era Analysis, Key Innovations, Stakeholders, Impact, Challenges, Conclusion).  
-   - Milestone: 1-week first draft of full report (8,000–10,000 words).  
-
-9. **Validation & Fact-Checking**  
-   - Task: Verify model release dates, paper citations, parameter counts, and stakeholder claims via primary sources (original papers, official press releases, archived GitHub repos).  
-   - Task: Cross-check with secondary sources (AI history books, expert interviews, peer-reviewed historiographies).  
-   - Milestone: 3-day validation report flagging/correcting inaccuracies.  
-
-10. **Finalization & Revision**  
-    - Task: Edit for clarity, narrative flow, and consistency; refine visuals (timelines, param scaling charts).  
-    - Task: Format references (APA/MLA) and appendices (model comparison table, key paper list).  
-    - Milestone: 2-day final report submission.
-===========
-Agent[ResearchAgent]:
-
-===========
-Agent[ResearchAgent]:
-successfully transferred to agent [ReportSupervisor]
-===========
-Agent[ReportSupervisor]:
-
-===========
-Agent[ReportSupervisor]:
-successfully transferred to agent [WriterAgent]
-===========
-Agent[WriterAgent]:
-# The History of Large Language Models: From Foundations to Mainstream Revolution  
-
-
-## Abstract  
-Large Language Models (LLMs) represent one of the most transformative technological innovations of the 21st century, enabling machines to understand, generate, and manipulate human language with unprecedented fluency. This report traces the historical trajectory of LLMs, from their conceptual roots in early natural language processing (NLP) to their current status as mainstream tools. It examines key technical milestones—including the invention of the transformer architecture, the rise of pretraining-fine-tuning paradigms, and the scaling of model parameters—and contextualizes these within the contributions of academic labs and tech giants. The report also analyzes societal impacts, from revolutionizing NLP tasks to sparking debates over bias, misinformation, and AI regulation. By synthesizing chronological, technical, and cultural data, this history reveals how LLMs evolved from niche research experiments to agents of global change.  
-
-
-## 1. Introduction: Defining Large Language Models  
-A **Large Language Model (LLM)** is a type of machine learning model designed to process and generate human language by learning patterns from massive text datasets. Key characteristics include: (1) a transformer-based architecture, enabling parallel processing of text sequences; (2) large-scale pretraining on diverse corpora (e.g., books, websites, articles); (3) general-purpose functionality, allowing adaptation to tasks like translation, summarization, or dialogue without task-specific engineering; and (4) scale, typically defined by billions (or tens of billions) of parameters (adjustable weights that capture linguistic patterns).  
-
-LLMs emerged from decades of NLP research, building on foundational concepts like statistical models (e.g., n-grams), early neural networks (e.g., recurrent neural networks [RNNs]), and word embeddings (e.g., Word2Vec, GloVe). By the 2010s, these predecessors had laid groundwork for "language understanding," but were limited by task specificity (e.g., a model trained for translation could not summarize text) and data sparsity. LLMs addressed these gaps by prioritizing scale, generality, and architectural innovation—ultimately redefining the boundaries of machine language capability.  
-
-
-## 2. Era-by-Era Analysis: The Evolution of LLMs  
-
-### 2.1 Pre-2017: Pre-Transformer Foundations (1950s–2016)  
-The roots of LLMs lie in mid-20th-century NLP, when researchers first sought to automate language tasks. Early efforts relied on rule-based systems (e.g., 1950s machine translation using syntax rules) and statistical methods (e.g., 1990s n-gram models for speech recognition). By the 2010s, neural networks gained traction: RNNs and long short-term memory (LSTM) models (Hochreiter & Schmidhuber, 1997) enabled sequence modeling, while word embeddings (Mikolov et al., 2013) represented words as dense vectors, capturing semantic relationships.  
-
-Despite progress, pre-2017 models faced critical limitations: RNNs/LSTMs processed text sequentially, making them slow to train and unable to handle long-range dependencies (e.g., linking "it" in a sentence to a noun paragraphs earlier). Data was also constrained: models like Word2Vec trained on millions, not billions, of tokens. These bottlenecks set the stage for a paradigm shift.  
-
-
-### 2.2 2017–2020: The Transformer Revolution and Early LLMs  
-The year 2017 marked the dawn of the LLM era with the publication of *"Attention Is All You Need"* (Vaswani et al.), which introduced the **transformer architecture**. Unlike RNNs, transformers use "self-attention" mechanisms to weigh the importance of different words in a sequence simultaneously, enabling parallel computation and capturing long-range dependencies. This breakthrough reduced training time and improved performance on language tasks.  
-
-#### Key Models and Breakthroughs:  
-- **2018**: OpenAI released **GPT-1** (Radford et al.), the first transformer-based LLM. With 124 million parameters, it introduced the "pretraining-fine-tuning" paradigm: pretraining on a large unlabeled corpus (BooksCorpus) to learn general language patterns, then fine-tuning on task-specific labeled data (e.g., sentiment analysis).  
-- **2018**: Google published **BERT** (Devlin et al.), a bidirectional transformer that processed text from left-to-right *and* right-to-left, outperforming GPT-1 on context-dependent tasks like question answering. BERT’s success popularized "contextual embeddings," where word meaning depends on surrounding text (e.g., "bank" as a financial institution vs. a riverbank).  
-- **2019**: OpenAI scaled up with **GPT-2** (1.5 billion parameters), demonstrating improved text generation but sparking early concerns about misuse (OpenAI initially delayed full release over fears of disinformation).  
-- **2020**: Google’s **T5** (Text-to-Text Transfer Transformer) unified NLP tasks under a single "text-to-text" framework (e.g., translating "translate English to French: Hello" to "Bonjour"), simplifying model adaptation.  
-
-
-### 2.3 2020–Present: Scaling, Emergence, and Mainstream Adoption  
-The 2020s saw LLMs transition from research curiosities to global phenomena, driven by exponential scaling of parameters, data, and compute.  
-
-#### Key Developments:  
-- **2020**: OpenAI’s **GPT-3** (175 billion parameters) marked a turning point. Trained on 45 terabytes of text, it exhibited "few-shot" and "zero-shot" learning—adapting to tasks with minimal examples (e.g., "Write a poem about AI" with no prior poetry training). GPT-3’s release via API (OpenAI Playground) introduced LLMs to developers, enabling early applications like chatbots and code generation.  
-- **2022**: **ChatGPT** (based on GPT-3.5) brought LLMs to the public. Launched in November, its user-friendly interface and conversational ability sparked a viral explosion (100 million users by January 2023). ChatGPT refined training with **Reinforcement Learning from Human Feedback (RLHF)**, aligning outputs with human preferences (e.g., helpfulness, safety).  
-- **2023**: Meta released **Llama 2** (7B–70B parameters), an open-source LLM that lowered barriers to entry, allowing researchers and startups to fine-tune models without proprietary access. Meanwhile, OpenAI’s **GPT-4** (100B+ parameters) expanded multimodality (text + images) and improved reasoning (e.g., solving math problems, coding).  
-- **2023–2024**: The "race to scale" continued with models like Google’s **PaLM 2** (540B parameters), Anthropic’s **Claude 2** (200B+ parameters), and open-source alternatives (e.g., Mistral, Falcon). Compute usage skyrocketed: training GPT-3 required ~3.14e23 floating-point operations (FLOPs), equivalent to 355 years of a single GPU’s work.  
-
-
-## 3. Key Technical Milestones  
-### 3.1 The Transformer Architecture (2017)  
-Vaswani et al.’s *"Attention Is All You Need"* (Google, University of Toronto) replaced RNNs with self-attention, a mechanism that computes "attention scores" between every pair of words in a sequence. For example, in "The cat sat on the mat; it purred," self-attention links "it" to "cat." This parallel processing reduced training time from weeks (for RNNs) to days, enabling larger models.  
-
-### 3.2 Pretraining-Fine-Tuning Paradigm (2018)  
-GPT-1 and BERT established the now-standard workflow: (1) Pretrain on a large, unlabeled corpus (e.g., Common Crawl, a web scrape of 1.1 trillion tokens) to learn syntax, semantics, and world knowledge; (2) Fine-tune on task-specific data (e.g., GLUE, a benchmark of 10 NLP tasks). This decoupled language learning from task engineering, enabling generalization.  
-
-### 3.3 Scaling Laws and Emergent Abilities (2020s)  
-In 2020, OpenAI researchers articulated **scaling laws**: model performance improves predictably with increased parameters, data, and compute. By 2022, this led to "emergent abilities"—skills not present in smaller models, such as GPT-3’s in-context learning or GPT-4’s multi-step reasoning.  
-
-### 3.4 Instruction Tuning and RLHF (2022)  
-Post-2020, training shifted from task-specific fine-tuning to **instruction tuning** (training on natural language instructions like "Summarize this article") and **RLHF** (rewarding models for human-preferred outputs). These methods made LLMs more usable: ChatGPT, for instance, follows prompts like "Explain quantum physics like I’m 5" without explicit fine-tuning.  
-
-
-## 4. Stakeholders: The Ecosystem of LLM Development  
-LLM evolution has been driven by a mix of tech giants, academic labs, and startups, each with distinct priorities:  
-
-### 4.1 Tech Giants: Closed vs. Open Models  
-- **OpenAI** (founded 2015, backed by Microsoft): Pioneered the GPT series, prioritizing commercialization via closed APIs (e.g., ChatGPT Plus, GPT-4 API). Focus: user-friendliness and safety (via RLHF).  
-- **Google DeepMind**: Developed BERT, T5, and PaLM, integrating LLMs into products like Google Search (via BERT) and Bard. Balances closed (PaLM) and open (T5) models.  
-- **Meta AI**: Advocated for open science with Llama 1/2 (2023), releasing weights for research and commercial use. Meta’s "open" approach aims to democratize LLM access and accelerate safety research.  
-- **Microsoft**: Partnered with OpenAI (2019–present), providing Azure compute and integrating GPT into Bing (search), Office (Copilot), and GitHub (Copilot X for coding).  
-
-### 4.2 Academic Labs  
-- **Stanford NLP**: Contributed to BERT and T5 research; developed HELM (Holistic Evaluation of Language Models), a benchmark for LLM safety and fairness.  
-- **UC Berkeley**: Studied LLM bias (e.g., 2021 paper "On the Dangers of Stochastic Parrots," critiquing LLMs as "statistical mimics" lacking true understanding).  
-
-
-## 5. Impact & Societal Context  
-### 5.1 Transforming NLP and Beyond  
-LLMs have redefined NLP performance: By 2023, GPT-4 outperformed humans on the MMLU benchmark (a test of 57 subjects, including math, law, and biology), scoring 86.4% vs. 86.5% for humans. Beyond NLP, they have revolutionized:  
-- **Content Creation**: Tools like Jasper and Copy.ai automate marketing copy; artists use DALL-E (paired with LLMs) for text-to-image generation.  
-- **Education**: Khan Academy’s Khanmigo tutors students; Coursera uses LLMs for personalized feedback.  
-- **Coding**: GitHub Copilot (2021) generates code from comments, boosting developer productivity by 55% (Microsoft, 2023).  
-
-### 5.2 Cultural Shifts  
-- **Prompt Engineering**: The rise of "prompt engineers"—professionals skilled in crafting text inputs to elicit desired LLM outputs—became a new career path.  
-- **AI-Native Products**: Startups like Character.AI (chatbots with distinct personalities) and Perplexity (AI-powered search) emerged as "LLM-first" services.  
-- **Public Perception**: Post-ChatGPT, LLMs shifted from "AI hype" to tangible utility, though skepticism persists (e.g., 62% of U.S. adults worry about job displacement, Pew Research, 2023).  
-
-
-## 6. Challenges & Critiques: A Historical Perspective  
-### 6.1 Technical Limitations  
-- **Pre-2020**: Data sparsity (small corpora limited generalization); task specificity (models like BERT required retraining for new tasks).  
-- **Post-2020**: **Hallucinations** (fabricating facts, e.g., GPT-3 citing fake research papers); **energy use** (training GPT-3 emitted ~500 tons of CO₂, equivalent to 125 round-trip flights from NYC to London); **computational inequality** (only tech giants can afford 100B+ parameter models).  
-
-### 6.2 Societal Risks  
-- **Bias**: Early LLMs mirrored training data biases (e.g., BERT associated "doctor" with "male" in 2019 audits). Responses included bias mitigation datasets (e.g., WinoBias) and audits (e.g., Stanford’s Gender Shades).  
-- **Misinformation**: GPT-2’s realistic text generation prompted calls for regulation; by 2023, deepfakes (e.g., AI-generated political speeches) became a policy focus.  
-- **Regulation**: The EU AI Act (2024) classified LLMs as "high-risk," requiring transparency (e.g., disclosing AI-generated content) and safety testing.  
-
-
-## 7. Conclusion: A Revolution in Five Years  
-The history of LLMs is a story of exponential progress: from the transformer’s 2017 invention to ChatGPT’s 2022 viral explosion, a mere five years. What began as an academic breakthrough—parallelizing text processing with self-attention—evolved into a technology that writes code, tutors students, and shapes global policy.  
-
-Yet challenges persist: scaling has outpaced our understanding of how LLMs "think," and debates over bias, energy use, and access (closed vs. open models) intensify. As we look to the future, this history reminds us that LLMs are not just technical achievements, but mirrors of society—reflecting both our ingenuity and our flaws. Their next chapter will depend on balancing innovation with responsibility, ensuring these models serve as tools for collective progress.  
-
-
-## References  
-- Devlin, J., et al. (2018). *BERT: Pre-training of deep bidirectional transformers for language understanding*. NAACL.  
-- Hochreiter, S., & Schmidhuber, J. (1997). *Long short-term memory*. Neural Computation.  
-- Mikolov, T., et al. (2013). *Efficient estimation of word representations in vector space*. ICLR.  
-- Radford, A., et al. (2018). *Improving language understanding by generative pre-training*. OpenAI.  
-- Vaswani, A., et al. (2017). *Attention is all you need*. NeurIPS.  
-- Weidinger, L., et al. (2021). *On the dangers of stochastic parrots: Can language models be too big?*. ACM FAccT.
-===========
-Agent[WriterAgent]:
-
-===========
-Agent[WriterAgent]:
-successfully transferred to agent [ReportSupervisor]
-===========
-```
-
-## WithDeterministicTransferTo
-
-### 什么是 WithDeterministicTransferTo？
-
-`WithDeterministicTransferTo` 是 Eino ADK 提供的 Agent 增强工具，用于为 Agent 注入任务转让（Transfer）能力 。它允许开发者为目标 Agent 预设固定的任务转让路径，当该 Agent 完成任务（未被中断）时，会自动生成 Transfer 事件，将任务流转到预设的目标 Agent。
-
-这一能力是构建 Supervisor Agent 协作模式的基础，确保子 Agent 在执行完毕后能可靠地将任务控制权交回监督者（Supervisor），形成“分配-执行-反馈”的闭环协作流程。
-
-### WithDeterministicTransferTo 核心实现
-
-#### 配置结构
-
-通过 `DeterministicTransferConfig` 定义任务转让的核心参数：
-
-```go
-// 包装方法
-func AgentWithDeterministicTransferTo(_ context.Context, config *DeterministicTransferConfig) Agent
-
-// 配置详情
-type DeterministicTransferConfig struct {
-    Agent        Agent          // 被增强的目标 Agent
-    ToAgentNames []string       // 任务完成后转让的目标 Agent 名称列表
-}
-```
-
-- `Agent`：需要添加转让能力的原始 Agent。
-- `ToAgentNames`：当 `Agent` 完成任务且未中断时，自动转让任务的目标 Agent 名称列表（按顺序转让）。
-
-#### Agent 包装
-
-WithDeterministicTransferTo 会对原始 Agent 进行包装，根据其是否实现 `ResumableAgent` 接口（支持中断与恢复），分别返回 `agentWithDeterministicTransferTo` 或 `resumableAgentWithDeterministicTransferTo` 实例，确保增强能力与 Agent 原有功能（如 `Resume` 方法）兼容。
-
-包装后的 Agent 会覆盖 `Run` 方法（对 `ResumableAgent` 还会覆盖 `Resume` 方法），在原始 Agent 的事件流基础上追加 Transfer 事件：
-
-```go
-// 对普通 Agent 的包装
-type agentWithDeterministicTransferTo struct {
-    agent        Agent          // 原始 Agent
-    toAgentNames []string       // 目标 Agent 名称列表
-}
-
-// Run 方法：执行原始 Agent 任务，并在任务完成后追加 Transfer 事件
-func (a *agentWithDeterministicTransferTo) Run(ctx context.Context, input *AgentInput, options ...AgentRunOption) *AsyncIterator[*AgentEvent] {
-    aIter := a.agent.Run(ctx, input, options...)
-    
-    iterator, generator := NewAsyncIteratorPair[*AgentEvent]()
-    
-    // 异步处理原始事件流，并追加 Transfer 事件
-    go appendTransferAction(ctx, aIter, generator, a.toAgentNames)
-    
-    return iterator
-}
-```
-
-对于 `ResumableAgent`，额外实现 `Resume` 方法，确保恢复执行后仍能触发确定性转让：
-
-```go
-type resumableAgentWithDeterministicTransferTo struct {
-    agent        ResumableAgent // 支持恢复的原始 Agent
-    toAgentNames []string       // 目标 Agent 名称列表
-}
-
-// Resume 方法：恢复执行原始 Agent 任务，并在完成后追加 Transfer 事件
-func (a *resumableAgentWithDeterministicTransferTo) Resume(ctx context.Context, info *ResumeInfo, opts ...AgentRunOption) *AsyncIterator[*AgentEvent] {
-    aIter := a.agent.Resume(ctx, info, opts...)
-    iterator, generator := NewAsyncIteratorPair[*AgentEvent]()
-    go appendTransferAction(ctx, aIter, generator, a.toAgentNames)
-    return iterator
-}
-```
-
-#### 事件流追加 Transfer 事件
-
-`appendTransferAction` 是实现确定性转让的核心逻辑，它会消费原始 Agent 的事件流，在 Agent 任务正常结束（未中断）后，自动生成并发送 Transfer 事件到目标 Agent：
-
-```go
-func appendTransferAction(ctx context.Context, aIter *AsyncIterator[*AgentEvent], generator *AsyncGenerator[*AgentEvent], toAgentNames []string) {
-    defer func() {
-        // 异常处理：捕获 panic 并通过事件传递错误
-        if panicErr := recover(); panicErr != nil {
-            generator.Send(&AgentEvent{Err: safe.NewPanicErr(panicErr, debug.Stack())})
-        }
-        generator.Close() // 事件流结束，关闭生成器
-    }()
-
-    interrupted := false
-
-    // 1. 转发原始 Agent 的所有事件
-    for {
-        event, ok := aIter.Next()
-        if !ok { // 原始事件流结束
-            break
-        }
-        generator.Send(event) // 转发事件给调用方
-
-        // 检查是否发生中断（如 InterruptAction）
-        if event.Action != nil && event.Action.Interrupted != nil {
-            interrupted = true
-        } else {
-            interrupted = false
-        }
-    }
-
-    // 2. 若未中断且存在目标 Agent，生成 Transfer 事件
-    if !interrupted && len(toAgentNames) > 0 {
-        for _, toAgentName := range toAgentNames {
-            // 生成转让消息（系统提示 + Transfer 动作）
-            aMsg, tMsg := GenTransferMessages(ctx, toAgentName)
-            // 发送系统提示事件（告知用户任务转让）
-            aEvent := EventFromMessage(aMsg, nil, schema.Assistant, "")
-            generator.Send(aEvent)
-            // 发送 Transfer 动作事件（触发任务转让）
-            tEvent := EventFromMessage(tMsg, nil, schema.Tool, tMsg.ToolName)
-            tEvent.Action = &AgentAction{
-                TransferToAgent: &TransferToAgentAction{
-                    DestAgentName: toAgentName, // 目标 Agent 名称
-                },
-            }
-            generator.Send(tEvent)
-        }
-    }
-}
-```
-
-**关键逻辑**：
-
-- **事件转发**：原始 Agent 产生的所有事件（如思考、工具调用、输出结果）会被完整转发，确保业务逻辑不受影响。
-- **中断检查**：若 Agent 执行过程中被中断（如 `InterruptAction`），则不触发 Transfer（中断视为任务未正常完成）。
-- **Transfer 事件生成**：任务正常结束后，为每个 `ToAgentNames` 生成两条事件：
-  1. 系统提示事件（`schema.Assistant` 角色）：告知用户任务将转让给目标 Agent。
-  2. Transfer 动作事件（`schema.Tool` 角色）：携带 `TransferToAgentAction`，触发 ADK 运行时将任务转让给 `DestAgentName` 对应的 Agent。
-
-## 总结
-
-WithDeterministicTransferTo 为 Agent 提供了可靠的任务转让能力，是构建 Supervisor 模式的核心基石；而 Supervisor 模式通过中心化协调与确定性回调，实现了多 Agent 之间的高效协作，显著降低了复杂任务的开发与维护成本。结合两者，开发者可快速搭建灵活、可扩展的多 Agent 系统。

docs/Eino/docs/core_modules/eino_adk/agent_interface.md

@@ -1,390 +0,0 @@
----
-Description: ""
-date: "2026-03-02"
-lastmod: ""
-tags: []
-title: Agent 抽象
-weight: 3
----
-
-# Agent 定义
-
-Eino 定义了 Agent 的基础接口，实现此接口的 Struct 可被视为一个 Agent：
-
-```go
-// github.com/cloudwego/eino/adk/interface.go
-
-type Agent interface {
-    Name(ctx context.Context) string
-    Description(ctx context.Context) string
-    Run(ctx context.Context, input *AgentInput, opts ...AgentRunOption) *AsyncIterator[*AgentEvent]
-}
-```
-
-<table>
-<tr><td>Method</td><td> 说明</td></tr>
-<tr><td>Name</td><td>Agent 的名称，作为 Agent 的标识</td></tr>
-<tr><td>Description</td><td>Agent 的职能描述信息，主要用于让其他的 Agent 了解和判断该 Agent 的职责或功能</td></tr>
-<tr><td>Run</td><td>Agent 的核心执行方法，返回一个迭代器，调用者可以通过这个迭代器持续接收 Agent 产生的事件</td></tr>
-</table>
-
-## AgentInput
-
-Run 方法接收 AgentInput 作为 Agent 的输入：
-
-```go
-type AgentInput struct {
-    Messages        []Message
-    EnableStreaming bool
-}
-
-type Message = *schema.Message
-```
-
-Agent 通常以 ChatModel 为核心，因此规定 Agent 的输入为 `Messages`， 与调用 Eino ChatModel 的类型相同。`Messages` 中可以包括用户指令、对话历史、背景知识、样例数据等任何你希望传递给 Agent 的数据。例如：
-
-```go
-import (
-    "github.com/cloudwego/eino/adk"
-    "github.com/cloudwego/eino/schema"
-)
-
-input := &adk.AgentInput{
-    Messages: []adk.Message{
-       schema.UserMessage("What's the capital of France?"),
-       schema.AssistantMessage("The capital of France is Paris.", nil),
-       schema.UserMessage("How far is it from London? "),
-    },
-}
-```
-
-`EnableStreaming` 用于向 Agent **建议**其输出模式，但它并非一个强制性约束。它的核心思想是控制那些同时支持流式和非流式输出的组件的行为，例如 ChatModel，而仅支持一种输出方式的组件，`EnableStreaming` 不会影响他们的行为。另外在 `AgentOutput.IsStreaming` 字段会标明实际输出类型。运行表现为：
-
-- 当 `EnableStreaming=false` 时，对于那些既能流式也能非流式输出的组件，此时会使用一次性返回完整结果的非流式模式。
-- 当 `EnableStreaming=true` 时，对于 Agent 内部能够流式输出的组件（如 ChatModel 调用），应以流的形式逐步返回结果。如果某个组件天然不支持流式，它仍然可以按其原有的非流式方式工作。
-
-如下图所示，ChatModel 既可以输出非流也可以输出流，Tool 只能输出非流，即：
-
-- 当 `EnableStream=false` 时，二者均输出非流
-- 当 `EnableStream=true` 时，ChatModel 输出流，Tool 因为不具备输出流的能力，仍然输出非流。
-
-<a href="/img/eino/eino_adk_streaming.png" target="_blank"><img src="/img/eino/eino_adk_streaming.png" width="100%" /></a>
-
-## AgentRunOption
-
-`AgentRunOption` 由 Agent 实现定义，可以在请求维度修改 Agent 配置或者控制 Agent 行为。
-
-Eino ADK 提供了一些通用定义的 Option，供用户使用：
-
-- `WithSessionValues`：设置跨 Agent 读写数据
-- `WithSkipTransferMessages`：配置后，当 Event 为 Transfer SubAgent 时，Event 中的消息不会追加到 History 中
-
-Eino ADK 提供了 `WrapImplSpecificOptFn` 和 `GetImplSpecificOptions` 两个方法，供 Agent 包装与读取自定义的 `AgentRunOption`。
-
-当使用 `GetImplSpecificOptions` 方法读取 `AgentRunOptions` 时，与所需类型（如例子中的 options）不符的 AgentRunOption 会被忽略。
-
-例如可以定义 `WithModelName`，在请求维度要求 Agent 修改调用的模型：
-
-```go
-// github.com/cloudwego/eino/adk/call_option.go
-// func WrapImplSpecificOptFn[T any](optFn func(*T)) AgentRunOption
-// func GetImplSpecificOptions[T any](base *T, opts ...AgentRunOption) *T
-
-import "github.com/cloudwego/eino/adk"
-
-type options struct {
-    modelName string
-}
-
-func WithModelName(name string) adk.AgentRunOption {
-    return adk.WrapImplSpecificOptFn(func(t *options) {
-       t.modelName = name
-    })
-}
-
-func (m *MyAgent) Run(ctx context.Context, input *adk.AgentInput, opts ...adk.AgentRunOption) *adk.AsyncIterator[*adk.AgentEvent] {
-    o := &options{}
-    o = adk.GetImplSpecificOptions(o, opts...)
-    // run code...
-}
-```
-
-除此之外，AgentRunOption 具有一个 `DesignateAgent` 方法，调用该方法可以在调用多 Agent 系统时指定 Option 生效的 Agent：
-
-```go
-func genOpt() {
-    // 指定 option 仅对 agent_1 和 agent_2 生效
-    opt := adk.WithSessionValues(map[string]any{}).DesignateAgent("agent_1", "agent_2")
-}
-```
-
-## AsyncIterator
-
-`Agent.Run` 返回了一个迭代器 `AsyncIterator[*AgentEvent]`：
-
-```go
-// github.com/cloudwego/eino/adk/utils.go
-
-type AsyncIterator[T any] struct {
-    ...
-}
-
-func (ai *AsyncIterator[T]) Next() (T, bool) {
-    ...
-}
-```
-
-它代表一个异步迭代器（异步指生产与消费之间没有同步控制），允许调用者以一种有序、阻塞的方式消费 Agent 在运行过程中产生的一系列事件。
-
-- `AsyncIterator` 是一个泛型结构体，可以用于迭代任何类型的数据。当前在 Agent 接口中， Run 方法返回的迭代器类型被固定为 `AsyncIterator[*AgentEvent]` 。这意味着，你从这个迭代器中获取的每一个元素，都将是一个指向 `AgentEvent` 对象的指针。`AgentEvent` 会在后续章节中详细说明。
-- 迭代器的主要交互方式是通过调用其 `Next()` 方法。这个方法的行为是 阻塞式 的，每次调用 `Next()` ，程序会暂停执行，直到以下两种情况之一发生：
-  - Agent 产生了一个新的 `AgentEvent` : `Next()` 方法会返回这个事件，调用者可以立即对其进行处理。
-  - Agent 主动关闭了迭代器 : 当 Agent 不会再产生任何新的事件时（通常是 Agent 运行结束），它会关闭这个迭代器。此时 `Next()` 调用会结束阻塞并在第二个返回值返回 false，告知调用者迭代已经结束。
-
-通常情况下，你需要使用 for 循环处理 `AsyncIterator`:
-
-```go
-iter := myAgent.Run(xxx) // get AsyncIterator from Agent.Run
-
-for {
-    event, ok := iter.Next()
-    if !ok {
-        break
-    }
-    // handle event
-}
-```
-
-`AsyncIterator` 可以由 `NewAsyncIteratorPair` 创建，该函数返回的另一个参数 `AsyncGenerator` 用来生产数据：
-
-```go
-// github.com/cloudwego/eino/adk/utils.go
-
-func NewAsyncIteratorPair[T any]() (*AsyncIterator[T], *AsyncGenerator[T])
-```
-
-Agent.Run 返回 AsyncIterator 旨在让调用者实时地接收到 Agent 产生的一系列 AgentEvent，因此 Agent.Run 通常会在 Goroutine 中运行 Agent 从而立刻返回 AsyncIterator 供调用者监听：
-
-```go
-import "github.com/cloudwego/eino/adk"
-
-func (m *MyAgent) Run(ctx context.Context, input *adk.AgentInput, opts ...adk.AgentRunOption) *adk.AsyncIterator[*adk.AgentEvent] {
-    // handle input
-    iter, gen := adk.NewAsyncIteratorPair[*adk.AgentEvent]()
-    go func() {
-       defer func() {
-          // recover code
-          gen.Close()
-       }()
-       // agent run code
-       // gen.Send(event)
-    }()
-    return iter
-}
-```
-
-## AgentWithOptions
-
-使用 `AgentWithOptions` 方法可以在 Eino ADK Agent 中进行一些通用配置。
-
-与 `AgentRunOption` 不同的是，`AgentWithOptions` 在运行前生效，并且不支持自定义 option。
-
-```go
-// github.com/cloudwego/eino/adk/flow.go
-func AgentWithOptions(ctx context.Context, agent Agent, opts ...AgentOption) Agent
-```
-
-Eino ADK 当前内置支持的配置有：
-
-- `WithDisallowTransferToParent`：配置该 SubAgent 不允许 Transfer 到 ParentAgent，会触发该 SubAgent 的 `OnDisallowTransferToParent` 回调方法
-- `WithHistoryRewriter`：配置后该 Agent 在执行前会通过该方法重写接收到的上下文信息
-
-# AgentEvent
-
-AgentEvent 是 Agent 在其运行过程中产生的核心事件数据结构。其中包含了 Agent 的元信息、输出、行为和报错：
-
-```go
-// github.com/cloudwego/eino/adk/interface.go
-
-type AgentEvent struct {
-    AgentName string
-
-    RunPath []RunStep
-
-    Output *AgentOutput
-
-    Action *AgentAction
-
-    Err error
-}
-
-// EventFromMessage 构建普通 event
-func EventFromMessage(msg Message, msgStream MessageStream, role schema.RoleType, toolName string) *AgentEvent
-```
-
-## AgentName & RunPath
-
-`AgentName` 和 `RunPath` 字段是由框架自动进行填充，它们提供了关于事件来源的重要上下文信息，在复杂的、由多个 Agent 构成的系统中至关重要。
-
-```go
-type RunStep struct {
-    agentName string
-}
-```
-
-- `AgentName` 标明了是哪一个 Agent 实例产生了当前的 AgentEvent 。
-- `RunPath` 记录了到达当前 Agent 的完整调用链路。`RunPath` 是一个 `RunStep` 切片，它按顺序记录了从最初的入口 Agent 到当前产生事件的 Agent 的所有 `AgentName`。
-
-## AgentOutput
-
-`AgentOutput` 封装了 Agent 产生的输出。
-
-Message 输出设置在 MessageOutput 字段中，其他类型的自定义输出设置在 CustomizedOutput 字段中：
-
-```go
-// github.com/cloudwego/eino/adk/interface.go
-
-type AgentOutput struct {
-    MessageOutput *MessageVariant
-
-    CustomizedOutput any
-}
-
-type MessageVariant struct {
-    IsStreaming bool
-
-    Message       Message
-    MessageStream MessageStream
-    // message role: Assistant or Tool
-    Role schema.RoleType
-    // only used when Role is Tool
-    ToolName string
-}
-```
-
-`MessageOutput` 字段的类型 `MessageVariant` 是一个核心数据结构，主要功能为：
-
-1. 统一处理流式与非流式消息：`IsStreaming` 是一个标志位。值为 true 表示当前 `MessageVariant` 包含的是一个流式消息（从 MessageStream 读取），为 false 则表示包含的是一个非流式消息（从 Message 读取）：
-
-   - 流式 : 随着时间的推移，逐步返回一系列消息片段，最终构成一个完整的消息（MessageStream）。
-   - 非流式 : 一次性返回一个完整的消息（Message）。
-2. 提供便捷的元数据访问：Message 结构体内部包含了一些重要的元信息，如消息的 Role（Assistant 或 Tool），为了方便快速地识别消息类型和来源， MessageVariant 将这些常用的元数据提升到了顶层：
-
-   - `Role`：消息的角色，Assistant / Tool
-   - `ToolName`：如果消息角色是 Tool ，这个字段会直接提供工具的名称。
-
-这样做的好处是，代码在需要根据消息类型进行路由或决策时， 无需深入解析 Message 对象的具体内容 ，可以直接从 MessageVariant 的顶层字段获取所需信息，从而简化了逻辑，提高了代码的可读性和效率。
-
-## AgentAction
-
-Agent 产生包含 AgentAction 的 Event 可以控制多 Agent 协作，比如立刻退出、中断、跳转等：
-
-```go
-// github.com/cloudwego/eino/adk/interface.go
-
-type AgentAction struct {
-    Exit bool
-
-    Interrupted *InterruptInfo
-
-    TransferToAgent *TransferToAgentAction
-    
-    BreakLoop *BreakLoopAction
-
-    CustomizedAction any
-}
-
-type InterruptInfo struct {
-    Data any
-}
-
-type TransferToAgentAction struct {
-    DestAgentName string
-}
-```
-
-Eino ADK 当前预设 Action 有四种：
-
-1. 退出：当 Agent 产生 Exit Action 时，Multi-Agent 会立刻退出
-
-```go
-func NewExitAction() *AgentAction {
-    return &AgentAction{Exit: true}
-}
-```
-
-1. 跳转：当 Agent 产生 Transfer Action 时，会跳转到目标 Agent 运行
-
-```go
-func NewTransferToAgentAction(destAgentName string) *AgentAction {
-    return &AgentAction{TransferToAgent: &TransferToAgentAction{DestAgentName: destAgentName}}
-}
-```
-
-1. 中断：当 Agent 产生 Interrupt Action 时，会中断 Runner 的运行。由于中断可能发生在任何位置，同时中断时需要向外传递独特的信息，Action 中提供了 `Interrupted` 字段供 Agent 设置自定义数据，Runner 接收到 Interrupted 不为空的 Action 时则认为产生了中断。Interrupt & Resume 内部机制较为复杂，在 【Eino ADK: Agent Runner】-【Eino ADK: Interrupt & Resume】章节会展开详述。
-
-```go
-// 例如 ChatModelAgent 中断时，会发送如下的 AgentEvent：
-h.Send(&AgentEvent{AgentName: h.agentName, Action: &AgentAction{
-    Interrupted: &InterruptInfo{
-       Data: &ChatModelAgentInterruptInfo{Data: data, Info: info},
-    },
-}})
-```
-
-4. 中止循环：当 LoopAgent 的一个子 Agent 发出 BreakLoopAction 时，对应的 LoopAgent 会停止循环并正常退出。
-
-# 语言设置
-
-ADK 提供了 `SetLanguage` 函数用于设置内置提示词（prompt）的语言。这影响所有 ADK 内置组件和中间件生成的提示词语言。本能力在 [alpha/08](https://github.com/cloudwego/eino/releases/tag/v0.8.0-alpha.13) 版本引入。
-
-## API
-
-```go
-// Language 表示 ADK 内置提示词的语言设置
-type Language uint8
-
-const (
-    // LanguageEnglish 表示英文（默认）
-    LanguageEnglish Language = iota
-    // LanguageChinese 表示中文
-    LanguageChinese
-)
-
-// SetLanguage 设置 ADK 内置提示词的语言
-// 默认语言是英文（如果未显式设置）
-func SetLanguage(lang Language) error
-```
-
-## 使用示例
-
-```go
-import "github.com/cloudwego/eino/adk"
-
-// 设置为中文
-err := adk.SetLanguage(adk.LanguageChinese)
-if err != nil {
-    // 处理错误
-}
-
-// 设置为英文（默认）
-err = adk.SetLanguage(adk.LanguageEnglish)
-```
-
-## 影响范围
-
-语言设置会影响以下组件的内置提示词：
-
-<table>
-<tr><td>组件/中间件</td><td>影响的提示词</td></tr>
-<tr><td>FileSystem Middleware</td><td>文件系统工具描述、系统提示词、执行工具提示词</td></tr>
-<tr><td>Reduction Middleware</td><td>工具结果截断/清理的提示文字</td></tr>
-<tr><td>Skill Middleware</td><td>技能系统提示词、技能工具描述</td></tr>
-<tr><td>ChatModelAgent</td><td>内置系统提示词</td></tr>
-</table>
-
-> 💡
-> 建议在程序初始化时设置语言，因为语言设置是全局生效的。在运行时更改语言可能导致同一会话中出现混合语言的提示词。
-
-> 💡
-> 语言设置仅影响 ADK 内置的提示词。你自定义的提示词（如 Agent 的 Instruction）需要自行处理国际化。