dsh-web 插件安装失败或不显示？5 类高频故障的快速定位与修复

【免费下载链接】dsh-webDeepSeek Harness (DSH) Web 插件聚合生态 · 万物皆插件，通过创意工坊分发｜｜DeepSeek Harness (DSH) Web Plugin Aggregation Ecosystem · Everything is a plugin, distributed via the Creative Workshop项目地址: https://gitcode.com/gh_mirrors/ds/dsh-web

dsh-web 是 DSH Web GUI 的插件全家桶，装上后侧边栏即拥有任务看板、移动端远程、Git 图谱、皮肤中心等能力。它最高频的吐槽就是 dsh-web 插件安装失败，或装完入口不显示。好消息是，绝大多数问题按症状对号入座，几分钟就能排掉。本文按"你看到的报错现象"把 5 类高频故障从高频到低频排开，带着症状直接跳到对应小节即可。

快速自检：动手排查前先跑一遍

九成问题是下面四条之一，先过一遍再往下看：

• 是否彻底重启过dsh web进程？只刷新网页不会加载新模块。
• 安装命令是否带了--profile web？装错 profile 等于白装。
• 目标插件行是否被停用？SSH、skill-explorer 等低频插件出厂默认关闭，需在插件管理里逐行打开。
• 宿主版本是否满足全家桶声明的下限（DSH >= 0.2.1-rc.3）？

# 前两条的验证命令：输出应包含 web-ui-* 行，否则进入分场景排查 dsh --profile web --dump-config # 重启进程后，看侧边栏入口是否出现 dsh web

四条都通过仍不行，直接进入下面的分场景排查。

分场景排查：按报错现象对号入座

安装后侧边栏没有入口：dsh-web 插件不显示

现象：安装命令跑完提示成功，重启后侧边栏依旧没有新入口；或干脆只刷新了网页，什么都没变。原因：插件是随宿主进程启动时挂载的，浏览器页面刷新不会重新加载模块；另一个高频失误是安装时漏掉--profile web，包装进了别的 profile。修复：在正确 profile 里安装并彻底重启服务进程：

dsh plugin --profile web add @linxin666/dsh-web-all@latest dsh web dsh --profile web --dump-config

第一条对已安装的 profile 是幂等无碍的；第三条输出应包含web-ui-*行，说明配置层已挂载。✅

dsh-web 插件安装失败：ERR_PNPM_IGNORED_BUILDS 构建脚本被拦截

现象：首次add报ERR_PNPM_IGNORED_BUILDS，pnpm 拒绝依赖的构建脚本，安装中断。原因：pnpm 的安全策略默认拦截 postinstall 构建脚本，而这一族插件依赖cloudflared（自动隧道）、ssh2、cpu-features等原生组件，不批准就装不到位——类似安检，未申报的行李上不了飞机。修复：在 profile 的pnpm-workspace.yaml写入审批，再重新执行安装：

allowBuilds: cloudflared: true cpu-features: true ssh2: true

📌 审批必须在首次 add 之前就位。装失败后再补审批重跑会 exit 0，但dsh.profile.bundles里并没有那一行——静默半挂载，重跑修不回来。此时用官方--from-default-profile web参数重置 profile（或换新 profile），重新走"审批 + 安装"。

修完安装仍中断，跳到下一场景。

安装 dsh-web 回退旧版本或缺少功能：pnpm 发布时间门禁

现象：安装显示成功，启动后功能缺失；或 pnpm 明确报回退拉取了旧版本——这是典型的 dsh-web pnpm 报错之一。原因：pnpm 11 默认带minimumReleaseAge发布时间门禁，新版本发布后的短时间内会被当"可疑包"处理，解析回退到旧版；个别环境的 registry 缓存也会让latest解析滞后。修复：在 profile 的pnpm-workspace.yaml加命名空间排除，然后重跑安装命令；也可以在安装时显式带版本号（包名后追加@0.4.11）：

minimumReleaseAgeExclude: - '@linxin666/*'

装完重启后仍"缺功能"，先用dump-config核对版本号是否符合预期，版本不对就回到本节重做。

启动报 Failed to load plugins 或 Cannot find package

现象：安装命令 exit 0，但dsh web启动时报Failed to load plugins或Cannot find package '@linxin666/dsh-...'，GUI 打不开。原因：两类常见情况——一是 profile 里冻结了过旧的版本，新版 loader 会直接拒绝旧的槽位注册形式；二是 pnpm 的 isolated 依赖隔离不把子包提升到顶层，宿主按顶层解析时找不到。修复：前者把 profilepackage.json里的@linxin666/*依赖升到最新版；后者把 profile 的链接方式改为 hoisted：

# <profile>/pnpm-workspace.yaml nodeLinker: hoisted

pnpm install dsh web

修完仍打不开，先确认旧进程已彻底结束再重启。

源码调试：宿主已挂载但 UI 空白

现象：用link:方式装了本地仓库，dump-config显示行已挂载，但 Web 界面就是没有入口。原因：profile 目录并不是 pnpm workspace，聚合包里的workspace:*依赖会回退拉取 npm 已发布版本；npm 版本滞后或损坏时，宿主侧一切正常，浏览器半区却出不来。修复：把仓库构建产物链接进 profile，让全部子包走本地代码：

node scripts/link-profile.mjs dsh web

若启动报ERR_MODULE_NOT_FOUND，多半是卫星仓检出（皮肤、宠物）没跑过pnpm install，在对应satellites/<仓>目录装一次依赖，再重跑链接脚本即可。

验证与回滚

验证两步：dsh --profile web --dump-config退出码为 0、输出包含全部web-ui-*行且无模块缺失告警；再重启dsh web，侧边栏入口与功能面板正常打开。任务看板入口是最直观的标尺：

想回退到纯净状态，一条卸载命令加重启：

dsh plugin --profile web remove @linxin666/dsh-web-all dsh web

✅ 到此完成：重启后入口消失，说明回滚生效。

进阶调试备忘：改源码的完整链路

需要改源码的读者：要求 Node.js >= 22 与 pnpm；当前 SDK 已结束内测，公开包通常无需令牌，若仍走私有 scope 认证，把令牌放环境变量与用户级~/.npmrc（只放环境变量，勿提交）：

git clone https://gitcode.com/gh_mirrors/ds/dsh-web.git cd dsh-web export NPM_TOKEN='<你的令牌>' # 仅私有 scope 认证场景需要 pnpm install pnpm -r build node scripts/link-profile.mjs dsh plugin --profile web add link:$(pwd)/packages/dsh-web-all

挂载成功后即可按包开发，各插件源码分布在 packages/（形态参照 packages/dsh-task-board/）；挂载机制与 profile 链接细节见 docs/plugins.md 与 docs/development.md。创意工坊站点源码在 market/：

排错心法

• 先确认进程真重启、profile 装对。刷新网页不算重启；装错 profile 比重装更浪费时间。
• 安装失败先看时机：构建脚本被拦就补审批后重做，版本回退就加排除或钉版本；别盲目重跑，半挂载是修不回来的。
• 宿主挂了但 UI 没出来，就查依赖来源：源码调试必须先跑link-profile.mjs，别让workspace:*悄悄回退成 npm 旧版本。

【免费下载链接】dsh-webDeepSeek Harness (DSH) Web 插件聚合生态 · 万物皆插件，通过创意工坊分发｜｜DeepSeek Harness (DSH) Web Plugin Aggregation Ecosystem · Everything is a plugin, distributed via the Creative Workshop项目地址: https://gitcode.com/gh_mirrors/ds/dsh-web