DeepSeek Harness 实操教程!(万字长文)
前两天,DeepSeek 正式公布了V4-Pro,随后又直接把 Agent 框架开源了。
这个项目叫 DeepSeek Harness,简称 dsh。
如果你平时只在 DeepSeek 网页里聊天,可以把这次的变化理解成:
以前的 AI 主要坐在聊天框里回答问题,现在它开始走进你指定的电脑文件夹,自己查看文件、执行命令、整理计划,在得到允许后还能修改内容。
它开始面对一个真实项目:里面有文件、有结构,也有可能被改动的内容。
不过先把预期放稳。
官方把当前版本标成了技术预览。
简单说,它已经可以安装和研究,但仍在快速变化,后续可能出现无法兼容旧配置的更新。
第一次使用,先拿测试文件夹练手,别急着把整个工作目录交给它。
它到底是什么
Harness 这个词直译过来有“挽具、套具”的意思。
放到 AI 领域,可以理解成一套把模型、工具和工作环境连接起来的系统。
模型负责思考,工具负责行动,工作区决定它能看到什么。
三样东西接起来,AI 才能从“告诉你怎么做”,走到“在指定范围里帮你做”。
DeepSeek Harness 自带一个 Web UI。
Web UI 就是可以在浏览器里打开的操作页面,外观接近我们熟悉的聊天工具。
底层依然运行在你的电脑上,浏览器只是操作窗口。
官方还用了一个专业说法:一切皆插件。
普通用户先把它理解成“以后可以继续加能力”就够了。
模型、文件操作、命令行、会话和其他工具都能通过模块进行组合。
至于 Cordis、Bundle、Profile 这些词,基础安装阶段完全不用管。
开始前,认识这 6 个词
下面会出现几个技术词,先看一遍,后面的安装会顺很多。
1. Node.js
运行 dsh 需要的一套基础环境,你可以把它理解成 dsh 的发动机。
安装 Node.js 不代表你要学编程。
2. PowerShell
Windows 自带的命令窗口,我们只会在里面复制几条命令,不需要手写代码。
3. npm
Node.js 自带的软件包管理工具,负责下载和管理程序。
4. npx
npx 也会随 Node.js 一起安装。
它可以临时下载并运行 dsh,所以本教程不要求你先手动安装 Harness。
5. API Key
一串通常以 sk- 开头的密钥。
Harness 要拿着它去调用 DeepSeek 模型,它相当于模型接口的通行证,需要保密,也会产生 API 用量。
6. 工作区
你允许 Harness 处理的电脑文件夹。Agent 读取文件、创建文档或执行命令,都会围绕这个目录进行。
认识这些就够了。
从零开始安装
第 1 步:安装 Node.js
打开浏览器,搜索 Node.js ,找到官网进入下载页面。
截至 2026 年 8 月 15 日,Node.js 官网提供的长期支持版是 24.x。
DeepSeek Harness 当前源码要求 Node.js 22.19.0 及以上的 22.x,或者 24.0.0 及以上版本。
普通用户直接选择 24.x LTS 就可以,LTS 的意思是“长期支持版”,通常比追最新测试功能更省心。
Windows 用户下载对应的安装程序后,双击打开,没有特殊需求时,安装向导保持默认选项,一路继续即可。
安装完成后,先把已经打开的 PowerShell 或终端全部关闭,旧窗口可能还识别不到刚安装的 Node.js。
现在重新打开 PowerShell:
- 点击 Windows 开始菜单;
- 输入
PowerShell; - 打开“Windows PowerShell”。
在窗口里依次粘贴下面两条命令,每粘贴一条就按一次回车:
1 | node --version |
第一条会显示 Node.js 版本,第二条会显示 npm 版本。
你的版本号不一定和我的一样,只要第一条显示 v24...,或者显示不低于 v22.19.0 的版本;第二条也能显示数字,这一步就通过了。
如果出现“无法将 node 识别为命令”之类的提示,先关闭 PowerShell 再打开一次。
仍然无效时,重新安装 Node.js,然后重启电脑再检查。
第 2 步:准备 DeepSeek API Key
接下来准备模型密钥。
打开 DeepSeek 开放平台的 API Key 页面,登录自己的 DeepSeek 开放平台账号。
找到创建 API Key 的入口,新建一条密钥,然后复制保存,密钥以 sk- 开头。
这里有三个容易混淆的地方:
- API Key 不是 DeepSeek 网页版的账号密码;
- Harness 调用的是 DeepSeek API,会按照 API 的实际用量计费;
- 账户余额不足时,调用可能返回 402 错误。
所以创建密钥后,顺手检查一下开放平台余额,具体价格会调整,发布文章时以官方页面通知为准。
密钥暂时放在密码管理器或安全的临时位置,下一步会粘贴到 Harness。
不要把完整密钥发给别人,也不要让它出现在截图里。
第 3 步:创建一个测试文件夹
现在给 Harness 准备一个单独的工作区。
打开 Windows 文件资源管理器,进入一个容易找到的位置,比如“文档”。
新建文件夹,并把它命名为 test1。
双击进入这个文件夹。
第一次测试建议使用空文件夹,这样即便选错设置或误操作,也不会碰到日常文件。
第 4 步:直接在这个文件夹里打开 PowerShell
保持文件资源管理器停留在 test1 文件夹。
点击窗口上方显示文件路径的地址栏,把里面的路径文字选中,然后改成powershell ,按回车。
Windows 会打开一个 PowerShell 窗口,而且当前位置已经是 test1。
不要关闭这个 PowerShell,下一步就在这里执行。
第 5 步:运行 Harness
把下面这一整行复制到 PowerShell,然后按回车:
1 | npx @deepseek-ai/dsh web |
这条命令可以拆成三部分理解:
npx:帮你临时下载并运行程序;@deepseek-ai/dsh:DeepSeek 官方发布的软件包;web:启动浏览器操作页面。
第一次运行需要准备相关文件,等待时间会比后面长。
由于我已经安装好了,所以这里直接给我运行的地址。
如果终端询问是否继续下载或安装,按照屏幕提示确认即可,不同 npm 版本的提示文字可能略有区别。
等待过程中不要连续重复粘贴命令,也不要关闭窗口。
看到终端打印出访问地址时,说明本地服务已经启动。官方默认地址是:
1 | http://127.0.0.1:3080 |
127.0.0.1 指的是你当前这台电脑。
它看起来像网址,实际连接的是本机正在运行的 Harness 服务。
第 6 步:在浏览器里打开 Harness
现在不要关 PowerShell。
只要 PowerShell 被关闭,网页也会跟着失去连接。
打开 Chrome、Edge 或你常用的浏览器,把终端打印的地址复制到地址栏。默认情况下就是:
1 | http://127.0.0.1:3080 |
按回车后,应该会进入 DeepSeek Harness 的 Web UI。
如果浏览器显示无法访问,先回到 PowerShell 看看程序是否还在运行、终端有没有红色错误。
到这一步,Harness 已经在电脑上跑起来了,但它还没有模型,也没有选中工作区,所以暂时不能开始对话。
第 7 步:把 DeepSeek 模型接进来
如果是初次打开网页的话,它回首先提示你去添加你的API Key,后续可以在设置里面改。
如果后续要修改的话,在 Harness 页面中打开:
设置 → 模型
找到 DeepSeek 对应的卡片,把第 2 步准备好的 API Key 粘贴进去,然后保存。
保存后不需要重启 Harness,模型配置会在下一次请求时生效。
如果页面要求选择模型,就从当前列出的 DeepSeek 模型中选择一个,模型名称会随着服务更新而变化,以你页面里的实际选项为准。
API Key 保存后,页面只会显示脱敏信息,不会重新展示完整密钥。
密钥会保存在 $DSH_HOME/.credentials.yaml 中,这个路径是配置存放位置,普通用户不需要现在去修改它。
这里显示的是我已经添加好了其他的模型 API。
第 8 步:选中刚才的测试文件夹
模型配置好以后,回到主页面,点击 选择工作区。
添加并选中刚刚创建的 test1 文件夹。
为什么还要再选一次?
因为“从哪个文件夹启动 Harness”和“当前会话允许操作哪个工作区”是两层设置,新的 Web UI 在添加工作区前不会自动选中任何目录。
选中后,原本不可用的消息输入框会开放。
现在检查下面四项:
- PowerShell 里的 dsh 仍在运行;
- 浏览器能正常打开 Harness 页面;
- DeepSeek 模型已经保存并处于可选择状态;
- 当前工作区显示为
test1,消息输入框可以点击。
四项都满足,安装和基础配置就完成了。
到这里,你已经可以开始正式使用了。
安装完成后,怎样关闭和再次启动
Harness 运行时,PowerShell 窗口需要保持打开。
想停止服务时,回到 PowerShell,按Ctrl + C,或者直接关掉窗口也行。
关闭后,浏览器里的 Harness 页面将会无法继续连接,这是正常现象。
下次使用时,不需要从头安装 Node.js。
只要重新进入 test1 文件夹,在地址栏输入 powershell,再运行:
1 | npx @deepseek-ai/dsh web |
然后打开终端给出的本地地址即可。
模型与密钥设置会保存在 dsh 的配置目录中,正常情况下不需要每次重新填写。
当前产品仍在技术预览阶段;若升级后配置行为发生变化,以新版官方文档为准。
如果安装卡住,按这个顺序排查
连续操作时先不要到处改设置。对照自己卡在哪一步:
1. node --version 没有结果
Node.js 没安装成功,或者旧 PowerShell 没刷新环境。
先关闭 PowerShell,重新打开;仍然失败,再重新安装 Node.js,并重启电脑。
2. npm --version 没有结果
npm 会跟着 Node.js 一起安装。
只装好了 Node 却没有 npm 时,优先重新运行 Node.js 安装程序。
3. npx @deepseek-ai/dsh web 一直下载失败
先看终端给出的具体错误。
常见影响因素包括网络连接、npm 下载源和代理设置。
不要根据别人的旧教程随意安装同名 Python 包,它们解决不了官方 npm 包的下载问题。
4. 3080 页面打不开
确认 PowerShell 没有被关闭,并检查终端实际输出的地址。
如果提示 3080 端口被占用,可以换到 8080:
1 | npx @deepseek-ai/dsh --profile web --port 8080 |
再访问终端打印的新地址。
5. 页面打开了,输入框仍是灰色
依次检查:
- 模型 API Key 是否保存;
- 是否选择了一个可用模型;
- 是否添加并选中了工作区。
官方 Web UI 在没有选中工作区时会禁用输入框。
6. 模型提示 401 或 MISSING_CREDENTIAL
401 一般表示密钥认证失败。重新检查 API Key 是否复制完整。
MISSING_CREDENTIAL 表示当前模型没有找到可用凭据,回到“设置 → 模型”重新保存密钥。
7. 模型提示 402
DeepSeek 官方错误码中,402 表示余额不足。前往开放平台检查余额和充值状态。
第一次实操
安装完成不代表要立刻拿真实项目上手。
test1 现在还是空的,Agent 没有东西可读。
我们先放入两个简单文本文件。
1. 创建“说明.txt”
打开 Windows 记事本,粘贴:
1 | 这是我的第一个 Harness 测试文件夹。 |
选择“文件 → 另存为”,保存到 test1,文件名填写:
1 | 说明.txt |
2. 创建“待办.txt”
再新建一个记事本文档,粘贴:
1 | 1. 了解 Harness 是什么 |
保存到同一个文件夹,文件名填写:
1 | 待办.txt |
这样我们就有了一组自己完全知道答案的测试材料。
Agent 总结得对不对,可以直接对照原文检查。
第一个任务:只允许读取,不允许修改
回到 Harness 页面,新建会话,把下面这段完整粘贴进去:
1 | 请先只读取当前工作区中的文件。 |
这段提示词故意写得比较完整,因为第一次任务的目标不是考 AI 猜谜,而是确认三件事:
- 它能不能看到正确的文件;
- 它能不能遵守只读要求;
- 它的回答能不能和原始内容对上。
如果页面出现操作确认,先看清楚它准备做什么。
读取两个文本文件不需要安装依赖,也不应该修改其他目录。请求明显超出任务范围时,先拒绝,再让它解释原因。
任务完成后,不要只看回答写得像不像。
打开 说明.txt 和 待办.txt,逐条核对文件名、目标和待办顺序。
第二个任务:确认计划后,只新建一个文件
只读结果可信,再进入写入测试。
继续发送:
1 | 根据刚才读取到的内容,准备在当前工作区新建“项目概览.md”。 |
看到计划后,先自己检查内容。
确认没有编造、没有漏项,也没有准备修改其他文件,再回复:
1 | 确认创建。完成后告诉我你实际新建了哪个文件,不要做其他改动。 |
执行结束后,回到 Windows 文件资源管理器。
正常情况下,dsh-first-run 中会多出一个 项目概览.md。用记事本或任意 Markdown 编辑器打开它,检查内容是否和刚才确认的版本一致。
这里的“正常情况下”只是待验证的预期。最终是否创建成功、是否弹出权限确认、用了多久、有没有多改文件,都要以真实操作记录为准。
以后给 Harness 下任务,记住这个公式
任务越模糊,Agent 自己补充的假设就越多。
普通用户不需要学习复杂的提示词技巧,只要把下面五件事写清楚:
- 目标:最后想得到什么;
- 范围:允许查看或修改哪里;
- 限制:哪些事情绝对不能做;
- 步骤:是否要先给计划、等待确认;
- 验收:完成后如何检查。
可以复制这份模板:
1 | 目标:XXX |
四个普通人能直接改写的用法
整理一批文档
1 | 只读取“本周资料”文件夹,按主题列出文件清单和每份文件的核心内容。 |
检查知识库
1 | 只读取当前 Markdown 知识库,找出重复主题、可能失效的内部链接和缺少索引的文件。 |
帮项目补说明文档
1 | 阅读当前项目,拟一份 README 大纲。 |
帮忙定位报错
1 | 检查当前项目的报错。 |
三条安全边界,比提示词更重要
第一条:工作区里放什么,它就可能看到什么
本地启动不等于模型离线。
只要你连接的是云端模型 API,模型请求仍会发送给相应提供方,工作区中被读取并放入模型上下文的内容,也可能随请求发送。
所以不要把密码、私钥、客户数据、身份证件、私人照片或公司机密放进测试工作区。
第二条:出现确认框,先看动作
当操作在当前权限策略下需要审批时,Web UI 会先询问用户。
审批机制只是最后一道提醒,看到确认框时,要看它准备读取哪里、修改什么、执行哪条命令。
第三条:重要目录先备份
以后把 Harness 用到真实项目时,至少满足一项:
- 项目已经提交 Git;
- 文件有可恢复备份;
- 使用的是可以随时删除的副本。
Agent 说“任务完成”只代表它结束了当前操作,不代表每一处修改都正确。最终还要由人检查文件和差异。
模型和会话
更换模型
在“设置 → 模型”中可以配置 DeepSeek,也可以添加其他提供方或 OpenAI 兼容接口。
“提供方”就是提供模型 API 的服务商。
第一次上手,先把 DeepSeek 官方模型跑通,不必同时配置 Anthropic、OpenAI、Azure 或其他网关。
选择新模型后,它会成为新会话的默认模型。
已经发送过消息的旧会话会保留原来的模型记录,切换后没有变化时,新建会话再试。
自定义提供方
公司网关或自建模型可以通过“添加自定义提供方”接入。
需要填写 Provider ID、Base URL、API 协议、凭据和模型名称。
把这些词翻译一下:
- Provider ID:这条模型线路的内部名字,要用小写,保存后不能直接改名;
- Base URL:模型接口地址;
- API 协议:Harness 应该用哪种格式和模型通信;
- 模型名称:服务端实际提供的模型 ID。
普通用户没有自建模型时,可以跳过整段。
图片输入
官方模型配置文档写明,DeepSeek 自身的 chat-completions 路由按纯文本处理,不能靠修改 Harness 设置把它变成图片模型。
如果上传图片时直接被拒绝,先检查当前模型是否真的声明并支持图片输入。
下面是进阶区,根据能力学习
完成 Web UI、只读任务和单文件写入测试后,你已经走通了 Harness 的基础用法。
后面的 Headless、Python SDK 和插件开发,是给自动化或开发需求准备的。
Headless:不打开网页,直接跑一次任务
Headless 可以理解成“无界面模式”。
它接收一条任务,运行一个新的持久会话,打印最终回答,然后退出。
在目标项目文件夹中运行:
1 | npx @deepseek-ai/dsh --profile headless "只读分析当前项目,并概括主要目录和待办。不要修改文件。" |
命令从哪个文件夹运行,哪个文件夹就是默认工作区,没有浏览器确认过程时,更要提前写清范围和限制。
Python SDK:把 Harness 接进自己的程序
SDK 可以理解成给程序员使用的一套调用接口。
开发者可以在 Python 代码中启动 Harness、指定工作区、运行任务并读取结果。
当前官方快速上手文档列出的支持环境是:
- Linux x64;
- Linux arm64;
- macOS 14 及以上的 arm64。
官方内置示例依赖 POSIX 终端,并明确说明不支持 Windows agent。
Windows 普通用户先使用 Web UI 或 Headless,不要照抄 Python 示例排错。
插件:给 Harness 增加一个功能
先说清楚,最近 GitHub 上确实冒出了不少带 dsh-plugin 标签的项目,但这个标签里也混有和 Harness 无关的仓库。
不要把标签数量当成“已经有多少可放心安装的插件”。
下面只介绍我能核对到安装说明、重启方法和卸载命令的社区项目;它们不是 DeepSeek 官方插件,也不等于经过安全审计。
插件可以理解成给 Agent 安装一个小扩展:
“
它可能多一个界面按钮、一个搜索工具,或一种新的工作方式。它不是浏览器扩展,更不是“装了就一定变聪明”的魔法包。
这里有两个够用的词:
- Profile:一套可以直接启动的 Harness 组合。我们前面启动的是
web,所以插件都要装进web这个组合; - Bundle:插件作者打包好的一组插件和配置。普通用户不用自己制作它。
先装一个社区插件市场:把“找插件”放到界面里
对于第一次装插件的人,我更建议先装 dsh-market。
它本身就是一个社区插件,装好后会在 Harness 的“设置”里增加“Plugin Market(插件市场)”入口,用来查看插件介绍、来源和安装过程。
它的优点不是“绝对安全”,而是把原本要在命令行里辨认的包名、来源和安装进度放进了界面。
市场作者也明确提醒:列表收录不等于背书,插件仍是第三方代码。
按下面连续操作。
前提是你已经按本文前面的步骤成功启动过一次 dsh web。
第 1 步:先停止正在运行的 Harness。
回到运行 npx @deepseek-ai/dsh web 的 PowerShell 窗口,按一次 Ctrl + C。看到命令可以再次输入,就表示服务已停。
第 2 步:仍在你的测试文件夹里,安装插件市场。
1 | npx @deepseek-ai/dsh plugin --profile web add dshmarket |
社区项目的原始文档通常把这条命令简写成 dsh plugin --profile web add dshmarket。
本文前面没有要求你全局安装 dsh,所以统一在前面加上 npx @deepseek-ai/dsh;后面的插件命令也沿用这个写法。
安装过程中,如果终端提示要运行某个依赖的构建脚本,不要凭感觉一路确认。
先记下包名,到插件项目的 GitHub 页面查看它为什么需要该脚本;不确定就先按 Ctrl + C 取消。
市场项目说明它会默认拦截这类脚本并要求显式允许,但这不是替你审计代码。
第 3 步:重新启动 Harness。
1 | npx @deepseek-ai/dsh web |
重新在浏览器打开本地页面后,进入设置 → Plugin Market(插件市场)。如果页面没有新入口,不要只刷新网页;先确认你停掉并重新启动的是 web 服务。
第 4 步:第一次只做“查看”,不要急着安装。
打开某个插件的详情页,先检查四件事:
- 它具体增加什么功能,而不是只看名字;
- 作者和源代码仓库是谁;
- 安装时是否要求额外允许构建脚本;
- 它会不会读取文件、调用网络、操作终端,或者要求你填写额外的 Key。
尤其是远程 SSH、自动执行终端命令、云同步、上传文件和通知类插件,第一次不要装进装有真实资料的工作区。
先在本文创建的 test1 测试文件夹里试。
从一个功能开始,不要直接装“全家桶”
有一个开源项目,提供任务看板、Git 图、皮肤等 Web UI 扩展,并且支持单独安装。
它同时记录了不同 pnpm 安装布局、依赖构建脚本和版本门槛带来的排障方式。
这恰好说明一个原则:功能越多,依赖越多,普通用户的排错成本也越高。
所以不建议第一次就安装它的 dsh-web-ui-all 聚合包。
我这里做一个简单演示。
观察发现UI已经发生了改变,右下角也新增了一个桌宠。
后续,等你已能在插件市场里判断来源、会重启服务、会卸载后,再从单个插件项目的 README 复制对应包名安装。
不要使用它文档里的“从 GitHub 仓库安装(开发调试)”方案:那需要 git、pnpm、克隆源码和手动构建,是给插件开发和排错准备的,不是普通用户的安装路径。
不想用了,怎样卸载和回退
插件装错或不喜欢,先停掉 dsh web,然后用 remove 卸载。
比如卸载上面两个演示插件:
1 | npx @deepseek-ai/dsh plugin --profile web remove dsh-find-plugin |
之后重新启动:
1 | npx @deepseek-ai/dsh web |
如果卸载后界面仍有残留,不要反复安装覆盖。先重启服务;仍有问题时,可以执行下面这条命令查看 web 组合是否还挂着插件配置:
1 | npx @deepseek-ai/dsh --profile web --dump-config |
这份输出是排错信息,不要原样发到公开群里;配置和路径信息可能泄露你电脑的使用环境。
插件市场还提供了备份、导出日志等功能,但它的备份可能包含 Profile 配置甚至凭据形态,没看清提示前不要上传到公开网盘或群聊。
最后再强调一次:官方插件机制支持从本地、npm 和 GitHub 等来源组合插件;
从 GitHub 安装时,构建脚本可能在 Agent 沙箱之外直接运行。
只安装可信来源;真要从 GitHub 安装,最好固定到具体 commit,而不是永远追踪最新代码。
想学习自己开发插件,再从官方的插件教程开始。
常见使用问题
提示 UNKNOWN_MODEL
当前会话找不到对应模型,重新选择已配置的模型,或者把缺少的模型添加到自定义提供方。
获取模型列表返回 401
先检查 API Key。
自定义提供方的模型发现会调用 GET /models;目标服务没有提供这个接口时,需要手动填写模型。
换模型后,旧会话仍在用原模型
这是会话记录的设计,新建会话,再选择新模型。
图片在发送前被拒绝
当前模型没有声明图片能力,DeepSeek 自身的 chat-completions 路由是纯文本,不能通过普通设置改变。
Windows 上 Python 示例无法运行
当前官方示例不支持 Windows agent,改用 Web UI、Headless,或者换到官方列出的 Linux、macOS 环境。
看到这里,相信你已经可以基本上掌握 Harness 的使用了。
现在再把这些词拆开看,其实也没有那么难懂。
安装一个运行环境,准备一把 API Key,在空文件夹里打开本地页面,再明确告诉它:这一次只读,别改。
普通人真正需要学会的,不是背下多少命令。
而是在 AI 准备动手前,习惯先告诉他,工作目录是哪儿,准备读取哪些文件,要做的操作是什么,如何停止一个任务。
DeepSeek 这次开源的,不只是又一个聊天框。
它是把一个会做事的助手,放到了你电脑上,可以让更多的人体验到AI来帮你操作电脑文件的便捷。
第一轮,别急着把它塞进正在赶工的项目,也别急着装一堆插件。
先让它待在一个随时可以清空的小文件夹里,完成一件你知道正确答案的小事。
最后想说的话
Harness 或许是一个非常有趣的的系统,里面的插件也很不错。
但我认为,有个缺点:对普通用户不友好。
或许,DeepSeek 团队有自己想法。
Harness 也许不是一个现在就能让所有人用得舒服的产品。
插件应该怎么组合,AI Agent 应该如何扩展,模型和工具之间又应该建立怎样的关系。
这些问题,可能还没有标准答案。
因为没有答案,所以才值得有人去尝试。
很多真正重要的东西,在最开始的时候,本来就不会很好用。
技术需要时间,产品需要迭代,生态更需要一群人不断试错。
如果你把 DeepSeek Harness 当成一个面向普通用户的成熟产品,它确实还有很长的路要走。
不妨把它看成 DeepSeek 对未来 AI Agent 形态的一次探索。
或许就变得有意思了。
至少,他们又往前走了一步。
就像他们的 Slogan 所说的:
探索未至之境。
希望 DeepSeek 继续保持这份探索的勇气。
也希望有一天。
我们现在觉得复杂、晦涩、难以上手的东西。
能够真正变成普通人也可以轻松使用的工具。
这条路可能还很远。
但总要有人先出发。


































