2026年DeepSeek Harness常用命令大全

前言

DeepSeek Harness 开源之后，很多小伙伴第一时间就装上了。

装完之后发现一个问题——

。

• dsh web 能跑起来，但 --profile headless 是干嘛的？
• --patch 什么时候用？
• --dump-config 和 --dump-default-config 有什么区别？
• 插件怎么装？
• 参数顺序有什么讲究？

这些问题我一开始也懵。

翻了一晚上官方文档和社区资料，才把整个命令体系摸清楚。

今天这篇文章，我就把 dsh 的所有命令从头到尾整理一遍，形成一份完整的速查手册。

希望对你会有所帮助。

一、dsh 到底是什么？

在聊具体命令之前，我们先花 2 分钟搞清楚一件事：

dsh 是

。

它的核心作用是

——所谓 profile，就是由多个插件组合包按顺序叠加而成的运行配置。

简单说：

。

内置了两个 profile：

• web：启动 Web UI
• headless：一次性任务模式，跑完打印结果就退出

这两个 profile 首次使用时都会从随附模板自动初始化。

其他 profile 需要通过 dsh plugin 命令自行创建。

二、启动命令

2.1 方式一：npx 一键启动（尝鲜首选）

这是最快的方式，适合首次体验、不想装全局包：

npx -y @deepseek-ai/dsh web

执行后浏览器会自动打开本地界面，默认地址 http://127.0.0.1:3080。首次使用会自动初始化配置目录。

：需要 Node.js ≥ 22。

2.2 方式二：全局安装（日常使用）

如果你打算长期使用，建议全局安装：

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

装好后，后续直接输入 dsh web 即可启动，不用每次都敲 npx。

：npx @deepseek-ai/dsh适用于首次安装或临时调用；当安装完成后，便可以直接使用dsh命令。需要注意的是，这两者后续所接的参数完全一致。

2.3 方式三：从源码运行（适合二次开发）

如果你想修改源码或开发插件：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

构建完成后用 pnpm dsh 代替 dsh 命令即可，参数用法完全一致。

三、Profile 启动命令

这是 dsh 最核心的命令模式：

dsh --profile <名称>

启动位于 $DSH_HOME/profiles/<名称> 的指定 profile。

：

# 启动 Web UI（最常用）
dsh web                    # --profile web 的别名

# 启动 Web UI（完整写法）
dsh --profile web

# 一次性任务模式
dsh --profile headless "任务描述"

：

# 启动名为 my-agent 的自定义 profile
dsh --profile my-agent

：web 和 headless 以外的 profile 必须通过 dsh plugin 命令先创建才能使用。

四、一次性任务命令（headless 模式）

不想开界面，直接跑一个任务拿结果——这是 headless 模式的核心价值：

dsh --profile headless "你的任务描述"

：

# 让 Agent 总结当前仓库
dsh --profile headless "Summarize this repository and identify its main packages."

# 跑测试并汇总结果
dsh --profile headless "把当前目录的测试跑一遍并汇总结果"

# 验证 CLI 链路是否正常
dsh --profile headless "Say hello in one line."

运行后会打印 Agent 的最终回答并退出，

。

：

• 0
  ：headless 任务正常完成（最终轮次结束）

• 非零
  ：配置错误、启动失败或任务失败

写脚本时可以直接用退出码判断成败。

五、插件管理命令

Harness 的口号是“一切皆插件”，插件管理自然也是高频操作：

dsh plugin --profile <名称> 

这个命令把 pnpm 操作转发到指定 profile 目录，用来给 profile 安装、移除插件。

：

# 给 web profile 安装社区插件
dsh plugin --profile web add dsh-some-plugin

# 安装特定版本的插件
dsh plugin --profile web add @rvaim/dsh-compat@latest

# 给 tui profile 安装终端插件
dsh plugin --profile tui add @wxgmjfhy/dsh-tui

# 给 headless profile 安装插件
dsh plugin --profile headless add @useorgx/deepseek-harness-plugin@0.1.0

：

dsh plugin --profile web remove dsh-compat
dsh plugin --profile tui remove @wxgmjfhy/dsh-tui

：插件变更后通常需要重启 Harness 才能生效。在 Web UI 中也可以通过“设置 → 插件”进行可视化管理。

六、查看帮助与配置

6.1 查看帮助

# 查看启动器自己的帮助（profile 启动器的参数）
dsh --help

