DeepSeek?Harness（简称 DSH）是 DeepSeek 开源的AI Agent运行框架，公式：Agent = 大模型 + Harness。
模型负责思考；Harness负责让AI读写本地文件、执行终端命令、调用工具、拆分复杂任务；核心理念一切皆插件，当前为开发者预览版，会频繁更新，适合尝鲜，不要直接上生产环境。
??安全提醒：DSH可以操作你电脑本地文件、运行shell命令，务必新建空文件夹作为工作区，不要直接选桌面、系统目录、重要项目文件夹，防止误删文件。
第1步：安装 Node.js（必须前置）
DSH是Node程序，Windows/macOS/Linux都需要，推荐版本 Node.js 22.19+ /24.x LTS。
- 打开Node官网，下载LTS长期支持版本，一路下一步安装。
- 安装完成，打开终端
- Windows：PowerShell（不要用cmd）
- Mac：终端
- 验证是否安装成功，输入命令：
|
1 |
node -v |
输出版本号，代表安装成功。如果提示“不是内部命令”，重启终端，或者重新安装Node。
第2步：一行命令启动DSH Web界面（最简单，小白选这个）
复制下面整行，粘贴到终端回车执行：
|
1 |
npx @deepseek-ai/dsh web |
- 第一次运行，会提示 Need to install the following packages，输入 y，回车确认下载包。
- 等待下载、启动服务，终端输出：
dsh web: http://127.0.0.1:3080 - 不要关闭这个终端窗口！关闭就停止服务。复制这个地址，浏览器打开：http://127.0.0.1:3080
备选：全局安装（网络差、想固定版本）
|
1 2 |
npm install -g @deepseek-ai/dsh dsh web |
进阶：源码编译运行（做插件开发才需要，小白跳过）
|
1 2 3 4 5 |
git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install pnpm run build pnpm dsh web |
第3步：获取DeepSeek API?Key
网页打开后会弹窗要求填入API密钥，没有key无法调用大模型。
- 访问DeepSeek开放平台，登录账号。
- 进入API Keys页面，点击【添加API Key】，复制生成的密钥。
注意：密钥只显示一次，保存好，不要泄露给别人，会消耗你的账户余额。
第4步：Web界面基础配置
- 浏览器打开 http://127.0.0.1:3080，弹出内测提示，点击继续。
- 在弹窗粘贴刚才复制的API?Key，点击【保存并继续】。
- 后续修改key：页面左下角设置?? → Models，粘贴密钥保存，无需重启服务。
- 选择工作区（最重要！）
- 点击页面左上角【选择工作区】按钮，新建一个空文件夹，选中这个空文件夹作为工作目录。
?正确：D:\dsh?test、~/dsh?demo 这种全新空文件夹
?禁止：桌面、文档、你的正式项目、系统文件夹！AI会读写、修改甚至删除目录下文件。
选中之后对话框才解除灰掉，可以输入指令。
第5步：认识4种运行模式（小白优先标准模式）
DSH左上角可以切换模式，四种模式不是简单改提示词，是加载不同插件集合：
- 标准模式 Standard（新手默认）：完整Agent，读写文件、shell终端、网页搜索、任务规划，日常写代码优先选这个。
- 代码模式 Code Mode：把多个工具操作合并为TypeScript脚本批量执行，适合复杂批量任务。
- 极简模式 Minimal：最小工具集，只有文件编辑+bash，适合调试，限制AI能力。
- 创作者模式 Creator：用来开发自定义Agent插件，普通用户不用。
第6步：第一次实战任务（测试是否跑通）
工作区已经选好空文件夹，模式选【标准模式】，权限默认即可。
输入第一条简单指令，复制发送：
在当前目录新建一个index.html，写一个简单的网页，标题是我的第一个DSH测试页面，页面输出hello DSH Harness
观察页面发生的动作：
- Agent自动规划任务
- 调用文件工具创建index.html
- 你可以看到每一步工具调用记录
- 任务完成后，打开本地工作文件夹，确认index.html已经生成。
小提示：遇到风险操作（比如删除文件），DSH会弹出确认框，你手动允许才会执行，不要随便点允许。
第7步：常用实操示例（直接复制测试）
示例1：写Python脚本
写一个python脚本，实现冒泡排序，保存为sort.py，同时生成readme.md说明怎么运行
示例2：重构已有项目（注意：工作区选你的测试项目，不要选重要项目）
读取当前目录下sort.py，给全部函数增加注释，优化代码，直接覆盖原文件
示例3：执行终端命令
执行命令打印当前目录文件列表，把结果输出到list.txt
常见踩坑与排错
问题1：npx命令报错
- Node版本太低，升级Node到22.19以上。
- 国内npm下载慢，设置镜像：
|
1 |
npm config set registry https://registry.npmmirror.com |
问题2：浏览器打不开 http://127.0.0.1:3080
- 确认终端还在运行DSH，不要关闭终端；
- 看终端实际输出地址，个别环境端口会变，复制终端打印出来的地址。
问题3：API调用报错
- 检查API Key复制完整，不要带空格换行；
- DeepSeek账户余额充足；
- 设置 → Models确认密钥已经保存。
问题4：输入框灰色无法输入
没有选择工作区！点击左上角选择工作区，选中文件夹后输入框激活。
问题5：想停止DSH
回到运行的终端窗口，按 Ctrl + C，服务停止。下次使用重新执行 npx @deepseek-ai/dsh web。
补充：其他运行方式（小白了解即可）
- 无头Headless模式（无界面，自动化脚本）
|
1 |
dsh run "你的任务指令" |
- Python SDK：适合写程序调用Agent，需要单独安装SDK包。
重要安全注意事项
- DSH具备本地文件读写、运行系统命令的能力，永远不要把工作区设置到包含私人资料、重要业务代码的目录。
- 遇到删除文件、修改系统配置的请求，一定要人工确认，不要一键放行。
- 当前版本是开发者预览，插件、配置后续版本可能会不兼容更新，不适合生产项目直接使用。
参考链接
- 官方仓库：https://github.com/deepseek-ai/deepseek-harness
- DeepSeek开放平台：api.deepseek.com
