排查 DSH 问题

关闭终端后重新打开，再运行 node --version 与 npm --version。如果仍然失败，先修复 Node.js 安装或 PATH。

Node 要求取决于 DSH 版本：历史源码快照声明 ^22.19.0 || >=24.0.0；v0.2.2-alpha.2 要求 >=24.9.0。先核对所用包的要求，再与 node --version 比较。

第一次启动时 npx 可能正在下载 DSH。没有明确错误时先保持窗口打开，等 Web UI 地址或真正的 npm/网络错误。不要连续启动多个副本，否则第二个进程可能制造端口冲突。

说明已有进程监听 3080，常见情况是之前的 DSH 没退出。Windows PowerShell 可运行 Get-NetTCPConnection -LocalPort 3080 -State Listen；macOS/Linux 可运行 lsof -nP -iTCP:3080 -sTCP:LISTEN。停止旧进程，或改用 npx @deepseek-ai/dsh web --port 13080。

启用了 Hyper-V、WSL2 或 Docker Desktop 的 Windows 可能把包含 3080 的 TCP 范围保留给系统。运行 netsh interface ipv4 show excludedportrange protocol=tcp；如果 3080 落在排除范围里，直接选范围外的端口，例如 --port 13080。这和 EADDRINUSE 不一样，可能根本没有进程可杀。

先看终端最后几行。npm/下载错误按安装或网络问题处理；DSH 自己的配置或插件树错误则解决那条具体错误后再重启。

本机启动通常会在完整 Loader 就绪后交给默认浏览器打开。始终可以手动打开终端打印的 URL。通过 SSH 启动时不自动打开浏览器是预期行为；DSH 会打印主机 URL，由 SSH 客户端或编辑器负责转发。需要主动禁用自动打开可使用 --no-open。

打开 Settings → Models，给当前会话使用的服务商重新保存凭证。内置 DeepSeek Key 存在 $DSH_HOME/.credentials.yaml；保存后界面只会收到脱敏描述，不会回显原始密钥。

选择当前真实存在于已配置服务商下的模型，或为自定义服务商补上模型。不要照搬旧截图里的模型名。

说明请求已经带着凭证到达服务商但被拒绝。确认粘贴的是有效 Key。自定义服务商执行模型发现时也可能在 OpenAI-compatible GET /models 上返回 401。

apiKeyEnv 写的是“环境变量名称”，不是把密钥直接写进去。DSH 在进程启动时继承环境；如果 DSH 已经运行之后才新增或修改变量，需要从包含该变量的 Shell 重启 DSH。

选择当前可用的服务商与模型。如果保存的默认模型来自一个已经删除的服务商，也会出现这个状态。已经发过请求的 Session 会保留它自己日志里记录的模型；修改默认值主要影响新 Session。

手工添加的自定义模型默认按纯文本处理，除非配置明确声明图片输入。DeepSeek 官方 chat-completions 路由本身是纯文本路由，不能靠改这个字段变成视觉模型。

确认 DSH 终端进程仍在，并使用它实际打印的地址。如果启动已经报 EADDRINUSE 或 EACCES，先解决端口错误，不要只刷新浏览器。

新 Web UI 有三个独立就绪条件：保存服务商凭证、选择工作区、选择模型。启动 DSH 时所在的目录只是初始文件系统位置，并不会自动成为已选工作区；仍然要点击 Choose workspace 明确选中。

不要把这个参数直接套到当前官方 CLI。当前 CLI behavior reference 明确说明 Web alias 暂不支持 --host 0.0.0.0。远程使用优先采用 SSH/编辑器端口转发，或你当前版本明确支持的部署方式。

在 DSH 外部直接打开当前已选工作区核验文件，并确认请求路径确实位于这个工作区。

首次测试使用普通用户拥有的文件夹，不要选择受保护系统目录或需要管理员权限的位置。

