Trae-Agent的Patch逻辑

Trae Agent Patch 生成与选择机制

概述

Trae Agent 项目采用多 Patch 生成 + Selector Agent 选择的两阶段策略来解决软件工程问题。本文档详细分析这一机制的实现原理和代码结构。

---

一、整体流程

┌─────────────────────────────────────────────────────────────────────────────┐
│                         Phase 1: Patch 生成阶段                              │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  1. 运行多次 TraeAgent（每次独立执行）                                       │
│     - 相同的问题描述                                                         │
│     - 相同的代码库                                                           │
│     - 不同的随机种子或温度参数                                                │
│     - 生成多个候选 Patch                                                     │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  2. 收集候选 Patch                                                           │
│     - 保存每个 Patch 的 diff                                                 │
│     - 记录回归测试结果（可选）                                               │
│     - 生成 candidate_patches.jsonl                                          │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                      Phase 2: Patch 选择阶段                                 │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  3. Selector Agent 评估                                                      │
│     - 分析每个 Patch 的正确性                                                │
│     - 在沙箱中验证（可选）                                                   │
│     - 选择最佳 Patch                                                         │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  4. 多数投票（可选）                                                         │
│     - 多次运行 Selector Agent                                                │
│     - 统计选择频率                                                           │
│     - 选择得票最高的 Patch                                                   │
└─────────────────────────────────────────────────────────────────────────────┘

---

二、Phase 1: Patch 生成

2.1 多次运行生成多 Patch

原理：通过多次独立运行 TraeAgent，利用 LLM 的随机性生成不同的解决方案。

# 伪代码示意
def generate_multiple_patches(instance, num_candidates=10):
    """生成多个候选 Patch"""
    candidates = []
    
    for i in range(num_candidates):
        # 每次使用略微不同的参数
        config = TraeAgentConfig(
            model=model,
            temperature=0.5 + i * 0.05,  # 略微调整温度
            max_steps=200,
        )
        
        agent = TraeAgent(config)
        execution = await agent.execute_task()
        
        # 提取生成的 Patch
        patch = extract_patch_from_execution(execution)
        candidates.append({
            "instance_id": instance["instance_id"],
            "patch": patch,
            "regression": [],  # 回归测试结果
        })
    
    return candidates

2.2 候选 Patch 数据格式

文件 : evaluation/patch_selection/example/example.jsonl

{
    "instance_id": "astropy__astropy-14369",
    "issue": "问题描述...",
    "patches": [
        "patch diff 1",
        "patch diff 2",
        ...,
        "patch diff N"
    ],
    "success_id": [
        1,
        0,
        ...,
        1
    ],
    "regressions": [
        [],           // Patch 1 通过所有回归测试
        ["test_a"],   // Patch 2 有回归测试失败
        ...,
        []            // Patch N 通过所有回归测试
    ]
}

字段	说明
instance_id	问题实例 ID
issue	问题描述
patches	候选 Patch 列表（diff 格式）
success_id	是否正确（1=正确，0=错误）
regressions	回归测试失败的测试名列表

---

三、Phase 2: Patch 选择

3.1 入口: selector.py

文件 : evaluation/patch_selection/selector.py

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--candidate_path", required=True)  # 候选 Patch 文件
    parser.add_argument("--num_candidate", type=int, default=10)
    parser.add_argument("--group_size", type=int, default=10)
    parser.add_argument("--majority_voting", action="store_true")
    args = parser.parse_args()
    
    # 加载候选 Patch
    candidate_dic = {}
    with open(args.candidate_path, "r") as file:
        for line in file.readlines():
            candidate = json.loads(line.strip())
            candidate_dic[candidate["instance_id"]] = candidate
    
    # 创建评估器
    evaluation = SelectorEvaluation(
        llm_config,
        args.num_candidate,
        args.max_retry,
        args.max_turn,
        args.log_path,
        args.output_path,
        args.patches_path,
        instance_list,
        candidate_dic,
        tools_path,
        args.statistics_path,
        args.group_size,
        majority_voting=args.majority_voting,
    )
    
    # 运行评估
    evaluation.run_all(max_workers=args.max_workers)

3.2 分组处理策略

文件 : evaluation/patch_selection/trae_selector/selector_evaluation.py

def run_instance(
    instance,
    candidate_log,
    num_candidate: int,
    group_size: int,
    ...
):
    """
    将候选 Patch 分组处理
    例如：50 个候选，group_size=10，分为 5 组
    """
    groups = []
    for i in range(0, num_candidate, group_size):
        this_group = {
            "instance_id": candidate_log["instance_id"],
            "issue": candidate_log["issue"],
            "patches": candidate_log["patches"][i:i + group_size],
            "regressions": candidate_log["regressions"][i:i + group_size],
            "success_id": candidate_log["success_id"][i:i + group_size],
        }
        groups.append(this_group)
    
    # 每组独立选择
    for group_id, group in enumerate(groups):
        run_instance_by_group(
            instance=instance,
            candidate_log=group,
            group_id=group_id,
            num_groups=len(groups),
            ...
        )

