Harness Engineering

前言：Harness Engineering 的诞生

作者 杨艺韬 · 3,770 字 · 发布于 · 更新于

一个令人不安的事实

2026 年，AI Agent 是整个软件行业投入最集中的方向之一。

Claude Code、Cursor 这类编码 Agent 已进入许多工程师的日常开发；Devin 声称能独立完成软件工程任务；AutoGPT 变体层出不穷；LangChain 在 GitHub 上的 Star 数早已超过 10 万。每一周，都有新的 Agent 产品发布，声称"会改变一切"。

但在这股热潮背后，有一个常被忽略的事实：

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

数据会说话。这不是印象流，几家可以点名的机构给出了方向一致的数字：

三条数据的口径并不相同：联想/IDC 统计的是 POC 的转化率，Gartner 预测的是 agentic 项目的取消率，RAND 转述的是 AI 项目的整体失败率。它们不能相加，也不该互相印证成一个"行业失败率"。放在一起只说明一件事：从能跑到能上线之间，隔着一层系统性的东西。

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

这层工程，本专栏称之为 Harness Engineering。这个叫法不是本专栏发明的：2026 年 2 月 5 日，Mitchell Hashimoto 在博客《My AI Adoption Journey》中写道 "I've grown to calling this 'harness engineering'"（https://mitchellh.com/writing/my-ai-adoption-journey）；同月 OpenAI 发表《Harness engineering: leveraging Codex in an agent-first world》（https://openai.com/index/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 2026.3.31 快照（= @anthropic-ai/claude-code@2.1.88 的 source map，该版本已下架） ~38 万行 TS（src/ 下 .ts 实测 379997 行） 本专栏主要案例（工具、权限、记忆、编排）
LangGraph 1.1.6 ~6.1 万行 Py（libs/ 排除 tests 实测 61283 行） 状态机、中断、checkpointer 实现参考
LangChain langchain-core 1.2.26 系 ~14.7 万行 Py（libs/core+langchain+langchain_v1 排除 tests 实测 147303 行） 工具抽象、Agent 基础组件对比
OpenClaw v2026.3.31（开源项目，与《OpenClaw 设计与实现》同一基准） ~168 万行 TS（全仓 .ts 实测 1681598 行，含测试与扩展） Provider 路由、热切换、Gateway 架构

口径说明：上表每个数字都注明了统计范围，因为"多少万行"离开范围就没有意义——含不含测试、含不含 vendor、含不含 partner 包，结论可以差出一倍。Python 侧两个数字可以这样复现：

# LangGraph
git clone https://github.com/langchain-ai/langgraph.git && cd langgraph
git checkout 1.1.6
find libs -name '*.py' -not -path '*/tests/*' -print0 | xargs -0 wc -l | tail -1

# LangChain（checkout 到与《LangChain 设计与实现》同一基准快照）
git clone https://github.com/langchain-ai/langchain.git && cd langchain
git checkout langchain-core==1.2.26
find libs/core libs/langchain libs/langchain_v1 -name '*.py' -not -path '*/tests/*' -print0 | xargs -0 wc -l | tail -1

版本说明：LangChain 与 LangGraph 的 1.0 于 2025 年 10 月 17 日同日 GA。本专栏采用 1.x 分支，与《LangChain 设计与实现》专栏的基准快照保持一致；本专栏中出现的 StateGraph、interrupt/Command、langgraph.store、langchain_core.* 等 API 均以 1.x 为准。涉及 0.x 时代的写法（如 AgentExecutor）只在讲历史演进时出现，并会明确标注。

Claude Code 是引用最多的案例——它是目前少数可以近距离观察的、复杂度足够高的生产级 Agent Harness，其工具系统、权限模型、记忆机制、多 Agent 协调的设计都极具参考价值。本专栏中引用的 Claude Code 行为、prompt、数据结构来自对其公开文档、官方博客、技术分享的研究，以及作者对其可观测行为（CLI 交互、工具调用模式、错误处理策略等）的工程还原；部分实现细节基于作者获得的源码快照进行分析，会在相关章节注明。

本专栏的结构

全专栏 22 章（含前言），分成开篇与八个部分（与首页目录同一套划分）：

graph TB
    subgraph "开篇（ch00-01）"
        P0[ch00 前言<br/>你在读的这一章]
        P1[ch01 为什么是 Harness]
    end
    subgraph "第一部分 · Agent 架构基础（ch02-04）"
        P2[ch02 架构模式]
        P3[ch03 Agent 主循环]
        P4[ch04 上下文工程]
    end
    subgraph "第二部分 · 工具工程（ch05-07）"
        P5[ch05 工具设计]
        P6[ch06 工具编排]
        P7[ch07 工具错误恢复]
    end
    subgraph "第三部分 · 提示词架构（ch08-10）"
        P8[ch08 Prompt 架构]
        P9[ch09 指令优先级]
        P10[ch10 Few-shot、CoT 与动态提示策略]
    end
    subgraph "第四部分 · 状态与记忆（ch11-13）"
        P11[ch11 短期记忆：上下文窗口管理]
        P12[ch12 长期记忆：持久化与检索]
        P13[ch13 多轮对话与会话状态机]
    end
    subgraph "第五部分 · 安全与权限（ch14-15）"
        P14[ch14 权限模型]
        P15[ch15 沙箱与隔离]
    end
    subgraph "第六部分 · 多 Agent 系统（ch16-17）"
        P16[ch16 多 Agent 协调模式]
        P17[ch17 Human-in-the-Loop]
    end
    subgraph "第七部分 · 生产化（ch18-20）"
        P18[ch18 评估与测试]
        P19[ch19 可观测性]
        P20[ch20 成本控制与性能优化]
    end
    subgraph "第八部分 · 总结（ch21）"
        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:#2563eb,color:#fff,stroke:none
    style P21 fill:#10b981,color:#333,stroke:none

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

每一章的写作节奏

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

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

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

读者画像

本专栏为以下几类人写：

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

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

本专栏重方法论、轻具体框架。真实系统的分析难免会引用源码路径、字段名或版本号；这些细节仅用于理解设计意图，不是需要记忆的 API 规范。我会引用大量代码作为案例，但这些代码不是让你照抄——是让你理解"它为什么这样设计"。

这意味着：

当你关闭这个专栏，脑子里留下的应该是"Agent 系统应该怎么设计"的思维框架，而不是"具体某个 API 怎么用"的记忆。前者能用很多年，后者可能几个月就过时。

一次写作的诚实披露

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

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

起步

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

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

下面从第 1 章开始。

延伸阅读的推荐起点