# 桌面端适配说明

本插件同时支持两种运行形态：

1. **web profile**（`dsh web`）：Host 半侧通过 `webServer.tapIndex` 往 `index.html` 注入启动界面。
2. **DeepSeek Harness Desktop**（Electron）：可能改用 `file://` + IPC 下发前端，`tapIndex` 不会被调用。
   此时由**浏览器半侧自举**（`lib/client.js` 的 `selfBoot()`）。

两条路径用一个 `window.__DSH_UMBRELLA_BOOT__` 标记握手，保证**不会重复播放**。

> **边界说明**：自举依赖 `/dsh-umbrella/splash.css` 与 `/dsh-umbrella/splash.js` 两条路由。
> 如果某个桌面端构建**完全没有** HTTP 路由层（纯 `file://` 直读，且不注册插件路由），
> 自举会因 404 而失败；此时插件按设计**优雅降级**：移除根节点、解开滚动锁、页面照常可用，
> 只是不播放动画。这种情况需要在宿主侧提供静态资源通道，插件本身无法绕过。

---

## 一、自举判定

`selfBoot()` 只在以下条件全部成立时才动手：

| 条件 | 说明 |
|---|---|
| `__DSH_UMBRELLA_BOOT__` 为空 | Host 没注入过，本侧也没自举过 |
| `__DSH_UMBRELLA__` 为空 | 页面上没有 Host 注入的配置 |
| 没有 `#dsh-umbrella-root` | DOM 里没有现成的根节点 |
| `__DSH_UMBRELLA_FAILED__ !== true` | 之前没失败过（失败过就不再扑一次） |

任一步失败都会 `release(false)`：移除根节点、解开滚动锁、打 `FAILED` 标记，把页面原样还回去。

---

## 二、Windows 标题栏透明化

Electron 在 Windows 上用 `titleBarOverlay` 绘制最小化 / 最大化 / 关闭按钮，底色跟随应用主题。
启动动画播放时，右上角会留一块与应用主题同色的方块：第一幕纯黑时是一条亮带，
临床白底板阶段三个深色图标压在浅色块上，色差刺眼。

处理方式：

1. preload 会挂一个用于测色的隐藏 `<span>` 探针，其 `background-color` 引用
   `--dsw-specific-sidebar-fill`。
2. 播放期间把探针的内联 `background-color` / `color` 改成 `rgba(0,0,0,0)`，
   逼宿主发出 `setTitleBarOverlay({ color: transparent, symbolColor: transparent })`。
3. 同时把 `<html>` 上的相关 token 改成透明，作为双保险。
4. 探针可能被应用重挂（主题切换 / 热重载），代码会在节点脱离文档后重新查找，并用
   600ms 间隔自愈；连续两次确认透明后停止。
5. 揭幕 / 跳过 / 自举失败 / 9 秒兜底一律还原；另有 60 秒硬上限，动画卡住也不会把按钮永久藏住。

**只在 Windows 桌面端生效**：判据是 UA 含 `Win`，且协议为 `dsh-app:` 或文档带
`data-windows-titlebar` 标记。浏览器与 macOS 下整段空转，不碰任何样式。

排查把手：`window.__DSH_UMBRELLA_CHROME__`（`hide()` / `show()` / `isDesktopWin()`）。

---

## 三、自举失败的表现

如果桌面端出现「装了但没动画」，按顺序检查：

1. `dsh plugin --profile desktop list` 是否有 `dsh-umbrella-startup`。
2. 安装前是否**完全退出**了桌面端（含托盘）。
3. DevTools Console 是否有 `[dsh-umbrella-startup] 启动界面自举失败` 的警告。
4. 访问 `/dsh-umbrella/splash.js` 是否返回 401（路由已注册）。

若路由 404，说明 Host 半侧没加载；若路由 401 但仍无动画，说明浏览器半侧自举被
`__DSH_UMBRELLA_FAILED__` 短路，重启桌面端即可重试。

---

## 四、与 web 端的差异

| 项 | web profile | 桌面端 |
|---|---|---|
| 注入方式 | `tapIndex` 改写 `index.html` | 可能无 `webServer`，由客户端自举 |
| 标题栏 | 不处理 | Windows 下整层透明 |
| 播放标记 | `sessionStorage` / `localStorage` | 同左 |
| 资源路由 | `/dsh-umbrella/*` | 同左；若宿主无路由层则自举失败并降级（不播动画） |

除标题栏外，两端的动画、音频、设置面板行为一致。