3.3 Patch 预处理流程

def run_instance_by_group(...):
    """单组 Patch 处理流程"""
    
    # 1. 构建候选列表
    candidate_list = []
    for idx in range(len(candidate_log["patches"])):
        cleaned_patch = clean_patch(candidate_log["patches"][idx])
        is_success_regression = len(candidate_log["regressions"][idx]) == 0
        
        candidate_list.append(CandidatePatch(
            id=idx,
            patch=candidate_log["patches"][idx],
            cleaned_patch=cleaned_patch,
            is_success_regression=is_success_regression,
            is_success_patch=candidate_log["success_id"][idx],
        ))
    
    # 2. 回归测试过滤
    candidate_list_regression = [
        c for c in candidate_list if c.is_success_regression
    ]
    if len(candidate_list_regression) > 0:
        candidate_list = candidate_list_regression
    
    # 3. Patch 去重
    candidate_list_deduplication = []
    cleaned_candidate_set = set()
    for candidate in candidate_list:
        if candidate.cleaned_patch not in cleaned_candidate_set:
            cleaned_candidate_set.add(candidate.cleaned_patch)
            candidate_list_deduplication.append(candidate)
    candidate_list = candidate_list_deduplication

3.4 CandidatePatch 数据结构

文件 : evaluation/patch_selection/trae_selector/selector_agent.py

class CandidatePatch:
    def __init__(
        self,
        id,                           # Patch ID
        patch,                        # 原始 Patch
        cleaned_patch,                # 清理后的 Patch（用于去重）
        is_success_regression,        # 是否通过回归测试
        is_success_patch,             # 是否正确（Ground Truth）
    ):
        self.id = id
        self.patch = patch
        self.cleaned_patch = cleaned_patch
        self.is_success_regression = is_success_regression
        self.is_success_patch = is_success_patch

---

四、Selector Agent 核心逻辑

4.1 系统提示词设计

文件 : evaluation/patch_selection/trae_selector/selector_agent.py

def build_system_prompt(candidate_length: int) -> str:
    return f"""\
# ROLE: Act as an expert code evaluator. 
Given a codebase, an github issue and **{candidate_length} candidate patches** 
proposed by your colleagues, your responsibility is to **select the correct one** 
to solve the issue.

# WORK PROCESS:
1. Understand the Issue and Codebase
   - 阅读问题描述
   - 查看代码库上下文

2. Analyze the Candidate Patches
   - 分析每个 Patch 的逻辑
   - 对比问题描述和代码变更

3. Validate Functionality (Optional but Recommended)
   - 编写单元测试验证
   - 运行测试检查副作用

4. Select the Best Patch
   - 选择最佳解决方案

# FINAL REPORT:
### Status: succeed
### Result: Patch-x
### Analysis: [解释为什么 Patch-x 是正确的]

# IMPORTANT TIPS:
1. Never avoid making a selection.
2. Do not propose new patches.
3. There must be at least one correct patch.
"""

4.2 SelectorAgent 执行流程

class SelectorAgent:
    def __init__(
        self,
        llm_config: ModelConfig,
        sandbox: Sandbox,
        project_path: str,
        issue_description: str,
        candidate_list: list[CandidatePatch],
        max_turn: int = 50,
    ):
        self.llm_config = llm_config
        self.sandbox = sandbox
        self.candidate_list = candidate_list
        self.max_turn = max_turn
        
        # 初始化工具
        self.tools = [
            tools_registry["bash"](model_provider=llm_config.model_provider.provider),
            tools_registry["str_replace_based_edit_tool"](...),
        ]
        
        # 构建初始消息
        self.initial_messages = [
            LLMMessage(role="system", content=build_system_prompt(len(candidate_list)))
        ]
        
        # 添加用户提示（包含所有候选 Patch）
        user_prompt = f"""
[Codebase path]: {project_path}

[Github issue description]:

{issue_description}

[Candidate Patches]:
"""
        for idx, candidate in enumerate(candidate_list):
            user_prompt += f"\nPatch-{idx + 1}:\n```\n{candidate.patch}\n```"
        
        self.initial_messages.append(LLMMessage(role="user", content=user_prompt))

4.3 选择执行循环

