Skip to content
Back to search

dsh-boot-animation

打开新对话、或打开你钉住的会话时,视频铺满整个窗口播放一段片头开机动画。支持换成自己的视频,每个会话只播一次或每次打开都播

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nativedog1--dsh-boot-animation/badge.svg)](/listings/nativedog1--dsh-boot-animation)

HTML

<a href="/listings/nativedog1--dsh-boot-animation"><img src="/api/listings/nativedog1--dsh-boot-animation/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

dsh plugin --profile web add github:NativeDog1/dsh-boot-animation

> 仓库里已经提交了构建产物 `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 层是在启动时装配的):

# 停掉当前的 dsh web,然后
dsh web

装完看不到效果?先做这件事

DSH 的客户端 bundle 响应带 `cache-control: max-age=31536000, immutable`, 而 URL 上的 `rev` 是**进程 nonce**、不会随内容变化。所以浏览器会一直用**第一次抓到的副本**。

装好或升级后请在新窗口里按 **Ctrl+Shift+R(硬刷新)**。普通 F5 不够。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 508 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # dsh-boot-animation
  2. 给 DSH 加一段**开机动画**:每次打开 DSH 播一次,视频铺满整个窗口。
  3. > English: [README.en.md](README.en.md)
  4. - **每次启动 DSH 播一次**(0.4.2 起;在这之前是「每个新会话一次」,所以看起来像一次性的)
  5. - **指定会话每次打开都播** —— 在侧边栏页脚点一下图钉即可
  6. - **铺满窗口**、可跳过、放完自动关闭
  7. - **可以换自己的片子**(三种方式,见下)
  8. ## 安装
  9. ```sh
  10. dsh plugin --profile web add github:NativeDog1/dsh-boot-animation
  11. ```
  12. > 仓库里已经提交了构建产物 `lib/`,也没有 `prepare` 生命周期脚本,
  13. > 所以这条命令**不编译任何东西**,不会触发 pnpm 的 `allowBuilds` 构建授权。
  14. > (等包发布到 npm 之后,也可以写成 `dsh plugin --profile web add dsh-boot-animation`。)
  15. ### 支持的 DSH 版本
  16. | DSH 版本线 | 状态 |
  17. |---|---|
  18. | `0.1.5-rc.x` / `0.1.7-rc.x` | ✅ 支持(桌面版旧内核,以及 `npm i -g @deepseek-ai/dsh` 那条线) |
  19. | `0.2.0-rc.x` | ✅ 支持(桌面版新内核,以及 `@next` 那条线) |
  20. **本插件刻意不声明任何 `@deepseek-ai/dsh-*` 的 `peerDependencies`。** host 半边只用
  21. `ctx.webServer`,客户端半边只通过**动态注入**取 `slots` / `uiSession`,两处都不静态
  22. 依赖某个宿主包。这样做的直接好处是:它**永远不会被 dsh 的版本兼容闸门跳过** ——
  23. 0.2.0 起那道闸门会把 `peerDependencies` 对不上的插件**整包跳过**,现象是"装上了、
  24. 但重启后什么也没发生",而且不报错(市场自己的兼容守卫也会拦)。其它插件要靠
  25. `^0.1.5-rc.3 || ^0.2.0-rc.1` 这种 `||` 列表来适配,本插件不需要,也不会因为漏写
  26. 某条版本线而被跳过。
  27. 代价是宿主形状变了得自己容忍,这部分由测试守着:`verify-blank`(13 种宿主形状)、
  28. `verify-session-id`、`verify-client-boot`(11 项 boot 安全)。例如"这是不是全新对话"
  29. 在 0.2.0 从 binding 上的 `blankBit` 挪到了 `session.getSnapshot().blank` —— 两种都读,
  30. 并且**订阅那个 face 本身**而不是采样一次。
  31. 装完**必须重启一次 DSH 服务**才生效(bundle 层是在启动时装配的):
  32. ```sh
  33. # 停掉当前的 dsh web,然后
  34. dsh web
  35. ```
  36. ### 装完看不到效果?先做这件事
  37. DSH 的客户端 bundle 响应带 `cache-control: max-age=31536000, immutable`,
  38. 而 URL 上的 `rev` 是**进程 nonce**、不会随内容变化。所以浏览器会一直用**第一次抓到的副本**。
  39. 装好或升级后请在新窗口里按 **Ctrl+Shift+R(硬刷新)**。普通 F5 不够。
  40. ## 用法
  41. ### 「什么时候播」是一个开关(0.4.2 新增)
  42. 片库面板(页脚 **🎛**)里有一行明确写着:
  43. ```
  44. 什么时候播: [ 🚀 每次启动 DSH 时播放一次:开 / 关(只在新建会话时播) ]
  45. ```
  46. | 开关 | 行为 |
  47. |---|---|
  48. | **开**(默认) | **每次启动 DSH 应用时播一次** —— 在启动后你进入的那个对话里播。同一轮使用中切会话、新建会话都不重复;下次打开 DSH 再播一次 |
  49. | **关** | 回到原来的行为:只在**新建会话**时播一次(一个会话记一次,之后不再播) |
  50. - 记录写在 `sessionStorage`(`dsh-boot-animation:boot`),浏览器把它限定在一个标签页里、
  51. 关掉标签页就清掉,所以开关打开时的「一次」= **一次应用启动**,而不是「一个会话」
  52. - **被钉住的会话两种模式下都一样**:钉住的会话仍然每次进入都重播,这个开关管不到它
  53. - **开关本身存在宿主那边**(`$DSH_HOME/boot-animation/selection.json` 的 `playOnAppStart`),
  54. 不存 localStorage —— localStorage 按来源(`host:port`)隔离,DSH 换个端口设置就丢了
  55. - 界面上的开关状态是**读回宿主设置**显示的;宿主还没答复之前插件不做任何播放决定
  56. > 0.4.1 及之前没有这个开关,固定是「每个会话只播一次」—— 于是同一个会话里片头只播一次、
  57. > 之后**永远**不再出现。这就是「开了一次之后就再也没有见过」「是个一次性的」的成因。
  58. > 0.4.2 把规则交给你选,默认值是新的「每次启动播一次」,所以**默认行为变了**:
  59. > 如果你要的是老行为,把开关关掉即可。
  60. >
  61. > 直接按 F5 刷新页面**会**再播一次(开关打开时):sessionStorage 在同一个标签页里能扛过刷新。
  62. > 如果你连着刷新好几次都看得到,那不是 bug。
  63. ### 让某个会话每次打开都播(推荐)
  64. 1. 打开那个会话
  65. 2. 点侧边栏最下面的 **🎞** 图标(就在「设置」旁边)
  66. 3. 图标变绿 **🎬** = 已钉住
  67. 之后**每次**进入这个会话都会播一遍 —— 切走再切回来、刷新页面,都会重播。
  68. 无论上面那个开关是开还是关,都一样。
  69. 再点一下图标取消。
  70. > 注意:如果刚启动时你的活动主面板不是「对话」(比如停在某个插件的面板上),
  71. > 当前会话还不存在,图钉是禁用状态。先打开一个对话即可。
  72. ### 只给某一个会话换片头(0.4.0 新增)
  73. 上面那个 🎞 图钉管的是「**什么时候播**」;如果你要管「**这个会话播哪一段**」,
  74. 用片库里的 **「仅本会话」**:
  75. 1. 打开那个会话
  76. 2. 点页脚 **🎛** 打开片头片库
  77. 3. 在你想播的那一行点 **「仅本会话」**
  78. 那一行会变成蓝底并挂上「本会话」徽章,面板顶部也会写明「本会话固定播放:xxx」,
  79. 旁边有 **「取消(回到全局)」**。之后**只有这个会话**播这一段 ——
  80. 其它会话、以及你在别处选的那一段,都不受影响。
  81. 「选它」改的是**全局**,「仅本会话」改的是**这一个会话**,两者互不覆盖。
  82. 优先级:**会话覆盖 → 随机 → 全局选择 → 环境变量 → `intro.mp4` → `videos/` → 内嵌内置片**。
  83. 会话覆盖连「随机播放」也压得住 —— 把一个会话钉住之后又被随手塞一段随机片,
  84. 那不是"钉住"的意思;但显式请求随机的调用(`mode=random`)仍然不被覆盖。
  85. > 指的那一段被删掉或移走时,这个会话**回落到全局**而不是黑屏,并在 diagnostics 里
  86. > 记一条 `conversation-override-stale`;文件回来了这条钉住自动生效
  87. > (不会因为一次失联就被清掉)。
  88. ## 片头是怎么进出画面的(0.4.4)
  89. 进来是「显影」,出去是「虚化淡出」,都不是硬切:
  90. | 阶段 | 视觉 | 时长 |
  91. |---|---|---|
  92. | 进入 | 视频从 `opacity 0 / blur(14px) / scale(1.04)` 显影到清晰 | 340ms |
  93. | 退场 | 视频 `opacity → 0` + `blur(16px)` + 轻微放大;同时整层底色变透明,**backdrop 模糊从 18px 衰减到 0** | 460ms(浮层 500ms 后才卸载) |
  94. 退场的模糊在视频**背后**,所以应用是「先糊后清」地浮出来,而不是从硬边后弹出。
  95. 退场期间底层立刻可点(`pointer-events:none`),不需要等动画放完。
  96. 系统开了「减少动态效果」(`prefers-reduced-motion`)时,这两段动画直接关掉。
  97. 两个时长(`460ms` 与 `HANDOFF_MS = 500`)写在不同文件里,**必须**保持前者更短 ——
  98. 动画被半路切断比没有动画更难看,`npm run verify:handoff` 专门断言这一条。
  99. ## 换自己的视频(片库)
  100. 插件现在是一个**片库**,不是单个槽位:它会把所有能找到的视频都列出来,你选一个,选择会被记住。
  101. ### 插件自带四段片头(内嵌在代码里)
  102. 装完不用加任何东西,片库里就已经有四段可选:
  103. | 片库里的名字 | 来源 | 大小 |
  104. |---|---|---|
  105. | `DeepSeek 品牌片头` | 内嵌 `lib/clips.data.js` | 1.2 MB |
  106. | `DeepSeek 赛博朋克片头` | 内嵌 `lib/clips.data.js` | 1.8 MB |
  107. | `DeepSeek 数字角色苏醒` | 内嵌 `lib/clips.data.js` | 2.5 MB |
  108. | `DeepSeek 启动问题` | 内嵌 `lib/clips.data.js` | 3.2 MB |
  109. **这些片段没有落盘的 mp4 文件** —— 它们以 base64 存在 `lib/clips.data.js` 里,host 在
  110. 第一次被请求时才 import(约 11.5 MB 的模块,如果在启动时解析,每次开 DSH 都要白付这个代价)。
  111. 这样做的意义是:不会再有 `files` 字段漏写、安装副本过期、或者随包发出一个没做 faststart
  112. 的容器这些事。`media/*.mp4` 只是 `npm run embed-clips` 的输入,**不随包发布**。
  113. 四段都是 **faststart** 过的(`moov` 在文件头),可以边下边播;生成脚本会拒绝任何
  114. `moov` 不在前面的输入。这很重要:索引表在文件末尾的 mp4 要整段下载完才出画面,
  115. 叠加客户端 25 秒看门狗,表现就是「片头全黑」。
  116. 体积:npm 包 **9.1 MB**(tarball)/ 解包 **12.2 MB**。四段都做过 CRF 20 重编码 + faststart
  117. 重排,相比各自的原片省下 36%–71%(合计 20.4 MB → 8.7 MB),画质指标 SSIM 0.988–0.996、
  118. PSNR 44–48 dB —— 这是「肉眼看不出差别」的区间。原片另存于仓库外 `~/dsh-dev/_clip-masters/`。
  119. 想换成自己的片子:把 mp4 放进 `media/`,改 `scripts/embed-clips.mjs` 里的清单,
  120. 跑 `npm run embed-clips`。(临时试片不用这么麻烦 —— 见下面的「最省事的方式」。)
  121. ### 最省事的方式(推荐)
  122. 1. 把 mp4 丢进 `~/.dsh/boot-animation/videos/`
  123. 2. 在侧边栏页脚点 **🎛**(在 🎞 图钉旁边)打开「片头片库」
  124. 3. 点一下你想播的那一条
  125. 选中的那段会在**下一次**播放片头时登场:下次启动 DSH、以及你钉住的会话。
  126. > Windows 上就是 `C:\Users\<你>\.dsh\boot-animation\videos\`
  127. > 具体路径以片库面板底部显示的那一行为准。
  128. >
  129. > 你不需要为了"干净"删任何东西:**同一个视频存在多份副本时,片库只列一条**
  130. > (按 大小+mtime 判定同一份内容),并标注「合并 N 份重复」。你的文件一直留在
  131. > 原处,只是不重复显示。这解决的是历史上一个真实的困惑:用户自己也放了一份
  132. > `intro.mp4`,于是同一段片子在面板上出现两次、挂两个不同徽章,看起来像
  133. > "插件里没有这一段"。
  134. ### 片库面板
  135. | 元素 | 作用 |
  136. |---|---|
  137. | ✓ 标记 | 当前生效的那一条(全局选择) |
  138. | 来源徽章 | `你自己加的` / `插件自带` / `内置原始` / `环境变量` |
  139. | 文件大小 | 帮你确认换对了没有 |
  140. | **▶ 预览** | **立刻播放这一行**,不改你的任何选择 |
  141. | **选它** | 把它设为**全局**片头(以后开片头都播它) |
  142. | **仅本会话** | **只让当前这个会话**播它,不动全局选择(见上) |
  143. | `本会话` 徽章 | 这一行是这个会话固定播放的那段 |
  144. | 面板顶部的本会话条 | 本会话当前固定播放哪一段,带「取消(回到全局)」 |
  145. | 刷新 | 刚往文件夹里丢完文件,点它重新扫描 |
  146. | `原片源` 徽章 | 历史上那个 `intro.mp4` 落点,仍然优先 |
  147. | ⚠ 未优化 徽章 | 该文件的索引表 `moov` 在末尾,建议重排(见下) |
  148. | `铺满屏幕` / `完整显示` | 播放时怎么贴合窗口,见下 |
  149. ### 换了片子却"没反应"?先点「预览当前」
  150. 片头动画的触发**故意很窄**:
  151. - **启动 DSH**:整轮启动只播**一次**(0.4.2 起;记录在 `sessionStorage`)
  152. - **钉住的会话**:每次打开都播
  153. 所以**在同一个会话里切来切去**,片子**本来就不会重播** —— 这很容易被误认为
  154. "我换了片子但另一个视频不出现"。点片库里的 **▶ 预览当前** 可以立刻播放选中的那段,
  155. 确认换对了没有。
  156. ### 播放时怎么贴合窗口(黑边问题)
  157. 覆盖层铺满整个窗口,但**窗口的长宽比几乎不会是视频的长宽比**——浏览器有标题栏和
  158. 工具栏,可视区通常比 16:9 更宽。这时:
  159. | 模式 | CSS | 效果 |
  160. |---|---|---|
  161. | **铺满屏幕**(默认) | `object-fit: cover` | 填满窗口,**没有黑边**,超出部分被裁掉 |
  162. | 完整显示 | `object-fit: contain` | 整帧都在,长宽比不匹配时**留黑边** |
  163. 在片库面板里切换,**下次播放生效**。选「完整显示」的情况:片子里有贴着边缘的字幕、
  164. logo 或水印,不想被裁掉。
  165. > 如果黑边来自**视频本身烧进去的边框**(导出时带上的),改 CSS 没用,要用
  166. > ffmpeg 裁掉:`ffmpeg -i in.mp4 -vf "crop=W:H:X:Y" -c:a copy out.mp4`。
  167. > 判断方法:`ffmpeg -v info -i in.mp4 -vf cropdetect=24:16:0 -f null -`,
  168. > 若 `crop=` 值全程稳定,就是烧进去的;若随画面变化,那只是深色背景,别裁。
  169. ### 支持的格式
  170. `.mp4` `.m4v` `.webm` `.mov` `.mkv` —— 但**能不能播取决于浏览器解码**。
  171. H.264 + AAC 的 mp4 最稳;HEVC(H.265)、ProRes、部分 mkv 大概率只有声或黑屏。
  172. ### 手动方式(老办法,仍然有效)
  173. host 半侧按这个顺序解析,**每次请求都重新解析**(换片子不用重启):
  174. | 顺序 | 位置 |
  175. |---|---|
  176. | 0 | **当前会话的覆盖**(`selection.json` 的 `conversationOverrides`;只有带 `?session=` 的请求会看这一层) |
  177. | 1 | `~/.dsh/boot-animation/selection.json` 里选中的那个 id(片库面板写的) |
  178. | 2 | 环境变量 `DSH_BOOT_ANIMATION` 指向的文件 |
  179. | 3 | `~/.dsh/boot-animation/intro.mp4`(历史落点,仍优先于片库里的其他文件) |
  180. | 4 | `~/.dsh/boot-animation/videos/` 里最新修改的那个 |
  181. | 5 | **内嵌的四段**(按 `scripts/embed-clips.mjs` 里的顺序,品牌片头优先)—— 永远兜得住,因为它在代码里 |
  182. 所以最保险的手动换法依然是:
  183. ```sh
  184. mkdir -p ~/.dsh/boot-animation
  185. cp 我的片子.mp4 ~/.dsh/boot-animation/intro.mp4
  186. ```
  187. 想确认当前用的是哪一个,直接访问状态端点:
  188. ```sh
  189. curl http://127.0.0.1:3080/dsh-boot-animation/status.json
  190. curl http://127.0.0.1:3080/dsh-boot-animation/videos.json
  191. ```
  192. 看**某个会话**会播哪一段,以及把某个会话钉到某一段(`id: null` 取消):
  193. ```sh
  194. curl "http://127.0.0.1:3080/dsh-boot-animation/resolve.json?mode=active&session=<会话id>"
  195. curl -X POST http://127.0.0.1:3080/dsh-boot-animation/select \
  196. -H 'content-type: application/json' \
  197. -d '{"scope":"conversation","sessionId":"<会话id>","id":"builtin:cyberpunk"}'
  198. ```
  199. 不带 `?session=` 时,每一个回答都和 0.3.0 逐字节一致。
  200. ### 排错:视频是黑的 / 放着放着没了
  201. **多半是容器没做 faststart。** 如果 mp4 的索引表 `moov` 在文件末尾,浏览器必须
  202. **整段下完**才能解码,中间一直黑屏;而客户端有 **25 秒看门狗**(`STALL_TIMEOUT_MS`),
  203. 超时就自己把覆盖层关掉 —— 症状就是「点开什么都没有」。
  204. 用 ffmpeg 重排一下容器(**无损**,不重新编码):
  205. ```sh
  206. ffmpeg -i 原片.mp4 -c copy -movflags +faststart 修好的.mp4
  207. ```
  208. 验证 moov 是否前置:
  209. ```sh
  210. ffprobe -v trace 修好的.mp4 2>&1 | grep -m1 moov # 偏移应该很小
  211. ```
  212. ## 浏览器的两条硬性策略
  213. 自动播放**带声音**、以及 Fullscreen API,**都要求用户手势**,任何网页都绕不过。所以:
  214. 1. 动画以**静音**在铺满窗口的覆盖层里自动开始(视觉上已经是全屏)
  215. 2. **点一下画面**:同时开启声音并进入**真全屏**
  216. 3. 万一连静音自动播放也被拒,会显示「点击播放」而不是黑屏
  217. ## 覆盖范围(说实话)
  218. - 浮层是 `position:fixed;inset:0;z-index:2147483000`,覆盖的是 **DSH 客户端窗口**
  219. —— 也就是你能看到侧边栏、对话框的那一整块区域
  220. - **它盖不住操作系统的屏幕**。Windows 的任务栏、桌面、别的应用窗口都在它上面。
  221. **这不是 Windows 开机画面**,也不会替代系统启动过程 —— 它是 DSH 这个应用自己的片头
  222. - 覆盖层的矩形与视口逐像素相等、四个角与中心都命中在它内部,这一点由
  223. `scripts/verify-letterbox.mjs` 在真实浏览器里量过(见「验证脚本」一节)
  224. - **别的插件如果用更高的 z-index,我们压不过它**。`2147483000` 是我们自己的值,
  225. 不是全局最大值;宿主自己的部分浮层也在同一量级。真遇到有东西盖在片头上,
  226. 那是两个浮层的层级之争,本插件不改别人的值,也不声称"一定在最上层"
  227. - 库面板(片库)的遮罩是 `2147483200`,**刻意比浮层高 200**:
  228. 打开片库时它必须盖在正在播的片头之上
  229. ## 排错
  230. | 现象 | 原因 / 处理 |
  231. |---|---|
  232. | 完全没出现 | 十有八九是缓存:**Ctrl+Shift+R**(普通 F5 不够)。升级/装完还要**重启一次 DSH 服务** |
  233. | 装完当天见过一次,之后再也没见过 | **0.4.1 及之前的 bug**:那时是「每个会话只播一次」。升到 0.4.2 后是「每次启动 DSH 一次」。还不行就看下一行 |
  234. | 一直不播(怀疑"脚本没生效") | 见下面「装上了但没反应 / 脚本像没生效」一节,三条可能逐条排除 |
  235. | 有时整个启动都不出现,重启又好 | **0.4.2 及之前的 bug**:`/videos.json` 只要有一次没读到,`settingsLoaded` 就一直是假,整轮启动都不会播。0.4.3 起会先重试两次,仍未答就在 8 秒后用宿主默认值照常播 |
  236. | 桌面端右上角三个窗口按钮压着片头,「跳过」点不到 | 0.4.3 起「跳过」自动下移到窗口按钮**之下**,并且**随时按 Esc** 都能退出。系统绘制的窗口按钮永远赢过任何 z-index,所以不再靠层级硬顶 |
  237. | 侧边栏的 🎛 点了没反应 / 按钮被挤没 | 0.4.3 起这个按钮不会再被同一条页脚行里的其它插件压扁(`flex:0 0 auto` + 置顶)。若对方渲染了整行宽的卡片,把它的显示位置改到「设置」可彻底避免 |
  238. | 官方客户端里按钮样式怪、图标看不清 | 0.4.3 起不再继承宿主的全局按钮样式,也不再引用宿主根本没有的 `--dsw-alias-text-*` 变量(那会让悬停态在深色侧边栏里变成看不见的深灰) |
  239. | 钉住了也不播 | 确认图钉是绿色;确认打开的就是被钉的那个会话 |
  240. | 黑屏无画面 | 先看 moov 是否前置(见上「排错:视频是黑的」);再访问 `/dsh-boot-animation/status.json` 看片源;最后看浏览器控制台有没有解码错误 |
  241. | 换了片没生效 | 片库里点完要有 ✓ 才生效;确认文件在 `videos/` 里并点了「刷新」 |
  242. | 只有一个会话播的不是你选的 | 那个会话可能有「仅本会话」覆盖:打开片库看顶部那条,点「取消(回到全局)」 |
  243. | 某个会话的固定片头突然没了 | 它指的片段被移走或删除了 —— 该会话已回落到全局;`status.json` 里能看到 `conversation-override-stale` |
  244. | 播到一半自己没了 | 25 秒看门狗(`STALL_TIMEOUT_MS`)超时 —— 通常还是 faststart 或解码太慢 |
  245. | 片头只盖住一块面板,没铺满窗口 | 这**不该发生**:浮层是 `position:fixed`,只有祖先里有 `transform` / `filter` / `perspective` / `contain` / `will-change` 时才会退化成盖一块面板。跑 `npm run verify:letterbox` 量一下;插件自身不设置这些属性 |
  246. | 有东西盖在片头上面 | 另一个浮层的 z-index 更高(我们的是 `2147483000`)。**本插件不保证压过别人的浮层**,也不会为了压过它去改全局层级 |
  247. | 想让片头盖住任务栏 / 整个屏幕 | 做不到,也不该做:覆盖范围是 **DSH 客户端窗口**,不是操作系统屏幕。这不是开机画面 |
  248. | 想看到插件在干什么 | 把 `src/client/index.ts` 顶部的 `DEBUG` 改成 `true` 重新构建,控制台会打印每次决策 |
  249. ### 装上了但没反应 / "插件脚本像是被覆盖了、没生效"
  250. 这一条**多半不是本插件能修的**:下面是三个已知原因,都能自查。请按顺序排除,
  251. **不要**把「看起来像被覆盖」直接当成代码 bug。
  252. **① 浏览器缓存(最常见)。** 宿主给客户端 bundle 的响应头是
  253. `cache-control: max-age=31536000, immutable`,而 URL 上的 `rev` 是**进程 nonce**、
  254. **不随内容变化**。所以浏览器会一直用**第一次抓到的那份**,装新版本也一样。
  255. - 处理:在新窗口里按 **Ctrl+Shift+R**(硬刷新)。普通 F5 不够。
  256. - 再确认:装完/升级后**重启一次 DSH 服务**(`dsh web`)—— bundle 层是启动时装配的。
  257. **② 换了端口(或 `localhost` ↔ `127.0.0.1`)—— 这是浏览器语义,插件绕不开。**
  258. `localStorage` 和 `sessionStorage` 都按**来源(`scheme://host:port`)隔离**。
  259. DSH 换端口 = 换来源 = 之前「钉住的会话」和「已播记录」**一个都读不到**:
  260. ```js
  261. // 在 GUI 的开发者工具里粘一下,看当前来源和记录
  262. location.origin
  263. JSON.stringify({ boot: sessionStorage.getItem('dsh-boot-animation:boot'),
  264. pinned: localStorage.getItem('dsh-boot-animation:pinned') })
  265. ```
  266. `boot` 为 `null` 且**没有**播片头 → 记录其实在另一个来源下。重新钉一次即可。
  267. **③ 宿主没提供插件需要的槽位。** 本插件的两个服务(`slots` / `uiSession`)走
  268. **动态注入**;宿主既不支持动态注入、又没有 `uiSession` 时,插件会**静默闲置**,
  269. 不报错也不挂载。这是刻意的(静态注入一旦被宿主跳过,**整个 GUI 会打不开**,有实测事故),
  270. 但症状确实很像"脚本没生效":
  271. ```js
  272. // 控制台里应该能看到这一行(插件每次加载都会打,与 DEBUG 无关)
  273. // [dsh-boot-animation] idle: host offers no dynamic injection and no uiSession
  274. ```
  275. - 看到这一行 → 是宿主/版本问题,不是本插件。先确认 DSH 版本在该支持线内(见上表)。
  276. - **没看到任何 `[dsh-boot-animation]` 输出** → 脚本根本没被加载,
  277. 这时才该怀疑插件确实没装上/被跳过(例如兼容闸门跳过、或安装副本过期)。
  278. 用 `dsh plugin --profile web list` 确认它在列表里,再 Ctrl+Shift+R。
  279. ## 实现速记(给维护者)
  280. - 挂载点:`shell.overlay`(帧级浮动层,`kind: list`,新增一格不顶替官方 UI)+
  281. `sidebar.footer.action`(页脚那个图钉和 🎛 片库入口)
  282. - **这个插件绝对不能用静态 `inject`** —— 这是踩过的坑,别改回去。
  283. 客户端加载器把**任何不是 `active` 的条目**都当成致命错误:
  284. ```js
  285. if (u !== "active") if (u === "pending") { … }
  286. if (o.length > 0) throw new Error(`web boot: ${o.length} entry did not activate …`)
  287. ```
  288. 静态 `inject` 一旦有宿主给不出的服务,本插件 fiber 就**永远 pending**,
  289. 于是**整个 GUI 打不开**。实测事故原文:
  290. ```
  291. web boot: 1 entry did not activate dsh-boot-animation: pending (waiting for service: uisession)
  292. ```
  293. 所以两个服务都用 cordis 的**动态注入** `ctx.inject(['slots','uiSession'], cb)`
  294. —— 等待发生在**子 fiber**,我们自己的条目照常 `active`。宿主给不出时插件静默闲置,
  295. 这对一个装饰性插件才是正确的失败方式。
  296. `scripts/verify-client-boot.mjs` 专门断言"产物里没有静态 `inject`",并覆盖四种服务情形。
  297. - 当前会话来自 `ctx.uiSession.adapter.current` 这个 React 友好的 store。
  298. **它的快照不是会话记录**,而是解析后的描述符产物
  299. `{ key, hooks, keyedHooks, props }` —— 会话 id 在 `props.sessionId`,会话快照在 `hooks.session`
  300. - **「这是个全新对话」的字段,DSH 0.2.0 起改了位置**:`hooks.session` 现在是
  301. `SessionFace`(`ISession & ObservableSnapshot<SessionSnapshot>`),空白标志在
  302. **`getSnapshot().blank`**;0.2.0 之前它是直接挂在 binding 上的 `blankBit`,而
  303. 0.2.0 把它变成了 `private`。
  304. 这两个字段都读(新优先),并且**订阅那个 face 本身**而不是采样一次 ——
  305. 旧写法的问题不是报错而是**沉默**:读一个不存在的字段得到 `undefined`,
  306. 判断恒为假,于是「新对话自动播放」悄悄失效。同理,触发也不要求
  307. "必须是切换会话的那一次渲染",否则会取决于两个 store 谁先落定。
  308. - 「每次点开都播」实现为**监听进入会话**这个动作,而不是记"播过没有",
  309. 所以被钉的会话不受"已看过"记录限制
  310. - 视频路由支持 **Range**(浏览器对媒体会发 Range;该给 206 却给 200 时有些播放器会拒绝播放)
  311. - 媒体响应是 **`no-cache` + ETag,不是 `no-store`**:`no-store` 让浏览器一个字节都不能留,
  312. 于是**每次开片头都要重下整段**,加载期间就是黑屏。`no-cache` 表示"留着但要先问",
  313. 配合 ETag:没换片子 → 304 直接用本地副本(秒开);换了片子 → ETag 不同 → 重新下发。
  314. 这条的正确性由 `verify-routes.mjs` 断言(含"带旧 ETag 请求新片子必须 200"的反例)
  315. - **hook 只能在组件里调**:`apply()` 是插件加载器调的,不是 React 调的,所以状态
  316. 全部住在 `AppRoot` 组件内。片库入口在图钉那个 slot、对话框在 overlay 那个 slot,
  317. 是两个独立的 React 根,用模块级 `libraryOpeners` 订阅集合桥接
  318. - 片库的路由:`videos.json`(列)、`media/<id>`(按 id 流)、`select`(POST 写选择或钉会话)、
  319. `resolve.json`("现在播谁")、`boot.mp4`(老路由,302 到具体片段,向后兼容)
  320. - **按会话覆盖是主机的一层,不是客户端的一层**:`resolveActive(sessionId)` 把
  321. `conversationOverrides[sessionId]` 排在最前面,客户端只把 session 带上(`?session=`)——
  322. 优先级链因此仍然只有一份实现。`mode=random` 是唯一绕过它的入口,因为那是调用方
  323. **指名**要随机;`mode=active` / `mode=selected` 都认这一层
  324. - `conversationOverrides` 放进 `selection.json`(v3)而不是另开一个文件:它就是用户选择,
  325. 而这个 store 是插件里唯一知道怎么原子写、怎么自愈损坏文件的地方,另开一个文件
  326. 等于把那两件事再抄一遍。键值两侧的校验和 `selectedClipId` 完全一样(路径一律被拒),
  327. 所以手改文件也无法从这张表里塞进媒体路径;表有上限(200),淘汰**最久没被设置**的那个
  328. - `videos.json` / `status.json` **只公布发问那个会话的** `conversationClipId`,
  329. 从不把整张表发给浏览器 —— 一个把用户钉过的每个会话 id 都吐出去的端点,
  330. 比一个只回答被问到的问题的端点差得多
  331. - 内嵌片段的 id 是 `builtin:<name>`,与路径派生的 id 不会撞;它们的 ETag 用自身的
  332. 内容哈希(`"embedded-<sha256前16位>"`),所以重校验是精确的、不依赖 stat
  333. - **同一个视频在多个位置时按内容去重**(sha256;文件侧按 size+mtime 缓存哈希结果),
  334. 内嵌那份优先胜出 —— 它不可能被删掉,所以指向它的选择永远解析得到
  335. - **prefix 路由不能带尾部斜杠**:webserver 用
  336. `pathname !== prefix && !pathname.startsWith(prefix + '/')` 匹配,注册
  337. `.../media/` 会被当成 `.../media//`,永远匹配不上(曾导致 /media/<id> 全 404)
  338. - **「什么时候播」是一条纯函数**:`decidePlay()`(`src/client/session.ts`)吃下
  339. sessionId / 是否刚进入 / 宿主设置是否到达 / `playOnAppStart` / 是否被钉 / 是否新会话 /
  340. 两个记录,吐出 `none | play(pinned | app-start | new-conversation)`。副作用(写记录)
  341. 在 `recordDecision()` 里,UI 只负责收集输入和调 `playMode()`。这样决策矩阵可以在测试里
  342. 穷举(`verify-play-decision.mjs`),而不是靠渲染一个浮层去反推
  343. - **设置到达之前不做决定**:`snapshot.settingsLoaded` 为假时 `decidePlay` 一律返回 `none`。
  344. 默认值猜错任何一边都会让"明确关掉开关的人"又被播一次
  345. - 覆盖层**不依赖祖先的层叠上下文**:它插在 `shell.overlay` 槽位里,而宿主那个
  346. `data-shell-overlay` 层是 `position:absolute;inset:0`,**没有** `transform` / `filter` /
  347. `contain` / `will-change`,所以 `position:fixed` 真的以视口为包含块。
  348. 这条不靠读代码保证:`verify-letterbox.mjs` 会走一遍真实祖先链,
  349. 并且用一个 `transform:translateZ(0)` 包裹的**反例页面**做阴性对照 ——
  350. 探针必须能看出反例没铺满,否则"正面通过"没有意义
  351. ## 验证脚本(改完跑一遍)
  352. | 命令 | 作用 |
  353. |---|---|
  354. | `npm run verify:routes` | 用**服务器自己的匹配规则**驱动真实 handler,断言每条路由 |
  355. | `npm run verify:conversation` | 按会话覆盖的完整行为:只对自己生效、不碰全局选择、压过随机但不压过 `mode=random`、片段失效时回落并记录、只公布发问者的钉住、校验与上限 |
  356. | `npm run verify:boot-scope` | 启动记录的作用域(sessionStorage)、存储抛异常 / 不存在时回退到内存 |
  357. | `npm run verify:play-decision` | 「什么时候播」的决策矩阵:开关开 / 关、钉住会话、宿主设置未到达、同一轮不重复 |
  358. | `npm run verify:app-start-setting` | 开关作为宿主设置的完整往返:默认 true、`/select` 写入与读回、非布尔被拒、v3 旧文件迁移 |
  359. | `npm run verify:letterbox` | 用 CDP 驱动本机 Edge,量出所选贴合方式实际留多少黑边,并**量出覆盖层是否等于视口 + 四角/中心命中测试 + 阴性对照** |
  360. | `npm run verify:boot-animation` / `verify:pin` | 真 GUI 端到端(`npm run verify:gui-boot` / `verify:gui-pin`;需要带 `--remote-debugging-port` 的 DSH GUI,**不是** `npm run check` 的一部分)。`gui-boot` 也会量一遍覆盖层 |
  361. | `npm run verify:settings-fallback` | 宿主读不到设置时的两级兜底:`/videos.json` 重试两次,仍未答才由 8 秒定时器放行决策(用真实 `ClientStore` + 脚本化 `fetch` 驱动) |
  362. | `npm run verify:desktop-chrome` | 四个现场问题的 CSS/UX 不变量:标题栏让位(WCO 几何 + Esc)、页脚按钮不可被压扁、`:where()` 重置不夺走按钮边框、不再引用不存在的宿主 token |
  363. | `npm run verify:handoff` | 进出场的时序不变量:`HANDOFF_MS` 必须**长于** CSS 时长(半路切断比没有动画更难看)、退场同时有淡出与模糊、backdrop 模糊从强到 0、退场期间指针穿透、reduced-motion 有守卫 |
  364. | `npm run check` | 上面全部 **21 组**(build / routes / selection / conversation / cache / blank / boot / boot-scope / play-decision / settings-fallback / app-start-setting / preview / playback / random / fallback / install / teardown / version-refresh / session-id / desktop-chrome / handoff) |
  365. | `npm run build:client` | 先跑 CSS 检查再构建(防带病构建) |
  366. 两个脚本都是被真实 bug 逼出来的,各自都有过一次"用自己的规则测自己"的教训:
  367. 它们的断言刻意复刻被测方的规则,并且在提交前会做**反向验证**(故意改坏 → 必须报错)。
  368. > 客户端构建有一个坑:整个 CSS 是一段模板字符串,注释里写一个反引号就会提前把它
  369. > 结束掉,而报错是 **TypeScript 的 parse error 指向某行 CSS**,同时 `lib/client.js`
  370. > 保持不变 —— 看起来像改成功了其实没生效。`scripts/check-css-template.mjs` 专门
  371. > 拦这个,已接进 `build:client`。
  372. ## 许可
  373. BSD-3-Clause,见 [LICENSE](LICENSE)。包内 `lib/clips.data.js` 里的内嵌片源以相同条款分发。
  374. ## 安装时报 `connection to github.com timed out after 5000ms`
  375. 如果安装插件时看到这样的提示:
  376. ```
  377. 任务 ① 安装 dsh-boot-animation
  378. {"code":"operation-error","diagnostic":"dsh: connection to github.com timed out after 5000ms"}
  379. ```
  380. **这不是插件坏了。** 这一行是 DSH 在**拉取插件**时自己报的:它在 5 秒内没能从 github.com 取到东西。
  381. 插件运行时代码里没有任何访问 github.com 的请求 —— 它的 `fetch` 全部指向自己的本地路由,超时常量是 25 秒的卡顿检测,
  382. 和这里的 `5000ms` 没有关系。
  383. 常见原因与处理:
  384. 1. **网络到 github.com 不通或很慢**(国内尤其常见)。先做的是:**再装一次**;仍然失败就换网络(手机热点试一下)、
  385. 或挂上代理后重试。
  386. 2. **不想走网络**:把仓库克隆到本地,用本地路径安装,例如
  387. `dsh plugin add <你克隆下来的目录>`。走本地路径不需要连 github.com。
  388. 3. **安装包体积**:这个仓库里带着插件自带的四段片头(`lib/clips.data.js` 约 12 MB,是把视频内嵌进代码里的结果)。
  389. 在慢网络上,这个体积本身也会把 5 秒的窗口撑爆。0.4.1 已把仓库里两个无关的大文件删掉(见 CHANGELOG),
  390. 安装时传输的体积因此明显变小。
  391. 如果你确认网络正常、重试多次仍失败,请把上面那段 `diagnostic` 原文贴到 issue 里 —— 里面有 DSH 报的原始原因。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.