从零搭建 Agent Harness 系列（一）为什么要做、做什么、怎么做

随着AI Agent的发展，关于如何开发出一个工业级可用的Agent慢慢有了一些共识和雏形，目前的集大成者和大家都比较认可的就是Harness，所以我也通过一些实践，总结一些心得。

Agent 开发的“三大失控摩擦力”

1. 上下文失控：我们盲目地给模型塞入几十个工具描述，却不知道大模型的注意力会被这些冗长的系统设定严重稀释，导致“降智”和幻觉。

2. 状态失控：传统的框架在内存中维护着极其复杂的隐式状态机。一旦对话轮数过多，模型就会得“健忘症”；一旦遇到顽固报错，模型就会陷入死循环（Doom Loop）。而由于状态被框架封装在黑盒里，人类开发者根本无法在中途介入干预。

3. 边界失控：我们既希望 Agent 拥有改变物理世界的能力（执行代码、修改文件），又缺乏底层的物理拦截机制。大模型的“冲动”一旦越界，就是灾难。

这些摩擦力的存在，让我们意识到：单纯靠堆砌 Prompt 或者调用更高层级的应用框架，是永远无法构建出工业级 Agent 的。那么，真正的解法，究竟是什么？

框架正在坍塌，Harness（驾驭工程）正在崛起

要理解这场架构革命的深刻性，我们必须清晰地看到 AI Agent 演进的一条底层暗线。在深入剖析了当今业界最顶尖的原生 Coding Agent（如 Anthropic 的 Claude Code 以及备受瞩目的开源项目 OpenClaw）后，我得到了一个极其深刻的行业洞见：

The Framework Layer is Collapsing into the Harness.

传统的应用框架层正在加速坍塌，并逐渐融入底层的驱动工程中。在早期，由于大模型逻辑推理能力弱，我们需要用厚重的 Framework 去帮它做意图识别、路由分发。框架扮演的是一个“事无巨细的微管家”。

但今天，面对 GPT-5.2 或 Claude 4.6 Sonnet 这样极其聪明的模型，它们原生就具备了顶级的规划（Planning）和工具调用（Function Calling）能力。

此时，“微管家”式的框架反而成了阻碍。我们需要的不再是教模型“怎么想”的抽象层，而是一个为模型提供健壮物理躯体和生存环境的底层引擎——这就是 Harness（驾驭工程）。

在LLM出现之前，系统（广义的系统，而非信息系统）中的确定性会变为流程，变成框架，不确定性由人来兜底。但是LLM的出现，它这种基于大语言数据的概率模型，让其表现出了在纯语义层面较为可靠的判断能力，所以理论上只要我们能将所有已知各种模态，各种来源的信息转为语言形式，交给大模型去做纯语义层面的较为可靠的判断，再将这些纯语义的判断重新输出为各种其他流程或者框架或者人类可以理解和执行的内容。

Harness 的本质，就是为大模型写一个微型操作系统（OS）。在这个 OS 里，大模型是 CPU，上下文窗口是极其珍贵的 RAM（内存），各种本地操作是外设（硬件）。Harness 不干涉 CPU 的计算，但它必须极其严苛地管理内存回收（上下文压缩）、调度硬件接口（极简工具集）、并随时准备触发系统中断（拦截高危操作与死循环）。大模型（CPU）决定了智力（算力）的上限，而 Harness （OS）决定了这套智力在现实世界中能发挥出几成。

Harness的核心哲学就是将推理交给LLM，相信只要给LLM提供可靠的输入token和安全边界，它就可以得到正确的结果。系统只负责将各种来源各种形式的数据变为token，然后将LLM推理出来的token交给可以理解它的外界环境。从这个曾面讲，Observability&Evaluation， Action & Tools 这些才是Harness的产物，Context Engineering 只是因为上下文窗口有限的现实限制所产生的，不是Harness这个理想模型本身的必然产物

注：Harness 原意为“马具 / 缰绳”，Harness Engineering 是指通过构建受控环境，包括设计和构建约束机制、反馈回路、工作流控制和持续改进循环等，让 AI 在约束下高效可靠地工作。国内多译为“驾驭工程”或“管控工程”，这里使用“驾驭工程”这种译法。

当 AI 拥有了强大的原生推理和行动能力，我们的角色将从一个“调包侠”或“Prompt 裱糊匠”，蜕变为整个 AI 物理法则的“设计者”与“驾驭者”。你将花更多的时间思考：

• 如何设计一个像 OS GC（垃圾回收）一样的阶梯掩码算法，在不丢失模型意图的前提下，榨干最后一点 Token 空间？
• 如何在底层构建一个安全的防线，让大模型在发疯执行 rm -rf 时被精准拦截？
• 如何为引擎建立科学的链路追踪（Tracing）和自动化度量（Benchmark）体系，用数据证明你的 Agent 真的变聪明了？

