v1 版本路线图

本页记录从已发布的 v0.9.9 基线迈向 LWE v1 的维护中开发方向。发布后请删除或折叠过时版本小节；当产品范围、已验证运行时支持或发布优先级变化时，应同步更新本页。

v1 目标

LWE v1 应成为可信赖的 Linux Wallpaper Engine 迁移应用，而不是宣称广泛运行时兼容的产品。

v1 目标包括：

• 基于 Tauri 2 和 SvelteKit 的 Linux 桌面应用；
• 由 Rust 后端负责 Workshop、Library、Desktop、Settings、兼容性、持久化和运行时集成服务；
• 以 Wallpaper Engine 创意工坊内容作为主要内容来源；
• 视频类壁纸是 v1 唯一可运行的运行时类型；
• 场景类和网页类壁纸可用于元数据识别和兼容性报告，但除非未来实现并验证，否则不可运行；
• Wayland + niri 是已验证桌面目标；
• 英文和简体中文用户可见文档与文案持续维护。

版本序列

版本	主题	主要结果
v0.7.0	支持矩阵锁定	产品事实保持一致并有测试覆盖。
v0.8.0	运行时强化	视频应用、清除和恢复在 niri 上可靠工作。
v0.8.5	Library 工作流强化	日常 Library 工作流安全且清晰。
v0.9.0	Workshop 清晰度	发现和 Steam 同步预期诚实明确。
v0.9.5	诊断与发布准备	支持能力和发布姿态准备就绪。
v0.9.6	预览性能	已发布：Library 和 Workshop 卡片网格使用受控缩略图资源，而不是原始预览媒体。
v0.9.7	Workshop 浏览打磨	已发布：Workshop 导航、缓存搜索恢复和少量结果布局更流畅。
v0.9.8	后台功耗画像	已发布：运行时和后台刷新减少不必要工作，复用热快照，并暴露轻量快照来源诊断。
v0.9.9	Wayland 能力基础设施	已发布：由 Wayland 协议能力决定动态壁纸是否可用；缺少必要协议时优雅降级。
v1.0.0-rc.1	首个候选版	范围冻结并完成端到端验证。
v1.0.0-rc.2	可选阻塞修复候选版	仅在 rc.1 发现发布阻塞问题时使用。
v1.0.0	稳定 v1	诚实、可靠、视频优先的稳定版。

v0.7.0：支持矩阵锁定

主题：让产品事实在所有位置保持一致。

交付内容：

• 权威支持矩阵：
  • 视频是可运行的首发目标；
  • 场景仅用于元数据识别和兼容性报告；
  • 网页仅用于报告识别；
  • 其他/应用内容不支持运行时工作流。
• 兼容性策略、Library 投影、Workshop 详情、Desktop apply 和文档保持一致。
• 场景不再显示为完全支持或可应用。
• Apply 仅对可运行视频 Library 项启用；对仅识别项目禁用并给出解释。
• 英文和简体中文文档同步更新。

验收标准：

• 已同步视频报告为可运行支持。
• 已同步场景报告为已识别/运行时不支持。
• 网页报告为运行时不支持。
• Desktop apply 在调用后端前以清晰原因拒绝非视频内容。
• 测试覆盖视频、场景、网页、缺少元数据和缺少主资源行为。
• CI 测试不依赖 Steam 或真实桌面会话。

不得宣称：

• 场景运行时支持；
• 网页运行时支持；
• 泛 Wayland 支持；
• 超出已验证 Wayland + niri 路径的合成器支持。

v0.8.0：niri 上可靠的视频运行时

主题：让当前运行时路径可靠。

交付内容：

• 强化将视频应用到选定显示器的流程。
• 强化按显示器清除。
• 清除一个显示器时保留其他输出上的壁纸。
• 启动时恢复已保存分配。
• 改进 Desktop 运行时状态，包括活动输出、过期状态、恢复失败和后端初始化/运行时错误。
• 为运行时变更保留有文档说明的手动真实桌面验证清单。

