SWE-agent 仓库配置完全指南：PreExisting / Local / Github 三种 Repo 类型与 `--env.repo` 参数详解

SWE-agent 仓库配置完全指南PreExisting / Local / Github 三种 Repo 类型与--env.repo参数详解【免费下载链接】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 解决 GitHub Issue 的第一步是把目标代码仓库正确地搬进隔离的沙箱部署环境并把它重置到指定提交Agent 才能在此基础上展开排查与修改。本文以 docs/reference/repo.md 为主线系统讲解 SWE-agent 支持的三种仓库类型预存在仓库、本地仓库、GitHub 仓库及其配置类PreExistingRepoConfig、LocalRepoConfig、GithubRepoConfig并结合 sweagent/environment/repo.py 与 sweagent/environment/swe_env.py 的源码实现说明仓库从复制到重置的完整生命周期、--env.repo命令行参数的用法、简化输入自动检测机制以及常见坑位。读完本文你将能针对自己的场景已有部署镜像、本地待提交仓库、公开或私有 GitHub 仓库正确配置 SWE-agent 的运行环境。一、仓库配置在整个运行流程中的位置SWE-agent 的运行单元是环境environment。环境的职责包括启动部署默认是 Docker 容器、把代码仓库放入容器、把仓库重置到指定基准提交然后再让 Agent 读取问题陈述并开始操作代码。仓库配置正是这段流程的输入描述。从 sweagent/environment/swe_env.py 可以看到每次reset()都包含两个关键步骤_copy_repo()检查容器根目录下是否已存在同名仓库文件夹若不存在则调用repo.copy(deployment)把仓库复制进沙箱_reset_repository()进入/{{repo_name}}目录执行repo.get_reset_commands()返回的 git 命令序列把仓库清理干净并切到base_commit。也就是说任何一种仓库配置类最终只需对外提供三个能力这在源码中体现为一个RepoProtocol见 sweagent/environment/repo.py协议成员作用base_commit仓库要被重置到的基准提交repo_name仓库在容器内的文件夹名称copy(deployment)将仓库复制/克隆到部署环境get_reset_commands()返回复制后执行的重置命令列表二、三种仓库类型总览官方文档 docs/reference/repo.md 明确指出SWE-agent 当前支持三种仓库类型配置类type判别值仓库来源典型场景PreExistingRepoConfigpreexisting已存在于部署镜像/容器中的仓库使用预装了目标代码的自定义镜像LocalRepoConfiglocal本机文件系统上的 Git 仓库想在本地仓库上跑 Agent或私有代码GithubRepoConfiggithubGitHub 上的公开/私有仓库 URL直接针对 GitHub 仓库 Issue 跑任务这三个类以及简化输入辅助函数repo_from_simplified_input都定义在sweagent.environment.repo模块中对应源码文件 sweagent/environment/repo.py并通过类型别名RepoConfig组合成一个联合类型供EnvironmentConfig.repo字段使用见 sweagent/environment/swe_env.py。在sweagent run命令中仓库类型统一通过--env.repo前缀的各子参数指定。接下来逐一详解。三、PreExistingRepoConfig使用部署中已存在的仓库如果目标仓库已经存在于部署环境例如自定义 Docker 镜像里已经git clone好了代码不需要 SWE-agent 再做复制就用PreExistingRepoConfig。配置参数参数类型默认值说明repo_namestr必填仓库文件夹名称。仓库必须位于部署的根目录即容器内/下base_commitstrHEAD要重置到的提交。可以是分支名如dev、标签如v0.1.0或提交哈希如a4464baca1ftypeLiteralpreexisting序列化/CLI 判别字段不要修改resetboolTrue是否在复制操作后把仓库重置到base_commit命令行用法文档给出的示例--env.repo.repo_nametestbed # 部署根目录下的文件夹名 --env.repo.typepreexisting源码行为从 sweagent/environment/repo.py 的实现看copy()方法什么都不做pass因为仓库已经存在get_reset_commands()在resetTrue时返回标准的 git 重置命令序列resetFalse时返回空列表。若镜像中的仓库初始状态就是干净的可以用resetFalse省去重置步骤。值得注意的是当resetTrue时重置序列与另外两种类型完全一致由模块级辅助函数_get_git_reset_commands()生成见 sweagent/environment/repo.pygit fetch git status git restore . git reset --hard git checkout base_commit git clean -fdq这一串命令的目的同步远端引用、展示当前状态、丢弃工作区改动、硬重置、切到目标提交、清理未跟踪文件确保 Agent 拿到的是一个纯净的基线代码树。一个实际参照sweagent/run/run_shell.py 中启动交互式 shell 时就使用了PreExistingRepoConfig(repo_namerepo, resetFalse)仓库名为repo、不执行重置——这正适合只想进入容器手动操作的场景。四、LocalRepoConfig使用本地 Git 仓库如果你希望 SWE-agent 直接基于本机磁盘上的某个 Git 仓库运行例如私有代码、尚未推送的改动使用LocalRepoConfig。它会把本地仓库整个上传到部署环境而不是走网络克隆。配置参数参数类型默认值说明pathPath必填本地仓库的路径base_commitstrHEAD要重置到的提交分支名 / 标签 / 提交哈希均可typeLiterallocal判别字段不要修改命令行用法--env.repo.path/path/to/repo --env.repo.typelocal源码行为仓库名自动生成repo_name是一个只读属性取自路径的最终目录名并将空格替换为-、去除单引号见 sweagent/environment/repo.py。例如/path/to/my repo会得到my-repo。你不能手动设置它。上传前校验copy()首先调用check_valid_repo()sweagent/environment/repo.py它会用 git 库向上搜索父目录确认路径确实是一个 Git 仓库如果仓库处于 dirty 状态有未提交/未暂存改动会抛出ValueError在PYTEST_CURRENT_TEST环境变量存在时跳过该检查即测试环境下允许 dirty。请先 commit 或 stash 再运行。上传与权限校验通过后通过 SWE-ReX 的runtime.upload把整个目录上传到容器的/{repo_name}随后执行chown -R root:root /{repo_name}统一属主若权限设置失败会抛出RuntimeErrorsweagent/environment/repo.py。重置命令get_reset_commands()始终返回标准重置序列不提供resetFalse开关。本地仓库的典型完整命令参照 sweagent/run/run_single.py 顶部文档中的示例把部署后端换成 Modal、仓库换成本地路径sweagent run --config config/default.yaml --agent.model.name gpt-4o \ --env.deployment.typemodal --env.repo.path /path/to/repo \ --problem_statement.pathpath/to/problem_statement.md五、GithubRepoConfig从 GitHub 克隆仓库GithubRepoConfig是最常用的配置给定一个 GitHub 仓库 URLSWE-agent 会在沙箱里初始化 git 仓库并浅克隆目标提交。这是默认配置 config/demo/default.yaml 采用的方式env: repo: github_url: https://github.com/SWE-agent/test-repo配置参数参数类型默认值说明github_urlstr必填GitHub 仓库 URL也支持简写见下文base_commitstrHEAD要克隆并重置到的提交clone_timeoutfloat500git clone 操作的超时时间秒typeLiteralgithub判别字段不要修改命令行用法sweagent run --config config/default.yaml --agent.model.name gpt-4o \ --env.repo.github_urlhttps://github.com/SWE-agent/test-repo/ \ --problem_statement.github_urlhttps://github.com/SWE-agent/test-repo/issues/1源码行为URL 自动补全model_post_init中如果github_url只包含一个/例如SWE-agent/test-repo会自动补全为https://github.com/SWE-agent/test-reposweagent/environment/repo.py。仓库名规则repo_name返回{org}__{repo}格式即SWE-agent__test-repo由 sweagent/utils/github.py 中的GITHUB_REPO_URL_PATTERN正则解析 org 与 repo 名得到。私有仓库支持copy()会读取环境变量GITHUB_TOKEN若已设置且 URL 中不含则把 token 拼进 URLhttps://{token}{host}/{org}/{repo}从而支持私有仓库的认证克隆若 URL 中已含会打印警告并原样使用sweagent/environment/repo.py。克隆策略在容器内依次执行mkdir /{repo_name}→cd /{repo_name}→git init→git remote add origin url→git fetch --depth 1 origin base_commit→git checkout FETCH_HEAD。注意这里不是常规git clone而是初始化 指定提交的深度为 1 的 fetch好处是只拉取目标提交附近的最小历史显著加快大型仓库的准备工作同时天然地把仓库放到容器根目录下的/{repo_name}sweagent/environment/repo.py。重置命令同样返回标准重置序列。关于 base_commit 的取值三个配置类的base_commit字段语义一致默认HEAD即最新提交支持三种取值形态分支名如dev标签如v0.1.0提交哈希如a4464baca1f。SWE-agent 将从此提交开始处理问题_reset_repository()会先cd /{repo_name}再执行重置命令确保 Agent 面对的工作树精确对应这个提交sweagent/environment/swe_env.py。六、repo_from_simplified_input用一条字符串自动选型除了手写完整配置sweagent.environment.repo还导出一个便捷函数repo_from_simplified_input()sweagent/environment/repo.py签名如下repo_from_simplified_input(*, input: str, base_commit: str HEAD, type: Literal[local, github, preexisting, auto] auto) - RepoConfig传入typelocal把input当作本地路径构造LocalRepoConfig传入typegithub把input当作 GitHub URL构造GithubRepoConfig传入typepreexisting把input当作仓库名构造PreExistingRepoConfig传入typeauto默认若input以https://github.com/开头则视为 GitHub 仓库否则视为本地路径。注意自动检测对预存在仓库不适用——预存在仓库只能显式指定typepreexisting。这个函数同样被批量运行场景复用例如 sweagent/run/batch_instances.py 中根据实例输入自动在三种配置类之间分派。七、在 YAML 配置文件中声明仓库除了命令行仓库配置也可以写在 YAML 配置文件里由--config加载。参考 config/demo/default.yamlenv: repo: github_url: https://github.com/SWE-agent/test-repo # GithubRepoConfig deployment: image: tiny python_standalone_dir: problem_statement: github_url: https://github.com/SWE-agent/test-repo/issues/1三种类型在 YAML 中的写法与命令行参数一一对应只是把--env.repo.xxx的层级改成了env.repo.xxx嵌套结构# 本地仓库 env: repo: type: local path: /path/to/repo base_commit: HEAD # GitHub 仓库 env: repo: type: github github_url: https://github.com/SWE-agent/test-repo clone_timeout: 500 # 预存在仓库 env: repo: type: preexisting repo_name: testbed reset: truetype字段是 pydantic 判别联合discriminated union的判别键用于反序列化时把 YAML 正确映射到对应配置类配置类均设置了extraforbid意味着出现未声明字段会直接报错能及早发现拼写错误。八、生命周期串联copy 与 reset 是如何协作的理解仓库配置最好的方式是看它在环境启动时如何被消费。梳理 sweagent/environment/swe_env.py 中的调用链SWEEnv.start()启动部署、创建 bash 会话、设置环境变量sweagent/environment/swe_env.pyreset()先cd /再调用_copy_repo()若repo为None则直接跳过即不配置仓库也能运行Agent 在空容器里操作先执行ls检查repo.repo_name是否已存在于根目录已存在则不再复制避免重复克隆否则触发环境钩子on_copy_repo_started可用来自定义复制前后行为随后调用repo.copy(deployment)sweagent/environment/swe_env.py接着_reset_repository()执行cd /{repo_name}export ROOT$(pwd -P)get_reset_commands()超时上限 120 秒sweagent/environment/swe_env.py。这解释了为什么PreExistingRepoConfig的copy()是空实现却依然可用仓库已在镜像中_copy_repo()的ls检查会发现它存在而跳过复制get_reset_commands()则负责把已有仓库重置到目标提交。三种配置类在这一流程中完全对称只是复制环节的实现不同。九、常见问题与注意事项1. 旧参数--repo_path/--env.repo.path的迁移SWE-agent 1.0 已经移除了旧的--repo_path顶层参数。sweagent/run/run_single.py 中注册了自动纠正规则ACS--repo_path会被拦截并提示改用--env.repo.github_url或--env.repo.pathrepo.path会自动映射为env.repo.path。如果你还在用旧写法请统一迁移到--env.repo.*前缀。2. 本地仓库必须是干净的LocalRepoConfig在复制前强制检查repo.is_dirty()存在未提交改动会直接报错。这是刻意的设计确保上传到沙箱的就是仓库的完整可复现状态而不是夹杂工作区噪音。运行前请先git commit或git stash。3. 预存在仓库必须在部署根目录PreExistingRepoConfig.repo_name的定位是容器根目录下的文件夹名如/testbed。如果仓库位于其他路径需要调整镜像或改用其他类型。4. 私有仓库记得配GITHUB_TOKEN使用GithubRepoConfig访问私有仓库时请设置环境变量GITHUB_TOKEN读取逻辑见 sweagent/environment/repo.py。另外 sweagent/utils/github.py 还提供了_is_repo_private辅助函数对私有仓库 GitHub API 会返回 404而非 403SWE-agent 据此把 404 也判定为私有提示配置 token。5. 大型仓库的克隆超时GithubRepoConfig.clone_timeout默认 500 秒若目标仓库历史庞大或网络较慢导致 fetch 超时可在--env.repo.clone_timeout或 YAML 中调大。深度为 1 的 fetch 已经能避免克隆完整历史但仓库体积本身仍可能很大。6. 重置不是删除重来hard_reset()sweagent/environment/swe_env.py会关闭并重启整个部署是比reset()更彻底的清场方式。当仓库本身而非仓库内改动需要重建时使用它。十、小结SWE-agent 的仓库配置层虽然接口简单却支撑着复制 → 重置 → 供 Agent 操作的完整链路。三类配置的选型要点镜像里已经带代码 →PreExistingRepoConfigrepo_name 可选reset本地磁盘上的仓库 →LocalRepoConfigpath需干净工作树上传后自动命名GitHub 上的仓库 →GithubRepoConfiggithub_url支持简写、token 认证与浅克隆指定提交。所有配置既可通过--env.repo.*命令行传入也可写入env.repo的 YAML 块需要快速原型时repo_from_simplified_input的auto模式能在 URL 与本地路径之间自动选择。掌握这些细节你就可以针对任意代码仓库稳定复现 SWE-agent 的运行基线把精力聚焦到问题解决本身。进一步阅读仓库配置类的完整 API 文档见 docs/reference/repo.md环境整体配置含post_startup_commands等相邻字段见 docs/reference/env_config.md 与 sweagent/environment/swe_env.py。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考