dsh-wallpaper-studio 0.0.0-stage → 0.1.2

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-wallpaper-studio contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,294 @@
1
- # Temporary Holding Version
1
+ # dsh-wallpaper-studio · 壁纸工作室
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ DeepSeek Harness(DSH)的**动态壁纸 + 主题色 + 透明度**插件。装进 Web GUI / DSH 桌面版之后,在
4
+ 「插件 → 已安装插件 → dsh-wallpaper-studio」里的「壁纸工作室」卡片上,把自己喜欢的图片或视频铺成整个界面的背景,顺手把主色、底色、
5
+ 面板色和各层不透度一起调掉。
6
+
7
+ 纯客户端实现:不改宿主源码、不依赖原生模块、不需要 Steam / Wallpaper Engine 运行时。
8
+
9
+ ---
10
+
11
+ ## 1. 它参考的是什么
12
+
13
+ DSH 插件市场里「主题与外观」分类最热的壁纸插件是
14
+ [`elysia395/dsh-wallpaper-engine`](https://github.com/elysia395/dsh-wallpaper-engine)(★ 6921、月下载 13 万+):
15
+ 把本机 Wallpaper Engine 的视频 / Web / Scene 壁纸铺到 `dsh web` 的聊天背后,配一个 iOS 液态玻璃
16
+ 风格的设置窗,滑条调模糊、亮度、边框、遮罩和面板不透明度。
17
+
18
+ 这个插件沿用了它被验证过的**产品结构**:
19
+
20
+ | 参考实现的做法 | 本项目 |
21
+ | --- | --- |
22
+ | 全屏背景层 + 遮罩 + 模糊,压在界面最底层 | 同样:`#dws-bg` 固定定位、`z-index:-1`、`inset:-48px` 给模糊留边 |
23
+ | 液态玻璃设置窗、滑条即时生效 | 同一套交互心智:卡片折叠 + 滑杆 + 取色器,改一下立刻生效、无需保存按钮 |
24
+ | 通过设计令牌把面板调成半透明 | 只覆盖 alias 层令牌,不写宿主私有类名 |
25
+ | 壁纸素材存本地,重启不丢 | Blob 存 IndexedDB,设置存 localStorage |
26
+
27
+ 换掉的两件事,也是本项目的取舍:
28
+
29
+ 1. **不依赖 Wallpaper Engine / Steam / 本机壁纸库。** 壁纸来源是:自己上传的图片或视频、直链 URL、
30
+ 以及 6 套内置渐变动效。装完即用,Windows / macOS / Linux / 纯浏览器都一致。
31
+ 2. **不绑定宿主的内部 DOM。** 参考实现要按 DSH 版本逐个维护 `[data-composer-card]`、
32
+ `[class*="_sidebarCol"]` 这类选择器,宿主一改版就得跟着改。本项目只动 alias 设计令牌
33
+ (`--dsw-alias-*`),版本漂移时最坏情况是局部不跟着透,不会白屏、不会吃掉别的插件。
34
+
35
+ ---
36
+
37
+ ## 2. 功能一览
38
+
39
+ ### 动态壁纸
40
+ - **上传图片**:JPG / PNG / WebP / **GIF(保留动效**);**上传视频**:MP4 / WebM,静音循环播放。
41
+ - **直链 URL**:按扩展名自动分流图片/视频(需 CORS 友好直链)。
42
+ - **6 套内置动态壁纸**:极光流动、午夜星尘、森林晨雾、熔岩余烬、樱粉暮色、冰川微光。
43
+ 纯 CSS 渐变 + 缓慢位移动画,零素材、零网络请求,`prefers-reduced-motion` 下自动静止。
44
+ - **缩放方式**:填充 / 适应 / 平铺。
45
+ - **效果**:壁纸可见度、背景模糊(0–40px)、遮罩暗度(可读性面纱)、主背景遮底。
46
+ - 素材只存在本机浏览器:图片/视频走 **IndexedDB**(不占 localStorage 配额,大文件更安全),
47
+ 配置走 localStorage。**不会上传到任何服务器**。
48
+
49
+ ### 主题色
50
+ - 三个角色、原生取色器 + HEX 输入双通道:**主色**(品牌色 / 选中态 / 焦点环跟随)、
51
+ **底色**(整页画布)、**面板色**(卡片 / 侧栏 / 气泡)。
52
+ - 面板色的浅阶(layer-2 / layer-3 / module / sidebar-fill)由底色按比例混出来,
53
+ 自动保持同色系的层次感,不需要手调五个颜色。
54
+ - 深浅模式**各一组**值:切到深色主题时自动用对应的一套,不会出现「深色下白底刺眼」。
55
+ - 每个角色都可「跟随默认」,一键回到 DSH 原生配色。
56
+
57
+ ### 透明度
58
+ - 面板 / 输入框 / 弹层三档独立不透明度(0–100%),互不干扰:
59
+ 主面板全透时输入框仍能看清字,下拉菜单也不会变成水泥块。
60
+ - 令牌层面生效,因此卡片、侧栏、气泡、菜单、输入条一起跟随,不用逐个写选择器。
61
+
62
+ ### 其他
63
+ - **6 套配色预设**:默认 / 午夜 / 海洋 / 森林 / 樱粉 / 冰川(一次配好主色 + 底色 + 面板色 +
64
+ 透明度 + 内置壁纸)。
65
+ - **配置导入导出**:一串 JSON 就能把整套外观发给别人。
66
+ - **侧栏底部快速开关**:临时关掉壁纸恢复原生界面,不用进设置页。
67
+
68
+ ---
69
+
70
+ ## 3. 安装
71
+
72
+ 三种通道任选一种(`--profile web` 指 Web GUI;桌面版按桌面版自己的 profile 名替换)。
73
+
74
+ ```bash
75
+ # ① npm 公共包
76
+ dsh plugin --profile web add dsh-wallpaper-studio
77
+
78
+ # ② GitHub Release 附件(不经过 npm 也行;文件名不带版本号,所以地址长期有效)
79
+ # curl -L -O https://github.com/xiaojiuop/dsh-wallpaper-studio/releases/latest/download/dsh-wallpaper-studio.tgz
80
+ dsh plugin --profile web add ./dsh-wallpaper-studio.tgz
81
+
82
+ # ③ 本地目录(开发用,link: 是活链,改完 rebuild 刷新页面即生效)
83
+ dsh plugin --profile web add link:/abs/path/to/dsh-wallpaper-studio
84
+ ```
85
+
86
+ 装完**重启宿主**(`dsh web` 或桌面版应用),因为客户端 bundle 只会在启动时组成启动图。
87
+ package.json 的 `files` 已经包含构建产物 `lib/`,从 git / tarball 安装不需要现场跑构建。
88
+
89
+ ### 装完怎么确认
90
+
91
+ ```bash
92
+ # 1. bundle 真的被服务出来了。注意宿主用的是「合并端点」,不是 /plugins/<id>/client.js
93
+ # (后者是 404)。每个启动项自己带 URL,直接从页面里取最稳:
94
+ # F12 → Console → window.__DSH_BOOT__.entries.find(e => e.id === "dsh-wallpaper-studio").url
95
+ # 形如 plugins/??dsh-wallpaper-studio/client.js&rev=b1fe5fd8b3dc
96
+ TOKEN=… # dsh web 启动日志里那条带 token 的地址
97
+ curl -c /tmp/cj -b /tmp/cj -L "http://127.0.0.1:3080/?token=$TOKEN" -o /dev/null
98
+ curl -b /tmp/cj "http://127.0.0.1:3080/plugins/??dsh-wallpaper-studio/client.js&rev=b1fe5fd8b3dc" | head -c 120
99
+ # 应看到 window.__ModuleLoader__.load({ id: "dsh-wallpaper-studio", factory: (require) => {
100
+
101
+ # 2. 页面里插件在启动图中
102
+ # F12 → Console → window.__DSH_BOOT__.entries.map(e => e.id)
103
+ ```
104
+
105
+ **已在真实宿主上验证**(`@deepseek-ai/dsh@0.2.2-rc.1`,Linux + Node 22):
106
+ `dsh plugin --profile web add ./dsh-wallpaper-studio-0.1.0.tgz` 成功(0.1.2 起同一通道改用下面的
107
+ `dsh-wallpaper-studio.tgz`)→ `--dump-config` 里出现本插件行 →
108
+ 启动图 74 项含 `dsh-wallpaper-studio` → bundle 200/54KB → 浏览器里壁纸层注入、`--dws-wall-opacity`
109
+ 生效、侧栏「壁纸工作室」按钮渲染、插件页「已安装插件」显示「运行中」,卡片里 7 个滑条 / 3 个取色器 /
110
+ 6 个预设 / 9 个 chip 全部到位,上传图片后壁纸层立刻变成 `blob:`,刷新后从 IndexedDB 自动恢复。
111
+
112
+ 页面若卡在 loading:DSH 的 boot 是 all-or-nothing,`assertEntriesActive()` 会把「哪个 entry、
113
+ 为什么没 ACTIVE」直接列在页面上。本插件只依赖 `slots` 与 `locale` 两个核心服务,
114
+ 正常组合下不会因此挂掉。
115
+
116
+ ---
117
+
118
+ ## 4. 用起来
119
+
120
+ **插件 → 已安装插件 → dsh-wallpaper-studio**,点开「查看」就是这张卡片(旧版宿主里位置是
121
+ 「设置 → 插件 → 壁纸工作室」)。侧栏底部还有一个「壁纸工作室」快速开关。
122
+
123
+ | 区块 | 控件 | 说明 |
124
+ | --- | --- | --- |
125
+ | 动态壁纸 | 缩略图网格 | 「无壁纸」+ 6 套内置动态壁纸,点一下立即切换 |
126
+ | | 上传图片 / 上传视频 | 本机文件直接入库,页面上立刻生效 |
127
+ | | 直链输入 + 加载 | 粘贴图片/视频地址;视频自动识别 |
128
+ | | 移除 | 清掉当前壁纸(上传的文件同时从 IndexedDB 删掉) |
129
+ | 背景效果 | 壁纸可见度 | 0–100%,低值等于把壁纸淡进底色里 |
130
+ | | 背景模糊 | 0–40px,只作用于壁纸本身,不会糊到界面 |
131
+ | | 遮罩暗度 | 壁纸上的可读性面纱;浅色模式是白纱、深色模式是暗纱 |
132
+ | | 主背景遮底 | 整页画布的遮盖度;0% = 壁纸完全露出来 |
133
+ | | 缩放方式 | 填充 / 适应 / 平铺 |
134
+ | 主题色 | 主色 / 底色 / 面板色 | 取色器或直接输 HEX;「跟随默认」清空该角色 |
135
+ | 界面通透 | 面板 / 输入框 / 弹层 | 三档独立不透明度 |
136
+ | 配色预设 | 6 个 chip | 一次覆盖颜色 + 透明度 + 内置壁纸,之后还能继续微调 |
137
+ | 导入导出 | 复制配置 / 粘贴应用 / 恢复默认 | 配置就是一段 JSON |
138
+
139
+ 所有改动**即时生效并自动保存**,没有「保存」按钮;关掉插件(或卸载)会把界面完整还原成原生外观。
140
+
141
+ ---
142
+
143
+ ## 5. 实现原理(给要改代码的人)
144
+
145
+ ### 5.1 前端插件契约
146
+ - 宿主扫描 `package.json` 里的 `dsh.client.platform: "web"`,把 `exports["./client"]` 指向的
147
+ `lib/client.js` 组成启动图,页面按 `/plugins/<id>/client.js?rev=…` 拉取并激活。
148
+ - `lib/client.js` 必须是「惰性 CJS 闭包工厂」:
149
+
150
+ ```js
151
+ window.__ModuleLoader__.load({ id: "dsh-wallpaper-studio", factory: (require) => {
152
+ var module = { exports: {} }; var exports = module.exports;
153
+ /* …插件代码,最后 return module.exports… */
154
+ } });
155
+ ```
156
+
157
+ 外置的平台模块(本项目只用 `react`)通过注入的 `require` 解析;缺了这层外壳,
158
+ 构建和下载都正常,**只有启动会失败**(`loaded without registering …`)。
159
+ - 工厂返回值就是浏览器 fiber 的插件模块表:`{ name, inject: ['slots','locale'], apply }`。
160
+ - 槽位只用**增量**槽位:`plugins.bundle.config`(0.2.x 插件页里本包的配置区,key = 包名;旧版宿主自动
161
+ 换成 `settings.plugin.item`,按启动图里有没有 `dsh-client-ui-plugin-manager` 决定,靠 `locale` 取文案)、
162
+ `sidebar.footer.action`(快速开关)。不注册 `root` / `sidebar` / `conversation`,
163
+ 所以永远不会把别人的界面顶掉。
164
+
165
+ ### 5.2 壁纸怎么铺到「最底层」
166
+ ```
167
+ body
168
+ ├─ #dws-bg position:fixed; inset:-48px; z-index:-1; pointer-events:none
169
+ │ ├─ ::before 壁纸(图片 / 渐变),opacity = --dws-wall-opacity,filter = blur(--dws-blur)
170
+ │ ├─ <video> 视频壁纸(muted / loop / playsinline / object-fit:cover)
171
+ │ └─ ::after 可读性面纱 rgba(… , --dws-scrim)
172
+ └─ #root 宿主界面(背景被令牌调成半透明,于是壁纸透上来)
173
+ ```
174
+ `z-index:-1` 让它画在 body 背景之上、所有内容之下;`inset:-48px` 给模糊滤镜留出出血边,
175
+ 避免边缘出现透明缝。`html[data-dws-active]` 时把 `#root` 的实底挖空
176
+ (并对 Windows 桌面版的 `[data-windows-titlebar]` 外框做同样的 punch-out),
177
+ 否则桌面端会有一层不透明外框挡住壁纸。
178
+
179
+ ### 5.3 透明度走设计令牌,不走私有类名
180
+ 写入两张表,都只针对 alias 令牌,带 `!important` 以免和宿主主题表互相打架:
181
+
182
+ ```css
183
+ body { --dsw-alias-bg-base: rgba(…); --dsw-alias-bg-layer-1: rgba(…); … }
184
+ body[data-ds-dark-theme], body[data-theme="dark"], html[data-theme="dark"] body { … 深色一套 … }
185
+ ```
186
+
187
+ 覆盖的令牌:`bg-base`、`bg-layer-1/2/3`、`bg-overlay`、`bg-module-platform`、
188
+ `specific-sidebar-fill`、`specific-bubble`、`fill-l1/l2`、`specific-menu`、
189
+ `menu-surface-fill`、`specific-input-major`、以及主色 `brand-primary` / `state-business-primary` /
190
+ `button-info-fill`。面板色的浅阶用 `mixHex(panel, base, 0.08/0.14/0.06/0.04)` 派生,
191
+ 所以换底色时整套层次自动重算。
192
+
193
+ ### 5.4 存储
194
+ | 内容 | 位置 | 原因 |
195
+ | --- | --- | --- |
196
+ | 配置(开关/颜色/透明度/当前壁纸元信息) | `localStorage["dsh-wallpaper-studio:v1"]` | 小、同步读、首帧就能投影 |
197
+ | 壁纸 Blob(图片/视频原图) | IndexedDB `dsh-wallpaper-studio-db / media` | 不占 localStorage 5MB 配额,大文件安全 |
198
+
199
+ ### 5.5 卸载即还原
200
+ `apply` 里的所有 DOM 副作用都包在 `ctx.effect` 里;disposer 会移除壁纸层、令牌表、
201
+ `data-dws-active` 属性,暂停并释放视频、`URL.revokeObjectURL` 掉所有对象 URL。
202
+ 停用开关走的是同一条 `teardown()`,所以「临时关掉」和「卸载插件」都不会留残留样式。
203
+
204
+ ---
205
+
206
+ ## 6. 已知限制(诚实版)
207
+
208
+ - **局部不透**:令牌能覆盖绝大多数表面,但宿主仍有少量硬编码的 static 色(例如改动卡片的
209
+ `--changes-fill` / `--deliverable-fill`)。这些位置保持不透明——比反过来「整块变透明看不清字」安全。
210
+ - **令牌名以当前 alias 层为准**:主色/底色/面板/透明度全部集中在 `modeTokens()` 一个函数里。
211
+ DSH 后续大版本若重命名令牌,只改这一处即可。
212
+ - **视频编码**:能不能播取决于浏览器(H.264/WebM 一般没问题,HEVC 大概率不行);播不了会静默不显示,
213
+ 建议先用 MP4 试。
214
+ - **配额**:IndexedDB 单次上传建议 ≤100MB,超了可能被浏览器拒绝(会给出错误提示,不会崩)。
215
+ - **同类插件冲突**:`dsh-ui-appearance`、`dsh-any-background`、`dsh-wallpaper-bg` 这类外观插件
216
+ 也在写同一批令牌,同时启用会互相覆盖 —— **同类只留一个**。
217
+ - **深色模式取值**:三档不透明度对两种模式共用一套数值,颜色则分模式各一份;
218
+ 如果某套配色在深色下偏灰,用「配色预设 → 午夜」这类深色向预设起步更省事。
219
+
220
+ ---
221
+
222
+ ## 7. 目录结构
223
+
224
+ ```
225
+ dsh-wallpaper-studio/
226
+ ├─ package.json # name / exports / dsh.client / dsh.bundle
227
+ ├─ cordis.patch.yml # bundle 层:把本包插入宿主插件树
228
+ ├─ icon.png # 512×512,238 KB(宿主上限 256 KiB,已在限内)
229
+ ├─ locale/
230
+ │ ├─ en.json # meta.title / meta.description(插件管理页那一行)
231
+ │ └─ zh.json
232
+ ├─ lib/
233
+ │ ├─ index.js # Host 半(导出 name / apply,故意保持最小)
234
+ │ └─ client.js # 浏览器半(构建产物:banner + 闭包工厂 + footer)
235
+ ├─ src/client.js # 浏览器半源码(改这个)
236
+ ├─ scripts/
237
+ │ ├─ build-client.mjs # 零依赖:banner/intro/footer 拼装
238
+ │ ├─ check-client-bundle.mjs # 发布前静态校验(21 项)
239
+ │ └─ smoke.mjs # 免宿主冒烟(16 项)
240
+ ├─ release/ # 发布用物料:npm / GitHub Release / 市场 PR 脚本
241
+ ├─ assets/icon-180.png # 180×180,市场列表卡片用(市场只收 GitHub 上的位图)
242
+ └─ LICENSE # MIT
243
+ ```
244
+
245
+ `test/render-test.mjs`(jsdom + React 18 渲染级验证)是开发机上的临时脚本,**不随包、也不在本仓库**
246
+ —— `scripts/smoke.mjs` 用 `node:vm` 加一个 React 桩覆盖了同一批断言,且零依赖。
247
+
248
+ ## 8. 开发
249
+
250
+ ```bash
251
+ npm run build # src/client.js → lib/client.js
252
+ npm run check # 契约/产物静态校验(21 项)
253
+ npm run smoke # 工厂注册、模块表、槽位注册、词典键位、卸载清理(16 项)
254
+
255
+ # 没有 npm 的机器(比如只装了 DSH 桌面版)直接让 node 跑同一批脚本:
256
+ node scripts/build-client.mjs && node scripts/check-client-bundle.mjs && node scripts/smoke.mjs
257
+ ```
258
+
259
+ `build-client.mjs` 是幂等的:同一份 `src/client.js` 反复构建,产出的 `lib/client.js` 字节完全一致,
260
+ 所以 `lib/client.js` 直接进版本库、不需要在安装时现场构建。
261
+
262
+ ### 发布
263
+
264
+ 发布流程(npm 公共包 + GitHub Release 附件 + 插件市场 PR)见 [`release/RELEASE.md`](release/RELEASE.md),
265
+ 三个脚本都在 `release/` 下,全部可重复执行、失败可重试。
266
+
267
+ 改完 `src/client.js` 后 `npm run build` → 刷新页面即可(本地 link 安装时不需要重新 `plugin add`;
268
+ 改了 `dsh.client.inject` / `immediately` 这类清单字段才要重启宿主)。
269
+
270
+ ---
271
+
272
+ ## 9. 隐私
273
+
274
+ - 不上传任何文件,不请求任何外部接口;
275
+ - 不读取系统壁纸、不扫描 Steam / Wallpaper Engine 目录;
276
+ - 壁纸素材、配置全部留在本机浏览器;卸载插件时对象 URL 与 IndexedDB 记录可自行清理
277
+ (卡片里的「移除」会同时删除 IndexedDB 记录)。
278
+
279
+ ## 10. 参考与致谢
280
+
281
+ - 产品参考:[`elysia395/dsh-wallpaper-engine`](https://github.com/elysia395/dsh-wallpaper-engine)(DSH 市场最热壁纸插件)
282
+ - 令牌与分层方式参考:`dsh-ui-appearance`、`dsh-any-background`、`dsh-wallpaper-bg` 的公开实现
283
+ - 插件前端契约依据:DSH 前端插件开发指南(`dsh.client` / 闭包工厂 / 槽位目录 / 设计令牌分层)
284
+
285
+ MIT License.
286
+
287
+ ## 变更记录
288
+
289
+ - **0.1.2** — 上架包:补 `locale/en.json` + `locale/zh.json`(插件管理页那一行标题/描述,此前只能回退到
290
+ `package.json` 里那段中英混合的长 description)、补 `LICENSE`、`exports` 增加 `./locale/*.json`、
291
+ `files` 增加 `locale/*.json`。功能与 0.1.1 一致,`lib/client.js` 字节未变。
292
+ 此前的实验版本曾以 `dsh-wallpaperu` 这个名字发在 npm,现已标记 deprecated 并指向本包。
293
+ - **0.1.1** — 在 0.1.0 基础上新增「界面磨砂 / Interface frost」:只对面板背后那一层壁纸做
294
+ `backdrop-filter`,壁纸本身仍然清晰,正文压在图上也看得清。
@@ -0,0 +1,8 @@
1
+ # dsh-wallpaper-studio — bundle patch layer.
2
+ # `dsh plugin --profile web add` composes this layer, so the host loader puts
3
+ # the package into the plugin tree and the ClientModuleRegistry can then
4
+ # discover its `dsh.client` browser half.
5
+
6
+ - insert:
7
+ - id: dsh-wallpaper-studio
8
+ name: 'dsh-wallpaper-studio'
package/icon.png ADDED
Binary file