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 默认会在本机启动：
https://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。工作区范围越小，真出问题时就越容易排查和收拾。
六、完成第一个任务
第一次不要一上来就输入“帮我把整个项目全部优化一下”。这类任务缺少明确终点，结果既难验收，也很容易顺带改出一堆无关内容。
建议先用一个只读任务，让 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 的核心并不只是“再做一个 AI 聊天窗口”。更关键的是，它的模型、工具、会话、权限和 UI 都可以独立替换与组合，这正是它相比普通客户端更有扩展性、也更有差异化价值的地方。下一篇文章，我们再继续聊 Profile、Skill、MCP，以及我会如何规划更长流程的任务执行。
