编码智能体Coding Agent已经成为许多研发团队处理重复代码、修复小型 bug、补单元测试的常用工具但真正有挑战的任务是长时程、全仓库的栈迁移Stack Migration。SWE Refactor Bench 这类基准正是用来检验 Coding Agent 能否在完整仓库规模下完成跨技术栈迁移而不是只在单文件、短任务上表现良好。这类问题很适合拿来讨论因为它同时踩中了三个难点任务周期长、修改范围覆盖整个仓库、变更对象是底层技术栈而不是单个函数。就算智能体在普通代码生成任务上得分很高面对一次全仓库依赖替换、API 迁移和构建系统调整时也很可能因为上下文丢失、调用点遗漏、构建失败反复循环而中途崩溃。所以这篇文章会先拆解这类基准要回答的问题再分析栈迁移为什么难然后给出一个可复现的评测流程最后讨论如何把评测思维应用到真实的仓库迁移项目里。1. SWE Refactor Bench 到底在测什么1.1 从单点修复到全仓库重构能力跨度在哪里现在很多智能体基准都是给一个带 bug 的文件让模型生成几行修复代码然后用隐藏测试判断是否通过。这种任务周期短、影响面小模型只需要关注局部变量、函数签名和少量上下文就可以完成。但 SWE Refactor Bench 这类基准刻意把任务放大到整个仓库要智能体完成的不再是“修一行代码”而是“让整个仓库从旧技术栈平滑过渡到新技术栈”。两者之间的能力跨度非常明显单点修复只需理解函数内部逻辑全仓库迁移需要理解模块之间的依赖关系。单点修复可以直接运行测试验证全仓库迁移需要先让项目编译通过再让测试通过然后还要处理被改 API 的上游调用点。单点修复失败可以回退到原文件全仓库迁移一旦中间步骤产生大量半成品代码回退成本会非常高。SWE Refactor Bench 刻意把这些因素揉进一个评测任务里目的就是测试智能体在“局部正确”之外是否具备全局规划、跨文件一致修改和持续验证的能力。1.2 long-horizon 任务为什么是独立难点“long-horizon”是这类迁移任务最明显的特征。它不等于“代码多”而是指整个任务需要多轮决策并且后续决策依赖前面步骤产生的中间状态。短任务里模型可以一次性读完上下文然后输出结果长任务里模型必须先规划再执行再根据编译和测试结果修正最后可能还要回归验证。长时程任务会带来几个具体问题上下文窗口限制仓库一变大模型不可能一次性把所有文件装进上下文必须按需读取、选择性记忆。中间状态不一致迁移进行到一半时仓库既不是旧版本也不是新版本这时继续编译测试会出现大量阶段性报错分散智能体的注意力。失误累积前面一步漏改一个调用点后面构建失败时很难快速定位是哪一步引入的。回退与重试成本如果整个仓库被改到不可编译智能体需要自己判断是继续修复还是回退到某个稳定点。所以评测“能否完成长时程任务”本质上是在评测智能体的分治能力、错误恢复能力和状态管理能力而不只是代码生成能力。1.3 stack migration 比普通重构更复杂在哪里“Stack Migration”在 SWE Refactor Bench 语境下通常指从一个技术栈切换到另一个技术栈。常见场景包括构建工具替换、基础库替换、框架版本升级、语言运行时升级等。它比普通重构复杂因为普通重构通常保持外部行为不变而栈迁移要求在替换底层实现的同时尽量保持上层业务代码不变或只做受控修改。以一次典型的 HTTP 客户端从requests迁移到httpx为例表面上只需要替换依赖名称和方法名实际上会波及requirements.txt或pyproject.toml里的依赖声明。import requests的导入语句。requests.get(url, params..., headers...)这类调用语法。response.status_code、response.json()、response.text等属性访问差异。超时、异常、会话Session行为的差异。单元测试里 mock 的目标函数路径。文档、示例代码、CI 脚本中对库的引用。任何一层遗漏都会导致迁移之后构建或测试失败。SWE Refactor Bench 里的迁移任务通常比这个例子更宏观可能涉及构建工具从 Webpack 换到 Vite、测试框架从 Jest 换到 Vitest、ORM 从 SQLAlchemy 1.x 升到 2.x 等但核心困难是一致的调用点分散、语义不完全等价、验证依赖整个仓库的构建测试链路。1.4 用一个表快速理解评测维度可以把 SWE Refactor Bench 这类基准关注的维度整理成一张对照表帮助理解它在测什么评测维度短任务修复SWE Refactor 类迁移修改范围单个文件或函数全仓库可能数十到数百个文件任务周期几分钟内完成多轮规划、执行、验证、修复上下文需求局部变量和函数即可依赖图、构建配置、历史调用点验证手段单测直接运行编译、单测、集成测试、回归测试失败成本低改一处即可重试高中间状态可能阻塞后续步骤对规划能力要求低高路径依赖明显这张表不是来自某个正式标准而是从工程实践角度提炼出的关键差异。理解这些差异才能看懂后续评测指标和任务设计为什么这样安排。2. 栈迁移任务的四类核心难点2.1 跨文件 API 映射与语义对齐栈迁移的第一步通常是整理新旧技术栈之间的 API 映射表。这是工作量最小的一步但也是错误最容易扩散的一步。因为新库和旧库的接口很少完全一致往往存在“同名不同语义”“不同名同语义”“单函数分裂成多个函数”等情况。以requests和httpx的一个差异为例# requests 的写法 response requests.get(https://example.com, timeout3) data response.json() # httpx 的写法 response httpx.get(https://example.com, timeout3) data response.json()从表面看两者差异不大但更深层的语义并不完全相同。httpx天然支持 HTTP/2默认重试策略、连接池配置、异常类型都可能与requests不同。如果业务代码里存在对超时异常类型的捕获那么从requests.exceptions.Timeout迁移到httpx.TimeoutException就是一个需要全局替换的类型映射。如果把例子放大到完整框架迁移比如从 Spring Boot 2 升到 Spring Boot 3则涉及javax到jakarta的命名空间替换、Spring Security配置方式调整、Spring Data JPA的 API 变更。这些变更不是简单的字符串替换还牵涉到依赖传递、启动类扫描、配置属性名称变化。智能体要完成这类任务不能只做正则替换必须理解每个调用点实际使用的 API 契约并判断在新栈下应该用哪个替代接口。2.2 依赖图和调用点扩散一个仓库里公共模块被大量调用的情况很常见。比如一个工具类里定义了send_request()全仓库有 50 个服务在调用它。迁移底层 HTTP 客户端时即使公共函数本身只改一处依赖它的 50 个调用点是否受影响取决于公共函数是否保留原有签名。很多时候迁移会向上层扩散底层库先换掉接着发现返回类型变了调用方需要适配调用方改完后发现测试替身mock路径变了测试代码也要改测试代码改完后发现构建脚本里的依赖版本冲突CI 配置又要改。整个过程呈波浪式扩散可能横跨业务的每一层。这也是全仓库迁移最考验智能体规划能力的地方。理想顺序是先改底层依赖和公共封装再逐层向上修复调用点最后统一处理测试和构建配置。如果顺序颠倒前面刚修好的文件会因为后续变更再次报错造成大量重复劳动。对智能体来说比较好的做法是先读取项目的模块依赖图生成一个“受影响文件清单”再按依赖方向分层处理。这个思想在 SWE Refactor Bench 这类任务中基本是必需步骤否则任何短视的局部修改都会在后续构建中暴露出来。2.3 构建、测试与回归验证闭环全仓库迁移是否完成不能靠肉眼检查也不能靠“没有搜索到旧 API 名称”来判断。一个可被接受的迁移任务必须有一个机器可执行、可重复的验收闭环拉取迁移后的仓库执行构建脚本执行单元测试和集成测试再执行针对迁移行为的专项验证。这个闭环在评测中非常关键因为它决定了智能体的每次修改是否有即时反馈。很多智能体在真实项目中表现不佳原因之一就是它们只能“生成代码”却不能“运行代码”。一旦迁移任务需要根据编译错误调整下一步智能体的输出质量就取决于它能否获取构建日志、测试报告并据此修正文件。一个典型的迁移验证流程可以写成下面这样# 1. 清理旧构建缓存 rm -rf .build .cache # 2. 安装新依赖 python -m pip install -r requirements.txt # 3. 静态检查是否还有旧 API 残留 grep -rn from requests src tests || true # 4. 运行测试 python -m pytest tests/ --tbshort # 5. 构建发布包 python -m build当智能体可以在每次编辑后执行这套流程时它会把“猜测”变成“验证”从而缩小错误范围。SWE Refactor Bench 这类任务要测试的核心能力之一就是智能体是否建立了这种“编辑-构建-测试-修复”的循环。2.4 长时程执行中的上下文与状态管理长时程任务里智能体的上下文是有限的但仓库状态是不断变化的。刚读完的文件可能马上被另一个编辑操作修改刚修复的编译错误可能因为其他文件的变更重新出现。如果智能体不能有效掌握“当前仓库状态”就会在错误的假设上继续改代码。上下文管理常见的策略包括先收集仓库结构生成文件树和模块依赖摘要。按任务阶段只读取当前要处理的文件不在无关文件上消耗上下文。每次构建测试后只记录新增错误和未解决错误减少日志噪声。维护一个“已完成清单”和“待办清单”防止重复修改。重要中间结果用文件落盘避免依赖模型对话记忆。这些策略虽然不是某一项评价指标但在评测中会直接影响最终成功率。SWE Refactor Bench 这类基准的价值就是把这类“工程能力”从模型能力中剥离出来观察让团队看到某个智能体到底是因为代码生成能力强而成功还是因为规划能力强而成功。3. 自己搭建一个可复现的迁移评测流程3.1 先定义迁移目标和范围如果你想在自己的团队里复现类似 SWE Refactor Bench 的评测第一步不是写 prompt而是先定义迁移目标和范围。迁移目标必须能被机器验证至少要满足下面几条明确旧栈和新栈的版本范围。明确允许修改的目录比如src、tests、build、docs。明确不允许修改的边界比如vendor、third_party、生成代码。明确验收测试的命令和预期结果。一个示例任务定义可以写成任务将仓库中的 HTTP 客户端从 requests 迁移到 httpx。 范围src/、tests/、requirements.txt、pyproject.toml。 不允许修改.github/ 下的发布脚本如果有上游模板。 验收标准 1. requirements.txt 不再包含 requests除非仍有其他模块直接依赖。 2. src/ 和 tests/ 中没有 from requests 和 import requests。 3. python -m pytest tests/ 全部通过。 4. 保留 requests.exceptions.Timeout 的捕获语义改为 httpx.TimeoutException。这个定义已经足够让一个工程师开始干活也能让一个智能体开始行动。对于评测基准来说理想情况下每个任务都应有 3 到 5 个这样明确的验收条件。3.2 准备基线仓库与迁移前状态可复现的基准需要三个状态迁移前基线一份可以成功构建和测试的旧栈仓库。迁移后参考实现一份由专家完成的新栈仓库用于对照。任务输入只有迁移前基线不提供参考实现。准备基线仓库时要注意“确定性”。需要锁定依赖版本、锁定 Python/Node/Java 版本否则同一个任务在不同时间运行可能因为依赖版本漂移而得到不同结果。常见做法是使用 lock 文件、容器镜像或提交固定的 package-lock.json / poetry.lock。迁移前基线必须保证原仓库能持续通过测试。如果基线本身测试就是红的评测结果就会失真分不清是迁移任务失败还是初始仓库就不可用。3.3 构造验证集和评分方式验证集不能只用单元测试还需要加入专项检查。例如迁移到新库后可以添加一个验证脚本扫描旧 API 是否残留import ast import sys from pathlib import Path BLOCKED_IMPORTS {requests} def check_file(path: Path): tree ast.parse(path.read_text(encodingutf-8)) for node in ast.walk(tree): if isinstance(node, ast.Import): for alias in node.names: if alias.name.split(.)[0] in BLOCKED_IMPORTS: return False if isinstance(node, ast.ImportFrom): if node.module and node.module.split(.)[0] in BLOCKED_IMPORTS: return False return True def main(): root Path(src) failed [] for path in root.rglob(*.py): if not check_file(path): failed.append(str(path)) if failed: print(blocked imports found in:, failed) sys.exit(1) if __name__ __main__: main()这种检查脚本可以让评分更严格避免智能体只把import requests改成import httpx但不处理调用点就声称完成。评分方式可以分层编译构建通过通过率。单元测试通过基础功能保留率。迁移专项检查通过旧 API 残留率。静态分析通过比如 lint避免出现未使用导入或格式错误。人工抽检对关键文件做代码审查判断是否属于合理迁移。3.4 编写任务描述与智能体输入任务描述要尽量降低歧义但也不要给太细的步骤提示否则测不出智能体的规划能力。比较好的结构是你正在参与一次全仓库技术栈迁移。当前仓库使用 requests 作为 HTTP 客户端请将它迁移到 httpx。 迁移时必须保持测试通过。 - 先分析仓库结构和依赖关系列出需要修改的文件清单。 - 再分批修改每次修改后运行构建和测试。 - 不要只替换 import要处理异常类型、调用参数和 mock 路径。 - 最终提交的代码不应出现 requests 导入。这里的关键是“先分析、再分批、每步验证”它符合工程师的真实工作方式也不至于把答案直接喂给智能体。在 SWE Refactor Bench 这类基准中任务描述通常是标准化的多组任务共用同一套 prompt 模板只是替换仓库路径、旧栈、新栈和验收命令。这样可以让不同智能体之间的对比更公平。4. 用编码智能体执行一次完整迁移4.1 迁移工作流从规划到验收无论智能体底层是什么模型一个完整的全仓库迁移工作流大体可以分成五步收集仓库信息读取 README、包管理文件、目录结构确定技术栈和入口。生成受影响文件清单搜索旧 API 的 import、调用、文档和 CI 相关位置。制定分阶段计划先改底层配置和公共封装再改调用点最后改测试。循环执行修改与验证每次只处理一个模块修改后立即构建测试。提交差异并复盘记录失败点、残留 API、需要人工确认的部分。对工程师来说这套流程很自然对智能体来说难点在于把“计划”落到文件系统级别的操作上。一个较好的方式是让智能体先把计划写入一个migration_plan.md文件再逐步勾选完成状态。这样即使模型对话上下文丢失也可以重新读取计划文件恢复进度。4.2 用脚本化迁移减少机械错误全仓库迁移中最容易错的不是复杂逻辑而是大量重复的机械替换。比如将requests.get替换为httpx.get如果完全靠模型逐文件改写很可能因为上下文窗口和注意力限制漏掉某些文件。更稳妥的方式是先用脚本完成机械替换再让智能体处理需要语义判断的差异。例如用sed或者一个简单的 Python 脚本处理统一导入和函数名# 仅作为示意实际需要谨慎处理先确认替换规则 grep -rl import requests src tests | xargs sed -i s/import requests/import httpx/g但不建议直接执行这种全局替换因为requests.get与httpx.get的参数和异常类型并不完全一致。更推荐的做法是先生成一份“机械替换报告”列出所有需要修改的文件和行号由智能体决定哪些可以批量处理哪些需要单独判断。在真实工程里很多团队会先写 codemod 脚本用 AST 级别的方式改写源码而不是用正则。这是因为正则不能区分注释、字符串、实际代码调用。SWE Refactor Bench 这类基准虽然没有强制要求使用 AST但从评测稳定性角度看能生成 codemod 脚本的智能体通常成功率更高因为它的修改更可控、可回滚。4.3 持续构建与测试循环智能体的工作循环非常重要。比较差的循环是“读文件-改完所有文件-一次性构建”因为一次性改完发现大量错误时很难定位。比较好的循环是“改一个模块-构建测试-修复错误-再改下一个模块”。在实现上这需要智能体具备执行命令的能力并且能读懂错误日志。下面是一个循环的伪代码表示while 存在未处理文件: 当前模块 plan 中下一个模块 修改当前模块相关文件 执行构建与测试 if 失败: 提取错误日志 定位最近修改的文件 修复后重新构建 else: 标记当前模块完成 更新 migration_plan.md这个循环里最关键的不是修改代码而是“提取错误日志并定位到具体文件”。仓库一旦迁移到一半构建日志可能包含大量来自不同模块的错误智能体必须过滤掉与当前模块无关的错误集中处理自己刚引入的问题。4.4 Agent 配置示例和参数说明如果你要在本地搭建一个运行智能体的评测环境几个关键参数需要格外注意参数含义常见值影响max_steps最大执行步数50 到 200步数过少无法完成长任务过多会浪费资源timeout单条命令超时时间120 秒构建和测试可能较慢需要留足时间context_window模型可用上下文窗口128k 到 200k越大越能容纳仓库结构但不等于理解越好retry_limit单步失败重试次数3 到 5限制过紧会让模型在偶发错误上崩溃log_level执行日志级别debug评测结束后需要 debug 日志复盘失败原因这些参数没有绝对标准但评测时要固定不变避免因为环境差异导致结果不可比。尤其要注意的是智能体一次执行耗时可能很长如果评测平台有请求超时限制需要把任务拆成可断点续跑的模式否则中途断掉就丢失全部进度。5. 结果评估与失败排查5.1 常用指标与判定方式评测不能只记录“成功”或“失败”还要记录“卡在哪里”。常用的指标可以分成几类完成率任务达到验收标准的比例。构建通过率迁移后的仓库能否成功构建。测试通过率原测试集中通过的比例。残留率旧 API 关键字在源码中出现的次数。人工修正率专家需要手工修正的文件数量。耗时与步数智能体完成迁移消耗的步数和命令数。每个指标都要有明确的采集方式。比如“构建通过率”要在迁移完成后重新拉取仓库从干净环境执行一次构建命令而不是使用迁移过程中的缓存。一个示例结果输出可以这样组织任务requests - httpx 结果通过 构建通过 测试32/32 通过 残留旧 API0 修改文件数18 执行步数64 人工修正05.2 失败模式分类从实际观察来看智能体在栈迁移任务上的失败模式有比较明显的规律。整理成表失败模式现象常见原因半途而废任务执行到一半停止仓库处于不可编译状态最大步数耗尽或模型认为自己已完成但验收未通过局部正确测试通过但旧 API 残留例如只在部分文件替换 import只处理了主路径文件遗漏辅助目录语义偏差构建通过但运行行为与旧栈不一致例如异常类型不同只关注函数名等效忽略语义差异过度修改把无关模块也一并重写导致新增大量风险计划阶段没有定义修改边界重复返工同一个文件被反复修改前后不一致没有保存文件状态上下文丢失构建死循环反复报同一个错误持续修改却无法解决未能识别错误根因只做表面修补这些模式对应了真实工程师在迁移过程中也会遇到的问题。SWE Refactor Bench 这类基准的价值就是从模型输出中把这些模式量化出来帮助研发团队判断智能体是否可信。5.3 排查路径和复现技巧当一次迁移任务失败后排查顺序应该从结果倒推查看最终仓库是否可构建。如果不可构建直接看第一个编译错误。如果可构建但测试失败对比失败测试与修改文件之间的关联。如果测试全通过但残留旧 API检查扫描脚本覆盖的目录范围。如果一切指标正常但人工审查不通过检查是否改了任务范围之外的文件。如果是中途失败查看执行日志最后几步明确是超时、步数耗尽还是模型主动停止。复现技巧也很重要。建议把每次评测的完整执行日志、中间 diff、测试输出都保存下来并以“任务ID-模型名-时间戳”命名。如果出现非确定性失败可以重复运行 3 次记录成功次数而不是拿一次运气结果下结论。6. 从基准回到工程实践6.1 评测思维如何迁移到真实仓库SWE Refactor Bench 这套方法不只是给评测机构用的。真实项目里团队在做大规模技术栈升级时完全可以借鉴它的思路先把当前仓库做成可复现基线确保迁移前构建测试通过。定义明确的验收标准让“完成迁移”不是感觉而是可执行命令。用依赖扫描、残留检测脚本约束修改范围。把任务拆成多个可验证的阶段每个阶段独立提交。保留详细日志方便迁移结束后回溯问题。这套做法可以把一次“感觉风险很大的全仓库迁移”变成一系列可验证的小步骤降低出错成本和审查难度。6.2 结合实践的检查清单在开始一次真实的栈迁移之前可以参考下面这份清单[ ] 已锁定旧栈和新栈的具体版本并确认依赖兼容性。[ ] 迁移前仓库在干净环境中能构建、测试通过。[ ] 已生成旧 API 的调用点清单覆盖 src、tests、scripts、docs。[ ] 已明确允许修改和禁止修改的目录边界。[ ] 已编写迁移专项检查脚本能检测残留旧 API。[ ] 已定义分阶段提交计划每个阶段有独立验收命令。[ ] 已准备回滚方案例如保留迁移前分支或 tag。[ ] 迁移过程中每完成一个模块都执行构建和测试。[ ] 迁移完成后从干净环境重新执行全部验收命令。[ ] 已安排至少一名未被迁移任务“污染”的专家做代码审查。这份清单既可以给人类工程师用也可以作为智能体评测的一部分用来核对最终交付物是否完整。6.3 扩展方向从 SWE Refactor Bench 这个方向延展可以看到几个值得继续关注的问题一是跨语言迁移。现在很多栈迁移还停留在同语言、同生态内替换真正困难的是把 Java 服务迁移到 Kotlin、把 Python 服务迁移到 Go这类任务会涉及语义模型的变化评测难度会大幅提升。二是迁移质量度量。目前普遍用构建和测试通过率来衡量迁移成功但这些指标很难捕捉性能劣化、可维护性下降、隐藏行为差异。后续基准可以引入性能回归测试、代码结构相似度、复杂度变化等指标。三是多智能体协作。单智能体处理全仓库迁移容易上下文溢出多个智能体分别负责规划、执行、验证可能是更接近团队工作的架构。SWE Refactor Bench 这类基准的评测协议也需要相应支持并行执行和冲突合并。四是人机协同评估。完全自动化迁移目前仍然有风险比较现实的做法是让智能体完成底层机械修改人类工程师负责验收关键模块。如何设计“人机返工率”这样的指标会是未来评测和工程实践的重要方向。对于正在评估 Coding Agent 是否值得引入团队的研发负责人来说与其看模型在代码生成榜单上的排名不如先构造一个小型仓库迁移任务跑一次类似 SWE Refactor Bench 的流程。那会比任何宣传数据都更接近真实生产力。