dsh 启动就报错：command not found、settings unavailable 与加载失败的合并排查

启动报错看着杂，其实只有三层：命令层找不到 dsh、包管理层缺 pnpm、插件加载层初始化失败。 先分层，再修；三层混着查，最容易在错误方向重装。

先分三层

按报错出现的位置分层，比按报错文字分更准。

命令层最先排查。 连 dsh 都找不到，后面的插件问题无从谈起；先用 npx 对照一次，能快速区分「没装」与「路径不对」。

包管理层其次。 命令能跑但一装插件就报 pnpm，说明运行环境缺包管理器；这不是插件问题。

插件加载层最后。 前两层都正常，才进入插件；这一层的报错通常带具体模块名或字段名。

第一层：命令找不到

四种写法，本质相同：系统找不到可执行文件。 逐个对照。

1. zsh: command not found: dsh。 macOS/Linux 常见；先看是否全局安装，再看 npm 全局 bin 是否在 PATH。
2. dsh not found。 与上一条同类，可能是 shell 配置未重新加载。
3. 'dsh' 不是内部或外部命令。 Windows 的 CMD/PowerShell 表述；检查安装位置与 PATH。
4. dsh 命令不存在。 中文描述，含义相同；先确认安装方式。

最快的对照实验是用 npx。 执行 npx @deepseek-ai/dsh --version：能输出版本，说明包在、PATH 有问题；同样报错，说明没装或安装失败（来源）。

PATH 问题不要靠猜。 看全局 bin 目录是否在 PATH，改完重新打开终端；只改当前会话，重启后又会失效。

第二层：pnpm 与依赖

命令能跑，但一涉及 profile 插件就报 pnpm。 这类问题的修复很直接。

1. 确认 pnpm 是否安装：pnpm -v。
2. 不在 PATH 时，按官方说明安装并配置路径；不要只在一个终端里临时生效。
3. 重新执行触发报错的命令，确认不再提示 pnpm。
4. 如果 pnpm 在、仍报错，检查是否多个版本冲突；用 which pnpm 看实际调用的是哪个。
5. 最后再启动，确认插件链路可用。

pnpm 是插件链路的必需项。 用 npm 替代可能在安装阶段看似成功，加载阶段才失败；这类问题更难查。

多版本冲突比缺失更隐蔽。 命令存在但版本不兼容，报错信息可能指向别的模块；先确认实际调用的版本。

第三层：插件加载

前两层正常，启动仍失败，问题在插件加载。 四类报错按出现频率排。

1. cannot read properties of undefined (reading 'prepare')。 模块初始化读到了空对象；多与插件版本、构建产物或依赖有关。
2. crypto.randomUUID is not a function。 运行环境缺少该 API；常见于旧运行时或 Web 环境差异。
3. settings are unavailable in this browser。 浏览器环境拿不到设置；与入口、缓存或权限有关。
4. failed to load plugins。 加载阶段整体失败；先看日志里的第一个失败插件。

这一层的排查顺序是「定位插件 → 看版本 → 停用对照」。 先确认是哪一个插件导致，再决定升级、停用或回滚。

不要一次停用全部插件。 全停只能证明「插件有问题」，不能定位是哪一个；一次停一个，结果才可用。

排查顺序：从外到内

按「命令 → 包管理 → 插件」从外到内，能避免重复劳动。

1. 用 npx 对照，确认命令层是否正常。
2. 检查 pnpm 与 PATH，确认包管理层可用。
3. 看日志里的第一个失败插件，确认加载层问题。
4. 停用可疑插件，复测启动；恢复则定位成功。
5. 升级或回滚该插件，再复测。

每一步只改一件事。 同时改 PATH、pnpm 与插件，问题消失也不知道是哪一步解决的。

记录每一步的结果。 命令是否可跑、pnpm 是否可用、停用哪个插件后恢复；下次遇到同类问题可以直接对照。

修复后验证

启动成功不等于修好，要验证三个信号。

1. 命令信号： dsh --version 正常输出版本。
2. 加载信号： 启动日志没有失败记录，插件列表可读。
3. 功能信号： 打开一个会话，执行一次最小操作，确认插件入口可用。

三个信号都过，才算恢复。 只看启动画面，可能只是跳过失败插件继续启动，问题仍在。

验证后保留日志。 出问题时能对照「修复前」与「修复后」的差异，判断是否真的改变。

预防：升级与安装的边界

启动类报错，很多来自「装了什么就升级什么」的习惯。 三条边界能减少问题。

1. 核心与插件分开升级： 先升核心，再升插件；反过来容易出现插件要求新核心。
2. 一次只升一个插件： 出问题能立刻定位；批量升级只能全停。
3. 保留可回退版本： 记录升级前版本与配置，出问题能退回去。

边界不是限制，是排查成本。 每次只动一个变量，问题永远只有一条线索。

下一步

先分层，再逐层修。 想看命令找不到的完整排查，看《dsh 命令找不到》；想看 prepare 报错，看《cannot read properties of undefined reading prepare》；想看插件加载失败，看《插件加载与激活失败》。

来源：dsh CLI README、DeepSeek Harness 官方文档、deepseek-harness 仓库