项目概览

本页为维护项目及当前开发范围的贡献者提供必要上下文。

产品方向

LWE 是一个 Linux 动态壁纸平台，服务于把实际 Wallpaper Engine 工作流迁移到 Linux 的用户。

产品形态是桌面应用优先，而不是守护进程优先。核心差异化能力是把创意工坊发现、获取编排、同步感知、导入、兼容性可见性和运行时支持整合进同一工作流。

首发范围

首发优先事项：

• 以创意工坊为中心的发现和获取编排；
• 将兼容性报告作为用户可见功能；
• 以本地库为中心的日常使用；
• 视频类壁纸运行时支持；
• 逐项验证的实验性 2D 场景播放；
• 英文和简体中文产品界面；
• 用于应用和清除壁纸的 Linux 桌面集成。

首发非目标：

• 完整网页壁纸运行时兼容；
• 创作者工具；
• 云或社区系统；
• 高级自动化规则；
• 对未验证桌面环境承诺支持。

活跃架构

关键路径：

路径	用途
src/	Svelte/SvelteKit 前端应用
src-tauri/	活跃 Tauri 桌面壳
crates/lwe-core	共享模型、配置和跨领域 Rust 类型
crates/lwe-library	本地库索引、元数据和本地资源管理
crates/lwe-engine	运行时/播放和 Linux 壁纸集成知识
crates/lwe-scene	独立实现的场景包与纹理读取器
packaging/aur/lwe	稳定版 AUR 包元数据
packaging/aur/lwe-git	开发版 AUR 包元数据
.github/workflows/	质量检查、发布和文档部署自动化

已退役的 wayvid GUI/CLI 路径只能作为历史上下文。除非规格明确说明其对 LWE 方向有价值，否则不要重新引入旧产品叙事。

实验性场景路径由 Rust 独立实现，不依赖 Open Wallpaper Engine 运行时。该路径共用 PreparedScene::prepare 进行兼容评估和应用前验证。准备阶段在运行时线程之外读取文件和解码纹理；引擎负责 GL 初始化、呈现确认和清理。缓存的兼容评估仅保留摘要，不能代替应用前验证。未知特性一律阻断播放。

当前渲染器接纳显式固定正交尺寸的 2D 图片层、有界 sprite/rope 粒子及子发射器、包含 Shake、Shine、WaterRipple、Iris 的受支持材质/特效 pass、四 pass LDR 泛光，以及单条 FLAC 循环图层。粒子可保留单图片 TEXS0002 图集帧，进行序列/随机帧选择与序列帧插值；有界平面湍流、透明度/尺寸振荡和角运动共用有限准备、模拟、几何预算与 SceneClock。原版噪声/随机行为一致性尚未验证。保存相机的 eye/center X/Y 相等、朝向负 Z、up 为默认时，按原版静态加载分支观察结果规范化，保存的 X/Y 不必为零。精确 user/value 绑定在类型/范围或选项成员校验后解析 bool/slider/color/combo；combo 条件相等可产生可见性，未知条件及无效默认/覆盖值严格阻断。项目/输出选择在准备前验证，与分配一起原子保存至同一 session。此前在记录的单输出机器上通过的原生 bool/slider 编辑、保存失败回滚/重试、新进程恢复和完整重置，本轮新增 Yakuza combo/颜色编辑、保存失败/重试、重启和重置流程已另行通过原生验收。

旧式静态图片分支在运行时适配本机或项目自带 GLSL，接受 genericimage、双纹理和四纹理两种 flowimage、swayimage 与 flag。对象省略尺寸时使用模型 width/height，保留项目资源优先级、作者自上而下的 UV 数学、图片/存储 padding、受支持的重复/边缘限制纹理标志与 SceneClock 动画。旗帜法线解码按实际绑定的源纹理格式派生 combo。声明式 usershadervalues 把经验证的 bool/slider/color 选择从项目属性映射到材质 uniform；当前 LWE 的用户映射优先于显式材质常量，原程序发生冲突时的精确优先级仍未核实。未知着色器、shader 编译期 combo、运行时依赖、采样标志和映射目标继续阻断。

