上一课你刚用 headless 一次性 runner 跑通了端到端流水线：工具插件与自定义 LLM 适配器串成一条链，一次任务从启动到完成，退出码、命令行输出与会话轨迹全部核对无误。一切正常时，插件加载几乎是隐形的；可一旦加载失败，就得立刻换一副排查眼光。插件加载失败分两大家族：挂载失败，和补丁未生效。挂载失败会报错，很响；补丁未生效常常一声不吭。排查路径不同，别混在一起。

先弄清你面对的是什么。一个运行中的 dsh，是启动时按有序层堆叠出的插件树：每个 bundle 贡献配置行和代码，profile 把它们列出来，并持有你自己的 cordis.patch.yml。没有特权核心需要打补丁——你要扩展 dsh，就在其他插件旁边挂载一个插件；注册是 effect，插件卸载时自动回卷。

Cordis 内核负责挂载、卸载插件并解析依赖。插件挂不上，先问三个问题：它在不在插件树里？它的依赖有没有人提供？它的版本和环境对不对得上？

排查按固定顺序推进：读启动输出定位失败阶段，核对插件树里的行 id，查依赖声明，区分版本问题与配置问题，最后用最小化配置回滚。每步都缩小范围。

先读日志，再动配置。

启动输出按层顺序推进：bundle 按 profile 中的列出顺序应用，之后才是补丁层。失败打印在哪一行，哪一行就是分界线。分界线之前都正常，问题出在这一层；分界线之后才炸，往往是下游依赖了没挂上的服务。

Cordis 的加载是依赖驱动的：一个插件要等它依赖的服务可用才挂载。日志里第一个失败的插件不一定是元凶——它可能只是没等到依赖。往前看一层，找它 inject 的服务由谁提供。

还有一类故障不在启动期：插件挂载成功，但直到某次事件或工具调用才报错。这种别先查补丁，先确认该服务确实由某个已挂载插件提供。

版本问题还是配置问题？看报错的时间点和内容。

版本问题出现在启动早期：引擎校验不过、依赖解析失败、插件与 dsh 的 API 对不上。特征是换环境就复现，和配置内容无关。配置问题出现在补丁应用之后：字段校验失败、服务行为不对、补丁静默不生效。特征是改配置就变，换环境不变。

分不清时，做两个实验：把插件版本固定到文档实测过的版本，看故障是否消失；把配置回滚到最小，看故障是否消失。前者变好是版本问题，后者变好是配置问题。