RepoLaunch — 仓库构建/测试环境自动化框架

目录入口见 README。它供环境的榜见 swe-bench-live。

一句话

给一个 repo + commit，自动产出「装好依赖、能编译、能跑测试、能判每个用例 pass/fail」的 Docker 环境——把「这个仓库到底怎么装、怎么测」这件纯靠人工经验的事，变成机器可复现的产物。

论文里的定位是 the first agentic SWE tool for repository build and test management across programming languages and operating systems。它的消费者不是人，而是下游的评测/训练流水线。

要先分清它不是什么：

容易误解	实际
一个 coding agent harness	不是。它不改 bug、不跑任务，它负责把环境准备好交给别人跑
评测器 / 判分器	不是。它产出环境 + 测试解析器，判分逻辑由下游（如 SWE-bench-Live evaluator）决定
SWE-bench 官方组件	微软同一批人做的上游供给工具，但不属于 SWE-bench 评测协议本身
单机轻量小工具	重资源、强依赖 Docker 与 LLM，适合批量/平台级场景（见下文门槛）

什么时候会用到它

正向场景：

批量造可执行环境——手上有一批 repo×commit，想让它们都能跑起来（这是它的主战场）
造 SWE-bench 类基准——题目需要一个「测试能跑、还能判单个用例通过与否」的容器。SWE-bench-Live 的题目环境就是这么来的（论文标题即 automated SWE dataset creation）
给 coding agent 做 RL/SFT——训练需要环境能反复 reset、每次改动后能重建、能自动判定测试通过与否。GLM-5 已用它造 agentic RL 环境
复现历史 commit 的依赖安装——尤其是跨语言、跨 OS 的多仓库，人工一个个写 Dockerfile 成本极高

反例（不该用的场景）：

单个自己熟悉的项目 → 手写 Dockerfile 更快更可控
机器资源不足 → 每个 worker 要 4 vCPU / 16GB，且必须有 Docker
跑在容器化集群 pod 里 → 硬依赖 Docker-in-Docker，官方明确说不可行
需要 macOS 环境 → 代码里直接 NotImplementedError

它做了什么

输入：一行 JSONL，核心就四个字段。

{"repo": "robbert-vdh/nih-plug", "instance_id": "robbert-vdh__nih-plug-28b149e",
 "base_commit": "28b149ec4d62757d0b448809148a0c3ca6e09a95",
 "created_at": "2025-09-07T21:34:16Z", "language": "Rust"}

created_at 是可选项，但对 Python 很关键——它开启 PyPI 时间机器（见下文）。hints 字段可塞入 CI 配置等提示。

输出（{workspace}/organize.jsonl 里的核心字段）：

字段	含义
`docker_image`	提交好的镜像，如 `repolaunch/dev:robbert-vdh__nih-plug-28b149e_linux`
`docker_image_layers`	`{base_image, setup_layer[], organize_layer[]}`，可反向重建 Dockerfile
`rebuild_commands`	改代码后重编译的最小命令
`test_commands` / `print_cmds`	跑全量测试的命令 / 把测试输出打出来的命令
`log_parser`	一段 Python 脚本 `parser(log) -> {"用例名": "pass/fail/skip"}`
`test_status`	该 commit 下所有用例的基线状态映射
`pertest_command`	「只跑某一个用例」的命令映射（尽力而为，可能不存在）

一句话概括：镜像 + 重建命令 + 测试命令 + 解析器 + 用例级状态，这五样合起来才是一个能拿来判分的环境。

实现了哪些功能

能力	覆盖情况
语言	C / C++ / C# / Python / Java / Node.js（JS & TS）/ Go / Rust（9 个 handler）
平台	Linux / Windows / Android（Android 镜像基于 Linux 构建）；macOS 未实现
两阶段流水线	setup（探索式装环境）→ organize（蒸馏出干净命令与 parser）
镜像层 → Dockerfile	`gen_dockerfile` 从 `docker_image_layers` 反向重建，支持 linux/windows
测试输出 → 结构化状态	LLM 现场写 parser 并用真实日志回归验证，输出 `pass/fail/skip`
单用例运行命令	`testone` 阶段生成 `testcase → command` 映射
多 commit 结果复用	medium-commit 策略，同仓库多 commit 共享底镜像（见下文）
可编程 API	`LaunchedInstance.build/test/parse_test_log/apply_patch` 等
LLM 无关	LiteLLM 统一接入，支持任意 provider 与本地模型
历史依赖还原	PyPI 时间机器（仅 Python）

