一、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 任务和社区桌面端，底下跑的都可以是同一套运行时。

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

你需要：

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

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

先确认环境：

第一次别拿重要项目试手。复制一份仓库，或者先切一条临时 Git 分支，后面检查和回滚都省心。

三、启动官方 Web UI

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

DSH 默认在本机启动：

调用命令时所在的目录会成为默认工作区位置。不过新版 Web UI 不会自动选中工作区，后面仍需要手动添加并确认。

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

DSH 仍处于预览阶段。如果你希望复现稳定环境，可以固定版本：

四、配置 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。工作区选得越小，出问题时越容易收拾。

六、完成第一个任务

第一次别输入“帮我把项目全部优化一下”。这种任务没有明确终点，结果很难验收，还容易顺手改出一堆无关内容。

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

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

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 会话。

跑通以后

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

走完一遍之后，你会发现 DSH 的重点确实不是“再做一个聊天窗口”。模型、工具、会话、权限和 UI 都能单独替换，这才是它和普通客户端拉开差距的地方。下一篇接着聊 Profile、Skill、MCP，以及我会怎样安排更长的任务。