前言¶

DeepSeek Harness（DSH）桌面端启动时，会先出现一张写着「HARNESS 正在加载插件…」的加载卡。这段画面出现在文档解析、shell 拉起、组合加载插件到主界面就绪之间的空窗里，开发者很难在业务插件里「抢」到更早的一帧。

若你希望这段等待时间有统一的视觉开场，而不是默认加载卡，dsh-boot-compass 做的是接管首帧：用纯 CSS 覆盖层挡住加载卡，播放一段五阶段罗盘序列，再交接给主界面。实现上不依赖视频资源，也没有额外运行时依赖。社区目录 SkillHub 将其归类为「趣味换装」；维护者为 linshufan21，仓库当前约 1 star。

下面介绍它解决什么问题、如何安装，以及使用时需要留意的边界。

这是什么¶

一句话：它不画 DSH 的业务 UI，而是在被服务的文档里尽早占位，接管启动链上的首帧。

插件通过组合层把样式与脚本注入服务 HTML：首帧是 html.dshboot-on::before 的纯 CSS 覆盖层，比客户端插件更早就位；后续启动画面挂在 shadow root 里，不改动 DSH 原有 DOM。播完五阶段后，主界面若已就绪则立刻交接，否则停在「稳定定格」等待，最多 12 秒。

它明确不做：无设置界面、不注册客户端模块、不改主题包、不安装依赖、不读取用户数据。禁用或卸载后，DSH 恢复默认加载体验。

核心功能¶

首帧与交接¶

• 加载卡尚未绘制时，覆盖层已出现在画面上。
• 全片默认时长约 4.5 秒（可通过 localStorage 调整，见下文）。
• 动画仅使用 transform、opacity、filter；系统开启「减弱动效」时降级为交叉淡入，进度指示仍保留。

五阶段罗盘序列¶

README 中的阶段命名为：

核心唤醒 ── 环形展开 ── 轨道汇聚 ── 能量同步 ── 稳定定格

罗盘从绷紧状态开始，亮弧扫刻度、指针解扣并回摆停住，最后一拍静止等待主界面接管（不再用「冲击波推出镜头」式的收尾）。浅色主题下编排相同，底色为 #F6F7FB，也可通过开关强制浅色。

跳过与等待¶

• 点击屏幕，或按 Esc / 空格 / Enter，可将时间轴前推到释放点，约 0.6 秒内完成交接（仍会走完释放相关节拍，不是硬切）。
• 主界面未就绪时，动画停在「稳定定格」；就绪 gate 最长等待 12 秒。

关窗后再开时的重播（Windows）¶

DSH 0.2.0 起，从托盘再次打开窗口时，可重播启动动画。插件不单独依赖 document.hidden（alt-tab 被盖住也会 hidden），在 Windows 上通过宿主 FFI 查询 IsWindowVisible / IsIconic 区分「真隐藏」与「仅被盖住」。

• 默认 replay 为 window：最小化再还原、收进托盘再打开会重播；被其它窗口盖住再切回不会。
• 窗口需离开可见状态超过 replaymin（默认 600 ms）才触发；宿主约每 250 ms 采样。
• macOS / Linux 上重播逻辑不生效，启动动画本身仍可用。

冷启动首帧可能略顿¶

首次冷启动时，头一两个节拍可能不够跟手。README 说明原因在挂载任务（建 shadow root、注入大量 CSS 规则与动画注册）与 DSH 自身启动争用主线程，而非脚本体积本身；关窗再开后页面已在运行，重播与首播一致。可通过缩短 total、点击跳过或 mode = 'off' 缓解。

安装与启用¶

要求 DSH >= 0.2.0-rc.1 且 < 0.3.0（package.json 中 dsh.engines.dsh）；README 列出的已测版本包括 0.2.0-rc.1、0.2.0-rc.2、0.2.1-rc.1、0.2.1-rc.2。Node >= 20。许可证 MIT。

桌面客户端¶

侧栏 → 插件 → 添加插件，填入：

