[提案] 支持导入 Wallpaper Engine 的视频 / 网页壁纸（征求意见，暂未写代码）

[liziye627-design]

你好 @ayuayue，感谢之前合并 #399。我们想在 PiDeck 现有的壁纸功能上做一个扩展：从用户本机已订阅的 Wallpaper Engine 创意工坊目录里导入视频和网页类型的壁纸作为背景。动手前先来问问你是否欢迎这个方向，以及你对设计的偏好。你点头之前我们不会提 PR。

目标

很多用户本地已经有 Wallpaper Engine 订阅的壁纸。希望 PiDeck 能直接把其中的动态壁纸用作工作台背景，并且继续沿用现有的透明度档位，让面板透出壁纸。

范围

做：

• 由用户在设置里选择 Wallpaper Engine 的创意工坊目录（steamapps/workshop/content/431960/）。能自动检测到 Steam 目录就预填，检测不到就让用户手动选。
• 读取每个子目录里的 project.json，只取 title、type、file、preview、general.properties 这几个字段，用来列出和预览壁纸。
• 分两期，由你决定是否都做：
  • 第一期：只做 type: video。
  • 第二期：type: web（会运行第三方 HTML/JS，隔离方案见下文）。

不做：

• scene 类型（scene.pkg 是 Wallpaper Engine 的私有格式）和 application 类型（外部 exe）。
• 不调用 Steam API，不下载、不订阅工坊内容。
• 不复制、不分发任何工坊文件，只在原位置读取，userData 里只存目录路径和选中的壁纸 ID。
• 不复用 linux-wallpaperengine、Open Wallpaper Engine 等项目的代码（它们是 GPL-3.0，PiDeck 是 MIT），只参考公开的文件格式。

视频和网页壁纸本身就是普通文件，所以在 macOS、Linux 上只要能访问到这些文件（比如从 Windows 拷来的目录或共享盘）也能播放。不过 Wallpaper Engine 和 Steam 订阅本身只在 Windows 上。

设计草图（尽量贴合现有实现）

1. 视频协议：视频需要 Range 请求和流式读取，否则大视频会整块常驻内存。现有的 pideck-bg:// 是 readFile 整个读入，注册时 stream: false，只适合静态图。我们考虑的方案按优先级排列：
   • 方案 A（首选）：沿用 pideck-video://（src/main/videogen/VideoGenProtocol.ts）的做法，或直接复用它。它已经通过 createReadStream 和单区间 Range 流式输出给 <video>，引用名走白名单正则，视频字节不进 IPC，主窗口 CSP 的 media-src 也已经允许 pideck-video:。壁纸这边同样只传白名单引用名，主进程再解析到用户选定的工坊目录里，并做路径逃逸检查。
   • 方案 B：把 pideck-bg:// 放开到用户明确选择的那一个工坊目录，同时改成流式输出。
   • 方案 C：新开一个专用协议（比如 pideck-we://）。
2. IPC：只加少量窄通道，比如"选择工坊目录""列出可用壁纸（只返回解析后的元数据）""选中某个壁纸"，类型都放在 src/shared。渲染进程拿不到任意路径。
3. 渲染：
   • 视频：放一个 <video muted loop playsinline> 作为背景层，透明度继续走 useAppAppearance.ts 的现有档位，不改动现有的静态图逻辑和 wallpaperThemeSync 的契约测试，只为新类型补测试。
   • 网页（第二期）：复用现有的 pideck-html://（src/main/htmlPreviewProtocol.ts）。它用沙箱 <iframe>，CSP 由主进程通过响应头下发，和主窗口策略解耦（bug: HTML 预览窗 (FileDiffViewer) 中内联 JavaScript 无法执行，被主窗口 CSP 拦截 #377）。壁纸不开 Node integration，不暴露 preload 和 IPC。现在文件预览用的 CSP 允许 'unsafe-inline' 和 'unsafe-eval'，壁纸会沿用同一套机制，但单独下发一份不允许联网的 CSP，只允许加载该壁纸目录里的资源。general.properties 这类用户属性暂时只用默认值，不做属性编辑器。

内存 / CPU 计划

• 窗口失焦、最小化或被遮挡时暂停视频（网页壁纸也会暂停或降帧）。
• 按屏幕分辨率显示，不额外缓存大图或多份解码结果。
• 全局只保留一个壁纸实例，切换时先释放旧实例。
• 用仓库自带的 PIDECK_MEMORY_PROFILE=1 和 scripts/analyze-memory.mjs 做前后对比：无壁纸、静态图壁纸、视频壁纸三种情况各测一次，结果连同测试环境（系统、分辨率、视频规格）一起贴出来。目前我们还没有测出任何数字，所以这里不写具体指标。

