Eino 生态
├── eino          # 核心框架：类型定义、组件抽象、编排能力
├── eino-ext      # 扩展实现：各种 ChatModel、Tool、Retriever 的具体实现
├── eino-devops   # 开发工具：可视化调试、开发
└── eino-examples # 示例代码：最佳实践

Input → ChatTemplate → ChatModel → Output

        ┌─→ Tool A ─┐
Input → │           │ → ChatModel → Output
        └─→ Tool B ─┘

go get github.com/cloudwego/eino@latest
go get github.com/cloudwego/eino-ext@latest

package main

// 用户档案
type UserProfile struct {
    UserID      string   `json:"user_id"`
    Name        string   `json:"name"`
    Age         int      `json:"age"`
    Gender      string   `json:"gender"`      // male, female
    City        string   `json:"city"`        // 所在城市
    BodyType    string   `json:"body_type"`   // slim, medium, large
    HealthNotes string   `json:"health_notes"` // 健康备注，如：怕冷、关节炎
    StylePrefs  []string `json:"style_prefs"` // 风格偏好：casual, formal, sporty
    ColorPrefs  []string `json:"color_prefs"` // 颜色偏好
}

// 衣物信息
type ClothingItem struct {
    ID          string   `json:"id"`
    Type        string   `json:"type"`        // top, bottom, outerwear, shoes, accessory
    Name        string   `json:"name"`        // 衣物名称
    Color       string   `json:"color"`       // 颜色
    Style       string   `json:"style"`       // casual, formal, sporty
    WarmthLevel int      `json:"warmth_level"` // 保暖等级 1-5
    Occasions   []string `json:"occasions"`   // 适合场合
    ImageURL    string   `json:"image_url"`   // 图片链接
}

// 天气信息
type WeatherInfo struct {
    City        string `json:"city"`
    Temperature int    `json:"temperature"`  // 摄氏度
    FeelsLike   int    `json:"feels_like"`   // 体感温度
    Humidity    int    `json:"humidity"`     // 湿度
    Condition   string `json:"condition"`    // 天气状况：晴、多云、雨、雪
    WindSpeed   int    `json:"wind_speed"`   // 风速
    UVIndex     int    `json:"uv_index"`     // 紫外线指数
}

// 穿搭推荐
type OutfitRecommendation struct {
    Top        *ClothingItem `json:"top"`
    Bottom     *ClothingItem `json:"bottom"`
    Outerwear  *ClothingItem `json:"outerwear,omitempty"`
    Shoes      *ClothingItem `json:"shoes"`
    Accessory  *ClothingItem `json:"accessory,omitempty"`
    Reason     string        `json:"reason"`     // 推荐理由
    StyleTips  string        `json:"style_tips"` // 穿搭小贴士
}

func NewWeatherTool() tool.InvokableTool {
    return tool.NewTool(
        &schema.ToolInfo{
            Name:        "get_weather",
            Description: "获取指定城市的当前天气信息，包括温度、体感温度、湿度、天气状况等",
            Parameters: map[string]interface{}{
                "type": "object",
                "properties": map[string]interface{}{
                    "city": map[string]interface{}{
                        "type":        "string",
                        "description": "城市名称，如：北京、上海、杭州",
                    },
                },
                "required": []string{"city"},
            },
        },
        func(ctx context.Context, input string) (string, error) {
            var params struct {
                City string `json:"city"`
            }
            json.Unmarshal([]byte(input), &params)

            // 实际项目中调用天气 API，这里模拟
            weather := WeatherInfo{
                City:        params.City,
                Temperature: 8,
                FeelsLike:   5,
                Humidity:    65,
                Condition:   "多云",
                WindSpeed:   15,
                UVIndex:     2,
            }

            result, _ := json.Marshal(weather)
            return string(result), nil
        },
    )
}