在已验证 Wayland + niri 上的验收标准：

• LWE 能发现活动显示器。
• 已同步视频壁纸可见地应用到一个显示器。
• 在有硬件条件时，多显示器应用可用。
• 清除一个显示器不会停止其他显示器壁纸。
• 重启后恢复已保存分配，或报告明确恢复失败。
• 缺少视频文件、输出不匹配、Wayland layer-shell 失败、EGL 失败和后端超时都会产生可操作错误。

不得宣称：

• niri 之外的运行时可靠性；
• 场景或网页运行时支持；
• CI 已验证桌面运行时行为，除非存在已验证真实桌面 runner。

v0.8.5：Library 工作流强化

主题：让 Library 成为可信赖的日常使用界面。

交付内容：

• Library 卡片和详情面板清晰展示运行时状态。
• Apply 控件受可运行状态和显示器可用性限制。
• 应用、清除和恢复后，已分配显示器标签保持准确。
• 刷新、应用和清除流程尽可能保留用户上下文。
• 空状态、过期状态、不可用状态和部分支持状态易于理解。
• 大型本地库的分页和过滤保持可预期。

验收标准：

• 可运行视频项目易于识别和应用。
• 如果 Library 展示仅识别的场景/网页项目，它们不可应用且解释原因。
• 应用失败不会用死状态替换已填充的详情 UI。
• Library 命令/单元测试不依赖已安装 Steam。
• Desktop invalidation 后 Library 状态正确更新。

不得宣称：

• 所有 Library 项都可运行，除非 UI 强制保证这一点；
• 仅识别的场景/网页项目可通过重新同步变成可运行支持。

v0.9.0：Workshop 与同步清晰度

主题：让发现和获取预期诚实明确。

交付内容：

• 围绕 Steam Web API key 设置打磨 Workshop 搜索和过滤。
• 本地 Workshop 刷新解释已同步、缺少 project.json、缺少主资源和不支持运行时类型。
• “在 Steam 中打开”明确作为获取/订阅交接。
• Settings 清晰展示 Steam 集成状态。
• 在线搜索结果不暗示本地同步或运行时支持。

验收标准：

• 缺少 Steam API key 时引导用户到 Settings。
• Steam 未安装、缺少 Wallpaper Engine、没有 Workshop 内容时尽可能产生不同信息。
• 格式错误的项目元数据不会导致整个目录扫描失败。
• 场景/网页搜索结果标记为已识别/运行时不支持。
• 网络和解析测试避免真实 Steam API 调用。

不得宣称：

• LWE 直接下载 Workshop 内容；
• 搜索结果可见代表本地内容已同步；
• Steam 元数据推断是权威结果。

v0.9.5：诊断、持久化与候选版准备

主题：为可支持的 v1 候选版做准备。

交付内容：

• 用户可复制的诊断界面。
• 验证语言、主题、Steam API key、登录启动偏好和 Workshop 过滤条件的设置持久化。
• 敏感值被隐藏。
• 在文档中加入发布冒烟检查清单。
• 记录包和发布产物预期。

诊断信息应包括：

• 可用时显示 LWE 版本和包类型；
• 可用时显示 OS、会话和合成器线索；
• 显示器发现结果；
• 运行时后端状态或最近后端初始化错误；
• Steam 发现结果；
• Wallpaper Engine Workshop 内容可用性；
• 按兼容性/运行时状态统计的 Library 数量；
• 当前支持范围提醒。

实现说明：除非包管理器或报告者提供信息，否则包类型显示为 unknown/local build；诊断信息不应声称能完美识别环境。

验收标准：

• 设置在重启后保留。
• 诊断信息不会暴露 Steam API key。
• 登录启动不可用状态非致命且可见。
• .deb、.rpm、.AppImage、AUR stable 和 AUR git 发布路径均有文档说明。
• 必需 CI 检查已记录且通过。
• 影响运行时的候选版必须进行手动运行时验证。

