ruflo GAIA L1 复现指南：稳定配置、收敛层与 34/53 得分的完整验证流程-开发者社区

ruflo GAIA L1 复现指南：稳定配置、收敛层与 34/53 得分的完整验证流程

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo

本文基于 ruflo 仓库的提交复现文档（docs/benchmarks/submission/reproduction.md），完整覆盖 GAIA Level 1 基准测试稳定配置（iter63 收敛层）的环境准备、构建、运行与结果验证全流程。读完本文，你可以精确复现34/53（64.2%）的基准成绩区间，理解收敛层（convergence layer）如何通过确定性终结机制消除空答案失败，并掌握从源码层面解读 harness 参数含义的方法。

复现目标与适用前提

这份文档针对的是 ruflo 提交的GAIA 2023 Level 1 验证集（53 题）稳定配置：

固定 commit：3ef6e175ddeb867135f00e843247aba2324d3c6d（打包时间 2026-05-28，对应 harness 包@claude-flow/cli版本 3.10.4，见 config.json）；
模型：claude-sonnet-4-6，纯 ToolCalling 路由模式；
核心特性：启用收敛层（convergence layer），即--enable-convergence标志。

需要说明的前提：当前仓库主干的 CLI 版本已演进（package.json 中的版本高于 3.10.4），若要对齐提交包中的成绩，必须 checkout 到上述 commit，而不是直接使用最新主干。提交包状态在 metadata.md 中标记为 "DRAFT — pending n=3 confirmation"，标题分 34/53 是 n=1 单次运行结果，官方口径要求以 n=3 均值为准。

前置依赖与环境变量

基础依赖：Node.js 20+、npm 9+、Git。

环境变量：

# Mandatory export ANTHROPIC_API_KEY=<your-key> # Optional (used for web search grounding) export GOOGLE_AI_API_KEY=<your-key> # Optional (HuggingFace for dataset access) export HF_TOKEN=<your-token>

文档明确要求：切勿将这些密钥回显或写入任何文件。结合仓库源码，这三个变量的实际解析逻辑如下：

ANTHROPIC_API_KEY是模型调用与 LLM-as-judge 判分的唯一必需凭据，在 gaia-bench 命令中通过resolveAnthropicApiKey()一次性解析并在所有题目间共享；
GOOGLE_AI_API_KEY用于 web 搜索接地（grounding）：从 grounded_query.ts 看，工具链调用 Gemini 2.5 Flash 的google_search接地工具获取检索证据，再由 Sonnet/Haiku 推理作答，源码同时支持回退到gcloud secrets versions access latest --secret=GOOGLE_AI_API_KEY读取；
HF_TOKEN用于从 HuggingFace 下载 GAIA 数据集。从 gaia-loader.ts 的源码结构看，其解析顺序为：先读$HF_TOKEN环境变量，失败则回退到 GCP Secret Manager 的huggingface-token密钥；数据集下载被真实 token 门控，而--smoke-only模式使用内置 5 题 fixture，无需 token。

克隆、检出与构建

git clone https://gitcode.com/GitHub_Trending/cl/ruflo cd ruflo git checkout 3ef6e175ddeb867135f00e843247aba2324d3c6d

cd v3/@claude-flow/cli npm install npm run build cd ../../..

构建脚本在 v3/@claude-flow/cli/package.json 中定义为tsc，产物落在dist/目录，main指向dist/src/index.js。这也解释了运行命令为何是node v3/@claude-flow/cli/dist/cli.js——执行的是编译后的 CLI 产物而非源码。

运行基准命令

node v3/@claude-flow/cli/dist/cli.js gaia-bench run \ --level 1 \ --model claude-sonnet-4-6 \ --limit 53 \ --enable-convergence

这条命令的完整参数集（含默认值）可以从 gaia-bench.ts 的命令定义中逐一核实，常用项如下：

