---
title: "AI Harness 深度解析：从概念到工程实践"
date: 2026-03-18 21:00:00
author: Gamehu
tags:
  - AI
  - Harness Engineering
  - LLM Evaluation
  - 软件工程
categories:
  - AI
---

<div class="tag-container">
  <span class="ai-tag">AI Infrastructure</span>
  <span class="sub-tag">续篇</span>
</div>

上一篇[《从一次 tenantId 联调 bug，看我们该怎么给 AI 项目补齐 harness》](/2026/03/07/从一次tenantId联调bug-看我们该怎么给AI项目补齐harness/)里，我记录了一个真实项目中的 harness 搭建过程。

那次经历让我意识到：

<span class="highlight-text">AI 工程化的竞争力，不是"谁的模型更像天才"，而是"谁先把自己的真实环境整理成一个不会误导 agent 的工作台"。</span>

但「补齐 harness」这件事，说起来容易，做起来却有很多模糊地带——

- Harness 到底包括哪些具体的东西？
- 什么场景下应该优先补哪部分？
- 业界那些号称"零手写代码"的项目，他们的 harness 是怎么设计的？

这篇不聊具体 bug 了，我想从**概念、分类、工程实践**三个层面，把 Harness 这件事系统地理清楚。

如果你也在搞 AI Coding，正在困惑"除了写 prompt 还应该做什么"，这篇应该能帮到你。

[^1]: [Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/) - OpenAI, 2026-02-11

---

## 什么是 Harness？

**Harness = 用来控制、驱动、约束、评估一个系统行为的外部执行框架**

换句话说：
- ❌ 不是业务逻辑
- ✅ 是"包在系统外面的一层控制系统"

### 类比理解

| 类比 | 含义 |
|------|------|
| 马具（Horse Harness） | 控制马的方向和行为 |
| 安全带 | 限制人的自由，保证安全 |
| Test Harness | 控制程序执行并验证结果 |

核心本质：**让一个"有能力但不可控"的系统变得可控**。[^2]

