Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

15.8 KB
Raw Blame

官方壁纸 OSS 按需下载方案

状态:客户端实现已完成,资源已由用户上传,两区文件完整性校验通过。日期:2026-10-15。

实施结果:三张 640×400 缩略图合计 169,078 bytes;生产 Renderer 构建确认六个原始高清 素材均未进入产物,壁纸资产减少 20,383,757 bytes(约 19.44 MiB)。缓存沿用 userData/cindy-media/client-wallpaper/,地址只含素材哈希及扩展名;升级不清缓存,也不按 应用版本生成新地址。已有自动测试覆盖下载后更换应用版本、重载模块并断网,图片与视频均 直接复用磁盘文件且下载调用为零。以下保留设计依据;末尾记录当前验证范围。

基于 Issue #6088,用户希望减少安装体积, 将动态桌面相关资产改为使用时下载。本次盘点基于本 worktree 的 3f4ec18ec53a604651320a76db6cfb463afebd90,只统计三套官方壁纸的媒体文件。

1. 当前体积

文件位于 apps/desktop/src/renderer/assets/wallpapers/。以下是文件逻辑字节, 不是压缩安装包大小,也不是文件系统分配空间;MiB = 1,048,576 bytes。

壁纸 MP4 字节 / MiB WebP 字节 / MiB 合计 MiB
窗边陪伴 cindy-window 6,091,872 / 5.81 1,101,332 / 1.05 6.86
未来工作室 cindy-studio 3,606,656 / 3.44 1,649,522 / 1.57 5.01
梦境漫游 cindy-dream 6,312,719 / 6.02 1,790,734 / 1.71 7.73
总计 16,011,247 / 15.27 4,541,588 / 4.33 19.60

六个文件合计 20,552,835 bytes(20.55 MB / 19.60 MiB)。 三段视频的清单规格均为 2304×1440、24 fps、约 12 秒。

当前 renderer/lib/wallpaper.ts 直接 import 六个文件;视频清单均为 delivery: bundled。 执行现有发布脚本的 --verify-only 已确认三段视频的大小及 SHA-256 与清单一致, 其输出为 CDN upload total: 0 bytes。

此项可以独立减少随包资产,但不能据此解释或解决 issue 中超过 1 GB 的全部占用。 真实收益须用同平台、同架构、同依赖基线的构建产物对比;压缩下载量单独测量。

2. 推荐交付方式

高清 WebP 与 MP4 均放 OSS,经现有 CDN 分发;包内保留轻量预览图和资源清单。

范围 可移出原始素材 保留能力与代价
只迁视频 15.27 MiB 高清静态壁纸离线即用;首次启用动态时下载视频
图片、视频都迁出(推荐) 19.60 MiB,须扣除新预览图 列表和离线首用显示预览;选中后下载高清图,启用动态再下载视频

预览图同时供设置列表和下载前背景使用,沿用同一场景与裁切。三张合计以不超过 300 KiB 为初步预算,须实际制作并目检后确认;预算不是已测结果。 若达到该预算,资产净减少至少约 19.31 MiB,尚未计入新增代码、清单及打包差异。

用户实际使用过的高清资源仍占本地存储。全部使用后,本地资源总占用会接近原素材体积; 收益主要是降低安装包与初装占用,避免所有用户都下载三套素材,也避免每次完整更新重复携带。

使用时机

  1. 默认无壁纸、打开设置列表或浏览缩略图:不下载高清资源。
  2. 选中一套壁纸:立即显示内置预览,优先读取该壁纸已校验缓存;未命中则下载该套高清 WebP。
  3. 动态模式且未开启系统减少动态效果:再下载该套 MP4。小窗口和大窗口规则相同。 图与视频分别完成,图失败不阻止可用视频播放;视频失败不阻止静态图显示。
  4. 下载完成后,在图片解码或视频首帧可用时平滑替换。失败继续显示已有图或预览,设置内显示 下载状态与重试入口,不阻塞其他页面。手动重试立即生效;网络恢复后的自动重试有次数上限, 只针对仍被选中且需要的资源。
  5. 下载后重启或离线再次选中,直接使用缓存。切换到静态、关闭壁纸或切换场景后, 不应用迟到结果,也不继续自动重试。已经开始的小文件下载允许完成并留存缓存, 避免一个窗口关闭中断其他窗口的共用请求;下载有总超时和有限重试。
  6. 沿用现有隐藏窗口暂停播放、减少动态效果、单画布和整窗连续背景行为。

