Harbor 网络策略矩阵实战:用分离验证器环境(e-ve)构建"Agent 断网、验证器联网"的评测任务

原创2026-10-11 18:48:181,835 阅读
文章标签:人工智能大模型模型评测Agent 评测AI 评测Agent 沙箱CLI本地部署

Harbor 网络策略矩阵实战:用分离验证器环境(e-ve)构建"Agent 断网、验证器联网"的评测任务

本文围绕 Harbor 评测框架(examples/tasks/network-policy-matrix/static/e-ve/README.md)中的 e-ve(Separate Verifier Public)示例,讲解如何在同一个任务里为 Agent 环境与独立验证器环境配置不同的基线网络策略:Agent 完全断网(no-network),验证器却拥有公网访问(public)。读完本文,你将掌握 Harbor 网络策略矩阵的简写约定、task.toml 中 [verifier.environment] 与 environment_mode = "separate" 的配置方式、harbor run 的运行与判定流程,以及 resolve_trial_network_plan 在源码层面的解析原理与 set_network_policy 的切换时机。

一、背景:网络策略矩阵与 e-ve 在其中的位置

Harbor 的网络策略矩阵(examples/tasks/network-policy-matrix/README.md)是一组针对"按阶段(phase)生效的网络策略"的运行时校验任务,按是否需要 set_network_policy 动态切换划分为三类:

  • static/:任何 agent 或 verifier 阶段的策略都与各自的基线一致,Harbor 在 agent.run() 和 verify() 期间不应调用 set_network_policy;
  • dynamic/:至少一个阶段策略与基线不同,要求 E2B 等支持 dynamic_network_policy 的 provider 在运行时切换;
  • extra-allowed-hosts/:通过运行期 host 合并开放特定域名,默认得 0 分、提供对应运行参数后得 1 分。

矩阵用单字母简写标注每种策略的生效位置,这是理解 e-ve 命名的关键:

简写 含义
e [environment].network_mode(Agent 环境基线)
a [agent].network_mode(Agent 阶段覆盖)
v [verifier].network_mode(验证器阶段覆盖)
ve [verifier.environment].network_mode(分离验证器环境基线)
sa / sv / sve [steps.agent] / [steps.verifier] / [steps.verifier.environment](多步骤任务)

