第十三章：Plugin 与 Tool 系统设计深度对比

// 框架定义的工具接口（简化版）
type Tool interface {
    Name() string                    // 工具名称
    Description() string             // 功能描述
    Schema() *jsonschema.Schema      // 参数 JSON Schema
    Execute(ctx context.Context, params json.RawMessage) (string, error)  // 执行逻辑
}

package tools

import (
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
    "time"

    "github.com/invopop/jsonschema"
)

// SearchTool 实现了 Tool 接口的完整搜索工具
type SearchTool struct {
    client  *http.Client
    apiKey  string
    baseURL string
}

// SearchParams 定义输入参数结构
type SearchParams struct {
    Query      string `json:"query" jsonschema:"description=搜索关键词,minLength=1,maxLength=200"`
    MaxResults int    `json:"max_results,omitempty" jsonschema:"description=最大结果数,minimum=1,maximum=50,default=10"`
    Language   string `json:"language,omitempty" jsonschema:"description=搜索语言,enum=zh,enum=en"`
}

// SearchResult 定义输出结构
type SearchResult struct {
    Title   string `json:"title"`
    URL     string `json:"url"`
    Snippet string `json:"snippet"`
}

func NewSearchTool(apiKey string) *SearchTool {
    return &SearchTool{
        client:  &http.Client{Timeout: 30 * time.Second},
        apiKey:  apiKey,
        baseURL: "https://api.search.example.com/v1",
    }
}

// Name 返回工具名称——LLM 通过这个名字来调用
func (s *SearchTool) Name() string {
    return "web_search"
}

// Description 返回功能描述——帮助 LLM 判断什么时候该用这个工具
func (s *SearchTool) Description() string {
    return "搜索互联网获取最新信息。当需要查找实时数据、新闻、技术文档或任何LLM训练数据中可能过时的信息时使用。"
}

// Schema 返回参数的 JSON Schema——告诉 LLM 怎么传参数
func (s *SearchTool) Schema() *jsonschema.Schema {
    reflector := &jsonschema.Reflector{}
    return reflector.Reflect(&SearchParams{})
}

// Execute 执行搜索——收到 LLM 生成的参数后真正干活
func (s *SearchTool) Execute(ctx context.Context, params json.RawMessage) (string, error) {
    // 1. 解析参数
    var p SearchParams
    if err := json.Unmarshal(params, &p); err != nil {
        return "", fmt.Errorf("参数解析失败: %w", err)
    }

    // 2. 设置默认值
    if p.MaxResults == 0 {
        p.MaxResults = 10
    }
    if p.Language == "" {
        p.Language = "zh"
    }

    // 3. 构建请求
    reqURL := fmt.Sprintf("%s/search?q=%s&num=%d&lang=%s",
        s.baseURL,
        url.QueryEscape(p.Query),
        p.MaxResults,
        p.Language,
    )

    req, err := http.NewRequestWithContext(ctx, "GET", reqURL, nil)
    if err != nil {
        return "", fmt.Errorf("构建请求失败: %w", err)
    }
    req.Header.Set("Authorization", "Bearer "+s.apiKey)

    // 4. 发送请求
    resp, err := s.client.Do(req)
    if err != nil {
        return "", fmt.Errorf("搜索请求失败: %w", err)
    }
    defer resp.Body.Close()

    // 5. 解析响应
    var results []SearchResult
    if err := json.NewDecoder(resp.Body).Decode(&results); err != nil {
        return "", fmt.Errorf("解析搜索结果失败: %w", err)
    }

    // 6. 格式化输出（给 LLM 看的文本）
    output := fmt.Sprintf("搜索 \"%s\" 找到 %d 条结果:\n\n", p.Query, len(results))
    for i, r := range results {
        output += fmt.Sprintf("%d. %s\n   链接: %s\n   摘要: %s\n\n", i+1, r.Title, r.URL, r.Snippet)
    }

    return output, nil
}

agent := agentframework.NewAgent(
    agentframework.WithLLM(llmClient),
    agentframework.WithTools(
        tools.NewSearchTool(os.Getenv("SEARCH_API_KEY")),
        tools.NewFileReadTool(),
        tools.NewCodeExecuteTool(),
    ),
    agentframework.WithSystemPrompt("你是一个研究助手..."),
)

package main

import (
    "context"
    "fmt"
    "os/exec"

    agentframework "trpc.group/trpc-go/trpc-agent/agent"
    "trpc.group/trpc-go/trpc-agent/mcp"
)

