dsh 命令大全：dsh web、dsh plugin 怎么用？DeepSeek Harness 参数与退出码详解

dsh 是 DeepSeek Harness 的命令行启动器，命令分四族：dsh web 启动 Web UI、dsh --profile headless "任务" 跑一次性会话、dsh --profile <name> 启动任意 profile、dsh plugin 管理插件——启动器只解析自己的参数，之后的内容交给被启动的应用。 本文是一份 dsh 命令大全，按「入口命令速查 → 参数归属 → dsh web → dsh plugin → 配置排查 → 退出码」组织，所有命令与参数都出自官方 dsh CLI README 与 CLI behavior reference，可直接复制执行。

dsh 命令有哪几条？web、plugin、--profile 入口命令速查

dsh 是 DeepSeek Harness 的命令行启动器，只做一件事：加载选中的 profile，把其余参数交给被启动的应用。 官方文档一句话总结：命令语法由 src/args.ts 负责，src/bin.ts 只加载选中的 runner（来源）。Entry modes 表定义了全部四条入口命令，这就是 dsh 命令大全的骨架（来源）：

想先跑起来，按下面三步（来源）：

1. 打开终端，进入你要当工作区的项目目录；
2. 执行 npx @deepseek-ai/dsh web（没全局装时用 npx）或 dsh web（已全局装），等终端打印访问地址；
3. 浏览器打开 Web UI，配 API 密钥、选工作区，发第一条任务。

配套的机制事实（来源）：

1. 调用目录 = 默认工作区根：所有模式都把启动 dsh 时所在的目录当作默认文件系统位置。
2. 自动初始化：web 和 headless profile 首次使用会从内置模板自动生成（web = base + web-app，headless = base + headless）；其他名字的 profile 缺失时会报错并提示 dsh plugin --profile <name> add <package>（来源）。
3. 数据目录：profile 都放在 $DSH_HOME/profiles/<name>，$DSH_HOME 默认 ~/.dsh。

dsh 参数归属：--profile 之后参数归谁？怎么传给 web 或 headless

dsh 启动器只解析自己的参数；第一个它不认识的 token 开始，之后的每个参数都原样交给被启动的 profile 去解析。 官方用一条命令说明这条边界（来源）：

dsh --profile web --port 8080        # --port 属于 web 应用
dsh --profile headless "run the tests"  # 引号内的任务是 headless 应用的位置参数
dsh --profile web --help             # 打印 web 应用的帮助，不启动任何东西
dsh --help                           # 打印启动器自己的帮助

几个容易踩的边界细节（来源）：

1. -V/--version 只在应用参数边界之前生效：dsh --version 打印启动器版本；写在边界之后就会被交给应用。
2. 字面 -- 需要写两个：启动器会消费一个 --，应用参数里需要字面 -- 时要写 -- --。
3. web 应用自己的命令行：--host、--port、可重复的 --trusted-host（来源）。
4. headless 应用自己的命令行：只有任务文本这一个位置参数，不传任务是用法错误。

dsh web 怎么用？改端口、受信主机与启动参数示例

dsh web 是 --profile web 的硬编码别名，负责把 Web UI 跑起来；它支持 --host、--port 和 --trusted-host 三个参数。 Web UI 默认服务在 http://127.0.0.1:3080（来源）。常用写法：

# 最简启动（等价 dsh --profile web）
dsh web

# 改端口：--port 是 web 应用的参数
dsh web --port 8080

# 叠加本地补丁后启动
dsh web --patch ./extra.cordis.yml

# 打印组合后的配置树，不启动
dsh web --dump-config

# 查看 web 应用的完整参数
dsh web --help

操作要点（来源）：

1. 默认 3080：启动成功后在浏览器访问 http://127.0.0.1:3080，第一次启动需在设置里配 API 密钥并选工作区，详见《npx @deepseek-ai/dsh web 怎么用？DeepSeek Harness 一键启动与参数详解》。
2. 不支持 --host 0.0.0.0：CLI 目前会以用法错误退出，想限制来源主机用 --trusted-host 加入受信主机名。
3. npx 等价写法：没全局安装时在命令前加 npx @deepseek-ai/dsh，如 npx @deepseek-ai/dsh web --port 8080。

