常见问题与排障
August 15, 2026 · View on GitHub
本页记录 DSH-Code 安装、启动和插件加载时最常见的问题。开始排查前，请确认 Node.js 版本符合 ^22.19 || >=24，并使用 dsh --profile cli 启动。
Linux：Failed to load native module: pty.node
现象
启动时出现类似错误：
Failed to load native module: pty.node
Cannot find module './prebuilds/linux-x64/pty.node'
这类错误最外层常表现为插件树加载失败；真正的根因是 node-pty 找不到自己的原生二进制 pty.node。
原因
DSH 的本地子进程插件依赖 node-pty@1.1.0。在 Linux x64、Node 24 等没有匹配预构建二进制的环境中，它本应回退到 node-gyp 源码编译；但全局安装链路可能在编译失败后仍显示安装成功，留下缺失的 pty.node。这与 DeepSeek Harness 已报告的问题一致。上游讨论 #1219
Node v24.19.0 本身仍处于 DSH 当前声明的 Node 支持范围内，不必先为了此问题降级 Node。上游讨论 #649
解决
先安装构建环境。Ubuntu/Debian：
sudo apt update
sudo apt install -y build-essential python3 make g++
node-pty 官方将 Linux 编译前提列为 make、Python 与 build-essential；上面的命令显式安装了这些工具。node-pty 构建说明
然后进入当前全局 DSH 安装所使用的 node-pty，手动重新构建：
cd "$(npm root -g)/@deepseek-ai/dsh/node_modules/node-pty"
npx node-gyp rebuild
成功时输出末尾应出现 gyp info ok。确认构建产物已生成：
ls -lh build/Release/pty.node
最后重新启动 DSH：
dsh --profile cli --help
也可以使用 dsh web 验证 Web UI。只要 build/Release/pty.node 存在且命令可启动，即表示原生模块已可加载。
若最初的安装日志明确提示安装脚本被拦截，请先按 npm 输出的 --allow-scripts 提示重新安装 DSH，再执行上面的手动构建。授权脚本是允许自动构建的前提，但在此故障中不能替代手动 node-gyp rebuild。
如果 npx node-gyp rebuild 仍失败，请保留从 gyp info using node-gyp 到最后一条 gyp ERR! 的完整输出；其中的 Python not found、make not found、g++ not found 或 Node 头文件下载失败，分别对应不同的环境修复路径。
GitHub 源码安装：pnpm 要求 allowBuilds
现象
执行：
dsh plugin --profile cli add github:unlinearity/dsh-code
pnpm 报告 Git 依赖的 prepare 脚本未获许可，或要求在 pnpm-workspace.yaml 中配置 allowBuilds。
原因
GitHub 安装使用仓库源码，不包含发布包中的 lib/ 构建产物。DSH-Code 会在 Git 包的 prepare 阶段构建它；pnpm 需要对此构建步骤显式授权。
解决
将 pnpm 输出的 完整 allowBuilds 条目复制到 profile 的配置文件，然后重新执行同一条安装命令：
~/.dsh/profiles/cli/pnpm-workspace.yaml
该键会包含 Git URL 和 commit，例如：
allowBuilds:
dsh-code@git+https://github.com/unlinearity/dsh-code.git#<commit>: true
不要将它简化成 dsh-code: true；pnpm 校验的是带来源与版本的完整键。Windows 上对应的文件位于 %USERPROFILE%\\.dsh\\profiles\\cli\\pnpm-workspace.yaml。
验证：
dsh --profile cli --dump-config
输出中应能看到 dsh-code/startup。
GitHub 安装出现 ERR_PNPM_ENOENT 或临时目录错误
现象
pnpm 在 dsh-code_tmp_* 目录中报 ENOENT，例如无法扫描 node_modules。
原因
这通常是 Git 包的准备阶段未完成：旧版本的源码包没有在安装时构建 lib/，或者 pnpm 因未授予 allowBuilds 而跳过了构建。
解决
- 先按上一节授予 pnpm 输出的完整
allowBuilds条目。 - 确认使用的是包含 Git 安装修复的 DSH-Code 提交。
- 重新执行 GitHub 安装命令。
若只是使用 DSH-Code，而非参与源码开发，推荐改用 npm 发布包：
dsh plugin --profile cli add dsh-code
发布包已包含运行所需的构建产物，不需要 Git 包的准备阶段。
找不到 pnpm
现象
DSH 启动时显示：
dsh: pnpm not found on PATH — install pnpm to manage profile plugins
解决
npm install -g pnpm
pnpm --version
重新打开终端后再执行 DSH。若 pnpm --version 仍不可用，请检查 npm 的全局 bin 目录是否已加入 PATH。
插件安装后仍无法启动
先检查 profile 是否已加载 DSH-Code：
dsh --profile cli --dump-config
再检查基础 CLI 和插件版本：
dsh --version
pnpm --version
如仍无法定位，请附上完整的安装输出、dsh --profile cli --dump-config 输出，以及系统、架构和 Node.js 版本信息后提交 Issue。不要只截取最后一行错误；原生模块和 pnpm 问题通常需要前面的安装日志来判断原因。