Jean's Blog

一个专注软件测试开发技术的个人博客

0%

Harness Engineering驾驭工程介绍

发表于 分类于
学习Harness Engineering学习笔记第一讲

介绍

Harness Engineering（驾驭工程）是 2026 年前后在 AI 工程领域兴起的软件工程范式，核心是围绕大语言模型（LLM）与 AI 智能体（Agent）构建可控、安全、可复用的运行环境与约束体系，核心公式：Agent = Model + Harness（模型提供能力，驾驭层负责可控执行）。

词源隐喻（精准易懂）

  • 野马：LLM / 大模型，能力强但不可控、易失控；
  • 马具（Harness）：驾驭系统，含规则、工具、校验、流程；
  • 骑手：工程师，负责设计系统、设定目标；
  • 千里马：AI Agent（模型 + Harness），安全可靠的生产力工具。

核心公式拆解

组成部分 类比 核心作用 关键描述
Model 引擎 决定 Agent 的能力上限 生成、推理、代码理解等核心能力都在模型权重里，但 “引擎再强，没有底盘和刹车，跑不过 100 公里就失败”
Harness 底盘 + 刹车 + 方向盘 保住 Agent 的运行下限，让上限真正落地 包含循环刹车、状态持久化、工具编排、上下文管理、验证闭环，是让模型能稳定持续运行的工程系统

三层次能力对比：差异从来不在生成代码，在持续行动

维度 ChatGPT（裸对话） ChatGPT + Code Interpreter Claude Code
能写代码吗 能 能 能
能真跑代码吗 否 能（沙箱内） 能（你本地）
能读写你的文件系统吗 否 否（只能沙箱临时文件） 能（整个项目目录）
能跨工具编排吗（git/pytest/shell） 否 部分（Python 内） 能
能持续 30 分钟不失败吗 否 否（context 溢出） 能（机制保护）
任务失败时会自己补救吗 否 部分（在同一回合内） 能（跨回合 + 跨 session）

  看到这张表，我们要注意到一个反差：前两行三列几乎没有差距（都能写代码、都能在沙箱里跑），但从第 3 行开始三列几乎跨了三个时代。而三列用的模型——GPT-5 / GPT-5 / Sonnet 4.6——都是当前最前沿的旗舰，能力基础在同一梯队。既然模型本身差距不大，造成第 3 行之后巨大落差的就只剩一个变量：模型外面那一层，也就是本课要讲的 harness。

  换个更狠的说法：把 Claude Code 里的 Sonnet 4.6 换成 GPT-5，它还是比裸的 GPT-5 强；把裸 ChatGPT 的模型升级到 Sonnet 4.6，它也追不上最朴素的 Claude Code。为什么？因为一次裸 API 调用产生的那次对话本身，就没有文件系统、没有 git commit 能力、没有跨 session 的进度文件——这些差异不在模型权重里，在调用模型的那套系统里。

为什么说 Harness 才是 Agent 落地的关键？

  1. Model 决定 “能跑多快”，Harness 决定 “能跑多久”

​ 很多人误以为 “模型越强，Agent 越好用”，但实际落地中，没有完善的 Harness，再强的模型也像没有底盘的引擎 —— 跑两步就失控、出错、崩溃，根本没法完成长任务。

  1. Harness 是让模型 “听话” 的约束与保障

它就像方向盘和刹车，帮模型：

  • 控方向：通过上下文管理、工具编排，让模型始终朝着目标前进，不跑偏；
  • 控风险：通过验证闭环、状态持久化，及时纠错、防崩溃，避免 “脱缰”；
  • 控流程：通过循环刹车（重试 / 校验机制），让模型的每一步都在可控范围内。

Harness 的真实效果

证明了 Harness 的价值：

同模型仅改 Harness，Terminal Bench 2.0 通过率从 52.8% → 66.5%，提升了 13.7 个百分点（LangChain 2026-02-17）

这意味着：模型本身没变，只是优化了驾驭层，任务成功率直接提升了近 14%。

这也印证了使用F1 类比：“引擎差一点，但底盘调校好了，能跑满整个赛季二十几个大奖赛。”

