dsh-wallpaper-position

Name: ankhishtar2-lang/dsh-wallpaper-position
Author: ankhishtar2-lang

[!WARNING] 本仓库是 vibe coding 产物。 代码由作者与 AI（DeepSeek Harness 会话）对话生成、多轮迭代而来，没有经过人工逐行审计，也只在作者本机环境（WSL2 + dsh 0.1.5-rc.1 系列）实测过。请自行审阅后再使用；不要直接用于生产或安全敏感场景。代码按 MIT「按原样（AS IS）」提供，不附带任何担保，风险自负。

A vibe-coded satellite plugin for dsh-dream-skin: nudge the wallpaper's position per image (X/Y in pixels) from 设置 → 外观, remembered separately for every wallpaper.

dsh-dream-skin 的壁纸是整屏铺满（background-size: cover、 background-position: center）的固定层。构图偏左/偏上的图会压住聊天文字，而它本身没有提供位移设置。这个插件补上这一块：在设置页里按像素微调，且每张图各自记忆。

1. 它做什么

在 设置 → 外观（dream-skin 页） 注册一项设置：「壁纸位移（仅对当前这张图生效）」；
两个数值输入框（X / Y），步进 1 px，范围 ±5000 px，配 −10 / −1 / +1 / +10 微调按钮与「恢复默认位置」；
按图片记忆：键是当前壁纸内容哈希，换图即换一套位移，互不干扰；
纯前端实现：只写 CSS 变量，不动图片、不改 dream-skin 的任何文件；
即时生效，无需重启 dsh（改完立刻反映到壁纸上）。

2. 依赖声明（重要）

2.1 运行期硬依赖：`dsh-dream-skin` 插件

依赖点	说明
设置插槽 `settings.dreamSkin.item`	本插件的设置项注册在这里（`id: wallpaper-position`，`order: 90`）。插槽不存在时，插件只是「隐身」，不影响 dsh 启动
壁纸层 DOM	依赖 dream-skin 把壁纸渲染成 `body` 直接子节点、且内联样式里同时含 `background-image` 与 `position:fixed` 的元素（本插件用属性选择器命中它）
壁纸来源	读取 `localStorage["dsh-dream-skin:wallpaper"]`（dream-skin 写入的当前壁纸 data URL）来算「这张图」的身份

dream-skin 改了壁纸层的 DOM 结构或存储键名时，本插件会静默失效（不会报错、也不影响 dsh）。

2.2 无其它依赖

不需要任何外部程序、系统服务、网络访问；
host 半只有一个空 apply()：不注册路由、不读写文件、不联网；所有逻辑都在浏览器半。

2.3 平台与版本

项目	要求
dsh 核心	在 `0.1.5-rc.1` 系列的 web profile 上验证
profile	`web`
平台	Linux / WSL2（其实浏览器端逻辑与平台无关）
Node	`>= 20`（仅安装脚本用到）
浏览器	需要 `localStorage` 与 CSS 自定义属性（现代浏览器均可）

2.4 `package.json` 里的声明

"peerDependencies": { "dsh-dream-skin": "*" },
"dshDependencies": {
  "plugins": [{ "name": "dsh-dream-skin", "required": true, "provides": "settings.dreamSkin.item 插槽 + 壁纸层" }],
  "programs": [], "services": [], "platform": ["Linux", "WSL2"], "node": ">=20"
}

3. 安装

git clone https://github.com/ankhishtar2-lang/dsh-wallpaper-position.git
cd dsh-wallpaper-position
bash scripts/install.sh
systemctl --user restart dsh-web-profiled.service      # 由你手动执行

手动安装：把目录拷到 $DSH_HOME/profiles/web/node_modules/dsh-wallpaper-position/，把 "dsh-wallpaper-position" 追加进 profile package.json 的 dsh.profile.bundles，重启。

⚠️ 硬红线（这个插件踩过两次）：host 半必须导出 apply，哪怕是空实现： export function apply() {}。dsh 的插件加载器 fail-fast 且不隔离 —— 一个条目 apply 失败会让整棵插件树 boot 失败，dsh web 完全起不来，而「用来写插件的工具」正是 dsh 自己，于是会把自己钉死、只能从外部终端救。症状：3080 没有监听（用 ss -lntp | grep 3080 判断，不要用 ps）。急救：在 profile patch 层给该条目加 disabled: true，再重启。

