dsh-boot-animation-pro

给 DSH 加一段开机动画：打开 DSH、新对话、或你钉住的会话时，视频铺满整个窗口播放。

这是 NativeDog1/dsh-boot-animation 的二次开发版， 增加播放控制、触发规则、片库管理、画面特效、分时段片头和中英双语界面。 出处、许可与差异见 FORK.md。English: README.en.md

如果你用上了，点个 ⭐ Star 让我知道有人在用 —— 这是这个项目唯一想要的回报。

一条命令安装（复制即用）：

dsh plugin --profile web add github:Yiheng-guo/dsh-boot-animation-pro

桌面版 App 把 web 换成 desktop。装完完全退出 DSH 再重开才生效。

装好之后长什么样

铺满屏幕（默认）：填满窗口，超出裁掉，0 黑边	完整显示：整帧都在，长宽比不匹配时留黑边

上面两张是真实浏览器渲染实测截图（Headless Chrome 2560×1313 视口，1280×720 片源， scripts/verify-letterbox.mjs 测量）：铺满模式黑边 0px，完整显示模式左右各 113px。

安装

dsh plugin --profile web add github:Yiheng-guo/dsh-boot-animation-pro

仓库里已提交构建产物 lib/，也没有 prepare 生命周期脚本，所以这条命令不编译任何东西， 不触发 pnpm 的 allowBuilds 构建授权。

装完必须重启一次 DSH（bundle 层在启动时装配）：

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

从源码目录安装（开发用）

git clone https://github.com/Yiheng-guo/dsh-boot-animation-pro.git
cd dsh-boot-animation-pro
npm install && npm run build && npm run check   # 可选：先自检

# 挂进 profile（默认 desktop，可 --profile web）
npm run dsh:link
# 卸载
npm run dsh:unlink

scripts/dsh-link.mjs 写的东西和 dsh plugin add 完全一致：profile 的 node_modules/ 下一个符号链接、 dependencies 一行、dsh.profile.bundles 一项。可逆，且重复执行是幂等的。

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

DSH 的客户端 bundle 响应带 cache-control: max-age=31536000, immutable。装好或升级后请 完全退出 DSH 再重开；如果是浏览器窗口，按 **Ctrl+Shift+R（Mac 上是 Cmd+Shift+R）**硬刷新。

DSH 桌面版没有绑定 Cmd+Shift+R。用 Cmd+Q 退出再打开即可 —— 进程换了之后启动页会重新取， 而 rev 是内容哈希，内容变了 URL 就变了，不会命中旧缓存。

用法

什么时候播（触发规则）

侧边栏左下角点 🎛 → 「触发」标签页，五种模式：

模式	什么时候播
新对话一次 + 钉住的会话每次	默认。新建对话播一次；另外钉住的会话每次进都播
每个新对话一次	只在没说过话的新对话播
每次打开会话都播	切换任何会话都播（最频繁）
每次启动 DSH 只播一次	一次启动最多播一次。「每次打开 DeepSeek 都能看到」选这个
不自动播放	只在你手动点「▶ 预览 / ▶ 播一次」时播

• 冷却时间：距上次播放不足 N 分钟就不自动播（0 = 不限）。它和会话名单是否决条件，对以上每种模式都生效。
• 会话名单：不限制 / 只在这些会话播 / 这些会话不播。当前会话可以一键加入或移出。

钉住某个会话（让它每次都播）

侧边栏点 🎞 → 变绿 🎬 = 已钉住，之后每次进这个会话都播。再点一下取消。

换自己的视频

最省事：把 mp4 丢进 ~/.dsh/boot-animation-pro/videos/，点 🎛 →「刷新」→ 点「选它」。

片库面板里每条都有：

按钮	作用
▶ 预览	立刻播这一段，不改你的选择（试片用，面板不关，可以连着试）
选它	设为以后开片头时播放的片段
☆ / ★	收藏，置顶显示
改名	起个显示名（留空恢复默认）
删除	从磁盘删除该文件（会二次确认）

手动方式（仍然有效，host 按此顺序解析，每次请求都重新解析，换片子不用重启）：

