DeepSeek Harness 上手教程：从安装到第一个 AI Agent 任务

本文带你从零开始安装 DeepSeek Harness（dsh），配置好模型，跑通第一个 AI Agent 任务。全程约 15 分钟，跟着做就行。

一、DeepSeek Harness 是什么？为什么值得学？

DeepSeek Harness（简称 dsh） 是 DeepSeek 官方开源的 AI Agent 运行框架，设计理念是 "万物皆插件"（Everything is a Plugin）：模型接入、沙箱 Shell、文件编辑、子 Agent、Web 界面等所有能力都是可插拔的插件，底层由 Cordis 微内核驱动。

简单说，它能把一个大语言模型变成一个真正能干活的编码 Agent：读写你的项目文件、执行终端命令、拆解任务委派给子 Agent、维护执行计划——而且自带图形化的 Web UI，不用记复杂命令就能用。

几个值得学的理由：

• 官方出品、开源免费：DeepSeek AI 官方项目，MIT 协议，GitHub 已有超 24 万 star，是 2026 年 9 月 Agent 基础设施领域声量最高的国产开源项目之一。
• 上手门槛低：一条 npx 命令启动 Web 界面，配好 API Key 就能用；同时支持无头 CLI 模式，方便接入脚本和自动化流程。
• 国内可用：DeepSeek API 国内直连，无需特殊网络环境。
• 可扩展：插件架构意味着你可以自己开发插件，给 Agent 加新能力。

⚠️ 注意：项目目前处于 developer preview（开发者预览） 阶段，迭代很快，未来版本可能有不兼容的 breaking change。生产环境使用前请评估。

二、环境准备

开始之前，先确认电脑上有 Node.js。dsh 对版本有明确要求：

先检查版本：

node -v
# 期望输出 v22.19.0 以上（如 v22.23.1），或 v24.x.x

如果版本不对或没装，去 Node.js 官网 下载安装 LTS 版本，或用 nvm 安装：

# macOS / Linux（已装 nvm）
nvm install 22
nvm use 22

Windows 用户：在 PowerShell 里可以用 winget install OpenJS.NodeJS.LTS 安装，装完后重启 PowerShell 再继续。

另外准备好：DeepSeek API Key（获取方式见第四节）。

三、安装

官方推荐的方式不需要全局安装，用 npx 直接运行即可。先新建一个空文件夹作为演示工作区（让 Agent 的第一个任务有个干净的地盘）：

mkdir dsh-demo && cd dsh-demo

然后启动：

npx @deepseek-ai/dsh web

第一次运行会自动下载 @deepseek-ai/dsh 包，稍等片刻。启动成功后：

• Web UI 默认跑在 http://127.0.0.1:3080
• 本地启动时会自动用默认浏览器打开页面
• 进程保持在前台运行，按 Ctrl+C 停止服务

常用启动参数：

npx @deepseek-ai/dsh web --no-open    # 不自动打开浏览器，只打印地址
npx @deepseek-ai/dsh web --port 3081  # 3080 端口被占用时换端口
dsh --version                          # 装好后查看版本（全局安装时）

进阶：也可以 npm install -g @deepseek-ai/dsh 全局安装后直接用 dsh web；想从源码构建可 git clone 仓库后 pnpm install && pnpm run build && pnpm dsh web。新手用 npx 方式就够了。

四、配置 DeepSeek API Key

dsh 本身不带模型，需要你提供 API Key。没有 Key 的话，Agent 是"空转"的——界面能开，但发任务会报错。

获取 API Key（DeepSeek 开放平台）：

1. 打开 https://platform.deepseek.com，注册 / 登录账号
2. 进入 API keys 页面，创建一把新的 Key 并复制
3. 注意：API 调用按量计费，请确认账户有可用余额

在 Web UI 里配置：

1. 打开 Web UI（http://127.0.0.1:3080）
2. 点击 设置（Settings）→ 模型（Models）
3. 粘贴你的 DeepSeek API Key，保存
4. 模型路由会立即生效，无需重启服务

dsh 也支持其他模型提供方和自定义 OpenAI 兼容接口（见官方模型配置指南），本文先用官方 DeepSeek API 走通全流程。

五、选择工作区

dsh 有个重要概念：工作区（workspace）。Agent 只能读写你明确授权的目录，这是它的安全边界。

