TrueGrowth/docs/STARTUP_AND_TOOLBAR_LESSONS.md

启动拆包与工具栏状态经验总结

更新日期：2026-04-21

这轮最值得记住的规律

1. 启动进度只能有一个“百分比真源”

这轮 loading 卡顿感的根因，不是进度条本身，而是进度来源混杂：

• HTML 启动壳自己在写阶段百分比
• 主线程初始化阶段也在写百分比
• Service Worker 又在回传资源进度

结果就是进度条会“跳”“卡”“倒像是更慢了”。

更稳的做法是：

• SW 未就绪前，只做短时间平滑模拟，让用户知道系统在工作
• SW 一旦开始回传进度，就由 SW 接管后半段百分比
• 其余阶段只更新文案，不再写数值

一句话：文案可以多源，百分比只能单源。

2. 懒加载要区分“触发器”和“内容体”

这轮多个两击问题，本质都和这个边界有关：

• 可以延后的是抽屉内容、弹窗内容、工具窗口内容
• 不该延后的是用户第一下要点到的按钮、触发器、壳层容器

如果把触发器本身也放进懒加载链路，第一次点击就可能只完成“挂载按钮/挂载容器”，第二次点击才真正打开内容，用户会直接感知成 bug。

推荐原则：

• 按钮、抽屉骨架、输入框外壳常驻
• 重内容、重依赖、低频模块按需挂载
• 首次点击允许局部 loading，但不允许“点击无响应”

3. 依赖编辑器上下文的组件，不能被随意挪出树外

这轮 AI 图片生成 报 useBoard must be used inside <Plait>，本质是把依赖 Plait 上下文的对话框，移到了错误的挂载层级。

经验是：

• 凡是依赖 useBoard()、useDrawnix()、选择态、画布上下文的组件
• 在做延迟加载、拆层、抽离壳层时
• 先确认它依赖的 Provider / Board Context 还在不在上游

尤其是：

• 对话框懒加载
• 抽屉懒加载
• “核心画布壳层 / 延后功能层”拆分

如果组件依赖的是“当前画布实例”，那它的懒加载位置必须仍在画布上下文树内。

4. setState(updater) 里不要顺手改别的面板状态

左侧“项目 / 工具箱 / 任务面板”要点两下的问题，根因不是点击事件丢了，而是 toggle 逻辑写成了：

• 在 setState(prev => ...) 的 updater 里
• 顺手调用 closeAllDrawers()
• 于是一次点击里混进了多份状态更新

这种写法在互斥面板场景里很容易让首击状态被冲掉。

更稳的方式是显式顺序化：

1. 先判断目标当前是否已打开
2. 如果要打开，先关闭其它互斥面板
3. 最后再打开目标面板

一句话：updater 里只算当前值，不做跨状态副作用。

5. 左侧常驻工具栏的顺序，不能跟“最近激活顺序”绑定

这轮另一类体验问题是：左侧常驻工具点一下就换位。

根因不是图标组件，也不是 selected 高亮，而是工具栏数据源按 activationOrder 排序：

• 工具一打开 / 一恢复，激活顺序就刷新
• 工具栏再按这个顺序重排
• 用户看到的就是“按钮自己跑了”

对常驻工具栏来说，用户心智更接近“固定栏位”，不是“最近使用列表”。

所以更合理的规则是：

• pinned 工具始终保持既有栏位顺序
• 打开后只替换本栏位的状态
• 非 pinned 的临时实例再单独排到后面

一句话：常驻栏看重空间记忆，不看重最近激活。

6. 版本更新后的懒加载 chunk 失效，要有“一次性自恢复”

这次 DrawnixDeferredRuntime 的报错：

• Failed to fetch dynamically imported module

本质不是业务逻辑错误，而是用户页面停留在旧版本，部署后旧 HTML / 旧运行时还在引用已经失效的 hash chunk。

这类问题的特点是：

• 用户刷新前一切正常
• 一旦触发某个 React.lazy() 模块才爆
• 报错看起来像功能坏了，实际是版本切换窗口里的静态资源失配

