dsh-boot-animation

给 DSH 换掉原生启动页，并给闲置的界面加一层屏保。两个功能各自独立开关，不改 DSH 本体源码，升级 DSH 不受影响。

功能	一句话
启动动画	打开页面时用一段全屏短片盖住 DSH 的启动页，片尾交叉溶解进界面。
屏保	闲置一段时间后用全屏层盖住界面，点一下或按任意键收回，退出时播特效。

特性

• 素材按扩展名支持四类：视频（.mp4 .m4v .webm .mov）、静态图（.png .jpg .jpeg .avif）、动图（.gif .webp）、Live2D 模型（含 .model3.json 的文件夹）。.svg 与 .mkv 一律忽略。
• 片头池多片随机，先把池子里每条轮一遍再重来，不会连着重复同一条；底部进度条跟内核真实的启动进度走。
• 启动路径上每个走不下去的地方都有上界：素材清单 10 秒不应答就当作没有素材、某段片子 6 秒出不来画面就换下一段、时长未知走 20 秒兜底、内核 15 秒不就绪就提示「启动较慢，点击继续」；Esc / 空格 / 回车随时直接进。
• 设置全在「设置 → 插件」的「启动动画」卡片里，不用重启 DSH：屏保那几项立刻生效，启动动画那几项下次启动生效。
• 屏保两个触发条件任一满足即出现：整机闲置（Windows 读系统闲置计数）与窗口失去焦点。
• 屏保收回必须点一下或按一个键；鼠标移动不算「回来」，也不会重置窗口失焦的计时（只有 Windows 的整机闲置计数会因为它归零）。
• 屏保退出三种特效：粒子消散 / 重力下坠 / Glitch 宽带位移，默认每次随机挑一个；关掉是普通淡出。特效是透明的，碎开时露出的是你的界面。
• 屏保可轮换（15 秒 / 30 秒 / 1 分钟 / 5 分钟，默认不轮换）：到点就换下一条，带交叉溶解，且不会连着放同一条。
• 不改 DSH 源码：只往 <head> 注入脚本，再提供一张设置卡片。
• 指针互动特效（水波涟漪 / 星屑吸附）的实现仍在代码里，但卡片上已不提供入口——这个效果在桌面版上一直没能稳定工作，所以入口被撤了。设置字段与实现都保留，现有配置不会丢。细节见 MANUAL.md。

环境要求

条件	要求
DSH	0.2.0-rc.2。这一版换了插件提供设置的接法（声明 Config，不再注册命名空间），更旧的 DSH 要用旧版插件
Node.js	^22.19.0 或 >=24
浏览器	Chromium 内核（Chrome / Edge）。Firefox 没测过

装法

三条路，选一条。细节与撤销办法见 INSTALL.md。

路 A：官方命令

dsh plugin --profile web add <解压出来的目录>

这条路会让 pnpm 把依赖也装好，装完重启一次 DSH。桌面版（DSH Desktop）的 profile 叫 desktop，而这条命令不允许直接改它，桌面版请走路 B 或路 C。

路 B：Windows 脚本（免重启）

powershell -ExecutionPolicy Bypass -File tools\install.ps1

路 C：macOS / Linux 脚本

sh tools/install.sh --profile desktop   # 桌面版
sh tools/install.sh                     # dsh web 用的那个（默认 web）

路 B / 路 C 是同一件事：找 DSH 的位置（先看 DSH_HOME，再找 ~/.dsh）、在 profile 的 node_modules 里建目录链接、往 cordis.patch.yml 追加一行、并把设置卡片需要的 @deepseek-ai/schemastery（DSH 自带那份，要 3.18.4 及以上）链上。不碰 package.json，不跑 pnpm。 找不到 profile 会明确报错并列出有哪些 profile，装之前自动备份 cordis.patch.yml；大多数 profile 会热加载，不热加载的脚本会提醒你手动重启。撤销用 tools/uninstall.ps1 / tools/uninstall.sh，参数同上。

装完刷新浏览器：看到深海底背景 + 一条短片铺满窗口就是装好了。左侧菜单里没有「启动动画」这一项，几乎只有一个原因——插件旁边链接的 schemastery 太旧（缺 .volatile()），卡片会静默消失，控制台留一条 boot-animation: 开头的告警。

启动动画

打开页面时依次是：深海底背景 + 一条从片头池随机取来的素材铺满窗口 → 底部一条细进度条跟内核的启动进度走 → 片尾开始溶解进界面 → 覆盖层整个移除。

短片以静音开始（Chromium 不允许没有用户手势的带声音自动播放）。点一下画面才开声音，这一下故意不进入——手势解锁需要时间起效，绑成一次点击就是「刚出声就进界面」。进入交给片尾；想早点进，点一下或按 Esc / 空格 / 回车。