对 AI Agent 来说，哪怕模型不是顶尖的，只要 Harness 足够完善，也能稳定跑完全程、拿到好结果；反之，再强的模型，没有好的 Harness，也只能跑一两圈就退赛。

Harness Engineering 硬数据反击表

数据 出处 含义
同模型仅改 harness，Terminal Bench 2.0 从 52.8% → 66.5%，+13.7pp，排名 Top 30 → Top 5（测试模型：gpt-5.2-codex；同一任务集 Terminal Bench 2.0；测试时间 2026-02-17） LangChain 博客
2026-02-17，作者 Vivek Trivedy：
Improving DeepAgents with Harness Engineering		 证明 harness 是可测量的工程变量，不是玄学
OpenAI 内测产品：5 个月、约 100 万行代码（原文 “on the order of a million”）、约 1500 个 PR（原文 “roughly 1,500”）、全程零人工编码、开发时间约为传统方式的 1/10（原文 “on the order of ten times faster”；博文注明此为团队内部估算，非严格对照实验） OpenAI 工程团队博文
2026-02-11：
Harness engineering: leveraging Codex in an agent-first world		 证明 harness 可以承担生产级工程强度
Manus 团队 6 个月内重构 harness 5 次，每次都是删掉过时的复杂逻辑 Phil Schmid 博文
2026-01-05：
The importance of Agent Harness in 2026		 证明 harness 是活的工程系统，不是一次性架构
2026-04-02 Birgitta Böckeler在 martinfowler.com 发表 “Harness engineering for coding agent users”，Martin Fowler 系博客正式纳入 martinfowler.com:
Harness engineering for coding agent users		 证明业界权威博客已把它当作成熟命名的工程学科

Model 是 Agent 的上限潜力，Harness 是 Agent 的下限保障。没有 Harness 的模型只是 “裸奔的引擎”，加上 Harness，才是能稳定跑完比赛的 “可用赛车”。

AI工程思维的三级跃迁