genericimage2 图片路径接纳缺省 VERSION 的旧版 Brightness/Alpha 接口及显式 VERSION 1/2 Color4 接口，特效后保留 VERSION 2 的作者配置 0/30/31 模式合成。Fullscreen/passthrough、Scroll、Pulse 和有界的项目自带 pass 使用原始、项目优先的资源；完整画面 FBO 快照和命名目标保留各自输入。真实桌面输出 monitor 采集提供归一化的十六档立体声频谱 uniform，仅在分配持久保存与 Finalize 后激活。暂停/回滚渲染器在强制重绘时保留已显示画面的音频输入。这不证明 Windows FFT 分频一致或完整 SceneScript 音频 API 支持。

活动相机路径、自动投影、倾斜/反向/非默认 up、动态相机运动、图层/模型 parent 绑定、不支持的组件/绑定形状、更广泛的 SceneScript/FFT API、HDR 及使用指南中的其他限制仍阻断。Open Wallpaper Engine 源码仅作为行为参考，LWE 不执行其 C++ 运行时。原版噪声、子系统、rope 和完整画面的视觉 A/B 尚未完成。CPU 测试和构建不能证明实际可见播放；真实桌面验收分别记录样本、流程和环境。

纯标量 SceneScript 保留准备 worker 上的 Oxc AST 校验和有界 QuickJS 执行。另一条有界 SceneScript worker 路径支持 init/update/applyUserProperties、有限 Vec3 与图片层状态，以及仅初始化期间的图片模型 createLayer(path)。全部作者对象先保留独立 handle，新层随后获得新 handle；创建资源经过共用准备，引擎只接收已验证快照，并等待快照后才 ACK 首帧。暂停重绘/回滚保留已接纳状态，取消、异常、执行超时、worker 失败和未知能力沿用可逆应用边界。源码/AST、绑定数、总层数、VM 内存/栈及回调时间均有有限上限。仅支持模块全局注册的 registerAudioBuffers(64).average：它是就地更新的 Float32Array，输入来自对桌面输出采样进行的真实 64 档变换，而非扩展十六档数据。Windows 分频、归一化和视觉 FFT 一致性尚未核验。导入、通用动态访问、时钟/随机 API、光标/媒体交互、其他通道/分辨率及更广宿主 API 仍阻断，3420277613 仍需更广脚本与资源。Yakuza 八组背景/音频条 CPU 组合、五组完整 GPU 用例和真实原生 UI 事务已通过，真实私有输出 monitor 经 64 档 FFT、原始脚本至离屏音频条 GPU 的链路也通过，与可见原生 UI 分别验证，不证明用户当前音乐/视频路由，详见开发记录。

共面的 perspective:true 图片层仅限固定正交投影、origin Z=0、无 X/Y 旋转、无相机运动/视差。等效平面变换是依据这些约束作出的数学推断；保留的原二进制证据确认规范相机，但未证实逐层 perspective 映射或视觉一致性。

SceneInventory::collect 是有界的静态依赖/资源结构 API，与 PreparedScene::prepare 的播放资格验证分开。它沿已建模的引用检查资源，扫描包内 JSON/TEX/着色器和项目元数据，区分可达声明与仅存在于包中的声明，记录结构位置与未知形状，并把属性绑定与可执行脚本分开。它不解码纹理/媒体负载或执行 JS。未知/文字子树中看似资源的私有值不能导出；脚本、着色器、文字正文及私有属性值均省略。JSON、着色器、资源、节点、深度、观察/字符串、mip 和动画帧都有明确总预算；预算耗尽或资源失败会产生部分报告。PKG 索引、范围读取与哈希复用同一打开的 descriptor 并检查元数据一致性，不宣称文件系统不可变快照。

