修复常见 dsh 报错

安装与环境

ERR_PNPM_FETCH_404 — 包找不到

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

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

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

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

npm install -g pnpm

node: command not found

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

3080 端口被占用

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

dsh web --port 8080

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

凭证与模型

MISSING_CREDENTIAL

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

DEEPSEEK_API_KEY: sk-你的key

UNKNOWN_MODEL

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

「获取可用模型」返回 401

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

插件（实测验证）

插件装了但不激活

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

插件加载时 ERR_REQUIRE_ESM

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

cannot get property "systemPrompt" without inject

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

git 插件提示 allowBuilds

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

依赖「@deepseek-ai/dsh-type-meta」找不到

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

运行时

Web UI 发送按钮一直灰

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

技能在 CLI 能用、Web UI 不能用

web profile 默认禁用了 tool-skill 和 skill-filesystem；headless/CLI profile 是开的。同一个技能一个能用、另一个静默无效。

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