10 个关键问题 Q&A

1. Q：2.2.0 最大变化是什么？ A：定位升级，从实验框架转为面向生产环境的 Super-Agent 平台。
2. Q：旧版本配置可以直接复用吗？ A：不行，存在破坏性变更，接口、存储、配置字段不兼容。
3. Q：多实例能力解决什么问题？ A：支持多个 Agent 并行运行，会话资源互相隔离，互不干扰。
4. Q：知识库 RAG 部分有哪些增强？ A：优化检索链路，支持自定义插件接入，拓展知识调用方式。
5. Q：安全层面新增了哪些能力？ A：权限管控、调用操作审计、输入输出内容安全过滤。
6. Q：所有项目都建议立刻升级吗？ A：不是，简单原型测试项目可暂缓，有协同、审计需求优先升级。
7. Q：升级前必须做哪些准备？ A：备份数据，对照清单核对原有配置，梳理依赖接口。
8. Q：模型渠道这块有什么改进？ A：兼容更多大模型后端，支持模型路由调度，灵活切换底座。
9. Q：工作流新特性适合什么场景？ A：长流程业务，需要分支判断、失败自动重试的复杂任务。
10. Q：上线推荐怎么降低风险？ A：采用灰度发布，先小流量验证接口、知识库、权限策略

定位：把 2.1 的 Super-Agent Harness 升级为可规模化生产部署的 Agent 平台，核心方向：多实例高可用、目标驱动工作流、可信任委托、生产级安全加固；自 2.1.0 合计合并 1068 个 PR，里程碑 3 正式关闭。
仓库：bytedance/deer-flow，发布者 WillemJiang

一、破坏性变更（Breaking Changes｜升级重点风险清单）

这是升级最需要优先处理的部分，很多配置不调整会直接启动失败：

1. 本地开发默认仅监听回环地址：make dev/make start 不再监听 0.0.0.0，2026/8001/3000、/setup 不暴露局域网 / VPN；如需外网暴露，在 .env 设置 BIND_HOST=0.0.0.0，非法 IP 格式直接拒绝。
2. 凭证静态加密（必配）：新增环境变量 DEER_FLOW_CREDENTIALS_KEY（Fernet 密钥，逗号分隔支持密钥轮换），IM 机器人凭证、MCP OAuth 刷新令牌加密落盘；多实例部署缺少该变量直接拒绝启动。原有明文 channels/runtime-config.json 自动迁移入库 channel_runtime_configs；降级版本需要重新录入机器人配置。
3. 多进程 Gateway 依赖 Redis Stream：GATEWAY_WORKERS>1 / deployment.multi_instance:true / WEB_CONCURRENCY 开启时，必须启用 Redis stream bridge；非 GitHub 类 IM 渠道必须开启 channels.leader_lease 选主租约。
4. 调度器接口返回结构变更：/api/scheduled-tasks* 错误体改为 {"detail":{"code","message","params"}}；新增单用户最大并发调度上限 scheduler.max_concurrent_runs_per_user 默认 = 2；DST 夏令时跳变时间会返回 422 拒绝。
5. 会话删除级联清理：删除 thread 时同步删除 run、事件、反馈；旧 thread id 重建无法读取历史数据。
6. 模型对话历史默认追加只读：自动裁剪旧工具输出 elide_superseded_writes 改为可选开关 tool_output.elide_superseded_writes=false（默认关闭）；skill allowed-tools 仅做兼容元数据，不再拦截工具。
7. 中间件工具纳入权限校验：plan 模式 write_todos、扩展中间件工具统一走一层鉴权；原有 tools 策略没有包含它们的部署会绑定失败。
8. 默认 fail-closed 安全策略收紧：网页抓取后端（Browserless/Crawl4AI/Firecrawl/fastCRW）默认禁止回环 / 内网；SSRF 防护拦截 CGNAT 100.64.0.0/10；IM 白名单解析失败时拒绝所有人而不是放行；外部 system/developer 消息直接 400 拒绝。
9. 上传与路径校验强限制：Windows 保留设备名（COM、CONIN$ 等）禁止上传 / 沙箱写入；同名文件自动追加 _N 后缀，不再截断覆盖；转换后的 md 文件禁止覆盖已有文件。
10. 指令菜单精简：/ 下拉只保留内置 /goal / /compact；技能改用 @ 内联引用。
11. API 入参校验严格化：非法 run 请求直接返回 422/400 而不是 500；SQLite file: URI、YAML 布尔值写入整型配置等直接拒绝。