func NewUserProfileTool(profileStore map[string]*UserProfile) tool.InvokableTool {
    return tool.NewTool(
        &schema.ToolInfo{
            Name:        "get_user_profile",
            Description: "获取用户的个人信息，包括年龄、性别、身体状况、穿衣风格偏好等",
            Parameters: map[string]interface{}{
                "type": "object",
                "properties": map[string]interface{}{
                    "user_id": map[string]interface{}{
                        "type":        "string",
                        "description": "用户ID",
                    },
                },
                "required": []string{"user_id"},
            },
        },
        func(ctx context.Context, input string) (string, error) {
            var params struct {
                UserID string `json:"user_id"`
            }
            json.Unmarshal([]byte(input), &params)

            profile, ok := profileStore[params.UserID]
            if !ok {
                return `{"error": "用户不存在"}`, nil
            }

            result, _ := json.Marshal(profile)
            return string(result), nil
        },
    )
}

func NewWardrobeTool(wardrobeStore map[string][]*ClothingItem) tool.InvokableTool {
    return tool.NewTool(
        &schema.ToolInfo{
            Name:        "get_wardrobe",
            Description: "获取用户衣柜中的所有衣物，可按类型筛选（top上衣、bottom下装、outerwear外套、shoes鞋子、accessory配饰）",
            Parameters: map[string]interface{}{
                "type": "object",
                "properties": map[string]interface{}{
                    "user_id": map[string]interface{}{
                        "type":        "string",
                        "description": "用户ID",
                    },
                    "clothing_type": map[string]interface{}{
                        "type":        "string",
                        "description": "衣物类型筛选，可选：top, bottom, outerwear, shoes, accessory。不填则返回全部",
                    },
                },
                "required": []string{"user_id"},
            },
        },
        func(ctx context.Context, input string) (string, error) {
            var params struct {
                UserID       string `json:"user_id"`
                ClothingType string `json:"clothing_type"`
            }
            json.Unmarshal([]byte(input), &params)

            items, ok := wardrobeStore[params.UserID]
            if !ok {
                return `{"error": "衣柜为空"}`, nil
            }

            // 按类型筛选
            if params.ClothingType != "" {
                filtered := make([]*ClothingItem, 0)
                for _, item := range items {
                    if item.Type == params.ClothingType {
                        filtered = append(filtered, item)
                    }
                }
                items = filtered
            }

            result, _ := json.Marshal(items)
            return string(result), nil
        },
    )
}

func NewFeedbackTool(feedbackStore map[string][]string) tool.InvokableTool {
    return tool.NewTool(
        &schema.ToolInfo{
            Name:        "save_feedback",
            Description: "保存用户对穿搭推荐的反馈，用于改进后续推荐",
            Parameters: map[string]interface{}{
                "type": "object",
                "properties": map[string]interface{}{
                    "user_id": map[string]interface{}{
                        "type":        "string",
                        "description": "用户ID",
                    },
                    "feedback_type": map[string]interface{}{
                        "type":        "string",
                        "description": "反馈类型：like（喜欢）、dislike（不喜欢）、too_warm（太热）、too_cold（太冷）、wrong_style（风格不对）",
                    },
                    "feedback_detail": map[string]interface{}{
                        "type":        "string",
                        "description": "详细反馈内容",
                    },
                },
                "required": []string{"user_id", "feedback_type"},
            },
        },
        func(ctx context.Context, input string) (string, error) {
            var params struct {
                UserID         string `json:"user_id"`
                FeedbackType   string `json:"feedback_type"`
                FeedbackDetail string `json:"feedback_detail"`
            }
            json.Unmarshal([]byte(input), &params)

            feedback := fmt.Sprintf("[%s] %s: %s", 
                time.Now().Format("2006-01-02 15:04"), 
                params.FeedbackType, 
                params.FeedbackDetail)

            feedbackStore[params.UserID] = append(feedbackStore[params.UserID], feedback)

            return `{"status": "反馈已保存，感谢您的意见！"}`, nil
        },
    )
}

package main

import (
    "context"
    "os"

    "github.com/cloudwego/eino-ext/components/model/openai"
)

