Harness Engineering 的六层体系架构

⚠️ 先厘清一个关键概念

在深入细节之前，有必要先区分两个常被混用的概念：

• Agent Harness（技术实体）：这是 AI Agent 的“运行控制面板”和“硬件底座”，是一套具体的技术控制系统，负责处理模型推理之外的所有结构化事务。
• Harness Engineering（工程方法论）：这是一套系统化的工程方法论，回答“如何设计、构建、维护高可用的 Agent Harness”。它相当于 Agent Harness 背后的设计模式、工程原则与最佳实践。

简单来说，Harness Engineering 是“道”，Agent Harness 是“器”。下文讨论的六层架构，正是 Harness Engineering 这套方法论在 Agent Harness 这个“器”上的具体体现。

---

📊 六层架构速览

一个成熟的 Harness 体系，从内到外可分为六个职责分明的控制层：

层级	核心问题	关键机制
L1：信息边界层	Agent 该知道什么、不该知道什么？	定义角色、裁剪信息、动态检索、渐进式披露
L2：工具系统层	Agent 如何与外部世界交互？	精确工具定义、MCP 标准协议、沙箱执行
L3：执行编排层	复杂任务如何拆解与执行？	ReAct 循环、Plan-and-Execute 模式
L4：状态与记忆层	Agent 如何拥有记忆、保持状态？	工作记忆、会话记忆、长期记忆分层管理
L5：评测与观测层	如何知道 Agent 干得好不好？	轨迹捕获、质量评分、反馈闭环
L6：约束与恢复层	出错了怎么办？如何确保安全？	权限门控、沙箱隔离、自动重试与回滚

---

🔍 逐层深度剖析

L1：信息边界层 (Information Boundary)

这一层要解决的核心问题是：在有限的上下文中，如何让模型看到此刻最该看到的东西？

尽管模型上下文窗口已扩展到百万 Token 级别，但把海量信息一股脑塞给模型会带来三个严重问题：

1. 长上下文衰减：模型对中间段信息的注意力会明显下降，即“Lost in the Middle”效应。
2. 成本爆炸：每次调用都携带几十万 Token，成本难以承受。
3. 噪声干扰：无关信息会让模型抓不住重点，甚至产生幻觉。

实践中，这一层通过以下机制来解决：

• 动态组装：每一轮对话前，根据当前任务动态检索相关文件、历史决策和工具输出。
• 分层加载：核心指令常驻，工作记忆按需加载，长期记忆按查询拉取。
• 渐进式披露：用简短的 AGENTS.md 文件作为“地图”，只说明工作原则、关键文档路径、常用命令、架构不变量和PR验收标准，指向更详细的文档，而非一次性灌输全部信息。
• 结构化切片：将大文件切成语义块，通过 embedding 或关键词检索按需注入。

关键洞察：信息边界层不是简单地“塞更多信息”，而是在正确的时间、以正确的粒度、给模型正确的那部分信息。OpenAI的实践表明，Codex通过跨多个上下文窗口工作，自动清理会话历史，实现了长任务的高效执行。

L2：工具系统层 (Tool System)

模型输出的本质是文本，要让文本“动起来”改变世界，必须依赖工具调用。这一层决定了 Agent 的物理能力边界。

• 工具描述的精确性：工具名、参数 Schema、描述文案，每一个字都会影响模型的调用准确率。
• MCP 协议：模型上下文协议（Model Context Protocol）正在成为业界默认的工具接入标准。
• 执行沙箱：代码执行、Shell 命令、浏览器操作都必须在隔离环境中运行，防止对宿主系统造成影响。
• 结构化反馈：执行成功/失败、错误信息、输出摘要，都要以模型能理解的结构化方式回传。

关键洞察：工具系统层的设计哲学是让工具对模型“可推理”——工具不仅要能用，还要让模型能准确地理解“什么时候该用、怎么用、用了会怎样”。

L3：执行编排层 (Orchestration)

这是 Agent 从“单轮问答”升级为“多步任务执行”的关键。它负责将一个复杂目标拆解为可执行的动作序列。

两种核心模式：

• ReAct 循环：最经典的范式——思考 (Reason) → 行动 (Act) → 观察 (Observe) 的循环。
• Plan-and-Execute：先生成完整计划再逐步执行，中途可根据情况重新规划。Claude Code 将这种模式进一步拆分为规划模式和执行模式，避免盲目试错。