官方 dsh plugin 会把包管理操作转给 pnpm，因此 CLI 管理插件时 pnpm 必须在 PATH 上。它和“只用 npm 快速启动 Web UI”是两回事：普通 Web UI 快速启动本身不要求先装 pnpm。

Git-hosted 源码插件可能在安装时通过 prepare 执行构建。pnpm 10+ 会先拦住并要求在目标 Profile 的 pnpm-workspace.yaml 明确批准。把它理解为“允许第三方代码在安装阶段执行”，先审源码，不要为了消除报错直接批准。

新增、移除或更新 Bundle 会修改磁盘上的 Profile，但已经运行的 Profile 继续使用本次启动时的 Bundle 集合。修改 Bundle 后需要重启对应 Profile 或 DSH Desktop。

修复版本为 v0.2.1-alpha.5（预发布版）。启停插件后，重新打开当前会话的 / 菜单，检查技能列表是否更新。若问题仍在，记录 DSH 版本、插件名称和复现步骤。查看该版本更新说明 →

不同 Profile 有独立依赖与 Bundle 组合。CLI 操作时明确目标 Profile；装到一个 Profile 的插件不会偷偷复制到另一个。

修复版本为 v0.2.1-alpha.5（预发布版）。这版还减少了新建或恢复多个终端时的重复查询。

升级后切换面板，检查是否仍出现重复重试。若问题仍在，记录 DSH 版本、终端错误和面板切换步骤。查看该版本更新说明 →

一位 Windows 用户报告从 0.2.1-rc.5 更新至 0.2.2-rc.1 后，DSH_HOME 中的工作区记录、会话和插件状态消失，项目文件仍在。报告中提到的原因是用户推测，尚未获上游确认。更新前备份实际 DSH_HOME；如果已经丢失，先停止向原目录写入，检查已有备份并保留日志。 #12290

另一位 Windows 用户报告，升级至 0.2.2-rc.1 后打开旧会话会使其从侧栏消失，输入框不可用；该报告称会话日志仍完整。它与上方数据丢失报告是不同现象，不能据此认定同一原因。先备份会话数据、记录版本及错误，关注上游调查；不要删除会话文件。 #12277

两位用户报告从 0.2.1-rc.2 更新到 rc.3 时，自定义安装目录内的工作区或 DSH_HOME 被删除。原因和影响范围尚未获维护者确认。更新前将工作区及数据目录放在安装目录之外，并将数据备份到独立位置；已经丢失时先停止向原位置写入，并检查已有备份。 #10851 · #10975

Windows 和 macOS 用户报告 rc.2 或 rc.3 重复启动后认证 Cookie 累积，可能导致启动失败或 HTTP 431。这是用户调查，尚未确认是所有同类错误的原因。先记录版本、系统和错误日志，备份数据并关注上游讨论；报告中的清理 Cookie 做法不是官方确认的修复。 #11366 · #11397

一位用户报告 rc.3 启动后界面冻结；原因和解决方案尚待上游确认。记录版本、系统和现象，保存诊断信息并关注讨论；不要禁用核心界面组件作为修复。 #11283

检查报错中的请求地址。插件的 baseURL 默认为 https://api.deepseek.com/v1/tools，网关需要转发 /v1/tools/search 和 /v1/tools/fetch。若部署使用 /api/v1/tools 等前缀，填入包含该前缀的完整基础地址。

补齐网关路由，或改用支持这两个端点的 API 地址。也可在网页搜索设置中关闭新版 API 并保存，恢复 Messages 搜索与本地 HTTP 抓取。

凭据缺失时，检查此插件的 apiKeyEnv 引用，默认名称为 DEEPSEEK_API_KEY。API Key 通过 Authorization: Bearer 发送。DeepSeek 账号会话若收到 401，按错误中的指引重新登录。

传输失败、HTTP 错误或响应格式错误会使用此错误码。结合请求地址和 HTTP 状态排查。Fetch API 返回的失败状态表示抓取服务失败，不能据此判断目标网页的 HTTP 状态。