agent/runtime: integrate Harbor SkillsBench as the first Harbor benchmark onboarding example

[Shuo-O]

Issue Draft: 接入 Harbor benchflow/skillsbench 作为 agent benchmark 范例

建议标题

feat(agent): integrate Harbor SkillsBench as the benchmark integration example

背景

agent 模块主链已经设计完成，后续需要一个“其他同学可以照着接”的 Harbor dataset 范例。

截至 2026-04-02，我建议优先选择 Harbor registry 上的 benchflow/skillsbench：

• Harbor 当前页面展示 87 个任务
• 任务名称覆盖代码调试、文档处理、数据比对、仓库分析等真实工作流
• 能比较自然地映射到 agent 模块的 installed_client + agent_runtime + agent_eval_kits 主链

注意：SkillsBench 官方站点文案仍写 84 个任务，因此本 issue 应以 Harbor registry 当前内容为准，不要求任务数和论文/官网完全一致。

为什么选 SkillsBench

从 Harbor registry 可见的任务名来看，这个数据集具备比较强的“典型性”：

• react-performance-debugging
• gh-repo-analytics
• pptx-reference-formatting
• pdf-excel-diff

从 SkillsBench 官方文档来看，它还包含一批需要外部 API 或较重资源的任务，例如：

• gh-repo-analytics
• scheduling-email-assistant
• speaker-diarization-subtitles
• trend-anomaly-causal-inference
• video-tutorial-indexer

这意味着它能作为一个很好的接入样例，帮助我们把下面这些问题一次性走通：

• Harbor dataset 的 sample 标准化
• 多类型任务的 instruction / cwd / env 抽取
• secret / heavy task 的排除策略
• agent artifact 和 verifier contract 的统一输出

目标

把 benchflow/skillsbench 接到 GAGE 的 agent runtime 主链中，形成一份可运行、可测、可扩展的 benchmark 接入范例。

范围

本 issue 包含

• 新增 skillsbench 对应的 benchmark kit
• 新增最小 smoke dataset / smoke config
• 跑通 installed_client 路径
• 完成 verifier 接线
• 增加最小单测和一条 smoke 回归
• 产出一份面向后续接入者的 sample / config 约定

本 issue 不包含

• 一次性跑完整个 SkillsBench 全量任务
• 处理所有需要第三方 API key 的任务
• 为所有 multimodal / heavy task 一次性补完基础设施

建议分阶段实施

Phase 1: 可稳定回归的 smoke 子集

先挑选一组“不依赖 secret、构建负担适中、能覆盖多种任务类型”的子集，跑通主链。

建议显式排除官方文档里已知的高风险任务：

• gh-repo-analytics，需要 GH_AUTH_TOKEN
• mhc-layer-impl，需要 Modal token
• pedestrian-traffic-counting，需要模型 API key
• pg-essay-to-audiobook，需要 OPENAI_API_KEY 和 ELEVENLABS_API_KEY
• scheduling-email-assistant，需要额外 token 且有挂载约束
• speaker-diarization-subtitles，Docker build 容易 OOM
• trend-anomaly-causal-inference，需要 ANTHROPIC 和 OPENAI
• video-filler-word-remover，需要 OPENAI_API_KEY
• video-tutorial-indexer，需要 OPENAI_API_KEY

Phase 2: 扩大覆盖面

在 Phase 1 稳定后，再评估：

• 是否纳入外部 API 任务
• 是否增加多模态任务
• 是否需要专门的 remote environment / artifact collector

建议实现落点

代码

• src/gage_eval/agent_eval_kits/skillsbench/
• src/gage_eval/role/adapters/dut_agent.py
• 如需 native verifier，再评估是否新增 src/gage_eval/agent_runtime/verifier/skillsbench.py

配置

• config/custom/skillsbench/smoke_installed_client_skillsbench.yaml
• config/custom/skillsbench/smoke_skillsbench.jsonl

测试

• tests/unit/agent_eval_kits/test_skillsbench_kit.py
• 如需 verifier 单测，再加 tests/unit/agent_runtime/test_skillsbench_verifier.py

设计要求

sample contract

至少要明确：

• instruction 从哪里取
• cwd / workspace_root 从哪里取
• env / metadata 怎么透传
• 哪些 task 需要额外 runtime surface

runtime contract

必须明确：

