第42章：Harness框架

学习目标

理解Harness的核心定位：Agent的标准化执行框架
掌握Harness的架构：环境、数据集、评估器、执行器
了解如何使用Harness评估Agent质量
学会构建测试领域Agent Harness

前置要求

已完成第40-41章Agent开发的学习
理解Agent的基本执行流程
了解测试评估的基本概念

一句话定义

Harness（执行框架）

Harness是Agent的标准化执行和评估框架——它定义了Agent运行的环境、输入数据、执行流程、评估标准，让Agent的质量评估有统一的基准。

生活类比：考试系统

为什么叫Harness？

Harness就像考试系统：提供了考场（环境）、试卷（数据集）、监考老师（执行监控）、评分标准（评估器）。Agent在Harness中"考试"，成绩就是质量评估结果。

例如："测试Agent Harness"定义了测试任务数据集、执行监控、成功率评估标准。

Harness的核心架构

Harness测试框架架构图 — **图42-1** Harness框架架构：测试数据集（试卷）→ 执行环境（考场）→ 监控日志（监考）→ 评估器（评分），为Agent提供标准化质量评估基准

Harness架构组成

┌──────────────────────────────────────────────────────────────────┐
│                   Harness 框架架构                                 │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  1. Environment（执行环境）                                 │  │
│  │  ───────────────────────────────────────────────────────    │  │
│  │  - 工具可用性：哪些MCP Server/Skill可被调用                 │  │
│  │  - 资源限制：最大执行次数、时间限制                          │  │
│  │  - 状态隔离：每次执行的独立上下文                            │  │
│  │  - 配置管理：API密钥、环境变量                               │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              ↓                                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  2. Dataset（测试数据集）                                   │  │
│  │  ───────────────────────────────────────────────────────    │  │
│  │  - 任务定义：用户目标、预期输出                              │  │
│  │  - 输入数据：任务所需的上下文信息                            │  │
│  │  - Ground Truth：预期的正确结果                             │  │
│  │  - 难度分级：简单/中等/困难任务                              │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              ↓                                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  3. Executor（执行器）                                      │  │
│  │  ───────────────────────────────────────────────────────    │  │
│  │  - 任务分发：按数据集逐个执行任务                            │  │
│  │  - 执行监控：记录每次工具调用、思考过程                      │  │
│  │  - 日志收集：保存执行轨迹便于分析                            │  │
│  │  - 并行执行：支持多任务并行测试                              │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              ↓                                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  4. Evaluator（评估器）                                     │  │
│  │  ───────────────────────────────────────────────────────    │  │
│  │  - 成率评估：任务是否成功完成                                │  │
│  │  - 质量评估：输出是否符合预期                                │  │
│  │  - 效率评估：执行耗时、调用次数                              │  │
│  │  - 稳定性评估：多次执行的一致性                              │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              ↓                                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  5. Reporter（报告生成器）                                  │  │
│  │  ───────────────────────────────────────────────────────    │  │
│  │  - 结果汇总：成功率、失败原因分布                            │  │
│  │  - 详细日志：每个任务的执行轨迹                              │  │
│  │  - 对比分析：不同版本/模型的对比                             │  │
│  │  - 可视化图表：趋势图、分布图                                │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Harness的核心组件详解

组件	职责	配置要素	示例
Environment	定义Agent运行环境	工具列表、资源限制、配置	测试工具MCP Server、max_iterations=10
Dataset	定义测试任务集	任务列表、输入数据、预期结果	10个测试报告生成任务
Executor	执行Agent任务	Agent实例、执行策略	LangChain AgentExecutor
Evaluator	评估执行结果	评估标准、评分规则	成功率、准确性、耗时
Reporter	生成评估报告	报告格式、可视化选项	HTML报告、JSON日志

Harness配置示例

YAML - Harness配置

# test-agent-harness.yaml
name: test-report-agent-harness
version: 1.0.0
description: 测试报告生成Agent评估框架

# 1. Environment配置
environment:
  tools:
    - mcp_server: test-tools-server
    - skill: test-report-generator
  limits:
    max_iterations: 10
    timeout_seconds: 120
    max_tokens: 4000
  config:
    api_keys:
      anthropic: "${ANTHROPIC_API_KEY}"
    test_platform_url: "https://test.company.com"

# 2. Dataset配置
dataset:
  name: test-report-tasks
  tasks:
    - id: task-001
      input: "生成web项目今天的测试报告"
      expected_output:
        contains: ["测试报告", "通过率"]
        format: "html"
      difficulty: "easy"
      
    - id: task-002
      input: "分析支付模块失败测试的根因"
      expected_output:
        contains: ["根因", "建议"]
        has_sections: ["问题描述", "分析过程", "修复建议"]
      difficulty: "medium"
      
    - id: task-003
      input: "执行回归测试并生成完整报告"
      expected_output:
        contains: ["执行结果", "缺陷分析", "改进建议"]
        format: "html"
        attachments: ["report.html"]
      difficulty: "hard"