下载状态放在当前选中壁纸的缩略图上:半透明遮罩按实际下载字节从底部向上填充, 0% 为空、100% 铺满,完成后移除。所需图片与视频按字节加权,已缓存的资源计为完成; 下载停顿时进度保持不变,中断后从头重下时如实回退,而非按时间模拟进度。 失败改为重试图标,点击同一缩略图或聚焦后按 Enter 即可重试。按 2026-10-15 用户要求, 不增加可见的下载状态文字或独立重试按钮;读屏说明保留,并支持减少动态效果。 进度只使用底部为原点的 transform 与语义 token,同时实现 Light/Dark,依据 DESIGN.md 的可选壁纸、双模式及内容规范。

3. 已有实现可以复用什么

现有入口 已有能力 本次需要调整
shared/wallpaper-video-manifest.json 视频大小、SHA-256、规格与分发方式 增加静态图描述,保留稳定壁纸 ID;正式资源显式标记 CDN
main/wallpaper-video.ts 固定清单选择、HTTPS、字节数/哈希校验、并发合并、缓存读取、失败退避 扩展图片,接入统一下载器,提供可恢复的加载状态
main/appearance-settings-ipc.ts / preload 受信本机 Renderer 的 ensure 接口,只接收壁纸 ID 扩展受限资源类型和状态;继续拒绝任意 URL、路径及远程调用
renderer/components/layout/WallpaperVideo.tsx 本地播放、首帧显示、失败回退、暂停与释放解码器 改为资源就绪后播放,不依赖内置 MP4,也不再只在 HD 档请求
renderer/hooks/useWallpaperSettings.tsx / renderer/lib/wallpaper.ts 全窗背景、选择与模式 使用内置预览及下载后的静态图;去掉高清媒体的打包 import
main/cindy-media/ client-wallpaper 作用域、原子落盘、Range 播放、发布锁与回收 继续复用;扩展官方 WebP 的保留引用
scripts/publish-wallpaper-videos.mjs 按清单校验、按区域上传 OSS、CDN 下载后复核 支持 WebP,统一发布源文件命名;增加发布前只读远端核验

不能只切换 delivery 的原因

  • WallpaperVideo 先调用 getWallpaperVideo(),没有内置地址就直接返回。 只删 MP4 import 会导致 CDN 下载入口也不执行。
  • AdaptiveWallpaper 仅在显示需求超过 HD 阈值时下载,小窗口仍依赖内置视频。 当前三套也没有另一份独立的低清视频可保留。
  • 目前所有失败都返回 null,主进程设置五分钟退避;Renderer 没有定时或联网重试, 同一场景持续显示时不保证恢复。需要显式重试状态与触发机制。
  • 高清 WebP 目前始终由 import 提供,现有 CDN 清单、发布脚本与引用保留只覆盖 MP4。 扩展图片时须同步修改自定义壁纸与官方下载两条回收入口,避免误删官方图或自定义图。
  • 当前下载将整段视频读入内存。按 统一下载约定,新增实现应使用 main/downloader/index.ts 的公共入口,复用流式写盘、超时、进度、重试与校验,不再扩写独立 HTTP 下载器。

