SWE-agent 提交前审查机制：解读 review_on_submit_m 工具包与 `submit -f` 强制提交设计-开发者社区

SWE-agent 提交前审查机制：解读 review_on_submit_m 工具包与`submit -f`强制提交设计

【免费下载链接】SWE-agentSWE-agent takes a GitHub issue and tries to automatically fix it, using your LM of choice. It can also be employed for offensive cybersecurity or competitive coding challenges. [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/sw/SWE-agent

本篇文章围绕 SWE-agent 仓库中的 tools/review_on_submit_m 工具包展开，剖析这套"提交前审查（review on submit）"机制的定位、配置方式与底层实现原理。读完本文，你将掌握：为什么默认的submit会立即结束任务、review_on_submit_m如何把"提交"改造成"先审查再确认"的两阶段流程、submit -f为何是唯一触发真实提交的入口，以及如何结合 registry 变量自定义审查提示语。

一、背景：默认`submit`的"一锤定音"行为

在 SWE-agent 中，agent 解决一个 GitHub issue 后，需要调用一个特殊的submit命令来提交其修改并结束会话。默认的提交工具由 tools/submit/config.yaml 定义：

tools: submit: signature: "submit" docstring: "submits the current file" arguments: []

从源码结构看，submit是一个无参数的独立命令，一旦模型调用它，agent 就会立即进入提交流程。底层处理逻辑位于 sweagent/agent/agents.py 的handle_submission方法：

首先通过check_for_submission_cmd检测模型输出中是否包含<<SWE_AGENT_SUBMISSION>>标记（对应 sweagent/tools/tools.py）；
命中后读取容器内的/root/model.patch文件（该文件由git add -A && git diff --cached > /root/model.patch生成，见 sweagent/agent/agents.py）；
将 patch 内容写入step.submission，并把exit_status置为submitted，同时将step.done置为True，任务就此终结。

换言之，默认机制下模型一旦认为自己"改完了"就会立刻提交，缺少一道"自查、回归验证、清理测试文件"的缓冲环节。

二、review_on_submit_m：把"提交"改造成"审查+确认"

tools/review_on_submit_m/README.md 对该工具包的定位描述得非常直接：

Provides an alternative forsubmitthat does not immediately submit, but asks the agent to perform additional reviewing steps. Onlysubmit -fwill trigger the real submit.

核心设计思想是：

不立即提交：用review_on_submit_m替换默认submit后，模型调用submit并不会触发真正的提交，而是被引导去执行额外的审查步骤（重新跑复现脚本、清理临时文件、还原被改动的测试文件等）。
-f是唯一真实入口：只有submit -f（force）才会触发真实提交。这相当于把"提交"升级为一个显式的、需要二次确认的动作，杜绝模型草率收工。

该工具包在仓库历史中也有明确演进记录：docs/installation/changelog.md 提到旧版review_on_submit工具包已被review_on_submit_m取代。

三、工具包文件结构与 config.yaml 解析

review_on_submit_m是一个标准的 SWE-agent 工具包（tool bundle），目录下包含三个文件：

tools/review_on_submit_m/ ├── README.md # 功能说明 ├── config.yaml # 工具定义 └── install.sh # 安装脚本（当前为空）

其中 tools/review_on_submit_m/config.yaml 是关键，完整内容如下：

tools: submit: signature: "submit" docstring: "submits the current file" # Do not actually show the -f argument to the model, only # use it from the agent for submission after error

这短短几行透露出两个重要设计意图：

复用submit命令名：工具包重新定义了名为submit的工具，以覆盖（override）默认提交行为，因此当模型调用submit时，实际进入的是"审查流程"而非"立即提交"。
-f对模型不可见：注释明确指出，"不要真的把-f参数展示给模型，只允许 agent 在出错后使用它进行提交"。这意味着-f是一个"内部逃生通道"——当审查流程因为某种原因无法完成（例如模型反复提交失败）时，由 agent 框架侧强制执行真实提交，而不是让模型自由调用。这是防止模型"作弊式跳过审查"的关键约束。

对比默认的 tools/submit/config.yaml（arguments: []），review_on_submit_m的 config 中也没有显式声明arguments字段，且刻意不在签名与文档中暴露-f，进一步印证了"对模型隐藏强制提交参数"的设计。

四、如何启用：bundles 加载机制

在 SWE-agent 中，工具包通过agent.tools.bundles列表加载，加载逻辑由 sweagent/tools/bundle.py 的Bundle类实现：每个 bundle 必须包含config.yaml，其中声明的tools会被解析为Command对象，并最终合并进模型可见的命令列表（见 sweagent/tools/tools.py 的commands属性；同名工具重复定义会直接抛出ValueError）。

仓库的默认配置 config/default.yaml 正是这样组合的：

tools: bundles: - path: tools/registry - path: tools/edit_anthropic - path: tools/review_on_submit_m

使用要点：

tools/registry必须放在前面：review_on_submit_m的审查消息依赖 registry 提供的跨调用持久化状态（详见第五节），因此依赖关系上要求 registry 先被加载。
无需额外安装：该 bundle 的 install.sh 目前为空文件，安装阶段不会有额外副作用；ToolHandler._install_commands只会对存在install.sh的 bundle 执行source install.sh（见 sweagent/tools/tools.py）。
同样的组合也出现在多份基准配置中，例如 config/benchmarks/250212_sweagent_heavy_sbl.yaml、config/benchmarks/anthropic_filemap_multilingual.yaml、config/benchmarks/250525_anthropic_filemap_simple_review.yaml等，说明"提交前审查"是官方评测配置的默认一环。

五、registry 支撑：审查消息从哪来

review_on_submit_m本身没有bin/目录与可执行脚本，它的"审查提示"内容是通过registry 变量注入的。这正对应 docs/usage/adding_custom_tools.md 中的说明：registry 特别适合"需要在多次调用间维护状态"的复杂工具，review_on_submit_m正是这样一个"跟踪提交阶段"的工具。

5.1 registry_variables 配置项

ToolConfig.registry_variables（见 sweagent/tools/tools.py）允许在配置中预置一组键值对。在ToolHandler.reset时，这些变量会被序列化为 JSON 写入容器的/root/.swe-agent-env文件（见 sweagent/tools/tools.py），供后续任意工具调用读取。

5.2 SUBMIT_REVIEW_MESSAGES：审查提示模板

config/default.yaml 中给出了完整的配套配置：

registry_variables: USE_FILEMAP: 'true' SUBMIT_REVIEW_MESSAGES: - | Thank you for your work on this issue. Please carefully follow the steps below to help review your changes. 1. If you made any changes to your code after running the reproduction script, please run the reproduction script again. If the reproduction script is failing, please revisit your changes and make sure they are correct. If you have already removed your reproduction script, please ignore this step. 2. Remove your reproduction script (if you haven't done so already). 3. If you have modified any TEST files, please revert them to the state they had before you started fixing the issue. You can do this with `git checkout -- /path/to/test/file.py`. Use below <diff> to find the files you need to revert. 4. Run the submit command again to confirm. Here is a list of all of your changes: <diff> {{diff}} </diff>

这份审查清单的设计逻辑非常清晰，也解释了review_on_submit_m想要防住的四类典型问题：

步骤	审查内容	目的
1	修改后重新运行复现脚本	确保修复在最终状态下依然有效
2	删除复现脚本	避免把临时调试文件一并提交
3	还原被改动的测试文件（`git checkout --`指定路径）	防止污染测试套件，保证提交"最小化"
4	再次运行`submit`确认	显式二次确认，形成两阶段流程

消息末尾的<diff>块使用 Jinja 变量{{diff}}，渲染时会注入当前累积变更（对应配置中 history/templates 对 diff 的传递），让模型能够对照完整变更清单逐一核对。各版本基准配置（如 config/benchmarks/250212_sweagent_heavy_sbl.yaml）通过 YAML 锚点&submit_review_messages/*submit_review_messages复用了同一份审查消息，保证多 agent 配置下提示语一致。

5.3 registry 的读写实现

registry 的持久化实现在 tools/registry/lib/registry.py：

默认文件路径为/root/.swe-agent-env，可通过SWE_AGENT_ENV_FILE环境变量覆盖；
registry.get(key, default)支持"先查 registry 文件、回退到环境变量、再回退到默认值"的三级查找；
registry[key] = value采用"读文件 → 更新字典 → 原子写回"的方式，保证多次工具调用之间状态连续。

正因如此，SUBMIT_REVIEW_MESSAGES（一个字符串列表）可以完整地跨调用传递，而不必担心子进程环境变量丢失的问题。

六、底层提交链路：从`submit`到`/root/model.patch`

无论使用默认 submit 还是 review_on_submit_m，最终的真实提交都收敛到同一条链路，理解这条链路有助于明白-f存在的意义：

提交标记检测：ToolHandler.check_for_submission_cmd扫描模型输出中的<<SWE_AGENT_SUBMISSION>>（见 sweagent/tools/tools.py）；
强制提交路径：handle_submission(step, observation="", force_submission=True)允许在"未检测到提交标记"时也强制执行提交逻辑（见 sweagent/agent/agents.py）。force_submission的典型使用场景是环境意外死亡后的自动收尾（autosubmit）；
读取 patch：提交内容来自容器内/root/model.patch；若文件缺失，则记录警告并放弃本次提交；
标记状态：成功读取非空 patch 后，step.submission被赋值，exit_status变为submitted，step.done = True，agent 主循环随即终止。

对应的测试用例见 tests/test_agent.py：test_run_autosubmit与test_successful_submission分别验证了"强制提交"与"正常提交"两种路径下exit_status、submission字段的取值。

由此可以看出：submit -f的"真实提交"在框架层面的等价含义是——绕过审查消息的周转，直接让handle_submission拿到 patch 并终止任务。而普通submit之所以"不立即提交"，正是因为它先把审查清单（SUBMIT_REVIEW_MESSAGES）喂回给模型，等待模型完成自查后再次调用submit。

七、自定义与使用建议

7.1 复用该 bundle

在自定义配置中启用提交前审查，只需在agent.tools.bundles中加入tools/review_on_submit_m并预置审查消息，参考 docs/usage/adding_custom_tools.md 的写法：

agent: tools: bundles: - path: tools/registry - path: tools/edit_anthropic - path: tools/review_on_submit_m registry_variables: SUBMIT_REVIEW_MESSAGES: - | 你的自定义审查清单…… parse_function: type: function_calling

7.2 实践要点

审查清单按场景裁剪：SWE-bench 类任务强调"最小变更、不碰测试文件"，因此默认清单要求还原测试文件；若你的场景允许修改测试，可自行调整第 3 条。
不要向模型暴露-f：这是该 bundle 的设计红线。-f属于框架内部通道（如失败兜底与 autosubmit），模型不应知道它的存在，否则审查步骤会被模型"一步跳过"。
保持 bundle 顺序：tools/registry需先于review_on_submit_m加载，因为审查消息的读取依赖 registry 环境。

八、总结

review_on_submit_m是 SWE-agent 工具包体系中一个"小而关键"的设计：它没有庞大的可执行脚本，而是通过命令名覆盖 + registry 注入审查消息 + 隐藏强制提交参数三个机制，把默认的"一键提交"升级为"审查—确认"的两阶段流程。结合config/default.yaml中的SUBMIT_REVIEW_MESSAGES清单与 sweagent/agent/agents.py 的提交处理逻辑，你可以清楚地看到：所谓"review on submit"，本质是在模型自以为完成时，把一份结构化自查清单重新塞回对话，让最终落到/root/model.patch的变更经得起复现与最小化检验。对于追求提交质量、需要防御模型"草率收工"的评测与自动化修复场景，这是一套开箱即用的参考实现。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

SWE-agent 提交前审查机制：解读 review_on_submit_m 工具包与 `submit -f` 强制提交设计