flowchart LR
    A["第一代
Prompt Engineering
提示词工程
2022-2023 · 单轮对话
- 优化单次调用指令
- 精准表达意图"] --> B["第二代
Context Engineering
上下文工程
2024-2025 · 多轮精准
- 提供模型'当前可见信息'
- 包含历史对话、检索、工具"]
    B --> C["第三代
Harness Engineering
驾驭工程
2025-2026 · 长时运行
- 系统性约束与治理
- 持续观测、纠偏、收敛"]

    style A fill:#e6f2ff,stroke:#3399ff,stroke-width:2px
    style B fill:#e6f9e6,stroke:#339966,stroke-width:2px
    style C fill:#fff2e6,stroke:#cc6633,stroke-width:2px

第一代：Prompt Engineering（提示词工程）

时间：2022-2023 年，聚焦单轮对话场景

核心目标：解决「单次调用的指令表达」问题

  • 优化单次调用指令：通过清晰、结构化的提示词（如角色设定、示例、约束），让模型单次输出符合预期
  • 精准表达意图：解决模型理解偏差、答非所问的问题，是早期和大模型交互的核心手段

本质：

是 “教模型听懂话” 的基础工程，核心是优化单轮输入的语言表达，但对多轮对话、外部信息依赖的场景能力有限。

第二代：Context Engineering（上下文工程）

时间：2024-2025 年，聚焦多轮精准交互场景

核心目标：解决「多轮对话中的信息完整性与可见性」问题

  • 提供模型 “当前可见信息”：不仅包含用户的新指令，还会把历史对话、外部检索的知识、工具调用结果等信息，整理成模型能 “看到” 的上下文
  • 包含历史对话、检索、工具：比如 RAG（检索增强生成）、Agent 工具调用，本质都是通过上下文工程，让模型在多轮交互中始终掌握关键信息，保证回答的连贯性与准确性

本质：

是 “管理模型的视野” 的工程，它完全包含了提示词工程的能力，同时扩展了多轮、多信息源场景下的上下文组织能力，是当前主流的 AI 应用（如对话机器人、RAG 系统）的核心技术。

第三代：Harness Engineering（驾驭工程）

时间：2025-2026 年，聚焦长时运行场景

核心目标：解决「AI 系统长期运行的稳定性与可控性」问题

  • 系统性约束与治理：为长期运行的 AI Agent / 系统建立规则边界、权限控制、目标对齐机制，避免模型在长流程中偏离任务目标
  • 持续观测、纠偏、收敛：在 AI 长时间运行的过程中，实时监控行为与输出，发现偏差时自动调整提示词、上下文或流程，让系统始终收敛到预期目标

本质：

是 “驯服与治理 AI 系统” 的工程，它包含了前两代的所有能力，同时增加了长时运行的闭环控制能力，是面向复杂、长期任务（如自动化工作流、智能体集群）的下一代核心技术。

关键总结

  1. 递进关系：三代技术不是替代关系，而是包含与扩展的关系：
    • 提示词工程是基础
    • 上下文工程在提示词之上，解决多轮与信息扩展问题
    • 驾驭工程在前两者之上，解决长时运行的治理与控制问题
  2. 场景升级：从 “单次对话” 到 “多轮交互”，再到 “长期自治系统”，技术演进完全匹配了 AI 应用复杂度的提升
  3. 核心变化：交互的重心从 “怎么说清楚一句话”，变成了 “怎么管好一个持续运行的系统”

三代工程的包含关系与术语边界

Prompt Engineering、Context Engineering、Harness Engineering 之间到底是什么关系；Agent、Scaffolding、Framework、Runtime 这四个词各自和 Harness 的边界在哪里；以及 LangChain 本身是什么——是 Framework、Runtime，还是一个 Harness？

三代工程：包含关系而非替代关系

  三代工程不是”旧的被淘汰、新的上位”的替代关系，而是同心圆式的包含关系——写 prompt 的时候不会突然不需要上下文，管理 context 的时候也不会突然不需要 prompt。每一代都把前一代的能力吸纳进来，再加一层新的工程维度。

  提示词工程（2022-2023）管的是单轮 LLM 对话里如何把问题问得更好。上下文工程（2024-2025）管的是多轮对话里喂给 LLM 的信息如何更精准——包括 RAG、tool calling 的 schema、对话历史管理、instruction caching。驾驭工程（2025-2026）管的是多轮工具调用 + 长时间运行时，整个系统如何不失败——包括循环刹车、状态持久化、验证闭环、子代理分治。

  下次再看到”上下文工程取代提示词工程”或”驾驭工程取代上下文工程”这种标题，你可以直接关掉。作者没有理解同心圆。

  为了让”包含而非替代”不只停留在图示，我们把它落到一个真实产品上走一遍——以 Claude Code 处理”写登录功能”这个任务为例：当它启动时，Prompt Engineering 层在工作——system prompt 里写着”你是编程助手、使用 Anthropic 推荐的指令工程范式”；同时 Context Engineering 层也在工作——它会读取你项目目录里的 CLAUDE.md、把已有 tool 的 schema 注入 context、监测并压缩过长的 tool 输出；同时 Harness Engineering 层在工作——它用 max_iterations 硬刹车兜底循环、用 progress 文件持续保存进度、用 compaction 阈值触发 context 清理。一次 Claude Code 会话同时运行着三代工程的所有机制，没有哪一层被”替代”，只有层层叠加。这是包含关系最朴素的验证——同一个产品可以同时被三代工程的任意一代观察，都能看到对应机制在工作\。

术语边界：Agent / Scaffolding / Framework / Runtime vs Harness

  把身边几个高频术语一次性捋清楚，每个术语用”是什么 / 解决什么 / 与 Harness 区别”三连定位。在看表之前先认识两个后面反复出现的名字：LangGraph 是 LangChain 2024 年推出的状态机运行时（checkpoint / interrupt / 状态持久化），DeepAgents 是 LangChain 2025 年基于 LangGraph 预装八大机制的 harness 成品库。

术语边界对照

术语 是什么 解决什么 与 Harness 的关系
Agent 一个”会用工具完成任务”的软件实体（概念层） 让 LLM 具备行动能力，不只是回答 Agent 是目标，Harness 是让目标能持续运行的工程系统
Scaffolding prompt 到达模型前的组装层（含 prompt template / few-shot 拼接 / tool schema 注入） 让 LLM 的输入更可控 Scaffolding 是 Harness 的一部分（偏 context 装配层）
Framework 提供类库和抽象的开发工具包（LangChain / LlamaIndex 等） 让你不用从零写 LLM 调用链 Framework 是积木，Harness 是用积木搭出来的整车
Runtime 负责执行 agent 逻辑的运行时引擎（LangGraph / DeepAgents SDK） 让 agent 的状态机在工业环境可运行 Runtime 是发动机，Harness 是发动机 + 底盘 + 传动

  这里需要特别留意一个陷阱——“scaffolding” 在学术文献里比 harness 宽泛很多，甚至会覆盖到 prompt template 和微调数据。

【常见误区】把 scaffolding 当 harness 的同义词 后果：很多博客把 ‘prompt scaffolding’ 和 ‘harness’ 混用，让读者低估 harness 的工程复杂度 —— 以为做好 prompt 组装就等于做好了 harness，脱离 runtime 执行层的循环刹车、进度续传、验证闭环等关键机制。

正确做法：按本课的三代工程同心圆图定位 ——scaffolding 只是 context 装配层的一个子集，是 harness 的一部分，真正的 harness 必须覆盖 context + runtime + 长任务保护三层。

排查方法：看一个系统被宣称是 harness 时，检查它是否包含：(a) 循环终止刹车、(b) 跨 session 进度持久化、(c) 真机功能验证 —— 三者缺一就不是完整 harness

驾驭工程的拐点

Karpathy 时间判断：2025 Q3 是分水岭

“Agents basically didn’t work before December [2024]. Now they just barely work. And this is the window where harness engineering becomes real engineering.” —— Andrej Karpathy（YC AI Startup School 2025-06-17 主题演讲 “Software Is Changing (Again)”，后续在 X/Twitter 反复引用）

  Karpathy 这句话翻译过来是：”Agent 在 2024 年 12 月之前基本上跑不起来。现在它们勉强能跑起来。而这个勉强能跑起来的窗口，正是驾驭工程成为真正工程学科的时间点。” 原文的关键词是”勉强（barely）”——它不是说模型变神了，而是说模型终于跨过了某个基准线，让”在模型外面围一层系统让它长时间运行”从不可能变成可行。

  那个基准线具体是什么？大致可以用 SWE-bench（Princeton 提出的 GitHub issue 修复基准）60% 通过率来标——当 Claude 3.5 Sonnet 在 2025 年 Q3 把 SWE-bench Verified（经人工复核的高质量子集）带到 60% 这个量级，模型已经能”完成多数简单任务”，这时候我们在外面加 harness 才有边际收益。模型只有 30% 通过率的时候，harness 设计得再好也救不了；模型 90% 通过率的时候，harness 要做的事反而变少。60-90% 这个区间，是驾驭工程的黄金窗口——而这个窗口恰好从 2025 Q3 开始。

节点时间轴：术语怎么一步步被命名的

  下面这张表，是”Agent Harness” 这个术语从首用到定型的完整历史。请注意第一行——术语首用是 Vivek Trivedy（2025-09-23），不是 Harrison Chase，也不是 Anthropic。这一点很多博客写错了，本课在这里一次性正名。

驾驭工程术语演化 8 节点时间轴

# 日期 事件 作者 / 出处
1 2025-09-23 博文 “The Claude Code SDK and the Birth of HaaS（Harness-as-a-Service，把 harness 封装为服务形态）” 首次使用 “Agent Harness” 术语 Vivek Trivedy（独立 AI 博客作者，vtrivedy.com）
2 2025-10-25 博文 Agent Frameworks, Runtimes, and Harnesses - oh my! 明确引用并传播该术语，并自认 “I didn’t come up with it” 并链接 Trivedy Harrison Chase（LangChain 博客）
3 2025-11-26 官方首篇系统化博文 Effective Harnesses for Long-Running Agents Anthropic，作者 Justin Young
4 2026-01-05 博文 The importance of Agent Harness in 2026，提出 Bitter Lesson（Rich Sutton 2019 经典，简单通用方法最终胜过复杂领域知识）三原则（Start Simple / Build to Delete / Harness is the Dataset） Phil Schmid（Hugging Face 技术博主，philschmid.de）
5 2026-02-11 官方博文 Harness engineering: leveraging Codex in an agent-first world，用生产实证定型术语 OpenAI 工程团队
6 2026-02-17 博文 Improving DeepAgents with Harness Engineering，用 +13.7pp 实证证据证明 harness 的可量化价值 Vivek Trivedy @ LangChain
7 2026-02-18 博文 A Guide to Which AI to Use in the Agentic Era，用三分框架把概念推向大众 Ethan Mollick（Wharton 商学院教授，AI 大众传播者，oneusefulthing.org）
8 2026-03-24 博文 Harness Design for Long-Running Application Development，提出 GAN（生成对抗网络，”生成者 vs 鉴别者”对抗思路）启发的 Planner-Generator-Evaluator 三角色架构 Anthropic，作者 Prithvi Rajasekaran

  仔细看这张时间轴，我们会发现一个有意思的规律：前 4 个节点（2025-09 到 2026-01）是社群博客驱动的概念孵化；后 4 个节点（2026-02 到 2026-03）是大厂用实证数据 + 官方架构博文把它钉成学科。Trivedy 和 Schmid 是种子，Anthropic 和 OpenAI 是定调者，Mollick 是大众化传播者——六个月完成了一门学科从诞生到定型的完整周期。

  还有一个细节：Anthropic 在 6 个月里一口气发了两篇官方博文（2025-11-26 和 2026-03-24），前一篇讲”机制是什么”，后一篇讲”架构怎么设计”。这个节奏说明什么？说明 Anthropic 把驾驭工程当成严肃的工程学科在持续投资，不是一次博客营销。

实证数据收束：两个决定性证据

回到 Karpathy 那句话的核心——“勉强能跑起来”的时代，决定成败的不再是模型选型，而是 harness 设计。两条硬数据让这个判断落地：

  • 证据一（LangChain 2026-02-17）：同模型、同 benchmark、只改 harness，Terminal Bench 2.0 从 52.8% → 66.5%，+13.7 个百分点。当你用这一条去反驳”这是 feedback control 换皮”的人，对方没得反驳——feedback control 没人能给你看 benchmark 曲线。

  • 证据二（OpenAI 2026-02-11）：一个内测产品，5 个月、约 100 万行代码（原文 “on the order of a million”）、约 1500 个 PR（原文 “roughly 1,500”）、全程零人工编码、开发时间\约为传统方式的 1/10**。这是 OpenAI 以官方博文形式做的技术声明，可以当作”驾驭工程能承担生产级工程强度”的硬证据。

这两条证据合起来的教学结论：决定模型能不能上线的是模型本身，决定能不能稳定交付的是 harness。前者是 2023 年之前 AI 工程的核心问题，后者是 2026 年及以后的核心问题——我们现在学驾驭工程，不是跟风，是踩在学科刚立起来的最佳时间点上。

naive agent （裸奔智能体）的八种失效方式

示例代码展示

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
"""
naive_agent_demo.py — 教学示意：增强可读性的 ~50 行 naive tool-calling 循环
故意保留全部 8 个故障点，不作生产参考。
"""
import os
import json
import subprocess
from openai import OpenAI  # 依赖: openai>=1.50.0

# -------------------------- 配置区 --------------------------
MODEL = os.getenv("OPENAI_MODEL", "gpt-5")
# 课堂安全保护：限制最大循环次数，避免无限运行
SAFE_MAX_ITER = 3
client = OpenAI()

# 工具定义（标准 OpenAI Function Call Schema）
TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "读取文件内容",
            "parameters": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "write_file",
            "description": "写入/覆盖文件内容",
            "parameters": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "run_pytest",
            "description": "运行 pytest 测试",
            "parameters": {"type": "object", "properties": {}}
        }
    }
]

