复现论文实验
仓库中的 experiments/ 目录包含了论文实测结果背后的完整评估框架、容器执行器、启动脚本与汇总分析工具。它独立于日常安装的插件，两者仅共享底层的 tokeneconomizer/ 标准库包。
目录分工
| 子目录 | 职责说明 |
|---|---|
te_harness/ | 在每个 SWE-Bench 任务的 Docker 镜像内（Web-Bench 则在宿主机上）运行智能体 CLI，并调用基准自带的官方评分器进行判分 |
te_bench/ | 各实验组（arms）定义、基准领域适配器（adapters）以及被评估的任务集加载器（workloads.py） |
scripts/ | launch/（批量启动器）、run_experiment.py（单条任务流运行器）、aggregate.py（结果汇总）与 compare_arms.py（成对成本/通过率比较） |
workloads/ | 被评估的任务 ID 清单：swebench.json（277 个任务）、webbench.json（102 个任务）以及两个安全审计任务集 |
tests/ | 无需 Docker、外部数据集或 API 密钥即可运行的离线单元测试 |
环境要求
- 操作系统与磁盘：Linux x86_64，配置好免
sudo的 Docker，并预留约 200 GB 磁盘空间用于存放 SWE-Bench 任务镜像。 - 基础工具链：Python 3.10+、git，以及带 npm 的 Node.js（供 Web-Bench 构建使用）。
- API 密钥：一个 Anthropic API Key（供 Claude Code 与 Copilot CLI 计费）和一个 OpenAI API Key（供 Codex 计费）。
- 宿主机智能体 CLI：在宿主机上安装论文所使用的精确版本，评估框架会将它们挂载进每个任务容器中：
宿主机安装固定版本 CLI
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.170 # Claude Code
npm install -g @openai/codex@0.153.1 # Codex
curl -fsSL https://gh.io/copilot-install | VERSION=1.0.84-7 bash # Copilot CLI五步环境配置
1. 安装代码与运行离线测试
进入 experiments 目录后，后续所有命令都在该目录下执行：
步骤 1 · 安装与烟雾测试
git clone https://github.com/microsoft/TokenEconomizer.git && cd TokenEconomizer
python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[test,baselines]' # baselines 会安装 aider，供 RepoMap 对照组使用
cd experiments
python -m pytest tests -q
bash scripts/launch/smoke_test.sh # 使用桩智能体（stub agent）端到端验证所有实验组接线2. 准备 SWE-Bench 数据与镜像
请在仓库外部选择一个数据目录，并务必使用 readlink -f 解析出规范绝对路径（如果通过符号链接访问，Web-Bench 的所有测试都会失败）：
步骤 2 · 导出任务并拉取 277 个镜像
export DATA="$(readlink -f ~/te_data)"
git clone https://github.com/SWE-bench/SWE-bench.git "$DATA/SWE-bench"
pip install -e "$DATA/SWE-bench" # 将官方评分器安装到当前虚拟环境
python scripts/export_swebench_tasks.py --out-dir "$DATA/swebench"
docker login # 匿名拉取镜像会触发速率限制
xargs -a "$DATA/swebench/image_tags.txt" -P 4 -n 1 docker pull -q3. 构建 Web-Bench 五个受测项目
拉取并构建评估所用的五个 Web-Bench 项目，同时安装它们锁定的 Playwright 浏览器内核：
步骤 3 · 构建 Web-Bench
git clone https://github.com/bytedance/web-bench.git "$DATA/web-bench"
( cd "$DATA/web-bench" && npm install -g @microsoft/rush && rush install \
&& rush build --to @web-bench/eval --to @web-bench/calculator --to @web-bench/expressjs \
--to @web-bench/react --to @web-bench/zustand --to @web-bench/table \
&& cd projects/calculator && npx playwright install chromium chromium-headless-shell )
export TOKENECONOMIZER_WEBBENCH_PROJECTS="$DATA/web-bench/projects"
export TOKENECONOMIZER_WEBBENCH_TASKS="$DATA/webbench_tasks.json"
python scripts/webbench_tasks_from_yaml.py --all # zustand 项目仅自带 tasks.yml
python scripts/export_webbench_tasks.py4. 配置 .env 密钥与路径
复制 cp .env.example .env，并填入展开后的绝对路径（.env 文件不支持变量展开）：
| 环境变量 | 填写说明 |
|---|---|
ANTHROPIC_API_KEY, OPENAI_API_KEY | 你自己的 Anthropic 与 OpenAI API 密钥 |
COPILOT_PROVIDER_API_KEY | 再次填入你的 Anthropic 密钥（Copilot CLI 通过自带的 provider 设置直接向 Anthropic 计费） |
DATA | 步骤 2 中确定的规范数据目录绝对路径 |
TOKENECONOMIZER_RESULTS | 实验结果输出目录，例如 $DATA/results |
TOKENECONOMIZER_SWEBENCH_TASKS | $DATA/swebench/swebench_tasks.json |
TE_SWEBENCH_REPO | $DATA/SWE-bench |
TOKENECONOMIZER_WEBBENCH_PROJECTS, TOKENECONOMIZER_WEBBENCH_TASKS | 与步骤 3 中导出的两个绝对路径一致 |
5. 单任务真机冒烟验证
在启动大规模全量实验前，先跑 1 个真实计费任务，确认能够产出包含评分的完整记录：
步骤 5 · 单任务验证
AGENT=claude MODEL=claude-sonnet-5 DOMAIN=swebench ARMS=baseline REPOS=sympy/sympy SEEDS=0 \
LIMIT=1 DETACH=0 RUNNER=te_harness.swebench:make_runner bash scripts/launch/main_sweep.sh运行完成后，检查 $TOKENECONOMIZER_RESULTS/claude_swebench_sonnet5/baseline/sympy_s0/ 下的 row.json，应能看到大于 0 的 num_turns、非空的 token 统计以及 resolved 布尔值。
运行论文实验组
main_sweep.sh 负责运行 Claude Code 与 Copilot CLI，codex_ab.sh 负责运行 Codex。每条命令代表一条实验通道（lane）：在所有受测仓库或项目上，使用随机种子 0、1、2 依次跑完列出的所有实验组（arms）。重复执行同一条命令会自动跳过已完成的单元（断点续跑）；加上 DRYRUN=1 可仅打印执行计划。
| 代码中的 Arm 名称 | 对应论文中的实验组 |
|---|---|
baseline / baseline-medium / baseline-low | 默认执行配置（高、中、低推理强度） |
rtk / repomap | 固定策略基线：RTK（压缩终端输出）与 RepoMap（仓库符号地图） |
trimech（Codex 上为 codex-trimech） | TokenEconomizer（三大机制全开） |
trimech-rtk / trimech-repomap | TokenEconomizer + RTK、TokenEconomizer + RepoMap 组合 |
inject-only / untool-only / spiral-only | 消融实验：单独启用微技能、工具剪枝或失败循环干预 |
trimech-web | Web-Bench 上的 TokenEconomizer 配置（适配较短的任务流） |
SWE-Bench：复现论文表 1、图 1(b)、图 5 及表 2(a) 消融实验
SWE-Bench 全量启动脚本
SWE="baseline baseline-medium baseline-low rtk repomap trimech trimech-rtk trimech-repomap"
for MODEL in claude-sonnet-5 claude-opus-4-8; do
AGENT=claude MODEL=$MODEL DOMAIN=swebench ARMS="$SWE inject-only untool-only spiral-only" \
RUNNER=te_harness.swebench:make_runner bash scripts/launch/main_sweep.sh
done
AGENT=copilot MODEL=claude-sonnet-5 DOMAIN=swebench ARMS="$SWE" \
RUNNER=te_harness.swebench:make_runner bash scripts/launch/main_sweep.sh
for MODEL in gpt-5.6-terra gpt-5.6-sol; do
MODEL=$MODEL DOMAIN=swebench \
ARMS="baseline baseline-medium baseline-low rtk repomap codex-trimech codex-trimech-rtk codex-trimech-repomap" \
RUNNER=te_harness.swebench:make_runner bash scripts/launch/codex_ab.sh
doneWeb-Bench：复现论文表 2(b)
Web-Bench 全量启动脚本
for MODEL in claude-sonnet-5 claude-opus-4-8; do
AGENT=claude MODEL=$MODEL DOMAIN=webbench ARMS="baseline trimech-web" \
RUNNER=te_harness.webbench:make_runner bash scripts/launch/main_sweep.sh
done
AGENT=copilot MODEL=claude-sonnet-5 DOMAIN=webbench ARMS="baseline trimech-web" \
RUNNER=te_harness.webbench:make_runner bash scripts/launch/main_sweep.sh
for MODEL in gpt-5.6-terra gpt-5.6-sol; do
MODEL=$MODEL DOMAIN=webbench ARMS="baseline codex-trimech" \
RUNNER=te_harness.webbench:make_runner bash scripts/launch/codex_ab.sh
done防作弊答案守卫（Answer-key Guard）。 包括
baseline 在内的所有实验组都运行在统一的防作弊守卫下：通过 PreToolUse 钩子与容器内 /etc/hosts 屏蔽规则，禁止智能体直接从 GitHub 获取基准测试的公开答案，并移除联网工具。结果汇总与对比
每条通道会将结果写入 $TOKENECONOMIZER_RESULTS/<agent>_<benchmark>_<model>/（例如 claude_swebench_sonnet5），每个任务目录下包含 row.json、transcript.jsonl 与 run_config.json。通道结束时，aggregate.py 会自动生成 index/all_rows.csv 与 index/summary_by_cell.csv。
使用 compare_arms.py 可以将任意实验组与基线按任务实例一一配对，输出计入缓存定价与插件自身模型调用后的净成本变化及解决任务数对比：
成对比较实验组与基线
python scripts/compare_arms.py --baseline <tree>/baseline/<cell> --arm <tree>/<arm>/<cell>如果你在复现过程中遇到报错，请查阅 故障排查与诊断 页面中的实验排障表，或参考上游仓库的 experiments/README.md。