• agent_runtimes[].benchmark_kit_id = "skillsbench"
• 使用哪种 environment kind
• 初始 smoke 是否只要求 terminal + fs

verifier contract

必须明确：

• SkillsBench 的成功/失败结果如何被 GAGE 统一成 eval_result
• agent 产物如何映射到 verifier 输入
• 是否先复用 judge_adapter，还是直接实现 dataset 专属 verifier

验收标准

• smoke config 可解析、可启动
• 至少 1 组 SkillsBench smoke task 在本地稳定跑通
• 运行后能稳定产出 stdout.log、trajectory.json 和标准化 eval_result
• 有最小单测覆盖 prepare_inputs / finalize_result / verifier input
• 文档说明清楚哪些任务被 Phase 1 排除以及原因

开放问题

1. SkillsBench 在 Harbor registry 和官方站点的任务数不一致，最终以哪个为准
2. verifier 是优先对接 Harbor 原生 oracle，还是先做 GAGE 内部统一包装
3. Phase 1 是否只做无密钥子集，还是允许通过环境变量注入少量 secret

参考链接

• Harbor registry dataset: https://registry.harborframework.com/datasets/benchflow/skillsbench
• SkillsBench getting started: https://www.skillsbench.ai/docs/getting-started
• SkillsBench paper: https://www.skillsbench.ai/skillsbench.pdf

[Shuo-O]

补一版更具体的 implementation template，基于当前已经验证过的 agent/runtime 主链来做 SkillsBench onboarding，而不是从零重写一套 Harbor runtime。

当前可直接复用的主链

截至 2026-04-02，GAGE 已经有这些 benchmark 证据：

• terminal_bench: sandbox 和 remotesandbox(attached) 都已完成 10/10
• swebench: sandbox 已完成 10/10，remotesandbox(attached) 本轮为 9/10
• appworld: sandbox 和 remotesandbox(managed) 都已完成 10 样本实跑
• tau2: benchmark kit 已接通，但本轮被上游 quota 阻塞

因此这类 Harbor dataset 的重点应是：

• 复用现有 installed_client + agent_runtime + agent_eval_kits 主链
• 只新增 dataset-specific 的 sample contract、resource contract、verifier bridge 和 smoke 配置
• 不新增一套 Harbor 控制面

最值得借的现有实现

1. terminal_bench

适合借：

• 最小 smoke dataset 组织方式
• terminal + fs 的基线 surface
• native verifier 的最小 contract

参考位置：

• src/gage_eval/agent_eval_kits/terminal_bench/
• src/gage_eval/agent_runtime/verifier/terminal_bench.py

2. swebench

适合借：

• workspace / repo / patch 类任务的 sample 组织方式
• judge_adapter 路径下的 verifier bridge
• benchmark logic 下沉到 kit，而不是写进 scheduler

参考位置：

• src/gage_eval/agent_eval_kits/swebench/
• src/gage_eval/role/judge/swebench_docker.py

3. appworld

适合借：

• richer surfaces 的资源声明方式
• remote / managed sandbox 接线方式
• richer metadata 和端点透传方式

参考位置：

• src/gage_eval/agent_eval_kits/appworld/
• src/gage_eval/role/judge/appworld_evaluate.py

4. tau2

适合借：

• 非纯 patch 任务的数据单位拆分方式
• benchmark metadata 和 session resources 联合推导 contract 的方式

参考位置：

• src/gage_eval/agent_eval_kits/tau2/
• src/gage_eval/role/judge/tau2_eval.py

建议的落地形状

代码

• src/gage_eval/agent_eval_kits/skillsbench/
• src/gage_eval/role/adapters/dut_agent.py
• 如需 native verifier，再评估是否新增 src/gage_eval/agent_runtime/verifier/skillsbench.py

建议最小文件集：

• __init__.py
• kit.py
• sub_workflow.py
• units.py
• resources.py
• judge_bridge.py

配置

• config/custom/skillsbench/smoke_installed_client_skillsbench.yaml
• config/custom/skillsbench/smoke_skillsbench.jsonl

测试

• tests/unit/agent_eval_kits/test_skillsbench_kit.py
• 如需 native verifier，再加 tests/unit/agent_runtime/test_skillsbench_verifier.py
• 建议再补 1 条 integration smoke

contract 建议

sample contract