# 查看 Web 应用自己的参数（而不是启动器的）
dsh --profile web --help

# 查看 headless 应用的参数
dsh --profile headless --help

：裸 --help 显示的是启动器的帮助；加 --profile 后显示的是该应用的参数帮助。

6.2 查看配置（排查问题很有用）

# 查看内置默认配置（未叠加任何 patch）
dsh --dump-default-config

# 查看叠加所有层后的最终配置
dsh --dump-config

这两个命令在不启动的情况下检查组合后的配置树，

。

6.3 临时覆盖配置

# 用一次性覆盖层启动（不改文件）
dsh --patch <文件路径> --profile web

--patch 会替换目标行的整个 config 值，而不是深度合并其中的键。

七、最重要的规则：参数顺序

这是 dsh 命令最容易踩的坑。

。

# ✅ 正确：启动器参数在前，应用参数在后
dsh --profile web --port 8080        # --port 是 web 应用的参数
dsh --profile tui --resume       # --resume 是终端应用的参数
dsh --profile headless "run tests"   # 任务文本是应用参数

# ❌ 错误：应用参数跑到了启动器前面
dsh --port 8080 --profile web        # 启动器看不到 --profile

# 看帮助的区别
dsh --profile web --help             # 看 web 应用自己的参数
dsh --help                           # 看启动器的参数

：启动器参数在最前，应用参数在最后。

八、Python SDK 调用

除了 CLI 命令，Harness 还提供了 Python SDK：

# 安装 Python 库
pip install deepseek-harness

# 安装 CLI 工具
pip install deepseek-harness-cli

# MCP 服务器（stdio transport）
npx -y @deepseek-harness/mcp

在 Python 代码中调用 Harness 的完整示例可以参考官方 Python SDK 文档。

九、完整命令速查表

命令	作用
npx @deepseek-ai/dsh web	一键启动 Web UI
dsh web	启动 Web UI（全局安装后）
dsh --profile	启动指定 profile
dsh --profile headless "任务"	一次性任务，跑完退出
dsh plugin --profile	管理 profile 插件
dsh --help	启动器自己的帮助
dsh --dump-default-config	打印内置默认配置
dsh --dump-config	打印叠加后的最终配置
dsh --patch	用一次性覆盖层启动
pnpm dsh web	从源码启动（构建后）

十、优缺点

优点

：核心命令只有十几条，日常常用的不超过 5 条。dsh web 一条命令就能跑起来。

：Web UI 适合日常开发，headless 模式适合脚本和 CI/CD。

：一条 dsh plugin 命令搞定所有插件操作，统一通过 pnpm 管理。

--dump-config 和 --dump-default-config 让配置问题一目了然。

“启动器在前，应用在后”的规则一旦记住，基本不会出错。

缺点

：启动器的 flag 必须写在最前面，否则会被误解为应用参数。

：dsh 当前为 0.1.0-rc.6（预发布阶段），生产环境请谨慎评估。

web 和 headless 以外的 profile 必须通过 dsh plugin 先创建。

：需要 Node.js ≥ 22 才能运行。

十一、常见问题速查

A：npx @deepseek-ai/dsh 是首次安装/临时调用；装好后可以直接用 dsh 命令。

两者后续参数完全一致。

A：确认是否已安装，或改用 npx @deepseek-ai/dsh 前缀。

A：手动访问 http://127.0.0.1:3080，确认端口没被占用。

--help

A：加 --profile 后 --help 显示的是该应用参数；裸 --help 是启动器。

A：它等 Agent 完成全部工作才退出，长任务属正常。

A：用 --patch 一次性覆盖层。

十二、写在最后

回到最初的问题：

我把 dsh 的命令体系整理成了一张表：

• 启动
  ：dsh web（Web UI）和 dsh --profile headless "任务"（一次性任务）

• 配置
  ：dsh --dump-config 和 dsh --dump-default-config

• 插件
  ：dsh plugin --profile

• 帮助
  ：dsh --help

• 规则
  ：启动器参数在前，应用参数在后

这套命令体系非常简洁，具体操作如下： - 日常使用：npx @deepseek-ai/dsh web，用于启动Web UI。 - 批处理操作：dsh --profile headless "任务"，可进行批处理任务。 - 排查问题：dsh --dump-config，用于排查相关问题。 - 管理插件：dsh plugin，方便对插件进行管理。

记住“

”这条规则，基本就能顺畅使用了。