deer-flow/CHANGELOG_zh.md

更新日志

本文件记录 DeerFlow 的所有重要变更。

格式参考 Keep a Changelog， 版本号遵循 语义化版本规范。

English | 中文

[未发布]

本节累积面向 2.1.0 里程碑（里程碑 2）的工作。

⚠ 不兼容变更（Breaking Changes）

• 沙箱： E2B 现在将 sandbox.replicas 作为进程级容量上限来强制执行。默认的 wait 策略会等待 acquire_timeout，随后令当前智能体回合失败。DeerFlow 不会自 动重试该回合。可使用 burst 配合 burst_limit 允许有限地超出额度多开 VM。reject 策略可在返回容量错误前先回收一个预热 VM。(#4391)
• 技能： 包含 SKILL.md 的目录现在是一个运行时包边界。该包内嵌套的 SKILL.md 文件被视为支撑数据，不再注册为独立技能；若自定义目录结构较为特殊，需将可独立加 载的技能移到不带自身 SKILL.md 的命名空间目录下。(#4098)
• 记忆： 记忆系统现已可插拔（memory.manager_class 选择后端；默认 deermem 自包含）。DeerMem 私有配置从 memory: 顶层移入 memory.backend_config，/memory/config 响应（以及 client.get_memory_config()）的结构也发生了变化。(#4122)
• 记忆： /memory/config 与 client.get_memory_config() 不再返回扁平的 DeerMem 字段（storage_path、max_facts、debounce_seconds、token_counting、guaranteed_* 、staleness_* 等）。改为返回 {enabled, mode, injection_enabled, manager_class, backend_config}，其中 backend_config 是一个由当前后端自行解释的不透明 dict 。记忆数据响应（/memory、/memory/status 的 data）未变。读取旧扁平字段的 外部 API / SDK 客户端需改为读取 backend_config。(#4122)
• 记忆： 自定义 memory.storage_class 发生迁移：旧的默认路径 deerflow.agents.memory.storage.FileMemoryStorage 已不存在（现为 deerflow.agents.memory.backends.deermem.deermem.core.storage.FileMemoryStorage ）。自定义 MemoryStorage 子类的 __init__ 必须接受 config（此前为无参）。 损坏或过期的 storage_class 会记录错误并回退到 FileMemoryStorage（不会崩溃 ）——请更新路径与签名以恢复使用。(#4122)
• 记忆： storage_path 的语义由“文件路径”改为“根目录”。抽象化之前，绝对 storage_path 是共享的记忆文件（不按用户隔离），相对值则是 data base_dir 下的全局文件。现在 storage_path（无论绝对或相对）都是根目录；按用户的记忆存放在 {storage_path}/users/{uid}/memory.json 。若升级后仍保留旧的默认 storage_path: memory.json（一个相对文件名），会导致 按用户的记忆孤立，或在保存时触发 NotADirectoryError。因此旧版迁移会带告警 丢弃以 .json 结尾的文件式 storage_path 值，且当 storage_path 解析到一 个已存在的文件时工厂会抛出异常。如需自定义根目录，请将 memory.backend_config.storage_path 设置为一个目录。(#4122)
• 记忆： 当 memory.mode: tool 搭配一个未实现 search() 的后端时，现在会在 Gateway 启动时由 MemoryManager 的不变量校验快速失败并抛出 ValueError，而不 是启动成功后在每次 memory_search 调用时静默返回空结果。两个内置后端都实现了 search()（DeerMem 会检索，noop 返回 []），因此仅影响未覆盖 search() 就 接入的自定义后端。这是有意为之——静默返回空比启动期报错更糟。修复方式：切换到 mode: middleware，或覆盖 search()（并设置 supports_search=True）。(#4324)

新增

智能体与运行时

• 中间件： 新增 TokenBudgetMiddleware，强制单个 run 的 token 预算，在主智 能体与子智能体之间累加共享。(#3412)
• 中间件： 结构化的工具结果元数据与工具进度状态机，让运行时对多步工具流拥有 一等可见性。(#3601)
• 上下文： 每个 run 记录生效的记忆身份，并在摘要过程中持久化持久上下文（系统 消息、记忆与工具状态），以结构化运行时元数据的形式发出，压缩（compaction）不再 丢失这些信息。(#3556、#3887、#3906)
• 运行时： 目标延续（goal continuation）允许 run 跨多个智能体回合朝目标继续 执行，并跟踪、限制 continuation_count。(#3858)
• 子智能体： 系统维护的委派账本（delegation ledger）防止对在途任务重复委派， 并设总委派上限以约束单个 run 的扇出。(#3877、#4115)
• 子智能体： 在会话中持久化并展示子智能体的步骤历史。(#3845)
• 工具： 结构化摘要取代预览中原始的超大工具输出。(#3377)
• 文件： 文件工具引入确定性的“写前读”版本门控，避免覆盖并发编辑。(#3912)
• 网关： 感知缓存的成本核算将 token 成本归因到缓存 / 未缓存路径；Redis stream 桥接启用分布式事件流；并向用户暴露手动上下文压缩。(#3920、#3191、#3969)
• 运行时： 双模式 checkpoint 存储（基于 LangGraph DeltaChannel）将长调研 / 编码 run 的会话存储从 O(N²) 降至近线性。(#4292)
• 智能体： 配置声明的主智能体中间件，让部署方无需修改运行时链即可加入自定义 AgentMiddleware 类。(#3964)
• 智能体： 按智能体的模型与生成设置（temperature、max_tokens、thinking_enabled 、reasoning_effort）可覆盖共享的模型 profile。(#4347)
• 运行时： 记录终态的 artifact 投递回执，使预期要 present_files 的 run 在 投递失败时不再误报成功。(#4365)
• 上传： 通过 list_uploaded_files 工具懒加载历史文件，而非注入完整清单。(#4174)

记忆

• 记忆： 记忆合并（consolidation）合成碎片化的事实，并通过 LLM 为每条事实分 配的 expected_valid_days / staleFactsToExtend 进行过期审查，剪除静默过期的 事实。(#3996、#3860、#4143)
• 记忆： 保证注入纠正事实（并优雅降级），使用户的纠正始终能触达模型。(#3592)
• 记忆： 精简可插拔的 MemoryManager 接口以方便后端接入——新后端不再需要实现 未被调用的抽象方法，DeerMem 专有的 hook 注入也移出共享工厂。(#4326)
• 记忆： 增量式按智能体作用域的 Markdown 事实存储，按智能体隔离事实，且更新 单条事实时无需重写或重建整个集合的索引。(#4279)
• 记忆： 记忆消息处理新增会话水位（watermark）、无意义回合过滤与持久化队列， 使抽取不再每回合都重新喂入完整会话。(#4447)

技能

• 技能： 原生 SkillScan（阶段一）在加载时静态分析技能包；describe_skill 支 持延迟发现，模型按需获取技能 schema，而非一开始就加载全部技能。(#3033、#3775)
• 技能： 按用户的自定义技能隔离，并配合沙箱挂载。(#3889)

模型与集成

• 社区工具： 新增网络检索 / 抓取引擎——GroundRoute、Crawl4AI（web_fetch）与 fastCRW provider——并新增 Browserless web_capture 截图工具和 Brave image_search 。(#3675、#3821、#3585、#3881、#3866)
• MCP： MCP 工具调用支持按 server 的 tool_call_timeout，并提供路由提示引导 模型选用正确的 server。(#3843、#4004)
• 社区工具： 将“智能体化浏览器控制”作为会话的一等能力——基于 Playwright 的浏 览器会话由智能体操作，用户可在工作区中观察或接管。(#4187)
• 社区工具： Lark / 飞书 CLI 集成打包了运行时安装、官方 lark-* 技能包与交 互式授权流程，使该集成不再依赖手动环境配置。(#3971)

渠道

• 渠道： 把 IM 的 channel_user_id 以 DEERFLOW_CHANNEL_USER_ID 暴露给沙箱 命令。(#3926)
• 渠道： 对同一会话的密集消息进行排队，并在批次间保留话题卡片预览。(#3988)

认证与防护

• 认证： 通用 OIDC / SSO 认证，并支持 Keycloak。(#3506)
• 护栏： 已认证的运行时上下文在 GuardrailRequest 中暴露，安全干预以 run 事 件的形式持久化。(#3665、#3837)
• 认证： “保持登录”选项，配合统一的会话 cookie 策略（HTTPS 下使用持久化 Secure cookie，公网 HTTP 下使用会话 cookie）。(#4255)
• 认证： 部署方可关闭本地自注册，将新账号限制为仅通过 SSO / OIDC 开通。(#4311)
• 鉴权： 内置 RBAC 鉴权 provider 与统一工厂，并在装配期（模型可见前移除工具 ）与运行期（拒绝被禁用的调用）双重强制执行工具鉴权。(#4260、#4370)

沙箱与 provisioner

• 沙箱： 新增 E2B 与 BoxLite（micro-VM）沙箱 provider；BoxLite 自带预热池。(#3883 、#3940、#3951)
• provisioner： ClusterIP Service 与按技能作用域的 PVC 挂载，并支持配置沙箱 容器端口。(#4016、#3928)

前端

• 前端： 支持对助手回合进行分支，以及针对引用追问的侧边对话。(#3950、#3934)
• 前端： 支持重新生成最新回答。(#3637)
• 前端： 引用来源证据面板、智能体 run 的工作区变更评审，以及可视化的 ask_clarification 卡片。(#3907、#3945、#3956)
• 前端： 语音输入、方向键回溯 prompt 历史、输入框内容润色，以及“（思考了 N 秒）”思考时长标签。(#4036、#3718、#3986、#3627)
• 前端： 用 agents_api 特性开关控制智能体 UI 的可见性，并在后端与 UI 中持 久化 AI 回合时长。(#3769、#3663)
• 前端： 将斜杠技能（slash-skill）激活渲染为内联标签（chip）。(#3981)
• 前端： 本地化的 AI 辅助声明。(#4374)
• 前端： 支持置顶最近会话。(#4442)
• 前端： 在输入框中校验 /goal 目标长度。(#4337)

可观测性与工具

• 可观测性： trace-id 关联与增强日志，以及通过 Monocle 实现的智能体可观测性 。(#3902、#4024)
• 工具： 类 Hermes 的终端工作台（deerflow CLI，基于 DeerFlowClient），以 及脱敏的社区支持包（support-bundle）生成器。(#3760、#3886)
• 安装向导： 安装向导现在会询问 OpenAI 兼容的 gateway 模型是否支持 thinking ，并新增火山引擎 Coding Plan 快速安装路径。(#3428、#4141)
• TUI： clear 命令。(#4306)

变更

• 沙箱： Helm chart 现在默认将每个沙箱的 Service 设为 ClusterIP 而非 NodePort ，因此代码执行沙箱只能通过集群内 Service DNS（http://sandbox-<id>-svc.<ns>.svc.cluster.local ）访问，不再绑定到每个节点（包括 GKE / EKS / AKS 上外部可达的）网卡。升级时现 有 chart 安装会从 NodePort 切到 ClusterIP。如需保留原有可达性（外部探测命中 30xxx 端口，或 gateway 不在 K8s 的 Docker-Compose / 混合部署路径），请设置 provisioner.sandboxServiceType: NodePort（必要时配合 provisioner.nodeHost）。provisioner 本身不变（自 #4016 起已按模式感知）。(#4190)
• 技能： 处于激活态的限制型技能若要委派给子智能体，必须在 allowed-tools 中 显式声明 task。只读发现基础设施（tool_search 与 describe_skill）仍可用， 但无法为被禁用的业务工具授予 schema 可见性或执行权限。(#4098)
• 记忆： 抽象化之前位于顶层的 memory.* DeerMem 字段（storage_path、max_facts 、debounce_seconds、model_name、token_counting、staleness_*、consolidation_* 等）在加载时会带告警自动迁移到 backend_config，因此升级不会静默地把自定 义配置回退为默认值（model_name -> backend_config.model.model）。将它们移到 config.yaml 的 memory.backend_config 下即可消除告警。(#4122)
• 记忆： 新增 memory.mode（middleware | tool）；tool 模式会注册供模 型直接调用的记忆工具（memory_search/add/update/delete），取代被动的逐 回合摘要。manager_class 解析改为快速失败（未知后端时抛出 ValueError，而非 静默回退）。(#4023)
• 中间件： 声明式分层中间件构建器；ThreadData 现在先于 Uploads 运行。(#3809)
• 沙箱： 宿主机到虚拟机的输出脱敏正则现在统一归属，消除重复的模式编译。(#4108)
• 文档： AGENTS.md 成为智能体指引的权威来源，CLAUDE.md 通过 @AGENTS.md 导入；模块指南同步刷新。(#3770)

修复

• 运行时： 会话元数据现在仅在 run 通过启动屏障后才切换为 running，待取消的 run 不再短暂呈现 running 状态；worker 启动期间客户端可能观察到先前的会话状态 。(#4450)
• 运行时： 通过原子化、感知租约的接管（takeover）claim 重新检查孤儿候选 run ，使扫描后的成功心跳仍保持 run 活跃，且仅有一个 reconciler 上报恢复。(#4424 、#4434)
• 技能： allowed-tools 只作用于斜杠激活或实际加载的主智能体技能，避免被动 启用的技能与评测 fixture 从每个 run 中移除 MCP、网络、文件与委派工具。(#4095 、#4098、#4192)
• 模型： 在所有 BaseChatOpenAI 子类（VllmChatModel、MindIEChatModel、PatchedChatMiMo 、PatchedChatStepFun、PatchedChatMiniMax）上生效 api_base，而不只是 ChatOpenAI / PatchedChatOpenAI。此前这五个子类会静默丢弃配置的 endpoint，随后以一个含义 不明的 unexpected keyword argument 'api_base' 让每次请求都失败；它们也未被纳 入未知配置 key 的告警。两者现在都基于 issubclass(BaseChatOpenAI) 判断。(#4146)
• 智能体： 在 LLM 请求前合并 SystemMessage；保证工具运行后仍有可见响应；避 免在流结束前发起默认的 LLM 标题调用；为省略号预留空间以使本地标题遵守 max_chars ；并将工具输出尾部前移，使回退截断遵守 max_chars。(#3711、#4033、#3885 、#4052、#4017)
• 智能体： 动态上下文的日期扫描跳过无日期的提醒；从不含 config.yaml 的智能 体目录加载 SOUL.md；update_agent 的旧版智能体守卫要求存在 config.yaml； 并拒绝空的 SOUL.md 更新。(#3685、#4136、#4166、#4219)
• 中间件： 为循环检测的工具频次计数器加窗口，避免长 run 误触；阻止标题中间件 流式输出 token；修复“同内容列表耗尽时位置回退误取无关 todo”的问题；在 _apply 、before_agent、_clear_run_state 与 _drain_pending_warnings 之间持有 token 预算锁；丢弃孤立的 ToolMessage 以免严格型 provider 返回 400；净化非法 tool-call 参数；并在 dangling 修复中从空的 tool-call 名称与畸形 tool-call id 恢复。(#4072 、#3566、#3709、#3714、#4080、#4193、#4008、#4246)
• 子智能体： 继承 LoopDetectionMiddleware 与摘要中间件，使工具循环能被打断 、步骤能被捕获；将回合预算上限以 MAX_TURNS_REACHED 暴露并附带部分结果；在累 加式 stop_reason + token_budget 上统一护栏上限；压缩前注入持久上下文；保留 父 checkpoint 命名空间；在 general-purpose 系统 prompt 中禁用 task 工具；flush 失败时重新缓冲子智能体事件以避免丢失步骤；并修复子智能体 run_id 为 None 时 丢失 loop_capped 停止原因的问题。(#3931、#4009、#3949、#3980、#4040 、#4215、#4161、#4082、#4059)
• 记忆： 加固对 null / 空值边界情况的处理——跳过仅含空白的事实；在更新、检索 与剩余三处原始读取中规整 null 的 confidence / source.confidence；将显式 null 的 backend_config 值视为缺省；修复事实无 id 或事实列表为空时的 KeyError / UnboundLocalError；停止防抖更新队列的忙等（busy-spin）；并在优雅关闭时刷写记 忆队列以防丢失。(#3719、#4074、#4076、#4034、#4217、#3993、#3992 、#4073、#4181)
• 运行： 关闭 run 原子性中的多 worker 归属缺口；在租约续期于截止期前无法确认 时令本地执行快速失败，并在 peer 接管后对迟到的完成写入加围栏；多 worker 下将 cancel 降级为租约接管；让 create_thread 在插入竞态时仍幂等；从运行时上下文读取 stop_reason ；并将 run 时长持久化到 checkpoint 以供历史读取。(#4003、#4064、#4414、#3800 、#4188、#4118、#4431)
• 运行时： 序列化 SQLite event-store 写入，避免按会话的序列号冲突；在 journal 中跳过隐藏的人类消息；并去掉 _merge_stream_text 中静默丢弃 delta 的行为。(#4077 、#3698、#4085)
• 网关： 按真实 event_type 关联会话消息反馈；把 artifact 服务、gateway 上 传与 Discord 渠道中的阻塞文件 IO 移出事件循环；限制上传文件的上下文清单；并实 时追踪畸形的 Redis 重连 id。(#3651、#3551、#3935、#3927、#3917、#4012)
• 上传： 在写入前先占位转换后的 Markdown 配套文件名，使同词干（stem）的两个 可转换上传（或一个可转换上传加一个同词干 .md 上传）不再在同一请求内静默互相 覆盖。uploads.auto_convert_documents 开启时，配套 .md 会得到唯一名称（如 a_1.md ）；POST /threads/{id}/uploads 与 DeerFlowClient.upload_files 都会在 markdown_file 中返回实际文件名。(#4288)
• 配置： 将为 null 的对象型配置节规整为默认值；在 store 与 sync checkpointer 中遵循统一数据库配置；并让旧版 DB 回填在已存在的表上补建缺失的 Index 对象。(#3573 、#3904、#3994、#4090)
• 模型： 将 stream_chunk_timeout 默认值应用到所有 BaseChatOpenAI 子类； 并为 ChatOpenAI 把 api_base 规范化为 base_url，遇到未知配置 key 时给出告 警。(#4102、#3790)
• MCP： 按 server 隔离工具发现失败；同步 session-pool 单例的生命周期；按配置 内容 + 路径（而非仅更新的 mtime）失效工具缓存；在加载时校验 MCP 工具名，使延迟 prompt 保持惰性；并按来源 server 路由工具，而非按名称前缀。(#3772、#3797、 #4124、#4154、#3812)
• 技能： 斜杠技能每个 run 仅激活一次，而非每次模型调用都激活；补齐技能安装安 全扫描的覆盖缺口；在评审 CI 中识别被完全删除的技能包，并在 SkillScan 中把剩余 的 requests / httpx 方法识别为网络出口；在无参 skills prompt 段落复用已解 析的 app 配置；并支持不重启 Gateway 即可重新加载已挂载技能。(#4103、#3924 、#4169、#4130、#4160、#4264)
• 沙箱： 为反向路径翻译与输出脱敏正则加上段边界；在 read_file / str_replace 中处理单边行范围与空文件；对齐 AIO bash 工作目录；在 Windows 的反向 resolve 包 含性检查中使用 os.sep；在 bash 命令中规范化 Windows 反斜杠路径；阻止 glob / grep / ls 暴露被禁用技能的文件；并在沙箱审计中允许合法的 heredoc 命令。(#4035 、#4053、#4078、#4079、#4051、#4058、#3869、#4096、#3786)
• 沙箱： 同步沙箱 provider 单例的生命周期（含并发回归测试），并让 provisioner 中的 k8s 调用不阻塞事件循环。(#3730、#3941)
• 沙箱： 将沙箱 artifact 挂载与渠道用户对齐；修复非 root / NFS 主机上的本地 开发（make dev）；停止时回收 macOS 上的 nginx 进程；并修复 Docker 中生产环境 Postgres 的 UV-extras 检测。(#3729、#3590、#3828、#3897)
• 渠道： 在解析渠道 provider 配置前先校验 provider；对 GitHub webhook 重投递 去重，并丢弃冗余的 GitHub review-comment webhook 扇出；把斜杠技能白名单检查限 定在 run 的 owner 作用域；将飞书文件消息批量到一个会话，并以 bot @mention 前缀 分发飞书群命令；在 /connect 绑定码前接受前导 @mention，且不把裸 connect 当 作绑定命令；阻止飞书创建会话话题并限流卡片更新；让 UI 运行时渠道配置优先于 config.yaml ；修复 bot_login / mention_login 仅含空白时 require_mention 的门控；防护 企业微信中为 null 的引用字段；并将入站去重按聊天作用域的工作区建立 key，使 Telegram 、飞书、微信与钉钉在默认（未绑定）配置下不再因重投递重复执行智能体，遇到瞬时失 败时释放去重 key 以便重投递仍可恢复。(#4100、#4104、#4131、#4129、#3753 、#4229、#4222、#4251、#3810、#3674、#4055、#4069、#4287)
• 前端： 摘要过程中保留消息与持久上下文；流式期间保留 artifact 并稳定 artifact 路径；解析相对 artifact 图片路径；在 header 下拉中保留已展示的 artifact；保持 孤立的工具消息可见；工具步骤期间展示助手文本；客户端导航时重置新会话；防止并发 提交导致流被取消；修复过期 run 的重连与取消处理；修复聊天公式渲染、单波浪线 markdown 、双重 reasoning 渲染、UTF-16 markdown 二进制分类与 Streamdown 中的 <memory> 标签；让最近会话行整体可点击；上传前校验附件上限并修复消息复制中上传文件元数据 ；修复移动端工作区与可访问性阻塞、卡片工具消息 bug 以及侧边聊天工具栏 / 面板按 钮行为；拦截未解析的建议模板占位符；刷新通知权限；仅对已完成回合显示分支操作； 在自定义智能体聊天中启用重新生成；并为被中断的首回合 run 生成兜底标题。(#3826 、#3791、#4094、#4038、#3854、#3880、#4114、#3673、#3878、#3908 、#3557、#4245、#3870、#3966、#4209、#3733、#3900、#3944、#3740 、#3976、#3959、#3961、#3764、#3768、#4147、#3967、#3874、#3644)
• TUI： /quit 退出前先中断活动 run。(#4235)
• harness： 当大纲标题数恰好等于 MAX_OUTLINE_ENTRIES 时不再误判为被截断。(#3856)
• 追踪： 把 Langfuse trace 元数据附加到目标评估器。(#4202)
• 上下文： 修复 context-compress 的 bug。(#4065)
• ThreadData： 修复 runtime.context 为 None 时的 AttributeError。(#3989)
• goal： 修复 stand-down 期间 continuation_count 被重复递增的问题。(#4199)
• 熔断器： 修复半开探测不可重试后熔断器卡死的问题。(#3991)
• GitHub： allow_authors 登录名改为大小写不敏感匹配。(#4218)
• 社区工具： image_search 现在返回全分辨率图片 URL。(#3990)
• 技能： 把技能历史接口中的阻塞文件 IO 移出事件循环。(#3563)
• 技能： SkillScan 不再把惰性求值的 PEP 695 类型别名误判为网络出口。(#4315)
• 追踪： 从运行时上下文解析 Langfuse trace 的用户。(#3794)
• 护栏： 将内部 owner 归因透传到护栏上下文。(#3839)
• 子智能体： 子智能体上限与 MIN_SUBAGENT_LIMIT 保持一致地限幅。(#4081)
• 子智能体： 加载按用户作用域的技能。(#4356)
• MCP： 按 server 的 OAuth 预热改为失败即软降级，并持久化轮换后的 refresh token 。(#4084)
• MCP： 忽略畸形的类路径文本。(#4456)
• 认证： 邮箱账号改为大小写不敏感解析。(#4101)
• 认证： 从 setup-status 超时中恢复。(#4371)
• 调度器： 修复一个调度竞态，该竞态可能为同一个定时任务启动两个 run。(#4105)
• 渠道： 缓冲并在 busy run 期间排空被排队的 GitHub 评论。(#4133)
• 渠道： 在转换为 mrkdwn 前先转义 Slack 保留字符。(#4197)
• 渠道： 飞书卡片 / reaction SDK 调用上检查 response.success()。(#4234)
• 渠道： 丢弃不携带会话身份的入站钉钉消息。(#4316)
• 渠道： 支持接收入站 Telegram 附件。(#4392)
• 记忆： 合并后的事实从其来源继承 expected_valid_days。(#4225)
• 配置： _memory_config 与 AppConfig 自动重载保持同步。(#4208)
• Postgres： 用 pool_recycle 与 command_timeout 加固异步引擎，消除陈旧连 接导致的 504。(#4230)
• harness： 为 invoke_acp_agent 增加超时，避免无限挂起。(#4238)
• 社区工具： 在 web_fetch（Browserless）中暴露目标页的错误状态。(#4239)
• 沙箱： 放宽 BoxLite / AIO 的租户哈希范围，并在回收时校验身份。(#4171)
• 沙箱： str_replace 在任意文件上遇到空 old_str 时改为无操作。(#4256)
• 沙箱： 序列化 E2B 的释放状态转换。(#4355)
• 沙箱： 限制 E2B 输出同步的资源占用。(#4364)
• 沙箱： 在 after_agent 中解包被 Overwrite 包裹的沙箱状态。(#4381)
• 沙箱： 本地 AIO 流量绕过代理。(#4444)
• 模型： 暴露因长度截断的模型响应，而非直接丢弃。(#4309)
• 流式： 保持大文件生成过程的响应性。(#4354)
• 流式： 把自定义事件暴露给 astream_events。(#4403)
• 流式： 对回放历史中的缺口发出信号。(#4426)
• 摘要： 使用 run 模型进行摘要，摘要 provider 失败时回退。(#4361)
• 运行时： 模型调用后移除临时的图片上下文。(#4267)
• 运行时： 阻止子图流式帧冒充根帧。(#4407)
• 运行时： 拒绝不支持的 run 选项与流模式。(#4430)
• 运行时： 序列化 checkpoint 写入与活动 run、线性化 delta 模式的 checkpoint 恢复，并接受 SDK 默认的 stream_resumable=false，以避免恢复竞态。(#4437、#4460 、#4468)
• checkpoint： 解包对空 channel 的 Overwrite 首次写入。(#4383)
• nginx： 允许超长聊天 prompt 通过 /api/langgraph/，不再直接返回 500。(#4277)
• 网关： 当 header 已设置时，优先使用 X-Trace-Id 而非 metadata.deerflow_trace_id 。(#4283)
• 网关： 为分支补种 run-events，使继承的历史在分叉后仍然保留。(#4385)
• 网关： 分支历史补种的 run id 按继承的回合作用域划分。(#4459)
• 前端： 加固 artifact 与 markdown 渲染。(#4117)
• 前端： 工作区变更评审中，把“符号链接替换文件”与“删除”区分开。(#4170)
• 前端： 把工作区变更文本缓存生命周期中的阻塞文件 IO 移出事件循环。(#4268)
• 前端： 对 artifact URL 的路径段进行编码。(#4278)
• 前端： 厘清 run 时长的展示。(#4348)
• 前端： 在分支会话中保留重新生成状态。(#4358)
• 前端： reasoning-effort 未设置时默认展示为 Medium。(#4373)
• 前端： 剥离并解析 <current_uploads> 上传上下文标签。(#4402)
• 前端： 保持前导的孤立工具消息可见。(#4408)
• 前端： 刷新后保持已完成子任务卡片的稳定。(#4432)
• 前端： 通过 inline style 应用消息图片的 maxWidth。(#4446)
• 前端： 恢复 artifact 与侧边面板的可调整大小。(#4469)
• 前端： 允许非 localhost 主机访问 dev-server。(#4471)
• 内容安全： 回填空的内容过滤响应，避免污染会话。(#4394)
• 工具： 从 list_uploaded_files 的 schema 中排除注入的 runtime。(#4376)

性能优化

• 运行时： 为 MemoryRunStore 按 thread_id、MemoryRunEventStore 事件按 run_id 建立索引，避免 O(n) 扫描。(#3562、#3686)
• 子智能体： 通过 seen-id 集合对流式 AI 消息去重（O(n²) -> O(n)）。(#3687)
• 沙箱： LocalSandbox 的路径改写正则与本地路径脱敏模式改为按实例缓存，不再 每次搜索命中都重新编译。(#3648、#3713)
• 消息： 按组为工具调用结果建立索引。(#4411)
• 前端： 流式渲染按帧预算合并，而非逐 chunk 渲染。(#4425)
• 前端： 不再在每个流式 chunk 上重新推导消息内容。(#4441)

安全

• 提示词注入： 新增输入净化中间件防御提示词注入，输入护栏中伪造的框架标签会 被拦截，系统上下文以 SystemMessage 注入以隔离角色。(#3662、#4155、#3661)
• 提示词注入： 对渲染进模型 prompt 的不可信内容进行 HTML 转义——记忆事实与摘 要、SOUL.md、子智能体描述、技能元数据，以及记忆更新 prompt 中的会话块——并中 和 web_capture 工具结果中的提示词注入标签。(#4028、#4119、#4137、#4157 、#4162、#4099、#4060、#4097、#4128)
• 机密： 从技能环境中清除继承来的密钥环境变量（MYSQL_PWD、REDISCLI_AUTH 、缩写形式的 *_PASS 与 Postgres 的 PGPASSFILE）；请求作用域的密钥对斜杠激 活与自主调用的技能都会绑定。(#4018、#4026、#3871、#3938)
• web_fetch： 针对自托管 provider 的 SSRF 防护。(#3942)
• 护栏： 空的 allowlist 现在会拒绝所有工具，而非放行（fail open）。(#4067)
• 鉴权： 全局技能管理接口现在要求管理员权限；旧版 skills 挂载按用户可见性门 控；artifact 遵循受信任的 owner-user-id header；受信任的鉴权主体透传到运行时 。(#3855、#3985、#3982、#4203)
• 认证： 在 access-token 生命周期内持久化 csrf_token cookie。(#3872)
• 存储： 不再在 checkpoint 状态中持久化 base64 图片数据。(#4140)

2.0.0 — 2026-06-15

DeerFlow 2.0 是围绕"超级智能体"框架的彻底重写，核心包含子智能体、持久化记忆、 沙箱执行以及可扩展的技能（Skill）/工具系统。本版本与 1.x 系列没有共享代码， 原有的 Deep Research 框架仍在 main-1.x 分支上维护。

本次发布关闭了 2.0.0 里程碑， 自首个 2.0 里程碑标签以来累计合并 180 个 Pull Request。

⚠ 不兼容变更（Breaking Changes）

• harness： 从 RunStore 重新加载历史 run，并持久化"已中断（interrupted）" 状态。run 的取消 / 多任务调度语义现在要求拥有该 run 的 worker 上具备可用的 RunStore；跨 worker 的取消请求将返回 409，不再静默"伪成功"。(#2932)

新增

智能体与运行时

• 智能体： 自定义智能体支持自我更新，并按用户隔离 —— 智能体可在普通对话中 持久化对自身 SOUL.md / config.yaml 的修改。(#2713)
• 循环检测： 支持配置开关，并可按工具维度覆盖触发频率。(#2586、#2711)
• 循环检测： 警告注入延后执行，避免与工具调用生命周期错位。(#2752)
• 运行： 将 model_name 从 gateway 请求一直透传到运行时与持久化层（SQLite 存储）。(#2775)
• 子智能体： 通过终态任务事件，把子智能体的 token 用量流式上报到 header。 (#2882)
• 记忆： 新增 memory.token_counting 配置，支持在受限网络环境下禁用 tiktoken。(#3465)
• 建议： AI 追问（follow-up）建议改为可选。(#3591)

模型与集成

• 模型： 新增 StepFun 推理模型适配器。(#3461)
• 社区工具： 新增 Brave Search 网络检索工具。(#3528)
• 渠道： Discord 增加"仅响应 mention"模式、话题路由（thread routing）以及 正在输入指示。(#2842)
• IM： 新增"用户自有 IM 渠道连接"——用户可以在运营方配置的 bot 之上，绑定 自己的 Slack / Telegram / Discord / 飞书 / 钉钉 / 微信 / 企业微信 账号。 (#3487)
• 模型： 新增 MiMo 推理内容（reasoning content）的补丁支持。(#3298)
• 模型： 新增 MiniMax provider，用于图像 / 视频 / 播客类技能，并新增"音乐 生成"技能。(#3437)
• 社区工具： 新增 SearXNG 与 Browserless 的网络检索 / 抓取工具。(#3451)
• 社区工具： 为 image_search 新增 Serper Google 图片 provider。(#3575)
• 渠道： Telegram 智能体回复改为就地编辑占位消息的方式流式输出。(#3534)

可观测性

• 追踪： LangGraph 追踪名设置为 lead_agent（自定义智能体则使用其 agent_name），让 Langfuse / LangSmith 中的 trace 更清晰。(#3101)
• 前端： 优化 token 用量的展示模式。(#2329)
• 默认值： 默认开启 token 用量统计。(#2841)
• 默认值： 提高默认的上下文摘要触发阈值。(#3174)
• 追踪： 把子智能体的 span 归属到父线程的 Langfuse trace 上。(#3611)

技能

• 技能： 新增 blocking-io-guard 技能，用于阻塞 IO 排查与运行时锚点。 (#3503)
• 技能： 新增面向维护者的 issue 与 PR 工作流技能。(#3554)
• 技能： 增强维护者编排（orchestrator）的评审工作流。(#3606)

性能优化

• harness： 把 thread 元数据过滤下推到 SQL，不再在 Python 侧后过滤。 (#2865)
• 运行时： 为 run 增加 thread_id 索引，避免 RunManager 中的 O(n) 扫描。 (#3499)
• 运行时： 为 MemoryRunEventStore 中的消息建立索引，避免 O(n) 扫描。 (#3531)
• 持久化： 按类缓存 Base.to_dict 的列反射结果。(#3654)
• 沙箱： 加快 glob/grep 遍历中的 should_ignore_name 判断。(#3657)

安全

• 上传： 拒绝指向符号链接的上传目标。(#2623)
• 上传： 在 Windows 上支持基于符号链接保护的安全上传。(#2794)
• MCP： 在 MCP 配置接口的响应中对敏感字段进行脱敏。(#2667)
• MCP： 加固 MCP 配置接口对异常输入的处理。(#3425)
• 认证： 拒绝跨站点（cross-site）的认证 POST 请求。(#2740)
• 网关： 限制 skill artifact 预览的解压上限，避免被 zip-bomb 类构造滥用。 (#2963)
• 沙箱： 仅在 aio（DooD）沙箱模式下挂载宿主机的 Docker socket。(#3517)
• 沙箱： 默认不再 bind-mount 宿主机的 CLI 认证目录。(#3521)

修复

运行时、网关与持久化

• 运行时： rollback 恢复的 checkpoint 现在能够覆盖更新的 checkpoint。 (#2582)
• 运行时： 持久化 run 的消息摘要。(#2850)
• 运行时： 限制 write_file 执行失败时上报的观测信息长度，避免失败 trace 撑爆上下文。(#3133)
• 运行时： 加锁保护同步单例的初始化与 reset 路径。(#3413)
• 运行时： 为 run events 移除 PostgreSQL 上不必要的聚合 FOR UPDATE。(#2962)
• 运行： gateway 重启后从持久化存储中恢复历史 run。(#2989)
• 网关： threads 接口返回 ISO 8601 格式的时间戳。(#2599)
• 网关： 对已经处于 interrupted 状态的 run，cancel 接口幂等返回。 (#3058)
• 网关： 将 stream_existing_run 拆分为按 HTTP 方法区分的多个路由，确保 OpenAPI operationId 唯一。(#3228)
• 事件： 序列化结构化的 DB event 内容。(#2762)
• 持久化： SQLite 后端的存储统一返回带时区的时间戳。(#3130)
• 持久化： 复用 token 用量按模型分组的 SQL 表达式。(#2910)
• 运行： 忽略已过期的 run reconnect 冲突。(#3284)
• nginx： 把 CORS 策略下放到 gateway 的 allowlist，避免双重应用。 (#2861)
• 持久化： 修复运行时 journal 中 run 生命周期事件的记录。(#3470)
• 网关： 在无状态（stateless）run 接口上强制校验 thread 归属。(#3473)
• 运行时： 通过 SSE values 事件把 interrupt 透传给 LangGraph SDK。(#3605)
• 序列化： 从流式 values 事件中剥离 base64 图片数据。(#3631)
• 历史： 从 REST 接口响应中剥离 base64 图片数据。(#3535)
• 网关： token 用量归因到实际使用的模型。(#3658)

智能体、子智能体与中间件

• 子智能体： 让"子智能体超时"成为原子化的终态。(#2583)
• 子智能体： 工具与中间件按 model 覆盖（model override）来构造。(#2641)
• 子智能体： 把 system_prompt 与 skills 合并到单条 SystemMessage。 (#2701)
• 子智能体： 子智能体与父 run 的 checkpointer 隔离。(#3559)
• 智能体： update_agent 与 setup_agent 一致，遵循 runtime.context 的 user_id。(#2867)
• 智能体： 解决 TodoMiddleware 中 todos 通道的类型冲突。(#3200)
• 智能体： 把自定义智能体路由中的阻塞文件 IO 移出事件循环。(#3457)
• 智能体： 新智能体的 bootstrap 流程保持在用户作用域内。(#2784)
• 循环检测： 注入 warn 时仍保持 tool-call 配对。(#2725)
• 中间件： 同步原始 tool-call 元数据。(#2757)
• 中间件： dangling 配对中间件正确处理非法 tool call。(#2891)
• 中间件： 防止 todo 完成提醒消息泄漏到 IM 渠道。(#2907)
• 中间件： 调用模型前先把 tool result 的相邻关系规范化。(#2939)
• 智能体： resolve_agent_dir 要求存在 config.yaml，从而跳过仅含记忆的 目录。(#3481)
• 智能体： 在 context / configurable 间同步 agent_name，并拒绝空的 soul。(#3553)
• 中间件： 把 UploadsMiddleware 中的上传扫描移出事件循环。(#3311)
• 中间件： 把记忆注入移出事件循环，避免 tiktoken 造成阻塞。(#3411)
• 中间件： 针对非挂载型沙箱，把超限的工具输出外置到沙箱中。(#3417)
• 中间件： 在中间件 state 中保留 sandbox reducer。(#3629)
• 子智能体： general-purpose 的 max_turns 提升到 150，默认超时提升到 30 分钟。(#3610)

记忆与追踪

• 记忆： 用常驻事件循环替换短生命周期的 asyncio.run()。(#2627)
• 记忆： 队列化的 memory 更新按智能体维度隔离。(#2941)
• 记忆： 解析被外层包裹的 memory 更新 JSON 响应。(#3252)
• 追踪： 把 session_id 与 user_id 透传到 Langfuse trace。(#2944)
• 追踪： 修复中文 memory trace 信息显示为 unicode 转义序列的问题。 (#3104)

工具、沙箱与 MCP

• MCP： 修复 MCP 配置中列表型变量的环境变量解析。(#2556)
• 模型： Codex 的 token 用量记录到 usage_metadata。(#2585)
• 沙箱： 在 RemoteSandboxBackend 中补上 list_running。(#2716)
• 沙箱： Windows / Git Bash 下关闭 MSYS 路径转换。(#2766)
• 沙箱： 沙箱就绪轮询不再阻塞事件循环。(#2822)
• 沙箱： Sandbox API 边界统一遵守 /mnt/user-data 契约。(#2881)
• 沙箱： Provisioner 的 PVC 数据按用户隔离。(#2973)
• 沙箱： 合并幂等的沙箱状态更新。(#3518)
• 工具： 引入 Runtime 类型别名，消除 Pydantic 序列化告警。(#2774)
• 工具： 在重入式 get_available_tools 调用之间保留 tool_search 的提升 状态。(#2885)
• harness： 为同步客户端封装仅异步可用的 config 工具。(#2878)
• harness： 同步客户端可用所有原本仅异步的工具（统一封装）。(#2935)
• 工具检索： 通过移除 ContextVar，可靠地隐藏延迟加载的 MCP schema。 (#3342)
• 检索： 修复 DDGS 的维基百科区域处理。(#3423)
• web_fetch： 在受限网络环境下为 Jina reader 支持代理。(#3430)
• 沙箱： 通过 Command 持久化懒加载获取到的沙箱状态。(#3464)
• 沙箱： 修复 AIO 沙箱缓存被陈旧复用的问题。(#3494)
• 沙箱： 在使用全新 id 重试前先创建 shell session。(#3577)
• 沙箱： 不再把字符串字面量路径片段误判为不安全的绝对路径。(#3623)
• 沙箱： read_file 命中二进制文件时返回可操作的提示信息。(#3624)
• MCP： 让 stdio MCP 产出的文件可通过虚拟沙箱路径解析。(#3600)
• MCP： 在设置页的工具列表上展示"需要管理员权限"的状态。(#3533)
• MCP： 新增工具缓存重置接口。(#3602)
• 上传： 修复上传文件大小的接口契约。(#3408)

技能与渠道

• 技能： 强制校验 allowed-tools 元数据。(#2626)
• 技能： 在各聊天渠道下加固 /skill 斜杠激活。(#3466)
• 技能： 修复自定义 skill 安装时的权限问题。(#3241)
• 渠道： Gateway 的命令请求需要鉴权。(#2742)
• 技能： SKILL.md 出现 YAML 错误时，展示出错行号与引号提示。(#3335)
• 技能： 把技能压缩包的安装移出事件循环。(#3505)
• 渠道： 提取回复时忽略隐藏的控制消息。(#3270)
• 渠道： 渠道重启时重新加载配置。(#3514)
• 渠道： 暴露企业微信（WeCom）WebSocket 连接失败的信息。(#3526)
• 渠道： Discord 上传完成后关闭文件句柄。(#3561)
• 渠道： 用户自有 IM 消息要求绑定身份。(#3578)
• 渠道： IM 文件与辅助命令限定在 owner 作用域内。(#3579)
• 渠道： 以运行时的 provider 状态为权威来源。(#3580)
• 渠道： 加固运行时凭证管理接口。(#3581)
• 渠道： 让渠道连接流程可确定（deterministic）。(#3582)
• 渠道： 集中各渠道共享的重试辅助逻辑。(#3583)
• 渠道： 增加运行态的防护约束（operational guardrails）。(#3584)
• 渠道： 按相等性（equality）退订渠道监听器。(#3608)

认证

• 认证： 用缓存响应替换 setup-status 接口的 429 限流。(#2915)
• 认证： 自动生成的 JWT secret 持久化保存，重启后仍可用。(#2933)
• 认证： 对齐"认证禁用（auth-disabled）"模式与 mock 历史加载行为。 (#3471)

前端

• 前端： 在 prod 模式下恢复 getGatewayConfig 的 localhost 兜底。 (#2718)
• 聊天： 修复新会话第一条用户消息被吞掉的问题。(#2731)
• 前端： header 总计 token 数采用后端线程级 token 用量。(#2800)
• 前端： 异步 chat submit 完成后再清空输入框。(#2940)
• 前端： 修复登录页闪烁与 ResizeObserver 死循环。(#2954)
• 前端： 对恢复出的会话消息去重。(#2958)
• 前端： 避免乐观渲染产生重复的用户消息。(#3002)
• 前端： 流式中的 assistant 消息不再展示复制按钮。(#3176)
• 前端： 新建 thread 后立即在侧边栏显示。(#3283)
• 前端： 新建会话的 thread 消息相互隔离。(#3508)
• 前端： 限制深层嵌套列表的缩进，避免渲染崩溃。(#3393、#3570)
• token 用量： token 用量按 message id 去重聚合。(#2770)
• 前端： 剪贴板复制回退到 Streamdown。(#3397)
• 前端： 移除用 Backspace 删除 prompt 附件的快捷键。(#3410)
• 前端： 把记忆设置的工具栏重排为两行。(#3433)
• 建议： 解析追问问题前先剥离内联的 <think> 推理内容。(#3435)
• 前端： 追问建议被禁用时不再发起请求。(#3599)
• 前端： 工作区会话列表在超过 50 个 thread 后分页加载。(#3485)
• 前端： 避免长串不可断行文本导致用户消息气泡溢出。(#3488)
• 前端： SSR 鉴权探测无法连通 gateway 时仍保持工作区可交互。(#3495)
• 前端： 用户消息按纯文本渲染，并限制引用（blockquote）嵌套层级。 (#3502)
• 前端： 删除后重置当前激活的会话。(#3519)
• 前端： 优化移动端工作区布局。(#3646)
• 前端： 多段（multi-part）AI 消息渲染完整内容。(#3649)

构建、部署、脚本与配置

• 打包： 新增 postgres extra 以支持 store / checkpointer，并完善安装 说明。(#2584)
• harness： 运行时路径以项目根目录为基准解析。(#2642)
• Docker： 让 nginx 在每次请求时再解析 upstream 名称。(#2717)
• Docker： 把 Gateway 默认改为单 worker，避免多 worker 模式下出现异常。 (#3475)
• 脚本： make dev 重启时保留 uv extras。(#2767、#2754)
• 脚本： 停止时清理本地 nginx。(#3005)
• 部署： 没有 python3 时，secret 生成回退到 python / openssl。 (#3074)
• 配置： 让 reload boundary 在代码层面可发现。(#3144、#3153)
• replay-e2e： 重放 fixture 按调用方与会话作为 key。(#3453)
• 安装向导： 更新 LLM provider 向导的默认值。(#3421)
• 配置： 把 config.yaml 中为 null 的列表字段归一为空列表。(#3434)
• 脚本： gateway reload 时排除运行时状态目录。(#3426)
• 脚本： 在 uvicorn 的 reload-exclude 生效前先创建 backend/sandbox 目录。 (#3460)
• 脚本： 修复 make start-daemon 之后无法用 make stop 正确停止 next-server 的问题。(#3498)
• Makefile： 修复 per-commit hooks 的安装。(#3569)
• replay-e2e： 重放匹配改为按会话，而非使用当前系统 prompt。(#3436)

变更

• provider（重构）： 各 provider 间共享 assistant payload 的回放匹配逻辑。 (#3307)
• lead-agent（重构）： 把 build_middlewares 改为 public，去掉最后一个跨 模块的私有导入。(#3458)
• todo（重构）： 移除未使用的完成提醒计数器。(#3530)

文档

• 补充 blocking-IO 检测的使用与维护说明。(#3233)
• 清理文档中残留的"独立 LangGraph 服务器"相关内容。(#3301)
• 在 PR 模板与 CONTRIBUTING 中补充 AI 辅助声明。(#3398)
• 补充自定义 AIO 沙箱镜像的文档。(#3548)

内部改进

• 开发： 新增 async / thread 边界检测器。(#2936)
• 运行时： 增加 lifecycle 端到端测试覆盖。(#2946)
• Windows： 后端 Makefile 各 target 加入 PYTHONIOENCODING 与 PYTHONUTF8。(#3069)
• blocking-io： 检测器以"显式失败（fail-loud）"方式解析仓库根目录，并提供 共享 CLI 入口。(#3512)
• 运行时： 为 JsonlRunEventStore 的异步 IO 增加 Blockbuster 运行时锚点。 (#3313)
• CI： 统一 PR / issue 打标签逻辑，修复 reviewing 任务的崩溃与标签抖动。 (#3455)