第九章：实战项目 - 智能代码审查助手

用户提交代码 --> CodeReviewPipeline (SequentialAgent)
  |
  |-- Step 1: CodeAnalyzer     (分析代码结构，统计行数、复杂度)
  |-- Step 2: BugDetector      (检测潜在 Bug，找安全隐患)
  |-- Step 3: StyleChecker     (检查代码风格，是否符合 Go 惯例)
  |-- Step 4: ReportGenerator  (汇总所有结果，生成最终报告)

用户输入代码
    |
    v
[CodeAnalyzer] --调用工具--> count_lines, check_complexity
    |  输出存到 state["code_analysis"]
    v
[BugDetector] --读取--> {code_analysis}
    |  输出存到 state["bug_report"]
    v
[StyleChecker] --读取用户原始代码-->
    |  输出存到 state["style_report"]
    v
[ReportGenerator] --读取--> {code_analysis}, {bug_report}, {style_report}
    |  生成最终报告
    v
用户看到完整的审查报告

mkdir code-review-assistant && cd code-review-assistant
go mod init code-review-assistant
go get google.golang.org/adk
go get google.golang.org/genai

code-review-assistant/
  |-- go.mod
  |-- go.sum
  |-- main.go    <-- 所有代码都在这里

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "strings"

    "google.golang.org/genai"

    "google.golang.org/adk/agent"
    "google.golang.org/adk/agent/llmagent"
    "google.golang.org/adk/agent/workflowagents/sequentialagent"
    "google.golang.org/adk/cmd/launcher"
    "google.golang.org/adk/cmd/launcher/full"
    "google.golang.org/adk/model/gemini"
    "google.golang.org/adk/tool"
    "google.golang.org/adk/tool/functiontool"
)

// ============================================================
// 第一部分：工具定义
// ============================================================
// 这些工具负责"精确计算"的活儿，LLM 不擅长数数，
// 但我们的 Go 函数可以精确地统计代码信息。

// CountLinesInput 是代码行数统计工具的输入参数
type CountLinesInput struct {
    Code string `json:"code" description:"要统计行数的代码文本"`
}

// CountLinesOutput 是代码行数统计工具的输出结果
type CountLinesOutput struct {
    TotalLines   int `json:"total_lines" description:"总行数"`
    CodeLines    int `json:"code_lines" description:"代码行数"`
    CommentLines int `json:"comment_lines" description:"注释行数"`
    BlankLines   int `json:"blank_lines" description:"空行数"`
}

// countLines 统计代码的行数信息
// 它会把代码按行拆开，逐行判断是代码行、注释行还是空行
func countLines(ctx tool.Context, input CountLinesInput) (CountLinesOutput, error) {
    lines := strings.Split(input.Code, "\n")
    output := CountLinesOutput{TotalLines: len(lines)}

    // 标记是否在多行注释块中
    inBlockComment := false

    for _, line := range lines {
        trimmed := strings.TrimSpace(line)

        // 处理多行注释块
        if inBlockComment {
            output.CommentLines++
            if strings.Contains(trimmed, "*/") {
                inBlockComment = false
            }
            continue
        }

        switch {
        case trimmed == "":
            // 空行
            output.BlankLines++
        case strings.HasPrefix(trimmed, "//"):
            // 单行注释
            output.CommentLines++
        case strings.HasPrefix(trimmed, "/*"):
            // 多行注释开始
            output.CommentLines++
            if !strings.Contains(trimmed, "*/") {
                inBlockComment = true
            }
        default:
            // 代码行
            output.CodeLines++
        }
    }

    return output, nil
}

// CheckComplexityInput 是复杂度检查工具的输入参数
type CheckComplexityInput struct {
    Code string `json:"code" description:"要检查复杂度的代码文本"`
}

// CheckComplexityOutput 是复杂度检查工具的输出结果
type CheckComplexityOutput struct {
    Functions  int      `json:"functions" description:"函数数量"`
    MaxNesting int      `json:"max_nesting" description:"最大嵌套深度"`
    Warnings   []string `json:"warnings" description:"警告信息列表"`
}

