Agent丨什么是 Self-Reflection 机制？它在代码生成或故障排查 Agent 中如何应用？

type

Post

status

Published

date

May 28, 2026

slug

agent53

summary

一、先给结论：Self-Reflection 不是“让模型自言自语”，而是一个工程闭环

在 Agent 系统里，Self-Reflection 可以理解为：

Agent 在一次行动失败、结果不确定、质量需要提升，或即将交付前，基于可观察证据对自己的输出、工具调用轨迹、错误信息和任务目标进行复盘，生成下一步修正策略，并把有价值的经验沉淀到短期或长期记忆中。

它的核心不是“模型相信自己想得更深”，而是把下面这个闭环工程化：

从研究上看，Self-Reflection 有两个代表脉络：Self-Refine 强调“生成初稿 → 自反馈 → 再改写”的迭代过程，不依赖额外训练或强化学习；Reflexion 强调 Agent 根据任务反馈生成语言形式的反思，并把这些反思放进 episodic memory，以便后续试错时改善决策。(arXiv)

在代码 Agent 中，Self-Reflection 最有价值的地方不是写“更漂亮”的解释，而是让 Agent 能够在失败后自我修复：比如看到 npm test 失败、TypeScript 编译错误、接口返回 500、Playwright 截图不符合预期后，自动归因、缩小修改范围、重新执行测试，直到通过或触发人工接管。SWE-agent 这类工程研究也说明，代码 Agent 的关键不只是模型能力，还包括面向 Agent 设计的命令、文件查看、编辑、反馈格式和测试执行接口。(NeurIPS 会议记录)

二、Self-Reflection 与 ReAct、Self-Refine、Reflexion 的关系

1. ReAct：让 Agent 边思考边行动

ReAct 的基本思想是让语言模型交替生成 reasoning trace 和 action，使模型能够在行动后吸收外部观察结果，再调整计划。它解决的是“只靠一次性推理容易幻觉和错误传播”的问题。(arXiv)

典型 ReAct 循环是：

ReAct 里已经有“观察后调整”的味道，但它不一定显式生成一段可复用的反思。Self-Reflection 是在 ReAct 之上增加一个“复盘层”：把失败轨迹转换成结构化经验，例如“本次失败的根因是什么、下次遇到类似错误应该先检查什么”。

2. Self-Refine：同一个模型自评并改写

Self-Refine 更像生成任务中的“草稿-批改-修订”模式。论文中，LLM 先生成初始输出，再由同一 LLM 反馈，最后基于反馈迭代 refine；作者强调它不需要监督数据、额外训练或 RL。(arXiv)

在代码生成里，它可以对应：

但仅靠模型自查有风险。代码场景必须接入真实反馈，例如编译器、单测、lint、类型检查、运行日志、浏览器截图。否则 Self-Reflection 很容易变成“自我安慰式审查”。

3. Reflexion：把失败经验写入记忆

Reflexion 的关键点是“不更新模型权重，而是更新语言记忆”。Agent 根据 scalar feedback 或自然语言反馈生成反思，并维护 episodic memory，后续任务再把这些经验取出来辅助决策。(开放评论)

在故障排查 Agent 中，这非常实用。例如：

以后 Agent 遇到类似错误时，不需要从零推理，可以先检索历史反思。

4. Self-Reflection 的实证观察

有研究比较了多种 self-reflection agent 类型，包括 Retry、Advice、Explanation、Instructions、Solution、Composite 等。该实验显示，多种反思形式都能显著提升多选问题的再回答表现，其中包含更多具体信息的反思通常优于简单 Retry 或关键词提示。不过该研究也明确指出，实验主要是单步问题，真实多步 Agent 更需要结合工具反馈和外部记忆。(arXiv)

这对工程实现的启示是：

Self-Reflection 最好不要只发生在语言空间里，而要绑定环境反馈、工具结果和可验证动作。

三、成熟代码 Agent 中的 Self-Reflection 影子

1. Claude Code：通过工具、Hooks、Memory 形成外部反馈闭环

Claude Code 官方文档将其定位为 agentic coding tool，可以读取代码库、编辑文件、执行命令，并通过 MCP 连接外部工具；同时支持 CLAUDE.md 项目指令、自动记忆、Skills 和 Hooks。官方文档中提到，Hooks 可以在 Claude Code 动作前后运行 shell 命令，例如文件编辑后自动格式化、提交前运行 lint。(Claude Code)