二、亮点（Highlights｜产品能力跃迁）

1. 定时任务升级：目标驱动工作流（重点特性）

普通定时任务 →带目标、终止条件、安全上限的归属式工作流

• 聊天内可创建管理归属自己的调度，Web 聊天有任务卡片，页面 / REST / 聊天入口能力对齐
• 公平排队：按用户限流（max_concurrent_runs_per_user），逐个用户消费队列，防止单用户打满资源
• 任务可检索、Agent 停止 / 暂停 / 目标不达标会自然语言说明 + 跳转对应运行记录
• 通知本地化、幂等，同事件只推送一次

2. 多实例就绪：Gateway 集群高可用（生产部署核心）

• IM 渠道基于租约 + 纪元（fencing epoch）做选主，多 Gateway 实例负载、自动故障转移
• Helm /compose 完整支持多副本：共享 JWT 密钥、滚动更新（surge-then-drain）、PodDisruptionBudget
• Provisioner 副本保证沙箱创建不因为单实例重启中断
• Workflow 扩展依靠 Postgres ExecutionFence 跨网关协同、可认证断点恢复
• 本地一键集群：make dev-multi 启动双 Gateway 集群

3. 扩展平台成熟：Full-Stack Plugin 体系

• 统一插件命名空间：可注册前端页面、对话动作、模型工具；带版本 manifest、ESModule 依赖图
• 插件支持 @ 引用提供者，插件可走 Gateway 准入直接发起完整 Agent Run
• Agent-Teams：自定义 Agent 通过 @组队协作，共享活动流、持久团队状态
• 可选 Script 工作流扩展：QuickJS 沙箱子进程编排分支、串行 Agent 任务（默认关闭）
• 扩展 API 升级 0.2.2 → 0.2.7，配套 Capability Center 插件市场

4. 知识库检索：Provider 无关、可核验引用

• RAGFlow、LightRAG 解耦，通过扩展 API 注册，统一检索返回、证据、引用格式
• 引用（citation）在预算裁剪、子 Agent 委托、回放场景下保留，RAGFlow 支持带原文片段的可校验内联引用
• 单消息独立检索白名单，fail-closed；新增 WeKnora、knowledge-platform 扩展，支持分层逻辑空间、角色继承权限

5. 模型管理平台化

• 管理员后台统一模型管理（Settings→Models）：加密目录、乐观版本控制、厂商预设
• 标准化推理能力契约（thinking/dialect/effort），统一主 Agent、子 Agent 思考策略，前端支持推理强度选择
• 模型别名体系：单模型最多 16 个别名，任务 / 会话 / 子 Agent 可单独覆盖选择
• 新增接入：Kimi K3.1、Opper、API Route、You.com、Webz News、Unbrowse、兼容 EXA 接口

6. IM 渠道运营级能力（国内 IM 友好）

• QQ：腾讯开放平台 WebSocket，无需公网回调地址
• 微信：WebUI 扫码绑定
• 飞书 / 企微 / QQ 统一主动通知：任务完成、失败、人工确认通知，持久消息发件箱保证可靠推送
• 飞书交互式按钮卡片；IM 会话内 /model 即时切换模型；/connect 绑定改为持久弹窗 + 复制绑定码
• Gateway 重启后任务可续跑 on_disconnect:continue，消息幂等防重复投递

7. Memory、Workspace、可观测、权限体系增强