# -------------------------- 工具实现（全部无保护） --------------------------
def read_file(path: str) -> str:
    """故障点④：文件不存在会抛出异常，被主循环吞成空串"""
    with open(path, "r", encoding="utf-8") as f:
        return f.read()

def write_file(path: str, content: str) -> str:
    """故障点⑥：无权限校验，可覆盖任何文件（如系统配置、代码库核心文件）"""
    with open(path, "w", encoding="utf-8") as f:
        f.write(content)
    return "write done"

def run_pytest() -> str:
    """故障点④：只返回 stdout，丢弃 exit code，agent 无法感知测试失败"""
    result = subprocess.run(
        ["pytest"],
        capture_output=True,
        text=True,
        encoding="utf-8"
    )
    return result.stdout

# -------------------------- 主循环（八大故障点集中地） --------------------------
def naive_agent(task: str):
    messages = [
        # 故障点③：system prompt 后续会被修改，破坏前缀一致性，导致 prompt cache 失效
        {"role": "system", "content": "你是编程助手。完成任务后停止。[session_iter=0]"},
        {"role": "user", "content": task},
    ]

    # 故障点①：真实 naive agent 是 while True，这里只是这里演示加了次数限制
    for i in range(SAFE_MAX_ITER):
        # 故障点③：每次迭代修改 system prompt，导致上下文不稳定
        messages[0]["content"] = f"你是编程助手。完成任务后停止。[session_iter={i}]"

        # 调用 LLM 获取决策
        response = client.chat.completions.create(
            model=MODEL,
            messages=messages,
            tools=TOOLS
        )
        msg = response.choices[0].message

        # 故障点②：无上下文管理，消息无限追加，导致 token 消耗爆炸、上下文窗口溢出
        messages.append(msg)

        if msg.tool_calls:
            for tool_call in msg.tool_calls:
                # 解析工具调用参数
                args = json.loads(tool_call.function.arguments)
                tool_name = tool_call.function.name

                try:
                    # 故障点⑥：无安全校验，直接执行任何工具调用（包括危险命令）
                    tool_func = {
                        "read_file": read_file,
                        "write_file": write_file,
                        "run_pytest": run_pytest
                    }[tool_name]
                    tool_result = tool_func(**args)
                except Exception:
                    # 故障点④：所有异常都吞成空串，agent 以为一切正常，无法感知错误
                    tool_result = ""

                # 把工具执行结果追加到上下文
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": tool_result
                })
        else:
            # 故障点⑦：无独立的任务评估器，仅靠模型自报完成即退出；故障点⑤：退出后不保存进度
            print("Agent 认为任务已完成，退出循环")
            break

