DeepSeek Harness 安装指南

DeepSeek Harness 是 DeepSeek 官方开源的智能体框架，命令行工具为 dsh。项目目前处于开发者预览阶段，可能出现破坏兼容性的变更，升级前应先备份 ~/.dsh。

官方 npm 包是 @deepseek-ai/dsh，不要与无作用域的 dsh 包（一个 JavaScript shell）混淆。命令名为 deepseek 的 deepseek-harness-cli、以及发布桌面安装包的 deepseek-harness-desktop 都不是 DeepSeek 官方仓库，本文不作为官方安装方式。

Web UI 默认只监听 127.0.0.1 且没有认证，不要暴露到局域网或公网。DeepSeek API Key 与 New API 令牌是两套独立的模型接入方式，计费和凭据互不通用。

1. 安装

前置条件：

Node.js ^22.19.0 或 >=24.0.0。这是所有安装方式的硬性要求；npx / 全局安装只需 Node.js + npm，源码构建还需要 Git 2.26+ 和 pnpm 11.7.0（通过 Corepack 启用）。
官方推荐 npx 或全局安装；桌面安装包（Windows/macOS/Linux）不是官方仓库发布，而是第三方 fork sdkwork-ai/deepseek-harness-desktop 的 Releases 提供，使用时需自行核验来源。
国内网络：npx 从 npm 官方 registry 下载，直连失败时先配置 npm 镜像；源码 clone GitHub 失败时可用 https://gh-proxy.com/ 前缀。

1.1 Windows

先确认 Node.js 版本：

复制代码

node --version

未安装或版本不满足时，用 winget 安装 Node.js LTS（22 或 24）：

复制代码

winget install OpenJS.NodeJS.LTS

然后启动（推荐，npx 每次运行解析 npm 渠道的最新版本）：

复制代码

npx @deepseek-ai/dsh web

或全局安装后启动：

复制代码

npm install -g @deepseek-ai/dsh
dsh web

启动 Web UI，浏览器访问 http://127.0.0.1:3080。安装完成后关闭并重新打开 PowerShell，确保 dsh 命令可用。需要更换端口时加 --port，例如 dsh web --port 8080。

1.2 macOS

先确认 Node.js 版本，未安装时用 Homebrew 安装：

复制代码

brew install node
node --version

然后启动：

复制代码

npx @deepseek-ai/dsh web

或全局安装：

复制代码

npm install -g @deepseek-ai/dsh
dsh web

安装完成后重新打开终端。

1.3 Linux

先确认 Node.js 版本；Ubuntu / Debian 未安装时可用 NodeSource 安装 Node.js 24（示例）：

复制代码

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node --version

然后启动：

复制代码

npx @deepseek-ai/dsh web

或全局安装：

复制代码

npm install -g @deepseek-ai/dsh
dsh web

安装完成后重新打开终端。

2. 验证

全局安装时：

复制代码

dsh --version

能够输出 dsh 版本号，即表示安装成功。使用 npx 方式时，可运行：

复制代码

npx @deepseek-ai/dsh --version

启动 Web UI 后，浏览器能够打开 http://127.0.0.1:3080 并显示界面，即表示运行入口正常。尚未配置 API Key 不影响此项验证。

3. 配置

3.1 首次启动与 API Key

DeepSeek Harness 是本地运行时，不使用账号登录，而是使用 DeepSeek 开放平台的 API Key。启动：

复制代码

npx @deepseek-ai/dsh web

首次使用时：

点击 Choose Workspace 选择一个项目目录。选择工作区前输入框是禁用的；工作区是安全边界，Agent 只能操作你明确添加的目录。
进入 Settings → Models ，在预置的 DeepSeek 卡片中粘贴 API Key 并保存。
API Key 在 DeepSeek 开放平台的 API Keys 页面创建，以 sk- 开头，仅创建时显示一次，请立即复制保存。

也可以只用环境变量启动：

复制代码

export DEEPSEEK_API_KEY=你的_DeepSeek_API_Key
npx @deepseek-ai/dsh web

Windows PowerShell：

复制代码

$env:DEEPSEEK_API_KEY = "你的_DeepSeek_API_Key"

3.2 API Key（DeepSeek / New API 示例）

需要修改的用户文件位于 harness home，默认 ~/.dsh（可用 DSH_HOME 覆盖）：

系统	主配置	密钥文件
Windows	`%USERPROFILE%\.dsh\settings.yaml`	`%USERPROFILE%\.dsh\.credentials.yaml`
macOS / Linux	`~/.dsh/settings.yaml`	`~/.dsh/.credentials.yaml`

settings.yaml 保存模型与提供商等非敏感设置；.credentials.yaml 保存密钥，是"变量名: 值"的裸 YAML 映射，不要加外层键或 version 字段。环境变量的优先级高于这两个文件。下面两个示例一次只启用一个作为默认模型。

