SWE-Explore 基准解读：Coding Agents 如何探索 Repositories 与 TaoToken 配置骨架

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_url，harness 里会到处是硬编码，复现实验时非常痛苦。

TaoToken 在这里的角色是统一入口：一个 Key、一个 API 地址，就能在多个模型之间切换，配置集中在配置文件里，换模型只改一个字段。官网入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api （注意这个不带 UTM 参数，写进配置里就用它）。

你需要先拿到 Key：进控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，在 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 创建一个。建议按实验批次建 Key，比如swe-explore-batch1，方便后面看用量、定位是哪轮跑爆了。

注意：Key 只放在本地配置文件或环境变量里，别提交进 git。基准仓库里经常有.env.example，照着填但别把真 Key 写进 example。

3. 可复制配置骨架：config.toml 与 settings.json

下面这套骨架的思路是：把「模型通道」和「agent 行为」分开。config.toml管模型和 API，settings.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对应论文里 K=5 的设置，和平均 4.7 个 ground truth 区域对齐。line_budget控制返回区域的总行数上限，这是 SWE-Explore 的核心约束之一——不是让你无限返回，而是在预算内比排序质量。

3.3 环境变量

export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

Windows PowerShell 用$env:TAOTOKEN_API_KEY="sk-..."。设完可以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.json：explorer 返回的 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 日志校验动作

校验分三步，别跳。

第一步，确认请求真的走了 TaoToken：

grep -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'): d=json.load(open(f)) if d.get('finish_reason')=='length': print('截断:',f) "

有截断就调大max_tokens，或者把 explorer 的单轮输出约束得更紧。这一步能帮你排除「模型没答完」被误判成「探索失败」的情况。

5. 本篇常见错排查

5.1 401 / 403：Key 没读到

最常见的原因是环境变量名对不上。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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，配额和并发更稳，不会跑到一半被限流打断。想先手动验证某个模型在探索任务上的表现，可以开模型对话 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 直接试一轮，确认输出格式符合ranked_regions再写进 harness。接入细节和参数说明都在接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 里，配置字段对不上时优先查它。

最后留一个实操建议：第一次跑全量前，先用 10 个实例做一轮 smoke test，重点看metrics.json里context_efficiency和rec_at_l的分布，确认没有全 0 或全 1 的异常值。这两个指标在论文里和下游修复成功率的 Pearson r 达到 0.95，是最值得盯的两个数。