Files
deerflow-code/frontend-web/docs/firefox52-rspack-全功能兼容开发计划.md
T

32 KiB
Raw Blame History

Firefox 52 全功能兼容与 Rspack 高性能构建开发计划

1. 文档信息

项目 内容
目标分支 fix/firefox52-compat
独立工作区 F:\react01\firefox-web
前端目录 F:\react01\firefox-web\frontend-web
目标浏览器 Firefox 52(Windows x64)
技术方向 React 18.3 + Tailwind CSS 3.4 + Rspack 2.x + 内置 SWC
核心目标 尽可能保持现有全部功能,提高冷构建和增量构建速度,保证主要页面与主题样式
当前状态 兼容构建与自动回归已接通:核心交互 20/20、主题布局 12/12、完整路由 118/118,真实普通问答与智能体问答均通过

1.1 2026-10-09 实施进度

已完成:

  • 建立 Firefox 52 专用 Rspack/SWC 单目标构建,开发服务器、快速构建、正式构建和预览命令均已接通;持久化缓存生效。当前机器实测冷生产构建 16.865 秒,首轮后的四次稳态构建中位数 1.584 秒、P95 1.641 秒。
  • 运行时降级到 React 18.3;Tailwind CSS 采用 feat/tailwind-v3-legacy-chrome 已验证方案降级到 3.4,保留现有主题 token 和组件类名。
  • 建立统一兼容入口,补齐 Pointer Events、requestSubmit、scrollIntoView({block:"nearest"})、Blob、UUID、Clipboard、ResizeObserver、Web Streams 等能力。
  • 流式请求使用 XHR onprogress 适配 SSE/NDJSON/Range 等接口;单元测试 4/4 通过。
  • 修复 Firefox 52 下的 SPA 路由白屏、display: contents 根布局失效、侧边栏分隔线颜色、首页宽度 token、欢迎标题透明、常用提示词换行、Radix 菜单无法点击、cmdk 下拉框崩溃和 Enter 无法发送。
  • CSS 兼容样式拆到 src/styles/firefox52/;PostCSS 自动转换 rgb(var(...) / alpha)、:where() 和暗色后代选择器,并为 flex gap 提供回退。
  • MapLibre 固定到 4.7.1,xlsx 解压改用 fflate;对 LangChain/LangGraph/LangSmith、Oniguruma、React Router、Zod 等依赖启用精确转换或源码兼容 loader。
  • 修复 LangGraph 普通 async 方法中 for await 被错误降为同步迭代的问题,并增加 loader 回归测试;修复 XYFlow 12.12 的 BigInt 渲染序号导致流程页面白屏的问题。
  • 增加 check:firefox52-css、check:firefox52-js、核心交互、真实流式、主题布局和 118 条完整路由脚本,用于阻止现代 CSS/JS 语法、路由和页面交互回归。
  • 建立 docs/firefox52-dependency-compatibility.md 和 docs/firefox52-route-compatibility.md,记录版本、补丁原因、验证入口与平台限制。

本阶段验证结果:

验证项 结果
Firefox 52 核心页面与交互冒烟 20/20 通过
Firefox 52 真实普通问答 线程创建、路由跳转、XHR 增量流与最终回复均通过
Firefox 52 真实智能体问答 自动选择可用智能体,线程创建、XHR 增量流与最终回复均通过
主题与布局 6 套主题 × 全量/简洁布局,12/12 通过
Word 导出 后端实际生成非空 DOCX,MIME 与下载文件名通过
完整路由 开发与生产预览均为 118/118;分别点击 71/74 个可见非破坏性 Tabs;强制刷新模式支持按过滤器分批运行
关键交互 设置和更多、换肤、Agent/模型选择、提示词管理、Enter 提交、项目创建、业务链条、定时任务新建、Markdown 编辑器与 Word 下载
正式产物 CSS 检查 通过
正式产物 Acorn ES2017 解析 464/464,通过
Firefox 52 浏览器自身 new Function 解析 464/464,0 错误
正式产物 JS 体积 25.2 MiB(464 个按需 chunk)
Rspack 生产构建 冷构建 16.865 秒;稳态中位数 1.584 秒、P95 1.641 秒

