DeepSeek Harness 插件故障排查：dsh 安装报错、cordis.patch.yml 冲突与 Profile 失效修复指南（2026）
DeepSeek Harness（dsh）插件安装与配置常见问题排查手册：pnpm workspace allowlist 报错、dsh bundle 格式错误、cordis.patch.yml 冲突、Profile 不生效、插件装了却不加载，逐项给出原因与修复命令。
最近更新: 2026-08-26
何时使用本指南
在「找到插件」与「插件正常运行」之间出问题时使用本页：dsh plugin add 失败、monorepo 里奇怪的 pnpm-workspace allowlist 报错、cordis.patch.yml 改了没反应、Profile 加载了错误的插件组合。每个小节都按同一结构展开——症状、原因、修复命令。
还没走到安装步骤？先读安全安装插件指南；不确定自己在改哪一层配置？先看配置详解。
动手之前先记住一条铁律：每次修改配置后都要重启 dsh。插件树在启动时由 Cordis 容器组装，「什么都没发生」的案例里一半只是改了配置忘了重启。
一、安装时提示找不到插件（Plugin not found）
症状：dsh plugin add dsh-some-tool 报解析错误，或者安装成功但插件始终没有出现。
原因：CLI 按精确包名从 npm registry 解析。常见原因：包名拼写错误、少了 @scope/ 前缀、插件只通过 GitHub 分发（npm 上没有条目）、或 --profile <name> 与之后启动的 Profile 不一致——条目加进了你从未启用的 Profile。
修复步骤：
- 先用
npm view dsh-some-tool核对包的确切名称。插件的详情页与仓库 README 会给出可用的安装命令——社区插件的安装方式由插件自己维护。 - 插件只在 GitHub 分发时，用源码地址安装并锁定分支：
dsh plugin add github:owner/repo#main。 - 让参数与启动方式一致：用
dsh plugin --profile web add <package>安装的，就用dsh --profile web启动，不要裸执行dsh。 - 本地开发时直接链接目录：
dsh plugin add ./path/to/my-dsh-plugin。
二、安装卡住或失败：pnpm workspace allowlist
症状：在 pnpm monorepo 中安装插件时卡住，或报 pnpm-workspace allowlist、module not found、ESM & CJS 解析错误——尤其是从 git 或本地构建安装时。
原因：pnpm 严格限制依赖边界。从 GitHub 安装的插件实际上进入了工作区，如果包没有在边界内声明，pnpm 不会链接它，运行时就无法解析插件或其依赖。
修复步骤：
- 把包声明进边界：在根目录
package.json的 dependencies（或pnpm-workspace.yaml的允许清单/目录）中加入该插件，然后在工作区根目录执行pnpm install。 - 重新安装并重启：
dsh plugin add <package>，再启动dsh让重建后的插件树生效。 - 有 npm 发布版时优先使用发布版：发布包自带依赖，天然绕开工作区边界问题。
- 确认运行环境：
node -v应输出 20.0.0 及以上。
三、cordis.patch.yml 冲突（覆盖顺序问题）
症状：两个插件功能重叠——两个侧边栏、两个 OCR 引擎、同一个服务的两套实现——其中一个的设置被静默忽略；dsh 可能提示 Profile patch collision / Override order issue。
原因：patch 是覆盖层，叠加在 bundle 与 profile 之上，后写的条目胜出。当两个条目注册同一服务或同一 UI 面板时，声明顺序决定结果。YAML 里重复的键或缩进错误，也可能悄悄改写条目。
修复步骤：
- 打开你实际使用的文件：
cat ~/.dsh/profiles/<name>/cordis.patch.yml，工作区内则是<项目根>/.dsh/cordis.patch.yml。 - 调整顺序：把希望生效的插件移到
plugins:列表末尾——后面的条目覆盖前面的。 - 或者保留两者、解除冲突：把其中一个条目的
enabled设为false。 - 最干净的长线方案：把冲突插件拆进不同 Profile，用
dsh --profile <name>分别启动。 - 重启前先校验 YAML——一次缩进错误就会改变条目的含义：
yq eval . cordis.patch.yml。
四、dsh bundle 格式错误
症状：dsh 能启动，但插件组合与文档描述完全不同；或者从别处复制来的配置文件不断报冲突、加载失败。
原因：三个配置层各有分工：bundle 是随 dsh 分发的官方插件集合，profile 是你自定义的「bundle + 插件」组合，patch 只针对单个插件条目做外科手术式覆盖。如果 cordis.patch.yml 把整套 bundle 重新声明了一遍——几十条插件外加本应属于 profile 层的设置——格式就混了，这些覆盖项开始与 bundle 自带内容互相打架。
修复步骤：
- 让 patch 保持精简——每个插件一个条目，只有
enabled与options：
# ~/.dsh/profiles/default/cordis.patch.yml
plugins:
dsh-vision-toolkit:
enabled: true
options:
ocrEngine: 'default'
- 想一次启用整套插件？那是 profile 层的职责：在 profile 里配置组合，而不是把每条插件都粘进 patch。
- 删掉重复条目、保存并重启
dsh。此时插件的工具/面板应当正常加载，不再打印冲突信息。
五、Profile 不生效
症状：改了 cordis.patch.yml，重启后没有任何变化；或者为某个 Profile 安装的插件无处可寻。
原因：三选一的经典失误：改错了文件（配置文件有两处，且项目级覆盖全局级）、启动时用的 Profile 名与修改的目录不一致、或者压根没重启。
修复步骤：
- 先看两处文件是否都存在：
ls ~/.dsh/profiles/*/cordis.patch.yml 2>/dev/null，以及项目根目录下ls .dsh/cordis.patch.yml 2>/dev/null。 - 记住优先级：两者都存在时
<项目根>/.dsh/cordis.patch.yml覆盖~/.dsh/profiles/<name>/cordis.patch.yml。 - 让参数与目录一致：改了
~/.dsh/profiles/web/cordis.patch.yml，就用dsh --profile web启动——不是dsh，也不是dsh --profile headless。 - 重启验证：
dsh --profile web，检查插件的工具或面板是否出现。还是没有？看下一节。
六、插件装上却加载不了（failed to register）
症状：安装成功、配置看着没问题，但启动时 dsh 报 Plugin failed to register / Lifecycle timeout——或者插件无声无息地没加载。
原因：通常是运行时太旧（Node.js 低于 20）、依赖缺失（git 安装需要自己构建）、声明顺序与别的插件冲突，或条目被留成了 enabled: false。还有一个相关的失败模式是沙箱：dsh 默认 read-only 运行，需要读写磁盘或访问网络的插件可能在加载时就被拦下，报 Permission denied / Sandbox security policy violation。
修复步骤：
- 检查运行时：
node -v——升级到 20.0.0 及以上（推荐 Node 22 LTS）。 - 源码安装需要构建：进入插件目录执行
pnpm install && pnpm build，然后重启。 - 干净重装：
dsh plugin remove <package>，确认cordis.patch.yml中的条目，再dsh plugin add <package>。 - 确认条目处于启用状态：
dsh plugin add会写入enabled: true；如果手改过 YAML，检查它还在不在。 - 如果报错与沙箱有关且插件可信，启动时放行：
dsh --sandbox workspace-write（详见安全沙箱指南）。 - 通过 dsh-market Web UI 安装的？去 Settings → Plugin Market 看插件状态——后台会应用配置并热重载，失败状态会显示在那里。