dsh plugin 怎么用？add、remove、why、update 与 GitHub 源码安装

dsh plugin 把 --profile <name> 之后的参数完整转发给 profile 目录里的 pnpm，所以 pnpm 的 add、remove、why、update 等动词全部原样可用。 profile 缺失时它会先按模板初始化（web 用 shipped 模板、其他名字用 @deepseek-ai/dsh-base），再执行 pnpm（来源）。示例：

# 从 npm 装插件到 web profile
dsh plugin --profile web add dsh-plugin

# 从 GitHub 仓库装插件（git 源码，装完即生效）
dsh plugin --profile tui add github:deepseek-harness/turtle-ui

# 卸载插件
dsh plugin --profile tui remove turtle-ui

# 查看某个依赖为什么被装进来
dsh plugin --profile web why dsh-plugin

# 更新 profile 里的插件
dsh plugin --profile web update

装 GitHub 源码插件的两个要点（来源）：

1. git 插件首次 add 可能失败：带源码的 git 插件装的时候要跑 prepare 脚本，pnpm ≥10 默认阻止，会提示把打印出的 allowBuilds key 复制到 profile 目录的 pnpm-workspace.yaml 再重跑。
2. 本地目录优先：相对路径（.、../plugin 及 file:/link: 形式）会锚定到启动目录，所以从插件源码目录里执行 dsh plugin --profile web add . 装的是本地这份，不是 npm 包。

装完的插件，dsh.profile.bundles 会自动与被安装状态对账：新依赖声明了 dsh.bundle.patch 就加入补丁层、卸载后自动移出（来源）。不想背 dsh plugin 参数的话，装完 DSH Plugin Hub 就能在 Web UI 的「设置 → 插件市场」可视化安装、卸载、更新插件。

dsh 配置排查：--patch、--dump-config、--dump-default-config 怎么用

dsh 的组合树默认由「bundle 补丁 → profile 的 cordis.patch.yml → home 级 $DSH_HOME/cordis.patch.yml → --patch 覆盖层」逐层叠加，越靠后的层越优先；想看补丁叠成了什么样，用 dump 命令只打印不启动（来源）。 排查时照下面做：

# 只打印 bundle 层（不含 profile/home/patch 覆盖）
dsh --profile web --dump-default-config

# 打印完整组合树：bundle + profile + home + --patch
dsh --profile web --patch ./extra.yml --dump-config

1. 插件装了但没生效？先 dsh --profile web --dump-config，看对应行来自哪个文件、被谁覆盖——每条注释都会标出供给它的文件。
2. 想临时改某个配置又不想动文件？--patch ./extra.yml 传入本地补丁，最后叠加、优先级最高。
3. 两个限制：dump 不运行应用参数解析，所以带应用参数会报错；它也不会真的启动 Web UI。

dsh 退出码怎么看？脚本里怎么判断命令成败

dsh 用退出码表达结果：headless 任务 completed 退出 0、否则 1，帮助请求退出 0、被拒参数非零，SIGINT 报 130、SIGTERM 报 0。 无效命令、跨模式参数、配置错误、启动失败都会非零退出（来源），所以脚本里直接判断 $? 即可，不必解析输出文本：

给脚本/自动化用的一个完整例子——跑一次性任务并判断成败：

dsh --profile headless "run the tests"
if [ $? -eq 0 ]; then
  echo "任务完成"
else
  echo "任务失败，退出码 $?"
fi

另外 web 在收到 SIGINT/SIGTERM 时会给插件树最多 5 秒优雅关闭，第一次 Ctrl+C 是正常排空而不是秒杀（来源）。把 dsh 写进脚本或 CI 时，先判退出码是最可靠的信号——dsh web、dsh plugin、dsh --profile 各命令的常用写法照上文速查即可，想一键管理插件就直接用 DSH Plugin Hub 的界面。

来源：dsh CLI README、dsh CLI behavior reference、官方 Quickstart