harness

DeerFlow Harness 架构分析

May 8, 2026

什么是 Harness

Harness 是 DeerFlow 的核心代理框架层，以独立 Python 包 deerflow-harness 的形式发布，是整个系统的”引擎”部分，封装了所有构建、运行 AI 代理所需的核心能力，上层应用（Gateway、Channels 等）基于 Harness 提供的能力进行业务开发。

设计目标

可复用性：作为独立包可被其他项目直接引用，快速搭建 AI 代理系统，避免重复造轮子
可扩展性：高度模块化设计，所有核心组件都支持自定义扩展，适应不同业务场景需求
边界清晰：与上层应用严格解耦，Harness 不依赖上层应用代码，保证框架的通用性
生产级：内置线程安全、资源管理、错误处理、监控告警等生产级特性，支持高并发场景
易用性：提供简洁的 API 接口，屏蔽底层复杂实现，降低 AI 代理开发门槛

架构分层

Harness 采用模块化架构，核心分为以下几层：

┌─────────────────────────────────────────────────────────┐
│                      Client API                         │
│  (DeerFlowClient: 嵌入式调用接口，与 Gateway API 兼容)    │
├─────────────────────────────────────────────────────────┤
│                      Agent Layer                        │
│  Lead Agent / Middleware Chain / Thread State / Memory  │
├─────────────────────────────────────────────────────────┤
│                   Core Capability Layer                 │
│  Tools / MCP / Skills / Subagents / Sandbox / Models    │
├─────────────────────────────────────────────────────────┤
│                  Foundation Layer                        │
│  Config / Reflection / Guardrails / Tracing / Utils     │
└─────────────────────────────────────────────────────────┘

核心组件详解

1. 基础层 (Foundation Layer)

配置系统 (config/)

统一配置加载：支持 config.yaml 和 extensions_config.json 两种配置文件
环境变量解析：自动解析配置中的 $ENV_VAR 格式的环境变量引用
热重载：配置文件修改自动检测重载，无需重启服务
配置验证：Pydantic 模型校验配置格式正确性
包含子配置：AppConfig、ModelConfig、SandboxConfig、SkillsConfig、MemoryConfig 等

反射系统 (reflection/)

动态类加载：通过字符串路径（如 module.path:ClassName）动态加载类和实例
类型校验：加载时自动校验类是否继承自预期的基类
错误友好：缺失依赖时返回可执行的安装提示

护栏系统 (guardrails/)

插件化护栏：支持自定义 GuardrailProvider 实现工具调用鉴权
内置实现：AllowlistProvider 基于白名单的工具访问控制
中间件集成：在工具调用前自动执行护栏检查，拒绝非法操作

2. 核心能力层 (Core Capability Layer)

沙箱系统 (sandbox/)

抽象接口：Sandbox 和 SandboxProvider 接口定义
多实现支持：本地文件系统模式、Docker 容器模式、远程 K8s 模式
路径映射：虚拟路径到物理路径的自动转换，对 Agent 透明
工具封装：bash/read_file/write_file/ls/str_replace 等沙箱工具

模型系统 (models/)

模型工厂：create_chat_model() 统一创建不同厂商的 LLM 实例
多厂商支持：Anthropic、OpenAI、DeepSeek、Minimax、Google 等
扩展特性：支持思考模式、视觉能力、响应式 API 等
凭证管理：自动加载环境变量中的 API Key

工具系统 (tools/)

内置工具：present_files/ask_clarification/view_image 等
MCP 集成：自动加载 MCP 服务器提供的工具，支持 SSE/HTTP/stdio 传输
社区工具：Tavily 搜索、Firecrawl 爬虫、Jina AI 阅读、DuckDuckGo 搜索等
工具分组：支持按组加载工具，灵活配置 Agent 可用能力

技能系统 (skills/)

技能发现：自动扫描 skills/ 目录下的技能
技能解析：解析 SKILL.md 中的元数据（名称、描述、权限等）
技能注入：自动将启用的技能注入到 Agent 系统提示中
技能安装：支持通过 API 上传安装 .skill 格式的技能包