func NewChatModel() (*openai.ChatModel, error) {
    return openai.NewChatModel(context.Background(), &openai.ChatModelConfig{
        Model:   "gpt-4-turbo",
        APIKey:  os.Getenv("OPENAI_API_KEY"),
        BaseURL: "https://api.openai.com/v1", // 或者用 OpenRouter
    })
}

package main

import (
    "context"
    "fmt"

    "github.com/cloudwego/eino/components/tool"
    "github.com/cloudwego/eino/flow/agent/react"
    "github.com/cloudwego/eino/schema"
)

// 系统提示词——这是穿衣助手的"灵魂"
const SystemPrompt = `你是一个专业的智能穿衣助手，帮助用户根据天气、个人情况和衣柜中的衣物，推荐今天的穿搭。

## 工作流程

1. **了解用户**：首先使用 get_user_profile 获取用户的基本信息（年龄、性别、身体状况、穿衣偏好）
2. **查看天气**：使用 get_weather 获取用户所在城市的天气
3. **查看衣柜**：使用 get_wardrobe 查看用户有哪些衣物可选
4. **综合推荐**：根据以上信息，给出穿搭建议

## 推荐原则

- **健康优先**：如果用户有健康问题（如怕冷、关节炎），要特别注意保暖
- **场合适配**：根据用户今天的安排（如果用户提到了）选择合适的风格
- **个性尊重**：尽量符合用户的风格和颜色偏好
- **天气适应**：
  - 温度 < 10°C：需要外套，注意保暖
  - 温度 10-20°C：可穿轻薄外套或厚衬衫
  - 温度 > 20°C：轻便穿着
  - 下雨：建议防水外套或带伞
  - 大风：避免裙装或宽松衣物

## 输出格式

推荐时请包含：
1. 具体的衣物搭配（从用户衣柜中选择）
2. 为什么这样搭配的理由
3. 穿搭小贴士

## 反馈处理

如果用户对推荐不满意，请：
1. 使用 save_feedback 保存用户反馈
2. 根据反馈调整推荐（如：太冷就加衣服，风格不对就换一套）
3. 给出新的推荐
`

func main() {
    ctx := context.Background()

    // 1. 初始化数据存储（实际项目中这些会是数据库）
    profileStore := initUserProfiles()
    wardrobeStore := initWardrobes()
    feedbackStore := make(map[string][]string)

    // 2. 创建 ChatModel
    chatModel, err := NewChatModel()
    if err != nil {
        panic(err)
    }

    // 3. 创建所有工具
    tools := []tool.BaseTool{
        NewWeatherTool(),
        NewUserProfileTool(profileStore),
        NewWardrobeTool(wardrobeStore),
        NewFeedbackTool(feedbackStore),
    }

    // 4. 创建穿衣助手 Agent
    agent, err := react.NewAgent(ctx, &react.AgentConfig{
        Model:         chatModel,
        Tools:         tools,
        SystemPrompt:  SystemPrompt,
        MaxIterations: 15, // 允许多轮工具调用
    })
    if err != nil {
        panic(err)
    }

    // 5. 开始对话
    userID := "user_001"

    // 第一轮：请求推荐
    input := []*schema.Message{
        schema.UserMessage(fmt.Sprintf(
            "我是用户 %s，今天要去参加一个商务会议，帮我看看穿什么合适？",
            userID,
        )),
    }

    output, err := agent.Run(ctx, input)
    if err != nil {
        panic(err)
    }
    fmt.Println("🤖 穿衣助手:", output.Content)

    // 第二轮：用户反馈
    input = append(input, 
        schema.AssistantMessage(output.Content),
        schema.UserMessage("感觉你推荐的外套有点太正式了，我想要休闲一点的"),
    )

    output, err = agent.Run(ctx, input)
    if err != nil {
        panic(err)
    }
    fmt.Println("🤖 穿衣助手:", output.Content)
}