if __name__ == "__main__":
    # 故障点⑧：无 token/cost 预算控制，会持续消耗 API 费用
    naive_agent("读取 test_calculator.py，修复失败的测试，运行 pytest 确认通过")

这段代码是一个诚实的 “tool-calling 教科书实现”——100 行左右完成了所有”必要的事”：调 LLM、解析 tool_calls、执行工具、把结果塞回 messages、下一轮。如果你是刚学 Agent 的人，这就是你会从 OpenAI cookbook 里抄来的版本。它的罪不在写得差，在太朴素——朴素到完全没有防御性设计，也就完全没有 harness。

其中的八大故障模式

失效模式 典型现场表现 直接后果 对应你代码中的位置
循环失控 while True 无终止条件 / 无独立的终止验证 API 额度耗尽、服务器资源被占满，任务停不下来 代码中用了 SAFE_MAX_ITER_FOR_CLASSROOM 做课堂保护，去掉就是典型的 while True
Context 溢出 messages 列表被无限追加，无裁剪 / 归档 / 淘汰逻辑 超出模型上下文窗口报错；token 消耗指数级上升，费用失控 messages.append(msg) 每次循环都追加消息，上下文越攒越大
Cache Miss（缓存失效） 每次循环修改 system prompt 等固定前缀，导致缓存不命中 请求延迟翻倍、token 费用翻倍，无法享受模型缓存优化 messages[0]["content"] = f"...[session_iter={i}]" 每次迭代都修改 system prompt
Tool 错误吞 工具调用异常被 try-except 吞掉 / 工具执行的返回码被丢弃 Agent 完全感知不到错误，在错误状态上继续操作，越跑越偏 except Exception: result = "" 和 run_pytest() 只返回 stdout、丢弃 returncode
状态丢失 无进度文件 / 状态快照，所有状态仅存在内存中 会话崩溃 / 关闭后进度全丢，任务无法续跑 主循环结束后没有任何持久化逻辑，退出即丢状态
缺权限闸 无危险命令拦截、无路径白名单，高危操作（rm -rf // 覆盖核心文件）直接执行 数据损毁、生产事故，甚至服务器被破坏 write_file 可覆盖任意路径文件，无任何安全校验 / 权限控制
缺自动化评审 完全依赖 Agent 自评 “任务完成”，无独立的第三方评估器 任务没完成 / 结果错误，但 Agent 认为自己做完了，问题被带到交付环节 else: break 仅靠模型说 “完成了” 就退出，没有独立验证
成本失控 无 token 预算、调用次数上限、费用告警机制 长任务无限消耗 API，直接耗尽月度预算，产生巨额账单 代码中无 token 计数、预算检查的任何逻辑

