dsh-wallpaper_share 26.8.23 → 26.8.26-T

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +255 -251
  2. package/lib/client.js +627 -145
  3. package/lib/client.js.map +1 -1
  4. package/lib/index.js +190 -58
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,251 +1,255 @@
1
- # dsh-wallpaper_share · Wallpaper Engine ↔ DeepSeek Harness 壁纸同步
2
-
3
-
4
- https://github.com/user-attachments/assets/4461d385-de62-42be-8420-7edce5606f44
5
-
6
-
7
-
8
- [中文](#中文) | [English](#english)
9
-
10
- 把 Wallpaper Engine 当前显示的壁纸实时同步为 DeepSeek Harness Web 界面的背景（磨砂玻璃风格），并提供 `wallpaper_share` 会话视图标签页用于控制显示器来源、透明度 / 模糊 / 阴影、渲染模式与专注模式。
11
-
12
- > **纯显示同步**：只读取 WE 状态，不控制 / 不修改桌面壁纸（换壁纸请在 WE 内操作）。
13
- > **无敏感信息**：代码不含 Steam 用户名 / SteamID / 令牌；WE 安装目录运行时自动检测（注册表 `HKCU\Software\WallpaperEngine\installPath` → 常见 Steam 路径），检测不到时才需要手动配置。
14
-
15
- ---
16
-
17
- <a name="中文"></a>
18
- # 中文
19
-
20
- ## 增强模式兼容矩阵
21
-
22
- | 壁纸类型 | 增强模式行为 |
23
- | --- | --- |
24
- | `video` | 播放源视频（支持 HTTP Range，可正常 seek） |
25
- | `web` | iframe 加载源页面 |
26
- | `image` | 显示源图 |
27
- | `scene` | **浏览器子集渲染器**（默认）：真实图层树 + transform + 已解码纹理 / 粒子 / puppet 动画合成进 canvas；或**外部 renderer**（`sceneRendererPath` + WS 帧流）；renderer 不可用/失败 → 提取 pkg 内嵌高清纹理 → 预览 |
28
- | `application` / `other` | 回退静态预览 |
29
-
30
- > scene 增强的完整 fallback 链与各层实现（渲染模式 / 纹理解码 / 粒子 / puppet）见 **[docs/scene-fallback.md](docs/scene-fallback.md)**。
31
-
32
- ## 功能
33
-
34
- - **实时同步**：在 Wallpaper Engine 中应用壁纸后，页面背景约 2 秒内自动跟随
35
- - **多显示器**：自动跟随"最近变化"的一台；复数显示器时可手动锁定某台作为背景来源
36
- - **视觉效果滑块（即时生效）**：面板透明度 0–100% / 背景模糊 0–30px / 阴影深度 0–100%
37
- - **渲染模式切换**：性能（静态预览图，默认）⇄ 增强（加载壁纸源内容）
38
- - **Scene 实时渲染（新增）**：scene 壁纸增强模式默认走**浏览器子集渲染器**（真实 `scene.json` 图层树 + transform + 已解码纹理合成进 canvas，含粒子与 puppet 动画）；显式配置 `sceneRendererPath` 后走独立 renderer 子进程（offscreen，不弹窗）→ WebSocket 帧流；完整回退链见 [docs/scene-fallback.md](docs/scene-fallback.md)
39
- - **专注模式 🎯**：任务进行中自动切换为 30% / 15px / 90%，任务完成后自动切换为 9% / 6px / 40%
40
- - **同步开关** ⏻ 一键启停
41
- - 自诊断路由 `/we-sync/diag`（仅本机可访问，含 scene renderer 状态与纹理提取结果）
42
-
43
- ## 安装（官方 `dsh plugin` 通道，零手工配置）
44
-
45
- > 前置：DSH 已用 `dsh --profile web` 启动过至少一次。
46
-
47
- ```bash
48
- # 任选其一：
49
- dsh plugin --profile web add github:YRN-playmaker/dsh-wallpaper_share
50
- # 从 GitHub 安装（仓库自带预构建 lib/，不需要构建许可）
51
- dsh plugin --profile web add dsh-wallpaper_share
52
- # 从 npm 安装（发布后）
53
- dsh plugin --profile web add ./dsh-wallpaper_share-0.2.0.tgz
54
- # 本地 tarball 安装
55
- ```
56
-
57
- ```bash
58
- # 安装 test 分支（最新开发版，含 Scene 渲染 / 粒子 / puppet 动画）：
59
- dsh plugin --profile web add github:YRN-playmaker/dsh-wallpaper_share#test
60
- ```
61
-
62
- ```bash
63
- # 重启 dsh（web profile），打开页面即可看到 wallpaper_share 标签页
64
- ```
65
-
66
- **无需手动编辑任何配置文件**：包内 `dsh.bundle.patch` 指向的 `cordis.patch.yml` 会在安装时自动加入 profile 的 bundle 层，其中一行同时是 host 行（node 半：轮询 + HTTP 路由）和 `dsh.client` roster 行（浏览器半的预构建 `lib/client.js` 由模块系统自动注入页面）。包发布时**自带预构建产物**，用户侧零构建。
67
-
68
- ## 从源码构建（开发者）
69
-
70
- 1. 把本仓库根目录（`package.json` / `src/` / `tsconfig.json` / `tsdown.config.ts`）拷入你的 DSH checkout：`packages/client/we-sync/`；
71
- 2. `pnpm install`
72
- 3. `pnpm --filter dsh-wallpaper_share exec tsc -b`
73
- 4. `pnpm --filter dsh-wallpaper_share bundle`
74
- 5. 产物在 `packages/client/we-sync/lib/`（`index.js` node 半 + `client.js` 浏览器半），拷回本仓库 `lib/` 后 `pnpm pack` 出新 tarball。
75
-
76
- > 也可以在本仓库根目录直接 `pnpm install && pnpm build`（`tsdown` 独立构建，不依赖 DSH checkout）。
77
-
78
- ## 配置
79
-
80
- 包源码 `src/index.ts` 顶部 `CONFIG`：
81
-
82
- | 配置项 | 默认值 | 说明 |
83
- | --- | --- | --- |
84
- | `wallpaperEngineDir` | `''`（自动检测） | 检测失败时手动指定安装目录 |
85
- | `workshopContentDir` | `''`（自动推导） | 工作坊内容目录 |
86
- | `pollIntervalMs` | `2000` | 轮询间隔 |
87
- | `previewMaxBytes` | `6291456` | 预览图大小上限 |
88
- | `sceneRendererPath` | `''`（内置参考 renderer） | 外部 scene renderer 可执行文件；留空用内置参考 renderer（诊断动画） |
89
- | `wallpaperEngineAssetsDir` | `''`（自动推导） | WE engine assets 目录（自动为 `<weDir>/assets`；缺失时 renderer 不可用） |
90
- | `sceneRenderWidth` | `1920` | scene renderer 输出宽度 |
91
- | `sceneRenderHeight` | `1080` | scene renderer 输出高度 |
92
- | `sceneRenderFps` | `30` | scene renderer 目标帧率 |
93
- | `sceneRenderQuality` | `80` | JPEG/WebP 帧质量（0..100） |
94
- | `sceneRenderMode` | `'auto'` | `'auto'`（浏览器子集渲染器为主；配置了 `sceneRendererPath` 则 external）\| `'browser'` \| `'external'` |
95
- | `particleRateScale` | `1` | 粒子发射率缩放（WE rate 单位 = 每秒粒子数） |
96
- | `particleSizeScale` | `1` | 粒子尺寸缩放 |
97
-
98
- ## 排查
99
-
100
- - `http://127.0.0.1:3080/we-sync/diag`：内部状态（`kind` / `fingerprint` / `weDir` / `lastError` / 每台显示器的 `sceneImage` 提取结果 / **scene renderer 的 capabilities / status / fallback 层**）；
101
- - `lastError` 提示未找到安装目录 → 在包源码 `CONFIG.wallpaperEngineDir` 手动指定后重新构建 / 重新安装；
102
- - scene 增强无动态画面 → 看 `scene.available`：`false` 表示 renderer 缺失或 assets 目录缺失（`/we-sync/diag` 里有 `reason`）；
103
- - 页面没变化 → 刷新页面，确认标签栏出现 `wallpaper_share`。
104
-
105
- ## 已知限制
106
-
107
- - scene 增强的"真实动态画面"取决于渲染模式：默认浏览器子集渲染器做**图层树 + transform + 纹理/粒子/puppet 动画合成**（shader effect / SceneScript / keyframe 动画为后续）；外部 renderer（`sceneRendererPath`）可提供真实渲染，但需用户自备（如 WSL2 封装的 linux-wallpaperengine 离屏封装，GPL，独立组件）；
108
- - 参考 renderer 为 1920×1080 RGBA 全帧传输，CPU 占用偏高（本机实测 ~24-27fps @960×540）；真 renderer 建议输出 JPEG/WebP 以降低带宽；
109
- - 多显示器时取 `lastselectedmonitor`（无则第一台）；
110
- - 视觉参数仅保存在页面内存，刷新回到默认值（72% / 6px / 30%）。
111
-
112
- ## 目录
113
-
114
- - `package.json` — 包清单：`dsh.bundle.patch` → `cordis.patch.yml`，`dsh.client` → 浏览器半，`exports["./client"]` → 预构建 `lib/client.js`
115
- - `cordis.patch.yml` — bundle 补丁层（host 行 + dsh.client roster 行）
116
- - `src/index.ts` — node 半源码（轮询 / HTTP 路由 / scene 纹理提取 / HTTP Range / SceneAdapter 接入 / SceneModel 路由 / WebSocket 帧流）
117
- - `src/scene/` — SceneAdapter 模块（协议 / 能力探测 / renderer 进程 / WebSocket / fallback / **PKGV0001 解析 / SceneModel 图层模型 / .tex 解码 / puppet mdl 解析**）
118
- - `src/client/` — 浏览器半源码（主题覆盖 / 背景层 / SceneCanvas / **SceneModelRenderer 子集渲染器 / ParticleRuntime** / wallpaper_share 面板）
119
- - `docs/` — 格式与实现文档（`tex-format-findings.md` / `mdl-skinning-findings.md` / **`scene-fallback.md`**）
120
- - `tools/scene-renderer/` — 内置参考 renderer（协议契约实现；真 renderer 按同协议替换）
121
- - `lib/` — 预构建产物（用户零构建；GitHub 安装也无需构建许可）
122
- - `dsh-wallpaper_share-0.2.0.tgz` — 发布 tarball（GitHub Release 附件）
123
- - `install.ps1` — 可选的一键安装脚本（走官方 `dsh plugin add` 通道）
124
- - `CHANGELOG.md` — 更新记录
125
-
126
- ## 许可证
127
-
128
- gplv3
129
-
130
- ---
131
-
132
- <a name="english"></a>
133
-
134
-
135
-
136
- # English
137
- <img width="1920" height="1080" alt="deepseek21" src="https://github.com/user-attachments/assets/4edaa26e-c5da-4801-b7b3-5ba04cd28184" />
138
- Sync the wallpaper currently displayed by Wallpaper Engine onto the DeepSeek Harness Web UI as a frosted-glass page background (display-only), with a `wallpaper_share` conversation-view tab for monitor selection, transparency / blur / shadow sliders, render-mode, and focus mode.
139
-
140
- > **Display-only**: reads WE state only — never controls or changes your desktop wallpaper.
141
- > **No sensitive data**: no Steam username / SteamID / tokens. The WE install dir is auto-detected at runtime (registry `HKCU\Software\WallpaperEngine\installPath` → common Steam paths); manual config is only a fallback.
142
-
143
- ## Enhanced-mode compatibility matrix
144
-
145
- | Wallpaper type | Enhanced-mode behavior |
146
- | --- | --- |
147
- | `video` | plays the source video (HTTP Range supported, so seeking works) |
148
- | `web` | loads the source page in an iframe |
149
- | `image` | shows the source image |
150
- | `scene` | **browser subset renderer** (default): real layer tree + transforms + decoded textures / particles / puppet animations composited into canvas; or **external renderer** (`sceneRendererPath` + WS frame stream); renderer unavailable/failed → extracted pkg texture → preview |
151
- | `application` / `other` | falls back to the static preview |
152
-
153
- > The full scene fallback chain and per-layer implementation (render modes / texture decoding / particles / puppet) is documented in **[docs/scene-fallback.md](docs/scene-fallback.md)**.
154
-
155
- ## Features
156
-
157
- - **Live sync**: after applying a wallpaper in Wallpaper Engine, the page background follows within ~2 seconds
158
- - **Multi-monitor**: follows the "most recently changed" monitor automatically; lock one as the background source when several monitors exist
159
- - **Instant visual sliders**: panel transparency 0–100% / background blur 0–30px / shadow depth 0–100%
160
- - **Render-mode toggle**: Performance (static preview, default) ⇄ Enhanced (loads the wallpaper source)
161
- - **Scene live rendering (new)**: scene wallpapers in enhanced mode use the **browser subset renderer** by default (real `scene.json` layer tree + transforms + decoded textures composited into canvas, including particles and puppet animations); with `sceneRendererPath` configured it runs a standalone renderer subprocess (offscreen, no window) → WebSocket frame stream; full fallback chain in [docs/scene-fallback.md](docs/scene-fallback.md)
162
- - **Focus mode 🎯**: auto-switches to 30% / 15px / 90% while a task runs, then 9% / 6px / 40% when all tasks finish
163
- - **Sync toggle** ⏻ one-click on/off
164
- - Self-diagnostic route `/we-sync/diag` (localhost only, includes scene renderer status and texture extraction results)
165
-
166
- ## Install (official `dsh plugin` flow, zero manual config)
167
-
168
- > Prerequisite: DSH has been started at least once with `dsh --profile web`.
169
-
170
- ```bash
171
- # Pick one:
172
- dsh plugin --profile web add github:YRN-playmaker/dsh-wallpaper_share
173
- # install from GitHub (the repo ships prebuilt lib/, no build allowance needed)
174
- dsh plugin --profile web add dsh-wallpaper_share
175
- # install from npm (once published)
176
- dsh plugin --profile web add ./dsh-wallpaper_share-0.2.0.tgz
177
- # install from the local tarball
178
- ```
179
-
180
- ```bash
181
- # Install the test branch (latest dev build: Scene rendering / particles / puppet animations):
182
- dsh plugin --profile web add github:YRN-playmaker/dsh-wallpaper_share#test
183
- ```
184
-
185
- ```bash
186
- # Restart dsh (web profile) and open the page — the wallpaper_share tab appears
187
- ```
188
-
189
- **No config files to edit by hand**: the `cordis.patch.yml` referenced by `dsh.bundle.patch` is added to the profile's bundle layers automatically on install. Its single row is both a host row (node half: polling + HTTP routes) and a `dsh.client` roster row (the prebuilt browser half `lib/client.js` is injected into the page by the module system). The published package ships **prebuilt artifacts**, so users never build anything.
190
-
191
- ## Build from source (developers)
192
-
193
- 1. Copy the repo root (`package.json` / `src/` / `tsconfig.json` / `tsdown.config.ts`) into your DSH checkout as `packages/client/we-sync/`;
194
- 2. `pnpm install`
195
- 3. `pnpm --filter dsh-wallpaper_share exec tsc -b`
196
- 4. `pnpm --filter dsh-wallpaper_share bundle`
197
- 5. Artifacts land in `packages/client/we-sync/lib/` (`index.js` node half + `client.js` browser half); copy them back to the repo `lib/` and run `pnpm pack` for a new tarball.
198
-
199
- > You can also run `pnpm install && pnpm build` directly in this repo root (`tsdown` standalone build, no DSH checkout required).
200
-
201
- ## Configuration
202
-
203
- `CONFIG` at the top of `src/index.ts`:
204
-
205
- | Key | Default | Meaning |
206
- | --- | --- | --- |
207
- | `wallpaperEngineDir` | `''` (auto-detect) | Manual install dir when detection fails |
208
- | `workshopContentDir` | `''` (auto-derived) | Workshop content directory |
209
- | `pollIntervalMs` | `2000` | Polling interval |
210
- | `previewMaxBytes` | `6291456` | Preview size cap |
211
- | `sceneRendererPath` | `''` (built-in reference renderer) | External scene renderer executable; empty = built-in reference renderer (diagnostic animation) |
212
- | `wallpaperEngineAssetsDir` | `''` (auto-derived) | WE engine assets dir (`<weDir>/assets`; renderer unavailable when missing) |
213
- | `sceneRenderWidth` | `1920` | Scene renderer output width |
214
- | `sceneRenderHeight` | `1080` | Scene renderer output height |
215
- | `sceneRenderFps` | `30` | Scene renderer target FPS |
216
- | `sceneRenderQuality` | `80` | JPEG/WebP frame quality (0..100) |
217
- | `sceneRenderMode` | `'auto'` | `'auto'` (browser subset renderer by default; external when `sceneRendererPath` set) \| `'browser'` \| `'external'` |
218
- | `particleRateScale` | `1` | Particle emission rate scale (WE rate unit = particles per second) |
219
- | `particleSizeScale` | `1` | Particle size scale |
220
-
221
- ## Troubleshooting
222
-
223
- - `http://127.0.0.1:3080/we-sync/diag`: internal state (`kind` / `fingerprint` / `weDir` / `lastError` / per-monitor `sceneImage` extraction results / scene renderer capabilities / status / fallback layer);
224
- - `lastError` says the install dir was not found → set `CONFIG.wallpaperEngineDir` manually and rebuild / reinstall;
225
- - Scene enhanced mode shows no dynamic footage → check `scene.available`: `false` means the renderer or assets dir is missing (`reason` is shown in `/we-sync/diag`);
226
- - Nothing changes on the page → refresh, and confirm the `wallpaper_share` tab exists.
227
-
228
- ## Known limitations
229
-
230
- - For scene wallpapers, the "real dynamic footage" depends on the render mode: the default browser subset renderer composites the layer tree + transforms + decoded textures/particles/puppet animations (shader effects / SceneScript / keyframe animations are future work); the external renderer (`sceneRendererPath`) provides true rendering but must be provided by the user (e.g. a WSL2-wrapped headless linux-wallpaperengine, GPL, standalone);
231
- - The reference renderer transmits full 1920×1080 RGBA frames — CPU-heavy (~24-27fps @960×540 measured locally); a real renderer should output JPEG/WebP to reduce bandwidth;
232
- - Multi-monitor setups use `lastselectedmonitor` (or the first monitor);
233
- - Visual settings live in page memory only and reset on refresh (72% / 6px / 30%).
234
-
235
- ## Contents
236
-
237
- - `package.json` — manifest: `dsh.bundle.patch` → `cordis.patch.yml`, `dsh.client` → browser half, `exports["./client"]` → prebuilt `lib/client.js`
238
- - `cordis.patch.yml` — the bundle patch layer (host row + dsh.client roster row)
239
- - `src/index.ts` — node half source (polling / HTTP routes / scene-texture extraction / HTTP Range / SceneAdapter / SceneModel routes / WebSocket frame stream)
240
- - `src/scene/` — SceneAdapter modules (protocol / capability probe / renderer process / WebSocket / fallback / PKGV0001 parsing / SceneModel layer model / .tex decoding / puppet mdl parsing)
241
- - `src/client/` — browser half source (theme overrides / background layers / SceneCanvas / SceneModelRenderer subset renderer / ParticleRuntime / wallpaper_share panel)
242
- - `docs/` — format & implementation docs (`tex-format-findings.md` / `mdl-skinning-findings.md` / `scene-fallback.md`)
243
- - `tools/scene-renderer/` — built-in reference renderer (protocol contract implementation; real renderers replace it with the same protocol)
244
- - `lib/` — prebuilt artifacts (zero build for users; GitHub installs need no build allowance)
245
- - `dsh-wallpaper_share-0.2.0.tgz` — release tarball (attach it to GitHub Releases)
246
- - `install.ps1` — optional one-shot installer (uses the official `dsh plugin add` flow)
247
- - `CHANGELOG.md` — release notes
248
-
249
- ## License
250
-
251
- gplv3.
1
+ # dsh-wallpaper_share
2
+ # Wallpaper Engine ↔ DeepSeek Harness 壁纸同步
3
+
4
+
5
+ https://github.com/user-attachments/assets/4461d385-de62-42be-8420-7edce5606f44
6
+
7
+
8
+
9
+ [中文](#中文) | [English](#english)
10
+
11
+ 把 Wallpaper Engine 当前显示的壁纸实时同步为 DeepSeek Harness Web 界面的背景，并提供 `wallpaper_share` 标签页用于调整壁纸表现。支持**场景壁纸**的完整动效与应用壁纸的导入。
12
+
13
+ > **纯显示同步**：只读取 WE 状态，不控制 / 不修改桌面壁纸（换壁纸请在 WE 内操作）。
14
+ > **无敏感信息**：代码不含 Steam 用户名 / SteamID / 令牌；WE 安装目录运行时自动检测（注册表 `HKCU\Software\WallpaperEngine\installPath` → 常见 Steam 路径），检测不到时才需要手动配置。
15
+
16
+ ---
17
+
18
+ <a name="中文"></a>
19
+ # 中文
20
+
21
+ ## 兼容矩阵
22
+
23
+ | 壁纸类型 | 增强模式 | 性能模式
24
+ | --- | --- | --- |
25
+ | `video` | 播放源视频（支持 HTTP Range，可正常 seek） | 显示静态预览图或gif |
26
+ | `web` | iframe 加载源页面 | 显示静态预览图或gif |
27
+ | `image` | 显示源图 | 显示源图 |
28
+ | `scene` | 读取pkg并由**浏览器渲染器** | 显示pkg静态纹理 |
29
+ | `application` | 可从wallpaper_share预览 | 可从wallpaper_share预览
30
+
31
+ > scene 增强的完整 fallback 链与各层实现（渲染模式 / 纹理解码 / 粒子 / puppet）见 **[docs/scene-fallback.md](docs/scene-fallback.md)**。
32
+
33
+ ## 功能
34
+
35
+ - **实时同步**：在 Wallpaper Engine 切换壁纸后，harness页面背景自动跟随
36
+ - **多显示器**：复数显示器时可手动锁定某台作为背景来源
37
+ - **视觉效果滑块**：支持面板透明度/ 背景模糊/ 阴影深度调整
38
+ - **渲染模式切换**：性能（静态预览图）⇄ 增强（加载包括特效动画在内的所有壁纸内容）
39
+ - **Scene 实时渲染（实验内容）**：scene 壁纸增强模式默认走**浏览器子集渲染器**（真实 `scene.json` 图层树 + transform + 已解码纹理合成进 canvas，含粒子与 puppet 动画）；显式配置 `sceneRendererPath` 后走独立 renderer 子进程（offscreen，不弹窗）→ WebSocket 帧流；完整回退链见 [docs/scene-fallback.md](docs/scene-fallback.md)
40
+ - **专注模式**：随任务启停变化背景的复杂度以专注于当前任务内容
41
+ - **后台任务可视化** 收纳侧边栏时，通过圆形ui感知任务进度：绿-空闲；蓝-任务进行；橙-需要手动介入
42
+ - **同步开关** ⏻ 一键启停
43
+ - 自诊断路由 `/we-sync/diag`（仅本机可访问，含 scene renderer 状态与纹理提取结果）
44
+
45
+ ## 安装（官方 `dsh plugin` 通道，零手工配置）
46
+
47
+ > 前置：DSH 已用 `dsh --profile web` 验证。
48
+
49
+ ```bash
50
+ # 任选其一：
51
+ dsh plugin --profile web add github:YRN-playmaker/dsh-wallpaper_share
52
+ # 从 GitHub 安装（仓库自带预构建 lib/，不需要构建许可）
53
+ dsh plugin --profile web add dsh-wallpaper_share
54
+ # 从 npm 安装（发布后）
55
+ dsh plugin --profile web add ./dsh-wallpaper_share-0.2.0.tgz
56
+ # 本地 tarball 安装
57
+ ```
58
+
59
+ ```bash
60
+ # 安装 test 分支（最新开发版，含 Scene 渲染 / 粒子 / puppet 动画）：
61
+ dsh plugin --profile web add github:YRN-playmaker/dsh-wallpaper_share#test
62
+ ```
63
+
64
+ ```bash
65
+ # 重启 dsh（web profile），打开页面即可看到 wallpaper_share 标签页
66
+ ```
67
+
68
+ **无需手动编辑任何配置文件**：包内 `dsh.bundle.patch` 指向的 `cordis.patch.yml` 会在安装时自动加入 profile 的 bundle 层，其中一行同时是 host 行（node 半：轮询 + HTTP 路由）和 `dsh.client` roster 行（浏览器半的预构建 `lib/client.js` 由模块系统自动注入页面）。包发布时**自带预构建产物**，用户侧零构建。
69
+
70
+ ## 从源码构建（开发者）
71
+
72
+ 1. 把本仓库根目录（`package.json` / `src/` / `tsconfig.json` / `tsdown.config.ts`）拷入你的 DSH checkout：`packages/client/we-sync/`；
73
+ 2. `pnpm install`
74
+ 3. `pnpm --filter dsh-wallpaper_share exec tsc -b`
75
+ 4. `pnpm --filter dsh-wallpaper_share bundle`
76
+ 5. 产物在 `packages/client/we-sync/lib/`（`index.js` node 半 + `client.js` 浏览器半），拷回本仓库 `lib/` 后 `pnpm pack` 出新 tarball。
77
+
78
+ > 也可以在本仓库根目录直接 `pnpm install && pnpm build`（`tsdown` 独立构建，不依赖 DSH checkout）。
79
+
80
+ ## 配置
81
+
82
+ 包源码 `src/index.ts` 顶部 `CONFIG`：
83
+
84
+ | 配置项 | 默认值 | 说明 |
85
+ | --- | --- | --- |
86
+ | `wallpaperEngineDir` | `''`（自动检测） | 检测失败时手动指定安装目录 |
87
+ | `workshopContentDir` | `''`（自动推导） | 工作坊内容目录 |
88
+ | `pollIntervalMs` | `2000` | 轮询间隔 |
89
+ | `previewMaxBytes` | `6291456` | 预览图大小上限 |
90
+ | `sceneRendererPath` | `''`（内置参考 renderer） | 外部 scene renderer 可执行文件；留空用内置参考 renderer（诊断动画） |
91
+ | `wallpaperEngineAssetsDir` | `''`（自动推导） | WE engine assets 目录（自动为 `<weDir>/assets`；缺失时 renderer 不可用） |
92
+ | `sceneRenderWidth` | `1920` | scene renderer 输出宽度 |
93
+ | `sceneRenderHeight` | `1080` | scene renderer 输出高度 |
94
+ | `sceneRenderFps` | `30` | scene renderer 目标帧率 |
95
+ | `sceneRenderQuality` | `80` | JPEG/WebP 帧质量（0..100） |
96
+ | `sceneRenderMode` | `'auto'` | `'auto'`（浏览器子集渲染器为主；配置了 `sceneRendererPath` 则 external）\| `'browser'` \| `'external'` |
97
+ | `particleRateScale` | `1` | 粒子发射率缩放（WE rate 单位 = 每秒粒子数） |
98
+ | `particleSizeScale` | `1` | 粒子尺寸缩放 |
99
+
100
+ ## 排查
101
+
102
+ - `http://127.0.0.1:3080/we-sync/diag`：内部状态（`kind` / `fingerprint` / `weDir` / `lastError` / 每台显示器的 `sceneImage` 提取结果 / **scene renderer 的 capabilities / status / fallback 层**）；
103
+ - `lastError` 提示未找到安装目录 → 在包源码 `CONFIG.wallpaperEngineDir` 手动指定后重新构建 / 重新安装；
104
+ - scene 增强无动态画面 → 看 `scene.available`：`false` 表示 renderer 缺失或 assets 目录缺失（`/we-sync/diag` 里有 `reason`）；
105
+ - 页面没变化 → 刷新页面，确认标签栏出现 `wallpaper_share`。
106
+
107
+ ## 已知限制
108
+
109
+ - scene 增强的"真实动态画面"取决于渲染模式：默认浏览器子集渲染器做**图层树 + transform + 纹理/粒子/puppet 动画合成**（shader effect / SceneScript / keyframe 动画为后续）；外部 renderer（`sceneRendererPath`）可提供真实渲染，但需用户自备（如 WSL2 封装的 linux-wallpaperengine 离屏封装，GPL，独立组件）；
110
+ - 参考 renderer 为 1920×1080 RGBA 全帧传输，CPU 占用偏高（本机实测 ~24-27fps @960×540）；真 renderer 建议输出 JPEG/WebP 以降低带宽；
111
+ - 多显示器时取 `lastselectedmonitor`（无则第一台）；
112
+ - 视觉参数仅保存在页面内存，刷新回到默认值（72% / 6px / 30%）。
113
+
114
+ ## 目录
115
+
116
+ - `package.json` — 包清单：`dsh.bundle.patch` → `cordis.patch.yml`，`dsh.client` → 浏览器半，`exports["./client"]` → 预构建 `lib/client.js`
117
+ - `cordis.patch.yml` — bundle 补丁层（host 行 + dsh.client roster 行）
118
+ - `src/index.ts` — node 半源码（轮询 / HTTP 路由 / scene 纹理提取 / HTTP Range / SceneAdapter 接入 / SceneModel 路由 / WebSocket 帧流）
119
+ - `src/scene/` — SceneAdapter 模块（协议 / 能力探测 / renderer 进程 / WebSocket / fallback / **PKGV0001 解析 / SceneModel 图层模型 / .tex 解码 / puppet mdl 解析**）
120
+ - `src/client/` — 浏览器半源码（主题覆盖 / 背景层 / SceneCanvas / **SceneModelRenderer 子集渲染器 / ParticleRuntime** / wallpaper_share 面板）
121
+ - `docs/` — 格式与实现文档（`tex-format-findings.md` / `mdl-skinning-findings.md` / **`scene-fallback.md`**）
122
+ - `tools/scene-renderer/` — 内置参考 renderer（协议契约实现；真 renderer 按同协议替换）
123
+ - `lib/` — 预构建产物（用户零构建；GitHub 安装也无需构建许可）
124
+ - `dsh-wallpaper_share-0.2.0.tgz` — 发布 tarball（GitHub Release 附件）
125
+ - `install.ps1` — 可选的一键安装脚本（走官方 `dsh plugin add` 通道）
126
+ - `CHANGELOG.md` — 更新记录
127
+
128
+ ## 许可证
129
+
130
+ gplv3
131
+
132
+ ---
133
+
134
+ <a name="english"></a>
135
+
136
+
137
+
138
+ # English
139
+ <img width="1920" height="1080" alt="deepseek21" src="https://github.com/user-attachments/assets/4edaa26e-c5da-4801-b7b3-5ba04cd28184" />
140
+ Real-time synchronization of the wallpaper currently displayed in Wallpaper Engine to the background of the DeepSeek Harness Web interface, along with a `wallpaper_share` session view tab to control monitor source, transparency / blur / shadow, render modes, and focus mode.
141
+
142
+ > **Display-Only Sync**: Only reads WE status; does not control or modify desktop wallpapers (please change wallpapers within WE).
143
+ > **No Sensitive Data**: Code contains no Steam usernames / SteamIDs / tokens; WE installation directory is auto-detected at runtime (Registry `HKCU\Software\WallpaperEngine\installPath` → common Steam paths), requiring manual configuration only when detection fails.
144
+
145
+ ---
146
+
147
+ ## Compatibility Matrix
148
+
149
+ | Wallpaper Type | Enhanced Mode | Performance Mode |
150
+ | --- | --- | --- |
151
+ | `video` | Plays source video (HTTP Range supported, seekable) | Shows static preview image or GIF |
152
+ | `web` | Loads source page in iframe | Shows static preview image or GIF |
153
+ | `image` | Displays source image | Displays source image |
154
+ | `scene` | Reads PKG and rendered by the **browser renderer** | Displays PKG static texture |
155
+ | `application` | Previewable via `wallpaper_share` | Previewable via `wallpaper_share` |
156
+
157
+ > See **[docs/scene-fallback.md](docs/scene-fallback.md)** for the complete fallback chain and layer-by-layer implementations (render modes / texture decoding / particles / puppet) for Scene enhanced mode.
158
+
159
+ ## Features
160
+
161
+ - **Real-Time Sync**: Background updates automatically within ~2 seconds after applying a wallpaper in Wallpaper Engine.
162
+ - **Multi-Monitor Support**: Automatically follows the "most recently changed" monitor; manually lock a specific monitor as the background source when multiple displays are connected.
163
+ - **Visual Effect Sliders**: Panel opacity (0–100%) / Background blur (0–30px) / Shadow depth (0–100%).
164
+ - **Render Mode Toggle**: Performance (static preview, default) ⇄ Enhanced (loads wallpaper source content).
165
+ - **Scene Live Rendering (Experimental)**: Scene wallpapers in enhanced mode default to the **browser subset renderer** (real `scene.json` layer tree + transforms + decoded textures composited into canvas, including particles and puppet animations); falls back to a standalone renderer subprocess (offscreen, no popups) → WebSocket frame stream when `sceneRendererPath` is explicitly configured. Full fallback chain documented in [docs/scene-fallback.md](docs/scene-fallback.md).
166
+ - **Focus Mode**: Automatically switches to 30% / 15px / 90% while tasks are running, and restores to 9% / 6px / 40% upon completion.
167
+ - **Sync Toggle** ⏻: One-click start/stop.
168
+ - Self-diagnostic route `/we-sync/diag` (localhost only, includes scene renderer status and texture extraction results).
169
+
170
+ ## Installation (Official `dsh plugin` Channel, Zero Manual Config)
171
+
172
+ > Prerequisite: DSH has been verified with `dsh --profile web`.
173
+
174
+ ```bash
175
+ # Choose one of the following:
176
+ dsh plugin --profile web add github:YRN-playmaker/dsh-wallpaper_share
177
+ # Install from GitHub (includes prebuilt lib/, no build toolchain required)
178
+ dsh plugin --profile web add dsh-wallpaper_share
179
+ # Install from npm (after release)
180
+ dsh plugin --profile web add ./dsh-wallpaper_share-0.2.0.tgz
181
+ # Install from local tarball
182
+ ```
183
+
184
+ ```bash
185
+ # Install test branch (latest dev build with Scene rendering / particles / puppet animation):
186
+ dsh plugin --profile web add github:YRN-playmaker/dsh-wallpaper_share#test
187
+ ```
188
+
189
+ ```bash
190
+ # Restart dsh (web profile) and open the page to see the wallpaper_share tab
191
+ ```
192
+
193
+ **No manual configuration required**: The `cordis.patch.yml` specified by `dsh.bundle.patch` is automatically added to the profile's bundle layer during installation. Its entry acts simultaneously as a host entry (Node side: polling + HTTP routing) and a `dsh.client` roster entry (browser side: prebuilt `lib/client.js` automatically injected by the module system). The package **ships with prebuilt artifacts**, requiring zero user-side builds.
194
+
195
+ ## Build from Source (Developers)
196
+
197
+ 1. Copy this repository root (`package.json` / `src/` / `tsconfig.json` / `tsdown.config.ts`) into your DSH checkout at `packages/client/we-sync/`;
198
+ 2. Run `pnpm install`;
199
+ 3. Run `pnpm --filter dsh-wallpaper_share exec tsc -b`;
200
+ 4. Run `pnpm --filter dsh-wallpaper_share bundle`;
201
+ 5. Outputs will be in `packages/client/we-sync/lib/` (`index.js` for Node + `client.js` for browser). Copy them back to this repository's `lib/` and run `pnpm pack` to generate a new tarball.
202
+
203
+ > You can also run `pnpm install && pnpm build` directly in this repository root (`tsdown` standalone build, independent of DSH checkout).
204
+
205
+ ## Configuration
206
+
207
+ Top of `src/index.ts` under `CONFIG`:
208
+
209
+ | Option | Default | Description |
210
+ | --- | --- | --- |
211
+ | `wallpaperEngineDir` | `''` (Auto-detect) | Manually specify installation directory if auto-detection fails |
212
+ | `workshopContentDir` | `''` (Auto-derived) | Steam Workshop content directory |
213
+ | `pollIntervalMs` | `2000` | Polling interval in ms |
214
+ | `previewMaxBytes` | `6291456` | Maximum preview file size limit |
215
+ | `sceneRendererPath` | `''` (Built-in reference renderer) | External scene renderer executable; leave empty to use built-in reference renderer (diagnostic animation) |
216
+ | `wallpaperEngineAssetsDir` | `''` (Auto-derived) | WE engine assets directory (defaults to `<weDir>/assets`; renderer unavailable if missing) |
217
+ | `sceneRenderWidth` | `1920` | Scene renderer output width |
218
+ | `sceneRenderHeight` | `1080` | Scene renderer output height |
219
+ | `sceneRenderFps` | `30` | Scene renderer target FPS |
220
+ | `sceneRenderQuality` | `80` | JPEG/WebP frame quality (0..100) |
221
+ | `sceneRenderMode` | `'auto'` | `'auto'` (browser subset renderer first; external if `sceneRendererPath` is configured) | `'browser'` | `'external'` |
222
+ | `particleRateScale` | `1` | Particle emission rate scale (WE rate unit = particles per second) |
223
+ | `particleSizeScale` | `1` | Particle size scale |
224
+
225
+ ## Troubleshooting
226
+
227
+ - `http://127.0.0.1:3080/we-sync/diag`: View internal status (`kind` / `fingerprint` / `weDir` / `lastError` / per-monitor `sceneImage` extraction results / **scene renderer capabilities / status / fallback layer**).
228
+ - `lastError` indicates installation directory not found → Manually specify `CONFIG.wallpaperEngineDir` in source and rebuild/reinstall.
229
+ - Scene enhanced mode has no dynamic visuals → Check `scene.available`: `false` indicates missing renderer or assets directory (refer to `reason` in `/we-sync/diag`).
230
+ - No UI changes → Refresh the page and confirm the `wallpaper_share` tab is present in the tab bar.
231
+
232
+ ## Known Limitations
233
+
234
+ - "True dynamic rendering" for Scene wallpapers depends on the render mode: the default browser subset renderer handles **layer tree + transforms + texture / particle / puppet animation compositing** (shader effects / SceneScript / keyframe animations are planned for future updates); an external renderer (`sceneRendererPath`) provides full native rendering but must be provided separately (e.g., WSL2-wrapped headless linux-wallpaperengine, GPL, standalone).
235
+ - The reference renderer transmits full 1920×1080 RGBA frames, resulting in higher CPU usage (~24–27 fps @ 960×540 benchmarked locally); dedicated renderers should stream JPEG/WebP to reduce bandwidth.
236
+ - Multi-monitor setups default to `lastselectedmonitor` (or display 1 if unavailable).
237
+ - Visual slider parameters are stored in page memory only and reset to defaults (72% / 6px / 30%) on reload.
238
+
239
+ ## Directory Structure
240
+
241
+ - `package.json` — Package manifest: `dsh.bundle.patch` → `cordis.patch.yml`, `dsh.client` → browser side, `exports["./client"]` → prebuilt `lib/client.js`
242
+ - `cordis.patch.yml` — Bundle patch layer (host entry + dsh.client roster entry)
243
+ - `src/index.ts` — Node-side source (polling / HTTP routes / scene texture extraction / HTTP Range / SceneAdapter integration / SceneModel routing / WebSocket frame streaming)
244
+ - `src/scene/` — SceneAdapter module (protocol / capability probing / renderer process / WebSocket / fallback / **PKGV0001 parsing / SceneModel layer model / .tex decoding / puppet mdl parsing**)
245
+ - `src/client/` — Browser-side source (theme overrides / background layer / SceneCanvas / **SceneModelRenderer subset renderer / ParticleRuntime** / wallpaper_share panel)
246
+ - `docs/` — Format specifications & technical docs (`tex-format-findings.md` / `mdl-skinning-findings.md` / **`scene-fallback.md`**)
247
+ - `tools/scene-renderer/` — Built-in reference renderer (implements protocol contract; drop-in replacement target for native renderers)
248
+ - `lib/` — Prebuilt distribution artifacts (zero-build for end users; GitHub direct install requires no build pipeline)
249
+ - `dsh-wallpaper_share-0.2.0.tgz` — Release tarball (GitHub Releases asset)
250
+ - `install.ps1` — Optional one-click install script (via official `dsh plugin add` flow)
251
+ - `CHANGELOG.md` — Release history & changelog
252
+
253
+ ## License
254
+
255
+ GPL-3.0