# 前言
> 智能体 = 大模型 + Harness。深入剖析 Harness 工程原理、设计、实现。
## 本书简介
2026 年初，业界逐渐形成共识： **决定智能体成败的，往往不是底层大模型的能力，而是包裹在模型外围的 Harness 系统**。
“Harness 工程”(Harness Engineering)这一概念开始进入主流视野。多个生产级智能体项目(Agent)的经验表明：模型不再是差异化因素，围绕模型构建的工程系统才是。
毫不夸张地说， **智能体 = 大模型 + Harness**。大模型提供推理的“大脑”，Harness 提供执行、记忆与安全保障的“身体”。验证循环、重试策略、状态管理、检查点恢复——这些 Harness 层的能力，决定了一个智能体系统能否从原型走向生产。软件工程社区开始系统化地探讨这一工程范式。
Harness 一词意为“驾驭”，原指骑手用以驾驭烈马的缰绳和鞍具系统——如同骑手通过缰绳和鞍具将烈马的奔腾之力化为可控的前行，Agent Harness 将大模型的推理能力转化为可靠、可控、可观测的生产级系统。它包含运行时引擎、工具层、记忆子系统、编排引擎、安全体系和可观测性基础设施等核心子系统。
本书不讲“Agent 是什么”——那是 [《智能体 AI 权威指南》](https://yeasy.gitbook.io/agentic_ai_guide) 的主题；不讲“上下文如何管理”——那是 [《大模型上下文工程权威指南》](https://yeasy.gitbook.io/context_engineering_guide) 的领域；也不讲“AI 安全攻防”——[《大模型安全权威指南》](https://yeasy.gitbook.io/ai_security_guide) 已有深入覆盖。本书只聚焦一个问题： **如何设计和构建驱动智能体的工程基础设施**。
## 三大参考系统
全书以三个具有代表性的生产级开源系统作为核心参考案例，贯穿始终：
[**OpenAI Codex**](https://github.com/openai/codex) 代表 **性能型智能体** 的 Harness 范式。它以 Rust 为核心实现语言，通过系统级编程实现了高性能、内存安全的 Harness 架构。其特色包括：基于 Starlark 的执行策略引擎(execpolicy)、平台原生沙箱（Linux 上使用 Bubblewrap + seccomp，macOS 使用 sandbox-exec，Windows 使用 restricted-token）、skills/core-skills 技能模块体系、OpenTelemetry 原生可观测性（otel 模块），以及内置 MCP 服务端支持等。
[**Claude Code**](https://github.com/anthropics/claude-code) 代表 **任务型智能体** 的 Harness 范式。它围绕终端交互场景构建了一套精密的工程系统，约 50 万行 TypeScript 代码实现了完整的 Harness 架构。其特色包括：基于异步生成器的 Agent 循环引擎(QueryEngine)、24+内置工具的类型安全注册体系、分层权限系统（含 ML 自动审批）、autoDream 记忆整合引擎、40+ 编译时特性门控、以及 Coordinator 多智能体编排模式等。
[**OpenClaw**](https://github.com/openclaw/openclaw) 代表 **自驱型智能体** 的 Harness 范式。它通过 Gateway 控制平面、Heartbeat 心跳机制和多渠道接入层，实现了无需用户持续指令即可自主运行的 Agent 架构。其 Harness 特色包括：基于 WebSocket 的 Gateway 协议、三级权限模型(Free/Ask-first/Approve-once)、MEMORY.md + 每日记忆的双层记忆体系、Lobster 确定性工作流引擎，以及 ClawHub 技能注册中心等。更多内容可参考 [《OpenClaw 从入门到精通》](https://yeasy.gitbook.io/openclaw_guide)。
这三个系统分别展示了 Harness 工程在不同场景和技术路线下的设计取舍：
| 维度 | Codex（性能型） | Claude Code（任务型） | OpenClaw（自驱型） |
| ---- | --------------------------------------- | ------------------------ | ------------------------------- |
| 核心语言 | Rust | TypeScript（\~50万行） | TypeScript |
| 触发方式 | 用户指令驱动 | 用户指令驱动 | Heartbeat 自主唤醒 + 定时任务 |
| 运行模式 | 按需启动、完成即停 | 按需启动、完成即停 | 持续后台运行 |
| 工具生态 | skills + core-skills 模块 + MCP | 24+ 内置工具 + MCP 扩展 | ClawHub 技能注册中心（13000+预构建skills） |
| 记忆模型 | state 模块会话管理 | autoDream 自动整合 | MEMORY.md + 每日日志 |
| 安全模型 | execpolicy 策略引擎(allow/prompt/forbidden) | 风险分级 + ML 自动审批 | 三级权限(Free/Ask/Approve) |
| 沙箱实现 | 平台原生沙箱(Bubblewrap/seccomp/Landlock) | 进程级隔离 | 容器级隔离 |
| 多智能体 | 分层 Agent 消息协议 | Coordinator 模式 + 子 Agent | Lobster 工作流引擎 |
| 可观测性 | OpenTelemetry 原生集成 | 内置结构化日志 | 每日记忆日志 |
## 实战项目：MiniHarness
全书贯穿一个从零构建的实战项目—— **MiniHarness**，一个最小但完整的 Agent Harness 系统，使用 **Python** 实现。
MiniHarness 从第一章介绍、第二章搭建脚手架开始，每章在前一章的基础上逐步添加子系统：运行时引擎 → 工具层 → 记忆子系统 → 输出治理 → 编排引擎 → MCP 集成 → 生产化加固 → 可靠性保障 → 安全层 → 测试验收。全书读完，读者将拥有一个包含所有核心子系统的可运行 Harness。
## 目标读者
本书面向已具备 AI Agent 基本概念、希望深入工程实现的技术读者：
* **Agent 平台工程师**：正在构建或维护 Agent 运行平台，需要掌握运行时引擎、工具层、安全子系统等核心模块的设计方法。
* **AI 应用架构师**：需要评估和选型 Harness 框架，设计可靠的 Agent 系统架构。
* **全栈开发者**：希望理解自己使用的 Agent 框架“引擎盖下”到底发生了什么，从而更好地排查问题和优化性能。
* **技术决策者**：需要理解 Harness 工程的核心权衡，制定 Agent 基础设施的技术战略。
读者应具备 Python 编程经验，并对大语言模型和 AI Agent 有基本了解。如需补充 Agent 基础知识，推荐先阅读 [《智能体 AI 权威指南》](https://yeasy.gitbook.io/agentic_ai_guide)。
## 学习路线图
根据不同的角色和学习目标，以下路线图为你展示了最优的章节阅读顺序：
```mermaid
graph LR
Start[Harness 工程学习入口] --> Ch1[第1章：Harness 导论]
Ch1 --> Role1["平台工程师
第1-3章 → 第4-7章 → 第10-11章"]
Ch1 --> Role2["应用架构师
第1-3章 → 第8-9章 → 第12章"]
Ch1 --> Role3["全栈开发者
第1-2章 → 第4-7章(含 MiniHarness)"]
Ch1 --> Role4["技术决策者
第1-3章 → 第12章 → 第14章"]
Role1 --> End1["掌握核心子系统设计"]
Role2 --> End2["设计生产级 Agent 架构"]
Role3 --> End3["独立构建 Harness 系统"]
Role4 --> End4["制定 Agent 基础设施战略"]
```
| 读者角色 | 学习重点 | 核心成果 |
| --------------- | ---------------------------- | --------------------------------- |
| **Agent 平台工程师** | 第1-3章 → 第4-7章 → 第10-11章 | 掌握运行时、工具层、记忆、安全等核心子系统的设计与实现 |
| **AI 应用架构师** | 第1-3章 → 第8-9章 → 第12章 | 设计可靠的多智能体编排架构与 MCP 集成方案 |
| **全栈开发者** | 第1-2章 → 第4-7章（含 MiniHarness） | 通过实战项目独立构建包含所有核心子系统的 Harness |
| **技术决策者** | 第1-3章 → 第12章 → 第14章 | 理解 Harness 核心权衡，制定 Agent 基础设施技术战略 |
## 阅读方式
### 在线阅读
👉 **推荐**：[GitBook 在线版](https://yeasy.gitbook.io/harness_engineering_guide/)
### 下载离线版本
本书提供 PDF 版本供离线阅读，可前往 [GitHub Releases](https://github.com/yeasy/harness_engineering_guide/releases/latest) 页面下载最新版本。
如需获取默认分支自动更新的预览版，可直接下载 [harness\_engineering\_guide.pdf](https://github.com/yeasy/harness_engineering_guide/releases/download/preview-pdf/harness_engineering_guide.pdf)。该文件会随主线更新覆盖，不代表正式发布版本。
### 本地阅读
先安装 [mdPress](https://github.com/yeasy/mdpress)：
```bash
brew tap yeasy/tap && brew install mdpress
mdpress serve
```
启动后访问 [本地阅读地址](http://localhost:9000) 即可阅读。
## 你将学到什么
阅读本书后，你将具备设计和构建生产级 Agent Harness 系统的完整能力：
* 理解 Harness 工程的设计哲学与四大核心原则（约束优先、可验证性、渐进信任、故障假设）
* 掌握运行时引擎的实现：Agent 循环、消息流、流式处理、错误恢复和漂移纠正
* 设计高效可靠的工具层：工具抽象、执行流水线、动态发现与权限控制
* 构建记忆与上下文子系统：多层记忆架构、上下文组装引擎和自动化记忆整合
* 设计模型集成与输出治理层：模型抽象、结构化输出校验、幻觉检测机制
* 构建任务编排系统：状态机、工作流引擎、多智能体编排与通信协议
* 深入理解 MCP 协议架构，掌握在 Harness 中集成 MCP 的工程模式
* 构建容错与可靠性体系：可观测性、反馈循环、容错模式和幻觉防护
* 设计 Harness 安全体系：权限系统、沙箱隔离、工具调用护栏和路径校验
* 独立完成一个包含所有核心子系统的完整 Harness 实现（MiniHarness 项目）
## 全书结构
全书分为四个部分，共 14 章。
**第一部分：Harness 工程基础** （第 1-3 章）用一节篇幅回顾 Agent 背景后，立即切入 Harness 工程的定义、参考架构全景和四大设计原则，并介绍贯穿全书的实战项目 MiniHarness。
**第二部分：Harness 核心子系统** （第 4-7 章）逐一拆解 Harness 的四大引擎——运行时、工具层、记忆子系统、模型集成与输出治理。每章围绕“如何设计和构建这个子系统”展开，结合 Codex、Claude Code 和 OpenClaw 的真实实现进行剖析，并在 MiniHarness 中动手实现。
**第三部分：系统集成与工程实践** （第 8-11 章）从子系统上升到系统层面：任务编排与工作流引擎、MCP 协议集成、生产级 Harness 构建（提示词工程、插件体系、性能优化、特性门控），以及容错与可靠性工程。
**第四部分：安全、评估与演进** （第 12-14 章）覆盖 Harness 系统的安全体系设计、评估与质量保障方法论，最后展望 Harness 工程的未来演进方向。
## 与系列图书的关系
本书是 AI 工程系列图书之一，与其他图书形成互补：
| 图书 | 聚焦层次 | 核心问题 |
| ------------------------------------------------------------------ | --------- | ---------------------- |
| [零基础学 AI](https://yeasy.gitbook.io/ai_beginner_guide) | 概念层 | AI 是什么、怎么用 |
| [大模型提示词工程指南](https://yeasy.gitbook.io/prompt_engineering_guide) | 交互层 | 如何与大模型高效对话 |
| [大模型上下文工程权威指南](https://yeasy.gitbook.io/context_engineering_guide) | 技术层 | 如何管理 LLM 的上下文 |
| [智能体 AI 权威指南](https://yeasy.gitbook.io/agentic_ai_guide) | 理论层 | Agent 的范式、推理、记忆与协作 |
| [Claude 技术指南](https://yeasy.gitbook.io/claude_guide) | 产品层 | Claude 生态的全面使用 |
| [大模型安全权威指南](https://yeasy.gitbook.io/ai_security_guide) | 安全层 | AI 系统的攻防与合规 |
| [大模型原理与架构](https://yeasy.gitbook.io/llm_internals) | 原理层 | 大语言模型底层逻辑与架构 |
| [OpenClaw 从入门到精通](https://yeasy.gitbook.io/openclaw_guide) | 实践层 | OpenClaw 的部署与使用 |
| **本书：Harness 工程** | **基础设施层** | **如何构建驱动 Agent 的工程系统** |
## 参与贡献
欢迎贡献！您可以通过以下方式参与：
* 🐛 [提交 Issue](https://github.com/yeasy/harness_engineering_guide/issues) — 报告错误或提出建议
* 📝 [提交 PR](https://github.com/yeasy/harness_engineering_guide/pulls) — 改进内容或修复 typo
* ⭐ Star 本项目 — 帮助更多人发现这本书
## 约定
* **代码示例** 使用 Python，实战项目 MiniHarness 为完整的 Python 实现。
* **参考实现** 主要引用 Codex(Rust)、Claude Code(TypeScript)和 OpenClaw（TypeScript/Gateway 架构）的源码，用于说明生产级系统的设计决策。
* **术语处理**：非常见术语首次出现时给出中英文对照和解释，后续直接使用。
* **架构图**：使用 Mermaid 绘制，辅以文字说明，便于理解和复现。
* **交叉引用**：涉及其他图书已深入覆盖的主题时，给出引用链接而非重复讲解。
***
*本书基于 2026 年 4 月的技术现状编写。AI Agent 领域演进迅速，建议读者结合最新官方文档和社区动态来阅读。*
## 许可证
本书采用 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) 许可证。
您可以自由分享和演绎，但需署名、非商业使用、相同方式共享。
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://yeasy.gitbook.io/harness_engineering_guide/readme.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.