第4章 安装与第一次运行

第 4 节 / 共 13 节 课程:DeepSeek Harness 实战课

这一章只做一件事:把 DSH 装起来,跑通第一个只读任务。装不起来,后面都是空谈。

准备三样东西

  1. 电脑:Windows 10/11、macOS 14+、主流 Linux;建议 8GB 以上内存。
  2. DeepSeek API Key:在 https://platform.deepseek.com/ 注册、充值、创建。把它当密码,不要发群、不要写进代码仓库。
  3. 工作目录:专门放 Agent 要处理的文件,例如 D:\agent-work 或 ~/agent-work。不要一上来就操作整个 C 盘或用户目录。

方式一:桌面端(推荐非开发者)

  1. 打开 Releases:https://github.com/deepseek-ai/deepseek-harness/releases
  2. 下载对应系统安装包:Windows 的 .exe、macOS 的 .dmg、Linux 的 .AppImage 或发行版包(以 release 说明为准)。
  3. 安装并启动。
  4. 打开 设置 → 模型,填入 DeepSeek API Key,保存。
  5. 选择工作区,选中准备好的目录。
  6. 新建会话,输入第一个任务。

桌面端内置运行时,适合不想折腾 Node.js 的人;它的包与 npm CLI 独立,但共享产品数据与 $DSH_HOME。

方式二:命令行(推荐开发者)

第一步:安装 Node.js。到 https://nodejs.org/ 安装 Node.js 22 LTS 或更新版本,然后确认:

node -v
npm -v

第二步:安装 DSH:

npm install -g @deepseek-ai/dsh

npm 包页面:https://www.npmjs.com/package/@deepseek-ai/dsh 。确认:

dsh --version

截至 2026 年 11 月,npm 最新版约 0.2.2-rc.1;本机可能装到 0.2.1-rc.2。版本不必一致,命令以 dsh --help 为准。

第三步:启动 Web UI:

cd D:\agent-work
dsh web

默认地址通常是 http://127.0.0.1:3080 。端口被占用时,终端会打印实际地址,以输出为准。

第四步:配置模型。打开页面 → 设置 → 模型 → DeepSeek 卡片填 Key → 保存。模型路由立即生效,不需要重启。然后在模型选择器里选 deepseek-flash(日常)或 deepseek-v4-pro(复杂任务)。Key 是只写的,保存后只显示脱敏描述,明文存在 $DSH_HOME/.credentials.yaml。

第五步:选择工作区。点击“选择工作区”,添加并选中启动 dsh 时所在的目录。选中工作区之前,会话输入框不可用——这是安全设计:没有工作区,就没有文件边界。

第六步:第一个任务:

请先不要修改任何文件。
阅读当前工作区,列出目录结构,告诉我这个项目是做什么的、入口文件在哪、有哪些明显的风险。
最后用 5 条以内的要点回答。

这个任务的设计意图:先不要修改(只读,降低风险);列目录(强制观察);找入口(要求定位);找风险(要求判断);5 条以内(控制输出)。

第七步:验证。检查它是否真的读了文件、是否引用具体路径、是否对不确定处说“不确定”、是否擅自修改。如果开始编造,回到第 7 章重学提问。

其他启动方式

dsh headless "运行测试并把失败原因总结成三条"
dsh tui
dsh --profile sdk-minimal
dsh --dump-config

dsh --help 会列出当前版本支持的全部命令。不要背命令,学会看帮助。

升级与卸载

npm update -g @deepseek-ai/dsh
npm uninstall -g @deepseek-ai/dsh

桌面端在系统设置里卸载;彻底清理按官方“桌面端卸载清理”文档处理 $DSH_HOME 与残留数据。

安装排错表

现象可能原因处理
dsh: command not foundnpm 全局 bin 不在 PATH查 npm bin -g,把输出目录加入 PATH
页面打不开端口被占用/服务没起看终端输出,换端口或结束占用进程
输入框灰色没选工作区选择工作区
401 / 密钥无效Key 错、过期、额度不足重新生成 Key,检查余额
UNKNOWN_MODEL模型名不在目录在模型选择器里选已配置模型
一直转圈网络/代理/端点问题检查网络,确认 base URL
中文乱码终端编码Windows 用 UTF-8 终端,或改用 Web UI

本章练习

完成安装,截图保存“设置 → 模型”的成功状态(不要截到完整 Key);用只读任务让它介绍工作区;故意写一个模糊任务,观察它如何反问或猜测;把观察写进笔记。