Agent Harness 架构设计与实现：生产级 Agent 系统落地指南¶

Ch04.021 Agent Harness 架构设计与实现：生产级 Agent 系统落地指南¶

📊 Level ⭐⭐ | 39.1KB | entities/agent-harness-architecture-design-production-guide.md

1. 核心定义与演进脉络¶

三次工程重心迁移¶

AI 工程领域过去两年经历了三次重心迁移，层层递进而非替代：

核心公式¶

Agent = Model + Harness
Harness = Agent - Model

Harness 的本质：在 Agent 环境中除了模型外的所有东西，它决定了模型看到什么、能做什么、按什么规则做、做错了怎么纠偏，以及最后如何把能力稳定地交付出来 。

三层关系的通俗理解（以客户拜访为例）¶

• Prompt Engineering：把任务讲清楚（见面先寒暄，再介绍方案，再问需求，最后确认下一步）
• Context Engineering：把资料准备齐（客户背景、过往沟通记录、产品报价、竞品情况）
• Harness Engineering：建立持续观测、纠偏、验收的机制（带 checklist 去、关键节点实时回报、会后核对纪要、按明确标准验收）

2. 七层金字塔架构总览¶

3. L1：核心执行引擎¶

双循环架构¶

快执行循环（"小脑模式"）处理高频、简单的 Tool Call 场景，而慢思考循环在每 3 步或遇到错误时触发全局复盘。这一设计将任务成功率从 60% 提升至 90%+ 。

本质是将"系统 1 快速反应"与"系统 2 深度反思"分离，避免同一个执行循环中既要处理实时响应又要兼顾全局策略的相互干扰。断点续跑机制（每步状态持久化）与双循环形成互补，共同保障长时间任务的可恢复性。

Claude Code 的探索-规划-行动循环模式¶

Claude Code 泄露代码揭示了更细粒度的执行模式：

1. 探索阶段：只读代码、查信息、摸清结构
2. 规划阶段：和用户对齐思路
3. 行动阶段：最后再动手改代码

本质上就是先搞清楚，再决定怎么做，最后再执行。对于不熟悉的代码库，先花时间理解再动手，比一上来就改代码要高效得多。

多模型抽象层¶

统一接口实现多模型调度，成本降低 50%+，支持 5 个提供商、20+ 路由规则 。

4. L2：工具系统¶

五级风险分级¶

从 L0（只读自动执行）到 L4（直接拦截），五级分类覆盖了从无害到危险的全光谱操作 ：

这种精细化的权限模型使得同一个 Agent 系统可以同时支持低风险自动化场景（L0）和高风险人工审批场景（L3），而无需为不同风险级别部署独立的 Agent 实例。

命令风险分类模式¶

在执行前做一层"风险判断"：低风险的命令自动放行，高风险的才需要人工确认或直接拦截 。实现上通常是对命令做解析（比如看做什么操作、带了哪些参数、影响范围多大），再结合规则去判断风险等级。

单用途工具设计原则¶

把常见操作拆成专门的工具，比如读文件、改文件、搜索、匹配路径，各自都有明确的输入和边界。这样不仅更好理解，也更容易限制权限 。

MCP 生态：Agent 世界的 USB 标准¶

80% 的工具来自社区 MCP，说明 Agent 工具生态正在从"自建为主"转向"社区贡献为主" 。MCP 作为 Agent 世界的 USB 标准，解决了工具发现的互操作问题——工具提供者只需实现一次 MCP 协议，消费者即可无缝调用。

架构建议：在设计工具系统时应优先考虑 MCP 兼容接口，而非私有协议，以充分利用社区的工具生态。只有当 MCP 生态缺少关键能力时才考虑自建，并同步考虑将自建工具贡献回 MCP 社区。

渐进式工具扩展¶

先给一小部分常用工具，够用就行；其他工具按需再打开。比如读写文件、搜索这些作为默认能力，复杂一点的工具等用到再加载 。

5. L3：上下文工程¶

阶梯式上下文压缩¶

