第四章：tRPC-Agent-Go Team 多 Agent 协作

type Mode int
const (
    ModeCoordinator Mode = iota  // 有中心调度者
    ModeSwarm                    // 去中心化
)

func New(coordinator Agent, members []Agent, opts ...Option) *Team {
    team := &Team{
        coordinator: coordinator,
        members:     members,
        mode:        ModeCoordinator,
    }

    // 关键操作：把每个 member 包装为 AgentTool
    agentTools := make([]tool.Tool, len(members))
    for i, member := range members {
        agentTools[i] = NewAgentTool(member)
    }

    // 把 AgentTools 注入 Coordinator 的工具列表
    coordinator.AddTools(agentTools...)

    return team
}

// 差的描述 → Coordinator 无法准确判断该派谁
badAgent := llmagent.New(
    llmagent.WithName("agent1"),
    llmagent.WithDescription("一个助手"),  // 毫无区分度
)

// 好的描述 → 五要素：身份/能力/适用/不适用/格式
goodAgent := llmagent.New(
    llmagent.WithName("security_reviewer"),
    llmagent.WithDescription(`安全审查专家。
能力：检测SQL注入、XSS、CSRF等安全漏洞，审查认证和授权逻辑。
适用：代码安全审查、安全方案评审。
不适用：性能优化、代码风格、业务逻辑审查。
输入：代码片段或PR diff。输出：漏洞清单+修复建议。`),
)

// 技巧1：不给 Coordinator 任何普通工具
coordinator := llmagent.New(
    llmagent.WithName("coordinator"),
    llmagent.WithTools(),  // 空工具列表！只有框架自动注入的 AgentTools
)

// 技巧2：prompt 中强约束
// "你没有搜索/编程/分析能力。试图自己做一定会出错。"

// 技巧3：低 MaxSteps 限制思考时间
coordinator := llmagent.New(
    llmagent.WithMaxSteps(15),     // 约5次委派机会
    llmagent.WithTemperature(0.1), // 低温度 → 决策稳定
)

func NewSwarm(entryName string, members []Agent, opts ...Option) *Team {
    team := &Team{
        entryName: entryName,
        members:   members,
        mode:      ModeSwarm,
    }

    // 关键操作：让每个 member 知道所有其他 members
    wireSwarmRoster(team)
    // wireSwarmRoster 做的事：
    //   对每个 member，注入 transfer_to_agent 工具 + 所有同事信息

    return team
}

type SwarmConfig struct {
    MaxHandoffs            int           // 最大交接次数（防止无限循环）
    NodeTimeout            time.Duration // 单个 Agent 执行超时
    RepetitiveHandoffWindow int          // 重复交接检测窗口
}

// Swarm 在 session 中记录当前活跃的 Agent
const swarmActiveAgentKey = "swarm_active_agent:teamName"

// 新请求到达时，从 session 读取上次的活跃 Agent
func (t *Team) runSwarm(ctx, inv) {
    activeAgent := inv.Session.Get(swarmActiveAgentKey)
    if activeAgent == "" {
        activeAgent = t.entryName  // 首次请求从入口开始
    }
    // 从 activeAgent 继续执行
}

// transfer_to_agent 工具的内部实现（简化）
func transferToAgent(ctx context.Context, params map[string]any) (string, error) {
    targetName := params["agent_name"].(string)
    message := params["message"].(string)  // 交接说明

    inv := GetInvocationFromContext(ctx)
    inv.HandoffMessage = message
    inv.HandoffTarget = targetName
    // 当前 Agent 的对话历史默认传递给下一个 Agent
    return "transfer_successful", nil
}

// 四种裁剪策略

// 策略1：只传 handoff 消息（最激进）
team.WithContextInheritance(team.InheritNone)
// 下游只看到 transfer_to_agent 的 message 参数

// 策略2：滑动窗口（保留最近N条）
team.WithContextInheritance(team.InheritLastN(5))

// 策略3：LLM 摘要压缩
team.WithContextInheritance(team.InheritSummary)
// handoff 时自动调 LLM 压缩上下文，再传给下游

// 策略4：自定义裁剪
team.WithContextTransformer(func(msgs []*Message, from, to string) []*Message {
    // 只保留 system + tool_result + 最后一条 assistant
    var kept []*Message
    for _, m := range msgs {
        if m.Role == "system" || m.Role == "tool" {
            kept = append(kept, m)
        }
    }
    kept = append(kept, msgs[len(msgs)-1])
    return kept
})

// Team 级共享状态：所有 Agent 可读写
inv.State.Values["research_data"] = data  // A 写，B 读

// Agent 局部状态：通过 Agent 内部字段
type WriterAgent struct {
    draftCount int  // 只有 Writer 自己用
}

// 设计建议：
// - 下游需要的数据 → 写入 State（共享）
// - 内部执行细节 → 保留在局部
// - handoff 消息 → 描述"期望什么"，而非"dump所有数据"

// 定义一个多 Agent Team
researchTeam := team.New(coordinator, []*Agent{searcher, analyzer})

// 把 Team 作为图的一个节点
graph := NewStateGraph(schema)
graph.AddNode("collect_requirements", requirementsFn)
graph.AddNode("research", researchTeam.AsNode())  // Team 当节点用
graph.AddNode("generate_report", reportFn)
graph.AddEdge("collect_requirements", "research")
graph.AddEdge("research", "generate_report")

// GraphAgent 内部用 StateGraph 实现复杂逻辑
type ComplexResearchAgent struct {
    graph *StateGraph
}

func (a *ComplexResearchAgent) Run(ctx, inv) (<-chan *Event, error) {
    return a.graph.Execute(ctx, inv.State)
}

