DSH 安装教程（Windows、macOS、Linux）：DeepSeek Harness 各平台安装方式与首次启动

DeepSeek Harness 的安装方式在所有平台上只有三条：npx 免安装直跑、npm 全局安装、源码构建；真正的差异不在命令，而在各平台的路径、权限与运行环境。 这篇按「共同前置 → 路径怎么选 → 平台差异 → 首次启动判断」讲完，Windows、macOS、Linux 三端各自的坑都指到对应排查文。

DeepSeek Harness 三平台共同前置：Node.js、终端与网络

三个平台的前置条件完全一致：装好 Node.js、能在终端里执行命令、网络能访问 npm registry 与 GitHub（来源）。 四步确认：

1. 确认 Node.js 可用 — 终端执行 node -v 与 npm -v。预期：两条都输出版本号；报「不是内部或外部命令」或 command not found 说明没装或没进 PATH，见《安装报错：pnpm 与 node 不在 PATH》。
2. 确认包管理器 — 源码构建路径要用 pnpm，执行 pnpm -v；没有就先用 Corepack 开启。预期：pnpm -v 输出版本号。
3. 确认网络可达 — 免安装路径要能访问 npm registry，源码路径还要能 git clone GitHub。预期：npx 首次运行不会长时间卡在下载，镜像问题见《下载慢》。
4. Windows 额外一项：换个终端与路径习惯 — 用 PowerShell 而不是旧版 cmd，并让安装目录、数据目录都避开中文与空格。预期：路径里没有中文，后面几类截断类报错就不会出现。

DeepSeek Harness 三条安装路径怎么选：npx、npm 全局与源码构建

官方 README 给出两条现成路径——免安装的 npx @deepseek-ai/dsh web 与源码构建，第三条是把同一个包装到全局省去 npx 每次解析（来源）。 按目的选：

源码构建四步：

1. 克隆仓库 — git clone https://github.com/deepseek-ai/deepseek-harness.git。预期：得到 deepseek-harness 目录。
2. 进目录装依赖 — cd deepseek-harness 后执行 pnpm install。预期：依赖装完且没有 ERR_PNPM_* 一类报错。
3. 先构建再运行 — pnpm run build 准备仓库产物，然后 pnpm dsh web 启起来。预期：pnpm dsh web 直接使用已构建产物、不会重新构建，改代码后要重新 build 才生效。
4. 起不来的话先看报错词 — node/pnpm 找不到走环境排查，端口相关走端口排查。预期：报错词与对应文章能对上，不用猜。

想先看三条路径的完整取舍与卸载方式，读《dsh 三种安装方式全对比》。

DeepSeek Harness 各平台差异清单：Windows、macOS 与 Linux

命令在三个平台上是同一套，差异集中在路径与权限：Windows 是 PATH 与中文路径，macOS 是 launchd 与磁盘格式，Linux 是全局安装的写权限与受限环境。 逐个平台对照：

1. Windows — PATH 与「不是内部或外部命令」 — npm 全局前缀目录没进 PATH 时，装完也敲不出 dsh。预期：把该目录加进用户 PATH 并重开终端后命令可用，完整步骤见《dsh 命令找不到》。
2. Windows — 中文路径、沙箱与运行库 — 中文路径会被截断，沙箱会让 HTTPS 握手报错，原生模块（如 sharp）可能加载失败。预期：按报错词分流到《Windows 平台报错》。
3. macOS — launchd 不继承 PATH — 开机自启跑在 launchd 环境里，找不到终端里的 node，表现为反复崩溃重启。预期：在 plist 里写全 PATH 后恢复正常，见《macOS 平台报错》。
4. macOS — 别装在外置卷上 — exFAT 等格式缺少 inode 归属检查，把安装目录或数据目录放在上面会失败。预期：换到 APFS 本地卷即可。
5. Linux — 先解决全局安装权限 — 系统级 Node 下 npm install -g 要写系统目录，容易报 EACCES；标准做法是改用 nvm 或把 npm prefix 指到用户目录，而不是一路 sudo。预期：npm config get prefix 指向用户目录，装包不再要提权。
6. Linux — 受限环境可能缺工具链 — 容器或最小化镜像里可能没有编译原生模块所需的工具链，构建阶段会先失败。预期：补齐构建依赖或改用免安装的 npx 路径绕过构建。

DeepSeek Harness 首次启动成功怎么判断：端口、页面与插件市场

判断标准只有一条：终端打印出 http://127.0.0.1:3080，浏览器打开它能看到 Web UI（来源）。 三步确认，再顺手做第一件事：

1. 看终端输出 — 本机启动会打印 http://127.0.0.1:3080 并自动打开默认浏览器。预期：页面正常渲染即为成功；不想自动打开浏览器就加 --no-open，只跑服务器。
2. 通过 SSH 启动时换个判断方式 — 此时只打印宿主机 URL，不打开浏览器。预期：这是预期行为，不是失败；本地转发地址由 SSH 客户端或编辑器持有。
3. 打不开就分流排查 — 先确认服务还在前台运行，再看端口占用。预期：连接被拒（ECONNREFUSED）说明服务没起来，见《3080 打不开》。
4. 起起来之后第一件事：打开插件市场 — 顶部导航进入插件市场，按分类与 Star 浏览社区插件。预期：能看到插件卡片列表，说明本体与目录接口都通了。

插件市场是 DeepSeek Harness 内置的官方插件收录平台，把搜索、分类、版本与更新收在一页里，装插件不必回到命令行。用法与筛选技巧见《用插件市场装插件》。

DeepSeek Harness 按平台安装的注意事项与局限

1. 命令统一、环境不统一：三条安装路径在任何平台都成立，出问题基本都是环境层——PATH、权限、磁盘格式、原生模块，先按平台分类再看具体报错词。
2. 别用 sudo 绕权限：Linux/macOS 上 sudo npm install -g 会把全局目录的属主改乱，后面更难收拾；正确做法是改 prefix 或换 nvm。
3. 外置卷与网络盘不是安装位置：macOS 的 exFAT 已确认会失败，其他平台的同步盘、网络盘同样不建议承载安装目录与数据目录。
4. 源码路径要重新 build：pnpm dsh web 用的是已构建产物，改了源码不跑 pnpm run build 看不到效果。
5. 数据目录三平台一致：无论走哪条路径，用户级数据默认都在 ~/.dsh，路径规则见《dsh 配置文件在哪》。

装好本体后的下一步是把插件补齐。DSH Plugin Hub 既是插件市场也是插件管理界面，已安装列表、更新检测、日志与诊断都收在里面。

来源：DeepSeek Harness README（官方仓库）、用户指南（官方文档）、dsh CLI README（官方仓库）、dshplugin/dsh-plugin-hub