Bundle

dsh-wallpaper-position

dsh-dream-skin 的附属插件：在「设置 → 外观」里按图片记忆调整壁纸位移（X/Y 像素微调）

Source: ArimaKana-Akane
License: MIT
Updated: Updated 9 hours ago

Readme

# 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](https://github.com/RevolutionLA/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` 里的声明

```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. 安装

```bash
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`）：

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

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

```bash
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>` 注入一条规则

```css
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
bash scripts/uninstall.sh
systemctl --user restart dsh-web-profiled.service
```

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

```js
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](LICENSE)。
再次提醒：**vibe coding 产物，未经人工逐行审计，按「原样」提供，风险自负。**

Install

dsh plugin --profile web add github:ArimaKana-Akane/dsh-wallpaper-position

Profile: web

This source has no pinned commit, so a later push upstream changes what installs. Prefer pinning a commit.

Source