DeepSeek Harness 安装教程：桌面版、npm、源码与 Python SDK
本章节介绍 四种安装方式：桌面版、npm、源码安装与 Python SDK。 普通用户优先使用官网桌面版；希望通过浏览器访问本地 Web UI 的开发者可以选择 npm。
安装方式怎么选？
DeepSeek Harness 是面向文件处理、编程开发和自动化任务的 AI Agent 工具。
官网现已提供桌面安装包，普通用户无需先安装 Node.js 或打开终端。
| 安装方式 | 操作系统 | 是否需要 Node.js | 适用场景 |
|---|---|---|---|
| 官方桌面版 新手推荐 | Windows 64 位、macOS Apple 芯片 | 不需要单独安装 | 日常办公、文件处理、AI 编程 |
| npm 安装 | Windows、macOS、Linux | 需要（24.9 或更高版本） | 命令行启动本地 Web UI |
| 源码安装 | 支持的开发环境 | 需要（24.9 或更高版本） | 研究源码、开发插件和调试 |
| Python SDK | Linux x64 / arm64、macOS 14+（Apple 芯片）、Windows x64 | 不需要单独安装（自带运行时） | 通过 Python 集成 Agent |
版本说明：官网目前将 Harness 标注为预览版，具体界面与安装包可能变化。桌面版与 npm/Web UI 是同一产品的不同使用入口，不应把第三方社区桌面封装与官网安装包混淆。
安装前准备
桌面版：macOS 需要 Apple 芯片（M 系列）及 macOS 13 或更新版本；Windows 提供 64 位版本。
-
npm / 源码：需要 Node.js 24.9 或更高版本（旧版 Node 22 已不再支持）；源码方式还要安装 Git 和 pnpm（仓库通过 Corepack 固定 pnpm 版本，可用
corepack enable启用）。 -
Python SDK：需要 Python 3.10+，运行时自带，无需系统 Node.js。
-
模型配置：使用需要模型推理的功能时，请准备适用的模型服务凭据；不要把 API Key 写入教程公开代码或提交到 Git 仓库。
方式一：安装官方桌面版（推荐）
对初次接触 DeepSeek Harness 的用户来说，桌面版最省事：下载安装包，安装完成后像普通软件一样打开即可。
官方页面：DeepSeek Harness 官网与下载入口。
直接下载：macOS（Apple 芯片，DMG） | Windows（64 位，EXE）
下载链接来自官网当前入口，版本会更新；若直链失效，请回到官网重新下载。
| 平台 | 系统要求 | 安装包 | 安装方式 |
|---|---|---|---|
| macOS | Apple 芯片，macOS 13+ | .dmg | 打开 DMG，将应用拖入"应用程序"文件夹 |
| Windows | 64 位 Windows | .exe | 双击官方安装程序，根据向导完成安装 |
| Linux | 官网当前未列出独立桌面安装包 | — | 建议使用 npm / 源码方式；谨慎辨别社区桌面版 |
macOS 桌面版安装
进入 Harness 官网，选择 macOS（Apple 芯片），等待 DMG 文件下载完成。
双击打开 DMG，将 DeepSeek Harness 拖到应用程序文件夹，再从"启动台"或"应用程序"目录启动。
如果系统提示无法打开，应先核实安装包来源和开发者签名，再查看"系统设置 → 隐私与安全性"的相关提示。不要为了安装而直接关闭系统的全局安全防护。
Intel 芯片 Mac 当前不在官网明确提供的桌面下载范围内。请不要误下载 Apple 芯片版，建议使用 npm/Web UI 方式。
Windows 桌面版安装
进入 Harness 官网，选择 Windows（64 位），下载 EXE 安装程序。
双击运行安装包，按照安装向导完成安装，然后从开始菜单启动 DeepSeek Harness。
如果 Windows 出现安全提示，请先确认文件来自 download.deepseek.com 官方下载地址，并查看文件签名及系统提示；不要对来源不明的安装包直接选择忽略警告。
首次打开桌面版
进入应用后，先检查模型配置，然后选择一个专门用于测试的工作区，再创建第一条会话。
| 步骤 | 操作 | 说明 |
|---|---|---|
| 配置模型 | 打开模型设置，按界面提示配置服务商和凭据 | 需要有效的模型访问方式；不同版本的首次配置界面可能有所不同 |
| 选择工作区 | 选择一个测试项目文件夹 | Agent 可操作被授权访问的工作区文件，首次建议使用测试目录 |
| 创建会话 | 输入下面的示例任务 | 先执行只读任务，检查能否读取项目 |
请分析当前工作区的目录结构，列出主要文件及作用。 仅允许读取，不要修改、删除文件或运行安装命令。
待确认模型能正常响应、能够看到工作区文件后，再尝试生成文档、整理表格或修改代码等任务。
桌面版支持后台执行任务以及本地文件读写能力，但具体能力、审批行为和插件支持取决于当前版本与所安装的插件。
安全提醒：不要把网站生产目录、服务器密钥、包含隐私资料的文件夹作为第一次测试的工作区。文件编辑、命令执行和自动化操作可能改变本地数据。
方式二：npm 安装并启动 Web UI
我们可以使用 npm 命令来全局安装：
npm install -g @deepseek-ai/dsh
使用该方式安装后期方便使用 dsh 命令，安装完成后，输入以下命令即可启动：
dsh web
也可以使用 npx 命令安装快速体验，在终端执行：
npx @deepseek-ai/dsh web
命令会启动 Web UI，首次运行会自动初始化 web 配置模板，然后打印访问地址——默认是 http://127.0.0.1:3080。
验证是否成功：
1. 在浏览器打开终端打印的地址（默认 http://127.0.0.1:3080）；
2. 看到 DeepSeek Harness 的 Web 界面即安装成功；
3. 注意：新 Web UI 在添加工作区之前不会选中任何工作区——这是正常现象，下一步会配置。
小贴士：dsh 会把调用目录作为默认文件系统位置。建议先 cd 到你的项目目录，再执行 npx @deepseek-ai/dsh web，这样后续选择工作区时最方便。
方式三：从源码安装
适合开发插件、阅读源码或参与贡献，克隆仓库后按顺序执行：
git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install # 安装依赖（需要 pnpm，可用 corepack enable 启用仓库固定的 pnpm 版本） pnpm run build # 构建包与前端产物（生产运行需要） pnpm dsh web # 以源码方式启动 Web UI
从源码运行时的其他入口：
pnpm dsh --profile headless "run the tests" —— 一次性运行一个任务并打印最终答案；
pnpm dsh --profile web --dump-config —— 查看实际启动的完整配置树（开发插件时很有用）。
源码开发要求 Node.js 24.9+、Corepack 启用的 pnpm（仓库固定为 11.28.5）与 Git 2.26+。构建产物会嵌入版本号与七位源码 commit，便于对账。
方式四：Python SDK 安装
前置要求：Python 3.10+、Git、DeepSeek 兼容的 API 端点与凭据、一个 agent 可以修改的隔离 workspace。支持 Linux x64 / arm64、macOS 14+（Apple 芯片）与 Windows x64。创建虚拟环境并安装：
git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness python -m venv .venv . .venv/bin/activate python -m pip install deepseek-harness-sdk
设置凭据后即可在程序中调用（SDK 自带运行时，不需要系统提供 Node.js）：
export DEEPSEEK_API_KEY=sk-your-key-here # 如果模型不是默认 DeepSeek 端点，而是 OpenAI 兼容代理，还需要： # export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
在自己的 Python 程序中使用：
from deepseek_harness import DeepSeekHarness —— 仓库内置的 python/sdk/examples/minimal.py 是 SDK 调用的轻量包装，可直接参考；运行后会打印 assistant 的最终回复，指定的 dsh home 下会收到包含模型请求与工具调用的 JSONL 会话日志。
首次配置与第一个任务
对 npm 或源码方式启动的 Web UI，首次使用可以按照下面三步操作。桌面版则直接在应用窗口中进行类似的配置：
| 步骤 | 操作 | 说明 |
|---|---|---|
| 1配置模型 | 设置 → 模型 | 输入 DeepSeek API 密钥并保存。模型路由立即可用，无需重启服务器；也支持其他提供方与自定义 OpenAI 兼容端点 |
| 2选择工作区 | 点击「选择工作区」 | 添加启动 dsh 时所在的项目目录并选中。选中工作区前，会话输入框不可用 |
| 3运行任务 | 在会话中输入指令 | 例如 Summarize this repository and identify its main packages.——agent 会读写工作区文件、运行命令、委派子代理并维护计划；超出权限策略的操作会先征求你的审批 |
第一个任务建议从轻量指令开始："Summarize this repository and identify its main packages."
先让 agent 熟悉工作区，再逐步交付真实任务。—— 官方快速入门指南建议
桌面版与 Web UI 有什么区别？
两者面向的使用方式不同，核心 Agent 能力可能接近，但操作入口和环境依赖不同。
| 对比项 | 官方桌面版 | npm / Web UI |
|---|---|---|
| 打开方式 | 本地应用窗口 | 通过命令启动后使用浏览器 |
| Node.js | 无需单独安装 | 需要安装（24.9+） |
| 使用门槛 | 适合普通用户 | 适合开发者及自定义部署 |
| 后台执行 | 官网强调支持后台任务 | 依赖 Web 服务进程及部署配置 |
| 插件与开发 | 提供插件入口 | 更容易查看终端日志和项目源码 |
常用命令速查
| 命令 | 作用 |
|---|---|
npx @deepseek-ai/dsh web |
启动 Web UI（等价于 --profile web） |
dsh --profile headless "任务描述" |
一次性运行一个任务，打印最终答案后退出（适合脚本/CI） |
dsh plugin --profile <name> <pnpm 参数> |
管理某个 profile 的插件（转发给 pnpm 在 profile 目录执行） |
dsh --profile web --dump-config |
查看实际启动的完整配置树（不启动服务器） |
dsh --profile web --dump-default-config |
查看默认配置树（不含用户 patch） |
dsh --profile <name> --from-default-profile <模板> |
用随附模板重建一个自定义 profile（注意：会删除同名已有 profile 后重建） |
pip install deepseek-harness-sdk |
安装 Python SDK（自带运行时） |
关于 Profile：web 与 headless 两个 profile 会在首次使用时从内置模板自动初始化；其他随附模板包括 acp、sdk 和 sdk-minimal，以当前版本帮助为准；自定义 profile 可通过 --from-default-profile 从模板创建。dsh 的启动参数在前，应用参数在后，例如 dsh --profile web --port 8080 中 --port 属于 Web 应用。另外 dsh plugin 只在转发 pnpm 参数之前读取 --profile，正确写法是 dsh plugin --profile web add <包名>，把 --profile 放在 add 之后会报错。
常见问题与排错
桌面版下载后无法安装
确认平台与系统架构：Mac 桌面包仅面向 Apple 芯片、macOS 13+；Windows 使用 64 位版。优先从官方 Harness 页面重新下载安装包，避免第三方转载文件。
桌面版启动后无法运行任务
检查模型是否配置成功、是否已经选中工作区、网络是否可访问模型服务。初次测试建议只读任务，避免同时排查模型错误与文件权限问题。
问题 1：浏览器打不开 http://127.0.0.1:3080
确认终端里 dsh 进程仍在运行且没有报错；若端口被占用，可以用 dsh --profile web --port 8080 换一个端口（--port 0 可让系统自动选择空闲端口）；检查防火墙是否放行本地端口。注意 Web 监听地址只接受具体的本机 IPv4/IPv6 地址，不接受通配地址。
问题 2：npx 找不到 @deepseek-ai/dsh 或版本过旧
先确认 Node.js 已安装且版本不低于 24.9（node -v）；项目处于开发者预览阶段、迭代很快，先用 npx @deepseek-ai/dsh@latest --version 核对实际版本，再决定是否更新或改用源码安装。
问题 3：源码安装时 pnpm install / build 失败
确认已启用 Corepack（corepack enable，仓库固定 pnpm 11.28.5）；网络受限时可为 npm/pnpm 配置镜像源；构建要求 Node.js 版本满足仓库声明（24.9+）。
问题 4：会话输入框不可用 / agent 无法读写文件
最常见原因是没有选择工作区——回到「选择工作区」添加并选中项目目录；确认已在「设置 → 模型」中保存有效的 API 密钥，模型路由无需重启即可生效。
问题 5：Python SDK 运行时找不到 Node.js
SDK 自带运行时、正常情况下不需要系统 Node.js；如果报运行时缺失，请确认安装的是与 SDK 同版本的完整包（python -m pip install deepseek-harness-sdk），并按官方前置要求使用 Linux x64 / arm64、macOS 14+（arm64）或 Windows x64。