不得宣称：

• 诊断是完美的环境检测；
• 登录启动适用于所有桌面、会话和包格式；
• 包安装成功即可保证运行时支持。

v0.9.6：预览性能与缩略图缓存

主题：在存在大量预览资源时，让 Library 和 Workshop 浏览保持流畅。

问题陈述：

• 当前卡片网格可能直接接收 Workshop 自带的 preview.gif 和较大的 preview.jpg 文件。
• Tauri 会把本地路径转换成 asset URL，但前端仍然要求 WebView 解码和渲染原始媒体。
• 当许多卡片同时可见时，动态 GIF 预览尤其昂贵，因为每个文件可能包含大量帧。
• Wallpaper Engine 公开创作者指导将预览资源视为小型、受控的 UI 媒体。LWE 应遵循同样的产品原则，但不应宣称未公开的 Wallpaper Engine 客户端内部实现。

交付内容：

• 引入 LWE 自有的卡片封面缩略图缓存。
• Library 和本地 Workshop 卡片网格使用静态、受控尺寸的缩略图。
• 对动态 GIF 预览，为卡片网格生成静态首帧缩略图。
• 在向卡片网格暴露前，下采样过大的内置预览图。
• 原始预览媒体仅保留给详情视图或未来显式预览动作，不作为默认网格渲染资源。
• 将缩略图缓存命名和存储从已退役的 wayvid 术语迁移到 LWE 缓存命名空间。
• 更新 Tauri asset protocol scope，使前端只能读取所需的 Steam Workshop 路径和 LWE 缩略图缓存路径。
• 尽可能在暴露卡片数据前生成缩略图；当无法避免冷缓存工作时，应保留已知可用的视觉兜底，避免有预览媒体的项目长期显示占位。
• 避免每次选择项目时全量重处理列表；尽可能复用当前 Library/Workshop 投影。
• 添加轻量前端保护，例如 decoding="async" 和稳定图片尺寸。除非静态缩略图仍不足，否则虚拟列表或悬停播放预览作为后续工作处理。

实现说明：

• 优先复用 crates/lwe-library 中的缩略图代码，但应通过现有 Library/Workshop service 和 assembly 流程接入，而不是从 Svelte 直接调用。
• 缓存键应包含源路径和足够的文件身份信息，例如修改时间或大小，以便预览变化后重新生成。
• 缩略图失败应降级到现有占位图，而不是导致整个 Library 或 Workshop 页面失败。
• 生成的缩略图应足够小以适配卡片网格；当前 UI 可接受约 256-320 px 方形目标尺寸。

验收标准：

• Library 卡片网格不渲染原始本地 preview.gif 文件。
• 当已生成缩略图可用时，Library 卡片网格不渲染过大的本地预览图。
• 在显示最大支持分页数量时，包含大量 GIF 的本地 Workshop 内容仍保持响应。
• 热缓存下返回 Library 不会重新生成未变化的缩略图。
• 冷缓存缩略图生成不会让已有预览媒体的项目长期停留在占位图状态。
• 详情面板仍能一致地显示封面或占位图。
• 单元测试覆盖缩略图来源选择、GIF 首帧行为、缓存路径命名、过期缓存重新生成和占位降级。
• 前端测试覆盖缩略图封面路径渲染，同时不回归缺失封面占位行为。
• 手动验证记录在真实桌面会话中 GIF 密集 Library 的前后对比。

不得宣称：

• 未经官方文档支持的 Wallpaper Engine 私有客户端实现细节；
• 卡片网格已完整支持动态预览；
• 在所有 GPU、磁盘或桌面环境上保证性能；
• 场景或网页壁纸运行时支持；
• 独立于 Steam 的 LWE 托管 Workshop 下载。

v0.9.7：Workshop 浏览打磨

