# deerflow-book: a source-level guide to extending DeerFlow 2.0 > deerflow-book is a Chinese-language open source book that walks through DeerFlow 2.0 from architecture theory to line-by-line source analysis, covering Skills, sub-agents, sandboxing, memory and MCP integration, with every code example drawn from the real repository. It suits a developer who already knows LangGraph and needs to extend an existing agent framework, and it is not a beginner's introduction to agents. **hawkli-1994/deerflow-book** — 本书围绕 DeerFlow 2.0，从理论到源码，系统讲解如何进行二次开发。(精校) - Repository: https://github.com/hawkli-1994/deerflow-book - Website: https://hawkli-1994.github.io/deerflow-book - Stars: 562 · Forks: 88 - Language: JavaScript - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/hawkli-1994-deerflow-book ## A book organised around source files, not concepts deerflow-book is titled DeerFlow Secondary Development: Theory, Architecture and Source Analysis, and it describes itself as a deep technical analysis aimed at hardcore developers. Its stated scope is DeerFlow 2.0, moving from theory to source code to explain how to do secondary development on it. The organising principle is stated plainly: every code example is based on real source code, so that it stays consistent with the DeerFlow implementation. That claim is only credible because of how the table of contents is built. The source-analysis part of the book lists, for each chapter, the actual source files it covers. Chapter 5, the Agent core, is built around agents/thread_state.py and agents/middlewares/, and the highlights are the ThreadState type system, a list of more than fourteen middlewares and the DeerFlowClient SDK. Chapter 6 covers Skills and Tools with skills/security_scanner.py, skills/manager.py and skills/installer.py. Chapter 7 covers the sub-agent system through subagents/executor.py and subagents/config.py. Chapter 8 covers the sandbox with sandbox/sandbox_provider.py, sandbox/middleware.py and sandbox/security.py. Chapter 9 covers the memory system with agents/memory/storage.py, agents/memory/updater.py and agents/middlewares/memory_middleware.py. Chapter 11 covers MCP server integration with mcp/oauth.py, mcp/cache.py and mcp/client.py. This is a different book design from the usual conceptual tour. Rather than explaining event sourcing and then showing code, it pairs each idea with the file you would open to change it, which is what you need when the goal is to modify the framework rather than use it. The repository is a VitePress site. The package manifest declares the name deerflow-book at version 1.0.0, with three scripts for the documentation toolchain, vitepress dev, vitepress build and vitepress preview, and a single dev dependency on vitepress 1.6.4 with an override pinning vite to 6.2.6. There is a chapters/ directory holding the Markdown sources, an index.md, and a .vitepress/ configuration directory. The site is published at hawkli-1994.github.io/deerflow-book, and the licence is MIT. ## The three parts, and how the second part differs from the first The table of contents is in three parts plus appendices, and the structure tells you what the book is for. Part one is the theoretical foundation, three chapters. Chapter 1 is the introduction, covering DeerFlow's positioning, core features and technology stack. Chapter 2 is core concepts, and its highlights are the distinctions between Skill and Tool, Sub-Agent, Sandbox, Memory and Context Engineering. Chapter 3 is the architecture overview, with a system architecture diagram and the LangGraph Server, the Gateway API and the middleware chain. Part two is the source analysis, seven chapters, and the readme marks chapters 5 through 9 with a tick, indicating they have been deeply updated against the latest DeerFlow source. Chapter 4 covers project structure, directory organisation, module responsibilities and the configuration system, with no single source file listed because it spans the tree. Part three is the secondary development practice, four chapters, with a tick on chapter 11 only. Chapter 10 on context engineering covers context compression, RAG and token budget allocation. Chapter 11 is MCP server integration, with OAuth 2.0 authentication, tool caching and multiple transport modes across stdio, sse and http. Chapter 12 is custom Skill development, and its highlight is multimodal output Skills producing PPT, podcast, image, video and dashboard results. Chapter 13 is Human-in-the-Loop, covering approval node design, approval middleware and audit logs. Chapter 14 is enterprise application cases, covering multi-tenant isolation, RBAC, audit systems, a multimodal content platform and knowledge base integration. The appendices are a configuration reference with complete examples, a contributing guide with development conventions and the pull request process, a code sample appendix with full multimodal Skill code, and a glossary of core terms. The distinction between the parts is worth keeping in mind. Part one explains why the framework is shaped the way it is, part two shows where each piece lives in the code, and part three is where the book stops being about DeerFlow's internals and becomes about how to build on them. ## Running DeerFlow to follow along The book's quick start assumes you have the upstream DeerFlow repository running, since the examples are meant to line up with real behaviour. The upstream project is cloned and started with Docker Compose: ```bash # 克隆 DeerFlow 官方仓库 git clone https://github.com/bytedance/deerflow.git cd deerflow # 使用 Docker Compose 启动全套服务 docker-compose up -d # 检查服务状态 docker-compose ps ``` With the services up, the interface is served at http://localhost:2026. The first test the readme suggests is a conversation in the web UI using an @-prefixed mention of a skill, followed by a research topic, a depth level and an output format. DeerFlow is described as loading the named skill automatically, running the web search and information integration, and returning a structured research report. Two configuration templates are copied before the environment is configured: ```bash cp config.example.yaml config.yaml cp extensions_config.example.json extensions_config.json ``` The environment variables the readme lists are few and specific. OPENAI_API_KEY for the LLM API key and DEERFLOW_DATABASE_URL for the PostgreSQL connection string are both required. SANDBOX_MODE is optional and takes local, docker or provisioner, defaulting to local, and MCP_SERVERS_CONFIG points at the MCP server configuration file and is also optional. Appendix A holds the full configuration reference. That small set of required variables is worth noticing. A framework that needs only a model key and a database connection, with the sandbox mode left at local by default, is a much lighter thing to try than one that demands a cluster of infrastructure before it will start. ## Reading paths, prerequisites, and who the book assumes you are The readme gives four reading paths, and they are the most direct statement of the intended audience. An agent development beginner is directed to chapters 1, 2, 3 and then 12 for getting Skill development going quickly. A secondary development engineer is directed to chapters 4, 5, 6, 7 and 11 as the core architecture. An enterprise application developer is pointed at chapters 5, 8, 9, 13 and 14 for production work. A source contributor is told to read the whole book, then appendix B, and then go to the DeerFlow source directly. The prerequisites section is where the level becomes explicit. It asks for Python 3.12 or newer with familiarity with type annotations and async programming, an understanding of LangChain and LangGraph basics around graphs, state and nodes, real project experience with agent and LLM application development, and an understanding of Docker for the sandbox chapter. That is a real bar, and the book is not trying to lower it. The chapters on the ThreadState type system, the middleware lifecycle, the sandbox provider pattern and the sub-agent task state machine are all things that assume you already know what a graph and a state object are in LangGraph terms. One more audience note. The book is written in Chinese, with an English readme in the repository only in the sense that the table of contents in this version was translated for this summary; the actual chapters are Chinese, and the contributing section lists translation into other languages as a welcome contribution. For a reader who does not read Chinese, the project is currently a closed book, and the appendix C code samples would need translating too before they are useful. ## How the book tracks DeerFlow releases A source-level book is only as useful as its alignment with the upstream code, so the readme keeps a dated log of what changed and when, and that log is unusually detailed. The entry for 2026-06-21 is described as a major update and covers the memory material. It records that chapter 2 now makes explicit that the built-in memory does not use embeddings, a vector database or similarity retrieval. Chapter 9 was rewritten around JSON profile and facts, LLM updates, the MemoryMiddleware and prompt injection. Chapter 10 changed its memory retrieval example to JSON facts injection and now distinguishes external RAG extensions from the built-in mechanism. The configuration appendix and the glossary were updated to match. The 2026-05-02 entry covers DeerFlow 2.0 progress as of April 2026. Chapter 1 gained the core features Progressive Skill Loading, InfoQuest and multimodal output. Chapter 3 gained a section on where progressive Skill loading sits in the architecture. Chapter 6 gained the progressive Skill loading mechanism and InfoQuest integration. Chapter 12 gained multimodal output Skill development covering PPT, podcast, image, video and dashboard output. Chapter 14 gained a section on an enterprise multimodal content generation platform. The 2026-04-09 entry covers the deepest source updates. Chapter 5 added the ThreadState type system with NotRequired and Annotated, the full list of more than fourteen middlewares and the DeerFlowClient SDK. Chapter 6 added Skill security scanning, history management and the installer implementation. Chapter 7 added the SubagentExecutor, the task state machine and background task management. Chapter 8 added the sandbox provider pattern, the middleware lifecycle and security auditing. Chapter 11 added OAuth 2.0 authentication, MCP tool caching and multiple transports. The version information block records the DeerFlow version as 2.0, the book version as 2026.06 and the last update as 2026-06-21. The last push to the repository was on 2026-10-18, so there has been activity since that documented update, which means the log and the repository are not perfectly aligned. ## Where deerflow-book is the wrong tool The first limitation is the language. The chapters are Chinese, the readme in this repository is a Chinese document, and the translation contribution slot is listed as an open invitation rather than an existing English edition. If your team does not read Chinese, the book's value drops to the code examples alone, and those examples still need the surrounding explanation. The second is the coupling to one upstream version. The book explicitly tracks DeerFlow 2.0, the version block names DeerFlow 2.0, and the update log shows three rounds of re-alignment in three months. A book whose value is line-by-line correspondence with source code loses that value the moment the upstream code moves. The April, May and June updates each describe substantial rewrites of whole chapters, which tells you how quickly the correspondence decays. The third is that it is documentation for a specific framework, not a book about agent architecture in general. The theory part is short, three chapters, and it exists to set up the DeerFlow specifics rather than to teach you the field. If your problem is understanding LangGraph or agent design in the abstract, this is the wrong book even if you read Chinese. The fourth is the risk profile of what the source covers. Several chapters are about the parts of an agent framework that run untrusted code or make autonomous decisions: the sandbox provider modes of local, docker and provisioner, the security scanner in skills/security_scanner.py, the security auditing in sandbox/security.py, the sub-agent executor and its background task management, and the human-in-the-loop approval middleware. A reader following these chapters is learning how to extend a system that executes model-written code and makes tool calls, and the book is a description of how the upstream project does it rather than an independent assessment of whether those defaults are safe. The fifth is that DeerFlow is ByteDance's project and this is a community contribution. The readme is explicit that DeerFlow is ByteDance's open source project and that the book is a community-contributed secondary development guide, and the contributing section asks for pull requests covering content corrections, new source analysis, clearer examples and translations. That is healthy, and it also means the book has no guarantee of coverage for DeerFlow versions released after the last update. ## Conclusion deerflow-book fits a developer who has to modify DeerFlow 2.0 rather than merely run it, since the chapters are organised around the actual source files, agents/thread_state.py, skills/security_scanner.py, subagents/executor.py, sandbox/sandbox_provider.py and mcp/oauth.py among them, and each chapter pairs a concept with the file it lives in. It is the wrong choice if you are new to agent development, since the readme states a prerequisite of Python 3.12 or newer, working knowledge of LangChain and LangGraph, and real experience building LLM applications, and it is the wrong choice if you read English only, since the text is Chinese. Before adopting it, check the chapter update log against the DeerFlow version you are running, and note that the last push was on 2026-10-18 with the book at version 2026.06 covering DeerFlow 2.0. ## FAQ ### What is deerflow-book? It is an open source Chinese-language book about DeerFlow 2.0 secondary development, going from theory through architecture to source-level analysis. Every code example is based on real source, and the source-analysis chapters are organised around the actual DeerFlow files such as agents/thread_state.py, skills/security_scanner.py, subagents/executor.py and mcp/oauth.py. ### What are the prerequisites for reading deerflow-book? Python 3.12 or newer with type annotations and async programming, basic LangChain and LangGraph concepts around graphs, state and nodes, real project experience with agent and LLM application development, and an understanding of Docker for the sandbox chapter. ### How do I run DeerFlow to follow along with deerflow-book? Clone the upstream repository with git clone https://github.com/bytedance/deerflow.git, change into the deerflow directory and start the services with docker-compose up -d, then check the status with docker-compose ps. The web interface is served at http://localhost:2026. ### Which environment variables does DeerFlow need? OPENAI_API_KEY for the LLM API key and DEERFLOW_DATABASE_URL for the PostgreSQL connection string are required. SANDBOX_MODE is optional and takes local, docker or provisioner with a default of local, and MCP_SERVERS_CONFIG points at the MCP server configuration file. The full reference is in appendix A. ### How is deerflow-book published and licensed? It is a VitePress site built with three npm scripts, vitepress dev, vitepress build and vitepress preview, with a single dev dependency on vitepress 1.6.4. The online version is at hawkli-1994.github.io/deerflow-book, the Markdown sources are in the chapters/ directory, and the book is released under the MIT licence. ## Sources - [hawkli-1994/deerflow-book on GitHub](https://github.com/hawkli-1994/deerflow-book) - [Issues](https://github.com/hawkli-1994/deerflow-book/issues) - [License: MIT](https://github.com/hawkli-1994/deerflow-book/blob/main/LICENSE) - [Project website](https://hawkli-1994.github.io/deerflow-book) - [README](https://github.com/hawkli-1994/deerflow-book/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hawkli-1994-deerflow-book