4. 下载、缓存及升级约定

  • 清单随客户端发布,记录资源类型、大小、SHA-256 和格式;不增加运行时远程目录服务。 来源由客户端 cdnBaseUrl 和清单决定,Renderer 只选择已知 ID 与资源类型。
  • 延续 wallpapers/<sha256>.mp4,图片使用 wallpapers/<sha256>.webp。 OSS 保存原文件;内容变化生成新 hash 地址,不覆盖旧对象。
  • 下载使用统一下载器的完整性检查及来源限制,保留 HTTPS、禁止 URL 凭证和重定向的约束。 受控临时文件完成验证后通过 ingestClientWallpaper 发布;当前素材很小,可复用其有界 buffer 入仓接口。临时文件在下载结束及入仓结束后按成功、失败、取消分别收尾。 下载不占媒体发布锁,只有入仓和回收持锁。
  • 成品继续使用 cindy-media://client-wallpaper/<hash>.<ext>,由现有协议读取。 不新增媒体目录、数据库或协议,不直接从 Renderer 播放远端 URL。
  • 按资源合并多窗口请求,窗口离开只取消显示订阅,不中断其他窗口仍需要的下载。 图片与视频独立记录状态,关闭动态模式不影响静态图;失败结果不永久记作已完成。 同一下载的后来请求者立即收到当前字节快照;进度只回送已经通过授权的请求 frame, 不向所有窗口广播。preload 只暴露固定订阅并剥离 Electron event,结束时取消订阅。 此项属于本机 Desktop 外观,不读 SSH 工作目录、不增加 device-link 白名单或 Mobile 入口。
  • 所有当前清单内的已下载资源保留,不因切换壁纸删除重下。自定义媒体引用与官方图片/视频 引用合并后,由既有 recycler 回收已失去引用的旧资源;暂不引入 LRU 或自动容量配额。
  • 缓存及设置沿用客户端 profile 共用范围,登录前、切账号后都可使用。 不同步到另一设备,不随账号附件清理。现有壁纸 ID、动态设置、可见度、模糊设置不变。
  • 升级后若原来选中了官方壁纸,只请求当前所需资源,不预下载其他两套。 旧安装包的内置媒体不一定能跨升级保留,因此首次离线升级可能暂时只有预览; 保留原选择,联网后恢复高清及动态效果,不重置用户设置。

5. 发布顺序与当前远端状态

2026-10-15 初次盘点时,清单三段视频的预期地址在两个区域共六个 HEAD 请求均返回 404。 用户完成上传后,再实际下载两区共 12 个图片/视频对象:全部 200,大小、SHA-256 与 Content-Type 均匹配。响应暂未设置 Cache-Control;本地持久缓存不依赖 HTTP 缓存头。

  • global:https://hotfix.cindy.app/cindy/wallpapers/<sha256>.mp4
  • cn:https://hotfix.cindy.com.cn/cindy/wallpapers/<sha256>.mp4

两区使用相同内容哈希,已核验的 URL 不需要改动。

实施顺序:

  1. 制作轻量预览、补齐图片清单与发布脚本,离线核验全部原始素材。 原文件保留为发布输入,移出 Renderer 依赖图;本轮目标是发行包体积,不改写 Git 历史。
  2. 分别显式选择 global、cn 发布到现有公开资源渠道,按 区域规则 禁止相互回落。 下载每个 CDN 成品并复核字节数、SHA-256、Content-Type 和长期缓存响应头。
  3. 在隔离 Desktop 中完成按需加载和失败恢复验证,再切换客户端清单并移除高清资源 import。 为发布版本添加只读资源检查;任一必需对象缺失或不匹配,都不发布该区域的新客户端。
  4. 构建产物确认不含六个原始高清素材,只含预览和清单。记录 Windows/macOS/Linux 实际验证范围,分别比较压缩包、安装文件字节与首次使用后的缓存增量。

资产先发布、客户端后切换。新资源部署失败时继续发行原行为;回退客户端时旧资源对象保留, 不能因为新版本已发布就删除仍被旧客户端清单引用的 CDN 对象。 此方案无需修改服务端仓库;OSS/CDN 的公开资源发布属于单独的发布步骤。

已同步更新 媒体存储规则 中“三款全部随包”的旧约定, 以 2026-10-15 用户确认的新方向为准。上述发布步骤保留为后续更新素材时的操作约定。