func main() {
    // 创建 MCP Client，连接到天气工具 Server
    mcpClient, err := mcp.NewStdioClient(mcp.StdioConfig{
        Command: "npx",
        Args:    []string{"ts-node", "weather-server.ts"},
        Env:     []string{"WEATHER_API_KEY=xxx"},
    })
    if err != nil {
        panic(fmt.Sprintf("连接 MCP Server 失败: %v", err))
    }
    defer mcpClient.Close()

    // 获取 MCP Server 提供的工具列表
    mcpTools, err := mcpClient.ListTools(context.Background())
    if err != nil {
        panic(fmt.Sprintf("获取工具列表失败: %v", err))
    }

    // mcpTools 自动适配了 tRPC-Agent 的 Tool 接口
    // 可以和本地工具混合使用
    localTools := []agentframework.Tool{
        NewLocalCalculatorTool(),
    }

    allTools := append(localTools, mcpTools...)

    // 创建 Agent
    agent := agentframework.NewAgent(
        agentframework.WithTools(allTools...),
        agentframework.WithSystemPrompt("你是一个旅行助手，能查天气和搜索城市"),
    )

    // 运行
    result, err := agent.Run(context.Background(), "北京和东京下周哪个更适合旅游？比较一下天气。")
    fmt.Println(result)
}

// Plugin 接口定义（简化版）
type Plugin interface {
    Name() string  // Plugin 唯一标识
}

// 以下是可选实现的钩子接口（按需实现）
type BeforeAgentRunHook interface {
    BeforeAgentRun(ctx context.Context, input string) (string, error)
}

type AfterAgentRunHook interface {
    AfterAgentRun(ctx context.Context, input string, output string, err error) error
}

type BeforeToolCallHook interface {
    BeforeToolCall(ctx context.Context, toolName string, params json.RawMessage) (json.RawMessage, error)
}

type AfterToolCallHook interface {
    AfterToolCall(ctx context.Context, toolName string, params json.RawMessage, result string, err error) error
}

type BeforeLLMCallHook interface {
    BeforeLLMCall(ctx context.Context, messages []Message) ([]Message, error)
}

type AfterLLMCallHook interface {
    AfterLLMCall(ctx context.Context, messages []Message, response *LLMResponse, err error) error
}

type OnErrorHook interface {
    OnError(ctx context.Context, phase string, err error) error
}

package plugins

import (
    "context"
    "encoding/json"
    "fmt"
    "log/slog"
    "time"
)

// AuditPlugin 记录 Agent 运行过程的完整审计日志
type AuditPlugin struct {
    logger *slog.Logger
}

func NewAuditPlugin(logger *slog.Logger) *AuditPlugin {
    return &AuditPlugin{logger: logger}
}

func (p *AuditPlugin) Name() string { return "audit_logger" }

// BeforeAgentRun - Agent 开始运行前
func (p *AuditPlugin) BeforeAgentRun(ctx context.Context, input string) (string, error) {
    p.logger.Info("Agent 运行开始",
        "input_length", len(input),
        "input_preview", truncate(input, 100),
        "timestamp", time.Now().Format(time.RFC3339),
    )
    // 返回原始 input（可以在这里修改 input）
    return input, nil
}

// AfterAgentRun - Agent 运行完成后
func (p *AuditPlugin) AfterAgentRun(ctx context.Context, input, output string, err error) error {
    if err != nil {
        p.logger.Error("Agent 运行失败",
            "error", err.Error(),
            "input_preview", truncate(input, 100),
        )
    } else {
        p.logger.Info("Agent 运行完成",
            "output_length", len(output),
            "output_preview", truncate(output, 200),
        )
    }
    return nil
}

// BeforeToolCall - 工具调用前（可用于权限检查、参数审计）
func (p *AuditPlugin) BeforeToolCall(ctx context.Context, toolName string, params json.RawMessage) (json.RawMessage, error) {
    p.logger.Info("工具调用开始",
        "tool", toolName,
        "params", string(params),
    )

    // 安全检查示例：禁止调用某些危险工具
    blockedTools := map[string]bool{"delete_file": true, "execute_shell": true}
    if blockedTools[toolName] {
        return nil, fmt.Errorf("安全策略禁止调用工具: %s", toolName)
    }

    return params, nil // 返回原始参数（可以在这里修改参数）
}