更稳的处理方式不是把所有懒加载都改成手写 loader，而是补一层轻量兜底：

• 在 ErrorBoundary 里识别动态导入 / chunk 失效错误
• 按“当前版本 + 当前模块”做一次性重试标记，避免死循环
• 自动刷新一次，并带时间戳参数绕过旧缓存
• 应用成功启动后再清理恢复参数，避免 URL 污染

一句话：发布后 chunk 失效不是“要不要刷新”的问题，而是“要不要帮用户只刷新一次并避免循环”的问题。

这轮适合沉淀成默认规则的做法

• 启动进度：前半段可模拟，后半段由资源进度单源接管
• 懒加载：只懒内容，不懒触发器
• 组件拆层：先确认上下文依赖，再移动挂载位置
• 互斥面板：显式开关，不在 updater 内联副作用
• 常驻工具栏：固定顺序优先于最近激活
• 版本切换：懒加载 chunk 失效时自动恢复一次，但必须有防循环保护

后续开发检查清单

• 这个 loading 百分比现在到底是谁在写？
• 这个入口第一次点击，是打开内容，还是只完成挂载？
• 这个懒加载组件是否依赖画布 / Provider 上下文？
• 如果新版本刚发布，这个懒加载失败是不是“旧页面引用失效 chunk”而不是业务异常？
• 这个 toggle 是否在 updater 里偷偷改了别的 state？
• 这个工具栏是“固定栏位”还是“最近使用列表”？排序规则是否和用户心智一致？

一句话总结

这轮真正值钱的经验不是“把 bug 修掉了”，而是明确了 6 条边界：

• 百分比单源
• 触发器常驻
• 上下文不丢
• toggle 不串副作用
• 常驻栏位不乱跳
• 失效 chunk 只自恢复一次

---

2026-05-17：首屏壳层拆分与 chunk 守门经验

现象

• 首屏慢不只来自代码体积，也可能来自运行时静态环和 chunk 归属错误。
• 这轮真正卡住构建的，不是业务组件本身，而是 ai-chat 和 tool-windows 之间被常量文件、服务入口、懒加载边一起拉成了静态回边。
• 纯工具函数如果和会反向依赖 data/image 的运行时模块放在同一个文件里，循环会在源码层先炸，然后再在 chunk 层放大。

架构变更

• apps/web/src/main.tsx 只保留最早期恢复与 bootstrap 入口，后续应用初始化下沉到 bootstrap.tsx。
• Drawnix 拆成首屏壳层和延后功能层，任务恢复、自动插入、字体/视频恢复等副作用交给 idle 启动器。
• 动态导入失败恢复独立到 lazy-asset-recovery.ts，避免首屏入口顺手背上重恢复逻辑。
• 图片自然尺寸这类轻量能力单独下沉到纯工具模块，utils/image.ts 只保留导出和编辑逻辑。
• tool-ids.ts 这类纯常量不能被目录级 tool-windows 规则误收编，否则很容易把轻量调用侧拖回重 chunk。
• 构建后校验不再只看入口 HTML，还要看入口静态依赖链、chunk SCC 和首屏 500KB 预算。

经验

• 先修运行时循环，再谈 chunk 瘦身。
• manualChunks 是分包守门，不是架构补丁。
• 纯常量、纯工具、纯类型文件尽量留在低层共享入口，别让它们进入重运行时桶。
• 首屏建议目标 200-300KB 未压缩，500KB 作为硬上限。
• 构建校验脚本最好同时守三件事：入口链、chunk 环、首屏体积。
• 当环只剩纯常量误入重 chunk 时，先给低层入口加分包例外，再考虑继续拆模块。

复盘清单

• 这个文件是不是既做纯工具，又回引了运行时服务？
• 这个常量是不是被错误分到重 chunk 里了？
• 这个懒加载边界是不是只该延后内容，不该拖延触发器？
• 构建守门脚本有没有把“能跑”升级成“能跑且不超预算”？

后面继续做启动性能和工具系统时，只要这 6 条不破，很多体验问题都会提前消失。

---

