# DSH 开场插件开发复盘

## 加载器契约比语法通过更重要

最初客户端 ESM 能通过 node --check 和假 DOM 测试，却不符合 DSH 浏览器端实际加载方式，出现 import failed 并导致启动失败。应先用最小插件验证宿主与客户端两个入口，再做动画。保留 ESM 源码，通过确定性构建生成 __ModuleLoader__.load 的经典脚本入口；构建检查必须确认包名与 factory 导出一致。

## 可选素材不能拖垮整个舞台

原 Q 版依赖原皮肤的已启用路由。用户停用原皮肤后，Q 版 404，旧的全部成功才展示策略会连主立绘一起隐藏。修复为插件自己的限定同源路由读取本机原素材，核对准确哈希；Q 版失败只隐藏 Q 版。主立绘和背景独立随包提供。真实浏览器故障检查要拦截网络或隔离上下文，避免 immutable 缓存让 404 测试变成假成功。

0.3.1 进一步修复新用户没有安装原皮肤时缺少 Q 版的问题：把原 Q 版 WebP、上游许可全文和署名原文随包携带，去掉原皮肤可选依赖。发布检查直接从解包后的本包请求 Q 版，确认 200、字节数与哈希，不再以本机恰好安装原皮肤作为前提。

## 截图必须证明当时看见了什么

早期截图拍到说明文档，不能作为开场视觉验收。虚拟时钟、预加载、透明入场和 Shadow DOM 叠加时，应记录舞台挂载、阶段、opacity、图片 naturalWidth，再截取真实舞台。不能只看到 opacity:0 就断言产品故障，也不能只凭一个字显示就宣称全部人物正常。占位图只证明布局思路，真实 PNG 才能检查透明边缘、衣色和构图。

## 节奏要连同系统设置验收

御姐风格需要舒缓的入场、充分的停留和连续渐出。完整动画调整为 9.6 秒，同时尊重本机 prefers-reduced-motion，提供 2.6 秒静态开场。看到静态或更短开场时，先核对系统设置，不擅自替用户关闭无障碍选项。

## 清理路径是开场插件的核心功能

自然结束、点击、Esc、构建异常、素材失败、重复挂载以及竞争开场都必须清理遮罩、首帧标记、定时器和 document 监听。测试要断言正常工作界面能够露出，而不是只统计函数被调用次数。

## 验证分层，并检验探针自身

语法与包契约、假 DOM 生命周期、真实浏览器素材与画面、实际 DSH 安装重启分别提供不同证据。曾出现假 DOM querySelector、素材对象形状与状态字白名单不准确的探针误判；应修正探针后复现，再判断产品。断言数量不能替代实际加载器与视觉检查。

## 安装必须保留用户原来的 profile 结构

安装前备份插件、依赖声明、锁文件和配置。官方 CLI 安装本次重写了 cordis.yml，原配置实际是空根加 bundles 与 patch；我们保留生成文件作为记录，并恢复原根配置，再确认其他依赖声明、启用列表及 patch 没变化。装好的 20 个文件与 tgz 解包逐字节一致，主立绘、宫殿和原 Q 版经实际已安装 handler 返回 200 且哈希正确。没有重启就不能把这些检查写成 DSH 开机实机通过。

## 发布一个明确、可复现的成品

正式包携带运行代码、两张生成 PNG、原 Q 版 WebP、必要文档和检查脚本。第三方 Q 版必须同时携带原许可和署名，保留原字节。截图留在仓库，缓存、私有路径和调试探针不入安装包。冻结源文件后构建、验证、打包、解包复验并计算哈希；以最后一次产物为准。README 的版本、下载地址、文件大小和哈希应与实际下载一致。分工需要明确文件所有权，避免反复加任务与交叉改文件消耗大量上下文。

## 当前结论

0.2.4 已安装，素材读取与文件一致性检查通过，用户尚未完成新版完整重启验收。0.3.0 将包名精简为 dsh-boot，继续沿用经过浏览器预览的配色、人物和标题。原 v0.1.0 已公开发布；后续版本发布状态以 GitHub 实际仓库和下载文件为准。

0.3.1 将 Q 版图片随包携带，原皮肤不再是依赖；窗口尺寸的显示规则、动画节奏及缺图降级保持原行为。此次未操作用户的 DSH profile，实际升级重启仍需在用户环境验证。