前言¶

原文地址：https://yeasy.gitbook.io/harness_engineering_guide

随着智能体工程进入生产场景，越来越多生产案例显示： 模型能力只是必要条件，外围 Harness 系统决定了能力能否稳定转化为结果。

“Harness 工程”(Harness Engineering)这一概念开始进入主流视野。多个生产级智能体项目(Agent)的经验表明：当基础模型接近同一能力带时，差异往往转移到围绕模型构建的工程系统。

本书用一个工程化简写来概括： 智能体 = 大模型 + Harness。大模型提供推理的“大脑”，Harness 提供执行、记忆与安全保障的“身体”。验证循环、重试策略、状态管理、检查点恢复——这些 Harness 层的能力，决定了一个智能体系统能否从原型走向生产。软件工程社区开始系统化地探讨这一工程范式。

Harness 一词意为“驾驭”，原指骑手用以驾驭烈马的缰绳和鞍具系统——如同骑手通过缰绳和鞍具将烈马的奔腾之力化为可控的前行，Agent Harness 将大模型的推理能力转化为可靠、可控、可观测的生产级系统。它包含运行时引擎、工具层、记忆子系统、编排引擎、安全体系和可观测性基础设施等核心子系统。

本书不讲“Agent 是什么”——那是 《智能体 AI 权威指南》 的主题；不讲“上下文如何管理”——那是 《大模型上下文工程权威指南》 的领域；也不讲“AI 安全攻防”——《大模型安全权威指南》 已有深入覆盖。本书只聚焦一个问题： 如何设计和构建驱动智能体的工程基础设施。

1. 三大参考系统¶

全书以三个具有代表性的生产级公开参考系统作为核心参考案例，贯穿始终。本书按主要优化目标划分：性能型强调执行效率与沙箱，任务型强调交互工作流，自驱型强调后台唤醒与长期状态。

参考系统变化较快，本书正文只保留稳定架构特征；具体产品与特性名可见 附录 C：推荐资源。

OpenAI Codex 代表 性能型智能体 的 Harness 范式。它以 Rust 为核心实现语言，通过系统级编程实现了高性能、内存安全的 Harness 架构。其特色包括：基于 Starlark 的执行策略引擎(execpolicy)、平台原生沙箱（Linux 上优先用 PATH 上找到的第一个 Bubblewrap，找不到时回退到 Codex 自带的 codex-resources/bwrap；Bubblewrap 生效期间再叠加 PR_SET_NO_NEW_PRIVS 与 seccomp 网络过滤，Landlock 则退为需显式打开 features.use_legacy_landlock 的遗留路径。macOS 使用 seatbelt/sandbox-exec，Windows 原生支持 elevated / unelevated sandbox；WSL2 走与 Linux 相同的 Bubblewrap 路径）、skills/core-skills 技能模块体系、OpenTelemetry 原生可观测性（otel 模块），以及内置 MCP 服务端支持等。

Claude Code 代表 任务型智能体 的 Harness 范式。它围绕终端交互场景构建工程系统，核心特色包括：可直接读写代码库、运行命令、接入 MCP，提供 default、acceptEdits、plan、auto、dontAsk、bypassPermissions 等权限模式，并通过 skills、hooks、subagents、memory/compact 等公开机制扩展工作流。

OpenClaw 代表 自驱型智能体 的 Harness 范式。它通过 Gateway 控制平面、heartbeat/cron 触发机制和多渠道接入层，支持后台自动化运行。其 Harness 特色包括：Gateway 协议、基于配置的工具权限与执行审批、MEMORY.md + memory/YYYY-MM-DD.md 的明文记忆文件、Lobster 确定性工作流，以及作为公开 skills/plugins 注册中心的 ClawHub。更多内容可参考 《OpenClaw 从入门到精通》。

这三个系统分别展示了 Harness 工程在不同场景和技术路线下的设计取舍：

2. 实战项目：MiniHarness¶

全书贯穿一个从零构建的实战项目—— MiniHarness，一个最小但完整的 Agent Harness 系统，使用 Python 实现。