// AfterToolCall - 工具调用后（可用于结果审计、敏感信息脱敏）
func (p *AuditPlugin) AfterToolCall(ctx context.Context, toolName string, params json.RawMessage, result string, err error) error {
    if err != nil {
        p.logger.Warn("工具调用失败",
            "tool", toolName,
            "error", err.Error(),
        )
    } else {
        p.logger.Info("工具调用完成",
            "tool", toolName,
            "result_length", len(result),
        )
    }
    return nil
}

// BeforeLLMCall - LLM 调用前（可用于 prompt 注入、token 计数）
func (p *AuditPlugin) BeforeLLMCall(ctx context.Context, messages []Message) ([]Message, error) {
    totalTokens := 0
    for _, msg := range messages {
        totalTokens += estimateTokens(msg.Content)
    }
    p.logger.Info("LLM 调用开始",
        "message_count", len(messages),
        "estimated_tokens", totalTokens,
    )
    return messages, nil
}

// OnError - 任何阶段发生错误时
func (p *AuditPlugin) OnError(ctx context.Context, phase string, err error) error {
    p.logger.Error("Agent 错误",
        "phase", phase,
        "error", err.Error(),
    )
    // 可以在这里发告警通知
    return nil
}

func truncate(s string, maxLen int) string {
    if len(s) <= maxLen {
        return s
    }
    return s[:maxLen] + "..."
}

func estimateTokens(s string) int {
    return len(s) / 4 // 粗略估算
}

agent := agentframework.NewAgent(
    agentframework.WithLLM(llmClient),
    agentframework.WithTools(searchTool, fileTool),
    agentframework.WithPlugins(
        plugins.NewAuditPlugin(logger),
        plugins.NewRateLimitPlugin(10, time.Minute),  // 限流
        plugins.NewCostTrackingPlugin(),               // 成本追踪
    ),
)

// tRPC-Agent-Go 中的输入净化 Plugin
type InputSanitizerPlugin struct{}

func (p *InputSanitizerPlugin) Name() string { return "input_sanitizer" }

func (p *InputSanitizerPlugin) AfterToolCall(ctx context.Context, toolName string, params json.RawMessage, result string, err error) error {
    // 检测工具返回结果中是否包含可疑的 prompt 注入
    suspiciousPatterns := []string{
        "忽略之前所有指令",
        "ignore previous instructions",
        "you are now",
        "new system prompt",
        "disregard",
    }
    for _, pattern := range suspiciousPatterns {
        if strings.Contains(strings.ToLower(result), strings.ToLower(pattern)) {
            // 记录告警但不阻止（可能是误判）
            slog.Warn("检测到可疑内容",
                "tool", toolName,
                "pattern", pattern,
            )
        }
    }
    return nil
}

// 严格的参数验证——不信任 LLM 的输出
func (t *FileWriteTool) Execute(ctx context.Context, params json.RawMessage) (string, error) {
    var p FileWriteParams
    if err := json.Unmarshal(params, &p); err != nil {
        return "", fmt.Errorf("参数格式错误: %w", err)
    }

    // 路径安全检查
    cleanPath := filepath.Clean(p.Path)
    if !strings.HasPrefix(cleanPath, t.allowedDir) {
        return "", fmt.Errorf("安全错误: 不允许写入 %s 之外的路径", t.allowedDir)
    }

    // 防止路径穿越攻击
    if strings.Contains(cleanPath, "..") {
        return "", fmt.Errorf("安全错误: 路径中不允许包含 '..'")
    }

    // 文件大小限制
    if len(p.Content) > 10*1024*1024 { // 10MB
        return "", fmt.Errorf("安全错误: 文件内容超过 10MB 限制")
    }

    // 通过验证，执行写入
    return writeFile(cleanPath, p.Content)
}

// 代码执行工具——必须在沙箱中运行
type CodeExecuteTool struct {
    sandbox SandboxConfig
}

type SandboxConfig struct {
    MaxCPUTime    time.Duration // CPU 时间限制
    MaxMemory     int64         // 内存限制（字节）
    MaxOutputSize int64         // 输出大小限制
    NetworkAccess bool          // 是否允许网络
    FileAccess    []string      // 允许访问的文件路径
}