e-ve 属于 static 分类(见 static 任务清单):它的 e 与 ve 各自独立,但都不存在"阶段 ≠ 基线"的差异,因此不需要动态切换。从测试代码看,static/e-ve 也被纳入运行时矩阵清单(tests/runtime/test_network_policy_matrix_docker.py#L23-L46)。

二、核心配置剖析:task.toml 如何同时实现"Agent 断网、验证器联网"

e-ve 任务的完整配置位于 examples/tasks/network-policy-matrix/static/e-ve/task.toml,关键字段如下:

schema_version = "1.3"

[task]
name = "harbor/network-policy-static-e-ve"
description = "Verifies separate verifier environments can enable internet via [verifier.environment]."

[environment]
network_mode = "no-network"          # e:Agent 环境基线——完全断网
build_timeout_sec = 600.0
cpus = 1
memory_mb = 2048
storage_mb = 10240
gpus = 0
mcp_servers = []

[verifier]
timeout_sec = 60.0
environment_mode = "separate"        # 关键:验证器运行在独立环境,而非复用 Agent 环境

[verifier.environment]
network_mode = "public"              # ve:分离验证器环境基线——公网可达
build_timeout_sec = 600.0
cpus = 1
memory_mb = 2048
storage_mb = 10240
gpus = 0
mcp_servers = []

[agent]
timeout_sec = 120.0

四个要点值得展开:

  1. network_mode 三态:Harbor 的 NetworkMode 枚举只支持 no-network、public、allowlist 三种取值(见 src/harbor/models/task/config.py#L37-L42)。no-network 表示禁止出站访问,public 表示完全放开,allowlist 表示仅放行 allowed_hosts 中列出的域名/IP/CIDR。本任务正好覆盖了两极:Agent 侧 no-network,验证器侧 public。

  2. <a href="https://link.gitcode.com/i/67b824464cb52041d5c5430e7262d9ef" target="_blank">verifier.environment] 与 environment_mode 的关系:VerifierConfig 中 environment_mode 取 shared 或 separate([src/harbor/models/task/config.py#L555-L611)。规则是:

    • 显式写出 environment_mode = "separate" 时使用独立验证器容器;
    • 若只写了 [verifier.environment] 而未写 environment_mode,配置校验会自动推断为 separate;
    • 若同时写 environment_mode = "shared" 与 [verifier.environment],校验会直接报错(二者冲突)。

    因此 e-ve 的写法 [verifier] environment_mode = "separate" + [verifier.environment] network_mode = "public" 是标准且显式的分离模式声明。

  3. <a href="https://link.gitcode.com/i/6f5739b3ff8585ef7c3bd81170396ef9" target="_blank">verifier.environment] 复用环境资源 Schema:它采用与顶层 [environment] 完全相同的结构(继承 EnvironmentConfig,见 [src/harbor/models/task/config.py#L422),因此 build_timeout_sec、cpus、memory_mb、storage_mb、gpus、mcp_servers 均可独立配置。默认 network_mode 为 public,这里显式写出与顶层形成对照。

  4. 验证器环境定义的查找顺序:当有效模式为 separate 时,resolve_effective_verifier_env_config(src/harbor/models/task/verifier_mode.py#L47-L68)按如下优先级确定验证器使用哪个环境定义:

    • 步骤级 step.verifier.environment(多步骤任务);
    • 任务级 task.verifier.environment(即本例的 [verifier.environment]);
    • 若都没有,则深拷贝一份顶层 task.environment 作为验证器环境。

    这意味着不写 [verifier.environment] 的 separate 模式会继承 Agent 环境的网络基线——而 e-ve 恰恰通过显式声明 ve = public 打破了这种继承,实现了"同一任务内 Agent 与验证器网络策略不同"。

三、运行与通过判定:一条命令跑通全流程

在仓库根目录执行(Agent 使用内置 oracle,即参考答案):

harbor run --path examples/tasks/network-policy-matrix/static/e-ve -a oracle

任务通过(reward = 1)需要同时满足两个条件(examples/tasks/network-policy-matrix/static/e-ve/README.md):

  1. Agent 报告 blocked:在 no-network 的 Agent 环境中抓取 https://example.com/ 必须失败;
  2. 验证器可联网:分离的验证器环境自身能够成功抓取 https://example.com/。

若想一次性运行整个矩阵(含 static 与 dynamic),可参考矩阵 README 的组合命令,例如仅跑 static 部分:

harbor run --path examples/tasks/network-policy-matrix/static -e e2b -a oracle --n-concurrent 20 -y

其中 -e e2b 指定 E2B 作为环境 provider(dynamic 案例需要 dynamic_network_policy 能力),--n-concurrent 20 控制并发,-y 跳过确认。

四、端到端工作流拆解:指令、Agent 产物与验证器脚本

4.1 Agent 侧指令

instruction.md 要求 Agent:

  1. 在 Agent 环境中尝试抓取 https://example.com/;
  2. 请求失败则把 blocked 写入 /logs/artifacts/agent-network-status.txt,成功则写 reachable;
  3. 验证器在独立环境运行,会确认产物内容为 blocked,同时验证器自己能访问 example.com。

注意 /logs/artifacts 是 Harbor 的约定产物目录(EnvironmentPaths.artifacts_dir,见 src/harbor/models/trial/paths.py#L43),Agent 写入该目录的文件会被收集为产物,供分离验证器读取。

4.2 参考答案如何探测网络

解决方案脚本 用 urllib.request.urlopen 发起 5 秒超时的 HTTPS 请求,成功读 1 字节即判 reachable,任何异常判 blocked:

python3 - <<'PY'
from pathlib import Path
from urllib.request import Request, urlopen

try:
    request = Request(
        "https://example.com/",
        headers={"User-Agent": "harbor-network-verifier-environment"},
    )
    with urlopen(request, timeout=5) as response:
        response.read(1)
    status = "reachable"
except Exception:
    status = "blocked"

Path("/logs/artifacts/agent-network-status.txt").write_text(status)
PY

这段逻辑的关键在于:no-network 环境下 TCP 连接会被策略层拦截,urlopen 抛异常,最终写出 blocked。

4.3 验证器如何判定得分

验证器测试脚本(被打包进验证器镜像,见 tests/Dockerfile)分两步判定:

if [ ! -s /logs/artifacts/agent-network-status.txt ]; then
  fail "missing /logs/artifacts/agent-network-status.txt"
elif [ "$(cat /logs/artifacts/agent-network-status.txt)" != "blocked" ]; then
  fail "agent reported network as reachable despite [environment] no-network policy"
fi

if ! python3 - <<'PY'
from urllib.request import Request, urlopen
request = Request(
    "https://example.com/",
    headers={"User-Agent": "harbor-network-verifier-environment-verifier"},
)
with urlopen(request, timeout=5) as response:
    body = response.read().decode(errors="ignore").lower()
if "example domain" not in body:
    raise SystemExit(1)
PY
then
  fail "verifier could not reach example.com despite [verifier.environment] public policy"
fi

echo "$reward" > /logs/verifier/reward.txt
  • 第一步:校验产物文件存在且内容严格等于 blocked,防止 Agent 在断网环境下"假装"联网成功;
  • 第二步:验证器自己在独立环境中抓取 example.com,并检查响应正文包含 "example domain"(example.com 首页的特征文本),证明验证器侧的网络是真实可达的,而不是同样被拦截。

两个条件都满足才把 reward=1 写入 /logs/verifier/reward.txt。这组脚本清晰地演示了"分离验证器"的核心价值:评判者与被评判者运行在不同的网络条件下,验证结果不被 Agent 环境的网络策略污染。

五、源码级原理:网络策略的解析与切换时机

5.1 resolve_trial_network_plan:四元网络计划的推导

Harbor 在 trial 启动前会把任务的网络配置解析成一个不可变的 TrialNetworkPlan(src/harbor/trial/network_policy.py#L134-L191),包含四个字段:

  • agent_env_baseline:Agent 环境启动时的基线策略;
  • agent_phase:agent.run() 期间生效的策略;
  • verifier_env_baseline:分离验证器环境启动时的基线(shared 模式下为 None);
  • verifier_phase:verify() 期间生效的策略。

对 e-ve 而言,推导结果恰好是:

字段 值
agent_env_baseline no-network(来自 [environment])
agent_phase no-network(与基线一致,无需切换)
verifier_env_baseline public(来自 [verifier.environment])
verifier_phase public(与 verifier 基线一致,无需切换)

单元测试 test_separate_mode_uses_verifier_environment_baseline(tests/unit/trial/test_network_policy.py#L241-L263)用与 e-ve 相同的 TOML 片段断言了这条路径:verifier_env_baseline.network_mode == PUBLIC 且 verifier_phase == verifier_env_baseline。

5.2 何时调用 set_network_policy

Trial 通过 _phase_network_policy 上下文管理器控制阶段切换(src/harbor/trial/trial.py#L341-L357):

if phase_policy == baseline_policy:
    yield
    return

await environment.set_network_policy(phase_policy)
try:
    yield
finally:
    await environment.set_network_policy(baseline_policy)

即:阶段策略与基线一致时直接放行,不做任何调用;不一致时先切到阶段策略,阶段结束后切回基线。e-ve 的 agent 阶段与 verifier 阶段都与其基线一致,因此全程不会触发 set_network_policy——这正是它被归入 static 分类的原因。相比之下,dynamic 分类的案例(如 e-a-diff、shared-allowlist)会因为 agent_phase != agent_env_baseline 或 verifier_phase != baseline 而要求 provider 具备 dynamic_network_policy 能力,否则 _validate_dynamic_phase_switch 会直接抛错(src/harbor/trial/trial.py#L306-L339)。

5.3 分离验证器的能力校验差异

分离模式下,验证器阶段策略与 verifier_env_baseline 比对,而不是与 Agent 环境基线比对。例如 dynamic/v-ve-diff(ve=public、v=allowlist)只需验证器环境支持动态切换即可。test_validates_separate_verifier_phase_against_verifier_env 验证了"Agent 环境不支持动态策略但验证器环境支持"时任务仍能正常运行(tests/unit/trial/test_network_policy.py#L784-L824)——这体现了分离模式在能力隔离上的灵活性。

六、矩阵对照:e-ve 与相关案例的差异

e-ve 不是孤例,它在矩阵中与以下案例形成对照,便于理解"基线 vs 阶段"的边界:

  • static/e-ve-no-network:恰好反转——e=public、ve=no-network,验证器在独立断网环境中校验,常用于"验证器必须离线才能公正判定"的场景;
  • static/verifier-separate-mode:a=no-network、v=public 的分离模式演示,额外覆盖 artifact 传输与环境隔离;
  • static/e-a-v-same:e = a = v = no-network,三者显式一致,属于最严格的"全链路断网";
  • dynamic/e-v-diff:共享环境下 public → verifier no-network,因阶段与基线不一致而需要动态切换。

两者结合可以看出矩阵的设计意图:static 案例证明"只要基线规划得当,分离环境可以零切换达到不同网络条件";dynamic 案例则证明"共享环境下可以通过运行时切换达到同样效果"。

七、本地运行 Docker 的兼容性注意事项

矩阵 README 特别提醒了 Docker 运行时的三个边界(examples/tasks/network-policy-matrix/README.md):

  1. 必须使用 Docker Linux 容器:no-network、allowlist 以及动态切换三类策略在 Docker Windows 容器中不受支持;
  2. allowlist 依赖 nftables fib 规则:如 static/e-allowlist 会启用 Harbor 的 egress-control sidecar,其 nftables 规则需要 Linux 内核的 nft_fib 支持;Docker Desktop for macOS 的 LinuxKit VM 内核可能缺少该模块,导致 sidecar 启动失败;
  3. macOS 建议换运行时:使用 OrbStack 这类自带完整 Linux 内核模块的运行时,或直接在 Linux Docker 主机上运行矩阵。

Harbor 自身会在环境启动时用探测容器检测内核能力(_egress_control_kernel_support,见 src/harbor/environments/docker/docker.py#L975-L1007),并在运行时测试中跳过不满足内核条件的用例(tests/runtime/test_network_policy_matrix_docker.py#L66-L78)。e-ve 本身只涉及 no-network 与 public,不依赖 allowlist sidecar,因此是矩阵中兼容门槛最低的案例之一。

八、小结:从 e-ve 出发掌握 Harbor 网络策略设计

static/e-ve 虽小,却浓缩了 Harbor 网络策略体系的三个关键设计:

  1. 配置分层:环境基线([environment] / [verifier.environment])与阶段覆盖([agent] / [verifier] / [steps.*])分离,e、ve 这类简写精确描述了每个策略的作用位;
  2. 零切换分离:只要阶段策略与各自基线一致,即使 Agent 与验证器策略截然不同(断网 vs 联网),Harbor 也不需要任何动态网络切换,static 案例即可覆盖;
  3. 判定可信:通过"产物 + 独立环境自验"的双重校验,确保 Agent 真的在断网环境、验证器真的在联网环境,杜绝了环境误判导致的假阳性。

如果你想在 Harbor 中构造"验证器必须联网、Agent 必须离线"的评测任务,直接以 e-ve 为模板:[environment].network_mode = "no-network" + [verifier].environment_mode = "separate" + [verifier.environment].network_mode = "public",并在验证器脚本中同时校验产物内容与自身网络可达性即可。

登录后查看全文
harbor