Hooks 是代码 Agent 做 Self-Reflection 的关键工程抓手。Claude Code 的 Hook 生命周期中，PreToolUse 发生在模型生成工具参数之后、工具真正执行之前，可用于 allow、deny、ask、defer，甚至修改工具输入；PostToolUse 则发生在工具成功执行后，可以把额外上下文、替换后的工具输出或阻断反馈传回给 Claude。(Claude Code)

例如，PostToolUse(Edit|Write) 可以自动运行 lint，把错误作为反馈注入给 Agent；PreToolUse(Bash) 可以阻止危险命令；exit code 2 在 PreToolUse 中会阻止工具调用，并把 stderr 反馈给 Claude。(Claude Code)

这本质上是把“反思”从 Prompt 变成了运行时机制：

2. OpenCode：Plan 模式、工具权限、Skills 与自定义工具

OpenCode 官方文档称其是开源 AI coding agent，可在 terminal、desktop app 或 IDE extension 中使用；它支持 bash、edit、write、read、grep、glob、实验性 lsp、apply_patch、skill、todowrite、webfetch、websearch、question 等内置工具。(OpenCode)

OpenCode 的 Plan 模式很适合做“行动前反思”：文档说明 Plan mode 会禁用修改能力，让 Agent 先给出实现计划；用户反馈后，再切回 Build mode 执行。(OpenCode)

OpenCode 的权限系统也很适合做反思边界控制。它支持 allow、ask、deny 三类动作，并可以对 bash、edit 等工具配置细粒度规则，例如允许 git *、npm *，拒绝 rm *。(OpenCode)

源码层面，OpenCode 的 tool registry 会组装内置工具和自定义工具，并把工具描述、参数 schema、执行函数暴露给模型；自定义工具可以放在 .opencode/tools/ 或全局配置目录，用 TypeScript/JavaScript 定义，执行逻辑也可以调用其他语言脚本。(GitHub)

因此，OpenCode 中可以这样实现 Self-Reflection：

3. OpenHands：把代码 Agent 平台化

OpenHands 的 GitHub README 将其描述为 AI-driven development 项目，提供 Software Agent SDK、CLI、Local GUI 和 Cloud 等形态；SDK 是其 agentic 技术的核心，可用于定义 Agent 并在本地或云端运行，CLI 的体验也被官方描述为类似 Claude Code 或 Codex。(GitHub)

从 Self-Reflection 角度看，OpenHands 这类平台的价值在于：它不只是“聊天生成代码”，而是把运行环境、代码仓库、权限、队列、任务状态、协作流程都平台化。故障排查 Agent 需要的正是这种“可观察、可回滚、可验证、可审计”的执行环境。

4. OpenClaw / Pi：小核心、多扩展、可自举

OpenClaw 官方 README 描述它是运行在用户自己设备上的个人 AI assistant，支持多种聊天渠道，并提供 local-first gateway、多 Agent routing、first-class tools、skills、sandbox 等能力。其 README 也明确提示：OpenClaw 会连接真实消息入口，入站 DM 应视为不可信输入；非 main session 可以运行在 sandbox 中，Docker 是默认 sandbox backend。(GitHub)