上下文工程的核心不是简单截断，而是按语义分数分级处理 ：

• L0：保留关键信息
• L3 以下：逐步删除低分内容

这种分层策略避免了一刀切截断导致的语义断裂，同时会话隔离（独立生命周期 + LRU 淘汰）确保多租户场景下上下文不会相互污染。Token 消耗降低 52%，阶梯压缩提供了可预测的 Token 成本上限。

渐进式上下文压缩模式¶

新的对话尽量保留细节，稍旧的内容做轻量总结，再往前的就逐步压缩，甚至折叠成很短的摘要。可以理解为越久远的信息，保留得越粗 。

适用场景：对话轮次比较多（比如 20～30 轮以上）的任务。

权衡点：压缩一定是有损的。信息在一轮轮总结中会丢失，如果后面又需要这些细节，Agent 可能会"编"而不是承认不知道。

作用域上下文组装模式¶

把指令拆到不同作用域里：组织级、用户级、项目根目录、父目录、子目录。Agent 会根据当前所在的位置，动态加载对应的规则。这样既能保持全局一致，又能允许局部有差异 。

适用场景：Monorepo、多语言项目，或者不同目录有不同规范的代码库。

Anthropic 的 Context Reset 实践¶

与 Context Compaction（压缩历史继续跑）不同，Context Reset 直接换一个干净上下文的新 Agent，通过工作交接实现"清空包袱、重新出发"的效果 。

6. L4：记忆系统¶

三层记忆架构¶

知识编译（将知识单元转化为 QA 对）是降低幻觉率的关键——结构化的 QA 格式比自由文本更不容易被 LLM 误用。幻觉率从 30% 压至 5% 以下，准确率 95%+ 。

分层记忆模式¶

一个精简的索引始终放在上下文里（比如控制在几百行以内），和当前任务相关的内容按需加载，完整的历史记录则留在磁盘上，需要时再去查 。

记忆整合模式（Dream Consolidation）¶

加一个后台整理机制，在空闲时定期做清理：去重、删旧、重组结构，让记忆保持干净、可用。可以理解为给 Agent 做一次"垃圾回收" 。

像 Claude Code 泄露代码里提到的 autoDream，就是在做类似的事情：合并重复、处理冲突、控制索引规模。

持久化指令文件模式¶

放一个项目级的配置文件，每次会话自动加载。里面写清楚构建命令、测试方式、架构规则、命名约定这些内容。文件跟着代码仓库走，而不是靠人每次复制粘贴 。

适用场景：需要在多个会话里反复处理同一个代码库。

权衡点：有维护成本。这个文件需要跟着项目一起更新，一旦过时，反而会误导 Agent，还不如没有。

7. L5：自主决策引擎¶

目标管理¶

L5 层解决的核心问题：模型是否能持续做对 。

生成器+评估器模式¶

Anthropic 的核心实践：generator + evaluator（后扩展为 planner + generator + evaluator），本质是生产与验收必须分离 ：

• Planner：把短需求扩展成完整产品规格
• Generator：逐步实现
• Evaluator：像 QA 一样，用浏览器和工具真实操作应用检查功能、设计、代码质量

Evaluator 不是"读代码打分"，而是"带环境的验证"。

8. L6：多 Agent 协作¶

分支-合并并行模式¶

有些任务其实可以拆开做，但如果 Agent 一次只能处理一件事，最后还是会变成一条一条顺序执行。这个模式的思路是把任务拆成多个分支并行处理：每个子 Agent 在独立的代码副本里工作（比如用 git worktree），互不干扰。等都完成后，再把结果合并回来 。

适用场景：可以拆成多个互不依赖子任务的场景。

权衡点：合并会更复杂。如果不同分支改到了同一部分代码，冲突可能比顺序处理更难解决。

上下文隔离子智能体模式¶

把任务拆给不同的子 Agent，每个都有自己的上下文和权限 ：

• 做调研的只负责看和分析，不能改代码
• 做规划的只负责设计方案
• 真正执行的才有完整工具权限

