XCSDD/.trae/documents/plan.md

修复 XCSDD 启动缓慢及黑屏问题的实施计划

1. 问题分析 (Current State Analysis)

根据您提供的启动日志，导致软件启动缓慢（5秒黑屏）以及输出大量错误信息的原因主要有以下三点：

1. 生产环境默认开启了开发者工具 (DevTools)

   • 日志现象：5秒后输出的错误（Unknown VE context, Request Autofill.enable failed 等）全部来自 devtools://devtools/...。
   • 原因：在 electron/main.mjs 中，只要不是 headless 模式，就会自动执行 mainWindow.webContents.openDevTools()。在打包后的生产环境（win-unpacked）中，加载庞大的 DevTools 会严重阻塞主线程和渲染进程，是导致 5 秒黑屏的最主要原因。

2. GPU 缓存目录权限冲突

   • 日志现象：Unable to move the cache: 拒绝访问。 (0x5) 和 Gpu Cache Creation failed: -2。
   • 原因：Chromium 尝试在当前执行目录（或被锁定的临时目录）写入 GPU 着色器磁盘缓存，但没有写入权限。这会导致 GPU 进程初始化时发生等待/重试，进一步拖慢了启动速度。考虑到您的项目使用了 @react-three/fiber（3D 蓝图查看器），我们不能直接禁用硬件加速，否则 3D 渲染会极其卡顿。最优解是禁用 GPU 的磁盘缓存。

3. 窗口显示时机过早 (未应用 ready-to-show)

   • 原因：目前 new BrowserWindow({ show: !args.headless }) 会在窗口创建的瞬间直接显示。此时 React 尚未完成 DOM 渲染，因此用户会先看到一个纯黑/纯白的背景，直到页面加载完毕。

2. 拟定修改方案 (Proposed Changes)

我们将修改 electron/main.mjs 文件来彻底解决上述问题：

修改 1：按环境按需加载 DevTools

• 将 devTools: true 修改为 devTools: !app.isPackaged。
• 将自动打开控制台的逻辑修改为：if (!app.isPackaged && !args.headless)。
• 目的：确保在您打包发布后，不会再加载开发者工具，从而消除 5 秒的额外加载时间和相关报错。

修改 2：优雅地显示窗口 (防止黑屏闪烁)

• 窗口初始化时强制设置为 show: false。
• 监听 ready-to-show 事件，当渲染进程准备好第一帧画面时，再调用 mainWindow.show()。
• 目的：用户点击图标后，应用会在后台默默渲染，等画面准备好后瞬间弹出，实现“秒开”的视觉体验。

修改 3：禁用 GPU 磁盘缓存以消除权限报错

• 在 app.whenReady() 之前，添加代码：app.commandLine.appendSwitch('disable-gpu-shader-disk-cache');
• 目的：解决 Unable to move the cache (0x5) 报错，同时保留 WebGL 硬件加速，确保 3D 蓝图流畅运行。

3. 假设与决策 (Assumptions & Decisions)

• 假设：您的项目 app.isPackaged 在 win-unpacked 下能正确识别为生产环境（通常为 true）。
• 决策：不使用 app.disableHardwareAcceleration()，以保证 three.js 的性能。

4. 验证步骤 (Verification steps)

1. 实施计划后，重新运行 npm run electron:build 并在 win-unpacked 目录中启动 XCSDD.exe。
2. 观察控制台输出，确认不再有 cache_util_win.cc 和 devtools 相关的 ERROR。
3. 观察启动过程，确认应用在短暂等待后直接显示完整的 UI，不再有长达 5 秒的黑屏阶段。