dsh命令行怎么用？DeepSeek Harness启动参数与配置查看指南

本节目标：摸清 dsh 的常用命令和参数规则。学完你能熟练用命令行启动、查帮助、看配置，不再被「参数写哪边」搞晕。

dsh 是什么命令

官方文档对 dsh 的定位是「产品启动器」（product launcher）：它负责解析启动意图、加载对应的 Profile，把整个插件树组合起来。

调用形态有三种，命令本身完全一样：

npx @deepseek-ai/dsh web          # 零安装形态（npm）
dsh web                           # 全局安装形态（npm install -g @deepseek-ai/dsh）
pnpm dsh web                      # 源码形态（仓库内）

Note

本教程按官方惯例，用 dsh 代表命令本身。零安装路径下请写成 npx @deepseek-ai/dsh ...。

常用命令速查

命令	作用
`dsh web`	启动 Web UI，`--profile web` 的硬编码别名
`dsh --profile <name>`	启动指定 Profile
`dsh --profile headless "任务"`	无头模式跑一次性任务，打印最终答案后退出
`dsh plugin --profile <name> <pnpm 参数>`	管理某 Profile 的插件（转发给 pnpm，如 `add`、`remove`）
`dsh --patch <文件>`	追加一个 patch 覆盖层，可多次使用
`dsh --profile web --dump-config`	打印实际组合出的完整配置树（不启动服务器）
`dsh --profile web --dump-default-config`	只打印内置默认层（不含用户 patch）
`dsh --help`	启动器自身的帮助
`dsh --version` / `dsh -V`	启动器版本号

命令不规范、配置出错、启动失败时，都会以非零状态退出并打印错误——这是 CLI 的基本纪律。

Profile 是什么

Profile 是一套命名的配置组合，决定这次启动装哪些插件。dsh 用「Profile 目录 + 分层 patch」来组织配置，每个 Profile 对应 $DSH_HOME/profiles/<name>（默认 $DSH_HOME 是 ~/.dsh）。

web：内置模板，base + web-app，首次使用自动初始化
headless：内置模板，base + headless，首次使用自动初始化
其它名字：不会自动生成，需要先创建

创建自定义 Profile 用 dsh plugin 命令（需要 pnpm 在 PATH 上）：

dsh plugin --profile myagent add github:some-user/some-plugin

web 和 headless 之外的 Profile 不存在时，启动会报错并提示用这条命令创建。

Tip

想验证一个配置「到底生成了什么」，不用启动服务器，--dump-config 直接打印整棵配置树，每行还带来源注释（来自哪个层）。排查「某插件配置没生效」全靠它。

参数边界：启动器在前，应用参数在后

这是 dsh 命令行最容易踩的坑，规则只有一条：dsh 只解析自己的 flag，遇到第一个不认识的 token 就停，后面所有内容原样交给被启动的应用。

看官方例子：

dsh --profile web --port 8080        # --port 属于 web 应用，改监听端口
dsh --profile headless "run the tests"  # 任务文本是位置参数，属于 headless 应用
dsh web --help                       # 打印 web 应用的帮助，不启动应用
dsh --help                           # 打印启动器自身的帮助

所以规则是：启动器 flag 必须出现在第一个无法识别的 token 之前；web/plugin 是已识别子命令选择符，之后仍可接启动器 flag。--port/--host/--help 属应用参数。

web 应用目前支持这些参数：

参数	作用
`--host`	监听地址（默认 127.0.0.1）
`--port`	监听端口（默认 3080）
`--trusted-host`	追加受信任主机，可重复使用

Warning

官方 CLI 参考明确说，目前有意不支持 --host 0.0.0.0，传了会以用法错误退出。需要局域网访问，用 --trusted-host 加入主机名。网上有些教程教你绑 0.0.0.0，那是旧版或第三方写法，以官方文档为准。

—patch 与配置组合顺序

配置不是一份文件，而是分层叠加的。官方组合顺序是：

Profile 里 dsh.profile.bundles 列出的各 Bundle patch（按序）
Profile 自己的 cordis.patch.yml
Home 级 $DSH_HOME/cordis.patch.yml（各 Profile 共享的机器偏好）
--patch 覆盖层（按命令行顺序，最后写的优先级最高）

后应用的层优先。--patch 可以临时加一层配置而不改动任何文件：

dsh web --patch ./extra.cordis.yml

配合 --dump-config 验证效果：

dsh web --patch ./extra.cordis.yml --dump-config

Note

涉及 cordis.patch.yml 的写法与字段，第 9 章「配置体系」专门讲。这里先记住：配置是叠加出来的，dump 能看最终结果。

退出码与信号

CLI 的退出行为有明确约定：

配置解析、schema 校验、插件加载失败 → 报错并以非零状态退出
收到 SIGINT（按 Ctrl+C）→ 先优雅排空（最多 5 秒），退出码 130
收到 SIGTERM → 优雅排空，退出码 0
第二次收到信号 → 立即强制退出

这个约定对脚本化很重要，下一章的无头模式会直接用上。

小结

dsh 命令 = 启动器 flag（在前）+ 应用参数（在后）。常用五件套：web、--profile、--patch、--dump-config、--help。Profile 决定装什么，patch 决定怎么改，dump 负责验证。

命令行基础打牢，下一章进入重头戏：无头模式与脚本化运行。