每个子 Agent 只接触自己需要的信息，避免被"流噪声"影响。

未解决的张力：上下文隔离和全局一致性之间存在矛盾。当多个子 Agent 的决策需要保持一致时（比如都要遵守同一个架构规范），这种隔离反而会导致冲突或重复。

9. L7：垂直行业应用¶

医疗、法律、金融、研发场景¶

10. 六层 Harness 架构（行业实践）¶

与七层模型的对应关系¶

Harness Engineering 综合性指南提出了六层架构 ，可与七层模型映射：

头部企业实践¶

Anthropic：Generator + Evaluator 分离¶

两个典型问题：

• 上下文焦虑：任务一长，上下文窗口越来越满，模型开始丢细节、丢重点
• 自评失真：模型自己做完后自己评判，往往偏乐观

解决方案：Generator + Evaluator 分离，Evaluator 像 QA 一样用真实环境验证 。

OpenAI Codex：渐进式披露 + 架构约束内化¶

• 渐进式披露：AGENTS.md 只有 ~100 行充当"目录页"，指向仓库里的详细文档
• 6 小时连续运行：单次 Codex 运行经常连续工作 6 小时以上，Agent 自己跑应用、发现 bug、修复、验证、提 PR
• 架构约束写进系统：把资深程序员的经验判断写成机器可以自动执行的检查规则

LangChain：Harness 迭代的巨大威力¶

在底层模型完全不变的情况下，仅仅通过改造和迭代 Harness，就把自家代码智能体在 Terminal Bench 2.0 榜单上的得分从 52.8 拔高到了 66.5，直接从 Top 30 开外杀入 Top 5 。

11. 12 个可复用 Agentic Harness 设计模式¶

Claude Code 源码泄露揭示了 12 个可复用的设计模式 ，分为四类：

记忆与上下文（5个）¶

工作流与编排（3个）¶

工具与权限（3个）¶

自动化（1个）¶

12. 核心设计原则¶

黄金法则¶

把确定性的事情交给系统，把判断的事情交给模型；把局部的事情交给组件，把全局的事情交给机制。

这个原则在模式 12（确定性生命周期钩子）中体现得最明显：格式化代码、校验输入、重新加载配置——这些事情必须每次都做，而且不能出错，所以不应该依赖模型的记忆，而应该由系统强制执行。

延伸结论：Agent 框架的可靠性不取决于模型有多强，而取决于有多少关键流程被系统接管。

传统软件架构的呼应¶

这些设计模式在软件工程中有深厚的根基 ：

• 分层记忆 类似 CPU 的缓存层次结构（L1/L2/L3 Cache）
• 上下文压缩 类似于操作系统的内存分页和交换机制
• 生命周期钩子 就是 AOP（面向切面编程）的思想
• 命令风险分类 是 RBAC（基于角色的访问控制）模型的变体
• 分支-合并并行 就是 MapReduce 的思路

Agent 架构本质上是在用新的载体解决计算科学已经解决过的问题。

深度分析¶

1. Harness Engineering 是 AI 工程化的第三次范式跃迁¶

从 Prompt Engineering 到 Context Engineering 再到 Harness Engineering，代表了 AI 系统从"如何说"到"如何看"再到"如何做"的进化路径。前两阶段解决的是模型理解和信息获取问题，而 Harness Engineering 解决的是模型在真实执行中的控制问题——这才是生产级 AI 系统落地的核心障碍 。

2. 双循环架构揭示了"系统1+系统2"在 Agent 层的工程化实现¶

快执行循环（系统1）与慢思考循环（系统2）的分离，不只是认知科学的隐喻，而是有实测支撑的工程决策——任务成功率从 60% 提升至 90%+ 。这说明在 Agent 层面，单纯的模型能力提升远不如控制系统优化有效。LangChain 的案例更有说服力：底层模型完全不变，仅通过 Harness 迭代就在 benchmark 上从 Top 30 开外杀入 Top 5 。

3. MCP 生态的崛起标志着 Agent 工具链进入"工业化协作"阶段¶

