Harness Engineering 完全指南：AI Agent 时代的驾驭工程

视频来源：最近爆火的 Harness Engineering 到底是啥？一期讲透！ — code秘密花园
核心观点：AI 模型已经能写出 100 万行代码。真正的挑战不再是让它写得更好，而是怎么驾驭它稳定、可靠、不失控地工作。

一、什么是 Harness Engineering？

Harness Engineering（驾驭工程） 是围绕 AI 智能体设计和构建 约束机制、反馈回路、工作流控制和持续改进循环 的系统工程实践。

核心哲学：人类掌舵，智能体执行
本质：不优化模型本身，而是优化模型运行的环境
公式：Agent = Model + Harness

如果把模型比作 CPU，Harness 就是 操作系统。CPU 再强，如果 OS 拉胯，体验也会很差。

起源

2026 年 2 月 5 日：HashiCorp 联合创始人 Mitchell Hashimoto 在个人博客中首次提出该术语
6 天后：OpenAI 发布《Harness Engineering: leveraging Codex in an agent-first world》详细实验报告
随后：Martin Fowler 撰文分析，Anthropic 发布工程实践指南，迅速成为开发者社区热词

“Harness Engineering is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent will not make that mistake again in the future.”
—— Mitchell Hashimoto

核心理念：四个动词

动作	含义	类比
Constrain（约束）	设定边界，防止 Agent 越界	高速公路的护栏
Inform（告知）	提供上下文，让 Agent 理解任务	导航仪的地图
Verify（验证）	自动检查输出质量	质检员的检查表
Correct（纠正）	基于验证结果自动迭代	自动驾驶的路径修正

二、AI 工程范式的三次跃迁

Harness Engineering 不是凭空出现的，它是 AI 工程领域自然演进的第三个阶段：

阶段	核心概念	优化对象	解决问题	时间	交互模式
1	Prompt Engineering	输入措辞	单次对话质量	2022 ~ 2024	一问一答
2	Context Engineering	信息输入	知识边界与幻觉	2025	信息注入 → 生成
3	Harness Engineering	运行环境	Agent 可靠性与可持续性	2026 ~	人类掌舵，Agent 执行

生动类比

Prompt Engineering = 对马喊话的技巧

Context Engineering = 给马看的地图

Harness Engineering = 给马造一条高速公路，配上护栏、限速牌和加油站

为什么前两者不够用了？

对比维度	Prompt Engineering	Context Engineering	Harness Engineering
关注点	“说什么”	“给什么上下文”	“在什么条件下运行”
适用场景	单次问答	RAG / 知识注入	长链路自主任务
模型依赖	高	中	低
可扩展性	差	一般	强

关键结论：在长链路、可执行、低容错的真实商业场景中，瓶颈不在模型智能水平，而在 Harness 的基础设施质量。

三、Agent 常见失败模式

在讨论解决方案之前，先看看 Anthropic 工程师总结的 Agent 典型”翻车”姿势：

1. 试图一步到位

Agent 倾向于在一个会话中完成所有任务，导致上下文耗尽，留下半成品代码。

2. 过早宣布胜利

看到部分完成就认为任务结束，跳过了端到端验证。

3. 特性危险

Agent 擅长模式复制——包括坏模式。导致架构漂移和技术债务快速积累。

4. 自信过满

Agent 对幻觉和正确输出的置信度一样高，无法表达”我不确定”。

这些问题的共同点：不是模型不够聪明，而是运行环境缺乏约束和反馈。这正是 Harness Engineering 要解决的。

四、Harness 的四大护栏

这是 Harness Engineering 的核心组成：

护栏一：上下文工程 —— 新员工手册

目标：给 Agent 提供恰到好处的知识，既不多也不少。

核心实践：

建立 AGENTS.md 文件：位于仓库根目录，作为 Agent 的入口指南
渐进式披露：AGENTS.md 只写约 100 行作为目录，指向详细子文档
文档必须是活的反馈循环：每次 Agent 犯错后，增加一条规则，形成”免疫系统”
仓库即事实源：知识必须在 Git 仓库里，Slack/Wiki 对 Agent 来说等于不存在

# AGENTS.md 示例结构（~100行）
## 项目概述
本项目是一个 TypeScript 的 Web 服务...

## 快速命令
- 构建: `npm run build`
- 测试: `npm test`
- Lint: `npm run lint`

## 架构
详见 [docs/architecture.md](./docs/architecture.md)

