DeepSeek Harness 在 Windows 上的安装与配置指南

2026-09-13 12:59 2 阅读

为什么选择 DeepSeek Harness

DeepSeek Harness（简称 dsh）是 DeepSeek 官方推出的开源 AI Agent 框架，在 GitHub 上已获得超过 6.8 万星标。它采用 MIT 许可证，允许免费使用、修改和商业集成。对开发者而言，最大的吸引力在于其“一切皆插件”的设计哲学——从模型适配器到会话日志，所有功能模块都以插件形式存在，这意味着你可以按需替换或扩展任意组件，而无需改动核心代码。

在这里插入图片描述

与依赖云端服务的 Agent 平台相比，本地部署 dsh 能确保你的代码和文件始终留在本机，避免数据外泄风险。同时，你还能自由选择模型提供商（如 OpenAI、Anthropic、月之暗面等），并根据项目需求定制工具链和权限策略。

在这里插入图片描述

环境准备

在这里插入图片描述

在开始安装前，请确认你的系统满足以下要求：

在这里插入图片描述

Node.js：版本需为 22.19 或更高，推荐使用 24.x（实测 v24.14.0 可正常运行）。低版本会因 engines 字段校验失败而报错。
pnpm：仅当你打算从源码构建时才需要，建议版本为 11.7.0 或以上。
模型 API Key：用于调用大语言模型，可在 DeepSeek、OpenAI 或其他支持的平台获取。

在这里插入图片描述

如果你在中国大陆，建议提前配置 npm 镜像以加速依赖下载：

npm config set registry https://registry.npmmirror.com

两种部署方式

方式一：使用 npx 快速启动（推荐）

这是最简单的部署方法，适合大多数用户。只需一条命令即可运行：

npx @deepseek-ai/dsh web

首次执行时，系统会自动从 npm 下载最新版 dsh（例如 0.1.0-rc.6），完成后自动启动 Web 服务。打开浏览器访问 http://127.0.0.1:3080 即可进入操作界面。

这种方式无需克隆代码库，也不需要手动安装依赖，特别适合快速体验或日常使用。

方式二：从源码构建（适合开发者）

如果你计划开发自定义插件或参与框架改进，则建议从源码运行：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install
pnpm run build
pnpm dsh web

注意，该项目是一个 monorepo，依赖较多，pnpm install 和 build 过程可能耗时较长。构建完成后，同样通过 pnpm dsh web 启动服务。

基本使用流程

启动 Web 界面后，按以下步骤开始使用：

配置模型：点击右上角“设置” → “模型”，选择模型提供商（默认为 DeepSeek），填入对应的 API Key。
指定工作区：在主界面点击“Choose workspace”，添加你的项目目录并选中作为当前工作空间。Agent 将在此目录下读写文件、执行命令。
发起任务：新建一个会话，输入自然语言指令（如“帮我修复这个 Python 脚本中的错误”），Agent 会自动分析上下文、调用工具并返回结果。

设置面板详解

设置页面包含四个主要模块：

通用设置：可切换界面语言（支持中文）、主题（浅色/深色/跟随系统）、权限模式（决定 Agent 是否能执行危险操作）、Enter 键行为（发送消息或换行）等。
模型配置：支持超过 30 家模型提供商，包括 DeepSeek、OpenAI、Anthropic、Google、Groq、月之暗面、MiniMax 和 HuggingFace 等。只需选择提供方并填入密钥即可切换。
插件管理：列出已安装的插件，并提供搜索和安装入口。社区插件可通过 GitHub 的 dsh-plugin 标签查找。
Agent 预设：定义新会话的默认行为模式，例如是否启用代码执行、文件修改等能力。

插件机制与 CLI 工具

dsh 的核心是其自研的 Cordis 插件框架。每个插件本质上是一个服务（Service），通过上下文（Context）注册，支持依赖注入、类型化事件和可逆副作用（effect）。这种设计使得功能扩展非常灵活。

除了图形界面，dsh 还提供命令行工具：

dsh web          # 启动 Web 界面
dsh plugin       # 管理插件（安装/卸载/列表）
dsh profile      # 管理配置组合（Profile）
dsh dump-config  # 导出当前完整配置

例如，你可以创建一个名为 dev-profile 的配置组合，预装代码分析、测试运行和 Git 操作插件，然后在不同项目中复用该配置。

常见问题与注意事项

Node 版本过低：如果运行时报错提示 engines 不满足，请升级 Node.js 至 22.19 或 24+ 版本。
版本迭代较快：目前 dsh 处于预发布阶段（如 rc.5 到 rc.6），可能存在破坏性变更。若遇到异常行为，建议查看 GitHub 最新文档或提交 issue。
权限控制：默认情况下，Agent 对文件系统的操作受到限制。如需执行 shell 命令或修改关键文件，请在设置中调整权限模式，并谨慎评估安全风险。