Harness Engineering — AI Agent 工程方法论

讲清楚如何驾驭 AI Agent 的一套工程方法论。

模型是引擎，Harness 是缰绳。

Demo 五分钟，生产五个月。 把一个 Agent 跑通很容易——几十行代码接上 function calling 就有了。但把它交给真实用户之后，你会连续撞上一串没人替你解决的问题：工具返回 8000 token 的日志，上下文两轮就满了；同一句提示词昨天好用今天翻车，而你不知道改了什么；Agent 并发调用三个工具，其中一个依赖另一个的结果；它要删一个文件，你不知道该不该拦；上线一周后有人说"它变笨了"，而你手里没有任何可以对比的数据。

这些问题都不在模型里。它们在模型外面那一层——Harness。

flowchart LR
  U[用户意图] --> H
  subgraph H [Harness · 你要写的那一层]
    direction TB
    P[提示词架构<br/>分层与动态注入] --> L[Agent 循环<br/>推理→行动→观察]
    L --> T[工具系统<br/>设计·编排·纠错]
    T --> M[记忆<br/>短期预算 / 长期检索]
    M --> G[权限与沙箱]
    G --> O[评测与可观测]
  end
  H <--> LLM[大模型]
  H --> R[可交付的结果]

这个专栏讲的就是这一层。22 章，从 Agent 循环的实现讲到多 Agent 的失败模式矩阵，每一条方法论都能落到具体代码上，而不是停在"要注意上下文管理"这种正确的废话。

读完你能做到什么

不是"了解"，是能动手做出来的六件事：

1. 给上下文做预算。 把一个 Agent 的上下文按七个组成部分拆开，算清每部分的 token 份额，用对话紧缩与工具结果摘要把长会话压回窗口内（第4章 上下文工程、第11章 短期记忆）。
2. 设计不会被误用的工具。 从命名、参数校验、返回值形状到错误信息，让模型第一次就调对；调错时能自己恢复而不是无限重试（第5章 Tool Design、第7章 工具错误恢复）。
3. 让多个工具安全地并发。 依赖图、速率限制、超时与取消——从顺序执行升级到并发编排，并且知道哪些调用永远不该并发（第6章 工具编排）。
4. 把提示词当代码管理。 分层的 System Prompt、CLAUDE.md 式的用户自定义、为 Prompt Caching 对齐的拼装顺序，以及六个反模式（第8章 提示词架构、第9章 指令优先级）。
5. 建一套权限模型。 工具/动作/资源三层粒度、allow-list 与 deny-list 的取舍、动态权限升级、沙箱隔离——让 Agent 有能力做事，但做不了不该做的事（第14章 权限模型、第15章 沙箱隔离）。
6. 用数据判断它是不是变笨了。 评测集怎么建、轨迹怎么记录、成本与延迟怎么归因到具体环节（第18章 评测、第19章 可观测性、第20章 成本与性能）。

这个专栏的讲法

每个结论都有出处。 六种 Agent 架构模式（Tool-Augmented、ReAct、Plan-and-Execute、Reflexion、Multi-Agent、State Machine）不是罗列名词，而是给出各自的适用边界与失效方式；五种多 Agent 协调拓扑（Coordinator / Pipeline / Swarm / Debate / Hierarchical）配一张失败模式矩阵和一个决策矩阵，告诉你什么时候不该上多 Agent。

拿真实系统当解剖对象。 权限那一章直接拆 Claude Code 的四档权限模式；提示词那一章把分层模型映射回它源码里真实存在的模块。方法论是从跑在生产上的系统里提炼的，不是从论文里抄的。

每章都以「反模式 + 军规」收尾。 提示词架构六大反模式、多 Agent 四个反模式与七条军规——这些是这个专栏里最贵的部分：它们是别人已经付过学费的地方。

适合谁读

• 正在把 Agent 从 demo 推向生产的开发者。 你已经跑通了 function calling，现在卡在可靠性、成本和权限上。
• Agent 框架/平台的设计者。 你要为别人提供工具系统与编排能力，需要一套能站得住的抽象。
• 想看懂 Claude Code 这类产品内部构造的工程师。 这里讲的是它们共同的骨架。

不适合：想找"十个 Prompt 模板直接抄"的读者，以及希望不写代码就能搭出 Agent 的读者。这个专栏假设你会写代码，并且愿意为可靠性付出工程成本。

源码版本

本专栏的案例分析主要建立在两组代码上：

关于 Claude Code 这份快照，要先说清楚它今天已经拿不到了——它来自 @anthropic-ai/claude-code@2.1.89 短暂随包分发的 source map； github.com/anthropics/claude-code 仓库里没有产品源码（那是 issue、文档与插件仓库，没有 src/），现在的 npm 包里也不再有 .map 文件。所以正文里那些 src/query.ts、src/tools/shared/spawnMultiAgent.ts 的路径与行号，对照的是那份不可再获取的快照。

这也是本专栏刻意重方法论、轻具体实现的原因：源码路径和字段名只用来说明设计意图，不是需要记住的 API。LangChain 与 LangGraph 的 1.0 于 2025 年 10 月 17 日同日 GA，正文涉及 StateGraph、interrupt / Command、langgraph.store、langchain_core.* 时一律以 1.x 为准；出现 0.x 时代写法（如 AgentExecutor）只在讲历史演进时，且会明确标注。

目录

开篇

• 前言
• 第1章 Agent 不等于大模型：Harness 的价值

第一部分：Agent 架构基础

• 第2章 Agent 架构模式全景
• 第3章 Agent Loop：心跳与决策循环
• 第4章 上下文工程：比 Prompt Engineering 更重要的事

第二部分：工具工程

• 第5章 Tool Design：给 Agent 造趁手的兵器
• 第6章 工具编排与并发执行
• 第7章 工具结果处理与错误恢复

第三部分：提示词架构

• 第8章 System Prompt 分层设计
• 第9章 指令优先级与冲突消解
• 第10章 Few-shot、CoT 与动态提示策略

第四部分：状态与记忆

• 第11章 短期记忆：上下文窗口管理
• 第12章 长期记忆：持久化与检索
• 第13章 多轮对话与会话状态机

第五部分：安全与权限

• 第14章 Agent 权限模型设计
• 第15章 沙箱、隔离与防御性编程

第六部分：多 Agent 系统

• 第16章 多 Agent 协调模式
• 第17章 Human-in-the-Loop：人机协作设计

第七部分：生产化

• 第18章 评估与测试方法论
• 第19章 可观测性与调试
• 第20章 成本控制与性能优化

第八部分：总结

• 第21章 设计模式与架构决策

版权声明

本专栏内容为 杨艺韬 版权所有，保留一切权利。未经书面许可，不得全文或大段转载、改编、翻译，或用于任何商业用途（含以本专栏内容训练模型、生成衍生课程或商品）。

欢迎分享本专栏的链接。引用少量内容用于评论、教学或研究时，请署名 杨艺韬 并附上原文链接。