设计理念

了解 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 的核心逻辑。
• 每个中间件的效果是可见且可审计的，因为它只触及其声明的状态。

详见中间件页面的完整列表和配置说明。

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

技能是面向任务的能力包，包含指令、工作流、最佳实践以及让 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）将密钥排除在提交的配置文件之外，同时保持相同的结构。

总结