forgejudge

最终结果 — 最后一次完整测评，2026-07-02（第 34 次运行；隐藏测试 = Agent 看不到失败的测试；免费层费用为 $0；使用相同测试框架，仅切换模型；18 项任务 × 3 个种子 = 每个模型 54 次运行，总计 162 次）：

模型	pass@1	pass@3	当前状态
llama-3.3-70b-versatile	98.1%	100%	Groq 于 2026-08-16 停用
gpt-oss-120b	94.4%	94.4%	可用
llama-3.1-8b-instant	57.4%	72.2%	Groq 于 2026-08-16 停用

测试框架保持不变时，8B 模型比 70B/120B 模型低约 40 个百分点（这就是模型切换所显示的差异），而 pass@3 ≥ pass@1 反映了不同运行之间的波动——这正是 CI 门禁采用多种子测试的原因。每次运行的补丁都记录在 runs.json 中，重新评分后会得到相同结论；指向原项目的 Langfuse 追踪链接预计已无法访问。详情、之后未公开的测评，以及已停用的模型：docs/ARCHIVE.md。

ForgeJudge 是一个开源的自主软件工程 Agent。在维护期间，它通过每次提交公开验证自身质量：手工编写的单 Agent 求解器、确定性的“执行即评判”测试框架、包含单次运行追踪记录的排行榜（现已冻结为快照），以及用于阻止回归的 CI 门禁——所有组件都运行在一套**$0 / 可自托管的技术栈上，并针对一组抗数据污染、可通过内在机制验证**的黄金测试集。

交付成果是精心设计的测试框架、可观测性和门禁，而不是高通过率。 使用 $0 免费模型的 Agent 得分不高是设计使然。我们通过模型切换对比来证明其价值：在测试框架保持不变时，更好的模型会取得更高分数。

工作原理

flowchart TD
    G["Golden set · Git-canonical<br/>18 intrinsically-verifiable, mutation-hardened<br/>make-CI-green tasks"]

    subgraph SOLVER["Single-agent solver"]
        direction LR
        L["localize<br/>(BM25)"] --> R["repair<br/>(LLM router · critic · syntax edit-gate)"] --> V["validate<br/>(run tests)"]
    end

    G --> SOLVER
    SOLVER --> PATCH["unified diff"]
    SOLVER -. "every step traced" .-> TRACE["OTel → Langfuse<br/>per-run trace"]

    PATCH --> H["Deterministic harness, in a sandbox<br/>apply test_patch + candidate patch · run F2P / P2P<br/><b>RESOLVED iff</b> every FAIL_TO_PASS passes AND every PASS_TO_PASS stays green<br/>swebench-equivalent · stricter on skips · cheat-resistant"]

    H --> STORE["Run store<br/>Neon + pgvector"]
    STORE --> LB["Leaderboard<br/>pass@1 / pass@3 · cost · tokens · trace link"]
    H --> GATE["Multi-seed CI gate<br/>a PR that lowers the resolution rate fails the build"]

    style G stroke:#3fb950,stroke-width:2px
    style H stroke:#4cc2ff,stroke-width:2px
    style GATE stroke:#f0883e,stroke-width:2px

• 求解器 — 一个按阶段组织的循环（localize → repair → validate），不是多 Agent 群体：成本最低、确定性最强，也最易调试。使用 BM25 定位、通过免费层级调用的大模型路由器、语法编辑门控、低成本评审器预筛，以及带自动提交功能的成本/步数预算。
• 测试框架 — 编码了 SWE-bench RESOLVED_FULL 规则，并在 CI 中通过真实的 PASS/FAIL/ERROR/XFAIL 结果验证与 swebench.harness.grading 等效；对于被跳过的 FAIL_TO_PASS，则刻意采用更严格的判定：swebench 4.1.0 会将被跳过的 oracle 测试判为 RESOLVED_FULL（跳过既不算成功，也不算失败），因此，让 oracle 跳过而不是运行的补丁也会被判为已解决。ForgeJudge 将跳过视为未通过，从而堵住这一作弊途径。补丁也具备防作弊能力：评分前会还原规范测试文件，因此补丁无法使 oracle 失效。
• 黄金集 — 15 个专门构建的截止时间后样例，以及从作者自己的代码仓库中挖掘的 3 个任务（真实提交 SHA，MIT/自有许可证 — 无泄漏/左版风险）。每个样例都经过变异强化：对已修补区域的错误修复会被检测到（16 个经过变异强化，平均得分为 0.94；2 个因正则表达式/字符串代码而无法定论；0 个薄弱样例）。
• 沙箱 / CI / 扫描 — 在公开仓库上运行的 GitHub Actions 一举三得（临时隔离 VM 沙箱 + 回归门控 + 排行榜扫描），成本为 $0。归档前，扫描每晚运行；现在改为手动触发（workflow_dispatch）。
• 可观测性 — OpenTelemetry GenAI 跟踪跨度（invoke_agent → retrieval / chat / execute_tool、gen_ai.usage.*、gen_ai.evaluation.result 通过/失败判定）导出到 Langfuse Cloud；每次运行都会记录跟踪链接（位于原始 Langfuse 项目中；归档后不再保证链接有效）。