P1 首批运行时实现按每输出截止时间限帧，在静态/暂停场景稳定后停止持续 draw/swap/callback，并把当前、候选和保留的回滚资源纳入总计 512 MiB 的逻辑 RGBA 纹理/FBO 与粒子 VBO 预算。图片按尺寸共享临时目标：单个无名 pass 使用一个，多 pass 图使用两个，命名特效与泛光目标单独分配。估计不含驱动开销、EGL 后缓冲或视频内存，不等于实测 VRAM。EGL 所有权覆盖正常与初始化失败清理，初始视频只加载一次。Settings 保存 FPS/电池偏好并更新现有后端；隔离桌面服务 15 → 30 FPS 测试通过，每秒约 14.70 → 29.60 次完成 swap，后端身份与分配字节保留。有限原生英文 Settings/保存/新进程恢复及中文布局复核通过；实际电池/交流电转换、24 小时运行、十次真实休眠恢复、功耗、安装包与独立多显示器验收仍未完成。

已记录的 Scene 桌面验收

2026-10-09 的开发版本在 Wayland + niri、AMD Radeon 680M（1002:1681，amdgpu）与单个 eDP-1 显示器上通过显式启用的 Scene 流程，分辨率为 2160×1440、缩放为 1.25。样本 3337606455 包含一个图片图层、5 个 Shine 特效 pass、总计 6 个 pass；全分辨率截图确认实际可见渲染。三轮 Scene ↔ Video/应用/清除、会话保存失败回滚、commit 已处理后的取消，以及后端关闭/join 后的恢复均通过。原有视频重新应用流程也通过；测试使用隔离配置并恢复先前工作区画面。

这段历史证据仅覆盖单显示器上的一个样本。当时 3258032485 以 unsupported_camera 阻断，其此前截图仅用于研究。2026-10-10 的实现增加 REA 确认的规范相机分支、有界 inventory、帧调度和资源核算。11 项 P0 报告、3337606455 和 3258032485 的原生鼠标 UI 流程、swap 完成率/空闲 Probe 及 100 轮生命周期压力均记录于验收指南。这些流程不证明原引擎视觉一致或日用就绪。

后续 3659880761 原始包准备成功，包含 7 个渲染图层、5 个特效和 21 个 pass。作者默认配置为 6 个可见粒子根系统加 5 个子系统；第七个 Reactive 根系统为字面量 visible:false，保持隐藏，启用其音频响应仍阻断。最大粒子/顶点/work 为 3,965/26,790/30,980。同一单输出 niri/680M 机器最终六十秒 engine-only 桌面 Probe 通过：30 FPS 上限下约 27.95 次完成 swap/s，暂停六十秒期间 draw/swap/callback 均为零，恢复后约 28.33 swap/s，逻辑 GPU 负载为 134,862,328 字节。此 Probe 不写 session。随后原始默认配置的独立原生 UI 流程通过并人工复核英/中文截图：选择显示器应用/Running、同 PID 关闭隐藏、自有进程退出、新进程恢复、目标清除，以及 Settings 15 → 30 FPS 后分配字节不变、偏好恢复。独立原生属性编辑/保存失败/重试/恢复/重置，以及十二秒自有全屏覆盖/揭示也通过；遮挡期间 callback 未测量，休眠/锁屏和日用验收仍未完成。另一次私有 Pulse PCM Probe 确认候选/暂停/静音/drop 阶段无输出，激活后有输出；硬件扬声器及完整音频回滚/硬件输出行为仍未验证。

随后适配的原始 2903458386（2.5D Space）保留十个图片图层、十一个特效和二十四个 pass。十四段原始标量脚本通过七十个默认/边界/零值/混合属性 CPU 用例，十二个原始着色器程序以 GL 130 链接成功。同一单输出 niri/680M 机器上，真实 Library/Desktop 应用、全部二十个控件（十六 slider、三 bool、一 color）、原子保存失败回滚/重试、新进程恢复、完整重置、Settings 15 → 30 FPS、十二秒自有全屏恢复和清除通过。颜色编辑使用已渲染输入控件的事件，未操作系统颜色选择器。最终十二秒引擎 Probe 在 30 FPS 上限下约 27.25 次完成 swap/s，暂停十二秒 draw/swap/callback 均为零，恢复后约 27.33/s；逻辑 GPU 负载为 202,180,100 字节。真实 monitor 的立体声/暂停/恢复/清理测试须与原引擎视觉/FFT 一致性和日用长时间运行区分，详见 Space 记录。

