DeepSeek Harness 实操教程：从零安装到安全地让 AI 操作你的文件夹

很多人只在 DeepSeek 网页版里和 AI 聊天，却未曾想过 AI 能直接走进你电脑的指定文件夹，自主读取文件、制定计划，并在获得允许后协助修改内容。DeepSeek 发布 V4-Pro 之后，将实现这一能力的 Agent 框架开源，即 DeepSeek Harness（简称 dsh）。

当前官方将该版本标注为“技术预览”，意味着虽可正常安装研究，但仍处于快速迭代期，后续可能存在不兼容旧配置的更新。初次接触的朋友，建议先使用空的测试文件夹练手，切勿急于将整个工作目录交由其操作。

一、先搞懂：Harness 是什么，入门要认识哪几个关键词

Harness 直译为“挽具”或“套具”，在 AI 领域可理解为一套连接模型、工具与工作环境的的中枢系统：模型负责思考决策，工具负责落地执行，工作区决定 AI 的访问范围。三者结合，AI 才能从“只会告诉你怎么做”进化为“在指定范围内帮你动手做”。

DeepSeek Harness 自带 Web UI，即在浏览器中打开的操作页面，外观类似常用聊天工具。整个程序底层运行于本地电脑，浏览器仅提供操作窗口。官方提出的“一切皆插件”理念，普通用户无需深究底层逻辑，只需理解为“可随时扩展新能力”即可，无论是模型、文件操作、命令行还是会话工具，均可通过模块自由组合。至于 Cordis、Bundle、Profile 等专业术语，基础安装阶段无需关注，掌握以下六个关键词即可顺利走完安装流程：

1. Node.js
   ：运行 dsh 必需的基础环境，可视作 dsh 的“发动机”，只需安装，无需专门学习编程。
2. PowerShell
   ：Windows 系统自带的命令窗口，全程仅需复制粘贴几条命令，无需手写代码。
3. npm
   ：Node.js 自带的软件包管理工具，负责下载和管理 dsh 所需的程序文件。
4. npx
   ：随 Node.js 自动安装，可临时下载并运行 dsh，因此本教程无需提前手动安装 Harness，十分便捷。
5. API Key
   ：一串通常以 sk- 开头的密钥，相当于调用 DeepSeek 模型接口的通行证。Harness 需凭此请求模型服务，密钥务必保密，且调用模型会产生相应的 API 用量费用。
6. 工作区
   ：即允许 Harness 处理的电脑文件夹。AI 读取文件、新建文档、执行命令等所有操作均限定在此目录内进行。

掌握这六个词，基础准备即告完成，接下来从零开始一步步安装。

二、八步走通从零安装，新手也能一次成功

第 1 步：安装符合要求的 Node.js

打开浏览器搜索 Node.js 进入官网下载页面。截至 2026 年 8 月 15 日，Node.js 官网提供的长期支持版（LTS）为 24.x，而 DeepSeek Harness 当前源码要求 Node.js 版本为 22.19.0 及以上的 22.x，或 24.0.0 及以上版本。普通用户直接选择 24.x LTS 即可，该版本比测试版更稳定省心。

Windows 用户下载对应安装包后，双击打开安装向导，无特殊需求保持默认选项下一步即可。安装完成后，务必关闭所有已打开的 PowerShell 或终端窗口，否则旧窗口无法识别新环境。

重新打开 PowerShell 验证安装：点击 Windows 开始菜单，输入 PowerShell，打开"Windows PowerShell"，依次粘贴下面两条命令，每粘一条按一次回车：

node --version
npm --version

第一条命令输出 Node.js 版本号，第二条输出 npm 版本号。版本号无需与他人完全一致，只要第一条输出为 v24... 或不低于 v22.19.0，第二条能正常输出版本数字，即表示过关。若提示“无法将 node 识别为命令”，请关闭并重新打开 PowerShell，若仍不行则重新安装 Node.js 并重启电脑。

第 2 步：准备 DeepSeek API Key

打开 DeepSeek 开放平台的 API Key 页面，登录账号后找到创建入口，新建密钥并复制保存（密钥均以 sk- 开头）。

以下三点极易混淆，请务必记清：

