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 任务和社区桌面端，底下跑的都可以是同一套运行时。
text
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 版本。
先确认环境：
bash
node --version
npx --version第一次别拿重要项目试手。复制一份仓库，或者先切一条临时 Git 分支，后面检查和回滚都省心。
三、启动官方 Web UI
进入准备使用的项目目录，然后运行：
bash
cd /path/to/your-project
npx @deepseek-ai/dsh webDSH 默认在本机启动：
text
http://127.0.0.1:3080调用命令时所在的目录会成为默认工作区位置。不过新版 Web UI 不会自动选中工作区，后面仍需要手动添加并确认。
如果默认端口被占用，可以指定其他端口：
bash
npx @deepseek-ai/dsh web --port 3081DSH 仍处于预览阶段。如果你希望复现稳定环境，可以固定版本：
bash
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。工作区选得越小，出问题时越容易收拾。
六、完成第一个任务
第一次别输入"帮我把项目全部优化一下"。这种任务没有明确终点，结果很难验收，还容易顺手改出一堆无关内容。
先用一个只读任务认识项目：
text
请阅读这个仓库，不要修改文件。
输出：
1. 项目的主要入口；
2. 核心模块及职责；
3. 本地测试命令；
4. 目前最值得处理的一个小问题。确认它理解项目后，再给出一个边界明确的修改任务：
text
修复刚才发现的问题。
要求：
- 修改前先说明原因和涉及文件；
- 只改解决问题所需的最少文件；
- 完成后运行相关测试；
- 最后列出修改摘要和测试结果。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 会话。
跑通以后
第一次使用，按这条路径走就够了：
text
安装 Node.js
→ 在项目目录运行 npx @deepseek-ai/dsh web
→ 配置模型
→ 选择工作区
→ 先调查项目
→ 再执行一个有验收条件的小任务走完一遍之后，你会发现 DSH 的重点确实不是"再做一个聊天窗口"。模型、工具、会话、权限和 UI 都能单独替换，这才是它和普通客户端拉开差距的地方。下一篇接着聊 Profile、Skill、MCP，以及我会怎样安排更长的任务。