实现 Bug Diagnosis Agent（故障诊断智能体） 是整个 CodeFlow AI 项目中最具“侦探色彩”的部分。它的核心逻辑不是简单的文本生成，而是**“证据链还原”**。

为了实现这个 Agent，我们需要让 AI 具备像程序员一样“顺藤摸瓜”的能力：从混乱的日志（Log）中提取线索，去代码库（RAG）里寻找犯罪现场，最后给出修复建议。

---

第二部分：Bug Diagnosis Agent 实现教程

1. 核心流程设计

1. 线索提取 (Regex Parser)：从 Traceback 中提取文件名、行号、错误类型。

2. 现场还原 (Context Fetcher)：读取报错行及其上下游代码（Context Window）。

3. 深度检索 (RAG Search)：搜索项目中相关的类定义、配置文件或历史变更。

4. 因果推理 (LLM Reasoning)：分析变量为何为空、逻辑为何冲突。

5. 提交修复 (Change Gate)：通过我们上一章实现的 Change Gate 提交 Diff。

2. 核心工具代码实现

我们需要在 codeflow/langchain_agent.py 中新增一个工具类：DiagnosisToolkit。

import re
from langchain.tools import tool

class DiagnosisToolkit:
    
    @tool
    def parse_stack_trace(log_text: str):
        """从日志或堆栈信息中提取文件名和行号"""
        # 匹配 Python 典型的 Traceback: File "xxx.py", line 123
        pattern = r'File "(.*?)", line (\d+)'
        matches = re.findall(pattern, log_text)
        if not matches:
            return "未能解析出有效路径，请确保输入包含标准堆栈信息。"
        
        results = []
        for file_path, line in matches:
            results.append({"path": file_path, "line": int(line)})
        return results[-3:]  # 通常最后几行是核心报错点

    @tool
    def get_code_snippet(file_path: str, line_number: int, window: int = 15):
        """读取指定行号前后的代码片段"""
        try:
            with open(file_path, "r", encoding="utf-8") as f:
                lines = f.readlines()
            start = max(0, line_number - window)
            end = min(len(lines), line_number + window)
            snippet = "".join(lines[start:end])
            return f"--- {file_path} (Lines {start}-{end}) ---\n{snippet}"
        except Exception as e:
            return f"读取文件失败: {str(e)}"

    @tool
    def propose_bug_fix(file_path: str, new_code: str):
        """通过 Change Gate 提交修复建议"""
        # 调用我们上一篇博文实现的全局 ChangeManager
        change_id = global_change_manager.propose_change(
            file_path=file_path,
            new_content=new_code,
            agent_name="BugDiagnosisAgent"
        )
        return f"已生成修复建议，变更ID: {change_id}。请在侧栏查看预览。"

3. Agent 提示词策略 (System Prompt)

为了让 Agent 像侦探，我们需要给它注入逻辑：

“你是一名资深调试专家。当你收到日志时：1. 先解析堆栈。2. 读取报错位置的代码。3. 思考该处的变量可能来自哪里，是否有空指针、类型错误或逻辑越界。4. 如果需要，检索相关配置文件。5. 最后给出详细分析和修复代码。”

前言

每个程序员都有过这样的痛苦经历：生产环境突然报错，对着几百行的 Traceback 疯狂翻找代码，试图理清调用链。如果 AI 能像资深专家一样，看一眼日志就直接定位到那行“该死的 Bug”，甚至写好修复补丁，那该多好？

今天，我们就来为 CodeFlow AI 注入灵魂——实现 Bug Diagnosis Agent。

---

一、 诊断逻辑：从“看到现象”到“发现本质”

一个优秀的诊断智能体不应该只是复读报错信息。它的核心能力在于**“上下文补全”**。

我们的 Agent 遵循 P-L-A-F 诊断模型：

1. Parse (解析)：自动识别日志中的文件名和行号。

2. Locate (定位)：深入代码库，提取报错点周边的生存环境。

3. Analyze (分析)：利用 LLM 的逻辑能力推断数据流。

4. Fix (修复)：通过 Change Gate 提交安全的修复补丁。

---

二、 技术深挖：它是如何“思考”的？

1. 自动线索提取

Agent 使用正则工具自动扫描用户输入的日志。

• 输入：AttributeError: 'NoneType' object has no attribute 'send' in api/v1/user.py at line 45

• 动作：提取 api/v1/user.py 第 45 行。

2. 代码现场还原

只看报错那一行是不够的。Agent 会自动调用 get_code_snippet 工具，把报错行前后的逻辑全部读入。它会看到：

# Agent 看到的现场
user = user_service.get_by_id(user_id) # 假设这里返回了 None
user.send_notification(msg)            # 第45行：报错点

此时，Agent 会意识到：真正的 Bug 不在第 45 行，而是在 user_service.get_by_id 为什么没查到用户。

3. 跨文件追溯 (RAG 增强)

如果 user_service 在另一个文件中，Agent 会再次发起检索，读取 user_service.py 的定义。这种递归式的探索，正是它能锁定深层 Bug 的秘诀。

---

三、 实战演示：一次完美的修复

用户输入：

“后台报错了，日志如下：KeyError: 'db_config' in config_loader.py:22”

Agent 的执行轨迹：

1. [Tool: parse_stack_trace] 识别到 config_loader.py 第 22 行。

2. [Tool: get_code_snippet] 读取代码，发现是在读取环境变量。

3. [Tool: scan_project] 发现根目录缺少 .env.example。

4. [Agent 思考]：用户可能漏配了环境变量。

5. [Tool: propose_bug_fix] 在代码中加入 try-except 捕获 KeyError，并给出友好的报错提示。

6. [Change Gate] UI 弹出预览：

   code Diff

   downloadcontent_copy

   expand_less

   - value = settings['db_config']
   + value = settings.get('db_config', 'default_local_db')

---

四、 核心代码展示：诊断工具链

在博客中，我们可以分享如何定义这个 Agent 的工具接口（详见上文教程中的代码）。重点在于展示如何将正则解析、文件读取、Change Gate 提交这三者串联起来。

---

五、 总结

Bug Diagnosis Agent 的意义在于：它缩短了从“发现问题”到“修复问题”的路径。它不再是一个只会聊天的机器人，而是一个能读懂你的代码结构、理解你的逻辑漏洞、并遵循安全规则（Change Gate）的虚拟队友。

至此，CodeFlow AI 的四大智能体已经各就各位：

1. Code Review：把控增量代码质量。

2. Test Gen：筑起逻辑防线。

3. Doc Agent：让知识不再断层。

4. Bug Diagnosis：快速消灭存量 Bug。

下一篇预告：我们将迎来终极挑战——Refactoring Agent（代码重构）。看 AI 如何在大规模屎山上进行手术，且通过单测闭环保证手术成功！

---

给读者的启发：

• 精准上下文：给 AI 提供的信息不是越多越好，而是越准越好（通过行号定位）。

• 多级确认：对于诊断出的修复方案，永远不要跳过 Change Gate。

---

学习建议：

1. 练手：尝试故意在你的代码里造一个 ZeroDivisionError，然后把日志扔给你的 Agent，看它能否准确找到那个分母。

2. 扩展：如果你的项目是 Java 或 Go，记得修改 parse_stack_trace 里的正则逻辑，去适配不同语言的报错格式。