修复常见 dsh 报错

安装与环境

ERR_PNPM_FETCH_404 包找不到

你的 npm 镜像落后于官方，刚发布的包返回 404。

dsh plugin add <包名> --registry=https://registry.npmjs.org

'pnpm' 不是内部或外部命令 pnpm 缺失

dsh plugin 会调用 pnpm，但本机没装。

npm install -g pnpm

node: command not found Node.js 不在 PATH 里

dsh 启动器需要 Node.js 在 PATH 里。把 Node 目录（和 npm 全局 bin）加进 PATH，用 npm prefix -g 查路径。

npx @deepseek-ai/dsh 安装失败

通常是镜像滞后，或某个原生依赖没有预编译二进制。在 Linux 上 node-pty 不提供预编译，需要编译器工具链从源码构建。

npx @deepseek-ai/dsh --registry=https://registry.npmjs.org

先装构建工具（Debian/Ubuntu 用 build-essential python3），并改用 Node LTS，再重试。

3080 端口被占用 旧进程占着端口

旧 dsh 进程占着端口——页面甚至能正常加载，但连的是旧实例，配置改动永远不生效。

dsh web --port 8080

先杀掉旧进程，或用新端口。

凭证与模型

MISSING_CREDENTIAL 没存 API key

没存 API key。在 设置 → 模型 填，或写进 ~/.dsh/.credentials.yaml：

DEEPSEEK_API_KEY: sk-你的key

UNKNOWN_MODEL 模型未配置

选了个没配置的模型。给提供方添加该模型，或选已配置的模型。

「获取可用模型」返回 401 key 或 base URL 不对

key 不对——模型发现会调用 OpenAI 兼容的 GET /models 端点。基础 URL、key、模型名三者必须匹配。

maximum context length is 1048576 tokens 超出上下文窗口

对话加上你请求的补全超出了模型的上下文窗口。

开新会话、缩短系统提示词，或调低 max_tokens。长会话建议先总结再新开，别硬顶窗口。

插件

插件装了但不激活 缺少 dsh.bundle 清单

包没有 dsh.bundle 清单，dsh plugin add 只当普通依赖装——永远不加载。插件必须带 cordis.patch.yml 并在 package.json 声明 dsh.bundle.patch。

ERR_REQUIRE_ESM 插件被编译成 CommonJS

插件被编译成 CommonJS，但依赖了 ESM-only 的包（如 @deepseek-ai/dsh-tools）。插件必须构建成 ESM（"type": "module"）。

cannot get property "systemPrompt" without inject 缺少 inject 声明

插件代码调了 ctx.systemPrompt 却没声明 inject: ["systemPrompt"]。这是插件 bug——把这条报错原样发给作者。

allowBuilds 提示 git 插件构建脚本被阻止

从 GitHub 装的插件带 prepare 构建脚本，pnpm 默认阻止。把 pnpm 提示的 key 加进 pnpm-workspace.yaml 的 allowBuilds，再重跑。

「@deepseek-ai/dsh-type-meta」找不到 依赖还没发布

插件依赖了还没发到 npm 的包。客户端无解——作者得先发布。

reading 'prepare' of undefined dsh-tools 重复实例

插件的 peer 依赖拉进了第二份 @deepseek-ai/dsh-tools，内部 symbol-key 查找冲突，工具调度崩溃。

让 @deepseek-ai/dsh-tools 只作为单一共享依赖（peer 或只 bundled 一次），或请作者修 peer 版本范围。

duplicate loader entry id bundle 依赖被重复提升

dsh plugin add 把一个已声明 bundle 的依赖又提升进 bundle 栈，产生重复 entry id。

从 profile 的 bundle 配置里删掉重复项，再重新添加插件。

Failed to load plugins 插件挂载致命屏

某个插件在启动时挂载失败，UI 不提供任何恢复操作。

