Harness Engineering

前言：Harness Engineering 的诞生

作者 杨艺韬 · 2,635 字

前言：Harness Engineering 的诞生

一个令人不安的事实

2026 年，AI Agent 的热度达到了前所未有的高度。

Claude Code 每天处理几百万次编程对话；Cursor 被硅谷的工程师称为"最好的 AI 编辑器"；Devin 声称能独立完成软件工程任务；AutoGPT 变体层出不穷；Langchain 的 Star 数突破 100,000。每一周，都有新的 Agent 产品发布，声称"会改变一切"。

但在这股热潮背后，有一个被刻意回避的事实：

绝大多数 Agent 项目在 demo 阶段惊艳全场，到生产环境就一地鸡毛。

数据会说话。2025 年末某 AI 调研机构对 200 家正在部署 Agent 的企业做了访谈，得出的数字：

为什么会这样？不是模型不够强。GPT-4、Claude Opus 4、Gemini 2.0、DeepSeek-R1 的能力已经远超两年前的想象。问题出在模型之外——出在"驾驭模型"的那一层工程上。

我把这层工程叫做 Harness Engineering。

什么是 Harness Engineering

Harness 的英文原意是"马具"——缰绳、马鞍、马镫的总和。一匹烈马再强壮，没有马具也骑不动。

大模型就是这匹烈马。它的原始能力惊人：能写代码、会推理、懂多语言、支持 toolcall。但把这些能力安全、可靠、可观测地组织成一个真实的产品——这不是模型能自己做到的事。它需要一整套工程。

这套工程至少涵盖 9 个维度：

mindmap
  root((Harness<br/>Engineering))
    工具设计
      粒度决策
      接口稳定性
      错误边界
    提示词架构
      System Prompt 分层
      指令冲突消解
      prompt template 管理
    上下文工程
      有限 context 的高效利用
      历史对话压缩
      长文档分块
    状态与记忆
      短期 vs 长期
      session 状态机
      记忆检索
    权限与沙箱
      能做什么
      不能做什么
      隔离策略
    多 Agent 协调
      任务分解
      并发执行
      结果合成
    Human-in-the-Loop
      何时插入人类
      中断和恢复
      人机协作 UX
    可观测性
      决策追踪
      错误定位
      行为回放
    评估与测试
      成功率度量
      回归测试
      对抗性测试

这张图里每一个分支，都对应本书的一个或几个章节。它们没有一个是模型能自己解决的——全都是工程问题。

为什么叫 "Harness" 而不是 "Framework"

Framework（框架）这个词被用滥了。市面上每一个 LangChain、Semantic Kernel、LlamaIndex 都把自己叫 framework。但问题是：

Framework 是可替换的，Harness 是不可替换的。

你可以今天用 LangChain、明天切 LangGraph、后天换自研——framework 一换，一半代码要重写。但 Harness Engineering 讲的那些设计原则不会过时：

Framework 是工具，Harness Engineering 是方法论。前者帮你解决具体问题，后者帮你判断什么是正确的问题。

为什么现在写这本书

本书的背景素材来自杨艺韬讲堂过去一年的系列源码专著:

沿着这些专著反向归纳,会发现一个反复出现的信号——Agent 工程这个领域的知识极度碎片化:

这本书试图填补这个空白。一本关于方法论而非框架的书。

本书的材料来源

方法论必须有实例支撑。本书的素材来自四个真实项目：

项目 版本 代码规模 本书用途
Claude Code v2.x (2026.3) ~38 万行 TS（src/ 实测） 全书主要案例（工具、权限、记忆、编排）
LangGraph v0.4.x ~8 万行 Py 状态机、中断、checkpointer 实现参考
LangChain v0.3.x ~15 万行 Py 工具抽象、Agent 基础组件对比
OpenClaw v1.0 (自研) ~20 万行 TS Provider 路由、热切换、Gateway 架构

Claude Code 是引用最多的案例——它是目前最复杂的生产级 Agent Harness,其工具系统、权限模型、记忆机制、多 Agent 协调的设计都极具参考价值。本书中引用的 Claude Code 行为、prompt、数据结构均来自对公开可得的 claude-code-main 仓库源码的直接阅读,以及官方文档的对照核验。

