M05 Agent 设计模式

package patterns

import (
	"context"

	"github.com/yourname/llmagent/internal/llm"
)

// complete 是一次最朴素的模型调用：给系统提示词和用户输入，返回文本。
// 本章很多模式都建立在它之上。
func complete(ctx context.Context, p llm.Provider, model, system, user string) (string, error) {
	resp, err := p.Chat(ctx, llm.ChatRequest{
		Model: model,
		Messages: []llm.Message{
			{Role: llm.RoleSystem, Content: system},
			{Role: llm.RoleUser, Content: user},
		},
	})
	if err != nil {
		return "", err
	}
	return resp.Content, nil
}

package patterns

import (
	"context"
	"fmt"

	"github.com/yourname/llmagent/internal/llm"
)

type ChainStep struct {
	Name   string                   // 步骤名，用于报错定位
	System string                   // 本步的系统提示词
	Build  func(prev string) string // 用上一步输出构造本步用户输入
	Gate   func(out string) error   // 可选：校验本步输出，返回 err 则中止链
}

// RunChain 顺序执行各步骤，前一步输出作为后一步输入。
func RunChain(ctx context.Context, p llm.Provider, model, input string, steps []ChainStep) (string, error) {
	cur := input
	for _, s := range steps {
		out, err := complete(ctx, p, model, s.System, s.Build(cur))
		if err != nil {
			return "", fmt.Errorf("步骤 %q 调用失败: %w", s.Name, err)
		}
		if s.Gate != nil {
			if err := s.Gate(out); err != nil {
				return "", fmt.Errorf("步骤 %q 校验未通过: %w", s.Name, err)
			}
		}
		cur = out
	}
	return cur, nil
}

package patterns

import (
	"context"
	"fmt"
	"strings"

	"github.com/yourname/llmagent/internal/llm"
)

type Route struct {
	Name        string // 意图名，如 "code_gen"
	Description string // 给分类器看的说明，如 "用户想让你写或修改代码"
	Handle      func(ctx context.Context, input string) (string, error)
}

type IntentRouter struct {
	Provider llm.Provider
	Model    string
	Routes   []Route
	Fallback func(ctx context.Context, input string) (string, error) // 分类失败/无匹配时
}

// routeChoice 是分类器的结构化输出。
type routeChoice struct {
	Route string `json:"route"`
}

func (r *IntentRouter) Dispatch(ctx context.Context, input string) (string, error) {
	name, err := r.classify(ctx, input)
	if err == nil {
		for _, rt := range r.Routes {
			if rt.Name == name {
				return rt.Handle(ctx, input)
			}
		}
	}
	// 分类出错或没匹配上：走兜底（这本身就是一种优雅降级）
	if r.Fallback != nil {
		return r.Fallback(ctx, input)
	}
	return "", fmt.Errorf("无法路由，且未配置兜底（意图=%q, err=%v）", name, err)
}

func (r *IntentRouter) classify(ctx context.Context, input string) (string, error) {
	var b strings.Builder
	for _, rt := range r.Routes {
		fmt.Fprintf(&b, "- %s: %s\n", rt.Name, rt.Description)
	}
	system := "你是意图分类器。从下列类别中选出最匹配用户输入的一个，" +
		"严格只输出 JSON：{\"route\": \"类别名\"}。\n类别：\n" + b.String()

	out, err := complete(ctx, r.Provider, r.Model, system, input)
	if err != nil {
		return "", err
	}
	choice, err := llm.ParseInto[routeChoice](out)
	if err != nil {
		return "", fmt.Errorf("分类输出无法解析: %w", err)
	}
	return choice.Route, nil
}

package patterns

import (
	"context"
	"sync"
)

// Sectioning 并行执行一批互不依赖的任务，按原顺序返回结果；任一失败即整体失败。
func Sectioning(ctx context.Context, tasks []func(context.Context) (string, error)) ([]string, error) {
	results := make([]string, len(tasks))
	var wg sync.WaitGroup
	var firstErr error
	var once sync.Once

	cctx, cancel := context.WithCancel(ctx)
	defer cancel()

	for i, task := range tasks {
		wg.Add(1)
		go func(i int, task func(context.Context) (string, error)) {
			defer wg.Done()
			out, err := task(cctx)
			if err != nil {
				once.Do(func() { firstErr = err; cancel() })
				return
			}
			results[i] = out // 每个 goroutine 只写自己的下标，互不重叠，无需加锁
		}(i, task)
	}

	wg.Wait()
	if firstErr != nil {
		return nil, firstErr
	}
	return results, nil
}

package patterns

import (
	"context"

	"github.com/yourname/llmagent/internal/llm"
)

// Voting 用相同提示词独立跑 n 次，返回 n 个结果，交给上层聚合。
func Voting(ctx context.Context, p llm.Provider, model, system, user string, n int) ([]string, error) {
	tasks := make([]func(context.Context) (string, error), n)
	for i := range tasks {
		tasks[i] = func(ctx context.Context) (string, error) {
			return complete(ctx, p, model, system, user)
		}
	}
	return Sectioning(ctx, tasks)
}

// Majority 返回出现次数最多的结果，适合"是/否"或有限类别的投票。
func Majority(votes []string) string {
	counts := make(map[string]int)
	best, bestN := "", 0
	for _, v := range votes {
		counts[v]++
		if counts[v] > bestN {
			best, bestN = v, counts[v]
		}
	}
	return best
}

package patterns

import "context"

// Evaluation 是评估者的结构化输出。
type Evaluation struct {
	Pass     bool   `json:"pass"`     // 是否达标
	Score    int    `json:"score"`    // 0-100 分
	Feedback string `json:"feedback"` // 不达标时的具体修改意见
}

