Agent Harness 知识体系

2026 年初，OpenAI、Anthropic、LangChain、Thoughtworks、HumanLayer 等机构几乎在同一时间收敛到同一个核心洞察：AI Agent 的可靠性，更多取决于包裹在模型外围的系统（Harness），而非模型本身。^[1][2]

这一洞察彻底改变了工程团队的注意力分配：当智能体表现不佳时，团队不再本能地归因于"模型不够强"，而是审视 Harness 是否规范、上下文是否被浪费、工具是否清晰、反馈回路是否有效。OpenAI 内部用三人的工程团队、零行手写代码交付了约一百万行代码的产品，其核心经验正是：人类掌舵，智能体执行，而 Harness 是让智能体能够可靠工作的全部前提。^[1]

本知识体系以 OpenAI 官方《Harness Engineering》报告^[1]与 LangChain《The Anatomy of an Agent Harness》^[2]为双核心骨架，融合 OpenAI《A Practical Guide to Building Agents》^[3]、Anthropic 工程实践、Thoughtworks 方法论与社区开源生态，形成一套从定义 → 组件 → 工程方法 → 企业落地的完整知识框架，可直接作为搭建 Agent 企业应用知识底座的基础。

1.1 一句话定义

LangChain 的 Vivek Trivedy 给出了最清晰的表述：Agent = Model + Harness。用一句话概括——"如果你不是模型，你就是 Harness"。^[2]

Harness 是智能体中除模型本身之外的一切：每一段代码、每一份配置、每一条执行逻辑。一个裸模型不是智能体；只有当 Harness 赋予它状态、工具执行、反馈回路和可强制执行的约束时，它才成为智能体。