// checkComplexity 做一个简单的代码复杂度检查
// 它会统计函数数量、计算最大嵌套深度，并给出相应的警告
func checkComplexity(ctx tool.Context, input CheckComplexityInput) (CheckComplexityOutput, error) {
    output := CheckComplexityOutput{
        Warnings: make([]string, 0),
    }
    lines := strings.Split(input.Code, "\n")
    currentNesting := 0

    for _, line := range lines {
        trimmed := strings.TrimSpace(line)

        // 统计函数定义（简单匹配 func 关键字开头）
        if strings.HasPrefix(trimmed, "func ") {
            output.Functions++
        }

        // 通过花括号计算嵌套深度
        // 虽然简单粗暴，但对大多数 Go 代码够用了
        openBraces := strings.Count(line, "{")
        closeBraces := strings.Count(line, "}")
        currentNesting += openBraces - closeBraces

        if currentNesting > output.MaxNesting {
            output.MaxNesting = currentNesting
        }
    }

    // 根据统计结果给出警告
    if output.MaxNesting > 4 {
        output.Warnings = append(output.Warnings,
            fmt.Sprintf("嵌套层级过深（当前最大 %d 层），建议重构，提取子函数", output.MaxNesting))
    }
    if output.Functions > 20 {
        output.Warnings = append(output.Warnings,
            fmt.Sprintf("函数数量过多（当前 %d 个），建议拆分到多个文件", output.Functions))
    }
    if output.Functions == 0 {
        output.Warnings = append(output.Warnings,
            "没有检测到函数定义，请确认提交的是否为完整代码")
    }

    return output, nil
}