关键洞察：编排层的本质是把不确定的 LLM 推理，转化为确定性的任务执行流。模型负责“想”，编排层负责“管”。Codex的编排层让模型不再是“一次性回答”，而是能“持续工作”——在长任务中保持连贯性、跟踪指令、避免漂移。

L4：状态与记忆层 (State & Memory)

让 Agent 拥有“记忆”，在多轮对话和长时间任务中保持状态一致性。

• 工作记忆：记录当前任务的状态、执行进度和中间变量。
• 会话记忆：保存本次会话的完整历史，必要时进行摘要压缩。
• 长期记忆：跨会话持久化的知识和经验。Codex的记忆子系统（基于Rust核心的codex-rs/core/src/memories/）支持提取可复用的偏好和项目摘要，供后续任务检索

关键洞察：Claude Code 采用指针索引式 Memory——不直接存储完整内容，仅记录文件指针与主题标签，后台自动合并、去重、关联。这反映了行业共识：记忆不是“存更多”，而是“存得更聪明”。Codex采用外部化状态而非依赖模型内部记忆——仓库是系统事实来源。所有约定、计划和决策日志如果不在仓库中，对Codex就等于不存在。这反映了行业共识：记忆不是“存更多”，而是“存得更聪明”。

L5：评测与观测层 (Evaluation & Observability)

没有这一层，就无法判断 Agent 的表现好坏，更无法进行系统优化。

• 执行轨迹捕获：记录 Agent 的每一步思考、每一次工具调用及其结果。
• 成功信号定义：为每个任务明确“完成”的判定标准。
• 质量评分体系：建立可量化的评估维度，持续监控 Agent 表现。

关键洞察：评测与观测层让 Harness Engineering 的核心承诺成为可能——“每当 Agent 犯了一个错误，你就花时间设计一个解决方案，使得 Agent 在未来不会再犯同样的错误”。没有观测，就没有迭代的基础。

OpenAI构建了一个完整的Agent改进飞轮（Improvement Flywheel）：

1. Traces（轨迹）显示发生了什么
2. Feedback（反馈）解释哪些重要
3. Evals（评估）让期望可复用
4. Codex根据评估结果实施Harness变更

L6：约束与恢复层 (Constraint & Recovery)

这是确保 Agent 安全、可控、可靠的最后一道防线。

• 权限门控：通过生命周期钩子（hooks）进行身份验证和策略强制执行。权限体系可按风险等级设计，如“完全人工操作”、“每步审批”、“流程前一次性审批”等。
• 沙箱隔离：对高风险操作进行环境隔离和审批。
• 自动恢复：建立重试、回滚等机制，处理执行中的错误。

关键洞察：约束与恢复层是 Harness 区别于纯 Prompt/Context 工程的根本所在——它引入了确定性的机械执行环境，在模型决策之外提供了硬性的安全边界。

---

💎 其他精选视角

除了六层架构本身，网络上的精选文章还提供了几个重要视角：

1. Harness 的惊人效果

• 同一模型，仅改变 Harness 设计，编码基准测试分数可从 6.7% 跃升至 68.3%。
• LangChain 团队的实验也显示，仅修改 Harness（不换模型），任务完成率从 52.8% 提升到 66.5%。

2. Claude Code 的启示

• Claude Code 的代码库中，模型决策逻辑仅占 1.6%，剩下 98.4% 全是 Operational Harness。这直观地说明了：在真正的生产级 Agent 中，模型只是冰山一角。

3. Codex 的架构启示

• Codex的代码库中，Harness提供了核心的Agent循环和执行逻辑，是所有Codex体验的基础。这直观地说明了：在真正的生产级Agent中，模型只是冰山一角。
• Harness是开源的，并且越来越多地成为模型训练和评估的一部分，使其成为Codex中杠杆率最高的层面之一。

4. 三大工程的递进关系

• Prompt Engineering（怎么把指令说清楚）→ Context Engineering（该给 Agent 看什么）→ Harness Engineering（系统如何持续执行、纠偏、观测和恢复）。这三者不是替代关系，而是层层递进、层层包含。

---

🎯 总结

Harness Engineering 的六层体系，本质上是一套从信息供给、行动能力、任务规划、记忆系统、效果评估到安全兜底的完整闭环。penAI的Codex实践表明，Harness不是辅助工具——它是模型在工程环境中运行的前提条件。

一句话总结：模型决定 Agent 的智商上限，Harness 决定 Agent 的交付下限。六层架构就是实现这个“交付下限”的系统化工程蓝图。