2026-04-22：SW 空闲预取与常驻工具条恢复经验

现象

• 左侧常驻工具 icon 只有在点开工具抽屉后才出现
• SW 日志显示已经激活，但页面侧 SWChannelClient 多次初始化超时
• 开发态 idle-prefetch-manifest.json 缺失，prefetchIdleGroups 直接中止

根因

• 页面把“有 controller”误当成“有可用 Service Worker”，但实际存在 ready.active 已激活、页面仍未被 controller 接管的窗口期
• 常驻工具条显示链路和完整 tool-window runtime 启用链路绑死，导致“显示 icon”也被重运行时阻塞
• UI 又额外依赖 tool-windows 分组预取完成信号，开发态 manifest 缺失时就会一直卡住
• idle prefetch 单次跑批如果人为截断，完成状态就会长期失真，最后只能靠超时兜底

最终方案

• SWChannelClient 初始化放宽为：controller 或 navigator.serviceWorker.ready.active 任一可用即可建通道
• 常驻工具条拆成两段： icon 显示单独启用；点击 icon 时再按需启完整 tool-window runtime
• toolWindowService 恢复 launcher 状态时优先读取完整工具定义，保证首屏图标和标题完整
• SW 在 activate 后自动消费 idle prefetch 默认分组，并把完成状态广播给页面
• 页面监听 SW_IDLE_PREFETCH_STATUS，但只把它当优化信号；超时后直接放行常驻工具条，避免功能被优化链路反向阻塞
• idle prefetch 仍用小并发，但不能再裁剪总任务数，否则完成分组永远不闭环

这次最值得固化的规则

• Service Worker 可用性判断要区分： controller 是“当前页已受控”，ready.active 是“后台已有可用 worker”，两者不是一回事
• 首屏可见能力和重运行时能力要解耦： 先让用户看到、点得到，再做按需增强
• 预取状态只能作为加速信号，不能作为功能显示前置条件
• 开发态缺 manifest、生产态资源回源失败，都要保证 UI 有可退化路径

排障顺序建议

1. 先看 navigator.serviceWorker.controller 和 navigator.serviceWorker.ready.active 是否分叉
2. 再看显示链路是否被 runtime 初始化、manifest、预取完成状态串联阻塞
3. 最后才看图标数据源、launcher 恢复、工具定义是否缺字段

---

2026-04-26：SW 关闭场景下的通道初始化超时经验

现象

• 控制台持续出现 [SWChannelClient] Attempt 4 failed: Error: SW activation timeout
• 调试状态里 supported: true，但 controller: null、registration: null
• 本地开发默认关闭 SW 或 URL 带 ?sw=0 时仍然触发了 swChannelClient.initialize()

根因

• 页面只用“浏览器支持 serviceWorker”判断是否启动 SW 诊断链路，没有复用真正的 SW 启用开关
• sw-console-capture 为了尽早捕获日志，会主动初始化 swChannelClient，结果在 SW 未注册时反复等待不存在的 controllerchange
• SW 通道自身没有识别 ?sw=0，其他调用点即使绕过主入口，也可能重新进入初始化重试
• 日志队列在通道不可用时只进不出，虽然单条较小，但长期打开页面会形成不必要内存占用

固化规则

• SW 相关入口必须共享同一个开关语义： 生产和本地调试默认启用；?sw=0 显式关闭；本地默认启动命令必须同步 watch 最新 sw.js
• 调试、崩溃、控制台捕获这类旁路能力，不能因为“想诊断 SW”而绕过 SW 开关主动拉起通道
• SWChannelClient.initialize() 自身也要兜底识别 ?sw=0，避免未来新增调用点造成重复超时
• 离线日志队列必须有容量上限，通道不可用时丢弃最旧项，不能无限积压
• 控制台捕获要过滤 [SWChannelClient]、[ServiceWorkerChannel] 这类自身通道日志，避免错误日志再次驱动初始化与上报

排障顺序建议