• API Key 并非 DeepSeek 网页版的账号密码，二者不可通用；
• Harness 调用的是 DeepSeek 开放 API，按实际用量计费，并非免费；
• 若账户余额不足，调用将返回 402 错误，建议创建密钥后顺便检查余额，具体价格以官方页面实时通知为准。

密钥可暂存于密码管理器或安全位置，切勿将完整密钥发送给他人或传播带完整密钥的截图。

第 3 步：创建专属测试文件夹

为 Harness 准备一个单独的工作区。打开 Windows 文件资源管理器，在易于查找的位置（如“文档”文件夹）新建一个名为 test1 的文件夹，并双击进入。首次测试务必使用空文件夹，以防误操作影响其他日常文件。

第 4 步：在测试文件夹里直接打开 PowerShell

保持文件资源管理器停在 test1 文件夹内，点击窗口上方地址栏，选中原有路径文字，直接输入 powershell 后按回车。Windows 将自动打开一个当前路径已定位到 test1 的 PowerShell 窗口。后续操作均在此窗口进行，请勿关闭。

第 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 窗口，否则网页将失去连接。打开 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 在手动添加工作区前不会默认选中任何目录，因此必须手动选择。选中后，原本灰色的消息输入框将解锁。

安装结束前，请检查以下四点，全部满足即表示安装配置成功：

1. PowerShell 里的 dsh 服务正常运行；
2. 浏览器能正常打开 Harness 页面无报错；
3. DeepSeek 模型的 API Key 已保存且处于可选择状态；
4. 当前工作区显示为 test1，消息输入框可正常点击输入。

四条件均满足，即可正式使用。

三、安装完成后，怎么关闭和下次启动

Harness 运行时，PowerShell 窗口必须保持打开。若要停止服务，回到 PowerShell 按 Ctrl + C 即可，直接关闭窗口也能停止。关闭服务后，浏览器页面无法连接属正常现象。

下次使用时，无需重装 Node.js，只需重新进入 test1 文件夹，在地址栏输入 powershell 打开窗口，运行命令：

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 端口启动，命令为：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 为空，先放入两个简单测试文件验证 AI 工作状态。

第一步：准备测试材料

打开 Windows 记事本，新建文件，粘贴以下内容，另存到 test1 文件夹，命名为 说明.txt：

这是我的第一个 Harness 测试文件夹。目标是测试 AI 能否读取文件、整理待办，并在确认后生成一份项目概览。

再新建一个记事本，粘贴以下内容，同样保存到 test1，命名为 待办.txt：

1. 了解 Harness 是什么
2. 完成基础安装
3. 测试只读分析
4. 测试生成项目概览

如此便拥有了一组已知正确答案的测试材料，可直接对照原文检查 AI 总结的准确性。

第一个任务：测试只读能力，不允许修改任何内容

回到 Harness 页面，新建会话，完整粘贴以下提示词：

请先只读取当前工作区中的文件。完成以下任务：

1. 列出你实际读取到的文件名；
2. 用三句话概括这个测试项目的目标；
3. 把「待办.txt」里的事项按顺序整理出来；
4. 列出你无法确认的信息。
   限制：

• 不要创建、删除、移动或修改任何文件；
• 不要安装软件或依赖；
• 不要执行会改变电脑环境的命令；
• 如果信息不足，直接说明，不要猜测。

提示词详尽并非啰嗦，因首次任务旨在确认三件事：AI 能否看到正确文件、是否遵守只读要求、回答内容是否与原始文件一致。

若页面弹出操作确认框，务必看清 AI 拟执行的操作。读取两个文本文件无需安装依赖或修改其他目录，若 AI 请求超出任务范围，请直接拒绝并要求解释。任务完成后，不仅要看回答是否顺畅，还需打开 说明.txt 和 待办.txt，逐条核对文件名、项目目标和待办顺序。

第二个任务：确认计划后，测试新建文件

只读测试无误后，继续测试写入能力，发送以下内容：

根据刚才读取到的内容，准备在当前工作区新建「项目概览.md」。文件只包含四部分：

1. 项目目标；
2. 已有文件及用途；
3. 当前待办；
4. 无法确认的信息。
   先把执行计划和准备写入的完整内容发给我。在我回复「确认创建」之前，不要写入文件。不要修改「说明.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