def run(self):
    """Selector Agent 主循环"""
    messages = self.initial_messages
    turn = 0
    
    # 默认选择第一个
    final_id = self.candidate_list[0].id
    final_patch = self.candidate_list[0].patch
    
    while turn < self.max_turn:
        turn += 1
        
        # 1. 调用 LLM
        llm_response = self.llm_client.chat(messages, self.llm_config, self.tools)
        
        # 2. 检查是否完成选择
        match = re.search(
            r"Status:\s*(success|succeed).*\n.*Result:\s*Patch-(\d+)",
            llm_response.content,
        )
        
        if match:
            # 提取选择的 Patch
            selected_idx = int(match.group(2)) - 1
            final_id = self.candidate_list[selected_idx].id
            final_patch = self.candidate_list[selected_idx].patch
            break
        
        # 3. 执行工具调用（查看代码、运行测试等）
        tool_results = parse_tool_response(llm_response, self.sandbox_session)
        messages.extend(tool_results)
    
    return final_id, final_patch

---

五、多数投票机制

5.1 实现逻辑

文件 : evaluation/patch_selection/trae_selector/selector_evaluation.py

def run_instance_by_group(..., majority_voting=True):
    """多数投票选择"""
    
    if majority_voting:
        final_id_list = []
        final_patch_list = []
        
        # 多次运行 Selector Agent
        for idx in range(num_candidate):
            select_agent = SelectorAgent(
                llm_config=llm_config,
                sandbox=sandbox,
                project_path=project_path,
                issue_description=instance["problem_statement"],
                candidate_list=candidate_list,
                max_turn=max_turn,
            )
            
            final_id, final_patch = select_agent.run()
            final_id_list.append(final_id)
            final_patch_list.append(final_patch)
            
            # 提前终止：如果某个 Patch 超过半数
            from collections import Counter
            if max(Counter(final_id_list).values()) > num_candidate / 2:
                break
        
        # 统计投票结果
        counter = Counter(final_id_list)
        max_count = max(counter.values())
        most_common_ids = [elem for elem, count in counter.items() if count == max_count]
        
        # 选择得票最高的
        final_id = most_common_ids[0]
        final_patch = final_patch_list[final_id_list.index(final_id)]
    else:
        # 单次选择
        select_agent = SelectorAgent(...)
        final_id, final_patch = select_agent.run()

5.2 投票流程图

运行 1: Selector Agent → 选择 Patch-3
运行 2: Selector Agent → 选择 Patch-3
运行 3: Selector Agent → 选择 Patch-1
运行 4: Selector Agent → 选择 Patch-3  ← 超过半数，提前终止

投票统计:
- Patch-3: 3 票 (75%)
- Patch-1: 1 票 (25%)

最终结果: Patch-3

---

六、关键设计特点

6.1 为什么需要 Selector Agent？

问题	解决方案
多个 Patch 哪个最好？	Agent 智能分析
需要理解代码上下文	提供工具查看代码
需要验证正确性	可运行测试验证
避免人工判断	自动化选择流程

6.2 分组策略的优势

# 50 个候选，直接处理 → 上下文过长，LLM 难以处理
# 50 个候选，group_size=10 → 分 5 组，每组 10 个

Group 0: Patch 0-9   → 选择 Patch-3
Group 1: Patch 10-19 → 选择 Patch-12
Group 2: Patch 20-29 → 选择 Patch-25
Group 3: Patch 30-39 → 选择 Patch-31
Group 4: Patch 40-49 → 选择 Patch-42

最终轮: Patch [3, 12, 25, 31, 42] → 选择最佳

6.3 预处理流程的作用

步骤	目的
回归测试过滤	排除有明显副作用的 Patch
Patch 去重	减少重复分析，提高效率
清理格式	标准化 Patch 便于比较

---

七、使用示例

7.1 生成候选 Patch

# 运行多次 TraeAgent 生成 Patch
for i in {1..10}; do
    trae-cli run "Fix the bug" --output patch_$i.diff
done

# 组合成 candidate_patches.jsonl
python combine_patches.py --patches patch_*.diff --output candidates.jsonl

7.2 运行 Patch 选择

python evaluation/patch_selection/selector.py \
    --instances_path "swebench-verified.json" \
    --candidate_path "candidates.jsonl" \
    --result_path "./results" \
    --num_candidate 10 \
    --group_size 10 \
    --max_workers 10 \
    --config_file trae_config.yaml \
    --model_name claude-sonnet \
    --majority_voting

7.3 查看结果

# 分析选择结果
python evaluation/patch_selection/analysis.py --result_path ./results

# 输出结构
results/
├── log/              # LLM 交互日志
├── output/           # 标准输出
├── patch/            # 选中的 Patch
└── statistics/       # 统计结果

---

八、总结

阶段	核心组件	关键设计
Patch 生成	TraeAgent（多次运行）	利用 LLM 随机性
候选管理	candidate_patches.jsonl	结构化存储
预处理	回归测试 + 去重	过滤低质量 Patch
智能选择	Selector Agent	LLM 分析 + 工具验证
结果确认	多数投票	提高选择稳定性

核心思想：通过"生成多样性 + 智能选择"的组合，提高解决复杂软件工程问题的成功率。

---

最后更新: 2026-03-16