前言

写作动机

2026 年，AI Agent 正在从技术圈的玩具变成企业的生产力工具。Claude Code、Cursor、Devin、各种 AutoGPT 变体——每周都有新的 Agent 产品发布。但在这股热潮背后，一个令人不安的事实是：绝大多数 Agent 项目在 demo 阶段惊艳全场，到生产环境就一地鸡毛。

不是模型不够强。GPT-4、Claude Opus、Gemini Ultra 的能力已经远超两年前的想象。问题出在模型之外——出在"驾驭"模型的那一层工程上。

我把这层工程叫做 Harness Engineering。

什么是 Harness Engineering

如果把大模型比作一匹烈马，那 Harness 就是缰绳、马鞍和马镫的总和。它不是模型本身，而是让模型变成可用 Agent 的一切工程实践：

• 工具设计：给 Agent 什么能力？接口粒度怎么定？
• 提示词架构：system prompt 怎么分层？指令冲突怎么消解？
• 上下文管理：有限的上下文窗口如何高效利用？
• 状态与记忆：短期记忆和长期记忆如何协同？
• 权限与安全：Agent 能做什么、不能做什么？如何隔离？
• 编排与协调：多 Agent 如何分工？人机如何协作？
• 可观测性：Agent 做了什么决策？为什么？怎么调试？
• 评估与测试：Agent 的行为怎么测试？怎么度量好坏？

这些问题，没有一个是模型能自己解决的。它们需要工程方法论。

为什么现在写这本书

过去一年，我深度参与了多个 Agent 系统的设计与实现。从剖析 Claude Code 的 51 万行源码，到拆解 LangChain、LangGraph 的架构设计，再到构建自己的 Agent 平台，我积累了大量第一手的工程经验和教训。

更重要的是，我发现这个领域的知识极度碎片化。最佳实践散落在 Twitter 帖子、GitHub README、公司内部文档里，没有人做过系统整理。市面上的书要么是具体框架的教程（半年就过时），要么是笼统的 AI 概念科普（看完还是不会做）。

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

本书的案例来源

本书是方法论书籍，不绑定特定框架。但方法论必须有实例支撑，本书的主要案例来源：

项目	版本	获取方式	用于章节
Claude Code	v2.x (2026.3)	npm install -g @anthropic-ai/claude-code	全书（工具、权限、记忆、编排）
LangGraph	v0.4.x	pip install langgraph	Ch2,13,17（状态机、中断）
LangChain	v0.3.x	pip install langchain	Ch2,5（工具抽象、Agent）
vLLM	v0.8.5	git clone --branch v0.8.5 https://github.com/vllm-project/vllm.git	对比案例

Claude Code 是本书引用最多的案例——它是目前最复杂的生产级 Agent Harness（51 万行 TypeScript），其工具系统、权限模型、记忆机制、多 Agent 协调的设计都极具参考价值。本书中引用的 Claude Code 行为和系统提示词均来自作者在实际使用中的第一手观察。

这本书怎么读

本书分为八个部分，从基础架构到生产化，层层递进：

1. 开篇（第 0-1 章）：建立 Harness Engineering 的认知框架
2. 架构基础（第 2-4 章）：Agent 的核心架构模式和上下文工程
3. 工具工程（第 5-7 章）：如何设计、编排和管理 Agent 的工具
4. 提示词架构（第 8-10 章）：超越 Prompt Engineering 的系统化方法
5. 状态与记忆（第 11-13 章）：Agent 的记忆系统设计
6. 安全与权限（第 14-15 章）：让 Agent 可控的关键工程
7. 多 Agent 系统（第 16-17 章）：协调与人机协作
8. 生产化（第 18-21 章）：从评估、观测到成本优化的完整实践

每一章都遵循同一个模式：先讲问题域和设计意图，再看真实系统的实现方案，最后提炼可迁移的方法论。 我会大量引用 Claude Code、LangGraph、OpenClaw 等真实项目的代码作为案例，但本书的核心价值不在于教你用哪个框架，而在于让你理解框架背后的工程决策。

本书读者

• AI 应用开发者：在构建或准备构建 Agent 系统的工程师
• 技术负责人：需要评估 Agent 方案可行性、制定技术策略的决策者
• 框架开发者：正在设计或改进 Agent 框架的架构师
• 所有被 Agent 的不可控性折磨过的人

一个约定

本书重方法论、轻具体框架。框架会过时，方法论不会。当我引用某个框架的实现时，关注的是"它为什么这样设计"，而不是"这个 API 怎么调用"。如果你带着这个心态阅读，这本书的保质期会比任何框架教程都长。