AI Research 技术调研

DeerFlow (ByteDance)：从 LangGraph 研究图重写为 Claude-Code 式 lead-agent + subagent 的开源 super agent harness

19分钟阅读

DeerFlow (ByteDance)

一句话定位

DeerFlow 当前 main 分支已从早期”基于 LangGraph 的 coordinator/planner/researcher/reporter 固定四节点 deep-research 图”彻底重写，自称 “DeerFlow 2.0 — open-source super agent”：核心是一个 Claude-Code 风格的单 lead-agent + 动态 subagents harness，构建在 LangChain 新版 langchain.agents.create_agent middleware 框架之上（不再手写 StateGraph 节点），并把记忆学习、skill 自进化、guardrail、可插拔沙箱、多 provider 模型适配、tracing、IM channels、scheduled tasks 包进一个 FastAPI Gateway 产品。审计提示里的”四节点研究工作流”口径已过时，本 dossier 以重写后的代码为准。

数据点：76,729 stars / 10,416 forks（as-of 2026-07-11，直接抓 GitHub 仓库页 repo-stars-counter-star / repo-network-counter 计数元素）；License MIT。

核心架构总览（目录结构关键路径 + 引用的 commit）

分析对象：bytedance/deer-flow @ be637163a618a01062517ee9dcef0e8cb3fb2572（2026-07-10 23:13:06 +0800 feat(frontend): add voice dictation input (#4036)），--depth 1 克隆 main 分支，克隆日期 2026-07-11。

这是一个 monorepo：

  • harness 主体：backend/packages/harness/deerflow/（Python package 名 deerflow）——本 dossier 绝大多数路径都相对于此目录。
  • 网关：backend/app/gateway——FastAPI，内嵌 agent runtime，对外暴露 LangGraph-compatible 的 runs/threads API。Nginx 把 /api/langgraph/* rewrite 到 Gateway 原生 /api/*；langgraph.json 仅留作 LangGraph Studio/SDK 兼容入口，不是默认运行路径（见 backend/docs/ARCHITECTURE.md，留档 src-snapshot/backend-docs-ARCHITECTURE.md）。
  • 前端：frontend/（Next.js，本次未审）。
  • 产品面：app/channels（IM）、app/scheduler（定时任务）、app/gateway/routers——与 harness 核心弱相关。

harness 内部关键子目录：agents/（lead_agent、memory、middlewares、thread_state）、tools/（含 builtins/）、subagents/、skills/、guardrails/、sandbox/、models/、runtime/（journal、runs、checkpointer、secret_context）、tracing/、reflection/（config 里 use: 字符串的动态 import 解析）、config/、persistence/、scheduler/。

Agent Loop（主循环 / 何时继续何时停）

DeerFlow 不自写 while 循环。主循环由 langchain.agents.create_agent(model, tools, middleware, system_prompt, state_schema=ThreadState) 构图后的 LangChain agent runtime（模型 → 工具 → 模型）驱动。工厂在 agents/lead_agent/agent.py:_make_lead_agent（约 L396-599），对外入口 make_lead_agent（约 L389）保持 LangGraph Server 兼容签名。agent.py L25 from langchain.agents import create_agent、L26 AgentMiddleware（已核实源码）。

“何时继续、何时停”的语义完全由一整条有序 middleware 链承载，注册顺序即执行语义。工厂 build_middlewares（agent.py L217-364，已核实）按下述顺序装配，链尾附有大段排序不变量注释（L207-216）。关键控制项（均已在源码中核实类名/位置）：

  • DynamicContextMiddleware（L259）——每轮把日期/记忆/上传文件等易变项注入首条 HumanMessage 的 <system-reminder>（见 Prompt 章）。
  • SkillActivationMiddleware（L266）——/skill-name 显式激活。
  • DurableContextMiddleware（L274）——委派台账 / skill 文件注入（见 Memory 章）。
  • TitleMiddleware（L297）→ MemoryMiddleware（L300，MemoryMiddleware 是把对话推入记忆更新队列的入口）→ 条件 ViewImageMiddleware（L306，仅 vision 模型）。
  • DeferredToolFilterMiddleware（L319）——工具多时隐藏 schema（见 Tools 章）。
  • SystemMessageCoalescingMiddleware（L329）——合并 leading system 消息，兼容严格后端。
  • SubagentLimitMiddleware（L335，max_concurrent=max_concurrent_subagents）——截断超并发上限的并行 task 调用。
  • LoopDetectionMiddleware（L340）——检测并打断重复工具调用循环。
  • TokenBudgetMiddleware（L347）——每 run token 上限。
  • SafetyFinishReasonMiddleware（L360，条件 safety_config.enabled）——provider 安全终止时抑制后续工具执行；注释（L353-357）明确它注册在 custom middleware 之后，以便利用 LangChain 逆序 after_model 分派让 Safety 先跑。
  • ClarificationMiddleware（L363，注释明写 “should always be last”，已核实）——拦截 ask_clarification，需要澄清时中断执行等用户，是主要的”停机等人”路径。

状态 schema：agents/thread_state.py:ThreadState（含 SandboxState / ThreadDataState 等通道）。Run 生命周期、后台 worker、并发/取消/lease 在 runtime/runs/worker.py（1383 行）+ runtime/runs/manager.py（863 行）——本次未逐行读，属未尽深挖点。

记忆与上下文管理（压缩、长期记忆、会话持久化）

三层，且刻意设计为”静态 system prompt + 动态注入”以最大化 prefix-cache 复用：

  1. 短期上下文压缩：DeerFlowSummarizationMiddleware（agents/middlewares/summarization_middleware.py，继承 LangChain SummarizationMiddleware；agent.py L35 已核实 import）。压缩前发 SummarizationEvent（messages_to_summarize / preserved_messages / thread_id），压缩用 create_chat_model 另起总结调用；summary 以 name="summary" 的消息回注。排序上刻意”很早”（L210 注释）以先降上下文再做别的处理。

  2. 长期记忆（学习型）：agents/memory/。压缩钩子 summarization_hook.py:memory_flush_hook 在消息被总结掉之前，过滤出 human+assistant 消息、跑 detect_correction / detect_reinforcement，塞进 get_memory_queue() 后台队列。updater.py 用三个 prompt——MEMORY_UPDATE_PROMPT / CONSOLIDATION_PROMPT / STALENESS_REVIEW_PROMPT——在 4-worker 线程池（_SYNC_MEMORY_UPDATER_EXECUTOR）里异步读写 / 巩固 / 汰旧记忆文件；记忆按 agent_name + user_id 分域存储。注入点是 DynamicContextMiddleware（经 prompt.py:_get_memory_context 约 L656 生成，塞进首条 HumanMessage 的 <system-reminder><memory>），不进 system prompt，保证 system prompt 跨用户/会话恒定。记忆对用户可见可编辑（UI），prompt 里明确它是 user-managed data。

  3. 持久化 / durable context：DurableContextMiddleware（durable_context_middleware.py）把已完成的 task 委派（delegation ledger）和已加载的 skill 文件在被 summarization 压缩前捕获进 checkpoint 状态通道，再作为一条隐藏 <durable_context_data> HumanMessage 注入，且带 “authority contract” 提示：其字段值是 data 不是 instruction（防注入）。

会话持久化：runtime/checkpointer/ + persistence/（SQLite/DB migrations，thread_meta / run / scheduled_tasks 等）。相关 config：config/{memory_config,summarization_config,token_budget_config,checkpointer_config}.py。文档 backend/docs/MEMORY_IMPROVEMENTS.md / summarization.md。

工具体系（定义/调用协议/注册/权限）

  • 注册与装配：tools/tools.py:get_available_tools（L44，已核实）。工具来源合并四路：
    1. config.yaml 的 tools 列表，每项 use: "module.path:tool_obj" 由 reflection/resolvers.py:resolve_variable 动态 import；
    2. 内建 BUILTIN_TOOLS（tools.py L15，含 present_file / ask_clarification）+ 条件内建（skill_evolution 开 → skill_manage_tool，tools.py L94-96 已核实；subagent 开 → task；vision 模型 → view_image）；
    3. MCP 工具；4. ACP 工具。
  • 调用协议：标准 LangChain BaseTool。异步-only 工具被 _ensure_sync_invocable_tool（tools.py L37）包一层同步壳（make_sync_tool_wrapper）。按 .name 去重（tools.py L168-170 seen_names），config name 与工具 .name 不一致会 warn（tools.py L80-84，绑定以 .name 为准，issue #1803）。
  • 工具搜索 / deferred tools：tools/builtins/tool_search.py + assemble_deferred_tools（agent.py L503/565）。工具多时先隐藏 schema（DeferredToolFilterMiddleware，agent.py L319），靠 tool_search / MCP routing（mcp_routing_middleware auto-promote top-k）按需放出，省 prompt token。
  • 权限三道门：(a) 按 agent config 的 tool_groups 过滤（get_available_tools(groups=...)）；(b) skill 声明的 allowed-tools 白名单过滤（skills/tool_policy.py:filter_tools_by_skill_allowed_tools，任一 skill 声明 allowed-tools 即转白名单模式，read_file 恒允许）；(c) 运行时 Guardrail（见安全章）。此外 host-bash 工具在不允许时被直接剔除（tools.py L70-71 if not is_host_bash_allowed(config): 过滤 _is_host_bash_tool，已核实）。
  • 内建工具目录 tools/builtins/：task / tool_search / clarification / present_file / view_image / setup_agent / update_agent / invoke_acp_agent。

Prompt 设计（系统提示结构、动态组装）

  • 单一大模板 prompt.py:SYSTEM_PROMPT_TEMPLATE（约 L435-653），apply_prompt_template（约 L899）组装。结构化 XML 标签块：<role>、<soul>（agent 人格 SOUL.md）、<thinking_style>、<clarification_system>、<skill_system>、<subagent_system>（仅 subagent 开时）、<working_directory>、<response_style>、<citations>、<critical_reminders>。
  • Prompt-injection 防御是一等设计：用户输入包在 --- BEGIN/END USER INPUT --- 里当”不可信数据”；有 “System-Context Confidentiality” 段，禁止泄露/复述任何框架注入内容。
  • 缓存友好：system prompt 刻意做成完全静态（跨用户一致）；日期/记忆/上传文件等每轮变化项由 DynamicContextMiddleware（agent.py L259）注入首条 HumanMessage 的 <system-reminder>，不进 system prompt。SystemMessageCoalescingMiddleware（agent.py L329，已核实）把多条 SystemMessage 合并成单条 leading，兼容 vLLM/SGLang/Qwen/Anthropic 等严格后端。
  • 动态子块：subagent 段带 max_concurrent 数值与可用 subagent 列表（从 registry 动态生成，对齐 Codex 的 agent_type_description 模式）；skill 段是 metadata-only 的 <available_skills> 或 deferred 模式的 <skill_index>（配 describe_skill）；<citations> 段强制 web 结果用 [citation:Title](URL)。
  • Todo/plan 模式的 prompt 与工具描述内嵌在 agent.py:_create_todo_list_middleware（L92-204，返回 TodoMiddleware）。

Router / 编排（任务分解、多 agent、子 agent）

  • 无独立 router 模型：编排由 lead agent 自己在 <subagent_system>（prompt.py 约 L307-432）指令下完成——DECOMPOSE → DELEGATE（并行 task 调用）→ SYNTHESIZE，硬性”每轮 ≤N 个 task 调用”（N=max_concurrent_subagents，默认 3），超额被 SubagentLimitMiddleware（agent.py L335）静默丢弃，>N 走多批次。
  • 委派工具：tools/builtins/task_tool.py:task（LangChain @tool，参数 description / prompt / subagent_type），返回 Command。后台异步跑 + 自动轮询（_await_subagent_terminal 每 5s 轮询直到 terminal），对 LLM 表现为阻塞直到子代理完成。
  • 执行引擎：subagents/executor.py:SubagentExecutor（1058 行）——为每个 subagent 用 create_agent 独立建图、独立 ThreadState、独立 tracing trace_id（父子日志关联）、ThreadPoolExecutor 后台执行；SubagentResult 带 try_set_terminal 保证 terminal 状态只写一次（超时/取消/完成竞态安全），支持 cancel / timeout / token / turn / loop cap（stop_reason）。
  • subagent 类型：subagents/registry.py + subagents/builtins/{general_purpose,bash_agent}.py，也支持 config 自定义 subagent（get_subagent_config）。bash subagent 在 LocalSandboxProvider 下默认禁用（安全）。
  • ACP 外部 agent 编排：invoke_acp_agent 工具可调 codex / claude_code 等外部 agent，它们跑在独立 /mnt/acp-workspace（prompt.py _build_acp_section 约 L848）。

Skill / 插件体系

  • 完整 skill 系统 skills/：catalog / installer / parser / validation / describe / slash（/skill-name 显式激活）/ storage / permissions / tool_policy / security_scanner + security_static_scanner。Skill = SKILL.md（Anthropic Agent Skills 风格）+ 同目录资源，progressive（渐进）loading。
  • 注入：prompt.py:get_skills_prompt_section（约 L755）。两种模式——legacy 全 metadata <available_skills>（含 disabled_skills 显式禁用清单）；deferred discovery <skill_index> 仅列名 + describe_skill 工具。skill 有 category：built-in / custom(editable) / legacy(read-only)。
  • 激活中间件：SkillActivationMiddleware（agent.py L266）——用户 /skill-name 开头则确定性加载对应 SKILL.md，优先于模型侧相关性猜测。
  • 权限：skill 树装成 sandbox 只读（skills/permissions.py:make_skill_tree_sandbox_readable，去掉 group/other 写位）；skill 可声明 allowed-tools 收窄工具集（见工具章）。
  • 分域与缓存：用户级 vs 全局 skill 分域（get_or_new_user_skill_storage(user_id)），带 LRU 缓存（256 上限）与后台刷新线程（prompt.py 约 L45-224）。
  • MCP：mcp/ 目录，MCP server 工具经 get_cached_mcp_tools 装入并 tag_mcp_tool；配置在 extensions_config.json（Gateway API 可热改，从磁盘重读）。

自进化能力（自我改进 / 学习型记忆 / eval 驱动纠错）

  • Skill 自进化（显式功能，默认关）：config/skill_evolution_config.py:SkillEvolutionConfig（enabled 默认 False + 可选 moderation_model_name）。开启后 prompt 注入 _build_skill_evolution_section（prompt.py 约 L227-252）：任务用了 5+ 工具调用 / 踩了非显然的坑 / 被用户纠正后新解法有效 / 发现可复用工作流 → 用 skill_manage 工具 create/patch/edit/write_file/delete 持久化 skill（存进 per-user skills 目录）。工具本体 tools/skill_manage_tool.py（tools.py L94-96 条件装入，已核实）。
  • 写 skill 的安全审查：skills/security_scanner.py（LLM moderation，返回 ScanResult decision/reason）+ security_static_scanner.py（静态扫描），防自写 skill 引入危险内容。
  • 学习型长期记忆：见记忆章——correction/reinforcement 检测 + 后台记忆巩固/汰旧，等价于从对话轨迹里学偏好/纠错。
  • 自我配置更新：自定义 agent 可用 update_agent 工具改自己的 SOUL.md / config.yaml / tool_groups / model（prompt.py:_build_self_update_section 约 L827）。安全闸门：webhook channel（如 github，来源不可信外部评论者）不给 update_agent（agent.py L546-559）。
  • 无 RL/训练闭环：不反哺权重。“eval 驱动纠错”在此表现为运行期 loop/safety/guardrail 中间件的即时纠偏，而非离线 eval 回灌。

可观测性（日志 / trace 格式）

  • RunJournal（runtime/journal.py）：LangChain BaseCallbackHandler，把回调标准化成 RunEvent 写入可插拔 RunEventStore。设计要点（文件头 docstring）：只在 on_llm_end 记完整消息（不记 token 流）；on_chat_model_start 以 OpenAI 格式记 llm_request 并抽首条 human 作 run.input；on_chain_start(parent_run_id=None) 发 run.start；llm_response 用 OpenAI Chat Completions 格式；token 用量内存累加、run 结束写 RunRow；调用方标识经 tags 注入（lead_agent / subagent:{name} / middleware:{name}）。带 buffer + flush_threshold + 进度上报。
  • 分布式 tracing：tracing/factory.py:build_tracing_callbacks 支持 Langfuse 与 LangSmith（按 config 启用）。callback 只在 graph 调用根挂一次（agent.py L467-478 有大段 INVARIANT 注释），所有 create_chat_model 必须 attach_tracing=False，否则重复 span 且 session_id/user_id 丢失。subagent 经 inject_langfuse_metadata + trace_id 关联父子。
  • 中间件级审计：guardrail 决策写 RunJournal record_middleware(tag="guardrail", hook="wrap_tool_call", ...)（guardrails_middleware.py L110 已核实 journal.record_middleware）；另有 sandbox_audit_middleware.py、token_usage_middleware.py。

安全与权限（审批门、密钥管理）

  • Guardrail 层：guardrails/middleware.py:GuardrailMiddleware（class GuardrailMiddleware(AgentMiddleware[AgentState])，L22 已核实）。wrap_tool_call（约 L120）在每次工具调用前用 GuardrailProvider.evaluate(GuardrailRequest) 评估（含 tool_name/args/user_id/user_role/oauth/thread_id/is_subagent）。拒绝 → 返回 error ToolMessage（_build_denied_message L58-63，返回 ToolMessage，“Choose an alternative”）让 agent 自适应，不 raw 抛。fail_closed 默认 True（__init__ L31 fail_closed: bool = True，provider 异常 → 拦，均已核实）。决策落 RunJournal 审计。内建 provider guardrails/builtin.py:AllowlistProvider（allow/deny 名单）；provider 可插拔（OAP 语义，code 前缀 oap.*）。文档 backend/docs/GUARDRAILS.md。具体外部 provider 实现（guardrails/provider.py）本次只看接口未读实现。
  • 澄清即审批门：ClarificationMiddleware + prompt <clarification_system> 强制风险操作（删文件 / 改生产配置 / 覆写）先 ask_clarification(clarification_type="risk_confirmation") 拿显式确认再动手。non_interactive 模式禁用 ask_clarification（agent.py L52/501/563）。
  • 输入消毒：input_sanitization_middleware.py + prompt 的 user-input 边界标记 + 机密保护段。
  • 密钥管理：runtime/secret_context.py；模型凭据 models/credential_loader.py；Claude provider 支持从 env / ~/.claude/.credentials.json / OAuth token（sk-ant-oat）加载（models/claude_provider.py 头）。tracing 密钥在 tracing_config。
  • 越权面收窄：webhook channel 去掉 update_agent（见自进化章）；host bash 默认禁（见沙箱章）。

沙箱与执行隔离

  • SandboxMiddleware（sandbox/middleware.py，218 行）：按 thread_id 惰性（默认 lazy_init）获取 sandbox，跨轮复用，app 关闭时统一 shutdown()。工具调用后把惰性拿到的 sandbox_id 经 Command(update=...) 持久化进 graph state（否则下游看不到）。
  • Provider 可插拔：sandbox/sandbox_provider.py + sandbox/local/LocalSandboxProvider（宿主本地，非真隔离边界）+ community e2b_sandbox / aio_sandbox / boxlite（真隔离）。
  • 安全默认：sandbox/security.py——用 LocalSandboxProvider 时默认禁 host bash（is_host_bash_allowed 返回 False，除非 sandbox.allow_host_bash: true），bash subagent 同样禁；提示切 AioSandboxProvider 拿隔离 shell。get_available_tools 据此剔除 host-bash 工具（tools.py L70-71 已核实）。
  • 工作目录约定（prompt <working_directory>）：/mnt/user-data/{uploads,workspace,outputs}；可配 custom mounts（read-only/rw）；ACP agent 跑在独立 /mnt/acp-workspace。
  • 另有 sandbox/env_policy.py（环境变量策略）、file_operation_lock.py、read_before_write_middleware.py（改文件前必先读）。

与模型的协同设计

  • 多 provider 适配层 models/：factory.py:create_chat_model 统一入口 + 一批定制 provider：claude_provider（OAuth Bearer / API key 双模式、prompt caching、smart thinking，THINKING_BUDGET_RATIO=0.8、billing header）、vllm_provider、mindie_provider（华为昇腾）、openai_codex_provider，以及 patched 版 deepseek / mimo / minimax / stepfun / openai（修各家 OpenAI-兼容层怪癖，如 MiniMax 拒绝 user-message name 不一致）。
  • 能力位驱动行为：model config 带 supports_vision / supports_thinking；agent.py 据此决定是否加 ViewImageMiddleware / view_image 工具（L302-306，已核实条件装入）、thinking 不支持则降级（约 L435-437）、reasoning_effort 透传。
  • 缓存协同：静态 system prompt + SystemMessageCoalescingMiddleware（合并 leading system，兼容严格后端）+ <system-reminder> 动态注入，均为最大化 prefix cache 命中（见 prompt/记忆章）。
  • 小米交叉点：MiMo（小米自家模型）在列（patched_mimo.py），对本 wiki 的模型-harness 交叉分析有意义。

轨迹利用（session/trajectory 是否反哺训练/评测）

  • 不反哺训练：无 RL/SFT/数据导出闭环。轨迹的主要复用是 record/replay 契约测试：backend/docs/REPLAY_E2E.md + ReplayChatModel——录一次真实 run，回放到真实 FastAPI gateway 断言 SSE 事件序列等于 golden（Layer 1 后端 golden tests/test_replay_golden.py；Layer 2 全栈 Chromium 渲染），防前后端契约漂移。属”轨迹 → 回归测试”，不是”轨迹 → 训练”。
  • 运行期学习：对话轨迹经 memory 队列蒸出偏好/纠错记忆（记忆/自进化章），以及 skill 自进化——都是产品内自改进，不落训练集。
  • 持久化与产品形态：session 持久化在 persistence/ + checkpointer；run 事件在 RunEventStore（可观测章）；scheduled tasks（scheduler/ + persistence/scheduled_tasks/）可定时重跑 prompt（GitHub Trending / news digest 等 recipe），也属轨迹复用的产品形态。

与同类 harness 的关键差异（1-3 条）

  1. “重写”本身是最大差异：DeerFlow 从一个论文式固定研究图（coordinator/planner/researcher/reporter）掉头重写成通用 super agent。它没有自造 agent runtime，而是押注 LangChain 新版 create_agent + middleware 抽象，把所有决策逻辑（停机、压缩、记忆、guardrail、沙箱、限流）都编码成一条有序 middleware 链——排序即语义（ClarificationMiddleware 永远最后、SafetyFinishReason 借逆序 after_model 先跑）。这与 Claude Code / OpenHands 那种自写主循环、或 deepagents 直接用 LangGraph StateGraph 的写法都不同，是”把控制流外包给中间件顺序”的极端形态。
  2. 缓存/防注入被抬到架构级：刻意让 system prompt 完全静态、所有易变项走 <system-reminder> 动态注入、多 SystemMessage 合并成单条 leading——这套”为 prefix cache 命中而设计 prompt 布局”的做法在开源 harness 里少见其明确度；配合 --- BEGIN/END USER INPUT --- 边界 + durable-context 的 “authority contract”（data≠instruction），prompt-injection 防御是一等公民。
  3. 产品化纵深远超”研究 agent”：可插拔沙箱（local/e2b/aio/boxlite）、可插拔 guardrail provider（OAP oap.*）、多 provider 模型层（含昇腾 mindie、小米 mimo、OAuth Claude）、Langfuse/LangSmith 双 tracing、IM channels、scheduled tasks、skill 自进化 + 学习型记忆——是一个把 harness 当产品交付的完整栈，而非库。

原始源码定位

  • repo: https://github.com/bytedance/deer-flow
  • commit/version analyzed: be637163a618a01062517ee9dcef0e8cb3fb2572（main，2026-07-10 23:13:06 +0800 feat(frontend): add voice dictation input (#4036)），克隆日期 2026-07-11
  • 关键文件列表（相对 backend/packages/harness/deerflow/，除非注明）：
    • agents/lead_agent/agent.py（主 agent 工厂 + middleware 链，599 行）
    • agents/lead_agent/prompt.py（system prompt 模板 + 动态组装，973 行）
    • agents/thread_state.py（ThreadState 状态 schema）
    • agents/memory/{summarization_hook.py,updater.py}（学习型记忆）
    • agents/middlewares/{durable_context_middleware.py,summarization_middleware.py,dynamic_context_middleware.py,memory_middleware.py,system_message_coalescing_middleware.py,deferred_tool_filter_middleware.py,clarification_middleware.py,loop_detection_middleware.py,token_budget_middleware.py,safety_finish_reason_middleware.py,subagent_limit_middleware.py,view_image_middleware.py,skill_activation_middleware.py,title_middleware.py}
    • tools/tools.py（工具注册/装配/去重，176 行）+ tools/builtins/{task_tool.py,tool_search.py,...} + tools/skill_manage_tool.py
    • subagents/executor.py（subagent 执行引擎，1058 行）+ subagents/{registry.py,config.py,builtins/{general_purpose,bash_agent}.py}
    • skills/{tool_policy.py,permissions.py,security_scanner.py,catalog.py,installer.py,slash.py,describe.py}
    • guardrails/{middleware.py,builtin.py,provider.py}
    • sandbox/{middleware.py,security.py,sandbox_provider.py,env_policy.py} + sandbox/local/*
    • models/{factory.py,claude_provider.py,vllm_provider.py,mindie_provider.py,patched_mimo.py,credential_loader.py}
    • runtime/{journal.py,secret_context.py,runs/worker.py,runs/manager.py,checkpointer/}
    • tracing/factory.py
    • reflection/resolvers.py（use: 字符串动态 import 解析）
    • config/{skill_evolution_config.py,memory_config.py,summarization_config.py,token_budget_config.py}
    • docs（backend/docs/）：ARCHITECTURE.md、REPLAY_E2E.md、GUARDRAILS.md、MEMORY_IMPROVEMENTS.md、summarization.md

一手源存档（sources/）

/Users/zhao/projects/self-wiki/ai-research/sources/harness/deerflow/：

  • NOTES.md（第一阶段 12 维度源码级笔记，dossier 的主输入）
  • src-snapshot/（18 个核心源文件留档）：
    • agent.py、prompt.py、tools.py、executor.py、task_tool.py、builtin.py
    • durable_context_middleware.py、summarization_hook.py、summarization_middleware.py
    • guardrails_middleware.py、sandbox_middleware.py、security.py、permissions.py、tool_policy.py
    • journal.py、tracing_factory.py、skill_evolution_config.py、updater.py
    • backend-docs-ARCHITECTURE.md（后端架构文档留档）

注：本次 dossier 阶段额外核实的行号（agent.py 的 middleware 装配 L207-364、guardrails fail_closed=True L31 / record_middleware L110、tools.py host-bash 剔除 L70-71 与去重 L168-170）均直接读 src-snapshot/ 对应文件确认。未逐行读的部分（runtime/runs/worker.py、manager.py、guardrails/provider.py 外部实现、前端）已在正文标注为未尽深挖点。

关系图谱

反向链接