从 0 开始成为 DeepSeek Harness 高手｜保姆级教程

在这里插入图片描述

还在只会用网页版 AI 单纯对话？写代码要复制粘贴、处理文件手动操作、复杂任务只能分段提问，效率极低。

近期 DeepSeek 开源重磅智能体框架 DeepSeek Harness，上线即刷屏技术圈，GitHub 星标暴涨，主打本地可视化 Agent 工作台、全插件扩展、自主拆解任务、本地文件 / 终端 / 代码读写，不用复杂代码，普通电脑就能搭建专属 AI 自动化工具。

很多新手拿到命令直接报错、不会配密钥、分
不清三种安装方式、看不懂界面功能，今天这篇万字完整教程，从零起步，小白跟着操作就能搭建成功，全程无门槛，看完直接成为 Harness 熟练使用者。

一、先搞懂：什么是 DeepSeek Harness？适合谁用？

1. 核心定义

DeepSeek Harness（简称 DSH） 是 DeepSeek 官方开源的本地 AI 智能体运行框架，核心逻辑：大模型 + 工具插件 + 自主任务调度。

区别于普通对话 AI：普通 AI 只能单次回答，Harness 可以自主拆分长任务、循环调用工具、读写本地文件、运行代码、执行终端命令、联网检索，全程可视化展示每一步执行轨迹。

2. 核心优势

  • 全平台兼容：Windows / Mac / Linux 通用
  • 三种部署方案：临时体验 / 长期使用 / 源码二次开发任选
  • 内置海量插件：代码沙箱、文件读写、终端执行、网页搜索、数据分析
  • 本地存储配置：API 密钥仅存在本机，无上传泄露风险
  • 任务全程透明：每一步操作日志完整记录，可追溯、可撤回
  • 支持多模型接入：DeepSeek 全系、OpenAI、Claude 等兼容 API 模型

3. 适合人群

人群 能做什么
AI 新手爱好者 体验本地自主 Agent 工具
程序员 / 开发者 自动写代码、调试项目、批量处理脚本
学生 / 科研党 论文整理、数据统计、文献检索、实验自动化
办公运营 批量文案、表格处理、素材整理、自动化工作流

4. 前置必备条件

  1. 电脑系统：Win10 及以上、macOS 任意版本、Linux
  2. Node.js 运行环境：必须 v22 LTS 或 v24 LTS（版本过低直接报错）
  3. DeepSeek API Key：官网免费注册领取，新用户赠送免费调用额度
  4. 稳定网络：可正常拉取 npm 依赖包（国内网络慢可切换淘宝镜像）

二、第一步：安装 Node.js 运行环境

Harness 所有启动命令依赖 Node.js，是前置核心，不会安装直接跟着下面操作。

1. 下载官方安装包

官网地址：https://nodejs.org/zh-cn/

⚠️ 重点：下载 LTS 长期稳定版，不要选最新尝鲜版！
在这里插入图片描述

2. Windows 安装流程

  1. 双击下载完成的 .msi 安装包，弹出安装向导
  2. 到「Custom Setup」页面，务必勾选 Add to PATH（自动配置系统环境变量，取消会导致命令失效）
  3. 全部点击「Next 下一步」，默认路径安装即可，无需修改设置
  4. 安装完成点击 Finish 结束

3. macOS 安装流程

  1. 下载 .pkg 安装包，双击打开
  2. 跟随向导完成安装，系统自动配置环境变量
  3. 若终端识别不到 node，重启终端即可

4. 验证安装是否成功

Windows：快捷键 Win+R，输入 cmd 回车打开命令提示符
Mac：启动台搜索「终端」打开

输入校验命令：

node -v

输出类似 v24.19.0 版本号 = 安装成功；提示"不是内部命令" = 环境变量失效，重启电脑重试。

💡 PowerShell 用户注意：如果用 PowerShell 而非 CMD，设置 PATH 的命令是 $env:PATH = "F:\APP\Node.js;" + $env:PATH，不是 CMD 的 set PATH=... 写法，否则会报错（这个坑作者真实踩过！）。

三、第二步：申请 DeepSeek API Key（免费）