Armin Ronacher 在介绍 Pi 时提到，Pi 是 OpenClaw 底层使用的小型 coding agent；它的核心很小，主要只有 Read、Write、Edit、Bash 四个工具，但通过扩展系统、持久化扩展状态、热重载、session tree 等机制，让 Agent 能够写代码、reload、测试并循环直到扩展可用。(Armin Ronacher's Thoughts and Writings)

这给 Self-Reflection 一个重要启发：

工具不一定越多越好。更关键的是：工具输出是否稳定、状态是否可恢复、失败是否能形成下一步行动。

四、Self-Reflection 在代码生成 Agent 中怎么落地？

代码生成场景里，Self-Reflection 不应该每一步都触发，否则会浪费 token 并制造噪声。更合理的是在四类节点触发：

测试、编译、lint、类型检查失败多次修改后准备提交或生成 PR 前Agent 连续两轮没有进展，或重复执行相同命令工具返回空值、异常、权限拒绝、超时或不确定结果

1. 一个最小可用的代码生成反思循环

这个循环里，reflect() 不是让模型“随便想想”，而是强制它基于可观察证据输出结构化结果。

2. Reflection Prompt 模板

这个模板的关键是三点：

反思必须基于证据；
反思必须产出下一步行动；
反思必须有退出条件。

3. 代码生成中的五种 Self-Reflection 模式

模式	触发时机	反思输入	输出
失败驱动反思	test/build/lint 失败	stderr、失败用例、diff	根因与下一步修复
提交前自查	代码准备交付	diff、需求、测试结果	风险清单、补测建议
需求一致性反思	实现完成但需求复杂	用户需求、实现摘要	缺失功能、边界条件
代码审查反思	PR 前或多文件修改后	diff、架构规则	review comments
经验沉淀反思	修复成功后	问题、根因、修复、验证	memory/skill/playbook

其中“失败驱动反思”优先级最高，因为它绑定真实环境反馈；“提交前自查”次之，因为它可以降低明显低级错误；“经验沉淀反思”适合长期运行的团队级 Agent。

五、Self-Reflection 在故障排查 Agent 中怎么应用？

故障排查和代码生成不一样。代码生成的目标通常是“让测试通过”，故障排查的目标则是“定位根因，并给出安全修复方案”。因此，故障排查 Agent 的 Self-Reflection 更像 SRE 的 incident review。

1. 故障排查 Agent 的闭环

这里的 Self-Reflection 重点不是“我刚才答错了什么”，而是：

当前假设是否被证据支持？
有没有遗漏更高优先级的风险？
下一步诊断是否会破坏生产环境？
是否应该停止自动化并请求人工确认？

2. 故障排查 Reflection 输出结构

故障排查 Agent 一定要把“支持证据”和“反证”分开。否则它很容易过早锁定一个看似合理但错误的根因。

3. 适合故障排查的反思策略

第一种是“假设淘汰式反思”。Agent 每轮只能维护 2 到 4 个候选假设，每执行一个诊断动作后，必须更新假设评分，淘汰不再被证据支持的假设。

第二种是“风险门控式反思”。涉及生产写操作、重启、扩容、回滚、数据修复时，Agent 必须先反思风险，并给出 dry-run 或只读诊断方案。

第三种是“事故复盘式反思”。故障恢复后，Agent 将症状、根因、诊断路径、修复动作、验证命令、误判路径写入长期记忆，供未来 RAG 检索。

六、Self-Reflection 与 RAG / Memory 如何结合？

Self-Reflection 适合写入 Memory，但不能无脑写。否则长期记忆会变成“失败日志垃圾堆”。

推荐将反思记忆分成三类：

记忆类型	内容	生命周期
Episode Memory	某次任务的失败、修复、验证	短中期，可过期
Rule Memory	稳定的工程规则，如“本项目必须用 pnpm”	长期
Diagnostic Playbook	可复用排障流程	长期，但需版本化

写入记忆时建议使用如下 schema：

检索时，不要只做向量相似度。更合理的是：

Reflexion 研究强调把语言反思保存在 episodic memory 中用于后续决策；较新的 Self-Reflection 实证研究也指出，真实 Agent 需要把反思存储并在相似但不完全相同的问题中检索出来，而不是只在同一道题上重答。(开放评论)

七、工程实现：一个生产级 Self-Reflection 模块应该怎么设计？

1. 不要让模型直接“自评”，要让它“基于证据反思”

错误做法：

更好的做法：

2. Reflection 要结构化输出

不要让反思输出一大段自然语言。应强制 JSON schema，并做字段校验：

3. 反思之后必须有动作约束

Reflection 的结果只能进入几个分支：

4. 必须有停止条件

生产环境中，Self-Reflection 最危险的问题是“自我循环”。建议至少设置：

停止条件	说明
max_iterations	例如最多 5 到 8 轮
no_progress_count	连续两轮失败类型和错误栈不变
repeated_command	重复运行同一命令但无新信息
expanding_patch_scope	修改范围不断扩大
low_confidence	置信度低于阈值
destructive_action	涉及删除、迁移、重启、生产写入
cost_budget	超过 token、时间或工具调用预算

5. 通过 Hooks 把外部反馈注入 Agent

以 Claude Code 为例，可以用 PostToolUse 在 Edit 或 Write 后自动跑 lint/test，把失败反馈给 Agent；用 PreToolUse 阻断危险命令；用 Stop 或任务完成类 hook 阻止 Agent 在测试失败时结束。Claude Code Hooks 文档明确说明，Hooks 可在生命周期特定点执行，PreToolUse 可在工具执行前做决策控制，PostToolUse 可在工具完成后给 Claude 追加上下文或替换工具输出。(Claude Code)

示例：编辑后自动测试，并把失败变成反思输入。

实际使用时需要注意：PostToolUse 发生在工具已经执行之后，不能阻止已发生的文件写入或命令执行；如果要阻止危险动作，应使用 PreToolUse。(Claude Code)

八、代码生成 Agent 的完整实现蓝图

这套架构里，Self-Reflection 不是一个孤立 Prompt，而是连接了四件事：

环境反馈：测试、编译、日志、截图、监控
行为控制：权限、Hook、Sandbox、预算
知识沉淀：Memory、RAG、Skill、Runbook
交付验证：diff review、回归测试、用户确认

九、常见反模式

第一，空洞反思。Agent 只是说“我需要更加小心”，但没有证据、根因和下一步动作。

第二，过度反思。每次工具调用后都长篇复盘，导致成本高、上下文污染严重。

第三，自我验证。Agent 不跑测试，只说“代码现在应该可以工作”。代码场景必须使用编译器、测试框架、lint、运行时日志等外部验证。

第四，反思污染长期记忆。一次偶发错误被写成永久规则，后续任务不断误用。

第五，无退出条件。Agent 反复改同一段代码、跑同一个失败测试，最后越改越坏。

第六，绕过权限。为了“自动修复”，让 Agent 获得过大的 shell、文件、网络、生产系统权限。OpenCode 和 OpenClaw 这类工具都强调工具权限、sandbox 或安全默认值的重要性；OpenClaw README 甚至明确提醒入站 DM 是不可信输入，并建议非 main session 使用 sandbox。(OpenCode)

十、如何评估 Self-Reflection 是否真的有效？

可以从 Agent 执行指标和项目交付指标两层评估。

指标	解释
self-repair success rate	首次失败后，Agent 自修复成功比例
iterations to green	从失败到测试通过的平均轮数
no-progress loop rate	无进展循环比例
regression rate	修复一个问题后引入新问题的比例
tool hallucination rate	编造命令、文件、API、参数的比例
human intervention rate	需要人工接管的比例
reflection usefulness	反思是否包含证据、根因、下一步动作
memory reuse hit rate	历史反思被检索并成功复用的比例
cost per resolved issue	每个成功任务的 token、时间、工具调用成本

不要只看“Agent 最终有没有生成代码”。Self-Reflection 的价值在于降低失败后的人工介入成本，提高从失败反馈中恢复的概率。

十一、推荐落地方案

对于代码生成 Agent，我建议从轻到重分三阶段落地。

第一阶段：失败后反思。只在测试、构建、lint 失败时触发 Reflection，输出 JSON，驱动下一轮最小修复。

第二阶段：提交前反思。在最终交付前，根据 diff、需求、测试结果做一次代码审查式反思，检查遗漏需求、边界条件、安全风险和回归风险。

第三阶段：长期记忆反思。修复成功后，把“症状-根因-诊断-修复-验证”写入 Memory/RAG，并设置项目、版本、有效期和置信度。

对于故障排查 Agent，我建议从“只读诊断”开始，不要一开始就让 Agent 自动修生产。先让它做日志查询、指标分析、变更关联、假设淘汰和复盘沉淀。等只读诊断稳定后，再逐步开放低风险自动修复动作。

十二、总结

Self-Reflection 的本质是让 Agent 从“单次生成器”变成“可试错、可复盘、可修复、可沉淀”的工程系统。

在代码生成中，它让 Agent 能够根据编译器、测试、lint 和运行时反馈自我修复；在故障排查中，它让 Agent 能够基于证据更新假设、避免误判、沉淀事故经验。研究上的 Self-Refine、Reflexion 和 Self-Reflection experiments 证明了反思在测试时改进输出的潜力；工程上的 Claude Code Hooks、OpenCode 工具与权限、OpenHands 平台化运行环境、OpenClaw/Pi 的小核心可扩展架构，则展示了 Self-Reflection 真正落地所需的运行时基础设施。(arXiv)

一句话概括：

好的 Self-Reflection 不是“让模型多想一遍”，而是“让 Agent 每次失败都能基于证据变得更接近正确答案”。