deepagents context-retrieval-evals 数据集解析：以 cb-cloud-49 多实体比较任务为例-平芜编程栈

deepagents context-retrieval-evals 数据集解析：以 cb-cloud-49 多实体比较任务为例

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents

本篇指南以 context-retrieval-evals 数据集中的cb-cloud-49任务为完整样本，拆解 Deep Agents 上下文检索评测任务的数据结构、单源生成机制、沙箱环境与 LLM 评分逻辑。读完本文，你将掌握 30 个 Harbor 任务目录的每个文件含义、如何在本仓库中定位语料与验证器源码，并能独立复现该任务的"5 文件交叉检索 + 多实体比较"推理路径。

数据集概览：30 个上下文检索任务的来源与难度分层

cb-cloud-49隶属于 libs/evals/datasets/context-retrieval-evals 目录，该目录包含 30 个cb-cloud-任务（cb-cloud-1至cb-cloud-88的非连续采样）。数据集定位见 README：

评测内容：Agent 必须在 10 个文件的完整语料中检索、关联（join）并聚合信息才能作答，任务不告知哪些文件相关；
来源：任务派生自 Context-Bench 的cloud套件（合成的人/车辆/宠物/账户记录），由 harbor_adapters/contextbench 依据厂商数据filesystem_cloud.jsonl（100 条记录）生成，cb-cloud-对应第条记录（0 起始）；
评分：与上游 Letta letta-evals 一致，使用 LLMmodel_judge对照rubric.txt评分（对措辞/姓名/数字容错），而非字符串相等。

难度分层方面，difficulty与source_difficulty是 Context-Bench 原始分层标签（非事后按模型表现标注）：30 个任务为2 easy · 10 medium · 18 hard。cb-cloud-49在 README 任务表中标注为hard / multi_entity_comparison，且是入选样本中少数 Terra 未全过（5/6）的任务之一。

任务目录结构：一个自包含 Harbor 评测任务的四个组成部分

cb-cloud-49任务目录的自包含结构如下：

libs/evals/datasets/context-retrieval-evals/cb-cloud-49/ ├── instruction.md # 问题文本 + 作答约束 ├── task.toml # 任务元数据 + 网络环境配置 ├── environment/ │ └── Dockerfile # 沙箱镜像定义（构建期装 curl/ca-certificates） ├── solution/ │ └── solve.sh # 参考答案写入脚本 └── tests/ └── case.json # 问题 + 标准答案（唯一提交到仓库的按任务文件）

按 contextbench/adapter.py 的_write_task_files逻辑，任务目录由generate_task统一生成：每个任务拥有独立environment/files/（语料副本）、instruction.md、solution/solve.sh、task.toml与tests/。

instruction.md：问题陈述与作答约束

instruction.md 全文如下：

Who has more credit cards: the person with the most vehicles among residents of the same state as the owner of the pet named 'Austin' (using total bank balance as a tiebreaker), or the person with the most vehicles among residents of the same state as the owner of the pet named 'Caleb' (using the same tiebreaker)?
Use only the files under/app/files. Write your final answer (and nothing else) to/app/answer.txt.

后两行约束由 adapter.py 统一拼写：Agent 只能使用/app/files下的文件，最终答案（且只能写答案本身）写入/app/answer.txt。

case.json：问题与标准答案

tests/case.json 是每个任务唯一提交的按任务验证输入：

{"input": "Who has more credit cards: the person with the most vehicles among residents of the same state as the owner of the pet named 'Austin' (using total bank balance as a tiebreaker), or the person with the most vehicles among residents of the same state as the owner of the pet named 'Caleb' (using the same tiebreaker)?", "ground_truth": "Gregory Luna"}

ground_truth的标准答案为Gregory Luna。

task.toml：元数据与网络白名单

task.toml 声明：

version = "1.3" [metadata] source = "contextbench" suite = "cloud" difficulty = "hard" source_difficulty = "hard" question_type = "multi_entity_comparison" [environment] network_mode = "allowlist" allowed_hosts = ["astral.sh", "*.astral.sh", "github.com", "*.githubusercontent.com", "pypi.org", "*.pythonhosted.org", "api.smith.langchain.com", "api.anthropic.com", "api.openai.com", "generativelanguage.googleapis.com", "openrouter.ai", "*.baseten.co", "api.fireworks.ai", "ollama.com", "api.groq.com", "integrate.api.nvidia.com", "api.x.ai"]

关键字段含义（结合 adapter.py 的生成注释）：