所有 AI 推理依赖 API 密钥，无密钥无法调用模型，步骤超简单：

  1. 打开 DeepSeek 开放平台：https://platform.deepseek.com/
  2. 手机号注册 / 登录账号，完成实名认证（新用户赠送免费额度）
  3. 左侧导航栏找到「API 密钥」板块
  4. 点击「创建密钥」，自定义名称（随便填，如"本地 Harness"）
  5. 生成后立刻复制保存，密钥仅展示一次，关闭页面无法找回，丢失只能重新创建

💡 额度小提示：新用户免费额度在这里插入图片描述
足够日常学习测试；额度耗尽可在平台充值，DeepSeek 定价行业低价，调用成本极低。

四、第三步：3 种安装启动方案，按需选择

方案一：NPX 一键启动｜新手首选（临时体验，零全局污染）

适合偶尔使用、不想占用本地存储空间、不想安装全局包的用户。

  1. 桌面新建空白文件夹（建议命名「DSH 工作区」，方便 AI 读写文件）
  2. 终端 cd 切换到这个文件夹路径：
# Windows
cd C:\Users\你的用户名\Desktop\DSH工作区
# Mac
cd ~/Desktop/DSH工作区
  1. 输入一键启动命令：
npx @deepseek-ai/dsh web
  1. 首次运行自动下载全部依赖，等待 1–3 分钟（网络慢可切换 npm 镜像，文末有教程）
  2. 终端输出提示 dsh web: http://127.0.0.1:3080 代表启动成功
  3. 浏览器复制地址打开 Harness 网页后台

⚠️ 缺点：关闭终端窗口，服务直接停止，下次使用需要重新执行命令

⚠️ 首次启动必读：npx 第一次运行会显示 Ok to proceed? (y)，输入 y 回车即可。之后会经历约 1–3 分钟的静默安装期（CPU 可能占满），这是在下载 60+ 个依赖包，别误以为卡死把窗口关了。等它自己吐出 URL 就行。

方案二：全局安装｜长期主力使用（推荐日常重度玩家）

优势：一次安装永久生效，任意终端直接启动，无需重复下载依赖。

npm install -g @deepseek-ai/dsh

等待安装完成，无报错即成功。之后任意文件夹打开终端：

dsh web

浏览器访问 http://127.0.0.1:3080。

想锁版本避免 rc 变动：npm install -g @deepseek-ai/dsh@0.1.0-rc.6

方案三：源码部署｜开发者定制（修改源码 / 开发插件专用）

适合需要二次开发、自定义插件、修改底层逻辑的技术用户，提前安装 pnpm：

# 1. 克隆官方源码仓库
git clone https://github.com/deepseek-ai/deepseek-harness
# 2. 进入源码文件夹
cd deepseek-harness
# 3. 安装项目依赖
pnpm install
# 4. 编译构建项目
pnpm run build
# 5. 启动 Web 服务
pnpm dsh web

五、第四步：首次打开必做 2 项核心配置

打开网页端后，对话框默认灰色不可输入，必须完成两步设置：

Step 1：填入 DeepSeek API 密钥

  1. 页面右上角点击 Settings（设置）
  2. 左侧菜单栏选择 Models（模型配置）
  3. 找到 DeepSeek 配置卡片，将复制的 sk 开头密钥粘贴至输入框
  4. 默认模型选择 deepseek-chat（通用全能模型），点击保存

在这里插入图片描述

✅ 无需重启服务，配置即时生效，密钥本地加密存储，界面不会明文展示。

💡 如果网页里粘贴不了密钥？ 有些浏览器/安全软件会禁用密码框的右键粘贴。解决办法：① 先试 Ctrl+V 键盘快捷键；② 还不行就用环境变量方式启动（见文末附录），彻底绕开网页输入。

Step 2：选择本地工作区（安全核心设置）

这是 Harness 的安全机制，必须指定文件夹，AI 仅能读写选中目录内文件，不会篡改电脑其他文件。

  1. 返回首页对话界面，点击「工作区」
  2. 点击添加文件夹，选中之前桌面新建的 DSH 工作文件夹
  3. 选中文件夹后，对话框自动解锁，即可正常发送指令

在这里插入图片描述

六、界面全功能详细拆解（小白一看就懂）