这 8 个点，本质上就是驾驭工程（Harness Engineering）要解决的核心问题清单：

  • 循环失控、Context 溢出、成本失控 → 资源与成本治理
  • Cache Miss → 性能优化与成本控制
  • Tool 错误吞、缺权限闸 → 工具调用安全与可靠性
  • 状态丢失 → 任务可恢复性
  • 缺自动化评审 → 结果质量校验

所有成熟的 Agent 框架，本质上都是在给 naive agent 补上这些 “短板”，让它能稳定、安全、可控地运行。

naive agent （裸奔智能体）失效时间线

flowchart LR
    A[任务启动] --> B[第1轮]
    B --> C[第2轮]
    C --> D[第3轮+]
    D --> E[Session运行中]
    E --> F[任务完成/会话结束]

    %% 标注各阶段故障
    B -->|循环失控| B
    B -->|Cache Miss| C
    C -->|Tool错误吞| C
    D -->|Context溢出| D
    E -->|缺权限闸| E
    E -->|成本失控| F
    F -->|状态丢失| F
    F -->|缺自动化评审| F
失效模式 核心描述 风险发生阶段 直接后果
循环失控 while True 无终止验证，模型一直认为任务没完成，无限循环调用 API 第 1 轮就可能触发 API 额度被耗尽，任务永远停不下来
Context 溢出 messages 列表被无限追加，轮次越多 prompt 越长 第 3 轮后快速恶化 超出模型上下文窗口报错，Token 费用失控
Cache Miss system prompt 每轮被改写，前缀不稳定导致缓存全部失效 每轮循环都会触发 请求延迟翻倍、Token 费用翻倍
Tool 错误吞 except 捕获异常后返回空字符串，Agent 误以为工具调用成功 第 2 轮开始常见 在错误的基础上继续操作，任务越跑越偏
状态丢失 无进度文件，关闭窗口后所有进度清零 Session 结束时触发 长任务无法跨天续跑，一切努力白费
缺权限闸 无权限控制，rm -rf/sudo 高危命令可直接执行 任意时刻都可能触发 数据损毁、生产事故，甚至服务器被破坏
缺自动化评审 Agent 自评 “任务完成” 就退出，无独立 Evaluator 把关 任务完成时触发 问题没解决就交付，事后返工成本极高
成本失控 无 Token 预算控制，循环跑多久 API 烧多少 全程累积 长任务直接耗尽月度 API 预算，产生巨额账单