安装方式补充：从 npm 安装（可选）

本包的 package.json 已按 npm 发布要求准备好（去掉 private、用 files 白名单控制内容）。发布到 npm 后即可用 dsh 自己的命令安装（dsh plugin add 本质就是 pnpm add）：

dsh plugin --profile web add dsh-wallpaper-position

自己发布（需要你自己的 npm 账号；scripts/publish.sh 不接触也不保存任何 token）：

npm login
bash scripts/publish.sh --dry     # 自检 + 列出将要发布的文件，不发布
bash scripts/publish.sh           # 真正发布（改过代码要先升 version，同版本号不可覆盖）

发布后请同步更新 README 与上游收录表的描述，保持「描述属实」这一条成立。

4. 使用

先在 dream-skin 里选好壁纸；
打开 设置 → 外观，找到最下方的「壁纸位移（仅对当前这张图生效）」；
用 −10 / −1 / +1 / +10 或直接输入数字微调（X 向右为正，Y 向下为正）；
换到别的壁纸会自动加载那张图自己的位移；点「恢复默认位置」清零当前这张。

数据存放位置（只在本机浏览器里）：

位置	内容
`localStorage["dsh-wallpaper-position:map"]`	`{ "<壁纸内容哈希>": { "x": number, "y": number }, ... }`
`localStorage["dsh-dream-skin:wallpaper"]`	dream-skin 写入的当前壁纸 data URL（本插件只读）
CSS 变量 `--wp-x` / `--wp-y`（`:root`）	当前生效的位移

生效方式：往 <head> 注入一条规则

body > [style*="background-image"][style*="position:fixed"],
body > [style*="background-image"][style*="position: fixed"] {
  background-position: calc(50% + var(--wp-x, 0px)) calc(50% + var(--wp-y, 0px)) !important;
}

5. 已验证 / 已知限制

已验证

node --check 语法通过；host 半 apply 存在；dsh --profile web --dump-config 退出码 0；
设置行会注册进 settings.dreamSkin.item，控件用原生 DOM 构造（不吃 React 渲染歧义）。

已知限制

只做位移：没有缩放、旋转、翻转，也没有鼠标直接拖拽（想要这些要另写）；
依赖 dream-skin 的 DOM 与 localStorage 键名，上游一改就可能失效（静默失效，不报错）；
位移是「裁切平移」：cover 模式下把画面推太多会露出背景边缘，属预期行为；
早期版本用 react/jsx-runtime 的 jsx() 渲染控件时在界面上显示为空白方块，现已全部改为 document.createElement —— 如果你改了 UI 代码，请保持这个做法；
主题变量缺失时用固定颜色兜底；极端主题下观感可能一般。

6. 卸载

bash scripts/uninstall.sh
systemctl --user restart dsh-web-profiled.service

卸载后位移数据仍留在浏览器 localStorage 里，需要的话在控制台执行：

localStorage.removeItem('dsh-wallpaper-position:map')

7. 目录结构

dsh-wallpaper-position/
├── package.json          # dsh.bundle / dsh.client / peerDependencies / dshDependencies
├── cordis.patch.yml      # loader 条目：id=wallpaper-position
├── lib/
│   ├── index.js          # host 半：只有空 apply()（但绝不能省）
│   └── client.js         # 浏览器半：位移引擎 + 设置项 UI（原生 DOM）
├── scripts/              # install.sh / uninstall.sh
├── LICENSE
└── README.md

8. 许可

dsh-wallpaper-position

[!WARNING] 本仓库是 vibe coding 产物。 代码由作者与 AI（DeepSeek Harness 会话）对话生成、多轮迭代而来，没有经过人工逐行审计，也只在作者本机环境（WSL2 + dsh 0.1.5-rc.1 系列）实测过。请自行审阅后再使用；不要直接用于生产或安全敏感场景。代码按 MIT「按原样（AS IS）」提供，不附带任何担保，风险自负。

A vibe-coded satellite plugin for dsh-dream-skin: nudge the wallpaper's position per image (X/Y in pixels) from 设置 → 外观, remembered separately for every wallpaper.

1. 它做什么

