跳过主要内容
全部文章
教程

DeepSeek Harness 快速上手：从 npx 到你的第一个 Agent 会话

用 npx 安装 DeepSeek Harness，打开 127.0.0.1:3080 的 Web UI，填入 API key，选择工作区，跑通你的第一个 dsh agent 任务。

执行 npx @deepseek-ai/dsh web，在浏览器打开 http://127.0.0.1:3080，到 Settings → Models 填入 DeepSeek API key，选一个工作区目录，然后发送一个任务——这就是从零到跑通第一个 DeepSeek Harness（dsh）agent 会话的全部路径。不需要注册账号，也不需要提前手写配置文件。本文按顺序讲清楚每一步，以及那个权限确认弹窗到底是什么意思、如何装上你的第一个插件。

前置要求

dsh 是一个 Node.js CLI，唯一的硬性要求是较新的 Node 运行时：

要求版本
Node.js^22.19.0 || >=24.0.0（来自 apps/cli/package.json 的 engines 字段）
CI 覆盖的版本Node 22.19、24、26
pnpm装插件时才需要（dsh plugin 直接调用 pnpm）
启动 dsh 用的包管理器npm 的 npx（如下），或等效的 pnpm/bun 命令

如果你的 Node 版本较旧，先升级再开始——低于 22.15 的 Node 版本在 dsh 试图解压某个内部模块时会立刻报 node:zlib 错误（缺少 createZstdDecompress）。这个坑以及其他平台专属的安装问题，详见 在 macOS、Windows、Linux 上安装 DeepSeek Harness。

第一步：启动 Web UI

npx @deepseek-ai/dsh web

这条命令会拉取最新发布的包——截至本文撰写时 npm 上是 0.1.0-rc.6——并启动 Web UI，默认监听 http://127.0.0.1:3080。dsh web 是 dsh --profile web 的硬编码别名，所以第一次运行时还会用内置的 base + web-app bundle 模板，在 $DSH_HOME/profiles/web 下初始化一个 web profile（默认 $DSH_HOME 是 ~/.dsh）。

注意 dsh 仍处于开发预览期：README 明确写着版本之间会有破坏性变更。如果需要 CI 或自动化脚本的可复现性，请锁定版本号（npx @deepseek-ai/dsh@0.1.0-rc.6 web）。

在浏览器打开命令打印出来的地址。你会先看到一个设置引导页而不是聊天框——这是正常的，因为还没有配置任何模型 provider。

第二步：填入你的 API key

打开 Settings → Models。DeepSeek 卡片只有一个 API key 输入框，粘贴你的 key 并保存。不需要重启进程——你下一次发起请求就会立刻用上新的凭据。

在底层，这个 key 会被写入 $DSH_HOME/.credentials.yaml，Web UI 保存后不会再把明文回显出来，只显示一个脱敏的引用描述符。如果你想改用别的 provider——Anthropic、OpenAI，或者自建的 OpenAI 兼容端点——完整的配置路径见 配置你的 DeepSeek API Key 与模型 和 在 DeepSeek Harness 中使用 OpenAI、Anthropic 或任意 OpenAI 兼容 API。

第三步：选择一个工作区

在开始会话之前，dsh 要求你先选一个工作区（workspace）——agent 会把它当作自己的工作根目录。这不是可选项：没有选定工作区，"新建会话"流程就无法继续。

目录选择器有两种可能的后端：原生系统对话框（directory-picker-native）或应用内浏览式对话框（directory-picker-browse）。在某些平台上——尤其是 Windows，原生选择器依赖一个叫 koffi 的绑定——原生对话框可能加载失败；如果你遇到这个问题，切换后端的方法见我们的 Web UI 指南。

不管你选哪个目录，在默认的 workspace-write 沙箱模式下（下面会讲），它就会成为 dsh 信任的、可写入的根目录。

第四步：发送你的第一个任务

