夜雨聆风很多人只在 DeepSeek 网页版里和 AI 聊天，从来没想过 AI 能直接走进你电脑的指定文件夹，自己读文件、整计划、得到允许后还能帮你改内容。DeepSeek 发布 V4-Pro 之后，把这套能实现这个能力的 Agent 框架开源了，它就是 DeepSeek Harness，大家通常简称它为 dsh。
当前官方把这个版本标注为技术预览，意思是它已经可以正常安装研究，但还在快速迭代更新，后续不排除出现不兼容旧配置的更新。所以第一次接触的朋友，建议先拿空的测试文件夹练手，别急着把自己整个工作目录都交给它操作。
一、先搞懂：Harness 是什么，入门要认识哪几个关键词
Harness 直译是挽具、套具的意思，放到 AI 领域，可以理解成一套把模型、工具、工作环境连接起来的中枢系统：模型负责思考决策，工具负责落地执行，工作区决定 AI 能访问哪些内容。把这三样接在一起，AI 才能从「只会告诉你怎么做」，变成「在指定范围内帮你动手做」。
DeepSeek Harness 自带了 Web UI，也就是可以在浏览器里打开的操作页面，外观和我们平时用的聊天工具差不多，而且整个程序的底层都运行在你自己的电脑上，浏览器只是给你提供一个操作窗口而已。官方提到的「一切皆插件」，普通用户不需要深究底层逻辑，只要理解成「后续可以随时给它加新能力」就够了，不管是模型、文件操作、命令行还是会话工具，都能通过模块自由组合。至于 Cordis、Bundle、Profile 这些专业术语，基础安装阶段完全不需要管，认识下面六个词就足够顺利走完安装流程：
- Node.js
：运行 dsh 必需的基础环境，可以把它理解成 dsh 的发动机，你只需要安装它，不需要专门学编程。 - PowerShell
：Windows 系统自带的命令窗口，我们整个过程只需要复制粘贴几条命令，不需要自己手写代码。 - npm
：Node.js 自带的软件包管理工具，负责帮你下载和管理 dsh 需要的程序文件。 - npx
：会跟着 Node.js 一起自动安装，它可以临时下载并运行 dsh，所以这篇教程不需要你提前手动安装 Harness，非常省心。 - API Key
：一串通常以 sk-开头的密钥，相当于调用 DeepSeek 模型接口的通行证，Harness 需要拿着它去请求模型服务，这个密钥一定要保密，而且调用模型会产生对应 API 用量费用。 - 工作区
：就是你允许 Harness 处理的电脑文件夹，AI 读取文件、新建文档、执行命令，所有操作都只会在这个目录里进行。
认识这六个词，基础准备就完成了，接下来我们从零开始一步步安装。
二、八步走通从零安装，新手也能一次成功
第 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 或者终端窗口全部关掉，旧窗口识别不到刚安装的新环境。
接下来我们重新打开 PowerShell 验证安装：点击 Windows 开始菜单，输入 PowerShell，打开「Windows PowerShell」，然后依次粘贴下面两条命令，每粘一条按一次回车：
node --versionnpm --version
第一条命令会输出你安装的 Node.js 版本号，第二条输出 npm 的版本号。你的版本号不需要和别人完全一致，只要第一条输出是 v24...，或者不低于 v22.19.0，第二条能正常输出版本数字，这一步就过关了。如果提示「无法将 node 识别为命令」，先关了 PowerShell 重新开一次，还是不行的话就重新安装 Node.js，装完重启电脑再检查。
第 2 步：准备 DeepSeek API Key
接下来我们准备调用模型需要的密钥，打开 DeepSeek 开放平台的 API Key 页面，登录你的开放平台账号，找到创建 API Key 的入口，新建一个密钥之后复制保存好，密钥都是以 sk- 开头的。
这里有三个最容易混淆的点，一定要提前记清楚：
API Key 不是 DeepSeek 网页版的账号密码，二者不能通用； Harness 调用的是 DeepSeek 的开放 API，会按照 API 实际用量计费，不是免费的； 如果账户余额不足，调用会返回 402 错误，所以创建完密钥顺手检查一下账户余额更稳妥，具体价格以官方页面实时通知为准。
密钥可以暂时保存在密码管理器或者安全的临时位置，下一步要用到，千万不要把完整密钥发给别人，也不要把带完整密钥的截图到处发。
第 3 步：创建专属测试文件夹
我们给 Harness 准备一个单独的工作区，打开 Windows 文件资源管理器，找一个你容易找到的位置，比如「文档」文件夹，新建一个文件夹，命名为 test1，然后双击进入这个空文件夹。第一次测试一定要用空文件夹，哪怕设置错了或者误操作，也不会影响你电脑里的其他日常文件。
第 4 步：在测试文件夹里直接打开 PowerShell
保持文件资源管理器停在 test1 文件夹里，点击窗口上方显示路径的地址栏，把地址栏里原来的路径文字选中，直接输入 powershell 然后按回车，Windows 就会自动打开一个 PowerShell 窗口，而且这个窗口的当前工作路径已经自动定位到 test1 了。接下来的操作就在这个窗口进行，不要关它。
第 5 步：运行 Harness 本地服务
把下面这一整行命令复制到 PowerShell 里，然后按回车：
npx @deepseek-ai/dsh web
我们把这条命令拆开来解释，方便你理解：
npx：负责帮你临时下载并运行程序，不需要你提前全局安装； @deepseek-ai/dsh：就是 DeepSeek 官方发布的 Harness 程序包； web：指定启动带浏览器界面的 Web UI 模式。
第一次运行需要下载所有相关文件，等待时间会比后续运行长一些，如果终端提示你确认下载或者安装，按照屏幕提示确认就可以，不同版本的 npm 提示文字可能会有区别。等待的时候不要反复粘贴命令，也不要关掉窗口，等到终端打印出访问地址，就说明本地服务已经启动成功了，官方默认的访问地址是：
http://127.0.0.1:3080
这里的 127.0.0.1 指的就是你现在用的这台电脑，这个网址看起来是普通网址，实际连接的是你本机运行的 Harness 服务，不会对外网传输内容（除了模型 API 请求本身）。
第 6 步：浏览器打开 Harness 操作页面
这里一定要注意：不要关掉 PowerShell 窗口，只要 PowerShell 关了，网页就会失去连接。打开你常用的 Chrome、Edge 或者其他浏览器，把终端打印的地址复制到浏览器地址栏，默认就是 http://127.0.0.1:3080，按回车之后就能进入 DeepSeek Harness 的 Web UI 了。
如果浏览器显示无法访问，先回到 PowerShell 看看程序是不是还在运行，终端有没有红色的错误提示。到这一步，Harness 已经在你电脑上跑起来了，但还没配置模型，也没选工作区，所以还不能开始对话。
第 7 步：配置 DeepSeek 模型
第一次打开网页，会自动提示你添加 API Key，后续如果要改的话，也可以在设置里调整。操作路径是：打开 Harness 页面的「设置 → 模型」，找到 DeepSeek 对应的卡片，把我们第二步准备好的 API Key 粘贴进去，然后保存就可以。保存之后不需要重启 Harness，新的配置会在下次请求模型的时候自动生效。
如果页面要求你选择具体模型，从列出的 DeepSeek 模型里选一个就可以，模型名称会随着官方服务更新变化，以你页面上实际显示的选项为准。API Key 保存之后，页面只会显示脱敏后的信息，不会再展示完整密钥，密钥会保存在 $DSH_HOME/.credentials.yaml 这个路径里，普通用户不需要去修改这个文件。
第 8 步：选中我们提前准备的测试文件夹
模型配置好之后，回到 Harness 主页，点击「选择工作区」，添加然后选中我们刚才创建的 test1 文件夹。很多人会疑惑为什么还要再选一次，其实「从哪个文件夹启动 Harness」和「当前会话允许操作哪个工作区」是两层独立设置，新的 Web UI 在你手动添加工作区之前，不会默认选中任何目录，所以必须手动选一次。选中之后，原来不能用的消息输入框就会解锁可以输入了。
安装结束前，我们再检查四个点，都满足就说明安装配置成功了：
PowerShell 里的 dsh 服务还在正常运行； 浏览器能正常打开 Harness 页面，没有报错； DeepSeek 模型的 API Key 已经保存，处于可选择状态； 当前工作区显示为 test1，消息输入框可以正常点击输入。
四个条件都满足，你就可以正式开始用了。
三、安装完成后，怎么关闭和下次启动
Harness 运行的时候，PowerShell 窗口必须保持打开，想要停止服务的话，回到 PowerShell 按 Ctrl + C 就可以，直接关掉窗口也能停止。关闭服务之后，浏览器里的 Harness 页面会无法连接，这是正常现象。
下次使用的时候，不需要重新安装 Node.js，只要重新进入 test1 文件夹，在地址栏输入 powershell 打开窗口，然后运行命令：
npx @deepseek-ai/dsh web
打开终端输出的本地地址就可以了，模型和密钥的配置已经保存在 dsh 的配置目录里，正常情况下不需要每次重新填写。需要提醒的是，当前产品还是技术预览版，如果升级后配置逻辑变了，以新版官方文档为准。
四、安装卡住了？按这个顺序排查，大部分问题都能解决
安装的时候不要乱改设置，对照下面的步骤一步步排查，找到问题对应解决：
node --version没有输出结果：说明 Node.js 没安装成功，或者旧的 PowerShell 没刷新环境变量，先关了 PowerShell 重新开，还是不行就重新安装 Node.js，装完重启电脑再试。 npm --version没有输出结果：npm 是跟着 Node.js 一起安装的，如果 Node 正常但 npm 用不了，直接重新运行 Node.js 安装程序就能解决。 npx @deepseek-ai/dsh web一直下载失败：先看终端给出的具体错误，常见原因是网络问题、npm 下载源问题或者代理设置问题，不要照着网上的旧教程随便安装同名 Python 包，解决不了官方 npm 包的下载问题。 - 默认 3080 端口的页面打不开
：先确认 PowerShell 没关，然后看终端实际输出的地址对不对，如果提示 3080 端口被其他程序占用，可以换 8080 端口启动，命令是： npx @deepseek-ai/dsh --profile web --port 8080，然后访问终端输出的新地址就可以。 - 页面能打开，但输入框是灰色不能用
：依次检查三个点：API Key 有没有保存、有没有选中一个可用的模型、有没有添加并选中工作区，官方 Web UI 就是这么设计的，没选工作区就会禁用输入框。 - 模型提示 401 或者
MISSING_CREDENTIAL：401 一般是密钥认证失败，检查一下 API Key 有没有复制完整； MISSING_CREDENTIAL是当前模型找不到可用的凭据，回到「设置 → 模型」重新保存密钥就可以。 - 模型提示 402
：DeepSeek 的错误码里 402 就是余额不足，去开放平台检查余额和充值状态就可以。
五、第一次实操：先测只读，再测写入，稳扎稳打
安装完成不要急着拿真实项目上手，现在 test1 还是空的，我们先放两个简单的测试文件，验证 AI 能不能正常工作。
第一步：准备测试材料
打开 Windows 记事本，新建文件，粘贴下面这段内容，然后另存到 test1 文件夹，命名为 说明.txt：
这是我的第一个 Harness 测试文件夹。目标是测试 AI 能否读取文件、整理待办，并在确认后生成一份项目概览。
再新建一个记事本，粘贴下面这段内容，同样保存到 test1，命名为 待办.txt：
了解 Harness 是什么 完成基础安装 测试只读分析 测试生成项目概览
这样我们就有了一组完全知道正确答案的测试材料，AI 总结得对不对，我们可以直接对照原文检查，非常方便。
第一个任务：测试只读能力，不允许修改任何内容
回到 Harness 页面，新建会话，把下面这段提示完整粘贴进去：
请先只读取当前工作区中的文件。完成以下任务：
列出你实际读取到的文件名； 用三句话概括这个测试项目的目标； 把「待办.txt」里的事项按顺序整理出来； 列出你无法确认的信息。限制：
不要创建、删除、移动或修改任何文件； 不要安装软件或依赖； 不要执行会改变电脑环境的命令； 如果信息不足，直接说明，不要猜测。
这段提示词写得这么完整，不是故意啰嗦，因为第一次任务的目标不是考 AI，是帮我们确认三件事：AI 能不能看到正确的文件、能不能遵守我们说的只读要求、回答的内容对不对得上原始文件。
如果页面弹出操作确认框，一定要先看清楚 AI 准备做什么，读取两个文本文件根本不需要安装依赖，也不应该修改其他目录，如果 AI 请求的操作超出了任务范围，直接拒绝，让它解释原因就可以。任务完成之后，不要只看回答顺不顺，打开 说明.txt 和 待办.txt，逐条核对文件名、项目目标和待办顺序对不对。
第二个任务：确认计划后，测试新建文件
只读测试结果没问题，我们再测写入能力，继续给 AI 发下面这段内容：
根据刚才读取到的内容，准备在当前工作区新建「项目概览.md」。文件只包含四部分：
项目目标； 已有文件及用途； 当前待办； 无法确认的信息。先把执行计划和准备写入的完整内容发给我。在我回复「确认创建」之前，不要写入文件。不要修改「说明.txt」和「待办.txt」，也不要创建其他文件。
AI 给出计划之后，你先自己检查内容，确认没有编造内容、没有漏项、也没有准备修改其他原有文件，再回复「确认创建」，AI 完成之后会告诉你它新建了哪个文件，不会做其他多余改动。
执行结束之后，打开 Windows 文件资源管理器的 test1 文件夹，正常情况下会多出一个 项目概览.md，用记事本或者任意 Markdown 编辑器打开，检查内容是不是和刚才确认的版本一致。最终能不能创建成功、有没有弹出权限确认、用了多长时间、有没有多改其他文件，都要以你实际操作的结果为准，我们这个测试就是帮你验证整个流程的。
六、给 Harness 发任务的通用公式，不用学复杂提示词
以后给 Harness 下任务，记住这个规律：任务越模糊，AI 自己补充的假设就越多，出错的概率也越高。普通用户不需要学复杂的提示词技巧，只要把下面五件事写清楚就够了：
- 目标
：你最后想得到什么结果； - 范围
：允许 AI 查看或者修改哪些内容； - 限制
：哪些事情是绝对不能做的； - 步骤
：要不要先出计划、等你确认再动手； - 验收
：完成之后怎么检查结果对不对。
你可以直接复制这份模板用：
目标：XXX 允许范围：只处理XXX 禁止事项： - 不要XXX； - 不要XXX 执行方式：先检查现状并给出计划。涉及写文件、删除内容、安装软件或运行高风险命令时，先等待我确认。 交付物：XXX 验收条件：XXX 遇到不确定信息时直接列出，不要自行猜测。七、四个普通人直接能用的场景，改一改就能用
1. 批量整理文档
只读取「本周资料」文件夹，按主题列出所有文件的清单，以及每份文件的核心内容。先输出整理建议，不要移动、重命名或者删除任何原有文件。
2. 检查个人知识库
只读取当前的 Markdown 知识库文件夹，找出重复主题的笔记、可能失效的内部链接、没有加入索引的文件。先生成检查报告，不要修改任何原有笔记。
3. 给项目补写说明文档
读取当前项目的所有文件，拟一份 README 大纲，说明大纲每一部分的信息来自哪个源文件。先发大纲给我确认，不要直接修改原有的 README.md。
4. 帮你定位项目报错
检查当前项目的报错信息，先尝试复现问题说明原因，只给修复方案，不要直接修改代码。如果需要安装依赖或者修改环境，先问我确认再执行。
八、三条安全边界，比提示词技巧更重要
这三条一定要记住，能避免绝大多数风险：
第一条：工作区里放什么，AI 就能看到什么，敏感内容绝对不要放。很多人以为本地启动就是模型离线运行，其实不对，只要你连接的是云端模型 API，请求内容都会发给模型提供方，工作区里被 AI 读取、放到模型上下文的内容，也会跟着请求一起发送。所以绝对不要把密码、私钥、客户数据、身份证件、私人照片、公司机密放到 Harness 的工作区里。
第二条：弹出确认框的时候，先看清楚 AI 要做什么再点确认。当 AI 要执行的操作符合当前权限的审批要求时，Web UI 会提前问你，这个审批只是最后一道提醒，不是百分百安全保障，所以看到确认框一定要看清楚：AI 准备读哪个位置、修改什么文件、执行什么命令，没问题再点确认。
第三条：用在真实项目之前，一定要先备份。以后把 Harness 用到自己的真实项目上，至少满足一个条件：项目已经提交到 Git 能回滚、所有文件已经做好可恢复备份、用的是可以随时删掉的项目副本。AI 说「任务完成」只代表它结束了当前操作，不代表它所有修改都是对的，最终结果一定要你自己检查。
九、模型配置相关问题，一次说清
更换模型
在「设置 → 模型」里，你不仅可以配置 DeepSeek 的模型，还可以添加其他服务商的模型，或者兼容 OpenAI 接口的自定义模型，服务商就是提供模型 API 的机构。第一次上手先把 DeepSeek 官方模型跑通就行，不用一下子配置 Anthropic、OpenAI、Azure 这些其他模型。选好新模型之后，它会成为所有新会话的默认模型，旧会话会保留原来的模型设置，如果切换之后没变化，新建一个会话再试就可以。
自定义模型提供方
如果你有公司内部的模型网关，或者自己搭建了本地模型，可以通过「添加自定义提供方」接入，需要填写五个信息，给你翻译一下每个信息是什么意思：
- Provider ID
：这个模型线路的内部名称，必须用小写，保存之后不能直接改； - Base URL
：你的模型接口地址； - API 协议
：告诉 Harness 要用什么格式和你的模型通信； - 模型名称
：服务端实际提供的模型 ID。
普通用户没有自建模型，直接跳过这部分就可以。
图片输入问题
官方模型配置文档明确说明，DeepSeek 自身的 chat-completions 路由默认按纯文本处理，没办法靠改 Harness 设置把它改成支持图片的模型，如果上传图片被拒绝，先检查你当前用的模型是不是真的支持图片输入。
十、进阶玩法：给有需求的用户准备的内容
走完前面的 Web UI 安装、只读测试、写入测试，你已经掌握了 Harness 的基础用法，接下来的 Headless 模式、Python SDK、插件都是给有自动化需求或者开发需求的用户准备的，普通用户用不到可以直接跳过。
Headless：无界面模式，直接跑完任务退出
Headless 就是无界面模式，它会接收你给的任务，新建一个持久会话，跑完任务输出结果之后直接退出，不需要打开浏览器。使用方法就是在目标项目文件夹里运行命令：
`npx @deepseek-ai/dsh --profile headless