在 设置 → 外观（dream-skin 页） 注册一项设置：「壁纸位移（仅对当前这张图生效）」；
两个数值输入框（X / Y），步进 1 px，范围 ±5000 px，配 −10 / −1 / +1 / +10 微调按钮与「恢复默认位置」；
按图片记忆：键是当前壁纸内容哈希，换图即换一套位移，互不干扰；
纯前端实现：只写 CSS 变量，不动图片、不改 dream-skin 的任何文件；
即时生效，无需重启 dsh（改完立刻反映到壁纸上）。

2. 依赖声明（重要）

2.1 运行期硬依赖：`dsh-dream-skin` 插件

依赖点	说明
设置插槽 `settings.dreamSkin.item`	本插件的设置项注册在这里（`id: wallpaper-position`，`order: 90`）。插槽不存在时，插件只是「隐身」，不影响 dsh 启动
壁纸层 DOM	依赖 dream-skin 把壁纸渲染成 `body` 直接子节点、且内联样式里同时含 `background-image` 与 `position:fixed` 的元素（本插件用属性选择器命中它）
壁纸来源	读取 `localStorage["dsh-dream-skin:wallpaper"]`（dream-skin 写入的当前壁纸 data URL）来算「这张图」的身份

dream-skin 改了壁纸层的 DOM 结构或存储键名时，本插件会静默失效（不会报错、也不影响 dsh）。

2.2 无其它依赖

不需要任何外部程序、系统服务、网络访问；
host 半只有一个空 apply()：不注册路由、不读写文件、不联网；所有逻辑都在浏览器半。

2.3 平台与版本

项目	要求
dsh 核心	在 `0.1.5-rc.1` 系列的 web profile 上验证
profile	`web`
平台	Linux / WSL2（其实浏览器端逻辑与平台无关）
Node	`>= 20`（仅安装脚本用到）
浏览器	需要 `localStorage` 与 CSS 自定义属性（现代浏览器均可）

2.4 `package.json` 里的声明

"peerDependencies": { "dsh-dream-skin": "*" },
"dshDependencies": {
  "plugins": [{ "name": "dsh-dream-skin", "required": true, "provides": "settings.dreamSkin.item 插槽 + 壁纸层" }],
  "programs": [], "services": [], "platform": ["Linux", "WSL2"], "node": ">=20"
}

3. 安装

git clone https://github.com/ankhishtar2-lang/dsh-wallpaper-position.git
cd dsh-wallpaper-position
bash scripts/install.sh
systemctl --user restart dsh-web-profiled.service      # 由你手动执行

手动安装：把目录拷到 $DSH_HOME/profiles/web/node_modules/dsh-wallpaper-position/，把 "dsh-wallpaper-position" 追加进 profile package.json 的 dsh.profile.bundles，重启。

⚠️ 硬红线（这个插件踩过两次）：host 半必须导出 apply，哪怕是空实现： export function apply() {}。dsh 的插件加载器 fail-fast 且不隔离 —— 一个条目 apply 失败会让整棵插件树 boot 失败，dsh web 完全起不来，而「用来写插件的工具」正是 dsh 自己，于是会把自己钉死、只能从外部终端救。症状：3080 没有监听（用 ss -lntp | grep 3080 判断，不要用 ps）。急救：在 profile patch 层给该条目加 disabled: true，再重启。

安装方式补充：从 npm 安装（可选）

dsh plugin --profile web add dsh-wallpaper-position

自己发布（需要你自己的 npm 账号；scripts/publish.sh 不接触也不保存任何 token）：

npm login
bash scripts/publish.sh --dry     # 自检 + 列出将要发布的文件，不发布
bash scripts/publish.sh           # 真正发布（改过代码要先升 version，同版本号不可覆盖）

发布后请同步更新 README 与上游收录表的描述，保持「描述属实」这一条成立。

4. 使用

先在 dream-skin 里选好壁纸；
打开 设置 → 外观，找到最下方的「壁纸位移（仅对当前这张图生效）」；
用 −10 / −1 / +1 / +10 或直接输入数字微调（X 向右为正，Y 向下为正）；
换到别的壁纸会自动加载那张图自己的位移；点「恢复默认位置」清零当前这张。

数据存放位置（只在本机浏览器里）：