• dsh 进程启动时所在的目录就是默认的文件系统位置——这就是我们第三节先 cd dsh-demo 再启动的原因。
• 首次打开 Web UI 时没有选中任何工作区，会话输入框是不可用的。
• 点击 选择工作区（Choose workspace），添加启动 dsh 时所在的 dsh-demo 目录并选中它。

六、跑第一个 Agent 任务

万事俱备，开始一个新会话，在输入框里发送你的第一个任务。建议用这个具体可复现的小任务：

在当前目录下创建一个 todo.html，用纯 HTML/CSS/JS 实现一个待办清单网页：可以添加事项、删除事项、勾选完成状态，页面简洁美观。完成后告诉我文件位置。

然后观察 Agent 干活：

1. 制定计划：Agent 会先把任务拆成步骤（创建 HTML 骨架 → 写样式 → 写交互逻辑 → 自查）。
2. 读写文件：在工作区里创建 todo.html，你可以在左侧文件树里实时看到文件生成。
3. 请求审批：如果某步操作触发了权限策略（比如执行命令），Web UI 会先弹窗问你，允许 / 拒绝由你决定。
4. 汇报结果：完成后 Agent 会总结做了什么、文件在哪。

验证成果：在文件管理器里找到 dsh-demo/todo.html，双击用浏览器打开，试试添加、勾选、删除——一个能用的待办清单就诞生了，代码全是 Agent 写的。

再玩一个：让 Agent 给这个页面加个"深色模式"切换按钮，体验多轮对话、增量修改的工作流。你会发现 Agent 能读懂自己之前写的文件，直接做 diff 级修改。

七、常用技巧与命令

# 启动 Web UI（日常最常用）
npx @deepseek-ai/dsh web

# 无头模式：跑一次性任务，不开 Web 界面，直接打印最终答案后退出
DEEPSEEK_API_KEY=你的Key npx @deepseek-ai/dsh --profile headless "总结这个工作区"

# 查看版本
npx @deepseek-ai/dsh --version

使用技巧：

• 任务描述越具体越好：把"做个网页"换成"用纯 HTML/CSS/JS 做个待办清单，支持增删和勾选"，Agent 返工次数会少很多。
• 先小步验证：复杂项目先让 Agent 生成骨架、跑通，再逐步加功能，别一次性扔一个巨型需求。
• 善用审批机制：不确定 Agent 要执行的命令是否安全时，点"拒绝"并追问一句让它解释，这是 preview 阶段的好习惯。
• 换工作区 = 换项目：在不同目录启动 dsh，或在 UI 里切换工作区，就能让 Agent 在不同项目间干活。
• 想写插件：官方文档有专门的插件开发指南，所有能力都是插件，意味着你也能给 Agent"装外挂"。

八、常见问题

Q：node -v 显示 v23.x，启动报错怎么办？ A：23.x 全系不受支持。升级到 ^22.19.0 或 >=24.0.0（推荐 22.x LTS）。

Q：提示 3080 端口被占用？ A：换个端口启动：npx @deepseek-ai/dsh web --port 3081，然后访问 http://127.0.0.1:3081。

Q：npx 下载很慢或失败？ A：检查网络，或给 npm 配置国内镜像源后再试；也可以改用 npm install -g @deepseek-ai/dsh 全局安装。

Q：发任务后提示模型不可用 / 401 错误？ A：一般是 API Key 没配好或余额不足。去 Web UI 设置 → 模型里重新粘贴 Key，或登录 DeepSeek 开放平台 检查 Key 状态和账户余额。

Q：浏览器打不开 Web UI？ A：确认终端里 dsh 进程还在运行（Ctrl+C 会停止服务）；确认访问的是终端打印的地址，默认 http://127.0.0.1:3080。

Q：Agent 的每一步都要我点"允许"，很烦？ A：这是权限策略在保护你的文件系统。熟悉之后可以在设置里调整策略，但新手期建议保持默认——安全比省事重要。

Q：有中文文档吗？ A：有。官方文档站提供中文版（见下方官方资源），仓库 README 也有中文版。

九、官方资源链接汇总

遇到问题优先查官方文档，或去 GitHub Discussions / Discord 社区提问（仓库 README 里有入口）。

教程到此结束。下一步可以试试：让 Agent 读一个你自己的小项目并做总结，或者跟着官方文档学写第一个 dsh 插件——"万物皆插件"的真正玩法从那里开始。