// 初始化用户档案（模拟数据）
func initUserProfiles() map[string]*UserProfile {
    return map[string]*UserProfile{
        "user_001": {
            UserID:      "user_001",
            Name:        "张三",
            Age:         35,
            Gender:      "male",
            City:        "北京",
            BodyType:    "medium",
            HealthNotes: "轻微怕冷，膝盖有时不舒服",
            StylePrefs:  []string{"casual", "business_casual"},
            ColorPrefs:  []string{"藏青色", "灰色", "白色"},
        },
    }
}

// 初始化衣柜（模拟数据）
func initWardrobes() map[string][]*ClothingItem {
    return map[string][]*ClothingItem{
        "user_001": {
            // 上衣
            {ID: "t001", Type: "top", Name: "白色牛津纺衬衫", Color: "白色", Style: "business_casual", WarmthLevel: 2},
            {ID: "t002", Type: "top", Name: "藏青色羊毛衫", Color: "藏青色", Style: "casual", WarmthLevel: 4},
            {ID: "t003", Type: "top", Name: "灰色圆领T恤", Color: "灰色", Style: "casual", WarmthLevel: 1},
            {ID: "t004", Type: "top", Name: "条纹POLO衫", Color: "蓝白条纹", Style: "business_casual", WarmthLevel: 2},
            // 下装
            {ID: "b001", Type: "bottom", Name: "深灰色西裤", Color: "深灰色", Style: "formal", WarmthLevel: 3},
            {ID: "b002", Type: "bottom", Name: "卡其色休闲裤", Color: "卡其色", Style: "casual", WarmthLevel: 3},
            {ID: "b003", Type: "bottom", Name: "深蓝色牛仔裤", Color: "深蓝色", Style: "casual", WarmthLevel: 3},
            // 外套
            {ID: "o001", Type: "outerwear", Name: "藏青色羊毛大衣", Color: "藏青色", Style: "formal", WarmthLevel: 5},
            {ID: "o002", Type: "outerwear", Name: "灰色针织开衫", Color: "灰色", Style: "casual", WarmthLevel: 3},
            {ID: "o003", Type: "outerwear", Name: "黑色皮夹克", Color: "黑色", Style: "casual", WarmthLevel: 4},
            {ID: "o004", Type: "outerwear", Name: "卡其色风衣", Color: "卡其色", Style: "business_casual", WarmthLevel: 4},
            // 鞋子
            {ID: "s001", Type: "shoes", Name: "黑色皮鞋", Color: "黑色", Style: "formal", WarmthLevel: 2},
            {ID: "s002", Type: "shoes", Name: "棕色乐福鞋", Color: "棕色", Style: "business_casual", WarmthLevel: 2},
            {ID: "s003", Type: "shoes", Name: "白色运动鞋", Color: "白色", Style: "casual", WarmthLevel: 2},
        },
    }
}

// 流式运行
stream, err := agent.Stream(ctx, input)
if err != nil {
    panic(err)
}

fmt.Print("🤖 穿衣助手: ")
for {
    chunk, err := stream.Recv()
    if err == io.EOF {
        break
    }
    if err != nil {
        panic(err)
    }
    fmt.Print(chunk.Content) // 实时打印，有"正在思考"的感觉
}
fmt.Println()

                ┌─→ 查询用户档案 ─┐
用户输入 → 解析 → │                │ → 综合推理 → 生成推荐
                ├─→ 查询天气 ────┤
                └─→ 查询衣柜 ────┘

package main

import (
    "context"

    "github.com/cloudwego/eino/compose"
    "github.com/cloudwego/eino/schema"
)

// 穿衣推荐的中间状态
type OutfitContext struct {
    UserID   string          `json:"user_id"`
    Profile  *UserProfile    `json:"profile"`
    Weather  *WeatherInfo    `json:"weather"`
    Wardrobe []*ClothingItem `json:"wardrobe"`
}