80% 的工具来自社区 MCP 这一数据，意味着 Agent 工具生态正在从"各自为战"转向"标准化分工"。MCP 作为 Agent 世界的 USB 标准，解决了工具发现的互操作问题 。这对框架设计者的启示是：优先考虑 MCP 兼容接口，而非私有协议，才能最大化生态红利。

4. 知识编译模式将记忆系统的幻觉率压至 5% 以下¶

三层记忆架构（短期/中期/长期）中，知识编译（将非结构化知识转化为 QA 对）是降低幻觉率的关键设计。结构化 QA 格式比自由文本更不容易被 LLM 误用，准确率可达 95%+ 。这与 RAG 的"直接检索原始文档"模式形成鲜明对比——记忆系统的核心挑战不是检索精度，而是如何将知识转化为模型可靠使用的形式。

5. ETCLOVG 框架揭示了 Context & Memory 和 Governance 是开源生态的最大短板¶

CMU-Amazon 2026 Survey 显示，在 ETCLOVG 七层架构中，Context & Memory 和 Governance & Security 在开源生态中最为薄弱。这与行业对 Harness 工程的实际投入方向高度一致——大多数框架把资源集中在执行引擎和工具系统，而对记忆管理和安全治理的工程投入严重不足。

13. 实践启示¶

生产部署实践¶

1. 在生产环境部署双循环执行引擎

不要试图用单一执行循环同时满足实时响应和全局规划的需求。实现上，建议快循环使用轻量级模型（如 GPT-4o-mini）处理 Tool Call 路由，慢循环在检测到错误或每 N 步时切换至更强模型进行全局复盘。断点持久化使用标准序列化方案（如 JSON + 文件系统），确保崩溃重启后可精确恢复。

2. 为工具系统设计五级风险分级模型

在设计期就定义清楚每类工具的默认风险等级，并配置对应的执行策略。L0 只读工具（如网页搜索）可全自动执行，L2 新文件写入需要 Diff 预览确认，L3 危险操作（删除、修改系统文件）必须人工审批。将风险分级作为工具元数据的一部分，支持运行时按需调整。

3. 会话隔离结合 LRU 淘汰保障多租户稳定性

为每个用户会话分配独立的上下文生命周期，使用 LRU 策略在内存压力下优先淘汰最旧的会话。同时在入口层做租户隔离校验，避免越权访问。上下文压缩应在会话粒度独立执行，而非全局统一压缩，防止跨会话信息泄露。

4. 从知识编译入手构建低幻觉记忆系统

不要直接将原始文档注入长期记忆。先通过知识编译（实体抽取 + QA 对生成）将非结构化知识转化为结构化单元，再存入向量库。这比直接 RAG（直接 embedding 原文）能显著降低幻觉率，准确率可达 95%+。中期记忆的本地 DB 推荐使用 SQLite 或 PostgreSQL（支持 JSON），便于快速读写结构化状态。

5. 优先集成 MCP 生态工具而非自建

在规划工具系统时，先调研 MCP 生态是否有现成工具可用（当前已有大量社区贡献的工具）。只有当 MCP 生态缺少关键能力时才考虑自建，并同步考虑将自建工具贡献回 MCP 社区。这不仅降低开发成本，还能享受社区维护的工具更新。

Agent 应用开发者建议¶

从持久化指令文件开始：这是最容易落地、收益最明显的一个模式。只需要在项目根目录放一个配置文件，Agent 每次会话就会自动加载项目特定的规则和约定。这个投入几乎为零，但能显著减少重复错误。

优先实现工具的风险分类：如果打算让 Agent 执行 shell 命令，命令风险分类是必须要有的。可以先从一个简单的规则引擎开始，把高风险操作（删除、覆盖、系统配置修改）拦截或要求确认。

不要把所有事情塞进提示词：确定性生命周期钩子提醒我们：凡是必须每次都做的事情，都应该由系统强制执行，而不是写在提示词里期望模型记住。

从短任务开始，逐步增加复杂度：探索-规划-行动循环本质上是一种"慢就是快"的思路。对于不熟悉的代码库，先花时间理解再动手，比一上来就改代码要高效得多。