管理员、任务、iframe、公开页、canvas、会商和设置等静态入口已纳入完整路由矩阵。需要特定任务参数、外部系统、业务数据写入、硬件 WebGL 或精确物理分辨率的流程,仍需在对应部署环境补充人工验收,不能用静态入口通过替代。

2. 建设目标

本项目在独立兼容分支中建设 Firefox 52 专用前端构建链。现代浏览器版本继续在主开发目录使用现有 Vite 构建,兼容分支只生成 Firefox 52 单目标产物,不生成现代与旧版两套 bundle。

开发遵循以下目标:

  1. 功能覆盖优先:现有路由和主要业务流程都必须进入兼容验收矩阵,不能以“首页能够打开”作为完成标准。
  2. 构建性能优先:使用 Rspack、SWC、增量编译和持久化缓存,移除 legacy bundle 的二次 Babel/SystemJS 转换。
  3. 样式一致性优先:保留 Tailwind、TDesign、Radix 和自定义主题,系统处理 Firefox 52 不支持的 CSS 语法与布局能力。
  4. 兼容逻辑可维护:浏览器差异集中到构建配置、兼容入口、传输适配器和依赖补丁,不在业务组件中散落版本判断。
  5. 持续跟进主分支:兼容分支能够定期合并 master-zg 的新功能,并通过自动检查发现新增的不兼容依赖和语法。

3. 完成标准

3.1 功能标准

  • Firefox 52 打开登录页、首页和工作区时没有白屏。
  • 首屏与路由切换没有未捕获 JavaScript 异常、语法错误和 chunk 加载错误。
  • 功能矩阵中的 P0、P1 场景全部通过;P2 场景逐项验证并记录结果。
  • 无法由旧浏览器实现的原生能力必须提供等价回退,页面和主流程不能直接不可用。
  • 文件上传、文件下载、流式问答、Markdown、公式、代码块、流程图和 Word 导出必须作为专项验收项。
  • iframe、任务深链、公开分享页面和运行时配置必须保持现有 URL 与接口行为。

3.2 性能标准

先在阶段 0 获取当前 Vite legacy 的基线,后续使用相同机器、相同源码、相同依赖和相同环境重复测试。最终门槛如下:

指标 目标
开发服务器首次可访问时间 不高于基线的 50%,期望不超过 10 秒
修改单个 TSX 后的增量构建 P95 不超过 1.5 秒
修改全局 CSS 后的增量构建 P95 不超过 2 秒
无缓存生产构建 不高于基线的 50%
有缓存生产构建 不高于基线的 30%
连续构建稳定性 连续 10 次无随机失败、无失效 chunk、无内存溢出
产物浏览器检查 不含 Firefox 52 无法解析的模块入口和已知危险语法

绝对时间与相对提升发生冲突时,以“功能正确、样式正确、相对基线明显提升”为判断顺序。未达到性能门槛前不移除旧构建链。

3.3 样式标准

  • 全量模式、简洁模式、嵌入模式均无整体布局塌陷。
  • 浅色、深色、浅蓝、浅绿、冰蓝、浅黄等现有主题逐一验证。
  • 重点分辨率至少覆盖 1366×768、1920×1080、2560×1440。
  • 导航栏、侧边栏、表单、表格、标签页、弹窗、下拉框、Tooltip、抽屉和浮层没有明显错位或遮挡。
  • 页面不得出现因 @layer、现代颜色语法或不支持的选择器导致的整片无样式。
  • 主流程截图与现代浏览器参考图保持结构、间距、颜色和层级一致;字体抗锯齿造成的细微像素差异不作为失败。

4. 当前兼容基线

兼容分支已经存在以下措施,Rspack 迁移必须先等价承接,再进行优化:

  1. @vitejs/plugin-legacy 生成 Firefox 52 的 SystemJS legacy bundle。
  2. Mermaid legacy chunk 额外经过 Babel 转换。
  3. 对 p-queue、GFM autolink、Oniguruma parser、LangSmith XXHash 进行构建期源码补丁。
  4. 入口安装 AbortController、IntersectionObserver、ResizeObserver 和 Web Streams polyfill。
  5. PostCSS 展平 Tailwind @layer。
  6. 自定义颜色回退和 Lightning CSS 目标转换。
  7. 全局样式中已经维护主题对应的 legacy 色值。
  8. index.html 在应用入口前安装 AbortSignal.timeout 回退。

