夜雨聆风8月13日，DeepSeek 开源了自家的 Agent 运行框架——DeepSeek Harness（简称 DSH），上线不到 24 小时 GitHub Star 突破 5 万，目前已经超过 9 万。
它是什么？一句话说清楚：让大模型从"只会聊天"变成"真能干活"的工具箱。装上它，AI 就能读写你电脑上的文件、运行命令、拆分任务，碰到危险操作还会先问你"同不同意"。
这篇文章只做一件事：手把手带你从零装好 DeepSeek Harness，打开界面发第一条指令。全是你需要敲的每一行命令，每一步都有图可循。
一、先搞清楚：你为什么要装它
你可能已经在用 DeepSeek 的网页版聊天，或者用过 Codex、Claude Code 之类的编程助手。它们有个共同的问题：AI 只能聊天，不能动手。
DeepSeek Harness 解决的就是这个问题。它的核心公式：
Agent = 模型 + Harness
• 模型是大脑，负责理解和推理
• Harness 是手脚和工具架，负责让模型真的去读写文件、跑命令、拆任务
而且它最大的特色是"一切皆插件"——模型是插件，工具是插件，界面是插件，连 Agent 循环本身都是插件。想换模型？换个插件。想加新能力？装个插件。想改界面？还是插件。没有任何东西是焊死的。
目前支持的模型：DeepSeek 官方、OpenAI、Anthropic、Google、Kimi 等近 40 家，以及任何兼容 OpenAI 接口的自建服务。
二、安装前准备：四样东西
动手之前，先检查这四样东西齐了没：
硬件要求不高，普通笔记本就行。不需要 GPU，不需要 Docker，不需要数据库。
三、安装 Node.js（已装的跳过）
Node.js 是让 JavaScript 程序在你电脑上运行的环境，你不用懂它，装就行。
Windows 用户
1. 打开浏览器，访问 nodejs.org
2. 点击下载 LTS 版本（左下角那个大按钮，当前是 v24.19.0）
3. 双击下载的 .msi 文件，一路下一步
4. ⚠️ 安装过程中确保勾选了 "Add to PATH"（默认就是勾选的，别取消）
5. 安装完成后，新开一个 CMD 窗口（按 Win+R，输入 cmd，回车）
6. 输入以下命令确认：
// bash
node -v
看到 v24.x.x 或更高版本号，就说明装好了。
macOS 用户
方式一（推荐新手）：去 nodejs.org 下载 .pkg 安装包，双击安装。
方式二（有 Homebrew 的）：打开终端执行：// bash
brew install node
装完后新开终端，输入 node -v 确认版本。
Linux 用户
// bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
# 关掉终端重开
nvm install --lts
node -v
四、正式安装：三种方式，选一个就够
⭐ 方式一：一行命令直接跑（推荐新手）
这是最快的方式，不需要克隆代码，不需要配置包管理器。
打开终端（Windows 用 PowerShell 或 CMD，Mac 用 Terminal），输入：
// bash
npx @deepseek-ai/dsh web
第一次运行会问你是否下载，输入 y 回车。
然后等 1~3 分钟（取决于网速），终端会输出：
DeepSeek Harness
http://127.0.0.1:3080/
看到这个地址，说明启动成功了！ 打开浏览器，在地址栏输入 http://127.0.0.1:3080，就能看到界面。
💡 小贴士：npx 是 Node.js 自带的工具，意思是"临时下载并运行一个包"。你不需要提前安装任何东西，它帮你搞定。
方式二：全局安装（推荐经常用的人）
如果你打算天天用，每次都让 npx 临时下载太慢。全局装一次，以后秒启动：
// bash
npm install -g @deepseek-ai/dsh
装完后启动命令变成：
// bash
dsh web
启动速度会快很多，几秒钟就能看到地址。
⚠️ Windows 用户注意：如果全局安装后启动报错（提到 pty.node 或原生模块加载失败），是因为 npm 12 默认禁止了安装脚本。解决办法是加一个参数重新装：
`bash
npm install -g @deepseek-ai/dsh --ignore-scripts=false
这样就能正常编译原生模块了。
方式三：从源码安装（适合想改代码的开发者）
想读源码、追最新提交、写自己的插件，就用这种方式：
// bash
# 1. 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
# 2. 安装 pnpm（如果没有的话）
npm install -g pnpm
# 3. 安装依赖
pnpm install
# 4. 构建
pnpm run build
# 5. 启动
pnpm dsh web
五、首次配置：三步让 Agent 开工
第一步：配置 API Key
浏览器打开 http://127.0.0.1:3080 后：
1. 点击左侧菜单 Settings（设置）
2. 进入 Models（模型）页面
3. 找到 DeepSeek 卡片，把你的 API Key 粘贴进去
4. 点击 Save（保存）
🔒 安全提示：API Key 是"只写"的——保存后页面上永远只显示脱敏的描述符（类似 sk-****abcd），不会把明文回显出来。密钥存储在 $DSH_HOME/.credentials.yaml 文件中，保存后立即生效，不需要重启。
💡 没有 API Key？ 去 platform.deepseek.com 注册账号，进入 API Keys 页面，点击"创建 API Key"即可。新注册用户有免费额度。
第二步：选择工作区
1. 点击界面上的 "选择工作区" 按钮
2. 在弹出的文件选择窗口中，找到你之前新建的空文件夹（比如 dsh-test），选中它
3. 确定即可
⚠️ 重要提醒：
- 一定要选空的专用文件夹，里面什么都不要放
- 千万不要选"桌面"、"文档"、"下载"或"C盘根目录"
- 因为 Agent 会在工作区里读写文件、运行命令，选错目录可能导致重要文件被误改
- 没选中工作区之前，输入框是灰色的不能打字——这是安全设计
第三步：发出第一条指令
新建一个会话，直接在输入框里用自然语言发任务。比如：
英文版：
Summarize this directory and tell me what this project is about.
中文版：
分析这个目录的结构，告诉我每个文件和文件夹是干什么的。
Agent 会自己读写文件、跑命令来完成任务。碰到超出权限的操作，它会先停下来问你"同不同意"。
恭喜你，你的 AI Agent 已经开始干活了！ 🎉
六、四种运行模式：什么时候用哪个
DeepSeek Harness 内置了四种运行模式，本质区别就是当前会话加载了哪些工具插件：
模式 有什么工具 适合什么场景
标准模式 完整工具集（文件、Shell、搜索、子任务等） 日常开发首选，90% 时间用它
Code 模式 模型生成 TypeScript 编排多步操作 多步工具调用需要更可控的流程
极简模式 只保留 Shell 和文件编辑 最小化基准测试，精简对比
创造模式 允许运行时检查、试验插件组合 创建自定义 Agent 配置、试验新插件
新手直接用标准模式就行，不用纠结选哪个。
七、插件：给 Agent 加新技能
开源不到 24 小时，社区就涌现了 288 个插件仓库，现在已经超过 1000 个。装插件就是给 Agent 加新技能，装完刷新即可，热插拔，不需要重启。
通用安装命令
// bash
dsh plugin --profile web add <插件名>
⭐ 必装插件推荐
插件 功能
dsh-at-file 输入框里用 @ 直接调用文件
dsh-genui 模型回复里渲染图表、Mermaid、表格
ModLens 让纯文本模型也能处理图片
怎么找更多插件？
在 GitHub 上搜索话题 dsh-plugin，或者访问这两个精选列表：
• awesome-deepseek-harness（0xsline 维护，带安装命令）
• Awesome DSH Plugin（中英双语，分类更细）
八、避坑指南：7 个常见问题
问题 原因 解决办法
Node 版本太低报错 没装 v22+ 去 nodejs.org 下最新 LTS
3080 端口打不开 端口被占用 启动时加 --port 8080 换端口
全局安装后 pty.node 报错 npm 12 禁止了安装脚本 用 npm install -g @deepseek-ai/dsh --ignore-scripts=false
Web UI 保存 API Key 报错 用了非标准 API 网关 直接编辑 settings.yaml 配置文件
环境变量设了不生效 PowerShell 和 CMD 混用 在同一个终端窗口设置变量 + 启动
模型发不了图片 默认是纯文本模式 在 settings.yaml 里加 input: [text, image]
转圈超过 5 分钟不动 网络慢或首次下载 按 Ctrl+C 终止，重新执行命令（会接着下载）
九、一张图总结安装流程
1. 安装 Node.js 22+
↓
2. npx @deepseek-ai/dsh web
↓
3. 浏览器打开 http://127.0.0.1:3080
↓
4. Settings → Models → 填 API Key
↓
5. 选择工作区目录
↓
6. 输入自然语言 → Agent 开始干活
↓
7. 装插件 → 切模式 → 接第三方模型 → 自己造预设
十、最后说两句
1. 目前是 v0.1 开发者预览版，官方用全大写字母写了："THERE WILL BE COMPATIBILITY-BREAKING CHANGES"——未来会有破坏兼容性的变更。想尝鲜和开发的尽管上，但别把身家押上去当生产工具。
2. Python SDK 暂不支持 Windows，官方列出的支持平台是 Linux 和 macOS（Apple 芯片）。Windows 用户用 Web UI 就行，需要脚本化再考虑 WSL。
3. 第三方插件装之前看一眼源码。插件能碰你的 shell 和文件系统，安全攻击面比一般工具大，别什么插件都无脑装。
