🔬 SWE-agent 深度分析

Princeton NLP · 软件工程 Agent 框架 · Shell-First 架构范式

1. 项目概览与核心理念

SWE-agent 是 Princeton NLP 团队开发的软件工程 Agent，专为自动解决 GitHub issue 设计。它在 SWE-bench 基准上取得了领先成绩，核心论文 SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering 提出了一个关键洞察：

具体来说，SWE-agent 的 ACI 设计体现在：

• str_replace_editor — 专用的文件编辑命令，而非裸 bash
• 状态命令 (_state_anthropic) — 隐式收集环境状态（diff、cwd 等），注入观察模板
• Review-on-Submit — 提交前自动审查，引导模型检查变更质量
• Blocklist 过滤 — 禁止交互式命令（vim、gdb 等），避免 Agent 陷入

ACI 设计 Bundle 工具 Blocklist 安全 Review-on-Submit

2. 架构全景与核心循环

核心主循环 (DefaultAgent.step → forward_with_handling)

# 伪代码：DefaultAgent 核心循环
def run(env, problem_statement, output_dir):
    self.setup(env, problem_statement, output_dir)   # 安装工具 + 构造初始历史
    step_output = StepOutput()
    while not step_output.done:
        step_output = self.step()                      # 单步

def step():
    # 1. 历史处理 → messages
    messages = self.messages  # property: history → chain(history_processors)
    # 2. 前向推理 + 错误处理
    step_output = self.forward_with_handling(messages)
    # 3. 更新历史 & 轨迹
    self.add_step_to_history(step_output)
    self.add_step_to_trajectory(step_output)
    return step_output

def forward_with_handling(history):
    # 重试循环：格式错误/被阻止的命令/bash语法错误 → 重新查询
    n_format_fails = 0
    while n_format_fails < max_requeries:
        try:
            return self.forward(history)    # 模型查询 → 解析 → 执行 → 提交检查
        except FormatError:
            n_format_fails += 1
            history = requery_with_error_template(...)
        except _BlockedActionError:
            n_format_fails += 1
            history = requery_with_error_template(...)
        except BashIncorrectSyntaxError:
            n_format_fails += 1
            history = requery_with_shell_check_template(...)
        except CommandTimeoutError:
            return autosubmit(...)
        except ContextWindowExceededError:
            return autosubmit(...)
        except CostLimitExceededError:
            return autosubmit(...)

def forward(history):
    output = model.query(history)               # LLM 推理
    thought, action = tools.parse_actions(output) # 解析 thought + action
    step = handle_action(step)                   # 执行 + 状态收集
    return handle_submission(step)               # 检查是否提交

关键设计特点：

• 双重存储：history（发送给 LLM 的消息列表）和 trajectory（完整的执行轨迹，含所有状态）分开维护
• 重试不污染历史：格式错误时，错误的尝试记入 trajectory 但不写入 history，模型看到的是纠正后的上下文
• 错误分级：格式错误 → 重试；超时/上下文溢出/成本超限 → 自动提交；被阻止的命令 → 重试
• 连续超时计数：_n_consecutive_timeouts，达到阈值则终止
• 总执行时间限制：total_execution_timeout（默认 1800s），跨步骤累计

3. 工具系统：Bundle + Command 架构

SWE-agent 的工具系统是其最独特的设计之一。它不使用传统的 Python 函数工具，而是通过 Bundle 机制将 shell 脚本包装为 LLM 可调用的工具。

Bundle 机制详解

每个 Bundle 是一个独立目录，包含：

# tools/edit_anthropic/config.yaml
tools:
  str_replace_editor:
    signature: |
      str_replace_editor <command> <path> [<file_text>] [<view_range>] ...
    docstring: >
      Custom editing tool for viewing, creating and editing files
      * view: cat -n 显示; directory 列出2层
      * create: 创建新文件
      * str_replace: 精确替换（old_str → new_str）
      * insert: 在指定行后插入
      * undo_edit: 撤销上次编辑
    arguments:
      - name: command
        type: string
        enum: ["view", "create", "str_replace", "insert", "undo_edit"]
        required: true
      - name: path
        type: string
        required: true
      - name: old_str / new_str / insert_line / view_range ...
state_command: "_state_anthropic"

Bundle 的安装流程：

1. _upload_bundles() — 将整个目录上传到容器的 /root/tools/{name}/
2. 执行 install.sh（如果存在）
3. 将 bin/ 加入 PATH
4. _check_available_commands() — 验证所有命令可用

str_replace_editor — ACI 的核心工具

这是 SWE-agent 最关键的 ACI 创新。传统的 bash 编辑（sed/awk）对 LLM 来说太脆弱——特殊字符、转义、多行处理都是雷区。str_replace_editor 提供了 5 个子命令：