DeepSeek 直连示例：

官方适配器默认读取 DEEPSEEK_API_KEY、使用 https://api.deepseek.com，并默认提供 deepseek-v4-flash 与 deepseek-v4-pro 两个模型，因此最简单的方式是只保存密钥：

复制代码

# ~/.dsh/.credentials.yaml
DEEPSEEK_API_KEY: 你的_DeepSeek_API_Key

如需显式指定基址和模型清单，可在 settings.yaml 中写入：

复制代码

llm-deepseek:
  apiKeyEnv: DEEPSEEK_API_KEY
  baseURL: https://api.deepseek.com
  models:
    - id: deepseek-v4-pro
      name: DeepSeek-V4-Pro
    - id: deepseek-v4-flash
      name: DeepSeek-V4-Flash

字段含义：

deepseek-v4-pro：主力/前台模型，用于复杂推理、编程、智能体工作流和长上下文分析。
deepseek-v4-flash：轻量/后台模型，用于高频对话、信息抽取、路由等低成本任务。

New API 示例：

New API 等中转站通常提供 OpenAI 兼容的 /v1 接口。在 .credentials.yaml 中保存令牌：

复制代码

# ~/.dsh/.credentials.yaml
NEW_API_KEY: 你的_NewAPI_令牌

在 settings.yaml 中声明一个自定义提供商：

复制代码

llm-pi-ai:
  providers:
    newapi:
      displayName: New API
      apiKeyEnv: NEW_API_KEY
      api: openai-completions
      baseURL: https://你的NewAPI域名/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: deepseek-v4-pro
        - id: deepseek-v4-flash

使用该示例前必须确认以下几点：

New API 控制台确实向当前令牌开放了 deepseek-v4-pro / deepseek-v4-flash；如果控制台显示的是其他模型 ID（例如 deepseek/deepseek-v4-pro），必须替换 models[].id。
New API 实现了 OpenAI 兼容的 POST /v1/chat/completions、流式输出和工具调用。只有 Anthropic 接口的站点不能直接使用这份配置。
baseURL 填写包含 /v1 的基址，不要填写完整的 /v1/chat/completions 路径。apiKeyEnv 指向 .credentials.yaml 中的令牌变量，不要把密钥直接写进 settings.yaml。
compat 两项用于兼容中转站：多数中转站不接受 role: "developer" 的系统提示和 max_completion_tokens 输出上限字段；若中转站转发的是 DeepSeek 推理模型，可能还需追加 thinkingFormat: deepseek。

保存并验证：

确认 settings.yaml 缩进正确、.credentials.yaml 是合法 YAML（POSIX 下需 chmod 600 ~/.dsh/.credentials.yaml）。
通过文件修改的模型与提供商配置通常在下一次请求时生效，无需重启；为稳妥可完全退出并重新运行 dsh web（或 npx @deepseek-ai/dsh web）。
打开 Web UI 的 Settings → Models ，确认 DeepSeek 或 newapi 提供商与目标模型存在，并在模型选择器中选中，然后发送一条简单消息。能够正常返回，说明密钥、地址和模型路由均已生效。
排查时可运行 dsh --dump-config 查看最终叠加后的插件与提供商配置。

.credentials.yaml 和 .env 包含明文密钥，不要提交到 Git、网盘同步目录或聊天记录。第三方网关不是 DeepSeek 官方服务，使用前应核对模型真实性、计费、日志留存和数据处理规则。

4. 更新

npx 方式无需手动更新，npx @deepseek-ai/dsh web 每次运行解析 npm 渠道的最新版本。需要固定版本时，使用 npx --yes @deepseek-ai/dsh@0.1.0-rc.X web。
全局安装执行：

npm update -g @deepseek-ai/dsh
dsh --version

或重新安装：

复制代码

npm install -g @deepseek-ai/dsh

源码安装切换到目标 tag 后重建：

git fetch --tags
git checkout dsh-v0.1.0-rc.X
pnpm install --frozen-lockfile
pnpm run build

开发者预览版可能出现破坏兼容性的变更，升级前先备份 ~/.dsh（Windows 为 %USERPROFILE%\.dsh），以便需要时回退。

5. 卸载

按安装方式对应卸载：

全局安装：npm uninstall -g @deepseek-ai/dsh。
源码安装：停止正在运行的进程后删除 clone 目录。
npx 方式：没有应用目录需要卸载；npx 缓存可选择性清理，不影响 Harness 数据。

卸载程序后，配置、密钥和会话数据仍保留在 harness home（默认 ~/.dsh，Windows 为 %USERPROFILE%\.dsh）。需要彻底清除（含 API Key、会话与轨迹）时，卸载后手动删除该目录；删除前确认不再需要其中的数据。使用过 DSH_HOME 自定义目录时删除对应目录；默认的技能/智能体目录 ~/.agents 如未与其他项目共用，也可一并清理。