1. 先看当前 URL 是否带 ?sw=0，以及本地是否正在 watch 最新 sw.js
2. 再看是否存在 registration；如果没有注册，不要继续等 controllerchange
3. 最后排查是谁调用了 swChannelClient.initialize()，优先检查控制台捕获、崩溃上报、调试面板等旁路链路

---

2026-04-27：左侧浮岛工具栏与抽屉联动经验

现象

• 用户浏览器或系统存在左侧边缘标签时，固定贴边工具栏容易误触冲突。
• 直接把工具栏整体外移虽然能避让，但看起来像布局 bug，破坏“贴边悬浮岛”的原始观感。
• 将工具栏改成可拖动后，拖动过程中任务队列抽屉会被关闭态动画带出来。
• 任务队列抽屉从屏幕边缘大幅滑入，动画过重；抽屉打开后，左侧画布底色和抽屉底色割裂。
• 顶部拖动把手、底部固定按钮区如果只改父容器圆角，局部背景仍会把圆角视觉盖平。

根因

• “避让侧边标签”是用户个体环境问题，不适合用全局默认外移解决。
• 工具栏位置、抽屉位置、提示浮层位置、画布 fit-frame 避让如果各自写死宽度，拖动后必然错位。
• 关闭态抽屉的 transform 依赖工具栏右边界变量时，拖动工具栏会触发关闭态抽屉过渡，形成“被拖出来”的错觉。
• 任务队列抽屉和工具箱共用基础抽屉，但任务队列内容更重，应该用更轻的专属 motion。
• 抽屉只从工具栏右侧开始绘制时，工具栏左侧仍露出画布底色；抽屉色和画布色差会被用户感知成断层。

最终方案

• 默认仍贴屏幕左边缘，保持悬浮岛观感；只提供顶部拖动把手，让需要避让的用户手动拖入内侧。
• 工具栏横向位置用 localStorage 轻量持久化，双击把手复位到默认贴边位置。
• 统一维护 --aitu-toolbar-left 和 --aitu-toolbar-right-edge，抽屉、提示、fit-frame 都读同一套右边界。
• 拖动过程中只更新 CSS 变量和 DOM style，拖动结束后再落 React state，减少高频重渲染。
• 关闭态抽屉从 translateX(-100%) 隐藏，打开态再平移到工具栏右边界；拖动期间给根节点加 aitu-toolbar-dragging 禁用抽屉 transition。
• 任务队列抽屉使用轻量淡入： 160ms transform + 120ms opacity，关闭态保持 visibility: hidden 和 pointer-events: none。
• 抽屉打开时用同色 box-shadow 向左铺到屏幕边缘，工具栏 z-index 高于抽屉，让工具栏仍像浮在抽屉上。
• 工具栏底部固定区也要继承底部圆角，避免底部按钮区背景把父容器圆角盖平。

固化规则

• 默认位置优先保留产品最自然的视觉形态；兼容特殊环境时优先给用户可调能力，不要把所有用户都推到次优默认。
• 可拖动 UI 的高频 pointer move 不要每帧依赖 React state；能用 CSS 变量同步的位置，优先走 CSS 变量。
• 所有依赖工具栏边界的组件必须共享同一来源，不能散落硬编码宽度。
• 隐藏态元素如果跟随一个高频变化变量，要么禁用 transition，要么让隐藏态不依赖这个变量。
• 抽屉“内容从哪里开始”和“背景铺到哪里”可以分离：内容对齐工具栏，背景可延展到屏幕边缘。
• tooltip 只负责展示提示，不应接收 pointer events 挡住工具按钮点击。
• 改圆角时要检查内部固定区域、底部区域、滚动区域背景是否覆盖父容器弧度。

回归检查清单

• 默认桌面视口：工具栏 left = 0，右边界 CSS 变量等于工具栏实际右边界。
• 拖动把手：拖动时任务抽屉不外露，松手后位置持久化，双击可复位。
• 任务队列：首次打开有轻量动画，关闭态不可见且不可点击。
• 工具箱 / 项目抽屉 / 任务队列：打开后左边缘贴齐工具栏右边界。
• 抽屉打开后：工具栏左侧到屏幕边缘为抽屉同色背景，工具栏仍在上层。
• 移动端：不显示拖动把手，默认收起形态不变。

