> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 代码实现

实现 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`  | 只有标准化后受支持的主机或网络可访问    |
| `denylist`   | 保持正常出站访问，但阻止标准化后的拒绝目标 |

无法强制策略、目标类型或端口限制时必须默认拒绝。如果用户有意接受不同的网络行为，应提示用户将对应生命周期策略显式覆盖为受支持的 mode。不要声明只通过提示词、环境变量或尽力而为 agent 指令实现的模式。

动态 provider 必须支持从基线策略切换到运行策略；评测复用 Environment 时，还要支持从运行策略直接切换到 evaluation 策略。Harness 关闭、artifact 收集和主 Environment 释放都在运行策略下执行；复用 Environment 在评测后恢复基线策略。全新 evaluation Environment 以基线策略启动，仅在 `benchmark.evaluate()` 期间应用 evaluation 策略覆盖，并在保留或释放前恢复基线策略。

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

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

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

```text theme={"system"}
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，再验证注册表发现机制和实时配置结构：

```bash theme={"system"}
uv run agentcompass list env
uv run agentcompass config docs env <environment-id>
```