DeepSeek Harness 插件不加载怎么办？DSH plugin 安装后无效排查与修复
DSH plugin 装完不加载，九成是三种情况：没重启或刷新、装错 profile、插件包不完整——按「重启刷新 → dsh plugin list → 查 profile → 看启动日志」四步排查，再按「重装 → 改装 npm 版 → 回退版本」的顺序修复，装了 DSH Plugin Hub 的还能直接在通知中心看失败原因。
概览：插件不加载，先分类再动手
DeepSeek Harness 插件不加载的表现五花八门，但根因高度集中，先按清单排查能省很多时间。 DSH plugin 是导出 apply 函数的 TypeScript 模块，框架加载时调用 apply 并传入 ctx 注册能力（来源）；装完不生效，就是「加载」这步出了问题。常见表现：界面入口没出现、会话里没有新能力、宿主启动报错退出。本文按「根因 → 排查 → 修复」展开，排查部分给到具体步骤。
插件不加载的常见根因
三种根因占了绝大多数：没重启/没刷新、装错 profile、插件包不完整。 具体说：
- 没重启/没刷新：界面类插件在宿主启动时挂载，装完需要重启 dsh web 或刷新浏览器页面才生效——这是最常见、也最好解决的一种。
- 装错 profile：插件装在 profile 目录（$DSH_HOME/profiles/<name>）里，装到 web 之外的 profile，应用内自然看不到（来源）。
- 插件包不完整：git 分发的插件常缺构建产物，package.json 指向的入口文件在包里不存在，装完加载时报 ERR_MODULE_NOT_FOUND，严重时宿主直接启动失败。
排查步骤：四步定位问题
按顺序走四步，每步都能排除一类根因。 具体操作：
第 1 步：重启 dsh web 并刷新页面。 界面类插件在宿主启动时挂载，重启服务（Ctrl+C 后再跑一次 npx @deepseek-ai/dsh web）或刷新浏览器，能解决「没重启/没刷新」这类问题。重启后功能出现 → 收工；没出现 → 继续。
第 2 步：确认插件装到了当前 profile。 执行下面的命令，看插件在不在列表里：
# 查看 web profile 下已安装的插件
dsh plugin --profile web list
插件不在列表里 → 安装没成功或装错 profile，用正确的 profile 重新安装；在列表里但功能不出现 → 继续下一步。
第 3 步：核对 profile 目录。 插件是装在 profile 目录里的，确认插件确实在 $DSH_HOME/profiles/web（或你正在用的 profile）下，而不是装到了别的 profile。
第 4 步：看启动日志的报错。 重启宿主，观察终端或日志输出：报 ERR_MODULE_NOT_FOUND 即入口文件缺失（插件包不完整）；报其他错误多半是兼容性问题——插件详情页会标注目标 DSH 版本，核对与你装的 DSH 本体版本是否匹配。
修复：重装、改装 npm 版与回退版本
按根因对症下药：包不完整改装 npm 版，兼容问题回退版本，装错 profile 重新装。 具体方案：
- 改装 npm 分发版本：GitHub 源缺构建产物时，换成 npm 包重装，例如
dsh plugin --profile web add <包名>——npm 包由作者发布构建产物，一般不存在缺入口的问题。 - 回退版本：新版本与 DSH 本体不兼容时，装回旧版本，或等插件作者适配（参考《更新后插件不兼容回滚》）。
- 重装：
dsh plugin --profile web remove <包名>卸载后重新安装，清除可能的残留。 - 换界面入口重装：装了 DSH Plugin Hub 的，直接在「设置 → 插件中心」搜索该插件，重新一键安装。
用 DSH Plugin Hub 排查与重装
装了 DSH Plugin Hub 后，插件失败原因会写进通知中心，排查不用翻日志。 打开设置 → 插件中心，每次安装/升级/卸载的成功与失败都会留痕，失败原因一目了然；失败可一键提交 GitHub Issue 反馈作者，待重启项支持「稍后重启 / 立即重启」：
排查出问题后直接在插件中心重装，后台队列串行执行、弹窗实时显示进度，装完刷新页面即生效：
装插件时优先选 verified（已验证）状态的 npm 包，能绕开 git 分发缺构建产物这类问题。Hub 使用详见《DSH Plugin Hub 怎么用？》。
常见问题与下一步
- 升级后不兼容：升级本体后插件失效，多半是版本不匹配，参考《更新后插件不兼容回滚》。
- 想批量更新插件：参考《批量更新 DSH plugin》；不想敲命令就在「设置 → 插件中心」里一键更新。
- 插件一直加载失败：到插件详情页核对目标 DSH 版本，或通过通知中心一键提交 GitHub Issue 联系作者。
来源：DeepSeek Harness 官方 Quickstart、dsh CLI README、dshplugin/dsh-plugin-hub
常见问题
按顺序排查：先重启 dsh web 并刷新页面；再用 dsh plugin --profile web list 确认插件在列、装在哪个 profile；最后看启动日志的报错——多半是插件包不完整或目标 DSH 版本不匹配。
最常见三种：没重启/没刷新（界面类插件挂载在启动时）、装错 profile（web profile 之外的地方装了，应用内看不到）、git 分发缺构建产物（装完即报错或宿主启动失败）。
通常是 GitHub 源插件没提交构建产物：package.json 指向的入口文件（如 lib/index.js）在包里不存在。解决：改装 npm 分发版本，或反馈插件作者补构建产物。
执行 dsh plugin --profile web list 查看 web profile 下的插件列表；插件是装在 profile 目录（$DSH_HOME/profiles/<name>）里的，装到别的 profile 应用内就看不到。
先确认装到了当前使用的 profile（dsh plugin --profile web list 查看），再重启 dsh web 并刷新页面；界面类插件入口挂在设置页或插件中心插槽上，装对 profile 且刷新后才会出现。
能。装了 DSH Plugin Hub 后，安装/升级/卸载的成功与失败都会写入通知中心，失败原因一目了然，还支持一键重装与提交 GitHub Issue。
来源
- DeepSeek Harness 官方文档 - Quickstart· deepseek-harness
- dsh CLI README· deepseek-ai
- dshplugin/dsh-plugin-hub GitHub 仓库· GitHub