# dsh-bg-beautify 桌面版安装教程（DeepSeek Harness Desktop）

> 适用：**DeepSeek Harness 桌面版（Windows x64）**——即从官方 `.exe` 安装程序装出来的那个 Electron 应用。
> 如果你是从源码跑 `pnpm dsh web`，请改看 [安装教程-INSTALL.zh.md](./安装教程-INSTALL.zh.md)。

桌面版**不需要**你自己装 Node、pnpm，也**不需要**任何源码目录：安装包里已经带了 Node 运行时、pnpm 和 `dsh` CLI，插件用官方机制装进桌面版自己的 profile 即可——**不改任何源码（`apps/web`、`packages/client` 一概不动），不需要重新构建前端**。

---

## 0. 一句话流程

```
启动桌面版一次（初始化 profile） → 完全退出 → 注册 dsh 命令 → dsh plugin add → 重新打开桌面版
```

全程约 1 分钟。

---

## 1. 前置确认

- 桌面版已能正常启动，并且**至少启动过一次**——首次启动会创建保留 profile 目录 `%USERPROFILE%\.dsh\profiles\desktop`。没启动过就直接跑安装命令会报：
  `Open DeepSeek Harness Desktop once to initialize its profile, then fully quit it before running dsh plugin --profile desktop.`
- **完全退出桌面版**（见下面的说明），避免安装时和正在运行的实例抢 profile 的文件锁。
- 打开一个**终端**（Windows Terminal / PowerShell 均可）。

### 关窗口 ≠ 退出

桌面版关掉窗口后默认**继续在系统托盘运行**。要真正退出，二选一：

- 标题栏菜单 **应用 → 退出 DeepSeek Harness**；
- 或右键**系统托盘图标 → 退出**。

> 有任务在运行时会弹确认框，按提示确认即可。

### 找到桌面版安装目录

后面要用到 `<安装目录>\resources\runtime\cli\bin\dsh.cmd`。安装时若没改路径，一般是 `%LOCALAPPDATA%\Programs\DeepSeek Harness`；不确定就跑：

```powershell
(Get-ItemProperty 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*' |
  Where-Object DisplayName -like '*DeepSeek Harness*').InstallLocation
```

也可以直接：桌面快捷方式 → 右键 → **打开文件所在的位置**。

---

## 2. 让 `dsh` 命令可用（二选一）

### 方式 A：用桌面版自带的菜单注册（推荐）

桌面版窗口**左上角标题栏**有一排原生菜单（「应用」「编辑」）：

**应用 → 管理 dsh 命令…**

- 若显示「将 Desktop 命令添加到终端」→ 点 **安装**；
- 它做的是：把 `<安装目录>\resources\runtime\cli\bin` 写进**当前用户 PATH**，让终端里的 `dsh` 指向桌面版自带的 CLI；
- 官方行为说明：**现有命令会被保留**，不会改动你已有的其他 `dsh` 安装或 shell 启动文件；
- 完成后按提示**打开一个新终端**，运行：

```powershell
dsh --version
```

> 已经开着的终端读不到新的 PATH，必须**新开**一个。

### 方式 B：不改 PATH，直接用完整路径

```powershell
& "E:\app\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" --version
```

把路径换成你自己的安装目录即可。下面所有 `dsh ...` 命令都可以等价替换成这种写法。

---

## 3. 安装插件

```powershell
dsh plugin --profile desktop add github:halosb/dsh-bg-beautify
```

两个关键点，弄错就不会生效：

| 要点 | 说明 |
|---|---|
| **必须用 `--profile desktop`** | 桌面版跑的是保留 profile `desktop`。`--profile web` 是 `dsh web`（浏览器/源码版）那套 profile，装进去在桌面版里**不会**加载 |
| **不要加 `pnpm` 前缀** | 源码环境下才写 `pnpm dsh plugin ...`；桌面版的 pnpm 由安装包提供，直接用 `dsh` 即可 |

命令做了三件事：

1. 在 `%USERPROFILE%\.dsh\profiles\desktop` 目录里执行 `pnpm add`，把插件包装进**该 profile 自己的** `node_modules`；
2. 因为这个包声明了 `dsh.bundle`，自动把 `dsh-bg-beautify` 追加进 profile `package.json` 的 `dsh.profile.bundles` 列表；
3. 该 bundle 自带的 `cordis.patch.yml` 会在启动时插入一行 `id: bg-beautify / name: dsh-bg-beautify`。

装完输出大致是：

```
dependencies:
+ dsh-bg-beautify github:halosb/dsh-bg-beautify
Done in 3.6s using pnpm v11.7.0
```

### 从本地目录安装（可选，适合自己改代码调试）