flowchart LR
    subgraph AGENT["Agent 智能体"]
        direction LR
        M["Model 模型
推理 · 决策 · 生成"]
        H["Harness 外围系统
工具 · 上下文 · 记忆 · 护栏 · 编排"]
        M <--> H
    end
    U["用户 / 外部世界"] <--> AGENT
          

1.2 从模型视角推导：模型做不到什么

理解 Harness 各组件存在的原因，最好的方式是从模型的原生能力边界倒推。模型（大多数情况下）只能接收文本、图像、音频、视频，并输出文本——仅此而已。^[2]它开箱即用地无法做到：

• 跨交互维持持久状态——每次对话都是"失忆"的
• 执行代码——无法运行任何程序
• 访问实时知识——知识截止于训练数据
• 搭建环境、安装依赖——无法为完成任务准备运行环境

这些全部是 Harness 层的能力。下表展示了"我们想要的智能体行为 → 模型做不到 → Harness 的解决方案"的完整推导链：^[2]

其中，文件系统是最基础的 Harness 原语——它解锁了其他一切：智能体获得工作区、工作可增量持久化、多个智能体可通过共享文件协作。Git 为文件系统加上版本控制，使智能体可以追踪工作、回滚错误、分支实验。^[2]

1.3 为什么是现在

这是整套知识体系的核心章节。一个生产级 Harness 由以下组件构成，每个组件都对应一个"模型做不到、必须由外围系统补齐"的能力缺口。^[2][6]

flowchart TB
    Agent["Agent 智能体"]
    Model["Model 模型（推理核心）"]

    subgraph HARNESS["Harness 外围系统"]
        direction TB
        P["① 系统提示词与指令
人格 · 约束 · 行为准则"]
        T["② 工具 · 技能 · MCP
可调用的能力"]
        F["③ 文件系统与持久存储
工作区 · Git · 进度文件"]
        C["④ 代码执行与沙箱
Bash · 隔离环境"]
        M["⑤ 记忆与搜索
短期 · 长期 · 检索"]
        X["⑥ 上下文管理
压缩 · 卸载 · 渐进式披露"]
        O["⑦ 编排逻辑
子智能体 · 交接 · 模型路由"]
        K["⑧ 钩子与中间件
确定性控制流"]
        G["⑨ 护栏与安全
审批 · 白名单 · 注入防御"]
    end

    Agent --> Model
    Agent --> HARNESS
    P --> Model
    T --> Model
    F --> Model
    C --> Model
    M --> Model
    X --> Model
    O --> Model
    K --> Model
    G --> Model
          

2.1 系统提示词与指令

塑造智能体人格与约束的指令层。OpenAI 强调高质量指令对智能体至关重要：用现有文档（操作手册、支持脚本、政策文档）生成 LLM 友好的例程；提示智能体拆解任务；为每个步骤定义明确动作；捕获边缘情况。^[3]

实践要点：指令应清晰、无歧义、可执行；可用 o1 / o3-mini 等高级模型从现有文档自动生成指令；使用提示词模板（单一灵活的基础提示词 + 策略变量）替代大量独立提示词，显著简化维护与评估。^[3]

2.2 工具、技能与 MCP

工具是智能体与外部世界交互的接口。OpenAI 将智能体需要的工具分为三类：^[3]

每个工具应有标准化定义，支持工具与智能体之间灵活的多对多关系。工具描述会被注入系统提示词，因此清晰、准确、经过测试、可复用的工具能显著提升智能体的调用正确率。^[3]

技能（Skills）是 Harness 层的原语，通过渐进式披露解决"启动时加载过多工具/MCP 导致性能退化"的问题——技能按需激活，只在需要时带来聚焦的知识。^[2]MCP（Model Context Protocol）是工具的标准协议，让工具可发现、可复用、可跨智能体共享。

2.3 文件系统与持久存储

文件系统是最基础的 Harness 原语：智能体获得工作区、工作可增量持久化、中间输出可卸载出上下文、状态可跨会话存续。文件系统还是自然的协作面——多个智能体与人类可通过共享文件协调（Agent Teams 架构依赖于此）。Git 增加版本控制，使智能体可追踪工作、回滚错误、分支实验。^[2]

2.4 代码执行与沙箱

主流的智能体执行模式是 ReAct 循环（推理 → 行动 → 观察 → 循环）。但 Harness 只能执行它拥有逻辑的工具，因此更优方案是给智能体一个通用工具（如 Bash），让模型通过编写并执行代码自主解决问题——这是"给模型一台计算机"的关键一步。代码执行已成为自主问题求解的默认通用策略。^[2]

所有代码执行都需要发生在沙箱中：隔离环境、按需创建、任务完成即销毁；更严格的安全措施包括命令白名单与网络隔离。沙箱同时解锁了规模——环境可按需扇出到大量任务。^[2]

2.5 记忆与搜索

模型除权重和当前上下文外没有额外知识，唯一"增加知识"的方式是上下文注入。记忆的基元仍是文件系统：AGENTS.md 等记忆文件标准在智能体启动时注入上下文，智能体编辑后 Harness 将更新后的文件重新加载——这是一种持续学习形式。为弥补知识截止，Web 搜索与 MCP 工具（如 Context7）帮助智能体访问训练截止后的信息。^[2]

2.6 上下文管理

上下文是稀缺资源，Harness 本质上是"好的上下文工程的交付机制"。核心策略包括：压缩（上下文窗口将满时智能卸载与总结）、工具调用卸载（保留大输出的头尾 token，完整输出转存文件系统）、技能（渐进式披露保护模型免受上下文腐烂）。详见第 3 章。^[2]

2.7 编排逻辑

子智能体生成、交接（handoff）、模型路由等控制逻辑。编排模式分为单智能体系统与多智能体系统两大类，详见第 5 章。^[3]

2.8 钩子与中间件

为压缩、续跑、lint 检查、验证等提供确定性控制流的钩子与中间件。例如 Ralph Loop 通过钩子拦截模型的退出尝试，在干净的上下文窗口中重新注入原始提示，迫使智能体继续工作。^[2]

2.9 护栏与安全

审批策略、命令白名单、网络隔离、提示注入防御等安全机制。详见第 4 章。^[3]

上下文工程是把智能体的上下文窗口当作"工作记忆预算"来管理，而非当作垃圾倾倒场。它是 Harness 工程中最关键的实践。^[6]

3.1 上下文是稀缺资源

OpenAI 在实践中深刻体会到"一个巨型 AGENTS.md"的反模式：^[1]

• 上下文是稀缺资源——巨大的指令文件挤掉任务、代码和相关文档
• 过多的指导反而无效——当一切都"重要"时，一切都不重要了
• 它会立即腐烂——庞杂手册变成陈旧规则的坟场
• 难以核实——单个大文件不适合机械检查（覆盖率、新鲜度、所有权）

结论：给智能体一张地图，而不是一本 1000 页的说明书。^[1]

3.2 上下文腐烂（Context Rot）

Chroma 的研究提供了实证：模型在更长的上下文长度下表现可测量地更差，且当查询与上下文中的相关信息语义相似度低时，退化更陡峭。^[7]这意味着"更大的上下文窗口"并不能让模型更好地找到"针"——只是让"干草堆"更大。

3.3 渐进式披露（Progressive Disclosure）

渐进式披露是上下文工程的核心原则：智能体只在真正需要时才获得特定的指令、知识或工具。一次性加载所有内容会把智能体推入 HumanLayer 所称的"愚蠢区"——上下文窗口被填满导致即使简单任务也性能退化。^[4]

OpenAI 的实践：将 AGENTS.md 视为内容目录（约 100 行），指向结构化 docs/ 目录中的深层权威信息源。智能体从小而稳定的切入点开始，被指导"下一步该去哪里查看"。^[1]

3.4 压缩与工具调用卸载

压缩（Compaction）解决"上下文窗口将满时怎么办"：智能地卸载并总结现有上下文，使智能体可以继续工作。关键原则是全局状态信息（任务规划、子智能体状态、工具权限授权记录）必须保证不被压缩。^[8]

工具调用卸载（Tool call offloading）降低大工具输出对上下文的噪声污染：保留超过阈值 token 的工具输出的头尾，完整输出转存文件系统，模型需要时可访问。^[2]

3.5 子智能体作为上下文防火墙

子智能体提供上下文隔离：每个子智能体获得一个全新的、小的、高相关性的上下文窗口，只有浓缩后的结果流回父智能体。这比单纯扩大上下文窗口强大得多——"更大的上下文窗口不会让模型更擅长找针，只是让干草堆更大"。^[6]

3.6 上下文高效背压

HumanLayer 的背压哲学：验证机制必须上下文高效。每次变更后运行完整测试套件会向上下文窗口倾倒数千行通过的测试，智能体将失去对实际任务的追踪。规则是：成功静默，只有失败产生输出——吞掉通过检查的输出，只暴露错误。^[4]

4.1 强制执行不变量，而非微观管理

OpenAI 的核心方法：在中央层面强制执行边界，在本地层面允许自主权。^[1]他们要求 Codex 在边界处解析数据形状（"parse, don't validate"），但不规定实现方式。每个业务域遵循固定的分层架构（Types → Config → Repo → Service → Runtime → UI），依赖方向由自定义 linter 和结构测试机械强制。

关键技巧：自定义 linter 的错误信息被写成向智能体上下文注入修复指令——一种"正向的提示注入"，引导智能体自我修正。^[1]

4.2 沙箱与受控执行

Anthropic 的沙箱工作聚焦于在减少审批摩擦的同时不失去控制：更好的沙箱与策略设计让智能体在安全边界内更自主地工作。基于 MCP 的代码执行通过显式、可检查的工具边界赋予受控执行能力——明确智能体能与不能做什么。^[9]

4.3 工具设计安全

Anthropic 强调：工具接口应易于模型正确且安全地调用。设计不良的工具导致误用；设计良好的工具引导智能体走向正确行为。工具描述、参数设计、错误处理都是安全设计的一部分。^[10]

4.4 提示注入防御

OpenHands 的实践指南覆盖确认模式、分析器、沙箱化与硬策略，以降低提示注入风险。特别重要的是：MCP 服务器工具描述会被注入系统提示词——绝不连接不信任的 MCP 服务器。^[11]

4.5 质量检查进入循环

Thoughtworks 主张将质量检查移入智能体自身的循环，而非事后人工审查。通过将智能体锚定到参考应用来约束输出。人类的问题从"如何审查每一行"转变为"我应该在何处加强 Harness？"。^[12]

编排模式决定智能体如何执行工作流。OpenAI 将编排模式分为两大类：单智能体系统与多智能体系统。^[3]

5.1 单智能体系统

单个模型配备合适的工具与指令，在循环中执行工作流。核心是"run"的概念——一个 while 循环，让智能体运行直到退出条件达成（调用最终输出工具、模型返回无工具调用的响应、错误、或达到最大轮数）。^[3]

OpenAI 的通用建议：先最大化单个智能体的能力。更多智能体提供概念分离，但也引入额外复杂度与开销。当提示词包含大量条件分支、或工具数量过多且相似重叠时，才考虑拆分。

5.2 多智能体系统

多智能体系统可建模为图：智能体是节点。两种广泛适用的模式：^[3]

flowchart TB
    subgraph MGR["Manager 模式（智能体作为工具）"]
        direction LR
        M["Manager 智能体"] --> A1["专业智能体 A"]
        M --> A2["专业智能体 B"]
        M --> A3["专业智能体 C"]
    end
    subgraph DEC["去中心化模式（智能体间交接）"]
        direction LR
        D1["智能体 A"] -->|"handoff"| D2["智能体 B"]
        D2 -->|"handoff"| D3["智能体 C"]
    end
          

5.3 ReAct 循环

当前主流的智能体执行模式：模型推理（Reason）→ 通过工具调用行动（Act）→ 观察结果（Observe）→ 循环。^[2]

flowchart LR
    Start["用户请求"] --> Reason["推理 Reason
决定下一步"]
    Reason --> Act["行动 Act
调用工具"]
    Act --> Observe["观察 Observe
读取工具结果"]
    Observe --> Reason
    Observe --> Done{"任务完成?"}
    Done -->|"否"| Reason
    Done -->|"是"| Output["最终输出"]
          

5.4 Ralph Loop（长时程续跑）

Ralph Loop 是一种 Harness 模式：通过钩子拦截模型的退出尝试，在干净的上下文窗口中重新注入原始提示，迫使智能体继续针对完成目标工作。文件系统使其成为可能——每次迭代从新上下文开始，但读取上一次迭代的状态。^[2]

OpenAI 团队正是用这种模式让 Codex 在单个任务上持续工作超过六小时（通常在人类睡眠时间），并驱动"智能体对智能体"的审查循环。^[1]

6.1 短期记忆与长期记忆

企业级智能体系统需要两类记忆：^[13]

6.2 AGENTS.md 与智能体文件

AGENTS.md 是轻量开源格式，用于仓库本地指令，告诉智能体如何在代码库内工作。实践者共识：^[6]

• 保持简洁——60 行以下是好目标
• 避免自动生成——LLM 生成的智能体文件反而损害性能且多花 20%+ token
• 不包含目录列表——智能体自己就能发现仓库结构
• 使用渐进式披露——指向深层资源而非内联一切
• 指令普遍适用——避免让模型困惑的条件规则

6.3 文件系统作为记忆基元

记忆的基元是文件系统：智能体将知识从一个会话持久存储，并在未来会话注入——这是持续学习的形式。进度文件、Git 历史、结构化知识库共同构成智能体的"外部大脑"。^[2]

6.4 企业知识库与记忆

在企业场景中，长期记忆应沉淀用户偏好、业务规则、历史结论。框架后台周期性把"流水账"蒸馏为结构化知识。知识库（向量检索 + 知识图谱）与记忆系统配合，为智能体提供企业事实与源文档。^[8][14]

7.1 智能体可读性

OpenAI 的核心经验：目标是智能体的可读性。从智能体的角度看，运行时无法在上下文中访问的任何内容都是不存在的——存在 Google Docs、聊天记录或人脑中的知识都无法被系统访问。仓库本地的、已版本化的工件（代码、Markdown、模式、可执行计划）就是它所能看到的全部。^[1]

因此，需要把越来越多的人类决策（架构共识、产品原则、工程规范）推送到仓库中，以智能体可推理的形式组织与展示。

7.2 追踪、日志与指标

OpenAI 将可观测性工具直接暴露给智能体：日志、指标、追踪通过本地可观测性堆栈展示给 Codex，智能体可用 LogQL 查询日志、用 PromQL 查询指标。这让"确保服务在 800ms 内启动"、"四个关键用户旅程的任何跨度不超过两秒"这类提示变得可行。^[1]

智能体还通过浏览器自动化（DOM 快照、截图、导航）复现错误、验证修复、直接推理 UI 行为——形成自我验证回路。

7.3 Evals 与基准测试

评估是 Harness 工程的基石：建立性能基线 → 用最佳模型满足准确率目标 → 用更小模型优化成本与延迟。^[3]基准测试（如 Terminal-Bench 2.0）衡量的往往是 Harness 质量——LangChain 仅改 Harness 就从 Top 30 升到 Top 5。^[2]

7.4 Harness 质量度量

Thoughtworks 提出三种 Harness 调节维度：^[12]

本章是"用于搭建 Agent 企业应用知识底座"的直接落地方案，以 OpenAI 的实证案例为主线。

8.1 OpenAI 实证案例

OpenAI 团队从空 Git 仓库开始，五个月内交付约一百万行代码、约 1500 个 PR，全程零行手写代码，平均每人每天 3.5 个 PR，且团队从 3 人扩到 7 人后吞吐量反而增加。^[1]关键经验：

• 早期进展慢是环境规范不足，不是模型能力问题
• 人类工程师的工作从"写代码"转向"设计环境、明确意图、构建反馈回路"
• 遇到困难时的标准追问："究竟还缺什么能力？如何让这个能力对智能体既清晰可读又可强制执行？"

8.2 渐进式披露的知识库结构

这是知识底座的核心模式。OpenAI 将 AGENTS.md 视为内容目录（约 100 行），指向结构化 docs/ 目录：^[1]

配套机制：专职 linter 和 CI 作业验证知识库的更新状况、交叉链接与结构正确性；定期运行的"doc-gardening"智能体扫描过时文档并发起修复 PR。^[1]

8.3 规范架构与品味

仅靠文档无法保持智能体生成代码库的连贯性。企业落地需要：^[1]

• 强制执行不变量：分层架构 + 严格依赖方向 + 自定义 linter + 结构测试
• 品味不变式：结构化日志、命名约定、文件大小限制、平台可靠性要求
• 人类品味反馈到系统：审查评论、重构 PR、用户 Bug 被记录为文档更新或编码到工具中

8.4 熵与垃圾回收

完全自主的智能体也会引入新问题：智能体会复现仓库中已有的模式——包括不均衡或不理想的模式，导致漂移。OpenAI 的解决方案：^[1]

• 将"黄金原则"直接编码到仓库（机械规则，保持可读性与一致性）
• 建立循环清理流程：定期运行后台智能体任务，扫描偏差、更新质量等级、发起针对性重构 PR
• 功能类似垃圾回收：技术债务像高息贷款，持续小额偿还优于痛苦的一次性清偿

8.5 吞吐量改变工程理念

当智能体吞吐量远超人类注意力时，传统工程规范需要调整：尽量减少阻塞合并门、PR 生命周期短、偶发测试失败通过重跑解决。在低吞吐量环境中这样做不负责任，但在智能体驱动的系统中，纠错成本低、等待成本高。^[1]

9.1 主流 Harness 实现

9.2 MCP 与工具生态

MCP（Model Context Protocol）是工具与上下文的标准协议，让工具可发现、可复用、可跨智能体共享。企业构建知识底座时，应将内部系统（CRM、数据库、文档库、工单系统）封装为 MCP 服务器，形成统一的工具层。^[2][15]

9.3 选型框架

• 起步：用最成熟的框架（OpenAI Agents SDK / LangGraph）快速搭建原型，用最强模型建立性能基线
• 演进：先最大化单智能体能力，再按需拆分多智能体
• 关键判断：不追求"最像模型的 Harness"，而是针对你的任务优化 Harness——同一个模型在不同 Harness 中表现差异巨大^[2]

10.1 模型训练与 Harness 设计的耦合

今天的智能体产品（Claude Code、Codex）在训练时就把模型与 Harness 放在循环中，帮助模型提升在 Harness 设计者认为应原生擅长的动作上的能力（文件系统操作、Bash 执行、规划、子智能体并行）。这形成反馈回路：有用的原语被发现 → 加入 Harness → 用于训练下一代模型。^[2]

但耦合也有副作用：改变工具逻辑会导致模型性能下降（如 Codex 的 apply_patch 工具逻辑变化）。最适合你任务的 Harness，未必是模型后训练所用的那个。^[2]

10.2 Harness 能力被模型吸收

随着模型能力增强，今天 Harness 中的一部分会被模型原生吸收（规划、自我验证、长时程一致性）。但正如提示工程至今仍有价值，Harness 工程将继续有用——一个配置良好的环境、正确的工具、持久状态与验证回路，会让任何模型更高效，无论其基础智能如何。^[2]

10.3 开放问题

• 在共享代码库上并行编排数百个智能体
• 智能体分析自身 trace，识别并修复 Harness 层故障模式
• Harness按需动态装配正确的工具与上下文，而非预先配置
• 完全由智能体生成的系统中，架构连贯性如何随时间演变