架构设计 on Zewang's Blog

DeerFlow LangGraph 运行时详解：Run Manager、Worker 与 SSE 流式

Tue, 21 Apr 2026 00:00:00 +0000

背景

在前几篇笔记中，我们分析了 Agent 架构、Sandbox 系统、Skills 机制和 Tools 工具集。这些是 DeerFlow 的"静态"组件——定义了 Agent 能做什么。

本文聚焦"动态"部分：Agent 如何运行。核心问题是：

一个对话请求如何变成后台任务？
多个请求同时到达，如何处理冲突？
如何实现 SSE 流式响应，让前端实时看到 Agent 的思考过程？
用户中途断开，任务该继续还是取消？
如何安全地中断正在执行的任务？

DeerFlow 的答案是一个精心设计的 Runtime 模块，采用三层架构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


┌─────────────────────────────────────────────┐
│ Gateway API (REST) │
│ POST /threads/{id}/runs → 创建 Run │
│ GET /threads/{id}/runs/stream → SSE │
└─────────────────────────────────────────────┘
 ↓
┌─────────────────────────────────────────────┐
│ Run Manager │
│ RunRecord 状态管理、多任务策略、取消控制 │
└─────────────────────────────────────────────┘
 ↓
┌─────────────────────────────────────────────┐
│ Worker + StreamBridge │
│ run_agent() 执行 + SSE 事件推送 │
└─────────────────────────────────────────────┘

核心文件位于：backend/packages/harness/deerflow/runtime/

📝 备注

本篇是 DeerFlow 学习系列的第 5 篇。建议先阅读：

DeerFlow 导学路线

DeerFlow Agent 架构

架构总览

目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


deerflow/runtime/
├── __init__.py # 公共 API 导出
├── runs/
│ ├── manager.py # RunManager + RunRecord
│ ├── worker.py # run_agent() 执行引擎
│ └── schemas.py # RunStatus, DisconnectMode
├── stream_bridge/
│ ├── base.py # StreamBridge 抽象基类
│ └── memory.py # MemoryStreamBridge 实现
├── serialization.py # LangChain 对象序列化
└── store.py # LangGraph Store 配置

三层职责

层级	模块	职责
管理层	RunManager	RunRecord 创建、状态流转、并发控制、取消机制
执行层	worker.run_agent()	Agent 构建与执行、LangGraph 流式、异常处理
传输层	StreamBridge	SSE 事件队列、心跳保活、断线重连

核心数据流

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


用户请求 → Gateway
 ↓
RunManager.create_or_reject() // 检查冲突、创建 RunRecord
 ↓
asyncio.create_task(run_agent()) // 后台执行
 ↓
run_agent() 构建 Agent → agent.astream() 流式执行
 ↓
每产生一个 chunk → StreamBridge.publish() 入队
 ↓
前端 SSE 连接 → StreamBridge.subscribe() 消费
 ↓
任务完成 → publish_end() → cleanup()

Run Manager：状态管理中枢

RunManager 是 Runtime 的"大脑"，负责管理所有 Run 的生命周期。

RunRecord：单次运行的数据容器

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


@dataclass
class RunRecord:
 """Mutable record for a single run."""
 
 run_id: str # UUID，唯一标识
 thread_id: str # 所属对话线程
 assistant_id: str | None # 关联的 Assistant（可选）
 status: RunStatus # 当前状态
 on_disconnect: DisconnectMode # 断开时的行为
 multitask_strategy: str # 多任务策略：reject/interrupt/rollback
 metadata: dict # 用户自定义元数据
 kwargs: dict # 传递给 Agent 的参数
 created_at: str # ISO 时间戳
 updated_at: str # 最后更新时间
 
 # 内部状态（不可序列化）
 task: asyncio.Task | None # 后台执行任务
 abort_event: asyncio.Event # 取消信号
 abort_action: str # 取消动作：interrupt/rollback
 error: str | None # 错误信息

设计要点：

run_id 用 UUID 确保唯一性
task 和 abort_event 是 不可序列化 的运行时状态，用 repr=False 排除
metadata 和 kwargs 支持用户传递自定义配置

RunStatus：状态枚举

1
2
3
4
5
6
7


class RunStatus(StrEnum):
 pending = "pending" # 已创建，等待执行
 running = "running" # 正在执行
 success = "success" # 成功完成
 error = "error" # 执行失败
 timeout = "timeout" # 超时（预留）
 interrupted = "interrupted" # 用户中断

状态流转图：

1
2
3


pending → running → success/error/interrupted
 ↑
 └── cancel() 可从 pending/running 转到 interrupted

DisconnectMode：断开行为

1
2
3


class DisconnectMode(StrEnum):
 cancel = "cancel" # 用户断开 → 立即取消任务
 continue_ = "continue" # 用户断开 → 后台继续执行

默认是 cancel，符合大多数场景预期。continue_ 用于异步任务（如生成报告后发送邮件）。

RunManager 核心方法

1. create()：创建 Run

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


async def create(
 self,
 thread_id: str,
 assistant_id: str | None = None,
 *,
 on_disconnect: DisconnectMode = DisconnectMode.cancel,
 metadata: dict | None = None,
 kwargs: dict | None = None,
 multitask_strategy: str = "reject",
) -> RunRecord:
 """Create a new pending run and register it."""
 run_id = str(uuid.uuid4())
 now = _now_iso()
 record = RunRecord(...)
 
 async with self._lock:
 self._runs[run_id] = record
 return record

注意：所有状态修改都在 async with self._lock 下进行，确保并发安全。

2. create_or_reject()：原子性检查与创建

这是最关键的方法，解决 TOCTOU（Time-of-check to time-of-use）竞态：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


async def create_or_reject(
 self,
 thread_id: str,
 ...,
 multitask_strategy: str = "reject",
) -> RunRecord:
 """Atomically check for inflight runs and create a new one."""
 
 async with self._lock: # 整个检查+创建在锁内完成
 # 1. 检查是否有正在执行的 Run
 inflight = [r for r in self._runs.values() 
 if r.thread_id == thread_id 
 and r.status in (RunStatus.pending, RunStatus.running)]
 
 # 2. 根据策略处理
 if multitask_strategy == "reject" and inflight:
 raise ConflictError(f"Thread {thread_id} already has an active run")
 
 if multitask_strategy in ("interrupt", "rollback") and inflight:
 for r in inflight:
 r.abort_action = multitask_strategy
 r.abort_event.set()
 if r.task and not r.task.done():
 r.task.cancel()
 r.status = RunStatus.interrupted
 
 # 3. 创建新 Run
 record = RunRecord(...)
 self._runs[run_id] = record
 
 return record

三种 multitask_strategy：

策略	行为	适用场景
`reject`	有冲突 → 抛异常	默认，防止用户误操作
`interrupt`	中断旧任务，保留 checkpoint	用户想重新提问
`rollback`	中断旧任务，回滚到 pre-run 状态	取消整个任务

3. cancel()：主动取消

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


async def cancel(self, run_id: str, *, action: str = "interrupt") -> bool:
 """Request cancellation of a run."""
 async with self._lock:
 record = self._runs.get(run_id)
 if not record or record.status not in (RunStatus.pending, RunStatus.running):
 return False
 
 record.abort_action = action
 record.abort_event.set() # 触发信号
 if record.task and not record.task.done():
 record.task.cancel() # 取消 asyncio.Task
 record.status = RunStatus.interrupted
 return True

abort_event 是关键：Worker 在每次 astream() 循环中检查 abort_event.is_set()，实现 优雅中断。

4. cleanup()：延迟清理

1
2
3
4
5
6


async def cleanup(self, run_id: str, *, delay: float = 300) -> None:
 """Remove a run record after an optional delay."""
 if delay > 0:
 await asyncio.sleep(delay)
 async with self._lock:
 self._runs.pop(run_id, None)

默认延迟 300 秒，给迟到的客户端留出重连时间。

Worker：执行引擎

run_agent() 是 Agent 执行的核心函数，在后台 asyncio.Task 中运行。

执行流程概览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


async def run_agent(
 bridge: StreamBridge,
 run_manager: RunManager,
 record: RunRecord,
 *,
 checkpointer: Any,
 store: Any | None = None,
 agent_factory: Any,
 graph_input: dict,
 config: dict,
 stream_modes: list[str] | None = None,
 stream_subgraphs: bool = False,
 interrupt_before: list[str] | Literal["*"] | None = None,
 interrupt_after: list[str] | Literal["*"] | None = None,
) -> None:

完整流程：

1
2
3
4
5
6
7
8
9


1. set_status(running)
2. 记录 pre_run_checkpoint_id（用于 rollback）
3. publish("metadata", {run_id, thread_id})
4. 构建 Agent（注入 Runtime、Checkpointer、Store）
5. 配置 interrupt_before/after
6. 处理 stream_modes → 转为 LangGraph 内部模式
7. agent.astream() 循环 → publish 每个 chunk
8. 处理中断/异常 → set_status 最终状态
9. publish_end() → cleanup()

关键步骤详解

步骤 1：标记运行状态

1

await run_manager.set_status(run_id, RunStatus.running)

步骤 2：记录 pre-run checkpoint

1
2
3
4
5
6
7
8