## 代码规范
详见 [docs/code-style.md](./docs/code-style.md)

## 已知陷阱
- 不要直接导入 runtime 模块，必须通过 Provider
- 日期处理统一使用 dayjs，不要用 moment

护栏二：架构约束 —— 缰绳

目标：通过机械化规则约束 Agent 行为，而不是靠”求它别犯错”。

核心实践：

分层依赖模型：Types → Config → Repo → Service → Runtime → UI，严格单向依赖
自定义 Linter 强制执行：CI 阻断违规合并
Linter 错误消息 = 修复指令：不仅告诉 Agent 哪里错了，还告诉它怎么改
选择”无聊”的技术：使用稳定 API 的可组合库，且在模型训练数据中有充分表示

1
2
3

❌ Error: Module 'runtime' cannot import from 'ui'
   → Fix: Move this logic to a shared provider in 'service' layer
   → See: docs/architecture.md#layer-rules

护栏三：反馈循环 —— Agent 审 Agent

目标：让 Agent 具备”自知之明”，能自我发现并修复问题。

核心实践：

钩子运行预定义测试套件：每次生成后自动验证
失败时带着错误信息回传：Agent 获得修复线索
如果测试通过但代码有 Bug：Harness 判定测试无效，强迫重写测试
GAN 式三智能体架构：Planner → Generator ⇄ Evaluator，分离生成与评估

四步闭环验证（LangChain 实践）：

1	规划与发现 → 构建 → 验证（对照原始需求） → 修复

护栏四：熵管理 —— 垃圾回收

目标：对抗 AI 代码的”熵增”，持续小额偿还技术债。

核心实践：

Golden Principles（黄金原则）：将有主见的编码规则编码进仓库
后台清理 Agent：定期扫描偏离规则的代码，自动开出重构 PR
Doc-gardening Agent（文档园丁）：自动扫描并修复文档与代码的不一致
清理吞吐量 ≥ 生成吞吐量：否则技术债只会越积越多

五、六层架构详解

在四大护栏的基础上，业界进一步提炼出了更精细的六层架构体系：

层级	名称	解决什么问题	关键设计
L1	信息边界层	Agent 该知道什么、不该知道什么	角色定义、信息裁剪、任务状态结构化
L2	工具系统层	Agent 怎么跟外部世界交互	工具选拔、调用时机、结果提炼与反馈
L3	执行编排层	多步骤任务怎么串起来	理解→判断→分析→生成→检查的完整轨道
L4	记忆与状态层	长任务中间结果怎么管	当前任务状态、中间产物和长期记忆独立管理
L5	评估与观测层	Agent 怎么知道自己做对了	独立于生成过程的验证机制
L6	约束、校验与恢复层	出错了怎么办	规则拦截错误、失败时重试或回滚

解决核心矛盾：确定性 vs 不确定性

传统软件是确定性的，AI 系统是概率性的。Harness 的解法是：

不承诺消除不确定性，而是通过全程可追溯性建立信任。只有可以被看见的，才可以被信任。

六、关键技术洞察

1. 40% 上下文阈值

Dex Horthy 发现，168K token 的上下文窗口，用到约 40% 时，Agent 质量开始明显下降：

区间	表现
0-40%（Smart Zone）	推理聚焦、工具调用准确
>40%（Dumb Zone）	幻觉增多、兜圈子、格式混乱

最佳实践：监控上下文利用率，超过 40% 触发压缩或任务交接。

2. Context Resets（上下文重置）

当上下文接近饱和时，不硬撑，而是：

结构化提取当前任务状态
启动一个全新的”干净” Agent
将交接文档交给新 Agent

这类似于程序解决内存泄漏的方法：直接重启进程，从检查点恢复。

3. Blueprint 模式

Stripe 首创的确定性与概率性交替模式：

触发 → 预热 Devbox → Blueprint 编排 →
  [确定性节点] Lint 检查 →
  [Agent 节点] 功能实现 →
  [确定性节点] 推送代码 →
  [Agent 节点] 修 CI 错误 →
  [确定性节点] 开 PR

核心思想：模型不运行系统，系统运行模型。确定性门禁”夹住”概率性的 LLM 工作。

4. 推理计算的”三明治”策略

1	规划（高推理）→ 实现（中推理）→ 验证（高推理）

这种方式比全程高推理效果更好，且成本更低。

七、一线团队实战案例

案例一：OpenAI Codex —— 3 人 5 个月 100 万行代码

