wsk/deerflow-code
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
deerflow-code/frontend-web/docs/上游升级对比与建议.md
gozeros b638b541d0 初始化
2026-09-07 18:24:55 +08:00

8.1 KiB
Raw Permalink Blame History

DeerFlow 上游升级对比与回合建议

对比对象：bytedance/deer-flow（上游，HEAD 9f3be2a @ 2026-05-30）vs 本仓库 fork。 生成日期：2026-05-31。 说明：按用户要求，多语言 (i18n) 与 播客 / TTS (podcast) 不在本次升级范围内，已剔除。

0. 背景与对比结论

项 结论
fork 切出时间 ≈ 2026-05-12（与目录名 offline-backend-20260512 吻合）
上游当前 HEAD 9f3be2a @ 2026-05-30，完整历史 2186 提交
fork 之后上游新增 95 个提交（7 feat / 1 perf / 60 fix / 依赖与文档若干）
后端核心框架 packages/harness/deerflow/ 高度同源、目录结构完全一致，差异主要来自这 95 个提交
前端 技术栈已分道扬镳：上游仍是 Next.js，本仓库已迁到 Vite + React Router，文件几乎全不同

「升级」分两类，本文都覆盖：

  • A 类：fork 之后上游真正新增的（95 提交）——同源、可 cherry-pick，优先回合。
  • B 类：fork 时就裁掉/换了路线、上游一直保留的能力——成本高、按业务取舍。

1. 后端升级（A 类：fork 后上游新增）

1.1 新能力（feat / perf）

日期 升级 提交 说明
05-29 ToolOutputBudgetMiddleware #3303 给超大工具输出做预算保护，防止单个结果撑爆上下文
05-28 MiMo reasoning 支持 #3298 兼容小米 MiMo 模型思维链回传
05-21 链路追踪命名优化 #3101 图名改 lead_agent、用自定义 agent 名作 run_name
05-21 循环检测延迟告警 #2752 警告延迟注入，减少对正常多轮对话的误打断
05-20 Sandbox 下载文件接口 #3038 可把沙箱内产物取回
05-15 Discord 渠道增强 #2842 仅@提及、thread 路由、typing 指示
05-13 子代理 token 用量流式上报 #2882 subagent 消耗实时汇总到 header，利于展示/计费
05-12 perf：线程元数据过滤下推 SQL #2865 线程列表筛选走 SQL，性能提升

能力性增强（fix 前缀实为增强）：MCP 跨调用持久化会话、支持有状态 server（#3089 / #3203）；摘要触发阈值调优（#3174）。

1.2 重要稳定性修复

主题 提交 价值
摘要压缩后保留消息 #3280 数据正确性关键
重启后从持久化恢复 runs / interrupted 状态 #2932(破坏性)、#2989、#3152、#3155 网关重启不丢运行
JWT secret 持久化、多 worker 共享网关 token #2933、#3184 重启/多进程登录态不失效
memory 更新按 agent 隔离 + 包裹 JSON 解析健壮性 #2941、#3252 记忆串号/解析修复
MCP 配置接口脱敏 #2667 防密钥泄露
阻塞 IO 移出事件循环 #3311、#2822（+检测门禁 #3229） 消除事件循环阻塞

1.3 依赖升级

  • Python：langsmith 0.7.36 → 0.8.0、idna 3.13 → 3.15

1.4 怎么做（回合 A 类后端升级）

前提：本仓库 packages/harness/deerflow/ 与上游高度同源，cherry-pick 冲突面小。

  1. 加上游为远程并拉取历史（在后端所在 git 仓库根执行）： 
    git remote add upstream https://github.com/bytedance/deer-flow.git
git fetch upstream
  2. 逐条预览某个提交的改动范围： 
    git show <commit_hash> --stat
git show <commit_hash> -- backend/packages/harness/deerflow/...
  3. 单条回合（推荐用 -x 记录来源；如路径前缀不一致需先确认）： 
    git cherry-pick -x <commit_hash>
# 冲突时：解决后
git cherry-pick --continue

    注意：上游后端在 backend/ 子目录，本仓库后端在 offline-backend-20260512/backend/。若 cherry-pick 因路径不匹配失败，改用按文件打补丁：

    git show <hash> -- backend/<path> | git apply --directory=offline-backend-20260512/backend -p2 -3
  4. 回合后必跑校验（在 offline-backend-20260512/backend/）： 
    make test     # PYTHONPATH=. uv run pytest tests/ -v
