01 这件事
85,481 星的 DeerFlow 在 2.0 换过一次内核:新版与 1.x 不共享任何代码。README 明说这是一次 ground-up rewrite,旧的 Deep Research 框架留在 main-1.x 分支,活跃开发全在 2.0。
仓库 2025-05-07 创建,11 月 18 日仍在 push,MIT 许可证,主语言 Python。1,124 个未结条目拆开是 596 个 issue 与 528 个 PR,PR 占了近一半。
字节把它的定位从「研究框架」改成了 super agent harness:运行时替 agent 备好文件系统、记忆、技能、沙箱和子代理,不必自己逐个拼装。
README 顶部挂着两个信号:2 月 28 日 2.0 上线时拿到 GitHub Trending 日榜第一,说明页有英、中、日、法、俄、葡、韩共 7 种语言。星标跨两代产品累积,不能直接当成 2.0 的用户量。
- 公开技能包:
skills/public/下 23 个目录,每个都有 SKILL.md - 文档:20 份
docs/guide/指南,从配置到安全各占一篇 - 版本:3 个正式 release、12 个 tag,最新是 11-04 的 v2.2.0
02 核心机制
它的核心不是「会聊」,而是把长任务拆给一组有边界的执行单元。底层用 LangGraph 与 LangChain 编排,agent 可以规划、派生 sub-agent,并在沙箱里读写文件、跑 bash。
config.example.yaml 有 3,815 行、200,091 字节,默认启用的工具只有 10 个:三个联网搜索抓取工具,加七个文件与 shell 工具。
| 层 | 位置 | 体量 | 职责 |
|---|---|---|---|
| 配置 | config.example.yaml | 3,815 行 | 模型、工具、权限开关 |
| 执行 | backend/ | 2,805 文件 / 45.63 MB | 网关、调度、沙箱调用 |
| 界面 | frontend/ | 1,429 文件 / 24.06 MB | 工作区与 TUI |
| 扩展 | skills/public/ | 23 包 / 0.65 MB | 可插拔技能 |
模型层走 OpenAI 兼容接口,README 的原话是 model-agnostic。示例配置列了 29 个模型条目,覆盖 OpenAI、Claude、Gemini、DeepSeek、Kimi、本地 Ollama 等。
但同一份 README 紧接着给出火山引擎的 Coding Plan,点名 Doubao-Seed-2.0-Code、DeepSeek v3.2 和 Kimi 2.5。这是推荐,不是硬锁定:29 个示例里只有 3 个 API 端点指向火山方舟。
真正决定行为的是配置里的开关,很多默认关着。token_budget 要打开才拦 token;pii_redaction 默认不脱敏;知识库默认不启用。装完不等于全开。
- 预算:上限 200,000 token,八成警告、满额停
- 输出外置:超过 12,000 字符的内容搬到 .tool-results
- 循环检测:警告 3 次、硬停 5 次
- 写前读与 harness_guard:默认开,语法错误会阻断
03 关键细节与数据
版本节奏快得像 CI:v2.1.0 到 v2.2.0 只隔 41 天,官方说其间合了 1,068 个 PR。
| 版本 | 发布 | 可核对的说明 |
|---|---|---|
| v2.0.0 | 2026-06-25 | 推倒重来的首版 |
| v2.1.0 | 2026-09-24 | 2.x 第二代正式版 |
| v2.2.0 | 2026-11-04 | 37,335 字符 / 11 条破坏性变更 / 430 个不同 PR 引用 |
v2.2.0 的说明里还藏着运维门槛:多进程部署必须接 Redis,凭据加密后要多配一个环境变量,定时任务默认每人最多两个并发。这些写在 Breaking changes 里,不是可选优化。
完整 git tree 有 5,524 条目、4,881 个 blob、84,199,279 字节。体积大头不在技能,在前后端:backend 与 frontend 合占约 83%。
| 目录 | 文件数 | 体量 | 占总 blob |
|---|---|---|---|
| backend/ | 2,805 | 45.63 MB | 54.2% |
| frontend/ | 1,429 | 24.06 MB | 28.6% |
| examples/ | 188 | 3.03 MB | 3.6% |
| docs/ | 130 | 2.54 MB | 3.0% |
| skills/ | 107 | 0.65 MB | 0.8% |
安全文档把边界写得很直白。默认只绑 127.0.0.1;要跨机访问得自己设 BIND_HOST=0.0.0.0,且先做完防护。
消息入口也做进了 harness:飞书、Slack、Telegram、Discord、钉钉都能接。20 份指南还覆盖浏览器控制、MCP、长期记忆、可观测性和定时任务,比研究框架的说明书厚得多。
- Gateway 管理员等于主机代码执行权,stdio MCP 的 npx / uvx 白名单只是纵深防御
- 外部请求里的 system / developer 角色被 HTTP 400 拒绝,旧 checkpoint 里已注入的内容不会被清掉
- 暴露到网络前要配 IP 白名单、认证反向代理、独立 VLAN,并持续跟更新
04 怎么用
最短路径是让 Docker 跑起来,再把模型 key 填进向导生成的文件。README 给的本地流程拆开是五个动作。
git clone后cd deer-flow:拉仓库并进入目录make setup:交互式向导写 config.yaml 与 .env,官方说约两分钟make check:检查 Node.js 22+、pnpm、uv、nginxmake docker-init与make docker-start:拉沙箱镜像并起服务make doctor:填完 key 后检查占位符配置
浏览器开 localhost:2026。不想用 Docker 可以走 make install 加 make dev,但对依赖版本更挑。
配置分散在三处:向导写的 config.yaml 与 .env,Capability Center 里管理的 MCP server 和 Skills,以及可选的 RAGFlow 私有知识库。最后一项默认关,要自己打开。
把服务搬出本机之前还有一道手续:新实例没有账号,先通过 /setup 建管理员,再谈 IP 白名单和反向代理。顺序反了,等于先开门再配锁。
选模型时 README 给了四条硬指标,不是随便一个兼容端点都能跑顺复杂任务。
- 长上下文:10 万 token 以上,供深度研究和多步任务使用
- 推理能力:支撑自适应规划与复杂拆解
- 多模态输入:要读图和看视频就得模型支持
- 工具调用:function calling 与结构化输出要稳定
Claude Code、Codex、Cursor 用户还有一句式安装:把提示词交给编码 agent,它自己判断要不要 clone、读 Install.md、选 Docker,并在缺配置时停下来。
05 冷思考
真正要付的成本不是星标,是升级和安全边界。41 天合 1,068 个 PR 的另一面,是 v2.2.0 说明里的 11 条破坏性变更:本地开发默认绑回环、凭据静态加密、多进程必须接 Redis。
456 位贡献者、4,876 次提交,看起来不像一人项目。贡献者接口合计 4,554 次归属,口径与提交分页不同;排在首位的 MagicCube 有 610 次,也没到一言堂。
模型可换是真的:29 个示例只有 3 个指向火山,README 也承认任何 OpenAI 兼容 LLM 都能接。但网关管理员权限不可换,它等价于主机代码执行,白名单挡不住能拉远程包的启动器。
还有一条容易漏掉:外部注入的 system 消息即使被 400 拒绝,旧 checkpoint 里的残留也要开新会话才能避开,重启不会清理。
数据面的默认值同样保守:知识库、PII 脱敏、token 预算三项都默认关。batteries included 更像把零件都装上,是否上电由运维决定。
这也解释了为什么安全文档把 Gateway 管理员写得那么重。它有注册 stdio MCP 的权力,而 npx 与 uvx 这类启动器本来就用来拉远程包运行;白名单能挡参数,挡不住包本身。
判断:把它当本机可信环境里的长任务工作台,别急着当可公开的 Agent 服务。换模型是改一行配置;把沙箱、网关和凭据的边界立住,才是部署这套 harness 的真实工作量。
数据核对(核对时间 2026-11-18)
- 仓库:bytedance/deer-flow,MIT,Python,创建 2025-05-07,pushed 11-18
- API:85,481 星 / 12,054 fork;未结 1,124 = 596 issue + 528 PR
- 版本:3 release / 12 tag;v2.2.0 于 11-04 发布,说明 11 条 breaking
- 完整树:5,524 条目 / 4,881 blob / 84,199,279 字节(truncated=false)
- 配置:3,815 行,29 个模型示例 / 3 个火山端点 / 10 个默认工具
- 技能:23 个公开包;456 贡献者 / 4,876 提交