pre_run_checkpoint_id = None
try:
 config_for_check = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
 ckpt_tuple = await checkpointer.aget_tuple(config_for_check)
 if ckpt_tuple is not None:
 pre_run_checkpoint_id = getattr(ckpt_tuple, "config", {}).get("configurable", {}).get("checkpoint_id")
except Exception:
 logger.debug("Could not get pre-run checkpoint_id")

这是为 rollback 策略预留：中断时可以回滚到 Run 开始前的状态。

步骤 3：构建 Agent

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


from langchain_core.runnables import RunnableConfig
from langgraph.runtime import Runtime

# 注入 Runtime context（让 middleware 能访问 thread_id）
runtime = Runtime(context={"thread_id": thread_id}, store=store)
config.setdefault("configurable", {})["__pregel_runtime"] = runtime

runnable_config = RunnableConfig(**config)
agent = agent_factory(config=runnable_config)

# 挂载 checkpointer 和 store
if checkpointer:
 agent.checkpointer = checkpointer
if store:
 agent.store = store

Runtime 注入：LangGraph 的 Middleware 需要访问 thread_id，这里手动注入（langgraph-cli 会自动做，但 Gateway 需要自己处理）。

步骤 4：处理 stream_modes

LangGraph 的 astream() 支持多种模式，但 Gateway 需要适配：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


_VALID_LG_MODES = {"values", "updates", "checkpoints", "tasks", "debug", "messages", "custom"}

lg_modes: list[str] = []
for m in requested_modes:
 if m == "messages-tuple":
 lg_modes.append("messages") # 用户请求 "messages-tuple" → 内部用 "messages"
 elif m == "events":
 continue # "events" 模式不支持（需要 astream_events）
 elif m in _VALID_LG_MODES:
 lg_modes.append(m)

if not lg_modes:
 lg_modes = ["values"] # 默认模式

关于 “events” 模式：

1
2


if "events" in requested_modes:
 logger.info("'events' stream_mode not supported in gateway (requires astream_events + checkpoint callbacks). Skipping.")

events 模式需要 graph.astream_events()，它不能同时产生 values 快照。LangGraph JS 版通过内部 checkpoint callbacks 实现，但 Python 公共 API 没暴露。

步骤 5：流式循环

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


if len(lg_modes) == 1 and not stream_subgraphs:
 # 单模式，无 subgraphs：astream 直接 yield chunk
 single_mode = lg_modes[0]
 async for chunk in agent.astream(graph_input, config=runnable_config, stream_mode=single_mode):
 if record.abort_event.is_set(): # 检查中断信号
 logger.info("Run %s abort requested — stopping", run_id)
 break
 sse_event = _lg_mode_to_sse_event(single_mode)
 await bridge.publish(run_id, sse_event, serialize(chunk, mode=single_mode))
else:
 # 多模式或 subgraphs：astream yield tuple
 async for item in agent.astream(graph_input, config=runnable_config, stream_mode=lg_modes, subgraphs=stream_subgraphs):
 if record.abort_event.is_set():
 break
 mode, chunk = _unpack_stream_item(item, lg_modes, stream_subgraphs)
 if mode is None:
 continue
 sse_event = _lg_mode_to_sse_event(mode)
 await bridge.publish(run_id, sse_event, serialize(chunk, mode=mode))

关键点：

每次 chunk 都检查 abort_event.is_set()
serialize() 处理 LangChain 对象 → JSON

步骤 6：最终状态处理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


if record.abort_event.is_set():
 action = record.abort_action
 if action == "rollback":
 await run_manager.set_status(run_id, RunStatus.error, error="Rolled back by user")
 # TODO(Phase 2): 实现 checkpoint 回滚
 logger.info("Run %s rolled back", run_id)
 else:
 await run_manager.set_status(run_id, RunStatus.interrupted)
else:
 await run_manager.set_status(run_id, RunStatus.success)

rollback 的 TODO：当前只记录状态，真正的 checkpoint 回滚是 Phase 2 工作。

步骤 7：异常处理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


except asyncio.CancelledError:
 # Task 被 cancel() 取消
 action = record.abort_action
 if action == "rollback":
 await run_manager.set_status(run_id, RunStatus.error, error="Rolled back by user")
 else:
 await run_manager.set_status(run_id, RunStatus.interrupted)

except Exception as exc:
 # Agent 执行异常
 error_msg = f"{exc}"
 await run_manager.set_status(run_id, RunStatus.error, error=error_msg)
 await bridge.publish(run_id, "error", {"message": error_msg, "name": type(exc).__name__})

finally:
 await bridge.publish_end(run_id)
 asyncio.create_task(bridge.cleanup(run_id, delay=60))

StreamBridge：SSE 流式响应

StreamBridge 解耦了 生产者（Worker）和 消费者（SSE Endpoint）。

抽象接口

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


class StreamBridge(abc.ABC):
 @abc.abstractmethod
 async def publish(self, run_id: str, event: str, data: Any) -> None:
 """Enqueue a single event for *run_id*."""
 
 @abc.abstractmethod
 async def publish_end(self, run_id: str) -> None:
 """Signal that no more events will be produced."""
 
 @abc.abstractmethod
 def subscribe(self, run_id: str, *, last_event_id: str | None = None, heartbeat_interval: float = 15.0) -> AsyncIterator[StreamEvent]:
 """Async iterator yielding events for *run_id*."""
 
 @abc.abstractmethod
 async def cleanup(self, run_id: str, *, delay: float = 0) -> None:
 """Release resources for *run_id*."""

StreamEvent 数据结构

1
2
3
4
5


@dataclass(frozen=True)
class StreamEvent:
 id: str # 递增 ID，用于 SSE `id:` 字段
 event: str # SSE event name: metadata/updates/values/messages/error/end
 data: Any # JSON payload

两个特殊 Sentinel：

1
2


HEARTBEAT_SENTINEL = StreamEvent(id="", event="__heartbeat__", data=None) # 心跳
END_SENTINEL = StreamEvent(id="", event="__end__", data=None) # 结束

MemoryStreamBridge 实现

内存实现，基于 asyncio.Condition 实现生产者-消费者模式。

核心数据结构

1
2
3
4
5
6


@dataclass
class _RunStream:
 events: list[StreamEvent] = field(default_factory=list)
 condition: asyncio.Condition = field(default_factory=asyncio.Condition)
 ended: bool = False
 start_offset: int = 0 # 因 buffer overflow 被丢弃的事件数

publish：入队

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


async def publish(self, run_id: str, event: str, data: Any) -> None:
 stream = self._get_or_create_stream(run_id)
 entry = StreamEvent(id=self._next_id(run_id), event=event, data=data)
 
 async with stream.condition:
 stream.events.append(entry)
 # buffer 限制：超过 maxsize 删除旧事件
 if len(stream.events) > self._maxsize:
 overflow = len(stream.events) - self._maxsize
 del stream.events[:overflow]
 stream.start_offset += overflow
 stream.condition.notify_all() # 唤醒等待的消费者

buffer overflow 处理：保留最近 256 个事件，旧事件被丢弃但 start_offset 记录偏移。

subscribe：消费

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


async def subscribe(
 self,
 run_id: str,
 *,
 last_event_id: str | None = None,
 heartbeat_interval: float = 15.0,
) -> AsyncIterator[StreamEvent]:
 stream = self._get_or_create_stream(run_id)
 
 # 解析起始位置（支持 Last-Event-ID 重连）
 async with stream.condition:
 next_offset = self._resolve_start_offset(stream, last_event_id)
 
 while True:
 async with stream.condition:
 # 检查是否落后于 retained buffer
 if next_offset < stream.start_offset:
 logger.warning("subscriber fell behind; resuming from offset %s", stream.start_offset)
 next_offset = stream.start_offset
 
 local_index = next_offset - stream.start_offset
 if 0 <= local_index < len(stream.events):
 # 有事件：取出并前进
 entry = stream.events[local_index]
 next_offset += 1
 elif stream.ended:
 # 已结束：返回 END_SENTINEL
 entry = END_SENTINEL
 else:
 # 无事件：等待或超时返回心跳
 try:
 await asyncio.wait_for(stream.condition.wait(), timeout=heartbeat_interval)
 except TimeoutError:
 entry = HEARTBEAT_SENTINEL
 else:
 continue # 被唤醒，重新检查
 
 if entry is END_SENTINEL:
 yield END_SENTINEL
 return
 yield entry

关键特性：

Last-Event-ID 重连：客户端断开后重连，可从上次位置继续
心跳保活：15 秒无事件 → 返回 HEARTBEAT_SENTINEL，防止连接超时
buffer overflow 处理：客户端落后太多 → 从当前最早保留事件开始

SSE Endpoint 使用示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# Gateway 路由
@router.get("/threads/{thread_id}/runs/{run_id}/stream")
async def stream_run(thread_id: str, run_id: str, request: Request):
 last_event_id = request.headers.get("Last-Event-ID")
 
 async def generate():
 for event in bridge.subscribe(run_id, last_event_id=last_event_id):
 if event is HEARTBEAT_SENTINEL:
 yield ": heartbeat\n\n" # SSE comment
 elif event is END_SENTINEL:
 yield "event: end\ndata: {}\n\n"
 return
 else:
 yield f"id: {event.id}\nevent: {event.event}\ndata: {json.dumps(event.data)}\n\n"
 
 return StreamingResponse(generate(), media_type="text/event-stream")

