1. 为什么 SWE-Explore 值得单独拎出来看如果你最近在折腾仓库级 Coding Agents大概率已经被 SWE-bench 的「resolved / unresolved」二元结果折磨过跑完一轮只知道没修好却不知道是压根没找到相关代码还是找到了但 patch 写歪了。SWE-Explore 这个基准干的事就是把「探索仓库」这一步单独拆出来评测——给定一个仓库和一个 issue让 explorer 在固定行预算下返回一份排序后的相关代码区域列表再用行级 ground truth 去算覆盖、排序、上下文效率三类指标。它覆盖 848 个 issue、10 种编程语言、203 个开源仓库ground truth 来自那些真正把 issue 修成功的 agent 轨迹蒸馏出它们实际读过的代码区域。换句话说它衡量的是「你找得准不准」而不是「你最后修没修好」。这对需要复现基准、或者想给自己的 agent 接一套探索评测的开发者来说价值很直接你能定位到瓶颈到底在召回还是在排序。这篇不打算复述论文而是把「怎么把 SWE-Explore 这类基准任务跑起来」这件事讲透顺带给出用 TaoToken 统一 Key/API 通道的 config.toml 与 settings.json 骨架最后跑一次任务并校验日志。适合已经在写 agent harness、准备接基准、或者被多模型 Key 管理搞烦的人。2. 前置用 TaoToken 统一模型通道SWE-Explore 的评测里explorer 和 patcher 经常要换不同底模对比论文里就用了 GPT-5.4、Gemini-3-Pro 这类 patcher 做下游验证。如果你每个模型都单独配一套 Key、单独改 base_urlharness 里会到处是硬编码复现实验时非常痛苦。TaoToken 在这里的角色是统一入口一个 Key、一个 API 地址就能在多个模型之间切换配置集中在配置文件里换模型只改一个字段。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意这个不带 UTM 参数写进配置里就用它。你需要先拿到 Key进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建一个。建议按实验批次建 Key比如swe-explore-batch1方便后面看用量、定位是哪轮跑爆了。注意Key 只放在本地配置文件或环境变量里别提交进 git。基准仓库里经常有.env.example照着填但别把真 Key 写进 example。3. 可复制配置骨架config.toml 与 settings.json下面这套骨架的思路是把「模型通道」和「agent 行为」分开。config.toml管模型和 APIsettings.json管 explorer 的预算、返回区域数、日志路径。两者都只依赖 TaoToken 一个入口。3.1 config.toml# config.toml —— 模型通道统一走 TaoToken [api] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY # 从环境变量读别写死 timeout_seconds 120 max_retries 3 [models.explorer] name claude-sonnet-4-5 # explorer 用的底模 temperature 0.2 max_tokens 4096 [models.patcher] name gpt-5.4 # 下游 patcher用于验证探索质量 temperature 0.0 max_tokens 8192 [logging] level INFO log_dir ./logs/swe-explore save_raw_response true # 排障时非常关键关键点base_url只写一次explorer 和 patcher 共用换模型只改[models.*].name。save_raw_response true是我强烈建议开的后面校验日志时你会感谢自己。3.2 settings.json{ benchmark: swe-explore, dataset_split: test, explorer: { top_k_regions: 5, line_budget: 500, return_format: ranked_regions, max_turns: 30 }, repo: { clone_depth: 1, workdir: ./workspace/repos, language_filter: [python, java, go, typescript] }, evaluation: { metrics: [hit_file, hit_region, rec_at_l, context_efficiency, ndcg_at_500], ground_truth_source: agent_trajectories }, output: { result_dir: ./results/swe-explore, save_trajectory: true } }top_k_regions 5对应论文里 K5 的设置和平均 4.7 个 ground truth 区域对齐。line_budget控制返回区域的总行数上限这是 SWE-Explore 的核心约束之一——不是让你无限返回而是在预算内比排序质量。3.3 环境变量export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-...。设完可以echo $TAOTOKEN_API_KEY确认一下别设了个空值自己不知道。4. 跑通一次基准任务并校验日志配置就位后先别急着跑全量 848 个实例挑一个单实例验证链路。4.1 单实例运行python -m swe_explore.run \ --config ./config.toml \ --settings ./settings.json \ --instance_id swe-explore-py-0042 \ --repo_lang python \ --output ./results/swe-explore/single跑之前确认./workspace/repos目录存在否则 clone 会失败。第一次跑建议把max_turns临时调到 10快速看链路通不通通了再放开。4.2 成功结果长什么样跑完后./results/swe-explore/single下会有exploration.jsonexplorer 返回的 ranked regions每条含文件路径、起止行、score。trajectory.jsonl每一步的交互轨迹包括读了哪些文件、调了哪些工具。metrics.json本次实例的 hit_file、rec_at_l、context_efficiency 等。metrics.json里如果hit_file是 true 但rec_at_l只有 0.1 出头别慌——这正是论文里说的典型现象文件级定位已经不错行级召回才是瓶颈。大多数非 Oracle explorer 的 Recℓ 就在 0.14–0.19 这个区间。4.3 日志校验动作校验分三步别跳。第一步确认请求真的走了 TaoTokengrep -i taotoken.net/api ./logs/swe-explore/*.log | head -5应该能看到 base_url 命中的记录。如果看到的是别的域名说明配置没生效检查config.toml的base_url和环境变量优先级。第二步确认模型名和预期一致grep -i model ./logs/swe-explore/*.log | sort | uniq -c输出里 explorer 和 patcher 的模型名应该分别对应你配置里的值。如果 explorer 那行显示的是 patcher 的模型说明[models.*]段读串了。第三步看原始响应有没有被截断python -c import json,glob for f in glob.glob(./logs/swe-explore/*raw*.json): djson.load(open(f)) if d.get(finish_reason)length: print(截断:,f) 有截断就调大max_tokens或者把 explorer 的单轮输出约束得更紧。这一步能帮你排除「模型没答完」被误判成「探索失败」的情况。5. 本篇常见错排查5.1 401 / 403Key 没读到最常见的原因是环境变量名对不上。config.toml里写的是api_key_env TAOTOKEN_API_KEY那你 export 的就必须是这个名字大小写敏感。另一个坑是用了source ~/.bashrc但当前 shell 没重载echo一下确认。5.2 返回区域数不是 5检查settings.json的top_k_regions有没有被命令行参数覆盖。有些 harness 会优先读 CLI 参数你改了 json 但 CLI 传了--top_k 10结果就是 10。跑之前--dry-run打印一下最终生效配置最稳。5.3 rec_at_l 异常低但 hit_file 正常这不是 bug是 SWE-Explore 想暴露的核心问题。行级召回低说明 explorer 找到了文件但没定位到具体行区间。可以试着在 explorer 里加一轮「迭代代码图搜索」——论文里 CoSIL 就是靠这个把 Recℓ 显著拉高的比单纯换更强底模有效。5.4 日志里出现空上下文基线论文提到一个反直觉现象在容易子集上空上下文时模型靠 issue-only 先验反而略优于少量不完整上下文。如果你发现某个实例 explorer 返回了空区域但 patcher 居然修好了别急着当成探索成功——这可能是空上下文基线被高估评估时要单独标记出来。5.5 clone 超时或仓库太大clone_depth 1已经是最浅了还是慢的话把language_filter收窄先只跑 python 子集。203 个仓库全量 clone 对磁盘和网络都是考验分语言批次跑更现实。6. 接下来怎么接链路跑通之后下一步通常是两件事一是把 explorer 换成你自己的实现接进settings.json定义的接口二是做多模型对比看换底模对 Recℓ 的影响。后者用 TaoToken 会很省事——config.toml里改一行[models.explorer].name重跑同一批实例日志里模型名自动区分不用维护多套 Key。如果你要长期跑这类基准、或者把探索评测接进 CI建议直接上 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配额和并发更稳不会跑到一半被限流打断。想先手动验证某个模型在探索任务上的表现可以开模型对话 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 直接试一轮确认输出格式符合ranked_regions再写进 harness。接入细节和参数说明都在接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里配置字段对不上时优先查它。最后留一个实操建议第一次跑全量前先用 10 个实例做一轮 smoke test重点看metrics.json里context_efficiency和rec_at_l的分布确认没有全 0 或全 1 的异常值。这两个指标在论文里和下游修复成功率的 Pearson r 达到 0.95是最值得盯的两个数。