参数	默认值	说明
`--level / -l`	`1`	GAIA 难度级别 1/2/3
`--limit / -n`	全部	最大运行题数
`--models / -m`	`claude-haiku-4-5`	逗号分隔的模型 ID 列表
`--output / -o`	`text`	输出格式`text`或`json`
`--concurrency / -c`	`3`	并行题数
`--max-turns`	`12`	每题最大 agent 轮数
`--smoke-only`	`false`	使用 5 题内置 fixture，无需 HF token
`--enable-convergence`	`true`	收敛层，默认开启，`--no-enable-convergence`仅用于消融实验
`--judge-model`	`claude-sonnet-4-6`	判分模型
`--voting-attempts`	`1`	自一致性投票次数（N>1 每题成本约 N 倍）
`--hardness-routing`	`false`	基于难度预测的分类器路由，按题覆盖`--max-turns`与投票次数
`--enable-critic`	`false`	答案对抗性评审；投票启用时自动让位（成本控制优先级）
`--decompose`	`false`	将复杂题分解为 1–5 个子问题
`--planning-interval`	`4`	每 N 个 tool_use 轮次注入规划检查点，0 禁用

值得注意的优先级规则（源码注释明确声明）：--hardness-routing按题覆盖--max-turns与--voting-attempts；--voting-attempts > 1时压制--enable-critic。收敛层标志的默认值是true，只有显式传入false才关闭——因此提交命令中写--enable-convergence属于显式声明而非额外开启。

收敛层：稳定配置的核心机制

--enable-convergence对应 gaia-convergence.ts 中的确定性终结层。该模块头部注释给出了设计动机（iter 60 复盘结论）：超过某个阈值后，检索深度、上下文规模、工具多样性等信息增量会提高轨迹熵，使 agent 更难一致地收敛到最终答案；收敛层是"熵减器"——它剥离信息而不是增加信息。

它监控三种导致空FINAL_ANSWER的失败模式，检测顺序固定为：

max_turns：轮数达到上限（默认 12）仍未调用 final answer；
token_overflow：各轮输入 token 累计达到TOKEN_OVERFLOW_THRESHOLD = 120_000；
loop：同一工具 + 同一参数（SHA-256 截断 16 位十六进制指纹）在最近 5 轮窗口内重复 3 次（LOOP_REPEAT_THRESHOLD = 3、LOOP_WINDOW_SIZE = 5）。

一旦触发，进入强制提交（forced commit）阶段：注入一条精简指令提示（"基于已有观察，用 FINAL_ANSWER: X 作答，不要再探索"），进行一次无工具的最终 API 调用；若响应中仍没有FINAL_ANSWER:标记，则对全部历史 assistant 消息从后往前运行 Stage 1 抽取级联，返回第一个非空命中；仍为空才返回 null 并记录失败模式。

提交配置 config.json 中收敛层的参数声明与源码一致：

"convergence_layer": { "enabled": true, "max_turns_per_question": 12, "max_loop_iterations": 3, "token_budget_per_question": 128000, "deterministic_finalization": true, "description": "After max_turns, extract best partial answer deterministically rather than returning empty" }

该层在 gaia-agent.ts 中被接线：agent 循环每轮更新ConvergenceState（轮数、累计 token、工具调用指纹日志），耗尽maxTurns时若收敛层启用则走强制提交路径，并在结果中标记convergenceTrigger（max_turns/loop/token_overflow）与convergenceUsedFallback（是否从历史消息恢复答案）。

稳定配置的工具开关

除收敛层外，iter63 配置对工具目录做了明确的开/关决策（见 config.json），这些决策均由隔离实验支撑：

启用：

T1_attachment_readers：xlsx、pptx、py、png、mp3 五种格式的原生附件读取器，对应 GAIA 附件题；
T2_extraction_cascade：策略为narrowed的定向正则 + 答案归一化抽取，防止 iter 52b 出现的过度抽取回归；
web_search（google 后端）与python_exec。

禁用（含拒绝理由）：

visit_webpage：iter 61a 隔离实验比基线净减 3 题——页面抓取失败返回的噪声部分内容会把模型带离正确的搜索接地答案；
CodeAgent_smolagents：iter 56 得分 30/53，比 ToolCalling 模式的 34/53 低 4 题，且引入 Python 执行错误、导入失败、代码生成幻觉等第二类失败模式。

组件增益归因（基线 iter49 为 21/53、39.6%）见 metadata.md：T2 定向抽取 +6、T1 附件工具 +2、混合路由中性（未采用）、收敛层 +2.5（把空答案失败转化为部分答案恢复）。同一模型在未调优的基线配置下仅 21/53，文档因此强调这是harness 工程结果而非模型能力结果。

预期输出与得分区间

按文档，运行结束时的终端汇总形如：

