DeepSeek Harness 个人电脑部署完整教程
一、先搞清楚：dsh 是什么，不是什么
DeepSeek Harness（命令名 dsh）是 DeepSeek AI 开源的 AI Agent 运行时框架，采用“一切皆插件”的架构，由 Cordis 微内核驱动。它本身不是大语言模型，也不是聊天网页，而是一套用于组装、运行、调试智能体的底层基础设施——模型负责推理思考，Harness 负责环境交互、工具管理、安全沙箱、会话持久化和任务调度。
当前版本为开发者预览版，官方明确声明会有破坏性变更。npm latest 通道约为 0.1.x，alpha 通道更新更快。
部署前必须确认的前置条件：Node.js 版本必须满足 ^22.19.0 || >=24.0.0，这是仓库 package.json 中 engines 字段的硬性要求。在终端执行 node -v 验证，如果不符合，用 nvm 或 fnm 安装：nvm install 24 && nvm use 24。
二、部署方法总览与选择建议
个人电脑上部署 dsh 有三种主流方法，它们最终运行的是同一个 Web UI（默认 http://127.0.0.1:3080），区别在于安装方式、维护成本和适用场景。
方法 核心命令 适合场景 需要 Node.js 需要克隆源码
方法一：npx 临时运行 npx @deepseek-ai/dsh web 首次试用、临时测试 是 否
方法二：npm 全局安装 npm install -g @deepseek-ai/dsh 长期使用、命令行简洁 是 否
方法三：源码构建 git clone → pnpm install → pnpm run build → pnpm dsh web 需要修改源码、开发插件 是 是
选择建议：如果你只是想让 dsh 跑起来、体验一下 Agent 工作流，选方法一；如果你确定要长期使用，选方法二；如果你需要开发插件或修改框架行为，选方法三。此外，如果有多台设备需要通过局域网共享使用，可以考虑 Docker 方案（见第七节）。
三、方法一：npx 临时运行（最快上手）
这是最简单的启动方式，不需要全局安装任何东西。打开终端（Windows 用 PowerShell 或 CMD，macOS/Linux 用 Terminal），直接执行：
```bash
npx @deepseek-ai/dsh web
```
这条命令会自动下载 Harness 并启动 Web UI。启动后终端会输出类似 dsh web: http://127.0.0.1:3080/?token=xxxxxxxx 的地址，浏览器打开即可。本机启动时通常会自动打开默认浏览器，如果不希望自动打开，加 --no-open 参数。
npx 方式的特点：每次运行都会检查并缓存最新版本，但不会把 dsh 命令安装到系统 PATH 中。这意味着关掉终端后，下次使用还需要重新输入完整的 npx @deepseek-ai/dsh web。
常用参数：
```bash
npx @deepseek-ai/dsh web --no-open # 不自动打开浏览器
npx @deepseek-ai/dsh web --port 8080 # 使用 8080 端口（3080 被占用时）
npx @deepseek-ai/dsh@alpha web # 使用 alpha 通道（更新更快）
```
注意：--host 0.0.0.0 被 CLI 明确禁止，传入会以 usage error 退出。这是官方的安全设计，默认只绑定本机回环地址。
四、方法二：npm 全局安装（推荐长期使用）
如果你打算长期使用 dsh，全局安装是更干净的方式。安装后 dsh 命令会加入系统 PATH，之后直接敲 dsh web 即可启动，不用每次都带 npx 前缀。
安装命令：
```bash
npm install -g @deepseek-ai/dsh
```
如需指定版本，把包名改为 @deepseek-ai/dsh@版本号 即可。安装完成后，先单独验证命令是否可用：
```bash
dsh --version
```
如果看到版本号，说明安装成功；如果提示“命令未找到”，说明 PATH 没配好。在 Windows 上，常见原因是没有把 npm 全局目录加入 PATH。解决方法：找到 npm 全局目录（通常是 %APPDATA%\npm），将其加入用户变量 Path 中。
Windows 用户的实操注意：有实测记录显示，部分 Windows 环境下 npx @deepseek-ai/dsh web 可能安装失败，而 npm install -g @deepseek-ai/dsh 能够成功。如果你的 npx 方式反复报错，直接切换到全局安装。
启动：
```bash
dsh web
```
升级：npm i -g @deepseek-ai/dsh@latest（或 @alpha）。由于当前是开发者预览版，官方建议在生产环境使用时锁定版本号，不要轻易升级。
五、方法三：从源码构建（适合开发插件或修改框架）
如果你需要开发自定义插件、修改框架行为，或者想基于源码进行调试，需要从仓库构建。
前置要求：除了 Node.js，还需要 pnpm（官方锁定的版本为 pnpm@11.7.0）。如果没有安装 pnpm：
```bash
npm install -g pnpm
```
完整构建流程：
```bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
```
pnpm run build 会准备仓库构建产物，pnpm dsh web 使用这些已构建的产物启动 Web UI，不会重新构建。
一个重要的对比：有实践者明确指出，“本地装比容器装省心得多”。容器化部署时踩过的三个坑——pnpm 符号链接布局导致插件解析失败、Alpine/musl 环境加载不了 node-pty 的 glibc 预编译产物、profile patch 被卷挂载遮住——在本地直接 npm 安装时全都不存在，macOS 上拿到的也是 darwin-arm64 预编译包。因此，个人电脑部署优先推荐方法一或方法二，源码构建仅在确有开发需求时使用。
六、启动后的必做配置
6.1 配置 API Key
dsh 本身只是一个“壳”，真正干活的是背后的模型。首次打开 Web UI 后，需要配置 API Key。点击左下角 Settings → Models，添加提供方、粘贴 API Key、选择模型，保存即可。
以 DeepSeek 官方 API 为例：前往 platform.deepseek.com 的 API 开放平台，新建 API Key。如果使用其他兼容 OpenAI 协议的模型服务（如 SiliconFlow、阿里云百炼等），在 Models 配置中选择自定义 OpenAI 兼容端点，填入对应的 Base URL 和 Key。
6.2 创建工作区
工作区是文件边界，不是聊天分类。必须主动添加并选中一个工作区目录，Agent 才能读写文件。如果发现输入框是灰色的、无法发送消息，第一件事就是检查工作区是否已选中。
建议新建一个独立的测试目录（如 dsh-first-agent），在里面运行启动命令，然后在 Web UI 中将该目录添加为工作区。
6.3 选择预设模式
dsh 内置四种预设模式，第一次使用推荐“标准模式 + 只读权限 + 计划模式”的组合。
预设 特点 适用场景
标准模式 完整编码 Agent：文件编辑、Shell、检索、计划、子 Agent 日常任务首选
PTC 模式 标准能力 + TypeScript 编排多步工具调用 步骤多、工具调用密集
极简模式 仅 Bash + str_replace_editor 基准测试、教学
创造模式 运行时检查、插件实验、预设创作 插件开发；风险较高
权限设置：Read Only / Workspace Write / Full Access。Full Access 不是“高级版”，而是风险最高的选项。第一次使用请选择 Read Only 或 Workspace Write。
七、验证部署是否成功
启动后，依次完成以下检查，确认 dsh 正常工作：
第一步：Web UI 可访问。 浏览器打开 http://127.0.0.1:3080，能看到界面即成功。如果端口被占用，用 --port 8080 换端口，或用 --port 0 让系统自动分配空闲端口。
第二步：模型配置生效。 在 Settings → Models 中确认 API Key 已保存且模型可选。选择一个模型后，输入框应该变为可用状态。
第三步：发送一个简单任务。 在工作区选中后，输入一个简单任务（如“列出当前工作区目录下的文件”）。观察 Agent 是否能调用工具、返回结果。如果对话一直“转圈”无法发送，检查工作区是否选中，以及是否使用了 localhost 而非局域网 IP 访问。
八、多方法对比与常见问题
8.1 方法对比总结
维度 npx 临时 npm 全局 源码构建
安装耗时 首次约 1-2 分钟 1-2 分钟 3-5 分钟（含 build）
磁盘占用 缓存在 npm cache 全局 node_modules 完整仓库 + 构建产物
升级方式 自动跟随 latest 手动 npm i -g @latest git pull + 重新 build
命令简洁度 需输入长命令 仅 dsh web pnpm dsh web
适用场景 试用、临时 日常长期使用 插件开发、框架修改
8.2 常见问题
问题：dsh 命令找不到（Windows）。 原因通常是 npm 全局目录未加入 PATH。解决方法是找到 %APPDATA%\npm 目录，将其加入系统环境变量的用户 Path 中。安装完成后需要重新打开终端才能生效。
问题：npx 安装失败但 npm 全局安装成功。 这在 Windows 上是已记录的实测现象。如果 npx 反复报错，直接使用 npm install -g @deepseek-ai/dsh。
问题：3080 端口被占用。 用 dsh web --port 8080 指定其他端口，或 --port 0 让系统自动挑选。
问题：浏览器打开后对话一直转圈。 如果你是通过局域网 IP 访问，浏览器不会把局域网地址视为安全页面，导致 crypto.randomUUID 不可用，消息无法发送。dsh 默认只监听 127.0.0.1，本机使用 localhost 访问即可。如果确实需要局域网访问，需使用 Docker 方案（社区镜像 smanx/deepseek-harness 通过反向代理解决了这个问题）。
问题：版本更新导致配置失效。 当前为开发者预览版，破坏性变更频繁。如果升级后出现异常，回退到上一个可用版本：npm i -g @deepseek-ai/dsh@指定版本号。长期使用建议锁定版本，不要盲目跟随 latest。
九、Docker 方案（附加，供局域网共享使用）
如果你需要让同一局域网内的多台设备访问 dsh，或者希望把 Agent 的会话和文件操作隔离在容器中，可以考虑社区 Docker 方案。
社区镜像 smanx/deepseek-harness 将 dsh 装入 Node 24 容器，并加了一层反向代理：容器内 dsh 仍监听 127.0.0.1:3079，代理监听 0.0.0.0:3080。用局域网 IP 打开时，代理补上 crypto.randomUUID，设置和选目录功能也能正常使用。
环境要求：Linux（建议 Ubuntu 24.04），Docker Engine + Compose V2，支持 linux/amd64 和 linux/arm64 架构。
基本流程：创建 docker-compose.yml，映射宿主机 3080 到容器代理 3080，使用命名卷 dsh-data 持久化 /root/.dsh 目录。启动后通过局域网 IP 访问，默认无网页密码，设置两个环境变量后启用 Basic Auth。
Docker 方案的优势是隔离性好、支持局域网共享；代价是需要额外的 Docker 环境和配置工作。个人单机使用，优先推荐方法一或方法二。
总结：对于个人电脑部署 dsh，最务实的路径是：先确认 Node.js 版本 ≥ 22.19，然后用 npm install -g @deepseek-ai/dsh 全局安装，执行 dsh web 启动，在 Web UI 中配置 API Key 和工作区。整个过程通常不超过 10 分钟。只有在需要开发插件或修改框架时，才需要进入源码构建流程。