// ============================================================
// 第二部分：主函数 - 组装 Agent 流水线
// ============================================================

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

    // --------------------------------------------------------
    // 第 1 步：创建 LLM 模型
    // --------------------------------------------------------
    // 所有 LLMAgent 共享同一个模型实例。
    // 你可以换成其他模型，比如 "gemini-2.5-pro"。
    model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
        APIKey: os.Getenv("GOOGLE_API_KEY"),
    })
    if err != nil {
        log.Fatalf("创建模型失败: %v", err)
    }

    // --------------------------------------------------------
    // 第 2 步：创建工具
    // --------------------------------------------------------
    // 把我们上面定义的 Go 函数包装成 ADK 工具，
    // 这样 LLM 就能在需要的时候调用它们。

    // 代码行数统计工具
    countLinesTool, err := functiontool.New(functiontool.Config{
        Name:        "count_lines",
        Description: "统计代码的行数信息，区分代码行、注释行和空行，返回各项精确数字",
    }, countLines)
    if err != nil {
        log.Fatalf("创建 count_lines 工具失败: %v", err)
    }

    // 复杂度检查工具
    complexityTool, err := functiontool.New(functiontool.Config{
        Name:        "check_complexity",
        Description: "检查代码的复杂度信息，统计函数数量和最大嵌套深度，给出改进警告",
    }, checkComplexity)
    if err != nil {
        log.Fatalf("创建 check_complexity 工具失败: %v", err)
    }

    // --------------------------------------------------------
    // 第 3 步：创建四个专业 Agent
    // --------------------------------------------------------

    // === Agent 1: 代码结构分析师 ===
    // 它的任务是调用工具，统计代码的基本信息，
    // 然后总结出一份结构分析报告。
    codeAnalyzer, err := llmagent.New(llmagent.Config{
        Name:        "CodeAnalyzer",
        Model:       model,
        Description: "分析代码结构和基本统计信息",
        Instruction: `你是一个代码结构分析师。你的任务是分析用户提交的代码，给出精确的结构信息。

请按以下步骤操作：
1. 使用 count_lines 工具统计代码行数
2. 使用 check_complexity 工具检查代码复杂度
3. 阅读代码，总结其主要功能和结构

请严格按照以下格式输出：

## 代码结构分析

### 基本统计
- 总行数：（填入工具返回的数字）
- 代码行：（填入工具返回的数字）
- 注释行：（填入工具返回的数字）
- 空行：（填入工具返回的数字）

### 复杂度信息
- 函数数量：（填入工具返回的数字）
- 最大嵌套深度：（填入工具返回的数字）
- 复杂度警告：（列出工具返回的警告，没有则写"无"）

### 代码概述
用 2-3 句话简要描述这段代码的主要功能、使用了哪些包、代码的整体组织方式。

注意：数字必须使用工具返回的精确值，不要自己估算。`,
        Tools:     []tool.Tool{countLinesTool, complexityTool},
        OutputKey: "code_analysis",
    })
    if err != nil {
        log.Fatalf("创建 CodeAnalyzer 失败: %v", err)
    }

    // === Agent 2: Bug 猎手 ===
    // 它会结合代码分析的结果，深入审查代码中的潜在问题。
    // 注意指令中的 {code_analysis} —— 这就是指令模板，
    // ADK 会自动把 session state 中的 code_analysis 值替换进来。
    bugDetector, err := llmagent.New(llmagent.Config{
        Name:        "BugDetector",
        Model:       model,
        Description: "检测代码中的潜在 Bug 和安全隐患",
        Instruction: `你是一个经验丰富的 Bug 猎手，专门找 Go 代码里的隐藏问题。

前面的同事已经做了代码结构分析，结果如下：
{code_analysis}

现在轮到你了。请仔细审查用户提交的代码，重点关注以下类型的问题：

1. **空指针/nil 引用风险** - 是否有未检查 nil 就直接使用的地方？
2. **资源泄漏** - 文件、数据库连接、HTTP 响应体等是否正确关闭？有没有用 defer？
3. **并发安全** - 是否有竞态条件、死锁风险？共享变量有没有加锁？
4. **错误处理** - 是否有被忽略的 error 返回值？错误信息是否有意义？
5. **边界条件** - 切片越界、整数溢出、空切片/空 map 操作等。
6. **逻辑错误** - 条件判断是否正确、循环是否有 off-by-one 错误等。

请严格按照以下格式输出：

## Bug 检测报告

（对每个发现的问题，按以下格式列出）

### [严重/中等/轻微] 问题标题
- **位置**：具体说明在代码的哪一部分
- **问题描述**：详细说明问题是什么
- **风险**：可能导致什么后果
- **修复建议**：给出具体的修复方案

---

如果没有发现明显的 Bug，请输出：
## Bug 检测报告
经过仔细审查，未发现明显的 Bug 或安全隐患。代码质量良好。`,
        OutputKey: "bug_report",
    })
    if err != nil {
        log.Fatalf("创建 BugDetector 失败: %v", err)
    }

    // === Agent 3: 代码风格专家 ===
    // 专注于 Go 社区的编码规范和最佳实践。
    styleChecker, err := llmagent.New(llmagent.Config{
        Name:        "StyleChecker",
        Model:       model,
        Description: "检查代码风格和 Go 语言最佳实践",
        Instruction: `你是一个 Go 语言风格专家，深谙 Go 社区的编码规范和最佳实践。
你熟悉 Effective Go、Go Code Review Comments、Go Proverbs 等经典指南。

请审查用户提交的代码，从以下几个维度进行检查：

1. **命名规范**
   - 变量、函数、类型的命名是否符合 Go 惯例？
   - 缩写是否恰当（比如 URL 而不是 Url）？
   - 导出与非导出的命名是否合理？

2. **代码格式**
   - 缩进、空行的使用是否恰当？
   - 代码是否整洁，没有多余的空行或过长的行？

3. **注释质量**
   - 导出的函数和类型是否有文档注释？
   - 注释是否清晰、有价值（不是废话注释）？
   - 包级别的文档是否存在？

4. **Go 惯用模式**
   - 是否使用了 Go 惯用的错误处理方式（if err != nil）？
   - 是否合理使用了 defer、interface、goroutine 等？
   - 有没有"用其他语言的思维写 Go"的情况？

5. **包组织**
   - import 是否按标准库、第三方库、内部包分组？
   - 依赖是否合理？

请严格按照以下格式输出：

## 代码风格检查

（对每个问题，按以下格式列出）

- **[命名/格式/注释/惯用模式/包组织]** 问题描述 --> 建议的改进方式

### 风格评分

给出一个 1-10 分的整体风格评分，并简要说明理由。
- 1-3 分：风格问题严重，需要大幅改进
- 4-6 分：有一些问题，但基本可读
- 7-8 分：风格良好，有小改进空间
- 9-10 分：优秀，符合 Go 社区最佳实践`,
        OutputKey: "style_report",
    })
    if err != nil {
        log.Fatalf("创建 StyleChecker 失败: %v", err)
    }

    // === Agent 4: 报告生成器 ===
    // 汇总前面三个 Agent 的所有结果，生成最终的审查报告。
    // 注意它的指令中引用了三个 state key：
    // {code_analysis}、{bug_report}、{style_report}
    reportGenerator, err := llmagent.New(llmagent.Config{
        Name:        "ReportGenerator",
        Model:       model,
        Description: "汇总所有审查结果，生成最终的代码审查报告",
        Instruction: `你是一个代码审查报告撰写专家。你的任务是把前面三位同事的分析结果，汇总成一份简洁、专业、可执行的代码审查总报告。

以下是三位同事的分析结果：

### 一、代码结构分析
{code_analysis}

### 二、Bug 检测报告
{bug_report}

### 三、代码风格检查
{style_report}

请根据以上信息，生成最终报告。严格按照以下格式输出：

# 代码审查报告

## 概要
用一段话（3-5 句）总结这段代码的整体质量。要客观、具体，不要说空话。

## 评分

| 维度 | 评分(1-10) | 说明 |
|------|-----------|------|
| 代码质量 | x | 简要说明 |
| 安全性 | x | 简要说明 |
| 可维护性 | x | 简要说明 |
| 代码风格 | x | 简要说明 |
| **综合评分** | **x** | 综合评价 |

## 关键问题（必须修复）
列出最重要的、必须修复的问题。如果没有关键问题，写"无关键问题，代码质量良好"。
每条用编号列出，包含问题描述和具体修复建议。

## 改进建议（建议修复）
列出值得改进但不紧急的问题。
每条用编号列出，包含问题描述和建议的做法。

## 亮点
列出代码中做得好的地方，给开发者正向反馈。
如果没有特别的亮点，可以指出代码中合理的设计决策。

注意：
- 不要重复前面已有的详细内容，要做提炼和总结。
- 评分要基于实际发现的问题，不要凭感觉打分。
- 报告要对开发者有实际帮助，不要说套话。`,
        OutputKey: "final_report",
    })
    if err != nil {
        log.Fatalf("创建 ReportGenerator 失败: %v", err)
    }

    // --------------------------------------------------------
    // 第 4 步：组装流水线
    // --------------------------------------------------------
    // 用 SequentialAgent 把四个 Agent 串起来，
    // 它们会按照放入 SubAgents 的顺序依次执行。
    pipeline, err := sequentialagent.New(sequentialagent.Config{
        AgentConfig: agent.Config{
            Name:        "CodeReviewPipeline",
            Description: "智能代码审查流水线：分析结构 --> 检测 Bug --> 检查风格 --> 生成报告",
            SubAgents: []agent.Agent{
                codeAnalyzer,   // 第一步：分析代码结构
                bugDetector,    // 第二步：检测潜在 Bug
                styleChecker,   // 第三步：检查代码风格
                reportGenerator, // 第四步：生成审查报告
            },
        },
    })
    if err != nil {
        log.Fatalf("创建 CodeReviewPipeline 失败: %v", err)
    }

    // --------------------------------------------------------
    // 第 5 步：启动应用
    // --------------------------------------------------------
    // 使用 full.NewLauncher() 全家桶启动器，
    // 支持 console（命令行对话）、web（Web UI）等多种模式。
    config := &launcher.Config{
        AgentLoader: agent.NewSingleLoader(pipeline),
    }
    l := full.NewLauncher()
    if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
        log.Fatalf("运行失败: %v\n\n%s", err, l.CommandLineSyntax())
    }
}