make lint
    重点确认 tests/test_harness_boundary.py（harness→app 防火墙）与中间件链顺序未被破坏。
  5. 依赖升级：同步上游 pyproject.toml 对应行后执行 uv lock && make install；离线环境需同步更新 requirements-offline.txt / wheelhouse。

2. 前端升级（B 类：上游有、本仓库缺）

已剔除多语言、播客。下表为关键词核验结果（本仓库 vs 上游命中文件数）。

功能 本仓库 上游 状态
Prose 文本润色 0 8 上游独有
Replay 研究回放 2 29 上游完整，本仓库近乎无
PPT / PPTX 生成 2 14 上游完整，本仓库近乎无
Landing 落地页 0 11 上游独有（营销/介绍页，按需）
静态 demo 模式 无 #3170 fork 后上游新增

前端体验类修复（可参考实现）：流式渲染、消息去重、历史消息 Mermaid 预览、新建会话即时入侧栏。 前端依赖升级：brace-expansion 1.x → 5.0.5（安全）、uuid 10 → 14。

2.1 怎么做（前端能力移植）

前端技术栈已不同（Next.js → Vite + React Router），不能直接 cherry-pick，需按"读上游实现 → 适配到本仓库"的方式重写。

通用步骤：

  1. 在上游 frontend/src/ 定位目标功能的页面/组件/hook 与对应的后端 API 调用。
  2. 后端能力是否具备：Prose / PPT / Replay 依赖后端相应接口，先确认本仓库后端有无对应路由（多为 deep_research/skills 相关），没有则前端无法独立完成，需连带回合后端。
  3. 适配差异点：
    • 路由：上游 app router (src/app/...) → 本仓库 src/pages/ + PageRoutes.tsx / WorkspaceRoutes.tsx。
    • 导航 API：用本仓库 src/shims/（next/link、next/navigation 已 polyfill）。
    • 数据流：沿用本仓库 TanStack Query + @langchain/langgraph-sdk 流式。
  4. 验证：pnpm typecheck + pnpm dev 实测。

3. 推荐升级清单（按优先级）

P0 — 强烈建议（低风险、高价值，A 类）

  • 摘要压缩后保留消息 #3280 —— 数据正确性，直接影响长对话可用性。
  • 重启后恢复 runs / interrupted #2932 #2989 #3152 #3155 —— 生产稳定性核心。
  • JWT secret 持久化 / 多 worker 共享 token #2933 #3184 —— 否则重启或多进程部署会掉登录态。
  • 阻塞 IO 移出事件循环 #3311 #2822 —— 并发吞吐与响应延迟改善。

P1 — 建议（实用增强）

  • ToolOutputBudgetMiddleware #3303 —— 防超大工具输出拖垮上下文，对 agent 稳定性有实际帮助。
  • MCP 持久化会话 / 有状态 server #3089 #3203 —— 若用到有状态 MCP server 则必需。
  • MCP 配置接口脱敏 #2667 —— 安全加固。
  • 子代理 token 用量流式上报 #2882 —— 计费/可观测。
  • 线程元数据过滤下推 SQL #2865（perf） —— 列表性能。

P2 — 按需（看是否用到对应模型/渠道）

  • MiMo reasoning #3298（用小米模型才需要）
  • Discord 渠道增强 #2842（用 Discord 才需要）
  • Sandbox 下载文件接口 #3038、追踪命名 #3101、循环检测延迟告警 #2752

前端（按业务价值）

  • Replay 研究回放 —— 对"深研/写作"类产品体验提升明显，建议优先（需后端配合）。
  • Prose 文本润色 —— 与写作工作台契合，建议评估接入。
  • PPT 生成 —— 若有汇报/导出诉求再做。
  • Landing 落地页 —— 仅当面向外部用户时考虑。

暂不做

  • 多语言 i18n（本次明确排除）
  • 播客 / TTS（本次明确排除）

4. 建议执行节奏

  1. 先做 P0 后端 4 项 + 跑全量测试，单独提交一个"上游稳定性回合"分支。
  2. 再做 P1，逐条 cherry-pick、逐条验证。
  3. 前端 Replay / Prose 立项评估（确认后端依赖），单独排期重写适配。
  4. 依赖升级随回合同步，离线包 (wheelhouse / requirements-offline.txt) 一并更新。