序列化：LangChain 对象 → JSON

LangChain/LangGraph 对象（Message、State）不能直接 JSON 序列化，需要特殊处理。

serialize() 函数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


def serialize(obj: Any, *, mode: str = "") -> Any:
 """Serialize LangChain objects with mode-specific handling."""
 
 if mode == "messages":
 # messages-tuple: (chunk, metadata)
 return serialize_messages_tuple(obj)
 
 if mode == "values":
 # values: full state dict，删除内部 __pregel_* keys
 return serialize_channel_values(obj)
 
 return serialize_lc_object(obj)

serialize_lc_object：通用递归

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


def serialize_lc_object(obj: Any) -> Any:
 if obj is None:
 return None
 if isinstance(obj, (str, int, float, bool)):
 return obj
 if isinstance(obj, dict):
 return {k: serialize_lc_object(v) for k, v in obj.items()}
 if isinstance(obj, (list, tuple)):
 return [serialize_lc_object(item) for item in obj]
 
 # Pydantic v2
 if hasattr(obj, "model_dump"):
 return obj.model_dump()
 # Pydantic v1
 if hasattr(obj, "dict"):
 return obj.dict()
 # Fallback
 return str(obj)

serialize_channel_values：过滤内部键

1
2
3
4
5
6
7
8


def serialize_channel_values(channel_values: dict) -> dict:
 result = {}
 for key, value in channel_values.items():
 # 删除 LangGraph 内部键
 if key.startswith("__pregel_") or key == "__interrupt__":
 continue
 result[key] = serialize_lc_object(value)
 return result

__pregel_* 是 LangGraph 的内部状态键（如 __pregel_task_id），不应暴露给前端。

状态流转与取消机制

完整状态流转图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


 create()
 ↓
 ┌─────────┐
 │ pending │
 └─────────┘
 ↓ set_status(running)
 ┌─────────┐
 │ running │ ←─────────────────────┐
 └─────────┘ │
 ┌──────────┼──────────┬──────────┐ │
 ↓ ↓ ↓ ↓ │
 ┌─────────┐ ┌─────────┐ ┌───────────┐ ┌──────┐ │
 │ success │ │ error │ │interrupted│ │timeout│ │
 └─────────┘ └─────────┘ └───────────┘ └──────┘ │
 ↑ │
 │ cancel() │
 └────────────────────────┘

取消机制详解

取消涉及两个层面：

Task 层面：asyncio.Task.cancel() → 抛 CancelledError
Agent 层面：abort_event.set() → 在 astream 循环中检测并退出

为什么需要两种？

Task.cancel() 是强制中断，Agent 可能正在 LLM 调用中
abort_event.set() 是优雅中断，Agent 可以完成当前 chunk 再退出

DeerFlow 采用 混合策略：

1
2
3
4


async def cancel(self, run_id: str, *, action: str = "interrupt") -> bool:
 record.abort_event.set() # 先设置信号
 if record.task and not record.task.done():
 record.task.cancel() # 再取消 Task

Worker 处理：

1
2
3
4
5
6


async for chunk in agent.astream(...):
 if record.abort_event.is_set(): # 每次循环检查
 break # 优雅退出

except asyncio.CancelledError: # Task 强制取消
 # 处理状态

interrupt vs rollback

动作	checkpoint 处理	适用场景
`interrupt`	保留当前 checkpoint	用户想暂停后继续
`rollback`	回滚到 pre-run checkpoint	用户想完全取消

当前 rollback 实现是 TODO（Phase 2），核心思路：

1
2
3
4
5


# Phase 2: 回滚到 pre_run_checkpoint_id
if checkpointer and pre_run_checkpoint_id:
 # 调用 checkpointer.adelete() 或类似 API
 # 删除 run 期间产生的所有 checkpoint
 pass

总结

核心设计亮点

三层解耦：Manager 负责状态、Worker 负责执行、Bridge 负责传输
原子性并发控制：create_or_reject() 在锁内完成检查+创建，避免 TOCTOU
优雅中断：abort_event + Task.cancel() 双重机制
SSE 流式：基于 asyncio.Condition 的生产者-消费者模式
断线重连：Last-Event-ID + buffer retention

对比：DeerFlow Runtime vs LangGraph Platform API

特性	DeerFlow Runtime	LangGraph Platform
Run 状态管理	自定义 RunManager	LangGraph Server 内置
多任务策略	reject/interrupt/rollback	仅 reject
SSE 流式	自定义 StreamBridge	内置 Queue + StreamManager
断线重连	Last-Event-ID + buffer	同样支持
取消机制	interrupt + rollback	仅 interrupt
Checkpoint 回滚	TODO (Phase 2)	内置支持

关键文件索引

文件	核心类/函数	作用
`runs/manager.py`	`RunManager`, `RunRecord`	状态管理
`runs/worker.py`	`run_agent()`	执行引擎
`runs/schemas.py`	`RunStatus`, `DisconnectMode`	状态枚举
`stream_bridge/base.py`	`StreamBridge`	抽象接口
`stream_bridge/memory.py`	`MemoryStreamBridge`	内存实现
`serialization.py`	`serialize()`	LangChain → JSON

学习建议

跟踪一次完整请求：从 Gateway POST → RunManager → Worker → SSE
理解 asyncio 并发：Condition, Event, Task.cancel() 的配合
尝试并发请求：观察 multitask_strategy=reject 的冲突处理
测试断线重连：关闭 SSE 连接，用 Last-Event-ID 重连

后续预告

下一篇将深入 Subagents 并行执行，包括：

task() 工具的调用机制
SubagentExecutor 的线程池管理
并发控制（max 3，timeout 15min）
结果合并与错误处理

📝 备注

本系列笔记持续更新中，欢迎关注 Zewang’s Blog 获取最新内容。

DeerFlow Sandbox 系统详解：从抽象接口到容器隔离

Wed, 15 Apr 2026 00:00:00 +0000

背景

Sandbox 是 DeerFlow 的"执行引擎"，让 Agent 真能做事——不只是聊天，还能：

执行 bash 命令
读写文件
搜索文件内容
编写代码并运行

核心问题：如何给 Agent 一个安全、隔离、可重复的执行环境？

DeerFlow 的答案是 Sandbox abstraction + Provider 模式 + 路径映射：

Sandbox：抽象接口，定义能做什么
SandboxProvider：工厂模式，负责创建和管理 Sandbox 实例
LocalSandbox：本地模式，直接在宿主机执行
AioSandbox：容器模式，隔离的 Docker 环境

架构总览

三层设计

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


┌─────────────────────────────────────────────┐
│ Sandbox Tools (tools.py) │
│ bash / read_file / write_file / grep / ... │
│ ↑ 调用 Sandbox 实例 │
├─────────────────────────────────────────────┤
│ Sandbox (抽象基类) │
│ execute_command / read_file / write_file │
│ list_dir / glob / grep │
├─────────────────────────────────────────────┤
│ SandboxProvider (抽象工厂) │
│ acquire() / get() / release() │
├──────────┬──────────┬───────────────────────┤
│ Local │ Aio │ (其他实现) │
│ Provider │ Provider │ K8s/Remote... │
└──────────┴──────────┴───────────────────────┘

核心文件位置

文件	路径	职责
`sandbox.py`	`deerflow/sandbox/sandbox.py`	Sandbox 抽象基类
`sandbox_provider.py`	`deerflow/sandbox/sandbox_provider.py`	SandboxProvider 抽象工厂
`local_sandbox.py`	`deerflow/sandbox/local/local_sandbox.py`	LocalSandbox 实现
`local_sandbox_provider.py`	`deerflow/sandbox/local/local_sandbox_provider.py`	LocalSandboxProvider 实现
`aio_sandbox.py`	`deerflow/community/aio_sandbox/aio_sandbox.py`	AioSandbox 实现
`aio_sandbox_provider.py`	`deerflow/community/aio_sandbox/aio_sandbox_provider.py`	AioSandboxProvider 实现
`tools.py`	`deerflow/sandbox/tools.py`	7 个 Sandbox Tools

Sandbox 抽象基类

Sandbox 是抽象基类，定义了所有 Sandbox 必须实现的接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


class Sandbox(ABC):
 """Abstract base class for sandbox environments"""

 _id: str

 def __init__(self, id: str):
 self._id = id

 @property
 def id(self) -> str:
 return self._id

 # === 7 个抽象方法 ===

 @abstractmethod
 def execute_command(self, command: str) -> str:
 """执行 bash 命令"""
 pass

 @abstractmethod
 def read_file(self, path: str) -> str:
 """读取文件内容"""
 pass

 @abstractmethod
 def write_file(self, path: str, content: str, append: bool = False) -> None:
 """写入文件"""
 pass

 @abstractmethod
 def list_dir(self, path: str, max_depth=2) -> list[str]:
 """列出目录内容"""
 pass

 @abstractmethod
 def glob(self, path: str, pattern: str, ...) -> tuple[list[str], bool]:
 """glob 模式搜索"""
 pass

 @abstractmethod
 def grep(self, path: str, pattern: str, ...) -> tuple[list[GrepMatch], bool]:
 """文件内容搜索"""
 pass

 @abstractmethod
 def update_file(self, path: str, content: bytes) -> None:
 """更新文件（二进制）"""
 pass

7 个核心方法

