同样是 GPT-4 或 Claude，有人做的 Agent 稳定可靠，有人做的却频繁翻车。我最近在学习 Agent 工程化，把这个问题从头到尾理了一遍，发现问题不在模型本身，而在模型之外的整个系统，也就是 Harness。

有一组数据能说明这个差距。同一模型，仅改变 Harness 设计，编码基准测试分数可以从 6.7% 跃升至 68.3%。这个数字是我在整理资料时看到的，也是促使我把 Harness 六层架构完整过一遍的原因。

Harness Engineering 在 2025-2026 年成为 AI Agent 领域最重要的工程范式转移。核心公式很简单。

Agent = Model + Harness

Model 是推理大脑，Harness 是让大脑能干活的「身体」。工具、上下文、状态、权限、观测、恢复，全在 Harness 里。这六项正好对应后文的六层，上下文对应第一层，工具对应第二层，状态对应第四层，观测对应第五层，权限与恢复对应第六层。学术界也在做同样的拆解，MemoHarness 论文把 Harness 建模成六维空间模型，本文的六层是同一思路在工程侧的落地。

这篇是我的学习笔记整理，把 Harness 拆成六层架构，每层解决什么问题、有哪些工程实践，逐条过一遍。想入门 Agent 工程化的同学，希望它帮你省点时间。

一、第一层：上下文管理层

这一层要解决的是，如何让模型在有限的窗口里，看到此刻应该看到的东西。

现在模型上下文动辄 200K 甚至 1M token，但依然不能把所有内容都扔给模型。原因有三个。

1. 长上下文衰减。模型在中间段的注意力会明显下降，即「Lost in the middle」效应，塞得越长，关键信息越容易丢
2. 成本爆炸。每次调用带几十万 token，费用可观，一轮对话顶得上别人一天
3. 噪声干扰。无关信息太多，模型抓不住重点，关键指令被稀释在无关文本里

对应四个工程实践。

• 动态组装上下文。每轮对话前，根据当前任务动态检索相关文件、历史决策、工具输出
• 上下文压缩。接近上限时自动摘要早期对话，释放空间，长会话不失控
• 分层加载。核心指令常驻，工作记忆按需加载，长期记忆按查询拉取，三级各有各的加载方式
• 结构化切片。把大文件切成语义块，用 embedding 或关键词检索按需注入，避免整个文件占窗口

面试被问到上下文管理，可以直接说，这是 Harness 中最先应该投入的优化点，投入产出比极高。先动这里，成本和质量同时改善。

二、第二层：工具与执行层

这一层要解决的是，如何让模型精准地调用工具。

模型输出的本质是文本，要让文本「动起来」，必须依赖工具调用。这一层决定了 Agent 的物理能力边界，工具给不了的能力，模型再强也做不出来。

工程实践有四条。

• 工具描述的精确性。工具名、参数 schema、描述文案，每一个字都影响模型调用准确率
• 执行沙箱。代码执行、Shell 命令、浏览器操作都需要隔离环境，防止 agent 把宿主机器玩坏
• 工具执行结果的结构化反馈。成功/失败、错误信息、输出摘要，都以模型能理解的方式回传，甩一段原始日志等于没回传
• MCP 协议。正在成为业界默认标准，一次接入到处复用

工具设计原则，我学习时整理成了一张表。

原则	说明
名称语义互斥	不要让 search_docs 和 find_docs 同时出现，模型会懵
description 面向模型	让模型知道什么时候用、什么时候不用，写使用时机不写功能罗列
schema 严格	JSON Schema / enum / required 字段要清楚，能枚举就别开放
返回可控	大结果分页、截断、摘要、附来源，别让模型读十万行输出
最小权限	工具只暴露完成任务所需的最小能力，少一个危险面少一次事故

关键建议。不要每轮把所有工具描述都塞进上下文。工具描述保存为可按需读取的文件，让 Agent 只加载当前任务需要的能力，跟第一层的动态组装是同一个思路。

三、第三层：执行编排层

面对复杂目标，怎么把任务拆成模型能一步步执行的动作序列？

这一层是 Agent 从「单轮问答」升级为「多步任务执行」的关键。四种主流编排模式。

1. ReAct 循环。Reason（思考）→ Act（行动）→ Observe（观察）→ 再思考，最经典的单 Agent 循环，自己干到底
2. Plan-and-Execute。先生成完整计划，再逐步执行，中途可重规划。Claude Code 的 Plan Mode 就是这个思路，先对齐再动手
3. 多 Agent 协作。主 Agent 统筹，子 Agent 负责专项任务，搜索、写代码、审查各司其职，适合专业分工。像 oh-my-pi 这类工程级 Harness，已经把这种模式做成了产品能力，主 Agent 派生侦察、编码、评审等专职子 Agent，各自在隔离工作区干活，最后统一合并
4. 任务图（Task Graph）调度。把任务拆成 DAG，有并行、有依赖，像 CI/CD 流水线一样执行，适合确定性流程