主题：在导航和筛选边缘情况下保持 Workshop 页面响应流畅。

交付内容：

• 恢复缓存的在线 Workshop 搜索结果时，不再跳过本地 Workshop 和 Library 标记刷新工作。
• 离开页面时清理待执行的 Workshop 搜索防抖计时器。
• 限制在线 Workshop 搜索结果卡片宽度，避免少量结果时单个卡片横向撑满整个内容区域。
• 让加载骨架屏网格尺寸与最终结果网格保持一致。

验收标准：

• 导航到 Workshop 时，在恢复缓存或异步数据期间，页面壳和搜索控件保持响应。
• 返回已缓存的 Workshop 搜索时，如果本地标记缓存过期，仍会安排必要刷新。
• 只有一个在线搜索结果时，卡片保持正常比例，而不是变成全宽超大卡片。
• pnpm check 通过。

不得宣称：

• Workshop 搜索结果已经同步到本地；
• LWE 直接下载 Workshop 内容；
• 所有合成器或 WebView 性能问题都已修复。

v0.9.8：后台运行时功耗画像

状态：已作为 v0.9.8 发布完成。本版本包含更低的空闲渲染工作量、带缓存的监视器发现、普通页面加载和恢复路径可复用的 Workshop/Library 热快照读取、基于 Rustls 的 Workshop HTTP，以及轻量快照来源诊断。真实桌面功耗测量仍与环境相关，不应泛化到已验证 Wayland + niri 设置之外。

主题：降低 LWE 后台运行时的 CPU 唤醒和不必要工作，尤其是在存在活动视频壁纸时。

问题陈述：

• 当前 engine loop 会按帧间隔唤醒，扫描活动 surface，并为已渲染输出重新注册 frame callback。
• mpv 渲染路径会在热路径检查新帧并 drain mpv events。
• 显示器发现可能在每次请求时 shell out 到 niri msg -j outputs。
• Library 和 Workshop 投影在较便宜的缓存视图足够时，仍可能触发完整目录刷新和兼容性评估。
• 安全扫描当前通过 Tauri Linux GTK/WebKit 栈报告 glib 告警。应跟踪上游 Tauri/GTK 更新路径，不要用不安全的依赖覆盖来掩盖。

交付内容：

• 记录以下场景的 idle/background CPU 唤醒和 CPU 占用基线：
  • 应用打开但未运行壁纸；
  • 一个活动视频壁纸；
  • 应用最小化/后台运行且存在活动壁纸；
  • 热缓存后的 Library/Workshop refresh。
• 增加轻量运行时诊断或日志，暴露 frame pacing、跳帧、活动 surface 数量和后端 event-loop 状态，同时不增加正常路径开销。
• 尽可能减少逐帧 engine 工作：
  • 当 mpv 没有新帧且 surface 无 resize/state change 时避免渲染；
  • 对未变化 surface 避免重复 EGL make-current/resize/swap；
  • frame callback 只绑定到可见/活动壁纸 surface。
• 通过短期缓存或显式 invalidation 降低显示器发现成本，避免频繁调用 niri msg -j outputs。
• 拆分便宜 snapshot 读取和昂贵 Workshop/Library 完整刷新，使页面加载和 restore 流程可复用热投影。
• 持续维护安全依赖卫生：
  • Workshop HTTP 请求使用 Rustls-backed TLS，而不是 OpenSSL-backed native TLS；
  • 跟踪 Tauri/Linux GTK 依赖更新，寻找脱离易受攻击 glib 0.18.x 的受支持路径。

实现说明：

• 功耗优化影响运行时，应优先采用小而可测的改动，并保持当前 niri 视频路径可靠。
• 功耗声明必须基于真实桌面观察。CI 可以覆盖不变量和回归，但不能证明合成器/GPU 功耗行为。
• 优化时不改变支持范围；场景和网页壁纸仍保持仅识别，除非另行实现并验证。
• 不要为了让扫描器安静而对 Tauri 的 GTK 栈做不安全 Cargo patch。只有在行为和打包仍通过验证时，才升级 Tauri 或移除受影响功能。