方法	用途	Tool 对应
`execute_command`	执行 bash 命令	`bash` tool
`read_file`	读取文件内容	`read_file` tool
`write_file`	写入文件	`write_file` tool
`list_dir`	列出目录结构	`ls` tool
`glob`	glob 模式匹配	`glob` tool
`grep`	文件内容搜索	`grep` tool
`update_file`	二进制写入	内部使用

📝 备注

所有方法都是同步的。AioSandbox 通过 HTTP API 调用远程服务，但接口保持同步语义。

SandboxProvider 抽象工厂

SandboxProvider 是工厂模式，负责创建和管理 Sandbox 实例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


class SandboxProvider(ABC):
 """Abstract base class for sandbox providers"""

 @abstractmethod
 def acquire(self, thread_id: str | None = None) -> str:
 """获取 sandbox，返回 sandbox_id"""
 pass

 @abstractmethod
 def get(self, sandbox_id: str) -> Sandbox | None:
 """根据 ID 获取 Sandbox 实例"""
 pass

 @abstractmethod
 def release(self, sandbox_id: str) -> None:
 """释放 sandbox"""
 pass

生命周期

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


acquire(thread_id) → sandbox_id
 │
 ├─► 如果已存在：返回现有 sandbox_id
 │ （同一 thread_id 复用）
 │
 └─► 如果不存在：创建新 sandbox

get(sandbox_id) → Sandbox 实例
 │
 └─► 用于执行具体操作

release(sandbox_id)
 │
 └─► 释放资源，清理 sandbox

单例模式

全局单例 + 配置驱动：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


_default_sandbox_provider: SandboxProvider | None = None

def get_sandbox_provider(**kwargs) -> SandboxProvider:
 global _default_sandbox_provider
 if _default_sandbox_provider is None:
 config = get_app_config()
 # 从 config.sandbox.use 解析类名
 cls = resolve_class(config.sandbox.use, SandboxProvider)
 _default_sandbox_provider = cls(**kwargs)
 return _default_sandbox_provider

配置示例 (config.yaml)：

1
2
3
4
5
6
7


sandbox:
 use: deerflow.community.aio_sandbox:AioSandboxProvider  # 容器模式
 # use: deerflow.sandbox.local:LocalSandboxProvider # 本地模式
 image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
 port: 8080
 idle_timeout: 600 # 10分钟无活动自动清理
 replicas: 3 # 最大并发 sandbox 数

辅助函数

函数	用途
`get_sandbox_provider()`	获取单例
`reset_sandbox_provider()`	重置单例（测试用）
`shutdown_sandbox_provider()`	关闭并清理所有 sandbox
`set_sandbox_provider(provider)`	注入自定义 provider（测试用）

LocalSandbox：本地模式

LocalSandbox 直接在宿主机执行，适合开发调试。

PathMapping：路径映射

核心设计是 虚拟路径 → 本地路径 的映射：

1
2
3
4
5


@dataclass(frozen=True)
class PathMapping:
 container_path: str # Agent 看到的路径（虚拟）
 local_path: str # 实际物理路径
 read_only: bool = False

典型映射：

虚拟路径	本地路径	只读
`/mnt/skills`	`deer-flow/skills/`	True
`/mnt/user-data/workspace`	`.deer-flow/threads/{id}/user-data/workspace`	False
`/mnt/custom-mount`	`/home/user/my-data`	自定义

双向路径转换

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


class LocalSandbox(Sandbox):
 def _resolve_path(self, path: str) -> str:
 """虚拟路径 → 本地路径"""
 for mapping in sorted(self.path_mappings, key=lambda m: len(m.container_path), reverse=True):
 if path.startswith(mapping.container_path + "/"):
 relative = path[len(mapping.container_path):].lstrip("/")
 return str(Path(mapping.local_path) / relative)
 return path

 def _reverse_resolve_path(self, path: str) -> str:
 """本地路径 → 虚拟路径"""
 for mapping in sorted(self.path_mappings, key=lambda m: len(m.local_path), reverse=True):
 local_resolved = str(Path(mapping.local_path).resolve())
 if path.startswith(local_resolved + "/"):
 relative = path[len(local_resolved):].lstrip("/")
 return f"{mapping.container_path}/{relative}"
 return path

💡 提示

Agent 看到的是虚拟路径，但实际操作的是本地路径。输出结果再转回虚拟路径，保持一致性。

execute_command 实现

跨平台 shell 检测 + 路径替换：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


def execute_command(self, command: str) -> str:
 # 1. 替换命令中的虚拟路径
 resolved_command = self._resolve_paths_in_command(command)
 
 # 2. 检测可用的 shell
 shell = self._get_shell() # zsh > bash > sh > PowerShell > cmd
 
 # 3. 执行命令
 result = subprocess.run(
 resolved_command,
 executable=shell,
 shell=True,
 capture_output=True,
 text=True,
 timeout=600, # 10 分钟超时
 )
 
 # 4. 输出中转回虚拟路径
 return self._reverse_resolve_paths_in_output(output)

路径替换逻辑：

1
2
3
4
5


def _resolve_paths_in_command(self, command: str) -> str:
 """用正则替换命令中的虚拟路径"""
 patterns = [re.escape(m.container_path) + r"(?=/|$|\s)" for m in self.path_mappings]
 pattern = re.compile("|".join(f"({p})" for p in patterns))
 return pattern.sub(lambda m: self._resolve_path(m.group(0)), command)

例如：ls /mnt/skills/public/ → ls /path/to/deer-flow/skills/public/

文件操作方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


def read_file(self, path: str) -> str:
 resolved_path = self._resolve_path(path)
 with open(resolved_path, encoding="utf-8") as f:
 return f.read()

def write_file(self, path: str, content: str, append: bool = False) -> None:
 resolved_path = self._resolve_path(path)
 
 # 检查只读路径
 if self._is_read_only_path(resolved_path):
 raise OSError(errno.EROFS, "Read-only file system", path)
 
 os.makedirs(os.path.dirname(resolved_path), exist_ok=True)
 with open(resolved_path, "a" if append else "w", encoding="utf-8") as f:
 f.write(content)

def glob(self, path: str, pattern: str, ...) -> tuple[list[str], bool]:
 resolved_path = Path(self._resolve_path(path))
 matches, truncated = find_glob_matches(resolved_path, pattern, ...)
 # 转回虚拟路径
 return [self._reverse_resolve_path(m) for m in matches], truncated

LocalSandboxProvider：单例工厂

LocalSandboxProvider 使用单例模式，所有 thread 共享同一个 sandbox：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


_singleton: LocalSandbox | None = None

class LocalSandboxProvider(SandboxProvider):
 def __init__(self):
 self._path_mappings = self._setup_path_mappings()
 
 def acquire(self, thread_id: str | None = None) -> str:
 global _singleton
 if _singleton is None:
 _singleton = LocalSandbox("local", path_mappings=self._path_mappings)
 return _singleton.id # 永远返回 "local"
 
 def get(self, sandbox_id: str) -> Sandbox | None:
 if sandbox_id == "local":
 return _singleton
 return None
 
 def release(self, sandbox_id: str) -> None:
 # 单例模式，无需清理
 pass

路径映射配置

从 config.yaml 加载映射：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


def _setup_path_mappings(self) -> list[PathMapping]:
 mappings: list[PathMapping] = []
 
 # 1. Skills 目录（只读）
 skills_path = config.skills.get_skills_path()
 mappings.append(PathMapping(
 container_path="/mnt/skills",
 local_path=str(skills_path),
 read_only=True,
 ))
 
 # 2. 自定义挂载
 for mount in config.sandbox.mounts:
 mappings.append(PathMapping(
 container_path=mount.container_path,
 local_path=mount.host_path,
 read_only=mount.read_only,
 ))
 
 return mappings

配置示例：

1
2
3
4
5


sandbox:
 mounts:
 - host_path: /home/user/projects
 container_path: /mnt/projects
 read_only: false

📝 备注

LocalSandbox 是单例，所有 thread 共享。适合开发，不适合生产（无隔离）。

AioSandbox：容器模式

AioSandbox 通过 HTTP API 连接到 Docker 容器，实现真正的隔离环境。

架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


┌──────────────────────┐
│ AioSandbox │
│ (Python 客户端) │
├──────────────────────┤
│ HTTP API 调用 │
│ ↓ │
├──────────────────────┤
│ agent-infra/sandbox │
│ (Docker 容器) │
│ - Shell 执行 │
│ - 文件读写 │
│ - 搜索功能 │
└──────────────────────┘

初始化

1
2
3
4
5
6
7


class AioSandbox(Sandbox):
 def __init__(self, id: str, base_url: str, home_dir: str | None = None):
 super().__init__(id)
 self._base_url = base_url
 self._client = AioSandboxClient(base_url=base_url, timeout=600)
 self._home_dir = home_dir
 self._lock = threading.Lock() # 序列化并发请求

⚠️ 警告

容器内只有一个持久 shell session。并发请求会互相干扰，需要用 threading.Lock 序列化。

execute_command 实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


def execute_command(self, command: str) -> str:
 with self._lock:
 try:
 result = self._client.shell.exec_command(command=command)
 output = result.data.output if result.data else ""

 # 检测错误签名（并发干扰导致的 ErrorObservation）
 if "ErrorObservation" in output:
 logger.warning("Session corrupted, retrying with fresh session")
 fresh_id = str(uuid.uuid4())
 result = self._client.shell.exec_command(command=command, id=fresh_id)
 output = result.data.output if result.data else ""

 return output if output else "(no output)"
 except Exception as e:
 return f"Error: {e}"