func (t *CodeExecuteTool) Execute(ctx context.Context, params json.RawMessage) (string, error) {
    var p struct {
        Code     string `json:"code"`
        Language string `json:"language"`
    }
    json.Unmarshal(params, &p)

    // 在 Docker 容器或 gVisor 沙箱中执行
    result, err := t.runInSandbox(ctx, p.Code, p.Language, SandboxConfig{
        MaxCPUTime:    30 * time.Second,
        MaxMemory:     256 * 1024 * 1024, // 256MB
        MaxOutputSize: 1024 * 1024,        // 1MB output
        NetworkAccess: false,              // 禁止网络
        FileAccess:    []string{"/tmp/sandbox/"}, // 只能访问沙箱目录
    })

    if err != nil {
        return fmt.Sprintf("代码执行失败: %v", err), nil // 返回错误信息而非 error
    }
    return result, nil
}

// 基于角色的工具权限控制
type PermissionPlugin struct {
    policies map[string][]string // role -> allowed tools
}

func NewPermissionPlugin() *PermissionPlugin {
    return &PermissionPlugin{
        policies: map[string][]string{
            "reader":    {"web_search", "read_file"},
            "writer":    {"web_search", "read_file", "write_file"},
            "admin":     {"web_search", "read_file", "write_file", "execute_code", "send_email"},
        },
    }
}

func (p *PermissionPlugin) BeforeToolCall(ctx context.Context, toolName string, params json.RawMessage) (json.RawMessage, error) {
    role := getRoleFromContext(ctx) // 从 context 获取用户角色

    allowedTools, ok := p.policies[role]
    if !ok {
        return nil, fmt.Errorf("未知角色: %s", role)
    }

    for _, allowed := range allowedTools {
        if allowed == toolName {
            return params, nil // 允许
        }
    }

    return nil, fmt.Errorf("权限不足: 角色 %s 不允许使用工具 %s", role, toolName)
}

// 超时控制 Plugin
type TimeoutPlugin struct {
    toolTimeouts map[string]time.Duration
    defaultTimeout time.Duration
}

func (p *TimeoutPlugin) BeforeToolCall(ctx context.Context, toolName string, params json.RawMessage) (json.RawMessage, error) {
    timeout := p.defaultTimeout
    if t, ok := p.toolTimeouts[toolName]; ok {
        timeout = t
    }

    // 给 context 加上超时
    ctx, cancel := context.WithTimeout(ctx, timeout)
    // cancel 需要在 AfterToolCall 中调用（实际实现更复杂）
    _ = cancel

    return params, nil
}

// 限流 Plugin
type RateLimitPlugin struct {
    limiter *rate.Limiter
    toolLimiters map[string]*rate.Limiter
}

func (p *RateLimitPlugin) BeforeToolCall(ctx context.Context, toolName string, params json.RawMessage) (json.RawMessage, error) {
    limiter := p.limiter
    if tl, ok := p.toolLimiters[toolName]; ok {
        limiter = tl
    }

    if !limiter.Allow() {
        return nil, fmt.Errorf("限流: 工具 %s 调用频率超过限制", toolName)
    }
    return params, nil
}

// Agent 框架内部的并行工具执行逻辑
func (a *Agent) executeToolCalls(ctx context.Context, calls []ToolCall) []ToolResult {
    results := make([]ToolResult, len(calls))
    var wg sync.WaitGroup

    for i, call := range calls {
        wg.Add(1)
        go func(idx int, tc ToolCall) {
            defer wg.Done()

            // 找到对应的 Tool
            tool, ok := a.toolMap[tc.Name]
            if !ok {
                results[idx] = ToolResult{
                    CallID: tc.ID,
                    Error:  fmt.Sprintf("未知工具: %s", tc.Name),
                }
                return
            }

            // 执行 Plugin 的 BeforeToolCall
            params, err := a.runBeforeToolCallPlugins(ctx, tc.Name, tc.Arguments)
            if err != nil {
                results[idx] = ToolResult{CallID: tc.ID, Error: err.Error()}
                return
            }

            // 执行工具（带超时）
            toolCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
            defer cancel()

            output, err := tool.Execute(toolCtx, params)

            // 执行 Plugin 的 AfterToolCall
            a.runAfterToolCallPlugins(ctx, tc.Name, params, output, err)

            if err != nil {
                results[idx] = ToolResult{CallID: tc.ID, Error: err.Error()}
            } else {
                results[idx] = ToolResult{CallID: tc.ID, Output: output}
            }
        }(i, call)
    }

    wg.Wait()
    return results
}

// 工具链定义：搜索 → 提取正文 → 摘要
type ToolChain struct {
    steps []ChainStep
}