func BuildOutfitGraph(ctx context.Context) (*compose.CompiledGraph, error) {
    // 创建 Graph
    graph := compose.NewGraph[*OutfitContext, *OutfitRecommendation]()

    // 添加并行执行的节点
    graph.AddLambdaNode("fetch_profile", fetchProfileFunc)
    graph.AddLambdaNode("fetch_weather", fetchWeatherFunc)
    graph.AddLambdaNode("fetch_wardrobe", fetchWardrobeFunc)

    // 添加聚合节点（等待所有并行节点完成）
    graph.AddLambdaNode("aggregate", aggregateFunc)

    // 添加推理节点
    graph.AddChatModelNode("recommend", recommendModel)

    // 定义边（数据流向）——三个查询并行执行
    graph.AddEdge(compose.START, "fetch_profile")
    graph.AddEdge(compose.START, "fetch_weather")
    graph.AddEdge(compose.START, "fetch_wardrobe")

    // 三个查询都完成后，汇聚到 aggregate
    graph.AddEdge("fetch_profile", "aggregate")
    graph.AddEdge("fetch_weather", "aggregate")
    graph.AddEdge("fetch_wardrobe", "aggregate")

    // 聚合后生成推荐
    graph.AddEdge("aggregate", "recommend")
    graph.AddEdge("recommend", compose.END)

    // 编译 Graph
    return graph.Compile(ctx)
}

func main() {
    ctx := context.Background()

    compiledGraph, err := BuildOutfitGraph(ctx)
    if err != nil {
        panic(err)
    }

    // 运行
    input := &OutfitContext{UserID: "user_001"}
    recommendation, err := compiledGraph.Invoke(ctx, input)
    if err != nil {
        panic(err)
    }

    fmt.Printf("推荐穿搭：%s + %s + %s\n", 
        recommendation.Top.Name,
        recommendation.Bottom.Name,
        recommendation.Outerwear.Name,
    )
    fmt.Printf("理由：%s\n", recommendation.Reason)
}

// 添加条件分支——根据天气分流
graph.AddBranch("weather_router", func(ctx context.Context, input *OutfitContext) string {
    if input.Weather.Temperature < 5 {
        return "cold_strategy"    // 寒冷天气策略：保暖优先
    } else if input.Weather.Temperature > 28 {
        return "hot_strategy"     // 炎热天气策略：透气优先
    } else if input.Weather.Condition == "雨" {
        return "rainy_strategy"   // 雨天策略：防水优先
    }
    return "normal_strategy"      // 普通天气策略
})

graph.AddEdge("weather_router", "cold_strategy")
graph.AddEdge("weather_router", "hot_strategy")
graph.AddEdge("weather_router", "rainy_strategy")
graph.AddEdge("weather_router", "normal_strategy")

// 创建回调处理器
handler := callbacks.NewHandlerBuilder().
    OnStartFn(func(ctx context.Context, info *callbacks.RunInfo, input callbacks.CallbackInput) context.Context {
        log.Printf("👀 [%s] 开始执行", info.Name)
        if info.Name == "fetch_weather" {
            log.Printf("   正在查询天气...")
        } else if info.Name == "recommend" {
            log.Printf("   正在生成穿搭推荐...")
        }
        return ctx
    }).
    OnEndFn(func(ctx context.Context, info *callbacks.RunInfo, output callbacks.CallbackOutput) context.Context {
        log.Printf("✅ [%s] 执行完成", info.Name)
        if info.Name == "fetch_weather" {
            if weather, ok := output.(*WeatherInfo); ok {
                log.Printf("   天气：%s，温度：%d°C", weather.Condition, weather.Temperature)
            }
        }
        return ctx
    }).
    OnErrorFn(func(ctx context.Context, info *callbacks.RunInfo, err error) context.Context {
        log.Printf("❌ [%s] 执行出错: %v", info.Name, err)
        return ctx
    }).
    Build()

// 运行时传入回调
recommendation, err := compiledGraph.Invoke(ctx, input, compose.WithCallbacks(handler))

👀 [fetch_profile] 开始执行
👀 [fetch_weather] 开始执行
   正在查询天气...
👀 [fetch_wardrobe] 开始执行
✅ [fetch_profile] 执行完成
✅ [fetch_weather] 执行完成
   天气：多云，温度：8°C
