AI Harness 深度解析：从概念到工程实践

发表于 分类于
AI Infrastructure 续篇

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

那次经历让我意识到：

AI 工程化的竞争力，不是”谁的模型更像天才”，而是”谁先把自己的真实环境整理成一个不会误导 agent 的工作台”。

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

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

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

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

[^1]: Harness engineering: leveraging Codex in an agent-first world - OpenAI, 2026-02-11

什么是 Harness？

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

换句话说：

  • ❌ 不是业务逻辑
  • ✅ 是”包在系统外面的一层控制系统”

类比理解

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

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

[^2]: Test harness - Wikipedia

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

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

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

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

1
2
3
4
5
6
7
8
9
被测系统（SUT） ←→ Test Harness
                ↑
        ┌───────┴───────┐
        │  - 输入构造    │
        │  - Mock/Stub   │
        │  - 执行控制    │
        │  - 输出验证    │
        │  - 日志收集    │
        └───────────────┘

实际例子：

  • JUnit / TestNG 测试框架
  • 集成测试时启动的嵌入式数据库（H2）
  • 模拟外部 API 的 WireMock / MockServer

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

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

[^3]: JMH - OpenJDK

1
2
3
4
5
6
7
8
@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
public class MyBenchmark {
    @Benchmark
    public void testMethod() {
        // 被测代码
    }
}

Harness 的作用：

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

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

日常开发中常用的：

1
2
3
4
5
6
7
8
9
10
11
12
# 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 更聪明”。

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

阶段二：Context Engineering（2025）

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

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

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

[^4]: Andrej Karpathy on X - 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 - 2026-02

AI Harness 的核心定义

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

架构组成

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
┌──────────────────────┐
│     Test Dataset     │  ← 测试数据集（Prompt + Context）
│ (Prompt + Context)   │
└─────────┬────────────┘
          ↓
┌──────────────────────┐
│      Harness         │  ← 执行框架
│                      │
│ - 调用模型           │
│ - 控制参数           │
│ - 重试策略           │
│ - 日志记录           │
└─────────┬────────────┘
          ↓
┌──────────────────────┐
│     Evaluator        │  ← 评估器（规则 / LLM评估）
│ (规则 / LLM评估)     │
└─────────┬────────────┘
          ↓
┌──────────────────────┐
│      Metrics         │  ← 指标（准确率 / 稳定性 / 延迟）
│ (accuracy / score)   │
└──────────────────────┘

真实案例：没有 Harness vs 有 Harness

场景：客户对话意图识别

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

❌ 没有 Harness

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

👉 玄学开发

✅ 有 Harness

Step 1：构建测试集

1
2
3
4
5
6
7
8
9
10
11
12
[
  {
    "id": "case_001",
    "input": "客户说：这个太贵了",
    "expected": {"intent": "价格异议"}
  },
  {
    "id": "case_002", 
    "input": "能便宜点吗",
    "expected": {"intent": "价格异议"}
  }
]

Step 2：执行 Harness

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

Step 3：评估

1
2
3
4
5
6
7
8
9
10
11
# 规则评估
assert actual.intent == expected.intent

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

Step 4：输出指标

1
2
3
accuracy = 87%
stability = 方差 < 5%
avg_latency = 450ms

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

[^6]: 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]

1
2
3
4
5
6
7
8
9
# 传统格式
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 - AI Engineer Lab, 2026-03-13
[^8]: LLM Evaluation Framework - Zep AI, 2025-03-01
[^11]: Anthropic - Building a C compiler with a team of parallel Claudes
[^12]: Vercel - We removed 80% of our agent’s tools

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

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

当一个新的 Agent 会话”接手”任务时，它需要在几分钟内理解：

  • 项目当前状态是什么？
  • 已经完成了什么？
  • 下一步要做什么？

最佳实践：

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

关键原则：

每个会话应该能快速”读懂”项目，而不是靠猜测或试错。

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

1. Test Case 管理

1
2
3
4
5
6
7
8
9
10
{
  "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 服务 自动化集成测试
数据处理 输出数据校验
代码生成 编译 + 运行测试

反馈循环：

1
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 集成

1
2
3
git push →
自动跑 harness →
指标下降 → 阻断发布

[^9]: DeepEval - LLM Evaluation Framework

可用的 Harness 工具生态

开源框架

工具 特点 链接
OpenAI Evals 官方评估框架 github.com/openai/evals
DeepEval Pytest 风格，14+ 内置指标 github.com/confident-ai/deepeval
Promptfoo Prompt 测试和模型对比 github.com/promptfoo/promptfoo
HELM Stanford 的 holistic 评估 crfm.stanford.edu/helm
LangSmith LangChain 生态的观测和评估 smith.langchain.com
Ragas RAG 管道评估标准 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 逻辑——这些都需要被评估、被约束、被持续监控。

参考资源

官方/论文

工程实践

深度解读

官方工程博客

视频

最后

我们正处在一个转折点。

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

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

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

这就是 Harness 的起点。