---
source_url: "https://mp.weixin.qq.com/s/yOX1QZTHs54J-CBg-rKUig""
ingested: 2026-06-26
sha256: c2a728bb712b078d
---
sha256: 4f89360f9f8e1cbc
---
source_url: "https://mp.weixin.qq.com/s/yOX1QZTHs54J-CBg-rKUig"
original_url: "https://x.com/akshay_pachaar/status/2041146899319971922"
title: "深度拆解：AI 智能体 Harness 的构造【译】"
author: "宝玉AI（编译自 Akshay Pachaar）"
published: 2026-01-01
created: 2026-05-19
type: article
platform: wechat
tags: [AI-Agent, harness, LangChain, claude-code, OpenAI, anthropic, Agent-Framework, ReAct, Tool-Use, Memory, context-management, State-Management, Error-Handling, Guardrails, Verification, Subagent, LangGraph, CrewAI, AutoGen, TerminalBench, Scaffolding]
  - AI-Agent
  - Harness
  - LangChain
  - Claude-Code
  - OpenAI
  - Anthropic
  - Agent-Framework
  - ReAct
  - Tool-Use
  - Memory
  - Context-Management
  - State-Management
  - Error-Handling
  - Guardrails
  - Verification
  - Subagent
  - LangGraph
  - CrewAI
  - AutoGen
  - TerminalBench
  - Scaffolding
entities:
  - ai-agent-harness
  - anthropic-claude-code
  - openai-agents-sdk
  - langchain
  - langgraph
  - react-pattern
  - tool-use
  - memory-management
  - context-window
  - verification-loop
  - subagent-orchestration
  - moss-reid-llm三层记忆
  - verify-loop
  - context-compaction
  - observation-masking
  - checkpointing
  - llm-as-judge
  - openai-codex
  - crewai
  - autogen-microsoft
  - scaffolding-principle
