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 wallpaper (X/Y in pixels) from 设置 → 外观, remembered separately for every one.
dsh-dream-skin 的壁纸是整屏铺满（background-size: cover、
background-position: center）的固定层。构图偏左/偏上的图会压住聊天文字，
而它本身没有提供位移设置。这个插件补上这一块：在设置页里按像素微调，且每张壁纸各自记忆。
1. 它做什么
- 在 设置 → 外观（dream-skin 页） 注册一项设置：「壁纸位移（仅对当前壁纸生效）」；
- 两个数值输入框（X / Y），步进 1 px，范围 ±5000 px，配
−10 / −1 / +1 / +10微调按钮与「恢复默认位置」； - 按壁纸记忆：键是当前壁纸内容哈希，并区分类型（
image/url/gradient），
换图 / 换 URL / 换渐变即换一套位移，互不干扰；换壁纸后面板数字会跟着同步成新壁纸的记忆值； - 纯前端实现：只写 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） |
当前生效的位移 |
生效方式：往 `` 注入一条规则
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键名，上游一改就可能失效（静默失效，不报错）； - 位移规则会匹配任何「body 下、内联含
background-image且position:fixed的层」，
没有限定到 dream-skin 那一个元素（dream-skin 的壁纸层是匿名div，没有 class/id 可锚定）。
如果你同时装了别的整屏背景层插件，偏移量会同样作用到它们身上。
偏移为 0 时表达式等价于center，与这些层的默认值一致，所以只有在你主动设了非 0 位移时才会看出来。
这是刻意保留的取舍：给选择器加更多条件（例如z-index:-1）一旦和上游的内联样式序列化
不一致，功能就会静默失效，代价比这点交叉影响大； - 位移是「裁切平移」：
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 / publish.sh
├── LICENSE
└── README.md
8. 许可
MIT © 2026 ankhishtar2-lang —— 见 LICENSE。
再次提醒：vibe coding 产物，未经人工逐行审计，按「原样」提供，风险自负。