✅ [fetch_wardrobe] 执行完成
👀 [aggregate] 开始执行
✅ [aggregate] 执行完成
👀 [recommend] 开始执行
   正在生成穿搭推荐...
✅ [recommend] 执行完成

// 错误写法：忘记处理 EOF
for {
    chunk, err := stream.Recv()
    if err != nil {
        panic(err) // EOF 也会触发 panic！
    }
    fmt.Print(chunk.Content)
}

// 正确写法
for {
    chunk, err := stream.Recv()
    if err == io.EOF {
        break // 正常结束
    }
    if err != nil {
        panic(err) // 真正的错误
    }
    fmt.Print(chunk.Content)
}

// 错误：缺少 description，LLM 不知道参数的含义
"properties": map[string]interface{}{
    "user_id": map[string]interface{}{
        "type": "string",
    },
    "clothing_type": map[string]interface{}{
        "type": "string",
    },
}

// 正确：有清晰的 description 和示例
"properties": map[string]interface{}{
    "user_id": map[string]interface{}{
        "type":        "string",
        "description": "用户ID，如：user_001",
    },
    "clothing_type": map[string]interface{}{
        "type":        "string",
        "description": "衣物类型，可选值：top（上衣）、bottom（下装）、outerwear（外套）、shoes（鞋子）、accessory（配饰）",
    },
}

// 错误：每次调用都重新查询，效率低且可能不一致
func recommendOutfit(ctx context.Context, userID string) (*OutfitRecommendation, error) {
    profile := fetchProfile(userID)  // 第一次查询
    weather := fetchWeather(profile.City)
    wardrobe := fetchWardrobe(userID) // 如果用户在这之间更新了档案怎么办？
    // ...
}

// 正确：用 Graph 编排确保状态一致
func BuildOutfitGraph() {
    // Graph 会在同一个 context 中管理所有状态
    // 并行查询时会共享同一个时间点的快照
}

// 单次工具调用可能需要 5-10 秒
// 穿衣助手可能调用 4-5 次工具
// 设置 60 秒的总超时比较合理
ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
defer cancel()

output, err := agent.Run(ctx, input)

output, err := agent.Run(ctx, input)
if err != nil {
    // 区分不同类型的错误
    if errors.Is(err, context.DeadlineExceeded) {
        log.Println("⏰ 请求超时，可能是天气 API 响应慢")
    } else if errors.Is(err, context.Canceled) {
        log.Println("🚫 用户取消了请求")
    } else if strings.Contains(err.Error(), "rate limit") {
        log.Println("🔥 API 限流，请稍后重试")
    } else {
        log.Printf("❌ 未知错误: %v", err)
    }
    // 降级策略：返回一个通用推荐
    return defaultRecommendation, nil
}

// 场景：用户说"想穿休闲一点"，但又说"今天有重要会议"
// 这两个需求可能冲突

// 在 SystemPrompt 中明确优先级
const SystemPrompt = `
...
## 冲突处理原则
当用户需求存在冲突时，按以下优先级处理：
1. 健康/舒适优先（怕冷就要保暖，膝盖不好就别穿裙子）
2. 场合需求（正式场合不能穿拖鞋）
3. 用户明确要求（用户最新说的话权重最高）
4. 历史偏好（作为兜底参考）
...
`

┌─────────────────────────────────────────────────────────────┐
│                     智能穿衣助手 Agent                        │
├─────────────────────────────────────────────────────────────┤
│  SystemPrompt: 穿搭原则、推荐流程、反馈处理                      │
├─────────────────────────────────────────────────────────────┤
│  Tools:                                                      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │ 天气查询  │ │ 用户档案  │ │ 衣柜查询  │ │ 反馈保存  │        │
│  │ Tool     │ │ Tool     │ │ Tool     │ │ Tool     │        │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │
├─────────────────────────────────────────────────────────────┤
│  ChatModel: GPT-4 / Claude / 本地模型                         │
├─────────────────────────────────────────────────────────────┤
│  Callbacks: 日志、追踪、监控                                   │
└─────────────────────────────────────────────────────────────┘