文件操作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


def read_file(self, path: str) -> str:
 result = self._client.file.read_file(file=path)
 return result.data.content if result.data else ""

def write_file(self, path: str, content: str, append: bool = False) -> None:
 with self._lock:
 if append:
 existing = self.read_file(path)
 content = existing + content
 self._client.file.write_file(file=path, content=content)

glob / grep 实现

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


def glob(self, path: str, pattern: str, ...) -> tuple[list[str], bool]:
 result = self._client.file.find_files(path=path, glob=pattern)
 files = result.data.files or []
 return files[:max_results], len(files) > max_results

def grep(self, path: str, pattern: str, ...) -> tuple[list[GrepMatch], bool]:
 regex = f"(?i){pattern}" if not case_sensitive else pattern
 # 1. 先找候选文件（glob 或 list_path）
 # 2. 逐文件调用 search_in_file
 for file_path in candidate_paths:
 result = self._client.file.search_in_file(file=file_path, regex=regex)
 # 构建 GrepMatch...
 return matches, truncated

AioSandboxProvider：容器池管理

AioSandboxProvider 是复杂的容器生命周期管理器，核心特性：

多层缓存：in-process → warm pool → backend discovery
确定性 ID：同一 thread_id 总是得到相同 sandbox_id
Warm pool：release 不销毁容器，下次可快速复用
Idle timeout：后台线程定期清理空闲容器
Backend 抽象：支持本地 Docker 和远程 K8s

缓存层次

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


acquire(thread_id)
 │
 ├─► Layer 1: in-process cache（最快）
 │ _thread_sandboxes[thread_id] → sandbox_id
 │
 ├─► Layer 1.5: warm pool（容器还在运行）
 │ _warm_pool[sandbox_id] → (info, release_ts)
 │
 └─► Layer 2: backend discovery + create
 │ 跨进程文件锁保护
 │ _backend.discover() 或 _backend.create()

确定性 sandbox_id

1
2
3
4


@staticmethod
def _deterministic_sandbox_id(thread_id: str) -> str:
 """从 thread_id 生成确定性 sandbox_id"""
 return hashlib.sha256(thread_id.encode()).hexdigest()[:8]

意义：多个进程访问同一 thread_id 时，生成的 sandbox_id 相同，可以发现对方创建的容器。

Warm Pool 机制

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


def release(self, sandbox_id: str) -> None:
 """释放 sandbox 到 warm pool（容器继续运行）"""
 info = self._sandbox_infos.pop(sandbox_id)
 self._sandboxes.pop(sandbox_id)
 
 # 不销毁容器，放入 warm pool
 if info:
 self._warm_pool[sandbox_id] = (info, time.time())

def acquire(self, thread_id: str) -> str:
 # 先检查 warm pool
 if sandbox_id in self._warm_pool:
 info, _ = self._warm_pool.pop(sandbox_id)
 sandbox = AioSandbox(id=sandbox_id, base_url=info.sandbox_url)
 self._sandboxes[sandbox_id] = sandbox
 return sandbox_id # 无冷启动

效果：下次访问同一 thread 时，直接从 warm pool 取回，无需创建新容器。

跨进程文件锁

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


def _discover_or_create_with_lock(self, thread_id: str, sandbox_id: str) -> str:
 lock_path = paths.thread_dir(thread_id) / f"{sandbox_id}.lock"
 
 with open(lock_path, "a") as lock_file:
 fcntl.flock(lock_file, fcntl.LOCK_EX) # 跨进程锁
 
 # 再次检查缓存（可能其他进程刚创建）
 discovered = self._backend.discover(sandbox_id)
 if discovered:
 return discovered.sandbox_id
 
 # 确实需要创建
 return self._create_sandbox(thread_id, sandbox_id)

Idle Timeout 管理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


def _idle_checker_loop(self) -> None:
 while not self._idle_checker_stop.wait(timeout=60):
 self._cleanup_idle_sandboxes(idle_timeout)

def _cleanup_idle_sandboxes(self, idle_timeout: float) -> None:
 current_time = time.time()
 
 # 检查 active sandboxes
 for sandbox_id, last_activity in self._last_activity.items():
 if current_time - last_activity > idle_timeout:
 self.destroy(sandbox_id)
 
 # 检查 warm pool
 for sandbox_id, (info, release_ts) in self._warm_pool.items():
 if current_time - release_ts > idle_timeout:
 self._backend.destroy(info)

Backend 抽象

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


def _create_backend(self) -> SandboxBackend:
 provisioner_url = self._config.get("provisioner_url")
 
 if provisioner_url:
 # 远程模式：K8s Provisioner 动态创建 Pod
 return RemoteSandboxBackend(provisioner_url=provisioner_url)
 
 # 本地模式：直接管理 Docker 容器
 return LocalContainerBackend(
 image=self._config["image"],
 base_port=self._config["port"],
 container_prefix=self._config["container_prefix"],
 )

两种 Backend：

Backend	场景	实现方式
LocalContainerBackend	本地开发	`docker run` 启动容器
RemoteSandboxBackend	生产部署	Provisioner API 创建 K8s Pod

配置示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


sandbox:
 use: deerflow.community.aio_sandbox:AioSandboxProvider
 image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
 port: 8080
 container_prefix: deer-flow-sandbox
 idle_timeout: 600 # 10 分钟无活动自动清理
 replicas: 3 # 最大并发容器数（LRU 淘汰）
 mounts:
 - host_path: /home/user/projects
 container_path: /mnt/projects
 read_only: false
 environment:
 NODE_ENV: production
 API_KEY: $MY_API_KEY  # 支持环境变量引用
 provisioner_url: "" # 留空用本地模式

Sandbox Tools：Agent 可调用的工具

Agent 通过 7 个工具与 Sandbox 交互：

工具	功能	核心参数
`bash`	执行命令	`command`
`ls`	列出目录	`path`
`glob`	搜索文件	`pattern`, `path`
`grep`	搜索内容	`pattern`, `path`
`read_file`	读取文件	`path`, `start_line`, `end_line`
`write_file`	写入文件	`path`, `content`, `append`
`str_replace`	替换内容	`path`, `old_str`, `new_str`

bash 工具

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


@tool("bash", parse_docstring=True)
def bash_tool(runtime, description: str, command: str) -> str:
 """Execute a bash command in a Linux environment."""
 
 sandbox = ensure_sandbox_initialized(runtime)
 
 if is_local_sandbox(runtime):
 # 1. 验证路径权限
 validate_local_bash_command_paths(command, thread_data)
 # 2. 替换虚拟路径
 command = replace_virtual_paths_in_command(command, thread_data)
 # 3. 执行并遮蔽真实路径
 output = sandbox.execute_command(command)
 return mask_local_paths_in_output(output, thread_data)
 
 # 容器模式：直接执行
 return sandbox.execute_command(command)

路径替换逻辑：

Agent 写的命令：ls /mnt/user-data/workspace/ 实际执行：ls /path/to/.deer-flow/threads/{id}/user-data/workspace/

安全限制：

1
2
3
4


# 检查路径是否在允许范围内
def validate_local_bash_command_paths(command: str, thread_data) -> None:
 for path in extract_absolute_paths(command):
 validate_local_tool_path(path, thread_data)

glob / grep 工具

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


@tool("glob", parse_docstring=True)
def glob_tool(runtime, description, pattern, path, include_dirs=False, max_results=200):
 sandbox = ensure_sandbox_initialized(runtime)
 
 if is_local_sandbox(runtime):
 path = _resolve_local_read_path(path, thread_data)
 
 matches, truncated = sandbox.glob(path, pattern, max_results=max_results)
 
 # 遮蔽真实路径
 if thread_data:
 matches = [mask_local_paths_in_output(m, thread_data) for m in matches]
 
 return _format_glob_results(requested_path, matches, truncated)

@tool("grep", parse_docstring=True)
def grep_tool(runtime, description, pattern, path, glob=None, literal=False, ...):
 matches, truncated = sandbox.grep(path, pattern, glob=glob, ...)
 return _format_grep_results(requested_path, matches, truncated)

输出格式：

1
2
3
4
5


Found 5 paths under /mnt/user-data/workspace
1. /mnt/user-data/workspace/main.py
2. /mnt/user-data/workspace/utils.py
...
Results truncated. Narrow the path or pattern to see fewer matches.

read_file / write_file 工具

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


@tool("read_file", parse_docstring=True)
def read_file_tool(runtime, description, path, start_line=None, end_line=None):
 content = sandbox.read_file(path)
 
 # 支持行范围读取
 if start_line and end_line:
 content = content.splitlines()[start_line-1:end_line]
 
 return _truncate_read_file_output(content, max_chars=50000)

@tool("write_file", parse_docstring=True)
def write_file_tool(runtime, description, path, content, append=False):
 # 文件操作锁（防止并发写入冲突）
 with get_file_operation_lock(sandbox, path):
 sandbox.write_file(path, content, append)
 return "OK"

str_replace 工具

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


