第4章 安装与第一次运行
这一章只做一件事:把 DSH 装起来,跑通第一个只读任务。装不起来,后面都是空谈。
本章共 6 节,另附练习,建议按顺序阅读:
准备三样东西
- 电脑:Windows 10/11、macOS 14+、主流 Linux;建议 8GB 以上内存。
- DeepSeek API Key:在 https://platform.deepseek.com/ 注册、充值、创建。把它当密码,不要发群、不要写进代码仓库。
- 工作目录:专门放 Agent 要处理的文件,例如 D:\agent-work 或 ~/agent-work。不要一上来就操作整个 C 盘或用户目录。
方式一:桌面端(推荐非开发者)
- 打开 Releases:https://github.com/deepseek-ai/deepseek-harness/releases
- 下载对应系统安装包:Windows 的 .exe、macOS 的 .dmg、Linux 的 .AppImage 或发行版包(以 release 说明为准)。
- 安装并启动。
- 打开 设置 → 模型,填入 DeepSeek API Key,保存。
- 选择工作区,选中准备好的目录。
- 新建会话,输入第一个任务。
桌面端内置运行时,适合不想折腾 Node.js 的人;它的包与 npm CLI 独立,但共享产品数据与 $DSH_HOME。
方式二:命令行(推荐开发者)
第一步:安装 Node.js。到 https://nodejs.org/ 安装 Node.js 22 LTS 或更新版本,然后确认:
第二步:安装 DSH:
npm 包页面:https://www.npmjs.com/package/@deepseek-ai/dsh 。确认:
截至 2026 年 11 月,npm 最新版约 0.2.2-rc.1;本机可能装到 0.2.1-rc.2。版本不必一致,命令以 dsh --help 为准。
第三步:启动 Web UI:
默认地址通常是 http://127.0.0.1:3080 。端口被占用时,终端会打印实际地址,以输出为准。
第四步:配置模型。打开页面 → 设置 → 模型 → DeepSeek 卡片填 Key → 保存。模型路由立即生效,不需要重启。然后在模型选择器里选 deepseek-flash(日常)或 deepseek-v4-pro(复杂任务)。Key 是只写的,保存后只显示脱敏描述,明文存在 $DSH_HOME/.credentials.yaml。
第五步:选择工作区。点击“选择工作区”,添加并选中启动 dsh 时所在的目录。选中工作区之前,会话输入框不可用——这是安全设计:没有工作区,就没有文件边界。
第六步:第一个任务:
这个任务的设计意图:先不要修改(只读,降低风险);列目录(强制观察);找入口(要求定位);找风险(要求判断);5 条以内(控制输出)。
第七步:验证。检查它是否真的读了文件、是否引用具体路径、是否对不确定处说“不确定”、是否擅自修改。如果开始编造,回到第 7 章重学提问。
其他启动方式
dsh --help 会列出当前版本支持的全部命令。不要背命令,学会看帮助。
升级与卸载
桌面端在系统设置里卸载;彻底清理按官方“桌面端卸载清理”文档处理 $DSH_HOME 与残留数据。
安装排错表
| 现象 | 可能原因 | 处理 |
|---|---|---|
| dsh: command not found | npm 全局 bin 不在 PATH | 查 npm bin -g,把输出目录加入 PATH |
| 页面打不开 | 端口被占用/服务没起 | 看终端输出,换端口或结束占用进程 |
| 输入框灰色 | 没选工作区 | 选择工作区 |
| 401 / 密钥无效 | Key 错、过期、额度不足 | 重新生成 Key,检查余额 |
| UNKNOWN_MODEL | 模型名不在目录 | 在模型选择器里选已配置模型 |
| 一直转圈 | 网络/代理/端点问题 | 检查网络,确认 base URL |
| 中文乱码 | 终端编码 | Windows 用 UTF-8 终端,或改用 Web UI |
本章练习
完成安装,截图保存“设置 → 模型”的成功状态(不要截到完整 Key);用只读任务让它介绍工作区;故意写一个模糊任务,观察它如何反问或猜测;把观察写进笔记。
《DeepSeek Harness 实战课》课程目录
面向应用者的 DeepSeek Harness 实战课:讲清 API、Agent、Harness 三者关系,带你安装 DSH、写出可验收任务、让 Agent 读文件改代码跑测试、接 MCP/插件、做定时任务,并划清安全边界