子代理系统 (subagents/)

内置代理：general-purpose（通用代理）、bash（命令执行专家）
并发控制：默认最大 3 个并发子代理，避免资源耗尽
异步执行：后台线程池执行子代理任务，不阻塞主流程
事件通知：通过 SSE 推送子代理执行状态（开始/运行中/完成/失败）

MCP 系统 (mcp/)

多服务器管理：同时连接多个 MCP 服务器
懒加载：工具首次使用时才初始化，节省启动时间
缓存失效：配置文件修改自动重新加载 MCP 工具
OAuth 支持：自动刷新令牌，注入 Authorization 头

3. 代理层 (Agent Layer)

Lead Agent

入口函数：make_lead_agent() 创建代理实例
动态工具加载：根据配置自动组合沙箱、内置、MCP、社区、子代理工具
系统提示生成：动态注入技能、内存、子代理等相关的系统提示
基于 LangGraph：使用 LangGraph 作为工作流引擎

中间件链 (middlewares/)

按执行顺序排列：

ThreadDataMiddleware：创建线程专属目录结构
UploadsMiddleware：处理上传文件，注入到会话中
SandboxMiddleware：获取/释放沙箱实例
DanglingToolCallMiddleware：处理中断的工具调用
GuardrailMiddleware：工具调用鉴权
SummarizationMiddleware：接近 Token 限制时自动会话摘要
TodoMiddleware：计划模式下的任务列表管理
TitleMiddleware：自动生成会话标题
MemoryMiddleware：异步更新记忆系统
ViewImageMiddleware：图像数据注入，支持视觉模型
SubagentLimitMiddleware：子代理并发数限制
ClarificationMiddleware：拦截澄清请求，中断执行

状态管理

ThreadState：会话状态 Schema，包含沙箱、线程数据、标题、 artifacts、任务列表、上传文件、查看过的图片等
自定义 Reducer：实现状态合并逻辑，避免重复数据
Checkpoint：支持 SQLite 等持久化 Checkpoint 存储

记忆系统 (memory/)

事实提取：自动从对话中提取用户偏好、知识、目标等事实
去重逻辑：自动检测重复事实，避免冗余存储
延迟更新：队列批量处理更新，减少 LLM 调用次数
上下文注入：会话开始时自动注入相关记忆到系统提示

4. 客户端 API (Client API)

DeerFlowClient：嵌入式 Python 客户端，无需启动 HTTP 服务即可使用所有能力
API 兼容：返回格式与 Gateway API 完全一致，上层代码无需修改即可在 HTTP 和嵌入式模式下切换
流式支持：支持对话流式输出，与 LangGraph SSE 协议对齐

职责边界

Harness 包含的能力

✅ 所有代理运行相关的核心逻辑 ✅ Agent、工具、沙箱、模型、技能、子代理、MCP 等核心组件 ✅ 配置、反射、护栏等基础能力 ✅ 嵌入式客户端 API

Harness 不包含的能力

❌ FastAPI Gateway 接口层 ❌ IM 通道（Feishu/Slack/Telegram）集成 ❌ 前端页面 ❌ 具体业务逻辑

依赖规则

允许：App → Harness（上层应用调用 Harness 接口）禁止：Harness → App（Harness 不能依赖上层应用代码） 该规则由 tests/test_harness_boundary.py 单测强制保障

扩展点

Harness 提供了丰富的扩展点，支持按需定制：

自定义模型：实现模型 Provider，接入新的 LLM 厂商
自定义工具：开发新的工具类，扩展 Agent 能力
自定义沙箱：实现 SandboxProvider，支持新的隔离技术
自定义护栏：实现 GuardrailProvider，自定义工具访问控制逻辑
自定义中间件：添加新的中间件，扩展 Agent 处理流程
自定义技能：开发新的技能包，复用特定领域能力

架构设计优势

技术选型考量

