# 桌面端桌宠模式（独立窗口）使用说明

> 这篇说明写给**第一次打开桌宠、不太懂技术细节**的你。只要按下面的步骤做，就能把角色放到独立的桌面上。
> 如果你只想知道"我到底要不要做点什么"，直接看 **第二部分**。

---

## 一、这是什么？

开启"桌宠模式"后，角色的 Live2D 形象会出现在一个**独立的小窗口**里：

- 背景透明，没有系统窗口边框
- **始终显示在其他窗口之上**
- 主窗口最小化、或你切换到别的应用时，角色仍然停在桌面角落
- 它和主窗口里的角色是同一个，只是独立显示，不占主界面

> 想让它"浮在其他应用上面"，就要用到这种独立窗口。

---

## 二、我到底要不要动手？

先判断你属于下面哪种情况：

| 你的情况 | 要不要动手 |
| --- | --- |
| 用的是**开发版 / 未打包**的 DSH Desktop | ✅ 通常**什么都不用做**，直接用 |
| 用的是**安装版 TokensCowork** | ⚠️ 需要给它配一个运行环境，见 **第三步** |
| 用的是**浏览器版 `dsh web`** | ❌ 浏览器无法创建系统窗口，桌宠只能显示在页面内，无需配置 |

> 如果你现在看到的是"**页面内可拖动的角色** + 右下角一行小提示"，说明属于**安装版但缺运行环境**这一种，请继续看第三步。

---

## 三、给独立窗口配一个运行环境（只有安装版需要做）

> 下面 A、B、C 只需做**任意一项**。**推荐 A**，最直观。

### 方法 A：在设置里填路径（推荐）

1. 打开 TokensCowork。
2. 进入插件的**形象 / 设置**页面。
3. 在 **「桌宠 Electron 路径」** 里填一个**本机已有的 `electron.exe` 的完整路径**，例如：
   ```
   C:\Users\你的用户名\electron\electron.exe
   ```
   （完整路径 = 能直接双击打开的那个 `electron.exe` 文件的所在位置）
4. 点**保存**。
5. **重启 TokensCowork**（这一步很关键）。
6. 切到「桌宠」模式 → 角色会出现在独立小窗里。

### 方法 B：把 electron.exe 放进插件目录（一劳永逸）

1. 先拿到一个 `electron.exe`（见第四步）。
2. 把解压好的 `electron.exe` 连同它旁边的文件，整体放到：
   ```
   <插件目录>\vendor\win32-x64\
   ```
   - `win32-x64` 是 Windows 64 位的目录名。
3. 重启 TokensCowork，再切到「桌宠」模式。

> 方法 B 需要你找得到插件的安装目录，适合有一定基础的用户。

### 方法 C：设置环境变量（适合懂命令行的用户）

- 新建一个名为 `DSH_LIVE2D_AVATAR_ELECTRON` 的环境变量，值填 `electron.exe` 的完整路径。
- 重启 TokensCowork。

---

## 四、怎么拿到一个 electron.exe（小白版）

1. 打开浏览器，访问 Electron 官方的发布页：
   👉 <https://github.com/electron/electron/releases>
2. 找一个稳定版本，下载 **`electron-vXX.X.X-win32-x64.zip`**。
   > 认准 `win32-x64` 字样，这是给 Windows 64 位用的。
3. 把 zip 解压到任意一个方便找的目录，比如 `C:\electron`。
4. 解压后的 `electron.exe` 就是你要用的文件。

> 如果你本机之前装过 Node.js / Electron 相关工具，也可以直接用
> `你安装的路径\node_modules\electron\dist\electron.exe`。
> 也可以在有 Node 的机器上运行 `npm install electron`，然后把生成的
> `node_modules\electron\dist\electron.exe` 复制出来。

---

## 五、怎么判断成功没有？

切到「桌宠」模式后，看结果：

- ✅ 角色出现在**透明、无边框、置顶**的小窗里 → 成功。
- ⚠️ 角色仍留在主窗口里，右下角出现提示 → 说明没检测到运行环境。回到第三步检查路径，确认 `electron.exe` 真的存在，并**重启 TokensCowork**。

---

## 六、常见问题

**Q：我填了路径，为什么还是页面内浮层？**
A：按顺序检查：
1. 路径填的是**文件** `electron.exe`，不是文件夹；
2. 保存后**重启了 TokensCowork**；
3. 那个 `electron.exe` 能独立运行（双击它，能弹出一个空窗口就是好的）。

**Q：会不会和我主窗口里的角色重复显示？**
A：不会。插件检测到独立窗口在使用时，主窗口内就不再显示同一个角色。

**Q：关掉桌宠会影响 DSH 主程序吗？**
A：不会。桌宠是插件拉起的独立小进程，只负责显示角色；退出 TokensCowork 会一并关闭它。

**Q：它安全吗？**
A：桌宠窗口只从你自己的 DSH 服务加载角色资源，不访问外部网络。

**Q：我是浏览器版，是不是就不能用独立桌宠了？**
A：浏览器无法创建系统窗口，所以浏览器版只能显示**页面内浮层**。要用独立窗口，需使用安装版 / 开发版的 DSH Desktop。

---

## 七、一点背景（想了解再看）

DSH Desktop 把插件运行在受限的子进程里，插件**无法自己创建系统窗口**。所以独立桌宠需要借助一个通用的 Electron 运行时来"代开"窗口。

插件会自动按这个顺序找 Electron：

1. 设置里填的「桌宠 Electron 路径」
2. 环境变量 `DSH_LIVE2D_AVATAR_ELECTRON`
3. 插件 `vendor/` 目录
4. 开发版 DSH Desktop 自带的 Electron
5. 系统 `PATH` 上的 Electron

**找到就用，找不到就退回页面内浮层**，并在界面提示。