从这里开始

这本书只走一项任务

全书只用一个例子：deerflow --thread sales-review --mode ultra --file sales-notes.pdf "分析销售下滑并生成 sales-review.md"。用户上传访谈记录，要求 DeerFlow 补充调研，最后交付一份 Markdown 报告。

这不是 DeerFlow 已发布的 CLI，不能复制到终端运行。真实产品里，thread、mode、file 和目标来自网页表单，前端再调用 thread.submit。把它写成一行，只是为了让后面的每个变量都有固定名字。

固定例子有一个好处：当正文提到 Run、Middleware、Memory、Sandbox 或 Artifact 时，我们不必换一套场景重新解释。所有机制都要回答同一个问题——它对 sales-review.md 的生成过程做了什么。

三章分别负责什么

第 00 章就是你现在站的位置。它只交代任务、路线和阅读方法，不要求你先认识 LangGraph，也不提前解释二十个类名。

第 01 章回答“DeerFlow 是什么”。它从一次模型调用做不到的事情开始，逐步引出 Run、工具、状态、Sandbox 和 Artifact，最后给出一张系统图。读完这一章，你应该能说清 DeerFlow 的边界，而不是只记住它叫 Super Agent Harness。

第 02 章不再按模块讲。它从 thread.submit 出发，顺着 Gateway、worker、run_agent 和 agent.astream 一直走到 present_files。Middleware、Memory、Sub-agent 和持久化都在控制流需要它们时出现；属于旁支的细节会标成插叙，跳过也不影响主线。

代码只用来证明正文

正文会先说明当前执行到哪里，再放一小段真实源码，代码之后紧接着解释可见的函数、字段或分支。不会在每段源码前后套固定问答卡片；读者不需要每隔几段停下来做题。

每个代码块顶部都链接到 DeerFlow 仓库的固定 commit。这样正文不会因为主分支后续变化而和引文错位。需要完整上下文时可以打开出处，不需要时只读文中保留的主干。

class RunCreateRequest(BaseModel):
    """Validated run request used by both HTTP and internal launch paths."""

    model_config = ConfigDict(extra="forbid")

    assistant_id: str | None = Field(default=None, description="Agent / assistant to use")
    input: dict[str, Any] | None = Field(default=None, description="Graph input (e.g. {messages: [...]})")
    command: dict[str, Any] | None = Field(default=None, description="LangGraph Command")
    metadata: dict[str, Any] | None = Field(default=None, description="Run metadata")

比如这里的 RunCreateRequest 证明网页提交的不是一整句神秘命令，而是 input、command、metadata 等经过校验的字段。现在不用记住它们；第 02 章走到 Gateway 时会逐一放回控制流。

代码块右上角可以复制，也可以钉到页面右侧。第 02 章默认钉住第一段 worker 循环，它相当于整章的路标：往下读到模型、工具、事件或取消时，都能抬头确认它们最终回到哪条执行链。

读完应该得到什么

这不是部署手册，也不会穷举 DeerFlow 的每个配置项。目标是建立一个足够准确的运行模型：一次任务从哪里进入，谁在执行，模型与工具怎样往复，状态保存在哪里，最终文件为什么能被用户看到。

遇到故障时，这个模型还应该能帮你定位层次。没有 run_id，先看 Gateway；有 Run 没事件，去看 worker 与 StreamBridge；模型没看到信息，检查 Context 与 Memory；磁盘有文件但页面没有，检查 present_files 与 Artifact。

准备好之后，进入第 01 章。我们先不钻进调用栈，而是回答一个更基础的问题：模型已经会生成文字，DeerFlow 为什么还需要这么多运行结构。