MiniHarness 从第一章介绍、第二章搭建脚手架开始，每章在前一章的基础上逐步添加子系统：运行时引擎 → 工具层 → 记忆子系统 → 输出治理 → 编排引擎 → MCP 集成 → 生产化加固 → 可靠性保障 → 安全层 → 测试验收。全书读完，读者将拥有一个包含所有核心子系统的可运行 Harness。

3. 目标读者¶

本书面向已具备 AI Agent 基本概念、希望深入工程实现的技术读者：

• Agent 平台工程师：正在构建或维护 Agent 运行平台，需要掌握运行时引擎、工具层、安全子系统等核心模块的设计方法。
• AI 应用架构师：需要评估和选型 Harness 框架，设计可靠的 Agent 系统架构。
• 全栈开发者：希望理解自己使用的 Agent 框架“引擎盖下”到底发生了什么，从而更好地排查问题和优化性能。
• 技术决策者：需要理解 Harness 工程的核心权衡，制定 Agent 基础设施的技术战略。

读者应具备 Python 编程经验，并对大语言模型和 AI Agent 有基本了解。如需补充 Agent 基础知识，推荐先阅读 《智能体 AI 权威指南》。

4. 学习路线图¶

graph LR
    Start[Harness 工程学习入口] --> Ch1[第1章：Harness 导论]

    Ch1 --> Role1["<b>平台工程师</b><br/>第1-3章 → 第4-7章 → 第10-11章"]
    Ch1 --> Role2["<b>应用架构师</b><br/>第1-3章 → 第8-9章 → 第12章"]
    Ch1 --> Role3["<b>全栈开发者</b><br/>第1-3章 → 第4-7章(含 MiniHarness)"]
    Ch1 --> Role4["<b>技术决策者</b><br/>第1-3章 → 第12章 → 第14章"]

    Role1 --> End1["掌握核心子系统设计"]
    Role2 --> End2["设计生产级 Agent 架构"]
    Role3 --> End3["独立构建 Harness 系统"]
    Role4 --> End4["制定 Agent 基础设施战略"]

5. 你将学到什么¶

阅读本书后，你将具备设计和构建生产级 Agent Harness 系统的完整能力：

• 理解 Harness 工程的设计哲学与五大核心原则（约束优先、可验证性、渐进信任、故障假设、智能体工学）
• 掌握运行时引擎的实现：智能体循环、消息流、流式处理、错误恢复和漂移纠正
• 设计高效可靠的工具层：工具抽象、执行流水线、动态发现与权限控制
• 构建记忆与上下文子系统：多层记忆架构、上下文组装引擎和自动化记忆整合
• 设计模型集成与输出治理层：模型抽象、结构化输出校验、幻觉检测机制
• 构建任务编排系统：状态机、工作流引擎、多智能体编排与通信协议
• 深入理解 MCP 协议架构，掌握在 Harness 中集成 MCP 的工程模式
• 构建容错与可靠性体系：可观测性、反馈循环、容错模式和幻觉防护
• 设计 Harness 安全体系：权限系统、沙箱隔离、工具调用护栏和路径校验
• 独立完成一个包含所有核心子系统的完整 Harness 实现（MiniHarness 项目）

6. 全书结构¶

全书分为四个部分，共 14 章。

• 第一部分：Harness 工程基础 （第 1-3 章）用一节篇幅回顾 Agent 背景后，立即切入 Harness 工程的定义、参考架构全景和五大设计原则，并介绍贯穿全书的实战项目 MiniHarness。
• 第二部分：Harness 核心子系统 （第 4-7 章）逐一拆解 Harness 的四大引擎——运行时、工具层、记忆子系统、模型集成与输出治理。每章围绕“如何设计和构建这个子系统”展开，结合 Codex、Claude Code 和 OpenClaw 的真实实现进行剖析，并在 MiniHarness 中动手实现。
• 第三部分：系统集成与工程实践 （第 8-11 章）从子系统上升到系统层面：任务编排与工作流引擎、MCP 协议集成、生产级 Harness 构建（提示词工程、插件体系、性能优化、特性门控），以及容错与可靠性工程。
• 第四部分：安全、评估与演进 （第 12-14 章）覆盖 Harness 系统的安全体系设计、评估与质量保障方法论，最后展望 Harness 工程的未来演进方向。

7. 与系列图书的关系¶

本书是 AI 工程系列图书之一，与其他图书形成互补：