feat(desktop): 支持自定义背景图片

[Stella-xixi]

这次改了什么

摘要

为 Desktop 增加自定义背景图片能力。用户可以在设置 → 通用 → 外观中选择、更换或移除本地背景图片，并调节背景遮罩强度与模糊程度；背景可覆盖标题栏、侧栏与主内容区，同时通过半透明输入区和实体内容卡片保持可读性。

变更类型

• feat 新功能
• fix 缺陷修复
• refactor / perf 重构或性能优化
• docs / test / chore 文档、测试或工程维护
• 其他：

范围

• 关联 Issue / 需求：Feature request: support custom background images for the Cindy interface #3448
• 本 PR 包含：
  • 支持导入 JPG、PNG、WebP 背景图片，限制单张最大 25 MB，并校验实际文件格式。
  • 背景图片由 Desktop main 进程复制到应用用户数据目录，通过只读 cindy-background:// 协议加载。
  • 支持选择、更换、移除背景，以及调节遮罩强度和模糊程度。
  • 背景覆盖新建任务、设置和自动化等主界面；输入区在启用背景时使用半透明模糊材质。
  • 删除背景后恢复原有页面底色，并增强侧栏与内容区分隔线的可见度。
  • 同步 Light/Dark 语义 Token、五种语言文案、CSP/IPC/preload 类型及相关测试。
• 明确不包含：背景云同步、动态/视频背景、Mobile 背景设置、服务端改动。
• 用户可见变化：Desktop 外观设置新增“自定义背景”区域，主窗口可使用本地图片作为背景。
• 是否存在 breaking change：无。

UI 变化

• 引用的设计规范：docs/design-rules/DESIGN.md 的双模式交付门槛、语义 Token、层级与可读性约束；页面画布在有背景时透明，输入区使用半透明模糊材质，设置卡片与关键控件保留实体表面；无背景时恢复既有主题表面。

演示视频

📹 待手动上传：选择背景、更换背景、调节遮罩/模糊、跨页面展示、删除背景并恢复默认外观。

请将演示视频上传到这里。

怎么验证的

自动验证

pnpm test:unit:related
结果：通过；test runner 487 PASS / 8 SKIP，Desktop related unit PASS。

pnpm --filter desktop run --if-present typecheck
结果：通过。

pnpm check:i18n
结果：通过；五种语言 key 一致，仅有仓库既有非阻塞警告。

pnpm check:i18n-glossary
结果：通过；无新增术语违规，仅有仓库既有 proposed 术语警告。

pnpm check:design-inventory
结果：通过；34 个 surface 的 GENERATED 区块已同步。

pnpm check:dco -- --base origin/main
结果：通过；1 个 commit 带 DCO 签名。

手工验证

在 Windows Desktop CN 隔离开发环境中使用 JPG 图片验证：

• 背景覆盖标题栏、侧栏、新建任务主内容区、设置页和自动化页。
• 遮罩与模糊调节实时生效。
• 新建任务输入框在启用背景时保持半透明且内容可读。
• 移除背景后恢复默认表面，侧栏分隔线清晰可见。

未执行的验证

• 未在 macOS 实机验证原生文件选择器及标题栏表现。
• 演示视频由提交者在 PR 页面手动补充。

风险

风险分类

• 无已知风险
• SQLite / migration
• system prompt
• 协议兼容
• 权限 / 安全 / 用户数据
• 存量插件兼容（批准状态 / 指纹 / manifest 校验 / 安装布局 / 包格式）
• 原生层 / fingerprint / OTA
• 跨平台差异
• 其他：

影响与回滚

• 影响范围：仅 Desktop 本地外观设置、背景图片文件、只读自定义协议和对应 Renderer 表面；不修改数据库 schema、不访问服务端、不影响 Mobile。图片只复制到应用用户数据目录，协议路径固定且不接受任意本地路径。
• 回滚 / 降级方式：回滚本 PR 即可恢复原外观设置；用户也可在设置中点击移除背景，立即恢复默认界面并清理托管背景文件。

提交前检查

• 已 review 完整 diff
• 每个 commit 都带 DCO 签名（git commit -s，见 DCO）
• UI 改动已在「UI 变化」注明引用的设计规范章节
• 未提交凭证、令牌或授权文件
• 已补充必要文档
• 已确认测试结果或说明未执行原因

[greptile-apps]

Greptile Summary

此 PR 为 Desktop 增加本地自定义背景图片的导入、托管协议、外观参数与跨页面渲染能力。

• 在主进程中新增图片校验、托管文件、只读自定义协议及受信任 IPC
• 在 preload 和共享外观设置中新增背景图片、遮罩与模糊契约
• 在设置页和主界面各表面接入背景展示、预览及可读性材质
• 当前文件与设置提交顺序以及渲染端失败协调存在一致性问题

Confidence Score: 3/5

此 PR 在修复背景文件与设置的非原子提交，以及渲染端写入失败后的状态回滚之前不宜合并。

背景导入会先不可逆地替换文件再持久化 URL，并允许导入与移除重叠；同时设置 Hook 会在 IPC 失败后保留未保存的乐观状态并泄漏未处理异常。

