Agent Harness 深度解析：从框架对比到核心组件实现

在 AI Agent 的开发中，我们经常听到“框架”与“Harness”这两个词。它们看似相似，实则代表着两种截然不同的工程哲学。本文基于 B 站技术分享，以 DeepFlow 和 DeepSeek Harness 两个开源项目为例，拆解 Agent Harness 的架构设计与实现细节。

什么是 Harness？与 Agent Framework 有何不同？

Harness 本意是马具，用来控制马的行为。在 Agent 语境下，它指代包裹模型、提供运行时环境的操作层。一个常见的定义是：Agent = Model + Harness，即 Harness 是 Agent 中除了模型之外的所有部分。

与 LangChain 这类 Agent Framework 相比，Framework 更像一个编程库——它提供对 LLM 的抽象、工具原语、记忆和编排能力，但你需要自己实现工具调用循环、会话管理、网络重试等细节。而 Harness 是一个开箱即用的完整执行环境，相当于一个已经写好的 Agent。

为什么有了 Framework 还需要 Harness？核心原因有两点：一是避免重复造轮子，通用 Agent 的底层逻辑高度相似，标准化 Harness 可以复用；二是模型与 Harness 共同进化——同一模型在不同 Harness 上跑 Terminal Bench 数据集，效果存在差异。厂商发布的模型往往针对特定 Harness 调优，自研 Harness 可能无法完全释放模型能力。

Harness 的三大核心组成

从架构视角看，Harness 可以归纳为三个部分：

1. Runtime（模型运行时）：相当于模型的操作系统，负责执行工具调用、管理进程与沙箱环境。
2. User Interface（用户界面）：供用户发送消息、控制 Agent 权限、调整思考深度，并展示执行过程。
3. Context Manager（上下文管理器）：通过组织与修改 Context 来反向影响模型行为，包括 System Prompt、记忆注入、工具结果裁剪等。

这三者共同构成了 Harness 的完整闭环：Runtime 让模型“能做事”，UI 让用户“能控制”，Context Manager 让模型“知道该做什么”。

组件一：Orchestration Loop（编排循环）

几乎所有通用 Agent 都采用 ReAct 模式：Thought（模型推理）→ Action（调用工具）→ Observation（工具返回结果），循环往复。Harness 的众多组件都插入在这个循环的各个环节。

DeepSeek^广告 Harness 用 TypeScript 手写了三层循环：外层是 Agent 与用户的多轮对话；中间是 Thought-Action-Observation 循环；内层是模型调用失败时的网络重试。

DeepFlow 则基于 LangGraph 实现标准的 Model-Tools 循环，并通过 Middleware 机制在循环中插入扩展点。例如 Before Agent Middleware 会在 Agent 启动前把当前日期、System Prompt 等静态内容组织好，保证 Prefix Context 固定，从而节省 Token。Before Model Middleware 中可以加入摘要压缩逻辑，检测上下文是否逼近模型上限。

ReAct（Reasoning + Acting）模式由 Yao 等人于 2022 年提出，核心思想是让模型交替生成推理轨迹与行动指令，从而把"思考"显式化，弥补纯链式推理无法与外部环境交互的缺陷。相比更早的 Chain-of-Thought 只能产出内部推理文本，ReAct 的关键贡献在于引入 Observation 环节：工具的真实返回值会回填到上下文，模型据此修正下一步计划，形成闭环反馈。这也是它成为通用 Agent 事实标准的根本原因——模型无需一次性规划完整路径，可以边做边看、动态纠错。其代价是每轮工具调用都会消耗额外 Token 与延迟，且错误观察可能污染后续推理，因此在长任务中需要配合循环检测、预算控制与上下文压缩等手段，才不至于陷入重复调用或上下文爆炸。

组件二：Tools（工具）

工具是 Agent 的双手。工具通常以 Schema 形式定义，包含名称、功能描述和参数。常见的工具分类包括：子 Agent 系统、文件操作、搜索、Shell 命令执行、Web 访问、任务规划（To-Do List）、Skill 调用以及 IDE 特定工具。