GAIA Level 1 — 53 questions Model: claude-sonnet-4-6 Convergence layer: enabled [...per-question PASS/FAIL lines...] Pass rate : 33-35/53 (62.3%–66.0%) Mean turns: ~4.6 Mean time : ~43s per question Estimated cost: ~$3.90 USD

其中逐题 PASS/FAIL 行的具体格式（answer="..." expected="..." turns=N N.Ns）与 gaia-bench.ts 中的判分日志一致；JSON 输出（--output json）的契约为顶层对象{ level, model, summary: { total, passed, passRate, estCostUsd, meanTurns, meanWallMs }, results: [...] }，每题含task_id、answer、expected_output、turns、wallMs、token 计数等字段。

预期得分区间为 33–35/53。文档特别警示：±2 题的方差来自 web 检索类题目——搜索结果页的可用性在不同运行间波动，不应把单次运行当作确定性分数，应以 n=3 均值作为口径。

成本核算

Anthropic API（claude-sonnet-4-6）：完整 53 题约 $3.50–$4.50 USD；
Google Search API：额外成本可忽略；
总计约 $4 USD/次复现。iter63 实测为 $3.89（42.9s/题均值）。

成本估算在 gaia-bench.ts 中有硬编码的价格表：claude-sonnet-4-6为每百万 token 输入 $3.0、输出 $15.0（Haiku $0.25/$1.25，Opus $15/$75），estCostUsd字段即按全量输入/输出 token 加权计算得出，可与账单交叉核对。

结果验证

运行结束后，将自己的结果与提交包预测文件 predictions.json 对比——该文件为 53 条逐题记录（task_id、model_answer、turns、wall_seconds、输入/输出 token 数，个别题带error字段如 "fetch failed"）：

# Quick check: count your passing questions node -e "const r=require('./your-results.json'); console.log(r.summary.passed + '/' + r.summary.total)"

单题层面的答案差异属于预期内（运行间方差所致）。标题分 34/53 是在特定时间、特定运行下测得的；你的复现允许 ±2 题偏差——如果跑出 32 或 36，同样落在预期分布内。

方差分析与提交纪律

提交包中配套的 variance-analysis.md 给出了完整证据链，复现者应了解以下口径：

n=4 次 T2+T1 配置运行（iter 53a–61b）：均值 29.25/53，区间 27–31，标准差 ±1.6 题，95% CI 约 26–32；
题级稳定性分类：约 22 题稳定 PASS（单跳事实查询、数学、逻辑题）、约 12 题稳定 FAIL（视频帧级理解、深多跳维基链、特定数据结构反演、空答案失败）、约 19 题翻转（跨运行不一致，是分数方差的主要来源）；
翻转的三类典型模式：搜索可用性（中间页可能未被检索后端命中）、抽取精度（找对页面但抽错数字）、格式敏感（答案有多种可接受形式）。

文档同时解释了"为何提交均值而非峰值"：收敛层降低但不消除方差（翻转题仍然翻转）；HAL 要求可复现结果，单次幸运峰值不构成有效提交。提交策略为：n=3 均值 ≥35 以均值提交；33–34 如实报告均值并说明未达 HAL 前十门槛；<33 先排查回归再提交。空答案问题（iter63 有 8 题返回空串）被明确记为 harness 的真实局限，收敛层的目标就是把这类空串转化为部分答案恢复——逐题清单（含 task_id 与失败轮数）可在 variance-analysis.md 中查证。

延伸阅读与相关文件

reproduction.md：本文主体，复现步骤原文；
config.json：iter63 精确 harness 配置（commit、模型、收敛层参数、工具开/关）；
metadata.md：组件归因表、被拒组件根因、诚实定位（明确不做平级声明，HAL 榜首约 82%，本配置 64.2%）；
variance-analysis.md：全部实测运行表与题级稳定性分类；
predictions.json：53 题逐题预测答案与运行指标；
witness.json：提交包的 Ed25519 签名与五文件哈希，用于完整性校验；
gaia-bench.ts：gaia-bench run命令实现（参数、优先级、判分、成本估算）；
gaia-convergence.ts：收敛层实现（触发器检测、强制提交、抽取级联回退）；
gaia-loader.ts：数据集加载与HF_TOKEN解析回退链。

各迭代的历史运行结果（iter48–iter63b 的逐次 JSON）存放在 docs/benchmarks/runs/ 目录，可用于对照配置演化过程中的分数轨迹。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ruflo GAIA L1 复现指南：稳定配置、收敛层与 34/53 得分的完整验证流程