智能体架构 -- 反思模式，让AI自己当代码审查员

“这代码能跑，但不够好，你回去再想想。” —— 每个程序员的噩梦，现在轮到AI了。

想象一下这个场景：你接手了一个AI代码生成的项目，满怀期待地输入需求：“帮我写一个计算斐波那契数列的函数”。AI立刻吐出一段代码，你一看，递归，简单，但 O(2^n) 的时间复杂度，数据稍微大点就卡死。

你叹了口气：“这AI，和刚入行的我一样天真。”

但如果你告诉它：“嘿，兄弟，你这代码写得不咋地，你自己看看，哪里能优化？” 它会怎么办？今天要聊的 Reflection（反思）模式，就是让AI学会扮演这个“挑剔的代码审查员”的角色。

核心洞察：这不仅仅是一个技术模式，更是一种“元认知”能力。它让AI从“一个只会干活的执行者”，进化成了“能自我迭代的思考者”。

推荐阅读：

智能体架构 -- 工具使用，秒变真·智能助手

智能体架构 -- ReAct，让AI学会“三思而后行”

从“写完就扔”到“三省吾身”：什么是Reflection模式？

我们先抛开复杂的概念，用生活化的例子理解它。

工作流程

类比：就像一个资深程序员在指导一个实习生

1. 生成（Generate）：实习生（AI）接到任务，吭哧吭哧写出了第一版代码。功能实现了，但可能性能差、有边界bug、命名不规范。
2. 批判（Critique）：资深程序员（AI的另一个角色）登场。他不会直接骂人，而是冷静地指出问题：“这里如果输入是负数怎么办？”“这个递归算法复杂度太高，数据量一大就崩。”“变量名用 a、b 不清晰。”
3. 精炼（Refine）：实习生拿到这些具体的反馈，恍然大悟，然后改写出第二版代码。这一版，不仅修复了bug，还采用了更优的算法，代码也规范了。

这个由 “生成 -> 批判 -> 精炼” 构成的循环，就是Reflection模式。它把AI的思考过程拆解，让模型通过“自我对话”来提升输出质量。

⚠️ 注意：这里90%的人会踩坑很多人以为让AI写代码，就是简单地“一次性生成”。这忽略了高质量输出的本质——它是一个迭代优化的过程。Reflection模式的价值，就在于将这个隐性的迭代过程显性化、结构化。

这一模式将大语言模型（LLM）从简单的单轮生成器，提升为更具思辨力与稳健性的推理者。反思型智能体不再满足于给出最先想到的答案，而是退一步审视、批评并打磨自己的成果。这种自我迭代的改进过程，是构建更可靠、更优质AI系统的基石。

什么场景下适用？

• 代码生成：初版代码可能存在缺陷、效率低下或缺少注释。反思机制使智能体能扮演自己的代码审查员，在交付终稿前发现错误并优化写法。
• 复杂文本摘要：面对信息密集的文档，首轮摘要可能遗漏细节或忽略微妙之处。反思步骤有助于生成更全面、准确的摘要。
• 创意写作与内容创作：无论是邮件、博文还是故事，初稿总有提升空间。反思能让智能体优化语气、清晰度和感染力。

优势与局限

优势：

• 质量跃升：直接识别并修正错误，输出更准确、稳健、条理分明。
• 轻量实现：概念简单，仅需单一LLM即可实现，无需复杂外部工具。

局限：

• 认知偏差：智能体仍受自身知识与偏见的限制。若它不知道更优解法，批评也无法凭空创造新知——它只能修复已识别的缺陷。
• 延迟与成本增加：至少需要两次LLM调用（生成+批评/优化），比单轮生成更耗时、更昂贵。

动手实战：搭建一个反思型智能体

理论讲完，我们直接上代码。我们将用 Nebius AI Studio 的模型，配合 LangGraph 编排工作流，构建一个完整的反思智能体。

阶段0：环境准备与基础配置

在构建反思智能体之前，我们需要搭建运行环境。这包括安装必要库、导入模块以及配置API密钥。

步骤0.1：安装核心库

我们将安装本项目必需的Python库。langchain-nebius 提供Nebius AI Studio模型的接入，langchain 与 langgraph 构成核心编排框架，python-dotenv 管理API密钥，rich 用于美化输出。

# !pip install -q -U langchain-nebius langchain langgraph rich python-dotenv

步骤0.2：导入库并配置密钥

现在导入已安装库中的必要组件。我们将用 python-dotenv 从本地的 .env 文件安全加载Nebius API密钥。同时启用LangSmith追踪功能，这对调试多步智能体工作流极为有用。

操作提示：请在笔记本同级目录下创建 .env 文件，并按如下格式填入密钥：

NEBIUS_API_KEY="你的Nebius API密钥"
LANGCHAIN_API_KEY="你的LangSmith API密钥"