Review-on-Submit — 提交前审查

submit 命令不是一次性提交，而是多阶段审查流程：

# submit 命令执行流程
1. git add -A && git diff --cached > /root/model.patch
2. 检查 SUBMIT_STAGE（从 registry 读取）
3. 如果 STAGE < len(SUBMIT_REVIEW_MESSAGES):
   - 用 diff 填充审查消息模板
   - 输出审查消息（不提交！）
   - SUBMIT_STAGE += 1
   - exit(0) → Agent 看到 "请检查你的变更..."
4. 如果 STAGE == len(审查消息):
   - 输出 <<SWE_AGENT_SUBMISSION>> 标记
   - 真正提交

默认审查消息会要求 Agent：

1. 重新运行复现脚本确认修复
2. 删除复现脚本
3. 还原测试文件的修改
4. 再次 submit 确认

多阶段提交 审查机制

Blocklist — 安全网

blocklist = ["vim", "vi", "emacs", "nano", "nohup", "gdb", "less", "tail -f", "python -m venv", "make"]
blocklist_standalone = ["python", "python3", "ipython", "bash", "sh", "/bin/bash", ...]
block_unless_regex = {"radare2": r"\b(?:radare2)\b.*\s+-c\s+.*"}  # 只允许非交互用法

三层过滤机制：前缀匹配 → 精确匹配 → 条件放行。这比简单黑名单更灵活。

4. 输出解析器：8 种解析策略

SWE-agent 提供了 8 种解析器，是所有 Agent 框架中最丰富的。这反映了它对"模型输出 → 可执行动作"这一转化环节的极致关注。

解析器架构的精妙之处：

• 统一接口：所有解析器返回 (thought, action) 元组，后续处理完全一致
• 参数验证：FunctionCallingParser 和 XMLFunctionCallingParser 会检查必需参数和多余参数
• invoke_format：解析结果通过 command.invoke_format 格式化为最终 shell 命令
• 引号处理：_should_quote() 智能决定参数是否需要 shlex.quote
• 格式错误模板：每种解析器都有定制的错误提示模板，用 Jinja2 渲染

5. 历史处理器：上下文工程核心

SWE-agent 的 HistoryProcessor 链是它上下文工程的核心。多个处理器可以串联，按顺序对 history 列表做变换。

CacheControlHistoryProcessor — Prompt Caching 优化

这是 SWE-agent 针对 Anthropic Claude 的特别优化。它的工作原理：

# 在 history 的最后 N 条 user/tool 消息上添加 cache_control 标记
# Anthropic API 会缓存到标记位置，下次请求如果前缀相同则命中缓存
{
  "role": "user",
  "content": [{
    "type": "text",
    "text": "...",
    "cache_control": {"type": "ephemeral"}  ← 标记缓存断点
  }]
}

last_n_messages=2 意味着缓存断点在倒数第二条 user 消息处。这样每轮对话只有新的观察和动作需要重新处理，系统提示 + 早期历史都能命中缓存。

LastNObservations — 经典上下文窗口管理

# 论文中的经典配置：只保留最近 5 个观察
history_processors:
  - type: last_n_observations
    n: 5

# 实现细节：
# - 旧的观察替换为 "Old environment output: (n lines omitted)"
# - polling=1: 每步都更新（默认）
# - polling=5: 每 5 步更新一次，减少缓存失效
# - 支持 always_keep_output_for_tags / always_remove_output_for_tags 标签

注释中也指出：现代模型上下文窗口越来越大，这个处理器不再总是必需。但它展示了 SWE-agent 对 token 经济学的精细控制。

6. RetryAgent 与 Reviewer 系统

SWE-agent 的 RetryAgent 是 Agent 框架中少有的"多次尝试 + 质量评估"机制。

两种 RetryLoop 实现

Reviewer 的评分逻辑：

# Reviewer 评分 = 多次采样的均值 - 惩罚 - 标准差调整
scores = [self.interpret(answer) for answer in answers]  # 从 LLM 回复提取分数
accept = mean(scores) - penalty
if reduce_by_std > 0:
    accept -= std(scores) * reduce_by_std  # 保守化

# TrajectoryFormatter: 将轨迹格式化为文本供 Reviewer 阅读
# 支持 filter（过滤特定动作）和 output_filter（过滤特定输出）

7. Action Sampler：多路径决策

Action Sampler 是 SWE-agent 的另一个独特设计——在每一步，不只是问一次 LLM，而是采样多个候选动作，然后选择最好的。

# 流程
1. model.query(history, n=2) → 2 个候选
2. 解析每个候选的 thought + action
3. 构造 "同事讨论" 消息：
   "Your colleagues had the following ideas:
    Thought (colleague 0): ...
    Proposed Action (colleague 0): ...
    Thought (colleague 1): ...
    Please summarize and choose one."
