启动报错与插件加载排查
启动报错的四类根因#
官方 CLI 参考写明：配置解析、schema 校验、模块解析或插件启动失败时，dsh 会报告错误并以非零状态退出。排查第一步是读完整报错，先判断失败属于哪一类：
- 配置解析——
cordis.patch.yml本身写错 - schema 校验——某个插件收到的配置不合法
- 模块解析——插件代码找不到或没构建
- 插件启动——插件
apply运行时抛错
安装阶段就失败的（网络、Node 版本、构建授权）见安装失败排查，本文只讲装上之后的启动加载问题。
GitHub 插件缺少构建产物#
git 安装拉取的是源码而非构建产物：如果作者没有提供自包含的 prepare 脚本，TypeScript 包到手时没有 lib/ 输出，启动加载会以模块解析错误失败。先确认已按安装失败排查把包键加入 profile 的 pnpm-workspace.yaml allowBuilds 并重新安装；授权细节见插件配置与版本锁定。
授权后仍然失败，多半是作者侧缺少构建脚本，用户侧无解，可改用两种预构建分发形式之一，它们不需要任何构建授权：
- npm 发布版：
dsh plugin add <包名> - tarball：
dsh plugin add ./xxx-0.1.0.tgz
或者带着报错向作者反馈，渠道见反馈与社区渠道。
配置校验失败#
插件加载时会用其导出的 schema 校验配置，配置不合法会加载失败并给出明确错误信息，报错通常指明哪个字段出了问题。错误来自自己 profile 的 cordis.patch.yml 就直接修；错误指向组合包贡献的行，不要改包本身，在自己的 patch 层覆盖该行。
插件静默不加载#
不是所有加载问题都有报错。如果插件的 inject 声明了无人提供的服务，它会一直停在 PENDING 等待，不输出任何内容——这是合法状态，提供方可能稍后才挂载。插件"装了但不见效"时按顺序检查：
- 插件行是否被标记了
disabled: true - 安装时是否出现过一次性警告：没有
dsh.bundle声明的包只作为普通依赖保留，不激活任何配置层 - 用官方教程的诊断脚本枚举 fiber 状态，找出停在 PENDING 的插件
诊断脚本来自官方 Cordis 教程，加载后 500ms 打印所有等待依赖的插件：
import { FiberState, type Context } from '@deepseek-ai/cordis'
export const name = 'diagnose'
export function apply(ctx: Context) {
setTimeout(() => {
for (const runtime of ctx.registry.values()) {
for (const fiber of runtime.fibers) {
if (fiber.state === FiberState.PENDING) {
console.log(`${fiber.name} is PENDING — a required service is missing`)
}
}
}
}, 500)
}用 dump-config 看生效配置#
怀疑某行配置来路不明时，先让 dsh 打印组合后的完整配置树：
dsh --profile <name> --dump-config输出会注明每行来自哪个文件、被哪些 overlay 修改过；找不到目标的 patch 会报告到 stderr。profile 与 home 两级 cordis.patch.yml 的修改在运行中会被监视并事务式重新应用，改配置不需要重启。
插件自身代码出错#
报错栈指向插件包内部（apply 抛异常）时，问题大概率在上游：最近的推送引入了 bug。回退到上一个确认可用的提交验证：
dsh plugin add github:<owner>/<name>#<commit-sha>版本锁定用法见插件的安装、更新与卸载。确认是上游 bug 就去仓库提 issue，附上完整报错与所锁定的提交，渠道见反馈与社区渠道。
快速恢复启动#
只想先恢复可用时，移除问题插件，其依赖与配置层会一并删除：
dsh plugin --profile <name> remove <包名>移除前建议先 --dump-config 记下该插件贡献的配置行，事后按需补回。
本文依据官方 CLI 参考与发布教程整理，命令行为以上游文档为准。
