DeepSeek Harness：修好 npx 失败与端口 3080

这不是另一篇快速开始

npx 快速开始 假定 npx @deepseek-ai/dsh web 最终会打出 URL。本文写给另一半首次流量：终端挂住、3080 永不响应，或 UI 起来了但每条聊天都死在 API 错误上。请与可检索清单 排错 并用——这里讲的是 检查顺序，免得三个变量同时乱拧。

精确 flag 仍归上游。README 与本页冲突时，以 README 为准。

阶梯 1 — 碰 DSH 之前先证明 Node

上游预览文档要求 Node.js ^22.19.0 或 >=24.0.0。在即将跑 npx 的 同一个 shell 里执行 node -v 与 npm -v。nvm/fnm 在另一窗口选的版本不算数。

引擎不对的症状：包开始拉，随后 engines 检查失败；或者根本没有 node。先修 PATH、重开终端，再重试。不要「在挂住的 npx 进程里升级 Node」。

阶梯 2 — 让 @deepseek-ai/dsh 拉得下来

首次运行会下载很大的依赖树。失败看起来像超时、404，或缓存到极旧的 rc。

1. 确认 scope：@deepseek-ai/dsh——拼错会浪费半天。
2. 公司镜像落后时，用 --registry=https://registry.npmjs.org 再试。
3. 只有排除网络和 scope 拼写之后，再清有毒的 npx 缓存。

终端请留着。下载中途杀进程，等于去调试半写完的缓存。

阶梯 3 — 端口 3080 是本机套接字问题

Web UI 常见绑定 http://127.0.0.1:3080/。若别的进程占着 3080，服务可能起来了，浏览器却永远看不到 DSH。

• 找出占用者（按系统用 netstat / lsof / 资源监视器）。
• 停掉它，或按上游文档的端口 flag 启动（社区常见在 dsh web 上用 --port）。
• 首测留在 localhost。绑定 0.0.0.0 是安全决策，不是便利技巧。

终端健康但页面空白：换干净浏览器配置——扩展有时会拦本地脚本。

阶梯 4 — UI 在、聊天死（密钥与凭证）

本地 UI 通常是 控制面，不是离线权重。走 DeepSeek 路由的调用需要平台 API 密钥。核对模型 id、配额，以及粘贴时多出来的空格。

无头/CLI 路径可能读 $DSH_HOME/.credentials.yaml（常见 ~/.dsh/.credentials.yaml）。Unix 上权限过开时，运行时会拒绝该文件——chmod 600 是常见修法。本独立站从不发放密钥。

阶梯 5 — 插件登场时缺 pnpm

即便你用 npx 启动，dsh plugin add 也常会调出 pnpm。全局缺 pnpm，表现成「UI 都好了，安装却失败」。装好 pnpm、保证 bin 在 PATH，再重试 add——见 插件指南。

不要做的事

• 排端口时，不要把第一个工作区指到整个用户主目录。
• 3080 还抖着，不要叠三个新社区插件。
• 不要把上周博客当 CLI 法律——评估时请钉住预览版版本号。

接下来去哪

1. 健康安装叙事：npx 快速开始。
2. 分系统一句话：安装。
3. 分症状清单：排错。
4. 跑起来之后，先选 运行模式，再去淹在包海里。