进入方式三选一：

方式	什么时候进	片子循环
片尾交叉溶解（默认）	从片尾前「淡入时长」开始溶解，放完那一刻正好进	否
放完再淡	片子完整放完、停住，再淡出	否
点击才进	一直循环播放，直到你点一下	是

三种方式（「点击才进」除外）都还要等内核就绪——淡入就是界面显形的过程，内核没好就溶解出一个还没搭好的界面。片头放完但内核还没跟上时，画面停在最后一帧等它。

退场时片子的声音会和画面一起淡出，不会出现「画面没了声音还在响」或「声音被硬切掉」。地址后面加 ?dshbootdiag=1 可以让底部提示行变成实时读数（当前素材类型、是否循环、进度与音频状态），用来判断卡在哪一步。

屏保

默认关，因为它会抢屏幕——默认开着的话，你正在读文档、三分钟没动鼠标，画面会突然被盖住。要用就在设置里自己打开。

多久算离开：默认 3 分钟，可选 1 / 3 / 5 / 10 分钟或自定义 1–60 分钟。

怎么算「离开」：两个条件任一满足就触发——① 整台电脑一段时间没有任何输入（不管 DSH 是不是当前窗口）；② DSH 窗口失去焦点。两者互补：① 抓「你人走开了」，② 抓「你切去别的程序了」。

怎么收回：点一下，或者按任意键。鼠标移动不会把它弄掉（碰一下不该就把画面清了）。底部那行「点击或按任意键继续」就是提示这件事，可以在设置里关掉。移动本身也不重置「窗口失去焦点」那一半的计时，只有整机闲置计数会因为它归零——所以「读长网页时晃一下鼠标屏保就不出现」这个效果，在 Windows 上成立。

退出特效：收回时画面碎开飘散，四选一——随机（默认，每次退出重新挑）/ 粒子消散（往右飘）/ 重力下坠（往下掉）/ Glitch 宽带位移。关掉就是普通淡出。特效是透明的，碎块飞走时露出来的是你的对话界面，不是黑底。系统开了「减少动态效果」会自动退化成普通淡出。

轮换：屏保挂着的时候可以每隔一段时间换一条，可选 15 秒 / 30 秒 / 1 分钟 / 5 分钟，默认「不轮换」。换的时候是把画面换掉，不是收回屏保——收回还是要点一下；换的时候不播退出特效，带交叉溶解，并且先把池子里每条都放一遍再开始第二轮，绝不会连着放同一条。

声音：默认静音（这一层盖住屏幕时没人在看，突然出声会吓人）。设置里一个滑块管两件事：拖到最左＝静音，往右就有声音。只对视频有效，图片 / 动图 / Live2D 模型本来就没有音频路径。

不会盖住开机动画：启动动画还在演的时候屏保不会出来。窗口最小化时也不会出来（没人在看）。

一个做不到的事先说清楚：窗口被别的窗口盖住时屏保照样会出来。浏览器只能可靠知道「窗口是不是最小化了」，拿不到「被压在下面」这个状态——那是操作系统层面的事实。这不是坏了，是能力边界。

设置在哪里

设置 → 插件 → 「插件配置」，找到「启动动画」这一行，点一下展开。默认是收起的，和其他插件一样。

控件	默认	作用
开启启动动画	开	启动动画的开关。关掉＝不注入启动动画那一行，回到 DSH 原生启动页（屏保是另一个开关，不受影响）
播放影片声音	开	关掉是彻底静音：不尝试开声音，声音按钮也不生成
点鼠标直接进入	关	打开后按一下画面就直接进，不再用第一下解锁音频
显示底部提示文字	开	关掉只隐藏底部那行操作提示，标题和进度条保留
淡入时长	2 秒	1 / 1.5 / 2 / 3 / 4 秒
进入方式	片尾交叉溶解	片尾交叉溶解 / 放完再淡 / 点击才进
片头素材池	全选	勾选哪些参与随机轮播；每行带时长与状态徽章，可「预览」
启用屏保	关	屏保是抢屏幕的行为，必须自己打开
屏保时长	3 分钟	闲置多久算「离开」：1 / 3 / 5 / 10 分钟，或自定义 1–60 分钟
退出时播放特效	开	关掉＝收回时只做普通淡出
退出特效	随机	随机 / 粒子消散 / 重力下坠 / Glitch 宽带位移
随机切换	不轮换	屏保挂着时多久换一条：15 秒 / 30 秒 / 1 分钟 / 5 分钟
屏保声音	静音	一个滑块管两件事：拖到最左＝静音，往右就有声音。只对视频有效
屏保素材	全选	勾选 assets/screensaver/ 里哪些参与轮播，每行带类型徽章和「预览」
显示「点击或按任意键继续」提示	开	屏保底部那行说明