import os
import json
from typing import List, TypedDict, Optional
from dotenv import load_dotenv

# Nebius及LangChain组件
from langchain_nebius import ChatNebius
from pydantic import BaseModel, Field
from langgraph.graph import StateGraph, END

# 美化输出
from rich.console import Console
from rich.markdown import Markdown
from rich.syntax import Syntax

# --- API密钥与追踪配置 ---
load_dotenv()

# 设置LangSmith追踪
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_PROJECT"] = "智能体架构 - 反思模式 (Nebius)"

# 检查密钥是否已设置
ifnot os.environ.get("NEBIUS_API_KEY"):
    print("未找到NEBIUS_API_KEY，请在.env文件中设置。")
ifnot os.environ.get("LANGCHAIN_API_KEY"):
    print("未找到LANGCHAIN_API_KEY，请在.env文件中设置以启用追踪。")

print("环境变量加载完成，追踪功能已启用。")

阶段1：构建反思模式的核心组件

一个稳健的反思架构远不止一个简单提示词。我们将它构建为结构化的三模块系统：生成器、批评家与优化器。为确保可靠性，我们将使用Pydantic模型为每一步定义明确的输出格式。

步骤1.1：用Pydantic定义数据模型

我们将定义Pydantic模型，作为LLM输出结构的“契约”。这能让模型明确知道自己应以何种格式输出内容，在多步流程中——前一步的输出即为后一步的输入——这一点至关重要。

classDraftCode(BaseModel):
"""智能体生成的初版代码结构。"""
    code: str = Field(description="为解决用户需求而生成的Python代码。")
    explanation: str = Field(description="代码工作原理的简要说明。")

classCritique(BaseModel):
"""对生成代码的自我批评结构。"""
    has_errors: bool = Field(description="代码是否存在潜在错误或逻辑缺陷？")
    is_efficient: bool = Field(description="代码实现是否高效、优化？")
    suggested_improvements: List[str] = Field(description="具体、可操作的改进建议。")
    critique_summary: str = Field(description="批评总结。")

classRefinedCode(BaseModel):
"""采纳批评意见后生成的最终优化代码结构。"""
    refined_code: str = Field(description="最终改进后的Python代码。")
    refinement_summary: str = Field(description="基于批评意见所做修改的总结。")

print("已定义Draft、Critique与RefinedCode三套Pydantic模型。")

输出讨论：我们成功定义了数据结构。Critique模型尤为关键——通过明确要求 has_errors、is_efficient 等字段，我们引导LLM进行比单纯说“请审查代码”更结构化、更有价值的评估。

步骤1.2：初始化Nebius LLM与Console

我们将初始化驱动三个角色（生成器、批评家、优化器）的Nebius语言模型。选用 meta-llama/Meta-Llama-3.1-8B-Instruct 这类高性能模型，确保各步骤的推理质量。同时设置 rich 控制台，用于格式化输出。

# 选用高性能Nebius模型进行生成与批评
llm = ChatNebius(model="meta-llama/Meta-Llama-3.1-8B-Instruct", temperature=0.2)

# 初始化美化输出控制台
console = Console()

print("Nebius LLM与Console已初始化。")

步骤1.3：创建生成器节点

该节点的唯一任务：接收用户请求，产出初版代码。我们将 DraftCode Pydantic模型绑定到Nebius LLM，确保输出格式正确。

defgenerator_node(state):
"""生成初版代码。"""
    console.print("--- 1. 生成初稿 ---")
    generator_llm = llm.with_structured_output(DraftCode)

    prompt = f"""你是一位Python编程专家。请根据以下需求编写一个Python函数。
    请提供简洁、清晰的实现，并附上说明。

    需求：{state['user_request']}
    """

    draft = generator_llm.invoke(prompt)
return {"draft": draft.model_dump()}

步骤1.4：创建批评家节点

这是反思流程的核心。批评家节点接收初版代码，分析缺陷，并使用 Critique Pydantic模型生成结构化批评。

defcritic_node(state):
"""对生成的代码进行错误与低效点的批评。"""
    console.print("--- 2. 批评初稿 ---")
    critic_llm = llm.with_structured_output(Critique)

    code_to_critique = state['draft']['code']

    prompt = f"""你是一位资深的代码审查专家及高级Python开发者。请对以下代码进行透彻的批评。

    请从以下方面分析代码：
    1. **错误与缺陷**：是否存在潜在的运行时错误、逻辑缺陷或未处理的边界情况？
    2. **效率与最佳实践**：这是解决问题的最有效方式吗？是否符合Python标准规范（PEP 8）？

    请提供结构化批评，并附上具体、可操作的改进建议。

    待审查代码：
    ```python
{code_to_critique}
    ```
    """

    critique = critic_llm.invoke(prompt)
return {"critique": critique.model_dump()}