框架设计者建议¶

设计工具时要考虑权限粒度：工具不应该只是"能做什么"，还应该隐含"能对什么做"。一个 read_file 工具和一个 read_image 工具应该有不同的权限域。

把记忆管理做成基础设施：分层记忆、整合、压缩目前大多数框架都没有很好的支持。但从 Claude Code 的实现来看，这是大规模应用的前提条件。框架层面如果能提供标准化的记忆管理接口，会大大降低应用开发的难度。

生命周期钩子应该是框架原生支持的功能：而不是让开发者自己实现。确定性生命周期钩子的核心洞察——"确定性事件应该由系统触发"——应该成为框架设计的核心原则。

架构演进方向¶

基于 12 个设计模式所揭示的设计方向，未来 Agent 框架的几个演进趋势：

• 工具粒度会越来越细：更细粒度的工具会带来更好的可控性和可审查性
• 记忆管理会成为核心竞争力：当上下文窗口不再是瓶颈，如何在海量记忆中快速检索、保持一致性、避免膨胀，会成为新的工程难题
• 生命周期管理会标准化："什么时候该做什么"的标准化需求会推动确定性生命周期钩子成为一等公民
• 混合架构会取代单体架构：分支-合并、上下文隔离这样的多 agent 协作模式会成为常态

14. ETCLOVG 七层架构（CMU Survey）¶

CMU 等高校与 Amazon 联合发布的 2026 Survey 提出了与七层金字塔模型互补的 ETCLOVG Taxonomy，两者可对照阅读：

与七层金字塔的关键差异¶

1. Observability 独立成层：生产环境中监控与治理有独立工具栈和不同团队负责，这一分层在早期框架中常被混在执行循环里
2. Governance 独立成层：权限模型、生命周期钩子、组件加固、声明式宪法、审计基础设施需要独立关注
3. Verification 强调 trace-native：评估应从 traces 而非事后 log 分析中计算结果分数

开源生态覆盖现状¶

根据 Survey 对开源项目的统计分析：

关键发现：Context & Memory 和 Governance & Security 在开源生态中最为薄弱，是未来工程投入的重点方向。

15. 跨层合成：三大核心矛盾¶

15.1 成本-质量-速度三难困境（Cost-Quality-Speed Trilemma）¶

更强的沙箱、更丰富的上下文、更深入的评估会提升质量，但同时增加 Token 消耗、延迟和基础设施成本。生产 Harness 不能把质量当作标量目标，必须决定：

• 哪些风险值得昂贵的控制措施
• 哪些检查可以异步运行或放入回归测试套件

工程权衡示例：

• 每次 Tool Call 后做完整验证 → 质量↑ 成本↑ 延迟↑
• 只在关键节点验证 → 成本↓ 延迟↓ 风险↑
• 异步验证 + 实时标记 → 成本可控但引入状态复杂性

15.2 能力-控制权衡（Capability-Control Tradeoff）¶

更大的工具菜单、持久化记忆、更宽松的沙箱会扩大任务覆盖范围，但同时扩大误对齐或被攻击时的破坏半径。能力和控制是同一个设计轴的两端，贯穿：

• 工具 Schema 设计
• 上下文策略
• 运行时权限
• 身份认证
• 审计能力
• 人工审批流程

15.3 Harness 耦合问题（Harness Coupling Problem）¶

Harness 各层以脆弱的方式耦合。单独的 Prompt、工具、沙箱、验证器或监控器可能在隔离测试中表现良好，但与控制循环其余部分组合时会降低整体效果。

核心原则：Harness 变更必须作为系统级变更进行测试，不能仅在隔离环境中验证单层改进。

16. 测试策略：Agent Harness 如何测试¶

不同于传统软件测试，Agent Harness 的测试面临独特挑战：非确定性输出、长链路依赖、环境敏感性。

16.1 分层测试策略¶

16.2 Trace-Based Evaluation¶

以 trace 为核心对象的评估范式：

