← Back to home@ankhishtar2-lang

dsh-wallpaper-position

dsh-dream-skin satellite: per-image wallpaper position (X/Y px) settings row. Vibe-coded.

Stars
0
Language
JavaScript
Created
Sep 11, 2026
Updated
Sep 11, 2026
Theme
GitHub repo

Introduction

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.

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 上验证
profileweb
平台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. 使用

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

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

位置内容
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. 许可

MIT © 2026 ankhishtar2-lang —— 见 LICENSE。 再次提醒：vibe coding 产物，未经人工逐行审计，按「原样」提供，风险自负。