Harbor 网络策略矩阵实战:用分离验证器环境(e-ve)构建"Agent 断网、验证器联网"的评测任务
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
四个要点值得展开:
-
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。 -
<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"是标准且显式的分离模式声明。 - 显式写出
-
<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,这里显式写出与顶层形成对照。 -
验证器环境定义的查找顺序:当有效模式为
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):
- Agent 报告
blocked:在no-network的 Agent 环境中抓取https://example.com/必须失败; - 验证器可联网:分离的验证器环境自身能够成功抓取
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:
- 在 Agent 环境中尝试抓取
https://example.com/; - 请求失败则把
blocked写入/logs/artifacts/agent-network-status.txt,成功则写reachable; - 验证器在独立环境运行,会确认产物内容为
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→ verifierno-network,因阶段与基线不一致而需要动态切换。
两者结合可以看出矩阵的设计意图:static 案例证明"只要基线规划得当,分离环境可以零切换达到不同网络条件";dynamic 案例则证明"共享环境下可以通过运行时切换达到同样效果"。
七、本地运行 Docker 的兼容性注意事项
矩阵 README 特别提醒了 Docker 运行时的三个边界(examples/tasks/network-policy-matrix/README.md):
- 必须使用 Docker Linux 容器:
no-network、allowlist以及动态切换三类策略在 Docker Windows 容器中不受支持; allowlist依赖 nftablesfib规则:如static/e-allowlist会启用 Harbor 的 egress-control sidecar,其 nftables 规则需要 Linux 内核的nft_fib支持;Docker Desktop for macOS 的 LinuxKit VM 内核可能缺少该模块,导致 sidecar 启动失败;- 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 网络策略体系的三个关键设计:
- 配置分层:环境基线(
[environment]/[verifier.environment])与阶段覆盖([agent]/[verifier]/[steps.*])分离,e、ve这类简写精确描述了每个策略的作用位; - 零切换分离:只要阶段策略与各自基线一致,即使 Agent 与验证器策略截然不同(断网 vs 联网),Harbor 也不需要任何动态网络切换,static 案例即可覆盖;
- 判定可信:通过"产物 + 独立环境自验"的双重校验,确保 Agent 真的在断网环境、验证器真的在联网环境,杜绝了环境误判导致的假阳性。
如果你想在 Harbor 中构造"验证器必须联网、Agent 必须离线"的评测任务,直接以 e-ve 为模板:[environment].network_mode = "no-network" + [verifier].environment_mode = "separate" + [verifier.environment].network_mode = "public",并在验证器脚本中同时校验产物内容与自身网络可达性即可。