NativeDog1 / dsh-boot-animation

# dsh-boot-animation
给 DSH 加一段**开机动画**：每次打开 DSH 播一次，视频铺满整个窗口。
> English: README.en.md
- **每次启动 DSH 播一次**（0.4.2 起；在这之前是「每个新会话一次」，所以看起来像一次性的）
- **指定会话每次打开都播** —— 在侧边栏页脚点一下图钉即可
- **铺满窗口**、可跳过、放完自动关闭
- **可以换自己的片子**（三种方式，见下）
## 安装
 [code] 
> 仓库里已经提交了构建产物 `lib/`，也没有 `prepare` 生命周期脚本，
> 所以这条命令**不编译任何东西**，不会触发 pnpm 的 `allowBuilds` 构建授权。
> （等包发布到 npm 之后，也可以写成 `dsh plugin --profile web add dsh-boot-animation`。）
### 支持的 DSH 版本
| DSH 版本线 | 状态 |
|---|---|
| `0.1.5-rc.x` / `0.1.7-rc.x` | ✅ 支持（桌面版旧内核，以及 `npm i -g @deepseek-ai/dsh` 那条线） |
| `0.2.0-rc.x` | ✅ 支持（桌面版新内核，以及 `@next` 那条线） |
**本插件刻意不声明任何 `@deepseek-ai/dsh-*` 的 `peerDependencies`。** host 半边只用
`ctx.webServer`，客户端半边只通过**动态注入**取 `slots` / `uiSession`，两处都不静态
依赖某个宿主包。这样做的直接好处是：它**永远不会被 dsh 的版本兼容闸门跳过** ——
0.2.0 起那道闸门会把 `peerDependencies` 对不上的插件**整包跳过**，现象是"装上了、
但重启后什么也没发生"，而且不报错（市场自己的兼容守卫也会拦）。其它插件要靠
`^0.1.5-rc.3 || ^0.2.0-rc.1` 这种 `||` 列表来适配，本插件不需要，也不会因为漏写
某条版本线而被跳过。
代价是宿主形状变了得自己容忍，这部分由测试守着：`verify-blank`（13 种宿主形状）、
`verify-session-id`、`verify-client-boot`（11 项 boot 安全）。例如"这是不是全新对话"
在 0.2.0 从 binding 上的 `blankBit` 挪到了 `session.getSnapshot().blank` —— 两种都读，
并且**订阅那个 face 本身**而不是采样一次。
装完**必须重启一次 DSH 服务**才生效（bundle 层是在启动时装配的）：
 [code] 
### 装完看不到效果？先做这件事
DSH 的客户端 bundle 响应带 `cache-control: max-age=31536000, immutable`，
而 URL 上的 `rev` 是**进程 nonce**、不会随内容变化。所以浏览器会一直用**第一次抓到的副本**。
装好或升级后请在新窗口里按 **Ctrl+Shift+R（硬刷新）**。普通 F5 不够。
## 用法
### 「什么时候播」是一个开关（0.4.2 新增）
片库面板（页脚 **🎛**）里有一行明确写着：
 [code] 
| 开关 | 行为 |
|---|---|
| **开**（默认） | **每次启动 DSH 应用时播一次** —— 在启动后你进入的那个对话里播。同一轮使用中切会话、新建会话都不重复；下次打开 DSH 再播一次 |
| **关** | 回到原来的行为：只在**新建会话**时播一次（一个会话记一次，之后不再播） |
- 记录写在 `sessionStorage`（`dsh-boot-animation:boot`），浏览器把它限定在一个标签页里、
 关掉标签页就清掉，所以开关打开时的「一次」= **一次应用启动**，而不是「一个会话」
- **被钉住的会话两种模式下都一样**：钉住的会话仍然每次进入都重播，这个开关管不到它
- **开关本身存在宿主那边**（`$DSH_HOME/boot-animation/selection.json` 的 `playOnAppStart`），
 不存 localStorage —— localStorage 按来源（`host:port`）隔离，DSH 换个端口设置就丢了
- 界面上的开关状态是**读回宿主设置**显示的；宿主还没答复之前插件不做任何播放决定
> 0.4.1 及之前没有这个开关，固定是「每个会话只播一次」—— 于是同一个会话里片头只播一次、
> 之后**永远**不再出现。这就是「开了一次之后就再也没有见过」「是个一次性的」的成因。
> 0.4.2 把规则交给你选，默认值是新的「每次启动播一次」，所以**默认行为变了**：
> 如果你要的是老行为，把开关关掉即可。
>
> 直接按 F5 刷新页面**会**再播一次（开关打开时）：sessionStorage 在同一个标签页里能扛过刷新。
> 如果你连着刷新好几次都看得到，那不是 bug。
### 让某个会话每次打开都播（推荐）
1. 打开那个会话
2. 点侧边栏最下面的 **🎞** 图标（就在「设置」旁边）
3. 图标变绿 **🎬** = 已钉住
之后**每次**进入这个会话都会播一遍 —— 切走再切回来、刷新页面，都会重播。
无论上面那个开关是开还是关，都一样。
再点一下图标取消。
> 注意：如果刚启动时你的活动主面板不是「对话」（比如停在某个插件的面板上），
> 当前会话还不存在，图钉是禁用状态。先打开一个对话即可。
### 只给某一个会话换片头（0.4.0 新增）
上面那个 🎞 图钉管的是「**什么时候播**」；如果你要管「**这个会话播哪一段**」，
用片库里的 **「仅本会话」**：
1. 打开那个会话
2. 点页脚 **🎛** 打开片头片库
3. 在你想播的那一行点 **「仅本会话」**
那一行会变成蓝底并挂上「本会话」徽章，面板顶部也会写明「本会话固定播放：xxx」，
旁边有 **「取消（回到全局）」**。之后**只有这个会话**播这一段 ——
其它会话、以及你在别处选的那一段，都不受影响。
「选它」改的是**全局**，「仅本会话」改的是**这一个会话**，两者互不覆盖。
优先级：**会话覆盖 → 随机 → 全局选择 → 环境变量 → `intro.mp4` → `videos/` → 内嵌内置片**。
会话覆盖连「随机播放」也压得住 —— 把一个会话钉住之后又被随手塞一段随机片，
那不是"钉住"的意思；但显式请求随机的调用（`mode=random`）仍然不被覆盖。
> 指的那一段被删掉或移走时，这个会话**回落到全局**而不是黑屏，并在 diagnostics 里
> 记一条 `conversation-override-stale`；文件回来了这条钉住自动生效
> （不会因为一次失联就被清掉）。
## 换自己的视频（片库）
插件现在是