Harness Engineering应对的八大机制

序号 方案名称 核心实现 解决的失效模式 关键细节
1 Agent Loop 四相循环 Gather → Action → Verify → Iterate + max_iterations 硬刹车 循环失控 给 Agent 加上明确的终止条件和最大轮次限制，从源头避免无限循环。
2 Tool Use 工具编排 Schema 契约化调用，工具失败返回结构化错误，而非空字符串 Tool 错误吞 工具调用失败时，返回带错误码 / 原因的结构化数据，让 Agent 能感知错误、重试或调整。
3 Progress Tracking 进度追踪 claude-progress.txt + git commit 持久化进度快照 状态丢失 把每一步进度保存到文件 / 版本控制中，会话关闭后可续跑，长任务不怕中断。
4 Context Management 上下文管理 Token 监控 + 阈值压缩 / 重置 + 固定前缀 Context 溢出、Cache Miss 控制上下文长度，超出阈值时做压缩 / 归档；同时保持 system prompt 等前缀稳定，确保缓存命中。
5 Feature List 任务拆解 JSON 任务清单 + 单次只做一件事，从源头切细上下文 Context 溢出 把大任务拆成原子步骤，避免一次性把所有信息都塞进上下文，从源头控制 prompt 长度。
6 Verification Loop 验证闭环 Playwright/pytest 真机验证，不依赖 LLM 自评 缺自动化评审 用自动化测试工具（pytest、浏览器自动化）验证任务结果，而不是靠 Agent 自己说 “完成了”。
7 Subagents 子代理分治 独立 context 隔离子任务，主 Agent 不被中间过程污染 Context 溢出、循环失控 把复杂子任务交给独立子 Agent 处理，每个子 Agent 有自己的上下文，避免主循环被污染或失控。
8 Generator-Evaluator 生成 - 评估对抗 Planner + Generator + Evaluator 三角色分离，类似 GAN 缺自动化评审 引入独立的 “评估者” 角色，和生成者对抗，自动检查结果是否符合预期，避免自评偏差。