difficulty是权威难度桶，生成时等于源标签，校准后由stamp_calibrated_tiers覆写；source_difficulty保留原始标签用于溯源；
network_mode = "allowlist"是白名单而非断网：沙箱内的 langgraph/dcode Agent 必须访问自己的基础设施（包镜像 + 所选模型的 API）才能引导启动并作答；任意网页访问仍被阻止，防止答案查找（LangSmith 通过 egress 代理强制执行）；
allowed_hosts覆盖评分卡工作流可选的每个模型提供商 API 端点（仅 API 端点，绝不包含答案来源）。

Dockerfile：构建期预装 curl 以保持运行时纯 HTTPS

environment/Dockerfile：

FROM python:3.12-slim # Pre-install curl at build time (the build phase has network) so the # in-sandbox agent's runtime bootstrap skips apt; runtime egress is then # all-HTTPS via the task's network allowlist. RUN apt-get update \ && apt-get install -y --no-install-recommends curl ca-certificates \ && rm -rf /var/lib/apt/lists/* COPY files/ /app/files/

构建期（有网络）安装 curl 与 CA 证书，使运行期 Agent 引导流程跳过 apt，运行期出口流量全部经任务网络白名单走 HTTPS；COPY files/ /app/files/将语料注入沙箱。

solve.sh：参考答案回写

solution/solve.sh：

#!/bin/sh set -eu printf '%s\n' 'Gregory Luna' > /app/answer.txt

它演示了标准答案通道：最终答案仅写入/app/answer.txt，与 instruction.md 的作答约束一致。

单源生成机制：语料与验证器不重复提交

README 明确"Corpus and verifier are single-sourced"：两类按任务文件在 30 个任务中逐字节相同，因此被 git-ignore，由生成器恢复，而非逐个提交：

64.7K 行语料：唯一副本在 harbor_adapters/contextbench/vendor/files/，恢复进每个任务的environment/files/；
不变量验证器：tests/{test.sh,judge.py,rubric.txt}唯一副本在 templates/ 与vendor/rubric.txt；
每个任务只提交tests/case.json（问题 + 标准答案）。

本地运行前需执行恢复：

uv run python -m harbor_adapters.contextbench.main --populate datasets/context-retrieval-evals uv run harbor run --path datasets/context-retrieval-evals ...

CI（harbor.yml）在构建任务镜像前自动执行--populate。对应实现为 adapter.py 的populate_corpus，只处理直接子目录中source = "contextbench"的任务，并从单源副本复制语料与验证器不变量。

生成与校准 CLI：从 JSONL 记录到可运行任务

main.py 提供 CLI 驱动，三个互斥模式：

参数	作用
`--task-ids cb-cloud-49 ...`	按 id 生成指定任务（配合`--output-dir`）
`--limit N`	无`--task-ids`时生成`cb-cloud-0..N-1`前 N 个任务
`--populate DATASET_DIR`	恢复各任务的`environment/files/`与验证器不变量
`--stamp-tiers DATASET_DIR --calibration CAL.json`	用校准 JSON 覆写各任务`difficulty`

生成路径：record_for_task_id校验 id →parse_task_id解析cb-<suite>-→generate_task从filesystem_cloud.jsonl第行读取记录并组装任务目录（adapter.py）。

cb-cloud-49 对应的源记录

cb-cloud-49对应filesystem_cloud.jsonl的第 49 行（0 起始），其agent_args.extra声明了推理所需的最小文件集：

{ "required_files": ["pets.txt", "addresses.txt", "vehicles.txt", "bank_accounts.txt", "credit_cards.txt", "people.txt"], "question_type": "multi_entity_comparison", "difficulty": "hard" }

校准覆写 difficulty

生成时difficulty = source_difficulty（源标签）；校准后 stamp_calibrated_tiers 从校准 JSON 读取权威tier覆写difficulty，source_difficulty保留溯源。calibration.json（仓库根libs/evals/datasets/context-retrieval-evals/calibration.json）是源运行的可机读记录，包含聚合总数与每个任务的 Terra/Luna 结果。

语料形态：10 个文件的合成数据仓库

语料由 vendor/files/ 下的 10 个纯文本文件构成，总行数 64,657：

文件	行数	主键/外键
people.txt	1,500	`pers-XXXX`
addresses.txt	8,136	`addr-XXXX`(owner: pers-XXXX)
vehicles.txt	6,748	`veh-XXXX`(owner: pers-XXXX)
bank_accounts.txt	14,096	`acct-XXXX`(owner: pers-XXXX, balance)
credit_cards.txt	8,869	`card-XXXX`(owner: pers-XXXX)
pets.txt	5,742	`pet-XXXX`(owner: pers-XXXX, name)
employments.txt	4,176	`job-XXXX`
insurance_policies.txt	6,825	`pol-XXXX`
internet_accounts.txt	7,035	`net-XXXX`
medical_records.txt	1,530	`med-XXXX`