@tool("str_replace", parse_docstring=True)
def str_replace_tool(runtime, description, path, old_str, new_str, replace_all=False):
 """Replace a substring in a file with another substring."""
 
 with get_file_operation_lock(sandbox, path):
 content = sandbox.read_file(path)
 
 if old_str not in content:
 return f"Error: String to replace not found in file: {path}"
 
 if replace_all:
 content = content.replace(old_str, new_str)
 else:
 content = content.replace(old_str, new_str, 1) # 只替换第一个
 
 sandbox.write_file(path, content)
 
 return "OK"

📝 备注

replace_all=False 时，old_str 必须在文件中唯一出现。否则可能误改其他位置。

路径遮蔽：防止泄露宿主机信息

Local Sandbox 模式下，Agent 看到的路径与实际路径不同：

Agent 看到的	实际路径
`/mnt/user-data/workspace`	`.deer-flow/threads/{id}/user-data/workspace`
`/mnt/skills/public`	`deer-flow/skills/public`
`/mnt/acp-workspace`	`.deer-flow/acp-workspace`

双向遮蔽

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


def mask_local_paths_in_output(output: str, thread_data) -> str:
 """将输出中的真实路径替换为虚拟路径"""
 
 # 1. 遮蔽 skills 路径
 skills_host = "/path/to/deer-flow/skills"
 skills_container = "/mnt/skills"
 output = re.sub(skills_host, skills_container, output)
 
 # 2. 遮蔽 user-data 路径
 for virtual, actual in thread_mappings.items():
 output = re.sub(actual, virtual, output)
 
 return output

效果：

Agent 执行 ls /mnt/user-data/workspace/
输出：/mnt/user-data/workspace/main.py（而非 /home/user/.deer-flow/...）

文件操作锁：防止并发冲突

多个 Agent 同时写入同一文件时，需要锁机制：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


#deerflow/sandbox/file_operation_lock.py

_locks: dict[str, threading.Lock] = {}

def get_file_operation_lock(sandbox: Sandbox, path: str) -> threading.Lock:
 """获取文件级别的操作锁"""
 lock_key = f"{sandbox.id}:{path}"
 if lock_key not in _locks:
 _locks[lock_key] = threading.Lock()
 return _locks[lock_key]

使用方式：

1
2
3
4


with get_file_operation_lock(sandbox, path):
 content = sandbox.read_file(path)
 content = content.replace(old_str, new_str)
 sandbox.write_file(path, content)

输出截断：防止超大输出

所有工具都有输出截断机制，防止 Agent 崩溃：

1
2
3
4
5
6


def _truncate_bash_output(output: str, max_chars: int = 20000) -> str:
 if len(output) <= max_chars:
 return output
 
 kept = max_chars - 200 # 留空间给提示信息
 return f"{output[:kept]}\n... [truncated: showing first {kept} of {len(output)} chars] ..."

默认限制：

工具	默认最大输出
`bash`	20000 字符
`ls`	20000 字符
`read_file`	50000 字符
`glob`	200 条结果
`grep`	100 条结果

总结

架构总览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72


┌─────────────────────────────────────────────────────────────────┐
│ Agent Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ bash │ │ glob │ │ grep │ │read_file │ ... │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │
│ Tool Runtime │
│ │ │
│ ensure_sandbox_initialized() │
│ │ │
├─────────────────────────────────────────────────────────────────┤
│ Provider Layer │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ SandboxProvider (抽象) │ │
│ │ - acquire(thread_id) → sandbox_id │ │
│ │ - get(sandbox_id) → Sandbox │ │
│ │ - release(sandbox_id) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │ │
│ │ │ │
│ ┌────────────────┐ ┌────────────────────────────┐ │
│ │LocalSandboxProv│ │ AioSandboxProvider │ │
│ │ (单例模式) │ │ (容器池管理) │ │
│ │ │ │ - Warm Pool │ │
│ │ │ │ - Idle Timeout │ │
│ │ │ │ - Backend 抽象 │ │
│ └────────────────┘ └────────────────────────────┘ │
│ │ │ │
├─────────────────────────────────────────────────────────────────┤
│ Sandbox Layer │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Sandbox (抽象接口) │ │
│ │ - execute_command(command) → output │ │
│ │ - read_file(path) → content │ │
│ │ - write_file(path, content) │ │
│ │ - glob(path, pattern) → matches │ │
│ │ - grep(path, pattern) → matches │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │ │
│ ┌────────────────┐ ┌────────────────────────────┐ │
│ │ LocalSandbox │ │ AioSandbox │ │
│ │ (宿主机执行) │ │ (HTTP API → 容器) │ │
│ │ │ │ │ │
│ │ PathMapping │ │ threading.Lock │ │
│ │ 虚拟路径映射 │ │ (序列化并发请求) │ │
│ └────────────────┘ └────────────────────────────┘ │
│ │ │
├─────────────────────────────────────────────────────────────────┤
│ Backend Layer │
│ │ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ SandboxBackend (抽象) │ │
│ │ - create(thread_id, sandbox_id) → SandboxInfo │ │
│ │ - discover(sandbox_id) → SandboxInfo | None │ │
│ │ - destroy(info) │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │ │ │
│ ┌────────────────┐ ┌────────────────────────────┐ │
│ │LocalContainer │ │ RemoteSandboxBackend │ │
│ │ Backend │ │ (Provisioner API) │ │
│ │ (docker run) │ │ (K8s Pod 动态创建) │ │
│ └────────────────┘ └────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ Docker Container │ │
│ │ (agent-infra/ │ │
│ │ sandbox) │ │
│ │ - Shell 执行 │ │
│ │ - 文件操作 │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

核心设计亮点

抽象分层：Sandbox → Provider → Backend，三层解耦，易于扩展
双模式支持：
- LocalSandbox：开发调试，零依赖，单例模式
- AioSandbox：生产部署，容器隔离，池化管理
Warm Pool 机制：release 不销毁容器，下次可快速复用，减少冷启动
确定性 ID：sha256(thread_id)[:8]，跨进程发现同一容器
路径遮蔽：Agent 只看到虚拟路径，不知道宿主机布局
输出截断：防止超大输出导致 Agent 崩溃
文件操作锁：防止并发写入冲突

两种 Provider 对比

特性	LocalSandboxProvider	AioSandboxProvider
执行环境	宿主机	Docker 容器
隔离性	无	完全隔离
冷启动	无	约 60 秒
Warm Pool	不支持	支持
Idle Timeout	不支持	支持
跨进程共享	单例（同一进程）	确定性 ID
适用场景	开发调试	生产部署

扩展新 Sandbox

只需实现 Sandbox 接口和对应 Provider：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


class MySandbox(Sandbox):
 def execute_command(self, command: str) -> str:
 # 自定义实现...
 
 def read_file(self, path: str) -> str:
 # ...
 
 # 其他方法...

class MySandboxProvider(SandboxProvider):
 def acquire(self, thread_id: str | None) -> str:
 # 创建/获取 sandbox...
 
 def get(self, sandbox_id: str) -> Sandbox | None:
 # ...
 
 def release(self, sandbox_id: str) -> None:
 # ...

然后在配置中启用：

1
2


sandbox:
 use: my_package:MySandboxProvider

补充：Sandbox 生命周期管理

Tool 注册 vs Sandbox 创建

Tool 是静态注册的，Sandbox 是动态创建的：

1
2
3
4
5


# Tool 注册：Agent 启动时就存在
@tool("bash", parse_docstring=True)
def bash_tool(runtime, description, command):
 sandbox = ensure_sandbox_initialized(runtime) # ← 这里才创建 Sandbox
 ...

惰性初始化：第一次调用任何 tool 时才创建容器，而不是预先创建。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


def ensure_sandbox_initialized(runtime):
 sandbox_id = runtime.state.get("sandbox_id")
 
 if sandbox_id:
 # 已存在 → 直接获取
 return provider.get(sandbox_id)
 
 # 不存在 → 创建新的
 sandbox_id = provider.acquire(thread_id)
 runtime.state["sandbox_id"] = sandbox_id
 return provider.get(sandbox_id)

容器生命周期流程图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


┌─────────────────────────────────────────────────────┐
│ Thread/Session │
│ │
│ 1. 用户发起对话 │
│ ↓ │
│ 2. Agent 第一次调用 tool │
│ ↓ │
│ 3. ensure_sandbox_initialized() │
│ → provider.acquire(thread_id) │
│ → 创建容器（或从 Warm Pool 取） │
│ ↓ │
│ 4. 执行 tool 操作... │
│ ↓ │
│ 5. 继续调用其他 tool │
│ → provider.get(sandbox_id) ← 直接返回已有容器 │
│ ↓ │
│ 6. Session 结束 │
│ → provider.release(sandbox_id) │
│ → 放回 Warm Pool（不删除） │
│ │
│ ───────────────────────────────────────────────── │
│ │
│ Warm Pool 中的容器： │
│ - 等待 idle_timeout（如 30 分钟） │
│ - 超时 → backend.destroy() → 删除容器 │
│ - 下次 acquire → 直接从池中取出（快速复用） │
└─────────────────────────────────────────────────────┘

AioSandboxProvider 的管理逻辑

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