独立 CPU 门控通过本机十四个官方内置项目中的三个：Deep Space（deep_space，两层/两个 pass）、Beach（beach，三层/三个 pass）和 Eagle Flag（eagleflag，一层/一个 pass）；其余首项阻断为六项相机、四项 SceneScript 和一项模型。同一单输出 niri/680M 机器上，每个原始项目均通过十秒 engine-only 播放，30 FPS 上限下分别约 29.60、29.60 和 29.70 次完成 swap/s。各暂停十秒期间 draw/swap/callback 均为零，恢复三秒均约 29.67 swap/s；清除移除输出 metrics，后端关闭已 join。成对桌面截图确认可见运动，并人工复核画面；检查的 66 个原始资源文件及用户配置未改变，Probe 不写 session。工作区清理需修正命令，私有报告保留首轮失败及已验证的恢复。这些官方项目与 Workshop 3/11 语料独立，尚未加入本地库。这是有限引擎验收，不代表 builtin 原生 UI/持久化、原引擎 A/B、24 小时日用、独立多显示器或真实电池验收完成。

历史 2026-10-10 只读 CPU 门控复跑通过 3258032485、3337606455 和 3659880761（3/11），其余八项的首项阻断为五项 SceneScript、相机（2798622011）、HDR（2454418355）和图层数量上限（3485147659）。11 个原包 SHA-256 均与 P0 inventory 一致。此前 2/11 和 3659880761 泛光阻断属于历史快照，其默认原始包现在通过准备。复跑使用已记录的 scene_prepare 编译产物与本机 builtins，没有构建或启动桌面。本地数量是首项阻断快照，不代表全部依赖或整个 Workshop 比例。此前 100 轮生命周期通过时，测试进程 RSS 同时上升。后续 CPU/Scene/视频/混合/重启 Probe 显示释放后 Rust 活跃计数小或固定，视频/混合模式有大量 glibc 空闲块保留。轮数、内存压力、swap/文件页及未测原生分配使其不足以支持生产内存稳定性结论。验收记录保留确切计数与限制；进程 RSS 不是应用专属内存或实测 VRAM。 新增 20 轮 3659880761 → 视频 → 3659880761 → 清除 Probe 通过，清除后的 FD/Rust 活跃字节固定且关闭已 join；RSS 与分配器保留仍不足以支持内存稳定或原生无泄漏声明。

发布模型

渠道	输出
稳定版	GitHub Release 构建产物和 AUR lwe
预发布版	GitHub prerelease 构建产物和 AUR lwe-git

Linux 发布产物包括 .deb、.rpm 和 .AppImage。

工作区版本来源是 Cargo.toml。预发布版本由发布自动化根据基础版本、GitHub Actions 运行编号和短提交 SHA 派生。

v0.9.10 打包修复

v0.9.10 的打包维护修复 AppImage 图标链接并更新受支持的构建工具链。.tauri-cli-version 为两条发布渠道固定 CLI，rust-toolchain.toml 固定 Rust 构建工具链，上传门禁在发布前检查真实 AppImage。版本可用性以 GitHub Releases 为准。公开产物验证、niri 上的安装验收和 AppImage 目录复测是独立发布步骤。该打包阶段当时保持 Wayland + niri 上视频壁纸的运行时范围。

文档模型

所有维护中的文档都应位于 docs/ 下，并作为 VitePress 站点发布。用户可见文档必须同时提供英文和简体中文版本。

文档应优先覆盖：

1. 安装；
2. 首次使用设置；
3. 日常使用；
4. 故障排查；
5. 贡献者维护规则。

历史规划文档和过时实现说明不应继续保留在发布文档树中；其中仍有价值的信息应合并进维护中的页面。