4. model.query(history + discussion) → 最终动作

# 流程
1. model.query(history, n=4~10) → 候选集
2. 去重 + 过滤不可解析的
3. 如果候选涉及 edit 操作，增加采样量
4. 锦标赛：
   best = candidates[0]
   for i in 1..n:
     result = compare(best, candidates[i])
     if result == "second":
       best = candidates[i]
5. 返回 best

BinaryTrajectoryComparison 的比较提示词设计很有趣：

<thought1>...</thought1>
<action1>...</action1>
<thought2>...</thought2>
<action2>...</action2>

Please compare the two actions in detail.
Which action should we take?
The last line MUST be "first" or "second".

这种设计确保了模型输出可被确定性解析（interpret 函数只看最后一行的 first/second）。

8. SWE-ReX 环境层

SWE-agent 的环境完全由 SWE-ReX 运行时驱动，这是一个独立的 Docker 容器管理框架。

# 环境初始化流程
1. deployment.start()         → 启动 Docker 容器
2. runtime.create_session()   → 创建 bash session（source .bashrc）
3. set_env_variables()        → 设置 LANG, PAGER 等
4. _copy_repo()               → 将仓库克隆到容器
5. _reset_repository()        → git checkout base_commit + git clean
6. post_startup_commands      → 执行额外初始化命令

# 命令执行
communicate(input, timeout, check) →
  runtime.run_in_session(BashAction(command, timeout, check))
  → 返回 output + exit_code
  → check="raise" 时，非零退出码抛出 RuntimeError 并 close()

注意 communicate() 的 check 参数有三个级别：ignore（不检查退出码）、warn（警告但不中断）、raise（抛出错误并关闭容器）。这种渐进式错误处理让 Agent 能在大多数情况下继续运行。

9. 提示词工程与模板系统

SWE-agent 的提示词完全由 Jinja2 模板 驱动，模板本身是 YAML 配置的一部分。

TemplateConfig — 消息模板体系

class TemplateConfig:
    system_template: str              # 系统提示
    instance_template: str            # 初始用户消息（含问题描述）
    next_step_template: str           # 每步观察模板
    next_step_truncated_observation_template: str  # 观察被截断时
    next_step_no_output_template: str              # 无输出时
    strategy_template: str | None     # 策略提示（可选）
    shell_check_error_template: str   # bash 语法错误提示
    command_cancelled_timeout_template: str  # 命令超时提示
    demonstration_template: str | None  # 演示模板
    demonstrations: list[Path]          # 演示文件路径
    put_demos_in_history: bool          # 演示放入历史 vs 单条消息
    max_observation_length: int = 100000  # 观察截断阈值

default.yaml 的实际提示词

# System prompt（极简）
"You are a helpful assistant that can interact with a computer to solve tasks."

# Instance template（核心提示）
"""
<uploaded_files>{{working_dir}}</uploaded_files>
I've uploaded a python code repository in the directory {{working_dir}}.
Consider the following PR description:

<pr_description>{{problem_statement}}</pr_description>

Can you help me implement the necessary changes?
Follow these steps:
1. Find and read code relevant to the <pr_description>
2. Create a script to reproduce the error and execute it
3. Edit the sourcecode to resolve the issue
4. Rerun your reproduce script and confirm the error is fixed
5. Think about edgecases
"""

# Next step template
"OBSERVATION:\n{{observation}}"

关键设计决策：

• 极简系统提示：不把工具文档放在 system prompt 里，而是靠 Function Calling 的工具定义
• 结构化问题描述：用 XML 标签包裹（<pr_description>、<uploaded_files>），帮助模型定位关键信息
• 分步指导：instance_template 包含明确的 5 步工作流
• 观察截断：100KB 截断 + 专用模板提醒模型用更短的命令
• 演示系统：支持从 .yaml/.json 加载历史轨迹作为 few-shot

格式字典 (_get_format_dict)

模板变量来源极其丰富：

{
    "command_docs": tools.config.command_docs,    # 自动生成的工具文档
    **tools.config.env_variables,                  # 环境变量
    "problem_statement": ...,                      # 问题描述
    "repo": env.repo.repo_name,                    # 仓库名
    **problem_statement.get_extra_fields(),         # 问题特有字段
    "observation": step.observation,                # 当前观察
    "max_observation_length": ...,                  # 截断阈值
    **step.state,                                   # 环境状态（diff, cwd 等）
}

10. 与同类项目对比

核心差异分析

11. 关键洞察与设计取舍

分析时间：2026-05-17 · 源码版本：swe-agent main branch · 基于 100 个 Python 文件的深度阅读