报错排查：dsh 插件装上了却始终不加载

harness 里几乎所有「我的插件不工作」都是下面四种之一，而且一分钟内能分辨。根因通常是同一个错误假设：

第一步：它到底在不在组装里

dsh --profile web --dump-config

这会打印所有层应用之后、每一行可被 patch 命中的配置。在里面搜你的包名。

没有 → 包可能装上了，但没有东西挂载它。看成因 A。

有，但配置和你写的不一样 → 更高的层覆盖了你。看成因 C。

有，配置也对，但运行时能力还是缺 → 看成因 D。

成因 A：装了，但从没挂载

最常见的一种。你跑了：

dsh plugin --profile web add some-cordis-plugin

它装完包就结束了。你还需要在 $DSH_HOME/profiles/web/cordis.patch.yml 里加一行来挂载它。patch 按 标识符命中某一行，要么整行替换配置、要么插入新行——这里你要的是插入。

然后再 --dump-config 验一次。别跳过验证：这正是那类会悄无声息什么都不干的改动。

成因 B：装到了另一个 profile

插件装进 profile 自己的 node_modules。这种隔离是刻意的——它让两个 profile 能各持互不兼容的插件 集——但也意味着：

dsh plugin --profile web add thing     # 装进 web profile
dsh --profile headless                 # 看不见它

确认你装进的 profile 就是你启动的那个。两边都要，就装两次。

还有一点相关：bundle 先从 dsh 安装目录解析，再从 profile 的 node_modules。同名的东西两边都有时， 安装目录里那份赢。想靠同名去遮盖自带包的本地包，光靠名字做不到——改用 patch 覆盖自带的那一行。

成因 C：更高的层在覆盖你

层的顺序，优先级由低到高：

1. profile 叠的每个 bundle，按次序
2. $DSH_HOME/profiles/<名字>/cordis.patch.yml
3. $DSH_HOME/cordis.patch.yml
4. 运行时的 --patch 覆盖

后面的赢。 这个 bug 最常见的版本是：某人几个月前在 home 级 patch 文件里设了点什么，忘了，然后改 profile 级文件，发现毫无变化。

# 干净 profile 组装成什么样
dsh --profile web --dump-default-config > /tmp/base.txt
 
# 你实际启动的是什么
dsh --profile web --dump-config > /tmp/mine.txt
 
diff /tmp/base.txt /tmp/mine.txt

这份 diff 精确地等于你的层所做的全部改动。你想要的改动不在里面，就是你压根没做成；在里面但不对， 就是有更靠后的东西改写了它。

成因 D：挂载了，但这项能力没有提供者

有些工具背后需要东西。比如 lsp 工具需要一个已注册的 LSP provider——没有 provider，工具挂上了但无处 可问。

harness 把能力建模成 seam：拥有 ctx.<key> 的服务定义、一个或多个服务提供者、以及注入该服务的 消费者。一个没有提供者的消费者，是一份自洽但不干活的组装，而且启动时不会报错告诉你这件事。

如果插件出现在 --dump-config 里却还是不工作，问一句：它消费的是哪个服务，有东西提供它吗？

安装阶段就失败

如果 dsh plugin add 本身失败，记住底下是 pnpm，报错也是 pnpm 的报错：

• ERR_PNPM_FETCH_404——包名写错了，或者根本没发布。
• peer dependency 警告——插件是针对另一个核心版本构建的。在一个明确预期会有破坏性变更的 v0.1 预览版上，认真对待这类警告，别强行绕过去。
• 网络或 registry 报错——你的 registry 配置问题，不是 harness 的问题。

pnpm 全套词汇可用，所以版本号能把插件锁到和你 harness 匹配的版本：

dsh plugin --profile web add [email protected]

一份清单

1. --dump-config——那一行在吗？
2. 你装进的 profile 是你启动的那个吗？
3. 和 --dump-default-config 做 diff——你的改动真的在差异里吗？
4. 有没有一个你已经忘掉的 home 级 patch 层？
5. 这个插件消费的服务，有东西提供吗？