位置	内容
`localStorage["dsh-wallpaper-position:map"]`	`{ "<壁纸内容哈希>": { "x": number, "y": number }, ... }`
`localStorage["dsh-dream-skin:wallpaper"]`	dream-skin 写入的当前壁纸 data URL（本插件只读）
CSS 变量 `--wp-x` / `--wp-y`（`:root`）	当前生效的位移

生效方式：往 <head> 注入一条规则

body > [style*="background-image"][style*="position:fixed"],
body > [style*="background-image"][style*="position: fixed"] {
  background-position: calc(50% + var(--wp-x, 0px)) calc(50% + var(--wp-y, 0px)) !important;
}

5. 已验证 / 已知限制

已验证

node --check 语法通过；host 半 apply 存在；dsh --profile web --dump-config 退出码 0；
设置行会注册进 settings.dreamSkin.item，控件用原生 DOM 构造（不吃 React 渲染歧义）。

已知限制

只做位移：没有缩放、旋转、翻转，也没有鼠标直接拖拽（想要这些要另写）；
依赖 dream-skin 的 DOM 与 localStorage 键名，上游一改就可能失效（静默失效，不报错）；
位移是「裁切平移」：cover 模式下把画面推太多会露出背景边缘，属预期行为；
早期版本用 react/jsx-runtime 的 jsx() 渲染控件时在界面上显示为空白方块，现已全部改为 document.createElement —— 如果你改了 UI 代码，请保持这个做法；
主题变量缺失时用固定颜色兜底；极端主题下观感可能一般。

6. 卸载

bash scripts/uninstall.sh
systemctl --user restart dsh-web-profiled.service

卸载后位移数据仍留在浏览器 localStorage 里，需要的话在控制台执行：

localStorage.removeItem('dsh-wallpaper-position:map')

7. 目录结构

dsh-wallpaper-position/
├── package.json          # dsh.bundle / dsh.client / peerDependencies / dshDependencies
├── cordis.patch.yml      # loader 条目：id=wallpaper-position
├── lib/
│   ├── index.js          # host 半：只有空 apply()（但绝不能省）
│   └── client.js         # 浏览器半：位移引擎 + 设置项 UI（原生 DOM）
├── scripts/              # install.sh / uninstall.sh
├── LICENSE
└── README.md

ankhishtar2-lang/dsh-wallpaper-position

dsh-wallpaper-position

1. 它做什么

2. 依赖声明（重要）

2.1 运行期硬依赖：`dsh-dream-skin` 插件

2.2 无其它依赖

2.3 平台与版本

2.4 `package.json` 里的声明

3. 安装

安装方式补充：从 npm 安装（可选）

4. 使用

5. 已验证 / 已知限制

6. 卸载

7. 目录结构

8. 许可

Community comments

ankhishtar2-lang/dsh-wallpaper-position

dsh-wallpaper-position

1. 它做什么

2. 依赖声明（重要）

2.1 运行期硬依赖：`dsh-dream-skin` 插件

2.2 无其它依赖

2.3 平台与版本

2.4 `package.json` 里的声明

3. 安装

安装方式补充：从 npm 安装（可选）

4. 使用

5. 已验证 / 已知限制

6. 卸载

7. 目录结构

8. 许可

Community comments

ankhishtar2-lang/dsh-wallpaper-position

dsh-wallpaper-position

1. 它做什么

2. 依赖声明（重要）

2.1 运行期硬依赖：dsh-dream-skin 插件

2.2 无其它依赖

2.3 平台与版本

2.4 package.json 里的声明

3. 安装

安装方式补充：从 npm 安装（可选）

4. 使用

5. 已验证 / 已知限制

6. 卸载

7. 目录结构

8. 许可

Community comments

ankhishtar2-lang/dsh-wallpaper-position

dsh-wallpaper-position

1. 它做什么

2. 依赖声明（重要）

2.1 运行期硬依赖：dsh-dream-skin 插件

2.2 无其它依赖

2.3 平台与版本

2.4 package.json 里的声明

3. 安装

安装方式补充：从 npm 安装（可选）

4. 使用

5. 已验证 / 已知限制

6. 卸载

7. 目录结构

8. 许可

Community comments

2.1 运行期硬依赖：`dsh-dream-skin` 插件

2.4 `package.json` 里的声明

2.1 运行期硬依赖：`dsh-dream-skin` 插件

2.4 `package.json` 里的声明