DeepSeek Harness 中文入门:从启动到第一次任务

基于 DeepSeek Harness 0.2.2-rc.1 官方源码,完成 Node 环境检查、Web UI 启动、模型配置、工作区选择和第一次安全任务,并了解默认的会话日志上传。

社区整理已复核原始来源
DSH
0.2.2-rc.1
系统
Windows / macOS / Linux
风险
medium
本页目录(9)

先看结论

DeepSeek Harness(简称 DSH)最短的入门路径是:

  1. 确认 Node.js ≥24.9.0;
  2. 运行 npx @deepseek-ai/[email protected] web,浏览器会自动打开 http://127.0.0.1:3080;
  3. 在“设置 → 模型”配置模型;
  4. 选择工作区;
  5. 执行一个只读任务。

不想装 Node.js,可以改用官方桌面端(macOS Apple Silicon 与 Windows x64),它自带运行环境。

本文按 DSH 0.2.2-rc.1(固定提交 66491b05)的官方源码复核,属于源码审阅,没有运行实测。截至 2026-11-11,npm latest 与 next 都是 0.2.2-rc.1,仍是候选版;GitHub 上已有 0.2.2-rc.2 预发布,但还没有发布到 npm。DSH 仍处于开发者预览阶段,升级后要重新核对命令和配置。各版本的变化见 0.2 系列版本总览。

还不确定 DSH 和 DeepSeek 模型的区别,先读DeepSeek Harness 是什么;需要逐项检查环境时,使用安装与 Web UI 指南。

第一步:检查 Node.js

官方根包要求 Node.js 24.9.0 或更高,Node 22 自 0.2.2-rc.1 起不再支持。先在终端运行:

node --version
npx --version

版本低于 24.9.0 时,先升级 Node.js 再继续,排查方法见 Node 版本错误。如果暂时不能升级 Node,可以显式使用仍支持 Node 22.19 的 0.2.1-rc.5,但会缺少之后的修复和功能。

第二步:启动 Web UI

在你准备作为默认工作区的目录中运行:

npx @deepseek-ai/[email protected] web

在本机启动时,DSH 会用默认浏览器打开 http://127.0.0.1:3080。不想自动打开浏览器,加 --no-open;通过 SSH 启动时只打印地址,不会打开浏览器。启动命令所在目录是默认 workspace 根目录,但新的 Web UI 会话不会自动替你选中工作区,打开页面后需要自己添加并选择。端口冲突时不要反复重装,参考3080 端口占用修复。

第三步:配置模型

打开“设置 → 模型”,选择 DeepSeek 或其他 Provider,填写凭据并选择模型。0.2.1 起,在本机访问 Web 时也可以登录 DeepSeek 账号代替 API Key。新会话默认使用 deepseek-flash,已保存的模型选择优先。

DeepSeek API Key 保存后不会再以明文返回浏览器:官方实现把它写入 $DSH_HOME/.credentials.yaml,设置文件只保存引用。配置保存后立即生效,通常不需要重启。没有配置 DeepSeek 凭据时,模型选择器里不会显示 DeepSeek 分组,这不是安装失败。

两点容易踩坑:

  • 0.2.1 起,在 Web 中保存的密钥不会被 Headless 一次性任务使用,Headless 默认只读环境变量和 .env,见 Headless 指南。
  • 出现 MISSING_CREDENTIAL、UNKNOWN_MODEL 或模型列表 401 时,按模型、API Key 与 Provider 配置逐项检查凭据、模型 ID 和端点。

第四步:选择工作区

回到会话页,添加一个测试目录并设为当前 workspace。输入框仍然不可用时,先确认页面确实选中了工作区,而不只是从该目录启动了命令,判断方法见DSH 工作区未选择。

第一次不要选择整个用户目录、生产仓库或含大量私人文件的目录。建议新建一个只有少量示例文件的临时项目,用它观察读取、命令和审批行为。

第五步:执行第一次安全任务

建议输入一个没有写入副作用的任务:

只读取当前工作区,列出目录结构,并说明每个文件可能的用途。不要修改文件,不要安装依赖,不要访问工作区外路径。

观察三件事:模型是否收到你的要求、工具是否只访问预期目录、最终回答是否能由文件内容验证。DSH 的 Agent 可以读取和编辑文件、运行命令、调用工具并委派任务,是否需要审批取决于当前权限和工具策略。一次只读任务成功,不代表后续所有操作都安全。

理解默认权限

官方 CLI 参考说明,新 Web 会话默认使用 workspace-write 权限预设:Bash 和文件写入被限制在会话 workspace 与平台临时目录,读取和网络访问不受这项文件策略限制,进程可见性取决于沙箱后端。0.2.2-rc.1 还有两项默认变化:文件修改前的“先读后改”防护默认关闭;默认网页抓取不再拦截本机和内网地址。

处理敏感仓库时,从最小目录、最小凭据和明确审批开始。准备处理真实仓库前,阅读DSH 权限与沙箱指南;需要继续、分叉或压缩长任务时,阅读DSH Session 使用与恢复指南。

会话日志默认会上传给 DeepSeek

使用 DeepSeek 官方模型 API 时,DSH 默认会随后续请求把会话日志上传给 DeepSeek。官方说明导出内容可能包含消息文本、工具参数和结果,以及工作区路径。不希望上传时,在 Web 的“设置 → 通用 → 在使用官方模型 API 时上传 Session Log”中关闭。处理敏感项目前,先确认这个开关的状态。

完成后的检查

  • 记录 DSH 版本、Node 版本、操作系统、Provider 和验证日期。
  • 确认 API Key 没有出现在终端历史、截图、提交记录或公开 Issue 中。
  • 停止不再使用的进程,并检查测试目录有没有意外改动。
  • 继续了解DSH 插件、Profile 与 Bundle前,先理解插件代码和 MCP server 有各自独立的信任边界。

本文是完整路径,具体错误请进入对应排障页。如果你安装的版本和本页标注的不同,以官方仓库和命令帮助为准。

已经完成 Web 路径、希望不启动浏览器执行一次性任务时,可继续阅读DSH Headless 一次性 Agent 教程。

来源与维护信息

本文根据以下原始资料整理。版本变化后,请以官方资料和页面标注的验证日期为准。

完成当前任务后

按结果继续,不要停在文章末尾