1. 轨迹质量评分：不只是最终结果，而是评估完整执行路径
2. 失败归因：将失败精准定位到 Harness 的某一层（Context 不足？工具定义错误？验证器漏检？）
3. 回归测试：从生产 traces 自动生成回归测试用例

16.3 Golden Trace 管理¶

golden-traces/
├── success/
│   ├── simple-file-edit/
│   │   ├── trace.json      # 完整执行 trace
│   │   └── metadata.yaml   # 任务描述、预期结果
│   └── complex-multi-agent/
│       └── ...
├── failure/
│   ├── context-overflow/
│   └── tool-misuse/
└── regression/
    └── auto-generated/     # 从生产 traces 自动提取

16.4 Benchmark 生态¶

17. 生产部署：成本工程¶

17.1 Token 成本模型¶

单次任务成本 = Σ(每步 Token 数 × 单价)

              + Σ(工具调用成本)
              + 基础设施成本

关键优化点：

- 上下文压缩策略：Token 消耗降 52%
- 工具粒度：避免过度反序列化
- 路由策略：简单任务路由至小模型，成本降 50%+

17.2 分层成本控制¶

17.3 成本监控指标¶

• Token 消耗速率：$/小时、$/任务
• 上下文填充效率：有效 Token / 总 Token
• 工具调用效率：有效调用 / 总调用（含无效调用率）
• 任务成功率：每成本单位的产出质量

18. 失败模式与恢复策略¶

18.1 典型失败模式分类¶

18.2 恢复策略矩阵¶

18.3 自动恢复机制设计¶

class RecoveryManager:
    def __init__(self):
        self.strategies = {
            'tool_failure': [retry, fallback, skip],
            'context_overflow': [compress, reset, escalate],
            'validation_failure': [self_fix, human_review, abort],
            'permission_denied': [escalate, request_approval, abort]
        }

    def recover(self, error, state):
        for strategy in self.strategies[error.type]:
            if strategy.can_apply(error, state):
                result = strategy.apply(error, state)
                if result.success:
                    return result
        return self.escalate_to_human(error, state)

19. 安全与合规¶

19.1 提示注入防御¶

19.2 合规可审计性¶

医疗、法律、金融等强监管行业需要：

• 完整操作溯源：每步操作的时间、发起者、输入输出
• 决策解释性：为什么选择这个工具、为什么这样执行
• 版本控制：Prompt、工具定义、规则引擎的变更历史
• 审计报告自动生成：满足合规审查要求

20. 未来研究方向¶

基于 CMU Survey 的五大开放问题：

20.1 最高优先级¶

1. Trace 原生故障诊断：Traces 应该是计算结果分数、轨迹质量、失败归因和回归测试的主要对象，而不仅是事后调试材料
2. 长程 Agent 可靠状态管理：将上下文管理重新表述为状态估计问题——量化每次压缩、检索或遗忘步骤的信息损失

20.2 中期关注¶

1. 跨 Agent、工具、人的标准交接协议：交接应传输文本摘要之外的意图、约束、权限、制品、出处、预算状态、风险级别、trace 历史和未解决决策
2. 执行环境加固与扩展：Prompt 注入、目标错位、组合放大攻击的通用安全评估

20.3 长期战略¶

1. 自适应简化机制：随着模型改进，某些干预措施仍是必需的，而另一些变成成本、延迟或运营开销。未来 Harness 需要在联合质量、延迟、成本和风险约束下进行自我优化和简化

相关实体¶

• Code As Agent Harness Survey
• Agent Harness Architecture
• Agentscope Java Harness Framework Enterprise Distributed
• Agentic Ai System Architecture Harness Skill Mcp
• Harness Production Agent Engineering Deficit

→ 原文存档（主源） → Harness Engineering 综合性指南 → Claude Code 12 个设计模式 → ETCLOVG Survey (CMU 2026)

• Versa Takes Aim At Fragmented Enterprise Security With Cspm Orchestration Updat
• k-dense — the model is no longer the bottleneck
• MOC