测试范围（如实说明）

我们这边的开发环境是没有显示器的 Linux。这里只能用自己构造的 project.json 样例和测试视频，验证解析、协议和播放逻辑。真实的 Windows + Steam 工坊目录会由我们的成员在自己的 Windows 电脑上验证，PR 里会写清楚哪些是在什么环境测的。

想请你确认的问题

1. 你是否欢迎这个功能进入 PiDeck？还是更希望做成插件？
2. 视频协议：你倾向于方案 A（沿用或复用 pideck-video:// 的模式），方案 B（放开 pideck-bg:// 并改成流式），还是方案 C（新开协议）？网页壁纸复用 pideck-html:// 加一份独立的无网络 CSP，你能接受吗？
3. 是否同意先只做视频（第一期）？网页壁纸（第二期）要不要做，隔离方案你能接受到什么程度？
4. 设置页的入口放在现有的外观 / 壁纸设置里可以吗？
5. 动态壁纸要不要默认关闭，或者在低电量 / 省电模式下自动停用？

关于 AI 辅助

这个提案和后续的代码会在 AI 辅助下完成，由人审核。PR 里会如实写明哪些测试实际跑过、在什么环境下跑的，提交前会按 CONTRIBUTING 跑 npm run typecheck 和 npm run build，并提到 dev 分支。

---

English summary: We propose letting PiDeck import Wallpaper Engine video wallpapers (phase 1) and, optionally, web wallpapers (phase 2) from a workshop folder the user picks (steamapps/workshop/content/431960). We'd read only project.json and play the files in place, with no copying or redistribution, no Steam API, and no scene or application types. For video we'd preferably follow or reuse the existing pideck-video:// pattern (streaming with Range, whitelisted refs, no video bytes over IPC). The alternatives are widening pideck-bg:// to that one folder (today it uses readFile with stream:false) or a new protocol. Web wallpapers would reuse the sandboxed pideck-html:// iframe with a separate, no-network response-header CSP, and no Node integration or IPC. Memory would be benchmarked before and after with PiDeck's own PIDECK_MEMORY_PROFILE tool; we have no numbers yet. We'd test on headless Linux with sample files, and on a real Windows/Steam PC before the PR. The work is AI-assisted and human-reviewed. No code until you agree.

[ayuayue]

可以啊，我觉得挺好的，设计好，实现完整，测试充分就可以pr，我这边会合并的

[ayuayue]

你好 @ayuayue，感谢之前合并 #399。我们想在 PiDeck 现有的壁纸功能上做一个扩展：从用户本机已订阅的 Wallpaper Engine 创意工坊目录里导入视频和网页类型的壁纸作为背景。动手前先来问问你是否欢迎这个方向，以及你对设计的偏好。你点头之前我们不会提 PR。

目标

很多用户本地已经有 Wallpaper Engine 订阅的壁纸。希望 PiDeck 能直接把其中的动态壁纸用作工作台背景，并且继续沿用现有的透明度档位，让面板透出壁纸。

范围

做：

• 由用户在设置里选择 Wallpaper Engine 的创意工坊目录（steamapps/workshop/content/431960/）。能自动检测到 Steam 目录就预填，检测不到就让用户手动选。

• 读取每个子目录里的 project.json，只取 title、type、file、preview、general.properties 这几个字段，用来列出和预览壁纸。

• 分两期，由你决定是否都做：

  • 第一期：只做 type: video。
  • 第二期：type: web（会运行第三方 HTML/JS，隔离方案见下文）。

不做：

• scene 类型（scene.pkg 是 Wallpaper Engine 的私有格式）和 application 类型（外部 exe）。
• 不调用 Steam API，不下载、不订阅工坊内容。
• 不复制、不分发任何工坊文件，只在原位置读取，userData 里只存目录路径和选中的壁纸 ID。
• 不复用 linux-wallpaperengine、Open Wallpaper Engine 等项目的代码（它们是 GPL-3.0，PiDeck 是 MIT），只参考公开的文件格式。

视频和网页壁纸本身就是普通文件，所以在 macOS、Linux 上只要能访问到这些文件（比如从 Windows 拷来的目录或共享盘）也能播放。不过 Wallpaper Engine 和 Steam 订阅本身只在 Windows 上。

设计草图（尽量贴合现有实现）