验收标准：

• 在已验证 Wayland + niri 环境记录优化前后的测量结果。
• 活动视频壁纸不回归已验证路径上的应用、清除、恢复或多显示器行为。
• 手动测量显示 idle/background 路径减少了不必要唤醒或降低 CPU 占用。
• 常规导航中，显示器发现和 Library/Workshop 加载路径避免不必要的重复完整刷新。
• Workshop HTTP 请求的 cargo tree 中不再出现 OpenSSL/native-tls。

不得宣称：

• 所有设备都有电池续航改善；
• 超出已验证 Wayland + niri 路径的合成器支持；
• 场景/网页运行时支持；
• 已在本地修复上游 GTK/WebKit/Tauri 漏洞，除非依赖图确实移动到 fixed 版本。

v0.9.9：Wayland 能力基础设施

状态：已作为 v0.9.9 发布完成。本版本增加轻量 Wayland 能力报告、在动态壁纸运行时启动前进行门控、显式输出发现来源边界（保留 niri 作为已验证路径的增强来源）、协议支持与输出发现来源诊断，以及应用壳专用 WebKitGTK 启动 workaround 文档。

主题：让未来桌面兼容以 Wayland 协议能力为中心，而不是以桌面环境名称为中心。

问题陈述：

• LWE 当前已验证运行时路径是 Wayland + niri，但底层视频运行时更准确地说是 Wayland layer-shell + EGL/mpv 后端。
• 显示器发现目前只具体实现了 niri msg -j outputs，这会让输出可用性看起来像按桌面名称硬编码，而不是按能力判断。
• 其他 Wayland 合成器可能暴露足够协议来运行当前轻量运行时，但是否支持应由协议能力和真实验证决定，而不是泛化桌面环境声明。
• 某些环境（例如 GNOME/Mutter Wayland）可以通过 WebKitGTK workaround 启动应用壳，但可能不暴露动态壁纸所需的 layer-shell 协议。
• 在准备更广泛 Wayland 兼容时，LWE 不应加入 X11 运行时支持，也不应引入重型桌面环境专属依赖。

交付内容：

• 增加轻量 Wayland 能力报告，检查：
  • 是否存在 Wayland 会话并可连接显示；
  • 是否暴露 wl_compositor、wl_output、zwlr_layer_shell_v1 等必要 globals；
  • 动态壁纸运行时是可用、降级还是不支持；
  • 缺少必要协议时给出用户可理解的不支持原因。
• 将显示器发现重新表述为输出发现：
  • 保留 niri 作为已验证路径的增强输出信息来源；
  • 为稳定输出身份足够时的通用 Wayland 输出发现预留服务边界；
  • 避免把桌面环境名称作为主要运行时后端。
• 在启动运行时后端前，用能力报告门控 Desktop apply/restore 路径；缺少必要 Wayland 协议时返回优雅的不支持结果。
• 扩展诊断信息，包含 Wayland 能力数据：
  • 会话线索；
  • 协议可用性；
  • 输出发现来源；
  • 动态壁纸运行时支持状态和不支持原因。
• 记录 GNOME/Mutter WebKitGTK 启动 workaround：WEBKIT_DISABLE_DMABUF_RENDERER=1，并明确它只缓解应用壳启动，不代表壁纸运行时支持。
• 英文和简体中文文档保持诚实支持范围。

实现说明：

• 保持核心轻量：除非未来规划明确论证，否则不引入桌面环境专属 DBus/plugin 集成。
• v1 不规划也不实现 X11 壁纸运行时支持。
• 优先在 lwe-engine 中提供共享 Wayland 能力探测，因为该 crate 已拥有 Wayland client 依赖和 registry 代码。
• 合成器名称只用于诊断、已知问题提示和手动验证记录。
• 缺少 zwlr_layer_shell_v1 的合成器应在运行时启动前优雅失败，而不是尝试不可靠的兜底窗口。
• 在其他 Wayland 能力组合完成手动测试前，已验证路径仍是 Wayland + niri。