class AioSandboxProvider:
 _sandboxes: dict[str, AioSandbox] = {} # 活跃的 sandbox
 _last_used: dict[str, float] = {} # 最后使用时间
 
 def acquire(self, thread_id):
 sandbox_id = deterministic_id(thread_id)
 
 # 1. 检查是否已有活跃的
 if sandbox_id in self._sandboxes:
 return sandbox_id
 
 # 2. 尝试从 Warm Pool 恢复（容器可能还在运行）
 info = backend.discover(sandbox_id)
 if info:
 # 容器还在，直接复用
 self._sandboxes[sandbox_id] = AioSandbox(info)
 return sandbox_id
 
 # 3. 真正创建新容器
 info = backend.create(thread_id, sandbox_id)
 self._sandboxes[sandbox_id] = AioSandbox(info)
 return sandbox_id
 
 def release(self, sandbox_id):
 # 不删除，只是记录时间，等待下次复用
 self._last_used[sandbox_id] = time.now()
 
 def cleanup_idle(self):
 # 定期清理超时的容器
 for sandbox_id, last_used in self._last_used.items():
 if time.now() - last_used > idle_timeout:
 backend.destroy(self._sandboxes[sandbox_id].info)
 del self._sandboxes[sandbox_id]
 del self._last_used[sandbox_id]

生命周期关键时机

时机	操作	说明
第一次调用 tool	`acquire`	创建容器（或从 Warm Pool 取）
后续调用 tool	`get`	返回已有容器
Session 结束	`release`	放回 Warm Pool，不删除
idle_timeout 超时	`destroy`	真正删除容器

核心设计思想：

惰性创建：不预先创建，第一次用才创建，节省资源
Warm Pool：release 不删，保留复用，减少下次的冷启动时间
确定性 ID：sha256(thread_id)[:8]，即使跨进程也能找到同一容器

DeerFlow Agent 架构详解：从 Lead Agent 到完整执行链

Tue, 14 Apr 2026 00:00:00 +0000

背景

DeerFlow 的 Agent 不是简单的 LLM 调用封装，而是一个精心设计的执行引擎。本文将深入剖析 Lead Agent 的架构，帮助你理解：

Agent 如何组装（Model + Tools + Prompt + Middleware）
状态如何流转（ThreadState 的设计）
请求如何被处理（Middleware Chain 的执行顺序）
Prompt 如何动态生成（Skills、Memory、Subagent 的注入）

核心文件位于：backend/packages/harness/deerflow/agents/lead_agent/

Agent 组成结构

三大核心组件

make_lead_agent() 函数负责组装 Agent：

1
2
3
4
5
6
7
8
9


def make_lead_agent(
 model: BaseChatModel,
 tools: list[BaseTool],
 *,
 agent_name: str | None = None,
 available_skills: set[str] | None = None,
 subagent_enabled: bool = False,
 max_concurrent_subagents: int = 3,
) -> CompiledStateGraph:

Agent 由三部分组成：

1
2
3
4
5
6
7
8
9


┌─────────────────────────────────────┐
│ Lead Agent │
│ ┌─────────────┬─────────────┬─────┐│
│ │ Model │ Tools │Prompt││
│ │ (LLM实例) │(工具集合) │(动态) ││
│ └─────────────┴─────────────┴─────┘│
│ │
│ + Middleware Chain (14个中间件) │
└─────────────────────────────────────┘

Model: LangChain 的 BaseChatModel 实例（如 ChatOpenAI）

Tools: 工具集合，包括：

Built-in tools（present_files, ask_clarification）
Sandbox tools（bash, read_file, write_file）
Config tools（web_search）
MCP tools（从 extensions_config.json 加载）

Prompt: 动态生成的 system prompt，包含 Skills、Memory、Subagent 指引

CompiledStateGraph：为什么是单节点图？

Agent 本质是 LangGraph 的 CompiledStateGraph：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# create_agent 来自 langchain.agents
from langchain.agents import create_agent

return create_agent(
 model=model,
 tools=tools,
 middleware=middlewares,
 system_prompt=prompt,
 state_schema=ThreadState,
)

你可能疑惑：为什么只有一个节点？

LangGraph 理论上支持复杂的多节点图（planning → execution → reflection），但 DeerFlow 只用了一个 “agent” 节点。原因如下：

1. ReAct 循环由 LangGraph 内部处理

create_agent 是 LangChain 提供的 ReAct agent 构建函数。它内部已经实现了：

1

思考 → 工具调用 → 观察 → 再思考（自动循环）

你不需要手动构建这种循环图。LangGraph 会自动：

调用 Model 获取 response
如果有 tool_calls，执行工具
将工具结果追加到 messages
再次调用 Model
直到 response 没有 tool_calls

所以"单节点"不意味着简单，复杂逻辑在内部循环中。

2. Middleware 模式比多节点图更灵活

方案	优点	缺点
多节点图	流程可视化	每次修改要改图结构，状态分散，调试困难
Middleware Chain	动态组合、职责单一、易扩展	需要 Middleware 框架支持

DeerFlow 选择 Middleware Chain：

14 个 Middleware 按需启用/禁用（通过 features 配置）
职责单一：每个 Middleware 只做一件事
新增功能只需添加新 Middleware，不改图结构
执行顺序清晰：注册顺序即执行顺序

3. 状态管理简化

单节点 + ThreadState：

只有一个状态容器（ThreadState）
所有 Middleware 读写同一个状态
进出一趟，状态清晰

多节点图意味着：

状态在节点间流转
需要中间状态字段（如 planning_result、reflection_notes）
调试时很难追踪状态变化

4. Checkpointer 开箱即用

LangGraph 的 checkpointer 提供状态持久化：

单节点图也能享受这个功能
ThreadState 在每次执行前后自动保存
支持恢复、回滚、时间旅行调试

5. 为扩展留空间

单节点不排斥未来扩展：

可以随时添加 planning、reflection 节点
Subagent 其实就是一种"多 agent"的变体
DeerFlow 用 Middleware 模式，比硬编码节点更灵活

总结：DeerFlow 选择"单节点 + Middleware Chain"而非"多节点图"，是因为：

ReAct 循环已内置，无需手动构建
Middleware 比节点更灵活、更易扩展
单一状态容器简化状态管理
Checkpointer 自动工作

ThreadState：状态容器

ThreadState（thread_state.py）是 Agent 的状态容器，继承 BaseMessageThreadState：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


class ThreadState(BaseMessageThreadState):
 # === Sandbox 执行环境 ===
 sandbox: SandboxInfo | None = None
 sandbox_tools: list[Tool] = field(default_factory=list)
 
 # === 文件系统 ===
 uploaded_files: list[UploadedFileInfo] = field(default_factory=list)
 artifacts: list[str] = field(default_factory=list) # 输出文件列表
 
 # === 任务管理（Plan Mode）===
 todos: list[TodoItem] = field(default_factory=list)
 
 # === Subagent 控制 ===
 subagent_limit: SubagentLimitInfo | None = None
 active_subagent_count: int = 0
 
 # === Memory 系统 ===
 memory_save_request: MemorySaveRequest | None = None
 
 # === 其他 ===
 is_streaming: bool = False
 ...

关键字段说明

字段	用途
`messages`	对话历史（继承自 BaseMessageThreadState）
`sandbox`	当前 sandbox 的信息（路径、类型等）
`uploaded_files`	用户上传的文件列表
`artifacts`	Agent 生成的输出文件（用于 present_files）
`todos`	任务清单（Plan Mode 使用）
`subagent_limit`	Subagent 并发限制信息
`memory_save_request`	Memory 系统的保存请求

状态流转

每次请求时，ThreadState 从 LangGraph checkpointer 加载，执行过程中被中间件修改，最后保存回 checkpointer。

Middleware Chain：执行链

DeerFlow 的核心魔力在于 Middleware Chain。14 个中间件按顺序执行，每个负责特定功能。

注册顺序 vs 执行顺序

注册顺序（middlewares.py）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


def get_middlewares() -> list[Middleware]:
 return [
 SandboxMiddleware(), # 0
 UploadedFilesMiddleware(), # 1
 SandboxToolsMiddleware(), # 2
 DanglingToolCallMiddleware(), # 3
 GuardrailMiddleware(), # 4
 ToolErrorHandlingMiddleware(), # 5
 SummarizationMiddleware(), # 6
 TodoMiddleware(), # 7
 TitleMiddleware(), # 8
 MemoryMiddleware(), # 9
 ViewImageMiddleware(), # 10
 SubagentLimitMiddleware(), # 11
 LoopDetectionMiddleware(), # 12
 ClarificationMiddleware(), # 13 (最后)
 ]

钩子方法

每个 Middleware 有 6 个钩子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


class Middleware:
 async def before_agent(self, state: ThreadState, agent: CompiledStateGraph) -> ThreadState:
 """Agent 执行前"""
 return state
 
 async def after_agent(self, state: ThreadState, agent: CompiledStateGraph, result: AgentResult) -> tuple[ThreadState, AgentResult]:
 """Agent 执行后"""
 return state, result
 
 async def before_model(self, state: ThreadState, agent: CompiledStateGraph) -> ThreadState:
 """Model 调用前"""
 return state
 
 async def after_model(self, state: ThreadState, agent: CompiledStateGraph, response: BaseModel) -> tuple[ThreadState, BaseModel]:
 """Model 调用后"""
 return state, response
 
 async def wrap_model_call(self, state: ThreadState, agent: CompiledStateGraph, call_next: Callable) -> BaseModel:
 """包装 Model 调用"""
 return await call_next(state)
 
 async def wrap_tool_call(self, state: ThreadState, agent: CompiledStateGraph, tool: Tool, args: dict, call_next: Callable) -> Any:
 """包装 Tool 调用"""
 return await call_next(state, tool, args)