Loop 设计要处理四类问题，缺一个都会在长跑中出事。

• 停止条件。不能只依赖「Agent 声明自己做完了」，需要可验证的完成标准，跑完不等于做完
• 异常结束。中途遇阻后，是重试、停止还是等待人工介入？提前定义，别让 agent 现场随机决策
• 资源上限。限制执行轮次或实际运行时间，防止 Agent 无限循环烧 token
• 运行记录。保留可追溯的逐轮日志，否则执行偏离后很难回溯

最小可用的 Agent Loop，就这么几行。

for step in range(max_steps):
    调用模型 → 判断类型 → 执行工具或返回结果

先跑通这个循环，再往上加模式。

四、第四层：状态与记忆层

Agent 得记得自己是谁、做过什么、还要做什么。

这是 Agent 和普通 Chatbot 最本质的区别，Agent 有状态。Chatbot 问完就忘，Agent 得带着任务上下文往前走。

三类记忆，生命周期完全不同，别混。

类型	作用	生命周期
工作记忆 (Working Memory)	记录当前任务状态、执行到哪一步、中间变量	当前任务
会话记忆 (Session Memory)	记录多轮对话历史	单次会话
长期记忆 (Long-term Memory)	跨会话的知识、偏好、经验	持久化

三个设计要点。

• 独立管理当前任务状态与长期记忆，避免状态混淆。把一次任务的临时变量写进长期记忆，下次任务全串味
• 任务中断后具备恢复能力，靠状态持久化兜底，进程重启任务能续跑
• 跨轮聚合的 Token、费用和总耗时等预算机制，单轮看没问题，累计起来才吓人

五、第五层：评估与观测层

Agent 如何知道自己做对了没有？

没有观测就没有改进的可能。这一层让 Agent 的行为可观测、可对比、可审计，是「做得好不好」的唯一证据来源。

要捕捉的信号有四类。

• 执行轨迹。每一步的输入、输出、工具调用，全量留痕
• 成功信号。任务完成的标准是否达成，与第三层的可验证完成标准一一对应
• 失败模式。什么情况下会出错、为什么出错，错误才是改进的入口
• 成本与延迟。Token 消耗、响应时间、费用，性能预算靠它算

工程实践三条。

• 建立独立于生成过程的验证机制，让生成模型自己给自己打分，等于让考生自己批卷子
• 每次工具调用记录参数、结果、耗时、错误，一条不落
• 支持全链路追踪（trace id 贯穿整个执行过程），出问题一条线拉到底

六、第六层：约束、验证与恢复层

出错时怎么办？

这一层是 Harness 的最后防线。预设规则进行拦截，失败时提供重试、回滚或降级方案。四个机制。

• 权限分级。危险动作不可控？用 approval policy 拦截。DeepSeek Harness 中，工具调用、文件访问、Shell 执行都可以配置独立的审批策略，粒度细到每一类动作
• 错误恢复。Agent 报错后，是重试、回滚还是降级？提前定义，按错误类型分派，别一刀切
• 护栏机制。输入输出校验、成本上限、轮次上限，防止 Agent「跑飞」
• 永不复现。每次 Agent 犯错，都把解决方案工程化，确保未来不再犯同样的错误

Mitchell Hashimoto（Terraform 作者）对 Harness Engineering 的定义，我抄在笔记开头：

「每当 Agent 犯了一个错误，你就花时间设计一个解决方案，使得 Agent 在未来不会再犯同样的错误。」

七、实施优先级建议

不是所有项目都需要一开始就搭六层，按成熟度分三档推进。

优先级	层级	说明
P0（先做）	L1（上下文）+ L6（约束与恢复）	先让 Agent 知道该做什么，再设置出错时的拦截与恢复机制。投入最低、见效最快
P1（P0 稳定后）	L2（工具）+ L4（状态）+ L5（评估）	分层上下文管理、Agent 的端到端验证能力
P2（有余力时）	L3（编排）及进阶能力	Agent 专业分工、多 Agent 协作、定期垃圾回收

先做 P0 的两个层，跑出稳定基线，再谈编排和分工。

结语

Harness Engineering 是一套让模型能稳定干活的工程实践集合。

模型决定 Agent 的上限，Harness 决定下限，用户体验和商业价值都压在这一侧。同样的模型，能不能稳定交付，差距全在模型之外。

构建顺序就三句话，先让它知道该做什么，再让它犯错后能恢复，最后再让它变得更聪明。从第一层上下文管理开始，一步步把下限抬起来。

参考阅读：Lilian Weng《Harness Engineering for Self-Improvement》（lilianweng.github.io/posts/2026-07-04-harness/）· DeepSeek AI《DeepSeek Harness（dsh）》（github.com/deepseek-ai/deepseek-harness）· MemoHarness《Agent Harnesses That Learn from Experience》（arXiv:2607.14159）· oh-my-pi（Pi）《Coding agent with the IDE wired in》（github.com/can1357/oh-my-pi）

---