验收标准：

• 诊断信息能在当前设备显示 Wayland 能力报告。
• 当前已验证 niri 环境的视频应用、清除、恢复和显示器发现不回归。
• 缺少必要 Wayland 协议时，Desktop apply/restore 在启动壁纸运行时前返回清晰的不支持原因。
• 文档区分应用壳启动 workaround 和动态壁纸运行时支持。
• CI 覆盖能力报告格式和不支持门控，不依赖真实合成器。

不得宣称：

• X11 运行时支持；
• 未经明确验证的 GNOME/KDE/Hyprland/sway 运行时支持；
• 应用壳启动兼容等同于动态壁纸运行时兼容；
• 场景/网页运行时支持；
• 暴露 layer-shell 的每个 Wayland 合成器都自动完成验证。

v1.0.0-rc.1：首个候选版

主题：冻结范围并端到端验证。

交付内容：

• 除阻塞问题外冻结功能。
• 完整审查英文和简体中文文档。
• 起草带明确支持范围的发布说明。
• 通过手动 niri 运行时验收。
• 更新已知限制页面或小节。

验收标准：

• 全套 CI 通过：
  • pnpm check
  • pnpm test
  • pnpm build
  • pnpm docs:build
  • cargo fmt --all -- --check
  • cargo clippy --workspace --all-targets -- -D warnings
  • cargo check --workspace
  • cargo test --workspace
• 新安装 → Settings → Workshop/Library → 应用视频 → 清除 → 重启恢复路径完成手动验证。
• 手动检查场景/网页仅识别行为。
• 没有用户可见文案宣称未支持运行时行为。
• 发布产物构建成功。

不得宣称：

• v1 final 稳定性；
• 广泛合成器支持；
• 场景/网页运行时支持。

v1.0.0-rc.2：可选阻塞修复候选版

主题：仅修复 rc.1 发现的发布阻塞问题。

允许工作：

• 数据丢失修复；
• 安装或启动失败修复；
• 已验证 niri 上视频应用/清除/恢复失败修复；
• 错误支持范围声明修复；
• 包或发布产物阻塞修复；
• 严重文档不一致修复。

验收标准：

• rc.1 阻塞问题已解决。
• 不增加新功能范围。
• 对受影响区域重新进行手动验证。

不得宣称超出 rc.1 范围的新能力。

v1.0.0：稳定 v1

主题：可靠、诚实的首个稳定版本。

v1 交付内容：

• 视频 Wallpaper Engine 壁纸可在已验证 Wayland + niri 路径上运行。
• 场景/网页可用于兼容性报告，但运行时不支持。
• Library-first 日常工作流。
• 通过 Steam 进行 Workshop 发现/获取交接。
• Desktop 显示器应用、清除和恢复流程。
• Settings 持久化与诊断。
• 英文和简体中文维护文档。
• 发布产物：.deb、.rpm、.AppImage、AUR lwe 和 AUR lwe-git。

v1 验收标准：

• 全套 CI 通过。
• 文档构建通过。
• 新安装路径已记录并验证。
• 手动真实桌面 niri 验收通过。
• 不支持的场景/网页行为清楚且不可运行。
• 已知限制已记录。
• 发布说明准确描述支持范围。

v1 不得宣称：

• 完整 Wallpaper Engine 兼容；
• 场景壁纸运行时；
• 网页壁纸运行时；
• 创作者/编辑工具；
• 云或社区功能；
• 高级自动化；
• 泛 Wayland 支持；
• 未经明确验证的 GNOME/KDE/Hyprland/sway 支持；
• 独立于 Steam 的 LWE 托管 Workshop 下载。