当前方案的主要问题:

  • Vite 开发服务器依赖现代 ESM,Firefox 52 无法直接用于日常开发调试。
  • legacy 构建对最终 chunks 再执行 Babel 和 SystemJS 转换,模块量越大耗时越明显。
  • 依赖源码在构建过程中做字符串替换,缓存命中率、升级稳定性和错误定位都较差。
  • Web Streams polyfill只能补充 JavaScript API,不能自动让 Firefox 52 的 fetch 响应具备网络流式读取能力。
  • CSS 已有回退主要围绕旧版 Chrome 建设,还需要按 Firefox 52 实际渲染能力重新审计。

5. 总体技术方案

5.1 构建链

Firefox 52 专用构建使用以下组件:

  • @rspack/core
  • @rspack/cli
  • @rspack/dev-server
  • builtin:swc-loader
  • Rspack SWC JavaScript minimizer
  • Rspack Lightning CSS minimizer或现有 PostCSS + Lightning CSS 流程
  • HTML 生成插件、资源复制插件和 React Refresh 集成(确认 Firefox 52 可运行后启用)

构建目标分成两层:

  1. Rspack runtime 目标指定 Firefox 52,保证 chunk loader、bootstrap 和 HMR runtime 不输出危险语法。
  2. SWC env.targets 指定 Firefox 52,负责 TS、TSX、JSX 和业务 JavaScript 的语法降级及 core-js 注入。

生产构建仅输出一套 Firefox 52 产物,使用普通 script/JSONP chunk loading,不保留 Vite legacy 的 SystemJS 双阶段处理。

5.2 配置与资源保持