执行流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


用户请求 → LangGraph Server
 │
 ├─► before_agent (所有中间件，顺序 0→13)
 │
 ├─► wrap_model_call (嵌套执行)
 │ │
 │ ├─► before_model (顺序)
 │ │
 │ ├─► LLM 调用
 │ │
 │ ├─► after_model (逆序)
 │ │
 │ └─► Tool 调用（如有）
 │ │
 │ ├─► wrap_tool_call (嵌套)
 │ │ ├─► before_tool_call (不存在，直接 wrap)
 │ │ ├─► Tool 执行
 │ │ ├─► after_tool_call (不存在)
 │ │
 │ └─► 循环直到无 Tool 调用
 │
 ├─► after_agent (所有中间件，逆序 13→0)
 │
 └─► 返回响应

关键中间件详解

SandboxMiddleware (0)

职责：为 Thread 分配 sandbox

1
2
3
4
5
6
7
8
9


async def before_agent(self, state, agent):
 if state.sandbox is None:
 sandbox = await sandbox_provider.acquire(thread_id)
 state.sandbox = SandboxInfo(
 sandbox_id=sandbox.sandbox_id,
 root_path=sandbox.root_path,
 ...
 )
 return state

ToolErrorHandlingMiddleware (5)

职责：捕获 Tool 执行异常，生成友好错误消息

1
2
3
4
5


async def wrap_tool_call(self, state, agent, tool, args, call_next):
 try:
 return await call_next(state, tool, args)
 except Exception as e:
 return f"Tool execution failed: {str(e)}. Please try a different approach."

MemoryMiddleware (9)

职责：异步保存对话到 Memory 系统

1
2
3
4
5
6
7


async def after_agent(self, state, agent, result):
 if should_save_memory(state):
 state.memory_save_request = MemorySaveRequest(
 messages=state.messages,
 debounce_seconds=30
 )
 return state, result

ClarificationMiddleware (13)

职责：处理 ask_clarification 工具调用

1
2
3
4
5


async def wrap_tool_call(self, state, agent, tool, args, call_next):
 if tool.name == "ask_clarification":
 # 不执行工具，直接抛出 ClarificationRequested 异常
 raise ClarificationRequested(question=args["question"])
 return await call_next(state, tool, args)

这个中间件放在最后，确保 clarification 请求能中断执行流程。

Prompt 组装机制

prompt.py 的 apply_prompt_template() 生成最终 system prompt。

模板结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


SYSTEM_PROMPT_TEMPLATE = """
<role>
You are {agent_name}, an open-source super agent.
</role>

{soul}
{memory_context}

<thinking_style>
- Think concisely and strategically...
{subagent_thinking}
</thinking_style>

<clarification_system>
5 种 clarification types + workflow
</clarification_system>

{skills_section}
{deferred_tools_section}
{subagent_section}

<working_directory>
路径映射规则
</working_directory>

<response_style>
回复风格指引
</response_style>

<citations>
引用规范
</citations>

<critical_reminders>
关键提醒
</critical_reminders>
"""

动态注入组件

SOUL.md

Agent 的"个性"定义：

1
2
3
4
5


def get_agent_soul(agent_name: str | None) -> str:
 soul = load_agent_soul(agent_name) # 从 agents_config.yaml 加载
 if soul:
 return f"<soul>\n{soul}\n</soul>\n"
 return ""

Memory Context

跨会话记忆注入：

1
2
3
4


def _get_memory_context(agent_name: str | None) -> str:
 memory_data = get_memory_data(agent_name)
 memory_content = format_memory_for_injection(memory_data)
 return f"<memory>\n{memory_content}\n</memory>\n"

Skills Section

Skills 动态加载 + 缓存：

1
2
3
4


def get_skills_prompt_section(available_skills: set[str] | None) -> str:
 skills = _get_enabled_skills() # 从 extensions_config.json 读取
 # 使用 lru_cache 缓存
 return _get_cached_skills_prompt_section(skill_signature, ...)

Skills 缓存机制：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 线程异步加载
_enabled_skills_cache: list[Skill] | None = None
_enabled_skills_lock = threading.Lock()

def _refresh_enabled_skills_cache_worker():
 while True:
 skills = _load_enabled_skills_sync()
 with _enabled_skills_lock:
 _enabled_skills_cache = skills

# LRU 缓存 prompt 片段
@lru_cache(maxsize=32)
def _get_cached_skills_prompt_section(...):
 ...

Subagent Section

动态生成 subagent 指引，包含并发限制：

1
2
3
4
5
6
7


def _build_subagent_section(max_concurrent: int) -> str:
 n = max_concurrent
 return f"""
**HARD CONCURRENCY LIMIT: MAXIMUM {n} `task` CALLS PER RESPONSE**
- If count ≤ {n}: Launch all in this response
- If count > {n}: Pick the {n} most important sub-tasks
"""

Clarification Types

5 种 clarification 类型：

类型	用途	示例
`missing_info`	缺失关键信息	“Deploy the app” → 缺少环境信息
`ambiguous_requirement`	多种理解方式	“Optimize the code” → 性能 vs 可读性
`approach_choice`	多种方案可选	“Add auth” → JWT vs OAuth
`risk_confirmation`	危险操作确认	删除文件、修改生产配置
`suggestion`	建议征询	“I recommend refactoring…”

完整请求生命周期

用一个例子说明完整流程：

用户请求：“分析这个 PDF 并生成报告”

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


1. LangGraph Server 收到请求
 └─► 从 checkpointer 加载 ThreadState
 
2. before_agent (所有中间件)
 ├─► SandboxMiddleware: 分配 sandbox
 ├─► UploadedFilesMiddleware: 解析上传的 PDF
 ├─► SandboxToolsMiddleware: 注册 sandbox 工具
 └─► ... 其他 before_agent
 
3. wrap_model_call 嵌套执行
 ├─► before_model (顺序)
 │ └─► SummarizationMiddleware: 检查是否需要压缩历史
 │
 ├─► Model 调用 (LLM)
 │ └─► System Prompt 包含: Skills、Memory、uploaded_files
 │ └─► LLM 返回: tool_calls = [read_file("xxx.pdf")]
 │
 ├─► after_model (逆序)
 │ └─► DanglingToolCallMiddleware: 检查 dangling calls
 │
 └─► Tool 执行循环
 ├─► wrap_tool_call
 │ ├─► ToolErrorHandlingMiddleware: 捕获异常
 │ ├─► read_file 执行
 │ └─► 返回 PDF 内容
 │
 ├─► 再次 Model 调用
 │ └─► LLM 返回: write_file("report.md", "...")
 │
 ├─► wrap_tool_call
 │ └─► write_file 执行
 │ └─► state.artifacts.append("report.md")
 │
 ├─► 再次 Model 调用
 │ └─► LLM 返回: present_files(["report.md"])
 │
 ├─► wrap_tool_call
 │ └─► present_files 执行
 │ └─► 返回文件列表给前端
 │
 └─► 无更多 tool_calls，结束循环
 
4. after_agent (所有中间件，逆序)
 ├─► ClarificationMiddleware: 检查是否有 clarification 请求
 ├─► MemoryMiddleware: 请求保存记忆
 ├─► TitleMiddleware: 生成对话标题
 ├─► TodoMiddleware: 更新任务状态
 └─► SandboxMiddleware: 清理 sandbox（如需要）
 
5. 返回响应
 ├─► SSE 流式返回给前端
 └─► ThreadState 保存到 checkpointer

关键设计洞察

1. Middleware Chain 的灵活性

中间件模式让功能模块化，易于扩展。新增功能只需添加新中间件，无需修改核心代码。

2. 状态驱动的执行

ThreadState 作为单一状态容器，所有中间件读写同一个状态，避免状态分散。

3. 动态 Prompt 组装

Prompt 不是静态字符串，而是根据配置动态生成：

Skills 从 extensions_config.json 加载
Memory 从 memory.json 加载
Subagent section 根据并发限制动态生成

4. Skills 缓存优化

Skills 加载使用线程异步 + LRU 缓存：

避免每次请求都读取文件
mtime 检测文件变更自动刷新缓存

5. Clarification 中断机制

ClarificationMiddleware 通过抛出异常中断执行，确保 clarification 请求能立即停止 Agent，等待用户输入。

扩展建议

如果你想深入理解 Agent 架构，建议：

跟踪一次完整请求：在 agent.py 的 agent_node() 加日志，观察每一步
修改中间件顺序：尝试调整 middleware 注册顺序，观察行为变化
自定义中间件：创建一个简单的中间件，理解钩子机制
动态 Prompt 实验：修改 prompt.py 的模板，观察 Agent 行为变化

总结

DeerFlow 的 Lead Agent 是一个精心设计的执行引擎：

组装：Model + Tools + Prompt + Middleware
状态：ThreadState 作为单一状态容器
执行：Middleware Chain 按 hooks 钩子执行
Prompt：动态组装，注入 Skills、Memory、Subagent 指引

理解这个架构，是深入学习 DeerFlow 其他模块（Sandbox、Memory、MCP）的基础。