生效方式分两种：屏保那几项立刻生效（每次出现前都会重新读一遍设置）；启动动画那几项下次启动就用新的，想现在看效果就点卡片上的「刷新」，页面会重新播一遍。

换自己的素材

两个池子，两个文件夹，不要混着放：片头是演一遍就交接，屏保是盖住等你回来。

池子	文件夹	放什么
片头池	assets/videos/	视频（另外三类技术上也能放，但片头只演一遍，用视频才有意义）
屏保池	assets/screensaver/	视频 / 图片 / 动图 / Live2D 模型文件夹

• 卡片里两个小节各有一个按钮（打开片头文件夹 / 打开屏保文件夹），直接在系统文件管理器里打开对应目录，目录不存在会自动建一个。网页自己没有打开本地文件夹的权限，所以这一步是让 Host 侧替你做的。
• 视频推荐 mp4（H.264 + AAC），兼容性最好。看片头池那一行：带黄色 未优化 徽章的是索引表（moov）在文件末尾，浏览器要整段下完才出画面——点右边的「优化」，它在插件进程里把索引表无损挪到最前（只搬位置、不重编码），原片自动备份到 assets/videos/originals/（这个子目录不参与轮播）。图片和动图不需要这一步。
• 其它两个徽章：一直没有画面 是能开始播但 8 秒内一帧都没出来，放启动动画只会看到背景色；浏览器播不了 是浏览器拒绝解码。遇到就换一段，或重新导出成 H.264 mp4。
• 刷新页面就生效，新素材是每次请求实时扫描出来的，不用重启、不用重新构建。
• 屏保池的行没有「未优化」徽章也没有「优化」按钮——重排是 mp4 的事，而屏保池里还可能有图片、动图、模型。

已知限制

• 屏保的「整机闲置」那一半只有 Windows（读 GetLastInputInfo）。其他平台只剩「窗口失去焦点」这一半，屏保仍能用，但触发会迟钝一些。
• 进入前的等待等于片长。播完才进，抽到 15 秒那段就要看满 15 秒——随时点一下或按 Esc 提前进。
• 屏保里的 Live2D 模型需要自己装适配器：把一个函数挂到 globalThis.__DSH_BOOT_ANIM_LIVE2D__ 上，接口约定写在 src/renderers.js 顶部。插件不含 Live2D 运行时（那是专有库）。没有适配器时这一条会被跳过，卡片上标「无适配器」。
• 卡片的文案是硬编码中文，没走 DSH 的 locale 字典。
• 启动动画依赖 DSH 启动页的 [data-dsh-boot] 结构（读进度弧、识别启动失败都靠它）。DSH 大改版可能失效，失效只是退回原生启动页，不会崩。
• 屏保的触发条件与收回语义没有离线测试覆盖——要真实窗口的闲置、失焦与点击才能验，只能在装机后自己试。

文档导航

文档	给谁	内容
MANUAL.md	用它的人	设置逐项含义、徽章含义、换素材、出问题怎么办
INSTALL.md	装机的人	三条安装路、装完检查、卸掉
AGENTS.md	维护者	架构、两条依赖的 DSH 事实、每条踩出来的规则、改动后要不要重启、怎么自检

tools/ 里有五个离线自检套件（verify-pools / verify-encoding / verify-icon-route / verify-client-card / verify-exit-effects），都不需要 DSH 在跑：

node tools/verify-pools.mjs        # Host 半侧：两个池的清单、字节路由、整张路由表
node tools/verify-encoding.mjs     # UTF-8 无 BOM、中文没坏、注入的脚本里没有 </script
node tools/verify-icon-route.mjs   # 卡片图标路由与它的白名单
node tools/verify-client-card.mjs  # 设置卡片，对着桩 DOM
node tools/verify-exit-effects.mjs # 屏保的退出特效、选择器，以及九个字段真的从实时配置读

另有四个装机脚本（install.ps1 / uninstall.ps1 / install.sh / uninstall.sh）。更早的开发工具（命令行版重排、媒体诊断、浏览器自检、更宽的 verify/ 套件）不随包发出，需要时看 AGENTS.md。

许可

代码是 MIT，见 LICENSE：改、用、再分发、商用都可以，保留版权声明即可。

素材不是。 assets/videos/ 和 assets/screensaver/ 里的视频是作者自己的原创动画，作者保留全部权利，不在 MIT 范围内。随插件原样使用（非商用）没问题；不得转售、不得商用、不得抽出来单独分发。要商用请先取得作者书面许可，或者把这些片子删掉换成你自己的。

assets/icon/ 里的三个图标属于代码，跟着 MIT 走。