工作流与架构

两个 LangGraph 状态机，串成一条流水线：

flowchart TD
    A["输入 JSONL<br/>repo / base_commit / language"] --> B

    subgraph SETUP["① setup：把环境搞起来"]
        B["locate_related_file<br/>LLM 挑出 CI/README/setup 文档"] --> C["select_base_image<br/>从语言候选镜像里选基础镜像"]
        C --> D["start_bash_session<br/>起容器 + 语言环境准备"]
        D --> E["setup<br/>ReAct：装依赖 / 编译"]
        E --> F{"verify<br/>跑测试并输出<br/>逐用例状态"}
        F -->|报告问题| E
        F -->|"issue=None<br/>（容忍少量失败）"| G["save_result"]
    end

    G --> H["② organize：蒸馏出干净产物"]
    H --> I["rebuild<br/>最小重建命令 + 自动验证"]
    I --> J["testall<br/>跑全量测试 + 产出结构化日志"]
    J --> K["parselog<br/>写 parser 并用真实日志回归"]
    K --> L["testone<br/>单用例运行命令"]
    L --> M["organize.jsonl<br/>镜像 + 命令 + parser + 状态"]

三层结构，职责清楚：

层	模块	干嘛的
Agent 层	`launch/agent/`	LangGraph 节点：定位文档、选镜像、ReAct 装环境、验证、组织命令、生成 parser
Runtime 层	`launch/core/runtime.py`	统一 Docker 运行时接口，屏蔽平台差异（`SetupRuntime.from_base_image/from_launch_image`）
Platform 层	`launch/core/platforms/`	`linux.py` / `windows.py` / `android.py` 三套具体实现

再往上还有 launch/run.py：ThreadPoolExecutor 并发跑多实例，带 rich 进度条和 10 小时全局超时；launch/scripts/ 放辅助脚本。

三个值得注意的设计点

1. setup 与 organize 分离。 setup 阶段的命令历史是「脏」的——混着大量试错、报错、探索性命令。organize 阶段专门把这些蒸馏成最小重建命令和干净测试命令，而且每条提交都会自动执行验证，不通就带着错误重试。这个「先探索、再收敛、且收敛要过验证」的结构是整个项目最实用的一点。

2. 用纯文本 Thought-Action，而不是 tool call。 官方理由是：很多小参数量的开源模型处理不好 tool call 字段，纯文本放在 content 里兼容性最好。动作靠 XML 风格标签解析（<command> / <search> / <stop> / <submit> / <python>），见 launch/agent/action_parser.py。这个取舍直接决定了它适合拿来做 RL 训练。

3. PyPI 时间机器。 Python 项目有 created_at 时，会在宿主机起一个本地 Tornado PyPI 服务，只暴露 cutoff 日期之前发布的版本，再把容器里的 pip index-url 指过去。这样装出来的是当时真实存在的依赖版本，而不是今天的最新版——对复现历史环境很重要，也很少有工具做到。

多 commit 复用（省钱的关窍）

同一仓库往往要造多个 commit 的环境。朴素做法是每个 commit 从头跑一遍 Agent，成本高、镜像也重复。

launch/scripts/adjacent_commit_run.py 的做法：

选一个时间在中位的 commit，用 RepoLaunch 完整跑一遍
其余 commit 直接在 med 镜像上 git checkout，复用同一套 rebuild/test 命令与 parser
用「通过的测试数量」比对，判定这次 checkout 是否安全；不安全就重新分组、重选 med commit

实测数据（856 个 GitHub issue / 93 个仓库，GPT-5.6-Sol-Medium）：

指标	结果
环境构建成功率	≥ 98%（对比每个 commit 独立跑的 ~90%）
LM API 成本	省 82%
Docker 镜像存储	省 78%

成功率反而更高，原因是大量失败来自 LLM 生成随机性；复用 medium commit 的规则化 checkout 减少了随机性。