指标	数据
团队规模	3-7 人
开发周期	5 个月
代码产出	~100 万行
手写代码	0 行
人均日 PR	3.5 个

五大方法论：

地图式文档 (AGENTS.md)：只写约 100 行作为目录，渐进式披露详细内容
机械化约束：架构约束靠自定义 Linter 强制执行，报错信息自带修复方法
可观测性接入：接入 Chrome DevTools Protocol，Agent 能自己截图、测性能
熵管理：后台自动扫描并清理低质量代码，清理速度跟得上生成速度
仓库即事实源：知识必须在 Git 仓库里

案例二：Anthropic —— GAN 式三智能体架构

C 编译器项目（Nicholas Carlini）：

16 个并行 Claude Opus 实例
两周时间，10 万行 Rust 代码
GCC 测试通过率 99%

关键经验：

日志写文件不打控制台（防上下文污染）
测试子采样：每个 Agent 跑确定的 1-10%，集体覆盖全量
Agent 角色专业化（去重、优化、文档等专职 Agent）

三智能体架构：

Planner (大胆规划)
    ↓
Generator (分 Sprint 执行)
    ⇅
Evaluator (Playwright 实测打分)

分离生成与评估，解决 Agent 自信过满的问题。

案例三：Stripe Minions —— 每周 1300+ 无人值守 PR

架构特点：混合状态机（Blueprint 模式）

确定性节点：Lint、Push 代码（该确定的地方确定）
Agent 节点：实现功能、修 CI 错误（该灵活的地方灵活）

核心组件：

组件	功能
Devbox	预装环境的 EC2 实例，启动仅需 10 秒
Toolshed MCP	集中管理近 500 个工具
反馈回路	Pre-push hook 秒级修 lint，推送后最多跑 2 轮 CI（300 万+测试）

案例四：LangChain —— 排名从 30 跃升至 5

操作：仅优化 Agent 运行的外部环境（文档结构、验证回路、追踪系统），底层模型参数完全未改动。

结果：Terminal Bench 2.0 得分从 52.8% 飙升至 66.5%，排名从全球第 30 位跃升至第 5 位。

启示：一个格式的改变，等于十个模型升级。

案例五：Can Boluk —— 编辑格式改变一切

安全研究员 Can Boluk 将 Agent 的代码编辑格式从传统 patch 改为 Hashline 格式：

1 2	42:a3f\| let x = compute(); 43:b7e\| console.log(x);

结果：Grok Code Fast 1 的基准得分从 6.7% 跃升至 68.3%。

结论：决定 Agent 效果的最大变量往往不是模型本身，而是其所处的环境。

案例六：Mitchell Hashimoto —— 单 Agent 六步进阶

Hashimoto 坚持单 Agent 模式，不跑多 Agent，保持深度参与：

步骤	实践
1	放弃聊天模式，直接在干活环境使用
2	复现自己的工作（每件事做两次，手动+Agent）
3	下班前启动 Agent 跑长任务
4	外包确定性任务，关掉通知
5	工程化 Harness——每犯一次错，就加规则永不再犯
6	始终有 Agent 在运行

AGENTS.md 的精髓：每一行对应一个历史失败案例，形成持续积累的防错系统。

八、工具生态

安全执行沙箱

工具	特点	启动时间
E2B	开源，支持多语言，轻量级	<200ms
Daytona	企业级，支持状态持久化	<90ms
AgentSandbox	专注 Python/Bash，API 友好	可变
Microsandbox	开源，VM 级隔离	<1s

浏览器自动化

工具	特点
BrowserUse	开源平台，78,000+ GitHub stars
Nanobrowser	Chrome 扩展，支持多 Agent 工作流
Playwright	微软开源，Anthropic 推荐的端到端测试方案
Puppeteer MCP	通过 MCP 协议接入浏览器自动化

可观测性

工具	功能
Langfuse	开源，追踪 Agent 推理链
AgentOps	专注 Agent 性能监控
Helicone	LLM 调用追踪与成本分析
Galileo	企业级 Agent 可观测性

编排框架

框架	特点	适用场景
LangChain/LangGraph	生态完善，支持复杂状态流	企业级复杂应用
CrewAI	角色扮演，多 Agent 协作	团队协作场景
AutoGen	微软出品，对话驱动	研究/实验场景
OpenAI Agents SDK	OpenAI 原生，深度集成	OpenAI 生态应用

Harness 与传统框架的层级关系