步骤1.5：创建优化器节点

这是逻辑链条的最后一环。优化器节点同时接收初版代码与结构化批评，负责编写最终改进版代码。

defrefiner_node(state):
"""根据批评意见优化代码。"""
    console.print("--- 3. 优化代码 ---")
    refiner_llm = llm.with_structured_output(RefinedCode)

    draft_code = state['draft']['code']
    critique_suggestions = json.dumps(state['critique'], indent=2)

    prompt = f"""你是一位Python编程专家，任务是依据批评意见优化一段代码。

    你的目标是重写原始代码，全面落实批评意见中提出的改进建议。

    **原始代码：**
    ```python
{draft_code}
```

    **批评意见与建议：**
{critique_suggestions}

    请提供最终优化后的代码，并附上修改总结。
    """

    refined_code = refiner_llm.invoke(prompt)
return {"refined_code": refined_code.model_dump()}

阶段1讨论：至此，我们已构建反思智能体的三大核心逻辑组件。每个组件均为功能单一、职责明确的函数（或称“节点”）。各阶段均使用结构化输出，确保数据在节点间可靠流转。接下来，我们将使用LangGraph编排这一工作流。

阶段2：使用LangGraph编排反思工作流

步骤2.1：定义图状态

“状态”是图的工作记忆，是节点间传递的中心对象，每个节点均可读取或写入。我们将用Python的 TypedDict 定义 ReflectionState，容纳工作流中的所有数据。

classReflectionState(TypedDict):
"""表示反思图的状态。"""
    user_request: str
    draft: Optional[dict]
    critique: Optional[dict]
    refined_code: Optional[dict]

print("已定义ReflectionState TypedDict。")

步骤2.2：构建并可视化图

现在用 StateGraph 将各节点组装为连贯工作流。反思模式的流程是简单的线性序列：生成 → 批评 → 优化。我们将定义此流程，编译并可视化图结构，以验证其正确性。

graph_builder = StateGraph(ReflectionState)

# 向图中添加节点
graph_builder.add_node("generator", generator_node)
graph_builder.add_node("critic", critic_node)
graph_builder.add_node("refiner", refiner_node)

# 定义工作流边
graph_builder.set_entry_point("generator")
graph_builder.add_edge("generator", "critic")
graph_builder.add_edge("critic", "refiner")
graph_builder.add_edge("refiner", END)

# 编译图
reflection_app = graph_builder.compile()

print("反思图编译成功！")

# 可视化图
try:
from IPython.display import Image, display
    png_image = reflection_app.get_graph().draw_png()
    display(Image(png_image))
except Exception as e:
    print(f"图可视化失败：{e}，请确保已安装pygraphviz。")

输出讨论：图已成功编译。可视化结果确认了我们设想的线性工作流：状态从入口（生成器）出发，流经批评器与优化器节点，最终到达终止状态。这一简洁而强大的结构现已准备就绪，随时可执行。

阶段3：端到端执行与评估

图已编译完成，是时候见证反思模式的实际表现。我们将分配一项编程任务——该任务的朴素初版解法往往不够优化，恰好成为自我批评与改进的理想测试案例。

步骤3.1：运行完整反思工作流

我们将调用已编译的LangGraph应用，要求其编写“寻找第n个斐波那契数”的Python函数。我们以流式方式获取结果，并正确累积完整状态，以便最终检查所有中间步骤。

user_request = "编写一个Python函数，用于计算第n个斐波那契数。"
initial_input = {"user_request": user_request}

console.print(f"[bold cyan]🚀 启动反思工作流，请求：[/bold cyan]'{user_request}'\n")

# 正确捕获最终完整状态
final_state = None
for state_update in reflection_app.stream(initial_input, stream_mode="values"):
    final_state = state_update

console.print("\n[bold green]✅ 反思工作流执行完毕！[/bold green]")

步骤3.2：分析“优化前后”对比

这是见证成果的时刻。我们将检查 final_state 中存储的各阶段输出，依次打印初版代码、批评意见及最终优化代码，清晰展示反思流程带来的价值。

if final_state and'draft'in final_state and'critique'in final_state and'refined_code'in final_state:
    console.print(Markdown("--- ### 初版代码 ---"))
    console.print(Markdown(f"**说明：** {final_state['draft']['explanation']}"))
    console.print(Syntax(final_state['draft']['code'], "python", theme="monokai", line_numbers=True))

    console.print(Markdown("\n--- ### 批评意见 ---"))
    console.print(Markdown(f"**总结：** {final_state['critique']['critique_summary']}"))
    console.print(Markdown(f"**改进建议：**"))
for improvement in final_state['critique']['suggested_improvements']:
        console.print(Markdown(f"- {improvement}"))

    console.print(Markdown("\n--- ### 最终优化代码 ---"))
    console.print(Markdown(f"**优化总结：** {final_state['refined_code']['refinement_summary']}"))
    console.print(Syntax(final_state['refined_code']['refined_code'], "python", theme="monokai", line_numbers=True))