type ChainStep struct {
    Tool       Tool
    ParamMapper func(prevResult string) json.RawMessage  // 从上一步结果映射参数
}

func NewResearchChain() *ToolChain {
    return &ToolChain{
        steps: []ChainStep{
            {
                Tool: NewSearchTool(),
                ParamMapper: func(_ string) json.RawMessage {
                    return json.RawMessage(`{"query": "AI Agent frameworks 2024", "max_results": 3}`)
                },
            },
            {
                Tool: NewWebScrapeTool(),
                ParamMapper: func(searchResult string) json.RawMessage {
                    // 从搜索结果中提取第一个 URL
                    url := extractFirstURL(searchResult)
                    return json.RawMessage(fmt.Sprintf(`{"url": "%s"}`, url))
                },
            },
            {
                Tool: NewSummarizeTool(),
                ParamMapper: func(pageContent string) json.RawMessage {
                    return json.RawMessage(fmt.Sprintf(`{"text": %q, "max_length": 500}`,
                        truncate(pageContent, 5000)))
                },
            },
        },
    }
}

func (tc *ToolChain) Execute(ctx context.Context) (string, error) {
    var prevResult string
    for i, step := range tc.steps {
        params := step.ParamMapper(prevResult)
        result, err := step.Tool.Execute(ctx, params)
        if err != nil {
            return "", fmt.Errorf("链式执行第 %d 步失败: %w", i+1, err)
        }
        prevResult = result
    }
    return prevResult, nil
}

// 支持动态注册的 Agent
type DynamicAgent struct {
    mu    sync.RWMutex
    tools map[string]Tool
    // ...其他字段
}

func (a *DynamicAgent) RegisterTool(tool Tool) {
    a.mu.Lock()
    defer a.mu.Unlock()
    a.tools[tool.Name()] = tool
    // 同时需要更新 LLM 的可用工具列表
    a.refreshToolListForLLM()
}

func (a *DynamicAgent) UnregisterTool(name string) {
    a.mu.Lock()
    defer a.mu.Unlock()
    delete(a.tools, name)
    a.refreshToolListForLLM()
}

// 一个"工具发现"工具——Agent 可以用它来加载新工具
type ToolDiscoveryTool struct {
    agent    *DynamicAgent
    registry ToolRegistry  // 可用工具的注册中心
}

func (t *ToolDiscoveryTool) Execute(ctx context.Context, params json.RawMessage) (string, error) {
    var p struct {
        Category string `json:"category"` // 如 "database", "email", "file"
    }
    json.Unmarshal(params, &p)

    // 从注册中心查找该类别的工具
    availableTools := t.registry.FindByCategory(p.Category)

    // 动态加载
    for _, tool := range availableTools {
        t.agent.RegisterTool(tool)
    }

    names := make([]string, len(availableTools))
    for i, tool := range availableTools {
        names[i] = tool.Name()
    }
    return fmt.Sprintf("已加载 %d 个 %s 类工具: %v", len(availableTools), p.Category, names), nil
}

// 将工具按类别分组，第一轮只展示组名，选定组后再展示具体工具
type ToolGroup struct {
    Name        string
    Description string
    Tools       []Tool
}

var toolGroups = []ToolGroup{
    {
        Name:        "search",
        Description: "搜索相关工具（网页搜索、学术论文搜索、新闻搜索）",
        Tools:       []Tool{webSearch, paperSearch, newsSearch},
    },
    {
        Name:        "file",
        Description: "文件操作工具（读写文件、列目录、创建文件夹）",
        Tools:       []Tool{readFile, writeFile, listDir, mkdir},
    },
    {
        Name:        "code",
        Description: "代码相关工具（执行Python、执行Shell、格式化代码）",
        Tools:       []Tool{pythonExec, shellExec, formatCode},
    },
}

// 三级结果压缩策略
type ResultProcessor struct {
    maxLength     int    // 阈值1：超过这个长度就截断
    summarizeAt   int    // 阈值2：超过这个长度就用 LLM 摘要
    referenceAt   int    // 阈值3：超过这个长度就只给引用
}

func NewResultProcessor() *ResultProcessor {
    return &ResultProcessor{
        maxLength:   4000,   // 4K 字符以内：直接使用
        summarizeAt: 10000,  // 4K-10K：截断 + 提示有省略
        referenceAt: 50000,  // 10K-50K：LLM 摘要
        // >50K：只给引用（存到文件，给 Agent 文件路径）
    }
}

