一、什么是智能体 Harness？
智能体 Harness 可以理解为：把大模型包起来、让它能稳定完成任务的一整套运行框架。
模型本身只是"会预测下一段文本"的核心能力；Harness 则负责把它变成一个可用的 Agent。
举个代码助手的例子：
LLM：负责理解需求、生成计划、写代码思路。
Harness：负责读取仓库文件、调用编辑工具、运行测试、处理报错、遵守权限、把最终结果反馈给用户。
没有 Harness，模型只能聊天；有了 Harness，模型才能持续地执行任务。
LangChain 的 Vivek Trivedy 提出的那个经典公式："如果你不是模型，你就是 Harness。"
二、三个工程层级
模型周围有三个同心圆的工程层级：
提示工程（Prompt Engineering）：精心制作模型接收的指令。
上下文工程（Context Engineering）：管理模型在什么时间看到什么内容。
驾驭工程（Harness Engineering）：涵盖以上两者，再加上整个应用基础设施：工具编排、状态持久化、错误恢复、验证循环、安全执行和生命周期管理。
Harness 不是提示词的外包装。它是让自主智能体行为成为可能的完整系统。
三、生产级 Harness 的 核心分层架构
Harness 不是 LLM 的 "单层包装"，而是一套多层嵌套的生产级运行支撑系统，让无状态的 LLM 具备稳定执行、安全管控、规模扩展的能力。
1.中心层：LLM（无状态模型）
- 角色：整个系统的 "推理大脑"，只负责理解指令、生成推理和输出。
- 本质限制：它是无状态的，不记得之前的对话、任务进度或外部状态，所有上下文都由 Harness 提供。
- Harness 的作用：不改变模型本身，而是为模型提供 "稳定的舞台和剧本"。
2. 第一层：Runtime（运行时引擎，系统的 "心脏"）
这是最贴近 LLM 的核心执行循环，决定了整个智能体的执行节奏和流程。
(1).Orchestration Loop（编排循环）
- 核心作用：整个系统的 "心跳"，控制执行流程，它实现了思考-行动-观察（TAO）循环，也叫 ReAct 循环
- 关键能力：组装 Prompt → 调用 LLM → 解析输出 → 执行工具 → 结果回写，循环往复直到任务完成或终止
(2).Prompt Construction（提示词构建）
- 核心作用：动态生成给 LLM 的指令，决定模型看到什么
- 关键能力：它是分层的：系统提示词、工具定义、记忆文件、对话历史，以及当前用户消息。OpenAI 的 Codex 使用严格的优先级栈：服务器控制的系统消息（最高优先级）、工具定义、开发者指令、用户指令（级联的AGENTS.md文件，32 KiB 限制），然后是对话历史。
(3).Output Parsing（输出解析）
- 核心作用：把 LLM 的自然语言输出转为可执行的结构化指令
- 关键能力：从模型输出中提取工具调用参数、任务指令，过滤无关文本，确保后续环节能理解。现代 Harness 依赖原生工具调用，模型返回结构化的 tool_calls 对象，而不是必须解析的自由文本。Harness 检查：有工具调用吗？执行它们并循环。没有工具调用？那就是最终答案。
(4).Error Handling（错误处理）
- 核心作用：捕获并处理执行中的异常，避免系统崩溃
- 关键能力：模型调用失败、工具报错、格式解析错误、超时重试、降级策略，保障流程不中断。LangGraph 区分四种错误类型：瞬态错误（带退避的重试）、大语言模型可恢复错误（将错误作为 ToolMessage 返回，让模型自行调整）、用户可修复错误（中断以获取人工输入）、以及意外错误（冒泡以供调试）。Anthropic 在工具处理程序内部捕获失败，并将它们作为错误结果返回，以保持循环运行。Stripe 的生产级 Harness 将重试次数上限设为两次。
3. 第二层：Capabilities（能力层，给模型装 "手脚" 和 "外挂"）
Runtime 只负责流程，而这一层为模型提供了和外部世界交互、持续执行任务的核心能力。
(1).Orchestration Loop（编排循环）
- 核心作用：整个系统的 "心跳"，控制执行流程
- 关键能力：组装 Prompt → 调用 LLM → 解析输出 → 执行工具 → 结果回写，循环往复直到任务完成或终止
(2).Tools（工具集）
- 核心作用：智能体的 "手"，连接外部系统和能力
- 关键能力：它们被定义为模式（名称、描述、参数类型），注入到大语言模型的上下文中，让模型知道有哪些可用工具。工具层处理注册、模式验证、参数提取、沙盒化执行、结果捕获，以及将结果格式化回大语言模型可读的观察内容。Claude Code 提供六大类工具：文件操作、搜索、执行、网络访问、代码智能和子智能体生成。OpenAI 的 Agents SDK 支持函数工具（通过@function_tool）、托管工具（WebSearch、CodeInterpreter、FileSearch）和 MCP 服务器工具。
(3).Memory（记忆系统）
- 核心作用：解决 LLM "天生失忆" 的问题，保存任务状态
- 关键能力：短期记忆 是单次会话内的对话历史。长期记忆 跨会话持久化：Anthropic 使用CLAUDE.md项目文件和自动生成的MEMORY.md文件；LangGraph 使用按命名空间组织的 JSON 存储；OpenAI 支持由 SQLite 或 Redis 支撑的会话（Sessions）。
Claude Code 实现了一个三层层级结构：一个轻量级索引（每条约 150 个字符，始终加载）、按需拉取的详细主题文件、以及仅通过搜索访问的原始转录文本。一个关键的设计原则是：智能体将自己的记忆视为"提示"，在行动前会针对实际状态进行验证。
(4).State Management（状态管理）
- 核心作用：记录和维护任务执行的进度与状态
- 关键能力：任务节点、工具调用结果、上下文状态的持久化，支持断点续跑、多轮会话延续。LangGraph 将状态建模为流经图节点的类型化字典，通过 reducer 合并更新。检查点发生在超级步骤边界，支持中断后恢复和时间旅行调试。OpenAI 提供四种互斥策略：应用内存、SDK 会话、服务器端 Conversations API，或轻量级的 previous_response_id 链式调用。Claude Code 采取了不同方法：用 git 提交作为检查点，用进度文件作为结构化草稿本。
(5).Context Management（上下文管理）
- 核心作用：解决 "上下文膨胀" 和 "腐烂" 问题
- 关键能力：动态筛选、压缩、排序有效信息，控制注入模型的 Token 数量，避免无关信息干扰模型判断。当关键内容落在窗口中间位置时，模型性能下降 30% 以上（Chroma 的研究，与斯坦福的"Lost in the Middle"发现相互印证）。即使是百万 token 的窗口，随着上下文增长，指令遵循能力也会下降。
- 生产级策略包括：
压缩（Compaction）：接近限制时总结对话历史（Claude Code 保留架构决策和未解决的 bug，同时丢弃冗余的工具输出）。
观察屏蔽（Observation Masking）：JetBrains 的 Junie 隐藏旧的工具输出，但保留工具调用可见。
即时检索（Just-in-time Retrieval）：维护轻量级标识符并动态加载数据（Claude Code 使用grep、glob、head、tail，而不是加载完整文件）。
子智能体委托（Sub-agent Delegation）：每个子智能体进行广泛探索，但只返回 1,000 到 2,000 token 的浓缩摘要。
Anthropic 的上下文工程指南指出目标是：找到最小的高信号 token 集合，以最大化期望结果的可能性。
4. 第三层：Safety & Scale（安全与规模层，给系统装 "刹车" 和 "护栏"）
这是生产环境和 Demo 的核心区别，决定了系统是否能稳定、安全地大规模运行。
(1).Guardrails & Safety（安全护栏）
- 核心作用：输入输出的 "第一道和最后一道防线"
- 关键能力：输入过滤（敏感词、恶意指令拦截）、输出审核（幻觉检测、合规校验）、权限控制，防止模型违规操作。
(2).Verification Loops（验证循环）
- 核心作用：对工具执行结果和模型决策进行校验
- 关键能力：用规则引擎、外部校验器或 LLM-as-judge 验证结果正确性，避免错误结果被带入后续流程。Anthropic 推荐三种方法：基于规则的反馈（测试、linter、类型检查器）、视觉反馈（通过 Playwright 截图用于 UI 任务）、以及大语言模型作为裁判（一个单独的子智能体评估输出）。
(3).Subagent Orchestration（子智能体编排）
- 核心作用：拆解复杂任务，实现多智能体协作
- 关键能力：将大任务拆分为子任务，调度子智能体并行 / 串行执行，解决单模型能力不足的问题。Claude Code 支持三种执行模型：Fork（父上下文的字节级相同副本）、Teammate（单独的终端面板，基于文件的邮箱通信）、以及 Worktree （拥有自己的 git 工作树，每个智能体一个独立分支）。OpenAI 的 SDK 支持智能体作为工具（专家处理有界的子任务）和交接（handoffs，专家完全接管控制）。LangGraph 将子智能体实现为嵌套状态图。
(4).Tool Scoping（工具范围控制）
- 核心作用：限制工具的调用权限和使用场景
- 关键能力：按用户、任务类型、权限等级限制可调用的工具，防止模型滥用工具导致数据泄露或系统故障
(5).Crempt Loops（上下文治理循环）
- 核心作用：持续优化上下文的有效性
- 关键能力：动态清理冗余信息、压缩长文本、更新记忆，避免上下文窗口被垃圾信息占满
四、循环运转：逐步拆解
第 1 步（提示词组装）： Harness 构建完整输入：系统提示词 + 工具模式 + 记忆文件 + 对话历史 + 当前用户消息。重要上下文被放置在提示词的开头和结尾（基于"Lost in the Middle"发现）。
第 2 步（大语言模型推理）： 组装的提示词被发送到模型 API。模型生成输出 token：文本、工具调用请求，或两者兼有。
第 3 步（输出分类）： 如果模型只产生了文本而没有工具调用，循环结束。如果它请求了工具调用，进入执行阶段。如果请求了交接，更新当前智能体并重新开始。
第 4 步（工具执行）： 对于每个工具调用，Harness 验证参数、检查权限、在沙盒环境中执行、并捕获结果。只读操作可以并发运行；变更操作串行运行。
第 5 步（结果打包）： 工具结果被格式化为大语言模型可读的消息。错误被捕获并作为错误结果返回，以便模型自我纠正。
第 6 步（上下文更新）： 结果被追加到对话历史。如果接近上下文窗口限制，Harness 触发压缩。
第 7 步（循环）： 返回第 1 步。重复直到终止。
终止条件是分层设置的：模型产生没有工具调用的响应、超过最大轮次限制、token 预算耗尽、护栏绊线触发、用户中断、或返回安全拒绝。一个简单问题可能需要 1 到 2 轮。一个复杂的重构任务可以跨多轮串联几十个工具调用。
对于跨越多个上下文窗口的长时间运行任务，Anthropic 开发了一种两阶段的"Ralph Loop"模式：一个初始化智能体设置环境（初始化脚本、进度文件、功能列表、初始 git 提交），然后每个后续会话中的编码智能体读取 git 日志和进度文件来定位自己，挑选最高优先级的未完成功能，进行工作，提交，并写入摘要。文件系统提供了跨上下文窗口的连续性。
五、真实 Harness 如何实现这一模式
Anthropic 的 Claude Agent SDK 通过单个query() 函数暴露 Harness，该函数创建智能体循环并返回一个异步迭代器来流式传输消息。运行时是一个"笨循环"。所有智能都存在于模型中。Claude Code 使用一个收集-行动-验证循环：收集上下文（搜索文件、阅读代码）、采取行动（编辑文件、运行命令）、验证结果（运行测试、检查输出），重复。
OpenAI 的 Agents SDK 通过Runner类实现 Harness，具有三种模式：异步、同步和流式。该 SDK 是"代码优先"的：工作流逻辑用原生 Python 表达，而不是图 DSL。Codex Harness 在此基础上扩展了三层架构：Codex Core（智能体代码 + 运行时）、App Server（双向 JSON-RPC API）和客户端界面（CLI、VS Code、网页应用）。所有界面共享同一个 Harness，这就是为什么"Codex 模型在 Codex 界面上感觉比在通用聊天窗口中更好"。
LangGraph 将 Harness 建模为显式状态图。两个节点（llm_call和tool_node）通过条件边连接：如果存在工具调用，路由到 tool_node；如果不存在，路由到 END。LangGraph 从 LangChain 的 AgentExecutor 进化而来，后者在 v0.2 中被弃用，因为它难以扩展且缺乏多智能体支持。LangChain 的 Deep Agents 明确使用了"智能体 Harness"这一术语：内置工具、规划（write_todos工具）、用于上下文管理的文件系统、子智能体生成和持久化记忆。
CrewAI 实现了基于角色的多智能体架构：Agent（围绕大语言模型的 Harness，由角色、目标、背景故事和工具定义）、Task（工作单元）和 Crew（智能体集合）。CrewAI 的 Flows 层增加了"在关键处注入智能的确定性骨架"，管理路由和验证，而 Crews 处理自主协作。
AutoGen（正在演变为 Microsoft Agent Framework）开创了对话驱动的编排。其三层架构（Core、AgentChat、Extensions）支持五种编排模式：顺序、并发（扇出/扇入）、群聊、交接和 magentic（一个管理智能体维护动态任务账本，协调专家）。