dsh plugin 报 plugin tree failed to load：DeepSeek Harness 排查

dsh plugin 报 plugin tree failed to load 时，别从最外层那句话往下猜——这条报错链是嵌套的，最内层那句才是真实原因。 最常见的两种底层原因：端口 3080 已被占用（报错文本为 listen eaddrinuse: address already in use 127.0.0.1:3080），以及 profile 的 cordis.yml 里 include 条目有问题。本文教你先从外到内把这条链读完，再按成因分头处理，最后重启确认 DeepSeek Harness 的插件树加载完整。

DSH plugin 这条报错怎么读：从外到内三层

failed to apply loader entry 在同一条报错里可能出现多次，每嵌套一层就多一个冒号分隔——最后那一段才是根因。 以最常见的一条完整报错为例：

error: dsh: plugin tree failed to load:
  failed to apply loader entry include (cordis:include):
  failed to apply loader entry webserver (@deepseek-ai/dsh-host-webserver):
  listen eaddrinuse: address already in use 127.0.0.1:3080

逐段读，四层各管一件事：

1. plugin tree failed to load：DeepSeek Harness 的加载器在启动阶段要按 profile 的 cordis.yml 把各个 loader entry 组合成插件树，只要有任何一个 entry 应用失败，整棵树就判定为加载失败，进程在启动阶段直接退出，agent 还没机会跑起来。
2. failed to apply loader entry include (cordis:include)：第一层失败的 entry 名叫 include，提供它的包是 cordis:include。include 自身不提供业务能力，只负责把别的配置条目并入插件树——所以「include 失败」通常不是 include 坏了，而是它引入的东西坏了。
3. failed to apply loader entry webserver (@deepseek-ai/dsh-host-webserver)：再往里一层失败的是 DeepSeek Harness 的 Web 服务加载项，它负责把 Web UI 绑到本机端口。
4. listen eaddrinuse: address already in use 127.0.0.1:3080：真正的根因——绑定 3080 时被系统拒绝，因为这个端口已经有程序在监听（来源）。

一句话：报错链是从外往内收的，越靠后越接近根因。先读最后一段，再决定要不要往前看。

两类真实原因：dsh plugin 端口被占用与 cordis.yml 条目异常

最内层那句指向哪一类，决定你后面怎么修。

一、3080 端口已被占用（最常见）

只要本机已经有一个程序在监听 3080，新的 dsh web 或桌面端就会在 webserver 这一步抛 EADDRINUSE。 常见来源有两类：

1. 上一个 dsh web 还活着：终端窗口被关掉了但进程没退，或者托盘常驻的桌面端已经把 3080 占住。
2. 别的程序碰巧用了 3080：某些本地服务、代理工具、开发服务器会撞到同一个端口。

定位占用进程：macOS / Linux 用 lsof -i :3080，Windows 用 netstat -ano | findstr :3080。确认真的是残留的 dsh 实例就停掉它；如果占用者是别的程序而你不想动它，就改用 dsh web --port 8080 换端口——注意 --port 是 web 应用的参数，必须放在 dsh web 之后。端口排查的完整流程见 127.0.0.1:3080 打不开怎么办。

二、cordis.yml 的 include 条目有问题

如果最内层是 failed to validate config file .../cordis.yml，那问题就在 profile 的配置文件上，跟端口无关。 profile 的配置放在 $DSH_HOME/profiles/<profile>/ 下，其中 cordis.yml 是根配置、cordis.patch.yml 是覆盖层。两类典型情况：

1. 文件内容确实被写坏了：手工编辑 cordis.yml 或 cordis.patch.yml 时数组括号不配对、写进非法 YAML，include 解析不过就会报校验失败。
2. 并发启动撞上写入窗口：同一个 profile 同时起两个实例时，启动阶段会就地重写 cordis.yml，在亚毫秒级的窗口里另一个进程读到空文档，于是报校验失败——但你事后去看这个文件，它是完好的。这一类的机制与规避见 cordis.yml 覆盖竞态排查。

三步恢复：释放 3080、修 include、重启确认 dsh plugin 插件树

按「先排除最常见、再修配置、最后验证」的顺序走，多数情况三步内恢复。

1. 第一步：释放被占用的 3080。 先用命令定位占用者：

lsof -i :3080                  # macOS / Linux
netstat -ano | findstr :3080   # Windows

确认它不是你要保留的服务后停掉；不想动那个进程就改用 dsh web --port 8080，然后访问 http://127.0.0.1:8080。

2. 第二步：检查 profile 里 include 指向的条目。 打开 $DSH_HOME/profiles/<profile>/cordis.yml 与 cordis.patch.yml，重点看最近手改过的那几行——最常见的是数组括号不配对、条目被误删、新增插件条目写在错误的位置。改成合法 YAML 后保存。

3. 第三步：重启并确认插件树加载完整。 重新执行 dsh web（等价于 dsh --profile web），等终端打印出访问地址。需要关闭时按一次 Ctrl+C：DeepSeek Harness 会给插件树最多 5 秒清理现场，卡住时再按一次立即退出，退出码是 130（来源）。

DSH plugin 排查注意事项

先记住「最内层才是原因」，再按端口与配置两条线分头走，能省掉大部分无效重装。

1. 先读最内层：plugin tree failed to load 只是外壳，真实原因永远在最后一个冒号之后。
2. failed to apply loader entry X (Y) 里 Y 才是包名：X 是条目名（如 include、webserver），Y 是提供它的包（如 @deepseek-ai/dsh-host-webserver）。
3. 别急着重装插件：端口占用和配置竞态都与插件文件无关，重装解决不了。
4. 改 cordis.yml 前先备份：它是 profile 的根配置，写坏会让整个 profile 起不来。
5. 一次只启动一个实例：确认上一个 dsh web 真的退出后再启动下一个。
6. 3080 被占用的正解是换端口，不是删文件：dsh web --port 8080。
7. 要核对已装插件时，插件市场比翻 YAML 快：在「设置 → 插件市场」即 DSH Plugin Hub 里逐项查看已装清单与版本。
8. 其他插件类报错可参考插件不加载排查。

来源：DeepSeek Harness CLI README、dsh CLI 行为参考、Discussion #441。