> ## 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.

# 代码实现

实现 Harness 兼容性、生命周期、安装、限制、密钥和标准化结果。

实现拥有 agent 循环、且只通过公开 runtime 契约通信的最小适配器。

## 1. 建立上游执行契约

记录官方框架或 CLI 版本、支持的 model 协议、配置格式、提示词流程、工具与工作区行为、安装方法、超时、终止规则、轨迹格式和凭证处理。

版本会影响命令、提示词、输出解析或得分可复现性时必须固定上游版本。优先使用公开 SDK 或 CLI 契约，不要依赖私有内部函数。

## 2. 定义配置与计划类型

在 `src/agentcompass/harnesses/` 下创建 Harness。典型集成包含：

* 用户可见参数的 `RuntimeHarnessConfig` 子类。
* 保存解析后 runtime 状态的类型化 `HarnessPlan`。
* 注册到 `HARNESSES` 的 `BaseHarness` 子类。
* 必要时用于配置生成、启动和轨迹解析的专用适配器。

公共调节项应放在配置类中，使 CLI、Python SDK、配置文件和生成的组件文档解析出相同字段。密钥不得进入数据类表示形式和已持久化计划元数据。

计划用于版本、启动模式、安装策略、步骤限制、命令超时和成本行为等标准化 runtime 选择。不要修改 `RunRequest`，也不要检查私有 Benchmark 字段。

## 3. 提前验证兼容性

围绕能力而不是 Benchmark ID 实现 `supports(environment, model)`，并验证：

| 维度          | 需要回答的问题                                                          |
| ----------- | ---------------------------------------------------------------- |
| model 协议    | 支持 `openai-chat`、`openai-responses` 和 `anthropic-messages` 中的哪些？ |
| Environment | agent 是否需要终端、文件、端点转发、浏览器、GUI 或特权操作？                              |
| 工作区         | 能否在已准备工作区中工作，而不假设 Benchmark 专属路径？                                |
| 凭证          | model 或外部服务凭证是否位于正确执行位置？                                         |
| 安装          | 所选启动和安装策略能否在 Environment 中运行？                                    |

尽可能在 Environment 启动前拒绝不支持的组合。不要静默切换协议、provider、安装模式或 model。

## 4. 实现生命周期

runtime 按以下顺序调用 Harness：

```text theme={"system"}
start_session under baseline network policy
  -> run_task under run network policy
  -> close_session under run network policy
```

`start_session()` 可以安装可信 Harness、生成配置、上传启动文件、启动后台进程或构造客户端。将这些准备与不可信 agent 运行过程分开，使 Benchmark 可以使用公开基线策略和受限运行策略。

`run_task()` 必须只执行一个 `PreparedTask`。使用 `prepared.input.prompt`、`messages`、`files`、`media`、`tools` 和 `workspace`，不要回读 Benchmark 内部实现。返回最佳可用最终答案、请求的文件、有序轨迹、词元用量、耗时、产物和准确 `TaskStatus`。

成功、超时、取消或错误时，`close_session()` 都必须释放 Harness 负责的客户端、子进程、服务器、临时配置和后台任务。它不关闭 Environment；该生命周期归 runtime 所有。

## 5. 标准化结果，但不改变得分

Harness 报告执行，而不是 Benchmark 正确性。进程退出代码为零不代表任务成功，非空答案也不代表答案正确。

必须保留：

* 供评测器使用的最终答案和输出产物。
* 准确的 `COMPLETED` 或 `RUN_ERROR` 状态，并保留超时、拒绝、无效输出和终止详情。
* 有序助手消息、工具调用、命令结果和 Environment 观察结果。
* model 与 Harness 用量、延迟、步骤数量和终止原因。
* 安装、启动、解析、model API 和 runtime 错误上下文。

不要把评测器失败转换为 Harness 失败，也不要在 Harness 内设置 Benchmark `correct` 或 `score`。

## 6. 处理安装与依赖

只支持实现能够复现的安装策略。常见选择包括固定预安装任务镜像、受控的受限执行前安装，或隔离驱动侧软件包可选依赖。

* agent CLI 或软件包版本影响结果时必须固定。
* 暴露安装返回码、标准输出和标准错误，但不能泄漏凭证。
* 不要假设每个任务镜像都有软件包管理器或编译器。
* 不要为了准备方便而放宽 agent 运行网络策略。
* 准备昂贵或对网络敏感时，优先使用兼容预构建镜像。
* 专用软件包不应进入 AgentCompass 默认安装。

model、评委、搜索和 provider 凭证必须通过受支持 Environment/配置机制传入，并在命令、生成的文件、日志、轨迹、URL 和异常中递归脱敏。

## 7. 限制命令、步骤、成本与 model 请求

每个限制只能有一个清晰负责人。Harness 命令超时约束 agent 命令或进程；步骤上限约束 agent 循环；model 客户端重试处理请求传输；runtime 重试重复失败任务尝试。不要用同一个参数名表示多层限制。

根据 Harness 成本跟踪契约处理未知 model 定价。用户显式选择忽略错误或已禁用成本模式时，缺少成本元数据不得终止计分运行。

## 8. 注册并检查组件

从 `src/agentcompass/harnesses/__init__.py` 导出 Harness，再验证注册表发现机制和配置结构：

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

Harness 必须有稳定 `id` 和非空用户可见 `description`。