本书的八篇结构

全书 22 章（含前言），分成八篇：

graph TB
    subgraph "第一篇 · 开篇（ch00-01）"
        P0[ch00 前言<br/>你在读的这一章]
        P1[ch01 Agent Harness 全景]
    end

    subgraph "第二篇 · 架构基础（ch02-04）"
        P2[ch02 核心架构模式]
        P3[ch03 上下文工程]
        P4[ch04 循环与终止]
    end

    subgraph "第三篇 · 工具工程（ch05-07）"
        P5[ch05 工具设计哲学]
        P6[ch06 工具编排]
        P7[ch07 工具注册与发现]
    end

    subgraph "第四篇 · 提示词架构（ch08-10）"
        P8[ch08 System Prompt 分层]
        P9[ch09 Prompt Template]
        P10[ch10 少样本与 Chain-of-Thought]
    end

    subgraph "第五篇 · 状态与记忆（ch11-13）"
        P11[ch11 短期记忆]
        P12[ch12 长期记忆]
        P13[ch13 会话状态机]
    end

    subgraph "第六篇 · 安全与权限（ch14-15）"
        P14[ch14 权限模型]
        P15[ch15 沙箱与隔离]
    end

    subgraph "第七篇 · 协调（ch16-17）"
        P16[ch16 多 Agent 协调]
        P17[ch17 Human-in-the-Loop]
    end

    subgraph "第八篇 · 生产化（ch18-21）"
        P18[ch18 评估与测试]
        P19[ch19 可观测性]
        P20[ch20 成本与性能]
        P21[ch21 设计模式总结]
    end

    P1 --> P2 & P3 & P4
    P4 --> P5 & P6 & P7
    P7 --> P8 & P9 & P10
    P10 --> P11 & P12 & P13
    P13 --> P14 & P15
    P15 --> P16 & P17
    P17 --> P18 & P19 & P20 & P21

    style P0 fill:#3b82f6,color:#fff,stroke:none
    style P21 fill:#10b981,color:#fff,stroke:none

八篇是一条自洽的工程 pipeline——从底层架构到顶层运营。你可以线性读完、也可以按问题驱动跳读。

每一章的写作节奏

本书每一章都按同一个节奏组织：

  1. 问题域：这一章解决的是什么工程问题？为什么它很难？
  2. 设计意图：理想的解法应该具备哪些特征？
  3. 真实系统的实现：Claude Code / LangGraph / OpenClaw 是怎么做的？为什么这样选？
  4. 可迁移的方法论：从具体实现提炼出来的、跨框架跨语言的工程原则

注意第 4 步——可迁移性是本书的核心承诺。具体代码会过时，但"工具粒度应该按最小可撤销操作设计"这样的原则不会过时。如果你读完一章只记住了某个 framework 的 API 调用，那我们都失败了。

读者画像

本书为以下几类人写：

你不需要是 Python/JavaScript 大神。但需要：

一个约定：重原则、轻代码

本书重方法论、轻具体框架。我会引用大量代码作为案例，但这些代码不是让你照抄——是让你理解"它为什么这样设计"。

这意味着：

当你关闭这本书，脑子里留下的应该是"Agent 系统应该怎么设计"的思维框架，而不是"具体某个 API 怎么用"的记忆。前者保值 10 年，后者保值 3 个月。

一次写作的诚实披露

这本书由我一个人写成，但它的素材来自无数前人的工作：

如果说这本书有什么独特价值，那就是把这些碎片连成一张完整的工程地图。地图上的每一块石头都不是我挖出来的，但地图是我画的。

起步

Agent 工程是一门年轻的学科。它的最佳实践还在快速演进。任何敢说"我已经把它搞明白了"的人都是骗子——包括我自己。本书试图捕捉的是当前阶段（2026 年）的最佳共识。五年后回头看，某些章节可能会显得幼稚。那没关系——好的方法论书是阶梯，踩上去达到下一层后拆掉就好。

如果你读完这本书后觉得"我现在对 Agent 工程有了清晰的判断框架"——就是它的全部目标。

翻页，让我们开始这场旅程。

杨艺韬 2026 年 4 月 · 于北京

延伸阅读的推荐起点