• Memory：独立存储 cognitiveStyle 协作偏好；CJK bigram 词法召回排序；TypeSafe 预筛、抽取水印防重复抽取
• Workspace：@支持引用技能、项目文档、其他会话（单条最多 16 个）；工具输出稳定 artifact 短 ID art_xxx；自定义 Agent 包导入导出；项目文档搜索 + 文档货架 LLM 摘要
• 可观测：run 终止事件闭环；每一次 LLM 调用埋点（提供商、模型、token、停止原因）；子 Agent 批量结果评审、CSV/JSON 校验验收标准
• 持久层：可选 sha256 内容寻址 Blob 存储，多 Gateway 共享工具产物，规避本地文件路径失效
• RBAC：自定义角色、账号冻结管理；可选 PII 脱敏、TypeSafe 风险网关拦截高危工具调用

三、性能优化（Performance）

• 上下文压缩缓存：相同渲染 prompt 直接复用摘要，减少 LLM 调用
• 沙箱预热预加载：和首波模型响应并行，加速异步子 Agent
• MCP 服务缓存：服务配置不变不再重新发现，仅指纹变更时重连
• 大量搜索工具（You.com/Tavily/Firecrawl等）改造为协程，不阻塞事件循环
• Gateway 冷导入、目录扫描、大导出分页、SSE 流式代理缓冲、图片回传大小上限、文档转换异步化等批量优化

四、安全加固（重点，Fail-Closed 为核心思想）

1. SSRF 全链路防护：web 搜索、图片搜索、浏览器、MCP 统一 URL 策略；Agent 浏览器走会话级 SOCKS5 代理 + DNS 策略拦截 DNS 重绑定
2. 权限补齐：大量仅鉴权无权限校验的路由补充细粒度权限（threads:write /sandbox:execute /model:use 等）
3. 凭证防泄漏：SkillScan 识别 sk、GitHub PAT、Google Key，IM 通知、MCP 日志、500 报错详情脱敏
4. SkillScan 语法结构检测（不是关键词匹配）：fork 炸弹、curl sudo、二进制魔数检测、AST 解析密钥规则，减少误报；限制正则防止 ReDoS、超大文件防 OOM
5. 配置默认关闭风险项、SVG 标记为活跃内容、链接协议白名单

五、Bug 修复（Notable fixes）

覆盖 Run 流、沙箱、IM 渠道、模型适配、MCP、调度器、前端、Memory、Skills、Goal 评估、CLI/TUI、扩展事务；重点是断连恢复、流回放间隙、并发竞态、时区 / DST 调度、多 Worker 写覆盖、各种模型厂商特殊返回结构兼容。

六、部署 & 运维（Deploy & ops）

• Docker：nginx 固定版本规避 seccomp 问题；env_file 可选；SIGTERM 优雅退出；文档上传独立 100MB 流式限制
• K8s Helm：多副本、PVC 复用、provisioner 配置、数据库密钥优先级封装、PDB
• 健康检查 /health/ready：Redis stream 不可达返回 503
• 升级迁移脚本：包含加密凭证、线程绑定、调度停止条件、租约、用户隔离等数据迁移；提供 make config-upgrade / make doctor
• CI：独立 skill 回归测试分片、uv.lock 版本校验、开发环境 env 解析防命令注入

七、升级决策建议

✅ 适合升级场景：

• 准备上生产、做多实例集群、需要飞书 / 企微 / QQ 稳定机器人
• 依赖定时 Agent 任务、多子 Agent 组队、RAG 知识库、MCP 工具生态
• 有合规 / 安全要求：凭证加密、SSRF 防护、细粒度权限、审计溯源

⚠️ 升级前置动作：

1. 提前配置 DEER_FLOW_CREDENTIALS_KEY（Fernet 密钥）
2. 存量多 Worker 部署确认 Redis Stream 可用
3. 核对 IM 白名单配置，解析格式错误会直接拒绝所有人
4. 调度相关 API 调用方适配新的错误返回结构
5. 备份数据库，本次包含大量 schema 迁移