升级到 rc.3 之后一打开窗口就消失、重开又循环闪退,日志里只报 "两个必需插件没启动",先别急着去翻配置文件把插件手动打开。这类问题的核心结论是:闪退循环的根因通常不在静态配置里,而是 profile 中残留的 rc.2 旧版插件在加载期被版本兼容性检查静默判定为不兼容、运行时直接置为禁用,导致 llm、tools 两个底层服务没有提供者,上层 agent-loop、tool-executor-native 这两个 required 插件一直挂起,启动审计发现必需插件未激活后直接抛出致命错误,壳层进程反复拉起 host 形成重启循环。要解决它,方向不是在 YAML 里强行打开 disabled,而是把 profile 依赖与应用本体对齐到同一 rc.3 版本,清理不该被 pin 住的应用自带运行时包,并用与应用一致的 pnpm 版本重装依赖;整套流程建议先在隔离环境复现和验证,确认通过后再动正式配置,避免崩溃期间反复写入覆盖掉原有设置。
一、先看现象:这不是偶发崩溃,而是启动重启循环
升级到 rc.3 后,桌面端窗口只出现几秒就消失,随后自动重开、再次消失,反复出现。界面本身不弹错误提示,线索集中在日志目录中每隔几分钟成对出现的 host 日志与 web-boot 日志,时间戳连着好几轮,说明壳层进程在反复拉起 host,而 host 每次都在同一处失败退出。
| 观察项 | 典型表现 | 说明 |
|---|---|---|
| 启动表现 | 窗口出现几秒后消失,自动重开再消失 | 属于崩溃循环,不是单次偶发闪退 |
| 日志报错 | DesktopHostFatalError: startup failed: 2 required plugins did not activate | 只给出症状:必需插件未激活 |
| 等待服务段 | 19 个插件在等服务,其中两个标 required | 分别是 agent-loop(等 llm、tools)与 tool-executor-native(等 tools) |
| 缺失服务段 | providers: [] | 不是服务注册失败,而是根本没有插件在提供该服务 |
| 插件状态段 | rc.2 版本行 state 为 disabled,rc.3 行 active | 被禁用的旧版本包是重点排查对象 |
二、先排除配置层:为什么在配置里找不到 disabled
第一反应往往是 "是不是配置把插件禁用了",实际排查下来会发现:配置目录里一条 disabled 记录都没有,组合后的插件树也完好,甚至手动在配置里覆盖 disabled: false 仍然不起作用。原因在于执行顺序 —— 配置补丁层先组装 entry 选项,随后才进入模块解析与兼容性检查,检查不通过时由运行时把 entry 选项改写为禁用,运行时写入优先级压过静态配置覆盖,所以改 YAML 这一层救不回来。
需要特别区分两种性质完全不同的 disabled:
- 故障禁用(本次根因):版本兼容性检查未通过,旧版插件被运行时隔离,不会导入模块。
- 正常禁用:由官方 bundle 主动关掉的 CLI 行(如 tool-bash、tool-fs、tool-web、plan-mode 等),--dump-config 层注释里会标明是被 bundle 修补关闭,桌面端装配方式本身就不挂这些行。
同一份日志里两种禁用并存,必须逐行确认是谁禁用的,不能只按关键字或数量归类。
三、分层定位:把启动失败拆成五层,逐层缩小范围
排查插件化 Electron 客户端的启动失败,可以从上到下分成五层,理清层次后就知道该看哪个文件,不靠猜:
| 层级 | 检查对象 | 典型日志 / 入口 | 本次是否命中 |
|---|---|---|---|
| L1 壳层 | Electron 主进程、渲染进程是否起来 | web-boot 日志 | 否,壳层只是在反复拉起 host |
| L2 Host | host 子进程是否异常抛错 | host 日志 error 段 | 只看到症状,看不到根因 |
| L3 组合层 | profile 插件树是否组装正确 | cordis.yml、cordis.patch.yml、--dump-config | 否,组合结果完好 |
| L4 加载层 | 每个插件能否加载、能否拿到依赖服务 | 加载器 stdout(crash log 未捕获) | 是,根因藏在这一层 |
| L5 解析层 | 包能否解析、版本是否匹配 runtime | ERR_MODULE_NOT_FOUND、兼容性检查 | 属于兼容性侧触发 |
关键提醒:应用 crash log 只捕获抛出的异常,没有捕获加载器的标准输出;那些 dsh: ... 提示写到 host 进程的 stdout/stderr,进程一退出就丢失。所以必须手工隔离启动一次,把 stdout 完整抓下来,才能拿到加载器的原话。
四、根因:加载期的版本兼容性检查
加载器在导入插件前会检查插件声明的 DSH 版本要求,并与运行时版本比较:清单声明了 engines.dsh 时只由该范围决定,忽略 peerDependencies;否则 peerDependencies 中对 @deepseek-ai/dsh 及 @deepseek-ai/dsh- 的每个范围都必须匹配。最关键的一点是:预发布版本参与范围匹配,rc.2 与 rc.3 即使只差一个预发布序号,也被判定为互不兼容。
完整因果链可以串成一条线:
- 应用本体升到 rc.3,而 profile 依赖仍是 rc.2;
- 版本检查判定 llm、tools 等旧版插件不兼容;
- 运行时把对应 entry 标记为 disabled(写入运行时条目,不写回你的 YAML);
- llm、tools 服务没有任何提供者,providers: [];
- agent-loop、tool-executor-native 两个 required 插件一直 pending;
- 启动审计发现必需插件未激活,抛出致命错误;
- 壳层重启 host,进入无限循环。
五、修复步骤:先隔离复现,再动正式环境
1. 准备隔离的 DSH_HOME 复现环境
不改动正式配置,先复制一份配置到临时目录并软链依赖,自己启动一次 boot,把标准输出重定向到日志文件:
- 新建临时 home 目录与隔离 profile 目录;
- 把原 profile 下的 cordis.yml、package.json、pnpm-workspace.yaml、cordis.patch.yml 复制过去;
- 软链原 profile 的 node_modules,避免重复装包;
- 别忘了复制 home 层的 cordis.patch.yml;
- 用 ELECTRON_RUN_AS_NODE=1 以应用自带 Electron 作为 Node 运行时启动 CLI,stdout 与 stderr 一并写入 boot 日志,从中读取加载器对每个插件的版本判定原话。
2. 清理 profile 中不该 pin 的应用自带运行时包
应用自带的 runtime 包一旦被 pin 进 profile,会形成 "影子副本":既过不了版本检查,又解析不到只有应用内部才有的兄弟包。需要从 profile 依赖中删掉以下 8 个应用自带运行时包:
- @deepseek-ai/dsh-llm
- @deepseek-ai/dsh-tools
- @deepseek-ai/dsh-attachment
- @deepseek-ai/dsh-http-proxy
- @deepseek-ai/dsh-mcp-client
- @deepseek-ai/dsh-scope
- @deepseek-ai/dsh-subprocess
- @deepseek-ai/dsh-timeout
应用不带、由用户自装的插件(子代理提供方、桥接、本地 link 包等)则保留并同步升到 rc.3。
3. 对齐 pnpm 版本后重装依赖
装依赖用的 pnpm 版本必须和应用一致,否则会写出应用读不了的 lockfile 格式。处理要点:
- 不要直接用系统 pnpm(版本可能偏高),也不要用系统 Node 起子进程绕过;
- 优先使用应用自带的 pnpm,同样以 ELECTRON_RUN_AS_NODE=1 方式调用;或把对应版本 pnpm 装到临时目录,用应用内置 Electron 运行;
- 非 TTY 环境下必须带 CI=true,否则 pnpm 会拒绝清理 node_modules;
- 若 profile 用了供应链策略白名单(如 minimumReleaseAgeExclude),新发布的 rc 版本号要同步补进去,否则会被策略卡住;
- 留意 corepack 可能偷偷往 package.json 写入 packageManager 字段,使用系统 pnpm 跑过后要检查并删除,避免改变应用自带 pnpm 的版本行为。
4. 先隔离验证,再切回正式环境
隔离环境启动通过、必需插件全部 active、服务提供者正常注册后,再把同样的依赖调整应用到正式 profile 并重装依赖。崩溃循环期间不要在正式环境反复重启:应用写 patch 配置是整份覆盖,内存里只保留上一次成功读到的子集,反复崩溃期间的写入可能丢掉 locale、部分 UI 设置和 MCP server 配置。
六、回滚与版本对齐注意事项
单方面回滚 profile 没有意义:应用本体已经是 rc.3,把 profile 依赖退回 rc.2 后,版本检查会立刻再次触发。正确的对齐方式只有两种:
- 让 profile 升到 rc.3,与当前应用本体保持一致;
- 若确实要回到 rc.2,则必须同时把应用本体降回 rc.2,两边版本严格匹配。
七、避坑清单
- crash log 不含加载器 stdout,"谁禁用了什么" 只在 host 进程标准输出里,需要手工跑一次 CLI 才看得到。
- disabled: false 覆盖救不了版本检查,配置在组合期生效,检查在加载期执行,后者优先。
- 同名的禁用分正常禁用与故障禁用两种,用 --dump-config 的层注释区分。
- Electron 持有的 profile 会被独占锁定,软链别名即可只读查看组合树、跑隔离启动。
- profile 里不要 pin 应用自带运行时包,避免形成影子副本。
- 非 TTY 环境跑 pnpm 必须加 CI=true。
- 供应链策略白名单要同步补新版本号。
- 崩溃中的客户端可能不响应 SIGTERM,必要时用强杀方式结束进程。
【常见问题】
问题 1:升级 rc.3 后闪退,日志提示必需插件未激活,为什么在配置里搜不到 disabled 记录?
回答 1:rc.3 加载期的版本兼容性检查会在运行时把不兼容插件置为禁用,这个写入发生在配置组合之后,运行时优先级高于静态配置,所以配置文件里看不到对应记录;手动覆盖 disabled: false 也无法生效,需要通过隔离启动查看加载器 stdout 确认被检查隔离的插件,再按版本对齐修复。
问题 2:rc.2 和 rc.3 差一个预发布序号,为什么升级 rc.3 后旧版插件会被判定不兼容?
回答 2:rc 预发布版本同样参与版本范围匹配,0.2.2-rc.2 与 0.2.2-rc.3 被视为互不兼容;旧版插件声明的 DSH 版本范围覆盖不到 rc.3 运行时,导入前就会被拒绝并标记停用,这正是本次 rc.3 启动闪退与必需插件挂起的直接触发条件。
问题 3:修复 rc.3 闪退时,profile 里哪些依赖可以保留,哪些必须删除?
回答 3:应用自带的 8 个 dsh 运行时包(llm、tools、attachment、http-proxy、mcp-client、scope、subprocess、timeout)不应在 profile 中 pin,需要删除,交给应用自身的 runtime resolution 解析;用户自装的第三方插件、子代理提供方、桥接与本地 link 包可以保留,但要同步升到与 rc.3 兼容的版本。
问题 4:回滚到 rc.2 能不能解决升级 rc.3 后的闪退问题?
回答 4:单独把 profile 退回 rc.2 无法解决,因为应用本体已是 rc.3,版本检查会再次触发不兼容;要回退就必须应用本体与 profile 依赖一起降回 rc.2,否则正确方向是把 profile 全部对齐升到 rc.3。
问题 5:重装 rc.3 依赖时 pnpm 报错或 lockfile 格式读不了,应该怎么处理?
回答 5:这类问题通常是 pnpm 版本与应用不一致导致的,应改用应用自带的 pnpm 或以应用内置 Electron 作为 Node 运行时调用对应版本 pnpm;非 TTY 环境带上 CI=true,并检查供应链策略白名单是否补了新 rc 版本号、package.json 里是否残留 corepack 写入的 packageManager 字段。
【参考资料】
- [2026-11-17](升级到 rc.3 后一打开就闪退?日志说两个必需插件没启动,问题不在配置里)阿里云开发者社区
- [2026-11-11](DeepSeek Harness 更新与卸载:DSH 版本、Profile 和插件回退指南)52DSH
- [2026-11-07](dsh-plugin-dshm 版本兼容要求说明)npm
- [2026-11-04](deepseek-harness Releases 与上游 Release notes)Gitea
- [2026-11-01](@wisdoverse/dsh-skills-manager 兼容性矩阵)npm
- [2026-08-21](DeepSeek Harness 更新日志与最新版本)DSHarness
【免责声明】
本文基于公开技术资料与社区排查案例整理,仅用于技术问题定位与参考,文中涉及的版本号、插件名称、目录路径与命令参数请以你当前实际安装的官方版本和官方文档为准。不同环境、不同插件组合下现象可能存在差异,操作前建议先备份配置与依赖清单,并在隔离环境验证通过后再修改正式环境;本文不构成任何使用承诺或结果保证,因参照本文操作产生的环境变更或数据风险,需由操作者自行评估并承担。