---

2026-04-27：右侧停靠工具栏与双向抽屉经验

现象

• 工具栏只允许拖到左侧内缘时，右手用户或右侧工作流无法获得同等避让能力。
• 工具栏拖到右侧后，项目/工具箱/任务抽屉如果仍向右展开，会被屏幕边界截断。
• 对话抽屉、小地图、缩放控件如果只按“右屏幕边缘”定位，会被右侧工具栏遮挡。
• 对话抽屉收起态如果只平移，不做 visibility / pointer-events 隐藏，右侧仍会露出面板边缘。
• 抽屉内容对齐工具栏后，抽屉背景没有铺满到屏幕边缘时，会出现画布色和抽屉色断层。

根因

• 工具栏位置从“左边界变量”升级为“双侧停靠语义”后，依赖它的浮层也必须知道当前停靠方向。
• 右侧停靠时，遮挡区域不是工具栏右边界，而是 viewportWidth - toolbarLeft。
• 抽屉宽度、抽屉展开方向、导航控件避让、fit-frame 可视区计算，不能各自用硬编码边距。
• 关闭态元素跟随工具栏位置时，仅靠 transform 容易在边缘露出残影或接收交互。

最终方案

• 工具栏可拖到屏幕最右侧，超过屏幕中线后在根节点标记 aitu-toolbar-dock-right。
• 继续用轻量 CSS 变量同步布局，不新增配置实体： --aitu-toolbar-left、--aitu-toolbar-right-edge、--aitu-toolbar-right-dock-width、--aitu-toolbar-right-avoidance、--aitu-toolbar-side-panel-max-width。
• 右侧停靠时，项目/工具箱/任务抽屉向左展开，关闭态从屏幕外隐藏，打开态左边缘贴齐工具栏左侧。
• 右侧停靠的抽屉用同色 box-shadow 向屏幕边缘延展背景，内容对齐和背景铺满分离处理。
• SideDrawer 的 resize 方向按停靠侧切换；右侧停靠时拖左边缘调整宽度。
• ChatDrawer 右侧停靠时让出工具栏宽度，打开态背景铺到屏幕右边缘，关闭态使用 opacity + visibility + pointer-events 彻底隐藏。
• ViewNavigation / 小地图同时避让工具栏占位和打开的对话抽屉；fit-frame 按左右遮挡分别计算可视区。
• 顶部拖拽把手默认态进一步弱化，只在 hover、focus、dragging 时增强。

固化规则

• 可拖动悬浮工具栏一旦支持跨屏停靠，所有依赖边界的组件都要读统一 CSS 变量，不再假设工具栏永远在左侧。
• 判断抽屉展开方向应基于工具栏中心点所在半屏，而不是用户最后一次拖动方向。
• 右侧停靠时，导航控件的避让值要叠加工具栏宽度和已打开抽屉宽度，避免小地图被抽屉压住。
• 关闭态抽屉必须同时处理视觉隐藏和交互隐藏：visibility: hidden、pointer-events: none、必要时配合 opacity。
• 抽屉背景延展可以用同色阴影铺屏，但不要让内容区域跟着铺满，否则会破坏对齐和可读性。
• 改动右侧面板时，要同步回归 ChatDrawer、ViewNavigation、Minimap、fit-frame 和各类 toolbar-right 抽屉。

回归检查清单

• 工具栏拖到右边缘：工具栏不出屏，刷新后位置保留。
• 右侧工具栏打开项目/工具箱/任务抽屉：抽屉向左展开，不被屏幕裁切，背景铺到右侧屏幕边缘。
• 对话抽屉关闭态：面板不可见且不可点击，只保留把手。
• 对话抽屉打开态：右侧让出工具栏宽度，背景延伸到屏幕右侧。
• 对话抽屉打开 + 小地图展开：小地图和缩放控件避开“工具栏 + 对话抽屉”组合宽度。
• fit-frame：工具栏/抽屉在左侧或右侧时，Frame 都居中到剩余可视区。