[^2]: [Test harness - Wikipedia](https://en.wikipedia.org/wiki/Test_harness)

---

## 传统软件中的 Harness（你其实一直在用）

在 AI 火爆之前，Harness 这个概念已经在软件工程中存在几十年了。你可能每天都在用，只是没意识到。

### 1. Test Harness（测试框架）——最经典

这是 Harness 一词在软件工程中最常见的用法。

```
被测系统（SUT） ←→ Test Harness
                ↑
        ┌───────┴───────┐
        │  - 输入构造    │
        │  - Mock/Stub   │
        │  - 执行控制    │
        │  - 输出验证    │
        │  - 日志收集    │
        └───────────────┘
```

**实际例子**：
- JUnit / TestNG 测试框架
- 集成测试时启动的嵌入式数据库（H2）
- 模拟外部 API 的 WireMock / MockServer

### 2. Benchmark Harness（基准测试框架）

Java 开发者最熟悉的 **JMH**（Java Microbenchmark Harness）就是典型代表。[^3]

[^3]: [JMH - OpenJDK](https://openjdk.org/projects/code-tools/jmh/)

```java
@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
public class MyBenchmark {
    @Benchmark
    public void testMethod() {
        // 被测代码
    }
}
```

**Harness 的作用**：
- 预热 JVM，消除 JIT 编译影响
- 多轮运行，统计置信区间
- 控制 GC 时机，减少干扰
- 输出标准化的性能报告

### 3. Integration Harness（集成测试框架）

日常开发中常用的：

```yaml
# docker-compose.test.yml
version: '3'
services:
  app:
    build: .
    depends_on:
      - postgres
      - redis
  postgres:
    image: postgres:15
  redis:
    image: redis:7
```

这就是一种 Harness——**构造一个可控的系统环境**。

**其他例子**：
- 流量回放工具（GoReplay、TCPReplay）
- 混沌工程工具（Chaos Monkey）
- 负载测试工具（JMeter、k6）

### 4. 安全 Harness

- **沙箱（Sandbox）**：限制程序能访问的资源
- **Seccomp**：Linux 系统调用过滤
- **浏览器沙箱**：Chrome 的多进程架构

这些都是 Harness 的变体：**给"有能力但不可控"的系统加上约束**。

> **说明**：上文采取的是"广义 harness"用法，用来帮助理解"外层控制框架"这一共同本质；在不同子领域里，具体术语并不完全相同（如 sandbox/seccomp 更常见的分类是 security isolation，test harness 是软件工程的固定用法，而 agentic coding 语境下的 harness 更接近 orchestration + context + tools + validation + feedback loops）。

---

## 2025 年底到 2026 年初：长时自主 Agent 的工程实践升温

到 2025 年底到 2026 年初，行业里关于长时自主 agent 的工程实践明显升温，多个团队开始公开分享长时任务、多 agent 协作、可读环境与 harness 设计经验。

### 从"人类驱动"到"长时自主"

之前的 AI 工具（包括 ChatGPT、Copilot）大多是**人类驱动的**——你需要不断提示下一步动作。

但 2026 年的新趋势是**长时自主智能体（long-running autonomous agents）**：

- **OpenClaw**：通过内存上下文 + 触发器 + Cron 任务，实现持续自主运行
- **Cursor**：报告了一个"构建浏览器"的长时自主编码实验，官方写法是 over 1 million lines of code；他们同时还展示了其他长期并发 agent 项目
- **Anthropic**：用并行 Claude agents 构建了一个 Rust 写的 C compiler，重点不是"炫技"，而是总结如何为长时自主 agent team 设计 harness

这些项目的共同点是：**AI 不再等待人类指令，而是自主规划和执行长时任务**。

### 新问题出现了

当 AI 可以连续运行数小时甚至数天时，Prompt Engineering 和 Context Engineering 都不够了：

- 如何确保**跨会话**的上下文连贯？
- 如何让下一个"接手"的 Agent **快速理解**当前项目状态？
- 如何验证 Agent 的产出是否正确（而不是让它自己说"完成了"）？
- 如何设计**工具和环境**，让模型表现最佳？

这就是 **Harness Engineering** 要解决的问题。

---

## 为什么 AI 时代 Harness 突然重要？

因为 **LLM = 非确定性系统（Non-deterministic system）**

### 传统软件 vs AI 系统

| 维度 | 传统软件 | AI 系统 |
|------|----------|---------|
| 行为决定 | 代码决定 | Prompt + Model + Context |
| 确定性 | 确定性 | 概率性 |
| 断言方式 | `assertEquals(expected, actual)` | 自然语言输出（无限空间） |
| 可预测性 | 同一输入永远同一输出 | 同一 Prompt 可能不同结果 |

同一个 Prompt：
- 第一次正确
- 第二次错误
- 第三次又正确

这就是 AI 开发的日常。

---

## 从 Prompt Engineering 到 Harness Engineering

### 阶段一：Prompt Engineering（2023-2024）

关注点是"我怎么写 prompt 更聪明"。

```
给定角色 + 分步骤 + 加示例 → 期望输出
```

### 阶段二：Context Engineering（2025）

Andrej Karpathy 在 2025 年的推文中强调：**"context engineering > prompt engineering"**。[^4]

关注点是"模型在推理时能看到什么完整上下文"。

```
RAG + MCP + Memory + 外部工具 → 丰富上下文
```

[^4]: [Andrej Karpathy on X](https://x.com/karpathy/status/1937902205765607626) - 2025

### 阶段三：Harness Engineering（2026-）

当 AI 智能体开始执行**长时自主任务**（long-running autonomous tasks），Context Engineering 也不够用了。

**Harness Engineering 的核心关注点**：

1. **跨会话设计** —— 任务可能持续数小时、数天，需要中断和恢复
2. **多智能体协作** —— 不同 Agent 如何接力完成任务
3. **上下文检索** —— 每个新会话如何快速获取相关上下文
4. **工具设计** —— 选择什么样的工具让模型表现最佳
5. **验证机制** —— Agent 会过早声明"完成"，需要独立验证

**智能体的常见问题**：
- 忽略团队规范
- 生成违反架构依赖方向的代码
- 在并行执行时相互冲突
- 通过"熵增"逐渐降低代码质量
- **过早声明任务完成**（而实际上有 bug）

这些问题不是"模型应该看到什么"，而是：
> "系统应该阻止什么、测量什么、修复什么、验证什么"

2026 年 2 月，HashiCorp 联合创始人 Mitchell Hashimoto 在博客中明确使用了 **"harness engineering"** 这一说法，并赋予了它清晰的工程含义："I don't know if there is a broad industry-accepted term for this yet, but I've grown to calling this 'harness engineering.'" [^5]

[^5]: [Mitchell Hashimoto - My AI Adoption Journey](https://mitchellh.com/writing/my-ai-adoption-journey) - 2026-02

---

## AI Harness 的核心定义

> **AI Harness = 用于系统性验证、评估、对比、约束 LLM 行为的工程基础设施**

### 架构组成

```
┌──────────────────────┐
│     Test Dataset     │  ← 测试数据集（Prompt + Context）
│ (Prompt + Context)   │
└─────────┬────────────┘
          ↓
┌──────────────────────┐
│      Harness         │  ← 执行框架
│                      │
│ - 调用模型           │
│ - 控制参数           │
│ - 重试策略           │
│ - 日志记录           │
└─────────┬────────────┘
          ↓
┌──────────────────────┐
│     Evaluator        │  ← 评估器（规则 / LLM评估）
│ (规则 / LLM评估)     │
└─────────┬────────────┘
          ↓
┌──────────────────────┐
│      Metrics         │  ← 指标（准确率 / 稳定性 / 延迟）
│ (accuracy / score)   │
└──────────────────────┘
```

---

## 真实案例：没有 Harness vs 有 Harness

### 场景：客户对话意图识别

输入：客户说"这个太贵了"  
期望输出：`{"intent": "价格异议"}`

#### ❌ 没有 Harness

- 手动调 Prompt
- 靠感觉判断效果
- 不可复现

👉 玄学开发

#### ✅ 有 Harness

**Step 1：构建测试集**

```json
[
  {
    "id": "case_001",
    "input": "客户说：这个太贵了",
    "expected": {"intent": "价格异议"}
  },
  {
    "id": "case_002", 
    "input": "能便宜点吗",
    "expected": {"intent": "价格异议"}
  }
]
```

**Step 2：执行 Harness**

- 调用 LLM
- 控制 temperature
- 多次运行取平均

**Step 3：评估**

```python
# 规则评估
assert actual.intent == expected.intent

# 或用 LLM 评估（LLM-as-a-Judge）
judge_prompt = f"""
评估以下输出是否正确：
输入：{input}
期望：{expected}
实际：{actual}
返回：正确/错误 + 原因
"""
```

**Step 4：输出指标**

```
accuracy = 87%
stability = 方差 < 5%
avg_latency = 450ms
```

👉 **本质：把 AI 从"感觉好不好"变成"指标好不好"**[^6]

[^6]: [LLM Testing Framework Guide](https://www.leanware.co/insights/llm-testing-framework-guide) - Leanware, 2025-11-13

---

## OpenAI 的实验数据

OpenAI 在 2025 年 8 月-2026 年 1 月进行了一项实验：[^1]

| 指标 | 数据 |
|------|------|
| 团队规模 | 3 → 7 人 |
| 手写代码 | 0 行 |
| 生成代码 | 约 100 万行 |
| Pull Request | 约 1500 个 |
| 平均 PR/天 | 3.5 个/工程师 |
| 速度估算 | 比手动开发快约 10 倍 |

关键点：**初期生产力很低**，因为环境、工具、抽象和 repo 内部结构尚未充分为 agent 优化。随着 Harness 逐步完善，性能才大幅提升。

工程师的角色变成了"让智能体有用"——设计系统、架构和约束条件。

---

## Harness 改变结果的惊人案例

### 案例 1：Hashline（Can Boluk, 2026）

安全研究员 Can Boluk 发布了一个实验，只改变智能体的编辑格式：[^5]

```
# 传统格式
function hello() {
  return "world";
}

# Hashline 格式（每行加 2-3 字符哈希）
1:a3|function hello() {
2:f1|  return "world";
3:0e|}
```

智能体可以通过哈希引用行（如"替换 2:f1"），而不需要精确重现字符串。

**结果**：
- Grok Code Fast 1 的基准测试分数从 **6.7% → 68.3%**
- 平均输出 token 减少约 20%
- **模型权重没变，只有 Harness 变了**

### 案例 2：LangChain（Terminal Bench 2.0）

固定使用 `gpt-5.2-codex` 模型，**只改进 Harness**：[^5]

- 分数从 52.8% → 66.5%（+13.7 分）
- 排行榜排名从约 30 名 → 约 5 名

主要改进是添加了一个自动分析失败模式的工具。

**结论：在换模型之前，先检查 Harness。它往往提供最高的 ROI。**

---

## AI Harness 的核心组件

基于 OpenAI、Anthropic、Vercel 等公司的实践，一个完整的 AI Harness 应该包含：[^7][^8]

[^7]: [How to Evaluate LLMs on Your Own Data](https://aiengineerlab.in/models/evaluation/) - AI Engineer Lab, 2026-03-13
[^8]: [LLM Evaluation Framework](https://www.getzep.com/ai-agents/llm-evaluation-framework/) - Zep AI, 2025-03-01
[^11]: [Anthropic - Building a C compiler with a team of parallel Claudes](https://www.anthropic.com/engineering/building-c-compiler)
[^12]: [Vercel - We removed 80% of our agent's tools](https://vercel.com/blog/we-removed-80-percent-of-our-agents-tools)

### 0. 可读环境（Legible Environment）—— 长时任务的基础

对于长时运行的智能体，最重要但最容易被忽视的是**环境可读性**。

当一个新的 Agent 会话"接手"任务时，它需要在几分钟内理解：
- 项目当前状态是什么？
- 已经完成了什么？
- 下一步要做什么？

**最佳实践**：

| 文件 | 用途 |
|------|------|
| `features.json` | 功能清单和完成状态 |
| `progress.md` | 当前进度和阻塞项 |
| `AGENTS.md` | 项目架构和开发规范 |
| `init.sh` | 环境初始化脚本 |
| Git 提交历史 | 变更记录和决策轨迹 |

**关键原则**：
> 每个会话应该能快速"读懂"项目，而不是靠猜测或试错。

Vercel 和 Anthropic 的实践表明：**结构化的进度跟踪文件比复杂的记忆系统更有效**。[^11]

### 1. Test Case 管理

```json
{
  "id": "case_001",
  "input": "...",
  "expected": {...},
  "metadata": {
    "category": "价格异议",
    "difficulty": "medium",
    "source": "production_log"
  }
}
```

### 2. 执行器（Executor）

- 支持多模型（GPT / Claude / DeepSeek / Qwen）
- 支持多 Prompt 版本
- 控制温度、重试策略

### 3. Evaluator（评估器）

| 评估方式 | 适用场景 |
|----------|----------|
| **规则匹配** | JSON 结构验证、正则匹配 |
| **LLM-as-a-Judge** | 主观质量、语义相似度 |
| **人工评审** | 复杂场景、边界 case |
| **混合评估** | 先用规则过滤，再用 LLM 评估 |

### 4. Metrics（指标）

- **accuracy**：意图识别准确率
- **faithfulness**：事实一致性（防幻觉）
- **stability**：多次运行方差
- **latency**：响应延迟
- **cost**：单次调用成本
- **format_reliability**：结构化输出成功率

### 5. E2E 验证（端到端测试）—— 防止"假完成"

**关键洞察**：Agent 有强烈的倾向过早声明任务"完成"。这一观察来自多个团队的自主 agent 实验总结。

单元测试不够，因为 Agent 可能：
- 代码通过了测试，但功能不工作
- 实现了功能，但引入了回归 bug
- 完成了任务，但破坏了其他模块

**解决方案**：提供端到端验证工具

| 场景 | 验证工具 |
|------|----------|
| Web 应用 | Puppeteer、Playwright |
| API 服务 | 自动化集成测试 |
| 数据处理 | 输出数据校验 |
| 代码生成 | 编译 + 运行测试 |

**反馈循环**：
```
Agent 声明完成 → E2E 测试 → 失败 → 反馈给 Agent → 修复 → 重新验证
```

这比人工检查快得多，也更可靠。

### 6. 工具设计：通用优于专用

Vercel 的实践经验：[^12]

- **原来**：大量 specialized tools
- **改进后**：删掉大部分工具，只保留非常少的基础工具，核心是一个 **execute arbitrary bash commands** 的 file system agent，再加 ExecuteSQL

**结果**（在 5 个代表性查询上）：
- 成功率：从 80% → **100%**
- 速度：从 274.8s → 77.4s，**快 3.5 倍**

**原因**：
- 模型对通用原生工具（如 bash）的理解更深刻
- 减少工具选择的开销
- 批处理减少往返次数

**设计原则**：
> 让模型直接面对 legible file system + 少量通用工具，而不是复杂的专用工具链。

### 7. CI/CD 集成

```
git push →
自动跑 harness →
指标下降 → 阻断发布
```

[^9]: [DeepEval - LLM Evaluation Framework](https://github.com/confident-ai/deepeval)

---

## 可用的 Harness 工具生态

### 开源框架

| 工具 | 特点 | 链接 |
|------|------|------|
| **OpenAI Evals** | 官方评估框架 | [github.com/openai/evals](https://github.com/openai/evals) |
| **DeepEval** | Pytest 风格，14+ 内置指标 | [github.com/confident-ai/deepeval](https://github.com/confident-ai/deepeval) |
| **Promptfoo** | Prompt 测试和模型对比 | [github.com/promptfoo/promptfoo](https://github.com/promptfoo/promptfoo) |
| **HELM** | Stanford 的 holistic 评估 | [crfm.stanford.edu/helm](https://crfm.stanford.edu/helm/latest/) |
| **LangSmith** | LangChain 生态的观测和评估 | [smith.langchain.com](https://smith.langchain.com) |
| **Ragas** | RAG 管道评估标准 | [github.com/explodinggradients/ragas](https://github.com/explodinggradients/ragas) |

### 商业平台

| 平台 | 特点 |
|------|------|
| **Galileo** | 企业级，内置 guardrails 和实时监控 |
| **Arize Phoenix** | 开源可观测性 + 幻觉检测 |
| **Weights & Biases** | 实验跟踪 + LLM 评估 |

---

## 工程落地建议

### 起步三要素

1. **写上下文文件**
   
   创建 `CLAUDE.md` 或 `AGENTS.md`，包含：
   - 项目结构
   - 构建命令
   - 编码规范
   
   每次智能体犯错，就添加一条防止再犯的规则。[^5]

2. **选择性地连接 MCP**
   
   如果智能体经常引用某个外部系统，就通过 MCP 连接它。典型例子包括 Issue Tracker、Wiki、监控系统。
   
   **但只连接必要的**，否则 token 会被浪费。

3. **从简单评估开始**
   
   - 收集 50 个真实生产 Prompt
   - 在 3-5 个模型上运行
   - 人工评分，对比差异
   - 逐步自动化

### 常见陷阱

| 陷阱 | 解决方式 |
|------|----------|
| 只用合成数据 | 必须包含真实生产案例 |
| 测试样本太少 | 至少 30-50 个例子 |
| 忽略延迟和成本 | 把速度和价格纳入评估 |
| 过早过度自动化 | 早期保留人工评审 |
| 只关注模型能力 | 测试完整系统，不只是模型输出 |

---

## 核心总结

> **Harness 的本质：让不可控系统变成可度量、可优化、可上线的工程系统**

AI 开发的核心资产正在转移：

| 过去 | 现在 |
|------|------|
| 代码 | 数据集 |
| 逻辑 | Prompt |
| 单测 | Harness |

如果用传统软件工程类比，Harness Engineering 有点像 JUnit、CI/CD、测试基建、脚手架、约束机制和运行环境设计的组合体——它覆盖的不只是"评测和 CI"，还包括 agent legibility、repo as system of record、AGENTS.md、自动化反馈循环、工具约束、任务接力、E2E verification、并行协作结构。

你写的 Prompt、RAG 流程、Agent 逻辑——这些都需要被评估、被约束、被持续监控。

---

## 参考资源

### 官方/论文

- [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/) - OpenAI 官方文章
- [OpenAI Evals](https://github.com/openai/evals) - 官方评估框架
- [HELM - Stanford](https://crfm.stanford.edu/helm/latest/) - 全面的 LLM 评估基准
- [Test Harness - Wikipedia](https://en.wikipedia.org/wiki/Test_harness)

### 工程实践

- [Promptfoo](https://github.com/promptfoo/promptfoo) - 开源 Prompt 测试框架
- [DeepEval](https://github.com/confident-ai/deepeval) - Python LLM 评估框架
- [LangChain Evaluation](https://python.langchain.com/docs/guides/evaluation/) - LangChain 评估指南

### 深度解读

- [Beyond Prompts and Context: Harness Engineering](https://madplay.github.io/en/post/harness-engineering) - 概念演进时间线
- [OpenAI Harness Engineering - InfoQ](https://www.infoq.com/news/2026/02/openai-harness-engineering-codex/) - 中文技术解读
- [LLM Testing Framework Guide](https://www.leanware.co/insights/llm-testing-framework-guide) - 测试框架最佳实践
- [How to Evaluate LLMs](https://aiengineerlab.in/models/evaluation/) - 实用评估方法

### 官方工程博客

- [OpenAI - Harness engineering](https://openai.com/index/harness-engineering/) - OpenAI 官方 Harness Engineering 文章
- [Anthropic - Building a C compiler with parallel Claudes](https://www.anthropic.com/engineering/building-c-compiler) - Anthropic 并行 agent 实验
- [Cursor - Scaling long-running autonomous coding](https://cursor.com/blog/scaling-agents) - Cursor 长时自主编码实验
- [Vercel - We removed 80% of our agent's tools](https://vercel.com/blog/we-removed-80-percent-of-our-agents-tools) - Vercel 工具设计经验
- [Mitchell Hashimoto - My AI Adoption Journey](https://mitchellh.com/writing/my-ai-adoption-journey) - Harness Engineering 概念提出

### 视频

- [Andrej Karpathy - Software 2.0](https://www.youtube.com/watch?v=zjkBMFhNj_g) - 关于 AI 软件范式的经典演讲

---

## 最后

我们正处在一个转折点。

Prompt Engineering 只是开始，Context Engineering 是中间阶段，而 **Harness Engineering** 是 AI 应用走向生产就绪的必经之路。

如果你正在开发 AI 应用，不妨从今天开始：

1. 收集 50 个真实的测试用例
2. 建立一个简单的评估脚本
3. 在每次 Prompt 变更时跑一遍

这就是 Harness 的起点。