type CountLinesInput struct {
    Code string `json:"code" description:"要统计行数的代码文本"`
}

func countLines(ctx tool.Context, input CountLinesInput) (CountLinesOutput, error) {
    // ...
}

model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
    APIKey: os.Getenv("GOOGLE_API_KEY"),
})

codeAnalyzer, err := llmagent.New(llmagent.Config{
    Name:        "CodeAnalyzer",
    Instruction: `你是一个代码结构分析师...`,
    Tools:       []tool.Tool{countLinesTool, complexityTool},
    OutputKey:   "code_analysis",
})

bugDetector, err := llmagent.New(llmagent.Config{
    Name:        "BugDetector",
    Instruction: `...前面的同事已经做了代码结构分析，结果如下：
{code_analysis}
...`,
    OutputKey:   "bug_report",
})

styleChecker, err := llmagent.New(llmagent.Config{
    Name:        "StyleChecker",
    Instruction: `你是一个 Go 语言风格专家...`,
    OutputKey:   "style_report",
})

reportGenerator, err := llmagent.New(llmagent.Config{
    Name:        "ReportGenerator",
    Instruction: `...
{code_analysis}
...
{bug_report}
...
{style_report}
...`,
    OutputKey:   "final_report",
})

Agent A (OutputKey: "code_analysis")
  --> LLM 回复了一段文本
  --> ADK 自动把这段文本存到 session.State["code_analysis"]