一个值得关注的实现细节是 To-Do List 工具。DeepSeek Harness 中的实现是无状态的——Harness 不记录任务进度，只检查两个约束：所有任务状态必须是 pending、in-progress、done 三种之一；且同时只能有一个任务处于进行中。至于任务增减和完成度，完全由模型自行维护。

工具调用依赖模型提供商的 Guided Decoding 技术。当模型输出工具调用特殊 Token 后，Provider 会强制下一个 Token 为 JSON 花括号，并在枚举字段处将其他 Token 的 Logits 置为负无穷，只允许合法选项参与采样。这样 Harness 才能可靠解析工具调用。

Guided Decoding（引导式解码）是推理服务端的一种约束采样技术，常见实现包括基于有限状态机的语法约束与基于 JSON Schema 的结构化输出。其原理是在每个解码步根据已生成前缀计算合法 Token 集合，并把这些位置之外的 Logits 直接压到负无穷，使采样只能在合法集合内进行。对 Harness 而言，这意味着工具调用的参数可以被保证为合法 JSON，并满足枚举、必填字段等类型约束，从而避免解析失败与重试开销。局限在于约束越复杂，前缀状态维护成本越高，且强约束可能干扰模型原本的概率分布，在参数较长或嵌套较深时略微降低语义质量。

组件三：File System（文件系统）

文件系统解决了三个问题：突破 Context 容量限制、提供持久化记忆、作为多 Agent 的共享中间层。让模型直接使用人类文件系统的 Rationale 在于：模型在训练中已经见过大量 Shell 和文件操作代码，无需专门设计一套 Agent 文件系统。

DeepFlow 提供 Docker 和 Local Sandbox 两种模式。Local 模式下实现了路径虚拟化：System Prompt 中告知模型用户文件位于虚拟路径，Harness 在工具调用时做正向和反向路径映射。

不过这种设计“防君子不防小人”——模型可以通过代码拼接绕过虚拟路径。因此 DeepFlow 默认启用 Docker 模式，Local Sandbox 需主动开启且默认禁用 Bash。

组件四至六：Bash 执行、Sandbox 与 Memory

Bash 与代码执行让 Agent 能自己编写工具，弥补预定义工具的不足。Claude Code 通过黑白名单机制管理 Bash 指令：先检查拒绝列表，再检查允许列表，然后看只读白名单，最后询问用户。

Sandbox 则负责安全隔离，既防止访问敏感文件，也支持多租户隔离。DeepSeek Harness 使用内核级沙箱，在执行 Python 脚本前拼接沙箱指令，在内核层对进程做访问控制。

Memory 的核心目标是 Continuous Learning Without Re-Changing。它分为长期记忆（如 Agent.md 中的用户偏好和新知识）与短期记忆（当前任务进度）。DeepFlow 的 Memory 机制是一个 After Agent Middleware，每轮对话结束后经过三步过滤：只保留用户最初输入和 AI 最终输出；过滤客套轮次；检测用户校准或偏好信号。随后调用独立的模型判断信息是否具有持久性、描述性，并输出置信度，达标后才写入 Agent.md。

内核级沙箱通常依托 Linux 的命名空间（Namespace）与控制组（cgroup）实现隔离：前者隔离进程视图、网络与挂载点，后者限制 CPU、内存与进程数。更细粒度的文件访问控制可借助 seccomp 过滤系统调用，或使用 Landlock、gVisor 等机制收窄进程权限。与容器共享内核不同，这些方案在进程启动阶段即施加策略，因此即使 Agent 生成的代码存在越权意图，也难以突破限制。代价是兼容性——某些依赖特殊系统调用的脚本可能运行失败，需要在隔离强度与可用性之间权衡，这也是 Agent 沙箱普遍提供多档安全级别的原因。

组件七：Context Management（上下文管理）

