dsh 命令行速查表
DeepSeek Harness 值得记住的每一条命令——安装、启动、模式、插件、配置与版本管理——整理成可打印的速查表。
最近更新: 2026-10-03
dsh 是 DeepSeek Harness 的命令行入口：一个二进制，启动所有形态——Web UI、终端会话、一次性 headless 任务，以及自动化 profile。它也是安装、更新、修复整套 harness 最快的路径。
本页是速查参考：只收录已核实的命令，全部取自官方 apps/cli README、根 README 与 npm 包，并与站内分步教程交叉核对。打印一份放在终端旁，需要完整步骤时再顺着链接进入教程。
速览
- ▸一条命令安装：npm install -g @deepseek-ai/dsh（需要 Node.js 20+）；不想装全局？npx @deepseek-ai/dsh web 直接跑。
- ▸dsh web 启动 Web UI（127.0.0.1:3080）；dsh --profile <名字> 启动任意 profile；dsh --profile headless 跑一次任务就退出。
- ▸插件按 profile 隔离：用哪个 --profile 装（dsh plugin --profile web add），就必须用同一个 profile 启动。
- ▸@latest 更新，精确版本号回滚（如 @0.2.0-rc.2）；任何排错前先跑 dsh --version。
安装与首次启动
从零到跑起来共四步。npm 路线是官方文档路线；源码路线服务于开发。
- 1
检查运行时
dsh 需要 Node.js 20 或更高版本（推荐 Node 22 LTS）。终端里 node -v 应显示 v20.0.0 以上——这一条检查能挡住最常见的「插件注册失败」工单。
$node -v - 2
全局安装 CLI
一次全局安装，dsh 命令进入 PATH；继续之前用 dsh --version 确认。macOS/Windows 桌面客户端（0.2.0-rc.2 起）还提供 Manage dsh command 菜单项，可以替你装好命令，无需单独的 Node.js 或 pnpm。
$npm install -g @deepseek-ai/dsh$dsh --version - 3
启动：装了用 dsh，没装用 npx
npx @deepseek-ai/dsh web 不做全局安装直接运行当前版本，是第一次体验最快的路。dsh web 效果相同：启动 Web profile、打开浏览器，并由命令本身打印访问地址（默认 127.0.0.1:3080；--no-open 不开浏览器，--port 换端口；SSH 下只打印主机地址）。首次连接模型在 Settings → Models 完成。
$npx @deepseek-ai/dsh web$dsh web - 4
替代路线：从源码运行
面向开发：克隆仓库，安装并构建一次，之后 pnpm dsh web 直接用构建产物，不再重复构建。同一个启动器转发所有参数——pnpm dsh --profile headless 接引号里的任务，且需要在环境变量或仓库根 .env 里配置 DEEPSEEK_API_KEY。
$git clone https://github.com/deepseek-ai/deepseek-harness$pnpm install$pnpm run build$pnpm dsh web
profile、镜像源与第三方插件审查清单，见安装教程： 安全地安装插件
模式对照：每个入口启动什么
dsh 没有单独的桌面、服务端或客户端二进制——一个启动器，不同 profile。下表内置 profile 首次使用时会自动从模板初始化。
| 模式 | 命令 | 给你什么 |
|---|---|---|
| Web UI | dsh web | 浏览器里的仪表盘（127.0.0.1:3080）：工作区、插件市场、设置。日常的可视化主界面。 |
| Headless | dsh --profile headless "task" | 每次调用一个全新持久化会话：执行任务、打印最终答案、退出。为脚本和 CI 而生。 |
| ACP | dsh --profile acp | 官方 automation-only 的 Agent Client Protocol 服务（JSON-RPC stdio）——给编辑器与自动化客户端；有意省略计划、标题、终端视图等呈现面。 |
| SDK | dsh --profile sdk | 通过 JSON-RPC stdio 服务 SDK 客户端，直到关闭或断开——程序化集成。 |
| SDK Minimal | dsh --profile sdk-minimal | 以独立最小代理树服务 SDK 客户端——最轻量的嵌入方式。 |
| TUI | dsh --profile tui | 终端原生会话；--resume <id> 这个 flag 属于该终端应用。 |
| Desktop | — | 保留给 Electron 桌面客户端——CLI 拒绝启动它、导出它的配置或管理它的插件。 |
模式是「表面」，会话能做什么由 agent 预设决定——Standard、PTC、Minimal、Creator 四个内置预设，区别在工具箱： 四种模式：Standard、PTC、Minimal、Creator
常用命令速查表
按用途分组，方便打印：插件、会话与 profile、配置检查、诊断，版本管理在下一节。命令逐字照录；安装时用的 flag 必须与启动时一致。
插件——按 profile 安装与管理
| 命令 | 作用 |
|---|---|
| dsh plugin --profile web list | 打印该 profile 的插件条目与磁盘目录——动手前先核对。 |
| dsh plugin --profile web add <package> | 从 npm registry 安装插件到 web profile（把 profile 名换成你自己的）。 |
| dsh plugin --profile web add github:owner/repo#tag | 安装仅发布在 GitHub 的插件，#ref 可钉住分支或标签。 |
| dsh plugin --profile web add ./path/to/plugin | 从本地文件夹安装插件——本地开发路线。 |
| dsh plugin --profile web update | 更新一个 profile 的全部插件。 |
| dsh plugin --profile web remove <package> | 从一个 profile 移除插件。 |
会话与 profile
| 命令 | 作用 |
|---|---|
| dsh web | 启动 Web profile——等同 dsh --profile web，命令会打印访问地址。 |
| dsh --profile <name> | 启动 $DSH_HOME/profiles/<名字> 下的指定 profile（web、headless、acp、sdk、sdk-minimal、tui 首次使用自动从模板初始化）。 |
| dsh --profile headless "one-off task" | Headless 一次性：全新持久化会话，打印最终答案后退出。 |
| dsh --profile tui --resume <id> | 在终端应用里恢复一个持久化会话。 |
| dsh --profile <name> --from-default-profile web | 从内置模板新建自定义 profile 并启动。 |
配置——先检查再修改
| 命令 | 作用 |
|---|---|
| dsh --dump-default-config | 不启动、直接打印默认组合树——看原生 dsh 会组装出什么。 |
| dsh --dump-config | 应用你的 profile 与 patch 覆盖后打印组合树——同样不启动。 |
| dsh --dump-config-schema | 打印插件条目与 patch 的 JSON Schema（而非配置值）。 |
| dsh --patch <file> | 本次启动在组合树之上再叠加一个 patch 文件。 |
| cat ~/.dsh/profiles/<name>/cordis.patch.yml | 手工读取某个 profile 的 patch 文件——若存在工作区级 .dsh/cordis.patch.yml，它会覆盖前者。 |
层级顺序：bundle patch → profile cordis.patch.yml → $DSH_HOME/cordis.patch.yml → --patch 覆盖。每次改配置先问自己「我在改哪一层」—— Profile、Patch 与 Preset
诊断
| 命令 | 作用 |
|---|---|
| dsh --version | 显示运行时版本（用于 peer 范围检查）。任何排错前先跑它。 |
| dsh --help | 启动器自带帮助；应用级 flag 因 profile 而异（试试 dsh --profile web --help）。 |
| node -v | 确认 Node.js 20+——插件注册失败最常见的原因。 |
| npm prefix -g | 打印 npm 全局前缀——dsh 可执行文件在其 bin 目录里；shell 报 command not found 时与 PATH 对照。 |
这里的命令跑不通时，按「症状 → 原因 → 修复」排错百科逐条处理： 故障排查与报错百科
重启与启动
没有 dsh restart 这样的子命令——重启就是停下再启动同一个 profile。官方参考的规矩：增删或更新 bundle 之后要重启那个 profile，因为插件树是启动时组装的。
| 命令 | 作用 |
|---|---|
| dsh web | 启动 Web UI——插件或配置改过之后再跑一次；不重新启动，改动都不算生效。 |
| dsh --profile <name> | 启动（或重启）任何 profile 都一样——「启动时组装插件树」的规矩对每个 profile 都成立。 |
| Ctrl+C → same start command again | 重启这个动作本身：第一次 SIGINT/SIGTERM 触发优雅排水（graceful drain）——退出进程，再用同一条命令启动。 |
| npx @deepseek-ai/dsh web | 不做全局安装直接启动——npx 一条命令拉起同一个 Web UI，适合临时用一次。 |
不是所有卡住都值得重启：桌面端命令跑到五分钟左右报「This operation was aborted」，那是讨论 #8737——本地长 RPC 在约 305 秒被客户端超时掐断，重启治不了。
版本管理
更新与回滚是同一条命令，区别只在标签。上车预发布通道前，先看 npm dist-tags 或 release notes。
| 命令 | 作用 |
|---|---|
| npm install -g @deepseek-ai/dsh@latest | 把 CLI 更新到 npm latest 最新——截至 2026-10-01 是 0.2.0-rc.2。 |
| npm install -g @deepseek-ai/dsh@<exact-version> | 钉住（或回滚到）精确版本——复现问题或恢复时永远不要用 @latest。 |
| dsh plugin --profile web update | 更新一个 profile 的插件。 |
| dsh plugin --profile web add github:owner/repo#v1.2.3 | 把插件钉在标签上，而不是跟随移动的分支。 |
升级前先备份 ~/.dsh/profiles/<名字>/cordis.patch.yml——0.2.0-rc 升级潮在讨论区留下了大量工作区被清空、插件批量失效的报告。
完整的更新与回滚教程（含 Web UI 市场路线）： 升级 DSH 与插件
平台一行卡
每个平台一段可复制的命令。四条路的终点相同：127.0.0.1:3080 的 Web UI。
macOS
终端里免安装直接跑，npm 只询问一次，输 y：
Windows
PowerShell（无需 WSL）：先装一次，再启动——
Linux
先查运行时，再免全局安装运行：
WSL2
WSL2 内直接用 Linux 命令；dsh 也能原生跑在 Windows 上，二选一并固定使用——混用会把 ~/.dsh 分成两份。
dsh CLI 常见问题
打开速查表之后最先冒出来的问题。
dsh 和 DeepSeek Harness 是同一个东西吗？
dsh 是 harness 的命令行入口，也就是 npm 上发布的 @deepseek-ai/dsh 包。桌面客户端与 Web UI 是同一棵树上的不同表面：dsh web 从同一份安装启动 Web profile。0.2.0-rc.2 起，macOS/Windows 桌面客户端还内置 Manage dsh command 菜单项，能替你安装并管理这条 CLI（含插件），无需单独的 Node.js 或 pnpm。
用 npx @deepseek-ai/dsh web 还是先全局安装？
npx 是零安装路线——拉包跑一次 Web UI，最快看到界面，也是全局安装坏了时的临时替代。日常使用建议全局安装（npm install -g @deepseek-ai/dsh）：dsh web 秒启，dsh --version 告诉你实际在跑什么，dsh plugin 管理插件。两条路线都可以用 dsh --version 验证。
装了插件，dsh 启动后却没有——去哪了？
几乎都是 profile 不匹配。dsh plugin --profile web add <包名> 把条目写进 web profile；之后如果直接运行 dsh（默认 profile），那棵树里没有这个插件。先用 dsh plugin --profile web list 确认条目和目录，再用 dsh --profile web 启动。所有 flag 同理：装的时候用什么，启动时就用什么。
profile 存在哪里，怎么新建？
profile 位于 $DSH_HOME/profiles/<名字>，也就是 harness home（默认 ~/.dsh，DSH_HOME 可改）下面。内置 profile（web、headless、acp、sdk、sdk-minimal、tui）首次使用自动从模板初始化。自定义 profile：dsh --profile <名字> --from-default-profile web 复制一份内置模板并启动。不启动、只看组合结果用 dsh --dump-config。
desktop profile 是干什么的——为什么 dsh 拒绝它？
desktop 这个名字保留给 Electron 桌面客户端。CLI 会拒绝启动它、导出它的配置、管理它的插件，所以 dsh --profile desktop 按设计直接报错。想要那个表面就用桌面客户端；浏览器路线用 dsh web。
dsh 怎么更新？升级坏了怎么回滚？
更新：npm install -g @deepseek-ai/dsh@latest（npm latest 截至 2026-10-01 是 0.2.0-rc.2），然后 dsh --version 确认。回滚：改装精确版本 npm install -g @deepseek-ai/dsh@0.1.5-rc.2——永远不要用 @latest 回滚。升级前先备份 ~/.dsh/profiles/<名字>/cordis.patch.yml；单个插件可用 dsh plugin add github:owner/repo#v1.2.3 钉住。
相关教程
每张速查表背后的完整分步教程。
DeepSeek Harness：10 步全流程导览
从 git clone 到 headless 模式——安装、接服务商、配预设、Creator 模式造插件、沙箱与轨迹收据，一篇导览走完。
阅读指南安全地安装插件
dsh 里“安装插件”到底发生什么，附一套第三方代码审查清单。
阅读指南四种模式：Standard、PTC、Minimal、Creator
每种 agent preset 包含什么、什么场景用哪种，以及怎么在 Creator 模式里做自己的 preset。
阅读指南Profile、Patch 与 Preset
一个 dsh 进程如何由层层配置组装而成——以及怎么把它调成你的形状。
阅读指南升级 DSH 与插件
经过核实的升级命令：查版本、升级 dsh CLI、在终端或 Web UI 插件市场更新插件，以及安全回滚。
阅读指南故障排查与报错百科
症状 → 原因 → 修复：安装失败、pnpm workspace allowlist 报错、cordis.patch.yml 冲突、bundle 格式错误与 Profile 不生效。
阅读指南