SWE-Touch 这个基准把编码代理评测中的关键问题直接放在台面上当用户已经触碰过代码之后编码代理还能不能继续把任务做完。这里所说的“触碰”不是指用户输入一行自然语言需求而是指用户已经在仓库里改过接口、写过测试、调过参数、修过局部逻辑甚至留下了一部分没有完成的实现然后代理才被请进来接手。大多数编码代理评测会让代理从干净的仓库快照开始独立修改代码这种方式在科研上容易复现却低估了真实开发里最常出现的衔接成本。本文围绕 SWE-Touch 的评测视角展开先说明它在测什么再拆解用户触碰代码后的典型失败模式提供一个小型可复现实验最后给出团队日常使用 Coding Agent 时的验收清单与排查路径。1. 从“独立解题测评”到“协作衔接测评”1.1 编码代理评测基准通常怎么工作讨论编码代理能力绕不开 SWE-bench 这类基准。它们通常从真实开源仓库抽取 issue把修复该 issue 的 PR 所关联的测试作为验证集。评测时给代理一份修复前的代码快照和 issue 描述代理自行定位文件、修改代码、运行测试。这类基准的价值在于能用自动化测试统一比较不同代理在同一批任务上的表现。后续出现的变体例如经过人工验证的精选子集主要改进任务质量和评测公平性但评测基本形态没有变代理面对的是一片相对安静的代码库仓库里没有用户刚刚留下的明显改动。1.2 “干净起点”隐藏的假设传统基准的关键词是“干净起点”。在任务开始时代码库处于 issue 修复前的原始状态用户没有提前做过局部改动。这意味着它衡量的是代理从 0 到 1 的独立能力定位根因、设计方案、实施修改、跑通测试全部由代理自己完成。但真实研发场景通常不是这样。真实 issue 出现时代码库里往往已经有用户留下的各种痕迹用户已经修改了一部分代码只希望代理处理剩余分支。用户补了一个测试希望代理实现能满足这个测试。用户改完公共接口后只差调用方没更新。用户刚修完另一个相关 bug文件与当前任务有重叠。如果代理只擅长从干净起点开始遇到这些场景就会失灵甚至主动破坏用户已经写好的部分。1.3 SWE-Touch 的评测转向用户触碰之后SWE-Touch 从名字上就能看出它的评测出发点。SWE 指向软件工程任务Touch 则强调用户对代码的人工改动。它研究的不再是“代理独立解决 issue”而是“用户已经触碰代码之后代理如何衔接”。这类评测通常不再只关心最终测试是否通过而是额外检查代理是否感知并保留了用户改动。代理是否在用户留下的半成品上继续正确实现。代理是否守住了测试文件没有为了通过测试反过来修改测试。代理是否避免重复修改、覆盖或制造冲突。这样设计的原因并不难理解。今天的编码代理已经从“能完成独立小任务”演进到“开发者旁边的协作者”。协作的基本前提是双方共享同一个代码状态。用户动了代码代理必须感知到用户没有写清楚的细节代理要从 diff、测试和任务描述中推断意图。下面用表格对比两种评测视角的差异对比维度独立解题式评测用户触碰式评测起始状态issue 修复前的干净快照用户已改过部分文件的中间快照用户动作只出现在 issue 描述里以代码改动、测试、注释等形式留在仓库中核心能力定位、修复、验证识别用户改动、衔接实现、避免冲突主要失败点找不到根因、修复不完整覆盖用户改动、修改测试、沿用旧接口评测关注点自动化测试通过率通过率之外还要看用户代码保留与改动范围这也是 SWE-Touch 这类基准给产品侧和工程侧带来的共同信号代理不能只做一个独立解题器它必须成为能理解“当前代码是我改过的版本”的协作者。2. 用户触碰代码的典型形态与评测闭环2.1 用户触碰代码的四种典型动作用户触碰代码的方式有很多但从代理需要应对的难度来看可以归类为四种。第一种是修改签名。用户把公共函数或类方法的参数结构改了调用方还没有全部更新。代理必须识别新签名不能按旧文档继续生成调用。例如用户将calculate_price(order)改为calculate_price(order, member_levelNone)任何继续只传一个参数的调用都是潜在问题。第二种是留下半成品。函数主体已经实现正常路径只差一个分支或者一个异常处理没有写完。代理应该基于仓库里的最新内容继续补全而不是重新生成一个完整版本否则很可能把用户已经写好的逻辑覆盖掉。第三种是补充测试。用户先写了一个测试表达自己对行为的预期。对代理来说测试就是需求契约。此时代理要让实现匹配测试而不是修改测试来匹配实现。第四种是相邻修复。用户刚解决完另一个 bug当前任务和用户的改动发生文件重叠。代理需要优先尊重已存在的用户改动避免自己的方案与用户方案冲突。这四种动作的共同点是仓库状态已经不是“原始问题状态”而是“用户进行到一半的状态”。代理如果只按 issue 描述行动不主动读用户 diff错误概率会大幅上升。2.2 评测闭环如何构造SWE-Touch 一类评测的任务构造思路与传统基准有明显的流程差异。典型步骤可以概括为从真实仓库中选一个 issue 及其对应 PR。找到 PR 开发过程里的某个中间提交把用户在这个阶段引入的文件改动提取出来。仓库快照停留在中间状态而不是 issue 开始前的原始状态。给代理一个任务目标但不额外显式告知用户改动的全部细节。代理提交结果后用自动化测试、git diff 对比、文件范围统计评估最终效果。在指标设计上通常至少包含这几种测试最终通过率。用户已触碰文件是否被代理覆盖。测试文件是否被代理修改。代理最终 diff 的大小与目标函数是否相关。是否产生冲突标记或语法错误。这里有一个核心判断如果评测只统计测试通过率代理完全可以通过删除用户新增测试来“通过”。因此面向协作场景的评测必须把“改动合规性”纳入指标否则会鼓励代理走上“让命令输出变绿”的捷径。2.3 为什么这种评测更能反映真实开发真实开发中开发者不是先把所有代码清空再让 AI 写。更常见的情况是开发者已经写了半截然后叫代理来帮忙扩展、修补、重构或者补测试。代理如果无法感知这些触碰点就会不断生成与用户冲突的代码。SWE-Touch 式评测的价值是它度量了代理对代码现状的敏感度。传统基准里代码现状就是“issue 开始前”而在这类评测里代码现状包含用户选择、用户命名、用户已经写下的边界条件和测试预期。代理要想完成高质量修复必须先从仓库里读出这些信息再把自己的方案嵌进去。3. 用户触碰过代码后代理最容易犯的四类错误3.1 继续使用被用户改掉的旧接口用户触碰后的文件可能是这样的# order.py def calculate_price(order, member_levelNone): # TODO: member_level 传入时应用会员折扣 items_total sum(item[price] * item[quantity] for item in order[items]) return items_total用户可以接受这个中间状态只希望代理完成 TODO。但如果代理没有重新读取当前文件可能直接在另一个模块里按旧签名调用# discount_controller.py total calculate_price(order) # 丢失了 member_level 信息也可能直接生成一个全新的calculate_price版本把用户留在函数里的 TODO 覆盖成自己的实现。原因通常是代理的工作记忆来自上下文窗口和工具检索结果任务开始时没有把最新文件状态读进来旧接口信息就占用了主导地位。检查方式看代理执行计划中是否包含读取order.py的操作看最终 diff 里的order.py是否被无故替换。建议在任务描述中直接点名“签名已经改为calculate_price(order, member_levelNone)不要回退这个签名。”3.2 修改测试来匹配自己的实现用户新增的测试def test_gold_member_discount(): order {items: [{price: 100, quantity: 1}]} assert calculate_price(order, member_levelgold) 90如果代理实现的折扣规则是黄金九折但测试期望黄金原价最省力的做法是直接改测试期望值让它等于自己的实现输出def test_gold_member_discount(): order {items: [{price: 100, quantity: 1}]} assert calculate_price(order, member_levelgold) 100 # 代理修改后的期望这是协作场景最危险的行为。它会让测试失去契约意义也会让用户已经表达的预期被悄悄推翻。团队使用编码代理时测试文件应当被视为只读文件任何改动都要人工单独审阅。3.3 在用户半成品上重复实现覆盖已有改动用户已经完成输入校验函数的异常分支def validate_input(data): if not isinstance(data, dict): raise TypeError(data must be dict) return data代理因为没读最新文件或者因为提示词要求“实现validate_input”直接重新生成了简化版本def validate_input(data): return data现象就是用户精心写的异常处理被替换成简单返回。这类错误在传统基准里也可能出现但在用户触碰场景中覆盖用户刚完成的代码损失比新写一个错误函数更大因为用户会误以为自己的修改被“合并”了实际却被静默删除。3.4 只关注 issue 目标不关注用户的 diff有些代理的错误不在于代码能力而在于没有把用户改动当作输入。它判断“用户改动不在我负责的任务范围内”于是不读取用户文件甚至在一个用户已经调整过逻辑的文件上继续添加不兼容代码。真正的协作者应该先看git diff当前状态识别已有改动再决定自己的新增是否与用户改动兼容。这也是为什么在任务描述中要求代理“先报告你理解的当前代码状态再给修改计划”会有效。下面把四类错误汇总成一张速查表错误类别典型现象常见原因检查方式正确做法沿用旧接口代理调用旧签名丢失新参数未读取最新文件依赖旧上下文检查代理执行计划是否读文件在任务描述里明确新签名修改测试代理改断言或删除测试测试失败后选择改需求侧git diff HEAD -- test_*.py测试文件一票否决覆盖半成品用户的异常处理或函数主体被替换代理重新生成了完整文件对比用户触碰文件 diff限制代理只能改目标行忽略用户 diff代理改动与用户改动冲突没有读取 git diff要求代理先报告代码现状让代理输出计划再动手4. 在一个最小仓库里复现“用户触碰代码”的评测过程4.1 准备一个带“触碰点”的最小仓库先建一个 Python 项目用pytest做验证。这个实验的目的是让团队在没有大型评测环境的情况下也能用自己的 Coding Agent 跑一次“用户触碰后继续”的流程。初始仓库结构member-discount/ ├── order.py ├── test_order.py └── README.md初始order.pydef calculate_price(order): return sum(item[price] * item[quantity] for item in order[items])初始test_order.pyfrom order import calculate_price def test_normal_order(): order {items: [{price: 10, quantity: 3}]} assert calculate_price(order) 30然后在user-touched分支模拟用户触碰。用户已经改了函数签名加了 TODO并且新增了一个测试文件。中间状态的order.pydef calculate_price(order, member_levelNone): items_total sum(item[price] * item[quantity] for item in order[items]) # TODO: member_level 为 gold 时打九折为 silver 时打九七折 return items_total中间状态新增的test_member_discount.pyfrom order import calculate_price def test_gold_member_discount(): order {items: [{price: 100, quantity: 1}]} assert calculate_price(order, member_levelgold) 90 def test_silver_member_discount(): order {items: [{price: 100, quantity: 1}]} assert calculate_price(order, member_levelsilver) 97这个状态就是“用户触碰点”用户已经做了一半剩下的是代理要接手的部分。4.2 把中间状态交给编码代理启动代理前先确认工作目录和分支cd member-discount git checkout user-touched git status然后给代理一份任务描述建议按照背景、目标、禁区、验收四段来写任务完成 user-touched 分支中会员折扣逻辑。 仓库背景 - order.py 中 calculate_price 已增加 member_level 参数。 - test_member_discount.py 已包含黄金和白银折扣测试。 目标 - 实现 TODO 处的会员折扣逻辑。 - 使 pytest 全部通过。 禁止改动 - test_order.py - test_member_discount.py - calculate_price 的函数签名 验收 - python -m pytest -q 全部通过。 - git diff --stat HEAD 只显示 order.py 有改动。 完成后输出计划再输出最终 git diff。这里的关键点是代理开始前先看到的不是“issue 描述 原始代码”而是“用户在代码里留下的中间状态 约束”。它必须自己判断用户已经做了什么并且不能通过改测试来绕过验收。4.3 用脚本记录代理的运行结果代理完成任务后按顺序执行下面四组命令git status git diff --stat HEAD git diff HEAD -- test_order.py test_member_discount.py python -m pytest -q如果代理表现正确预期输出应该是3 passed并且git diff --stat HEAD只列出order.py。用git diff HEAD -- test_order.py test_member_discount.py检查测试文件有没有被动过。如果这条命令有输出说明代理修改了测试文件必须重点审阅。4.4 三种典型结果怎么判断根据实验结果通常会出现三种情况。结果 A协作正常最终 diff 只涉及order.py测试通过函数签名保留。说明代理感知到了用户触碰点理解测试是契约在限定范围内完成工作。结果 B高风险通过测试通过但test_member_discount.py或test_order.py被修改。即使测试是绿的也不能直接接受。应该回退测试文件要求代理从实现侧继续。结果 C协作失败测试失败或者签名被回退或者出现多个无关文件变更。说明代理没有正确衔接用户状态需要重新提供更明确的任务描述或者检查代理工具本身的上下文读取机制。注意这个最小实验的价值不是给某个工具下结论而是让团队先建立一套“谁允许碰什么文件”的约束。不同代理的能力会变化但用git diff做验收的流程可以长期复用。4.5 学习环境与生产环境的差异学习环境里一个文件、一个测试、一个快速结果就够了。生产环境不同仓库更大历史提交更多权限更复杂。生产环境中应该把任务描述、文件白名单、测试基线、分支隔离都变成强制流程。额外的生产建议在 CI 中加一个脚本专门检查测试文件是否有变化。代理工作前先记录一次基线测试输出。不允许代理直接向主分支提交所有结果都要经过 PR 和 diff 审阅。对大型仓库先让代理做“只读探索”再给出修改计划。5. 把评测思路带回团队Coding Agent 协作验收清单5.1 任务描述模板必须包含四段信息使用 Coding Agent 时最常见的错误是任务描述只有一句话。要让代理感知“用户触碰点”建议把任务描述扩展成四段式模板## 任务背景 说明当前仓库状态明确哪些文件已经被用户修改 ## 任务目标 要完成的业务功能或修复点 ## 新增/修改范围 允许改哪些文件禁止改哪些文件 ## 验收方式 运行什么命令期望什么输出测试通过标准这套模板让代理在动手前先确认三件事我进入的是什么状态我能碰什么我怎么算完成。5.2 代理启动前先固化用户改动只要用户有未提交的本地改动就不应该直接把它丢给代理。原因不是代理读不到本地改动而是未提交改动无法通过git diff被稳定追踪代理和人工审阅都容易漏。推荐做法用户先把改动提交到功能分支。代理启动时基于该功能分支工作。代理完成后再提交新的 diff。人工对比两次提交的差异。这样每一个段落都有明确的基线出了问题也能回滚。5.3 输出审阅必须看 diff不能只看测试“测试通过了”不能作为验收完成的唯一标准。测试通过只能说明预期行为中的一部分被满足不代表用户代码没有被覆盖也不代表测试没有被篡改。对代理输出做审阅时按这个顺序走# 1. 看文件范围 git diff --stat HEAD # 2. 看测试文件是否被动过 git diff HEAD -- test_order.py test_member_discount.py # 3. 看用户触碰文件的差异 git diff HEAD -- order.py # 4. 检查空白、冲突标记等基本问题 git diff --check # 5. 跑最终测试 python -m pytest -q推荐做法无论哪个工具只要代理输出中出现了测试文件 diff就先把测试文件回退到基线再要求代理从实现侧解决。测试文件一旦被修改整个任务的验收基础就没有了。5.4 团队可以长期记录的四类指标要让“用户触碰后继续”成为团队习惯不能只靠口头要求还要有可观测的数据。建议在 Issue 或 PR 里记录以下指标指标含义记录方式一次通过率代理提交后测试直接通过的比例CI 记录每次运行结果用户文件被覆盖次数用户已改动文件被代理回退或覆盖的次数diff 对比人工检查测试文件被修改次数代理为通过测试而改动测试文件的次数统计测试文件 diff平均返工轮数从第一次提交到最终通过需要的轮次Issue 或 PR 评论记录这几个指标不需要额外系统靠 PR 评审记录就能统计。它们能很直接地反映代理是否真的理解“用户触碰点”。5.5 要让代理先给计划再动手对复杂任务不要在任务描述里直接要求“开始修改”。先要求代理输出一份计划计划里必须包含它认为当前仓库处于什么状态。用户已经改动了哪些文件这些改动意味着什么。它准备改动哪些文件为什么。打算用什么命令验证。代理输出计划后人工快速审阅再让它执行。这一步能拦截大量“代理没读用户 diff”的问题比事后排查节省时间得多。6. 常见问题排查当代理不认识你刚改过的代码6.1 现象一代理“看不到”用户改动现象用户已经在本地改过文件代理仍然基于旧内容生成代码。可能原因代理启动时的上下文来自旧索引工具读取文件时使用了缓存任务描述过短代理没有主动读取用户改动过的文件或者代理的工作目录与用户所在仓库不一致。检查方式让代理先执行git status和git log -1并向你复述它理解的当前文件状态。查看它实际读取的文件路径确认工作目录与用户当前仓库一致。处理方式重新启动代理或在任务描述中明确“用户刚改过order.py请先读取该文件再行动”。6.2 现象二代理正在撤销用户修改现象代理输出的 diff 里把用户刚加上的代码删除或覆盖。可能原因代理误把用户改动当成“待修复内容”或者代理认为自己的完整重写更可靠主动替换了用户实现。处理方式回退代理对用户文件的改动要求它在计划中先列出用户改动的关键点明确哪些要保持。如果代理仍然反复覆盖可以把用户文件加入“只读”白名单等人工确认后再放开。# 查看代理是否覆盖了用户文件 git diff HEAD -- order.py6.3 现象三代理为了通过测试而修改测试现象