```powershell
dsh plugin --profile desktop add D:\path\to\dsh-bg-beautify
```

### 验证确实装进去了

```powershell
dsh plugin --profile desktop list --depth 0
```

应看到 `dsh-bg-beautify <版本>`。再看一眼 profile 配置：

```powershell
Get-Content "$env:USERPROFILE\.dsh\profiles\desktop\package.json"
```

`dependencies` 和 `dsh.profile.bundles` 里都应出现 `dsh-bg-beautify`。

> ⚠️ **桌面版不能用 `--dump-config` 验证**。`dsh --profile desktop --dump-config` 会被直接拒绝：
>
> ```
> error: profile "desktop" is managed exclusively by the Electron application
> ```
>
> 这是设计如此——`desktop` 是桌面版的保留 profile，**只有桌面版自带的 CLI** 才对它开放 `plugin` 子命令，其他 `dsh` 一律拒绝。所以请用上面的 `list` + 读 `package.json` 来验证。

> `%USERPROFILE%\.dsh` 是默认位置；若你设过 `DSH_HOME` 环境变量，profile 目录以 `DSH_HOME\profiles\desktop` 为准。

---

## 4. 重启桌面版（关键一步，别跳过）

插件分两半：host 半边（提供 `/bg/*`、`/bg/we/*`、`/bg/conv/*` 路由）和浏览器半边（`client.js`，背景层与设置页）。

浏览器半边由 `dsh-client-modules` 在**启动时**扫描包、把 `/plugins/dsh-bg-beautify/client.js` 编进 `window.__DSH_BOOT__` 引导图，**必须重启才会出现**。

**完全退出桌面版（连托盘图标一起退）→ 重新打开。**

---

## 5. 验证安装成功

1. 打开 **设置 → 背景美化**，能看到分区，顶部有「当前背景」状态行和五个标签：**背景图 / WE 壁纸 / 转换视频 / 光晕 / 品牌定制**。
2. 默认无背景图（只做半透明）：主区 0.25、侧边栏 0.5、卡片 0.7、输入区 0.75。
3. 在 **背景图** 标签里点「上传本地图片」或填一个图片 URL → **整页立刻出现背景**。
4. 想看客户端 bundle 有没有加载，按 **F12** 打开开发者工具 → Network，刷新后应能请求到 `GET /plugins/dsh-bg-beautify/client.js?rev=...` 且状态 **200**。

---

## 6. 快速上手

| 标签 | 内容 |
|---|---|
| **背景图** | 图片 URL / 本地上传 / 尺寸位置 / 背景固定 / 视频播放速度 / 四个透明度 / 文字颜色 / 背景纱幕 |
| **WE 壁纸** | 扫描（扫描即自动转换符合条件的场景壁纸）/ 壁纸库路径 / 缩略图网格点选即用 |
| **转换视频** | 打开文件夹 / 刷新 / 实时进度条 / 已转换 mp4·GIF 列表 |
| **光晕** | 输入框呼吸光晕全部设置（含心情光晕） |
| **品牌定制** | favicon / 欢迎语 / 标签页标题后缀 |

几个桌面版上同样适用的要点：