1. 视频协议：视频需要 Range 请求和流式读取，否则大视频会整块常驻内存。现有的 pideck-bg:// 是 readFile 整个读入，注册时 stream: false，只适合静态图。我们考虑的方案按优先级排列：

   • 方案 A（首选）：沿用 pideck-video://（src/main/videogen/VideoGenProtocol.ts）的做法，或直接复用它。它已经通过 createReadStream 和单区间 Range 流式输出给 <video>，引用名走白名单正则，视频字节不进 IPC，主窗口 CSP 的 media-src 也已经允许 pideck-video:。壁纸这边同样只传白名单引用名，主进程再解析到用户选定的工坊目录里，并做路径逃逸检查。
   • 方案 B：把 pideck-bg:// 放开到用户明确选择的那一个工坊目录，同时改成流式输出。
   • 方案 C：新开一个专用协议（比如 pideck-we://）。

2. IPC：只加少量窄通道，比如"选择工坊目录""列出可用壁纸（只返回解析后的元数据）""选中某个壁纸"，类型都放在 src/shared。渲染进程拿不到任意路径。

3. 渲染：

   • 视频：放一个 <video muted loop playsinline> 作为背景层，透明度继续走 useAppAppearance.ts 的现有档位，不改动现有的静态图逻辑和 wallpaperThemeSync 的契约测试，只为新类型补测试。
   • 网页（第二期）：复用现有的 pideck-html://（src/main/htmlPreviewProtocol.ts）。它用沙箱 <iframe>，CSP 由主进程通过响应头下发，和主窗口策略解耦（bug: HTML 预览窗 (FileDiffViewer) 中内联 JavaScript 无法执行，被主窗口 CSP 拦截 #377）。壁纸不开 Node integration，不暴露 preload 和 IPC。现在文件预览用的 CSP 允许 'unsafe-inline' 和 'unsafe-eval'，壁纸会沿用同一套机制，但单独下发一份不允许联网的 CSP，只允许加载该壁纸目录里的资源。general.properties 这类用户属性暂时只用默认值，不做属性编辑器。

内存 / CPU 计划

• 窗口失焦、最小化或被遮挡时暂停视频（网页壁纸也会暂停或降帧）。
• 按屏幕分辨率显示，不额外缓存大图或多份解码结果。
• 全局只保留一个壁纸实例，切换时先释放旧实例。
• 用仓库自带的 PIDECK_MEMORY_PROFILE=1 和 scripts/analyze-memory.mjs 做前后对比：无壁纸、静态图壁纸、视频壁纸三种情况各测一次，结果连同测试环境（系统、分辨率、视频规格）一起贴出来。目前我们还没有测出任何数字，所以这里不写具体指标。

测试范围（如实说明）

我们这边的开发环境是没有显示器的 Linux。这里只能用自己构造的 project.json 样例和测试视频，验证解析、协议和播放逻辑。真实的 Windows + Steam 工坊目录会由我们的成员在自己的 Windows 电脑上验证，PR 里会写清楚哪些是在什么环境测的。

想请你确认的问题

1. 你是否欢迎这个功能进入 PiDeck？还是更希望做成插件？
2. 视频协议：你倾向于方案 A（沿用或复用 pideck-video:// 的模式），方案 B（放开 pideck-bg:// 并改成流式），还是方案 C（新开协议）？网页壁纸复用 pideck-html:// 加一份独立的无网络 CSP，你能接受吗？
3. 是否同意先只做视频（第一期）？网页壁纸（第二期）要不要做，隔离方案你能接受到什么程度？
4. 设置页的入口放在现有的外观 / 壁纸设置里可以吗？
5. 动态壁纸要不要默认关闭，或者在低电量 / 省电模式下自动停用？

关于 AI 辅助

这个提案和后续的代码会在 AI 辅助下完成，由人审核。PR 里会如实写明哪些测试实际跑过、在什么环境下跑的，提交前会按 CONTRIBUTING 跑 npm run typecheck 和 npm run build，并提到 dev 分支。

English summary: We propose letting PiDeck import Wallpaper Engine video wallpapers (phase 1) and, optionally, web wallpapers (phase 2) from a workshop folder the user picks (steamapps/workshop/content/431960). We'd read only project.json and play the files in place, with no copying or redistribution, no Steam API, and no scene or application types. For video we'd preferably follow or reuse the existing pideck-video:// pattern (streaming with Range, whitelisted refs, no video bytes over IPC). The alternatives are widening pideck-bg:// to that one folder (today it uses readFile with stream:false) or a new protocol. Web wallpapers would reuse the sandboxed pideck-html:// iframe with a separate, no-network response-header CSP, and no Node integration or IPC. Memory would be benchmarked before and after with PiDeck's own PIDECK_MEMORY_PROFILE tool; we have no numbers yet. We'd test on headless Linux with sample files, and on a real Windows/Steam PC before the PR. The work is AI-assisted and human-reviewed. No code until you agree.

已回复