Files Needing Attention: apps/desktop/src/main/appearance-background.ts、apps/desktop/src/main/appearance-settings-ipc.ts、apps/desktop/src/renderer/hooks/useAppearanceBackground.ts、apps/desktop/src/renderer/components/settings/AppearanceSection.tsx

Important Files Changed

Filename	Overview
apps/desktop/src/main/appearance-background.ts	新增背景导入与协议服务，但文件替换和清理未与设置持久化或并发操作保持原子一致。
apps/desktop/src/main/appearance-settings-ipc.ts	新增受信任的导入、移除 IPC，但操作顺序会在失败或重叠请求下造成文件与设置分离。
apps/desktop/src/renderer/hooks/useAppearanceBackground.ts	新增背景状态适配器，但乐观写入缺少失败回滚和 Promise 拒绝处理。
apps/desktop/src/renderer/components/settings/AppearanceSection.tsx	新增背景选择、移除和参数滑块，调用点未处理参数写入及移除失败。
apps/desktop/src/shared/appearanceSettings.ts	新增背景字段、默认值、限制和自定义协议 URL 归一化，契约本身保持清晰。
apps/desktop/src/main/bootstrap-electron.ts	将背景协议权限和处理器接入 Electron 启动流程，注册位置与现有协议模式一致。
apps/desktop/src/renderer/components/layout/AppearanceBackground.tsx	新增不可交互的背景、遮罩和模糊渲染层，未发现独立功能缺陷。

Sequence Diagram

sequenceDiagram
  participant U as 用户
  participant R as Renderer 设置页
  participant P as Preload
  participant M as Main IPC
  participant F as 托管背景文件
  participant S as 外观设置存储
  U->>R: 选择背景图片
  R->>P: importBackground()
  P->>M: background-import
  M->>F: 校验并替换背景文件
  M->>S: 持久化 backgroundImage
  S-->>M: 设置快照或写入错误
  M-->>P: 导入结果
  P-->>R: 更新界面

Loading

Prompt To Fix All With AI

### Issue 1
apps/desktop/src/main/appearance-background.ts:69-71
**背景文件与设置提交失配**

当设置写入因锁竞争或文件不可读而失败时，这里已经覆盖背景文件并删除其他扩展名，导致失败的替换仍会使原背景 URL 返回 404。如果导入与另一次导入或移除操作重叠，未串行化的清理还会删除另一请求的文件，使持久化 URL 指向不存在的背景。

### Issue 2
apps/desktop/src/renderer/hooks/useAppearanceBackground.ts:40-46
**失败写入保留乐观状态**

当遮罩、模糊或移除请求因设置锁竞争、不可读设置文件等错误而被拒绝时，`setPatch` 已经应用的乐观状态不会回滚，且调用点通过 `void` 丢弃拒绝。界面因此继续显示未保存的背景设置并产生未处理的 Promise rejection，直到后续广播或重启时突然恢复持久值。

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "feat(desktop): support custom background..." | Re-trigger Greptile}

[MagicLizi]

这条 PR 正在等维护者确认，当前不会自动合并。

改动会让用户在外观设置里上传本地背景图，并铺到标题栏、侧栏和主内容区。请维护者直接在 PR 上 Approve；如果要改，请 Request Changes。讨论 issue：#3814

另外：请补一段改动后的界面效果证据（截图 / 录屏 / HTML 预览）。当前描述里的演示视频还是占位。

[MagicLizi]

命中 UI 路径(apps/desktop/src/renderer/components/layout/AppearanceBackground.tsx / apps/desktop/src/renderer/components/layout/MainLayout.tsx / apps/desktop/src/renderer/components/new-chat/ChatInput.tsx 等)但 description 未附界面效果证据——建议补充改动后效果:截图/录屏,或改动后界面的 HTML 页面(```html 代码块、.html 附件或在线预览链接),便于确认界面符合 DESIGN.md 设计规范

[MagicLizi]

@Stella-xixi 👋 这个 PR 还有 2 条 review conversation 没 resolve(apps/desktop/src/main/appearance-background.ts / apps/desktop/src/renderer/hooks/useAppearanceBackground.ts),auto-review 因此暂时跳过、没法继续审查 / 合并。

如果你已经按评论改完或回应了,请到对应 thread 上点 Resolve conversation;全部 resolve 后,下一轮 auto-review 会自动重新审查这个 PR。

[MagicLizi]

@Stella-xixi 👋 这个 PR 目前与 main 有合并冲突,auto-review 因此暂时跳过、没法继续审查 / 合并。

请在本地 merge 最新的 origin/main 解决冲突后推送;冲突解除后,下一轮 auto-review 会自动重新处理这个 PR。

[MagicLizi]

@Stella-xixi 👋 这个 PR 目前与 main 有合并冲突,auto-review 因此暂时跳过、没法继续审查 / 合并。

请在本地 merge 最新的 origin/main 解决冲突后推送;冲突解除后,下一轮 auto-review 会自动重新处理这个 PR。