命令行
dsh 是唯一入口命令,几乎所有操作都从一个 dsh 起。
官方零安装入口是 npx @deepseek-ai/dsh ...，要求 Node.js ^22.19.0 或 >=24.0.0。在官方源码仓库中则使用 pnpm dsh ...。下文统一写成 dsh ...。
一、基础用法
dsh --profile web # 启动 Web profile(等价 dsh web)
dsh web # Web UI(别名 --profile web)
dsh --profile headless "跑一下测试" # 一次性任务,执行完退出
dsh plugin ... # 管理 profile 插件依赖
dsh run子命令已移除;一次性任务改走--profile headless <task>。
二、launcher flags(启动器层)
这些在传给 app 之前就被 dsh 消费:
--profile <name> 选定 $DSH_HOME/profiles/<name>(首次自动初始化)
--patch <path> 额外叠一个 overlay patch(优先级高于 profile 层)
--dump-config 打印组合树并退出
--dump-default-config 只打印 bundle 层(无用户层/--patch)
dsh --profile web --dump-config # 看 web profile 的完整组合
dsh --profile tui --patch ./extra.yml # 自带 patch 启动
两个关键机制:
- 启动器只吃自己的 flag,其余原样交给应用。第一个启动器不认识的 token 之后全是"内层参数",原样进配置树:如
dsh --profile tui --resume abc的内层参数是['--resume', 'abc'](其中--resume是 TUI 应用自己的 flag)。 - flag 位置敏感:启动器 flag 必须放在应用参数之前,
--patch放到某个应用 flag 后面就归应用了。启动器消费一个--,需要把字面--传给应用时写-- --。 --help/--version由应用自己解析并打印,不是启动器统一处理。
三、Web 子命令
dsh web --port 8080 # 指定端口(0 = 随机)
dsh web --host 0.0.0.0 # 允许局域网访问
dsh web --trusted-host <host> # 信任的主机
dsh web --dump-config # 打印配置树并退出
- Web UI 默认只监听
127.0.0.1:3080 - 工作区在 Web UI 内用目录选择器选(非 CLI flag)
- 开发 HMR:源码目录
pnpm run dev:web重建 client 资源,dsh web自动轮询热更
四、headless 一次性任务
--profile headless 跑一次性任务:任务文本就是命令行剩余部分,提交成一个普通用户消息,跑完把最后一段非空助手文本写到 stdout 退出。
dsh --profile headless "跑 pnpm test,把失败用例汇总成清单"
dsh --profile headless "审查 src/server.ts 的鉴权逻辑,给 3 条可执行建议"
dsh --profile headless "用 glob 列出所有还在用旧 API 的调用点" > /tmp/out.txt
行为要点:
- 退出码:
turn/end是completed→0,否则1。 - 成功时 stderr 为空;出错时把错误码和消息写到 stderr。
- 只提交一个任务,无交互追问界面;不监听任何端口(不挂 Host/Web/浏览器)。
- 它是"跑完就退"的 CI/脚本友好形态,适合放进 shell、cron 或 Makefile。
五、插件管理
# 安装 bundle 插件(git 源一行)
dsh plugin --profile web add "github:dsh-external/<repo>#main"
# 本地目录开发
dsh plugin --profile web add link:/path/to/plugin
# 移除 / 查看依赖
dsh plugin --profile web remove <包名>
dsh plugin --profile web why <包名>
plugin把参数原样转发给 pnpm,在 profile 目录执行;只接受 pnpm 能识别的源(纯 git 源、link:等)。&path:子路径是 repository 插件机制自己的格式,装 monorepo 子包走插件面板的 repository 源,不经dsh plugin add。安装 bundle 后重启dsh web生效(repository 插件即改即生效)。
六、查看配置
dsh web --dump-config # 组合后配置树(带层来源注释)
dsh web --dump-default-config # 只 bundle 层
--dump-config 是排查"哪层覆盖了什么"的权威工具(见 启动与配置)。
七、环境变量
| 变量 | 作用 |
|---|---|
DSH_HOME | 覆盖主目录(默认 ~/.dsh) |
DSH_TELEMETRY_DISABLED | 任意非空值关闭遥测 |
DSH_TELEMETRY_OTLP_URL | 覆盖遥测上报端点 |
DSH_PERMISSION_MODE | 权限预设覆盖 |
DSH_TOOLS_MODE | 工具挂载模式 |
DEEPSEEK_API_KEY 等 | provider 凭据(也可存 .env) |
完整列表见 环境变量。
八、常见命令场景
| 想做什么 | 命令 |
|---|---|
| 跑一个 Web 会话 | dsh web |
| 跑一次性任务 | dsh --profile headless "任务" |
| 一次性任务存结果 | dsh --profile headless "任务" > /tmp/out.txt |
| 带应用层 flag 启动 | dsh --profile tui --resume abc |
| 看当前组合 | dsh web --dump-config |
| 只看 bundle 层 | dsh web --dump-default-config |
| 装个插件 | dsh plugin --profile web add "github:..." |
| 本地目录装插件 | dsh plugin --profile web add link:/path/to/plugin |
| 自带 patch 启动 | dsh --profile tui --patch ./extra.yml |