不要把 Harbor 原始字段直接泄漏到 scheduler。建议先在 units.py 做最小标准化：

• instruction
• workspace_root / cwd
• env
• metadata.expected_artifacts
• metadata.required_surfaces

然后由 sub_workflow.py 再组装成 scheduler 真正消费的输入。

runtime contract

Phase 1 的默认选择建议是：

• scheduler: installed_client
• environment: docker
• required surfaces: 先收敛为 terminal + fs
• extra env: 只允许显式白名单注入

如果某些 SkillsBench task 已经天然依赖 API / browser / remote service，就不要放进第一阶段 smoke。

verifier contract

建议顺序：

1. 先优先复用 judge_adapter
2. 只有当 SkillsBench 官方 oracle 足够稳定且 deterministic 时，再考虑 dataset 专属 native verifier

理由是第一份 onboarding issue 的目标是示范“怎么接”，不是一次性把 verifier 体系做复杂。

建议验收矩阵

L1: 必做

• smoke config 可解析
• 至少 1 组无密钥 SkillsBench smoke task 在 sandbox(docker) 稳定跑通
• 有最小单测覆盖 prepare_inputs、finalize_result、verifier input
• 产物符合 canonical sample root 约定

L2: 推荐

• sandbox(docker) 扩到 3 到 5 个异构任务
• 增加 1 条 integration smoke
• 文档补齐“排除任务清单 + 排除原因”

L3: 选做

• remotesandbox(attached) smoke
• richer surfaces，例如 api / env / mcp
• 对接 dataset 官方 oracle

Phase 1 建议排除项

第一阶段建议显式排除已知 secret / heavy task，例如：

• gh-repo-analytics
• mhc-layer-impl
• pedestrian-traffic-counting
• pg-essay-to-audiobook
• scheduling-email-assistant
• speaker-diarization-subtitles
• trend-anomaly-causal-inference
• video-filler-word-remover
• video-tutorial-indexer

期望产物结构

新的 SkillsBench smoke run 至少要稳定产出：

• summary.json
• events.jsonl
• samples.jsonl
• samples/<task_id>/<sample_id>/sample.json
• samples/<task_id>/<sample_id>/runtime_metadata.json
• samples/<task_id>/<sample_id>/agent/stdout.log
• samples/<task_id>/<sample_id>/agent/trajectory.json
• samples/<task_id>/<sample_id>/verifier/result.json

这样后续横向对比 benchmark 才不会再次因为 artifact path 不统一而返工。

如果需要，我可以下一步继续把这条 issue 再压成一版 checklist-style 子任务拆分。

[Shuo-O]

Follow-up to the integration example comment: the SkillsBench benchmark has now been integrated in the codebase and validated with representative runs.

Implemented on branch user/shuo/agent:

• commit: 5db83a29 (feat(agent-eval): integrate skillsbench benchmark)
• pushed to: origin/user/shuo/agent

What is now in repo:

• skillsbench_harbor dataset loader with auto-download support
• agent_eval_kits/skillsbench kit + judge bridge + sub-workflow
• SkillsBench docker verifier integration
• SkillsBench summary generator
• smoke/full installed-client configs
• oracle validation script
• transient Docker image build retry for flaky network/build failures
• Codex host-auth mount support for dockerized installed-client runs

Validation completed:

• regression tests: 32 passed
• config checker: SkillsBench smoke/full configs both passed
• ruff: passed
• registry manifest validation: passed

Representative oracle validation:

• dialogue-parser: pass
• civ6-adjacency-optimizer: pass
• find-topk-similiar-chemicals: fail, but root cause is task/runtime external SSL EOF in the official-solution path, not a GAGE verifier contract failure
• fix-druid-loophole-cve: verified that the new docker build retry path was triggered on transient build failure; the long-running build was then stopped because validation scope was reduced from full-suite to representative-only

Representative online installed-client validation:

• dialogue-parser completed end-to-end through installed_client -> docker sandbox -> workspace capture -> verifier -> summary
• the run itself succeeded structurally, but the benchmark result was tests_failed with score 0.833 because the agent output still contained one logic mistake (End treated as a regular reachable node)
• this means the integration path is working; the remaining failure is task-solving quality, not framework breakage

I also prepared a local package that contains the representative run artifacts and local reports for offline sharing, but that package is local-only and not attached to GitHub.