代码实现

实现 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：

start_session under setup network policy
  -> run_task under run network policy
  -> close_session after setup policy is restored

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，再验证注册表发现机制和配置结构：

uv run agentcompass list harness
uv run agentcompass config docs harness <harness-id>

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