LangGraph 作为工作流引擎：
- 原生支持状态管理、工具调用、多轮对话等 Agent 核心能力
- 内置 Checkpoint 机制，支持会话中断恢复
- 流式输出、事件驱动架构，适合构建交互型 Agent
- 生态丰富，与 LangChain 工具链无缝集成
Pydantic 作为配置与数据结构基础：
- 类型安全，自动校验，减少运行时错误
- 序列化/反序列化友好，方便 API 交互
- 自动生成 OpenAPI 文档，降低集成成本
模块化依赖设计：
- 可选依赖：社区工具、特定厂商 SDK 等作为可选依赖，用户可以按需安装
- 核心轻量：核心框架依赖少，启动速度快，部署方便

安全性设计

多层安全隔离：
- 沙箱层：Docker/K8s 容器级隔离，防止 Agent 操作影响宿主系统
- 路径映射层：虚拟路径到物理路径的转换，防止目录遍历攻击
- 护栏层：工具调用鉴权，禁止访问敏感资源
- 输入输出过滤：命令执行前后自动处理路径，防止泄露内部路径信息
最小权限原则：
- 技能目录只读挂载，防止 Agent 修改系统技能
- ACP 工作区只读挂载，Agent 只能读取执行结果
- 沙箱容器默认以非 root 用户运行，减少攻击面

性能优化

懒加载机制：
- MCP 工具首次使用时才初始化，减少启动时间
- 模型实例按需创建，避免预加载不必要的模型
- 技能配置懒加载，提高响应速度
缓存策略：
- MCP 工具缓存，配置文件修改才重新加载
- 沙箱暖池机制，避免容器冷启动开销
- 记忆系统批量更新，减少 LLM 调用次数
并发控制：
- 子代理并发数限制，防止资源耗尽
- 沙箱副本数限制，避免容器过多占用系统资源
- 线程池大小合理配置，平衡并发能力与资源消耗

可观测性

Token 使用统计：内置 Token 用量统计中间件，精确计算每轮对话的 Token 消耗
Tracing 支持：集成 OpenTelemetry，支持全链路追踪
结构化日志：所有核心组件都有完善的日志输出，方便问题排查
监控指标：内置关键指标采集，方便对接 Prometheus/Grafana 监控体系

测试保障

单元测试覆盖率超过 80%，核心模块覆盖率 100%
边界测试：覆盖异常场景、错误输入、并发冲突等
集成测试：验证与第三方服务（LLM、MCP、沙箱等）的集成兼容性
压力测试：验证高并发场景下的稳定性和性能表现

发布与使用

独立发布为 Python 包 deerflow-harness，版本遵循 SemVer 规范
其他项目可以通过 pip install deerflow-harness 直接安装使用
提供完整的文档和示例代码，降低使用门槛
内置完整的单元测试，保证包的质量和稳定性

架构设计亮点

双模式部署支持：同时支持嵌入式部署（直接调用 Python API）和 HTTP 服务部署（Gateway + LangGraph Server），同一套代码适配不同场景
API 一致性设计：嵌入式客户端与 Gateway API 返回格式完全一致，上层应用无缝切换部署模式
插件化生态：通过 MCP、技能、自定义扩展点，形成开放的插件生态，能力可以无限扩展
跨环境兼容：支持本地开发、Docker 部署、K8s 部署等多种环境，配置自动适配

可能的演进方向

多语言支持：目前核心是 Python 实现，未来可以考虑支持多语言 SDK
分布式调度：当前沙箱和子代理执行是单机模式，未来可以扩展为分布式调度，支持大规模部署
更丰富的扩展点：增加更多的钩子函数，允许更灵活的自定义 Agent 行为
可视化编排：提供可视化界面编排 Agent 工作流，降低使用门槛

适用场景

构建 AI 助理应用：快速搭建通用 AI 助理，支持工具调用、代码执行、文件处理等能力
企业内部 Agent 平台：基于 Harness 定制企业专属的 Agent 系统，集成内部业务系统和数据
AI 研发平台：作为 Agent 运行时，支撑上层的低代码 Agent 开发平台，让非专业人员也能构建 Agent
自动化工作流：构建复杂的自动化任务流，替代人工执行重复性高、规则明确的工作
教育与研究：作为 AI Agent 研究的实验平台，快速验证新的 Agent 架构和算法