sha256: "46ef308a57c52bc6148e2a86248dd72f9c47875a5a7a18559e4c26412d2ea07b"
rating: 8.5/9.0
review_value: 8.5
review_confidence: 9.0
review_result: strong
---
# 深度拆解：AI 智能体 Harness 的构造【译】
> 原文：https://x.com/akshay_pachaar/status/2041146899319971922
> 编译：宝玉AI
## 什么是 Agent Harness？
虽然这个术语在 2026 年初才正式确立，但其核心理念早已存在。**Harness** 是包裹在大语言模型之外的完整软件架构：它包括编排循环、工具、记忆、上下文管理、状态持久化、错误处理和护栏（Guardrails）。
LangChain 证明了这一点：他们仅仅通过改变包裹大语言模型的底层架构——模型没变，参数没变——就让系统在 TerminalBench 2.0 上的排名从 30 名开外飙升到了第 5 名。另一项研究则通过让大语言模型自己去优化这套架构，实现了 76.4% 的通过率，甚至超过了人类精心设计的系统。
现在，这套基础设施有了一个正式的名字：**AI 智能体 Harness**。
## 定义
LangChain 的 Vivek Trivedy 给出的定义公式：
> "如果你不是模型本身，那你就是 Harness。"
关键区别：
- **AI 智能体（Agent）**：用户感知到的行为体现——有目标、会用工具、能自我纠错的实体
- **Harness**：产生这种行为的背后机器
Beren Millidge 的类比（2023）：
> 原生大语言模型就像一个没有内存、没有硬盘、也没有输入输出设备的 CPU。
> - 上下文窗口 → 内存（快但容量有限）
> - 外部数据库 → 硬盘（大但速度慢）
> - 工具集成 → 设备驱动程序
> - **Harness → 操作系统**
## 工程化的三个层次
围绕模型，工程化分为三个层次：
| 层次 | 描述 |
|------|------|
| 提示词工程 | 精心设计模型接收到的指令 |
| 上下文工程 | 管理模型在什么时间点能看到什么内容 |
| Harness 工程 | 涵盖上述两者 + 工具编排、状态持久化、错误恢复、验证循环、安全执行、生命周期管理 |
## 生产级 Harness 的 12 个核心组件
### 1. 编排循环 (The Orchestration Loop)
系统的"心脏"。实现了"思考 - 行动 - 观察"循环（TAO = Thought-Action-Observation），也称为 **ReAct 循环**。
核心流程：整合提示词 → 调用 LLM → 解析输出 → 执行工具调用 → 反馈结果 → 重复，直到任务完成。
技术实现通常只是一个 `while` 循环。Anthropic 将运行时描述为"笨循环"——所有智慧存在于模型之中，Harness 只负责管理回合切换。
### 2. 工具 (Tools)
智能体的"双手"。定义为结构化模式（名称、描述、参数类型），注入到模型上下文中。
**Claude Code** 六大类工具：
- 文件操作
- 搜索
- 执行
- 网页访问
- 代码分析
- 子智能体创建
**OpenAI Agents SDK**：
- 函数工具（`@function_tool` 定义）
- 托管工具（网页搜索、代码解释器、文件搜索）
- MCP（Model Context Protocol）服务器工具
### 3. 记忆 (Memory)
在不同时间尺度上运作：
| 类型 | 范围 | 实现 |
|------|------|------|
| 短期记忆 | 单次会话 | 对话历史 |
| 长期记忆 | 多会话持久 | 项目文件、JSON 存储、SQLite/Redis |
**Claude Code 三层记忆架构**：
1. 轻量级索引（每条约 150 字符，始终加载）
2. 按需调用的详细主题文件
3. 仅通过搜索访问的原始对话记录
核心设计原则：智能体将记忆视为"提示"，在行动前必须根据实际状态进行验证。
### 4. 上下文管理 (Context Management)
**核心问题：上下文腐烂（Context Rot）**
- 关键信息处于窗口中间位置时，模型表现下降 30% 以上（斯坦福"迷失在中间"现象）
- 即便支持百万级 Token 的窗口，上下文增长也会导致指令遵循能力退化
**应对策略**：
- **压缩（Compaction）**：接近限制时总结对话历史（Claude Code 保留架构决策和未修复 Bug，丢弃冗余工具输出）
- **观察掩码（Observation Masking）**：隐藏旧工具输出，但保留工具调用记录
- **即时检索（Just-in-time Retrieval）**：仅保留轻量级标识符，动态加载（`grep`/`head` 而非加载整个文件）
- **子智能体委托**：每个子智能体仅返回 1000-2000 Token 浓缩摘要
目标（Anthropic）：找到能最大化达成目标概率的、信号最强的最小 Token 集合。
### 5. 提示词构建 (Prompt Construction)
层级化的输入构建：系统提示词 → 工具定义 → 记忆文件 → 对话历史 → 当前用户消息
**OpenAI Codex 优先级栈**：
1. 服务器控制的系统消息（最高）
2. 工具定义
3. 开发者指令
4. 用户指令
5. 对话历史（最低）
### 6. 输出解析 (Output Parsing)
现代 Harness 依赖**原生工具调用**（`tool_calls` 对象），而非需要解析的自由文本。
判断逻辑：
- 有工具调用？→ 执行，继续循环
- 无工具调用？→ 当前输出即为最终答案
OpenAI 和 LangChain 支持通过 **Pydantic 模型**进行模式约束。
### 7. 状态管理 (State Management)
| 框架 | 方法 |
|------|------|
| LangGraph | 图形节点中流动的类型化字典，关键步骤 Checkpointing |
| Claude Code | Git 提交作为存档点，进度文件作为结构化草稿纸 |
| OpenAI | 应用内存、SDK 会话、服务器端 API、响应 ID 链 |
Checkpointing 支持：中断恢复，甚至"时间旅行"式调试。
### 8. 错误处理 (Error Handling)
**关键洞察**：10 步骤过程，每步 99% 成功率 → 全流程仅 90.4%。错误会滚雪球。
**LangGraph 四类错误**：
1. **临时性**：带延迟重试
2. **模型可恢复**：将错误作为工具消息返回，让模型自愈
3. **用户可修复**：暂停等待人类干预
4. **意外错误**：上报调试
### 9. 护栏与安全 (Guardrails and Safety)
**OpenAI SDK 三层级**：
1. 输入护栏（第一个智能体运行时检查）
2. 工具护栏（每次工具调用前检查）
3. 输出护栏（检查最终结果）
触发"绊网（Tripwire）"机制 → 智能体立即停止。
**Anthropic 架构**：将"权限执行"与"模型推理"分离。模型决定想做什么，Harness 决定允许做什么。
### 10. 验证循环 (Verification Loops)
区分"玩具演示"和"生产级智能体"的关键。
**Anthropic 三法**：
- 基于规则的反馈（测试、代码检查）
- 视觉反馈（Playwright 截图）
- LLM-as-judge（子智能体评估输出）
**Boris Cherny（Claude Code 创造者）**：让模型验证自己的工作，产出质量提升 2-3 倍。
### 11. 子智能体编排 (Subagent Orchestration)
**Claude Code 三模式**：
- **克隆 (Fork)**：复制父级上下文
- **队友 (Teammate)**：通过文件邮箱通信的独立窗口
- **工作树 (Worktree)**：独立的 Git 分支
**OpenAI**：
- Agent as Tool（专家处理特定子任务）
- 移交（Handoff）：专家接管后续控制权
## 循环运作：步进式演练
1. **提示词组装**：Harness 构建完整输入信息
2. **模型推理**：发送给模型 API，模型生成 Token（文本或工具调用请求）
3. **输出分类**：无 tool_calls → 结束；有 → 进入执行阶段
4. **工具执行**：Harness 校验参数、检查权限，在沙箱中运行并捕获结果
5. **结果打包**：格式化为模型可读消息，捕获错误以便模型自愈
6. **上下文更新**：追加到历史记录，必要时触发压缩
7. **循环**：返回第 1 步，直到满足退出条件
## 现实中的框架实现
| 框架 | 特点 |
|------|------|
| **Anthropic** (Claude Agent SDK) | `query()` 函数暴露，"笨循环"，智慧全在模型 |
| **OpenAI** (Agents SDK) | 代码优先，Python 工作流，不用复杂图形语言 |
| **LangGraph** | 显式状态图，精细流程控制 |
| **CrewAI** | 基于角色的多智能体协作，流程层管理确定性骨干逻辑 |
| **AutoGen** (Microsoft) | 顺序执行/群聊/移交/动态任务管理 |
## "脚手架"比喻 (The Scaffolding Metaphor)
建筑脚手架是临时性基础设施——让工人能触及原本够不到的高度。脚手架本身不盖房子，但没有它，工人就上不去高层。
**关键洞察**：房子盖好后，脚手架是要拆除的。
随着模型能力提升，Harness 的复杂程度应该逐渐降低。
**协同进化原则**：现在的模型在训练时，就已经考虑了 Harness 的存在。Harness 设计得好 → 模型升级时不需要增加复杂度，性能自动提升。
## 定义 Harness 的 7 个关键决策
1. **单智能体 vs. 多智能体**：先充分挖掘单智能体潜力；多智能体带来额外开销和信息损耗
2. **ReAct vs. 先规划后执行**：ReAct 灵活但成本高；"先规划后执行"速度更快
3. **上下文管理策略**：总结对话 vs. 动态加载
4. **验证循环设计**：硬性代码测试 vs. LLM 打分
5. **权限与安全架构**：速度优先自动批准 vs. 安全优先步步确认
6. **工具范围管理**：最小工具集原则——暴露当前步骤所需的最小工具集往往效果最佳
7. **Harness 的厚度**：多少逻辑写死在系统里，多少逻辑留给模型发挥
## Harness 即产品
两个使用完全相同模型的智能体，性能可能天差地别——原因就在于 Harness 的设计。
**TerminalBench 的证据**：仅仅改变 Harness，就能让排名变动 20 多位。
**Harness 是硬核工程能力的体现**：
- 如何将上下文视为稀缺资源进行管理？
- 如何设计验证循环以防止错误累积？
- 如何构建不产生幻觉的记忆系统？
随着模型越来越强，Harness 会变薄，但它永远不会消失。即便最强大的模型，也需要系统来管理窗口、执行代码、保存状态并验证工作。
> 下次当你的智能体表现不佳时，别光顾着抱怨模型，去检查一下你的 Harness 吧。
---
*原文：https://x.com/akshay_pachaar/status/2041146899319971922*