怎么用

pip install repolaunch          # 或 git clone && pip install -e .
export TAVILY_API_KEY=...       # Agent 的联网搜索
export OPENAI_API_KEY=...       # 或任意 LiteLLM 支持的 provider
 
launch data/examples/config.json

data/examples/config.json 里最需要关心的几项：mode（{"setup": true, "organize": true}，两阶段可分开跑）、model_config（直接透传给 LiteLLM）、max_workers（按机器规格定）、os（linux/windows/android）、max_steps_*（各阶段步数上限）、cmd_timeout（单条命令超时，分钟）。

跑完拿到结果后用起来是这样：

from launch.api import LaunchedInstance
 
instance = LaunchedInstance(instance_dict, "linux")   # 从 organize.jsonl 载入
instance.apply_patch(diff_patch)                       # 打上你的改动
status = instance.build_test_parse()                   # 重建 + 测试 + 解析
# {"testcase1": "pass", "testcase2": "fail", "testcase3": "skip"}

配套脚本：upload_docker 推镜像到 Docker Hub；gen_dockerfile 从 docker_image_layers 反向重建 Dockerfile（--platform linux|windows）；collect 在中断后手动汇总结果。

资源门槛与局限

门槛：

硬依赖 Git、Python ≥ 3.12、Docker；再加 TAVILY_API_KEY 和一个 LLM key
容器限制 CPU_CORES=4 / MEM_LIMIT=16g（launch/core/platforms/base.py）。官方文档写「每个实例约 4 CPU / 16GB」，大仓库如 ClickHouse 要 10 CPU / 64GB，推荐 ≥1TB SSD（docker commit 是磁盘 I/O 密集操作）
官方原话：「机器的性能直接决定成功率」
不能在容器化集群 pod 上跑（需要 Docker）

局限：

成功率受 LLM 随机性影响，同一仓库重跑结果可能不同——这也是多 commit 复用能提升成功率的原因
parser 由 LLM 生成，会幻觉。代码里直接注释了 TODO: wrap the execution in some safe container to avoid dangerous LLM hallucinations，parser 通过 exec() 执行；解析失败时 parse_test_log 会告警并返回空 dict
验证是「容忍式」的——prompt 里写明超过 85% 用例通过就判成功，少数失败不算环境问题
Windows/Android 支持成熟度低于 Linux，Windows 还得处理 legacy builder 的引号与换行问题（生成脚本用 sentinel 编码绕开）
macOS 明确未实现

与 SWE-bench-Live 的配套关系

这是它归在 submission/ 而不是 opensources/ 的原因——RepoLaunch 是打榜链路的第一环：

RepoLaunch            造环境 + 造题        ← 本页
    ↓
harness               跑 agent 产出 patch  ← [[submission/opensources/swe-agent-for-eval]]
    ↓
SWE-bench-Live evaluator   按测试状态判分   ← [[submission/swe-bench-live]]

它给 SBL 贡献的是「题目环境如何生成」这一层能力——SBL 的 issue 任务需要 base commit 上可运行的环境和可判定的测试集，这正是 RepoLaunch 的产出。官方也把「用 RepoLaunch 自动造新 SWE 数据集」列为项目的主要贡献方向。

信源

信息来自对本地 clone（~/6ai/opensources/RepoLaunch，HEAD 7b0d06e）的结构与核心源码分析：launch/run.py（并发调度与两阶段编排）、launch/core/workflow.py（两个 LangGraph 状态机的真实节点）、launch/agent/{setup,organize}/*（ReAct 循环与四类动作）、launch/agent/prompt.py（Thought-Action 约定）、launch/core/platforms/base.py（PS1 元数据注入、容器资源限制）、launch/utilities/{language_handlers,timemachine}.py（9 语言镜像候选与 PyPI 时间机器）、launch/scripts/{gen_dockerfile,parser,adjacent_commit_run}.py，以及 docs/Development.md、docs/Development-agent-memory.md、arXiv:2603.05026 摘要与 GitHub API 元数据（145 stars / MIT / 2025-09-08 创建）。数据截至 2026-09-22。

zhaoweiguo 的知识库

目录