两道门控，各司其职

确定性的黄金集完整性门控（测试框架本身是否仍正常工作？）与随机性的回归门控（某项更改是否让 Agent 明显变差？）彼此分开 — 因为黄金集评分是确定性的，绝不能与每个种子的噪声运行结果取平均。

flowchart TD
    PR["Pull request / commit"] --> GG["Gold-integrity gate<br/>deterministic · $0 · re-grade all gold patches"]
    GG -->|"any gold task unresolved"| F1["fail — the harness broke"]
    GG -->|"all gold tasks resolved"| OK1["harness intact"]

    CRON["On-demand multi-seed sweep"] --> SEEDS["run the agent × N seeds<br/>→ one resolution rate per seed"]
    SEEDS --> RG["Regression gate<br/>small-sample CI (Student-t / Wilson)"]
    BASE["baseline_scores.json<br/>per-seed reference"] --> RG
    RG -->|"candidate CI upper bound &lt; baseline CI lower bound"| F2["❌ fail — real regression"]
    RG -->|"overlapping · equal · improved"| OK2["✓ no regression"]

    style GG stroke:#4cc2ff,stroke-width:2px
    style RG stroke:#f0883e,stroke-width:2px

快速开始

前置条件：uv（已为你配置 Python 3.12）— curl -LsSf https://astral.sh/uv/install.sh | sh。

git clone https://github.com/ahmedEid1/forgejudge && cd forgejudge
uv sync                       # Python 3.12, deps via uv

# Run the deterministic harness self-test (no API key, no network):
uv run python -m forgejudge.harness.runner_actions --patch-source gold   # 18/18 resolved

# Solve a task with a free model and grade it.
# Needs a (free) Groq key. Either export it, or put it in .env and pass --env-file:
#   export GROQ_API_KEY=...                     # or
#   cp .env.example .env && edit GROQ_API_KEY   # then: uv run --env-file .env python - <<'PY'
uv run python - <<'PY'
from forgejudge.golden.loader import load_tasks
from forgejudge.agent.solver import solve
from forgejudge.harness.grade import grade
task = {t.instance_id: t for t in load_tasks("golden/dataset.jsonl")}["fixture-semver-001"]
res = solve(task, run_id="demo", budget_usd=0.10, seed=0)
print(res.status, "→ resolved:", grade(task, res.patch).resolved)
PY

快速测试：uv run pytest -m "not slow"。完整黄金集验证 + 变异强化：uv run pytest -m slow。不使用数据库，扫描单个模型：uv run --env-file .env python -m forgejudge.eval.sweep --model groq/openai/gpt-oss-120b --seeds 0,1,2 --no-store --out runs-0.jsonl。完整的重新运行指南（密钥、数据库、部署）见 docs/ARCHIVE.md。完整的 pytest 标记说明和开发工作流见 CONTRIBUTING.md。

安装

要开发 Agent/测试框架本身？克隆仓库并运行 uv sync（见上文）。若要将 ForgeJudge 用作软件包：

已发布的 forgejudge==0.1.0 早于归档：其 models.yaml 在多个角色链中仍列有已弃用的 llama-3.3-70b-versatile。solve() 仍可通过其主模型 gpt-oss-120b 正常工作，但要使用当前角色链，请从 git 安装（pip install git+https://github.com/ahmedEid1/forgejudge）。