6. 验收

  • 未选中壁纸、只浏览设置列表:高清资源网络请求为零。
  • 首次静态使用只下载一张图;启用动态才下载对应视频,普通窗口与高 DPI 窗口均有效。
  • 多窗口只产生一份同资源下载;切换场景、模式或关闭窗口不应用过期结果。
  • 断网、404、超时、磁盘不足、错误大小或哈希均保留可用背景;手动重试、网络恢复和损坏缓存重下有效。
  • 已下载后离线重启、切账号可复用;自定义壁纸导入、替换、删除不误删官方资源,反向亦然。
  • 旧设置升级保持原选择;离线升级显示预览且不丢设置。
  • 在真实客户端检查 Light/Dark 下主界面、设置各分区、展开工具栏及独立窗口的连续背景, 下载前后无黑屏闪烁;隐藏窗口及减少动态效果继续生效,记录未验证的平台或模式。
  • 定向覆盖下载、引用回收、渲染触发和发布校验;运行 Desktop 类型检查,检查最终产物资源清单。

已完成:资源盘点、预览图、客户端与发布校验脚本、两区 CDN 实际文件核验、14 个测试文件 共 150 项定向测试、Desktop 类型检查、多语言及文档检查、生产 Renderer 构建和媒体排除验证。 Windows 隔离客户端实测了首次静态下载、三款视频播放(2304 像素宽,readyState=4,无播放错误)、 Light/Dark 设置界面;重启并切换三款场景后,六个本地文件的修改时间及 SHA-256 均保持不变。 独立侧栏与资源窗口实测从共享缓存取用、隐藏时视频暂停;插件面板宿主由入口与 preload 测试覆盖, 未做插件面板实机目检。三者只新增固定场景资源请求方法,不开放设置写入或任意路径、URL。 完整签名安装包前后对比及 macOS/Linux 实机验收尚未执行;Renderer 资产差值不代表压缩安装包差值。

2026-10-15 弱网与缩略图进度实测(Windows)

在独立 profile 中通过本机 CONNECT 代理限制真实 Global CDN 的响应速度并注入断流, 不解密 TLS、不替换文件响应、不修改系统网络设置。限速场景另外加入 800 ms 初始延迟。

场景 结果
静态图,64 KiB/s 约 20.15 秒完成,仅下载图片;校验完成前保留内置预览
视频,128 KiB/s 约 54.91 秒完成,等待期间保留高清静态图
视频约 256 KiB 时断流一次 自动重试,约 37.98 秒完成,文件哈希正确,无半成品媒体
离线首次请求 图片约 3.19 秒、视频约 4.12 秒进入失败状态,保留可用背景
恢复网络后手动重试 图片约 17.31 秒完成,恢复高清图
恢复网络后不操作 包含 30 秒等待和下载,约 62.20 秒自动恢复视频
已缓存资源离线再选中 约 215 ms 就绪,代理记录的 CDN 连接为零
连接保持但停止传输 三次真实空闲超时后约 103.75 秒进入失败状态,键盘激活缩略图可重试

按用户最终指定的填充方向重新实测:静态图约 20.46 秒完成,在真实 25% 和 70% 下载点 分别核实 Light/Dark,遮罩以缩略图底边为固定原点向上增长。视频传输被暂停时,合并进度 保持 44% 不动;随后断线显示缩略图重试图标,恢复网络后按 Enter 重试约 16.93 秒完成。 完成后的图片与视频 SHA-256 均匹配,再次离线选择的 CDN 连接仍为零。

进度改动另完成 8 个文件共 90 项定向测试、Desktop 类型检查、定向 ESLint 与设计颜色检查。 覆盖多窗口共享进度、后来请求者的快照、重试归零、关闭 frame 不影响下载、preload 取消订阅、 图片/视频字节加权、静态模式排除视频,以及缩略图进度与重试交互。弱网代理与测试实例在 验收结束后关闭,原验收沙盒恢复正常网络;真实截图和原始测量记录留在本地忽略的 artifacts, 不把测试截图加入工程文件。