文章目录
- Harness理解学习
-
- [LAYER1 上下文管理](#LAYER1 上下文管理)
- [LAYER2 工具系统](#LAYER2 工具系统)
- [LAYER3 执行编排](#LAYER3 执行编排)
- [LAYER4 状态与记忆](#LAYER4 状态与记忆)
- [LAYER5 评估与观测](#LAYER5 评估与观测)
- [LAYER6 约束与恢复](#LAYER6 约束与恢复)
- Harness实战
-
- [1. 什么是Harness Engineering?](#1. 什么是Harness Engineering?)
- [2. 为什么需要 Harness Engineering?](#2. 为什么需要 Harness Engineering?)
- [3. AI工程范式的三次跃迁](#3. AI工程范式的三次跃迁)
- [4. Agent 常见失败模式](#4. Agent 常见失败模式)
- [5. Harness 核心组件](#5. Harness 核心组件)
-
- [上下文工程（Context Engineering）------新员工手册](#上下文工程（Context Engineering）——新员工手册)
- 核心原则
- 实践建议------三层上下文体系
- [Agent 专业化（Agent Specialization）](#Agent 专业化（Agent Specialization）)
- 实践中的角色分工
- [持久化记忆（Persistent Memory）](#持久化记忆（Persistent Memory）)
- [结构化执行（Structured Execution）](#结构化执行（Structured Execution）)
- [架构约束（Architecture Constraints）------ 缰绳](#架构约束（Architecture Constraints）—— 缰绳)
- [反馈循环（Feedback Loop）------ 智能体审智能体](#反馈循环（Feedback Loop）—— 智能体审智能体)
- [熵管理（Entropy Management）------ 垃圾回收](#熵管理（Entropy Management）—— 垃圾回收)
- [6. Harness 业界最佳实战案例](#6. Harness 业界最佳实战案例)
- [7. Harness行业应用落地准则](#7. Harness行业应用落地准则)
- [8. Harness 项目开发应用实战1](#8. Harness 项目开发应用实战1)
- [9. Harness 项目开发应用实战2](#9. Harness 项目开发应用实战2)
Harness理解学习
注：其实很多视频讲解主要框架也是来源于橙皮书（可见文末参考链接），主要这个词语火起来还是来源于OpenAI的一篇文章（也是目前大家都在做的事，如何让Agent更加正确地完成任务），也可见文末参考文章。
Harness不是一个具体的软件框架或代码库，而是一种设计和架构AI Agent的工程范式（Engineering Paradigm）。
它的核心理念是：将大语言模型（LLM）与让它稳定、安全运行的"基础设施"分离开。你可以把Harness理解为AI Agent的"操作系统"或"控制框架"。
LAYER1 上下文管理
模型能不能稳定发挥，很多时候不取决于它"聪不聪明"而取决于它看到了什么。
1.角色和目标定义
模型要知道自己是谁、任务是什么、成功标准是什么。
2.信息选择和裁剪
上下文不是越多越好，而是越相关越好。
3.结构化组织
固定规则故哪里，当前任务放哪里，运行状态放哪里，外部证据放哪里，最好分层清楚。
LAYER2 工具系统
没有工具，大模型本质上还是一个文本预测器。
一旦接上工具，模型才真正开始"做事"。
1.给它什么工具
工具太少，能力不够;工具太多，模型会乱用。
2.什么时候该调工具
本来不需要查的时候别乱查，该查证的时候也别硬答。
3.结果怎么重新喂回
搜索回来的十条结果。不应该原封不动塞回去，而是要提炼、筛选、保持和任务的相关。
LAYER3 执行编排
解决核心问题：模型下一步该干什么。
很多Agent的问题，不是某一步不会而是不会把步骤串起来。
LAYER4 状态与记忆
没有状态的Agent，每一轮都像失忆。
这三类如果混在一起，系统会越来越乱。
分清楚以后，Agent才会越来越像一个稳定协作者。
LAYER5 评估与观测
很多系统不是"生成不出来"而是"生成完了以后，根本不知道自己做得好不好"。
也就是说，系统不仅要会做，还要知道自己有没有真的做对。
LAYER6 约束与恢复
如果没有恢复机制，Agent每次出错就只能从头再来。
Harness实战
1. 什么是Harness Engineering?
见上
2. 为什么需要 Harness Engineering?
见上
3. AI工程范式的三次跃迁
见上
4. Agent 常见失败模式
Anthropic 工程师在长时间运行 Agent 的过程中，总结了三种典型的翻车姿势，正是驾驭工程要解决的核心痛点：
失败模式 1：试图一步到位（One-shooting）
Agent 倾向于在一个会话里把所有功能都做完。结果是上下文窗口耗尽，留下一堆没有文档的半成品代码，下一个会话启动时只能花大量时间猜测之前发生了什么。
失败模式 2：过早宣布胜利
在项目后期，当部分功能已经完成后，Agent 会环顾四周，看到已有进展就直接宣布任务完成------即使还有大量功能未实现。
失败模式 3：过早标记功能完成
在没有明确提示的情况下，Agent 写完代码就标记为完成，却没有做端到端测试。单元测试或 curl 命令通过了不代表功能真正可用。
此外，智能体还有一个危险特性:它非常擅长模式复制。代码库里有什么模式，它就忠实地复制并放大一-包括坏模式和架构漂移。这意味着不加约束的Agent会以惊人的速度积累技术债务。
5. Harness 核心组件
上下文工程（Context Engineering）------新员工手册
就像给新员工一本详细的工作手册，AGENTS.md 是 AI 智能体进入代码仓库时看到的第一份指南。但这不是一本静态的 1000 页说明书------上下文是稀缺资源，过多的指导反而会挤掉任务、代码和相关文档的空间，变成陈旧规则的坟场。
更好的做法是：提供一个稳定、小巧的入口点，然后教 Agent 根据当前任务按需检索和拉取更多的上下文。Mitchell Hashimoto 的 Ghostly 项目 AGENTS.md 里每一行都对应一个历史 Agent 失败案例------文档是活的反馈循环，不是静态制品。
核心原则
Agent 应当恰好获得当前任务所需的上下文------不多不少。
每个团队都独立发现，将所有指令塞进一个文件无法扩展。解决方案是 分层上下文与渐进式披露：
- OpenAI 使用 AGENTS.md 作为动态反馈循环文件，每当 Agent 遇到失败时更新。
- Anthropic 使用大量 README 和每次会话频繁更新的进度文件。
- Horthey 倡导"频繁有意识压缩"（Frequent Intentional Compaction）。
- Vasilopoulos (2026 论文) 将上下文形式化为三层：热记忆（Hot Memory）、领域专家（Domain Experts）、冷记忆知识库（Cold-Memory Knowledge）。
实践建议------三层上下文体系
| 层级 | 加载时机 | 内容示例 | 上下文占用 |
|---|---|---|---|
| Tier 1：会话常驻 | 每次会话自动加载 | AGENTS.md / CLAUDE.md，项目结构概览 | 最小 |
| Tier 2：按需加载 | 特定子 Agent 或技能被调用时 | 专业化 Agent 的上下文、领域知识 | 中等 |
| Tier 3：持久化知识库 | Agent 主动查询时 | 研究文档、规格说明、历史会话 | 按需 |
Agent 专业化（Agent Specialization）
核心原则：专注于特定领域，拥有受限工具的 Agent 优于拥有全部权限的通用 Agent。
- Carlini（Anthropic C 编译器项目）将 Agent 专业化为编译器核心、去重、性能优化和文档四类角色。
- Vasilopoulos 部署了 19 个领域特定 Agent。
- Huntley 使用子 Agent 来保持主 Agent 上下文的清洁。
专业化不仅是组织性的------它本身就是上下文管理策略。每个专家因为携带更少的无关信息，所以运行在 "Smart Zone" 内。
实践中的角色分工
| Agent 角色 | 职责范围 | 工具权限 |
|---|---|---|
| 研究 Agent | 探索代码库、分析实现细节 | 只读（Read, Grep, Glob） |
| 规划 Agent | 将需求分解为结构化任务 | 只读，无写入权限 |
| 执行 Agent | 实现单个具体任务 | 限定范围的读写权限 |
| 审查 Agent | 审计完成的工作，标记问题 | 只读 + 标记权限 |
| 调试 Agent | 修复审查发现的问题 | 限定范围的修复权限 |
| 清理 Agent | 对抗熵积累，清理低质量代码 | 读写权限 |
持久化记忆（Persistent Memory）
核心原则：进度持久化在文件系统上，而非上下文窗口中。每次新 Agent 会话从零开始，通过文件系统制品重建上下文。
Anthropic 解决这一问题的方案堪称经典：
初始化 Agent：首次会话使用专门的 prompt，要求模型建立初始环境------init.sh 脚本、claude-progress.txt 进度文件和初始 git 提交。
编码 Agent：后续每次会话要求模型在做出增量进展的同时，留下结构化更新。
每个编码 Agent 的典型会话启动流程如下：
- 运行 pwd 查看工作目录
- 读取 git log 和进度文件，了解最近的工作
- 读取 feature list 文件，选择最高优先级的未完成功能
- 启动开发服务器，运行基础端到端测试
- 确认基本功能正常后，开始新功能开发
关键发现：使用 JSON 格式追踪 feature 状态比 Markdown 更有效，因为 Agent 不太可能不恰当地修改或覆盖结构化数据。
结构化执行（Structured Execution）
核心原则：将思考与执行分离。研究和规划在受控阶段进行，执行基于验证过的计划，验证通过自动化反馈（测试、Linter、CI）和人类审查完成。
所有团队都施加了刻意的执行序列：理解 → 规划 → 执行 → 验证。
- OpenAI 使用声明式 prompt 和反馈回路。轻量的计划用于小变更，复杂工作通过带有进度和决策日志的执行计划完成，并检查仓库。
- Huntley 将规划模式与构建模式分离。
- Horthy 的 Research-Plan-Implement 工作流围绕上下文管理精心设计。
人工检查点的价值：审查计划远比审查代码快。当规格正确时，实现自然可靠。当规格有误时，可以在 500 行代码生成之前及时纠正。
架构约束（Architecture Constraints）------ 缰绳
OpenAI 团队建立了严格的层级依赖模型：
Types → Config → Repo → Service → Runtime → UI
下层不能反向依赖上层。所有架构规则被编码为 自定义 Linter 规则，违反即 CI 阻止合并------无论代码是人写的还是 AI 写的。
有个关键细节：Linter 的错误信息本身也是上下文工程。它不只说你违反了规则 X，而是解释为什么这个规则存在、正确做法是什么，这样 Agent 读到错误后就能自我理解并修正，不需要人类介入。
反馈循环（Feedback Loop）------ 智能体审智能体
传统开发中，人类工程师负责代码审查（Code Review）。在驾驭工程中，这个工作变成了智能体对智能体的方式：Codex 在本地审核自身更改，请求额外审查，循环往复直到通过。
反馈循环中的钩子可以运行预定义的测试套件，并在失败时带着错误信息循环回到模型，或者提示模型独立评估其代码。如果 AI 写的测试用例通过了带有 Bug 的代码，Harness 就会判定测试无效，强迫它重新思考测试边界。
熵管理（Entropy Management）------ 垃圾回收
随着时间推移，软件系统会逐渐混乱（熵增），技术债务会积累。OpenAI 采用持续小额偿还的策略，而不是等问题严重时集中处理------他们把这个方法形象地称为垃圾回收，并认为技术债务就像高息贷款。
具体措施：定期运行后台 Codex 任务扫描偏差、更新质量等级、发起针对性重构 PR。此外还有一个专门的 Doc-gardening Agent（文档园丁代理），在后台自动扫描文档与代码之间的不一致，发现过时内容就自动提交 PR 修复------Agent 为 Agent 维护文档。
6. Harness 业界最佳实战案例
7. Harness行业应用落地准则
综合 OpenAI、Anthropic、LangChain、Stripe、HashiCorp 等多个独立信息源，业界在以下六个方面已形成明确共识：
| # | 共识 | 核心观点 |
|---|---|---|
| 1 | 瓶颈在基础设施，不在模型智能 | 五个独立团队得出相同结论。仅改变 Harness 工具格式，就能让模型得分从 6.7% 跳到 68.3% |
| 2 | 文档必须是活的反馈循环 | 静态文档是垃圾，动态文档才有价值。让后台 Agent 定期清理过时文档并提交 PR |
| 3 | 思考与执行分离 | 复杂任务不可能在单个上下文窗口内完成，需要 Orchestrator + Worker 分层架构，状态持久化到外部存储 |
| 4 | 上下文不是越多越好 | 上下文是稀缺资源。巨大的指令文件会挤掉任务空间，应按需检索、动态注入 |
| 5 | 约束必须自动化 | 人工 Review 是瓶颈。护栏要编码为 Linter、CI、类型系统，让机器来执行而非人 |
| 6 | 工程师角色在转变 | 从代码的编写者变成环境的建筑师。最大的工程挑战是设计让 Agent 可靠工作的控制系统 |
8. Harness 项目开发应用实战1
类似如何用 Harness Engineering 管好 AI 写代码的配套示例：
需求:基于 Harness Engineering 从0到1开发一个Java项目
技术:Spring Boot 2.7.x +Java 1.8 + Maven 3.6.3
落地路线图：三步走
在动手之前，先画清楚路线。Harness Engineering 的落地不是"一把梭"，而是渐进式的：
阶段1：信息层（1-2天）
- AGENTS.md 地图模式
- docs/ 结构化文档
- 编码规范文档化
适合 ：所有项目
收益：Agent 输出一致性 ↑
阶段2：约束层（3-5天）
- 分层架构 + Linter
- CI 约束检查
- 错误信息含修复指令
适合 ：中期项目
收益：代码质量可控
阶段3：自动化层（1-2周）
- Agent 自验证闭环
- 后台清理 Agent
- JaCoCo/截图自动验证
适合 ：长期维护项目
收益：人工审查量 ↓↓↓
不要一步到位。很多人失败就在于想一次性搞定所有基础设施。阶段1已经能带来显著提升，阶段2是质变点，阶段3是锦上添花。
9. Harness 项目开发应用实战2
这个例子是多agent编排：https://github.com/monkeyhlj/agent-harness-test/blob/main/README.md
【参考文章】如下：
- Mitchell Hashimoto
文章标题：《My AI Adoption Journey》
原文链接：https://mitchellh.com/writing/my-ai-adoption-journey - OpenAI
文章标题：《Harness engineering: leveraging Codex in an agent-first world》
原文链接：https://openai.com/index/harness-engineering/ - Anthropic
文章标题：《Effective harnesses for long-running agents》《Harness design for long-running application development》
原文链接：
https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
https://www.anthropic.com/engineering/harness-design-long-running-apps - LangChain
文章标题：《The Anatomy of an Agent Harness》
原文链接：https://www.langchain.com/blog/the-anatomy-of-an-agent-harness - Martin Fowler
文章标题：《Harness Engineering - first thoughts》
原文链接：https://martinfowler.com/articles/exploring-gen-ai/harness-engineering-memo.html
文章标题：《Harness engineering for coding agent users》
原文链接：https://martinfowler.com/articles/harness-engineering.html
【参考】https://github.com/alchaincyf/harness-engineering-orange-book
【参考】https://github.com/deusyu/harness-engineering
【参考】https://www.bilibili.com/video/BV1duoFBvEjR
【参考】https://www.bilibili.com/video/BV1Bm5T6sEJ7
【参考】https://mp.weixin.qq.com/s/bCHtm4KtGmdJLZUywjr-Aw