# Library + the `forgejudge` CLI (selftest / mcp / info):
pip install forgejudge
forgejudge selftest           # deterministic harness check — 18/18 resolved, no key
forgejudge mcp                # MCP server over stdio (needs the [mcp] extra)

# Zero-install MCP server (no venv to manage) — for an MCP client config:
uvx --from "forgejudge[mcp]" forgejudge mcp

可选扩展（仅在需要时安装）：

扩展	引入内容	用途
forgejudge[harness]	swebench	swebench 等效性评分检查
forgejudge[mcp]	fastmcp	MCP 服务（forgejudge mcp）
forgejudge[playground]	fastapi、uvicorn、httpx	受保护的实时 playground API（自托管；托管实例已不再维护）

pip install "forgejudge[mcp]"            # one extra
pip install "forgejudge[harness,mcp]"    # several

基础安装即可运行 forgejudge selftest 和 forgejudge info — 无需扩展、API 密钥或网络连接。

六项质疑，逐一回应

1. “你的基准测试受到污染／经过精心挑选。” 黄金集为近期编写／截止日期之后编写，仅取材于作者自己的代码仓库和固定样例（不存在第三方泄漏风险），并经过变异加固，确保错误补丁无法通过测试。SWE-bench Verified 现在普遍被认为已受污染——OpenAI 已停止报告该基准的结果（2026-02）；超过 32% 的“通过”案例泄漏了解决方案，约 31% 的案例通过了较弱的测试。这里的去污染是一项有文档记录且经过测试的特性，并非脚注。
2. “只是 LLM／框架的薄封装。” 编排器是手工编写的（未使用 LangChain）：控制循环、沙箱与评分测试框架、抗作弊评分器、变异加固器、OTel 插桩，以及多随机种子 CI 门禁，才是实际工作所在。
3. “你的解决率比 SOTA 低。” 使用高端模型和充足预算时，SOTA 约为 88–94%；$0 免费模型的结果刻意保持适中。交付成果是经过工程化设计的系统；模型替换对比（固定测试框架，更好的模型带来更高分数）就是证明。
4. “它真的自主运行，还是预先安排好的？” 每次运行都会记录 OpenTelemetry/Langfuse 跟踪记录，每个已存储的补丁都能通过重新评分，以确定性的方式复现其记录的判定结果。优先回放的演示环境展示了真实的解决过程，同时避免暴露成本／滥用风险。
5. “三个 Agent 项目——只会一招？” 三个领域采用同一种评估方法——黄金集 + 评判器 + 跟踪记录 + CI 门禁——自主程度逐步提高（Lumen → Thoth → ForgeJudge）。
6. 确定性。 temperature=0 并不保证确定性（pass@1 会有 2–6 个百分点的波动）。评分器完全确定；门禁使用多个随机种子（仅当候选版本的 CI 上界低于基线的 CI 下界时才失败），因此单次运行的不稳定不会导致构建失败。

仓库结构

路径	内容
forgejudge/golden/	黄金集加载器、固定样例契约、数据集构建器、变异加固器
forgejudge/harness/	确定性的 grade()、抗作弊运行器、swebench 等效性检查、沙箱执行器
forgejudge/agent/	localize → repair → validate 解决循环、评论器
forgejudge/llm/	基于角色的 LiteLLM 路由器，支持回退和成本核算
forgejudge/obs/	OpenTelemetry GenAI 跟踪 → Langfuse / Phoenix
forgejudge/eval/	排行榜测试、质量门控发布、多随机种子回归门禁、LLM-as-judge + Cohen's κ
forgejudge/store/	Neon（Postgres + pgvector）运行记录存储 + 排行榜查询
golden/dataset.jsonl	规范黄金集（每行一个 Task）
.github/workflows/	ci、gate（黄金集完整性）、eval（沙箱）、regression-gate、release（推送 v* 标签或按需触发），以及仅手动触发的 sweep、pages-deploy、publish-mcp
docs/	DESIGN.md（技术深入介绍）、ARCHIVE.md（最终结果 + 重新运行指南）

许可证

MIT © 2026 Ahmed Hobeishy。导入并注明采用 MIT 许可的 swebench 评分测试框架。