DeepSeek Harness 安装使用详细指南

cooldream2009

442人浏览 · 2026-08-15 18:21:30

cooldream2009 · 2026-08-15 18:21:30 发布

前言

DeepSeek Harness 的首个公开版本（v0.1 开发者预览版）于 2026 年 8 月 13 日晚间正式推出，可以视为中国版的 Claude Code，也是 DeepSeek 推出的 Agent 产品。它是一个面向开发者的预览版，以 MIT 协议在 GitHub 上开源，旨在让开发者提前体验并参与生态建设，而非面向普通用户的成熟产品。其核心理念是"一切皆插件"，所有组件都可自由替换。截至发稿时，该项目已获得 105K Star，增长势头迅猛。

本文将详细介绍 DeepSeek Harness 的安装、配置和使用流程，帮助开发者快速上手这款强大的 AI 编程助手。

1 DeepSeek Harness 简介

DeepSeek Harness 是一个基于插件架构的 AI Agent 平台，专为开发者设计。它通过对话式交互，能够理解开发者的意图，自动完成代码编写、文件操作、项目构建等复杂任务。与传统的 IDE 插件不同，Harness 采用了"一切皆插件"的设计理念，这意味着它的工具、提示词和能力都可以通过插件系统进行扩展和定制。

Harness 的核心优势在于其灵活性和可扩展性。开发者不仅可以使用官方提供的标准功能，还可以根据自己的需求创建自定义的 Agent 预设（Preset），甚至开发新的插件来扩展 Harness 的能力边界。这种设计使得 Harness 不仅是一个编程助手，更是一个可定制的 AI 开发平台。

2 DeepSeek Harness 的安装

2.1 Node.js 环境准备

安装 DeepSeek Harness 之前，需要先安装 Node.js 运行环境。Node.js 是 Harness 的底层依赖，提供了必要的运行时支持。
在这里插入图片描述

Node.js 的安装有两种方式：

方式一：MSI 安装包

这是最简单的安装方式，适合大多数用户。从 Node.js 官网下载 MSI 安装文件，双击运行安装程序，按照向导提示完成安装即可。安装完成后，Node.js 会自动配置到系统环境变量中，无需额外设置。

方式二：ZIP 压缩包

对于需要更灵活控制的用户，可以选择下载 ZIP 压缩包。解压后将解压目录的路径添加到系统环境变量 PATH 中。这种方式适合需要在多个 Node.js 版本之间切换的开发者，或者在没有管理员权限的机器上安装。

验证安装是否成功，可以在命令行中输入以下命令：

node -v
npm -v

如果输出了版本号，说明 Node.js 安装成功。

2.2 DeepSeek Harness 安装

Node.js 安装完成后，就可以安装 DeepSeek Harness 了。Harness 通过 npm 包管理器分发，使用 npx 命令可以直接运行而无需全局安装。

在命令行中输入以下命令：

npx @deepseek-ai/dsh web

首次运行时，系统会提示是否安装所需的包：

Need to install the following packages:
@deepseek-ai/dsh@0.1.0-rc.6
Ok to proceed? (y)

输入 y 确认安装。安装过程中可能会有一些警告信息（如 npm warn deprecated），这些是正常的，可以忽略。

安装完成后，会看到类似以下的输出：

dsh web: http://127.0.0.1:3080

这表明 Harness 已成功启动，并监听在 3080 端口。

3 DeepSeek Harness 的访问配置

3.1 访问路径选择

Harness 启动后，可以通过浏览器访问。这里有一个需要注意的细节：虽然通过 http://127.0.0.1:3080 可以直接访问主界面，但在点击"选择工作区"时会遇到报错。这是当前版本的一个已知 Bug。
在这里插入图片描述

解决方案是使用 http://localhost:3080 进行访问。使用 localhost 域名时，工作区选择功能可以正常使用。

工作区是 Harness 的工作目录，它决定了 Harness 可以访问和操作的文件范围。建议为每个项目创建独立的工作区，避免不同项目之间的文件混淆。

3.2 大模型配置

Harness 默认使用 DeepSeek 大模型，需要配置 API Key 才能正常使用。配置文件位于用户主目录下的 .dsh 目录中，文件名为 settings.yaml。

配置文件的完整路径为：C:\Users\你的用户名\.dsh\settings.yaml

以下是 DeepSeek 模型的默认配置示例：

  id: llm-deepseek
  name: '@deepseek-ai/dsh-llm-deepseek'
  config:
    apiKeyEnv: DEEPSEEK_API_KEY
    baseURL: https://api.deepseek.com
    thinking: enabled
    reasoningEffort: high
    maxTokens: 256000
    streamIdleTimeoutMs: 300000
    retryPolicy:
      mode: always
      backoff:
        initialDelayMs: 500
        maxDelayMs: 10000
        jitterRatio: 0.1
    defaultContextWindow: 1000000
    models:
      - id: deepseek-v4-flash
        name: DeepSeek-V4-Flash
      - id: private-reasoner
        description: Company-hosted reasoning model
        contextWindow: 512000

配置中的关键字段说明：