func (rp *ResultProcessor) Process(ctx context.Context, toolName string, result string) string {
    length := len(result)

    // 短结果：直接返回
    if length <= rp.maxLength {
        return result
    }

    // 中等长度：智能截断
    if length <= rp.summarizeAt {
        return result[:rp.maxLength] +
            fmt.Sprintf("\n\n[结果已截断，原始长度 %d 字符，显示前 %d 字符]", length, rp.maxLength)
    }

    // 较长：用 LLM 做摘要
    if length <= rp.referenceAt {
        summary := rp.summarizeWithLLM(ctx, result)
        return fmt.Sprintf("[以下是 %d 字符原始结果的摘要]\n\n%s\n\n[如需查看完整内容，请使用 read_file 工具读取临时文件]",
            length, summary)
    }

    // 超长：存文件，只返回引用
    tmpFile := rp.saveToTempFile(result)
    return fmt.Sprintf("[结果过长（%d 字符），已保存到临时文件: %s]\n"+
        "可使用 read_file 工具分段读取。\n"+
        "前 500 字符预览:\n%s", length, tmpFile, result[:500])
}

// 工具调用失败后的自动重试机制
func (a *Agent) executeWithRetry(ctx context.Context, call ToolCall, maxRetries int) ToolResult {
    var lastError string

    for attempt := 0; attempt <= maxRetries; attempt++ {
        // 执行工具
        result, err := a.executeTool(ctx, call)
        if err == nil {
            return result
        }

        lastError = err.Error()

        if attempt < maxRetries {
            // 构造反馈消息，让 LLM 修正参数
            feedbackMsg := Message{
                Role: "tool",
                Content: fmt.Sprintf(
                    "工具 %s 调用失败（第 %d 次尝试）。错误: %s\n"+
                    "请检查参数格式是否正确，并重新调用。",
                    call.Name, attempt+1, lastError,
                ),
                ToolCallID: call.ID,
            }

            // 把反馈消息发给 LLM，让它重新生成 tool_call
            newResponse := a.llm.Chat(ctx, append(a.messages, feedbackMsg))
            if len(newResponse.ToolCalls) > 0 {
                call = newResponse.ToolCalls[0] // 用 LLM 修正后的参数重试
            }
        }
    }

    return ToolResult{
        CallID: call.ID,
        Error:  fmt.Sprintf("工具调用失败（已重试 %d 次）: %s", maxRetries, lastError),
    }
}

// 带超时和降级的工具执行
type ResilientToolExecutor struct {
    timeout  time.Duration
    fallback func(toolName string, params json.RawMessage) (string, error)
}

func (e *ResilientToolExecutor) Execute(ctx context.Context, tool Tool, params json.RawMessage) (string, error) {
    // 创建带超时的 context
    timeoutCtx, cancel := context.WithTimeout(ctx, e.timeout)
    defer cancel()

    // 用 channel 接收结果
    type result struct {
        output string
        err    error
    }
    ch := make(chan result, 1)

    go func() {
        output, err := tool.Execute(timeoutCtx, params)
        ch <- result{output, err}
    }()

    select {
    case r := <-ch:
        return r.output, r.err

    case <-timeoutCtx.Done():
        // 超时了，尝试 fallback
        if e.fallback != nil {
            fallbackResult, fallbackErr := e.fallback(tool.Name(), params)
            if fallbackErr == nil {
                return fallbackResult, nil
            }
        }
        return "", fmt.Errorf("工具 %s 执行超时（%v），且降级方案也失败", tool.Name(), e.timeout)
    }
}

// 使用示例
executor := &ResilientToolExecutor{
    timeout: 30 * time.Second,
    fallback: func(toolName string, params json.RawMessage) (string, error) {
        // 降级策略：对搜索工具，返回缓存的旧结果
        if toolName == "web_search" {
            cached := cache.Get(string(params))
            if cached != "" {
                return "[缓存结果] " + cached, nil
            }
        }
        return "", fmt.Errorf("无可用降级方案")
    },
}

package research

import (
    "context"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "os"
    "os/exec"
    "path/filepath"
    "strings"
    "time"

    "trpc.group/trpc-go/trpc-agent/agent"
)

// ========== Tool 1: 智能搜索 ==========

type SmartSearchTool struct {
    searchAPIKey string
}

