# 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 仓库根执行）：
   ```bash
   git remote add upstream https://github.com/bytedance/deer-flow.git
   git fetch upstream
   ```
2. **逐条预览某个提交的改动范围**：
   ```bash
   git show <commit_hash> --stat
   git show <commit_hash> -- backend/packages/harness/deerflow/...
   ```
3. **单条回合**（推荐用 `-x` 记录来源；如路径前缀不一致需先确认）：
   ```bash
   git cherry-pick -x <commit_hash>
   # 冲突时：解决后
   git cherry-pick --continue
   ```
   > 注意：上游后端在 `backend/` 子目录，本仓库后端在 `offline-backend-20260512/backend/`。若 cherry-pick 因路径不匹配失败，改用按文件打补丁：
   > ```bash
   > git show <hash> -- backend/<path> | git apply --directory=offline-backend-20260512/backend -p2 -3
   > ```
4. **回合后必跑校验**（在 `offline-backend-20260512/backend/`）：
   ```bash
   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`) 一并更新。