记录格式为### 类型-编号 (owner: pers-XXXX)块 + 键值字段，例如：

### pet-0892 (owner: pers-0472) pet_id: pet-0892 name: Austin species: Rabbit

### card-0001 (owner: pers-0001) card_id: card-0001 provider: Discover

参考答案推理链复现：为什么答案是 Gregory Luna

结合语料可完整复现 cb-cloud-49 的推理链（问题为"多实体比较"：比较两条支线中"信用卡数量更多者"）。

支线 1：Austin 主人的州（Massachusetts）

pets.txt 中name: Austin→ 宠物pet-0892，主人pers-0472（Wesley Silva）；
addresses.txt 中addr-0961 (owner: pers-0472)的state: Massachusetts；
该州 21 名居民中，pers-0270（Gregory Luna）与pers-0282（Christopher Beck）车辆最多（各 4 辆）；
银行余额决胜：Gregory Luna $189,003.97 vs Christopher Beck $15,864.16；
支线 1 代表：Gregory Luna，信用卡数4。

支线 2：Caleb 主人的州（Vermont）

name: Caleb→ 宠物pet-0911，主人pers-0478（Kim Hampton）；
其州为 Vermont，该州 15 名居民中车辆最多者（各 4 辆）包括 Tiffany Johnson（$139,717.48）、Steven Cook（$115,794.76）、Kirk Moore（$51,335.32）、James Foster（$21,900.08）；
银行余额决胜后代表为Tiffany Johnson，信用卡数3。

结论

4 > 3，故拥有更多信用卡者为 Gregory Luna，与 case.json 的ground_truth一致。该任务被标注为 hard，因为正确作答至少需要 5 个文件交叉引用（pets → addresses → vehicles → bank_accounts → credit_cards → people）且存在多个并列候选，验证了 README 所述"Agent 无法推断哪些文件重要，必须检索、连接并聚合"。

评分机制：LLM Judge 而非字符串比较

测试由 templates/test.sh 调用 templates/judge.py，是 Letta letta-evalsRubricGrader（OpenAI provider）的沙箱内复刻：

判题提示：上游 rubric（vendor/rubric.txt）经string.Formatter().vformat代入{input}/{ground_truth}/{submission}，无系统提示、无包裹；
响应格式：Chat Completions +json_schema响应格式{score: float ∈ [0,1], rationale}；
温度规则：o1/o3/gpt-5 推理模型在 temperature 1.0 下调用（0.0 会 400），其余模型 0.0；
分数归一：score = clamp(float(score), 0.0, 1.0)，任何异常记 0.0（与上游一致）；
重试：至多 5 次，最终失败记 0.0。

两处与上游有意的差异，均由 deepagents 测试框架而非本文件决定：判题模型取自JUDGE_MODELS（如gpt-5.6-luna）而非上游的gpt-5-mini；提交物为/app/answer.txt（测试框架答案通道）而非 Agent 最后一条助手消息。

评分规则（rubric.txt）要点：

1.0 正确：最终答案与期望匹配。数字格式等价（"$145,315.33"="145315.33"）；数字文字等价（"2 dogs"="two dogs"）；姓名大小写不敏感；轻微措辞差异可接受；单位可隐含（问车辆时可写"4"="4 vehicles"）；若期望答案为姓名，响应中任意位置出现该姓名即视为正确；
0.5 仅拒绝：Agent 明确拒绝作答且未尝试；
0.0 错误：答案不同、声称找不到但答案存在、部分答案遗漏关键值、给出多个答案但未明确最终答案。

评分聚焦最终答案而非中间推理；过程有错但最终答案正确仍得 1.0；过程正确但最终答案错误得 0.0。

运行任务与查看结果

本地复现该任务的完整流程：

# 1. 恢复被 git-ignore 的语料与验证器（在 libs/evals 下执行） uv run python -m harbor_adapters.contextbench.main --populate datasets/context-retrieval-evals # 2. 运行 Harbor 评测（语法占位，参数按 Harbor CLI 实际提供） uv run harbor run --path libs/evals/datasets/context-retrieval-evals ...

运行后沙箱内 Agent 读取/app/files/（10 个语料文件）并写入/app/answer.txt；验证器将score写入/logs/verifier/reward.txt。注意语料为 64.7K 行、10 文件，Agent 无法预知哪些文件相关，这正是评测的核心挑战。