DeepSeek Harness 刚开源时，我最想弄清楚的是：它和普通的 AI 聊天窗口到底有什么区别？

折腾一轮之后，我觉得可以这样理解：聊天应用主要负责回答问题，Harness 则让模型进入真实工作区干活。

它能读写文件、运行命令、维护计划，遇到敏感操作再向用户申请批准。

下面从零开始，跑通官方 Web UI、模型配置和工作区，再交给 Agent 一个能验收的小任务。

一、DeepSeek Harness 是什么？

DeepSeek Harness，命令名为 dsh，是 DeepSeek AI 开源的 Agent Harness。

它当前处于 Developer Preview，更新速度很快，也可能出现不兼容改动。

最值得先理解的设计叫 Everything is a Plugin。

模型适配器、工具、会话日志、Agent Loop、沙箱、审批策略和 Web UI 都是可组合的插件。

所以，DSH 并不是一个形态固定的 Coding Agent。

官方 Web UI、一次性 Headless 任务和社区桌面端，底下跑的都可以是同一套运行时。

DeepSeek Harness
├── Model：连接 DeepSeek 或其他模型提供方
├── Agent Loop：组织模型请求和工具调用
├── Tools：文件、Shell、任务等能力
├── Session：保存可恢复、可回放的事件日志
├── Policy：沙箱与操作审批
└── UI：Web、Headless 或社区桌面端

二、开始前需要准备什么？

开始之前，你需要准备以下内容：

• 一台 macOS、Windows 或 Linux 电脑；
• Node.js；
• 一个可用的 DeepSeek API Key；
• 一个允许 Agent 读取和修改的测试项目。

官方 README 只要求先安装 Node.js。

当前源码仓库的运行环境声明为 Node.js ^22.19.0 或 >=24.0.0。为了减少兼容问题，建议直接使用当前 Node.js 24 版本。

先确认环境：

node --version
npx --version

第一次别拿重要项目试手。

复制一份仓库，或者先切一条临时 Git 分支，后面检查和回滚都省心。

三、启动官方 Web UI

进入准备使用的项目目录，然后运行：

cd /path/to/your-project
npx @deepseek-ai/dsh web

DSH 默认在本机启动：

http://127.0.0.1:3080

调用命令时所在的目录会成为默认工作区位置。

不过新版 Web UI 不会自动选中工作区，后面仍需要手动添加并确认。

如果默认端口被占用，可以指定其他端口：

npx @deepseek-ai/dsh web --port 3081

DSH 仍处于预览阶段。

如果你希望复现稳定环境，可以固定版本：

npx @deepseek-ai/dsh@0.1.0-rc.6 web

四、配置 DeepSeek 模型

打开 Web UI 后，进入 设置 → 模型，在 DeepSeek 卡片中填写 API Key 并保存。

模型配置保存后会在下一次请求生效，不需要重启服务。

官方实现不会把明文密钥重新发送给设置页面。

密钥保存在 $DSH_HOME/.credentials.yaml，设置文件只保存凭据引用。

如果你使用 OpenAI 兼容网关、自建服务或其他提供方，可以选择 添加自定义提供方。

然后填写 Provider ID、Base URL、协议、凭据和模型。

这里容易踩一个坑：Provider ID 会被会话、默认模型和凭据引用。

显示名称可以改，Provider ID 保存后就别随便动了。

五、选择工作区

返回主界面，点击 选择工作区，添加刚才启动 dsh 时所在的项目目录，然后选中它。

选中工作区之前，输入框是不可用的。

不是页面坏了，DSH 只是在等你先圈定 Agent 可以操作的项目。

新会话默认使用 workspace-write 权限模式。

文件写入和 Shell 产生的文件改动会被限制在工作区及平台临时目录；读取、网络访问和进程可见性并不等同于完全隔离。

所以，有沙箱也别把整个主目录扔给 Agent。

工作区选得越小，出问题时越容易收拾。

六、完成第一个任务

第一次不要输入“帮我把项目全部优化一下”。

这种任务没有明确终点，结果很难验收，还容易顺手改出一堆无关内容。

先用一个只读任务认识项目：

请阅读这个仓库，不要修改文件。

输出：
1. 项目的主要入口；
2. 核心模块及职责；
3. 本地测试命令；
4. 目前最值得处理的一个小问题。

确认它理解项目后，再给出一个边界明确的修改任务：

修复刚才发现的问题。

要求：
- 修改前先说明原因和涉及文件；
- 只改解决问题所需的最少文件；
- 完成后运行相关测试；
- 最后列出修改摘要和测试结果。

Agent 可以读取和编辑文件、运行命令、维护计划或委派工作。

当某项操作超过当前权限策略时，Web UI 会先请求你的批准。

七、我会这样给第一个任务

1. 先调查，再修改

先让 Agent 解释入口、依赖和测试方式。

确认它没有认错项目，再让它动手。

2. 把验收条件写进任务

“优化登录功能”几乎没法验收。

换成“修复刷新后登录状态丢失，并补一条覆盖刷新场景的测试”，任务边界立刻清楚很多。

3. 一个会话只解决一类问题

已发送过请求的会话会保留自己的模型和历史。

完全无关的任务最好开启新会话，避免旧上下文干扰判断。

4. 让 Agent 汇报验证证据

别只问“修好了吗”。

让它把执行过的命令、测试结果和没验证的部分一并贴出来。

5. 关键节点及时看 Git Diff

Agent 能改文件，不代表那些修改都该收下。

每完成一个小目标就看一次 diff，远比最后面对一大坨混合改动轻松。

八、常见问题

npx找不到

确认 Node.js 已正确安装，并重新打开终端。

执行 node --version 和 npx --version，两个命令都应返回版本号。

输入框无法使用

先配置模型，再添加并选中工作区。

默认模型指向已删除的提供方时，也需要重新选择模型。

出现MISSING_CREDENTIAL

进入模型设置重新保存 API Key，或者检查配置引用的环境变量是否存在。

首次启动很慢

npx 首次运行需要下载 DSH 及其依赖，速度取决于网络和 npm Registry。

完成缓存后，后续启动通常更快。

页面打不开或端口冲突

使用 --port 指定新端口，并确认终端中的 DSH 进程没有提前退出。

九、不想每次开终端怎么办？

目前，官方提供了CLI、Web UI和Headless这几种运行方式。

而社区项目DeepSeek Harness Desktop，利用Wails和Go为其封装了一层原生桌面窗口，负责启动DSH、选择端口、展示日志以及清理进程等功能。

它没有重新实现 Harness，模型、会话、插件和 Web UI 仍来自官方 DSH。

目前桌面版同样依赖本机 Node.js 与 npx，并且明确标注为非官方社区项目。

最新版还支持在可信局域网内扫码，用手机浏览器继续操作电脑上的 Harness 会话。

跑通以后

第一次使用，按这条路径走就够了：

安装 Node.js
→ 在项目目录运行 npx @deepseek-ai/dsh web
→ 配置模型
→ 选择工作区
→ 先调查项目
→ 再执行一个有验收条件的小任务

当你实际体验完一遍后，就会深刻认识到DSH的核心并非只是简单地“再打造一个聊天窗口”。

要知道，它的模型、工具、会话、权限以及UI都是能够独立进行替换的，这恰恰是它与普通客户端相比，能够脱颖而出、拉开差距的关键所在。

下一篇文章，咱们接着探讨Profile、Skill、MCP，以及我将如何规划安排更长的任务流程。