type SmartSearchParams struct {
    Query    string `json:"query" jsonschema:"description=搜索查询"`
    Type     string `json:"type,omitempty" jsonschema:"description=搜索类型,enum=web,enum=academic,enum=news"`
    Depth    string `json:"depth,omitempty" jsonschema:"description=搜索深度,enum=quick,enum=thorough"`
}

func (t *SmartSearchTool) Name() string { return "smart_search" }

func (t *SmartSearchTool) Description() string {
    return "智能搜索工具。支持网页搜索(web)、学术论文搜索(academic)、新闻搜索(news)三种模式。" +
        "quick模式快速返回前5条结果，thorough模式返回前20条并包含摘要。"
}

func (t *SmartSearchTool) Schema() interface{} {
    return generateSchema(&SmartSearchParams{})
}

func (t *SmartSearchTool) Execute(ctx context.Context, params json.RawMessage) (string, error) {
    var p SmartSearchParams
    if err := json.Unmarshal(params, &p); err != nil {
        return "", err
    }
    if p.Type == "" {
        p.Type = "web"
    }
    if p.Depth == "" {
        p.Depth = "quick"
    }

    // 根据类型分发到不同搜索后端
    switch p.Type {
    case "academic":
        return t.searchAcademic(ctx, p.Query, p.Depth)
    case "news":
        return t.searchNews(ctx, p.Query, p.Depth)
    default:
        return t.searchWeb(ctx, p.Query, p.Depth)
    }
}

func (t *SmartSearchTool) searchWeb(ctx context.Context, query, depth string) (string, error) {
    limit := 5
    if depth == "thorough" {
        limit = 20
    }
    // 调用搜索 API...
    return fmt.Sprintf("网页搜索 \"%s\" 返回 %d 条结果\n[结果内容...]", query, limit), nil
}

func (t *SmartSearchTool) searchAcademic(ctx context.Context, query, depth string) (string, error) {
    return fmt.Sprintf("学术搜索 \"%s\" 的结果\n[论文列表...]", query), nil
}

func (t *SmartSearchTool) searchNews(ctx context.Context, query, depth string) (string, error) {
    return fmt.Sprintf("新闻搜索 \"%s\" 的结果\n[新闻列表...]", query), nil
}

// ========== Tool 2: 文件操作 ==========

type FileOperationTool struct {
    workDir string
}

type FileOpParams struct {
    Operation string `json:"operation" jsonschema:"description=操作类型,enum=read,enum=write,enum=list,enum=append"`
    Path      string `json:"path" jsonschema:"description=文件路径（相对于工作目录）"`
    Content   string `json:"content,omitempty" jsonschema:"description=写入内容（write/append时必填）"`
}

func (t *FileOperationTool) Name() string { return "file_operation" }

func (t *FileOperationTool) Description() string {
    return "文件操作工具。支持读取(read)、写入(write)、追加(append)文件内容，以及列出(list)目录。" +
        "路径相对于工作目录。适用于保存研究结果、读取参考资料等场景。"
}

func (t *FileOperationTool) Schema() interface{} {
    return generateSchema(&FileOpParams{})
}

