转载：小红书 AI产品赵哥
前言 🔖
DeepSeek Harness（简称 DSH）是 DeepSeek 在 2026 年 8 月 13 日正式开源的 AI Agent 运行框架，MIT 协议，口号是：一切皆插件。
一句话解释：模型负责思考，Harness 负责动手。光有模型只能聊天，加上 Harness，AI 就能读你的代码、跑你的命令、改你的文件。
💡 Agent = Model + Harness
目前是 v0.1 开发者预览版，功能迭代快，适合尝鲜和研究，不建议直接上生产环境。
第一步：安装 Node.js 🔖
DSH 基于 Node.js 运行，先确认电脑上有这个环境。
检查是否已安装
打开终端（Windows 用命令提示符或 PowerShell），输入：
node --version
如果看到版本号（比如 v22.19.0），说明已经有了。建议版本 v22.19 以上，官方要求是 ^22.19.0 || >=24.0.0。
没装咋办？
去 nodejs 官网下载 LTS 长期支持版本，傻瓜式安装就行。
装完后重新打开终端，再执行 node --version 确认一下。很多时候 “找不到命令” 就是环境变量没刷新。
第二步：一键安装并启动 DSH 🔖
这是最快的方式，一条命令搞定：
npx @deepseek-ai/dsh web
或者全局安装后使用（以后用着更方便）：
npm install -g @deepseek-ai/dsh dsh web
两种方式选一种就行。推荐第一种 npx，适合首次尝鲜。
💡 如果卡住了怎么办？
npx 卡住，八成是网络问题 —— 换国内 npm 镜像源，或者直接从 GitHub 克隆源码安装。
跑起来后，终端会显示：
浏览器打开这个地址，就能看到 DSH 的 Web 界面了。
第三步：首次打开，三步配置 🔖
输入框默认是灰的，需要先做两件事才能开始对话。
🔹1 配置 API Key
进入 Settings → Models，找到 DeepSeek 卡片，填入你的 API Key 并保存。
还没有 Key？去任何一家开放平台注册账号，创建一个 sk‑xxx 格式的 Key。注意不要泄露给别人。
注意：可以接入其他 OpenAI 兼容的模型，不一定要用 DeepSeek 自家的。
🔹2 选择工作区
点「选择工作区」，添加一个你想让 AI 操作的文件夹。建议单独准备一个练习目录，避免 AI 误操作重要文件。
你在哪个目录启动 dsh web，那个目录就是默认工作区。
🔹3 选择运行模式
DSH 提供了四种预设模式，不同模式加载不同插件：
| 模式 | 特点 | 适合谁 |
|---|---|---|
| 标准模式 | 功能完整，包含文件编辑、Shell、搜索、子代理等 | 日常使用，大部分场景选这个 |
| PTC 模式 | 允许模型写 TypeScript 程序来组合多步操作 | 需要处理复杂自动化任务 |
| 极简模式 | 仅保留 Shell 和文件编辑两个工具 | 做基准测试、最小化复现 |
| 创造模式 | 提供运行时检查和插件实验指导 | 想自己开发插件和预设的开发者 |
第一次用选标准模式就行。
第四步：开始你的第一次对话 🔖
配置完成后，在对话框输入任务，点击发送。
新手建议从简单任务开始，别上来就把几百 GB 的项目扔进去。
推荐先试这个：
分析当前目录的结构，生成一个简要说明
或者：
帮我看看这个项目里有哪些测试文件
DSH 会开始工作 —— 读取文件、执行命令、调用工具，并把每一步的执行过程展示给你看。
🔹进阶一：从源码安装（想读源码 / 开发插件）
如果你不满足于一键启动，想深入研究或二次开发，可以走源码安装：
# 克隆仓库 git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness # 安装pnpm (如果没有的话) npm install -g pnpm # 安装依赖并构建 pnpm install pnpm run build # 启动 pnpm dsh web
🔹进阶二：Python SDK（程序化调用）
如果想在脚本或 CI/CD 中调用 DSH，可以用官方 Python SDK：
# 克隆仓库 git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness # 创建虚拟环境 python -m venv .venv source .venv/bin/activate # Windows用 .venv\Scripts\activate # 安装SDK pip install deepseek-harness-sdk # 设置API Key export DEEPSEEK_API_KEY=sk-your-key-here
然后参考仓库 examples 目录下的脚本，编写自己的调用代码。
安装常见问题与解决方法 🔖
我在首次安装的过程中，也遇到了一些问题，现整理如下。随着我的使用，发现更多问题再和大家分享。
🔹1 首次运行 npx 卡住不动
现象：执行 npx @deepseek‑ai/dsh web 后，终端只显示几行警告甚至完全没输出，看起来像卡死了，持续几分钟毫无反应。
终端示例：
原因：首次运行时，npx 会从 npm 仓库下载完整的依赖包。这不是卡死，而是在下载。但在 Windows 环境下，这个过程可能会好几分钟，且没有任何进度反馈。
解决方法：
- 耐心等待：首次下载确实需要时间，可以观察任务管理器的网络占用，确认是否在下载。
- 配置国内镜像源：在国内使用淘宝镜像源加速：配置后重新执行启动命令。
npm config set registry https://registry.npmmirror.com
- 改用全局安装：避免每次 npx 都重新下载缓存：
npm install -g @deepseek-ai/dsh dsh web
🔹2 Node.js 版本不兼容
现象：启动时报错，提示与 Node.js 版本相关。
解决方法：
- 在终端运行
node --version确认当前版本。 - 如果版本低于 v22.19，前往 nodejs 官网下载最新的 LTS 版本进行升级。
- 部分桌面应用可能要求 Node.js 24 或更高版本，注意查看对应说明。
🔹3 明明装了 Node.js，但提示找不到命令
现象：运行 node --version 时，提示 'node' 不是内部或外部命令。
解决方法：先关闭当前终端窗口，重新打开一个新的终端再试一次。这通常是因为安装 Node.js 后，环境变量没有立即刷新。如果问题依旧，需要手动将 Node.js 的安装目录添加到系统环境变量 Path 中。
🔹4 Windows 系统下 Bash 工具不可用
现象：使用极简模式时，涉及 Bash 命令的操作失败。
原因：Windows 系统默认没有内置 Bash 环境。
解决方法：
- 安装 Git for Windows：安装后它会提供一个可用的 Bash 环境。
- 切换模式：在 Windows 下使用 Bash 工具，需要将 Agent 的运行模式切换为 Full Access（完全访问）模式，全称
danger‑full‑access。 - 使用社区适配 Preset：社区已有开发者制作了专为 Windows 适配的
Minimal（Git Bash）预设，可以在 Web UI 中直接切换。
🔹5 桌面版封装应用启动报错
现象：使用第三方封装的 DSH 桌面应用时，启动超时或提示缺失依赖。
解决方法：
- 检查应用版本：确保你使用的是最新版本（部分桌面版已修复漏打包依赖的问题）。
- 数据目录冲突：某些桌面版会使用独立的数据目录（如
AppData\Roaming\dsh‑desktop\dsh‑home）来避免与旧的~/.dsh目录冲突。如果启动超时，检查是否有残留的 DSH 进程占用了端口，或清理旧的缓存目录。 - 安装路径：确保安装路径为纯英文字符，避免因中文路径导致渲染进程异常。
🔹6 插件加载失败或配置文件错误
现象：安装某个插件后，DSH 启动失败，或插件无法使用。
解决方法：
- 使用诊断工具：官方提供了
dsh‑doctor，可以自动扫描并尝试修复常见的配置问题：
npx dsh-doctor scan --profile web npx dsh-doctor recover --profile web
它会创建恢复点，修复失败时自动回滚，相对安全。
- 手动检查：检查
~/.dsh/profiles/web/cordis.patch.yml等配置文件是否有语法错误（如 YAML 格式不对），或引用了不存在的插件。
🔹7 端口 3080 被占用
现象：启动时终端报错 EADDRINUSE: address already in use。
解决方法：最常见的是之前启动的 DSH 实例没有完全关闭。关闭所有终端窗口，或在任务管理器中结束所有 node 进程，然后重新启动。如果确实需要更换端口，可以查阅官方文档配置其他端口。