Context 并非只能 Append Only。虽然追加模式对 KV Cache 最友好，但对任务执行效果未必最优。静态部分主要是 System Prompt，DeepFlow 的 System Prompt 包含：Soul（Agent 人设）、Thinking Style（先想清楚再动手）、Skill System、SubAgent System（提醒不要过度派活）以及 Critical Reminder（交付物路径、文件修改接口偏好等）。

动态部分则由 Memory、工具结果注入等 Context Management 行为构成，它们共同塑造模型每一轮看到的“世界”。

KV Cache 是自回归推理的显存优化手段：把已处理 Token 的 Key/Value 张量缓存下来，后续生成时只需计算新 Token 的注意力，从而把每步复杂度从与序列长度平方相关降为线性。前缀完全一致时缓存可直接命中，响应更快、成本更低；一旦在中间插入或修改内容，后续缓存全部失效，需要重新计算。这解释了为什么 Append Only 的追加式上下文对推理服务最友好，也解释了 DeepFlow 为何要在 Agent 启动前固定 System Prompt 等静态前缀、把记忆与工具结果注入放在其后。压缩、重排等操作虽然提升任务效果，但每次都会触发缓存重建，属于需要权衡的成本。

组件八：Context Rot Defense（上下文腐化防御）

Context 是稀缺资源，超过模型窗口会导致推理质量下降。常见防御手段有三种：Compaction（接近上限时总结压缩历史）、Offloading（工具输出暂存文件系统而非全部塞回 Context）、Skill（三级渐进披露，System Prompt 只放描述，按需加载 Skill.md 和深层文件）。

Compaction 由 Summarization Middleware 在 Before Model 位置触发，触发条件包括对话轮数或 Token 阈值。Token 估算常用字符数除以 4 的公式，对英文较准，中文和代码则会低估。

组件九：Long Horizon Execution（长程执行）

跨多个推理步骤和 Context 的复杂任务面临三大挑战：上下文过长导致遗忘、在错误路径上反复调用工具、目标拆解不清。解决方案组合了文件系统 Offload、To-Do List 规划与 Self Verification。

DeepFlow 的 Go Loop 机制在 After Agent 位置插入一个“严格完成度裁判”模型，判断当前返回是否真正满足用户目标。未完成则让 Agent 继续，并提示“除非确实受阻，否则不要要求用户继续”。该循环最多执行八轮，配合滑动窗口防止死循环。

组件十至十二：错误处理、Serving 与可观测性

错误处理覆盖循环检测与 Token 预算控制。Loop Detection 对工具调用类型做哈希，超过阈值时插入警告消息；Token Budget Middleware 在用量超限时提醒模型尽快输出已有结果。

Serving Layer 将各平台渠道抽象为统一接口。DeepFlow 通过 Channel Adapter 接入不同平台，例如微信 iLink 需要主动轮询消息，文件通过 CDN 传输。

Observability 方面，DeepSeek Harness 的 Session Log 设计颇具启发性：它是 Append Only 的唯一真相来源，前端渲染和 Context Manager 都通过读取 Session Log 来工作。优点是可确定性复现执行路径、便于定位 Bug；缺点是日志量巨大，且 Projection 协议一旦确定，后续改进可能面临兼容性问题。

模型与 Harness 的共同进化

DeepSeek 曾发布与 DeepSeek Harness 共同训练的模型，这是明显趋势。好处是模型适配 Harness，表现更优；模型训练中反复使用的工具也可以沉淀进 Harness。负面效应则是过拟合——模型可能无法迁移到其他 Harness，泛化能力下降。OpenAI Codex 的报告曾指出，训练数据过度集中于 Apply Patch 一种改文件方式，导致模型在其他方式上能力退化。

Harness 的本质，是为模型提供一个标准化、可复用的运行环境，同时通过 Context 管理反向塑造模型行为。理解它的组件设计，比单纯调用框架更能帮助开发者构建可靠的 Agent 系统。