# 3. Executor配置
executor:
  agent_type: "langchain-react"
  parallel_workers: 3
  retry_count: 2
  logging:
    level: "verbose"
    save_traces: true

# 4. Evaluator配置
evaluator:
  metrics:
    - name: success_rate
      weight: 0.4
      criteria: "任务是否成功完成"
      
    - name: output_quality
      weight: 0.3
      criteria: "输出是否符合预期"
      
    - name: execution_efficiency
      weight: 0.2
      criteria: "执行耗时和调用次数"
      
    - name: stability
      weight: 0.1
      criteria: "多次执行的一致性"
  
  thresholds:
    passing_score: 0.7
    excellent_score: 0.9

# 5. Reporter配置
reporter:
  output_format: "html"
  include_traces: true
  include_metrics: true
  visualization:
    - success_rate_chart
    - difficulty_distribution
    - execution_time_histogram

Harness执行流程

Harness 执行流程：

输入：Harness配置 + Agent实例

┌────────────────────────────────────────────────────────────┐
│  Phase 1: 初始化                                            │
│  ──────────────────────────────────────────────────────    │
│  1.1 加载Environment配置                                    │
│  1.2 准备工具和资源                                          │
│  1.3 验证Agent实例                                           │
└────────────────────────────────────────────────────────────┘
                          ↓
┌────────────────────────────────────────────────────────────┐
│  Phase 2: 任务分发                                          │
│  ──────────────────────────────────────────────────────    │
│  For each task in Dataset:                                 │
│    2.1 准备任务输入                                          │
│    2.2 设置执行上下文                                        │
│    2.3 触发Agent执行                                         │
└────────────────────────────────────────────────────────────┘
                          ↓
┌────────────────────────────────────────────────────────────┐
│  Phase 3: 执行监控                                          │
│  ──────────────────────────────────────────────────────    │
│  During execution:                                          │
│    3.1 记录每次工具调用                                      │
│    3.2 记录Agent思考过程                                     │
│    3.3 监控资源消耗                                          │
│    3.4 检测异常和超时                                        │
│    3.5 收集执行日志                                          │
└────────────────────────────────────────────────────────────┘
                          ↓
┌────────────────────────────────────────────────────────────┐
│  Phase 4: 结果评估                                          │
│  ──────────────────────────────────────────────────────    │
│  After execution:                                           │
│    4.1 计算成功率                                            │
│    4.2 检查输出质量                                          │
│    4.3 统计效率指标                                          │
│    4.4 测试稳定性（可选重复执行）                             │
│    4.5 综合评分                                              │
└────────────────────────────────────────────────────────────┘
                          ↓
┌────────────────────────────────────────────────────────────┐
│  Phase 5: 报告生成                                          │
│  ──────────────────────────────────────────────────────    │
│  5.1 汇总评估结果                                            │
│  5.2 生成详细日志                                            │
│  5.3 可视化展示                                              │
│  5.4 输出最终报告                                            │
└────────────────────────────────────────────────────────────┘

输出：评估报告 + 执行日志 + 评分结果

测试领域Harness应用

Harness类型	评估场景	数据集内容
报告生成Harness	评估Agent生成测试报告的质量	10个不同项目的报告生成任务
缺陷分析Harness	评估Agent根因分析能力	20个真实缺陷分析任务
用例生成Harness	评估Agent生成测试用例的准确性	15个需求解析+用例生成任务
回归测试Harness	评估Agent执行回归测试的效率	不同变更规模的回归任务
性能测试Harness	评估Agent性能测试设计和分析	压测场景设计+结果分析任务

Harness评估结果解读

评估报告关键指标

指标	含义	阈值参考
成功率	任务成功完成的比例	≥70%合格，≥90%优秀
输出质量	输出符合预期的程度	关键内容覆盖率≥80%
执行效率	完成任务的耗时和调用次数	平均耗时≤60s，调用≤10次
稳定性	多次执行的一致性	结果一致性≥85%

本章小结

Harness是Agent的标准化执行和评估框架，像"考试系统"
核心架构：Environment（环境）→ Dataset（数据集）→ Executor（执行器）→ Evaluator（评估器）→ Reporter（报告）
Environment定义工具可用性、资源限制、配置
Dataset定义任务集、输入数据、预期结果、难度分级
Executor执行监控、日志收集、支持并行
Evaluator计算成功率、输出质量、效率、稳定性
Reporter生成评估报告和可视化图表
测试领域Harness：报告生成、缺陷分析、用例生成、回归测试、性能测试

扩展阅读

第43章：开发者平台生态 - Agent开发工具链
第44章：Claude Code实战 - Claude Code的Harness集成