顺序	位置
1	片库里选中的那个
2	环境变量 DSH_BOOT_ANIMATION 指向的文件
3	~/.dsh/boot-animation-pro/intro.mp4
4	~/.dsh/boot-animation-pro/videos/ 里最新修改的
5	内嵌的四段（永远兜得住，因为它在代码里）

上一个版本（dsh-boot-animation）的 ~/.dsh/boot-animation/ 目录会被只读扫描， 所以升级后你原有的片子还在、还能列出来，但本插件不会去删它。

播放控制

🎛 →「播放」：音量、开片静音、倍速、进度条、倒计时自动跳过、片尾淡出、铺满/完整显示、随机播放。

关于声音：浏览器禁止带声音自动播放，所以动画一律静音起播。 点一下画面即可开启声音并进入全屏 —— 这是唯一符合浏览器策略的做法。 想让它一开始就尝试有声，关掉「开片时静音」；被浏览器拒绝时会显示「点击播放」而不是黑屏。

画面美化

🎛 →「画面」：标题、副标题、右下角水印，以及 4 种特效 —— 扫描线、暗角、颗粒、辉光。

分时段片头

🎛 →「时段」：按星期 + 时间段自动换片头。命中的第一条启用规则生效；都没命中就走上面的选择/随机。

跨午夜的时间段（例如 22:00 → 02:00）算在开始的星期上。所以「周五夜」在周六凌晨 1 点依然命中。

界面语言

🎛 →「界面」：跟随浏览器 / 中文 / English。有闸门（verify-i18n.mjs）禁止组件里出现硬编码文案。

排错

现象	原因 / 处理
完全没出现	先确认侧边栏有没有 🎞/🎛。有 → 是触发规则问题（见上）；没有 → 缓存，Cmd+Q 重开
停在已有会话不播	按设计如此。默认只在新对话和钉住的会话播；想要「每次打开都看到」选「每次启动 DSH 只播一次」
有声但听不到	静音起播。点一下画面开启声音
黑屏无画面	多半是 mp4 的索引表 moov 在文件末尾。片库会给这种文件打「⚠ 未优化」徽章；用 ffmpeg -c copy -movflags +faststart 无损重排
播到一半自己没了	25 秒看门狗超时 —— 通常还是 faststart 或解码太慢
想看到插件在干什么	把 src/client/diagnostics.ts 的 DEBUG 改成 true 重新构建，控制台会打印每次决策

开发

npm run check          # 全部闸门：typecheck + 22 个套件，约 570 条断言
npm run build          # 重新构建 lib/
npm run verify:letterbox   # 用真实浏览器量黑边（需要 Chrome/Edge/Chromium）

npm run extract-clips  # 从 lib/clips.data.js 反解回 media/*.mp4（带 sha256 校验）

media/ 不在源码归档里。 它只是生成 lib/clips.data.js 的输入，而后者已经提交了。 归档（也就是 pnpm add github:… 下载的东西）因此从 19MB 降到 9.5MB——在慢网络上这是 「装上了」和「放弃了」的差别。git clone 拿到的是完整仓库，不受影响。 从归档开始工作的人跑一次 npm run extract-clips 就能把文件还原出来，逐字节一致。

改代码前请先读 ARCHITECTURE.md 末尾的不变量清单。 其中三条是硬约束，违反了会直接把 GUI 弄挂或造成数据丢失。

安全

插件注册在 DSH web 服务器上的路由不受 app shell 的 web token 保护。因此所有会改变状态的接口 （/select、/remove）都必须先过 src/host/route-guard.js 的四道闸门：

1. Host 必须是回环地址 —— 挡 DNS rebinding
2. 拒绝 Sec-Fetch-Site: cross-site —— 浏览器自己声明的，网页伪造不了
3. 出现 Origin 时必须是回环源 —— 浏览器对每个 POST 都会带
4. Content-Type 必须是 application/json —— 逼出 CORS 预检

scripts/verify-route-guard.mjs 会把攻击原样重放一遍，断言既要 403、文件又必须还在。 新增任何写接口时请照抄这个模式。

许可

BSD-3-Clause，见 LICENSE（与原版逐字节相同，未修改）。 本仓库是 NativeDog1/dsh-boot-animation 的二次开发， 原始著作权归 NativeDog1 所有，详见 FORK.md。