┌──────────────────────────────────┐
│    Harness Layer                 │  ← 约束、反馈、熵管理
│    (Harness Engineering)         │
├──────────────────────────────────┤
│    Agent Frameworks              │  ← 智能体定义、路由
│    (LangGraph / CrewAI)          │
├──────────────────────────────────┤
│    SDK / API                     │  ← 模型调用
│    (OpenAI SDK / Anthropic SDK)  │
├──────────────────────────────────┤
│    Foundation Model              │  ← GPT / Claude / Gemini
│    (LLM)                         │
└──────────────────────────────────┘

注意：Harness 不是 Agent 框架的替代品，而是更上层的控制系统。模型正在吸收框架 80% 的功能，但持久化、可观测性、错误恢复等剩余 20% 是驾驭层的核心价值。

九、GitHub 高星开源实践项目

理论之外，以下是 GitHub 上 Stars 数较多、真正落地了 Harness Engineering 理念的开源项目：

1. DeerFlow 2.0（字节跳动）— ⭐ 60.4K Stars

GitHub：bytedance/deer-flow

字节跳动将第一代 Deep Research 框架从零重写，升级为 Super Agent Harness。它不只是一个框架，而是一个配备了”电池”的完整运行时。

Harness 实践亮点：

实践维度	具体做法
子 Agent 编排	Lead Agent 动态生成子 Agent，各自独立上下文和工具，并行执行后汇总
技能系统	Markdown 定义的结构化技能模块，渐进式加载保持上下文精简
沙箱隔离	Docker 容器级安全隔离（`AioSandboxProvider`），默认禁用主机 Bash
上下文工程	自动摘要已完成子任务，压缩不相关内容，防止上下文窗口溢出
长期记忆	跨会话持久化存储用户偏好、写作风格和知识
可观测性	原生集成 LangSmith / Langfuse，追踪所有 LLM 调用和工具执行

技术栈：Python (68.3%) + TypeScript (19.5%)，基于 LangChain / LangGraph 构建。

2. Claw Code（ClawCode）— ⭐ 48K+ Stars

GitHub：instructkr/claw-code

Claude Code 架构的 净室重写（Clean-Room Rewrite），用 Python + Rust 混合架构重新实现了 Anthropic 闭源的 51 万行 TypeScript 代码。发布后数小时内即达 30K+ Stars，成为 GitHub 历史上增长最快的项目之一。

Harness 实践亮点：

实践维度	具体做法
工具系统	19 个内置工具，每个工具独立权限控制和沙箱机制
查询引擎	管理所有 LLM 调用、响应流、缓存策略和多步编排
多 Agent Swarm	子 Agent 并行执行，隔离上下文 + 共享内存
MCP 集成	6 种传输类型（Stdio, SSE, HTTP, WebSocket, SDK, ClaudeAiProxy）
三级权限	针对每个工具的策略引擎、拒绝列表和交互式审批
Rust 性能核心	72.9% Rust，零依赖 JSON 解析器、OAuth PKCE 流程

技术栈：Rust (72.9%) + Python (27.1%)，6 个 Rust crate + 16 个运行时模块。

3. OpenHarness（香港大学 HKUDS）— ⭐ 8.7K Stars

GitHub：HKUDS/OpenHarness

最正统的 Harness Engineering 开源实现 —— 用 1.1 万行 Python 复刻了 Claude Code 51 万行代码的核心能力，将 Agent 从”黑盒”变成了”白盒”，是学习 Harness 架构的最佳项目。

10 大子系统：

子系统	功能
Engine	智能体循环核心：查询 → 流式传输 → 工具调用 → 循环
Tools	43 个工具（文件 I/O、Shell、搜索、Web、MCP）
Skills	按需加载的 `.md` 知识文件（commit、review、debug、plan、test）
Plugins	兼容 Claude Code 插件生态，复用 12 个官方插件
Permissions	三级权限：Default（写前确认）→ Auto（全放行）→ Plan（禁写入）
Hooks	PreToolUse / PostToolUse 生命周期钩子
Commands	54 个斜杠命令（/help、/commit、/plan、/resume 等）
MCP	Model Context Protocol 客户端
Memory	MEMORY.md 跨会话持久记忆 + 上下文自动压缩
Coordinator	子 Agent 派发、团队注册表、后台任务管理

附带 Ohmo 个人 Agent：支持飞书 / Slack / Telegram / Discord 交互，能自动分支、写代码、跑测试、开 PR。

