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。

1. 打开Node官网，下载LTS长期支持版本，一路下一步安装。
2. 安装完成，打开终端
   • Windows：PowerShell（不要用cmd）
   • Mac：终端
3. 验证是否安装成功，输入命令：

node -v

输出版本号，代表安装成功。如果提示“不是内部命令”，重启终端，或者重新安装Node。

第2步：一行命令启动DSH Web界面（最简单，小白选这个）

复制下面整行，粘贴到终端回车执行：

npx @deepseek-ai/dsh web

1. 第一次运行，会提示 Need to install the following packages，输入 y，回车确认下载包。
2. 等待下载、启动服务，终端输出：
   dsh web: http://127.0.0.1:3080
3. 不要关闭这个终端窗口！关闭就停止服务。复制这个地址，浏览器打开：http://127.0.0.1:3080

备选：全局安装（网络差、想固定版本）

npm install -g @deepseek-ai/dsh
dsh web

进阶：源码编译运行（做插件开发才需要，小白跳过）

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无法调用大模型。

1. 访问DeepSeek开放平台，登录账号。
2. 进入API Keys页面，点击【添加API Key】，复制生成的密钥。

注意：密钥只显示一次，保存好，不要泄露给别人，会消耗你的账户余额。

第4步：Web界面基础配置

1. 浏览器打开 http://127.0.0.1:3080，弹出内测提示，点击继续。

2. 在弹窗粘贴刚才复制的API‑Key，点击【保存并继续】。

   • 后续修改key：页面左下角设置⚙️ → Models，粘贴密钥保存，无需重启服务。  

3. 选择工作区（最重要！）
   点击页面左上角【选择工作区】按钮，新建一个空文件夹，选中这个空文件夹作为工作目录。

✅正确：D:\dsh‑test、~/dsh‑demo 这种全新空文件夹
❌禁止：桌面、文档、你的正式项目、系统文件夹！AI会读写、修改甚至删除目录下文件。
选中之后对话框才解除灰掉，可以输入指令。

第5步：认识4种运行模式（小白优先标准模式）

DSH左上角可以切换模式，四种模式不是简单改提示词，是加载不同插件集合：

1. 标准模式 Standard（新手默认）：完整Agent，读写文件、shell终端、网页搜索、任务规划，日常写代码优先选这个。
2. 代码模式 Code Mode：把多个工具操作合并为TypeScript脚本批量执行，适合复杂批量任务。
3. 极简模式 Minimal：最小工具集，只有文件编辑+bash，适合调试，限制AI能力。
4. 创作者模式 Creator：用来开发自定义Agent插件，普通用户不用。

第6步：第一次实战任务（测试是否跑通）

工作区已经选好空文件夹，模式选【标准模式】，权限默认即可。
输入第一条简单指令，复制发送：

在当前目录新建一个index.html，写一个简单的网页，标题是我的第一个DSH测试页面，页面输出hello DSH Harness

观察页面发生的动作：

1. Agent自动规划任务
2. 调用文件工具创建index.html
3. 你可以看到每一步工具调用记录
4. 任务完成后，打开本地工作文件夹，确认index.html已经生成。

小提示：遇到风险操作（比如删除文件），DSH会弹出确认框，你手动允许才会执行，不要随便点允许。

第7步：常用实操示例（直接复制测试）

示例1：写Python脚本

写一个python脚本，实现冒泡排序，保存为sort.py，同时生成readme.md说明怎么运行

示例2：重构已有项目（注意：工作区选你的测试项目，不要选重要项目）

读取当前目录下sort.py，给全部函数增加注释，优化代码，直接覆盖原文件

示例3：执行终端命令

执行命令打印当前目录文件列表，把结果输出到list.txt

常见踩坑与排错

问题1：npx命令报错

1. Node版本太低，升级Node到22.19以上。
2. 国内npm下载慢，设置镜像：

npm config set registry https://registry.npmmirror.com

问题2：浏览器打不开 http://127.0.0.1:3080

• 确认终端还在运行DSH，不要关闭终端；
• 看终端实际输出地址，个别环境端口会变，复制终端打印出来的地址。

问题3：API调用报错

1. 检查API Key复制完整，不要带空格换行；
2. DeepSeek账户余额充足；
3. 设置 → Models确认密钥已经保存。

问题4：输入框灰色无法输入

没有选择工作区！点击左上角选择工作区，选中文件夹后输入框激活。

问题5：想停止DSH

回到运行的终端窗口，按 Ctrl + C，服务停止。下次使用重新执行 npx @deepseek-ai/dsh web。

补充：其他运行方式（小白了解即可）

1. 无头Headless模式（无界面，自动化脚本）

dsh run "你的任务指令"

1. Python SDK：适合写程序调用Agent，需要单独安装SDK包。

重要安全注意事项

1. DSH具备本地文件读写、运行系统命令的能力，永远不要把工作区设置到包含私人资料、重要业务代码的目录。
2. 遇到删除文件、修改系统配置的请求，一定要人工确认，不要一键放行。
3. 当前版本是开发者预览，插件、配置后续版本可能会不兼容更新，不适合生产项目直接使用。

参考链接

• 官方仓库：https://github.com/deepseek-ai/deepseek-harness
• DeepSeek开放平台：api.deepseek.com