Agent测试框架Harbor指南

Harbor 框架指南

一、Harbor 是什么？

Harbor 是一个 AI Agent 单元测试框架。

通俗理解

想象你要测试一个 AI 编程助手的能力：

传统方式：
你给 AI 出题 → AI 写代码 → 你人工检查代码对不对

Harbor 方式：
你定义任务 → Harbor 自动启动容器 → AI 在容器里执行 → 自动测试验证 → 输出分数

Harbor 就像是给 AI Agent 用的 JUnit/pytest，只不过：

• 传统测试：测试代码函数
• Harbor 测试：测试 AI Agent 的行为结果

前提条件：什么任务适合用 Harbor？

核心要求：任务必须有可编程验证的输出结果。

✅ 适合 Harbor 的任务：
├── 代码任务：修复 bug、实现功能、代码重构
├── 数据任务：数据处理、格式转换、数据分析
├── 系统任务：配置服务器、部署应用、编写脚本
├── 安全任务：修复漏洞、渗透测试
└── 科学计算：模型训练、数据分析、仿真模拟

❌ 不适合 Harbor 的任务：
├── 创意写作：写文章、写诗、写故事
├── 主观评价：设计评审、代码风格偏好
├── 开放问答：提供建议、头脑风暴
└── 模糊目标："优化代码"、"改进体验"（没有明确标准）

为什么？ Harbor 的验证机制是执行测试脚本并检查输出文件。如果任务的"正确答案"是主观的或无法编程判断，就无法编写 test.sh。

核心特点

特点	说明
沙箱隔离	每个 Task 在独立 Docker 容器中运行
自动验证	通过测试脚本自动判断任务是否完成
多 Agent 支持	支持 Claude Code、OpenHands、GPT 等 18+ Agent
参考解答	Oracle 直接执行参考脚本，验证任务可解性

快速开始：

# 安装
uv tool install harbor

# 创建任务
harbor tasks init my-task

# 验证任务
harbor run --path ./my-task --agent oracle

---

二、核心架构与运行原理

架构图

┌─────────────────────────────────────────────────────────────┐
│                        Harbor 架构                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐                                            │
│  │  CLI 命令   │  harbor run --path ./task --agent claude  │
│  └──────┬──────┘                                            │
│         │                                                   │
│         ▼                                                   │
│  ┌─────────────┐                                            │
│  │    Job      │  管理多个 Trial，汇总结果                   │
│  └──────┬──────┘                                            │
│         │                                                   │
│         ▼                                                   │
│  ┌─────────────┐                                            │
│  │   Trial     │  单次评估：环境启动 → Agent执行 → 验证打分  │
│  └──┬──┬──┬───┘                                            │
│     │  │  │                                                 │
│     ▼  ▼  ▼                                                 │
│  ┌────┐┌────┐┌────┐                                        │
│  │环境││Agent││验证│                                        │
│  │    ││    ││器  │                                        │
│  └────┘└────┘└────┘                                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

执行流程

┌──────────────────────────────────────────────────────────────┐
│                    完整执行流程                               │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  1. 加载 Task                                                │
│     ├── task.toml    → 解析配置（超时、资源、环境变量）        │
│     ├── instruction.md → 读取指令内容                         │
│     └── environment/ → 读取 Dockerfile                        │
│                                                              │
│  2. 启动环境 (Docker)                                        │
│     └── docker build + docker up                              │
│                                                              │
│  3. 安装 Agent                                               │
│     └── Agent 安装需要的工具（如 claude-code CLI）            │
│                                                              │
│  4. 执行 Agent                                               │
│     └── instruction.md → 传给 Agent 作为任务指令              │
│                                                              │
│  5. 验证结果 (Verifier)                                      │
│     ├── tests/test.sh → 上传到容器 /tests/                   │
│     └── 执行测试 → 输出到 /logs/verifier/reward.txt          │
│                                                              │
│  6. 清理环境                                                 │
│     └── docker down --volumes                                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

---