一文讲透如何构建Harness——六大组件全解析

一句话概括

系统讲解如何构建 AI Agent Harness（智能体运行框架），将其拆解为六大核心组件进行逐一解析。

实践内容

核心公式：Agent = Model + Harness

• Model 是大脑，负责”想”；Harness 是模型之外的一切工程基础设施，负责让”想”变成”做”
• Harness 英文原意是”挽具”——套在马身上、让马的力量转化为拉车动力的装备

裸模型四大硬伤与 Harness 对应组件

硬伤	缺失的能力	Harness 对应组件
无法维持跨会话状态	长期记忆	文件系统 + 记忆（AGENTS.md）
无法执行代码	行动能力	Bash + 沙箱
无法获取实时知识	感知能力	Web Search + MCP
无法搭建工作环境	环境操控	文件系统 + 上下文工程 + 编排

六大组件详解

组件一：文件系统

• Agent 的”外部大脑”，突破上下文窗口限制的唯一途径
• 三大核心能力：工作空间与中间结果存储、Agent 协作基础（共享白板）、版本追踪与错误回滚（Git 集成）
• 设计原则：目录结构清晰约定俗成、文件粒度适中、元数据丰富

组件二：Bash + 沙箱

• 核心能力：自我验证循环（写→跑→看→修→再来）
• 测试数据：具备自我验证循环的 Agent 任务完成率比”一次性生成”高出 40%-60%
• 沙箱方案：Docker 容器（最主流）、gVisor/Firecracker（轻量）、WebAssembly、Nix
• 沙箱四大保障：资源限制、网络隔离、文件系统隔离、超时机制

组件三：记忆（AGENTS.md）

• 核心理念：工作中写入知识，存文件，下次自动注入——不改权重给模型加知识
• 工作机制：写入阶段→存储阶段→注入阶段
• 最佳实践：层次化存放（根目录全局/子目录局部）、结构化书写、定期清理、双向可编辑（人与 Agent 的”知识契约”）

组件四：Web Search + MCP

• Web Search 解决查询构建、结果筛选、内容提取、信息整合四个问题
• MCP（Model Context Protocol）= AI 世界的 USB 接口，将感知范围从公开互联网扩展到任何可编程数据源
• 协同效应示例：修复生产 Bug → MCP 获取错误日志 → MCP 查看代码变更 → Web Search 搜社区方案 → MCP 检查已知问题 → 生成修复方案

组件五：上下文工程

• 对抗 Context Rot（上下文腐烂）：信噪比下降、矛盾信息累积、Token 浪费、推理质量退化
• 核心策略：压缩（摘要替换冗长记录）、工具输出卸载（存文件保留摘要）、Skills 渐进加载、分层上下文结构（核心层/工作层/历史层）
• “上下文工程”正在取代”Prompt 工程”成为 AI 工程核心话题

组件六：编排 + Hooks

• 编排解决：子 Agent 调度、任务分发、模型路由（成本与质量平衡）、结果聚合
• 编排模式演进：线性管道→DAG 编排→动态编排→层级编排
• Hooks = 概率性生成 + 确定性校验：Lint 检查、续接（截断自动补全）、格式约束、安全过滤、成本控制

System Prompt：贯穿所有组件的”神经系统”

• 四个角色：定义角色边界、注入领域知识、约束安全规则、贯穿所有组件
• System Prompt 装”必须知道的”，AGENTS.md 装”最好知道的”

摘录

我花了三个月调 Prompt，模型回答质量提升了 20%。然后我花了两周搭 Harness，整体任务完成率从 35% 飙到了 82%。这条动态下面，点赞最高的评论只有四个字：方向错了。

Agent = Model + Harness。模型提供智能，Harness 让智能变得有用。这不是一个新概念，但它正在成为 2026 年 AI 工程领域最核心的共识。

没有文件系统，Agent 必须把所有中间产物都塞进上下文窗口——这既浪费 token，又容易超出上下文长度限制。有了文件系统，Agent 可以把中间产物写入文件，需要时再读取，实现”按需加载”。

没有 Bash，Agent 是一个”提建议”的顾问；有了 Bash，Agent 是一个”动手做”的工程师。在编程任务中，具备自我验证循环的 Agent 的任务完成率比”一次性生成”的方式高出 40%–60%。

AGENTS.md 提供了一条捷径：不碰模型权重，只通过上下文注入来添加知识。模型仍然是原来的模型，但它”看到”的信息变了，因此它的行为也变了。这就像是一种”即插即用”的知识扩展机制。

Context Rot 不是一个理论问题，它是每一个长时间运行的 Agent 都会遇到的实际挑战。一开始 Agent 的表现很好，但随着对话变长，它开始”变笨”——遗忘之前的约定，重复之前犯过的错误。

Hooks 的核心价值在于：它们用确定性的规则约束了概率性的模型输出。这种”概率性生成 + 确定性校验”的组合模式，是当前 Agent 工程中最有效的质量保障策略之一。

模型决定了 Agent 能力的下限，Harness 决定了 Agent 能力的上限。模型会继续进步，但进步的速度在放缓。与此同时，Harness 的工程空间还几乎没有被充分探索。

涉及实体

• Harness —— AI Agent 运行框架，本文核心讨论对象

涉及主题

• AI Agent Harness
• Agent 架构设计
• Prompt Engineering