func (t *FileOperationTool) Execute(ctx context.Context, params json.RawMessage) (string, error) {
    var p FileOpParams
    if err := json.Unmarshal(params, &p); err != nil {
        return "", err
    }

    // 安全检查：路径不能逃逸出工作目录
    fullPath := filepath.Join(t.workDir, filepath.Clean(p.Path))
    if !strings.HasPrefix(fullPath, t.workDir) {
        return "", fmt.Errorf("安全错误: 路径不能超出工作目录")
    }

    switch p.Operation {
    case "read":
        content, err := ioutil.ReadFile(fullPath)
        if err != nil {
            return "", fmt.Errorf("读取文件失败: %w", err)
        }
        return string(content), nil

    case "write":
        os.MkdirAll(filepath.Dir(fullPath), 0755)
        err := ioutil.WriteFile(fullPath, []byte(p.Content), 0644)
        if err != nil {
            return "", fmt.Errorf("写入文件失败: %w", err)
        }
        return fmt.Sprintf("成功写入 %d 字节到 %s", len(p.Content), p.Path), nil

    case "append":
        f, err := os.OpenFile(fullPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
        if err != nil {
            return "", fmt.Errorf("打开文件失败: %w", err)
        }
        defer f.Close()
        _, err = f.WriteString(p.Content)
        if err != nil {
            return "", fmt.Errorf("追加写入失败: %w", err)
        }
        return fmt.Sprintf("成功追加 %d 字节到 %s", len(p.Content), p.Path), nil

    case "list":
        entries, err := os.ReadDir(fullPath)
        if err != nil {
            return "", fmt.Errorf("列目录失败: %w", err)
        }
        var lines []string
        for _, entry := range entries {
            info, _ := entry.Info()
            typeStr := "文件"
            if entry.IsDir() {
                typeStr = "目录"
            }
            lines = append(lines, fmt.Sprintf("  %s [%s] %d bytes",
                entry.Name(), typeStr, info.Size()))
        }
        return fmt.Sprintf("%s 下有 %d 个条目:\n%s", p.Path, len(entries), strings.Join(lines, "\n")), nil

    default:
        return "", fmt.Errorf("未知操作: %s", p.Operation)
    }
}

// ========== Tool 3: 代码执行 ==========

type CodeExecuteTool struct {
    workDir string
    timeout time.Duration
}

type CodeExecParams struct {
    Language string `json:"language" jsonschema:"description=编程语言,enum=python,enum=shell"`
    Code     string `json:"code" jsonschema:"description=要执行的代码"`
}

func (t *CodeExecuteTool) Name() string { return "execute_code" }

func (t *CodeExecuteTool) Description() string {
    return "代码执行工具。支持执行 Python 和 Shell 代码。" +
        "适用于数据处理、计算、文件批量操作等场景。" +
        "代码在沙箱环境中运行，有超时限制。"
}

func (t *CodeExecuteTool) Schema() interface{} {
    return generateSchema(&CodeExecParams{})
}

func (t *CodeExecuteTool) Execute(ctx context.Context, params json.RawMessage) (string, error) {
    var p CodeExecParams
    if err := json.Unmarshal(params, &p); err != nil {
        return "", err
    }

    timeoutCtx, cancel := context.WithTimeout(ctx, t.timeout)
    defer cancel()

    var cmd *exec.Cmd
    switch p.Language {
    case "python":
        cmd = exec.CommandContext(timeoutCtx, "python3", "-c", p.Code)
    case "shell":
        cmd = exec.CommandContext(timeoutCtx, "sh", "-c", p.Code)
    default:
        return "", fmt.Errorf("不支持的语言: %s", p.Language)
    }

    cmd.Dir = t.workDir
    output, err := cmd.CombinedOutput()

    if err != nil {
        if timeoutCtx.Err() == context.DeadlineExceeded {
            return fmt.Sprintf("执行超时（限制 %v）。部分输出:\n%s", t.timeout, string(output)), nil
        }
        return fmt.Sprintf("执行出错: %v\n输出:\n%s", err, string(output)), nil
    }

    return string(output), nil
}

// ========== Tool 4: 内容摘要 ==========

type SummarizeTool struct {
    llmClient LLMClient
}

type SummarizeParams struct {
    Text      string `json:"text" jsonschema:"description=需要摘要的文本"`
    MaxLength int    `json:"max_length,omitempty" jsonschema:"description=摘要最大字数,default=300"`
    Focus     string `json:"focus,omitempty" jsonschema:"description=摘要关注点（可选，如'技术细节'、'结论'）"`
}

func (t *SummarizeTool) Name() string { return "summarize" }

func (t *SummarizeTool) Description() string {
    return "文本摘要工具。将长文本压缩为简短摘要。" +
        "可指定关注点来引导摘要方向。适用于处理搜索结果、长文档等场景。"
}

func (t *SummarizeTool) Schema() interface{} {
    return generateSchema(&SummarizeParams{})
}

func (t *SummarizeTool) Execute(ctx context.Context, params json.RawMessage) (string, error) {
    var p SummarizeParams
    if err := json.Unmarshal(params, &p); err != nil {
        return "", err
    }
    if p.MaxLength == 0 {
        p.MaxLength = 300
    }

    prompt := fmt.Sprintf("请将以下文本摘要为不超过 %d 字的简短总结", p.MaxLength)
    if p.Focus != "" {
        prompt += fmt.Sprintf("，重点关注: %s", p.Focus)
    }
    prompt += fmt.Sprintf(":\n\n%s", p.Text)

    summary, err := t.llmClient.Complete(ctx, prompt)
    if err != nil {
        return "", fmt.Errorf("生成摘要失败: %w", err)
    }
    return summary, nil
}