---
title: 设计理念
description: 了解 DeerFlow Harness 背后的设计理念，有助于你有效地使用它、自信地扩展它，并推断 Agent 在生产环境中的行为方式。
---

import { Callout, Cards } from "nextra/components";

# 设计理念

<Callout type="info" emoji="🏗️">
  DeerFlow 围绕一个核心思想构建：Agent
  行为应该由小型、可观察、可替换的组件组合而成——而不是硬编码到固定的工作流图中。
</Callout>

了解 DeerFlow Harness 背后的设计理念，有助于你有效地使用它、自信地扩展它，并推断 Agent 在生产环境中的行为方式。

## 为什么是 Harness，而非 Framework

框架提供抽象和构建块，你负责组装各部分并编写连接它们的胶水代码。

**Harness** 更进一步。它打包了一个有主张的、可直接运行的运行时，让 Agent 无需你每次重建相同的基础设施就能完成真实工作。

DeerFlow 之所以是 Harness，是因为它内置了：

- 带有工具路由的 Lead Agent
- 包裹每次 LLM 调用的中间件链
- 用于文件和命令的沙箱执行
- 按需加载专业能力的技能
- 用于委派并行工作的子 Agent
- 跨会话连续性的记忆
- 控制这一切的配置系统

你不需要从头设计编排层——Harness 就是编排层。

## 长时序任务是主要使用场景

DeerFlow 专为需要不止一次提示-响应交互的任务而设计。一个有用的长时序 Agent 必须：

1. 制定计划
2. 按顺序调用工具
3. 检查和修改文件
4. 在失败时恢复
5. 当任务太宽泛时委派给子 Agent
6. 最终返回具体的产出物

DeerFlow 中的每一个架构决策都以这个使用场景为标准进行评估。短暂、无状态的交互很简单。在真实世界压力下的长时序、多步骤工作流才是目标。

## 中间件链优于继承

DeerFlow 不要求你子类化 Agent 或覆盖方法来改变其行为。相反，它使用一个**中间件链**来包裹每次 LLM 调用。

每个中间件都是一个小型、专注的插件，可以在模型调用前后检查或修改 Agent 的状态。Lead Agent 的行为完全由活跃的中间件决定。

这种设计有几个优点：

- 各个行为（记忆、摘要、澄清、循环检测）相互隔离，可独立测试。
- 可以扩展链而无需触碰 Agent 的核心逻辑。
- 每个中间件的效果是可见且可审计的，因为它只触及其声明的状态。

详见[中间件](/docs/harness/middlewares)页面的完整列表和配置说明。

## 技能提供专业化但不污染上下文

**技能**是面向任务的能力包，包含指令、工作流、最佳实践以及让 Agent 在特定工作类型中有效的工具或资源。

关键设计决策是技能**按需加载**。基础 Agent 保持通用。当任务需要深度研究时，加载研究技能；当任务需要数据分析时，加载分析技能。

这很重要，因为它保持了基础 Agent 上下文的清晰。为撰写学术论文而设计的专业提示词不会污染专注于编码的会话。技能在相关时注入内容，仅此而已。

## 沙箱是执行环境

DeerFlow 为 Agent 提供一个**沙箱**：一个隔离的工作区，Agent 可以在其中读取文件、写入输出、运行命令并生成产出物。

这将 Agent 从文本生成器转变为能够真正完成工作的系统。Agent 不只是描述要写什么代码，而是可以写代码、运行代码并验证结果。

隔离性很重要，因为执行应该可重现且可控。沙箱是 DeerFlow 支持真实行动而不仅仅是对话的原因。

## 上下文工程让长时序任务可控

上下文压力是长时序 Agent 的主要挑战。如果所有内容无限期累积在上下文窗口中，Agent 会变得越来越慢、越来越嘈杂、越来越不可靠。

DeerFlow 通过**上下文工程**来解决这个问题——有意识地控制 Agent 在每个步骤中看到、记住和忽略什么：

- **摘要压缩**：当对话变得太长时，旧轮次被摘要替代。Agent 保留含义而不是全量内容。
- **子 Agent 上下文隔离**：当工作委派给子 Agent 时，子 Agent 只接收完成其任务所需的信息，而不是完整的父历史。
- **外部工作记忆**：任务产生的文件和产出物保存在磁盘上，而不在上下文窗口中。Agent 在需要时引用它们。
- **记忆注入**：跨会话事实以受控的 token 预算注入到系统提示中。

这是 DeerFlow 中最重要的思想之一。好的 Agent 行为不仅仅是关于更强大的模型，也关于在正确时间给模型提供正确的工作集。

## 配置驱动行为

DeerFlow 中所有有意义的行为都通过 `config.yaml` 控制。系统的设计使运维人员无需触碰代码就能改变 Agent 的行为——使用哪些模型、是否启用摘要压缩、如何限制子 Agent、哪些工具可用。

这个设计原则有三个含义：

1. **可重现性**：一个配置文件在某时间点完整描述了 Agent 的行为。
2. **可部署性**：相同的代码在不同环境中运行方式不同，因为配置不同。
3. **可审计性**：Agent 能做什么和不能做什么在一处可见。

环境变量插值（`api_key: $OPENAI_API_KEY`）将密钥排除在提交的配置文件之外，同时保持相同的结构。

## 总结

| 设计原则               | 实践含义                                 |
| ---------------------- | ---------------------------------------- |
| Harness 而非 Framework | 开箱即用的运行时，所有基础设施已预先连接 |
| 长时序优先             | 架构假设多步骤、多工具、多轮次任务       |
| 中间件优于继承         | 行为由小型、隔离的插件组合而成           |
| 技能提供专业化         | 领域能力按需注入，保持基础干净           |
| 沙箱用于执行           | 真实文件和命令操作的隔离工作区           |
| 上下文工程             | 主动管理 Agent 所见内容以保持有效性      |
| 配置驱动               | 所有关键行为通过 `config.yaml` 控制      |

<Cards num={2}>
  <Cards.Card title="Lead Agent" href="/docs/harness/lead-agent" />
  <Cards.Card title="中间件" href="/docs/harness/middlewares" />
</Cards>