Agent B (Instruction 里有 {code_analysis})
  --> ADK 渲染指令时，发现 {code_analysis} 模板
  --> 从 session.State["code_analysis"] 取值
  --> 替换到指令中
  --> 把完整指令发给 LLM

pipeline, err := sequentialagent.New(sequentialagent.Config{
    AgentConfig: agent.Config{
        Name:        "CodeReviewPipeline",
        Description: "智能代码审查流水线",
        SubAgents: []agent.Agent{
            codeAnalyzer,
            bugDetector,
            styleChecker,
            reportGenerator,
        },
    },
})

config := &launcher.Config{
    AgentLoader: agent.NewSingleLoader(pipeline),
}
l := full.NewLauncher()
if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
    log.Fatalf("运行失败: %v\n\n%s", err, l.CommandLineSyntax())
}

export GOOGLE_API_KEY="your-api-key-here"

go run . console

> 请帮我审查以下Go代码：

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func fetchData(url string) string {
    resp, err := http.Get(url)
    if err != nil {
        fmt.Println("error:", err)
    }
    body, _ := ioutil.ReadAll(resp.Body)
    return string(body)
}

func processItems(items []string) {
    for i := 0; i <= len(items); i++ {
        fmt.Println(items[i])
    }
}

func main() {
    data := fetchData("https://api.example.com/data")
    fmt.Println(data)

    items := []string{"a", "b", "c"}
    processItems(items)
}

# 代码审查报告

## 概要
这段代码存在多个严重问题，包括空指针引用风险、资源泄漏和数组越界错误。
代码功能简单但实现不够健壮，需要重点关注错误处理和资源管理。

## 评分

| 维度 | 评分(1-10) | 说明 |
|------|-----------|------|
| 代码质量 | 3 | 存在明显逻辑错误和空指针风险 |
| 安全性 | 2 | HTTP 响应体未关闭，错误被忽略 |
| 可维护性 | 4 | 代码简短但缺乏错误处理 |
| 代码风格 | 5 | 基本格式可以，但使用了废弃的包 |
| **综合评分** | **3** | 需要较大改进 |

## 关键问题（必须修复）
1. resp.Body 未关闭，每次调用都会泄漏资源
2. http.Get 出错后仍然访问 resp.Body，会导致空指针 panic
3. processItems 循环条件 i <= len(items) 导致数组越界
4. ioutil.ReadAll 的 error 被忽略

## 改进建议（建议修复）
1. 使用 io 包替代已废弃的 ioutil 包
2. fetchData 应该返回 (string, error) 而不是遇错忽略
3. 添加必要的函数文档注释

## 亮点
- import 分组合理
- 函数职责划分清晰（获取数据和处理数据分开）

// 不需要改 Agent 代码，只需要换一种启动方式
// go run . web

CodeAnalyzer (串行第一步)
    |
    v
ParallelAgent (并行执行)
  |-- BugDetector
  |-- StyleChecker
    |
    v
ReportGenerator (串行最后一步)

// 思路示例：在 Agent 执行前后记录时间
codeAnalyzer, err := llmagent.New(llmagent.Config{
    // ... 其他配置 ...
    BeforeAgentCallbacks: []agent.BeforeAgentCallback{
        func(ctx agent.CallbackContext) ([]genai.Part, error) {
            log.Printf("[%s] 开始执行...", ctx.AgentName())
            return nil, nil
        },
    },
})

codeAnalyzer, err := llmagent.New(llmagent.Config{
    // ...
    GenerateContentConfig: &genai.GenerateContentConfig{
        Temperature: genai.Ptr(float32(0.1)), // 降低温度，让 LLM 更听话
    },
})