DeepSeek Harness 实操教程：从安装到首次任务

在 DeepSeek 发布 V4-Pro 后，官方又开源了 Agent 框架 DeepSeek Harness（简称 dsh）。它把模型、工具和本地工作区连接起来：模型负责思考，工具负责执行命令，工作区决定 AI 能接触哪些文件。当前版本仍处于技术预览阶段，可以安装和试用，但后续更新可能不兼容旧配置，所以第一次使用务必放到独立的测试文件夹中。

Harness 是什么

Harness 直译是“挽具”，在 AI 领域可以理解为一套将模型、工具和工作环境连接起来的系统。模型负责思考，工具负责行动，工作区决定它能看到什么。三样东西接好，AI 才能从“告诉你怎么做”走到“在规定范围内帮你做”。

DeepSeek Harness 自带一个 Web UI，操作界面像聊天工具，底层仍运行在你自己的电脑上。官方强调“一切皆插件”，可以理解成后续能力都能通过模块追加。Cordis、Bundle、Profile 这些词在基础安装阶段不必深究。

开始前，认识这 6 个词

1. Node.js：dsh 的运行环境，相当于发动机。
2. PowerShell：Windows 自带命令窗口，只需要复制命令。
3. npm：Node.js 自带的包管理工具，负责下载和管理程序。
4. npx：随 Node.js 安装，可以临时下载并运行 dsh，所以本教程不需要提前手动安装 Harness。
5. API Key：以 sk- 开头的密钥，用于调用 DeepSeek 模型，需要保密，并按 API 用量计费。
6. 工作区：你允许 Harness 处理的电脑文件夹。

从零开始安装

第 1 步：安装 Node.js

打开浏览器搜索 Node.js，进入官网下载页面。截至教程发布时，长期支持版是 24.x。DeepSeek Harness 当前源码要求 Node.js 22.19.0 及以上（22.x），或 24.0.0 及以上。普通用户直接选择 24.x LTS。

Windows 用户下载安装程序后双击，保持默认选项一路安装。完成后关闭所有 PowerShell 再重新打开，然后依次执行：

node --version
npm --version

第一条返回 Node 版本，第二条返回 npm 版本。Node 版本不低于 v22.19.0 且 npm 能返回数字，就说明安装成功。若提示“无法将 node 识别为命令”，先重启 PowerShell；仍无效则重新安装 Node.js 并重启电脑。

第 2 步：准备 DeepSeek API Key

登录 DeepSeek 开放平台，进入 API Key 页面，新建一条密钥并复制保存。密钥以 sk- 开头。注意：API Key 不是网页版账号密码；调用 API 按实际用量计费；余额不足时会返回 402 错误。所以创建后顺手检查一下账户余额。

密钥不要发给别人，也不要出现在截图里。它会在下一步粘贴到 Harness。

第 3 步：创建测试文件夹

在“文档”或其他容易找到的位置新建一个文件夹，命名为 test1。第一次测试建议使用空文件夹，避免误操作碰到日常文件。

第 4 步：在文件夹里打开 PowerShell

进入 test1，点击文件资源管理器地址栏，把路径替换为 powershell 后按回车。Windows 会打开一个已定位到 test1 的 PowerShell 窗口。

第 5 步：运行 Harness

在 PowerShell 中运行：

npx @deepseek-ai/dsh web

第一次运行需要准备相关文件，耗时比后面长。如果终端询问是否下载，按提示确认。等待时不要重复粘贴命令或关闭窗口。看到终端打印出访问地址，说明本地服务已经启动。官方默认地址是：

http://127.0.0.1:3080

第 6 步：在浏览器里打开 Harness

保持 PowerShell 运行，不要关闭。打开浏览器，访问 http://127.0.0.1:3080。如果页面无法访问，先回到 PowerShell 看程序是否仍在运行、终端有没有报错。

到这个阶段，Harness 已经在电脑上运行，但还没有配置模型和工作区，无法直接对话。

第 7 步：把 DeepSeek 模型接进来

初次打开页面会提示添加 API Key，后续也可以在“设置 → 模型”中修改。把第 2 步保存的密钥粘贴进去并保存，不需要重启 Harness，配置会下次请求时生效。若要求选择模型，从当前列出的 DeepSeek 模型中选一个即可。

API Key 保存后页面只显示脱敏信息。完整密钥会存在 $DSH_HOME/.credentials.yaml 中，普通用户不必手动修改。

第 8 步：选中刚才的测试文件夹

回到主页面，点击“选择工作区”，添加并选中 test1 文件夹。这一步不能省：从哪个文件夹启动 Harness 和当前会话允许操作哪个工作区是两回事，新 Web UI 不会自动选中任何目录。

选中后输入框会开放。检查四项：PowerShell 里的 dsh 仍在运行；浏览器页面正常；模型已保存；工作区显示为 test1。都满足，基础配置就算完成。

安装完成后，怎样关闭和再次启动

停止服务时回到 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 没有被关闭，并检查终端输出的实际地址。如果端口被占用，可以改 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 里放两个文本文件，Agent 才能有东西可读。

创建说明.txt

用记事本粘贴以下内容：

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

另存为 说明.txt 到 test1。

创建待办.txt

再新建一个记事本，粘贴：

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

保存为 待办.txt，放在同一个文件夹。

这样我们就有了一组自己知道答案的测试材料，Agent 总结得对不对可以直接对照原文。

第一个任务：只允许读取，不允许修改

新建会话，粘贴以下提示词：

请先只读取当前工作区中的文件。

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

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

第一次任务的目标是确认三件事：它能否看到正确文件；它能否遵守只读要求；它能否和原始内容对上。如果页面弹出操作确认，先看清楚它准备做什么。读取两个文本文件不需要安装依赖，也不应该修改其他目录。请求明显越权时，先拒绝，再让它解释。

任务完成后，打开 说明.txt 和 待办.txt，逐条核对文件名、目标和待办顺序。

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

继续发送：

根据刚才读取到的内容，准备在当前工作区新建“项目概览.md”。

文件只包含四部分：
1. 项目目标；
2. 已有文件及用途；
3. 当前待办；
4. 无法确认的信息。

先把执行计划和准备写入的完整内容发给我。
在我回复“确认创建”之前，不要写入文件。
不要修改“说明.txt”和“待办.txt”，也不要创建其他文件。

看到计划后，先自己检查内容，再决定是否确认。