dsh-whale-intro 🐋

给 DSH 的一个开场：加载页面时鲸鱼娘先在海里出现，挥手 → 眨眼，然后随着界面淡入沉回背景里。

和「播一段视频再淡出」的区别在于时机：

	普通的启动视频插件	本插件
什么时候出现	界面已经渲染出来之后，再盖一层上去	在界面的启动页出现之前就占住屏幕
怎么接进界面	视频放完 → 淡出 → 露出界面（中间必然有一次"切"）	她一边沉下去，界面一边浮上来，是同一个动作

原理：客户端插件的浮层永远晚一步——DSH 的启动页是内核在 shell 脚本里同步建出来的。 只有往 <head> 里插一行解析阻塞脚本才能抢在它前面，这也是本插件把动画放在 Host 半侧、通过 webserver/index-inject 注入的原因。

行为

• 她出现时是淡淡的浮入（透明度 + 轻微上浮），不是"啪"地弹出来。
• 站着的时候有缓慢的浮动 + 轻微摆动（不是因为素材是动图，是 CSS 让她活着）。
• 2.3 秒时交叉淡入到眨眼那张——两张是同角度的站姿立绘，所以看起来像一个小动作，不像跳帧。
• 点一下、按任意键、滚一下滚轮，立刻跳过（0.42 秒的快速淡出）。
• 界面就绪（内核启动页消失 + #root 有内容）之后才交接；最早 3.4 秒、最晚 6 秒， 两个边界都是硬的：界面再慢也不会被她挡住。
• 开场期间会把内核自己的启动页按住（[data-dsh-boot]{opacity:0}）。它由 shell 脚本 在运行时创建，排在覆盖层后面——不按住的话同层级下它会盖在她上面，就又变成 "先闪一下白底加载卡"了。交接时这条规则会一起撤掉。
• 素材请求失败、脚本抛错、素材 1.5 秒内解不出来、标签页后台被节流—— 任何一条路都是立刻放行，不是卡住。
• 同一标签页内一次启动只演一遍（刷新不重播）。想看：地址后面加 ?whaleintro=1； 想临时关掉：?whaleintro=0。
• 进场层挂在 document.documentElement 上，不进 #root，所以不会干扰 React 挂载。

为什么现在是清楚的

之前那版播的是一段 640×360 的视频，其中她本人只占约 262×308 像素；按窗口高度 58% 显示时相当于放大约 1.5 倍，所以发糊——编码怎么调都救不回来（实测换 hqx、换 libplacebo 的 ewa_lanczossharp 都更差或只是更"干净"）。

现在用的是两张 512×512 带透明通道的立绘，按 58% 显示时约 522px，基本是原生 1:1， 所以发丝、荷叶边、围裙上的小鲸鱼都是清楚的。透明通道还顺手解开了一个限制：她身上不再带 黑色底，所以尺寸上限从 0.62 放宽到 0.95，想放多大放多大（超过 512px 会开始软）。

安装

桌面版（DSH Desktop，profile 名 desktop）

官方桌面版的市场只收 npm 上已发布的精确版本，GitHub 仓库装的插件在市场里点不了； 但桌面版自带 CLI 的 plugin 子命令对 desktop profile 放行，直接用它：

# 把 <你的 DSH 安装目录> 换成实际路径，例如 E:\DSH
$dsh = "<你的 DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd"

# ① 直接从 GitHub 装（需要能访问 github.com）
& $dsh plugin --profile desktop add "https://github.com/xulianglong-akk/dsh-whale-intro"

# ② 或者先下载到本地目录，再按目录装（路径里不要有空格）
& $dsh plugin --profile desktop add "D:\DSH\plugins\dsh-whale-intro"

装完完全重启 DSH（bundle 层是启动时装配的）。

卸载：& $dsh plugin --profile desktop remove dsh-whale-intro， 然后手工删掉残留链接 cmd /c rmdir "<profile>\node_modules\dsh-whale-intro" ——留着它下次启动可能被重新挂载（两层同 id 会产出两条 entry）。

旧版 dsh web（profile 名 web）

dsh plugin --profile web add "https://github.com/xulianglong-akk/dsh-whale-intro"

改代码后要不要重启，看改的是哪半边

改的东西	生效方式
src/intro.js（屏幕脚本）、assets/*	刷新页面即可（每次渲染索引都从磁盘重读）
entry.js（Host 半侧：路由、注入内容）	必须完全重启 DSH（一个进程只导入一次）
profile 里 cordis.patch.yml 的配置覆盖行	刷新（补丁层热重载）

改了 entry.js 之后、重启之前，开场是不显示状态（不是坏了）。

配置

改 profile 的 cordis.patch.yml，加一条按 id 定位的覆盖行（不用改本包）：

- id: dsh-whale-intro
  name: dsh-whale-intro
  config:
    enabled: true          # false = 完全不注入，回到 DSH 原生启动页
    oncePerLaunch: true    # false = 每次刷新都演一遍
    minMs: 3400            # 最早交接时间（毫秒）
    maxMs: 6000            # 最晚交接时间（毫秒）
    poseMs: 2300           # 第几毫秒交叉淡入到第二张（眨眼）
    sizeVh: 0.58           # 她占窗口高度的比例
    maxHeightPx: 620       # 她的高度上限（px），高窗口想让她更大就调这个

不改任何文件就能试参数（地址栏）

这些参数只影响这一次打开，优先级高于配置，适合先试出来再写进配置：

参数	作用	取值范围
?whaleintro=1 / =0	强制演一遍 / 这次不演	—
?whalesize=0.5	她占窗口高度的比例（默认 0.58）	0.2 – 0.95
?whalemax=900	她的高度上限（px，默认 620）	160 – 1600
?whalepose=1500	第几毫秒切到眨眼（默认 2300）	400 – 20000
?whalemin=2000	最早交接时间（毫秒，默认 3400）	0 – 20000
?whalemaxms=4000	最晚交接时间（毫秒，默认 6000）	1000 – 30000

例如"大一点、眨眼早一点"：?whaleintro=1&whalesize=0.7&whalepose=1400。

换素材

assets/pose-1.webp（挥手）和 assets/pose-2.webp（眨眼）就是全部内容。要求：

• 带透明通道的 WebP / PNG（本插件也会发 .gif .avif）；
• 两张同角度、同比例、同位置最好——不然交叉淡入会看起来像跳帧；
• 换完刷新页面即可，不用重启（路由按文件大小 + 修改时间自动换 URL）。

想只用一张：把 entry.js 里的 POSES 数组删到只剩一个文件名即可（那时不会交叉淡入）。

本地预览（不装进 DSH 也能看）

双击 preview.html，就是一遍完整的开场（含跳过与重播按钮）。

结构

entry.js             Host 半侧：素材路由（白名单 + Range）+ <head> 注入
src/intro.js         注入进 <head> 的进场层脚本（每次渲染索引时重新读取）
assets/pose-1.webp   鲸鱼娘·挥手（512×512，透明）
assets/pose-2.webp   鲸鱼娘·眨眼（512×512，透明）
cordis.patch.yml     让 DSH 认识本插件的挂载声明
NOTICE.md            素材来源与许可（务必保留）
preview.html         本地预览

素材来源

立绘来自 Sutera-Diffusus/dsh-whale-musume（MIT）， 只改名未改动。角色与立绘归原作者所有，详见 NOTICE.md。