DeepSeek Harness（命令行里叫 dsh）是 DeepSeek AI 开源的智能体运行底座（Agent Harness），口号是”一切皆插件”。它不只是一个聊天前端：它能读改你工作区的文件、执行命令、拆解计划、委派子任务，遇到敏感操作还会按权限策略先征求你的批准。本文用十分钟带你从零启动 Web UI，配好模型，跑通第一个真正读写你代码仓库的编程智能体任务，并讲清源码跑法和后续扩展路线。
一、背景：Harness 和普通聊天工具有什么区别
普通大模型聊天框的问题是”看得见摸不着”：它能给你一段代码建议，但改文件、跑测试、看报错、再改一轮的脏活全得你手工搬运。编程智能体要解决的正是这个闭环：模型能直接操作文件系统和终端，带着目标持续推进，直到任务完成或需要你拍板。
DeepSeek Harness 就是承载这种闭环的开源底座：MIT 协议，插件化架构，模型路由开箱支持 DeepSeek API，也支持其他 OpenAI 兼容 endpoint。你既可以用一行 npx 命令把它跑起来当生产力工具，也可以从源码构建，进而自己写插件扩展它的能力。当前版本处于开发者预览期，迭代快、偶有不兼容变更，认准官方仓库 deepseek-ai/deepseek-harness 为唯一真相源。
二、原理：Web UI、工作区与权限审批
理解三个机制，上手就没有困惑。
dsh 进程的工作目录即默认文件系统位置。 你在哪个目录启动 dsh，智能体默认就能操作哪个目录。这是有意的设计：把启动目录当作授权边界，研究代码就去代码目录启动，想让它整理文档就去文档目录启动。
Web UI 初始没有选中任何工作区。 刚打开的 Web UI 是一个空壳，会话输入框是不可用的，你必须先”添加工作区”（把启动 dsh 时所在的项目目录加进来）并选中它，会话输入框才会激活。这一步经常让新人以为服务坏了，其实只是还没选工作区。
敏感操作走审批。 智能体读文件、改文件、跑命令、委派工作、维护计划都在权限策略管控下。超出当前策略的操作，Web UI 会弹窗问你批不批准，而不是先斩后奏。所以你可以放心让它在你的仓库里干活：删库级操作一定会先经过你的眼睛。
模型方面，打开”设置 → 模型”填入 DeepSeek API Key 即可，模型路由即时生效不用重启。另有模型配置指南覆盖其他服务商和自定义 OpenAI 兼容地址。
三、环境准备
npx 路线只需要 Node.js：要求 ^22.19.0 或 >=24.0.0，老版本 Node 会装不上或跑出灵异 bug。先检查：
node --version # 需要 v22.19+ 或 v24+
源码路线额外需要 git 和 pnpm（仓库用 pnpm 管理 monorepo）。再准备一个 DeepSeek API Key（去 DeepSeek 开放平台申请），以及一个你想让智能体研究的项目目录（第一次玩建议用一个中小型开源仓库的本地 clone，别直接拿线上生产目录练手）。
远程服务器场景注意：Web UI 默认只监听回环地址 http://127.0.0.1:3080，这是刻意的安全默认——能跑命令的工具不应该默认暴露到局域网。远程使用请用 SSH 端口转发把 3080 映射到本地，再打开 CLI 打印的完整启动 URL（含 token，别泄露）。
四、分步实战
步骤 1：npx 一行命令启动 Web UI
npx @deepseek-ai/dsh web
npm 会按需下载包并启动服务，默认地址 http://127.0.0.1:3080，本地启动还会自动帮你打开浏览器。常用变体：
npx @deepseek-ai/dsh web --no-open # 不自动打开浏览器，只打印地址
npx @deepseek-ai/dsh web --port 8080 # 3080 被占用时换端口
npx @deepseek-ai/dsh@<version> web # 预览期建议 pin 版本，避免静默升级
关键细节：先 cd 到你的目标项目目录再执行这条命令，因为启动目录就是智能体默认的工作目录。终端里打印的启动 URL 带一次性 token，复制完整地址访问，根路由交换 token 后会跳转到干净地址。
步骤 2：配置模型
浏览器打开 Web UI 后：
- 进 设置 → 模型，填入 DeepSeek API Key，点保存——路由即时生效，无需重启服务。
- 需要其他服务商或自建 OpenAI 兼容 endpoint，按模型配置指南加。
- 回到主页，点 选择工作区，把启动
dsh时所在的项目目录添加进来并选中。选中之前会话输入框是灰的，这是正常的。
如果页面空白或异常，用 dsh web --dump-config 检查插件树是否健康；浏览器没自动弹出就手动打开 CLI 打印的完整 URL（含 token 部分）。
步骤 3：运行第一个任务
新建会话，发送：
Summarize this repository and identify its main packages.
然后观察智能体会做什么：列目录、读 README 和包清单、按需打开源码确认结构、维护一个 mini 计划，最后给你一份”这个仓库是什么、核心包有哪些、各负责什么”的总结。如果它要执行命令或做有风险的操作，Web UI 会先弹窗让你审批——点允许或拒绝即可。
第一个任务跑通后，趁热打铁试一个”改代码”任务，形成完整闭环：
给这个仓库的 README 顶部加一行一句话简介，改完跑一遍现有 lint/测试并告诉我结果。
你会看到完整闭环：读文件 → 改文件 → 跑命令 → 读报错 → 修 → 重跑 → 汇报。这就是编程智能体相对聊天框的核心价值：循环不需要你当搬运工。
步骤 4：源码跑法（想二次开发必须会）
npx 跑的是 npm 发布版；要读源码、改插件、跟最新 master，用源码构建：
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build # 先构建产物，之后才能跑
pnpm dsh web # 用已构建产物启动，不再重复构建
顺序不能乱：第一次必须先 pnpm run build 再 pnpm dsh web。跑起来后同样是 3080 端口的 Web UI，但背后是你的工作树——改一个包的代码，重新 build，再启动验证，循环就是这么转的。日常语境里文档写的 dsh 指的就是这个可用的 CLI 入口；走 npx 路线时把 dsh ... 换成 npx @deepseek-ai/dsh ... 即可。
步骤 5：继续深入的三条路线
- 换模型/加 endpoint：看模型服务商配置指南，把团队的网关或本地模型接进来。
- Python SDK：需要在自己的 Python 程序里驱动 harness，走 Python SDK 指南。
- 其他 CLI 模式与插件开发：读 apps/cli 的 README 了解无界面模式；想加新工具、新审批策略、新 UI 面板，就去学插件开发基础，前提是用上面的源码跑法。
五、常见坑
坑 1：Node 版本太老。 仓库 engines 要求 Node ^22.19 或 >=24，老运行时要么装不上，要么跑出看似 harness bug 的灵异问题，先 node --version 自查。
坑 2：启动目录错了。 在家目录随手启动，结果智能体默认位置是家目录，满屏无关文件。正确姿势：先 cd 到目标项目再启动。
坑 3：没选工作区就说输入框坏了。 全新 Web UI 默认无选中工作区，会话输入框不可用是预期行为，添加并选中启动目录即可。
坑 4：浏览器没弹出来以为没启动。 看终端打印的完整 URL（含 ?token=...），复制到浏览器打开；SSH 启动本来就只打印地址不弹浏览器。
坑 5：端口冲突。 3080 被占用就 --port 换一个，别去 kill 不明进程。
坑 6：预览期不 pin 版本。 预览版可能引入不兼容变更，npx 最好 pin 到验证过的版本，升级时看官方仓库的变更说明。
坑 7：把启动 URL 的 token 发到群里。 token 等于本次会话的钥匙，私聊自己、别截图外发；远程用 SSH 转发而非 --host 0.0.0.0（当前源码启动甚至直接拒绝该参数）。
进阶：Profiles、无头模式与插件开发
Web UI 跑顺之后，三个方向值得深入。
Profiles（配置档）。 CLI 支持 --profile 选择启动时加载的插件组合，出厂自带如 headless 等。不同任务用不同档：日常写代码用默认全功能档，CI 里跑自动化任务用 headless 档。注意预览期插件组合常调整，以你本地 dsh --help 输出为准，别背文档里的列表。
无头/CLI 模式。 不需要界面的场景（SSH 服务器、自动化脚本）看 apps/cli 的 README，用纯命令行驱动智能体跑任务。配合 --no-open 和端口参数，远程工作流完全成立：本地 SSH 转发起 3080，浏览器开 CLI 打印的 token URL。
插件开发。 “一切皆插件”是 harness 的核心设计：新工具、新审批策略、新 UI 面板都是插件。标准循环：源码 clone → pnpm install && pnpm run build → 读对应包的真实 API（别靠猜 README）→ 改代码 → 重 build → pnpm dsh web 验证。预览期 API 变得快，遇到对不上的地方直接读工作树的源码和变更记录，它比任何二手文档都新。
给智能体下好任务的心法。 目标具体（”给 README 加简介”而不是”优化下项目”）、验收标准写进问题（”改完跑 lint 并贴结果”）、审批弹窗逐条看。任务粒度控制在 15 分钟能验证一轮，太大的目标先让它出计划、你确认后再执行。
附：从第一个任务到日常工作流的 5 个实战任务
跑通总结仓库后，按这个顺序练，把 harness 吃透：
- 代码考古：”画出这个项目的模块依赖关系，哪个包是入口？”——练检索式阅读，观察它怎么列目录、跟 import 链。
- 文档补齐：”给缺 docstring 的三个核心函数补中英文 docstring，并跑 lint。”——练小幅改写+验证闭环。
- 报错修复：”跑测试，把第一个失败的用例修好，解释根因。”——练读报错、定位、改、重跑的完整循环。
- 小功能开发：”加一个 –json 输出选项，带测试。”——练需求理解+多文件改动+自测，审批弹窗会频繁出现，逐条看。
- 计划评审：”重构鉴权模块，先出计划，我确认后再动手。”——练大任务的”计划先行”模式，你当架构评审，智能体当执行。
五个任务走完，你会形成肌肉记忆：任务描述越具体、验收越前置，智能体产出越好。反之”优化一下这个项目”这种模糊指令，产出的也是模糊工作——这不是 harness 的缺陷，而是所有智能体工具的共性：输入的清晰度决定输出的上限。
常见问答
问：npx 和源码跑法选哪个？ 只用不改选 npx，一行命令零负担；要写插件、读实现、跟最新功能选源码。两者跑的是同一个 Web UI，配置和工作区用法完全一样，随时可以切换。
问：模型必须用 DeepSeek 吗？ 不必。设置页默认走 DeepSeek API，但模型配置指南覆盖了其他服务商和自定义 OpenAI 兼容 endpoint，团队网关和本地模型都能接。换模型后建议把第一个总结任务重跑一遍，直观对比效果差异。
问：让它操作我的代码安全吗？ 权限审批就是干这个的：读改文件、跑命令等敏感操作会先弹窗征求同意。建议再加两道保险：重要仓库先提交 git 再开工（随时可回滚），生产目录和密钥文件不要选作工作区。
问：任务卡住不动了怎么办？ 先看它维护的计划面板，确认卡在哪一步；缺信息就补一句，要求它继续。预览期偶发前端异常，--dump-config 检查插件树，必要时重启 dsh 进程，会话历史一般都在。
六、总结
DeepSeek Harness 的最小可用路径只有四步：切到项目目录 → npx @deepseek-ai/dsh web → 设置页填 Key → 选工作区并发第一个总结任务。npx 路线零安装开箱即用，源码路线多花几分钟但换来可修改的工作树。跑通之后，真正的功课是学会”怎么给智能体下好任务”：目标具体、验收标准写进问题里、审批弹窗认真看。从今天起，让改文件跑命令的循环在 harness 里转，你只负责拍板和验收。 点击阅读原文
参考资料：https://deepseek-harness.github.io/deepseek-harness/guide/quickstart 点击阅读原文
相关文章
