装好却没动画?401 还是 404:dsh-startup-screen 常见问题排查清单

原创2026-11-05 12:48:402,150 阅读

装好却没动画?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 步内解决:

  1. 设置页有没有「启动动画」? 没有 → 回到安装环节(dsh plugin add + 重启,参考 INSTALL.md);
  2. 手查 /dsh-startup/splash.js:404 → 没装好或没重启;401 → 插件是活的,问题在前端;
  3. 改「显示模式」为 总是 再刷新,排除会话/每日频控;
  4. 看 Console 三条日志(见第三节对照表);
  5. 桌面端读 window.__DSH_STARTUP_BOOT__ 确认走的是哪条注入路径(参考 DESKTOP.md)。

相关文档

⚠️ 卸载命令备查:dsh plugin --profile web remove dsh-startup-screen(桌面端把 web 换成 desktop)。重复注册、版本混装等问题,卸载后重装一次是最省时间的解法。

登录后查看全文
dsh-startup-screen