- **背景图三种写法**：`/bg/文件名`（插件内置伺服）、`https://` 外链、`data:` URI；留空 = 无图。
- **上传本地图片**最省事：选文件后自动写进 DSH 数据目录的 `assets\` 并填好 `/bg/文件名`（同名也不会覆盖已有图片，会自动加 `-2`）。
  > 不能直接填 `C:\...`：浏览器禁止 http 页面加载本地路径。
- **大图发糊**：取消勾选「背景固定」（Chromium 对 fixed 大背景会低分辨率光栅化），并把透明度调低让图透出来。
- **Wallpaper Engine** 需要本机已装 Steam + Wallpaper Engine 且壁纸已订阅下载；纯 3D / 粒子场景没有可用纹理，转不出动画属正常。
- **转换结果**在 `图片\dsh-bg-beautify\we-converted`，设置页「打开文件夹」一键直达。

数据文件（**在 DSH 数据目录里，不在插件目录**，更新插件不会丢）：

```
%USERPROFILE%\.dsh\plugin-data\desktop\dsh-bg-beautify\config.json   # 你的设置
%USERPROFILE%\.dsh\plugin-data\desktop\dsh-bg-beautify\assets\       # 你上传的背景图
```

> 0.4.0 起从插件目录（`…\node_modules\dsh-bg-beautify\`）迁到这里：那个目录由 pnpm 管理，
> 一次 `dsh plugin update` 就会把它重建，老版本的设置和已上传的图片会一起消失。
> 首次启动会自动把老文件搬过来（不删除包内自带的 `assets/1.png`），无需手动操作。
> 若你设过 `DSH_HOME`，把 `%USERPROFILE%\.dsh` 换成 `%DSH_HOME%`。

> 完整的设置项与默认值见 [README 的「默认值」](./README.md#默认值)。

---

## 7. 更新与卸载

**更新到最新版**：

```powershell
dsh plugin --profile desktop update dsh-bg-beautify
```

然后重启桌面版。

**卸载**：

```powershell
dsh plugin --profile desktop remove dsh-bg-beautify
```

然后重启桌面版即恢复默认外观。你的设置与上传的图片在 DSH 数据目录（`…\.dsh\plugin-data\desktop\dsh-bg-beautify\`），**不会被卸载删掉**，要彻底还原就手动删除该目录。

---

## 8. 排障

| 现象 | 原因 / 处理 |
|---|---|
| 设置里没有「背景美化」/ 页面没有任何变化 | 没重启桌面版。客户端引导图只在启动时组装——**完全退出（含托盘）**再打开 |
| `error: profile "desktop" is managed exclusively by the Electron application` | 你调用的不是桌面版自带的 `dsh`（PATH 上另一个 `dsh` 优先）。用第 2 节的**方式 B**完整路径调用，或用「应用 → 管理 dsh 命令…」修复注册 |
| `Open DeepSeek Harness Desktop once to initialize its profile…` | 桌面版从没启动过。先启动一次，再完全退出，然后重跑安装命令 |
| `error: required option '--profile <name>' not specified` | `--profile desktop` 是 `plugin` 子命令的必需参数：`dsh plugin --profile desktop add …`（`--profile` 放在 `plugin` **后面**） |
| 新终端里 `dsh` 还是旧命令 / 不是桌面版 | ① PATH 变更对**已开着**的终端无效，新开一个；② 装了多个 `dsh` 时优先级问题，应用会提示「另一个 dsh 的优先级更高。请移除或调整该安装的顺序…」——也可以直接用完整路径 |
| 安装命令卡住不动 | 桌面版正在运行时会持有 profile 的文件锁，`dsh plugin` 最多等 120 秒。完全退出桌面版后重跑 |
| 报 pnpm 阻止了构建脚本（`allowBuilds` / `prepare`） | 本插件是纯 JS、无构建步骤，正常不会触发。若确实被拦，按命令打印的提示把对应键加进 `%USERPROFILE%\.dsh\profiles\desktop\pnpm-workspace.yaml` 的 `allowBuilds`，再重跑 |
| 页面无背景图 | ① 没重启桌面版；② F12 → Network 看 `/plugins/dsh-bg-beautify/client.js` 是否 200，404 说明没装成功或没重启 |
| `/bg/xxx.jpg` 打开 404 | 文件名大小写不一致 / 没上传过 / 格式不支持（支持 jpg/png/gif/webp/avif/svg）。上传的图在 DSH 数据目录的 `assets\`，随包的默认图在插件目录的 `assets\`，优先取前者 |
| 设置了图片但显示不出来 | 用了 `C:\...` 或 `file:///...`？浏览器禁止 http 页面加载本地路径，改用「上传本地图片」或 `/bg/<文件名>` |
| 视频壁纸不播放 | 确认是 `.mp4`/`.webm`；浏览器自动播放策略要求静音（插件已强制静音）；窗口最小化或系统开了「减少动态效果」时会暂停并定格预览图（预期省电行为） |
| WE 扫描不到壁纸 | 本机需已装 Steam + Wallpaper Engine 且壁纸已下载；自动探测失败时在「壁纸库路径」手填 `…\steamapps\workshop\content\431960` 后重扫 |
| 转换提示「无纹理」 | 纯 3D / 粒子场景由 WE 私有引擎实时渲染，无公开格式可转，属格式物理限制（非插件缺失） |

---

## 附：桌面版 vs 源码版对照

| | 桌面版（Windows） | 源码版 / `dsh web` |
|---|---|---|
| profile | `desktop`（保留，仅桌面版 CLI 可管理） | `web` |
| 命令前缀 | `dsh` | `dsh` 或 `pnpm dsh` |
| Node / pnpm | 安装包自带，无需自备 | 需自备 Node ≥ 22 + pnpm |
| 配置文件 | `%USERPROFILE%\.dsh\profiles\desktop\package.json` | `%USERPROFILE%\.dsh\profiles\web\package.json` |
| 生效方式 | 重启桌面版（完全退出，含托盘） | 重启 `dsh web` |
| 配置校验 | `dsh plugin --profile desktop list`（**不支持** `--dump-config`） | `pnpm dsh --profile web --dump-config` |

---

## 反馈

- 📮 **反馈邮箱**：i@halosb.com
- 作者：芝麻 (halosb)

## 许可证

[MIT](./LICENSE)