在输入框里写一个任务并发送。几件事会自动发生：

  • dsh 会加载工作区根目录下能找到的任何 AGENTS.md 或 CLAUDE.md 文件，渲染预算最多 65,536 字节，并把内容并入 agent 的上下文。
  • 新会话默认使用 workspace-write 沙箱模式：agent 可以读写文件、跑命令，但文件系统写操作被限制在工作区根目录和平台临时目录内。这个模式本身不限制网络访问。
  • 如果你想从最精简的 agent 开始，dsh 内置了一个 minimal 预设——系统提示固定为 You are a helpful software engineer assistant.，只挂载 bash 和 str_replace_editor 两个工具。Web UI 新建会话时可以选这个"极简模式"。

你会看到 agent 的计划和工具调用实时流式输出。这是一个标准的、由 Cordis 插件驱动的 agent 循环：它用到的每一个工具——文件编辑、shell 命令、网页搜索——本身都是注册在当前运行的 dsh 实例上的一个插件。

第五步：处理审批弹窗

因为默认的权限预设是 workspace-write 沙箱搭配 ask 审批策略，你会不时看到一个弹窗询问是否允许某个具体操作——通常是触及沙箱边界之外的操作，或者插件作者标记为需要确认的操作。你可以就地允许或拒绝；默认情况下不会有任何操作静默执行。

如果你想要更严格或更宽松的策略——纯查看用的 read-only，或者完全不做沙箱、不弹审批窗的 danger-full-access——这是一个权限预设的选择,上面链接的 Web UI 指南里有讲。

第六步：安装你的第一个插件

dsh 自身只提供核心能力；其他几乎所有东西——UI 增强、记忆、浏览器控制、通知——都来自社区插件生态。安装一个插件只需要一条命令：

dsh plugin --profile web add github:liustack/modlens

这条命令会安装 modlens——一个让纯文本模型能处理粘贴图片的视觉桥接插件，是 FindHarness 人工审核索引里 star 数最高的条目之一。这条命令的完整机制——npm / GitHub / 本地路径三种来源、allowBuilds 安全提示、更新和卸载——详见 如何安装 DeepSeek Harness 插件。你可以在 FindHarness 插件列表 按分类浏览完整目录，或者直接从 UI 增强 或 工具与能力 这类分类页开始逛。

快速上手清单

[ ] 安装 Node.js ^22.19.0 或 >=24.0.0
[ ] npx @deepseek-ai/dsh web
[ ] 浏览器打开 http://127.0.0.1:3080
[ ] Settings → Models → 保存 DeepSeek API key
[ ] 选择工作区目录
[ ] 发送第一个任务，理解审批弹窗
[ ] 用 dsh plugin --profile web add ... 装上第一个插件

FAQ

运行 npx 之前需要单独安装 dsh 吗？

不需要。npx @deepseek-ai/dsh web 会按需下载并运行这个包，上手不需要额外的全局安装步骤。一旦你开始装插件，就需要确保 pnpm 在 PATH 里，因为 dsh plugin 会把参数原样转发给 pnpm。

npx 安装的是哪个版本？

取决于 npm latest 标签当前指向的版本——截至本文撰写时是 0.1.0-rc.6。dsh 没有 GitHub Releases 页面也没有 CHANGELOG，npm 是判断"你实际在跑哪个版本"的唯一可信来源。如果需要一个稳定的目标版本,请显式锁定（@deepseek-ai/dsh@0.1.0-rc.6）。

DeepSeek Harness 是免费的吗？

dsh 这个软件本身是 MIT 协议、免费的。但你仍然需要接入的模型 provider 的 API 额度——不管是 DeepSeek 自己的 API，还是任何你配置的 OpenAI 兼容/Anthropic 兼容端点。

我能跳过 Web UI，直接从终端跑一个任务吗？

可以——这正是 headless 模式的用途。见 DeepSeek Harness Headless 模式，了解一次性 CLI 和 CI 用法。

为什么我在局域网内的另一台机器上访问不了 Web UI？

这是设计使然。出于安全考虑，--host 0.0.0.0 有意不被支持——把端口暴露出去等于把远程代码执行能力暴露给了你的网络。请只用 127.0.0.1，或者用你自己信任的隧道/端口转发方案，详见 Web UI 指南。

Next steps