else:
    console.print("[bold red]错误：final_state不可用或不完整，请检查前序单元格的执行。[/bold red]")

输出讨论：执行结果完美诠释了反思模式的威力。

• 初版代码：生成了一个简单的递归解法。该解法虽然正确，但因重复计算相同值而效率极低，时间复杂度呈指数级增长。
• 批评意见：准确识别了上述重大缺陷。扮演“批评家”角色的LLM指出了效率问题，并建议改用更优的迭代法以避免重复计算。
• 最终优化代码：成功落实了批评建议。它将慢速递归函数替换为使用循环与双变量追踪序列的快速迭代解法。

这是一次实质性的优化。智能体不仅修正了代码格式，更是从算法层面进行了彻底重构，获得了更健壮、可扩展的解决方案——这正是反思模式的核心价值。

步骤3.3：定量评估（LLM作为裁判）

为使分析更规范，我们将调用另一LLM作为中立“裁判”，对初版代码与最终代码进行评分。这为我们提供了衡量反思改进效果的客观尺度。

classCodeEvaluation(BaseModel):
"""代码评估结构。"""
    correctness_score: int = Field(description="逻辑正确性评分，1-10分。")
    efficiency_score: int = Field(description="算法效率评分，1-10分。")
    style_score: int = Field(description="代码风格与可读性（PEP 8）评分，1-10分。")
    justification: str = Field(description="评分的简要说明。")

judge_llm = llm.with_structured_output(CodeEvaluation)

defevaluate_code(code_to_evaluate: str):
    prompt = f"""你是一位Python代码评审专家。请对以下函数在正确性、效率与风格三方面进行1-10分评分，并附简要说明。

    代码：
    ```python
{code_to_evaluate}
    ```
    """
return judge_llm.invoke(prompt)

if final_state and'draft'in final_state and'refined_code'in final_state:
    console.print("--- 评估初版代码 ---")
    initial_draft_evaluation = evaluate_code(final_state['draft']['code'])
    console.print(initial_draft_evaluation.model_dump())

    console.print("\n--- 评估优化后代码 ---")
    refined_code_evaluation = evaluate_code(final_state['refined_code']['refined_code'])
    console.print(refined_code_evaluation.model_dump())
else:
    console.print("[bold red]错误：final_state不完整，无法执行评估。[/bold red]")

输出讨论：LLM裁判的定量评估为反思模式的成功提供了数据支撑。初版代码可能在正确性上得分尚可，但效率分极低；而优化后的代码则在正确性与效率上均获得高分。这一自动化评分证实：反思流程不仅改变了代码形式，更在可量化的维度上显著提升了代码质量。

国内实践：把反思模式用起来

在实际的国内开发环境中，Reflection模式有着广阔的应用空间。

• 代码生成：国内很多低代码平台、AI辅助开发工具，都可以引入反思机制。比如在阿里云代码服务、腾讯云开发者平台中，AI生成的代码可以先自我审查一轮，再输出给用户，极大减少“无效代码”的产生。
• 智能客服：客服对话的初稿可能语气生硬或信息不全，通过反思优化，让回复更专业、更有人情味。
• 文档生成：API文档、技术博客的初稿往往需要多轮打磨，反思模式可以自动完成“审稿—修改”的过程。

⚠️ 注意：国内使用AI生成内容时，还需注意合规性（如数据安全、内容审核）。反思模式可以帮助过滤掉潜在的不合规内容，但最终的审核责任仍在开发者。

写在最后

在本教程中，我们借助Nebius AI Studio模型，完整构建、执行并评估了一个基于反思架构的端到端智能体。我们亲眼见证了这一简洁而强大的模式，如何将基础的LLM生成器，蜕变为更精密、可靠的问题解决者。

通过将流程拆解为“生成—批评—优化”三步，并用LangGraph进行编排，我们创造了一个能够自我识别并修正重大缺陷的稳健系统。从低效的递归解法到最优迭代方案的实质性跃升，充分说明反思是实现智能体从“完成任务”迈向“追求品质”的奠基性技术。

核心回顾

1. 原理：反思模式通过“生成—批评—优化”的自我迭代，让AI学会自我审查与改进。
2. 实践：我们用LangGraph实现了完整的反思工作流，并对比了优化前后的代码质量。
3. 避坑：反思模式虽好，但会增加调用成本和时间，且受限于模型本身的知识边界，无法解决它完全不知道的问题。

在你的项目中，有没有遇到过那种“AI生成的东西看着还行，但总觉得差点意思”的场景？你打算用反思模式去改进它吗？或者，你已经尝试过类似的自我审查机制？欢迎在评论区分享你的经验！