// 然后把这个 Agent 作为 Team 的一个 member
team := team.NewSwarm("complex_research", []Agent{complexResearchAgent, writerAgent})

// Swarm Runtime 自动记录 handoff 日志
type HandoffLog struct {
    Timestamp   time.Time
    FromAgent   string
    ToAgent     string
    Message     string   // handoff 时传递的消息
    Reason      string   // 为什么交接（从 LLM 思考中提取）
    StepCount   int      // 当前 Agent 执行了几步后交接
    TokensUsed  int      // 当前 Agent 消耗的 token
}

// 查看完整 handoff 链
// [14:30:01] triage_agent → security_reviewer: "检测到疑似SQL注入" (3步, 450 tokens)
// [14:30:08] security_reviewer → perf_reviewer: "安全问题已记录" (5步, 1200 tokens)
// [14:30:15] perf_reviewer → style_reviewer: "无性能问题" (2步, 300 tokens)
// [14:30:20] style_reviewer → END: "审查完成" (4步, 600 tokens)

coordinator := NewLLMAgent("review_manager",
    WithSystemPrompt("你是代码审查经理。分析 PR 内容，分配给合适的审查员。"),
)

securityReviewer := NewLLMAgent("security_reviewer",
    WithTools(sqlInjectionChecker, xssScanner),
    WithSystemPrompt("你是安全专家。只关注安全漏洞。"),
)

perfReviewer := NewLLMAgent("perf_reviewer",
    WithTools(queryAnalyzer, memoryProfiler),
    WithSystemPrompt("你是性能专家。只关注性能问题。"),
)

styleReviewer := NewLLMAgent("style_reviewer",
    WithTools(linter, formatterCheck),
    WithSystemPrompt("你是代码风格审查员。只关注规范。"),
)

team := team.New(coordinator, []Agent{securityReviewer, perfReviewer, styleReviewer})

securityReviewer := NewLLMAgent("security_reviewer",
    WithTools(sqlInjectionChecker, xssScanner, transferTool),
    WithSystemPrompt("你是安全专家。审查完安全问题后，转交给性能审查员。"),
)

perfReviewer := NewLLMAgent("perf_reviewer",
    WithTools(queryAnalyzer, memoryProfiler, transferTool),
    WithSystemPrompt("你是性能专家。审查完性能后，转交给风格审查员。"),
)

styleReviewer := NewLLMAgent("style_reviewer",
    WithTools(linter, formatterCheck),
    WithSystemPrompt("你是风格审查员。审查完后给出最终汇总意见。"),
)

team := team.NewSwarm("security_reviewer",
    []Agent{securityReviewer, perfReviewer, styleReviewer},
    WithMaxHandoffs(5),
)

// ===== 第三级：基础 Agent =====
frontendCoder := NewLLMAgent("frontend_coder", ...)
backendCoder := NewLLMAgent("backend_coder", ...)
dbDesigner := NewLLMAgent("db_designer", ...)
uiDesigner := NewLLMAgent("ui_designer", ...)
securityAuditor := NewLLMAgent("security_auditor", ...)
perfTester := NewLLMAgent("perf_tester", ...)
techWriter := NewLLMAgent("tech_writer", ...)

// ===== 第二级：子 Team（各自有 Coordinator）=====
devTeam := team.New(
    NewLLMAgent("dev_lead", WithSystemPrompt("你是开发组长，管理前端后端和数据库")),
    []Agent{frontendCoder, backendCoder, dbDesigner},
)

qaTeam := team.New(
    NewLLMAgent("qa_lead", WithSystemPrompt("你是QA组长，管理安全和性能测试")),
    []Agent{securityAuditor, perfTester},
)

designTeam := team.NewSwarm("ui_designer",
    []Agent{uiDesigner, techWriter},  // 设计→文档，线性流程用 Swarm
)

// ===== 第一级：顶层 Team =====
// 注意：子 Team 作为 Member 注入顶层 Coordinator
topTeam := team.New(
    NewLLMAgent("project_manager", WithSystemPrompt(`
        你是项目经理。你管理三个组：
        - dev_team: 开发组（前端、后端、数据库）
        - qa_team: 质量组（安全审查、性能测试）
        - design_team: 设计组（UI设计、技术文档）
        按项目需求委派给合适的组。
    `)),
    []Agent{devTeam.AsAgent(), qaTeam.AsAgent(), designTeam.AsAgent()},
)

// 递归深度限制
topTeam := team.New(coordinator, subTeams,
    team.WithMaxDepth(3),          // 最多3层嵌套
    team.WithTotalMaxSteps(50),    // 所有层级加起来最多50步
    team.WithTotalTokenBudget(100000),  // 总 token 预算
)

// 事件流的嵌套结构
// 顶层 Runner 收到的事件流：
//
// [team:top] thinking: "需要开发组先做"
// [team:top] tool_call: dev_team("实现用户注册功能")
//   [team:dev] thinking: "需要后端和数据库"
//   [team:dev] tool_call: backend_coder("写注册API")
//     [agent:backend_coder] thinking: "用 REST 设计"
//     [agent:backend_coder] tool_call: code_write(...)
//     [agent:backend_coder] final_response: "API 实现完成"
//   [team:dev] tool_call: db_designer("设计用户表")
//     [agent:db_designer] final_response: "表结构设计完成"
//   [team:dev] final_response: "开发完成"
// [team:top] tool_call: qa_team("测试注册功能")
//   ...

// 事件过滤：用户通常只需要看顶层事件
topTeam := team.New(coordinator, subTeams,
    team.WithEventFilter(func(ev *event.Event) bool {
        return ev.Depth <= 1  // 只向上传播前两层的事件
    }),
)