DeerFlow 版本演进深度解读：从 2.0「超级智能体」重写走向 2.1.0 里程碑（更新日志全解析）

DeerFlow 的中文更新日志（CHANGELOG_zh.md）完整记录了项目从 2.0.0 彻底重写以来所有重要变更，是了解这个开源 long-horizon SuperAgent harness 技术路线、配置迁移与升级风险的第一手资料。本文将围绕这份更新日志展开，梳理其版本治理约定、2.0 里程碑的能力基线，并对「未发布」章节中累积的 2.1.0 工作（不兼容变更、新增能力、修复与安全加固）逐项给出迁移指引与仓库源码佐证，帮助部署方评估升级影响、顺利完成配置迁移。

更新日志的治理约定：读懂这份文档的「语法」

DeerFlow 的更新日志遵循 Keep a Changelog 与语义化版本规范 的惯例：每个变更条目按 新增 / 变更 / 修复 / 性能优化 / 安全 / 文档 / 内部改进 分类，并以 ([#PR号]) 形式保留到具体 Pull Request 的可追溯引用。仓库同时维护 CHANGELOG.md（英文）与 CHANGELOG_zh.md（中文）两个语言版本。

当前文档包含两大版本块：

• [未发布]：累积面向 2.1.0 里程碑的所有工作，结构上先集中声明一批不兼容变更（Breaking Changes），再罗列新增、变更、修复等条目；
• [2.0.0] — 2026-06-15：DeerFlow 2.0 正式发布，围绕"超级智能体"框架的彻底重写。

阅读时需要注意：日志条目描述的是行为与配置语义，而仓库内 config.example.yaml 与源码实现才是这些语义的落地形态。下文会把日志中的每类关键变更与源码一一对应。

2.0.0 发布：围绕超级智能体框架的彻底重写

更新日志开门见山地指出，2.0 版本与 1.x 系列没有共享代码——DeerFlow 从"Deep Research"框架转变为集子智能体、持久化记忆、沙箱执行与可扩展技能/工具系统于一体的 super agent harness（仓库 backend/packages/harness 即为其核心实现）。原有 1.x 深研框架仍保留维护（不再赘述其远端位置）。该里程碑自首个 2.0 标签以来累计合并 180 个 Pull Request。

核心能力基线（2.0 新增）

智能体与运行时：

• 自定义智能体支持自我更新，且更新按用户隔离——智能体可在普通对话中把对自身 SOUL.md / config.yaml 的修改持久化（对应源码目录 backend/packages/harness/deerflow/agents 下的 agent 装配与管理逻辑）；
• **循环检测（loop detection）**支持配置开关并可按工具维度覆盖触发频率，警告注入延后执行，避免与工具调用生命周期错位；
• model_name 从 gateway 请求透传到运行时与持久化层；
• 子智能体的 token 用量通过终态任务事件流式上报到 header；
• 记忆新增 memory.token_counting 配置，可在受限网络环境下禁用 tiktoken（改为字符计数）；
• AI 追问（follow-up）建议改为可选。

模型与集成：

• 新增 StepFun 推理模型适配器、Brave Search 检索、SearXNG 与 Browserless 网络检索/抓取工具，并为 image_search 提供 Serper Google 图片 provider；
• 新增 MiMo 推理内容补丁支持与 MiniMax provider（图像/视频/播客类技能、音乐生成技能）；
• IM 渠道方面新增 "用户自有 IM 渠道连接"——用户可在运营方配置的 bot 之上绑定自己的 Slack / Telegram / Discord / 飞书 / 钉钉 / 微信 / 企业微信账号（对应 backend/app/channels 中大量 *_channel.py 连接器）；Discord 增加"仅响应 mention"模式与话题路由；Telegram 回复改为就地编辑占位消息流式输出。

可观测性：LangGraph trace 名设为 lead_agent（自定义智能体则用其 agent_name），子智能体 span 归属到父线程的 Langfuse trace；默认开启 token 用量统计并优化展示；提高默认上下文摘要触发阈值。

技能：新增面向排查的 blocking-io-guard 技能，以及面向维护者的 issue/PR 工作流技能。

性能优化：thread 元数据过滤下推到 SQL；为 run、消息与事件 store 增加索引消除 O(n) 扫描；按类缓存 Base.to_dict 列反射；加速 glob/grep 遍历中的 should_ignore_name。

安全：拒绝指向符号链接的上传目标（含 Windows 安全支持）；MCP 配置接口响应字段脱敏并加固异常输入；拒绝跨站点认证 POST；限制 skill artifact 解压上限防 zip-bomb；仅在 aio（DooD）模式下挂载宿主机 Docker socket；默认不再 bind-mount 宿主机 CLI 认证目录。

2.0 的修复条目体量巨大，覆盖运行时/网关/持久化（如 run 恢复、interrupted 状态幂等取消、ISO 8601 时间戳、SSE 透传 interrupt、剥离 base64 图片数据、token 用量归因到实际模型）、智能体/子智能体/中间件（如子智能体原子化超时、父 run checkpoint 隔离、general-purpose max_turns 提升到 150、默认超时提升到 30 分钟）、记忆与追踪、工具/沙箱/MCP（如 MCP 列表型变量环境变量解析、沙箱 /mnt/user-data 契约、工具检索 ContextVar 修复）以及技能与渠道——这些为后续 2.1 的能力地基打下了基础。

未发布（面向 2.1.0）：不兼容变更全解析

「未发布」章节是当前升级最需要关注的部分。以下逐条给出变更内容、影响面与升级动作，并用 config.example.yaml 及源码佐证。

网关：Trace id 无条件签发

Gateway 现在无条件为每个工作单元签发 trace id，且每个 Gateway HTTP 响应都携带 X-Trace-Id header（无论配置如何，无法关闭）。此前二者受 logging.enhance.enabled 控制；现在该配置仅控制日志输出（日志记录是否含 trace_id 字段及其格式）。使用默认 enabled: false 安装升级后也会开始收到该 header。定时任务、MCP 任务通知 run、IM 渠道消息与内嵌 DeerFlowClient 都会绑定 id。

关键影响：run 请求的 metadata 或 config.context 中提供的 deerflow_trace_id 现在会被忽略并覆盖，以保证响应 header、日志与持久化 run 记录一致；如需跨服务固定关联 id，应发送 X-Trace-Id 请求 header。logging 配置重启后生效。本次未新增或移除任何配置键。仓库侧佐证：该语义沉淀在 app_config.py 的 logging.enhance 配置说明（"Trace ids are always issued and always returned in the X-Trace-Id response header; this controls log output only"），并在 AGENTS.md 中明确了"重启生效"的重载边界。

技能与沙箱路径体系调整（升级高发区）

围绕技能挂载路径、沙箱容量与包边界，本次有四处相互关联的变更：

1. /mnt/skills 保留给"仅启用项"的托管投影视图：DEER_FLOW_HOST_SKILLS_PATH 与 SKILLS_HOST_PATH 不再使用；Docker/AIO 与 hostPath 部署改为从 DEER_FLOW_HOST_BASE_DIR 推导投影路径。指向 /mnt/skills 或其子路径的 E2B operator 挂载会被跳过并告警（避免遮蔽托管投影），额外内容请挂载到其他容器路径。用户投影会从磁盘重读全局启用状态，使技能启停切换在下一次获取沙箱时跨 Gateway worker 生效。既有 E2B 沙箱在重建前仍保留创建时快照；PVC 模式暂不提供已禁用技能的文件系统隔离。（[#4178]）
2. SKILL.md 目录成为运行时包边界：包内嵌套的 SKILL.md 文件被视为支撑数据，不再注册为独立技能；特殊目录结构需把可独立加载的技能移到不带自身 SKILL.md 的命名空间目录下。（[#4098]）
3. 激活态限制型技能委派需显式声明 task：处于激活态的限制型技能若要委派给子智能体，必须在 allowed-tools 中显式声明 task。只读发现设施（tool_search 与 describe_skill）不受影响，但无法为被禁用的业务工具授予 schema 可见性或执行权限。
4. 安全加固：投影技能文件改为复制而非 hardlink，沙箱写入不能再修改规范来源；遇到漂移的投影命名空间时所有平台（含 Windows）都会 fail closed；Custom Agent 技能 allowlist 在 sandbox 文件系统层强制（带 shell 或文件工具的 Custom Agent 无法读取策略排除的技能）。

E2B 沙箱容量语义与渠道能力变化

• E2B 强制 sandbox.replicas 作为进程级容量上限：默认 wait 策略等待 acquire_timeout 后令当前智能体回合失败（DeerFlow 不自动重试）；可用 burst + burst_limit 允许有限超额度多开 VM；reject 策略可在返回容量错误前先回收一个预热 VM。（[#4391]）
• 入站 webhook 去重迁移到 Postgres：多个 Gateway Pod 可同时服务同一 IM 渠道而不重复处理事件（此前依赖进程内去重）；对应的应用层实现见 backend/app/channels/dedupe_store.py。
• 钉钉入站消息支持文件与图片附件（[#4423]），并新增 Buzz (Nostr) 渠道连接器。

记忆系统架构级重构（升级动作最多的一类）

这是 2.1 最核心的架构变更，分多条实施：

1. 记忆系统可插拔：由 memory.manager_class 选择后端，默认 deermem 自包含后端。DeerMem 私有配置从 memory: 顶层移入 memory.backend_config。仓库侧佐证：config.example.yaml 中 memory: 顶层仅保留共享字段（enabled、injection_enabled、shutdown_flush_timeout_seconds、manager_class、backend_config），其中 manager_class 可选择 deermem/mem0/noop/openviking 已注册名或 dotted 路径；实际后端实现位于 backend/packages/harness/deerflow/agents/memory/backends 下的 deermem/、mem0/、noop/、openviking/、honcho/ 子目录。
2. /memory/config 与 client.get_memory_config() 响应结构变化：不再返回扁平 DeerMem 字段，改为 {enabled, mode, injection_enabled, manager_class, backend_config}，其中 backend_config 为当前后端自行解释的不透明 dict。记忆数据响应不变（/memory、/memory/status 的 data）；读取旧扁平字段的外部 API/SDK 客户端需改为读取 backend_config。（[#4122]）
3. memory.storage_class 迁移：旧默认路径 deerflow.agents.memory.storage.FileMemoryStorage 已不存在，现为 deerflow.agents.memory.backends.deermem.deermem.core.storage.FileMemoryStorage；自定义 MemoryStorage 子类的 __init__ 必须接受 config 参数（此前无参）。损坏或过期的 storage_class 会记录错误并回退到 FileMemoryStorage（不崩溃）。参见 backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py。
4. storage_path 语义由"文件路径"改为"根目录"：无论绝对或相对值现在都是根目录，按用户的记忆存放在 {storage_path}/users/{uid}/memory.json。若沿用旧的相对默认 storage_path: memory.json，会导致记忆孤立或保存时触发 NotADirectoryError——因此迁移会带告警丢弃以 .json 结尾的文件式 storage_path 值，且当 storage_path 解析到已存在文件时工厂抛出异常。自定义根目录应把 memory.backend_config.storage_path 设为目录。config.example.yaml 中该字段注释明确：空值由工厂注入绝对 runtime_home，非空值必须是根目录。
5. 顶层 DeerMem 字段自动迁移：抽象化之前位于顶层的 memory.* DeerMem 字段（storage_path、max_facts、debounce_seconds、model_name、token_counting、staleness_*、consolidation_* 等）在加载时带告警自动迁移到 backend_config（model_name → backend_config.model.model）。把它们显式移入 memory.backend_config 即可消除告警。（[#4122]）
6. 新增 memory.mode（middleware | tool）：tool 模式注册供模型直接调用的记忆工具（memory_search/add/update/delete），取代被动的逐回合摘要；manager_class 解析改为快速失败（未知后端抛 ValueError，而非静默回退）。（[#4023]）
7. mode: tool + 未实现 search() 的后端启动即失败：由 MemoryManager 的不变量校验在 Gateway 启动时抛 ValueError（此前是每次 memory_search 静默返回空）。两个内置后端都实现了 search()（DeerMem 检索、noop 返回 []）；只影响自定义后端。修复：切到 mode: middleware，或覆盖 search() 并设置 supports_search=True。（[#4324]）

配置与部署语义微调

• database.checkpoint_delta_snapshot_frequency 重命名并改默认值：迁移为 database.checkpoint_delta.snapshot_frequency，默认值从 1000 改为 10。旧顶层字段仍会告警后映射到新字段，显式新字段优先。依赖旧默认值的 delta 模式部署快照频率会提高 100 倍；想保留原节奏需显式设为 1000。（[#4516]）仓库侧佐证：DeltaChannel 快照节奏贯穿 agents/factory.py（checkpoint_snapshot_frequency: DeltaChannel snapshot cadence for "delta" mode）与 config.example.yaml 的 checkpoint_channel_mode: full（delta 用 DeltaChannel）配置块。
• Docker 入口端口默认只绑定回环地址（127.0.0.1）：两份 compose 文件发布端口不再默认暴露到所有网卡；需要跨网卡暴露必须设置 BIND_HOST。（[#4618]）

新增能力全景（面向 2.1.0）

认证与授权：从 PAT 到完整 RBAC

• **个人访问令牌（PAT）**用于程序化 API 访问：POST/GET/DELETE /api/v1/auth/pats 管理令牌（仅展示一次，以 SHA-256 摘要存储）；默认拒绝的路由策略只允许会话/run 生命周期路由，并进一步受令牌 threads/runs scope 限制；具备取消能力的请求维度（?action=、multitask_strategy）还额外要求 runs:cancel。（[#5041]）实现见 backend/app/gateway/auth/pat.py（含 is_pat_allowed_route、generate_pat_token、pat_token_digest）与 routers/auth.py 的 /pats 端点。
• 通用 OIDC / SSO 认证（支持 Keycloak）；"保持登录"选项配合统一会话 cookie 策略（HTTPS 下持久化 Secure cookie，公网 HTTP 下会话 cookie）；部署方可关闭本地自注册，将新账号限制为仅通过 SSO/OIDC 开通。
• 内置 RBAC 鉴权 provider 与统一工厂：工具鉴权在装配期（模型可见前移除工具）与运行期（拒绝被禁用调用）双重强制执行；Gateway 路由权限改由已配置的 AuthorizationProvider 推导；模型权限在 Gateway 路由与智能体运行时双重执行，获取沙箱时额外校验 sandbox:execute。

智能体、运行时与子智能体

• TokenBudgetMiddleware 强制单个 run 的 token 预算，在主智能体与子智能体间累加共享（[#3412]）。实现： token_budget_middleware.py，配置节见 config.example.yaml 的 token_budget: 与 agents: 下的 per-agent 覆盖。
• 结构化工具结果元数据 + 工具进度状态机，让运行时对多步工具流拥有一等可见性（对应 middlewares 目录下的 tool_result_meta.py、tool_progress_middleware.py、tool_receipt.py 等）。
• 上下文持久化：每个 run 记录生效的记忆身份，摘要过程中持久化系统消息/记忆/工具状态，compaction 不再丢信息。
• 目标延续（goal continuation）：run 可跨多个智能体回合朝目标继续执行并跟踪 continuation_count（源码 runtime/goal.py 区域，Evaluator 模型判断可见对话证据后返回 typed blocker）。
• 委派账本（delegation ledger）防重复委派 + 总委派上限约束单 run 扇出（backend/packages/harness/deerflow/agents/middlewares/delegation_ledger.py）；会话内持久化并展示子智能体步骤历史。
• 文件工具引入确定性"写前读"版本门控（read_before_write_middleware.py），避免覆盖并发编辑。
• 双模式 checkpoint 存储（基于 LangGraph DeltaChannel）把长调研/编码 run 的会话存储从 O(N²) 降至近线性（[#4292]）；Delta 模式历史缓存（内存/Redis）支持 O(1) 增量合成，通过 database.checkpoint_cache 配置（[#4638]）。
• 声明式主智能体中间件配置（[#3964]）、按智能体模型与生成设置覆盖（temperature/max_tokens/thinking_enabled/reasoning_effort，[#4347]）、scheduler.recursion_limit 控制定时 run 的 LangGraph super-step 上限（默认 1000，受 max_recursion_limit 限制，config.example.yaml）。
• 工具回执（tool receipt）与可验证委派：每次工具调用携带运行时签发、防篡改的回执，默认由新的 verification 配置节启用；子智能体报告必须引用回执并附可验证 handle，主智能体交叉核对执行记录，task 委派的 acceptance_criteria 在父侧确定性检查，无法判定项报告 UNVERIFIED 而非静默通过。（[#4659]、[#5076]、[#5090]、[#5109]）
• 人工输入卡片支持结构化表单字段（[#4406]）；内置子智能体接收当前日期上下文锚点（[#4797]）；设置页新增部署级子智能体目录 + 显式 worker allowlist（[#4887]）。
• 并发容量统一控制 + 批量子智能体：统一进程级容量控制器；可选 batch_task 工具把大量独立项目作为 SQL 持久、可恢复的批次执行（支持租约、有限重试、暂停/恢复/取消，聊天中展示进度）。（[#4998]）实现：batch_task_tool.py。

记忆能力深化

记忆合并（consolidation）通过 LLM 为每条事实分配 expected_valid_days 并做过期审查剪除静默过期事实（config.example.yaml 中 staleness_* 系列参数给出默认值）；保证纠正事实注入并优雅降级；精简可插拔 MemoryManager 接口；增量式按智能体作用域的 Markdown 事实存储（单条更新无需重建索引）；消息处理新增会话水位、无意义回合过滤与持久化队列；内置 FTS5/BM25 检索适配器免外部服务全文搜索；新增 OpenViking、mem0（HTTP）与 Honcho 后端；混合事实淘汰策略（[#4789]）并有可复现评测位于 backend/scripts/benchmark/deermem_eviction/。OpenViking 后端改用官方适配器，旧 trusted-mode 的 auth_mode/account 字段会被拒绝，改用绑定凭据的 USER API key（[#4707]）。

技能系统

原生 SkillScan（阶段一）静态分析技能包；describe_skill 延迟发现（模型按需取 schema）；按用户的自定义技能隔离配合沙箱挂载；技能列表选中后重开便于连续附加；"技能"设置页可直接安装本地 .skill archive 并复用按用户 installer 与安全扫描。

模型与社区工具集成

新增网络检索/抓取引擎 GroundRoute、Crawl4AI（web_fetch）与 fastCRW provider，Browserless web_capture 截图、Brave image_search；智能体化浏览器控制（Playwright 会话可观察/接管）成为会话一等能力；Lark/飞书 CLI 打包运行时安装与交互授权；新增 Serply（news/scholar 垂直搜索）与腾讯云 WSA，并为 DDGS、Brave、Tavily、SearXNG 提供统一原生时间范围过滤；可选只读 RAGFlow 检索暴露 knowledge_search(query) 工具并带 dataset ID allowlist；支持 MiniMax Code (mcode acp) 原生外部编码智能体；新增 Z.AI GLM-5.3-Flash profile（thinking 常开）；"设置 > 集成"按用户切换 Lark/飞书凭据，切换后撤销旧 OAuth token。

MCP：从工具到持久任务运行时

• 持久任务运行时：长时工具任务通过持久 driver 跨 Gateway 重启继续，进度/完成通知在聊天 UI 展示（backend/app/mcp_tasks）；共享 MCP server 按用户注入凭据、未映射用户默认拒绝、凭据脱敏；按 server 的 tool_name_prefix、tool_call_timeout（含 session_init_timeout 默认 60 秒）与路由提示；"设置 > 工具"通过定向 Gateway endpoint 增删改 MCP server；共享 HTTP/SSE server 支持 headers_from_context 把请求作用域 secret 映射为 header（config.context.secrets 提供值、配置只存键名、缺失默认拒绝）。

扩展系统（out-of-tree Python 扩展）

新增可贡献中间件、任务生命周期与系统模型 observer、Gateway 服务与 HTTP 路由的扩展系统，用 deerflow extensions 命令管理。deerflow-extension-api 升至 0.2.0，0.1 扩展启动时会被拒绝。仓库实现位于 backend/packages/harness/deerflow/extensions（loader、manager、registry、stack、gateway、injection 等模块），API 版本号在 backend/packages/extension-api/deerflow_extension_api/init.py 中声明为 API_VERSION = "0.2.0"。

渠道、前端与可观测性

• 渠道：channel_user_id 以 DEERFLOW_CHANNEL_USER_ID 暴露给沙箱命令；同会话密集消息排队 + 话题卡片预览保持；Buzz (Nostr) 连接器；DingTalk 附件支持。
• 前端：会话分支与追问侧边对话；重新生成最新回答；引用证据面板、工作区变更评审、可视化澄清卡片；语音输入、思考时长标签；上下文窗口使用量实时显示；artifact 内联编辑与 zip 打包下载；长会话大纲侧边菜单；分支会话 Title (2) 编号与树形会话列表；Browser Live。
• 可观测性：trace-id 关联 + Monocle 智能体可观测性；类 Hermes 终端工作台（deerflow CLI，基于 DeerFlowClient）+ 脱敏 support-bundle；安装向导询问 thinking 支持并新增火山引擎 Coding Plan 快速安装路径；TUI 支持 clear 与透明终端背景。

变更（Changes）要点

• 前端性能持续优化：公共根页面与本地化文档静态化、流式状态增量推导、虚拟化超长列表、代表性路由 JS/CSS 预算；Browser Live 帧改 JPEG 二进制协商；文本 artifact 支持 HTTP byte-range 流式读取（Web UI 初始预览限 1 MiB）。
• Helm chart 默认把沙箱 Service 设为 ClusterIP（升级会从 NodePort 切换；需外部可达时设置 provisioner.sandboxServiceType: NodePort）。
• 声明式分层中间件构建器；ThreadData 先于 Uploads 运行；AGENTS.md 成为智能体指引权威来源。
• 子智能体委派改按净收益路由：除非并行延迟、专长能力或上下文隔离明显有益，否则主智能体默认直接执行（[#4384]）；run-event journal 前创建的会话首 run 前回填 seed event。
• 记忆 OpenViking 后端（见上）；Gateway run-event journal、checkpoint 历史回填等数据一致性改进。

修复、性能优化与安全（选读中的高频项）

修复类覆盖了运行时一致性（多 worker 归属、孤儿 run 租约接管、SQLite event-store 序列化）、模型子类（api_base 在全部 BaseChatOpenAI 子类生效、stream_chunk_timeout 默认值统一）、子智能体（继承循环检测与摘要中间件、回合预算 MAX_TURNS_REACHED、压缩前注入持久上下文）、中间件 token 预算锁、沙箱路径/输出脱敏/反向外置目录语义、MCP server 故障隔离与缓存失效、渠道（入站去重 key 按聊天作用域、飞书批量与限流）、记忆空值边界与队列刷写、前端渲染与流式抖动等大量细节。

性能优化：MemoryRunStore/MemoryRunEventStore 建立索引；子智能体流式消息按 seen-id 去重（O(n²)→O(n)）；LocalSandbox 路径正则按实例缓存；read_file 只读请求行范围；Browser Live JPEG 编码；view_image 通过 wrap_model_call 注入避免 base64 双写 checkpoint；终态 run 后限制 Gateway 内存。

安全：输入净化中间件与伪造框架标签拦截；对渲染进模型 prompt 的不可信内容 HTML 转义（记忆/SOUL.md/子智能体描述/技能元数据）并中和 web_capture 注入标签；清除技能环境继承的密钥变量（MYSQL_PWD、REDISCLI_AUTH、*_PASS、PGPASSFILE）；web_fetch SSRF 防护；护栏空 allowlist 改为拒绝全部工具；MCP 来源工具结果经与内置网络工具相同信任边界净化；本地 Docker sandbox container 默认绑定 Docker bridge gateway、默认 seccomp profile、丢弃全部 capability、no-new-privileges 与有界资源（可用 DEER_FLOW_SANDBOX_BIND_HOST=0.0.0.0 / DEER_FLOW_SANDBOX_SECCOMP_UNCONFINED=1 恢复旧行为）；支持 bundle 中 secret-shaped key 脱敏；GET stream join 上的取消/回滚 action 返回 405；复用持久化 sandbox 前重新检查授权策略。

文档与内部改进

文档侧聚焦生产 Docker 下 LocalSandboxProvider 解析 sandbox.mounts[].host_path、Crawl4AI >= 0.9 bearer token、GitHub 去重 TTL、Honcho 记忆后端专门指南。内部改进包括：前端测试迁移 rstest、live client 测试显式 opt-in、blocking-IO 检测器跟踪 self/cls 属性链、checkpoint channel-mode 基准（对比 full/delta 的延迟/存储/回放，见 backend/scripts/benchmark）、混合 memory eviction 评测、五个远程 sandbox provider 共享 identity 推导与 acquire serialization（RFC #4741），以及若干依赖升级。

升级建议速览

1. 先读不兼容变更：升级前对照上文逐条检查——若自定义了记忆相关配置，务必把 DeerMem 字段迁入 memory.backend_config、把 storage_path 改为目录、更新 storage_class 为 ...deermem.core.storage.FileMemoryStorage 并让子类 __init__ 接受 config；
2. 注意 X-Trace-Id：升级后所有 HTTP 响应都会带该 header，logging.enhance.enabled 只控制日志输出，跨服务关联请改用 X-Trace-Id 请求 header；
3. 沙箱/技能路径：检查是否有指向 /mnt/skills 的 E2B 挂载、是否使用 DEER_FLOW_HOST_SKILLS_PATH 等废弃变量、SKILL.md 目录结构是否符合包边界约定；
4. 数据库配置：若依赖 database.checkpoint_delta_snapshot_frequency 或旧默认快照节奏（1000），请显式设置 database.checkpoint_delta.snapshot_frequency: 1000；
5. 网络绑定：依赖外部访问 compose 端口的部署需设置 BIND_HOST；
6. 完整可参考配置统一维护在 config.example.yaml，文档与设计说明见 backend/docs 与根目录 README_zh.md。