1. 首页会话区域

  • 新会话：新建独立任务对话，任务记录互不干扰
  • 模型选择：切换 deepseek-chat、deepseek-v4-pro 等模型
  • 思考强度：Off / High / Max 三档，Max 推理深度更高，复杂任务推荐开启
  • 输入框：发送自然语言指令，支持长文本复杂需求

2. 核心插件中心（Harness 灵魂功能）

内置插件全部开箱即用，无需额外配置：

插件 能力
文件读写插件 读取、新建、修改、批量重命名本地文档 / 表格 / 代码
代码沙箱插件 在线运行 Python/JS 代码，自动排查报错、生成可视化图表
终端执行插件 调用本机终端命令，批量处理文件、安装工具
网页搜索插件 实时联网检索最新资料，写论文、查资讯必备
数据处理插件 Excel/CSV 批量统计、清洗数据、生成分析报告

3. 任务轨迹面板

每一次 AI 执行操作完整记录：读取了哪个文件、运行了什么代码、调用了什么插件、返回结果是什么。支持撤回单步操作、查看完整执行链路，完全透明可控，不用担心 AI 乱改文件。

4. 设置中心细分功能

  • 模型管理：新增 OpenAI、Claude 等第三方模型 API
  • 界面主题：多套深浅色皮肤自定义
  • 网络代理：海外模型专用代理配置
  • 权限管控：限制文件读写、终端执行权限，提升电脑安全性

在这里插入图片描述

七、两大实战案例，手把手教你用 Agent 干活

案例 1：代码自动化开发（程序员刚需）

需求指令直接复制发送：

在当前工作目录创建批量重命名工具，适配 Windows 系统，
使用 Python 编写，添加详细注释，输出使用教程，
运行测试代码排查 bug

Harness 自主执行流程：

  1. 拆解需求：创建 py 文件 → 编写重命名逻辑 → 添加注释 → 自测代码 → 生成使用文档
  2. 调用文件插件新建脚本，代码沙箱运行自测，自动修复报错
  3. 生成 README 使用说明，全部文件保存至本地工作文件夹

案例 2：论文 / 长文自主创作（学生、自媒体适用）

发送指令：

写一篇 2000 字 AI 智能体学习科普文章，分 4 个章节，
先梳理大纲，填充内容，最后润色优化语句，逻辑通顺专业

普通 AI 只会一次性输出文本；Harness 分步执行：

  1. 联网检索 AI Agent 行业资料，梳理文章四级大纲
  2. 分章节分段撰写初稿
  3. 自查逻辑漏洞，修改不通顺段落
  4. 统一全文格式，输出完整成品文档保存本地

八、高频报错大全 + 解决办法（新手踩坑汇总）

报错 1：node 不是内部命令 / node 版本过低

  • 原因：未勾选 PATH 环境变量；Node 版本低于 v22
  • 解决：卸载现有 Node，重装 v24 LTS 版本，安装时勾选 Add to PATH，安装完成重启电脑

报错 2：npx/npm 下载依赖超时、失败

  • 原因：国内 npm 官方源访问缓慢
  • 解决：切换淘宝镜像，终端执行这条命令后重新启动：
npm config set registry https://registry.npmmirror.com

报错 3：API Key 无效、调用返回报错

  • 原因：密钥粘贴带空格、密钥创建错误、账号额度耗尽
  • 解决：重新前往平台复制密钥，删除前后多余空格；查看平台用量充值额度

报错 4：端口 3080 被占用，启动失败

  • 原因：上一次 dsh 进程没关掉，还占着端口
  • 解决：找到旧窗口按 Ctrl+C 关闭；或关掉占用端口的进程再重启。也可以改用其他端口（进阶操作）

报错 5：对话框灰色无法输入

  • 原因：未选择本地工作区文件夹
  • 解决：首页点击「工作区」，选中任意本地文件夹解锁输入框

报错 6：AI 无法读写本地文件

  • 原因：工作区未选中、文件夹权限不足
  • 解决：更换桌面新建文件夹作为工作区，避免系统盘保护目录

报错 7：PowerShell 里 set PATH=… 报错

  • 原因：把 CMD 语法粘进了 PowerShell
  • 解决：PowerShell 用 $env:PATH = "F:\APP\Node.js;" + $env:PATH（这个坑作者真实踩过！）