dsh-boot-compass

也可使用：

github:linshufan21/dsh-boot-compass

装完后点 立即启用，并 完全退出客户端再打开。开机动画在进程启动时注入，仅刷新页面看不到效果。

其它 profile（命令行）¶

desktop profile 只能由 Electron 宿主管理，CLI 会拒绝 --profile desktop。其它 profile：

dsh plugin --profile <name> add dsh-boot-compass

该命令会把组合包写入 profile 的 dsh.profile.bundles 并启用，重启对应 profile 后生效。

更新¶

客户端插件页点「更新」即可，无需卸载重装。README 提醒：发布 24 小时内 pnpm「新版本冷静期」可能导致不带版本号的安装静默回到旧版；可等待 24 小时，或在桌面 profile 下进入 $DSH_HOME/profiles/desktop 执行 pnpm add dsh-boot-compass@<version>。更新后同样需要完全退出再开。

典型用法¶

localStorage 开关¶

改完后刷新页面；要看到注入变更，多数情况仍需重启 profile / 完全退出客户端。

localStorage.setItem('dsh-boot-compass:mode', 'off')       // 整个关掉，直接进 DSH
localStorage.setItem('dsh-boot-compass:theme', 'light')    // 强制浅色；默认跟随系统
localStorage.setItem('dsh-boot-compass:total', 2000)       // 全片时长，800–12000 毫秒
localStorage.setItem('dsh-boot-compass:replay', 'window')  // 重播：window（默认）/ any / off
localStorage.setItem('dsh-boot-compass:replaymin', 5000)   // 离开多久算「重新打开」，默认 600

• mode 仅 'off' 有效。
• total 超出 800–12000 会被忽略并回到默认 4500。
• replay = 'any' 时按网页 hidden 规则，被盖住也会重播（非 Windows 上若需要类似行为可用此项）。

控制台调试¶

__dshBoot.replay()   // 立即再播一遍，无需反复关窗
__dshBoot.stats()    // 播放次数、上次未重播原因、宿主应答等

宿主只读路由¶

其它插件或脚本可查询窗口状态：

GET /__boot-compass/window
→ {ok, visible, iconic, epoch, kind, at, hiddenFor}

epoch 在「真的重新打开」时递增，可作为重播判定依据。

本地预览（不改 DSH）¶

仓库内 tools/preview.html 为单文件预览，内容与宿主注入一致；可点击试跳过，加 ?replay=1 可模拟重播判定。

适用场景与注意¶

适合谁： 希望在 DSH 桌面端统一启动观感、愿意用几秒开场替代默认加载卡的用户；接受纯前端动画、无额外依赖的部署方式。

权限与信任： 插件以当前 DSH profile 进程权限运行，声明权限包括 web:index-inject、dom:overlay、browser:local-storage、desktop:titlebar-overlay 等。安装前应在 GitHub 仓库 阅读源码与 cordis.patch.yml，确认与自身安全策略一致。

平台差异： 启动动画在 Windows / macOS / Linux 可用；关窗重播判定仅 Windows。认不出启动卡时最多等 2 秒仍会播完并交接，不会一直挂到 12 秒。

生态说明： DSH 奉行「一切皆插件」；SkillHub 为社区目录站点，与 DeepSeek / 幻方无官方从属关系。

卸载： 临时关闭用 mode = 'off'；彻底移除可在桌面插件页卸载，或执行 dsh plugin --profile <name> remove dsh-boot-compass。

结尾¶

dsh-boot-compass 把 DSH 启动空窗里的默认加载卡换成可设计的罗盘开场：首帧用 CSS 抢先、主体在 shadow DOM 内播放五阶段序列，再与主界面对接。安装命令以 dsh-boot-compass 或 github:linshufan21/dsh-boot-compass 为准，启用后记得完全重启客户端。

• 目录页：https://www.skillhub.cn/plugins/linshufan21/dsh-boot-compass
• GitHub：https://github.com/linshufan21/dsh-boot-compass