代码实现

实现 provider 配置、会话原语、生命周期、资源、网络强制执行和优先级。

通过共享 Environment 契约实现一个 provider，并把 provider 专属行为留在 Benchmark 和 Harness 之外。

​

1. 建立 provider 契约

以 provider 官方 SDK 和 API 文档为权威来源，记录：

• 身份验证、区域、项目、资源池、应用或组织范围。
• 镜像、快照、命名镜像、Dockerfile 或模板选择器及其互斥规则。
• 工作区和文件系统持久化行为。
• CPU、内存、磁盘、GPU、放置策略和配额字段。
• sandbox 启动、操作、空闲、最大值-生命周期和删除语义。
• 公共、受限和已加入允许列表网络能力。
• 命令、文件传输、端点、取消和错误行为。
• SDK 异步支持和线程安全保证。

provider 调用应对齐官方 API，不要发明 Benchmark 专属 Environment 字段。

​

2. 定义类型化 provider 配置

在 src/agentcompass/environments/ 下创建 provider。为每个公共字段定义 RuntimeEnvironmentConfig 子类，并实现注册到 ENVIRONMENTS 的 BaseEnvironment。

在结构中分离以下概念：

概念	示例
身份验证	API 密钥、令牌 ID/密钥、端点、组织
sandbox 来源	镜像、快照、命名镜像、模板
生命周期	启动超时、操作超时、空闲超时、最大值生命周期
资源	CPU、内存、磁盘、GPU、放置策略
工作区	默认值根目录、挂载、卷、持久化
provider 元数据	名称前缀、标签、标签、区域、资源池

provider 暴露的超时或资源语义存在实质差异时，不要使用一个通用字段。每个字段需要清晰单位、默认值、验证和互斥错误。凭证不得进入日志和已持久化计划。

​

3. 实现会话原语

provider 会话类实现 EnvironmentSession：

方法	必要行为
exec()	列表形式命令不经过命令解释器；显式字符串命令使用 shell=True；保留返回码、标准输出、标准错误和超时
upload() / download()	向活动 Environment 传入或取回一个文件
write_text() / read_text()	执行确定性 UTF-8 文本 I/O；缺失路径错误必须可操作
upload_dir() / download_dir()	传输目录树，不能静默改变请求根目录
endpoint()	provider 支持服务时返回外部可访问端点，否则返回 None
set_network_policy()	只有 provider 支持动态切换时才应用新的可强制策略

将 provider 专属响应标准化为 ExecResult。被执行命令返回非零状态时不要直接抛出；除非传输或 provider 执行自身失败，否则返回命令结果。保留超时与 provider 错误 的区别。

异步方法中使用异步 provider API。官方 SDK 只有阻塞调用时，应显式隔离，避免高任务并发数下阻塞事件循环。

​

4. 将打开与关闭实现为一个生命周期

BaseEnvironment.open() 根据 Recipe 调整后的 ExecutionPlan 创建一个任务 Environment；close() 释放它。Environment provider 不得加载 Benchmark 数据或改写 Benchmark 结果。

open() 期间：

1. 根据解析后计划构建并验证 provider 配置。
2. 解析互斥的镜像或 provider 原生选择器。
3. 应用资源、工作区、标签和准备网络策略。
4. 创建 sandbox，并且只等待到文档声明的启动超时。
5. provider 报告可用状态后构造会话。
6. 传播失败前清理已部分创建的资源。

close() 只停止或删除该会话拥有的准确资源。清理必须能处理部分启动，并对取消或重复错误处理足够幂等。不要通过宽泛名称或未经验证的全局搜索发现清理目标。

​

5. 声明并强制网络能力

根据 provider 真实强制执行能力设置 supported_network_modes、supported_allowlist_entry_types 和 supports_dynamic_network_policy。

模式	必要保证
public	provider 默认的出站访问权限
no-network	出站请求在传输层失败
allowlist	只有标准化后受支持的 host 或网络可访问

无法强制策略或允许列表条目类型时必须默认拒绝。不要声明只通过提示词、环境变量或尽力而为 agent 指令实现的模式。

动态 provider 必须支持准备阶段策略 → agent 运行阶段策略 → 准备 → 验证器策略的 runtime 顺序；全新验证器 Environment 必须以验证器策略启动。

保护并脱敏代理凭证、内部网关、策略令牌和生成的 URL。正常关闭或启动失败后，清理临时网络、代理容器和 provider 策略。

​

6. 保持用户优先 provider 优先级

Environment 代码使用最终计划；Recipe 负责 Benchmark 专属默认值。两层都必须保留：

explicit provider-native selector
  > explicit environment image
  > task metadata
  > recipe fallback

移除不兼容字段前先解析胜出项。资源逐字段应用，使用户显式值优先，未指定字段可以继承任务提示。保留显式工作区、命令、超时、凭证、网络策略、标签和标签。

新增 provider 通常需要为带有预构建任务镜像的 Benchmark 添加 Recipe。每个 Recipe 应只匹配一个 Benchmark/provider 组合，改写前复制计划，且不能调用 provider SDK。

​

7. 遵守 runtime 限制与可观测性

BaseEnvironment 应用进程全局的 provider 打开限制器。provider 代码还必须遵守 SDK 请求限制、任务并发数、账号配额和资源容量，不能增加无界内部并行扩展。

记录稳定 sandbox ID、生命周期阶段、耗时、所选非密钥镜像/快照和可操作 provider 错误。不要记录令牌、已签名 URL、内部代理凭证或可能包含密钥的完整环境字典。

​

8. 注册并检查组件

从 src/agentcompass/environments/__init__.py 导出 provider，再验证注册表发现机制和实时配置结构：

uv run agentcompass list env
uv run agentcompass config docs env <environment-id>