第 5 卷

第 5 / 43 卷作者：Un-named日期：2026-08-17

第 2 章：五分钟快速上手

> 本章目标：**跟着做，跑起来**。每一条命令都给出预期输出与常见错误解法。建议打开终端边看边做。

TL;DR（本章核心，30 秒版）

**装**：`npx -y @deepseek-ai/dsh web` → http://127.0.0.1:3080
**两种常用模式**：web（对话 UI）/ headless（`dsh --profile headless "任务"`，

CI 友好）——官方共四种运行模式（见 2.4.1 总览）

**推理档位**：off / low（关闭或弱思考/最快，官方 provider 用 `off`，网关用

`low`）/ high（默认）/ max（最强）——**工具链任务 90% 时间在思考，降档是最快提速**

**模型**：`deepseek-v4-flash`（默认，性价比）或 `deepseek-v4-pro`（旗舰）
**配置**：`~/.dsh/settings.yaml`（模型 + 推理档位）

[2.1 准备工作（30 秒检查）](#21-准备工作30-秒检查)
[Node 版本红线（≥22.19）](#node-版本红线2219)
[2.2 安装（三种方式）](#22-安装三种方式)
[安装坑（社区真实踩过）](#安装坑社区真实踩过)
[2.3 模式一：Web UI（`dsh web`）](#23-模式一web-uidsh-web)
[2.4 模式二：Headless（一次性任务，适合脚本/CI）](#24-模式二headless一次性任务

适合脚本ci)

[2.4.1 官方四种运行模式总览](#241-官方四种运行模式总览)
[2.5 你的第一个插件：给 web 加个 Git 面板](#25-你的第一个插件给-web-加个-git-面

板)

[2.6 配置与目录速查](#26-配置与目录速查)
[2.7 命令速查](#27-命令速查)
[2.8 排障速查](#28-排障速查)

</details>

2.1 准备工作（30 秒检查）

需要	检查命令	通过标准
Node.js≥22.19	node --version	v22.19.0或更高（红线，

见下）

npm（随 Node 附带）npm --version有版本号即可

网络	能访问npm registry	能装包
（可选）DeepSeek API	https://	用于真实对话
Key	platform.deepseek.com

> 没有 API Key 也能启动 dsh（界面能开），但对话需要 Key。本白皮书示例假设已配置。

Node 版本红线（≥22.19）

社区实测发现 **Node < 22.19 会触发两个致命缺失**：

缺失API	报错示例	触发帖号
node:zlib无	TypeError:	#100https://
createZstdDecompress	zlib.createZstdDecompr	github.com/deepseek-
	ess is not a function	ai/deepseek-harness/

discussions/100

AbortSignal.timeout未	AbortSignal.timeout is	#311https://
实现	not a function	github.com/deepseek-

ai/deepseek-harness/ discussions/311

**Workaround**：用 nvm/volta/fnm 切换到 `22.19.0+`。Node 24 早期版本（如 v24.15）也可能触发 `install-lefthook failed`——若遇此错，pin 到 `22.19.0` 最稳 ([#748]

(https://github.com/deepseek-ai/deepseek-harness/discussions/748))。

2.2 安装（三种方式）

**方式一：直接运行（推荐新手）**

npx -y @deepseek-ai/dsh --version

首次运行会下载 dsh（包体较大，含 40+ 插件模块，约 1-3 分钟）。看到版本号即成功：

0.1.0-rc.6

**方式二：全局安装（推荐频繁使用）**

npm install -g @deepseek-ai/dsh dsh --version

**方式三：免装 Node 的安装包（新手可选）**

不想装 Node？社区作者 codeAnqiang-ma （[#380](https://github.com/deepseek-ai/deepseek-harness/discussions/380) 插件踩

坑帖作者，已授权收录）提供了**免装 Node 的安装包**——mac DMG / Windows exe，底层官方 dsh 原样打包、自带 Node 运行时，零前置依赖：

版本发布对应安装包，含 SHA256 校验）

适合「不想折腾 Node 环境、双击即用」的尝鲜用户；需要插件开发/频繁升级的话仍建议方式一或二。

安装坑（社区真实踩过）

坑	现象	解决	帖号
首次npx极慢	npxdsh web首次	耐心等待；改用	#176https://
（Windows）	在Windows上8+	npm i -g	github.com/
	分钟零反馈，npm	@deepseek-ai/ds	deepseek-ai/
	需下载500+包	h后秒启	deepseek-

harness/ discussions/176

pnpm dlx 404pnpm dlx用 npx 或 npm i -g#369https:// @deepseek-ai/ds替代 pnpm dlxgithub.com/

h web 报deepseek-ai/ @deepseek-ai/dsdeepseek-

h-pty@0.0.1-rc.2 harness/ 未发布

discussions/369

pnpm全局装后找	pnpm add -g	pnpm全局安装的	#55https://
不到插件	@deepseek-ai/ds	依赖解析策略与	github.com/
	h后启动报Cannot	npm不同；建议用	deepseek-ai/
	find package	npm i -g或npx	deepseek-
	'cordis-plugin-		harness/
	timer'		discussions/55
WSL2上npx装不	在WSL2（Ubuntu	先确认npm代理配	#118https://
上	等发行版）里npx	置；仍不行就改用	github.com/
	-y@deepseek-	源码安装（社区实	deepseek-ai/
	ai/dsh安装失败	测可行）	deepseek-

harness/ discussions/118

> **WSL2 安装注意**：社区在 [#118](https://github.com/deepseek-ai/deepseek-harness/discussions/118) 反映 WSL2 上

`npx` 安装可能失败（Windows 原生侧正常，见该帖"win 上都装好开始玩了"的对照）。排查顺序：① 确认 npm 代理/registry 配置；② 若 `npx` 仍装不上，**先试源码安装**（clone 官方仓

库后 `pnpm install`，社区实测可行）。详见该帖评论区。

> > 全局安装方式对比：**`npm i -g`** 最稳（社区验证最多）；**`npx`** 适合尝鲜；**`pnpm

dlx`** 暂不建议（rc 阶段 pty 包未发布到 pnpm 可见 registry）。

全站分卷索引 · 43 卷