装好却没动画?401 还是 404:dsh-startup-screen 常见问题排查清单
装好却没动画?401 还是 404:dsh-startup-screen 常见问题排查清单
dsh-startup-screen 是 DeepSeek Harness 的启动界面与启动动画插件:装进 DSH 的 web profile 或桌面端后,刷新页面即可看到「黑幕 → DeepSeek 标识 → 过曝洗白 → 暖白档案底板 → 五步交互授权 → 揭幕」的完整开机动画。装完之后最常见的两个疑问就是:刷新页面却没动画、以及手查路由时看到的 401 到底算不算装坏了。这篇排查清单按「装好没动画 → 401/404 判读 → 控制台报错 → 卡黑幕」的顺序,帮你用最短时间定位 dsh-startup-screen 插件异常的原因。
一、先搞清楚:401 是「活着」,404 才是「没装上」
这是新手最容易误解的一点。装完插件后,你可以不带 token 直接在浏览器访问:
http://127.0.0.1:<端口>/dsh-startup/splash.js
| 返回码 | 含义 | 结论 |
|---|---|---|
| 401 | 路由已注册,被插件的信任栅栏拦下 | ✅ 安装成功,这是正常现象 |
| 404 | 路由根本不存在 | ❌ 没装成功,或者没有重启 DSH |
401 来自插件给每条自定义路由套上的「信任栅栏」:DSH 的连接层(requestRejection)会先判断请求是否可信,不可信就直接拒绝、不吐任何内容——这是为了防止任意网页读写这些路由。栅栏逻辑见 lib/index.js,对应测试断言见 test/smoke-host.mjs。
💡 所以正确的心智模型是:安装前路由 404,安装并重启后变成 401,两者一变化就说明插件已生效。官方文档 INSTALL.md 和 DESKTOP.md 都以此作为「验证装好了」的标准动作。
二、装好了却没动画:按顺序排除 5 个原因
1. 没有重启(最常见)
DSH 只在启动时加载插件。装完必须:
- web profile:关掉启动器窗口再重新双击;
- 桌面端:先完全退出 DeepSeek Harness Desktop(进程不能留着,desktop profile 的
package.json由进程加锁管理),装完再打开。
快速自检:重启后设置页里应该多出一项 「启动动画」。没有这一项 → 插件没装上或没重启,问题出在安装环节而不是动画本身。
2. 用错安装方式:手工拷目录不会被识别
DSH 靠 dsh.profile.bundles 层堆栈决定加载哪些插件,dsh plugin add 会在安装时把插件自带的 cordis.patch.yml 作为一层并入堆栈。手工把插件目录拷进 node_modules 不会被识别,这正是「装完没反应」的高频原因之一。
正确姿势(详见 INSTALL.md):
dsh plugin --profile web add ./dsh-startup-screen-1.1.2.tgz
Windows 也可以直接双击 安装.cmd,脚本会自动识别 web / desktop 两个 profile 并逐个安装。
3. 手工装过又用 dsh plugin add,导致重复注册
如果你之前手工在 profile 的 cordis.patch.yml 里加过 - id: dsh-startup-screen 这类条目,又走了 dsh plugin add,插件就会被注册两次,ctx.webServer.register() 对同一路径重复注册会直接报错。
处理:删掉手工添加的那两行 patch 条目(安装.cmd 会自动检测并提示),再重启 DSH。
4. 显示模式在「防打扰」:每次会话 / 每天只播一次
动画不是每次刷新都强制播放,默认显示模式是 session(一个浏览器会话只播一次)。这解释了为什么第一次看到动画、之后就「消失」了:
| 模式 | 行为 |
|---|---|
每次会话(默认) |
同一浏览器会话只播一次,关闭重开浏览器后再播 |
总是 |
每次刷新都播(排查问题时可以临时切到这个) |
每天 |
一天只播一次 |
进 DSH 设置页 → 启动动画,把「显示模式」改成 总是,再刷新验证。另外确认总开关「启用」是开的——enabled: false 时首屏兜底脚本会直接跳过动画(见 lib/index.js)。
5. 桌面端走了哪条路?用标记确认
桌面端有两条注入路径:Host 侧 tapIndex 改写 index.html,或浏览器半侧自举。两条路对用户表现一致,差异只在一个窗口标记上。打开开发者工具 Console 读:
window.__DSH_STARTUP_BOOT__ // 'index' = Host 注入;'client' = 浏览器半侧自举
判断与排查逻辑集中在 lib/client.js 的 selfBoot,行为矩阵与实测记录见 DESKTOP.md。
三、控制台出现这几行日志时,分别代表什么
打开开发者工具,对照下面这张表基本可以一锤定音:
| 日志 | 出处 | 含义与处理 |
|---|---|---|
<a href="https://link.gitcode.com/i/135fe65e5fd588f0b1e191691e6c8814" target="_blank">dsh-startup-screen] 启动界面自举失败,已放开页面:… |
[lib/client.js | 浏览器半侧拿不到路由(多半是 Host 半侧没激活),页面已被安全放开,检查插件是否真正装上 |
<a href="https://link.gitcode.com/i/0809982d218784ad4b32806d824ab161" target="_blank">dsh-startup-screen] 当前 profile 没有可用的 webServer… |
[lib/index.js | 走了降级路径(桌面端 file:// + IPC 形态),属 warn 不是错误,接着看浏览器半侧日志 |
<a href="https://link.gitcode.com/i/b705e3fd635bc168097bace0c02a4510" target="_blank">dsh-startup-screen] 动画异常,直接揭幕:… |
[lib/splash.js | 动画运行时抛错,插件选择直接揭幕放行,把控制台里的异常堆栈贴出来即可定位 |
三条路由(splash.css / splash.js / asset/*)与 /dsh-startup/config 配置接口的注册入口都在 lib/index.js,可以按这张表逐项验证返回值:
| 路由 | 正常返回 | 异常返回 |
|---|---|---|
/dsh-startup/splash.js |
200(浏览器内)/ 401(无 token) | 404 → 未装或未重启 |
/dsh-startup/asset/line-1.mp3 |
200 + audio/mpeg |
404 → 素材缺失(会自动回落 TTS,不影响启动) |
/dsh-startup/config |
200 JSON 配置 | 404 → 路由未注册 |
四、卡在纯黑幕不消失?9 秒兜底会救你
插件的设计底线是绝不把用户锁在黑屏里:
- 首屏兜底脚本里埋了一个 9 秒定时器(lib/index.js):如果连
splash.js都没跑起来(404、被拦截、语法错误),9 秒后无条件移除黑幕、解除滚动锁,并打上window.__DSH_STARTUP_FAILED__ = true; - 浏览器半侧自举同样有同款 9 秒自愈(lib/client.js);
- 桌面端 Windows 标题栏透明化也有揭幕 / 跳过 / 失败 / 9 秒兜底多重还原 + 60 秒硬上限,不会把窗口按钮永久藏住。
如果你看到的是「黑幕一闪而过」或「短暂黑幕后正常进入应用」,说明就是兜底放行了,按第二、三节继续查根因即可;如果你超过 9 秒仍黑屏,先刷新一次,再看 Console 是否被扩展拦截了脚本。
五、排查顺序速查表
按这个顺序走,90% 的问题都能在前 3 步内解决:
- 设置页有没有「启动动画」? 没有 → 回到安装环节(
dsh plugin add+ 重启,参考 INSTALL.md); - 手查
/dsh-startup/splash.js:404 → 没装好或没重启;401 → 插件是活的,问题在前端; - 改「显示模式」为
总是再刷新,排除会话/每日频控; - 看 Console 三条日志(见第三节对照表);
- 桌面端读
window.__DSH_STARTUP_BOOT__确认走的是哪条注入路径(参考 DESKTOP.md)。
相关文档
- README.md —— 功能总览与全部设置选项
- INSTALL.md —— 安装 / 手工安装 / 验证 / 卸载
- DESKTOP.md —— 桌面端适配与实机验证记录
- AUDIO-FIELDS.md —— 语音与音效素材槽位清单
- preview/index.html —— 离线预览页(不装 DSH 也能先看一遍动画效果)
- 冒烟测试:test/smoke-host.mjs、test/smoke-splash.mjs、test/smoke-client.mjs、test/smoke-desktop-boot.mjs
⚠️ 卸载命令备查:
dsh plugin --profile web remove dsh-startup-screen(桌面端把web换成desktop)。重复注册、版本混装等问题,卸载后重装一次是最省时间的解法。