方案的出处与背景

大部分方案都标注了 Claude Agent SDK / Anthropic 和对应的日期，说明这些都是 Anthropic 官方推出的成熟实践，不是凭空想出来的 “最佳实践”。

和驾驭工程（Harness Engineering）的关系

这 8 个方案，合起来就是驾驭工程的核心组成部分：

  • 循环控制、成本控制 → 资源治理
  • 上下文管理、子代理分治 → 信息治理
  • 工具编排、验证闭环 → 可靠性治理
  • 进度追踪 → 任务可恢复性治理
flowchart LR
    subgraph 前置防护
        A[Feature List 任务拆解] --> B[Agent Loop 四相循环 + max_iterations]
        C[Progress Tracking 进度快照] --> B
    end

    subgraph 运行中防护
        B --> D[Gather]
        D --> E[Action]
        E --> F[Verify]
        F --> G[Iterate]

        E -->|使用| H[Tool Use 工具编排（结构化错误）]
        B -->|持续控制| I[Context Management 上下文压缩/缓存优化]
        B -->|分治| J[Subagents 子代理隔离]
    end

    subgraph 结果验证
        G --> K[Verification Loop 真机验证]
        K --> L[Generator-Evaluator 对抗评估]
    end

LangChain 三层架构：Framework、Runtime、Harness 同一家

  接下来用 LangChain 这个你最熟悉的例子把上面四个术语同时落地。LangChain 创始人 Harrison Chase 在 2025-10-25 博文 Agent Frameworks, Runtimes, and Harnesses - oh my! 里把产品线切成了三层。

  在看表之前先做个小铺垫：如果你用过 LangChain 的 LCEL 或 AgentExecutor，你已经在用 Framework 层；LangGraph 是 LangChain 2024 年推出的状态机引擎，把一次对话升级为可暂停、可恢复的有状态工作流（这就是表里提到的 checkpoint / interrupt）；DeepAgents 则是在 LangGraph 之上预装好八大机制的”整车”。如果这三者的区别暂时记不住不用慌——我们在第八章生态地图里会再次见到它们，到时候再回过头看这张表会更清晰。顺便补一个生态定位：LangChain 在整体 AI 技术栈中位于 Framework+Runtime+Harness 层，上游是 LLM API（OpenAI / Anthropic / 国产模型），下游是应用（ChatBot / IDE / CLI）。

LangChain 三层产品架构

层 LangChain 对应产品 角色 类比
Framework langchain-core / integrations 提供 LLM / tool / retriever 的抽象基类 积木
Runtime LangGraph 提供状态机 / checkpoint / interrupt 的执行引擎 发动机
Harness DeepAgents 把 LangGraph 组装成”能跑长任务”的完整系统 整车

  看到这张表，我们就理解了为什么 2026 年之后 LangChain 的主推产品从 AgentExecutor 转向 DeepAgents——前者是 Runtime 级别的抽象（工程师还要自己拼装成 Harness），后者本身就是一个 Harness 成品。Harrison Chase 在那篇博文里说得很直白：大多数工程师需要的不是 runtime，是一个能直接跑的 harness，LangChain 要把 harness 这一层也做完。

  到这里我们手里已经有了 Agent = Model + Harness 公式、三代工程包含关系、四个术语边界、LangChain 三层落地——这是本课所有后续内容的”字典基底”。接下来我们要做一件更决定性的事：把一个没有 harness 保护的 naive agent 拉出来现场复现失效，让你亲眼看到缺了 harness 的 agent 到底有多脆弱。