我们不再是黑盒框架的使用者，而是成为了构筑 AI 世界秩序的系统架构师。

Harness Agent 的几个部分

1. 认知与核心引擎（The Core Engine）我们将抛弃黑盒，纯手写大模型原生的 ReAct 循环。设计优雅的多模型适配层（接入 Claude 与 OpenAI 兼容 API 模型），并前瞻性地引入独立的“慢思考（Thinking）”机制，极大提升复杂任务的规划成功率。

2. 极简工具与物理交互（Action & Tools）打造强扩展性的 Tool Registry。深刻贯彻极简工具哲学。手写支持多级模糊匹配的健壮 Edit 工具，并利用 Go 的并发特性压榨出并行工具执行的性能极限。

3. 上下文工程体系（Context Engineering）这是决定 Agent 智商的生命线。我们将实现系统提示词的动态组装、超长文本的阶梯降级压缩（Compaction）；更重要的是，摒弃复杂的内部状态机，把“记忆”与“待办”完全外部化为本地的文件系统。

4. 稳定性控制与多智能体（Safety & Coordination）让 Agent 走向生产环境。实现运行时提醒（Reminders）斩断死循环；通过 Middleware 拦截危险操作，在飞书中弹出卡片等待人类审批（Human-in-the-loop）；引入 Subagent 隔离复杂任务。

5. 可观测性与科学度量（Observability & Evaluation）这是高级工程师的分水岭。为引擎引入链路追踪（Tracing）、成本审计，并搭建自动化 Benchmark 评估脚本，科学量化引擎的每一次进步。

Harness（驾驭工程）：极简的动态运行时

随着 Claude 3.5 Sonnet、GPT-4o 等前沿模型的问世，大模型本身已经进化成了一个拥有极强自主规划能力的 CPU。它不需要你用代码去规定“先执行 A，再执行 B”。它只需要你给它一个包含当前状态的上下文（Context），并告诉它“这里有几个工具”，它就能自主推导出下一步该干什么。

基于这个前提，Harness（驾驭工程）应运而生。它不再是一个定义业务逻辑的图结构，而是一个极简的、动态的运行时环境（Runtime Environment）。

在 OpenClaw 等现代底层引擎中，架构被极大地拉平了。它抛弃了 DAG，转而回归了计算机科学中最古老也最可靠的结构：一个无限循环（Main Loop）+ 一组事件驱动的拦截器（Interceptors/Middlewares）。

对比两张图，你可以清晰地看到 Harness 的三大革命性转变：

1. 控制反转（IoC）：业务流程的控制权从“Go/Python 代码”完全转移到了“大模型的实时推理和规划”中。代码只提供物理定律（如文件读写和编辑、沙箱执行等），不干涉任务走向。

2. 防线前移：既然大模型是自由的，它就可能犯错或搞破坏。因此 Harness 的核心代码全部集中在了 Middleware（防止搞破坏）和 Compactor（防止内存被撑爆）上。

3. 状态透明：循环只依赖一个单一的数据结构——也就是不断累加的 Context 消息列表。没有任何隐式的树节点或图节点变量。

架构分层解析:

1. 入口交互层：引擎对外的触角。我们将支持终端命令行（CLI）输入，并将其接入飞书。更重要的是，这一层包含了人工审批（Human-in-the-loop）的异步回调机制。

2. 核心引擎层（心脏）：系统的控制中枢。Main Loop 负责维持 ReAct 循环。旁边的大模型适配器是“大脑接口”，抹平不同大模型（如 Claude 和 OpenAI 兼容）底层 API 的差异。新增的 Thinking 模块则负责在行动前强制模型进行慢思考。

3. 上下文工程层（内存管理器）：决定 Agent 能够跑多远的关键。
   a. Prompt 动态组装器：动态拼装模块化的系统规则（如读取 AGENTS.md）。

   b. Token 监控与阶梯压缩器：像 OS 的内存回收器一样，时刻盯着 Token 水位线触发压缩。

   c. 运行时事件提醒注入：是防走神的利器，在模型做决定的前一刻注入干预指令。

4. 基于文件系统的状态与记忆则是极简哲学的核心——抛弃内部变量，直接把进度写在本地 TODO.md 里。

5. 工具与执行层（四肢与手脚）：挂载了让模型改变物理世界的组件。动态的 ToolRegistry 配合极简工具集（read/write/edit/bash），让模型组合出无限可能。强大的 Middleware 机制则死死把守大门，拦截危险命令并对接审批。