技术栈：Python (95.1%)，兼容 Claude / OpenAI / Kimi / GLM 等多家模型。

4. awesome-agent-harness（资源索引）— ⭐ 180 Stars

GitHub：Picrew/awesome-agent-harness

收录 145 个 Harness Engineering 相关项目和工具的精选列表，分为 9 大类：

精选博客 / 2. 架构与编排 / 3. 上下文与状态工程 / 4. 执行沙箱 / 5. 协议与工具接口 / 6. 评估与基准 / 7. 可观测性 / 8. 安全与治理 / 9. 参考实现

适合作为入门导航和工具选型参考。

项目对比速查

项目	Stars	代码量	适合场景
DeerFlow 2.0	60.4K	大型项目	生产级长周期多 Agent 编排
Claw Code	48K+	51万行重写	研究 Claude Code 架构，Rust 高性能 Harness
OpenHarness	8.7K	1.1 万行	最佳学习项目 — 代码精简、架构清晰
awesome-agent-harness	180	索引	资源导航、工具选型

十、从零搭建 Harness 的步骤

P0：第一步

行动	说明
创建 `AGENTS.md`	只当目录用（~100 行），详细规则放子文档，Agent 每次启动自动加载
构建自定义 Linter	错误消息里直接告诉 Agent 怎么改，将架构约束机械化
团队知识进仓库	Git 仓库是唯一事实源，Slack/Wiki 对 Agent 来说等于不存在

P1：第二步

行动	说明
分层管理上下文	渐进式披露，避免上下文窗口爆炸
建立进度文件	用 JSON 格式追踪状态，防止 Agent 乱改
给 Agent 端到端验证能力	接入 Playwright 等浏览器自动化让它像用户一样自测
控制上下文利用率	尽量不超过 40%，增量执行或触发 Context Resets

P2：第三步（可选）

行动	说明
Agent 专业化分工	去重、优化、文档等专门角色
定期垃圾回收	自动化清理冗余代码和文档
可观测性集成	接入 Langfuse 等追踪系统
Trace 驱动迭代	基于数据而非感觉改进 Harness

十一、总结

Harness Engineering 代表了 AI 工程领域的第三次范式跃迁。它不是一个框架、不是一个工具，而是一种工程思维的转变：

为了获得更高的 AI 自主性，运行时必须受到更严格的约束。

就像高速公路——正是因为有了护栏、限速牌和车道线，车才能安全地开到 120 码。

Harness Engineering 最终将不再是一个专门的术语，而是成为像”版本控制”一样标准化的工程基础设施。能够掌握这一范式的团队，将在生产力上获得数量级的优势。

一、什么是 Harness Engineering？

起源

核心理念：四个动词

二、AI 工程范式的三次跃迁

生动类比

为什么前两者不够用了？

三、Agent 常见失败模式

1. 试图一步到位

2. 过早宣布胜利

3. 特性危险

4. 自信过满

四、Harness 的四大护栏

护栏一：上下文工程 —— 新员工手册

护栏二：架构约束 —— 缰绳

护栏三：反馈循环 —— Agent 审 Agent

护栏四：熵管理 —— 垃圾回收

五、六层架构详解

解决核心矛盾：确定性 vs 不确定性

六、关键技术洞察

1. 40% 上下文阈值

2. Context Resets（上下文重置）

3. Blueprint 模式

4. 推理计算的”三明治”策略

七、一线团队实战案例

案例一：OpenAI Codex —— 3 人 5 个月 100 万行代码

案例二：Anthropic —— GAN 式三智能体架构

案例三：Stripe Minions —— 每周 1300+ 无人值守 PR

案例四：LangChain —— 排名从 30 跃升至 5

案例五：Can Boluk —— 编辑格式改变一切

案例六：Mitchell Hashimoto —— 单 Agent 六步进阶

八、工具生态

安全执行沙箱

浏览器自动化

可观测性

编排框架

Harness 与传统框架的层级关系

九、GitHub 高星开源实践项目

1. DeerFlow 2.0（字节跳动）— ⭐ 60.4K Stars

2. Claw Code（ClawCode）— ⭐ 48K+ Stars

3. OpenHarness（香港大学 HKUDS）— ⭐ 8.7K Stars

4. awesome-agent-harness（资源索引）— ⭐ 180 Stars

项目对比速查

十、从零搭建 Harness 的步骤

P0：第一步

P1：第二步

P2：第三步（可选）

十一、总结

参考资源