把问题插件移出 profile（或重置 profile）再重启，然后逐个加回插件定位元凶。

运行时与 Web UI

Web UI 发送按钮一直灰 没选工作区

web profile 要先选工作区才能发送。点选择工作区并选中目录。

技能在 CLI 能用、Web UI 不能用 profile 能力不一致

web profile 默认禁用了 tool-skill 和 skill-filesystem；headless/CLI profile 是开的。

crypto.randomUUID is not a function 明文 HTTP 破坏 Web Crypto

Web Crypto API 只在安全上下文可用。用明文 http://（局域网 IP 或手机）访问 web UI 会触发此错。

改用 https:// 或 localhost，或在 web UI 前挂一个带 TLS 的反向代理。

Composer 输入框消失 markdown 图片引用损坏

删除草稿里的 markdown 图片引用可能导致输入框变空。

刷新页面。若反复出现，请带上复现步骤反馈。

/api/commands/list 返回 404 命令菜单为空

插件清单自动发现机制坏了，命令没注册上。

重装插件并重启 web UI；若仍存在请反馈。

技能菜单只按前缀匹配 中间词搜不到

技能搜索按名称前缀匹配，中间词搜不到。

从头开始输入技能名，或浏览完整技能列表。

远程访问时 设置 → 插件 一片空白 插件管理仅限本机

从另一台机器（局域网 IP 或隧道）打开 web UI 时，设置 → 插件面板静默空白——插件管理仅限本机，但没有任何提示告诉你这一点。

在 dsh 运行的那台机器上、通过 http://127.0.0.1:3080 管理插件。远程浏览器可以聊天，但插件的增删必须本机操作。

会话与缓存

恢复时会话日志损坏 追加日志出现序号断层

恢复时最后已提交的事件带新时间戳重新追加，在只追加日志里造成序号断层。

先导出数据，再开新会话，别继续恢复损坏的会话。

恢复后 KV 缓存命中率骤降 系统提示词顺序漂移

恢复时系统提示词各段顺序漂移，缓存命中率掉到接近零。

干净地新开会话而非恢复，并保持预设顺序稳定。

History "Failed to fetch (internal)" 会话增量损坏

带有畸形流式工具调用增量的会话无法加载。

刷新；若持续出现，说明会话文件已损坏——重新开。

平台相关

SEC_E_NO_CREDENTIALS Windows 沙箱破坏 HTTPS

受限令牌沙箱破坏了 Schannel HTTPS（curl、PowerShell）。OpenSSL 客户端（node、python）不受影响。

网络任务用完整访问预设，或改走 node/python 工具。

ERR_DLOPEN_FAILED Windows 上 sharp 加载失败

原生图像依赖在 dev/desktop 构建里加载失败。

采用相关讨论里的 workaround，或改用纯 JS 回退方案。

macOS launchd env: node PATH 缺失导致崩溃循环

LaunchAgent 启动时没有 PATH，找不到 node，dsh 陷入崩溃循环。

给 LaunchAgent 的 plist 加上 PATH 和 ThrottleInterval。

Windows 中文路径被截断 UTF-16 低字节被当成 NUL

UTF-16 低字节为 0x00 的字符（如「言」）被误判成 NUL 终止符，dsh 会把工作目录在该字符处截断，其下的文件/会话无法打开。

从避开这些字符的路径运行 dsh（纯 ASCII 路径，或目录名不含此类字）。这是上游 readUtf16 解码 bug——请带上你的完整路径反馈。

exFAT 卷上 pnpm install 失败 lefthook inode 归属检查

在 macOS 的 exFAT/USB 卷上，pnpm install 在 lefthook 安装步骤中止——exFAT 不保留 Unix inode/归属，钩子安装检查失败。

把项目挪到 APFS/HFS+（或其他带日志的）卷再重装。exFAT 用于跨设备传输，不适合跑 pnpm 工作区。

还没解决？看安装指南、插件指南或教程。