apiKeyEnv：指定 API Key 的环境变量名称，默认为 DEEPSEEK_API_KEY
baseURL：API 服务地址，可选配置
thinking：是否启用思考模式，默认为 enabled
reasoningEffort：推理努力程度，可选值为 off、high、max
maxTokens：单次请求的最大输出 Token 数
defaultContextWindow：默认上下文窗口大小

配置完 YAML 文件后，还需要设置系统环境变量。在 Windows 系统中，打开"系统属性"→"环境变量"，在系统变量中新建一个变量：

变量名：DEEPSEEK_API_KEY
变量值：你在 DeepSeek 官网获取的 API Key

获取 API Key 的地址为：https://platform.deepseek.com/api_keys

设置完成后，重启 Harness 服务使配置生效。

4 DeepSeek Harness 的使用体验

配置完成后，就可以开始使用 Harness 了。在对话区输入内容，Harness 会调用配置的大模型进行响应。
在这里插入图片描述

如果模型能够正常回答问题，说明配置成功。

为了测试 Harness 的实际工作能力，我进行了一个完整的任务测试：在工作区中放置了一个 Markdown 文档，内容为《需求分析方法论》，然后让 Harness 根据该文档制作一份 15 页的教学 PPT。

具体的指令为：“你看下 md 文件，根据 md 文件，生成 ppt，要求 ppt 15 页，适合教学。”

Harness 接收到任务后，开始了一系列自动化操作：

读取并分析 Markdown 文件内容
理解文档结构和核心要点
自动安装所需的 PPT 生成插件
根据内容规划 PPT 结构和布局
生成每一页的 PPT 内容
输出最终的 PPT 文件

由于是首次使用，Harness 需要下载和配置相关插件，整个过程耗时约 40 分钟。期间存在不断试错和调整的过程，但最终成功完成了 PPT 的制作。整个执行过程可以在"轨迹"面板中查看，便于了解 Harness 的决策逻辑。
在这里插入图片描述

这次任务总共消耗了 0.55 元人民币的费用，使用的是 DeepSeek-V4 模型。考虑到任务的复杂度和最终效果，这个成本是非常合理的。

5 Harness 的预设模式

Harness 的预设（Preset）定义了一个会话中 Agent 所运行的插件组合，包括工具、提示词和能力。用户可以复制现有预设进行修改，或者使用"创造模式"让 Agent 帮助创建自定义预设。

目前 Harness 提供了 4 种预设模式，各模式的特点如下表所示：

模式	标识	定位与核心能力
标准模式	standard	功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。当前为默认使用模式。
PTC 模式	code	具备标准模式全部能力，额外通过 Code Mode SDK 让模型用一个 TypeScript 程序组合多步操作，适合复杂任务编排。
极简模式	minimal	仅提供持久 bash + str_replace_editor 双工具的精简版 Agent，适合轻量或低延迟场景。
创造模式	cordis	用于创建自定义 Agent preset，具备标准模式全部能力，并提供运行时检查、插件实验和 preset 创作指导，面向开发者和插件作者。

标准模式适合日常开发任务，提供了完整的工具集；PTC 模式通过 TypeScript 编排能力，适合需要复杂逻辑控制的任务；极简模式去除了冗余功能，启动更快，适合简单的代码编辑场景；创造模式则是为开发者设计的，用于创建和测试自定义的 Agent 预设。

这四种模式的引入，标志着 Harness 从一个单一 Agent 演变为一个可切换多模式、可扩展的 Agent 平台。其中 PTC 模式（TypeScript 编排）和创造模式（自定义 preset）是核心亮点，体现了 Harness 向更灵活的开发者生态方向发展的战略意图。

结语

DeepSeek Harness 作为一款新兴的 AI 编程助手，展现了强大的潜力和灵活性。其"一切皆插件"的设计理念，为开发者提供了高度的自定义能力。虽然当前版本（v0.1）仍处于开发者预览阶段，存在一些已知问题（如 127.0.0.1 访问 Bug），但整体体验已经相当出色。

通过本文的介绍，相信读者已经掌握了 Harness 的安装、配置和基本使用方法。随着后续版本的迭代，Harness 必将带来更多令人期待的功能和改进。对于希望提升开发效率、探索 AI 辅助编程的开发者来说，DeepSeek Harness 无疑是一个值得关注和尝试的工具。

参考资料

DeepSeek Harness GitHub 仓库：https://github.com/deepseek-ai/deepseek-harness
DeepSeek API 平台：https://platform.deepseek.com
Node.js 官方网站：https://nodejs.org

DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

anywhere-labs/deepseek-harness-desktop 生命周期设计：Generation、回滚与有序退出

作为处理过后台服务、桌面窗口和外部子进程状态一致性的工程师，我认为桌面应用最难复现的故障，往往不是某个函数直接抛错，而是多个生命周期在错误时刻交叉：用户切换了 Profile，旧 renderer 还握着 service；窗口已经关闭，Host 却继续运行；包管理器父进程退出，后代仍占用文件；Electron 请求 relaunch，但 Cordis dispose 失败；新配置启动到一半就被写成