迁移时保持以下外部行为:

  • runtime-config.js 继续在应用 bundle 之前加载。
  • 保持现有 VITE_* 配置键,不要求部署环境一次性改名。
  • @/env、@/*、@vite/*、next/navigation、next/link 等 alias 保持一致。
  • base、静态资源目录、favicon、字体和图片路径保持可配置。
  • Hash 路由、BrowserRouter 深层路由、iframe 嵌入路由和公开页面刷新都能正确加载资源。
  • 开发端口与启动脚本可以通过环境变量覆盖,默认不与主开发工作区冲突。

5.3 构建模式

计划提供以下命令:

命令 用途
npm run dev / pnpm dev 默认启动 Firefox 52 Rspack Dev Server,端口 5174
pnpm dev:firefox52 Rspack Dev Server,供 Firefox 52 直接调试
npm run dev:vite / pnpm dev:vite 仅在现代浏览器调试时启动原 Vite Dev Server
pnpm build:firefox52 Firefox 52 正式单目标构建
pnpm build:firefox52:fast 不压缩、保留调试信息的快速验证构建
pnpm preview:firefox52 使用静态服务器验证正式产物
pnpm check:firefox52 扫描危险语法、资源路径和兼容清单
pnpm benchmark:firefox52 执行冷构建、热构建和增量构建基准
pnpm smoke:firefox52 运行 Firefox 52 核心页面与交互冒烟
pnpm smoke:firefox52:live 运行真实普通问答流式冒烟
pnpm smoke:firefox52:agent-live 选择当前可用智能体并运行真实流式冒烟
pnpm smoke:firefox52:themes 验证 6 套主题 × 2 种布局
pnpm smoke:firefox52:full 验证 118 个路由及可见非破坏性 Tabs

类型检查继续单独运行 pnpm typecheck,不阻塞开发构建的模块转换。

6. JavaScript 与浏览器 API 兼容方案

6.1 兼容入口

建立唯一的 Firefox 52 兼容入口,并保证它早于 React、路由、请求客户端和业务模块执行。兼容入口统一处理:

  • Promise、Map、Set、Symbol、迭代器及必要的 core-js 能力。
  • AbortController、AbortSignal.timeout 和 abort reason 差异。
  • ResizeObserver、IntersectionObserver、matchMedia 监听接口。
  • ReadableStream、WritableStream、TransformStream。
  • queueMicrotask、globalThis、Object.fromEntries、Promise.finally 等运行时能力。
  • crypto.randomUUID、Clipboard、下载、全屏等能力的回退实现。
  • requestIdleCallback、structuredClone 等组件可能间接使用的 API。

所有 polyfill 必须具备能力检测,只在缺失时安装,避免重复覆盖浏览器实现。

6.2 流式请求专项

流式问答是兼容工作的 P0 项。Firefox 52 的网络层不能依赖现代 fetch().body.getReader(),需建立统一传输适配器:

  1. 现代浏览器继续使用现有 fetch/SSE/NDJSON 路径。
  2. Firefox 52 使用 XHR onprogress 增量读取 responseText。
  3. 适配器统一处理 SSE、NDJSON、取消、超时、断线、服务端错误和 UTF-8 分片。
  4. LangGraph、普通问答、智能体问答、AI 写作、深度研究、会商、技能地址扫描等流式接口全部复用同一兼容层。
  5. 增加分片边界测试,覆盖半个 JSON、半个 UTF-8 字符、连续空行、最后一行无换行和中途取消。

6.3 不可直接转换的语法

以下内容不能只依赖 SWC 或 core-js,必须通过升级、降级、替代或固定补丁解决:

  • BigInt 字面量及 BigInt 专用算法。
  • 正则向后断言、Unicode property escapes 和不支持的正则 flag。
  • Module Worker 和依赖原生 ESM 的 Worker。
  • 运行时拼接后才生成的现代语法。
  • 强依赖新浏览器 Web API 的第三方组件。

处理顺序:优先选择兼容版本,其次维护专用 fork,再使用 patch-package 或安装后补丁。构建期间的逐文件字符串替换只作为临时迁移手段。

6.4 产物静态扫描

check:firefox52 至少扫描:

  • 未被打包的 import、export、import.meta。
  • BigInt 字面量和 BigInt64Array/BigUint64Array 直接依赖。
  • 正则向后断言、Unicode property escapes、dotAll 等危险正则。
  • 未处理的 async generator、module worker 和 module script。
  • 绝对开发机路径、丢失的 chunk、错误 public path。
  • HTML 中会被 Firefox 52 忽略且没有回退的入口脚本。

扫描结果必须支持白名单,白名单需要注明依赖、原因、验证方式和负责人,不能静默忽略。

7. 第三方依赖治理

7.1 依赖分级

建立 docs/firefox52-dependency-compatibility.md,按以下类别维护:

等级 含义 处理方式
A 原生兼容或经 SWC 即可兼容 正常打包
B 缺少 API polyfill 加入统一兼容入口
C 包含可转换的新语法 加入 SWC 依赖 allowlist
D 包含不可转换语法或新 API 固定版本、fork、patch 或替换
E Firefox 52 平台能力无法完整支持 提供业务等价回退并记录差异

7.2 首批专项依赖

优先审计以下依赖:

  • React 19、React DOM、React Router。
  • LangGraph SDK、LangChain、AI SDK、LangSmith。
  • Mermaid、Shiki、react-syntax-highlighter、Oniguruma。
  • CodeMirror、Tiptap/ProseMirror、KaTeX、Marked、react-markdown。
  • MapLibre GL、Leaflet、XYFlow、OGL、GSAP、Motion。
  • Radix UI、TDesign React、cmdk、Embla。
  • TanStack Query、Axios、Zod、date-fns、uuid。
  • docx、file-saver 和文件预览相关模块。

重型模块保持路由级或组件级动态加载。Rspack 必须把动态 import 转为 Firefox 52 可用的普通 chunk loader。

8. CSS 与视觉一致性方案

8.1 CSS 构建顺序

CSS 建议按以下顺序处理:

  1. Tailwind 4 生成样式。
  2. 展平 @layer,防止 Firefox 52 忽略整组规则。
  3. 生成颜色和透明度回退。
  4. 处理嵌套、逻辑属性、选择器和可安全转换的现代语法。
  5. Lightning CSS 按 Firefox 52 目标转换。
  6. 生产模式压缩,开发模式保持未压缩和快速 source map。

需重点验证当前 rgb(var(--legacy-*-rgb) / alpha) 在 Firefox 52 中的实际表现;若浏览器不接受空格分隔和斜杠透明度语法,应在构建期生成逗号分隔的 rgba() 或直接颜色值。

8.2 手写兼容 CSS 与文件拆分

构建工具无法可靠转换,或者转换后仍存在布局和交互差异的样式,直接编写 Firefox 52 专用 CSS。兼容样式不得继续集中追加到 globals.css,统一放在独立目录中按职责拆分:

src/styles/firefox52/
├── index.css                 # 只负责按固定顺序汇总核心兼容样式
├── tokens.css                # 颜色、透明度、阴影和主题变量回退
├── base.css                  # 浏览器基础差异和通用元素修正
├── layout.css                # 页面框架、侧边栏、滚动区和响应式布局
├── overlays.css              # Dialog、Popover、Select、Tooltip、Guide 等浮层
├── markdown.css              # Markdown、代码块、公式、表格和引用
├── editors.css               # CodeMirror、Tiptap、ProseMirror 等编辑器
├── visualizations.css        # Mermaid、XYFlow、图表、地图和 Canvas 容器
├── chat.css                  # 普通问答、智能体问答和消息时间线
├── writing-research.css      # AI 写作、深度研究和公文工作台
├── roundtable.css            # 会商、流程图和报告协作
├── task-workspaces.css       # 任务深链、目的树和快捷跳转栏
└── admin.css                 # 管理端表格、表单和配置页

拆分规则:

  1. 全局首屏必需的 tokens/base/layout/overlays 由 index.css 统一引入。
  2. Markdown、编辑器、可视化、会商、任务工作区和管理端样式随对应路由或组件导入,让 Rspack 生成独立 CSS chunk,避免所有用户加载完整兼容样式。
  3. 单个兼容 CSS 文件建议控制在 500 行或未压缩 30 KB 以内;超过任一门槛时继续按组件或业务域拆分。
  4. HTML 根节点由兼容入口设置稳定标记,例如 data-browser-compat="firefox52"。兼容规则应挂在该标记下,防止影响现代浏览器和公共组件的默认样式。
  5. 优先复用语义 token 和现有组件 class,不复制整份第三方组件样式。只覆盖 Firefox 52 实际不兼容的声明。
  6. !important 只用于第三方组件无法通过正常层叠覆盖的场景,并在规则旁注明原样式来源和原因。
  7. 文件加载顺序必须固定:主题 token → 基础样式 → 布局 → 通用浮层 → 业务页面。禁止依赖偶然的 chunk 到达顺序解决优先级。
  8. 每个文件明确对应验收页面,删除页面或修复上游兼容性时同步清理失效规则。

如果某个功能仅需要少量兼容规则,样式文件放在功能模块旁并使用 .firefox52.css 后缀;跨页面共用的兼容规则才放入 src/styles/firefox52/。构建检查需要统计各文件行数、体积、重复选择器和 !important 数量,超过门槛时提示拆分。

8.3 CSS 风险清单

建立自动扫描和人工验证清单,覆盖:

  • color-mix()、OKLCH、现代 rgb()/hsl()。
  • @layer、CSS nesting、container query。
  • :has()、:focus-visible、复杂 :is()/:where()。
  • Flexbox gap、Grid 差异和 subgrid。
  • aspect-ratio、inset、min()、max()、clamp()。
  • dvh/svh/lvh、逻辑方向属性。
  • backdrop-filter、mask、混合模式和复杂滤镜。
  • sticky、滚动容器、overscroll 和自定义滚动条。
  • Portal 浮层、z-index、transform containing block 和 pointer-events。

无法可靠转换的布局功能通过兼容 utility 或组件级基础样式回退解决,不能只隐藏出错区域。

8.4 视觉回归范围

每种主题至少截取以下代表页面:

  1. 登录页和新对话落地页。
  2. 普通问答流式消息页。
  3. 智能体列表、创建页和智能体聊天页。
  4. AI 写作工作台。
  5. 多智能体会商三步工作台和流程图。
  6. 知识库列表、编辑器和知识图谱。
  7. 任务管理、目的树弹窗和快捷跳转栏。
  8. 管理端表格、Tabs、表单和确认弹窗。
  9. iframe 嵌入页和公开分享页。
  10. 站点预览、地图、图表和全屏场景。

视觉验收重点比较布局边界、间距、颜色、滚动区域、遮罩和弹层位置。截图自动化优先使用与 Firefox 52 匹配的 Selenium/geckodriver;无法稳定自动化的页面纳入人工截图清单。

9. 全功能验收矩阵

9.1 P0:必须首先打通

功能域 核心场景
登录与鉴权 密码登录、URL 参数登录、退出、刷新恢复、鉴权失效
页面框架 全量/简洁模式、侧边栏、菜单、主题、路由刷新
普通问答 新建会话、历史会话、流式回答、停止、重试、错误显示
消息展示 Markdown、GFM、代码高亮、公式、链接、引用、流程图
文件 上传、附件卡片、产物预览、下载、Word 导出
智能体问答 智能体列表、进入聊天、新建和历史会话
iframe embed=1、hideJump=1、主题、独立鉴权、postMessage
错误恢复 断网、接口 401/403/500、chunk 加载失败、刷新恢复

9.2 P1:主要业务能力

功能域 核心场景
智能体管理 创建、编辑、模型、知识空间、SOUL、技能、保存、引导
舆情分析智能体 外部流式接口、会话、错误信息
AI 写作 经典版、对话版、阶段推进、干预、资料、Markdown 与 Word 下载
深度研究/公文 发起任务、过程状态、恢复、结果展示和下载
多智能体会商 普通、规划、8BF、岗位会商、链条配置、后台续跑
报告协作 会话列表、协作过程、结果编辑和导出
知识空间 列表、详情、上传、Markdown 编辑、Wiki、图谱、检索调试
Notebook 列表、详情、资料和生成流程
定时任务 任务列表、创建、运行详情、公开运行页
任务深链 rwfx、3qfx、xdfx、agentfx、单智能体、会商、行动分区
任务报告 生成、文件卡片、入库确认、宿主通知
轻应用 应用列表、窗口打开、iframe 宿主、动态菜单

9.3 P2:管理、配置和扩展能力

  • 用户、活动、记忆、模型、模型交换与并发配置。
  • 智能体、技能、技能上下线、技能地址扫描/预览/替换/回滚。
  • 菜单、简洁菜单、按钮、标签、固定问题、推荐问题、提示词前缀。
  • 敏感词、排行榜、插件、岗位和岗位角色。
  • 业务链、发布广场、私有广场、技能压缩、LLM 指标和 checkpoint 迁移。
  • 公开分享、排行榜、会商报告、会商看板和定时任务全屏页面。
  • Web App/Site Studio、地图、流程图、图表和沙箱 HTML 预览。
  • 微信样式入口、无界嵌入和其他特殊页面壳。

9.4 单项验收规则

每个功能项必须记录:

  • 入口 URL、角色和前置数据。
  • 页面是否正常加载及首个可交互时间。
  • 主操作、保存/提交、返回和刷新恢复结果。
  • 是否涉及流式、上传、下载、Worker、Canvas、SVG、WebGL 或 iframe。
  • Firefox 52 控制台错误和网络失败。
  • 样式截图、已知差异和回退行为。
  • 验收人、日期、构建 commit 和结果。

路由清单应由路由源码自动提取后与人工场景表合并,新增路由若未进入矩阵则 CI 提示失败。

10. 开发阶段

阶段 0:基线和可观测性

工作项:

  • 固定 Node、pnpm、Firefox 52、Rspack/SWC 候选版本和测试机器信息。
  • 记录 Vite legacy 的冷构建、热构建、增量构建、内存峰值和产物体积。
  • 保存当前主要页面在现代浏览器和 Firefox 52 的截图、控制台错误及网络日志。
  • 自动提取路由清单和动态 import 清单。
  • 输出依赖语法扫描报告和浏览器 API 使用清单。
  • 建立可重复执行的 benchmark 脚本,结果保存为 JSON 和 Markdown。

退出条件:任何人都能按文档复现当前构建时间和 Firefox 52 白屏/错误现状。

阶段 1:Rspack 并行构建骨架

工作项:

  • 增加 Rspack 配置、HTML、静态资源、alias、环境变量和 public path。
  • 接入内置 SWC,先处理项目源码,再逐步扩展到依赖 allowlist。
  • 接入 React、CSS、字体、SVG、图片和动态 import。
  • 建立 dev:firefox52、build:firefox52:fast 和 preview 命令。
  • 暂时保留 Vite legacy 命令作为对照和回退。

退出条件:Firefox 52 能通过 Rspack dev server 打开登录页和空工作区,没有语法错误与 chunk 加载错误。

阶段 2:运行时与流式链路

工作项:

  • 重整统一兼容入口和 polyfill 顺序。
  • 完成 XHR 流式适配器并接入核心请求路径。
  • 验证取消、超时、错误解析、鉴权头和跨域行为。
  • 处理 Web Worker、WebSocket、EventSource 和动态 chunk 加载。
  • 完成普通问答端到端测试。

退出条件:普通问答可以连续完成发送、流式接收、停止、重试和刷新恢复。

阶段 3:依赖清理和固定补丁

工作项:

  • 对首批专项依赖分级。
  • 把现有 Vite 字符串补丁迁移为版本固定、fork、alias 或安装后补丁。
  • 对 Mermaid、Shiki、Oniguruma、LangSmith、p-queue 等建立单独验收用例。
  • 配置最终产物危险语法扫描。
  • 为新增依赖增加 CI 扫描。

退出条件:生产产物通过静态扫描,补丁均有版本校验,依赖升级导致补丁失效时构建直接失败并给出清晰错误。

阶段 4:CSS 和组件样式兼容

工作项:

  • 把现有 PostCSS/Tailwind/Lightning CSS 流程接入 Rspack。
  • 建立 src/styles/firefox52/,按主题、布局、浮层和业务域拆分手写兼容 CSS,避免继续扩大 globals.css。
  • 配置核心兼容 CSS 与路由级兼容 CSS 的分包策略,并增加单文件行数、体积和重复规则检查。
  • 修复主题颜色、透明度、cascade layer、flex gap 和现代选择器问题。
  • 验证 TDesign、Radix、Tailwind 组件和 Portal 浮层。
  • 建立 CSS 危险语法扫描与代表页面截图回归。
  • 验证各主题和三种目标分辨率。

退出条件:P0 页面和代表组件没有布局塌陷、透明色失效、弹层错位或滚动锁死。

阶段 5:全功能逐批清零

按以下批次执行,每批都完成“功能、控制台、网络、样式、刷新恢复”五项检查:

  1. 登录、框架、普通问答和文件。
  2. 智能体管理与智能体问答。
  3. AI 写作、深度研究、公文。
  4. 多智能体会商、业务链和报告协作。
  5. 知识空间、Notebook、Markdown 编辑器和图谱。
  6. 任务深链、任务报告、轻应用和 iframe。
  7. 定时任务、管理端和设置页。
  8. 公开页面、Site Studio、地图、图表和其他扩展能力。

退出条件:P0、P1 全部通过,P2 完成验证;所有遗留项都有可执行的修复或等价回退方案。

阶段 6:构建性能专项优化

工作项:

  • 开启并调优 Rspack 持久化缓存和增量构建。
  • 开发模式关闭压缩,使用低成本 source map。
  • 生产模式使用 SWC minimizer,CSS 使用 Lightning CSS minimizer。
  • 缩小 SWC 转换范围,对不兼容依赖使用精确 allowlist。
  • 对 Mermaid、Shiki、MapLibre、编辑器、会商等重型模块做路由级拆分。
  • 检查重复依赖、barrel export、无效 locale 和大资源。
  • 评估 lazy compilation;仅在不破坏 Firefox 52 chunk 加载时启用。
  • 将耗时阶段输出到构建 profile,逐项消除长任务。

退出条件:达到第 3.2 节性能门槛,同时功能和样式回归无新增失败。

阶段 7:持续集成和离线部署衔接

工作项:

  • CI 执行 typecheck、Rspack 构建、危险语法扫描、核心单测和冒烟测试。
  • 保存构建时间趋势,超过阈值时提示回归。
  • 固定包版本和校验值,保证离线环境可重复安装。
  • 离线依赖与发布资产交由 knowledge-base-bj/deerflow-offline-deployment 仓库维护,本业务仓库只保留源码和依赖清单。
  • 更新启动脚本、部署文档、缓存策略和静态资源响应头。

退出条件:干净环境可以离线安装、构建、启动并通过 Firefox 52 冒烟测试。

阶段 8:切换与旧链路清理

工作项:

  • 完成最终功能矩阵、视觉报告和性能报告评审。
  • 将 Firefox 52 开发和构建命令切换到 Rspack。
  • 删除已经被固定补丁替代的 Vite legacy 临时代码。
  • 保留一段时间的 Vite 基准脚本,确认稳定后再彻底清理兼容分支中的旧依赖。

退出条件:连续多个提交未出现功能、样式和性能回归,Rspack 成为兼容分支唯一正式构建链。

11. 性能测试方法

每组测试至少执行 5 次,取中位数并记录 P95:

  1. 冷启动:删除构建缓存后启动开发服务器,测量到首页可请求时间。
  2. 热启动:保留缓存重启开发服务器。
  3. TSX 增量:修改一个叶子组件和一个高层布局组件。
  4. CSS 增量:修改组件样式和全局主题样式。
  5. 冷生产构建:删除 Rspack 缓存和 dist。
  6. 热生产构建:保留缓存、源码不变再次构建。
  7. 单文件生产变更:修改一个组件后重新构建。

记录字段:commit、构建模式、CPU、内存、磁盘、Node/pnpm 版本、总耗时、各阶段耗时、峰值内存、模块数量、chunk 数量、JS/CSS 体积和缓存命中率。

性能比较必须在相同机器和相同后台负载下进行。正式报告同时保留原始日志,避免只记录一次最佳结果。

12. 主分支同步策略

兼容分支需要持续接收正常业务开发,采用以下约束:

  • 构建和兼容代码集中在独立目录与入口,减少对业务组件的侵入。
  • 能通过适配器解决的问题不直接修改业务协议。
  • 定期从 master-zg 合并新功能,每次合并后自动更新路由和依赖扫描结果。
  • 新增路由必须进入功能矩阵;新增依赖必须进入依赖兼容清单。
  • 新增流式接口必须使用统一传输层,不能绕过 Firefox 52 XHR 回退。
  • 新增主题和全局组件必须进入样式截图集。
  • 冲突解决优先保留主分支业务逻辑,再在兼容层补充旧浏览器处理。

13. 风险与处理原则

风险 处理原则
第三方依赖停止支持旧浏览器 固定版本或维护兼容 fork
fetch 流式响应不可用 XHR onprogress 统一回退
Map/WebGL 能力差异 降级依赖或提供保持业务信息的二维/静态回退
编辑器、语法高亮和 Worker 依赖现代能力 classic worker、主线程回退或兼容版本
CSS 转换后仍存在布局差异 兼容 utility、组件基础样式和截图回归
Polyfill 体积过大 单目标按需注入,重型功能路由级加载
兼容补丁随依赖升级失效 精确版本校验,失败时终止构建
Rspack 插件兼容不足 优先使用内置能力,必要时编写小型 loader/plugin
主分支持续新增功能 自动路由、依赖、API 和 CSS 扫描
旧浏览器自动化不稳定 自动冒烟与人工矩阵结合,保留截图和日志证据

14. 交付物

实施完成后应包含:

  • Rspack 开发、快速构建和生产构建配置。
  • Firefox 52 统一 polyfill 入口和流式传输适配器。
  • 第三方依赖兼容清单及固定补丁。
  • CSS 兼容流水线、扫描脚本和视觉基准图。
  • 按职责拆分的 Firefox 52 手写兼容 CSS,以及对应的体积和重复规则检查。
  • 路由级功能验收矩阵。
  • 自动冒烟、危险语法扫描和构建性能脚本。
  • 基线报告、最终性能对比报告和已知差异说明。
  • 开发运行、离线构建、部署和故障排查文档。

15. 最终验收清单

  • Firefox 52 开发服务器可直接打开并调试。
  • 登录、导航、主题、路由刷新无白屏。
  • 普通问答和智能体问答可以稳定流式输出。
  • 上传、下载、Markdown、公式、代码、流程图和 Word 导出通过。
  • AI 写作、研究、会商、知识库、任务深链等 P1 功能全部通过。
  • 管理端、设置、公开页和扩展能力完成 P2 验证。
  • 所有现有主题和目标分辨率完成视觉回归。
  • 产物通过危险语法和资源路径扫描。
  • 冷构建、热构建和增量构建达到性能门槛(冷/热生产构建已记录,增量构建仍需单独量化)。
  • 连续构建与长时间运行无 chunk 丢失和内存异常。
  • 新增功能与依赖具备持续兼容检查。
  • 离线环境可以重复安装、构建和部署。