// Generator 根据上一轮反馈生成内容（首轮 feedback 为空）。
type Generator func(ctx context.Context, feedback string) (string, error)

// Evaluator 评估一份内容，给出是否达标与反馈。
type Evaluator func(ctx context.Context, output string) (Evaluation, error)

// EvaluatorOptimizer 生成→评估→（不达标则带反馈重生成）循环，至多 maxRounds 轮。
// 返回最终内容、最后一次评估、错误。
func EvaluatorOptimizer(ctx context.Context, gen Generator, eval Evaluator, maxRounds int) (string, Evaluation, error) {
	var output string
	var ev Evaluation
	feedback := ""
	for round := 0; round < maxRounds; round++ {
		var err error
		output, err = gen(ctx, feedback)
		if err != nil {
			return "", ev, err
		}
		ev, err = eval(ctx, output)
		if err != nil {
			return "", ev, err
		}
		if ev.Pass {
			return output, ev, nil // 达标，提前返回
		}
		feedback = ev.Feedback // 带着意见进入下一轮
	}
	return output, ev, nil // 用尽轮次：返回最后一版（注意 ev.Pass 可能为 false）
}

// agent 包：补一个公开的非流式入口（包装 M04 的 runFunctionCalling）
func (a *Agent) Run(ctx context.Context, goal string) (string, error) {
	st, err := a.runFunctionCalling(ctx, goal)
	if err != nil {
		return "", err
	}
	return st.Answer, nil
}

package patterns

import (
	"context"
	"fmt"
	"strings"

	"github.com/yourname/llmagent/internal/agent"
	"github.com/yourname/llmagent/internal/llm"
)

type subtask struct {
	ID          string `json:"id"`
	Description string `json:"description"`
}

type decomposition struct {
	Subtasks []subtask `json:"subtasks"`
}

type Orchestrator struct {
	Provider  llm.Provider
	Model     string
	NewWorker func() *agent.Agent // 工厂：每个子任务一个全新 worker，上下文互相隔离
}

func (o *Orchestrator) Run(ctx context.Context, goal string) (string, error) {
	// 1) 分解：让编排者把任务拆成子任务（结构化输出）
	system := "你是任务编排者。把用户任务拆解为若干可独立完成的子任务，" +
		"严格只输出 JSON：{\"subtasks\":[{\"id\":\"t1\",\"description\":\"...\"}]}"
	raw, err := complete(ctx, o.Provider, o.Model, system, goal)
	if err != nil {
		return "", err
	}
	d, err := llm.ParseInto[decomposition](raw)
	if err != nil {
		return "", fmt.Errorf("分解结果无法解析: %w", err)
	}
	if len(d.Subtasks) == 0 {
		return "", fmt.Errorf("编排者未产出任何子任务")
	}

	// 2) 并行执行：每个子任务一个独立 worker（上下文隔离，互不污染）
	tasks := make([]func(context.Context) (string, error), len(d.Subtasks))
	for i, st := range d.Subtasks {
		st := st // 捕获循环变量（Go 1.22+ 已自动，这里显式以兼容旧版）
		tasks[i] = func(ctx context.Context) (string, error) {
			worker := o.NewWorker()
			res, err := worker.Run(ctx, st.Description)
			if err != nil {
				return "", fmt.Errorf("子任务 %s 失败: %w", st.ID, err)
			}
			return fmt.Sprintf("[%s] %s\n%s", st.ID, st.Description, res), nil
		}
	}
	results, err := Sectioning(ctx, tasks)
	if err != nil {
		return "", err
	}

	// 3) 综合：把各 worker 的结果交给编排者整合成最终回答
	synthSystem := "下面是各子任务的执行结果，请综合成对原始任务的完整、连贯的回答。"
	return complete(ctx, o.Provider, o.Model, synthSystem,
		"原始任务：\n"+goal+"\n\n子任务结果：\n"+strings.Join(results, "\n\n"))
}

有一个 LLM 任务要做
        │
        ├─ 单次精心调用 + 好 prompt 够吗？
        │     └─ 够 → 单次调用或单 Agent，不上模式
        │
        ├─ 任务类型多样，需要分流？
        │     └─ 是 → Routing 前置
        │
        ├─ 路径已知，可拆固定几步？
        │     │
        │     ├─ 步骤独立可并行？
        │     │     └─ 是 → Parallelization
        │     │
        │     └─ 步骤有依赖，需要串行？
        │           └─ 是 → Prompt Chaining
        │
        ├─ 一次质量不够，需要反复打磨？
        │     └─ 是 → Evaluator-Optimizer
        │
        ├─ 任务结构未知，运行时才能决定？
        │     └─ 是 → Orchestrator-Workers
        │
        └─ 多 Agent 协作场景明显？
              └─ 是 → 进入 M08 多智能体拓扑

// 1) Planner：决定审查维度
type reviewPlan struct {
	Dimensions []string `json:"dimensions"` // 如 ["并发安全","错误处理",...]
}

func planReview(ctx context.Context, p llm.Provider, model, code string) (reviewPlan, error) {
	system := "你是资深 Go 评审。分析代码，列出最值得审查的 3-5 个维度，" +
		"只输出 JSON：{\"dimensions\":[\"...\"]}"
	out, err := complete(ctx, p, model, system, code)
	if err != nil {
		return reviewPlan{}, err
	}
	return llm.ParseInto[reviewPlan](out)
}

// 2) Generator：每个维度并行审查（用 patterns.Sectioning）
// 3) Evaluator + EvaluatorOptimizer：评估报告是否充分，不足则补漏
// 4) IntentRouter：前置判断输入是否为代码
//
// TODO: 由你拼装。重点体会三个角色"各司其职"如何比一个全能 Agent 更稳。