九、新手速记 & 进阶学习路线

新手速记 3 条核心要点

  1. 临时体验用 npx 一键启动，长期使用推荐全局安装 dsh
  2. 启动后必须两步配置：填 API 密钥 + 选择工作区，缺一不可
  3. Harness 核心价值不是简单聊天，是自主 Agent 工具调用、本地自动化任务

进阶玩法（入门后拓展）

  1. 自定义插件开发，新增专属工具能力
  2. 接入本地私有大模型，实现离线无网运行
  3. 搭建自动化办公工作流，批量处理表格、文案素材
  4. 源码二次开发，自定义 WebUI 界面、主题样式

附：Windows 一键启动批处理（推荐收藏）

每次手动设 PATH 太麻烦？创建一个 .bat 文件，以后双击就能启动：

第一步： 新建文本文件 F:\APP\dsh-key.txt，里面只写一行你的 API Key：

sk-你的真实密钥粘贴在这里

第二步： 新建 F:\APP\start-dsh.bat，内容如下：

@echo off
chcp 65001 >nul
echo ========================================
echo   DeepSeek Harness 一键启动器
echo ========================================
echo.

REM ---- 1. Node.js 进 PATH ----
set "NODE_HOME=F:\APP\Node.js"
set "PATH=%NODE_HOME%;%PATH%"

REM ---- 2. 注入 API Key ----
set "DEEPSEEK_API_KEY="
for /f "usebackq delims=" %%k in ("%~dp0dsh-key.txt") do (
    set "DEEPSEEK_API_KEY=%%k"
)

if "%DEEPSEEK_API_KEY%"=="" (
    echo [错误] 未找到 dsh-key.txt 或文件为空！
    echo 请在同目录下创建 dsh-key.txt 并填入你的 DeepSeek API Key。
    pause
    exit /b 1
)
echo [OK] API Key 已加载（来源：dsh-key.txt）

REM ---- 3. 进入工作区并启动 ----
cd /d F:\dsh-scratch
if errorlevel 1 (
    mkdir F:\dsh-scratch 2>nul
    cd /d F:\dsh-scratch
)
echo [OK] 工作区: %CD%
echo.
echo 正在启动 DeepSeek Harness Web...
echo 浏览器请访问: http://127.0.0.1:3080
echo 按 Ctrl+C 停止服务
echo ----------------------------------------
npx @deepseek-ai/dsh web
pause

第三步： 双击 start-dsh.bat 即可自动完成所有步骤。

💡 原理：环境变量 DEEPSEEK_API_KEY 的优先级高于网页填写，所以启动时直接注入，网页 Settings 里会显示 Key 来源为 env（只读），不用在网页里粘贴。

结尾结语

DeepSeek Harness 把 AI 智能体的门槛降到最低，不用复杂编程，普通电脑就能拥有能操作本地文件、自主完成复杂任务的 AI 助手。

本文完整覆盖从环境搭建到实战落地全流程，零基础跟着步骤操作就能成功部署，后续会持续更新插件开发、本地私有模型接入、自动化批量任务实战案例，感兴趣可以持续关注。

Logo
DeepSeek技术社区

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

更多推荐

Google能索引，AI却抓不到

很多技术团队有个错觉：只要Google能正常收录，内容就没问题。但现实是，你的页面在Google搜索结果里好好的，在ChatGPT、Perplexity、Claude的答案里却像从未存在过一样。

avatar DeepSeek技术社区

初识智能体

在过去两年中，几乎所有人都体验过大语言模型（如 ChatGPT、Claude、DeepSeek）的强大能力：写周报、润色邮件、解答编程疑难。被动响应：你问一句，它答一句。如果你的 Prompt 没有写清楚约束条件，它无法主动追问或修正目标。知行脱节：大模型能用流畅的文字告诉你“如何部署一个高可用 K8s 集群”，但它无法替你登录服务器敲下命令、查看报错日志并自动回滚。信息孤岛：大模型的知识止步于预

avatar DeepSeek技术社区

DeepSeek总结的时间旅行者的主键

来源：https://www.pgedge.com/blog/the-time-traveler-s-primary-key。

avatar DeepSeek技术社区